Tooltip as the example throughout.
1
Scaffold the spec
Use This writes two files:
agentic-spec init to generate the two files that define the component’s contract. Pass the component name, the output directory, and the current system version:specs/tooltip/index.md— YAML frontmatter with all contract fields set to their empty defaults,status: Draftspecs/tooltip/tokens.json— an empty token list, ready to receive entries in step 4
tokens.json yet. The token list is only valid once you have defined the parts and states it needs to cover.2
Fill the contract
Open Every state listed here must have a corresponding Storybook story before the component can reach AI-Ready. Define states completely now so you know exactly what you need to build.
specs/tooltip/index.md and fill the three structural fields in the YAML frontmatter. Do not add any tokens to token_contract yet — that comes after you have built the token files in step 3.semantic_parts — name every internal region of the component. These names are the targets that token names must reference. For Tooltip:required_aria — enumerate every ARIA attribute the component must expose to satisfy accessibility requirements. For Tooltip:interaction_states — list every distinct visual and behavioral state the component can occupy. For Tooltip:3
Add component tokens
If the values your component needs already exist as semantic tokens (check The cascade rule is one-way: component tokens reference semantic tokens, semantic tokens reference primitives, primitives hold raw values. A component token that references a primitive (
packages/tokens/src/semantic-light.json), you can skip straight to step 4. If you need new tokens, create packages/tokens/src/components/tooltip.json.Each entry must reference a semantic token — never a primitive directly, never a hex value:{color.white} instead of {surface.elevated}) is a cascade violation and the validator will reject it.After adding the file, run pnpm build in the packages/tokens workspace to confirm Style Dictionary resolves all references without errors:4
Reflect tokens in the spec
Now that the token files exist, add each token to both Then update The validator checks that
specs/tooltip/tokens.json and the token_contract field in the spec frontmatter.Update specs/tooltip/tokens.json with a full entry for every token you added. Each entry records the token’s tier, its role in the component, its reference chain, and its resolved hex value in both schemes:token_contract in the frontmatter of specs/tooltip/index.md to list every token name exactly as it appears in tokens.json:token_contract and the entries in tokens.json match exactly — extra tokens in either file are a failure.5
Implement against the spec
Build the component at
packages/ui/src/components/Tooltip.tsx. Open the spec and keep it alongside the code as you work — use it as the authority for structure, tokens, and ARIA.Key rules:- Bind only tokens from
token_contract. Any color, radius, or spacing value that comes from outside the contract is a lint failure. - Implement every state in
interaction_states.closed,opening,open, andclosingmust be distinguishable in code. - Emit every attribute in
required_aria. For Tooltip that meansrole="tooltip"on the floating element andaria-describedbywiring on the trigger.
apps/storybook/stories/Tooltip.stories.tsx. Every state listed in the spec needs its own story — the validator counts them.6
Promote to AI-Ready
As each gate passes, flip the corresponding entry in the Run the validator to confirm:If the validator reports a
checks: block of the spec frontmatter to true. When all five checks are true, change status from Draft to AI-Ready:lying-check error, one of the gates is claiming true while the underlying condition is not met. Fix the underlying issue — add the missing story, bind the missing token, wire the missing ARIA — and run the validator again. Do not fix the error by reverting the check to false and leaving status: AI-Ready; that is the same lie in a different field.Once the component passes, an AI agent pointed at specs/tooltip/index.md can write a screen using Tooltip without inventing tokens, guessing at states, or omitting ARIA.Common mistakes
Related
Token Cascade
The rules governing how component tokens reference semantic tokens and why primitives are off-limits at the component tier.
Agentic Specs
How the spec format is structured, what each field means, and how AI agents consume it before writing code.
Contract Rules
The full set of rules the validator enforces — token closure, cascade direction, check honesty, and AI-Ready gates.