# Design tokens

Tokens are the design contract: every visual value in every component resolves to one. They ship
in two forms, always in sync (a Jest test enforces it):

1. **Typed TS exports** — `import { spacing, colors, motion } from 'isotope-ui'`.
2. **CSS custom properties** — `--iso-*` on `:root`, from `isotope-ui/tokens.css` (also bundled
   into `isotope-ui/styles.css`).

`src/tokens/tokens.css` is generated by `pnpm build:tokens` — never edit it by hand.

## Naming

`--iso-<group>-<key…>`, nested keys joined with `-`:

| Group             | Examples                                                                                             |
| ----------------- | ---------------------------------------------------------------------------------------------------- |
| spacing           | `--iso-spacing-0` … `--iso-spacing-24` (rem scale)                                                   |
| radii             | `--iso-radius-none/sm/md/lg/xl/full`                                                                 |
| colors (palette)  | `--iso-color-gray-50` … `--iso-color-gray-900`, `blue`, `green`, `red`, `amber`                      |
| colors (semantic) | `--iso-color-text`, `--iso-color-surface`, `--iso-color-border`, `--iso-color-focus-ring`            |
| colors (tones)    | `--iso-color-<tone>-solid-bg/-solid-fg/-subtle-bg/…` for `neutral/accent/positive/critical/caution`  |
| shadows           | `--iso-shadow-sm/md/lg/overlay`                                                                      |
| borders           | `--iso-border-width-1/2`, `--iso-focus-ring-width`, `--iso-focus-ring-offset`                        |
| sizing            | `--iso-size-control-md`, `--iso-size-icon-sm`, `--iso-size-avatar-lg`                                |
| typography        | `--iso-font-family-sans`, `--iso-font-size-xl`, `--iso-font-weight-bold`, `--iso-line-height-normal` |
| motion            | `--iso-duration-fast/base/slow/slower/loop`, `--iso-easing-standard/enter/exit`                      |
| z-index           | `--iso-z-dropdown/sticky/overlay/modal/toast/tooltip`                                                |
| breakpoints       | `--iso-breakpoint-sm/md/lg/xl/2xl` (informational — see below)                                       |

## Overriding (theming)

The shape is fixed; the values are yours. Override at `:root` or any subtree:

```css
.brand-purple {
  --iso-color-accent-solid-bg: #7c3aed;
  --iso-color-accent-solid-bg-hover: #6d28d9;
}
```

Components pick up overrides automatically — they only ever read `var(--iso-*)`.

## Semantic over raw

Components use semantic tokens (`--iso-color-text`, tone sets) rather than palette entries, so a
theme override at the semantic layer restyles the whole library coherently.

## Breakpoints caveat

CSS custom properties can't be used inside `@media` conditions. The `--iso-breakpoint-*`
properties exist for tooling/introspection; media queries in component CSS must use the literal
value with a comment pointing at `breakpoints.ts`.

## Motion

Durations and easings only from `motion` tokens. Respect `prefers-reduced-motion` in any
animation you add:

```css
@media (prefers-reduced-motion: reduce) {
  .shimmer {
    animation: none;
  }
}
```