---

name: design-system description: Use when building, editing, or reviewing any page or component on this site - anything that produces markup or CSS. Covers the token system, the component library, when to build something new, and the layout rules. Trigger on requests to add a page, add a section, change styling, adjust spacing or colour, or make something "look better".

Design system

The one rule

Use what exists. This site has a small component library on purpose. A page that introduces its own spacing, its own colours, or its own card style breaks the consistency the template exists to provide.

Tokens

src/design/tokens.json is the source of truth. src/styles/tokens.css is generated from it by npm run tokens — never edit the CSS directly.

Every value in a component comes from a variable:

| Need | Variable | |---|---| | Text colour | --color-ink, --color-ink-muted | | Backgrounds | --color-paper, --color-paper-sunk, --color-accent-soft | | Borders | --color-rule | | Links, primary action | --color-accent | | Warnings only | --color-signal | | Font size | --size-xs … --size-3xl | | Spacing | --space-1 … --space-24 | | Corner radius | --radius-sm, --radius-md | | Column widths | --layout-measure, --layout-content, --layout-wide |

If a value you need is not in the scale, use the nearest one. Do not invent padding: 13px.

Components

Read src/pages/kitchen-sink.astro for the current inventory. At time of writing:

• BaseLayout — every page starts here. Takes title and description.
• Hero — one per page, at the top. headline plus optional standfirst.
• Section — the main building block. title, width (content | wide), sunk to tint the background.
• Callout — note or warning. For things a reader would otherwise miss.
• CodeBlock — lang or file label.
• ComparisonTable — columns, rows, and a required caption.
• Figure — wraps a diagram or screenshot, requires a caption.
• Steps — numbered sequence. Only when the content really is a sequence.
• CallToAction — primary or secondary.

Building something new

Only when nothing above fits. Then:

1. Put it in src/components/ as a .astro file with a typed Props interface and a doc comment per prop.
2. Style it in the component's own <style> block, scoped, using tokens only.
3. Add a case to kitchen-sink.astro.
4. Tell the person you added a component and why nothing existing worked.

Layout

• Running text stays within --layout-measure (68ch). Do not widen it.
• Sections handle their own vertical rhythm. Do not add margins between them.
• Test at 375px wide. Tables scroll horizontally; nothing else should.

What not to do

• No new colours outside the token file
• No page-level <style> blocks
• No decorative gradients, drop shadows, or hover animations on every card
• No all-caps eyebrow labels above headings
• No numbered markers unless the content is a sequence