---
title: "Design System Template"
type: template
template_for: "a design system document (docs/design.md) for an app codebase, read by AI coding agents"
notion_copy: "https://app.notion.com/p/40228f1440b98174b095ef8dfbd5e51b"
used_by: []
kit: ""
date_added: 2026-10-22
last_reviewed: 2026-10-22
tags: []
---

# Design System Template

<!--
HOW TO USE THIS TEMPLATE
========================
0. Survey the repo ONCE before writing anything. Do not fill sections in the
   order they appear until this is done. Find and note: the UI framework and
   styling engine (`package.json`), the token source file (a Tailwind `@theme`
   block, a CSS variables file, or a theme object), the component directories
   and how many components each holds, the layout or shell components, the
   class-merge helper, and three or four finished screens to read for visual
   character. Everything below assumes you already know these paths. Every
   value you write must be counted out of the code you just found. If you
   cannot find a value, mark it TBD rather than inventing a plausible one.
1. This file is scaffolding, not a deliverable. Do not copy it into the target
   repo. Fill it in and save the finished document as `docs/design.md` in the
   target repo, or at the repo root as `design.md` if there is no `docs/`
   folder. Rename the H1 to "<Product> Design System".
2. Fill each section in order. Every section carries a "How to derive this"
   note. Follow it. Read the values out of the codebase, not out of a mockup.
3. Delete every section marked "Include only if applicable" that does not
   apply to the repo. A padded document stops being read.
4. Delete every instruction block, including this one, before shipping.
5. Add the CLAUDE.md stub at the bottom of this file to the repo's CLAUDE.md.
   Without it, the document exists but never gets loaded.

   If a person is doing this: copy that block, paste it into the repo's
   CLAUDE.md, and fill in the three rules.

   If an agent is reading this file: adding that block to the repo's CLAUDE.md
   is part of the job, not an optional follow-up. Create CLAUDE.md at the repo
   root if it does not exist. If it does exist, append the block as a new
   "## Design system" section rather than replacing anything already there.

WHY THE DERIVATION NOTES MATTER
A section list alone produces a form. The value of a design document is that
each number is counted out of the code, so "the convention" means "what the
code actually does most", not "what the scale offers". Do the counting.

SECTION STATUS
Required:  Overview, Token architecture, Colors, Typography, Spacing, Shape,
           Elevation, Component library, Accessibility, Do's and don'ts,
           Building a new screen, Known gaps, Source files.
Optional:  Page shells, Forms and inputs, Charts and data display, Motion,
           Theming and dark mode.
-->

# [Product] Design System

The reference for any new screen, component, or user flow in [product].

**What this is.** Every value here was read out of the codebase, not out of a mockup. Where the code disagrees with itself, this document names the convention to follow and records the disagreement under [Known gaps](#known-gaps).

**Marking.** Each point is one of three states:

- **Resolved.** This is how the system works. Follow it.
- **Proposed - needs validation:** a first-pass reading that needs [owner]'s sign-off.
- **TBD - open task. Owner: [role].** Nobody has decided yet. Do not treat it as settled.

**Read this first if you are:** building a new page ([Building a new screen](#building-a-new-screen)), picking a colour ([Token architecture](#token-architecture)), or choosing a card treatment ([Elevation](#elevation)).

---

## Contents

1. [Overview](#overview)
2. [Token architecture](#token-architecture)
3. [Colors](#colors)
4. [Typography](#typography)
5. [Spacing](#spacing)
6. [Page shells](#page-shells)
7. [Shape](#shape)
8. [Elevation](#elevation)
9. [Component library](#component-library)
10. [Forms and inputs](#forms-and-inputs)
11. [Charts and data display](#charts-and-data-display)
12. [Motion](#motion)
13. [Accessibility](#accessibility)
14. [Theming and dark mode](#theming-and-dark-mode)
15. [Do's and don'ts](#dos-and-donts)
16. [Building a new screen](#building-a-new-screen)
17. [Known gaps](#known-gaps)
18. [Source files](#source-files)

---

## Overview

> **How to derive this.** Read `package.json` for the UI framework, styling engine, and component library. Find the token source file (a Tailwind `@theme` block, a CSS variables file, a theme object, or similar). Count the components in each directory tier. Then look at three or four finished screens and describe the visual character in plain words.

**Resolved.** The stack is [component library] on [styling engine]. Design tokens live in [path]. [Note anything unusual, for example: there is no config file because the styling engine reads a single theme block.]

The system is built from three things:

| Layer | Where | What it is |
|---|---|---|
| **Tokens** | [path] | Colours, type scale, radius, shadow, breakpoints |
| **Components** | [paths] | [count] reusable pieces |
| **Shells** | [paths] | [count] page frames. Every screen lives in one. |

**The visual character.** [Two or three sentences. Light or dark. Dense or airy. What the page floor is, what content sits on, how the accent hue is used. Be concrete.]

**Key characteristics:**

- [The typeface situation in one line.]
- [The card treatment in one line, for example: cards are bordered, not shadowed.]
- [The working palette in one line, including which available colours are unused.]
- [The dominant font weight in one line.]
- [Any capability that exists in code but does not render, for example light-only in practice.]

---

## Token architecture

> **How to derive this.** Find every layer between a raw value and a component: raw hex, primitive ramps, semantic aliases, utility ramps. Then grep the codebase for raw values (`grep -rE '#[0-9a-fA-F]{6}' src/`) and count the files. State plainly which layer a component author is allowed to touch.

**Resolved. This is the rule that matters most.**

Colour is [N] layers. Which layer you reach for is not a style preference.

| Layer | Example | Use it? |
|---|---|---|
| **1. Raw values** | `[#example]` | **Never.** |
| **2. Primitive ramps** | `[--color-brand-600]` | **No.** Implementation detail of layer 3. |
| **3. Semantic aliases** | `[bg-primary, text-secondary]` | **Yes. This is the default API.** |
| **4. Utility ramps** | `[bg-utility-success-50]` | **Yes, but only** for status and data visualisation. |

In one line: **[state the rule in a single sentence].**

### Why it matters concretely

[Give the concrete consequence, not a tidiness argument. For example: the theme redefines aliases, not ramps, so a component written against a raw value can never be themed.]

### Recognising a violation

If you are typing a [raw value], stop. The sanctioned exceptions, and only these:

1. [Third-party brand colours, if applicable.]
2. [SVG asset internals, if applicable.]
3. [User-chosen values, if applicable.]

---

## Colors

> **How to derive this.** Copy the ramps out of the token file exactly, including the notation used (hex, rgb, oklch). For each step, grep for its alias to find where it is actually used, and put that in the "use" column. A ramp step with no use is dormant and should be labelled as such.

### Notation

[State how values are written in the token source, and give both forms if the file mixes them, so a search for either succeeds.]

### [Brand / accent ramp]

| Token | Value | Common use |
|---|---|---|
| `[--color-brand-50]` | `[value]` | [alias and where it appears] |
| ... | | |

### [Neutral ramp]

| Token | Value | Role |
|---|---|---|
| `[--color-gray-50]` | `[value]` | [for example: the page floor] |
| ... | | |

### Status ramps

| Step | Success | Warning | Error |
|---|---|---|---|
| [50] | `[value]` | `[value]` | `[value]` |
| ... | | | |

**The convention for a status treatment:**

```
[fill class]   [text class]   [border class]
```

[State the pairing in one line, for example: fill at 50, text at 700, border at 200. Do not invent a different pairing.]

### Semantic aliases worth memorising

| Alias | Resolves to | Meaning |
|---|---|---|
| `[bg-primary]` | [value] | [Card surface] |
| ... | | |

### The extended palette

> **How to derive this.** List every ramp the token file ships. Then grep for each one outside the component that declares it. Ramps with zero product uses are stock library defaults, not a product decision. Say so.

**Resolved.** [List the ramps that exist but are unused.]

**The rule: [state whether to use them, and who must approve adding one].**

---

## Typography

> **How to derive this.** Read the font loading (the HTML head, a font import, or a CSS `@font-face`). Copy the size scale out of the token file with its line heights and tracking. Then grep for each semantic type utility and record the adoption count, so "prefer this" is an honest instruction rather than a wish.

### Family

**Resolved.** [Typeface(s)], loaded from [source] as [static or variable].

```css
[--font-body: ...]
[--font-display: ...]
[--font-mono: ...]
```

[Note if two font tokens resolve to the same family, and what that means.]

### The scale

**Resolved.** [State the base unit and where it comes from.]

| Token | Size | Line height | Tracking |
|---|---|---|---|
| `[text-xs]` | [12px] | [18px] | [0] |
| ... | | | |

[Note any renamed or non-standard step, for example: `text-md` is 16px and is the body default.]

[Note where negative tracking starts.]

### The semantic layer (prefer this)

**Resolved.** [Path] defines [N] semantic utilities that bundle size, line height, weight, and colour into one class. They are the intended API.

| Utility | Size | Weight | Colour | Use for |
|---|---|---|---|---|
| `[text-heading-lg]` | [30px] | [600] | [primary] | [Page title] |
| ... | | | | |

**Adoption is currently [N] uses across the app.** [State what most screens do instead.]

**The rule for new work: use the semantic utility.**

### Weights

**Resolved.** [N] weights.

| Weight | Use |
|---|---|
| [400] | [Body copy] |
| [500] | [Labels] |
| [600] | [Headings, buttons, nav] |
| [700] | [If used at all, name the single place] |

[State the emphasis rule, for example: go up a size, not up a weight.]

### Numerals

[State the rule for numbers in columns, for example `tabular-nums` on anything in a column or that updates in place.]

---

## Spacing

> **How to derive this.** Find the base unit in the token file. Then grep the padding and gap classes actually used across `src/` and list only the values that appear. A scale nobody uses is noise.

**Resolved.** Base unit [Npx]. The values actually in use:

| px | Class | Use |
|---|---|---|
| [4] | `[gap-1]` | [Icon to label] |
| ... | | |

**Page-level rhythm:** [Npx] between sibling cards, [Npx] between major page regions.

### Container widths

| Token | Value | Where |
|---|---|---|
| `[--max-width-container]` | [1280px] | [Which shell] |
| [Sidebar] | [256px] | [Which shell] |

### Breakpoints

| Name | Width | Source |
|---|---|---|
| `[sm]` | [640px] | [Default or custom] |
| ... | | |

[Name the one breakpoint that carries the real mobile/desktop switch, and what changes there.]

---

## Page shells

> **Include only if applicable.** Skip if the app has a single layout.
>
> **How to derive this.** List the layout components. For each, paste the actual class string of its root and its main regions, count how many pages use it, and state in one line when to pick it.

**Resolved.** Every screen lives in exactly one of [N] page frames. Picking the right one is the first decision on a new screen.

### 1. `[LayoutName]` - [what it is for]

`[path]`

```
[root classes]
├── [region]   [classes]
└── [region]   [classes]
```

- [Notable detail, for example where the nav config lives.]
- [Notable detail, for example a deliberate omission and why.]
- **Use for:** [one line].

[Repeat per shell.]

### Choosing

| The screen is... | Shell |
|---|---|
| [description] | `[Layout]` |

---

## Shape

> **How to derive this.** List the radius scale from the token file. Then count occurrences of each step across `src/` and put the count in the table. The convention is the ranking, not the scale. If a design tool holds a separate radius scale, check that the two agree and record the result with a date.

### Radius scale

| Token | Value | px | Uses in code | Use |
|---|---|---|---|---|
| `[rounded-sm]` | [0.25rem] | [4px] | [N] | [Where] |
| ... | | | | |

**The convention, from what the code actually does:** [controls Npx, cards Npx, large panels Npx, full-bleed bands Npx]. [State the governing idea in one line, for example: the bigger the surface, the bigger the radius.]

[If a design tool holds its own scale: state whether it agrees, on what date it was checked, and name any token that exists on one side only.]

---

## Elevation

> **How to derive this.** Count the separation techniques in use: `grep -ro 'border border-secondary' src/ | wc -l` against the ring and shadow equivalents. Name the winner as the convention and paste the exact winning class string. Then find the exception (usually library primitives) and name it rather than explaining it away.

**Resolved.** The system uses [N] different separation techniques, and they are not interchangeable.

| Technique | Where | Example |
|---|---|---|
| **`[border]`** | **[Cards and panels. The default.]** | `[exact class string]` |
| **`[ring]`** | [Interactive controls] | `[exact class string]` |
| **`[shadow]`** | [Things that float] | [Modals, dropdowns, popovers] |

Counted across `src/`: **[N] [technique] to [N] [technique].** [Technique] is the card convention.

The most common card in the codebase, verbatim:

```
[exact class string]
```

### The exception

[Name where the rule breaks, for example: feature-level cards use border, library primitives use ring. State which one a new screen should follow.]

### Why [the control technique] on controls

[Give the mechanical reason, for example: a ring does not participate in layout, so focus can thicken it without reflowing.]

### Shadow scale

| Token | Use |
|---|---|
| `[shadow-xs]` | [Inputs, resting buttons] |
| ... | |

[Paste any custom shadow definition that carries visual character, with its CSS.]

---

## Component library

> **How to derive this.** List the component directories and what lives in each. Then find the authoring convention by reading two or three components side by side: how variants are declared, how classes are merged, whether a `className` prop is forwarded. A component written without that convention will not look like the codebase. Document buttons, badges, tables, tabs, modals, and empty states individually, because those are the pieces most often rebuilt from scratch.

**Resolved.** [N] components in [N] tiers. Check for an existing one before building anything.

| Tier | Path | What lives there |
|---|---|---|
| **[Base]** | `[path]` | [Primitives] |
| **[Application]** | `[path]` | [Assemblies] |
| **[Foundations]** | `[path]` | [Marks and icons] |

### How components are authored

**Resolved.** [Name the convention and show it.]

```[jsx]
[A short, real example from the codebase showing variant declaration and class merging.]
```

[List what the convention buys, in two or three numbered points.]

### Buttons

`[path]`. [Base library.] Defaults are [size] and [colour].

**Sizes:**

| Size | Padding | Type | Height |
|---|---|---|---|
| `[sm]` | `[px-3 py-2]` | `[text-sm font-semibold]` | [36px] |
| ... | | | |

**Colours:**

| Colour | Treatment | Use for |
|---|---|---|
| `[primary]` | [fill and text] | [The one main action on a screen] |
| ... | | |

[State the one-primary-per-region rule.]

[Note any variant with a trap in it, for example a padding override that breaks tap targets, and link it to Known gaps.]

### Cards

| Kind | Class string | Use for |
|---|---|---|
| **Standard card** | `[exact class string]` | [Default container] |
| [Metric or KPI tile] | `[exact class string]` | [Numbers] |
| [Selection card] | `[exact class string]` | [Choices] |

Standard padding is [Npx]. [Note the hover or selected treatment if one exists.]

### Badges

`[path]`. [N] types:

| Type | Shape |
|---|---|
| `[pill-color]` | `[classes]` |

[State which colours to use and which to leave alone.]

### Tables

`[path]`. [Container classes, header row, body row heights, cell padding, how dividers are drawn, sort affordance.]

### Tabs

`[path]`. [Styles available, selected state per style, and which to default to.]

### Modals

`[path]`. [Overlay treatment, anchoring at each breakpoint, enter and exit timing, whether the primitive is styled.]

### Empty states

`[path]`. [Composition: icon, heading, supporting copy, actions. Sizes.]

---

## Forms and inputs

> **Include only if applicable.**
>
> **How to derive this.** Paste the shared control class string that inputs and selects have in common, plus the focus, disabled, and invalid states. Then list every form control that exists so nobody writes a bare `<input>`.

**Resolved.** All form controls live in `[path]` and are built on [base library], so keyboard behaviour and ARIA come free. Use them.

### The shared control treatment

```
[exact class string]
```

Focus: `[classes]`. Disabled: `[classes]`. Invalid: `[classes]`.

### The controls

| Component | Path | Notes |
|---|---|---|
| `[Input]` | `[path]` | [notes] |
| ... | | |

### Form rules

1. [Every input has a visible label.]
2. [Where error text goes.]
3. [Field gap and group gap.]
4. [One primary submit per form.]
5. [Disabled rather than hidden.]

---

## Charts and data display

> **Include only if applicable.**
>
> **How to derive this.** Find the charting library and how it takes colour. Grep the chart components for raw values and state honestly whether the correct pattern is the majority or the minority. Then read the best chart in the codebase and write its conventions down as rules.

**Resolved.** Charts use [library]. There are [N] chart components in `[path]`.

### Colour rules

[State how tokens reach the chart library, with a code example.]

```jsx
[example]
```

[State whether this pattern is the majority. If not, name the exemplar file to copy and link to Known gaps.]

**Sanctioned exceptions:** [for example third-party brand colours, with a table and a neutral fallback rule].

### Chart conventions

1. [Gridlines.]
2. [Axis text size and colour.]
3. [Bar and line treatment.]
4. [Animation policy.]
5. [Axis domain policy.]
6. [Container and sizing policy.]

### Non-chart data display

- **`[Component]`**: [what it does and when to pick it over a chart].

---

## Motion

> **Include only if applicable.**
>
> **How to derive this.** Grep for duration and transition classes and list the distinct timings by where they appear. Then state the governing rules.

**Resolved.** [State how much motion the system uses and where it comes from.]

| Where | Timing |
|---|---|
| [Button, nav, tab state] | `[duration-100 ease-linear]` |
| ... | |

**Rules:** [for example: enter slower than exit; nothing over 300ms; data visualisations do not animate on load].

---

## Accessibility

> **How to derive this.** Note what the base component library provides for free, then list the rules the team must uphold on top of it. If no contrast audit exists, say so as an open task rather than implying one was done.

**Resolved.** [Base library] does the heavy lifting. On top of that:

1. **Never colour alone.** [Every status colour is paired with a text label or an `aria-label`.]
2. **Hide decorative graphics.** [`aria-hidden` and empty `alt` policy.]
3. **A control is a control.** [Render a button only when there is something to activate.]
4. **Real headings, real levels.** [Pick level by structure, size comes from the type utility.]
5. **Real semantics.** [Which element for which content.]
6. **Focus is always visible.** [Where the focus ring comes from and not to strip it.]
7. **[Npx] tap targets.** [Note any component that fails this.]

**TBD - open task. Owner: [role].** [Contrast audit status.]

---

## Theming and dark mode

> **Include only if applicable.**
>
> **How to derive this.** Find the theme provider and read what it actually does at runtime, not what the token file declares. A palette that exists but never activates is a trap, and the document must say so plainly.

**Resolved.** [State whether a second palette exists, where, and how it is registered.]

**[State whether it actually activates, with the runtime evidence.]**

**What this means for you:**

- [Whether a themed rendering can be tested.]
- [Whether dormant variant classes may be deleted.]
- [Why semantic aliases still matter regardless.]

**TBD - open task. Owner: [role].** [Decide whether the theme is supported, and repair or remove accordingly.]

---

## Do's and don'ts

> **How to derive this.** This section is a compression of everything above. Each line should trace back to a rule already stated. Aim for scannable single lines. This is the section a coding agent obeys.

### Do

- [Reach for semantic aliases for all chrome.]
- [Use utility ramps for status and charts.]
- [Use semantic type utilities on new work.]
- [Default a card to the standard class string.]
- [Check the component directories before building anything.]
- [Pick the shell first.]
- [Pair every colour-coded state with a text label.]

### Don't

- [Don't write a raw value. Name the exceptions.]
- [Don't reference primitive ramps from a component.]
- [Don't open the extended palette.]
- [Don't put more than one primary button in a screen region.]
- [Don't use the technique that reflows where focus must thicken.]
- [Name any component-specific trap.]
- [Don't assume the second theme renders, if it does not.]

---

## Building a new screen

> **How to derive this.** Write the recipe you would give a new engineer on their first day, in the order they would actually do it. End with a pre-ship checklist short enough to run in a minute.

A working recipe.

**1. Pick the shell.** [Options and how to choose.]

**2. Set the page header.**

```jsx
[example]
```

**3. Lay out the content.** [Spacing rhythm and grid behaviour at each breakpoint.]

**4. Use the standard card.**

```jsx
[example]
```

**5. Assemble from existing components.** [Which directories to search, and the copy-the-nearest-example rule.]

**6. Cover all four states.** Loading, empty, error, loaded. [Name the component for each.]

**7. Check it at [375px, 768px, 1440px].** [Name the breakpoint where layout switches.]

**8. Run through the checklist.**

These apply to anything shipped, a whole page or a single card:

- [ ] No raw values
- [ ] Semantic aliases for chrome, utility ramps for status
- [ ] One primary button per screen region
- [ ] Every input has a label
- [ ] Every status colour has a text label
- [ ] Numbers in columns are tabular
- [ ] Tap targets meet the minimum
- [ ] Focus rings intact

These apply to a full screen:

- [ ] The shell is one of the [N] page shells, not a bespoke frame
- [ ] Loading, empty, error, and loaded states all render
- [ ] Checked at [375px, 768px, 1440px]

> **Note for anyone filling this in.** Steps 1 to 3 above are screen-scoped.
> Steps 4 to 8 apply to any piece of UI. Someone building a single card should
> still run the first checklist.

---

## Known gaps

> **How to derive this. Do not skip this section.** It is what stops the document from being a lie. Each gap is a place the codebase disagrees with the rules above. Give each one a count or a file list so it is verifiable, mark it Resolved as a fact, and assign an owner. If a gap has no owner, it will not close.

### 1. [Gap title]

**Resolved as a fact.** [What is true, with counts and file names.]

| [Hardcoded value] | Count | [The correct equivalent] |
|---|---|---|
| `[value]` | [N] | `[alias]` |

**TBD - open task. Owner: [role].** [What closing it looks like.]

### 2. [Gap title]

[Repeat. Common gaps worth checking for: raw values in components, off-palette values in charts, components that fail tap-target minimums, low adoption of semantic utilities, unreachable themes, unused fonts loading on every page, dead token indirection, no contrast audit, inconsistent loading and empty states.]

---

## Source files

> **How to derive this.** A flat map back to ground truth. If a reader disbelieves a value in this document, this table tells them where to check.

| What | Where |
|---|---|
| **All design tokens** | `[path]` |
| Styling entry point and custom variants | `[path]` |
| **Semantic type utilities** | `[path]` |
| Font loading | `[path]` |
| [Shell] | `[path]` |
| Nav config | `[path]` |
| Base components | `[path]` |
| Application components | `[path]` |
| Theme provider | `[path]` |
| Routes | `[path]` |
| Class-merge helper | `[path]` |
| **Visual style sheet (design tool)** | [link] |

[State whether the design tool page is a live mirror or a hand-set snapshot, because that determines whether it can drift.]

**Upstream reference.** [If components come from a third-party library, link it and say to check upstream before changing behaviour.]

---

<!--
THIS BLOCK BELONGS IN THE REPO'S CLAUDE.md, NOT IN THIS DOCUMENT.

A person doing this: copy the block below, paste it into the repo's CLAUDE.md,
fill in the three rules, correct the path if the document was not saved at
`docs/design.md`, then delete this whole comment from the document.

An agent doing this: adding the block to CLAUDE.md is part of the task. Create
CLAUDE.md at the repo root if it does not exist. If it does exist, append the
block as a new "## Design system" section and leave the rest of the file alone.
Correct the path if the document was not saved at `docs/design.md`. Then delete
this comment from the document.

## Design system

**Read `docs/design.md` before changing any UI**, adding a screen, or choosing
a colour, size, radius or spacing value. It is the source of truth for tokens,
components, the page shells, and the known gaps.

Three rules that hold even if that read gets skipped:

- **[Rule 1: the token layer rule, in one line with a concrete example.]**
- **[Rule 2: the card treatment, in one line with the exact class string.]**
- **[Rule 3: the radius convention, in one line.]**

Pick the three rules that are broken most often in the repo, not the three that
are most interesting.
-->
