> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Clementine DS: Token-Driven, AI-Ready React Components

> Clementine DS ships 10 React components, a 3-tier token cascade, and per-component specs that AI agents read to write correct, token-bound code.

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:

```
Primitives → Semantic → 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

> [card] [Quick Start](https://clementineds.mintlify.site/quickstart.md)
>
> Install and render your first component in under five minutes.

> [card] [Agentic Specs](https://clementineds.mintlify.site/concepts/agentic-specs.md)
>
> How AI agents read and validate the system's machine-readable contracts.

> [card] [Token Cascade](https://clementineds.mintlify.site/concepts/token-cascade.md)
>
> The 3-tier token architecture — primitives, semantic, and component tokens.

> [card] [Components](https://clementineds.mintlify.site/components/overview.md)
>
> All 10 components with usage examples, props, and token contracts.

> [card] [CLI Reference](https://clementineds.mintlify.site/cli/overview.md)
>
> Validate specs, scaffold new components, and bridge Figma with `agentic-spec`.

> [card] [Figma](https://clementineds.mintlify.site/integrations/figma.md)
>
> Figma variable collections that mirror the full three-tier token cascade.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.