In short
Document a component with every visual state shown explicitly, exact spacing and sizing values (not eyeballed from the design file), content rules for what happens with long or missing text, and a plain-language description of interactive behavior — enough that engineering can build it correctly without a clarifying question.
Documentation prevents the expensive kind of guessing
A component handed off with just a static, default-state image forces whoever builds it to guess at everything else — what does it look like disabled? What happens if the text is much longer than the example? These guesses often turn into a back-and-forth clarification cycle that's slower than documenting the answer upfront would have been.
Show every state explicitly
Document default, hover, focus, active, disabled, loading, and error states as explicit, separate visuals — not just described in text. A state left undocumented is a state that gets built inconsistently or skipped entirely, especially under time pressure.
Specify exact values, not approximate ones
Spacing, sizing, and color should be documented as exact values — ideally referencing the actual design tokens rather than a raw pixel measurement eyeballed from the design file. "16px padding" is good; "space-4 padding" is better, because it ties the component directly to the token system rather than an isolated number that can drift out of sync.
Content rules: the part most often skipped
Document what happens when content doesn't match the ideal example — a button label that's much longer than expected, a card with no image, a list with zero items. These edge cases are common in real usage and are exactly the cases most likely to be missed if only the ideal, happy-path example is documented.
Describing interactive behavior in plain language
For anything with interaction beyond a simple click — a dropdown's open/close behavior, a form field's validation timing, a modal's focus handling — write a plain-language description of the expected behavior, since this is rarely fully inferable from static visuals alone, however many states are shown.
Linking design and code
Where a code implementation already exists, link directly to it from the design documentation (and vice versa) — this turns documentation into a genuinely two-way, navigable resource rather than two disconnected artifacts that each go stale independently. Tools that support code-connect mapping between design components and their implementation make this easier to maintain.
A practical documentation template
For each component: name and purpose, all visual states, exact token-based values for spacing/color/type, content rules for edge cases, plain-language behavior description, and a link to the existing code implementation if one exists. This template, applied consistently, removes most of the guessing that a bare visual handoff leaves behind.
Related on Troiana: The Myth of the Pixel-Perfect Handoff.
Reference: the authoritative guidance lives at the W3C Design Tokens Community Group.
Common questions
What's the most commonly missing piece in component documentation?
Content rules for edge cases — what happens with unusually long text, missing images, or empty states — since documentation often only shows the ideal, happy-path example.
Should component documentation reference design tokens directly?
Yes — referencing the actual token name (like space-4) rather than a raw pixel value ties the component directly to the token system, reducing drift as the system evolves.
How much of a component's behavior can be shown visually versus written?
Visual states cover appearance well, but interactive behavior — timing, focus handling, open/close logic — usually needs a plain-language written description, since it's rarely fully inferable from static visuals alone.
