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 fromspecs/button/index.md — the gold-standard reference component.
Status levels
Thestatus 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: #2563ebin a component. The tokenbutton.bg.defaultexists precisely so you don’t have to know the hex. - Invent a token. If
button.bg.pressedisn’t intoken_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_statesmust 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 onaria-busywill silently fail. Implement every attribute inrequired_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 thetoken_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.
The validator
Theagentic-spec CLI validates specs mechanically against 15 rules. Before you make any changes to a component spec, run it: