Component Anatomy, States and Variants
A component is finished when its parts, its states and the reason each variant exists are all written down.
Definition
Anatomy names the parts of a component. States describe how each part responds to interaction and context. Variants are the deliberate alternatives. Undocumented, all three get reinvented by whoever needs them next.
Craft convention. True because the industry converged on it. Breaking it costs familiarity, not correctness.
On this plate
Reach for this when
- Adding a component to a shared library.
- Two teams have built the same thing differently.
- A component keeps acquiring one-off variants.
Common mistakes
- Focus states left to the browser default and then removed by a reset.
- Variants named after colour.
- Content limits discovered in production.
The specification checklist
| Aspect | What to define | Common omission |
|---|---|---|
| Anatomy | Required and optional parts, and their order | Optional parts nobody knew were optional. |
| States | Default, hover, focus, active, selected, disabled, loading, error, read-only | Focus and read-only, almost always. |
| Variants | Each alternative plus the condition for choosing it | Variants with no stated difference in meaning. |
| Sizes | The scale and what each size is for | A size added for one screen and kept forever. |
| Content limits | Minimum and maximum content, and wrapping behaviour | Behaviour with a very long label, or none. |
| Accessibility contract | Role, name, keyboard behaviour, announced state | State changes that are visual only. |
Keeping the set honest
Do
- Give each variant a meaning, not a look: destructive, not red.
- Document the decision rule between neighbouring variants in one sentence.
- Specify what happens with the longest realistic content and with none at all.
- Treat read-only and disabled as different states, because they mean different things.
Do not
- Do not add a variant for a single screen. Style it locally, and promote it if it recurs.
- Do not let a variant set grow past what a designer can hold in memory. Beyond about five, nobody chooses correctly.
- Do not express state with colour alone.
- Do not spec a hover state without specifying its touch equivalent.
Specifying one, in order
Each step is cheaper once the previous one is settled, which is why the order matters more than the format.
- 1
Name the job
One sentence saying what the component is for and what it is not. Every later argument resolves faster once this exists.
- 2
Draw the anatomy
Label every part, mark which are optional, and fix their order. Optional parts nobody wrote down are where variant drift begins.
- 3
Enumerate the states
Walk the whole list rather than the ones your design happens to show. Focus, read-only and loading are the three usually missing.
- 4
Justify each variant
Write the decision rule between neighbouring variants. A variant you cannot distinguish in one sentence is a duplicate.
- 5
Set the content limits
Minimum, maximum, wrapping and truncation, tested with the longest realistic label and with none at all.
- 6
Write the accessibility contract
Role, accessible name, keyboard behaviour and what is announced on each state change. This is specification, not a review note.
- 7
Publish the misuse
Name the nearest wrong choice and link the component that is right for it. This is the part that prevents the next fork.
The states a specification has to answer for
In practice
- i.
Read-only versus disabled
A disabled field says 'you cannot change this now'. A read-only field says 'this value is fixed'. Rendering both at 40 percent opacity makes a permanent value look like a temporary block, and generates support questions about how to enable it.
Commonly confused with
Close neighbours that get substituted for each other. The difference is stated first, then the condition that picks one over the other.
Component API Design
Design systemThe props, slots and events through which the component is used.
Key difference
Anatomy and variants describe what a component is and which alternatives exist. The API is how anyone gets at them in code. One is the decision, the other is the surface that exposes it, and a good decision with a bad API still gets forked.
Use Component Anatomy, States and Variants when
- Two teams have built near-duplicates because nothing was written down.
- The question is which states and variants are legitimate.
- The work is documentation and design, before any props are named.
Use Component API Design when
- People are overriding styles or forking to get what they need.
- The question is which variations to support and which to refuse.
- The work touches naming, defaults and breaking changes.
Local chart
SYS·009 · Region VI · Grid D4
This entry and the entries it is stated to connect with. Each line is labelled with what the connection means.
Continue from here
Each link says what the connection is, so you can tell a principle from an alternative from a thing people mix this up with.
Related concept
Connected closely enough to change how you apply this.
- Focus IndicatorsA11Y·003 · Accessibility
- Specification to Working CodeAI·010 · AI workflow
- Design and Code ParitySYS·010 · Design system
- Design System DocumentationSYS·003 · Design system
- Design TokensSYS·001 · Design system
- Visual StatesFND·053 · UI foundation