Marcus Andrey Study
Ler em português Library

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.

One component built like a toy: a long base with three shaped slots, a round one, a long one and a small square one, and the part that fits each seated in it. Point at a slot: its part lifts out and shows the empty slot underneath, while the parts beside it rise a touch. That's this step: a component is a frame with named slots, and what goes in each slot has to fit its shape. This step has five lessons: anatomy and API of a component, variants, properties and slots, states and edge cases, composition over configuration, and accessible components.Illustration: Marcus Andrey, drawn with Hairline (MIT, Lucas Marques).

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

Kestrel Bay → Mara Island

On time

09:40 · 50 min · Fri 4 Dec

Passengers
2 adults
Vehicle
None
  1. ContainerCard surface, border and radius tokens. Required.
  2. RouteText, the card's heading. Required. Wraps, never truncates.
  3. Status badgeA nested Badge component. Optional: on time, delayed, cancelled.
  4. Departure lineTime, duration and date, formatted by the system, not typed by hand.
  5. DetailsLabel and value pairs. Optional; zero to four.
  6. ActionsOne to two nested Buttons, compact size. The first is primary.
Harbour's Ticket card, taken apart. Each numbered part has a name, a rule for whether it's required, and the component or token it comes from. The card follows the site's light or dark mode, the way Harbour's modes would.

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:

PropTypeDefaultIn FigmaRule
childrenstringnone, requiredText property LabelA verb, sentence case, two or three words: "Book crossing"
variant"primary" | "secondary" | "ghost" | "danger""primary"Variant property VariantOne primary per view. Danger only for actions that can't be undone
size"default" | "compact""default"Variant property SizeCompact is for the staff console's dense tables; still 32 px high
iconStartIconNamenoneBoolean Show icon + instance swap IconDecorative: the label carries the meaning
loadingbooleanfalseVariant property State = LoadingKeeps focus and width; ignores further presses
disabledbooleanfalseVariant property State = DisabledLast resort. Say why next to it
type"button" | "submit""button"none (code only)Only the form's main action is submit
onClick() => voidnonePrototype interactionNever on a div: the component renders a real <button>
The API of Harbour's Button, filled in. Every row is a decision someone made once, so nobody makes it again: the name, the allowed values, the default, how it appears in Figma, and the rule for using it. Hover and focus aren't props: the browser sets them.

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", not color="red". When Skiff, the budget brand in Step 7, uses orange for danger, the API doesn't change.
  • The type limits the choices. variant accepts 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:

  1. The job. "Starts an action. Not for navigation: that's a link."
  2. The parts, required and optional.
  3. What changes between uses: the label, the importance, the size. Each of those becomes a prop.
  4. What never changes: the radius, the font, the focus ring. Those stay in tokens.
  5. The states it must have (see States and edge cases).
  6. 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)

  1. Pick a component you use every day, like a search field or a product card.
  2. Draw it and number its parts. Give each one a name a developer would also use.
  3. 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

Books, courses and videos to go deeper

Book links go to Amazon. As an Amazon Associate I earn from qualifying purchases, at no extra cost to you.

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

Saved only on this device.

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