Marcus Andrey Study
Ler em português Library

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.

1Job

What it does for the person, in one sentence.

"Starts an action"
2Parts

Each part named, required or not, and what happens when it's long.

Route: required, wraps
3Changes

Each real difference becomes a prop named after its meaning.

variant="danger", not red
4Never changes

Radius, font and focus ring stay in tokens, not props.

No "just add color"
5States

The states it must ship, listed before anything is drawn.

See the state matrix
6Not this

What 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

Six questions to answer in words before you draw a component, and the rule that turns each change into a variant, a property or a slot.

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

  1. 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."
  2. 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.
  3. 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.
  4. 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.
  5. 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.
  6. 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, withBorder break 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: ...
Source
Standard design-system practice, as described in the course lessons. Component properties (variant, Boolean, text, instance swap, slot): Figma Help. Components, recipes and snowflakes: Brad Frost (2021)

"See on Amazon" links are affiliate links. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

Saved only on this device.

↑ ↓ to move · Enter to open · Esc to close