Specifications that survive contact

Redlines are dead labour

The traditional handoff was an annotated screenshot: arrows and numbers marking every margin, every size, every hex code. It takes hours, it is obsolete the moment anything changes, and the numbers get transcribed by hand into code where they become untraceable magic values.

If you have tokens, hand over token names instead.

Bad:   padding 24px, gap 8px, radius 8px, #2F6DF6, 16px/1.55
Good:  padding var(--space-4), gap var(--space-2),
       radius var(--radius-md), background var(--colour-action),
       text var(--text-md)/var(--leading-normal)

The second version is shorter to write, unambiguous, and survives a rebrand without being rewritten. It also makes deviations visible: if a developer has to ask what token 18px is, the answer is that 18px is a mistake.

What a component specification must contain

Six sections, none of them long:

1. Anatomy — the named parts, from the components lesson.
2. Variants and sizes — the axes, with the token values for each.
3. States — the table from the states lesson.
4. Spacing — internal padding and gaps, as tokens. Not external margins, which belong to the layout.
5. Content rules — maximum label length, what happens when it is exceeded, whether it wraps or truncates, what the empty case is.
6. Accessibility notes — the accessible name, the keyboard behaviour, the focus treatment, anything that is not obvious from the visual.

The fifth is the one most often missing and most often needed. Truncate at one line with an ellipsis is a design decision, and if nobody makes it, the implementation will make it differently in three places.

Write the rules, not the pictures

A picture of a component in one configuration is not a specification, because implementation always encounters a case the picture did not show. What is the longest label? What if there is no icon? What happens at 320 pixels?

Rules answer those. Pictures do not, and a beautiful specification made entirely of pictures generates a constant stream of questions that the designer then answers ad hoc, inconsistently, over the following weeks.

A useful heuristic: for every visual you provide, write one sentence about what happens when the content is longer than shown, and one about what happens when the container is narrower.

Documentation goes stale, and stale documentation lies

This is the honest limitation, and it is severe. A specification that is out of date is worse than no specification, because it is wrong with authority. Somebody will build from it, and the discrepancy will be found in review, and the time spent is worse than if they had asked.

Two things keep documentation alive, and only two:

Proximity. Documentation that lives beside the code gets updated when the code changes. Documentation in a separate tool that requires a different login does not.

Use. Documentation that is the actual source — a component gallery rendered from the real components, so the examples cannot drift — cannot go stale, because it is generated from the thing it documents. Storybook does this and is free; a hand-written HTML page that imports the real stylesheet does most of it.

A static PDF of specifications is stale within a month, always. If that is the only option available, keep it to the decisions rather than the details, because decisions age more slowly than pixel values.

The handoff conversation

The document is not the handoff. A fifteen-minute conversation covering three questions prevents most of the problems a document cannot:

1. What is fixed and what is flexible? Which values are load-bearing and which were chosen because something had to be chosen. Developers routinely preserve an irrelevant 3px offset with great care while altering the one measurement that mattered, because nothing told them which was which.
2. What happens at the edges? The longest content, the narrowest screen, the slowest connection, the error.
3. What should you come back to me about? Set the threshold explicitly, or you will either be consulted about everything or about nothing.

Keep it short

A component specification that runs to eight pages will not be read. One that fits on a screen will.

The discipline is to document the decisions somebody could not infer, and to leave out everything they could. A button is a rectangle with a label in it; nobody needs that written down. What the button does when the label is forty characters long is not inferable, and that is what the page is for.