remarque-tokens 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -4,6 +4,31 @@ 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

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.4.0",
+  "version": "0.5.0",
   "engines": {
     "node": ">=18"
   },
@@ -42,7 +42,8 @@
     "./theme": "./theme.css",
     "./tokens.json": "./tokens.json",
     "./prose": "./prose.css",
-    "./prose.css": "./prose.css"
+    "./prose.css": "./prose.css",
+    "./package.json": "./package.json"
   },
   "files": [
     "tokens.css",

package/scripts/lib/css-tokens.mjs

@@ -44,8 +44,17 @@ export function declsOf(blocks, filterFn) {
   return decls;
 }
 
-/* Standard tier filters */
-export const isLightRoot = (b) => b.context === '' && b.prelude.includes(':root');
+/* 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') && b.prelude.includes(':root')) ||
-  b.prelude.includes('[data-theme="dark"]');
+  (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/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.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.4.0",
+      "version": "0.5.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"