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

remarque-tokens 0.17.0 → 0.19.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 (10) hide show

package/AGENT_RULES.md +4 -0
package/CHANGELOG.md +119 -0
package/REMARQUE.md +270 -0
package/deck.js +70 -0
package/forms.css +424 -0
package/package.json +8 -2
package/scripts/lib/css-tokens.mjs +11 -2
package/scripts/theme.mjs +38 -7
package/tokens.d.ts +1 -1
package/tokens.json +1 -1

package/AGENT_RULES.md CHANGED Viewed

@@ -145,6 +145,8 @@ 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)
+├── deck.js                   # Optional Palette Deck module: switch/persist/restore between remarque-theme-generated palettes (own subpath, NOT aggregated — dependency-free ESM, no CSS of its own)
 ├── 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
@@ -207,6 +209,8 @@ 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
+- [ ] If a page uses the Palette Deck (`remarque-tokens/deck`): `data-palette` is set/cleared on the same root element as `data-theme` (they compose, never conflict); the FOUC-safe restore is a synchronous classic `<script>` physically in `<head>` (never `type="module"`, which defers); the switcher control itself is a native, keyboard-operable element (e.g. `.remarque-input` `<select>`) at ≥44×44px, not a hand-rolled widget; every registered palette was generated via `remarque-theme --scope`, never hand-authored
 - [ ] Mobile version is roomy — not a compressed desktop layout
 - [ ] Mobile nav links have ≥44px touch targets
 - [ ] No pure white or pure black backgrounds

package/CHANGELOG.md CHANGED Viewed

@@ -4,6 +4,125 @@ 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.19.0 — 2026-07-23
+Palette Deck module (closes #56).
+### Added
+- **`deck.js` — palette-deck module (issue #56, re-scoped by 2026-07-23
+  consensus panel).** New own-subpath export (`remarque-tokens/deck`,
+  `remarque-tokens/deck.js`) — a dependency-free ~60-line ESM file, NOT
+  aggregated into `tokens.css` (it ships no CSS at all). Deliberately
+  THIN: the original theme-deck graduation proposal (12 terminal
+  palettes as `:root[data-theme-deck]` overrides) predates
+  `remarque-theme`; the panel re-scoped it to cover only what that
+  pipeline doesn't already provide — switching, persisting, and
+  FOUC-safely restoring a choice among already-generated palettes.
+  Generation, contrast solving, and hue/pairing remain entirely
+  `remarque-theme`'s job.
+  - `createDeck(names, opts?)` — registers a set of palette names,
+    returns `{ names, current, apply, restore }`. `apply(name)` sets/
+    clears `data-palette` on the root element and persists the choice to
+    `localStorage` (default key `remarque-palette`); `apply(null)`
+    reverts to the unscoped default. `restore()` re-applies a persisted
+    choice without re-persisting it (for the post-paint sync step — the
+    actual FOUC guard is a duplicated inline snippet, documented in
+    REMARQUE.md, matching how the light/dark theme toggle's own `<head>`
+    script already works). Unknown names throw rather than setting an
+    unvalidated attribute value.
+- **`--scope <name>` on `remarque-theme`.** Emits the derived palette
+  under `[data-palette="<name>"]` / `[data-palette="<name>"][data-theme="dark"]`
+  instead of `:root` / `[data-theme="dark"]`, so several generated
+  palettes can coexist in one stylesheet. `<name>` is validated with the
+  same slug grammar as `<light-slug>`/`--dark` before it is interpolated
+  into the attribute selector (security review precedent from #75/#76 —
+  it is the only control here, since a scope name has no upstream index
+  to check against). Derivation and self-verification are unaffected by
+  scoping — a scoped and unscoped run of the same pair emit
+  byte-identical declarations, differing only in the wrapping selector
+  (fixture-tested).
+- **`remarque-audit` recognizes scoped palettes directly.**
+  `scripts/lib/css-tokens.mjs`'s `isLightRoot` now treats a bare
+  `[data-palette="name"]` block as that scope's light root (one more
+  exact-match case, symmetric with the existing `[data-theme="light"]`
+  special case) — `isDarkBlock` needed no change, since
+  `[data-palette="name"][data-theme="dark"]` already matched its
+  existing rule. A `--scope`'d file is auditable exactly like any other
+  palette file; no "audit the unscoped version first" workaround is
+  needed. See REMARQUE.md "Palette Deck" for the full audit story and
+  why this was the smaller correct fix over a bespoke attribute-selector
+  grammar.
+- **Demo (`site/`):** a Palette Deck section on `/tokens` with a native
+  `<select class="remarque-input">` switcher (gruvbox / rosé-pine,
+  pinned slugs `gruvbox-light`/`gruvbox-dark` and
+  `rose-pine-dawn`/`rose-pine`), generated at build time by
+  `site/scripts/build-palette-deck.mjs` into `public/palettes/*.css`
+  (gitignored, regenerated every build — same pattern as
+  `public/tokens.json`). FOUC-safe restore snippet added to
+  `BaseLayout.astro`'s `<head>`, alongside the existing theme-toggle
+  script. VR baselines: `tokens.astro` only (new section on that page);
+  every other page is untouched by this release.
+## 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).

package/REMARQUE.md CHANGED Viewed

@@ -978,6 +978,276 @@ 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.
+---
+## Palette Deck
+A tiny runtime (`remarque-tokens/deck`, `deck.js`) for switching between
+several `remarque-theme`-generated palettes on one site — register a set
+of palette names, switch the active one, persist the choice, restore it
+before first paint. Issue #56.
+**What this module deliberately does NOT do.** The flagship site's
+`theme-deck.css` (12 terminal palettes as `:root[data-theme-deck=…]`
+overrides) was originally proposed for upstreaming as-is. A 2026-07-23
+consensus panel (3-0) re-scoped it: generation, contrast solving, and
+hue/pairing all now come from `remarque-theme` (`scripts/theme.mjs`,
+"Color Providers" above) — that pipeline makes deriving a new palette
+nearly free, so graduating a second, parallel generator would just
+duplicate it. What's left — and what this module is *only* — is the part
+`remarque-theme` doesn't provide: switching between already-generated
+palettes at runtime. No color math, no contrast solving, no palette
+authoring lives in `deck.js`; it is a dependency-free ~60-line ESM file
+that sets an attribute, reads/writes `localStorage`, and hands back
+enough to build a FOUC-safe restore. If you need to *generate* a palette,
+see "Color Providers"; this section is exclusively about *switching*
+between ones you already have.
+### The mechanism: `--scope`
+`remarque-theme` gained a `--scope <name>` flag for this module. Without
+it, output owns `:root` / `[data-theme="dark"]` outright — the normal,
+single-palette case. With `--scope <name>`, the same derivation emits
+under `[data-palette="<name>"]` / `[data-palette="<name>"][data-theme="dark"]`
+instead, so several generated palettes can coexist in one stylesheet
+(or several stylesheets) without fighting over `:root`:
+```
+npx remarque-theme gruvbox-light --dark gruvbox-dark --scope gruvbox -o palettes/gruvbox.css
+npx remarque-theme rose-pine-dawn --dark rose-pine --scope rose-pine -o palettes/rose-pine.css
+```
+`--scope`'s value is interpolated into a CSS attribute selector, so it is
+validated with the exact same slug grammar as `<light-slug>`/`--dark`
+(lowercase alphanumeric segments joined by single hyphens) before it
+touches any output — a scope name is a caller-supplied label with no
+upstream index to check it against, which is exactly why the regex
+carries the full weight here rather than acting as defense-in-depth for
+a separate lookup. Derivation, self-verification, and every contrast/
+gamut guarantee in "Color Providers" are **completely unaffected by
+scoping** — `theme.mjs` self-verifies the derived `[L, C, H]` values
+before it ever chooses a selector to emit them under, so a scoped and
+unscoped run of the same light/dark pair produce byte-identical
+declarations, differing only in which selector wraps them (fixture-
+tested in `scripts/test-theme.mjs`).
+### The audit story for scoped palettes
+`remarque-audit`'s selector classification (`scripts/lib/css-tokens.mjs`,
+`isLightRoot`/`isDarkBlock`) recognizes `[data-palette="name"]` directly:
+a bare `[data-palette="name"]` block counts as that scope's light root
+(the same kind of exact-match special case the file already carries for
+`[data-theme="light"]`), and `[data-palette="name"][data-theme="dark"]`
+was already recognized as dark by the existing rule (it contains the
+`[data-theme="dark"]` substring and starts with `[`) — no change needed
+there. This was the smaller correct fix, not a bespoke new
+attribute-selector grammar: one exact-match regex, symmetric with a
+pattern the file already used, rather than teaching the parser to
+understand arbitrary compound attribute selectors. The result: a
+`--scope`'d file is auditable exactly like any other palette file —
+`npx remarque-audit --palette palettes/gruvbox.css --src <dir>` — no
+"generate the unscoped version first" workaround required.
+### Markup/wiring contract
+Set (or clear) `data-palette` on `<html>`, alongside the existing
+`data-theme` attribute — the two compose independently. A deck palette
+carries *both* light and dark halves, so the light/dark toggle keeps
+working no matter which palette (or none) is active:
+```html
+<html data-theme="dark" data-palette="gruvbox">
+```
+```js
+import { createDeck } from 'remarque-tokens/deck';
+const deck = createDeck(['gruvbox', 'rose-pine']); // registered names
+deck.restore();                 // re-apply a persisted choice, if any
+deck.apply('rose-pine');        // switch + persist
+deck.apply(null);                // back to the unscoped default palette
+deck.current();                  // 'rose-pine' | null
+```
+`createDeck` validates every `apply()` call against the registered name
+list and throws on an unknown one — the deck never sets an attribute
+value it wasn't told about. Persistence (`localStorage`, default key
+`remarque-palette`) degrades to in-memory-only if storage is unavailable
+(private browsing, SSR) rather than throwing.
+**FOUC-safe restore.** Exactly like the light/dark theme toggle's own
+`<head>` script (see the demo's `BaseLayout.astro`), the deck's restore
+must run as a synchronous, render-blocking **classic** inline script
+physically in `<head>` — an ESM `<script type="module">` is deferred by
+the HTML spec and would let the default palette flash before the stored
+one applies. So the head snippet duplicates the ~3-line read-and-apply
+logic directly rather than importing `deck.js` (the same reason the
+theme toggle's head script doesn't import anything either):
+```html
+<script is:inline>
+  (function() {
+    var p = localStorage.getItem('remarque-palette');
+    if (p) document.documentElement.setAttribute('data-palette', p);
+  })();
+</script>
+```
+`deck.js` itself is loaded later (deferred/module, after first paint) to
+wire the switcher UI's change handler and to keep `restore()` available
+for pages that need to re-derive `current()` after the fact.
+### Provenance
+Re-scoped from the flagship site's theme-deck on the way up (issue #56,
+consensus panel, 2026-07-23) — see the root README's "Graduation"
+section. The original proposal predated `remarque-theme`; once that
+pipeline existed, generating N palettes stopped being the hard part and
+switching between them became the only piece worth a shared module.
+---
 ## Signature Moves
 These are the repeatable visual tells that make a Remarque site recognizable:

package/deck.js ADDED Viewed

@@ -0,0 +1,70 @@
+/*
+ * Remarque — Palette Deck (runtime switching between remarque-theme
+ * generated palettes)
+ * ───────────────────────────────────────────────────────────────────
+ * PROVENANCE — re-scoped, not graduated as-is. The flagship site's
+ * theme-deck (12 terminal palettes, `[data-theme-deck]`) was proposed for
+ * upstreaming whole in issue #56; a 2026-07-23 consensus panel (3-0)
+ * re-scoped it: generation, contrast solving, and pairing all now come
+ * from `remarque-theme` (`scripts/theme.mjs`, "Color Providers"), so this
+ * module is deliberately THIN — it does none of that. All it does:
+ *
+ *   1. register the set of valid palette names,
+ *   2. switch the active one (`data-palette` on the root element),
+ *   3. persist the choice (localStorage), and
+ *   4. hand back enough to build a FOUC-safe restore (see REMARQUE.md
+ *      "Palette Deck" for the inline <head> snippet — that snippet does
+ *      NOT import this module; it duplicates the ~3 lines of restore
+ *      logic directly, the same way the light/dark theme toggle's own
+ *      head script duplicates rather than imports, because a FOUC guard
+ *      must be a synchronous classic script and this file is an ESM
+ *      module).
+ *
+ * No framework, no build step, no CSS authored here — `--scope`'d palette
+ * files (npx remarque-theme <slug> --scope <name>) are the caller's job.
+ */
+const ATTR = 'data-palette';
+const DEFAULT_STORAGE_KEY = 'remarque-palette';
+/**
+ * @param {(string | { name: string })[]} palettes registered palette names
+ *   (or `{ name }` objects, for callers that also carry a label/slug pair)
+ * @param {{ root?: HTMLElement, storageKey?: string }} [opts]
+ */
+export function createDeck(palettes, opts = {}) {
+  const root = opts.root || document.documentElement;
+  const storageKey = opts.storageKey || DEFAULT_STORAGE_KEY;
+  const names = palettes.map((p) => (typeof p === 'string' ? p : p.name));
+  function isValid(name) {
+    return name == null || names.includes(name);
+  }
+  function current() {
+    return root.getAttribute(ATTR);
+  }
+  /** Switch palettes. `name === null` reverts to the unscoped default. */
+  function apply(name, { persist = true } = {}) {
+    if (!isValid(name)) throw new Error(`remarque palette-deck: unknown palette "${name}" (registered: ${names.join(', ') || '(none)'})`);
+    if (name) root.setAttribute(ATTR, name);
+    else root.removeAttribute(ATTR);
+    if (persist) {
+      try {
+        if (name) localStorage.setItem(storageKey, name);
+        else localStorage.removeItem(storageKey);
+      } catch { /* storage unavailable (private mode) — in-memory only for this load */ }
+    }
+  }
+  /** Re-apply a previously persisted choice (no-op if none / unknown). */
+  function restore() {
+    let stored = null;
+    try { stored = localStorage.getItem(storageKey); } catch { /* ignore */ }
+    if (stored && isValid(stored)) apply(stored, { persist: false });
+    return current();
+  }
+  return { names, current, apply, restore };
+}

package/forms.css ADDED Viewed

@@ -0,0 +1,424 @@
+/*
+ * Remarque — Form Control Primitives (issue #27)
+ * ────────────────────────────────────────────────
+ * Namespaced classes that style native form elements — no fake replacement
+ * widgets. A `<select>` is a `<select>`, a checkbox stays a checkbox with
+ * `accent-color` doing the recoloring work a browser already supports
+ * natively. This module exists because Remarque is editorial-first: forms
+ * are for the contact/search/newsletter moments a written-word site
+ * occasionally needs, not a component library for building app UIs. See
+ * "When NOT to use" in REMARQUE.md's "Forms" section before reaching for
+ * this on a page that wants more than a handful of fields. Also carries a
+ * small standalone-table section (`.remarque-table`) at the end of this
+ * file — see that section's header comment for why it lives here rather
+ * than in prose.css (issue #30's reference `Table.astro` needs the same
+ * table visual language OUTSIDE `.remarque-prose`).
+ *
+ * PROVENANCE — spec-native, not graduated from a downstream site (unlike
+ * essay.css/broadsheet.css). Built directly from issue #27; there was no
+ * prior flagship implementation to re-express in token vocabulary, so
+ * every value below is original to this module rather than a mapped-over
+ * site literal.
+ *
+ * Own subpath (remarque-tokens/forms, remarque-tokens/forms.css) — NOT
+ * included by the tokens.css aggregator, matching essay.css/broadsheet.css/
+ * print.css: most Remarque pages have zero forms. Import explicitly, after
+ * prose.css if both are in use:
+ *   @import 'remarque-tokens/prose.css';
+ *   @import 'remarque-tokens/forms.css';
+ * (string form — see AGENT_RULES.md Pitfall #6.)
+ *
+ * ─── MARKUP CONTRACT (summary — full version in REMARQUE.md) ──────────
+ *
+ *   <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>
+ *
+ * `data-state` lives on `.remarque-field` (not the input) — it recolors
+ * both the control's border AND the message text together from one
+ * attribute, the same "one attribute drives several descendants" shape
+ * essay.css's counter-driven numbering uses. `aria-invalid="true"` is the
+ * REAL accessibility signal (screen readers announce it); `data-state` is
+ * the visual layer on top. Author both together — see "State wiring"
+ * below for what happens if a consumer only sets one.
+ */
+/* ─── Field wrapper: label + control + help/error text stack ────────────
+ * A vertical rhythm of three parts. `--space-2` between label and control
+ * (tight — they read as one unit), `--space-2` again before the message
+ * line. No border, no background on the wrapper itself — `.remarque-field`
+ * is layout only, never a bordered "card" around the control (Components:
+ * "no component should be visually louder than the content it contains").
+ */
+.remarque-field {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-2);
+  max-width: var(--content-reading);
+}
+.remarque-field + .remarque-field {
+  margin-top: var(--space-5);
+}
+/* Label voice: same declarations as `.text-label` (tokens-core.css),
+   repeated rather than depended-on-as-a-mixin — the same non-mixin
+   precedent essay.css's TOC summary and broadsheet.css's kicker rows
+   establish. True small caps (`font-variant-caps`), never `text-transform:
+   uppercase` (REMARQUE.md "Small Caps"). Quiet mono metadata voice for the
+   label, not the body face — a form label identifies the field, the VALUE
+   typed into it is the content, and that distinction is the same one
+   `.text-label` already draws for dates/tags/status elsewhere. */
+.remarque-field-label {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: var(--leading-meta);
+  font-variant-caps: all-small-caps;
+  letter-spacing: var(--tracking-caps);
+  color: var(--color-muted);
+}
+/* Required-field marker: a plain asterisk in the accent color is the one
+   sanctioned use here (it is unambiguously "this is the interactive thing
+   that needs attention right now" — not decoration). Author it inside the
+   label: <label>Email <span class="remarque-field-required"
+   aria-hidden="true">*</span></label> — aria-hidden because `required` on
+   the input itself is the real signal a screen reader announces. */
+.remarque-field-required {
+  color: var(--color-accent);
+}
+/* Help/error/success message line — meta voice, body-face-adjacent size
+   floor (--text-meta, 14px, clears the USWDS small-text minimum). Neutral
+   (muted) by default; recolored by `.remarque-field[data-state]` below.
+   `text-wrap: pretty` matches `.remarque-prose`'s optical default for
+   short justified-feeling message copy. */
+.remarque-field-message {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: var(--leading-meta);
+  letter-spacing: var(--tracking-meta);
+  color: var(--color-muted);
+  margin: 0;
+  text-wrap: pretty;
+}
+/* ─── Text inputs: input / textarea / select ─────────────────────────────
+ * One shared class across all three native elements — same border,
+ * radius, spacing, and body-voice typography (Font Slots: "Body ... UI
+ * labels, navigation, buttons" — form values are UI labels' closest
+ * relative here, not metadata). `--color-border-bold`, not `-bold`'s
+ * quieter sibling: an input's boundary is a FUNCTIONAL edge (WCAG 1.4.11
+ * non-text contrast), the same reasoning `.remarque-sidenote`'s narrow-
+ * viewport border and `.remarque-toc-rail`'s hairline both already apply
+ * decoratively-vs-functionally in essay.css.
+ */
+.remarque-input {
+  display: block;
+  width: 100%;
+  min-height: 44px; /* USWDS/WCAG 2.5.5 touch-target floor — see AGENT_RULES.md */
+  padding: var(--space-2) var(--space-3);
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  line-height: var(--leading-title);
+  color: var(--color-fg);
+  background-color: var(--color-bg);
+  border: var(--border-width) var(--border-style) var(--color-border-bold);
+  /* Restraint rule (AGENT_RULES.md "Border radius never exceeds
+     --radius-md" + this module's own tighter floor): form controls stay
+     at --radius-sm, never the 8px ceiling other chrome is allowed. A
+     smaller control reads as more precise at a smaller radius. */
+  border-radius: var(--radius-sm);
+  transition: border-color var(--motion-fast) var(--motion-easing);
+}
+textarea.remarque-input {
+  min-height: 6rem; /* several lines tall by default — still clears the 44px floor */
+  resize: vertical;
+}
+/* Native select's disclosure triangle is left as the platform default —
+   restyling it means either `appearance: none` (which then requires a
+   hand-drawn replacement icon, exactly the "fake replacement" this module
+   avoids) or accepting a single browser's rendering as the reference,
+   neither of which is worth it for one triangle. */
+.remarque-input:hover {
+  border-color: var(--color-fg-muted);
+}
+/* Placeholder: --color-muted, the same 4.5:1-on-bg/-surface token used
+   everywhere else at this contrast tier — a conscious choice, not the
+   browser default (which is often far below AA). Placeholder text is
+   supplementary (never the only label — every `.remarque-input` pairs
+   with a real `<label>`), so 4.5:1 rather than `--color-fg-muted`'s 7:1
+   is the correct tier: AA is sufficient for non-essential hint copy. */
+.remarque-input::placeholder {
+  color: var(--color-muted);
+  opacity: 1; /* Firefox lowers placeholder opacity by default; pin it so the token value is what actually renders */
+}
+.remarque-input:disabled {
+  color: var(--color-disabled);
+  background-color: var(--color-bg-subtle);
+  border-color: var(--color-border);
+  cursor: not-allowed;
+}
+/* ─── Checkbox / Radio — accent-color, no fake replacements ──────────────
+ * `accent-color` is the ENTIRE recoloring mechanism: no `appearance:
+ * none`, no hand-drawn checkmark/dot, no absolutely-positioned pseudo-
+ * element standing in for the native control. This is a deliberate
+ * ceiling on customization, not an oversight — every browser Remarque
+ * targets supports `accent-color` on checkboxes/radios, and a real native
+ * control keeps every platform accessibility behavior (keyboard,
+ * high-contrast mode, forced-colors mode, screen-reader state
+ * announcements) for free, at the cost of not controlling the checkmark
+ * glyph's exact shape.
+ *
+ * Sizing: --space-5 (1.5rem / 24px) — comfortably inside the 44px touch
+ * target once the wrapping <label> below adds its own min-height, and
+ * large enough to keep the accent-colored fill legible (a 16px default
+ * checkbox reads as fussy at this system's generous spacing scale).
+ */
+.remarque-checkbox,
+.remarque-radio {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--space-2);
+  min-height: 44px; /* touch-target floor on the whole label, same shape as .nav-link */
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  line-height: var(--leading-title);
+  color: var(--color-fg);
+  cursor: pointer;
+}
+.remarque-checkbox input,
+.remarque-radio input {
+  accent-color: var(--color-accent);
+  width: var(--space-5);
+  height: var(--space-5);
+  margin: 0;
+  flex-shrink: 0;
+}
+/* `:has()` is a light progressive enhancement here, not a functional
+   dependency — a browser without it still gets a fully working, natively
+   disabled control; it just skips the muted label-text recolor. */
+.remarque-checkbox:has(input:disabled),
+.remarque-radio:has(input:disabled) {
+  color: var(--color-disabled);
+  cursor: not-allowed;
+}
+.remarque-checkbox input:disabled,
+.remarque-radio input:disabled {
+  cursor: not-allowed;
+}
+/* ─── Buttons ─────────────────────────────────────────────────────────────
+ * Quiet by rule (AGENT_RULES.md Components: "Buttons are quiet: text-only
+ * or subtle bordered. Never filled/solid as default."). The default
+ * variant is bordered, transparent background, body-voice text — reads as
+ * "a clickable label," not a colored block. `--primary` is the ONE
+ * sanctioned accent placement per viewport (Visual Rules: accent for
+ * "inline links and one interactive element per viewport") — even there,
+ * it stays unfilled: accent text + accent border, never a solid accent
+ * fill, so the same restraint the default variant holds carries through
+ * to the emphasized one. Hover on `--primary` washes in
+ * `--color-accent-subtle` (the same quiet-highlight token
+ * `.remarque-prose mark` already uses) rather than darkening to a filled
+ * block — a wash, not a fill.
+ */
+.remarque-button {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-2);
+  min-height: 44px;
+  padding: var(--space-2) var(--space-4);
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  font-weight: var(--weight-medium);
+  line-height: var(--leading-title);
+  color: var(--color-fg);
+  background-color: transparent;
+  border: var(--border-width) var(--border-style) var(--color-border-bold);
+  border-radius: var(--radius-sm);
+  cursor: pointer;
+  transition:
+    color var(--motion-fast) var(--motion-easing),
+    border-color var(--motion-fast) var(--motion-easing),
+    background-color var(--motion-fast) var(--motion-easing);
+}
+.remarque-button:hover:not(:disabled) {
+  border-color: var(--color-fg-muted);
+  color: var(--color-fg);
+}
+.remarque-button--primary {
+  color: var(--color-accent);
+  border-color: var(--color-accent);
+}
+.remarque-button--primary:hover:not(:disabled) {
+  color: var(--color-accent-hover);
+  border-color: var(--color-accent-hover);
+  background-color: var(--color-accent-subtle);
+}
+.remarque-button:disabled {
+  color: var(--color-disabled);
+  border-color: var(--color-border);
+  background-color: transparent;
+  cursor: not-allowed;
+}
+/* ─── Validation state wiring (0.17.0 state-color tokens) ────────────────
+ * `data-state` lives on `.remarque-field`, cascading down to the input's
+ * border and the message line's color together — author it alongside a
+ * real `aria-invalid="true"`/`aria-describedby` pair on the input (the
+ * markup contract above); `data-state` alone changes only the paint,
+ * `aria-invalid` is what a screen reader actually announces. `--warning`
+ * covers a caution/needs-attention message that isn't yet a hard failure
+ * (REMARQUE.md "State Colors" — "states needing attention before
+ * proceeding"), e.g. a password-strength hint. No `-subtle` background is
+ * used here: `-subtle` is sized for banner/callout backgrounds (REMARQUE.md
+ * "State Colors"), and painting a per-field background would make the
+ * field louder than the content it holds (Components rule) — border +
+ * message-text color is enough signal at this scale.
+ */
+.remarque-field[data-state="error"] .remarque-input,
+.remarque-input[aria-invalid="true"] {
+  border-color: var(--color-error);
+}
+.remarque-field[data-state="error"] .remarque-field-message {
+  color: var(--color-error);
+}
+.remarque-field[data-state="success"] .remarque-input {
+  border-color: var(--color-success);
+}
+.remarque-field[data-state="success"] .remarque-field-message {
+  color: var(--color-success);
+}
+.remarque-field[data-state="warning"] .remarque-input {
+  border-color: var(--color-warning);
+}
+.remarque-field[data-state="warning"] .remarque-field-message {
+  color: var(--color-warning);
+}
+/* `:user-invalid` — native, zero-JS validity feedback (matches only after
+   the user has interacted with the field and left it invalid, unlike
+   `:invalid`, which can match a required-but-untouched field on page
+   load). Guarded with `@supports selector(...)`: a browser lacking the
+   pseudo-class simply never matches this block and falls back to
+   whatever `data-state`/`aria-invalid` already provide — the same
+   "degrades to the no-JS/no-support baseline" shape essay.css's `@media`
+   gate uses for its own progressive enhancement. This is a bonus layer,
+   not a replacement for authoring `data-state="error"` explicitly. */
+@supports selector(:user-invalid) {
+  .remarque-input:user-invalid {
+    border-color: var(--color-error);
+  }
+}
+/* ─── Standalone data tables (issue #30) ──────────────────────────────────
+ * `.remarque-table` re-scopes prose.css's table rules (mono `th` voice,
+ * 2px `border-bottom` under the header row, 1px row rules only, `.num`
+ * for tabular-lining right-aligned numeric columns) under a top-level
+ * class instead of `.remarque-prose table`. This is intentionally a
+ * near-verbatim copy of those declarations, not a shared mixin (CSS has
+ * none) and not a requirement to wrap a standalone data table in the full
+ * `.remarque-prose` container — `.remarque-prose` also applies oldstyle
+ * proportional numerals, `> * + *` paragraph-spacing rhythm, and prose
+ * max-width, none of which a reference data grid (e.g. `Table.astro`)
+ * wants. Living in forms.css rather than a new subpath: this module is
+ * already "the supplementary-UI module" in AGENT_RULES.md's build order
+ * (step 7 groups buttons, tags, cards, code blocks, AND tables together),
+ * and a table this small does not justify its own subpath the way the
+ * Essay/Broadsheet modules' much larger surface area did.
+ *
+ * Wrap a wide table exactly like prose.css's convention:
+ *   <div class="remarque-table-wrap"><table class="remarque-table">...</table></div>
+ */
+.remarque-table-wrap {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+.remarque-table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: var(--text-body);
+}
+.remarque-table caption {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  color: var(--color-muted);
+  text-align: left;
+  caption-side: top;
+  margin-bottom: var(--space-2);
+}
+.remarque-table th {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  letter-spacing: var(--tracking-meta);
+  font-weight: var(--weight-semibold);
+  text-align: left;
+  padding: var(--space-2) var(--space-3);
+  border-bottom: 2px solid var(--color-border-bold);
+  color: var(--color-fg);
+}
+.remarque-table td {
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  padding: var(--space-2) var(--space-3);
+  border-bottom: var(--border-width) var(--border-style) var(--color-border);
+  color: var(--color-fg);
+}
+.remarque-table th.num,
+.remarque-table td.num {
+  font-variant-numeric: tabular-nums lining-nums;
+  text-align: right;
+}

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.17.0",
+  "version": "0.19.0",
   "engines": {
     "node": ">=18"
   },
@@ -32,7 +32,7 @@
     "drift": "node scripts/drift-check.mjs"
   },
   "devDependencies": {
-    "@williamzujkowski/oklch-terminal-themes": "0.3.0",
+    "@williamzujkowski/oklch-terminal-themes": "0.4.0",
     "culori": "^4.0.2"
   },
   "peerDependencies": {
@@ -72,6 +72,10 @@
     "./essay.css": "./essay.css",
     "./broadsheet": "./broadsheet.css",
     "./broadsheet.css": "./broadsheet.css",
+    "./forms": "./forms.css",
+    "./forms.css": "./forms.css",
+    "./deck": "./deck.js",
+    "./deck.js": "./deck.js",
     "./agent-rules": "./AGENT_RULES.md",
     "./spec": "./REMARQUE.md",
     "./package.json": "./package.json"
@@ -98,6 +102,8 @@
     "print.css",
     "essay.css",
     "broadsheet.css",
+    "forms.css",
+    "deck.js",
     "scripts/lib/css-tokens.mjs"
   ]
 }

package/scripts/lib/css-tokens.mjs CHANGED Viewed

@@ -54,12 +54,21 @@ const parts = (prelude) => prelude.split(',').map((s) => s.trim());
 const DARKISH = /(\.dark\b|\[data-theme="dark"\])/;
 const ROOTISH = /^(:root|html|body)\b/;
+// A bare palette-deck scope selector (remarque-tokens/deck, issue #56) — no
+// [data-theme] of its own, so it plays the same "light root" role for that
+// scope that :root plays sitewide. Exact-match, same shape as the existing
+// `[data-theme="light"]` special case immediately below — not a general
+// attribute-selector grammar, just one more enumerated light-ish selector.
+const PALETTE_SCOPE_LIGHT = /^\[data-palette="[a-z0-9-]+"\]$/;
 export const isLightRoot = (b) =>
   b.context === '' && parts(b.prelude).some((s) =>
-    (ROOTISH.test(s) && !DARKISH.test(s)) || s === '[data-theme="light"]');
+    (ROOTISH.test(s) && !DARKISH.test(s)) || s === '[data-theme="light"]' || PALETTE_SCOPE_LIGHT.test(s));
 /* Dark: media-query :root, the canonical [data-theme="dark"], or the
-   class-convention :root.dark / html.dark (compatibility bridge). */
+   class-convention :root.dark / html.dark (compatibility bridge). A scoped
+   deck palette's dark block ([data-palette="name"][data-theme="dark"])
+   already matches unchanged: DARKISH finds the [data-theme="dark"]
+   substring, and the selector starts with "[". */
 export const isDarkBlock = (b) =>
   (b.context.includes('prefers-color-scheme') && b.context.includes('dark') &&
     parts(b.prelude).some((s) => ROOTISH.test(s) && !DARKISH.test(s))) ||

package/scripts/theme.mjs CHANGED Viewed

@@ -50,13 +50,22 @@ try {
   OWN_VERSION = JSON.parse(readFileSync(join(HERE, '..', 'package.json'), 'utf8')).version;
 } catch { /* provenance is best-effort */ }
-const USAGE = `usage: remarque-theme <light-slug> [--dark <dark-slug>] [-o out.css]
+const USAGE = `usage: remarque-theme <light-slug> [--dark <dark-slug>] [-o out.css] [--scope <name>]
   <light-slug>     slug of a theme with isDark=false in ${PKG_SPEC}
   --dark <slug>    slug of a theme with isDark=true; defaults to the light
                     theme's "counterpart" from the dataset (0.2.0+) when it
                     has one, and is required when it doesn't
-  -o, --output     write the derived palette here instead of stdout`;
+  -o, --output     write the derived palette here instead of stdout
+  --scope <name>   emit under [data-palette="<name>"] instead of :root — for
+                    the palette-deck module (remarque-tokens/deck), where
+                    several generated palettes coexist in one stylesheet and
+                    are switched at runtime. <name> is validated with the
+                    same slug grammar as a theme slug (lowercase
+                    alphanumeric + hyphen) — it is interpolated into a CSS
+                    attribute selector, so it goes through the same
+                    byte-for-byte validation as light-slug/dark-slug above,
+                    not just a shape check (see "Security" above)`;
 function die(msg) {
   console.error(msg);
@@ -66,18 +75,33 @@ function die(msg) {
 /* ── CLI args ─────────────────────────────────────────────────────── */
 const argv = process.argv.slice(2);
-let darkSlug, outFile;
+let darkSlug, outFile, scopeName;
 const positional = [];
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === '--dark') darkSlug = argv[++i];
   else if (a === '-o' || a === '--output') outFile = argv[++i];
+  else if (a === '--scope') scopeName = argv[++i];
   else if (a === '-h' || a === '--help') { console.log(USAGE); process.exit(0); }
   else positional.push(a);
 }
 const lightSlug = positional[0];
 if (!lightSlug) die(USAGE);
+/* --scope is interpolated into a CSS attribute selector
+ * ([data-palette="<name>"]) — validated against the SAME slug grammar as
+ * light-slug/dark-slug below (SLUG_RE), not a looser check. Unlike those
+ * two, there's no upstream index to match it against (a scope name is the
+ * caller's own label, not a theme lookup key), so the regex IS the whole
+ * control here — which is exactly why it stays as strict as the lookup
+ * keys' defense-in-depth regex: lowercase alphanumeric + hyphen only,
+ * nothing that could break out of the quoted attribute value or inject
+ * additional CSS. */
+const SCOPE_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+if (scopeName !== undefined && !SCOPE_RE.test(scopeName)) {
+  die(`--scope "${scopeName}" is invalid — must be lowercase alphanumeric segments joined by single hyphens (e.g. "gruvbox", "rose-pine")`);
+}
 /* ── Resolve @williamzujkowski/oklch-terminal-themes ─────────────────
  * Tried from the consumer's cwd first (a project that installs the
  * themes package at its own top level), then from this script's own
@@ -734,9 +758,16 @@ selfVerify('dark', dark.raw);
 const decls = (tokens, indent = '  ') => Object.entries(tokens).map(([k, v]) => `${indent}--${k}: ${v};`).join('\n');
+const regenCmd = `npx remarque-theme ${lightSlug} --dark ${darkSlug}${scopeName ? ` --scope ${scopeName}` : ''}`;
+const lightSelector = scopeName ? `[data-palette="${scopeName}"]` : ':root';
+const darkSelector = scopeName ? `[data-palette="${scopeName}"][data-theme="dark"]` : '[data-theme="dark"]';
+const scopeNote = scopeName
+  ? `\n *\n * Scoped for remarque-tokens/deck (--scope "${scopeName}") — this is one\n * palette among several coexisting in a stylesheet, switched at runtime\n * via [data-palette] rather than owning :root outright. Self-verification\n * below runs on the same derived [L,C,H] values regardless of scope; see\n * REMARQUE.md "Palette Deck" for the audit story on scoped output.`
+  : '';
 const css = `/*
  * Generated by remarque-theme (remarque-tokens ${OWN_VERSION}) — DO NOT HAND-EDIT.
- * Regenerate instead: npx remarque-theme ${lightSlug} --dark ${darkSlug}
+ * Regenerate instead: ${regenCmd}
  *
  * Source themes (${PKG_SPEC}@${themesVersion}):
  *   light = "${lightSlug}"   dark = "${darkSlug}"
@@ -744,15 +775,15 @@ const css = `/*
  *
  * Palette tier only (--color-*, --weight-display) — see REMARQUE.md
  * "Token Tiers" / "Color Providers". Self-verified against the same
- * contrast + gamut checks as remarque-audit before being emitted.
+ * contrast + gamut checks as remarque-audit before being emitted.${scopeNote}
  */
-:root {
+${lightSelector} {
 ${decls(light.tokens)}
   --weight-display: 400;
 }
-[data-theme="dark"] {
+${darkSelector} {
 ${decls(dark.tokens)}
 }
 `;

package/tokens.d.ts CHANGED Viewed

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.17.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.19.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

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.17.0",
+      "version": "0.19.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"