Guidelines
Working with this system
How the system evolves, how releases ship, and how AI agents work with it directly — the same rules whether the change is made by a person or an agent.
Governance
Every change runs through the same gate: npm run validate chains the token linter, a token-architecture linter, a WCAG AA contrast check across all four theme combinations, a component-registry check, a story-coverage check, a full type check, and the test suite. A non-zero exit on any of them means the change isn't finished — the fix is to resolve the underlying issue, not route around the check.
A few things are off the table entirely, enforced by the token linter rather than left to review: raw hex or primitive tokens in component CSS, hardcoded spacing or motion values, hardcoded line-heights, and the two-argument var(--x, fallback) form — a token either exists or it doesn't.
An architectural change — a new token tier, a new brand, a changed component model — gets a written Architecture Decision Record before it lands: context, the decision, the alternatives considered, and the consequences, one file per decision.
Versioning and releases
Releases go out through Changesets. A change that should ship gets a changeset describing it; a bot collects the pending changesets into a single "Version Packages" pull request bundling the version bump and changelog. Merging that PR is what actually publishes — authenticated via npm's trusted publishing (OIDC) from GitHub Actions, not a stored token.
The changelog itself — the page you'd expect — is generated from conventional commits, grouped by type and git tag, not hand-written alongside the code.
Working with AI agents
AGENTS.md is the entry point for any agent working in this repo — a short router, not a rulebook, pointing at the real detail (architecture, the quality gates above, feature specs, decision records) rather than holding it all in one file.
A compact agent skill is published alongside it, with progressive disclosure and explicit rules naming what doesn't exist — cold-tested twice against fresh agents with no memory of this repo before being called done.
A read-only MCP server exposes the same data live, for anyone with it connected, instead of as a snapshot that can go stale between publishes:
list_componentsEvery public component — name, slug, tier, purpose, token count.get_componentOne component's compiled doc — real props, real tokens, a real usage example.search_tokensSearch tokens by name or category, resolved values included.get_tokenOne token's full entry — raw value, resolved per axis, what uses it.validate_tokenChecks a var() or token name against the real fabrication rules before it ships.get_registry_itemThe shadcn-spec manifest for a component, for deciding install vs. hand-write.get_skillThe current agent skill content, live.