agentic-spec validator enforces 15 rules on every component spec. Each rule prevents a specific class of bug that emerges when AI agents write code against a design system: a spec the agent can’t parse, a token the agent references that doesn’t exist, a status field that claims readiness the spec hasn’t earned. These rules are not stylistic preferences. They are the mechanical checks that keep the contract trustworthy.
Identity & structure rules
These rules verify that the spec and its companion token file exist, are parseable, and agree with each other. A spec that fails any of these can’t be read — by the validator, by an agent, or by a developer.Token cascade rules
These rules enforce the integrity of the 3-tier cascade. Each one catches a different way the token contract can become inconsistent — a name that points nowhere, an entry that’s never referenced, a tier value that’s malformed, a path that can’t resolve.Metadata sanity rules
These rules check the bookkeeping fields that agents and humans use to assess how much to trust a spec.Honesty gates
These two rules prevent specs from misrepresenting their own readiness. A spec that falsely claims to beAI-Ready corrupts the system for every agent and developer who trusts it.
Fixing a failure
Every line of validator output includes the rule name. Look it up in the tables above to understand what’s broken, then apply the relevant fix.Example error (blocks the build)
button.bg.invalid appears in the token_contract list in specs/button/index.md but has no corresponding entry in specs/button/tokens.json. You have two options:
- Add
button.bg.invalidtotokens.jsonwith a realpath,tier,role, andreferences— if the token should genuinely exist. - Remove
button.bg.invalidfromtoken_contractin the frontmatter — if the entry was added by mistake or is no longer needed.
Example warning (does not block the build, but blocks AI-Ready promotion)
tokens.json contains an entry named button.legacy that nothing in token_contract points at. The spec passes, but the warning will prevent the spec from being promoted to AI-Ready. Fix it by:
- Adding
button.legacytotoken_contract— if the token is still in use and should be part of the contract. - Removing
button.legacyfromtokens.json— if the token is stale and no longer needed.
Output formats
Run the validator in human-readable mode when working locally:--json for machine-readable output in CI pipelines, pre-commit hooks, or any tool that needs to parse the results:
package.json script or a GitHub Actions step — the build fails on errors, and warnings are visible in output without blocking the pipeline.
What the rules do NOT check
The validator is mechanical. It checks for structural consistency between the spec and its token file. It does not check:- Correctness about behavior. The spec might correctly describe a broken component. The validator won’t know.
- Design quality. Whether the chosen semantic tokens represent good design decisions is out of scope.
- ARIA sufficiency. The validator confirms that
required_ariais present and non-empty. It doesn’t evaluate whether the listed attributes are sufficient for the component’s accessibility needs. - State coverage. The validator confirms that
interaction_statesis present. It doesn’t check whether the listed states cover real user needs or edge cases.