Skip to main content
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.
Use --json for programmatic output in CI pipelines or agent toolchains that need structured data:
To scaffold a new component spec directory, use init:
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: 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 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.