AGENTS.md
An AGENTS.md design system that agents can follow
The exact files Glyph writes, shown here for an example brand called Ledgerly. Yours use your own colors, fonts and logo.
# AGENTS.md
## Design system
This project's brand lives in DESIGN.md and brand/tokens.css. Read DESIGN.md before any UI work.
- 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.
The logo is public/logo.svg. Use it as an image with "Ledgerly" as its alt text; never replace it with an icon.
Why it drifts
What goes wrong with design rules in AGENTS.md
A palette is not a system
Listing five hex codes tells an agent what colors exist, not which one a button uses. Semantic tokens (action, text, surface, status) answer that, in light and dark.
Adjectives are not rules
"Clean and modern" changes nothing. Rules an agent can check, like one primary action per view or no raw hex values, change what it writes.
One giant file
Putting the whole system in AGENTS.md buries your build and test notes. Keep a short design section in AGENTS.md and the detail in DESIGN.md.
Two files that disagree
Teams keep a CLAUDE.md and an AGENTS.md that drift apart. Generate both from one DESIGN.md, or have CLAUDE.md import it.
Setup
Use it in your repo
- 01
Generate a brand in Glyph so the AGENTS.md design section is filled with your real tokens instead of placeholders.
- 02
Add the design section to AGENTS.md and save DESIGN.md beside it.
- 03
Load brand/tokens.css once at the app root, so every agent that reads AGENTS.md finds the variables it names.
- 04
If you also use Claude Code, add the CLAUDE.md that imports DESIGN.md, so both agents read the same system.
Questions
Common questions.
- Should I use AGENTS.md or CLAUDE.md?
- Use AGENTS.md for agents that read it, such as Codex, and CLAUDE.md for Claude Code. Point both at one DESIGN.md so there is a single source of truth.
- What are semantic tokens?
- Names for what a color is for, such as --ds-action-primary-bg or --ds-status-danger-fg, instead of what it looks like. Components use the purpose, and the value can change per mode or brand.
- How long should the design section be?
- A handful of rules in AGENTS.md, with the token table, type scale and full rule list in DESIGN.md.
- Can I write this by hand?
- Yes, the example above is a good template. Glyph generates it from your actual colors, fonts and logo, with contrast checked for every text pair.