Claude Code
A design system Claude Code actually follows
The exact files Glyph writes, shown here for an example brand called Ledgerly. Yours use your own colors, fonts and logo.
# Ledgerly
## Design system
@DESIGN.md
Before you build or change any UI, follow DESIGN.md. The rules that matter most:
- Use only the variables in brand/tokens.css. Never write a raw hex value, and never use Tailwind's default palette (blue-500, indigo-600, slate-*) for brand UI.
- Buttons and links use the --ds-action-* and --ds-text-link tokens; the primary (#0F766E) appears on one action per view.
- Type is "Manrope" for headings (weight 500) and "Inter" for body text (weight 400). No other typeface, and no Inter fallback in its place.
- Dark mode comes from the .dark token values. Do not add dark: color variants by hand.
- Status is a word plus --ds-status-* color, never a colored dot alone.
- Reuse existing components before writing new ones; never invent a token, button style or radius that is not in DESIGN.md.
- No gradients, glass, pills for static tags, eyebrow labels or "Learn more →" links.
## Before you hand off
Check each screen you changed at phone and desktop width against DESIGN.md, and say which screens you checked.
Why it drifts
Why Claude Code drifts off your brand
It writes raw hex values
Asked to "make the button blue", Claude Code picks a hex it likes and writes it inline. Two sessions later there are four blues. A rule that bans raw values, plus named tokens to use instead, ends that.
It forgets between sessions
Instructions given in chat are gone in the next session. CLAUDE.md is read at the start of every session, so the brand rules are there before the first edit.
A long CLAUDE.md gets skimmed
A CLAUDE.md that tries to hold everything competes with the rest of your project notes. Glyph keeps CLAUDE.md short and imports the full system with @DESIGN.md, so the core rules stay at the top.
It invents components
Without a rule, Claude Code builds a new button for each page. The design system tells it to reuse existing components and to stop and ask when a token is missing.
Setup
Set it up in Claude Code
- 01
Describe the product you are building in Glyph, or paste its URL, and pick the logo, colors and type you want Claude Code to use.
- 02
Put CLAUDE.md and DESIGN.md in the project root and brand/tokens.css next to your global styles. On a paid plan, one command does all three: npx shadcn@latest add with your brand's install link.
- 03
Import brand/tokens.css once in your root layout.
- 04
Start a new session. Claude Code reads CLAUDE.md, follows the @DESIGN.md import, and builds with your tokens.
Questions
Common questions.
- Should I use AGENTS.md or CLAUDE.md?
- Claude Code reads CLAUDE.md. Other agents, such as Codex, read AGENTS.md. Glyph writes both from the same DESIGN.md, so you can keep both in the repo and they never disagree.
- How long should a brand CLAUDE.md be?
- Short. Glyph's CLAUDE.md is around twenty lines: the import of DESIGN.md and the handful of rules that matter most. The detail lives in DESIGN.md, which Claude Code loads through the import.
- How do I stop Claude Code from using default Tailwind colors?
- Give it named tokens and a rule that bans the default palette for brand UI. The generated files map your colors to Tailwind utilities like bg-brand-primary, so the right class is also the easy one.
- Does Claude Code support dark mode from these files?
- Yes. tokens.css defines every token under :root and .dark, and the rules tell Claude Code to rely on those values instead of writing dark: variants by hand.