Writing component specifications that engineers trust

There is a pattern in design handoff that repeats in almost every team: the designer delivers a spec, the engineer builds from it, the designer reviews the output and finds problems, and the post-mortem reveals that the spec was ambiguous on exactly the things that diverged. The gap isn't between intent and execution. It's between what the spec documented and what the implementation needed to know.

Engineers who skip specs, or use them only as visual reference without following them closely, are usually responding to a track record. Specs that have been incomplete in the past teach engineers that the spec doesn't have the complete answer. Once that trust is broken, the spec becomes a suggestion rather than a source of truth.

The completeness problem

A component spec that shows the default state, the hover state, and the active state has documented three states. The real component probably has eleven. Disabled states. Focus states visible enough for accessibility review. Loading states where asynchronous operations are involved. Error states for form controls. Empty states for components that display data. States for keyboard focus distinct from mouse hover. States for touch input on mobile.

The states that don't appear in the spec are the ones the engineer either invents or borrows from somewhere else. Inventing them produces inconsistency. Borrowing them means the component looks like a component from a different part of the system.

The solution isn't to add every possible state to every spec. It's to have an explicit inventory of standard states that every component is expected to address, so the engineer knows that "not shown in spec" means "use the system default" rather than "designer forgot." If the spec has a section that says "focus state follows system standard, see button focus treatment" rather than just not addressing it, the engineer has a complete answer.

Interaction specification gaps

Visual specs show what a component looks like. They rarely show how it behaves.

A tooltip component whose spec shows only the tooltip in its visible state leaves open: how long is the hover delay before it appears, how does it dismiss, what happens when the user moves from the trigger to the tooltip itself, does it reposition when near a viewport edge, does it have an animation and if so what are the duration and easing values.

An engineer building this component will make choices for all of those unspecified behaviors. The choices won't be wrong, in the sense that the component will work. But they won't match the design intent, which was formed by someone who thought through how the component should feel and just didn't write it down.

Interaction specs don't have to be exhaustive prose. For many behaviors, a reference to a system standard works: "animation follows system tooltip preset. 150ms fade, ease-out." The spec acknowledges the behavior and points to where the answer lives. That's enough for an engineer to implement correctly.

Spacing as the most common specification failure

Spacing in design specs fails in a specific way: it's specified relative to visible elements rather than as absolute values that account for the component's invisible geometry.

A button spec that shows 16px padding horizontally and 8px padding vertically looks complete. An engineer who implements that spec produces a button that may be correct visually in isolation and wrong in context: the spec didn't account for how the button's height relates to the line height of its label, or whether the spacing values should be the outer padding of the component or the spacing between the label and the component's internal background.

The version that doesn't cause problems: spacing values tied to tokens, and token values defined in the design system rather than specified per component. If the button uses spacing-sm for its horizontal padding and spacing-xs for its vertical padding, and those tokens have documented values, the engineer doesn't need to interpret the spec. They implement the tokens. The spec is communicating a design intent that resolves to a specific value through the token system.

A spec that bypasses tokens in favor of specific pixel values is a spec that requires the engineer to interpret it. Interpretation introduces variation.

Responsive behavior

Responsive behavior is the specification gap that causes the most visible inconsistency in production. A component that was specced at desktop viewport behaves differently at tablet and mobile sizes, and the spec doesn't say what should happen.

Engineers facing unspecced responsive behavior will use judgment, and their judgment about how a card layout should collapse on mobile is usually different from the designer's judgment. Neither is wrong. They're both reasonable. The spec should be the deciding factor, and it's absent.

This doesn't mean speccing every breakpoint for every component. It means answering the question explicitly for the components where responsive behavior matters. "Stacks vertically below 640px, image moves above text" is one sentence. That one sentence prevents the engineer from guessing and producing something that needs to be changed in design review.

Building trust through accuracy

The specs that engineers trust are the ones that have been accurate. This sounds circular, but it has a practical implication: accuracy is a track record, and track records are built by fixing spec errors when they're found.

When an engineer identifies something in production that differs from the spec because the spec was ambiguous or wrong, the spec needs to be updated. If it isn't, the next engineer to work on that component learns that the spec is aspirational, not descriptive, and they'll start treating it accordingly.

The system team's investment in reviewing specs before handoff, not to approve every design decision but to check for the predictable incompleteness patterns, pays back in fewer revision cycles. A spec review that catches the missing disabled state and the unspecced focus behavior takes fifteen minutes. A design review comment cycle on those issues takes two days and leaves the engineer feeling like they were asked to build something before it was ready.

They were.