specs/<component>/ and acts as the source of truth for every token, every interaction state, and every required ARIA attribute. AI agents — Claude, Cursor, Copilot, MCP servers — read that spec before they write code, which means they produce token-bound, accessible output on the first pass instead of inventing values from screenshots.
The three-tier token cascade
Every visual decision in Clementine flows through a one-way cascade before it reaches a component:packages/tokens/src/primitives.json) are the raw values: hex colors, pixel sizes, radii, font sizes. They have no semantic meaning — color.orange.500 is a color, not a role.
Semantic tokens (packages/tokens/src/semantic-light.json, semantic-dark.json) assign meaning to primitives: surface.elevated, text.primary, border.subtle. These are the tokens that flip when you switch color schemes. There are 32 semantic tokens covering light and dark modes.
Component tokens (packages/tokens/src/components/<name>.json) scope semantic tokens to a specific part of a specific component: button.bg.default, button.border.focus, tooltip.bg. A component may only reference tokens from its own component tier — never raw primitives, never another component’s tokens. This boundary is enforced by the spec validator.
The cascade means a single Figma mode switch, a single JSON edit, or a single theme override propagates cleanly through all 102 component tokens without touching component code.
Machine-readable specs and AI-Ready status
Each component’sspecs/<component>/ directory contains two files:
index.md— YAML frontmatter that declares the component’ssemantic_parts(named internal regions),required_aria,interaction_states,token_contract(a closed list of permitted tokens), andsources(exact file paths to code, stories, and tokens). The body documents the component in prose.tokens.json— a flat list of every token in the contract with its tier, role, reference chain, and resolved hex value for both light and dark modes.
token_contract matches tokens.json, and the spec has been reconciled with the code at last_verified. The CLI enforces this — you cannot flip status: AI-Ready while a gate is failing without the validator flagging a lying-check error.
When an agent reads an AI-Ready spec, it knows exactly which tokens to use, which parts to target, which states to handle, and which ARIA to emit — before writing a single line of code.
Start here
Quick Start
Install and render your first component in under five minutes.
Agentic Specs
How AI agents read and validate the system’s machine-readable contracts.
Token Cascade
The 3-tier token architecture — primitives, semantic, and component tokens.
Components
All 10 components with usage examples, props, and token contracts.
CLI Reference
Validate specs, scaffold new components, and bridge Figma with
agentic-spec.Figma
Figma variable collections that mirror the full three-tier token cascade.