# Design tokens

Name intent once. Carry it through your whole interface.

Tokens express the role of a design value. `bg-brand-mid` communicates brand emphasis; `text-neutral-strong` communicates readable primary text. Frontfriend generates semantic Tailwind utilities from your Design System.

## The vocabulary

The general form is `{utility}-{family}-{step}[-{state}]`. Common utilities include `bg-`, `text-`, `border-`, `ring-`, `outline-`, `fill-` and `stroke-`.

| Family | Purpose | Example |
| --- | --- | --- |
| `brand` | Brand emphasis | `bg-brand-mid` |
| `neutral` | General interface content | `text-neutral-strong` |
| `interactive` | Interactive surfaces | `bg-interactive-mid` |
| `positive` | Successful outcomes | `text-positive-strong` |
| `negative` | Errors and destructive actions | `bg-negative-mid` |
| `warning` | Attention and caution | `text-warning-strong` |
| `info` | Informational content | `text-info-strong` |
| `highlight` | Highlighted content | `bg-highlight-subtle` |
| `inverse` | Inverse contrast | `bg-inverse-mid` |

Foreground families such as `onbrand` pair with their background intent. Available steps and states come from the system; do not assume every combination exists.

## Layers and states

```tsx
<section className="bg-layer-raised text-neutral-strong border border-neutral-subtle rounded-lg p-6">
  <h2 className="text-lg font-semibold">A shared foundation</h2>
  <p className="text-neutral-mid">A change with a clear purpose.</p>
</section>
```

Surface examples include `layer-below`, `layer-surface`, `layer-raised`, `layer-control`, `layer-popover` and `layer-dialog`. Use `bg-overlay` for an overlay. Hover and active states can be explicit tokens, such as `bg-brand-mid-hover`; disabled controls use dedicated disabled tokens.

Spacing, radius and typography scale remain normal Tailwind utilities. Color families, surfaces, font families and animations use the generated vocabulary.

## shadcn compatibility

| shadcn role | Frontfriend role |
| --- | --- |
| `primary` | `brand-mid` |
| `primary-foreground` | `onbrand-mid` |
| `background` | `layer-below` |
| `foreground` | `neutral-strong` |
| `muted-foreground` | `neutral-mid` |
| `destructive` | `negative-mid` |
| `border` | `neutral-subtle` |

Compatibility variables preserve shadcn roles while your canonical vocabulary becomes semantic. Do not mechanically replace every string without understanding its role.

## Generated files

The build plugin resolves `@frontfriend/tailwind/theme.css` to generated cache assets. Configuration-driven classes are included for Tailwind scanning. Avoid editing generated cache files; update the Design System and regenerate.

When available, `.frontfriend/foundation.md` is the authoritative vocabulary for your specific system. See [Agent context](/docs/agent-context/) and [Dark mode](/docs/dark-mode/).