Skip to main content
Adding a component to Clementine DS follows a strict six-step workflow that keeps the agentic contract intact from the first commit. The order matters: you define the contract before you write implementation code, and you promote a component to AI-Ready only after the validator confirms every gate is green. Skipping steps — especially writing TSX before filling the spec — produces a component that drifts from the system and cannot be safely used by an AI agent. This walkthrough uses Tooltip as the example throughout.
1

Scaffold the spec

Use 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:
This writes two files:
  • specs/tooltip/index.md — YAML frontmatter with all contract fields set to their empty defaults, status: Draft
  • specs/tooltip/tokens.json — an empty token list, ready to receive entries in step 4
Do not edit 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 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:
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.
3

Add component tokens

If the values your component needs already exist as semantic tokens (check 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:
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 ({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 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:
Then update token_contract in the frontmatter of specs/tooltip/index.md to list every token name exactly as it appears in tokens.json:
The validator checks that 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, and closing must be distinguishable in code.
  • Emit every attribute in required_aria. For Tooltip that means role="tooltip" on the floating element and aria-describedby wiring on the trigger.
Once the component compiles, add a Storybook story for each interaction state in 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 checks: block of the spec frontmatter to true. When all five checks are true, change status from Draft to AI-Ready:
Run the validator to confirm:
If the validator reports a 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

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.