> ## 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.

# How AI Agents Read and Validate Clementine DS Specs

> Clementine DS ships machine-readable per-component specs so AI agents validate tokens, ARIA, and states before writing code — no guessing, no drift.

Every AI agent that writes against a design system faces the same three failure modes: it hallucinates tokens that don't exist, misses ARIA attributes that aren't obvious from visual inspection, and skips interaction states because they seemed implied. Clementine DS replaces the guess with a lookup. Each component ships a spec — a machine-readable contract in `specs/<component>/index.md` — that tells the agent exactly which tokens to bind, which ARIA attributes are required, and which states must be implemented. The validator checks the spec before code ships. If a step is missing, the build fails.

## The reading order

When you're asked to write code that uses a Clementine component, follow these steps in order. Skipping any one of them trades the contract for pattern-matching.

**1. Open the spec first**

Navigate to `specs/<component>/index.md`. The YAML frontmatter is the contract. The prose below the frontmatter is the human explanation of intent — useful context, but not the authoritative source.

**2. Check the status field**

Read `status`. If it reads `AI-Ready`, the spec has passed all five validation gates and is safe to write against. If it reads `In progress`, treat the contents as provisional — ask before writing code. If it reads `Draft`, the spec is incomplete; do not write code against it.

**3. Read token\_contract**

`token_contract` is a closed list. Every token a component may use is enumerated here. Anything outside the list is not allowed. If you need a value that isn't listed, the correct move is to extend the contract — not to inline a hex or reference a semantic token directly.

**4. Read required\_aria and interaction\_states**

Both are fully enumerated. `required_aria` lists every ARIA attribute the component must expose. `interaction_states` lists every state that must be implemented in code and covered by a Storybook story. Implement all of them, or do not implement the component.

**5. Open the code**

`sources.react.path` (or `sources.code.path`) points at the TSX implementation. Read the code as an implementation of the spec, not as the source of truth. If code and spec disagree, the spec is right.

## The spec frontmatter fields

The frontmatter block is what the validator reads and what agents load before writing code. Every field has a defined meaning.

| Field | What it means |
| - | - |
| `component` | Stable kebab-case identifier. Used by the validator, file paths, and agents as the canonical name. |
| `ds_version` | The version of the token system this spec was verified against. Agents use this for cache invalidation. |
| `status` | Trust level: `AI-Ready`, `In progress`, or `Draft`. Determines whether the spec is safe to write against. |
| `last_verified` | The date the spec was last reconciled with the actual code, in `YYYY-MM-DD` format. Staleness checks use this. |
| `required_aria` | Array of ARIA attributes the component must expose. Every entry is mandatory — missing one is a contract violation. |
| `semantic_parts` | Named regions inside the component (e.g. `root`, `label`, `icon-leading`). Every token must target one of these parts. Tokens that don't are dangling. |
| `token_contract` | The complete closed list of tokens this component may use. Treat it as the only vocabulary available. |
| `interaction_states` | Every state that must exist in code and in Storybook. Non-negotiable: implement all of them. |
| `checks` | Self-reported gate results. Five boolean fields (`aria_correct`, `structure_correct`, `states_complete`, `tokens_valid`, `no_invented_styles`). All five must be `true` for `AI-Ready` to be valid. |
| `sources` | Pointers to the code file, Storybook stories, and token files. Use these to locate the actual implementation. |

### Real example: the button spec frontmatter

This is the complete frontmatter from `specs/button/index.md` — the gold-standard reference component.

```yaml theme={null}
---
component: button
ds_version: clementine-ds@HEAD (2026-06-08 verified)
status: AI-Ready
last_verified: 2026-06-08

category: Component
required_aria: [aria-label, aria-disabled, aria-busy]

semantic_parts:
  root:          The native <button> element — owns interactive state, focus ring, padding, sizing
  icon-leading:  Optional leading icon (left of label) — replaces with spinner in loading state
  label:         The text content of the button
  icon-trailing: Optional trailing icon (right of label)
  spinner:       Loading-state indicator that replaces icon-leading

token_contract:
  - button.bg.default
  - button.bg.hover
  - button.bg.active
  - button.bg.disabled
  - button.bg-destructive.default
  - button.bg-destructive.hover
  - button.bg-outline.default
  - button.bg-outline.hover
  - button.fg.on-filled
  - button.fg.on-outline
  - button.fg.disabled
  - button.border.default
  - button.border.hover
  - button.border.focus
  - button.radius

interaction_states: [default, hover, focus, active, disabled, loading]

checks:
  aria_correct: true
  structure_correct: true
  states_complete: true
  tokens_valid: true
  no_invented_styles: true

sources:
  react:
    path: packages/ui/src/components/Button.tsx
    underlying_library: mantine
    exports: [Button, ButtonProps]
  storybook:
    path: apps/storybook/stories/Button.stories.tsx
  tokens:
    primitives: packages/tokens/src/primitives.json
    semantic_light: packages/tokens/src/semantic-light.json
    component: packages/tokens/src/components/button.json
    semantic_dark: packages/tokens/src/semantic-dark.json

patterns_used_in: [form, action-bar, modal-footer, toolbar]
pages_used_in: [dashboard, settings, list-view]
---
```

Notice what the frontmatter gives you in one read: the exact tokens you may use (15 of them, no more), the three ARIA attributes you must expose, the six interaction states you must implement, and the paths to the code and token files you need to open next. You don't need to infer any of it.

## Status levels

The `status` field is a three-way gate between you (or an agent) and the component.

| Status | What it means for you |
| - | - |
| `AI-Ready` | All five `checks` passed the validator. The spec is in the state it claims to be in. Safe to write against. |
| `In progress` | The spec exists and is being actively completed. Some checks may be `false`. Treat the content as provisional — ask before writing code against it. |
| `Draft` | The spec has been scaffolded but not completed. The token contract, ARIA requirements, or interaction states may be incomplete or wrong. Do not write code against a `Draft` spec. |

`AI-Ready` means something precise here: it requires `aria_correct`, `structure_correct`, `states_complete`, `tokens_valid`, and `no_invented_styles` to all be `true` in the `checks` block, and the validator must agree. A spec cannot self-promote to `AI-Ready` if the validator disagrees — that's the `ai-ready-gate` rule.

## What agents must NOT do

These are hard prohibitions, not style suggestions. Each one corresponds to a class of bug that breaks the contract for every downstream agent and human.

* **Bind a hex value directly.** Never write `color: #2563eb` in a component. The token `button.bg.default` exists precisely so you don't have to know the hex.
* **Invent a token.** If `button.bg.pressed` isn't in `token_contract`, it doesn't exist. Using it produces a runtime gap and a validator failure. The correct move is to extend the contract through the proper workflow (see below).
* **Skip an interaction state.** The disabled state is not "obvious." The loading state is not "probably covered." Every state in `interaction_states` must be implemented. If you skip one because it seemed implied, you leave a gap that the next agent or developer has to discover at runtime.
* **Drop an ARIA attribute.** The visual renders correctly without `aria-busy`. That's the problem. Screen readers and testing libraries that depend on `aria-busy` will silently fail. Implement every attribute in `required_aria`.
* **Change the spec to match code you already wrote.** The spec is the source of truth. If your code and the spec disagree, fix the code.

## Extending without breaking the contract

If you need a value that isn't in the `token_contract`, follow this workflow exactly. Every step is required — skipping one breaks the contract for the next person or agent who reads the spec.

**1. Add to the component token file**

Add a new entry to `packages/tokens/src/components/<name>.json`. The value must reference an existing semantic token (e.g. `{action.primary-hover}`), never a primitive or a raw hex.

**2. Add the semantic if it doesn't exist**

If no semantic token covers the intent you need, add it to both `packages/tokens/src/semantic-light.json` and `semantic-dark.json`. The new semantic must reference an existing primitive — never a raw hex.

**3. Update the spec's tokens.json**

Add the new entry to `specs/<name>/tokens.json` with its `tier`, `role`, `path`, `references`, and `primitive` fields filled in.

**4. Add to token\_contract**

Add the new entry name to the `token_contract` list in the spec frontmatter.

**5. Bump last\_verified**

Set `last_verified` to today's date in `YYYY-MM-DD` format.

**6. Re-run the validator**

Run `agentic-spec validate specs/<name>` and confirm it passes before proceeding.

**7. Now write the code**

Only after all six previous steps have passed is the new token available for use in the component.

This is slower than inlining a hex. It is also the only way the spec remains a contract that agents and humans can trust.

## The validator

The `agentic-spec` CLI validates specs mechanically against 15 rules. Before you make any changes to a component spec, run it:

```bash theme={null}
agentic-spec validate specs/button
```

For machine-readable output in CI:

```bash theme={null}
agentic-spec validate specs/button --json
```

The exit code is non-zero on any error, zero on warning-only or clean pass. Use this in pre-commit hooks and PR checks.

If the validator fails, the spec is not in the state it claims to be in. Do not write code against a failing spec — fix the spec first, then write the code. The [contract rules reference](https://clementineds.mintlify.site/concepts/contract-rules.md) lists every rule, what it checks, and how to fix each failure.


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