> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Add a New Component to Clementine DS: Six-Step Guide

> Follow the six-step workflow to scaffold a spec, define component tokens, implement the TSX, write Storybook stories, and reach AI-Ready status.

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:

```bash theme={null}
agentic-spec init tooltip --out ./specs --ds-version "clementine-ds@HEAD"
```

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:

```yaml theme={null}
semantic_parts:
  - root
  - arrow
  - body
```

**`required_aria`** — enumerate every ARIA attribute the component must expose to satisfy accessibility requirements. For Tooltip:

```yaml theme={null}
required_aria:
  - role: tooltip
  - aria-describedby
```

**`interaction_states`** — list every distinct visual and behavioral state the component can occupy. For Tooltip:

```yaml theme={null}
interaction_states:
  - closed
  - opening
  - open
  - closing
```

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:

```json theme={null}
{
  "tooltip": {
    "bg":     { "$value": "{surface.elevated}", "$type": "color" },
    "fg":     { "$value": "{text.primary}",     "$type": "color" },
    "radius": { "$value": "{radius.sm}",         "$type": "dimension" }
  }
}
```

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:

```bash theme={null}
cd packages/tokens && pnpm build
```

**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:

```json theme={null}
{
  "tokens": [
    {
      "name": "tooltip.bg",
      "tier": "component",
      "role": "fill",
      "path": "tooltip.bg",
      "references": "{surface.elevated}",
      "primitive": "{color.white}",
      "light": "#ffffff",
      "status": "existing"
    },
    {
      "name": "tooltip.fg",
      "tier": "component",
      "role": "text",
      "path": "tooltip.fg",
      "references": "{text.primary}",
      "primitive": "{color.gray.900}",
      "light": "#111827",
      "status": "existing"
    },
    {
      "name": "tooltip.radius",
      "tier": "component",
      "role": "border-radius",
      "path": "tooltip.radius",
      "references": "{radius.sm}",
      "primitive": "{size.2}",
      "light": "4px",
      "status": "existing"
    }
  ]
}
```

Then update `token_contract` in the frontmatter of `specs/tooltip/index.md` to list every token name exactly as it appears in `tokens.json`:

```yaml theme={null}
token_contract:
  - tooltip.bg
  - tooltip.fg
  - tooltip.radius
```

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.

```bash theme={null}
pnpm storybook
# Verify each story renders correctly at http://localhost:6006
```

**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`:

```yaml theme={null}
status: AI-Ready
checks:
  tokens_declared: true
  tokens_bound: true
  states_covered: true
  aria_complete: true
  spec_reconciled: true
```

Run the validator to confirm:

```bash theme={null}
agentic-spec validate specs/tooltip
# PASS tooltip (specs/tooltip)
#   tokens: 3 in contract, 3 in tokens.json · states: 4 · parts: 3
```

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

| Mistake | Fix |
| - | - |
| Binding a hex value directly in the TSX | Create a component token that references a semantic token, then bind the component token |
| Component token references a primitive (`{color.orange.500}`) | Add a semantic token in between — component tokens must reference semantic, never primitive |
| Flipping `status: AI-Ready` while a story is missing | The validator will catch this with a `lying-check` error — add the missing story first |
| `token_contract` lists more tokens than `tokens.json` | The lists must match exactly — remove the extra entry from the frontmatter or add the corresponding entry to `tokens.json` |
| `interaction_states` lists a state that has no story | Add the story or remove the state from the spec — the validator counts stories against the state list |
| New semantic token skips the primitives layer | Every semantic token must ultimately resolve to a primitive — trace the reference chain and add the primitive if it is missing |

## Related

> [card] [Token Cascade](https://clementineds.mintlify.site/concepts/token-cascade.md)
>
> The rules governing how component tokens reference semantic tokens and why primitives are off-limits at the component tier.

> [card] [Agentic Specs](https://clementineds.mintlify.site/concepts/agentic-specs.md)
>
> How the spec format is structured, what each field means, and how AI agents consume it before writing code.

> [card] [Contract Rules](https://clementineds.mintlify.site/concepts/contract-rules.md)
>
> The full set of rules the validator enforces — token closure, cascade direction, check honesty, and AI-Ready gates.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.