Framework · Design systems · 3 min read
Component API checklist
Six questions to answer in plain words before you draw a component (its job, parts, what changes, what never changes, its states and what it is not), then three checks that turn each answer into a variant, a property, a slot or a token.
What it does for the person, in one sentence.
"Starts an action"Each part named, required or not, and what happens when it's long.
Route: required, wrapsEach real difference becomes a prop named after its meaning.
variant="danger", not redRadius, font and focus ring stay in tokens, not props.
No "just add color"The states it must ship, listed before anything is drawn.
See the state matrixWhat it is not, so it doesn't end up doing another component's job.
"Not a link"Variant if it changes many parts · Property if it changes one layer · Slot if you can't predict it
Use it when
- A team asks for a new component, or a new option on an existing one.
- Figma and code call the same thing by different names, and every handoff starts with "which one is that?".
- A component has grown so many options that nobody knows which combinations work.
How to use it
- Write the job in one sentence. Say what it does for the person using the product, and what it is not for. Output: "Starts an action. Not for navigation: that's a link."
- Name every part. For each part, answer four questions: what is it called, is it required, where does it come from (text, token, another component), and what happens when it's long. Output: an anatomy table, one row per part.
- List what changes between uses. Each real difference becomes a prop: the label, the importance, the size. Name it after the meaning (
variant="danger"), never the look (color="red"). Output: a list of props, each with its type, its values and a default. - Pick the kind for each prop. A change that touches many parts at once is a variant. One part shown, hidden, swapped or relabelled is a property. Content you can't predict goes in a slot, with limits. Output: the Figma property type next to every prop.
- List what never changes, and what it is not. Radius, font and focus ring stay in tokens, not props. Hover and focus belong to the browser. Write the "not a link, not a toggle" line. Output: two short lists that stop overrides.
- Check the names on both sides. Same property names, same lower-case values and the same order in Figma, code and docs. Output: one name per thing, ready for the doc page.
Worked example
Harbour's team gets a request for a "red button" for cancelling a booking. They run the checklist before opening Figma.
| Question | Answer |
|---|---|
| Job | Starts an action. Not for navigation, not a toggle |
| Parts | Label (required, wraps), icon at the start (optional, a nested Icon), focus ring (from tokens) |
| What changes | variant: primary, secondary, ghost, danger · size: default, compact · iconStart: Boolean plus an instance swap |
| Kind | variant and size are variants; the icon is a Boolean, the label a text property |
| Never changes | Radius, font, focus ring, hover and pressed colours |
| Not | A link styled as a button |
"Red" becomes variant="danger", a meaning. When the budget brand Skiff uses orange for danger, nothing in the API changes. The icon stays a Boolean, so the set is 4 × 2 = 8 frames instead of 16.
Watch out for
- Props named after looks.
blue,big,withBorderbreak as soon as a theme or a brand changes. Name the meaning. - A prop for every one-off. One screen's request is not a reason. Wait until a second team needs it, or solve it with a slot.
- Overriding tokens through props. "Just add
color" makes consistency optional. If teams need a new colour, it's a token conversation. - A Boolean that changes three things. That's a variant pretending to be a switch. Use the one-layer test: if two values differ in only one layer, it's a property, not a variant.
Template
Fill this in before you open Figma, then paste it at the top of the component's doc page.
Component: ...
Job: ... (one sentence)
Not for: ... (use ... instead)
Parts (name / required? / comes from / when it's long):
- ... / yes / text, token ... / wraps
- ... / no / component ... / ...
Props (name / type / values / default / Figma property kind):
- variant / enum / ..., ..., ... / ... / variant
- size / enum / ..., ... / ... / variant
- ... / boolean / true, false / false / boolean
- ... / slot / max ... items of ... / empty / slot
Never changes (tokens, browser): ...
States it must have: ...
Teams that asked for each prop: ...
- Design SystemsAlla KholmatovaBook · 2017 (Amazon)
- Design That ScalesDan MallBook · 2023 (Amazon)
- Explore component propertiesFigma Help (external site)
- Design system components, recipes, and snowflakesBrad Frost (external site)
- ButtonCarbon (external site)
"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.