Imported from burhantoprakman/demo-site-template (.claude/skills/design-system/SKILL.md). Install upstream with npx skills add burhantoprakman/demo-site-template --skill design-system. Copyright stays with the author.

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:

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