validate to confirm.
Common errors
missing-token-entry — token in contract has no tokens.json entry
missing-token-entry — token in contract has no tokens.json entry
What it means:
Your spec’s How to fix it:Option A — Add the missing token to Option B — Remove the token name from
token_contract field lists a token name that does not appear in tokens.json. The contract points at nothing.Example output:tokens.json:token_contract in the spec frontmatter if you added it by mistake.Re-run agentic-spec validate specs/button after either change.orphan-token-entry — tokens.json entry not referenced by token_contract
orphan-token-entry — tokens.json entry not referenced by token_contract
What it means:
An entry exists in This is a warning, not an error. It does not fail the build on its own, but it does block
tokens.json but its name does not appear in token_contract. The entry is dangling — the spec does not claim to use it.Example output:AI-Ready promotion because a component with orphaned tokens cannot have checks.tokens_valid: true.How to fix it:Option A — Add button.legacy to token_contract in the spec frontmatter if the component genuinely uses it.Option B — Remove the entry from tokens.json if it is stale.lying-check — tokens_valid: true but validator disagrees
lying-check — tokens_valid: true but validator disagrees
What it means:
The spec’s How to fix it:
checks.tokens_valid is set to true, but the validator found errors in the token contract. The spec is misrepresenting its own gate state.Example output:- Fix the underlying token errors first (likely
missing-token-entryororphan-token-entry). - Re-run
agentic-spec validate specs/button. - Only set
checks.tokens_valid: truein the frontmatter after the validator confirms there are zero token errors.
checks: gate to true manually unless the validator agrees. The validator is what AI-Ready status means.ai-ready-gate — status is AI-Ready but a check is false
ai-ready-gate — status is AI-Ready but a check is false
What it means:
The spec has How to fix it:Option A — Fix the failing gate. If
status: AI-Ready, but at least one of the five checks: fields is false. AI-Ready requires all five to be true.Example output:states_complete: false, add the missing Storybook stories, verify they cover every state in interaction_states, then set checks.states_complete: true.Option B — If the component is genuinely not ready, drop status to In progress until all gates pass.The five gates are: aria_correct, structure_correct, states_complete, tokens_valid, no_invented_styles. All five must be true before you set status: AI-Ready.identity-mismatch — component field differs between index.md and tokens.json
identity-mismatch — component field differs between index.md and tokens.json
What it means:
The How to fix it:Make the
component: field in index.md does not match the component: field in tokens.json. The two files are wired to different components.Example output:component: field identical in both files. Use kebab-case and match the directory name. If you copied a spec from another component to bootstrap a new one, the component: field in tokens.json is the most common place to forget the update.bad-token-tier — component token referencing a primitive
bad-token-tier — component token referencing a primitive
What it means:
A How to fix it:
tokens.json entry has "tier": "primitive" or "tier": "semantic" when it should be "tier": "component". Component specs must only list component-tier tokens. Referencing a primitive directly from a component token file violates the cascade rule.Example output:- Change the
tierfield for the entry to"component". - Check that the token’s
pathpoints topackages/tokens/src/components/<name>.json, not toprimitives.json. - Check that the token in the JSON file references a semantic token (
{action.primary}), not a primitive value directly ({color.blue.6}).
semantic-light.json and semantic-dark.json first, then reference it from the component token.General advice
-
Always run
validateafter adding tokens. Add the entry totokens.json, add the name totoken_contract, then validate. Doing both edits in one pass and validating at the end catches errors from either side. -
Use
--jsonoutput for scripting. If you are building a pre-commit hook or an agent workflow that checks spec state, parse the JSON rather than scraping the human-readable output. The JSON schema is stable. -
Spec status should always reflect actual gate state. Set
status: Draftwhile you are building. Setstatus: In progresswhen the implementation exists but gates are not all passing. Setstatus: AI-Readyonly afteragentic-spec validatereturns zero errors and allchecks:aretrue. A spec that lies about its own status corrupts every agent and every human that reads it.