Skip to main content
Clementine DS is an opinionated React design system that ships three artifacts instead of two. Where most systems hand you a component library and a Storybook, Clementine adds a third: a per-component machine-readable spec that lives in 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:
Primitive tokens (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’s specs/<component>/ directory contains two files:
  • index.md — YAML frontmatter that declares the component’s semantic_parts (named internal regions), required_aria, interaction_states, token_contract (a closed list of permitted tokens), and sources (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.
A component reaches AI-Ready status when all five spec gates pass: tokens are fully declared and bound, all interaction states have Storybook stories, all ARIA requirements are implemented, the 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.