remarque-tokens 0.3.0 → 0.5.0

package/AGENT_RULES.md

@@ -138,6 +138,7 @@ project/
 ├── tokens.css                # Aggregator — imports the two tiers below
 ├── tokens-core.css           # CORE tier: type scale, spacing, widths, radius, motion, prose machinery. NEVER override
 ├── tokens-palette.css        # PALETTE tier: font slots, colors, accent, reading measure. Override freely, then run the audit
+├── prose.css                 # .remarque-prose long-form styling (aggregated by tokens.css; own subpath for opt-out)
 ├── theme.css                 # Tailwind v4 adapter (@theme inline) — import after tailwindcss + tokens
 ├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects use theme.css instead
 ├── public/

package/CHANGELOG.md

@@ -4,6 +4,53 @@ 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.5.0 — 2026-07-20
+
+Theme-convention unification (epic #47 item 4; ratified 3-0 by consensus
+panel with conditions, all implemented).
+
+### Added
+- **Dual dark selector**: the palette's manual-toggle block is now
+  `[data-theme="dark"], :root.dark` — `[data-theme]` stays canonical for
+  new sites; `:root.dark` is a compatibility bridge for class-keyed
+  consumers (sunset target: 1.0). Specificity asymmetry documented.
+- **`remarque-audit` parses both conventions natively** (plus
+  `html.dark`/`.dark`), so class-keyed sites can adopt the audit with no
+  flags. Fixture tests for all three conventions + a must-fail case run
+  in CI.
+- `exports` now includes `./package.json` (standard tooling expects
+  `require('remarque-tokens/package.json')`; previously blocked).
+
+### Fixed
+- Parser bug: light-theme extraction matched any selector *containing*
+  `:root`, so a `:root.dark` block would have leaked dark values into
+  the light-theme audit and could mask light-theme contrast failures.
+  Selector matching is now exact per comma-separated part.
+
+No token values changed in this release.
+
+## 0.4.0 — 2026-07-20
+
+### Added
+- **`remarque-tokens/prose`** subpath: `.remarque-prose` split out of
+  `tokens-core.css` into `prose.css`, so consumers with their own prose
+  system (e.g. the reference consumer's `.prose`) can import the core
+  structural tokens without it.
+
+### Changed
+- **Breaking for `/core` importers:** `remarque-tokens/core` no longer
+  includes `.remarque-prose` — import `remarque-tokens/prose` alongside
+  it, or use the aggregator (`remarque-tokens`), which now includes all
+  three files and is unchanged for consumers.
+- Demo pages exercise the Tailwind v4 adapter utilities directly
+  (`pt-remarque-10`, `rounded-sm`) instead of arbitrary-value escapes —
+  same computed styles, real coverage of the theme.css surface.
+- Internals: the brace-aware CSS token parser previously duplicated in
+  `audit.mjs` and `tokens-json.mjs` now lives once in
+  `scripts/lib/css-tokens.mjs` (shipped with the package for the bin).
+
+No token values changed in this release.
+
 ## 0.3.0 — 2026-07-20
 
 ### Added

package/README.md

@@ -67,6 +67,7 @@ The agent rules define build order, non-negotiable rules, disallowed patterns, a
 | `tokens.css` | Aggregator importing the two token tiers below |
 | `tokens-core.css` | Core tier — type scale, spacing, widths, radius, motion, prose styling. Never overridden |
 | `tokens-palette.css` | Palette tier — font slots, colors, accent, reading measure. The sanctioned personalization surface |
+| `prose.css` | `.remarque-prose` long-form styling — own subpath so sites with their own prose system can skip it |
 | `scripts/audit.mjs` | `npm run audit` — enforces the spec's contrast/gamut/font-floor/no-hardcoded-color checklist |
 | `fonts.css` + `fonts/` | Self-hosted @font-face declarations and woff2 files (no CDN requests) |
 | `tailwind.config.js` | Tailwind CSS **v3** configuration (v4 projects use an `@theme` block instead) |

package/REMARQUE.md

@@ -43,7 +43,7 @@ Remarque projects should feel like a modern technical publication — not a gene
 - **CSS framework:** Tailwind CSS — v4 via the shipped `remarque-tokens/theme.css` (`@theme inline` adapter; utilities reference the runtime tokens), or v3 via the shipped `tailwind.config.js`. One mechanism per project, never both.
 - **Component primitives:** shadcn/ui (when reusable components are needed)
 - **Markup:** Semantic HTML with ARIA landmarks
-- **Theming:** Light and dark mode via `[data-theme]` attribute (system preference + manual toggle)
+- **Theming:** Light and dark mode via the `[data-theme]` attribute (canonical; system preference + manual toggle). `:root.dark` is supported as a compatibility bridge for class-keyed sites (sunset: 1.0) — the audit parses both. Mind the specificity asymmetry: `[data-theme=\"dark\"]` is (0,1,0), `:root.dark` is (0,2,0). Platform endgame to watch: `color-scheme` + `light-dark()`
 - **Accessibility:** USWDS-informed. Keyboard navigation, skip-to-content link, ARIA labels, WCAG AA contrast compliance, 44px touch targets, 14px minimum small text
 - **Tokens:** Centralized CSS custom properties in two tiers — `tokens-core.css` (immutable identity) + `tokens-palette.css` (sanctioned personalization). `tokens.css` aggregates both. See "Token Tiers"
 - **Fonts:** Self-hosted woff2 (no CDN dependency). Preloaded via `<link rel="preload">`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "engines": {
     "node": ">=18"
   },
@@ -40,7 +40,10 @@
     "./tailwind": "./tailwind.config.js",
     "./theme.css": "./theme.css",
     "./theme": "./theme.css",
-    "./tokens.json": "./tokens.json"
+    "./tokens.json": "./tokens.json",
+    "./prose": "./prose.css",
+    "./prose.css": "./prose.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "tokens.css",
@@ -56,6 +59,8 @@
     "CHANGELOG.md",
     "theme.css",
     "tokens.json",
-    "scripts/tokens-json.mjs"
+    "scripts/tokens-json.mjs",
+    "prose.css",
+    "scripts/lib/css-tokens.mjs"
   ]
 }

package/prose.css

@@ -0,0 +1,139 @@
+/*
+ * Remarque — Prose Styling (core tier)
+ * ─────────────────────────────────────
+ * .remarque-prose: all typographic details for long-form reading.
+ * Split from tokens-core.css as its own subpath (remarque-tokens/prose)
+ * so consumers with their own prose systems can import the core
+ * structural tokens without it. The tokens.css aggregator includes it.
+ * Values consumed here come from the core + palette tiers.
+ */
+
+/* ─── Prose Styling ─────────────────────────────────────── */
+/*
+ * Apply .remarque-prose to any container with article/essay content.
+ * Handles all typographic details for long-form reading.
+ */
+
+.remarque-prose {
+  font-family: var(--font-body);
+  font-size: var(--text-body);
+  line-height: var(--leading-body);
+  color: var(--color-fg);
+  max-width: var(--content-reading);
+}
+
+.remarque-prose > * + * {
+  margin-top: var(--space-5);
+}
+
+.remarque-prose > :first-child {
+  margin-top: 0;
+}
+
+.remarque-prose h2 {
+  font-family: var(--font-display);
+  font-size: var(--text-section);
+  line-height: var(--leading-section);
+  letter-spacing: var(--tracking-title);
+  font-weight: var(--weight-medium);
+  margin-top: var(--space-7);
+  margin-bottom: var(--space-3);
+  color: var(--color-fg);
+}
+
+.remarque-prose h3 {
+  font-family: var(--font-body);
+  font-size: var(--text-body-lg);
+  line-height: var(--leading-title);
+  font-weight: var(--weight-semibold);
+  margin-top: var(--space-6);
+  margin-bottom: var(--space-2);
+  color: var(--color-fg);
+}
+
+.remarque-prose a {
+  color: var(--color-link);
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+  text-decoration-thickness: 1px;
+  transition: color var(--motion-fast) var(--motion-easing);
+}
+
+.remarque-prose a:hover {
+  color: var(--color-link-hover);
+}
+
+.remarque-prose strong {
+  font-weight: var(--weight-semibold);
+}
+
+.remarque-prose em {
+  font-style: italic;
+}
+
+.remarque-prose blockquote {
+  border-left: 2px solid var(--color-border-bold);
+  padding-left: var(--space-5);
+  margin-left: 0;
+  color: var(--color-fg-muted);
+  font-style: italic;
+}
+
+.remarque-prose ul,
+.remarque-prose ol {
+  padding-left: var(--space-5);
+}
+
+.remarque-prose li + li {
+  margin-top: var(--space-2);
+}
+
+.remarque-prose code {
+  font-family: var(--font-mono);
+  font-size: 0.9em;
+  background-color: var(--color-code-bg);
+  padding: 0.15em 0.35em;
+  border-radius: var(--radius-sm);
+  color: var(--color-code-fg);
+}
+
+.remarque-prose pre {
+  font-family: var(--font-mono);
+  font-size: var(--text-meta);
+  line-height: 1.6;
+  background-color: var(--color-code-bg);
+  border: var(--border-width) var(--border-style) var(--color-border);
+  border-radius: var(--radius-md);
+  padding: var(--space-5);
+  overflow-x: auto;
+}
+
+.remarque-prose pre code {
+  background: none;
+  padding: 0;
+  border-radius: 0;
+  font-size: inherit;
+}
+
+.remarque-prose hr {
+  border: none;
+  border-top: var(--border-width) var(--border-style) var(--color-border);
+  margin: var(--space-8) 0;
+}
+
+.remarque-prose img {
+  max-width: 100%;
+  height: auto;
+  border: var(--border-width) var(--border-style) var(--color-border);
+  border-radius: var(--radius-sm);
+}
+
+.remarque-prose figcaption {
+  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-top: var(--space-2);
+}
+

package/scripts/audit.mjs

@@ -22,7 +22,9 @@
  */
 
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
-import { join, relative } from 'node:path';
+import { join, relative, dirname } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { extractBlocks, declsOf, isLightRoot, isDarkBlock } from './lib/css-tokens.mjs';
 
 const args = process.argv.slice(2);
 function argOf(flag, dflt) {
@@ -75,57 +77,9 @@ function ratio(c1, c2) {
   return (hi + 0.05) / (lo + 0.05);
 }
 
-/* ── Brace-aware CSS block extraction ───────────────────── */
-/* Returns [{ prelude, body, context }] where context is the enclosing
-   at-rule prelude ('' at top level). One level of at-rule nesting is
-   supported — enough for token files; deeper nesting is flattened with
-   its outermost context. Comments are stripped first. */
-
-function extractBlocks(css) {
-  const src = css.replace(/\/\*[\s\S]*?\*\//g, '');
-  const blocks = [];
-  function scan(text, context) {
-    let i = 0;
-    while (i < text.length) {
-      const open = text.indexOf('{', i);
-      if (open === -1) break;
-      const prelude = text.slice(i, open).trim().replace(/^[;\s]+/, '');
-      let depth = 1, j = open + 1;
-      while (j < text.length && depth > 0) {
-        if (text[j] === '{') depth++;
-        else if (text[j] === '}') depth--;
-        j++;
-      }
-      const body = text.slice(open + 1, j - 1);
-      if (prelude.startsWith('@')) {
-        scan(body, prelude);
-      } else {
-        blocks.push({ prelude, body, context });
-      }
-      i = j;
-    }
-  }
-  scan(src, '');
-  return blocks;
-}
-
-function declsOf(blocks, filterFn) {
-  const decls = {};
-  for (const b of blocks) {
-    if (!filterFn(b)) continue;
-    for (const m of b.body.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) {
-      decls[m[1]] = m[2].trim();
-    }
-  }
-  return decls;
-}
-
 const blocks = extractBlocks(readFileSync(PALETTE, 'utf8'));
-const lightDecls = declsOf(blocks, (b) => b.context === '' && b.prelude.includes(':root'));
-const darkOverrides = declsOf(blocks, (b) =>
-  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') && b.prelude.includes(':root')) ||
-  b.prelude.includes('[data-theme="dark"]')
-);
+const lightDecls = declsOf(blocks, isLightRoot);
+const darkOverrides = declsOf(blocks, isDarkBlock);
 if (Object.keys(lightDecls).length === 0) fail(`no top-level :root declarations found in ${PALETTE}`);
 if (Object.keys(darkOverrides).length === 0) fail(`no dark-theme declarations found in ${PALETTE} (@media prefers-color-scheme: dark or [data-theme="dark"])`);
 // CSS cascade: dark blocks override light; unset dark tokens inherit light values.

package/scripts/lib/css-tokens.mjs

@@ -0,0 +1,60 @@
+/*
+ * Shared CSS token extraction for scripts/audit.mjs and
+ * scripts/tokens-json.mjs (previously duplicated in both).
+ */
+
+/* Brace-aware CSS block extraction. Returns [{ prelude, body, context }]
+   where context is the enclosing at-rule prelude ('' at top level).
+   One level of at-rule nesting is supported — enough for token files;
+   deeper nesting is flattened with its outermost context. Comments are
+   stripped first. */
+export function extractBlocks(css) {
+  const src = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const blocks = [];
+  function scan(text, context) {
+    let i = 0;
+    while (i < text.length) {
+      const open = text.indexOf('{', i);
+      if (open === -1) break;
+      const prelude = text.slice(i, open).trim().replace(/^[;\s]+/, '');
+      let depth = 1, j = open + 1;
+      while (j < text.length && depth > 0) {
+        if (text[j] === '{') depth++;
+        else if (text[j] === '}') depth--;
+        j++;
+      }
+      const body = text.slice(open + 1, j - 1);
+      if (prelude.startsWith('@')) scan(body, prelude);
+      else blocks.push({ prelude, body, context });
+      i = j;
+    }
+  }
+  scan(src, '');
+  return blocks;
+}
+
+export function declsOf(blocks, filterFn) {
+  const decls = {};
+  for (const b of blocks) {
+    if (!filterFn(b)) continue;
+    for (const m of b.body.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      decls[m[1]] = m[2].trim();
+    }
+  }
+  return decls;
+}
+
+/* Standard tier filters. Selector matching is exact per comma-separated
+   part — `.includes(':root')` would wrongly classify `:root.dark` (a
+   dark block in the class convention) as light. */
+const parts = (prelude) => prelude.split(',').map((s) => s.trim());
+
+export const isLightRoot = (b) =>
+  b.context === '' && parts(b.prelude).some((s) => s === ':root' || s === ':root.light' || s === '[data-theme="light"]');
+
+/* Dark: media-query :root, the canonical [data-theme="dark"], or the
+   class-convention :root.dark / html.dark (compatibility bridge). */
+export const isDarkBlock = (b) =>
+  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') &&
+    parts(b.prelude).some((s) => s === ':root')) ||
+  parts(b.prelude).some((s) => s === '[data-theme="dark"]' || s === ':root.dark' || s === 'html.dark' || s === '.dark');

package/scripts/tokens-json.mjs

@@ -13,45 +13,7 @@
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
-
-/* Brace-aware block extraction — kept in sync with scripts/audit.mjs
-   (duplicated deliberately: audit.mjs is a CLI whose import would run
-   its main; unifying them is tracked under issue #48's follow-ups). */
-function extractBlocks(css) {
-  const src = css.replace(/\/\*[\s\S]*?\*\//g, '');
-  const blocks = [];
-  function scan(text, context) {
-    let i = 0;
-    while (i < text.length) {
-      const open = text.indexOf('{', i);
-      if (open === -1) break;
-      const prelude = text.slice(i, open).trim().replace(/^[;\s]+/, '');
-      let depth = 1, j = open + 1;
-      while (j < text.length && depth > 0) {
-        if (text[j] === '{') depth++;
-        else if (text[j] === '}') depth--;
-        j++;
-      }
-      const body = text.slice(open + 1, j - 1);
-      if (prelude.startsWith('@')) scan(body, prelude);
-      else blocks.push({ prelude, body, context });
-      i = j;
-    }
-  }
-  scan(src, '');
-  return blocks;
-}
-
-function declsOf(blocks, filterFn) {
-  const decls = {};
-  for (const b of blocks) {
-    if (!filterFn(b)) continue;
-    for (const m of b.body.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) {
-      decls[m[1]] = m[2].trim();
-    }
-  }
-  return decls;
-}
+import { extractBlocks, declsOf, isLightRoot, isDarkBlock } from './lib/css-tokens.mjs';
 
 function typeOf(name, value) {
   if (name.startsWith('color-')) return 'color';
@@ -74,13 +36,10 @@ function valueFor(type, value) {
 }
 
 const version = JSON.parse(readFileSync('package.json', 'utf8')).version;
-const coreDecls = declsOf(extractBlocks(readFileSync('tokens-core.css', 'utf8')), (b) => b.context === '' && b.prelude.includes(':root'));
+const coreDecls = declsOf(extractBlocks(readFileSync('tokens-core.css', 'utf8')), isLightRoot);
 const paletteBlocks = extractBlocks(readFileSync('tokens-palette.css', 'utf8'));
-const lightDecls = declsOf(paletteBlocks, (b) => b.context === '' && b.prelude.includes(':root'));
-const darkOverrides = declsOf(paletteBlocks, (b) =>
-  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') && b.prelude.includes(':root')) ||
-  b.prelude.includes('[data-theme="dark"]')
-);
+const lightDecls = declsOf(paletteBlocks, isLightRoot);
+const darkOverrides = declsOf(paletteBlocks, isDarkBlock);
 
 const out = {
   $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.',

package/tokens-core.css

@@ -191,135 +191,6 @@ html {
   margin-inline: auto;
 }
 
-/* ─── Prose Styling ─────────────────────────────────────── */
-/*
- * Apply .remarque-prose to any container with article/essay content.
- * Handles all typographic details for long-form reading.
- */
-
-.remarque-prose {
-  font-family: var(--font-body);
-  font-size: var(--text-body);
-  line-height: var(--leading-body);
-  color: var(--color-fg);
-  max-width: var(--content-reading);
-}
-
-.remarque-prose > * + * {
-  margin-top: var(--space-5);
-}
-
-.remarque-prose > :first-child {
-  margin-top: 0;
-}
-
-.remarque-prose h2 {
-  font-family: var(--font-display);
-  font-size: var(--text-section);
-  line-height: var(--leading-section);
-  letter-spacing: var(--tracking-title);
-  font-weight: var(--weight-medium);
-  margin-top: var(--space-7);
-  margin-bottom: var(--space-3);
-  color: var(--color-fg);
-}
-
-.remarque-prose h3 {
-  font-family: var(--font-body);
-  font-size: var(--text-body-lg);
-  line-height: var(--leading-title);
-  font-weight: var(--weight-semibold);
-  margin-top: var(--space-6);
-  margin-bottom: var(--space-2);
-  color: var(--color-fg);
-}
-
-.remarque-prose a {
-  color: var(--color-link);
-  text-decoration: underline;
-  text-underline-offset: 0.2em;
-  text-decoration-thickness: 1px;
-  transition: color var(--motion-fast) var(--motion-easing);
-}
-
-.remarque-prose a:hover {
-  color: var(--color-link-hover);
-}
-
-.remarque-prose strong {
-  font-weight: var(--weight-semibold);
-}
-
-.remarque-prose em {
-  font-style: italic;
-}
-
-.remarque-prose blockquote {
-  border-left: 2px solid var(--color-border-bold);
-  padding-left: var(--space-5);
-  margin-left: 0;
-  color: var(--color-fg-muted);
-  font-style: italic;
-}
-
-.remarque-prose ul,
-.remarque-prose ol {
-  padding-left: var(--space-5);
-}
-
-.remarque-prose li + li {
-  margin-top: var(--space-2);
-}
-
-.remarque-prose code {
-  font-family: var(--font-mono);
-  font-size: 0.9em;
-  background-color: var(--color-code-bg);
-  padding: 0.15em 0.35em;
-  border-radius: var(--radius-sm);
-  color: var(--color-code-fg);
-}
-
-.remarque-prose pre {
-  font-family: var(--font-mono);
-  font-size: var(--text-meta);
-  line-height: 1.6;
-  background-color: var(--color-code-bg);
-  border: var(--border-width) var(--border-style) var(--color-border);
-  border-radius: var(--radius-md);
-  padding: var(--space-5);
-  overflow-x: auto;
-}
-
-.remarque-prose pre code {
-  background: none;
-  padding: 0;
-  border-radius: 0;
-  font-size: inherit;
-}
-
-.remarque-prose hr {
-  border: none;
-  border-top: var(--border-width) var(--border-style) var(--color-border);
-  margin: var(--space-8) 0;
-}
-
-.remarque-prose img {
-  max-width: 100%;
-  height: auto;
-  border: var(--border-width) var(--border-style) var(--color-border);
-  border-radius: var(--radius-sm);
-}
-
-.remarque-prose figcaption {
-  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-top: var(--space-2);
-}
-
 /* ─── Focus Styles ──────────────────────────────────────── */
 
 :focus-visible {

package/tokens-palette.css

@@ -106,8 +106,16 @@
   }
 }
 
-/* Manual dark mode toggle support */
-[data-theme="dark"] {
+/* Manual dark mode toggle support.
+   CANONICAL convention: [data-theme="dark"] — use it for new sites.
+   :root.dark is a compatibility bridge for class-keyed consumers
+   (sunset target: 1.0). NOTE the specificity asymmetry: [data-theme]
+   is (0,1,0) but :root.dark is (0,2,0) — site overrides that beat one
+   can lose to the other; always override with at least (0,2,0) or use
+   cascade order. Platform endgame worth tracking: color-scheme +
+   light-dark(), which obsoletes both selectors. */
+[data-theme="dark"],
+:root.dark {
   --color-bg:          oklch(0.16 0.01 80);
   --color-bg-subtle:   oklch(0.19 0.01 80);
   --color-fg:          oklch(0.90 0.005 80);

package/tokens.css

@@ -22,3 +22,4 @@
 
 @import './tokens-core.css';
 @import './tokens-palette.css';
+@import './prose.css';

package/tokens.json

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