@fieldui/tokens

Design tokens for Field — a headless-first React component library for audio interfaces (waveforms, transports, meters, spectrograms, scrubbers, regions, knobs, faders).

This package ships the CSS custom properties (and a TypeScript token map) that give Field its visual identity. The visual components in @fieldui/react read these tokens; the headless hooks in @fieldui/core don't depend on this package at all.

┌──────────────────────────────────────────────────────────────┐
│  @fieldui/react        components (canvas + radix + tailwind) │
│  @fieldui/core         headless hooks (audio graph, RAF, etc.)│
│  @fieldui/tokens   ←   CSS variables + TS token map           │
└──────────────────────────────────────────────────────────────┘

If you only want to theme existing Field components, you don't need to touch this package directly — it's a transitive dep of @fieldui/react. You override CSS variables on :root and the changes cascade through every component. This package is interesting on its own if you're (a) reading the brand vocabulary, (b) building UI of your own that should share the Field palette, or (c) referring to the variable names by their TypeScript constants instead of hard-coded strings.

Design language

Field's look is articulated in tokens.css ("Field Brand Guide v2.1") and is meant to feel like a small piece of hardware — workshop tools, lab gear, a synth on a desk:

| Layer | Defaults | |--------------|----------------------------------------------------------| | Surfaces | Warm "paper" stack — bone, oat, cream, wheat | | Ink | Soft black through driftwood and stone | | Accents | Tempered rust (primary), moss green, workwear cobalt, ochre warning | | Typography | DM Sans (UI) · JetBrains Mono (numerics) · VT323 (LCD readouts) | | Geometry | Tight 2/4/8/14px radii — "hardware corners", not pill shapes | | Spacing | Linear (8/16/24…) plus a golden-ratio scale (10/14/20/40/64) |

Three opinionated choices follow:

1. The token layer is the API. Components never hard-code colour. They read var(--color-audio-waveform-peak), var(--color-button-accent), etc., so re-declaring a single variable on :root re-tones the whole library — no ThemeProvider required.
2. Tailwind palette anchors are re-toned to the brand. tokens.css overrides --color-slate-*, --color-red-500, --color-blue-500, etc., so legacy utility classes (bg-slate-900, text-red-600) adopt the warm palette automatically.
3. Numerics are first-class. Time displays, level digits, and tabular readouts use the bitmap LCD face (.field-bitmap) or tabular monospace (.field-tabular), because reading numbers under motion is the workload.

Install

npm install @fieldui/tokens
# or pnpm / yarn / bun

Usage

CSS

Import the stylesheet once (typically in your app entry):

@import "@fieldui/tokens/tokens.css";

This declares all variables on :root. From there, reach for whichever variable fits your need:

.my-readout {
  background: var(--color-audio-transport-bg);
  color: var(--color-paper);
  font-family: var(--font-bitmap);
}

.my-meter-warn {
  background: var(--color-audio-meter-warn);
}

TypeScript

If you'd rather refer to variables through type-safe constants:

import { tokens, cssVar, cssVars } from "@fieldui/tokens";

// `tokens.color.audio.waveformPeak` is already wrapped — `var(--color-audio-waveform-peak)`.
const styles = { background: tokens.color.audio.transportBg };

// `cssVars` gives you the raw token names, no var(...) wrapper.
const peakName = cssVars.color.audio.waveformPeak; // "--color-audio-waveform-peak"

// `cssVar(name, fallback?)` is a tiny helper for ad-hoc usage.
const fg = cssVar("--color-ink", "#111110");

A rename in tokens.css flushes through the type system as a compile error, so Canvas components can reference these constants safely.

Theming

There's no ThemeProvider — themes are CSS variables, scoped however you like. This snippet retones the rust accents to cobalt across every Field component, with no React state involved:

:root[data-theme="lab"] {
  --color-audio-scrubber:    var(--color-cobalt);
  --color-audio-region:      color-mix(in oklab, var(--color-cobalt) 18%, transparent);
  --color-audio-meter-warn:  var(--color-ochre);
  --color-button-accent:     var(--color-cobalt);
}

Toggle <html data-theme="lab"> and every meter, scrubber, and button shifts. See tokens.css for the full vocabulary, including the Tailwind anchor overrides.

Token surface

A flavour of what's available — see the source for the full list.

Brand palette --color-paper / -soft / -warm / -deep (warm off-white stack) · --color-ink / -mute / -soft / -light (soft-black ink stack) · --color-rust / -deep / -pale (tempered orange accent) · --color-moss / -deep / -pale (fern green) · --color-cobalt / -deep / -pale (workwear blue) · --color-ochre (warning amber) · --color-lcd-green / --color-lcd-amber (bitmap LCD glow) · --color-rule / -soft (hairline dividers).

Audio-semantic colours (the layer canvas components reach for) --color-audio-waveform-peak, …-rms, --color-audio-meter-safe, …-warn, …-clip, --color-audio-scrubber, --color-audio-region, --color-audio-playhead, --color-audio-transport-bg.

Type scale --text-h1 / h2 / h3 / subtitle / body / body-bold / small / pre-title / button / link. Each carries a matching --text-*--line-height, --text-*--letter-spacing, and --text-*--font-weight.

Spacing linear --spacing-1…--spacing-8 (8 → 64 px) plus golden --spacing-golden-1…--spacing-golden-5 (10 → 64 px).

Radius --radius-xs (2 px) · -sm (4 px) · -md (8 px) · -lg (14 px).

Tailwind anchors --color-slate-* retoned to paper/ink, --color-red-* to rust, --color-blue-500 to cobalt, --color-green-500 to moss, --color-amber-500 to ochre. Drop-in transitions for legacy class soup.

Compatibility

• Tailwind CSS v4 (the file uses @theme {} blocks). Earlier Tailwind versions read the :root variables fine but won't pick up the type scale or palette anchors.
• Modern evergreen browsers — color-mix() and oklab are used in the audio-semantic and button palettes for graceful colour shifts. If your target list pre-dates 2023, you'll want to swap those for static hex fallbacks in your override layer.

Sibling packages

| Package | Role | |---------|------| | @fieldui/core | Headless React hooks for audio — transport, audio graph, peaks, regions, recording. No UI, no token dependency. | | @fieldui/react | Visual components built on @fieldui/core hooks; styles read these tokens. |

License

MIT — © 2026 fieldui.