design-system

A design system is not a folder of components. It is a set of decisions written down once so they stop being remade badly every time someone opens a file.

The test of a system is not whether it exists. It is whether a new screen built by someone who has never seen the product comes out looking like it belongs.

Engine

DS=$(ls "${CLAUDE_PLUGIN_ROOT:-/nonexistent}/engine/dstack.py" "$HOME/.claude/dstack/engine/dstack.py" 2>/dev/null | head -1)
python3 "$DS" "<query>" -c design-systems
python3 "$DS" "<query>" -c handoff
python3 "$DS" "<query>" --styles              # 40 style recipes, including full dark mode formulas
python3 "$DS" --audit -c design-systems

Read engine/reference/system-template.md for the output shape and engine/reference/examples/ for two worked examples.

Pick the mode

• Codebase exists, no system. Mode A, extract.
• Codebase has a system that drifted. Mode A, then Mode C.
• Nothing exists yet. Mode B, define.
• System exists and works, needs theming or dark mode. Mode D.

Mode A: Extract

A1. Inventory what is actually there

Count before you decide. The gap between what people think the system is and what the code contains is always larger than expected.

# every hardcoded color
grep -rhoE "#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)|hsla?\([^)]*\)" src/ | sort | uniq -c | sort -rn | head -40

# every font size
grep -rhoE "font-size:\s*[0-9.]+(px|rem|em)|text-\[[^]]+\]|text-(xs|sm|base|lg|xl|[0-9]xl)" src/ | sort | uniq -c | sort -rn | head -30

# every spacing value
grep -rhoE "(padding|margin|gap):\s*[0-9.]+(px|rem)|[pmg][xytblr]?-\[[^]]+\]" src/ | sort | uniq -c | sort -rn | head -40

# radius and shadow
grep -rhoE "border-radius:\s*[^;]+|box-shadow:\s*[^;]+" src/ | sort | uniq -c | sort -rn | head -30

Adjust the globs to the project. Report the raw counts. "Forty one distinct grays across the app" is the finding that makes the case for the work.

A2. Cluster and decide

For each dimension, collapse the inventory into a scale. The rule is the same every time: keep the values that carry meaning, delete the ones that were accidents.

• Two colors 2 percent apart are one color. Pick the one used most and migrate the other.
• A font size used twice in a 200 file codebase is not a scale step, it is a mistake.
• Spacing values that are not on a scale get snapped to the nearest step, not preserved.

State each collapse: #3b82f6, #3c83f7, #3b83f6 → --accent, 412 usages.

A3. Name for the product, not the palette

--gray-700 and --surface-2 describe the value. --ink and --parchment describe the world. Someone reading only your token names should be able to guess what the product is for.

Two layers, always:

• Primitives hold the raw values. --ink-900: #14110E
• Semantics hold the intent, and are the only layer components touch. --text-primary: var(--ink-900)

Components referencing primitives directly is what makes theming impossible later.

Mode B: Define

Do not invent a scale in the abstract. Design one screen first, take the values it needed, and generalize from those. A system built before any real screen is a guess.

The scales

Type. Four to six steps, not nine. A 1.25 ratio for dense product UI, 1.333 for marketing. Lock line height and tracking per step rather than globally: body at 1.5 to 1.6, headlines at 1.05 to 1.2, tracking minus 0.02em above 32px, plus 0.01em below 13px.

Spacing. One base unit, usually 4px, with a scale that skips: 4, 8, 12, 16, 24, 32, 48, 64, 96. Skipping is deliberate. If 20 and 24 both exist people pick at random and the rhythm dies.

Color. Start from three: one accent that means action, one neutral ramp, one surface. Add semantics only when a real need appears. Tint every neutral with 3 to 8 percent of the accent hue, because pure gray next to a colored accent reads as dead.

Radius. One base and a derivation rule: inner radius equals outer radius minus padding. Nesting a 8px radius inside a 8px radius with 12px padding is the tell that no rule exists.

Shadow. Two or three levels, each built from two layers: a tight 1px contact shadow plus a wide soft one, both under 12 percent opacity. If everything has a shadow, depth communicates nothing.

Motion. Four durations and three curves. Query the motion base for the values, or take them from design-motion.

Output shape

:root {
  /* primitives */
  --ink-900: #14110E;
  --ink-500: #6B6459;

  /* semantics, the only layer components use */
  --text-primary: var(--ink-900);
  --text-secondary: var(--ink-500);

  /* scales */
  --space-1: 4px;  --space-2: 8px;  --space-3: 12px;

  /* motion */
  --dur-fast: 150ms;
  --ease-out: cubic-bezier(0.16, 1, 0.3, 1);
}

Match the project's actual mechanism. Tailwind config, CSS variables, a TS token file, or Figma variables. Do not introduce a second system alongside the one that already exists.

Mode C: Migrate

A token file nobody uses is worse than no token file, because it looks solved.

1. Write the tokens.
2. Migrate mechanically, highest count first. The 412 usages of the accent are the whole win; the value used twice can wait.
3. Report coverage honestly: 312 of 340 hardcoded colors migrated, 28 remaining in three legacy files, listed below.
4. Add a guard so it does not drift back. A stylelint rule, an ESLint rule, or a CI grep that fails on raw hex outside the token file.

Never claim a migration is complete without the count. "Migrated to tokens" with no number means nobody checked.

Mode D: Theming and dark mode

Query --styles and read the Dark Mode recipe before starting. The important parts:

• Dark mode is not inverted light mode. Inverting produces muddy midtones and shadows that do nothing.
• Build an elevation ladder from the accent hue, not from pure gray. Take the accent, set saturation to about 25, and step brightness at 10, 20, 30, 40.
• On OLED, base can be #000000. On LCD use a very dark tinted gray around #0E0F11, because pure black with pure white text strains eyes on a glowing panel.
• Shadows stop working in the dark. Elevation comes from lighter surfaces and thin borders, not from darker shadows.
• Desaturate the accent slightly in dark mode. A color tuned against white vibrates against near black.
• Recheck every contrast pair. Passing in light mode says nothing about dark.

Theme by swapping the semantic layer only. If a component has to know which theme is active, the semantic layer is incomplete.

Always finish with the doc

Write DESIGN-SYSTEM.md at the project root using engine/reference/system-template.md. It records the decisions and, more importantly, the reasons. A token file says what. The doc says why, which is the part that stops the next person from adding a fifth gray.

Include:

• The intent in three lines: who, what job, what feeling
• Each scale, with the rule that generates it
• What is deliberately not in the system, and why
• How to add something new without breaking it

Rules

• Count, do not estimate. Every claim about the codebase comes from a command you ran.
• Fewer tokens than you want. A system with 8 spacing steps that everyone follows beats one with 20 that people ignore.
• Do not rename for taste. Renaming a working token across 400 files buys nothing and risks everything. Rename during a migration you were already doing.
• No dashes as punctuation in the doc or any copy you write.