One component, precisely – Anatomy, variants, states

To critique a component – or ask an agent to change one – you need three small vocabularies: what its parts are called, what its versions are called, and what its conditions are called. Miss any of the three and the request goes vague exactly where it needed to be precise.

Parts: anatomy

Take any component apart and the same roles repeat at every scale: something holding it together (container), something saying what it does (label), a small reinforcement (icon slot), and the content or input it wraps. That labelled breakdown is the component’s anatomy, and good system documentation leads with it because a diagram answers implementation questions faster than prose. The payoff is the quality of your questions: “can this button’s icon slot hold a status dot?” is answerable at a glance; “can I add a dot to this button?” isn’t, because it doesn’t say where.

Versions and conditions: the pair everyone blurs

Before anyone touches a button, someone decided: is this the important one on the screen (filled, high-contrast) or a lesser one (outlined, muted)? That decision was made at design time and doesn’t change while the app runs – a variant. Now the app is running: a cursor passes over, a press lands, the form goes invalid, data is loading – the appearance reacts live, with nobody redesigning anything. Those are states. The formulation that makes it stick: variants are situational, states are reactive.

And here’s the part that actually resolves the confusion – they multiply, they don’t compete for one slot. Every variant passes through every relevant state: a primary button can be hovered, pressed or disabled, and so can a secondary one. Three variants across four states is twelve appearances of one component – a grid, not a list:

Name the part, then multiply the versions by the conditions

Anatomy answers 'where'; variants and states answer 'which one, in what condition'.

↓Download report

Container. Holds the pieces together; carries the background, border, radius and padding. Size and shape live here.

3 variants × 4 states = 12 appearances, one component

variant ↓	Defaultlive – try them	Hoverpinned to compare	Pressedpinned to compare	Disabledlive
primary	Save	Save	Save	Save
secondary	Save	Save	Save	Save
tertiary	Save	Save	Save	Save

Inspect a partContainerIcon slotLabel

This grid is what a component-property system in Figma, or a component’s code props, exist to express: variant="primary" and state="hover" are two independent properties set simultaneously. Designing the grid once – every cell, including the three states nobody mocks up – is a large part of what separates a system component from a one-off.

Why the precision pays

“This button looks wrong when it’s greyed out” starts a discussion. “The disabled state on the secondary button is too faint” starts a fix – it names the variant, names the state, and any engineer (or agent) can walk straight to that cell of the grid. When a review note of yours gets actioned without a follow-up question, this vocabulary is usually why.