Skip to content

burhantoprakman/demo-site-template / .claude/skills/design-system

design-system

Verified

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:

NeedVariable
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
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall