Skip to main content
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.

Real example: the button spec frontmatter

This is the complete frontmatter from specs/button/index.md — the gold-standard reference component.
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. 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:
For machine-readable output in CI:
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 lists every rule, what it checks, and how to fix each failure.