Foundation — Governance
Foundation Page Structure Spec
Canonical structure for all Foundation component documentation pages. Every new component page must implement all required sections in order. This page also records the Sprint 11 consistency audit across the six agentic component pages.
Sprint 11 audit · 6 pages reviewed · 2 new demos added
Required Section Order
Sections 1–8 are required on every component documentation page. Section 9 (See Also) is optional but recommended when the component composes others.
Page Header
Overline breadcrumb, H1 title, lead paragraph (≤ 2 sentences), component list in mono.
tokens: --ds-text-primary · --ds-text-secondary · --ds-text-muted · --ds-border-structure
Conceptual Overview
2–4 principle cards or a short prose section. What problem does this pattern solve? When should you reach for it?
tokens: --ds-surface-raised · --ds-border-structure
Live Demo / Interactive Preview
Working component render, ideally interactive. For multi-variant components, use a tab selector. Key states must be visible without interaction: default, active, error.
tokens: --ds-surface-raised · --ds-color-temporal (tab active indicator)
Anatomy
Named parts diagram or labeled breakdown. Each part gets: name, token, and purpose. Use the overline label style for part names.
tokens: --ds-color-agency (active/executing parts) · --ds-color-validation (human-review parts) · --ds-color-temporal (in-flight parts)
Prop Table
TypeScript interface rendered as a reference table. Columns: Prop, Type, Default, Description. Required props marked with asterisk. Use mono font for type and default values.
tokens: --ds-surface-raised · --ds-border-structure · --ds-text-muted (header labels)
Token Reference
Table of semantic tokens this component consumes. Columns: Token, Value (light), Meaning, Use in this component.
Do / Don't
2–4 pairs maximum. Each pair: a concrete anti-pattern on the right, the corrected version on the left. Keep examples small and scannable.
tokens: --ds-color-outcome-positive (do) · --ds-color-outcome-negative (don't)
Usage
Minimal copy-paste code example. Use the import path. Show 1–2 variants. No extra prose — the code should speak for itself.
tokens: --ds-surface-raised (code block bg)
See Also
Related component links. 2–4 entries. Each entry: label + one-line description.
Prop Table Format
Required columns in order. Required props marked with * after the prop name. Type and default values use mono font.
* = required prop
Sprint 11 Consistency Audit
Audit of all six agentic foundation pages against the required section checklist. Columns are the 8 required sections. Green = present, red = missing.
| Page | Header | Overview | Demo | Anatomy | Tokens | Do/Don't | Props | Usage | Score |
|---|---|---|---|---|---|---|---|---|---|
| Agent Identity | 8/8 | ||||||||
| Trust & Provenance | 8/8 | ||||||||
| LLM Latency States | 8/8 | ||||||||
| Multi-Agent Coordination | 8/8 | ||||||||
| Agentic Design Language | 2/8 | ||||||||
| Agentic Playground | 5/8 |
Agent Identity: Complete — all 8 sections present. Sprint 11.
Trust & Provenance: Complete — all 8 sections present. ProvenanceChain + ConfidenceMeter prop tables. Sprint 11.
LLM Latency States: Complete — StreamingResponse + ThinkingState prop tables added. Sprint 11.
Multi-Agent Coordination: Complete — anatomy and AgentConflictPanel prop table added. Sprint 11.
Agentic Design Language: Concept page — different template applies. No component demos needed.
Agentic Playground: Interactive explorer with prop controls. Anatomy and Do/Don't out of scope for this format.
Demo Registry — Sprint 11 Additions
Two demos added to lib/demo-registry.tsx in this sprint. The other three priority components already had demos registered.
Anti-Patterns in Page Authoring
Don't
Define style constants locally (const overline = ...)
Do
Import from lib/site-styles.ts — 72 copies of MONO existed before consolidation
Don't
Skip the Token Reference section
Do
Every component page must declare which --ds-* tokens it consumes and why
Don't
Add a demo with hardcoded hex colors
Do
Demos must use var(--ds-*) tokens — they run in both light and dark mode
Don't
Omit the Do/Don't section because the component seems obvious
Do
No component is obvious. Document at least two anti-patterns — future authors will thank you
Don't
Use a human face or generic avatar for an agent identity
Do
Agent identity must use the geometric monogram system — never a photo or human avatar
Don't
Show only the happy path in the live demo
Do
Demos must include at minimum: default, active/loading, and error states