Skip to content
NewTemplates & toolkits are on the way — join the waitlist
Hecham Gazhi

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:

LevelDescriptionExamples
AtomsSmallest building blocksButton, input, label, icon, avatar
MoleculesSimple groups of atoms working togetherSearch field (input + button), form field (label + input + help text)
OrganismsComplex sections made of molecules and atomsHeader, product card grid, data table
TemplatesPage-level layouts with placeholder contentProduct listing layout
PagesTemplates with real contentThe 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.

Exampletext
Text field anatomy
┌─────────────────────────────────────────┐
  ① Label  "Email"                 ② Optional indicator
┌─────────────────────────────────────────┐
│ ③ Leading icon  ④ Input text       ⑤ Trailing action │  ← ⑥ Container
└─────────────────────────────────────────┘
  ⑦ Helper text / error message      ⑧ Character count

Variants, 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

StateApplies toNotes
Default / restAll
HoverPointer devicesNever the only way to reveal information
Focus-visibleAll interactiveClear ring for keyboard users; never remove outlines without replacement
Active / pressedButtons, list items
Selected / checkedToggles, tabs, chips, rowsUse more than colour
DisabledControlsConsider whether disabling is the right choice
LoadingButtons, components that fetch dataPrevent duplicate actions
Error / invalidForm controlsIcon + text + colour
Read-onlyForm controlsVisible and copyable but not editable

Live preview

Button

Default

Button

Hover

Button

Focus

Button

Pressed

Button

Disabled

Button

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.
Exampletsx
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:

  1. 1A clear purpose and "when to use / when not to use" guidance.
  2. 2Named anatomy.
  3. 3All variants, sizes and states designed and built.
  4. 4Token-based styling only — no hard-coded values.
  5. 5Responsive behaviour and content limits (long labels, wrapping, truncation).
  6. 6RTL support.
  7. 7Keyboard interaction, focus management and screen-reader labels.
  8. 8Contrast checked in all themes.
  9. 9Matching Figma component and code component with the same API.
  10. 10Documentation with examples, do's and don'ts.
  11. 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

  1. Pick a component: text field, select or card.
  2. Draw its anatomy and name every part.
  3. List variants, sizes and states, and remove any that aren't truly needed.
  4. Write its API as a TypeScript type and as Figma properties with the same names.
  5. Go through the component checklist and note what's missing.

Test yourself

Components quiz

5 questions. Score 70% or more to complete the lesson.

  1. 1.In atomic design, a search field made of an input and a button is a…
  2. 2.Which state do keyboard users rely on most?
  3. 3.Why keep the number of variants low?
  4. 4.Why prefer variant="danger" over boolean props like isDanger and isPrimary?
  5. 5.A component made of freely combined parts like Card.Media and Card.Body uses…