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
<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 and Dark mode.