Redlining and annotations: specifying without ambiguity
Redlines annotate a design with measurements, spacing, colours and behaviour so developers build it right. What to include, how to organize them, what to avoid.
What is it and what is it for?
In product design, the term describes the annotations that accompany a design when it moves to development. Figma calls them annotations and measurements; Zeplin talks about always-visible instructions pinned directly on a screen; and a 2017 Adobe article describes “Design Specs”, an Adobe XD feature that published measurements, colours and typography at a link so developers could look them up without asking the designer.
It closes the gap between two people looking at the same design with different information. The designer knows why the spacing is 24 pixels. The developer sees only a rectangle. Without annotations, the developer decides, and that decision rarely matches the designer’s.
What should it include?
Zeplin argues that handoff goes beyond colours, spacing, typography and measurements: it includes design intent, the context of flows and behaviour. Figma recommends highlighting important properties so developers can’t miss them, and offers preset categories for annotations: development, interaction, accessibility and content. According to its documentation, adding measurements and annotations requires a paid plan (Professional, Education, Organization, Government or Enterprise), a full seat and edit access to the file.
A practical list to review before handing off:
- Measurements and spacing between elements, with the values the code will use.
- Colours and typography with their token name, not just the hex value.
- States: empty, loading, error, disabled, hover and focus. A redline that shows only the default state leaves the developer blind to the rest.
- Behaviour: what happens on click, on typing, on losing focus, and in what order focus moves with the keyboard.
- Responsive rules: how the design behaves at each size, what is hidden, what stacks.
- Accessibility: reading order, alternative text, component names, and the relationship with the error state patterns where they apply.
- Content: real copy, maximum lengths, and what happens if the text does not fit.
And what it should not include: decisions that are not closed yet. A redline on a design under review is a maintenance cost nobody wants to pay.
How do you organize it?
Redlines work best when each screen has its own annotation layer and the annotations refer to components, not to loose pixels. If the primary button appears on forty screens, its specification lives in the component and the screens only reference it.
The practical rule is to annotate intent, not only appearance. “Spacing of 16 pixels” is a measurement. “Spacing between the label and the field, so reading groups the two” is an intent, and it helps the developer decide what to do if the label wraps onto two lines.
In his 2017 article on design specifications on the Adobe blog, Nick Babich recommends keeping specs up to date, giving each screen a name that states its function and involving the development team from the start. Figma adds that developers see annotations update in real time in Dev Mode. That synchronization is valuable, but only if someone keeps the annotations alive.
If you want to see how the whole handoff package fits together, read the design handoff process and the design specs. A redline is only one part of it.
Tokens, not loose values
A redline with fixed values (#2563eb, 16px) goes stale as soon as the palette changes. A redline with tokens (color.action.default, space.md) stays true even when the values change, because the token points to the right place. That is why annotations should use the same names as the token system. If your team does not have tokens yet, at least document the mapping between values and names.
When should you NOT make redlines?
- When the development team works in the same room and the conversation is constant. A heavy redline can be a pointless formality.
- When the design changes every day. Annotating a prototype that is still being explored wastes time.
- When the component already lives in the design system. It is enough to reference the component and annotate only what is new.
- When they replace the conversation. A redline does not replace the person who can answer a question.
Example
Illustrative example: a team designs a payment card with three states: normal, insufficient balance and loading. The redline shows the spacing between components with its token name, the error colour with its semantic token and the button’s behaviour in each state. It also states what happens if the merchant name runs over two lines: it truncates with an ellipsis and the full text appears on long press. When reviewing the implementation, the team finds that the loading state had no specification. They add it before launch, not after.
For your next handoff: review one screen and count how many states it has. If the redline shows only one, add the missing ones and ask a developer what else they need.
Common mistakes
- Annotating only the default state.
- Using fixed values instead of tokens.
- Annotating decisions that are not closed yet.
- Leaving handoff until the end, when development has already started.
- Annotating pixels instead of components and their behaviour.
- Not maintaining the annotations when the design changes.
- Filling the screen with notes nobody reads. As a rule of thumb, not a standard: if a block carries more than five or six annotations, a component is probably missing from the system.