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

# AI Coding Agents with Clementine DS: Using Component Specs

> Point Claude, Cursor, GitHub Copilot, or any MCP server at Clementine DS specs for token-correct, ARIA-complete code without hallucinated tokens.

Clementine DS is designed for AI agents to read. When you point an agent at `specs/button/index.md`, it gets a closed contract instead of needing to guess. The spec tells the agent which tokens to bind, which ARIA attributes to add, which interaction states to implement, and exactly which files to open. There is nothing to infer.

## The agent reading order

Follow these steps every time you ask an agent to write or modify a component:

**Step 1 — Open the spec.**
Navigate to `specs/<component>/index.md`. The YAML frontmatter is the machine-readable contract. The prose below it is the human explanation. Read the frontmatter first.

**Step 2 — Check `status`.**
Trust `AI-Ready`. Question `In progress` — the spec may be incomplete. Refuse `Draft` — the spec is not ready for code generation.

**Step 3 — Read `token_contract`.**
This is a closed list. Every token the component may use appears here. Anything outside this list is forbidden, even if it looks correct. If the value you need is not in the list, extend the token system — do not inline a value.

**Step 4 — Read `required_aria` and `interaction_states`.**
Both fields are fully enumerated. Implement every ARIA attribute in `required_aria`. Implement every state in `interaction_states`. Skipping either is a contract violation.

**Step 5 — Open the code.**
`sources.code.path` in the frontmatter points at the component's TSX file. The code is an implementation of the spec, not the source of truth. If code and spec conflict, the spec wins.

## What agents must NOT do

* Bind a hex value directly (e.g. `color: '#2563eb'`). Use the token.
* Invent a token that does not exist in `tokens.json` (e.g. `color.brand.primary`). Check the contract first.
* Skip an interaction state because it seemed obvious or low-priority. Every state in `interaction_states` must be implemented.
* Drop an ARIA attribute because the visual works without it. Accessibility is part of the contract.
* Change the spec to match code you have already written. The spec is the contract; code follows from it.

## Using the agentic-spec CLI in your agent workflow

Run the validator before making any edits to a component. A failing spec is telling you the component is not in the state it claims to be in — do not write code against it.

```bash theme={null}
# Validate before editing
agentic-spec validate specs/<component>

# Example output
# PASS button (specs/button)
#   tokens: 15 in contract, 15 in tokens.json · states: 6 · parts: 5
```

Use `--json` for programmatic output in CI pipelines or agent toolchains that need structured data:

```bash theme={null}
agentic-spec validate specs/<component> --json
```

To scaffold a new component spec directory, use `init`:

```bash theme={null}
agentic-spec init <name> --out ./specs --ds-version "clementine-ds@HEAD"
```

This creates `specs/<name>/index.md` (status: Draft) and `specs/<name>/tokens.json` with stubs. Fill in `semantic_parts` and `interaction_states` before writing any code.

## Supported tools

Any agent that can read files from the repository works with this system. Tested workflows include:

| Tool | How to point it at the system |
| - | - |
| **Claude** (Claude Code / claude.ai) | Open the repo, ask it to read `specs/<component>/index.md` before writing |
| **Cursor** | Open the monorepo as the workspace; Cursor reads specs on demand |
| **GitHub Copilot** | Works with Copilot Chat when specs are in the open workspace |
| **MCP servers** | Use `figma-console-mcp` or any file-reading MCP server; point at `specs/` as the authoritative source |

The system does not require a special plugin or integration. The contract is in plain markdown and YAML files. Any agent that can read a file can use it.

## Extending the system

If a token you need is not in the contract, the correct path is to extend the system — not to bypass it. Add the token at the right tier, wire it through the cascade, update the spec, and re-run the validator. See the [first component workflow](https://clementineds.mintlify.site/first-component.md) for a step-by-step walkthrough of this process.

## Why this works

Design systems fail with AI agents because agents operate on pattern recognition. An agent asked to style a button guesses that buttons are usually blue, focus rings are usually 2px, disabled text is usually grey — and it is sometimes right. When it is wrong, the error is silent.

Clementine replaces guessing with lookup. The spec narrows the token vocabulary to exactly the values this component uses. The agent reads the list, binds to the listed tokens, and produces code that is correct by construction. If any token in the list is broken, the validator says so before the code ships.

The spec does not make the agent smarter. It makes the problem smaller — small enough that correctness is mechanical.


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