Annotation Guideline

[dbrembilla]

Resolves #235
(to be merged only when the feature is complete)

• Adds Annotation Strategy Guideline to the available tabs in the project view.
• Annotation Strategy Guideline can be edited by admins and viewed by editors.
• Annotation Strategy Guidelines can have labels associated. A description, a preferred shape and a reference image can be added
• Annotation Strategy Guidelines can be enforced for the annotation process, making it so that only labels within a strategy can be used and the preferred shapes are enforced
• When annotating, description and reference image are displayed
• Enforcement applies to Largo as well, making it so that only labels with a Strategy Guideline can be used and the preferred shapes are enforced

[dbrembilla]

@mzur I should be done with this part of the changes, if you want to check them

[mzur]

High-level review first:

I thought about the name "annotation strategy" again. This is not really a "plan of action" (although this could be explained in the description) but rather a "set of rules" with some additional information attached. If this is enforced, it is more like a "policy". But since enforcement should be optional, maybe it could be a "guideline"? The thought occurred to me when I saw the tab "strategy" and had no idea what it really meant.

---

I now definitely prefer the alternative UI I mentioned earlier. Below is a mockup. We can also discuss this again before you start the implementation, so it will turn out "right" and you don't have to do duplicate work.

The UI consists of a block with the description at the top and a block for the labels below. The description can turn into "edit mode" with a click on the edit button. There, the description becomes a textarea and can be changed. Also a "power toggle" appears where the admin can toggle "enforcement" of the strategy/guideline. The edit button is replaced with a discard and a save button. When any of these is pressed, edit mode is disabled again. If a guideline is enforced, this is indicated with something next to the title (also for non-admins).

On the left of the labels block there is the label trees component with all label trees of the project. When a label is selected, the label description, shape and reference image appear to the right. Admins can edit these. If a label has a description/shape/image, this is indicated with an info icon in the label trees. This can be an example for the UI in the annotation tools later. Since a label can also have a star icon if it is favorite, both icons must work.

If a guideline is enforced, labels without description/reference/image are shown with a muted color in the label trees component. Maybe we need an extra property to "include" a label in a guideline even if it has no description/shape/image?

Each label should be saved individually after it was edited, not only after the whole strategy/guideline was saved (as it is done now).

---

The body of the strategy/guideline tab overflows the main body container on two levels (see below). Watch the use of container and row classes.

---

Currently when I create a strategy with only a description, I get the error "The reference images field is required." The strategy is saved though.

[dbrembilla]

Thanks for the feedbacks and for the prospect of the UI! FYI, that's a PNG and the background is transparent so it's kinda hard to read on the dark background in github.

The guideline naming also makes sense.

To signal that a guideline is enforced, could a bolt icon make sense?

On the left of the labels block there is the label trees component with all label trees of the project. When a label is selected, the label description, shape and reference image appear to the right. Admins can edit these

Should the labels have an Edit and Save button as well, so that it can be individually saved (similarly to what it is now)? I would show it besides the Label description title, similarly to the annotation guideline.

Each label should be saved individually after it was edited, not only after the whole strategy/guideline was saved (as it is done now).

In order to have the annotation guideline before the label, I would probably show the label components after the strategy is initially saved, what do you think?

If a label has a description/shape/image, this is indicated with an info icon in the label trees.

This makes sense, we could also make it so that when hovering on the info icon the information about the annotation guideline for the label appear, or that clicking that would either send you to the label in the annotation guideline or display the info somewhere in the UI. I would implement this after the tab is set up, for now I am just gonna add the icon.

If a guideline is enforced, labels without description/reference/image are shown with a muted color in the label trees component. Maybe we need an extra property to "include" a label in a guideline even if it has no description/shape/image?

We could also simply make it so that all properties of a label within a guideline are nullable, so that users that want to leave all the freedoms do not have to use all of them.

[mzur]

Should the labels have an Edit and Save button as well, so that it can be individually saved (similarly to what it is now)? I would show it besides the Label description title, similarly to the annotation guideline.

When an admin selects a label, it is automatically in "edit" mode. But we need a save button, yes.

In order to have the annotation guideline before the label, I would probably show the label components after the strategy is initially saved, what do you think?

This can be handled by the JS in the background for better UX. If the users saves a label before they created the guideline, the JS creates the guideline first (with empty description) and the saves the label.

This makes sense, we could also make it so that when hovering on the info icon the information about the annotation guideline for the label appear, or that clicking that would either send you to the label in the annotation guideline or display the info somewhere in the UI. I would implement this after the tab is set up, for now I am just gonna add the icon.

I think I prefer to show the info in the label indicator that currently only shows the label name at the bottom right of the annotation tools. But let's talk about this when we get there.

We could also simply make it so that all properties of a label within a guideline are nullable, so that users that want to leave all the freedoms do not have to use all of them.

Sounds good.

[mzur]

Fyi, GitHub now supports stacked PRs. I think you don't even need the gh CLI for that. Just open a new PR targeting the branch of this PR and it will be a stack. We can use this when annotation guidelines are implemented in the annotation tools and Largo.

[dbrembilla]

Fyi, GitHub now supports stacked PRs. I think you don't even need the gh CLI for that. Just open a new PR targeting the branch of this PR and it will be a stack. We can use this when annotation guidelines are implemented in the annotation tools and Largo.

Pretty cool feature! It's good to know

Btw, with the new UI there is some more space for the image. I would cap the maximum size to display to 300 pixels.
Would be something like this:

Video_2026-04-14_09-33-48.mp4

[mzur]

Neat. I may jump in at the end and move some buttons around. Just let me know when this is ready to review again.