Skip to main content
Most validation failures follow predictable patterns. The rule name in the error output tells you exactly which contract constraint was violated. Look it up below, read the fix, and re-run validate to confirm.

Common errors

What it means: Your spec’s token_contract field lists a token name that does not appear in tokens.json. The contract points at nothing.Example output:
How to fix it:Option A — Add the missing token to tokens.json:
Option B — Remove the token name from token_contract in the spec frontmatter if you added it by mistake.Re-run agentic-spec validate specs/button after either change.
What it means: An entry exists in 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:
This is a warning, not an error. It does not fail the build on its own, but it does block 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.
What it means: The spec’s 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:
How to fix it:
  1. Fix the underlying token errors first (likely missing-token-entry or orphan-token-entry).
  2. Re-run agentic-spec validate specs/button.
  3. Only set checks.tokens_valid: true in the frontmatter after the validator confirms there are zero token errors.
Never set a checks: gate to true manually unless the validator agrees. The validator is what AI-Ready status means.
What it means: The spec has status: AI-Ready, but at least one of the five checks: fields is false. AI-Ready requires all five to be true.Example output:
How to fix it:Option A — Fix the failing gate. If 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.
What it means: 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:
How to fix it:Make the 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.
What it means: A 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:
How to fix it:
  1. Change the tier field for the entry to "component".
  2. Check that the token’s path points to packages/tokens/src/components/<name>.json, not to primitives.json.
  3. Check that the token in the JSON file references a semantic token ({action.primary}), not a primitive value directly ({color.blue.6}).
If no suitable semantic token exists, add one to semantic-light.json and semantic-dark.json first, then reference it from the component token.

General advice

  • Always run validate after adding tokens. Add the entry to tokens.json, add the name to token_contract, then validate. Doing both edits in one pass and validating at the end catches errors from either side.
  • Use --json output 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: Draft while you are building. Set status: In progress when the implementation exists but gates are not all passing. Set status: AI-Ready only after agentic-spec validate returns zero errors and all checks: are true. A spec that lies about its own status corrupts every agent and every human that reads it.