Design Systems · Step 3 · 7 min read
Anatomy and API of a component
A component is a promise: these parts, these options, these rules, the same in Figma and in code. How to take a component apart into named parts, how to write its API before you draw it, and why the props table is the most useful page in the system.
A component is a promise, and its anatomy and API are the small print. When a designer drags Harbour's Ticket card into a screen and a developer imports it in code, both expect the same parts, the same options and the same limits. That only works if someone wrote them down: what the parts are called, which ones are required, what you can change and what you can't. Do that before you draw the variants, and half the arguments of the next six months never happen.
What you'll be able to do after reading:
- Take a component apart into named parts, and say which are required
- Write a component's API (props, types, defaults) before you design it
- Map each prop to its Figma property, so design and code match
- Tell a good API from one that will grow out of control
1. What a component is, in a system
In What a design system is you met components as one of the four parts of a system. Here's a sharper definition, from Brad Frost: design system components are "shared, content-agnostic, and context-agnostic built for maximal reuse" (Frost, Design system components, recipes, and snowflakes, 2021). A Button doesn't know it's on the booking screen; a Card doesn't know it holds a ticket.
Every component has two faces:
- Anatomy: the parts it's made of, with names. What you see.
- API: what someone using it can change, and how. What you can touch.
Public systems put both on every component page. IBM Carbon's button guidelines open their formatting section with the button's anatomy (Carbon, Button); the GOV.UK Design System gives each component "When to use this component", "When not to use" and "How it works" (GOV.UK, Button). Harbour does the same.
2. Anatomy: name every part
2Kestrel Bay → Mara Island
3On time409:40 · 50 min · Fri 4 Dec
- 1ContainerCard surface, border and radius tokens. Required.
- 2RouteText, the card's heading. Required. Wraps, never truncates.
- 3Status badgeA nested Badge component. Optional: on time, delayed, cancelled.
- 4Departure lineTime, duration and date, formatted by the system, not typed by hand.
- 5DetailsLabel and value pairs. Optional; zero to four.
- 6ActionsOne to two nested Buttons, compact size. The first is primary.
Harbour's Ticket card is the one people see most in the booking app. Taken apart, it has six parts. For each part, the anatomy answers four questions:
| Question | Ticket card, "Route" part |
|---|---|
| What is it called? | Route. The same word in Figma, in code and in the docs |
| Is it required? | Yes. A ticket without a route is a bug |
| Where does it come from? | Text, font.size.300, semibold; colour color.text.default |
| What happens when it's long? | It wraps. It never truncates, because "Mara Island Old Har…" is a different port |
Two of the parts are other components: the status is a Badge and the actions are Buttons. That's normal, and the anatomy should say so, because it means the card inherits their rules. If the Button's focus ring changes, the card's does too.
The names matter more than they look. If the designer calls it "title", the developer heading and the docs "route", three people will spend a meeting finding out they mean the same thing. Pick one, in the language of the product (a ferry ticket has a route), and use it everywhere.
3. API: what you can change
The API is the contract for the people who use the component. In code it's the props; in Figma it's the component properties. Here is the Button's, filled in:
| Prop | Type | Default | In Figma | Rule |
|---|---|---|---|---|
children | string | none, required | Text property Label | A verb, sentence case, two or three words: "Book crossing" |
variant | "primary" | "secondary" | "ghost" | "danger" | "primary" | Variant property Variant | One primary per view. Danger only for actions that can't be undone |
size | "default" | "compact" | "default" | Variant property Size | Compact is for the staff console's dense tables; still 32 px high |
iconStart | IconName | none | Boolean Show icon + instance swap Icon | Decorative: the label carries the meaning |
loading | boolean | false | Variant property State = Loading | Keeps focus and width; ignores further presses |
disabled | boolean | false | Variant property State = Disabled | Last resort. Say why next to it |
type | "button" | "submit" | "button" | none (code only) | Only the form's main action is submit |
onClick | () => void | none | Prototype interaction | Never on a div: the component renders a real <button> |
Read it as a list of decisions made once:
- The name of each prop says what it means, not what it looks like.
variant="danger", notcolor="red". When Skiff, the budget brand in Step 7, uses orange for danger, the API doesn't change. - The type limits the choices.
variantaccepts four values, not any string. Anything not on the list is a conversation with the system team, not a quiet override. - The default is the most common case. Most buttons are primary and default size, so a developer who writes
<Button>Book crossing</Button>gets the right thing. - Every prop has a Figma twin, with the same name. Figma has five kinds of component property: Boolean, instance swap, text, variant and slot (Figma Help, Explore component properties). The next lesson is about choosing between them.
- Some things are not props. Hover and focus belong to the browser; the label's font belongs to the tokens. If a prop lets people change those, consistency becomes optional.
4. Write the API before you draw
It's tempting to design the component first and let the API fall out of the frame. Do it the other way round. Before you open Figma, write down, in plain words:
- The job. "Starts an action. Not for navigation: that's a link."
- The parts, required and optional.
- What changes between uses: the label, the importance, the size. Each of those becomes a prop.
- What never changes: the radius, the font, the focus ring. Those stay in tokens.
- The states it must have (see States and edge cases).
- What it is not. "Not a link styled as a button. Not a toggle."
Then compare with two public systems. Material 3 has five common button types: elevated, filled, filled tonal, outlined and text (Material Web, Button). Carbon has primary, secondary, tertiary, ghost and danger (Carbon, Button). Harbour has four. Fewer is fine, as long as you can say what each one is for.
A small API is a feature. Every prop you add is one more thing to design, build, test, document and support forever. Add a prop when two or more teams need it, not when one screen might.
5. Common mistakes
- Designing the component first and inventing the API in the handoff (see Handoff to developers).
- Naming props after the look:
blue,big,withBorder. - Different names for the same part in Figma, code and docs.
- A prop for every one-off request, until nobody knows which combinations work.
- Letting people override tokens through props ("just add
color"). - Forgetting the "what it is not" line, so a Button ends up doing a link's job.
6. Vocabulary
| Term | Meaning |
|---|---|
| Anatomy | The named parts of a component, and which are required |
| API | What a user of the component can change: props in code, properties in Figma |
| Prop | One input of a coded component, with a name, a type and a default |
| Component property | Figma's version of a prop: Boolean, instance swap, text, variant or slot |
| Default | The value a prop has when nobody sets it; the most common case |
| Nested component | A component inside another, like the Button in the Ticket card |
7. Try it (no tools needed)
- Pick a component you use every day, like a search field or a product card.
- Draw it and number its parts. Give each one a name a developer would also use.
- Write its API as a list: prop, allowed values, default. Stop at six props.
Reflection questions: Which of your props describe a meaning, and which describe a look? Which part could you remove and still have the same component?
8. If you already practise
- Put the props table at the top of each component's doc page, and generate it from the code where you can, so it can't drift.
- Review new props like new components: who needs it, on how many screens, and what it costs to support.
- Keep a short "not this component" list per component, with what to use instead.
Checklist
Learn more
- Brad Frost, Design system components, recipes, and snowflakes (2021)
- Figma Help, Explore component properties
- Component pages: Carbon, Button · GOV.UK, Button · Material Web, Button
Books, courses and videos to go deeper
- Design SystemsAlla KholmatovaBook · Smashing Magazine, 2017 (Amazon)
- Design That ScalesDan MallBook · Rosenfeld Media, 2023 (Amazon)
Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.
Related
Tokens from Figma to code · Variants, properties and slots · States and edge cases · What a design system is · Handoff to developers · Component docs people use · Code Connect and the design-code bridge · Component API checklist