Scrollcraft
Chapter 10 of 15RO

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.

Chapter 10 of 154 min read

What you will learn

By the end of this chapter
  1. 01Turn colour, type, space and motion into a short list of named tokens.
  2. 02Build components that read tokens and never hold raw values.
  3. 03Make a theme or a reduced-motion version by changing tokens, not rules.
  4. 04Write a DESIGN.md that keeps the AI consistent from the first section to the last.

01 · Tokens

Four kinds
a

Colour

Name colours by their job, not their hue: --accent and --muted, not --blue. A minimalist page needs five or six, with one accent.

b

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.

c

Space

One unit and its multiples. When every gap is 8, 16, 24, 48 or 96, sections line up without anyone measuring.

d

Motion

Durations, easing curves and distances are design decisions too. Three durations and two curves cover almost every movement on a scroll site.

style.css
: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 scroll
1

A 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.

HTML
<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 values
a

One 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.

style.css
.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); }
b

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.

c

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.md
a

Write 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
# 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.
b

Point the AI at it

Prompt
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.
c

Audit drift

Prompt
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 decisions
1

One accent

It marks what can be clicked, what has focus and how far you have read. Used anywhere else, it stops meaning anything.

2

Two families at most

One for text, optionally one monospace for labels. Weight and size carry the hierarchy.

3

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.

4

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 tool

The 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

Prompt
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

Prompt
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.

Practice · Exercises

Try first, then compare
1

Name 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.

2

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.

CSS
@media (prefers-reduced-motion: reduce) {
  :root { --dur-fast: 0s; --dur-base: 0s; --dur-slow: 0s; }
}
3

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 course

Give the site for [subject] a design system it can grow with.

  1. Run “Extract tokens” and agree the set with the AI.
  2. Move every value into :root and replace the raw values, one group at a time, checking the page after each.
  3. Run “Write DESIGN.md” and commit both files.
  4. Change --accent once 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 criteria

0 of 4 criteria met

Next Architecture

Choosing a stack, a folder structure that scales, one animation loop for the whole site, and effects that clean up after themselves.

Keyboard shortcuts: [ previous chapter · ] next chapter