Inkwell.

Chapter 10

Use it

A design system is only useful if the next person, or the next AI agent, actually follows it. This chapter hands you the file and the tokens, and shows how to make sure they are read.

Built with

  • DESIGN.md
  • Design tokens
  • CSS variables

One file

The design system, in DESIGN.md.

DESIGN.md sits at the root of the repo. It starts with the tokens in a machine-readable block, then states the rules in plain imperative sentences: what to use, what never to do, and where each thing lives. A person can read it in a few minutes, and an AI agent can follow it without guessing.

The block below is copied from the real file when this page is built, so it is never out of date.

DESIGN.md (front matter)
---name: Inkwellpalette: Violaversion: 0.2tagline: Quiet by default. Violet when it matters.source_of_truth: src/app/globals.csscolors:  light:    background: "#f1edf8"    background-elevated: "#f7ead9"    background-surface: "#f1dec6"    foreground: "#211c2e"    foreground-muted: "#56506c"    foreground-subtle: "#726788"    primary: "#7c6fb0"    primary-light: "#9b8fd0"    primary-dark: "#5f5389"    secondary: "#f1dec6"    accent-warm: "#c98a3d"    accent-coral: "#d9854f"    success: "#4d7c5f"    error: "#b3402c"    offline: "#c0525a"    border: "rgba(90, 70, 140, 0.14)"  dark:    background: "#14121a"    background-elevated: "#1b1823"    background-surface: "#221e2c"    foreground: "#faebd7"    foreground-muted: "#b4aec4"    foreground-subtle: "#837c98"    primary: "#a89cd8"    primary-light: "#c3b9e8"    primary-dark: "#8b7fb8"    secondary: "#fae3c6"    accent-warm: "#f5c98a"    accent-coral: "#eda673"    success: "#6fae82"    error: "#d17563"    offline: "#c0525a"    border: "rgba(250, 227, 198, 0.12)"typography:  display: { family: Fraunces, token: --font-display, use: "Headings, titles, display moments" }  sans: { family: Synonym, token: --font-sans, use: "Body copy, nav, buttons. The body default" }  lead: { family: Amulya, token: --font-lead, use: "Lead paragraph under a heading" }  hero: { family: Bespoke Stencil, token: --font-hero, use: "The hero name lockup ONLY" }  mono: { family: JetBrains Mono, token: --font-mono, use: "Eyebrows, dates, tech tags, UI chrome" }font_size:  heroTitle: "clamp(2.75rem, 8.5vw, 6.5rem)"  heroTitleCompact: "clamp(2.25rem, 5.4vw, 4.25rem)"  sectionTitle: "clamp(2.75rem, 6.5vw, 4.5rem)"  subTitle: "clamp(1.5rem, 3vw, 2.25rem)"  entryTitle: "clamp(1.2rem, 2.5vw, 1.5rem)"  contactTitle: "clamp(2rem, 4vw, 3rem)"  lead: "clamp(1.125rem, 2.4vw, 1.375rem)"  heroLead: "clamp(1.125rem, 2.4vw, 1.5rem)"  body: 1remrounded:  xs: 0.375rem  sm: 0.5rem  base: 0.75rem  lg: 1rem  xl: 1.5rem  2xl: 2remmotion:  settle: "cubic-bezier(0.23, 1, 0.32, 1)"  rise: "cubic-bezier(0.22, 1, 0.36, 1)"  slide: "cubic-bezier(0.87, 0, 0.13, 1)"  ease-out: "ease-out"  linear: "linear"---
Download DESIGN.mdDownload tokens (JSON)

Make it read

Wire it to an agent.

A file nobody opens changes nothing. Tell your agent to read it. Most coding agents load a project instruction file such as AGENTS.md or CLAUDE.md at the start of every task, so a short pointer there is enough. This site does exactly that.

AGENTS.md or CLAUDE.md
## Design system Before you change UI, styles, colours, fonts, spacing or motion, read DESIGN.md.Use tokens. Never write a raw hex or a one-off size.

Copy and go

Tokens to copy.

These are the semantic colours, light and dark, as CSS custom properties. They are read from globals.css when the page is built. The same values are in the JSON download.

CSS custom properties
:root {  --background: #f1edf8;  --background-elevated: #f7ead9;  --background-surface: #f1dec6;  --foreground: #211c2e;  --foreground-muted: #56506c;  --foreground-subtle: #726788;  --primary: #7c6fb0;  --primary-light: #9b8fd0;  --primary-dark: #5f5389;  --secondary: #f1dec6;  --accent-warm: #c98a3d;  --accent-coral: #d9854f;  --success: #4d7c5f;  --error: #b3402c;  --offline: #c0525a;} [data-theme="dark"] {  --background: #14121a;  --background-elevated: #1b1823;  --background-surface: #221e2c;  --foreground: #faebd7;  --foreground-muted: #b4aec4;  --foreground-subtle: #837c98;  --primary: #a89cd8;  --primary-light: #c3b9e8;  --primary-dark: #8b7fb8;  --secondary: #fae3c6;  --accent-warm: #f5c98a;  --accent-coral: #eda673;  --success: #6fae82;  --error: #d17563;  --offline: #c0525a;}

Honesty

Keeping it true.

A rules file that drifts from the code is worse than none. So the repo has a small check, node scripts/check-design-md.mjs, that compares every colour in the front matter with globals.css and fails if one has changed. Run it after you edit a token. When the two disagree, the CSS is the truth and the file is the bug.