npm - remarque-tokens - Versions diffs - 0.16.0 → 0.17.0 - Mend

remarque-tokens 0.16.0 → 0.17.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (13) hide show

package/AGENT_RULES.md CHANGED Viewed

@@ -62,12 +62,14 @@ These are not guidelines. Agents must follow them literally.
 - Within the centered column, use `.content-reading` for prose-width sections (46rem, auto-centered within the 72rem column)
 - Do NOT use Tailwind's `max-w-reading` or `max-w-standard` on page sections — these only set max-width without centering. Use the CSS classes `.content-reading` / `.content-standard` instead, which include `margin-inline: auto`
 - Code blocks (`<pre>`) inherit the width of their parent container — no special wrapping needed when the parent is already constrained
+- Stacking order is structural, not personalization: never author a bare `z-index` number — reference `tokens-core.css`'s `--z-*` scale (`--z-base`/`--z-sticky`/`--z-dropdown`/`--z-overlay`/`--z-modal`/`--z-toast`/`--z-skip-link`). Tailwind v4 has no `--z-index-*` theme namespace, so use arbitrary values (`z-[var(--z-modal)]`) rather than bare Tailwind numbers. See REMARQUE.md "Stacking."
 ### Color
 - Accent color is used for exactly two things: inline links and one interactive element per viewport
 - Dark mode is not an inverted light mode — it must be independently tuned for readability
 - Background colors use `--color-bg`, never pure white (#fff) or pure black (#000)
+- State colors (`--color-error`/`--color-success`/`--color-warning`/`--color-disabled`, plus the `-subtle` banner-background companions on the first three) are for feedback moments only — form validation, status banners, disabled controls — never for decoration. The one-accent rule above still governs everything else. See REMARQUE.md "State Colors."
 ### Components
@@ -212,6 +214,8 @@ Before considering any implementation complete, verify:
 - [ ] Muted text placed on `--color-surface` still meets 4.5:1 (check the surface pairing, not just bg)
 - [ ] All transitions use the motion duration tokens (reduced-motion support depends on it)
 - [ ] Skip-to-content link present and functional
+- [ ] If state colors are used (error/success/warning/disabled): only for feedback moments (validation, banners, disabled controls), never decoration; every state text color and `-subtle` companion passes `npm run audit`
+- [ ] No bare `z-index` numbers anywhere in the page's CSS — every stacking layer references `tokens-core.css`'s `--z-*` scale
 - [ ] OG meta tags present (og:title, og:description, og:image)
 - [ ] `<html lang="en">` attribute set
 - [ ] The site looks more like a book than a web app

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,68 @@ All notable changes to `remarque-tokens` are documented here. Token value
 changes always state the design rationale — downstream sites pin against
 these entries when syncing.
+## 0.17.0 — 2026-07-23
+Semantic state colors + z-index scale (closes #26, closes #29).
+### Added
+- **State colors (`tokens-palette.css`, PALETTE tier)** — four semantic slots for feedback
+  moments (form validation, status banners, disabled controls), never decoration; the
+  one-accent rule still governs everything else. Hand-authored from the house ANSI hue
+  conventions, both themes, all three dark-mode conventions (`@media
+  prefers-color-scheme: dark`, `[data-theme="dark"]`, `:root.dark`):
+  - `--color-error` (hue 25, ANSI red) — light `oklch(0.52 0.12 25)` 5.44:1 bg / 5.28:1
+    surface; dark `oklch(0.62 0.11 26)` 5.07:1 bg / 4.82:1 surface.
+  - `--color-success` (hue 145, ANSI green) — light `oklch(0.51 0.12 145)` 5.08:1 bg /
+    4.93:1 surface; dark `oklch(0.61 0.11 145)` 5.36:1 bg / 5.10:1 surface.
+  - `--color-warning` (hue 85, ANSI yellow) — light `oklch(0.52 0.105 85)` 5.17:1 bg /
+    5.02:1 surface; dark `oklch(0.62 0.11 85)` 5.29:1 bg / 5.03:1 surface. The hard case:
+    yellow's low luminance-contrast means this slot solves noticeably darker in light
+    mode than error/success, the same shape as `--color-syntax-constant`'s solve.
+  - `--color-disabled` — aliased to `var(--color-muted)` in both themes: neutral
+    hue-80 muted family, deliberately **not** ANSI-derived.
+  - `-subtle` banner-background companions on the first three (`--color-error-subtle`/
+    `--color-success-subtle`/`--color-warning-subtle`, modeled on `--color-accent-subtle`
+    — near-bg lightness, state hue, low chroma) verified so `--color-fg` stays ≥4.5:1 on
+    them (the pairing that matters for callout/banner body text). No `-subtle` for
+    `--color-disabled` — a disabled control is quieter, not tinted.
+  - Every state text color ≥4.5:1 against `--color-bg` **and** `--color-surface`, both
+    themes; `scripts/audit.mjs` gains the 11 new pairings, `scripts/test-audit.mjs`'s
+    fixtures cover all seven tokens plus a must-fail case (`state-color-fails.css`).
+  - `scripts/theme.mjs` (`remarque-theme`) derives error/success/warning from a source
+    theme's red/green/yellow ANSI slots — keep-if-passing lightness checked against the
+    **stricter** of `--color-bg`/`--color-surface` at once (a new dual-target solver,
+    `keepOrSolveDual`/`solveDual`), not just one target like every other slot. Disabled
+    aliases the already-derived `--color-muted`. `-subtle` companions derive like
+    `--color-accent-subtle` (fixed 0.95 / bg+0.06 starting lightness — not the theme's
+    own solved bg lightness, which can exceed 0.95), nudged toward the extreme only if a
+    pathological theme doesn't already clear 4.5:1 against `--color-fg`. Self-verify
+    `CHECKS` mirrors `audit.mjs`'s new pairings exactly.
+  - `scripts/palette-golden.mjs` golden-gates all seven new tokens for free (it already
+    iterates whatever the bridge emits) — ΔE2000 ≤ 2.0 against `remarque-light`/
+    `remarque-dark`'s ANSI derivation, same identity/serialization contract as the rest
+    of the default palette. All new tokens land at ΔE ≤ 0.5 (see the PR description for
+    the full per-token table).
+  - REMARQUE.md "State Colors" — semantics, usage table, derivation note; Enforcement
+    Checklist gains the state-color pairing line.
+- **Z-index scale (`tokens-core.css`, CORE tier)** — stacking is structural, not
+  personalization. A small ordinal scale, sparse gaps of 10: `--z-base` (0), `--z-sticky`
+  (10), `--z-dropdown` (20), `--z-overlay` (30), `--z-modal` (40), `--z-toast` (50),
+  `--z-skip-link` (60, tops everything). Wired into `essay.css`'s sticky TOC rail
+  (`z-index: var(--z-sticky)`) and the demo site's skip-to-content link
+  (`focus:z-[var(--z-skip-link)]`, replacing a hardcoded Tailwind `focus:z-50`).
+  `theme.css`'s header comment documents the Tailwind v4 workaround — v4 has no
+  `--z-index-*` theme namespace, so `z-*` utilities can't map to these directly; use
+  arbitrary values (`z-[var(--z-modal)]`) instead, same pattern as the motion durations.
+  REMARQUE.md "Stacking" — the scale, and the rule that consumer CSS must never author a
+  bare `z-index` number. AGENT_RULES.md's Layout/Quality Checklist sections gain matching
+  lines.
+### Changed
+- **`scripts/tokens-json.mjs`** — `typeOf()` now types `--z-*` tokens as `number`
+  (unitless stacking-order integers), matching the existing `--leading-*` treatment,
+  instead of falling through to the generic `string` type.
 ## 0.16.0 — 2026-07-23
 Broadsheet pattern — masthead, lead article, numbered entry list, post-header kicker, graduated from the flagship (closes #36).

package/REMARQUE.md CHANGED Viewed

@@ -90,6 +90,23 @@ The audit remains the gate regardless of provenance — `remarque-theme` self-ve
 ---
+## State Colors
+Four semantic slots — `--color-error`, `--color-success`, `--color-warning`, `--color-disabled` — for feedback moments: form validation, status banners, disabled controls. **These are for feedback, not decoration.** The one-accent rule ("Visual Rules" / "Changing the Accent Hue") still governs expressive color everywhere else — a state color says "this specific thing failed/succeeded/needs attention/can't be used right now," not "this section is important." Don't recolor headings, borders, or chrome with a state color; reserve it for the actual feedback element (an inline error message, a success toast, a disabled button's text).
+Three of the four carry a `-subtle` companion — `--color-error-subtle`, `--color-success-subtle`, `--color-warning-subtle` — a faint tinted background for callout/banner-style feedback (an error banner, a success toast), sized the same way `--color-accent-subtle` is: near-`--color-bg` lightness, the state's hue, low chroma. `--color-disabled` has no `-subtle` companion — a disabled control is quieter than its enabled state, not tinted; use `--color-surface`/`--color-bg-subtle` for a disabled control's background if it needs one.
+| Slot | Use for | `-subtle` companion |
+|---|---|---|
+| `--color-error` | Validation errors, failure states, destructive-action confirmation text | `--color-error-subtle` (banner/callout background) |
+| `--color-success` | Confirmation messages, completed states | `--color-success-subtle` |
+| `--color-warning` | Caution messages, states needing attention before proceeding | `--color-warning-subtle` |
+| `--color-disabled` | Text/icon color for a disabled control | — (no subtle background; see above) |
+**Derivation:** hand-authored in `tokens-palette.css` from the house ANSI hue conventions — error hue 25 (red), success hue 145 (green), warning hue 85 (yellow) — the same conventions `--color-syntax-string`/`--color-syntax-constant` already use for green/yellow. `scripts/remarque-theme` derives all three from a source theme's `red`/`green`/`yellow` ANSI slots (keep-if-passing lightness, checked against the **stricter** of `--color-bg` and `--color-surface` at once, not just one), exactly like every other slot in "Color Providers." `--color-disabled` is deliberately **not** ANSI-derived — it aliases the already-derived neutral `--color-muted` family, since a disabled state is a muted/quiet register, not a hue. Warning (hue 85, yellow) is the hard case in light mode — yellow has low luminance-contrast against a light background, so its solved lightness sits noticeably darker than the other two states, the same shape as `--color-syntax-constant`'s solve. Every state text color holds ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background holds `--color-fg` ≥ 4.5:1 on it (the pairing that matters for a callout's body text) — both enforced by `scripts/audit.mjs` and golden-gated (ΔE2000 ≤ 2.0) against the upstream themes like the rest of the default palette.
+---
 ## Font Slots
 Remarque uses a three-slot font system. Each slot has a strict role, and each slot accepts a small set of approved faces — swap the face, keep the role.
@@ -365,6 +382,26 @@ Motion in Remarque is nearly invisible. The only permitted motion:
 ---
+## Stacking
+Stacking order is structural, not personalization — `tokens-core.css` (CORE tier, never overridden) carries a small ordinal `--z-*` scale:
+| Token | Value | Use for |
+|---|---:|---|
+| `--z-base` | 0 | Default stacking context — the implicit baseline |
+| `--z-sticky` | 10 | Sticky headers/rails (essay.css's TOC rail) |
+| `--z-dropdown` | 20 | Dropdown/select menus |
+| `--z-overlay` | 30 | Overlays/backdrops |
+| `--z-modal` | 40 | Modal dialogs |
+| `--z-toast` | 50 | Toast/notification stacks |
+| `--z-skip-link` | 60 | The skip-to-content link — tops everything; it must never be obscured when focused |
+**The rule: never a bare `z-index` number in consumer CSS.** Reference one of these seven tokens instead — an unnamed `z-index: 999` (or any other asserted integer) can't be reasoned about against the rest of the page's stacking contexts, and it's the same "hardcoded value bypasses the token system" problem as a literal hex color or a bare font-size. The scale is deliberately sparse (gaps of 10) so a future layer can be inserted between two existing rungs without renumbering everything above it.
+Tailwind v4 ships `z-*` as a static, non-themable utility scale — there's no `--z-index-*` entry in its default `@theme` to map these into. `theme.css` (the Tailwind v4 adapter) documents the workaround in its header comment: use arbitrary values with the tokens, `z-[var(--z-modal)]` / `focus:z-[var(--z-skip-link)]`, the same pattern already used for motion durations (`duration-[var(--motion-fast)]`).
+---
 ## USWDS Accessibility Compliance
 Remarque adopts typography and accessibility standards from the [US Web Design System (USWDS)](https://designsystem.digital.gov/documentation/accessibility/) and [WCAG 2.1](https://www.w3.org/WAI/WCAG21/Understanding/):
@@ -419,6 +456,8 @@ Every PR that ships Remarque pages MUST pass (`npm run audit` automates the colo
 - [ ] No hardcoded hex/rgb colors — only `var(--color-*)` tokens.
 - [ ] Body line-height ≥ 1.5 (Remarque target: 1.75).
 - [ ] Every `--color-syntax-*` slot ≥ 4.5:1 against `--color-code-bg` in both themes (see "Syntax Highlighting").
+- [ ] Every `--color-error`/`--color-success`/`--color-warning`/`--color-disabled` ≥ 4.5:1 against `--color-bg` **and** `--color-surface` in both themes; every `-subtle` background keeps `--color-fg` ≥ 4.5:1 on it (see "State Colors"). State colors used only for feedback moments, never decoration.
+- [ ] No bare `z-index` number in consumer CSS — reference `tokens-core.css`'s `--z-*` scale (see "Stacking").
 Agents reviewing PRs should reject changes that violate any line above without explicit rationale.

package/essay.css CHANGED Viewed

@@ -421,6 +421,9 @@
     align-self: start;
     justify-self: start;
     position: sticky;
+    /* --z-sticky (tokens-core.css, issue #29) — never a bare z-index
+       number in consumer CSS. */
+    z-index: var(--z-sticky);
     top: var(--space-6);
     width: 100%;
     max-height: calc(100vh - var(--space-8));

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "engines": {
     "node": ">=18"
   },

package/scripts/audit.mjs CHANGED Viewed

@@ -122,6 +122,20 @@ const CHECKS = [
   ['color-syntax-punctuation', 'color-code-bg', 4.5, 'syntax: punctuation'],
   ['color-syntax-variable', 'color-code-bg', 4.5, 'syntax: variable'],
   ['color-syntax-link', 'color-code-bg', 4.5, 'syntax: link'],
+  // Semantic state colors (issue #26) — feedback moments, not decoration.
+  ['color-error', 'color-bg', 4.5, 'state: error text'],
+  ['color-error', 'color-surface', 4.5, 'state: error text on surface'],
+  ['color-success', 'color-bg', 4.5, 'state: success text'],
+  ['color-success', 'color-surface', 4.5, 'state: success text on surface'],
+  ['color-warning', 'color-bg', 4.5, 'state: warning text'],
+  ['color-warning', 'color-surface', 4.5, 'state: warning text on surface'],
+  ['color-disabled', 'color-bg', 4.5, 'state: disabled text'],
+  ['color-disabled', 'color-surface', 4.5, 'state: disabled text on surface'],
+  // -subtle banner backgrounds: the pairing that matters is --color-fg on
+  // the subtle background (callout/banner body text), not the state color.
+  ['color-fg', 'color-error-subtle', 4.5, 'state: fg on error-subtle banner bg'],
+  ['color-fg', 'color-success-subtle', 4.5, 'state: fg on success-subtle banner bg'],
+  ['color-fg', 'color-warning-subtle', 4.5, 'state: fg on warning-subtle banner bg'],
 ];
 for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {

package/scripts/theme.mjs CHANGED Viewed

@@ -387,6 +387,101 @@ function deriveSyntaxLink(accent, codeBg, dir) {
   return keepOrSolve(accent[0], accent[1], accent[2], codeBg, 4.5, dir);
 }
+/* ── Semantic state colors (issue #26) ────────────────────────────────
+ * error/success/warning are derived from the theme's red/green/yellow ANSI
+ * slots — the same "ANSI colors already carry this domain's personality"
+ * argument as the syntax slots above, applied to feedback-moment colors
+ * instead of code tokens. Unlike every other keep-if-passing slot, the
+ * target here is TWO backgrounds at once (--color-bg and --color-surface,
+ * per the #26 scope comment: "keep-if-passing vs both") — a state color
+ * must hold 4.5:1 against whichever of the two is stricter, not just one.
+ * disabled is NOT ANSI — it aliases the already-derived neutral muted
+ * family, same as tokens-palette.css's hand-authored default.
+ */
+/* Dual-target variant of keepOrSolve/solveL: passes only when BOTH bg and
+ * surface clear `target` at the candidate L. Mirrors their guarded-nudge
+ * fallback shape, just checking two ratios instead of one. */
+function solveLDual(C, H, bg, surface, target, dir) {
+  const searchTarget = target * 1.03;
+  let lo = 0, hi = 1;
+  for (let i = 0; i < 40; i++) {
+    const mid = (lo + hi) / 2;
+    const c = fitChroma(mid, C, H);
+    const passes = ratio([mid, c, H], bg) >= searchTarget && ratio([mid, c, H], surface) >= searchTarget;
+    if (dir === 'darker') { if (passes) lo = mid; else hi = mid; }
+    else { if (passes) hi = mid; else lo = mid; }
+  }
+  let L = r3(dir === 'darker' ? lo : hi);
+  let c = fitChroma(L, C, H);
+  let guard = 0;
+  while ((ratio([L, c, H], bg) < target || ratio([L, c, H], surface) < target) && guard < 100) {
+    const next = dir === 'darker' ? r3(L - 0.001) : r3(L + 0.001);
+    if (next < 0 || next > 1 || next === L) break;
+    L = next;
+    c = fitChroma(L, C, H);
+    guard++;
+  }
+  const ok = ratio([L, c, H], bg) >= target && ratio([L, c, H], surface) >= target;
+  if (ok) return { L, C: c, H: r1(H), ok };
+  return { L, C: c, H: r1(H), ok: false };
+}
+function solveDual(C, H, bg, surface, target, dir) {
+  let r = solveLDual(C, H, bg, surface, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  // Chroma-collapse fallback, same rationale as solveL's.
+  r = solveLDual(0, H, bg, surface, target, dir);
+  if (r.ok) return [r.L, r.C, r.H];
+  die(
+    `internal error: cannot solve a state color for a ${target}:1 target against both bg and surface ` +
+    `(hue ${H.toFixed(1)}, direction ${dir}) even with chroma collapsed to 0 — pathological theme colors`
+  );
+}
+/* keep-if-passing against BOTH bg and surface at once. */
+function keepOrSolveDual(L0, C, H, bg, surface, target, dir) {
+  const L = Math.min(1, Math.max(0, r3(L0)));
+  const c = fitChroma(L, C, H);
+  if (ratio([L, c, H], bg) >= target && ratio([L, c, H], surface) >= target) return [L, c, r1(H)];
+  return solveDual(C, H, bg, surface, target, dir);
+}
+const STATE_CHROMA_CAP = 0.14; // same restrained ceiling as --color-accent / syntax slots
+function deriveStateColor(t, ansiName, label, bg, surface, dir) {
+  const [L0, C0, H0] = slotLch(t, ansiName, label);
+  const C = Math.min(C0, STATE_CHROMA_CAP);
+  return keepOrSolveDual(L0, C, H0, bg, surface, 4.5, dir);
+}
+/* -subtle companions: near-bg lightness (mirrors --color-accent-subtle
+ * EXACTLY — same fixed 0.95 / bg+0.06 starting points, not a theme-
+ * relative "bg's own lightness" — accent-subtle is the identity this
+ * mirrors, and its light-side constant is 0.95 regardless of how high a
+ * given theme's own solved bg lightness lands), state hue, low chroma —
+ * verified so --color-fg stays >= 4.5:1 on the result (the pairing that
+ * matters for a callout/banner's body text), not re-verified against bg/
+ * surface (it's a background, not a text color). `dir` 'darker' (light
+ * theme): subtle starts at 0.95. 'lighter' (dark theme): subtle starts at
+ * bg + 0.06. Nudged further toward the extreme (whiter in light, blacker
+ * in dark) only if a pathological theme's hue/chroma combination doesn't
+ * already clear 4.5:1 against fg at that starting lightness. */
+function deriveStateSubtle(bgL, H, chromaCap, fg, dir) {
+  let L = dir === 'darker' ? 0.95 : r3(Math.min(bgL + 0.06, 1));
+  let c = fitChroma(L, chromaCap, H);
+  let guard = 0;
+  while (ratio(fg, [L, c, H]) < 4.5 && guard < 200) {
+    L = dir === 'darker' ? r3(Math.min(1, L + 0.001)) : r3(Math.max(0, L - 0.001));
+    c = fitChroma(L, chromaCap, H);
+    guard++;
+  }
+  if (ratio(fg, [L, c, H]) < 4.5) {
+    die(`internal error: cannot solve a state-subtle background (hue ${H.toFixed(1)}, dir ${dir}) that holds --color-fg >= 4.5:1 — pathological theme colors`);
+  }
+  return [L, c, r1(H)];
+}
 /* ── LIGHT derivation ─────────────────────────────────────────────── */
 function deriveLight(t) {
@@ -425,6 +520,15 @@ function deriveLight(t) {
   const synPunctuation = deriveSyntaxPunctuation(fgC, fgH, codeBg, 'darker');
   const synVariable = deriveSyntaxVariable(fg, codeBg, 'darker', 0.08);
   const synLink = deriveSyntaxLink(accent, codeBg, 'darker');
+  // Semantic state colors (issue #26) — see the derivation helpers above.
+  // error/success/warning: keep-if-passing vs BOTH bg and surface at once;
+  // disabled: aliased to the already-derived muted family, not ANSI.
+  const stateError = deriveStateColor(t, 'red', 'light', bg, surface, 'darker');
+  const stateSuccess = deriveStateColor(t, 'green', 'light', bg, surface, 'darker');
+  const stateWarning = deriveStateColor(t, 'yellow', 'light', bg, surface, 'darker');
+  const stateErrorSubtle = deriveStateSubtle(bg[0], stateError[2], 0.02, fg, 'darker');
+  const stateSuccessSubtle = deriveStateSubtle(bg[0], stateSuccess[2], 0.02, fg, 'darker');
+  const stateWarningSubtle = deriveStateSubtle(bg[0], stateWarning[2], 0.02, fg, 'darker');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': [r3(bg[0] - 0.02), bg[1], bg[2]],
@@ -450,6 +554,13 @@ function deriveLight(t) {
     'color-syntax-punctuation': synPunctuation,
     'color-syntax-variable': synVariable,
     'color-syntax-link': synLink,
+    'color-error': stateError,
+    'color-error-subtle': stateErrorSubtle,
+    'color-success': stateSuccess,
+    'color-success-subtle': stateSuccessSubtle,
+    'color-warning': stateWarning,
+    'color-warning-subtle': stateWarningSubtle,
+    'color-disabled': { ref: 'color-muted' },
   };
   const tokens = {};
   for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
@@ -503,6 +614,14 @@ function deriveDark(t, accentHueLight) {
   const synPunctuation = deriveSyntaxPunctuation(fgC, fgH, codeBg, 'lighter');
   const synVariable = deriveSyntaxVariable(fg, codeBg, 'lighter', -0.08);
   const synLink = deriveSyntaxLink(accent, codeBg, 'lighter');
+  // Semantic state colors (issue #26) — mirrors the light derivation,
+  // direction flipped ('lighter': text on a dark bg/surface).
+  const stateError = deriveStateColor(t, 'red', 'dark', bg, surface, 'lighter');
+  const stateSuccess = deriveStateColor(t, 'green', 'dark', bg, surface, 'lighter');
+  const stateWarning = deriveStateColor(t, 'yellow', 'dark', bg, surface, 'lighter');
+  const stateErrorSubtle = deriveStateSubtle(bg[0], stateError[2], 0.04, fg, 'lighter');
+  const stateSuccessSubtle = deriveStateSubtle(bg[0], stateSuccess[2], 0.04, fg, 'lighter');
+  const stateWarningSubtle = deriveStateSubtle(bg[0], stateWarning[2], 0.04, fg, 'lighter');
   const raw = {
     'color-bg': bg,
     'color-bg-subtle': surface,
@@ -528,6 +647,13 @@ function deriveDark(t, accentHueLight) {
     'color-syntax-punctuation': synPunctuation,
     'color-syntax-variable': synVariable,
     'color-syntax-link': synLink,
+    'color-error': stateError,
+    'color-error-subtle': stateErrorSubtle,
+    'color-success': stateSuccess,
+    'color-success-subtle': stateSuccessSubtle,
+    'color-warning': stateWarning,
+    'color-warning-subtle': stateWarningSubtle,
+    'color-disabled': { ref: 'color-muted' },
   };
   const tokens = {};
   for (const [name, v] of Object.entries(raw)) tokens[name] = v.ref ? `var(--${v.ref})` : fmt(v);
@@ -564,6 +690,17 @@ const CHECKS = [
   ['color-syntax-punctuation', 'color-code-bg', 4.5, 'syntax: punctuation'],
   ['color-syntax-variable', 'color-code-bg', 4.5, 'syntax: variable'],
   ['color-syntax-link', 'color-code-bg', 4.5, 'syntax: link'],
+  ['color-error', 'color-bg', 4.5, 'state: error text'],
+  ['color-error', 'color-surface', 4.5, 'state: error text on surface'],
+  ['color-success', 'color-bg', 4.5, 'state: success text'],
+  ['color-success', 'color-surface', 4.5, 'state: success text on surface'],
+  ['color-warning', 'color-bg', 4.5, 'state: warning text'],
+  ['color-warning', 'color-surface', 4.5, 'state: warning text on surface'],
+  ['color-disabled', 'color-bg', 4.5, 'state: disabled text'],
+  ['color-disabled', 'color-surface', 4.5, 'state: disabled text on surface'],
+  ['color-fg', 'color-error-subtle', 4.5, 'state: fg on error-subtle banner bg'],
+  ['color-fg', 'color-success-subtle', 4.5, 'state: fg on success-subtle banner bg'],
+  ['color-fg', 'color-warning-subtle', 4.5, 'state: fg on warning-subtle banner bg'],
 ];
 function resolveRaw(raw, name, seen = new Set()) {

package/scripts/tokens-json.mjs CHANGED Viewed

@@ -22,6 +22,7 @@ function typeOf(name, value) {
   if (name.startsWith('weight-')) return 'fontWeight';
   if (name.startsWith('motion-') && /ms$/.test(value)) return 'duration';
   if (name.startsWith('leading-')) return 'number';
+  if (name.startsWith('z-')) return 'number'; // unitless stacking-order integers, not a length
   if (value === '0') return 'dimension';
   if (/(^|\s)(rem|px|em|%)/.test(value) || /^-?[\d.]+(rem|px|em)$/.test(value) || value.startsWith('clamp(')) return 'dimension';
   return 'string';

package/theme.css CHANGED Viewed

@@ -27,6 +27,14 @@
  * Pair every duration-[var(--motion-*)] utility with ease-remarque
  * (mapped below from --motion-easing) — without it Tailwind falls back
  * to its default `ease` timing function instead of the token (issue #31).
+ *
+ * Z-index utilities: Tailwind v4 ships z-* as a static, non-themable
+ * scale (there is no --z-index-* entry in its default @theme, so there
+ * is nothing here to map into). Use arbitrary values with the tokens
+ * instead — z-[var(--z-modal)], focus:z-[var(--z-skip-link)] — same
+ * pattern as the motion durations above, so every stacking layer stays
+ * traceable to tokens-core.css's --z-* scale (issue #29) instead of a
+ * bare Tailwind number.
  */
 @theme inline {

package/tokens-core.css CHANGED Viewed

@@ -80,6 +80,22 @@
   --motion-fast: 120ms;         /* hover states, focus rings */
   --motion-normal: 180ms;       /* theme transitions */
   --motion-easing: ease-out;
+  /* Z-Index Scale (issue #29) — stacking is structural, not
+     personalization: CORE tier, never overridden. A small ordinal scale,
+     sparse gaps of 10 so a future layer can be inserted between two
+     existing rungs without renumbering everything above it. Consumer CSS
+     must never author a bare z-index number — reference one of these
+     seven tokens instead (Tailwind v4 has no --z-index-* theme namespace,
+     so its z-* utilities can't reference these directly; see theme.css's
+     header comment for the arbitrary-value bridge, z-[var(--z-modal)]). */
+  --z-base: 0;
+  --z-sticky: 10;       /* essay.css's TOC rail, sticky headers/rails */
+  --z-dropdown: 20;
+  --z-overlay: 30;
+  --z-modal: 40;
+  --z-toast: 50;
+  --z-skip-link: 60;    /* tops everything — a focused skip-link must never be obscured */
 }
 /* ─── Reduced Motion ────────────────────────────────────── */

package/tokens-palette.css CHANGED Viewed

@@ -94,6 +94,29 @@
   --color-syntax-punctuation: oklch(0.52 0.01 80);    /* derived neutral, muted family — 4.69:1 */
   --color-syntax-variable:    oklch(0.26 0.01 80);    /* fg-adjacent (slight L offset) — 13.23:1 */
   --color-syntax-link:        var(--color-accent);    /* accent already clears code-bg — 4.5:1+ */
+  /* Semantic state colors (issue #26) — feedback moments (error/success/
+     warning banners, disabled controls), NOT decoration; the one-accent
+     rule still governs expressive color. Hand-authored from the house
+     ANSI hue conventions (scripts/theme.mjs derives error/success/warning
+     from a theme's red/green/yellow ANSI slots): error hue 25, success
+     hue 145, warning hue 85 — restrained chroma, keep-if-passing lightness
+     checked against the STRICTER of --color-bg/--color-surface (surface
+     is stricter in both themes here, same as --color-muted). Warning at
+     hue 85 is the hard case in light mode (low luminance-contrast yellow)
+     — solved dark, same register as --color-syntax-constant. Disabled is
+     neutral-derived (muted family), NOT ANSI — aliased to --color-muted.
+     -subtle companions (error/success/warning only, no disabled-subtle)
+     are derived like --color-accent-subtle: near-bg lightness, state hue,
+     low chroma — verified so --color-fg stays ≥4.5:1 on them, the pairing
+     that matters for callout/banner backgrounds. */
+  --color-error:          oklch(0.52 0.12  25);   /* ANSI red    — 5.44:1 bg / 5.28:1 surface */
+  --color-error-subtle:   oklch(0.95 0.02  25);   /* faint red banner background */
+  --color-success:        oklch(0.51 0.12  145);  /* ANSI green  — 5.08:1 bg / 4.93:1 surface */
+  --color-success-subtle: oklch(0.95 0.02  145);  /* faint green banner background */
+  --color-warning:        oklch(0.52 0.105 85);   /* ANSI yellow — 5.17:1 bg / 5.02:1 surface */
+  --color-warning-subtle: oklch(0.95 0.02  85);   /* faint yellow banner background */
+  --color-disabled:       var(--color-muted);     /* muted family, not ANSI-derived */
 }
 /* ─── Color: Dark theme ─────────────────────────────────── */
@@ -139,6 +162,18 @@
     --color-syntax-punctuation: oklch(0.60 0.005 80);   /* derived neutral, muted family — 4.59:1 */
     --color-syntax-variable:    oklch(0.82 0.005 80);   /* fg-adjacent (slight L offset) — 10.37:1 */
     --color-syntax-link:        var(--color-accent);    /* accent already clears code-bg */
+    /* Semantic state colors (issue #26) — see the light-theme block above
+       for the full rationale. Same hues (red 25 / green 145 / yellow 85),
+       lightened for a dark background; keep-if-passing checked against
+       the stricter of bg/surface (surface, here too). */
+    --color-error:          oklch(0.62 0.11 26);    /* 5.07:1 bg / 4.82:1 surface */
+    --color-error-subtle:   oklch(0.22 0.04 25);
+    --color-success:        oklch(0.61 0.11 145);   /* 5.36:1 bg / 5.10:1 surface */
+    --color-success-subtle: oklch(0.22 0.04 145);
+    --color-warning:        oklch(0.62 0.11 85);    /* 5.29:1 bg / 5.03:1 surface */
+    --color-warning-subtle: oklch(0.22 0.04 85);
+    --color-disabled:       var(--color-muted);
   }
 }
@@ -182,4 +217,14 @@
   --color-syntax-punctuation: oklch(0.60 0.005 80);
   --color-syntax-variable:    oklch(0.82 0.005 80);
   --color-syntax-link:        var(--color-accent);
+  /* Semantic state colors (issue #26) — see the light-theme :root block
+     for the full rationale. */
+  --color-error:          oklch(0.62 0.11 26);
+  --color-error-subtle:   oklch(0.22 0.04 25);
+  --color-success:        oklch(0.61 0.11 145);
+  --color-success-subtle: oklch(0.22 0.04 145);
+  --color-warning:        oklch(0.62 0.11 85);
+  --color-warning-subtle: oklch(0.22 0.04 85);
+  --color-disabled:       var(--color-muted);
 }

package/tokens.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.16.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.17.0). Do not edit — the CSS
  * (tokens-core.css + tokens-palette.css) is the source of truth;
  * tokens.json is the intermediate machine-readable form this file is
  * generated from. Regenerate with: node scripts/tokens-json.mjs
@@ -55,7 +55,14 @@ export type RemarqueCoreToken =
   | 'border-style'
   | 'motion-fast'
   | 'motion-normal'
-  | 'motion-easing';
+  | 'motion-easing'
+  | 'z-base'
+  | 'z-sticky'
+  | 'z-dropdown'
+  | 'z-overlay'
+  | 'z-modal'
+  | 'z-toast'
+  | 'z-skip-link';
 /** All palette-tier token names (tokens-palette.css). The sanctioned personalization surface. */
 export type RemarquePaletteToken =
@@ -90,7 +97,14 @@ export type RemarquePaletteToken =
   | 'color-syntax-type'
   | 'color-syntax-punctuation'
   | 'color-syntax-variable'
-  | 'color-syntax-link';
+  | 'color-syntax-link'
+  | 'color-error'
+  | 'color-error-subtle'
+  | 'color-success'
+  | 'color-success-subtle'
+  | 'color-warning'
+  | 'color-warning-subtle'
+  | 'color-disabled';
 /** Every Remarque token name, core + palette. */
 export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
@@ -202,6 +216,13 @@ export interface RemarqueTokenValues {
     readonly 'motion-fast': "120ms";
     readonly 'motion-normal': "180ms";
     readonly 'motion-easing': "ease-out";
+    readonly 'z-base': 0;
+    readonly 'z-sticky': 10;
+    readonly 'z-dropdown': 20;
+    readonly 'z-overlay': 30;
+    readonly 'z-modal': 40;
+    readonly 'z-toast': 50;
+    readonly 'z-skip-link': 60;
   };
   readonly palette: {
     readonly 'font-display': {
@@ -332,6 +353,34 @@ export interface RemarqueTokenValues {
       readonly light: "var(--color-accent)";
       readonly dark: "var(--color-accent)";
     };
+    readonly 'color-error': {
+      readonly light: "oklch(0.52 0.12  25)";
+      readonly dark: "oklch(0.62 0.11 26)";
+    };
+    readonly 'color-error-subtle': {
+      readonly light: "oklch(0.95 0.02  25)";
+      readonly dark: "oklch(0.22 0.04 25)";
+    };
+    readonly 'color-success': {
+      readonly light: "oklch(0.51 0.12  145)";
+      readonly dark: "oklch(0.61 0.11 145)";
+    };
+    readonly 'color-success-subtle': {
+      readonly light: "oklch(0.95 0.02  145)";
+      readonly dark: "oklch(0.22 0.04 145)";
+    };
+    readonly 'color-warning': {
+      readonly light: "oklch(0.52 0.105 85)";
+      readonly dark: "oklch(0.62 0.11 85)";
+    };
+    readonly 'color-warning-subtle': {
+      readonly light: "oklch(0.95 0.02  85)";
+      readonly dark: "oklch(0.22 0.04 85)";
+    };
+    readonly 'color-disabled': {
+      readonly light: "var(--color-muted)";
+      readonly dark: "var(--color-muted)";
+    };
   };
 }

package/tokens.json CHANGED Viewed

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.16.0",
+      "version": "0.17.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
@@ -177,6 +177,34 @@
     "motion-easing": {
       "$value": "ease-out",
       "$type": "string"
+    },
+    "z-base": {
+      "$value": 0,
+      "$type": "number"
+    },
+    "z-sticky": {
+      "$value": 10,
+      "$type": "number"
+    },
+    "z-dropdown": {
+      "$value": 20,
+      "$type": "number"
+    },
+    "z-overlay": {
+      "$value": 30,
+      "$type": "number"
+    },
+    "z-modal": {
+      "$value": 40,
+      "$type": "number"
+    },
+    "z-toast": {
+      "$value": 50,
+      "$type": "number"
+    },
+    "z-skip-link": {
+      "$value": 60,
+      "$type": "number"
     }
   },
   "palette": {
@@ -502,6 +530,69 @@
       "dark": {
         "$value": "var(--color-accent)"
       }
+    },
+    "color-error": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.52 0.12  25)"
+      },
+      "dark": {
+        "$value": "oklch(0.62 0.11 26)"
+      }
+    },
+    "color-error-subtle": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.95 0.02  25)"
+      },
+      "dark": {
+        "$value": "oklch(0.22 0.04 25)"
+      }
+    },
+    "color-success": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.51 0.12  145)"
+      },
+      "dark": {
+        "$value": "oklch(0.61 0.11 145)"
+      }
+    },
+    "color-success-subtle": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.95 0.02  145)"
+      },
+      "dark": {
+        "$value": "oklch(0.22 0.04 145)"
+      }
+    },
+    "color-warning": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.52 0.105 85)"
+      },
+      "dark": {
+        "$value": "oklch(0.62 0.11 85)"
+      }
+    },
+    "color-warning-subtle": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.95 0.02  85)"
+      },
+      "dark": {
+        "$value": "oklch(0.22 0.04 85)"
+      }
+    },
+    "color-disabled": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-muted)"
+      },
+      "dark": {
+        "$value": "var(--color-muted)"
+      }
     }
   }
 }