Skip to content

An open source design system that's fully customizable and agent ready

TypeScript
4.7 KB
Raw Blame

Design specifications

Design specs record human-owned visual and interaction intent: hierarchy, anatomy, state representation, allowed variation, and representative examples. They may describe one component or a cross-component pattern.

State taxonomy

State records are split by who drives the change. These are the only three state-taxonomy records:

Record Owns
User states Person-driven rest, hover, press, focus, selection, and manipulation states
System states System-driven disabled, loading, processing, status, and transient feedback states
Agentic states Agent-driven thinking, streaming, tool execution, waiting, synchronization, inspection, and rendering states

Other records

Record Owns
Spatial hierarchy Perceptual grouping through proximity, spacing tiers, and alignment
Control rhythm Alignment and density relationships among mixed controls
Shape relationships Role-based and concentric geometry for nested surfaces
Elevation hierarchy Agreement between perceived depth and actual layer order
Typography hierarchy Legible, distinguishable text roles across themes and layouts
Iconography Icon meaning, size, artwork, color, composition, and accessibility
Color emphasis Semantic color roles, contrast intent, and local emphasis
Motion Meaningful movement, timing hierarchy, and easing intent
Reduced motion Cross-fade on touch and immediate change otherwise under reduced motion
Ordered collection reordering Drag preview, candidate insertion, commit, and settle intent for ordered collections
Template composition Page- and block-level layout, hierarchy, spacing, component fidelity, and theming

Create a separate record when a subject has a different owner, approval lifecycle, requirement set, evidence set, or reason to change independently. Keep implementation mechanics, public API syntax, audit results, and consumer usage outside these records and link to their canonical owners instead.

Design specs do not own implementation mechanics, public prop syntax, current audit results, or consumer usage guidance. Component and family contracts link to stable design requirement IDs instead of copying their rationale.

Public-safe normative screenshots, diagrams, and visual state references live under docs/design/assets/<design-id>/. Each referenced asset records alt text, state, theme/mode, viewport when relevant, and what decision it demonstrates. Generated audit screenshots remain audit evidence rather than design authority. Private design sources stay private and are never named or linked here.

New design specs start as draft. Initial promotion to current, later changes, and normative asset updates require approval of their content from any current member of .github/ENGOWNERS or .github/DESIGNOWNERS (architecture:knowledge-contracts DEC-14). A mixed PR still needs an ENGOWNER for non-design current records. The design record names its content owners separately from this repository gate.

A DESIGNOWNER approves with a review or /approve-spec <sha>, like every other owner; in a mixed PR every other applicable code or spec-owner group remains required. The gate decides approval only; it never enables auto-merge.

Use docs/templates/knowledge/design-spec.md.