# Theming

A theme is three choices in one seed file. The generator derives every color, radius and focus ring for dark and light mode from them, so you never override tokens one by one.

## The seed

`npx werewolf-ui init` creates `tokens/seed.json` with the defaults below. Only the theme command changes it after that.

| Choice | Values | What it changes | Default |
| --- | --- | --- | --- |
| `accent` | A 3 or 6 digit hex | The accent tokens, the focus ring, and the hue of the grays when gray tint is above 0 | `#111111` |
| `gray-tint` | 0 to 1 | How much of the accent hue the neutral backgrounds, text, icons and borders take | `0` |
| `radius-base` | `sharp`, `default`, `round`, `pill`, or a px value | Every corner radius | `default` |

```json
{
  "seed": {
    "accent": { "$type": "color", "$value": "#111111" },
    "gray-tint": { "$type": "number", "$value": 0 },
    "radius-base": { "$type": "string", "$value": "default" }
  }
}
```

## Preview on this site

Open the Theme panel in the header and pick an accent, gray tint and radius. Every page of the docs, components included, updates live. Copy command gives you the matching theme command for your app.

## Apply it to your app

The theme command updates the seed and regenerates `styles/werewolf.css` together. Pass any of the three choices; omitted ones stay as they are. Both modes must pass every contrast check before anything is written, so a failed theme leaves the current one working.

```bash
npx werewolf-ui theme --accent "<hex>"
npx werewolf-ui theme --gray-tint 0.25 --radius-base round
npx werewolf-ui theme --radius-base 6px
```

If you edited the generated stylesheet by hand, the command reports a conflict instead of overwriting it. Review the file, then pass its path to `--overwrite`.

## How the accent behaves

The accent is for primary actions, selection, links and focus, not for decoration or large fills. When an accent is too dark or too light to reach 3:1 on the page in one mode, the generator adjusts it for that mode. The default `#111111` stays exact in light mode and turns near white in dark mode, with text on it picked for contrast. Because the dark accent then equals the main text color, links are always underlined.

## Radius presets

Each preset sets four steps. A px value `N` gives `N` for elements, `N + 4` for containers and `N + 8` for pages, with the inner step capped at 6px.

| Preset | `radius-inner` | `radius-element` | `radius-container` | `radius-page` |
| --- | --- | --- | --- | --- |
| `sharp` | 2px | 4px | 6px | 8px |
| `default` | 4px | 8px | 12px | 16px |
| `round` | 6px | 12px | 16px | 20px |
| `pill` | 6px | full | 20px | 28px |

## Dark and light mode

Dark is the default on `:root`. `data-theme="light"` on any element switches it and everything inside it to light; `data-theme="dark"` switches back. Remember the visitor's choice in your own app code.

## Touch sizes

The stylesheet ends with one `@media (pointer: coarse)` block that raises control heights, hit areas and input text on touch screens. It follows the input, not the screen width, so an iPad with a trackpad keeps mouse sizes. You do not need your own media queries for sizes.

## Export tokens to other platforms

Export the tokens of an initialized app to a directory inside it. Every export writes `json/dark.json` and `json/light.json`, plus the files of one platform: `web/` (CSS and the Tailwind theme), `ios/` (SwiftUI) or `android/` (Compose). Run the command once per platform. Native files use the touch sizes and contain tokens only; native components are planned for v2.

```bash
npx werewolf-ui tokens build --out exported-tokens
npx werewolf-ui tokens build --platform ios --out exported-tokens
npx werewolf-ui tokens build --platform android --out exported-tokens
```

## Without the CLI

In the Theme panel, Copy CSS or Download werewolf.css gives you the stylesheet for your choices; replace `styles/werewolf.css` with it. For the default theme only, [download tokens.css](https://www.werewolf-ui.dev/tokens.css). A stylesheet you replace by hand counts as your edit, so a later `theme` run asks for `--overwrite`.