# Theme

Candor's default theme: light, dark and high contrast, contrast-checked. Import styles/candor.css after Tailwind.

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

## Install

```bash
npx candor-ui add theme
```

Run `npx candor-ui@latest init` once first (https://candor.themethodic.com/get-started.md). Without the CLI: `npx shadcn@latest add @candor/theme`.
npm packages: tw-animate-css@^1.4.0.

## Example

```tsx
"use client"

import { Message } from "@/components/message"
import type { Message as MessageData } from "@/lib/chat"

const roles = ["background", "card", "muted", "primary", "accent-weak", "success", "warning", "destructive", "attention"]

const reply: MessageData = {
  id: "m1",
  author: { role: "agent", agent: { id: "a", name: "Support agent", role: "assistant" } },
  status: "complete",
  blocks: [{ kind: "paragraph", nodes: [{ kind: "text", text: "Your order shipped yesterday and arrives within two days." }] }],
}

export default function Example() {
  return (
    <div className="flex flex-col gap-6">
      <div className="grid grid-cols-3 gap-3 sm:grid-cols-5">
        {roles.map((r) => (
          <div key={r} className="flex flex-col gap-1.5">
            <div className="h-12 rounded-lg border" style={{ background: `var(--${r})` }} />
            <code className="text-xs text-muted-foreground">--{r}</code>
          </div>
        ))}
        {[1, 2, 3, 4, 5, 6].map((n) => (
          <div key={n} className="flex flex-col gap-1.5">
            <div className="h-12 rounded-lg" style={{ background: `var(--series-${n})` }} />
            <code className="text-xs text-muted-foreground">--series-{n}</code>
          </div>
        ))}
      </div>
      {/* Size tokens: the default, and the compact preset (data-density="compact"). */}
      <div className="grid gap-4 sm:grid-cols-2">
        {(["default", "compact"] as const).map((density) => (
          <section key={density} aria-label={`${density} density`} data-density={density === "compact" ? "compact" : undefined} className="flex flex-col gap-2 rounded-lg border p-3">
            <code className="text-xs text-muted-foreground">{density === "compact" ? 'data-density="compact"' : "--cd-text-prose, --cd-thread-width"}</code>
            <Message message={reply} />
          </section>
        ))}
      </div>
    </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`.