# Foundations — the token sheet (raw twin of /tokens)

Everything on /tokens is painted with utilities from `@candlelight-ds/tokens`.
The values are law (spec §2.9); the package's tests fail if one drifts.

Install: `pnpm add @candlelight-ds/tokens`

Tailwind v4 use:

```css
@import "tailwindcss";
@import "@candlelight-ds/tokens/tailwind.css";
```

Any other stack: `@import "@candlelight-ds/tokens";` (plain CSS custom
properties + normative structural classes; reproduce the utility names).

## The utility API (the names are the contract)

- Stage ladder: `bg-stage`, `bg-surface`, `bg-surface-2`, `bg-surface-3`,
  `border-hairline`, `border-hairline-strong`
- Ink ladder (three steps, no more): `text-ink`, `text-ink-mute`,
  `text-ink-faint` — alpha-composed white (`text-white/60`) is banned
- Voice: `bg-brass` / `bg-brass-hot` / `bg-brass-deep` (identity accent:
  armed, selected, primary, focus), `bg-live` (happening now), `bg-ready`,
  `bg-warn`, `bg-danger`, `bg-ember` (hold-to-strike ring)
- Fill ramp (never hand-mix alphas): `bg-fill-rest`, `bg-fill-hover`,
  `bg-fill-active`, `bg-fill-selected`
- Tint ramp (§2.4a — voice × stop, closed; ad-hoc voice alphas ≤50 are
  lint-banned): `-fill` 10% hover wash, `-chip` 12% chip fill, `-held` 15%
  pressed, `-rim` 45% armed rim — e.g. `bg-live-chip`, `hover:bg-brass-fill`,
  `bg-danger-held`, `ring-brass-rim`, `border-danger-rim`, over
  brass/live/ready/warn/danger. Dims above 50 (`text-brass/80` eyebrows,
  `hover:bg-danger/85` on solids) are a different job and stay slash-composed.
- Shadows: `shadow-raise`, `shadow-float`, `shadow-stage`
- Radii (closed scale — arbitrary radii are lint-banned): `rounded-cap` 4px
  chamfer, `rounded-sm` 8px controls, `rounded-md` 16px panels,
  `rounded-lg` 24px outermost shell
- Type (closed scale — arbitrary sizes are lint-banned): `text-nano` 9,
  `text-micro` 10, `text-eyebrow` 11, `text-tooltip` 11.5, `text-meta` 12,
  `text-body` 13, `text-body-lg` 14, `text-title` 15, `text-overlay-title`
  18, `text-heading` 20, `text-heading-lg` 28, `text-marquee` 68 (bundled:
  400 weight, −0.04em, lh 68). Weight/case stay at the call site.
- The baseline grid (§2.6a — `--baseline` 4px): every text step BUNDLES a
  baseline-locked leading — nano/micro 12 · eyebrow/tooltip/meta 16 ·
  body/body-lg/title 20 · overlay-title/heading 24 · heading-lg 32 ·
  marquee 68 — so using a step puts your line on the rhythm without
  asking. Arbitrary `leading-[Npx]` is lint-banned; override only with
  named `leading-*` steps on the rhythm. Prove a surface with the
  `grid-overlay` item (`.baseline-overlay` physics): mount it INSIDE the
  surface it audits, toggle with G from your surface map.
- Tracking: `tracking-chip` 0.16em, `tracking-label` 0.18em,
  `tracking-eyebrow` 0.22em, `tracking-title` −0.01em
- Z ladder: `z-surface`, `z-rail`, `z-float`, `z-overlay`, `z-announce` —
  999 does not exist
- Motion: `duration-instant` 120ms, `duration-ui` 150ms, `duration-sheet`
  150ms, `duration-scene` 2500ms, `ease-stage` — the vars are
  `--dur-*`/`--ease-stage`
- Structural classes: `.animate-stage-rise`, `.animate-scale-in`, `.skeleton`,
  `.sheet-panel`, `.key-cue`, `.key-cue-armed`, `.key-brass`, `.key-sunken`,
  `.pad-hit`, `.room-glow-layer`, `.room-glow-breathe`, `.slider`,
  `.scrollbar-custom`

## The contract metrics (one home per law number)

`import { SHEET_TAKEOVER_MAX, INK_SAVE_DEBOUNCE_MS, … } from
'@candlelight-ds/tokens/metrics'` — the behavioral contracts' numbers as
constants; components import them, never re-declare. The set:
`SHEET_TAKEOVER_MAX` 700 · `SHEET_WIDTH_MIN/MAX` 320/960 ·
`SHEET_LENS_WIDTH` 340 · `SHEET_FOCUS_WIDTH` 560 · `SHEET_HEADER_H` 72 ·
`LENS_CROSSFADE_MS` 120 · `MODAL_SM/LG/BARE_MAX_W` 460/640/560 ·
`STRIP_MIN_H` 76 · `INK_SAVE_DEBOUNCE_MS` 600 · `STRIKE_HOLD_MS` 600 ·
`ANNOUNCER_WALL_MS` 5500 · `TOAST_WALL_MS` 6000. Law-tested; a drift is a
red build.

Full law: /spec.md §2 and Appendices A–C.