Design systems: one source of truth.
A cinematic site feels deliberate because every size, colour and movement comes from a short list of decisions. Write that list down once, as tokens, and you and the AI both build from it.
What you will learn
By the end of this chapter- 01Turn colour, type, space and motion into a short list of named tokens.
- 02Build components that read tokens and never hold raw values.
- 03Make a theme or a reduced-motion version by changing tokens, not rules.
- 04Write a
DESIGN.mdthat keeps the AI consistent from the first section to the last.
01 · Tokens
Four kindsColour
Name colours by their job, not their hue: --accent and --muted, not --blue. A minimalist page needs five or six, with one accent.
Type
A scale of four or five steps. Each step is a clamp(), so headings grow with the screen without a breakpoint for every size.
Space
One unit and its multiples. When every gap is 8, 16, 24, 48 or 96, sections line up without anyone measuring.
Motion
Durations, easing curves and distances are design decisions too. Three durations and two curves cover almost every movement on a scroll site.
:root {
/* colour: named by role, not by hue */
--bg: #000; --surface: #070a0d; --line: #20262b;
--fg: #eaf0f4; --muted: #8d989f; --accent: #5cc8ff;
/* type: a short scale that grows with the screen */
--t-sm: 13px;
--t-md: clamp(15px, 1.2vw + 12px, 18px);
--t-lg: clamp(22px, 2.4vw + 14px, 32px);
--t-xl: clamp(40px, 8vw, 112px);
/* space: one unit and its multiples */
--s1: 8px; --s2: 16px; --s3: 24px; --s4: 48px; --s5: 96px;
/* motion: three durations, two curves, one distance */
--dur-fast: .2s; --dur-base: .6s; --dur-slow: 1.2s;
--ease-out: cubic-bezier(.2, .7, .2, 1);
--ease-in-out: cubic-bezier(.65, 0, .35, 1);
--rise: 24px;
}02 · Tokens, live
Press the button, then scrollA page built only from tokens
Every value on the page below reads a variable. The button changes one token, --accent, and the labels, borders and focus ring all follow.
Reduced motion is handled the same way: the media query sets the durations to zero instead of overriding every transition.
<header class="top">
<span class="brand">Field</span>
<button class="swap" type="button" aria-pressed="false">Change the accent</button>
</header>
<h1 class="t-xl">One set of tokens.</h1>
<p class="t-md muted">Every size, gap, colour and timing on this page comes from the variables at the top of the CSS.</p>
<div class="grid">
<article class="card reveal"><span class="t-xs">01</span><h2 class="t-lg">Type scale</h2><p class="muted">Four steps, each one a clamp.</p></article>
<article class="card reveal"><span class="t-xs">02</span><h2 class="t-lg">Spacing</h2><p class="muted">Multiples of one unit.</p></article>
<article class="card reveal"><span class="t-xs">03</span><h2 class="t-lg">Motion</h2><p class="muted">Two durations and one curve.</p></article>
</div>03 · Components read tokens
Never raw valuesOne rule
A component never writes a raw colour, size, gap or duration. If it needs a value that is not there, add a token first, then use it.
.btn {
padding: var(--s1) var(--s3);
font-size: var(--t-sm);
color: var(--fg);
border: 1px solid var(--line);
border-radius: 99px;
transition: border-color var(--dur-fast) var(--ease-out);
}
.btn:hover, .btn:focus-visible { border-color: var(--accent); }
/* a variant changes tokens, not rules */
.btn[data-tone="solid"] { background: var(--accent); color: var(--bg); border-color: var(--accent); }Variants through attributes
A variant such as data-tone="solid" swaps a few tokens. The markup stays readable, and the AI cannot invent a seventh shade of grey.
With Tailwind
In Tailwind 4 the same tokens go in an @theme block, and become classes like bg-accent. The rule does not change: utilities only, no arbitrary values.
04 · A design file for the AI
DESIGN.mdWrite the decisions down
Put a short DESIGN.md next to your rules file. The AI reads it before every change, so the fifth section looks like the first.
# DESIGN.md
## Mood
Quiet, dark, editorial. One idea per screen. Motion is slow and rare.
## Tokens
All values live in :root in style.css. Never write a raw colour, size,
gap or duration anywhere else. If a value is missing, add a token first.
## Type
Two families at most. Headings light (300), tight tracking (-0.04em).
Body 15–18px, line height 1.5, lines no wider than 65 characters.
## Colour
Black background, one accent (--accent) for links, focus and progress.
Body text at least 4.5:1 contrast.
## Motion
Reveals: --rise upwards over --dur-base with --ease-out, once.
Scrubbed scenes: no easing (the scroll is the easing).
Nothing moves under prefers-reduced-motion: set the durations to 0.
## Do not
Gradients on text, glassmorphism cards, bouncing, more than one accent,
invented numbers or logos.Point the AI at it
Read DESIGN.md and the :root tokens in style.css before you change anything. Use only those tokens. If you need a new value, propose the token first and wait for my answer.Audit drift
List every raw colour, font size, gap and duration in the CSS that does not come from a token. For each one, say which token it should use or propose a new one.05 · Stay minimal
Fewer, stronger decisionsOne accent
It marks what can be clicked, what has focus and how far you have read. Used anywhere else, it stops meaning anything.
Two families at most
One for text, optionally one monospace for labels. Weight and size carry the hierarchy.
One curve for most movement
A single ease-out for reveals and transitions makes the whole site move with one hand. Scrubbed scenes use none: the scroll is the easing.
Space before decoration
When a section feels empty, add space around it, not a gradient, a shadow or another card.
Practice · Work with AI
The same task in your toolThe AI is good at extracting tokens from existing CSS and bad at keeping to them unless told. Do both in that order.
Open a terminal in the project folder and run claude. Press Shift+Tab until plan mode is on, paste the prompt, read the plan, then approve it. Project rules go in CLAUDE.md.
Extract tokens
Read CLAUDE.md and style.css. Propose a token set for the site for [subject]: colours named by role, a type scale of four or five clamp() steps, a spacing scale from one unit, and motion tokens (durations, easing, distance). Show me the :root block and a table of which raw values each token replaces. Do not edit the CSS yet.Write DESIGN.md
Write DESIGN.md for the site for [subject] from the tokens we agreed: mood in one line, the token rules, type, colour, motion and a short list of things not to do. Under 60 lines. Then add one line to CLAUDE.md telling you to read DESIGN.md before any visual change.Open a terminal in the project folder and run gemini; the first time, it asks whether you trust the folder, so say yes for your project. Paste the prompt. Gemini CLI asks before it edits a file or runs a command: read each request before you accept it. Project rules go in GEMINI.md.
Extract tokens
Read GEMINI.md and style.css. Propose a token set for the site for [subject]: colours named by role, a type scale of four or five clamp() steps, a spacing scale from one unit, and motion tokens (durations, easing, distance). Show me the :root block and a table of which raw values each token replaces. Do not edit the CSS yet.Write DESIGN.md
Write DESIGN.md for the site for [subject] from the tokens we agreed: mood in one line, the token rules, type, colour, motion and a short list of things not to do. Under 60 lines. Then add one line to GEMINI.md telling you to read DESIGN.md before any visual change.Open a terminal in the project folder and run codex, then paste the prompt and approve each change. In the ChatGPT app without Codex, attach the files, paste the prompt and copy the changes back yourself. Project rules go in AGENTS.md.
Extract tokens
Read AGENTS.md and style.css. Propose a token set for the site for [subject]: colours named by role, a type scale of four or five clamp() steps, a spacing scale from one unit, and motion tokens (durations, easing, distance). Show me the :root block and a table of which raw values each token replaces. Do not edit the CSS yet.Write DESIGN.md
Write DESIGN.md for the site for [subject] from the tokens we agreed: mood in one line, the token rules, type, colour, motion and a short list of things not to do. Under 60 lines. Then add one line to AGENTS.md telling you to read DESIGN.md before any visual change.Practice · Exercises
Try first, then compareName by role
Rename these tokens by role: --blue, --grey-400, --white, --dark.
Hint: ask what each colour does on the page.
Show the solution
For example --accent, --muted, --fg and --bg (or --surface). Names by role survive a change of palette; names by hue become lies the day the accent turns orange.
Reduced motion by token
Make every transition on the page stop under reduced motion with one rule.
Hint: every transition already reads a duration token.
Show the solution
Set the duration tokens to zero inside the media query. Every rule that uses them follows.
@media (prefers-reduced-motion: reduce) {
:root { --dur-fast: 0s; --dur-base: 0s; --dur-slow: 0s; }
}Spot the drift
Find three raw values in your CSS that should be tokens.
Hint: search for #, px and s outside :root.
Show the solution
Typical finds: a hex colour in a hover state, a one-off margin: 37px, a transition: .3s that should be --dur-fast. Replace each with the nearest token, or add a token if none fits.
Practice · Course project
One site, built across the courseGive the site for [subject] a design system it can grow with.
- Run “Extract tokens” and agree the set with the AI.
- Move every value into
:rootand replace the raw values, one group at a time, checking the page after each. - Run “Write DESIGN.md” and commit both files.
- Change
--accentonce to check that the whole site follows.
Practice · Test it
Check the result- Outside
:root, the CSS has no hex colours and no raw durations. - Changing one token visibly changes every place that uses it.
- With reduced motion on, nothing transitions.
- Asked “Which file sets the design rules?”, the AI names DESIGN.md.
Practice · Assessment
Acceptance criteria0 of 4 criteria met