design-system

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

SKILL.md

GitHub

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