Foundations

DESIGN.md for LLMs

A portable, agent-readable design reference for Claude, Gemini/Google, Codex, and other coding agents. The root DESIGN.md file gives agents exact CAAT tokens plus plain-language rules for building consistent UI.

DESIGN.md alpha Claude-ready Google/Gemini-ready Codex-ready

Download DESIGN.md View inline file

Overview

The design-system repository now includes a root-level DESIGN.md file. It is the shared LLM reference for the CAAT visual identity, design tokens, component behavior, and page-building rules.

The structure follows the Google Labs DESIGN.md format: machine-readable YAML front matter first, then Markdown guidance written in the order agents expect.

Exact Tokens

Agents get explicit colors, typography, spacing, radius, and component token references instead of guessing from screenshots.

Design Rationale

The Markdown body explains why values exist and how to apply them across pages, components, and states.

Portable Context

The same file can be referenced by Claude, Gemini, Codex, GitHub Copilot, and other code-generation workflows.

Format

DESIGN.md has two layers. The token layer is normative; the prose layer gives agents judgment for applying those values in context.

Layer	Purpose	CAAT content
YAML front matter	Machine-readable values	Color tokens, Libre Franklin type scale, spacing/radius scale, and common component tokens.
Markdown body	Human-readable guidance	Overview, colors, typography, layout, depth, shapes, components, and do/don't guardrails.

---
version: alpha
name: CAAT Design System
colors:
  primary: "#003750"
typography:
  body-md:
    fontFamily: Libre Franklin
    fontSize: 1rem
---

## Overview
CAAT digital experiences should feel trustworthy, clear, and quietly confident.

Agent Usage

Give the root DESIGN.md file to the agent before it creates or edits UI. The instruction should make the file authoritative over generated defaults.

Agent	Use	Prompt pattern
Claude	Reference the root file when asking for component or page work.	`Read DESIGN.md first and follow CAAT tokens, layout, and component rules.`
Gemini / Google tooling	Use the Google DESIGN.md-compatible structure directly.	`Use DESIGN.md as the visual identity source before generating UI.`
Codex / other agents	Load the file as design context before editing HTML, CSS, React, or AEM code.	`Implement with existing CAAT components and do not invent new tokens.`

Before generating any CAAT interface:
1. Read DESIGN.md.
2. Use tokens from public/assets/css/tokens.css.
3. Prefer existing CAAT component classes.
4. Keep section rhythm, accessibility, and responsive rules intact.

Token Summary

The file condenses the live token system into the values most useful for agent generation. The CSS source remains canonical for implementation details.

Core colors

Deep CAAT Blue #003750

Accessible Green #367f32

Lime Accent #95e35c

Subtle Surface #eff2f7

Ink Text #102637

Category	Agent rule	Source
Color	Use deep blue for primary hierarchy, accessible green for secondary action, lime sparingly.	`colors` in `DESIGN.md`
Typography	Use Libre Franklin only, with strong headings and readable body line height.	`typography` in `DESIGN.md`
Layout	Compose pages from full-width white/grey/brand sections with constrained containers.	`public/foundations/page-layout.html`
Components	Prefer existing CAAT classes and variants before creating new CSS.	`public/assets/css/components/`

Generation Guidance

Use semantic tokens first. Component CSS should consume intent-based tokens such as text, action, surface, border, and feedback values.
Build with existing components. Buttons, cards, heroes, forms, navigation, badges, and layout sections already have documented classes.
Keep page rhythm simple. Alternate white and grey sections. Use brand blue as a sparse emphasis band, not a default background.
Protect accessibility. Maintain AA contrast, visible focus rings, semantic headings, ARIA states, and reduced-motion behavior.
Avoid generated novelty. Do not introduce unapproved fonts, shadows, one-off colors, nested cards, decorative separators, or non-token radii.

Source File

The complete DESIGN.md file is shown below and is available as a direct download.

Download DESIGN.md

Loading DESIGN.md...

Maintenance

Update DESIGN.md whenever a visual decision changes in the design system. Treat it like an API contract for agents.

Change	Required update
Token value changes	Update the YAML token value and the related prose rule.
New component variant	Add or revise the component token entry and the Components guidance section.
Layout foundation changes	Revise the Layout section and any agent prompt examples.
Accessibility rule changes	Update the Do's and Don'ts guardrails immediately.
Download file changes	Keep `/DESIGN.md` in sync with the repository root `DESIGN.md`.

Source alignment: The implementation source remains public/assets/css/tokens.css; DESIGN.md is the portable summary for agents and should not drift from the token file.