Design Systems · Lesson 07 / 13
Components
How to design system components that last: atomic design, anatomy, variants and properties, sizes, states, composition vs configuration, API design and a component checklist.
4 min read · 5 quiz questions
What makes a good system component
A component in a design system is a reusable piece of UI — a button, an input, a card — with a defined anatomy, a fixed set of options, every state designed, accessibility built in, and matching implementations in design and code.
Good components are flexible enough to cover real product needs, constrained enough to keep the UI consistent, and well documented so people use them correctly.
Atomic design
Brad Frost's atomic design is a popular way to think about how components build on each other:
| Level | Description | Examples |
|---|---|---|
| Atoms | Smallest building blocks | Button, input, label, icon, avatar |
| Molecules | Simple groups of atoms working together | Search field (input + button), form field (label + input + help text) |
| Organisms | Complex sections made of molecules and atoms | Header, product card grid, data table |
| Templates | Page-level layouts with placeholder content | Product listing layout |
| Pages | Templates with real content | The actual Shoes category page |
You don't have to use these names. The useful idea is that small, well-built parts compose into larger ones — so fixing an atom improves everything built from it.
Anatomy
Document the named parts of each component. Shared names make reviews and code easier.
Text field anatomy
┌─────────────────────────────────────────┐
① Label "Email" ② Optional indicator
┌─────────────────────────────────────────┐
│ ③ Leading icon ④ Input text ⑤ Trailing action │ ← ⑥ Container
└─────────────────────────────────────────┘
⑦ Helper text / error message ⑧ Character countVariants, properties and sizes
Variants
Visual versions for different emphasis or purpose: primary, secondary, tertiary, destructive. Each variant should have a clear "when to use" rule.
Properties
Options that can be combined: size (sm, md, lg), icon (none, leading, trailing, icon-only), full width (true/false), loading (true/false).
Sizes
Fixed sizes mapped to the sizing and spacing tokens, so components of the same size align in a row.
Common mistake: Variant explosion. Every new variant multiplies design, code, testing and documentation work — a button with 5 variants × 3 sizes × 4 icon options × 6 states already means 360 combinations. Add variants only when there's real, repeated need.
States
| State | Applies to | Notes |
|---|---|---|
| Default / rest | All | |
| Hover | Pointer devices | Never the only way to reveal information |
| Focus-visible | All interactive | Clear ring for keyboard users; never remove outlines without replacement |
| Active / pressed | Buttons, list items | |
| Selected / checked | Toggles, tabs, chips, rows | Use more than colour |
| Disabled | Controls | Consider whether disabling is the right choice |
| Loading | Buttons, components that fetch data | Prevent duplicate actions |
| Error / invalid | Form controls | Icon + text + colour |
| Read-only | Form controls | Visible and copyable but not editable |
Live preview
Default
Hover
Focus
Pressed
Disabled
Loading
Configuration vs composition
There are two ways to make components flexible:
- Configuration — one component with many props:
<Card title image badge footer actions variant />. Simple to use for common cases, but props pile up as needs grow. - Composition — smaller parts combined freely:
<Card><Card.Media/><Card.Body/><Card.Actions/></Card>. More flexible for unusual layouts, but more to learn.
Many systems use both: configuration for simple, highly consistent components (Button, Badge) and composition for containers with varied content (Card, Modal, Table).
Designing the component API
The API is the set of names and options people use — in Figma properties and in code props. Keep them aligned and predictable.
- Use the same names in Figma properties and code props.
- Choose sensible defaults so the simplest usage is the most common one.
- Prefer enums (
variant="danger") over many booleans (isDanger isPrimary), which can conflict. - Don't expose raw style overrides (custom colours, margins) unless necessary — they undermine consistency.
type ButtonProps = {
variant?: "primary" | "secondary" | "tertiary" | "danger"; // default "primary"
size?: "sm" | "md" | "lg"; // default "md"
iconStart?: React.ReactNode;
iconEnd?: React.ReactNode;
loading?: boolean;
disabled?: boolean;
fullWidth?: boolean;
type?: "button" | "submit" | "reset";
children: React.ReactNode; // the label
};
<Button variant="primary" size="md" iconEnd={<ArrowRight />}>Continue</Button>Component checklist
Before a component is marked as ready, check that it has:
- 1A clear purpose and "when to use / when not to use" guidance.
- 2Named anatomy.
- 3All variants, sizes and states designed and built.
- 4Token-based styling only — no hard-coded values.
- 5Responsive behaviour and content limits (long labels, wrapping, truncation).
- 6RTL support.
- 7Keyboard interaction, focus management and screen-reader labels.
- 8Contrast checked in all themes.
- 9Matching Figma component and code component with the same API.
- 10Documentation with examples, do's and don'ts.
- 11Tests: visual regression, accessibility and unit tests in code.
Key takeaways
- System components have a defined anatomy, limited options, every state, built-in accessibility and matching design/code versions.
- Atomic design shows how small parts compose into bigger ones.
- Add variants only for real, repeated needs — variant explosion is costly.
- Use configuration for simple components and composition for flexible containers.
- Align the API across Figma and code, with good defaults and enum options.
Exercise
Specify a component
- Pick a component: text field, select or card.
- Draw its anatomy and name every part.
- List variants, sizes and states, and remove any that aren't truly needed.
- Write its API as a TypeScript type and as Figma properties with the same names.
- Go through the component checklist and note what's missing.
Test yourself
Components quiz
5 questions. Score 70% or more to complete the lesson.
