remarque-tokens 0.2.0 → 0.4.0

package/AGENT_RULES.md

@@ -10,7 +10,7 @@ Read `REMARQUE.md` first for the full system specification. This file tells you
 
 Execute in this exact order. Do not skip steps. Do not reorder.
 
-1. **Load tokens.** Import `tokens.css` and configure `tailwind.config.js` with Remarque's font families and extended theme values. Verify fonts load correctly.
+1. **Load tokens.** Import `fonts.css` then `tokens.css`, and wire Tailwind: v4 projects import `theme.css` (after `tailwindcss` and the tokens, unlayered — see Pitfall #7); v3 projects use `tailwind.config.js`. Verify fonts load correctly.
 
 2. **Set up global typography.** Apply display, title, section, body, meta, and prose classes. Verify the type scale renders correctly at mobile and desktop widths.
 
@@ -138,7 +138,9 @@ 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
-├── tailwind.config.js        # Tailwind v3 ONLY — v4 projects skip this and use an @theme block (see site/src/styles/globals.css)
+├── 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/
 │   └── fonts/                # Self-hosted woff2 fonts (Inter, Newsreader, JetBrains Mono)
 ├── styles/
@@ -172,6 +174,8 @@ project/
 
 6. **String-form @import only:** Always write `@import './tokens.css';` (string form). Tailwind v4 / Lightning CSS silently DROPS `@import url(...)` for local files — the build succeeds while the entire token cascade vanishes from the output. Verify the built CSS contains `.remarque-prose` after changing imports.
 
+7. **Tokens must be imported unlayered (Tailwind v4):** never `@import "remarque-tokens" layer(...)`. theme.css's `@theme inline` mappings emit same-named self-referencing declarations inside `@layer theme`; the real token values win only because unlayered declarations beat layered ones. Layering the tokens makes every mapped utility circular and invalid, with no build error.
+
 ---
 
 ## Quality Checklist

package/CHANGELOG.md

@@ -4,6 +4,49 @@ 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.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
+- **`remarque-tokens/theme.css`** (#48): Tailwind v4 adapter using
+  `@theme inline` — utilities (`font-display`, `bg-surface`,
+  `max-w-reading`, `mt-remarque-9`, …) reference the runtime custom
+  properties directly, so palette switches (light/dark/theme-deck) flow
+  through utilities with zero value duplication. Import order:
+  `tailwindcss` → `remarque-tokens` → `remarque-tokens/theme.css`.
+- **`tokens.json`** (#48): machine-readable token inventory (W3C
+  design-tokens flavored, core/palette tiers, light+dark values),
+  GENERATED from the CSS by `scripts/tokens-json.mjs` — the CSS remains
+  the single source of truth; CI fails if the JSON goes stale.
+
+### Changed
+- The reference site now consumes the package itself (`file:..` link)
+  instead of maintaining file copies — the demo build is the package's
+  integration test, and the copy-sync burden is gone.
+
+No token values changed in this release.
+
 ## 0.2.0 — 2026-07-20
 
 First published release. Everything below is relative to the unpublished

package/README.md

@@ -21,16 +21,31 @@ Most developer sites inherit the visual language of SaaS dashboards or component
 
 ## Install
 
-Copy `fonts.css`, `tokens.css`, `tokens-core.css`, `tokens-palette.css`, and the `fonts/` directory into your project (`tokens.css` is an aggregator that imports the two tier files), then:
+```bash
+npm install remarque-tokens
+```
 
 ```css
-@import 'fonts.css';
-@import 'tokens.css';
+@import 'remarque-tokens/fonts.css';
+@import 'remarque-tokens';
+/* then optionally your site's palette overrides, loaded last */
+```
+
+Copy the `fonts/` woff2 files from `node_modules/remarque-tokens/fonts/` into your static assets (or serve them from wherever your bundler puts font URLs). Personalize by overriding `remarque-tokens/palette` tokens in your own stylesheet, then validate:
+
+```bash
+npx remarque-audit --palette src/styles/my-palette.css --src src
 ```
 
-Tailwind v3 projects can additionally copy `tailwind.config.js`. Tailwind v4 projects skip the config and write an `@theme` block from the token values (see `site/src/styles/globals.css` for the reference).
+**Tailwind v4** projects add the shipped adapter — utilities that track the tokens through every theme switch, no value duplication:
+
+```css
+@import "tailwindcss";
+@import "remarque-tokens";
+@import "remarque-tokens/theme.css";
+```
 
-> **npm:** `remarque-tokens` is not yet published to the registry — the publish pipeline (provenance, semver, changelog) is tracked in [#46](https://github.com/williamzujkowski/remarque/issues/46) and [#48](https://github.com/williamzujkowski/remarque/issues/48). Until then, the copy path above (or `npm install github:williamzujkowski/remarque`) is the supported install.
+**Tailwind v3** projects use the shipped config (`remarque-tokens/tailwind`) instead. A machine-readable token inventory ships as `remarque-tokens/tokens.json` (generated from the CSS — core/palette tiers, light+dark values) for tooling and AI agents. Prefer copy-paste? Grab `fonts.css`, `tokens.css`, `tokens-core.css`, `tokens-palette.css`, and `fonts/` directly — `tokens.css` aggregates the two tier files, so all three CSS files travel together. Use string-form `@import './tokens.css'` only (some bundlers silently drop `@import url(...)` for local files).
 
 ## For AI Agents
 
@@ -52,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

@@ -40,14 +40,14 @@ Remarque projects should feel like a modern technical publication — not a gene
 
 ## Technology Stack
 
-- **CSS framework:** Tailwind CSS — v4 via an `@theme` block written from tokens.css values (reference: `site/src/styles/globals.css`), or v3 via the shipped `tailwind.config.js`. One mechanism per project, never both.
+- **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)
 - **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:** Copy `fonts.css` + `tokens.css` + `tokens-core.css` + `tokens-palette.css` + `fonts/` (plus `tailwind.config.js` for Tailwind v3 projects) — `tokens.css` aggregates the two tier files, so all three CSS files travel together. npm publication of `remarque-tokens` is tracked in #46/#48; until it ships, install from GitHub (`npm install github:williamzujkowski/remarque`) or use the copy path
+- **Package:** `npm install remarque-tokens` — subpaths: `remarque-tokens` (aggregator), `/core`, `/palette`, `/fonts.css`, `/tailwind`; ships `npx remarque-audit`. Copy path also supported: `fonts.css` + `tokens.css` + `tokens-core.css` + `tokens-palette.css` + `fonts/` travel together (the aggregator imports the tier files)
 
 ### Tailwind Spacing Integration Note
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "engines": {
     "node": ">=18"
   },
@@ -37,7 +37,12 @@
     "./tokens-palette.css": "./tokens-palette.css",
     "./fonts.css": "./fonts.css",
     "./fonts/*": "./fonts/*",
-    "./tailwind": "./tailwind.config.js"
+    "./tailwind": "./tailwind.config.js",
+    "./theme.css": "./theme.css",
+    "./theme": "./theme.css",
+    "./tokens.json": "./tokens.json",
+    "./prose": "./prose.css",
+    "./prose.css": "./prose.css"
   },
   "files": [
     "tokens.css",
@@ -50,6 +55,11 @@
     "REMARQUE.md",
     "AGENT_RULES.md",
     "LICENSE",
-    "CHANGELOG.md"
+    "CHANGELOG.md",
+    "theme.css",
+    "tokens.json",
+    "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,51 @@
+/*
+ * 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 */
+export const isLightRoot = (b) => b.context === '' && b.prelude.includes(':root');
+export const isDarkBlock = (b) =>
+  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') && b.prelude.includes(':root')) ||
+  b.prelude.includes('[data-theme="dark"]');

package/scripts/tokens-json.mjs

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+/*
+ * Generates tokens.json (W3C design-tokens flavored) FROM the CSS —
+ * tokens-core.css and tokens-palette.css remain the single source of
+ * truth; this file is derived output for tooling and AI agents.
+ *
+ *   node scripts/tokens-json.mjs           # (re)write tokens.json
+ *   node scripts/tokens-json.mjs --check   # exit 1 if tokens.json is stale (CI)
+ *
+ * Multi-theme values use per-token light/dark groups with $value on each
+ * (the W3C spec has no native theming; this follows its $extensions
+ * escape hatch conservatively).
+ */
+
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { extractBlocks, declsOf, isLightRoot, isDarkBlock } from './lib/css-tokens.mjs';
+
+function typeOf(name, value) {
+  if (name.startsWith('color-')) return 'color';
+  if (name.startsWith('font-')) return 'fontFamily';
+  if (name.startsWith('weight-')) return 'fontWeight';
+  if (name.startsWith('motion-') && /ms$/.test(value)) return 'duration';
+  if (name.startsWith('leading-')) return 'number';
+  if (value === '0') return 'dimension';
+  if (/(^|\s)(rem|px|em|%)/.test(value) || /^-?[\d.]+(rem|px|em)$/.test(value) || value.startsWith('clamp(')) return 'dimension';
+  return 'string';
+}
+
+// W3C spec: number-like types carry numeric $value, not strings.
+function valueFor(type, value) {
+  if (type === 'number' || type === 'fontWeight') {
+    const n = Number(value);
+    if (!Number.isNaN(n)) return n;
+  }
+  return value;
+}
+
+const version = JSON.parse(readFileSync('package.json', 'utf8')).version;
+const coreDecls = declsOf(extractBlocks(readFileSync('tokens-core.css', 'utf8')), isLightRoot);
+const paletteBlocks = extractBlocks(readFileSync('tokens-palette.css', 'utf8'));
+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.',
+  $extensions: {
+    remarque: {
+      version,
+      tiers: {
+        core: 'immutable identity — overriding forks the system',
+        palette: 'sanctioned personalization surface — override freely, then run remarque-audit',
+      },
+    },
+  },
+  core: {},
+  palette: {},
+};
+
+for (const [name, value] of Object.entries(coreDecls)) {
+  const $type = typeOf(name, value);
+  out.core[name] = { $value: valueFor($type, value), $type };
+}
+for (const [name, value] of Object.entries(lightDecls)) {
+  const $type = typeOf(name, value);
+  const token = { $type, light: { $value: valueFor($type, value) } };
+  if (name in darkOverrides) token.dark = { $value: valueFor($type, darkOverrides[name]) };
+  else token.dark = { $value: valueFor($type, value), $extensions: { remarque: { inheritedFromLight: true } } };
+  out.palette[name] = token;
+}
+
+const json = JSON.stringify(out, null, 2) + '\n';
+
+if (process.argv.includes('--check')) {
+  const current = existsSync('tokens.json') ? readFileSync('tokens.json', 'utf8') : '';
+  if (current !== json) {
+    console.error('tokens.json is stale — run: node scripts/tokens-json.mjs');
+    process.exit(1);
+  }
+  console.log('tokens.json is fresh ✓');
+} else {
+  writeFileSync('tokens.json', json);
+  console.log(`tokens.json written — ${Object.keys(out.core).length} core + ${Object.keys(out.palette).length} palette tokens (v${version})`);
+}

package/theme.css

@@ -0,0 +1,77 @@
+/*
+ * Remarque — Tailwind v4 Theme Adapter
+ * ─────────────────────────────────────
+ * Maps Remarque's runtime CSS custom properties into Tailwind v4
+ * utilities (font-display, bg-surface, max-w-reading, mt-remarque-9, …)
+ * without duplicating any values: `@theme inline` makes utilities
+ * reference the vars directly, so light/dark/theme-deck palette
+ * switches flow through automatically and tokens-palette.css stays the
+ * single source of color truth.
+ *
+ * Usage (order matters — Tailwind first, tokens before this file):
+ *   @import "tailwindcss";
+ *   @import "remarque-tokens";
+ *   @import "remarque-tokens/theme.css";
+ *
+ * IMPORTANT: import "remarque-tokens" UNLAYERED — never wrap it in
+ * layer(...). Tailwind still emits the same-named theme keys as
+ * self-referencing declarations inside @layer theme; they are inert
+ * only because unlayered token declarations always beat layered ones
+ * in the cascade. Wrapping the tokens in a layer would make every
+ * mapped utility resolve to an invalid circular value.
+ *
+ * Spacing is namespaced remarque-* so Tailwind's default numeric scale
+ * is never overridden (mt-12 stays 3rem; use mt-remarque-9 for 6rem).
+ * Motion utilities: use arbitrary values with the tokens —
+ * duration-[var(--motion-fast)] — so reduced-motion zeroing applies.
+ */
+
+@theme inline {
+  /* Font slots */
+  --font-display: var(--font-display);
+  --font-body: var(--font-body);
+  --font-mono: var(--font-mono);
+
+  /* Colors — track the palette tier through every theme switch */
+  --color-bg: var(--color-bg);
+  --color-bg-subtle: var(--color-bg-subtle);
+  --color-fg: var(--color-fg);
+  --color-fg-muted: var(--color-fg-muted);
+  --color-muted: var(--color-muted);
+  --color-border: var(--color-border);
+  --color-border-bold: var(--color-border-bold);
+  --color-surface: var(--color-surface);
+  --color-accent: var(--color-accent);
+  --color-accent-hover: var(--color-accent-hover);
+  --color-accent-subtle: var(--color-accent-subtle);
+  --color-code-bg: var(--color-code-bg);
+  --color-code-fg: var(--color-code-fg);
+  --color-link: var(--color-link);
+  --color-link-hover: var(--color-link-hover);
+  --color-focus-ring: var(--color-focus-ring);
+  --color-selection-bg: var(--color-selection-bg);
+  --color-selection-fg: var(--color-selection-fg);
+
+  /* Content widths (max-w-reading / -standard / -wide) */
+  --max-width-reading: var(--content-reading);
+  --max-width-standard: var(--content-standard);
+  --max-width-wide: var(--content-wide);
+
+  /* Remarque spacing scale, namespaced (mt-remarque-9 = 6rem, …) */
+  --spacing-remarque-1: var(--space-1);
+  --spacing-remarque-2: var(--space-2);
+  --spacing-remarque-3: var(--space-3);
+  --spacing-remarque-4: var(--space-4);
+  --spacing-remarque-5: var(--space-5);
+  --spacing-remarque-6: var(--space-6);
+  --spacing-remarque-7: var(--space-7);
+  --spacing-remarque-8: var(--space-8);
+  --spacing-remarque-9: var(--space-9);
+  --spacing-remarque-10: var(--space-10);
+  --spacing-remarque-11: var(--space-11);
+  --spacing-remarque-12: var(--space-12);
+
+  /* Radius (rounded-sm / rounded-md — the system's ceiling) */
+  --radius-sm: var(--radius-sm);
+  --radius-md: var(--radius-md);
+}

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.css

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

package/tokens.json

@@ -0,0 +1,417 @@
+{
+  "$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",
+      "tiers": {
+        "core": "immutable identity — overriding forks the system",
+        "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
+      }
+    }
+  },
+  "core": {
+    "text-display": {
+      "$value": "clamp(2.75rem, 5.5vw, 5rem)",
+      "$type": "dimension"
+    },
+    "text-title": {
+      "$value": "clamp(1.875rem, 3.5vw, 3rem)",
+      "$type": "dimension"
+    },
+    "text-section": {
+      "$value": "clamp(1.375rem, 2.25vw, 2rem)",
+      "$type": "dimension"
+    },
+    "text-body-lg": {
+      "$value": "1.1875rem",
+      "$type": "dimension"
+    },
+    "text-body": {
+      "$value": "1.0625rem",
+      "$type": "dimension"
+    },
+    "text-meta": {
+      "$value": "0.875rem",
+      "$type": "dimension"
+    },
+    "text-micro": {
+      "$value": "0.8125rem",
+      "$type": "dimension"
+    },
+    "leading-display": {
+      "$value": 1.05,
+      "$type": "number"
+    },
+    "leading-title": {
+      "$value": 1.15,
+      "$type": "number"
+    },
+    "leading-section": {
+      "$value": 1.2,
+      "$type": "number"
+    },
+    "leading-body": {
+      "$value": 1.75,
+      "$type": "number"
+    },
+    "leading-meta": {
+      "$value": 1.5,
+      "$type": "number"
+    },
+    "tracking-display": {
+      "$value": "-0.02em",
+      "$type": "dimension"
+    },
+    "tracking-title": {
+      "$value": "-0.015em",
+      "$type": "dimension"
+    },
+    "tracking-body": {
+      "$value": "0em",
+      "$type": "dimension"
+    },
+    "tracking-meta": {
+      "$value": "0.02em",
+      "$type": "dimension"
+    },
+    "tracking-caps": {
+      "$value": "0.06em",
+      "$type": "dimension"
+    },
+    "weight-regular": {
+      "$value": 400,
+      "$type": "fontWeight"
+    },
+    "weight-medium": {
+      "$value": 500,
+      "$type": "fontWeight"
+    },
+    "weight-semibold": {
+      "$value": 600,
+      "$type": "fontWeight"
+    },
+    "space-1": {
+      "$value": "0.25rem",
+      "$type": "dimension"
+    },
+    "space-2": {
+      "$value": "0.5rem",
+      "$type": "dimension"
+    },
+    "space-3": {
+      "$value": "0.75rem",
+      "$type": "dimension"
+    },
+    "space-4": {
+      "$value": "1rem",
+      "$type": "dimension"
+    },
+    "space-5": {
+      "$value": "1.5rem",
+      "$type": "dimension"
+    },
+    "space-6": {
+      "$value": "2rem",
+      "$type": "dimension"
+    },
+    "space-7": {
+      "$value": "3rem",
+      "$type": "dimension"
+    },
+    "space-8": {
+      "$value": "4rem",
+      "$type": "dimension"
+    },
+    "space-9": {
+      "$value": "6rem",
+      "$type": "dimension"
+    },
+    "space-10": {
+      "$value": "8rem",
+      "$type": "dimension"
+    },
+    "space-11": {
+      "$value": "10rem",
+      "$type": "dimension"
+    },
+    "space-12": {
+      "$value": "12rem",
+      "$type": "dimension"
+    },
+    "content-standard": {
+      "$value": "72rem",
+      "$type": "dimension"
+    },
+    "content-wide": {
+      "$value": "88rem",
+      "$type": "dimension"
+    },
+    "radius-sm": {
+      "$value": "0.25rem",
+      "$type": "dimension"
+    },
+    "radius-md": {
+      "$value": "0.5rem",
+      "$type": "dimension"
+    },
+    "radius-none": {
+      "$value": "0",
+      "$type": "dimension"
+    },
+    "border-width": {
+      "$value": "1px",
+      "$type": "dimension"
+    },
+    "border-style": {
+      "$value": "solid",
+      "$type": "string"
+    },
+    "motion-fast": {
+      "$value": "120ms",
+      "$type": "duration"
+    },
+    "motion-normal": {
+      "$value": "180ms",
+      "$type": "duration"
+    },
+    "motion-easing": {
+      "$value": "ease-out",
+      "$type": "string"
+    }
+  },
+  "palette": {
+    "font-display": {
+      "$type": "fontFamily",
+      "light": {
+        "$value": "\"Newsreader\", Georgia, \"Times New Roman\", serif"
+      },
+      "dark": {
+        "$value": "\"Newsreader\", Georgia, \"Times New Roman\", serif",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "font-body": {
+      "$type": "fontFamily",
+      "light": {
+        "$value": "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif"
+      },
+      "dark": {
+        "$value": "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "font-mono": {
+      "$type": "fontFamily",
+      "light": {
+        "$value": "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace"
+      },
+      "dark": {
+        "$value": "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "content-reading": {
+      "$type": "dimension",
+      "light": {
+        "$value": "46rem"
+      },
+      "dark": {
+        "$value": "46rem",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "color-bg": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.975 0.005 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.16 0.01 80)"
+      }
+    },
+    "color-bg-subtle": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.955 0.005 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.19 0.01 80)"
+      }
+    },
+    "color-fg": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.18 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.90 0.005 80)"
+      }
+    },
+    "color-fg-muted": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.43 0.015 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.70 0.01 80)"
+      }
+    },
+    "color-muted": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.54 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.60 0.01 80)"
+      }
+    },
+    "color-border": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.88 0.005 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.25 0.005 80)"
+      }
+    },
+    "color-border-bold": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.62 0.01 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.50 0.01 80)"
+      }
+    },
+    "color-surface": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.965 0.005 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.19 0.01 80)"
+      }
+    },
+    "color-accent": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.50 0.14 250)"
+      },
+      "dark": {
+        "$value": "oklch(0.68 0.12 250)"
+      }
+    },
+    "color-accent-hover": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.42 0.11 250)"
+      },
+      "dark": {
+        "$value": "oklch(0.75 0.12 250)"
+      }
+    },
+    "color-accent-subtle": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.95 0.02 250)"
+      },
+      "dark": {
+        "$value": "oklch(0.22 0.04 250)"
+      }
+    },
+    "color-link": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-accent)"
+      },
+      "dark": {
+        "$value": "var(--color-accent)",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "color-link-hover": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-accent-hover)"
+      },
+      "dark": {
+        "$value": "var(--color-accent-hover)",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "color-focus-ring": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-accent)"
+      },
+      "dark": {
+        "$value": "var(--color-accent)",
+        "$extensions": {
+          "remarque": {
+            "inheritedFromLight": true
+          }
+        }
+      }
+    },
+    "color-selection-bg": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.92 0.04 250)"
+      },
+      "dark": {
+        "$value": "oklch(0.30 0.06 250)"
+      }
+    },
+    "color-selection-fg": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-fg)"
+      },
+      "dark": {
+        "$value": "oklch(0.92 0.005 80)"
+      }
+    },
+    "color-code-bg": {
+      "$type": "color",
+      "light": {
+        "$value": "oklch(0.945 0.005 80)"
+      },
+      "dark": {
+        "$value": "oklch(0.20 0.005 80)"
+      }
+    },
+    "color-code-fg": {
+      "$type": "color",
+      "light": {
+        "$value": "var(--color-fg)"
+      },
+      "dark": {
+        "$value": "oklch(0.88 0.005 80)"
+      }
+    }
+  }
+}