remarque-tokens 0.16.0 → 0.18.0

package/AGENT_RULES.md

@@ -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
 
@@ -143,6 +145,7 @@ project/
 ├── prose.css                 # .remarque-prose long-form styling (aggregated by tokens.css; own subpath for opt-out)
 ├── essay.css                 # Optional Essay module: sidenotes + sticky TOC rail (own subpath, NOT aggregated — import explicitly)
 ├── broadsheet.css            # Optional Broadsheet pattern: masthead, lead, entry list, post kicker (own subpath, NOT aggregated — import explicitly)
+├── forms.css                 # Optional form control primitives: field/input/checkbox/radio/button, state-color wiring (own subpath, NOT aggregated — import explicitly)
 ├── print.css                 # Print stylesheet (own subpath, NOT aggregated — import explicitly)
 ├── theme.css                 # Tailwind v4 adapter (@theme inline) — import after tailwindcss + tokens
 ├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects use theme.css instead
@@ -205,6 +208,7 @@ Before considering any implementation complete, verify:
 - [ ] Every page maps to an archetype (Essay, Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery)
 - [ ] If the Essay uses sidenotes/a TOC rail (`remarque-tokens/essay`): `.remarque-sidenote-ref`/`.remarque-sidenote` alternate in strict DOM order, the rail never intrudes into `.remarque-prose`'s own measure, and the page renders correctly with `essay.css`'s `@media` block deleted (the narrow-viewport/no-JS fallback)
 - [ ] If a Landing/archive page uses the Broadsheet pattern (`remarque-tokens/broadsheet`): entry numerals are generated from `data-entry-number` via `attr()` (not `counter()`), the entry list stays a `<ul>` (not `<ol>` — the numeral is `aria-hidden` and decorative), and every kicker/dateline row uses `font-variant-caps: all-small-caps`, never `text-transform: uppercase`
+- [ ] If a page uses form controls (`remarque-tokens/forms`): checkboxes/radios are styled with `accent-color` only — never `appearance: none` plus a hand-drawn replacement; every control (input, button, checkbox/radio label) is ≥44×44px; validation state lives on `.remarque-field[data-state]` AND a real `aria-invalid`/`aria-describedby` pair on the input, not `data-state` alone; disabled controls use `--color-disabled`, never a state color
 - [ ] Mobile version is roomy — not a compressed desktop layout
 - [ ] Mobile nav links have ≥44px touch targets
 - [ ] No pure white or pure black backgrounds
@@ -212,6 +216,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

@@ -4,6 +4,128 @@ 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.18.0 — 2026-07-23
+
+Form control primitives + reference components (closes #27, closes #30).
+
+### Added
+- **`forms.css` — form control primitives module (issue #27).** New own-subpath
+  module (`remarque-tokens/forms`, `remarque-tokens/forms.css`), NOT aggregated
+  into `tokens.css` — matches `essay.css`/`broadsheet.css`/`print.css`'s
+  opt-in convention. Spec-native (built directly from the issue, not
+  graduated from a downstream site — no prior flagship implementation to
+  re-express).
+  - `.remarque-field` (label + control + help/error message vertical stack),
+    `.remarque-field-label` (meta voice, same declarations as `.text-label`),
+    `.remarque-field-required`, `.remarque-field-message`.
+  - `.remarque-input` — shared class across `<input>`/`<textarea>`/`<select>`:
+    body-voice text, `--color-border-bold` boundary (functional, 3:1-checked),
+    `--radius-sm` (tighter than the general 8px ceiling — form controls stay
+    more precise-reading), ≥44px tall, `::placeholder` at `--color-muted`
+    (a conscious AA choice, documented — placeholder is supplementary hint
+    copy, never the field's only label).
+  - `.remarque-checkbox` / `.remarque-radio` — `accent-color` only, no
+    `appearance: none`, no hand-drawn replacement; native controls keep every
+    platform accessibility behavior. Sized at `--space-5` (24px), wrapped in
+    a `<label>` carrying the 44px touch target.
+  - `.remarque-button` (+ `--primary` variant) — quiet by rule: bordered,
+    transparent, body-voice text by default; `--primary` is the one
+    sanctioned accent placement per viewport, still unfilled (accent
+    text/border, hover washes in `--color-accent-subtle`, never a solid
+    fill). Disabled state (native `:disabled`) uses `--color-disabled`.
+  - Validation state wiring on the 0.17.0 state-color tokens:
+    `.remarque-field[data-state="error"|"success"|"warning"]` recolors the
+    input border and message text together; always pairs with a real
+    `aria-invalid`/`aria-describedby` on the input (`data-state` is paint
+    only). `.remarque-input:user-invalid`, guarded with
+    `@supports selector(:user-invalid)`, is a zero-JS bonus layer.
+  - `.remarque-table` / `.remarque-table-wrap` — a standalone-table
+    re-scoping of `prose.css`'s table rules (mono `th`, 2px header rule, 1px
+    row rules, `.num` tabular-lining columns) for data tables that shouldn't
+    be wrapped in the full `.remarque-prose` container. Lives in `forms.css`
+    rather than a fifth subpath — AGENT_RULES.md's build order already
+    groups tables with buttons/cards as one supplementary-UI step.
+  - REMARQUE.md "Forms" section — full markup contract, state-wiring rules,
+    restraint rules restated (radius/touch-targets/no-fake-replacements/
+    quiet-buttons/placeholder-contrast), standalone-tables note, and "when
+    NOT to use" (Remarque is editorial-first — contact/search/newsletter
+    moments, not app UIs). AGENT_RULES.md's File Structure Convention and
+    Quality Checklist gain matching entries.
+  - `scripts/audit.mjs`'s `--src .` invocation covers `forms.css` for free
+    (font-floor + no-hardcoded-color scans — no new pairings needed, this
+    module introduces no new color tokens).
+- **Reference components (demo site, issue #30)** — `site/src/components/`:
+  `Button.astro`, `Input.astro` (a `.remarque-field` wrapper — label/help/
+  error props, wires `for`/`id`/`aria-describedby`/`aria-invalid`),
+  `Table.astro` (`.remarque-table`, standalone). New demo page
+  `site/pages/components` exercises every input state (default/focus/error/
+  success/disabled), both button variants, and a sample table in both
+  themes — added to `site/tests/helpers.ts`'s `PAGES` for visual-regression
+  coverage (new baselines for this page only; no existing baseline changed)
+  and linked from the site nav.
+
+## 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

@@ -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.
 
@@ -939,6 +978,149 @@ the archive itself.
 
 ---
 
+## Forms
+
+Native form-control primitives — field wrapper, text input, checkbox,
+radio, button — shipped as their own subpath, `remarque-tokens/forms`
+(issue #27). Unlike the Essay Module and the Broadsheet pattern, this
+module was not graduated from a downstream site implementation; it is
+spec-native, built directly from the issue rather than re-expressing an
+existing literal.
+
+### Markup contract
+
+```html
+<div class="remarque-field">
+  <label class="remarque-field-label" for="email">Email</label>
+  <input class="remarque-input" type="email" id="email" name="email"
+    aria-describedby="email-help" />
+  <p class="remarque-field-message" id="email-help">
+    We'll never share your email.
+  </p>
+</div>
+
+<div class="remarque-field" data-state="error">
+  <label class="remarque-field-label" for="email2">Email</label>
+  <input class="remarque-input" type="email" id="email2" name="email2"
+    aria-invalid="true" aria-describedby="email2-message" required />
+  <p class="remarque-field-message" id="email2-message" role="alert">
+    Enter a valid email address.
+  </p>
+</div>
+
+<label class="remarque-checkbox">
+  <input type="checkbox" name="subscribe" />
+  <span>Subscribe to updates</span>
+</label>
+
+<label class="remarque-radio">
+  <input type="radio" name="plan" value="a" />
+  <span>Plan A</span>
+</label>
+
+<button class="remarque-button" type="button">Cancel</button>
+<button class="remarque-button remarque-button--primary" type="submit">Submit</button>
+```
+
+| Class | Applies to | Notes |
+|---|---|---|
+| `.remarque-field` | wrapping `<div>` | Label + control + message vertical stack. Layout only — no border/background of its own. |
+| `.remarque-field-label` | `<label>` | Meta voice (mono, small caps, `--color-muted`) — same declarations as `.text-label`, repeated per the non-mixin precedent essay.css/broadsheet.css already set. |
+| `.remarque-field-required` | `<span aria-hidden="true">` inside the label | Accent-colored asterisk. `aria-hidden` — the input's own `required` attribute is the real signal a screen reader announces. |
+| `.remarque-field-message` | `<p>` after the control | Help text by default; recolored by the parent's `data-state`. Wire `aria-describedby` on the input to this element's `id` in every case, valid or not. |
+| `.remarque-input` | `<input>` / `<textarea>` / `<select>` | Body-voice text, `--color-border-bold` boundary, `--radius-sm`, ≥44px tall. |
+| `.remarque-checkbox` / `.remarque-radio` | wrapping `<label>` | `accent-color` on the native control — no `appearance: none`, no hand-drawn replacement. The wrapping label carries the 44px touch target; the control itself stays at its natural (enlarged) size. |
+| `.remarque-button` | `<button>` | Quiet default: bordered, transparent, body-voice text. |
+| `.remarque-button--primary` | `<button>` | The one sanctioned accent placement per viewport (Visual Rules) — accent text + accent border, never a solid accent fill. Hover washes in `--color-accent-subtle`, it does not darken to a filled block. |
+
+### State wiring
+
+`data-state="error"` / `"success"` / `"warning"` on `.remarque-field`
+recolors both the input's border and the message text from the 0.17.0
+state-color tokens (`--color-error`/`--color-success`/`--color-warning`).
+`data-state` is the PAINT layer only — always pair it with the real
+accessibility signal on the input itself: `aria-invalid="true"` (screen
+readers announce this; `data-state` alone is invisible to them) and
+`aria-describedby` pointing at the `.remarque-field-message` id. A
+disabled control never gets a `data-state` — it uses the native
+`:disabled`/`disabled` state and `--color-disabled`, which is a muted
+register, not one of the three feedback hues (REMARQUE.md "State Colors":
+disabled is deliberately not ANSI-derived).
+
+As a zero-JS bonus layer, `.remarque-input:user-invalid` (guarded with
+`@supports selector(:user-invalid)`) picks up the same error border once
+a browser supports the pseudo-class and the user has actually interacted
+with an invalid field — it never replaces authoring `data-state="error"`
+explicitly, since `:user-invalid` alone has no matching text-message
+recolor and no `aria-invalid` wiring of its own.
+
+### Restraint rules restated
+
+- **Border radius**: form controls cap at `--radius-sm` (4px) — a
+  tighter ceiling than AGENT_RULES.md's general `--radius-md` (8px)
+  maximum for other chrome. A smaller, more precise-reading radius suits
+  a control the user directly manipulates.
+- **Touch targets**: every interactive control — input, textarea,
+  select, button, and the `<label>` wrapping a checkbox/radio — is
+  ≥44×44px (WCAG 2.5.5 AAA, USWDS floor; see "Touch Targets" above and
+  `.nav-link`'s identical convention in the demo site's `globals.css`).
+- **No fake replacements**: checkboxes and radios stay native elements
+  recolored with `accent-color` only. No `appearance: none` plus a
+  hand-drawn box/dot — that would trade away native keyboard behavior,
+  forced-colors-mode support, and screen-reader state announcements for
+  a purely cosmetic win this system doesn't need.
+- **Buttons stay quiet**: text-only or bordered, never filled/solid by
+  default — the primary variant included. Accent appears as text/border
+  color, never as a background fill (Visual Rules' one-accent rule and
+  Components' "never filled/solid as default" both still govern the
+  emphasized variant).
+- **Placeholder contrast**: `--color-muted` (4.5:1 on `--color-bg`/
+  `--color-surface`), a conscious choice — placeholder text is
+  supplementary hint copy, never the field's only label, so AA is the
+  correct tier rather than `--color-fg-muted`'s AAA.
+
+### Standalone tables
+
+`forms.css` also ships `.remarque-table` / `.remarque-table-wrap`
+(issue #30) — the same visual language as `.remarque-prose table`
+(mono `th` voice, 2px header rule, 1px row rules, `.num` for tabular-
+lining right-aligned numeric columns), re-scoped under a top-level
+class so a standalone data grid doesn't have to wrap itself in the full
+`.remarque-prose` container (which also applies oldstyle proportional
+numerals and prose spacing rhythm a data table doesn't want):
+
+```html
+<div class="remarque-table-wrap">
+  <table class="remarque-table">
+    <caption>Example</caption>
+    <thead>
+      <tr><th>Name</th><th class="num">Count</th></tr>
+    </thead>
+    <tbody>
+      <tr><td>Rows</td><td class="num">42</td></tr>
+    </tbody>
+  </table>
+</div>
+```
+
+Lives in `forms.css` rather than its own subpath — AGENT_RULES.md's
+build order already groups tables with buttons/cards/code blocks as one
+"supplementary UI" step, and this table variant is a small re-scoping,
+not enough surface area to justify a fourth optional module.
+
+### When NOT to use
+
+Remarque is editorial-first. This module exists for the handful of
+form moments a written-word site actually needs — a contact form, a
+site search box, a newsletter signup — not for building application
+UIs. If a page needs more than a few fields, conditional multi-step
+logic, inline data tables of editable rows, or anything that starts to
+resemble a settings/dashboard screen, that is out of scope for
+Remarque's forms primitives; reach for a dedicated UI/form library
+instead and keep Remarque to the page's editorial chrome around it.
+
+---
+
 ## Signature Moves
 
 These are the repeatable visual tells that make a Remarque site recognizable:

package/essay.css

@@ -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));