agent context· chapter 30 · 3 files · 1 export · 1 gate
the brand is readable by every coding agent
three files at the root carry every brand answer an external coding agent needs. AGENTS.md is the protocol. DESIGN.md is the visual identity. brand/designtoken.md is the agent-readable token superset. underneath them sits the W3C DTCG v1.0 export · one JSON file consumed by Figma's Tokens Studio, Style Dictionary v4, and any DTCG-aware downstream tool.
as of
01 · three filesAGENTS · DESIGN · designtokenthe three-file agent context stack
| file | scope | load | cap | standard |
|---|---|---|---|---|
AGENTS.md | project conventions · do/don't rules · file structure · safety boundaries | always-on · root → leaves | 32 KiB | OpenAI / Linux Foundation · 2025-12 |
DESIGN.md | visual identity · the WHY behind every brand decision · YAML frontmatter + Markdown prose | always-on · session start | 24 KiB | Google Labs · Apache 2.0 · 2026-04-21 |
brand/designtoken.md | full token graph · agent-readable superset of tokens.json | always-on · session start | open | agentskills.io · DTCG-superset |
SKILL.md | per-task domain knowledge · gotchas-driven | on-demand · loaded by agent | 5 K tokens / each | agentskills.io · 2026 |
why three files, not one
a single AGENTS.md hits the 32 KiB ceiling fast. the 2026 split is principled: protocol (AGENTS) ·identity (DESIGN) · graph(designtoken). each file answers a different question and loads at a different moment. the gate enforces that all three stay in parity with packages/tokens/tokens.json.as of
02 · dtcg v1.0218 leaves · 59 colorsthe W3C DTCG v1.0 export
| category | leaves | $type sample |
|---|---|---|
color | 59 | color.ink.0 · color |
space | 19 | space.0 · dimension |
fontSize | 17 | fontSize.10 · dimension |
fontWeight | 9 | fontWeight.thin · fontWeight |
lineHeight | 9 | lineHeight.tight · number |
letterSpacing | 6 | letterSpacing.tighter · string |
motion | 20 | motion.instant · duration |
radius | 10 | radius.0 · dimension |
hair | 4 | hair.1 · dimension |
shadow | 10 | shadow.0 · shadow |
opacity | 13 | opacity.0 · number |
z | 12 | z.below · number |
breakpoint | 7 | breakpoint.xs · dimension |
layout | 6 | layout.content-text-max · dimension |
blur | 7 | blur.0 · dimension |
gradient | 3 | gradient.amber-fade · gradient |
type | 7 | type.mono · fontFamily |
| token | hex | oklch |
|---|---|---|
color.amber.default | #d6a64a | oklch(75.2% 0.122 81.2) |
color.amber.soft | #c8a064 | oklch(72.9% 0.091 76.7) |
color.amber.deep | #a07a36 | oklch(60.3% 0.098 79.5) |
color.amber.muted | #8a6a30 | oklch(54.4% 0.086 80.1) |
color.green.default | #6dbf7e | oklch(73.5% 0.124 149.3) |
color.green.soft | #8fcf9b | oklch(79.7% 0.098 149.6) |
color.green.deep | #4a8a59 | oklch(57.7% 0.100 149.9) |
color.red.default | #c25e54 | oklch(60.1% 0.130 27.4) |
one source · three artefacts
tokens.json is the single source of truth. @zero/tokens's build emits four artefacts: tokens.css (runtime · already there), tokens.ts(typed runtime helpers), tokens.js (re-exports), and now dtcg.json (the W3C DTCG v1.0 export). parity is enforced by ci:design-md; if the YAML frontmatter of DESIGN.md drifts from tokens.json, the gate fails the merge.as of
03 · contract pinnedschema · version · substratethe design.md frontmatter pin
| field | value | source |
|---|---|---|
| schema | design.md.v1 | DESIGN.md frontmatter |
| version | 2026-05-10.4 | DESIGN.md frontmatter |
| adr | ADR-027 | DESIGN.md frontmatter |
| substrate | dark-only | DESIGN.md frontmatter |
| brand color | amber #d6a64a | tokens.json + DESIGN.md (parity-enforced) |
| signature color | acid #e5fe40 | tokens.json + DESIGN.md (parity-enforced) |
| amber coverage ceiling | ≤ 7% | brand-runtime · ci:amber |
how a coding agent reads this repo
on session start, the agent loads AGENTS.md + DESIGN.md(≤ 56 KiB total) and gets the complete answer to every brand decision. it does not have to re-derive the rules from chapter prose; it does not have to grep tokens.jsonto find the amber hex; it does not have to load every chapter to discover the 17 nots. the cost is one read per session, not one read per file edited.as of
04 · protocols (declared)A2UI · AG-UI · MCP-Apps · RSCrendering protocols · v2 surface
declared, not implemented
the four 2026 generative-UI protocols (A2UI · AG-UI · MCP Apps · Vercel RSC) are consumer-app concerns, not brand-system concerns. the brand system publishes the primitives (in @zero/ui · @zero/charts); the consumer (cockpit · league · the future getzero.dev) picks the protocol. a future ADR will land the rendering adapters when cockpit is the first consumer to need them.| protocol | scope | maturity | brand-system role |
|---|---|---|---|
A2UI · Google | declarative JSON for agent-emitted UI · flat adjacency list · LLM-friendly | v0.9 · Apache 2.0 · 2026-04-17 | publish primitive catalog (@zero/ui) the A2UI client renders into |
AG-UI | 16 event types over SSE/WS · agent ↔ frontend state contract | third leg of MCP / A2A / AG-UI | publish chart streaming primitives (@zero/charts · StreamingCursor) |
MCP Apps | interactive UI returned from MCP tools · ui:// URI scheme | live 2026-01-26 · first MCP extension | publish ApprovalGate · ConfidenceArc · ReasoningReveal · EvidenceTrail (already in @zero/ui) |
Vercel AI RSC | createStreamableUI · server → client React component streaming | experimental in AI SDK · UI for production | SSR primitives are RSC-clean today (chapter 28) |
as of
05 · agentic principlestransparency · confidence · delegationthe three agentic-UX principles already shipped
| principle | where it lives | primitive |
|---|---|---|
| transparency-control | show the right information at the right time · article I.6 · the pulse cools brand colours when network breathing slows | PostureBeacon · EvidenceTrail |
| confidence signalling | round to whole percentages · low → invisible · medium → faint line · high → labelled glyph | ConfidenceArc · the chart annotation layer (chapter 29) |
| progressive delegation | auto-approve scales with trust · early sessions show full plan · established sessions skip preview for proven safe types | ApprovalGate · SafetyShield · ReasoningReveal |
trust is a mechanical result of predictable communication
the three principles are not opinions. they are CI-enforced behaviours of the primitives that ship in @zero/ui. when an external coding agent assembles a screen from those primitives, it inherits the discipline by construction. the brand system does the work once; every consumer gets it for free.