# Tokens

Candor's tokens without its colours: the --cd-* variables, Candor's own @theme entries and the motion utilities every item's classes assume. It sets nothing a shadcn project already defines (radius, sidebar, colour roles, type scale, base styles). Every item installs it. A Candor project imports styles/candor.css and needs nothing more; with plain shadcn and your own colours, import styles/candor-tokens.css once, after Tailwind.

- Registry name: `tokens` (`@candor/tokens`)
- Tier: Free (MIT). No licence key needed.
- Docs: https://candor.themethodic.com/docs/tokens

## Install

```bash
npx candor-ui add tokens
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/tokens`.

## Example

```tsx
"use client"

import { Button } from "@/components/ui/button"

// The tokens a button's classes read: the radius (rounded-button), the control height per density and the press motion
// (cd-press). With plain shadcn and your own colours, import styles/candor-tokens.css after Tailwind to get them.
//
// Every token's name, layer, type, range and default is published as data at /r/tokens-manifest.json:
// { format, version, modes, densities, layers, types, tokens, patterns, slots, slotPatterns, internal }. Each token is
// { name, layer (theme, tokens, density, motion or sound), type (colour, length, duration, easing…),
// default: { light, dark?, hc? }, density?: { compact, spacious }, range?: { min?, max?, unit }, values?, description? };
// dark and hc appear only where they differ from light, and a default of null means Candor sets none. slots lists the
// data-slot names the components render, and internal the --cd-* names Candor's CSS uses itself, not for brand files.
export default function Example() {
  return (
    <div className="grid gap-4 sm:grid-cols-3">
      {(["default", "compact", "spacious"] as const).map((density) => (
        <section key={density} aria-label={`${density} density`} data-density={density === "default" ? undefined : density} className="flex flex-col items-start gap-2 rounded-lg border p-3">
          <code className="text-xs text-muted-foreground">{density === "default" ? "--cd-control-h" : `data-density="${density}"`}</code>
          <Button>Approve</Button>
          <Button variant="outline" size="sm">
            Ask for changes
          </Button>
        </section>
      ))}
    </div>
  )
}
```

## Rules for using Candor UI

- Components take plain typed data. Never pass model output as HTML or render it as a link; messages are typed blocks.
- A control that can't be used says why: wrap it in `<Locked reason="…">`, don't just disable it.
- Don't show a value you don't have: leave it out (it renders as —) rather than guess. An estimate is labelled as one.
- Nothing is pre-selected in a decision a person makes, and the agent is named from your app's data, never from model output.
- Your app's words go in `LocaleProvider` (fixed strings) and `TermsProvider` (nouns); entity kinds and agent roles in `EntityKindsProvider` and `AgentRolesProvider`.