Design System

Agent spec (DESIGN.md)

Machine-readable design contract for AI coding agents building the GRIDWATCH apps. YAML token front matter + prose rationale, one root spec and three per-app deltas.

Why this exists

The rest of this system is written for humans — tokens, components, and rationale that designers and engineers read. DESIGN.md is the same information, reshaped for the AI coding agents that help build the GRIDWATCH apps. It gives agents a persistent, structured understanding of the visual system so they can produce UI that stays on palette, on type, and on shape without needing to re-read the whole design-system site.

The format is a community spec: YAML front matter for machine-readable tokens, markdown body for the reasoning behind the values.

Where it lives

GRIDWATCH ships one root spec and three per-app deltas. The root is the shared contract. Each app file extends it and documents only what is specific to that app — default theme, default shape mode, layout target, and app-only components.

Each app ships in its own GitHub repository, so the per-app deltas live at the root of their respective repos.

Repo / File	Scope
`gridwatch/meta · DESIGN.md`	Root — 14-color semantic contract, typography scale, shape tiers, component tokens.
`gridwatch/gridwatch · DESIGN.md`	GRIDWATCH iPad client — default `command-post`, MapLibre rules.
`gridwatch/ghost-grid · DESIGN.md`	Ghost Grid iPad client — default `radar-scope`, Canvas layer rules.
`gridwatch/quick-reaction-force · DESIGN.md`	QRF iPhone client — compact portrait only, swipe-card rules.

Shape of a DESIGN.md file

Front matter is the contract agents read. Prose below is rationale.

---
version: alpha
name: <identity name>
description: <one-line summary>
colors:
  background:       "#RRGGBB"
  surface:          "#RRGGBB"
  surface_elevated: "#RRGGBB"
  accent:           "#RRGGBB"
  accent_secondary: "#RRGGBB"
  text_primary:     "#RRGGBB"
  text_secondary:   "#RRGGBB"
  text_muted:       "#RRGGBB"
  friendly:         "#RRGGBB"
  hostile:          "#RRGGBB"
  health_good:      "#RRGGBB"
  health_warn:      "#RRGGBB"
  health_crit:      "#RRGGBB"
  divider:          "#RRGGBB"
typography:
  <token-name>: { fontFamily, fontSize, fontWeight, ... }
rounded:
  <tier>: <dimension>
spacing:
  <scale>: <dimension>
components:
  <component>:
    backgroundColor: "{colors.*}"
    textColor:       "{colors.*}"
    rounded:         "{rounded.*}"
    ...
---

The 14 color keys are semantic roles, not brand swatches. Every theme shipped in registries/shared/themes/*.yaml satisfies the same 14 keys — twelve-bravo validate rejects a theme that omits any of them. Agents should read through Theme.Colors.* and never reference a single theme’s hex values in app code.

Relationship to this site

This site describes the FDT corporate design system — tokens, components, and patterns across every Frontier surface. DESIGN.md is a narrower, game-specific machine contract consumed at authoring time by AI agents working inside the GRIDWATCH meta-repo. They are not redundant:

The design system (this site) is the human-facing decision record: why a color means what it means, what a component is for, what accessibility rules apply.
DESIGN.md is the agent-facing token snapshot: exact values, exact token paths, exact component schemas. It is terser and more structured, deliberately.

When the two disagree, this site is the source of truth for intent; DESIGN.md is the source of truth for values. Values should always match.

Linting

The upstream spec ships a CLI. Lint any of the four files with:

npx @google/design.md lint DESIGN.md

It validates token references, flags invalid hex, checks WCAG contrast on component pairs, and emits JSON findings that an agent can act on. Run it before merging changes that touch colors, typography, or components.