Build design tokens and component specs, hand designs to engineers with clear annotations, and measure and iterate after launch.

Design Systems & Developer Handoff

Choose a product and five to eight of its most-used screens. Write them down.

Create one board per category: buttons, text styles, colours, form inputs, error and alert messages, and one more of your choice.

Screenshot every instance of each category across your chosen screens, crop it and place it on its board.

Group identical instances and count the distinct variations in each category.

For each category, note the differences that matter (size, colour, radius, label style, states) and any that look inaccessible, such as low-contrast text.

Fill in a table: category, variations found, notes, and a proposed consolidated set.

Write a three-sentence summary you could send to a product manager explaining why consolidation is worth doing.

## Why it matters

As a product grows, small inconsistencies pile up. One team's button has 4px corners, another's 8px. There are eleven shades of grey, three date pickers and two different error styles. Each one was a reasonable decision on the day, but together they make the product feel unreliable, slow designers down ("which button do I use?") and multiply engineering work, because every variation has to be built, tested and maintained.

A **design system** is how teams stop that drift. Knowing how to use, extend and argue for one is a core mid-level skill: most product design jobs today involve working inside a system rather than designing every screen from scratch.

## The core idea: shared decisions, written down and built once

A design system is a collection of reusable decisions, with the code and documentation that make them easy to follow. It usually has these layers:

| Layer | What it is | Example |
|---|---|---|
| Principles | The values that guide decisions | "Clear over clever" |
| Design tokens | Named values for colour, type, spacing, radius, shadow, motion | `color-primary`, `space-4` |
| Components | Reusable UI parts with states and variants | Button, Input, Modal |
| Patterns | Combinations of components for common jobs | Sign-in form, empty state |
| Documentation | When and how to use each piece | Usage guidelines, do and don't |
| Code library | The components implemented for developers | A React or web component package |
| Governance | How changes are proposed, reviewed and released | Contribution process, versioning |

A **style guide** (colours and fonts) or a **UI kit** (a Figma file of components) is part of a system, not the whole thing. A system only works when design and code match and people know how to contribute.

Well-known public systems are worth studying: Google's Material Design, IBM's Carbon, the UK government's GOV.UK Design System, Shopify's Polaris and Atlassian's design system all publish their tokens, components and guidelines for free.

## What a system buys you

- **Consistency**: users learn a pattern once and recognise it everywhere.
- **Speed**: designers assemble screens from tested parts; developers reuse code.
- **Quality**: accessibility, states and edge cases are solved once in the component.
- **Easier change**: update a token, and every screen that uses it updates.

The cost is real too: someone has to maintain it, and a system that is too rigid or out of date gets ignored. Small teams often start with tokens and a handful of core components, not a full system.

## The interface inventory (UI audit)

The classic way to start, or to justify, a design system is an **interface inventory**: collect every instance of each UI element across the product and put them side by side. Brad Frost popularised this approach. The visual evidence ("we have 14 button styles") persuades teams far better than any argument.

How to run one:

1. **Choose the scope**: a product, or the five to ten most-used screens.
2. **Pick categories**: buttons, form inputs, colours, type styles, icons, spacing, cards, alerts and messages, modals.
3. **Screenshot every instance** and crop it. Paste each category onto its own board (paper, slides or free Figma).
4. **Group duplicates** and count the variations.
5. **Note the differences** that matter: size, colour, corner radius, label style, states.
6. **Recommend a consolidated set**: for example, "3 button variants (primary, secondary, danger) in 2 sizes".

## Worked example: a small audit

An audit of a booking site's top eight screens found:

| Category | Variations found | Notes | Proposed |
|---|---|---|---|
| Primary buttons | 6 | 3 blues, radius 2/4/8px, 36 to 52px tall | 1 style, 2 sizes |
| Greys used for text | 9 | Several fail contrast on white | 3 text greys |
| Error messages | 4 | Red text, red box, toast, alert icon only | 1 inline pattern + 1 page alert |
| Date pickers | 3 | Two custom, one native | 1 accessible picker |
| Font sizes | 13 | 11px to 40px with no scale | 7-step type scale |

This table, plus the boards of screenshots, became the case for building tokens (next lesson) and a small component library.

## Common mistakes

- **Starting with a huge library.** Build what the product actually uses; grow from real needs.
- **Design-only systems.** A Figma kit that does not match the code creates two sources of truth.
- **No owner.** Without governance, the system drifts like the product did.
- **Auditing opinions instead of instances.** Collect what exists before deciding what is "right".
- **Treating the system as a rulebook only.** It should make the right choice the easy choice, with clear docs and a way to propose changes.

## Quick recap

- A design system is shared, reusable decisions: tokens, components, patterns, docs, code and governance.
- It buys consistency, speed, quality and easier change, at the cost of maintenance.
- An interface inventory collects every instance of each UI element to show inconsistency and guide consolidation.

## Try it

On the Do tab you will run an interface inventory on a real product and propose a consolidated set of components.


Explain what a design system contains and why teams build one, then audit a real interface for inconsistency.

Why design systems

Welcome to design systems - Lesson 1 : Introduction to design systems

What is a Design System? 6 Different Types of Design Systems

## Why it matters

Design tokens are the smallest, most reused decisions in a product: the exact blue of the primary button, the body text size, the gap between a label and its input. When those decisions live as hard-coded values scattered across hundreds of files and Figma layers, changing one (a rebrand, a dark mode, an accessibility fix) means hunting down every copy. **Design tokens** give each decision a name and a single source, so designers and developers use the same value and change it in one place.

## The core idea: name the decision, not the value

A token is a name-value pair: `color-primary = #2563eb`. The name is what people use. The value can change without anyone editing the places that use it.

Most systems use two (sometimes three) tiers:

| Tier | Purpose | Examples |
|---|---|---|
| Primitive (core, global) | The palette and raw scales, named by what they are | `blue-600: #2563eb`, `space-3: 16px` |
| Semantic (alias) | What a value is *for*, pointing at a primitive | `color-primary: blue-600`, `color-text: gray-900` |
| Component (optional) | One component's specific use | `button-padding-x: space-4` |

Designers and developers should mostly use **semantic** tokens. A button uses `color-primary`, not `blue-600`. Then a dark theme or a rebrand only changes which primitive each semantic token points at.

## Tokens in Figma and in code

In **Figma** (free plan included), **variables** store tokens: colour, number and string variables, organised into collections, with **modes** for themes such as light and dark. **Styles** (colour, text, effect) are an older, still common way to share values. Figma's free plan has some limits on modes, so check the current plan details if you need many themes.

In **code**, the simplest form of tokens is **CSS custom properties** (CSS variables):

```css
:root {
  --blue-600: #2563eb;          /* primitive */
  --color-primary: var(--blue-600);  /* semantic points at primitive */
  --space-3: 16px;
}

.button {
  background: var(--color-primary);
  padding: var(--space-2) var(--space-4);
}
```

A custom property is declared with two dashes, usually on `:root` (the `html` element) so it is available everywhere, and read with `var()`. Custom properties cascade and can be overridden, which is how themes work:

```css
:root[data-theme="dark"] {
  --color-text: #f9fafb;
  --color-surface: #111827;
}
```

Many teams keep tokens in a JSON file and use a build tool (Style Dictionary is a popular free one) to generate CSS, iOS and Android formats from the same source. The W3C Design Tokens Community Group is working on a standard JSON format so tools can share tokens.

## Worked example: a small token set

```text
Colour primitives   blue-600 #2563eb   blue-700 #1d4ed8   gray-900 #111827   gray-100 #f3f4f6   white #ffffff
Colour semantic     color-primary -> blue-600        color-primary-hover -> blue-700
                    color-on-primary -> white        color-text -> gray-900
                    color-surface -> white           color-background -> gray-100
Type                font-size-body 16px   font-size-heading 28px
Spacing (4/8 base)  space-1 4px   space-2 8px   space-3 16px   space-4 24px
Radius              radius-md 12px
```

Note the spacing tokens are named by step, not by pixel value (`space-3`, not `space-16`), so the scale can be tuned later without names becoming lies. Check that each semantic colour pairing meets contrast requirements: white on `#2563eb` passes WCAG AA for normal text (about 5.2:1).

## Naming tips

- Use a consistent pattern: `category-role-variant-state`, such as `color-primary-hover`.
- Name by purpose for semantic tokens (`color-danger`), never by appearance (`color-red`), so a theme can change the appearance.
- Keep the set small. Every token is a decision someone must understand.
- Document which pairs are safe together (text on surface, on-primary on primary).

## Common mistakes

- **Using primitives directly in components.** Themes then need every component changed.
- **Appearance names for semantic tokens.** `color-blue-button` breaks the moment the button turns green.
- **Tokens only in Figma** or only in code. They must match; one source should generate the other, or be checked regularly.
- **Hundreds of one-off tokens.** If a value is used once, it probably does not need a token.
- **Ignoring contrast** when defining colour pairs.

## Quick recap

- Tokens name design decisions so they are used and changed from one source.
- Primitive tokens hold raw values; semantic tokens say what a value is for and point at primitives.
- In Figma, use variables (with modes for themes); in code, CSS custom properties on `:root`, read with `var()`.
- Name by purpose, keep the set small, and keep design and code in sync.

## Try it

On the Do tab you will replace hard-coded values in a small page with colour, type and spacing tokens written as CSS custom properties.


Define primitive and semantic tokens for colour, type and spacing, and apply them with CSS custom properties.

Design tokens

Tokens, variables, and styles - Update: Introduction to design systems

CSS Variables - An introduction to CSS custom properties

Choose the component and list its anatomy: every named part.

List its variants (for example type and size) and write when each should be used.

List every state it needs: at least default, hover, focus, pressed or filled, disabled, and one of loading or error.

Build or sketch a grid with variants as rows and states as columns, so every combination is visible.

For each cell, note which tokens it uses (colour, spacing, type, radius). Mark any value that is not a token.

Check every focus state is clearly visible against its background, and every text colour has enough contrast.

Write the behaviour rules: keyboard interaction, long content, minimum target size and accessible name.

Write two usage rules (do and don't) that would stop someone misusing the component.

## Why it matters

A component that only exists as one pretty picture will be built differently by every developer who touches it. What happens on hover? What does it look like disabled, loading or with a very long label? Does it work with a keyboard? A **component spec** answers those questions once, so the component is built correctly, documented, and reused everywhere. Writing clear specs is one of the clearest signs of a mid-level designer.

## The core idea: anatomy, variants, states, behaviour

A complete spec covers four things.

**1. Anatomy.** The named parts of the component. For a button: container, label, optional leading icon, optional trailing icon. Name parts the way developers will (match the code where possible).

**2. Variants.** Deliberate, *designed* differences that a designer chooses when placing the component:

- **Type or emphasis**: primary, secondary, tertiary (text-only), danger.
- **Size**: small, medium, large.
- **Content options**: with icon, icon-only.

**3. States.** Differences caused by *interaction or system status*, which every variant must handle:

| State | Trigger | Typical visual change |
|---|---|---|
| Default (rest) | Nothing happening | Base style |
| Hover | Pointer over it | Slightly darker background |
| Focus | Keyboard focus | Visible focus ring (at least 3:1 against the background) |
| Active (pressed) | Being pressed | Darker still, or slight inset |
| Disabled | Not available | Reduced emphasis; not focusable or explained |
| Loading | Action in progress | Spinner, label kept or changed to "Saving...", repeat clicks blocked |

Form inputs add more: filled, error, read-only, and help-text states. Remember that a state like focus must be visible on every variant, not just the primary one.

**4. Behaviour and content rules.** What happens and what is allowed: keyboard support (Enter and Space activate a button), long labels (wrap or truncate?), minimum target size (for example at least 24 by 24 CSS pixels under WCAG 2.2, and many teams use 44 or 48), icon-only buttons need an accessible name, and when to use each variant ("one primary button per view").

## Variants in Figma

In Figma, a **component set** groups variants and uses **properties** to switch between them. A button might have:

- `Type` = Primary, Secondary, Danger (variant property)
- `Size` = Small, Medium (variant property)
- `State` = Default, Hover, Focus, Pressed, Disabled, Loading (variant property)
- `Label` (text property) and `Show icon` (boolean property)

Three types x two sizes x six states = 36 variants. That sounds like a lot, but building them all is how you find gaps, such as a danger button whose focus ring is invisible against red. Build each variant with auto layout and tokens (variables), so changes flow through.

## Worked example: a button spec

```text
Component: Button
Anatomy: container | leading icon (optional) | label | trailing icon (optional)
Variants:
  Type: primary (filled, color-primary), secondary (outline, color-primary border),
        danger (filled, color-danger)
  Size: medium (height 44, padding-x space-4, font-size-body)
        small  (height 32, padding-x space-3, font-size-small)
States (every type and size):
  hover    background -> *-hover token
  focus    2px focus ring color-focus, 2px offset, visible on all types
  pressed  background -> *-active token
  disabled 40% opacity is NOT used (fails contrast); use color-disabled-bg and
           color-disabled-text, and prefer explaining why the action is unavailable
  loading  spinner replaces leading icon, label "Saving...", aria-busy, ignore repeat clicks
Behaviour:
  Enter and Space activate. Label wraps to max 2 lines; never truncate.
  Icon-only buttons require an accessible label (e.g. "Close").
Usage:
  One primary button per view. Danger only for destructive, irreversible actions.
```

Notice the spec ties every visual decision to a **token** (previous lesson), covers every state for every variant, and states rules that a developer or a future designer can follow without asking you.

## Where specs live

Specs live in the design file (a documentation page next to the component) and in the system's docs site. Many teams also document components in code with a tool such as Storybook, which shows each state live. Whatever the tool, design and code docs should say the same thing.

## Common mistakes

- **Only designing the default state.** Developers then invent hover, focus and error.
- **Confusing variants and states.** A danger button is a variant; hovered is a state. Mixing them creates a tangled component set.
- **Invisible focus** on some variants.
- **Disabled = low opacity** text that nobody can read, with no explanation.
- **Hard-coded values** instead of tokens.
- **No usage rules.** Without "when to use", people use the danger style because they like red.

## Quick recap

- A component spec covers anatomy, variants, states and behaviour, plus usage rules.
- Variants are designed choices (type, size); states come from interaction (hover, focus, pressed, disabled, loading).
- In Figma, build a component set with variant, text and boolean properties, using auto layout and variables.
- Every state must exist and be accessible on every variant.

## Try it

On the Do tab you will write a full spec for a component, with every state for every variant.


Specify a component's anatomy, variants, states and behaviour so it can be built once and used everywhere.

Component specs

Figma Tutorial: Variants

Figma components and variants for beginners

Audit a product for inconsistency, define colour, type and spacing tokens, and spec components with states and variants.