remarque-tokens 0.24.0 → 0.25.0

package/AGENT_RULES.md

@@ -323,6 +323,30 @@ the documented DTCG divergences.
 
 ---
 
+## Installing the Skills
+
+This package ships two Claude Code skills under the npm subpath exports
+`remarque-tokens/skills/remarque` and `remarque-tokens/skills/adopt`
+(resolving to `skills/remarque/SKILL.md` and `skills/remarque-adopt/
+SKILL.md` in the installed package). Claude Code only discovers skills
+from a project's own `.claude/skills/` (or `~/.claude/skills/`), never
+from `node_modules` — copy them in explicitly, one `cp` per skill:
+
+```bash
+mkdir -p .claude/skills
+cp -r node_modules/remarque-tokens/skills/remarque .claude/skills/remarque
+cp -r node_modules/remarque-tokens/skills/remarque-adopt .claude/skills/remarque-adopt
+```
+
+The copies are versioned with the installed package, not auto-updating —
+re-copy both after a MAJOR bump, or any time this file's
+"Machine-Readable Output" shape changes.
+
+- `remarque` — the build/review contract for pages on the current version (tier rules, archetypes, pitfalls #6/#7).
+- `remarque-adopt` — the version-bump/migration playbook (this file's "Machine-Readable Output" section is its main dependency): verify the resolved version past the 0.x caret freeze, discover newly-required tokens from `remarque-audit --json`, solve missing values against the consumer's own backgrounds, classify `remarque-drift --json` output, report against a fixed PR-body contract.
+
+---
+
 ## How to Reference This System
 
 In prompts, issues, or agent instructions, use:

package/CHANGELOG.md

@@ -4,6 +4,19 @@ 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.25.0 — 2026-07-23
+
+`remarque-adopt` skill + skills npm export (closes #107) — ratified 3-0 (skill-suite vote, 2026-07-23), the anchor item of the skill suite. Codifies the consumer-conformance playbook run five times in one day as hand-written agent briefs (williamzujkowski.github.io#381, tsundoku#243/#237, remarque-starter#7/#8) into a procedural, machine-gated skill.
+
+### Added
+
+- **`.claude/skills/remarque-adopt/SKILL.md`** — a new Claude Code skill, distinct from the existing `remarque` loader skill: triggers on "bump remarque-tokens" / "upgrade the design system" / "adopt remarque in an existing site" / an audit failing after a version bump, not on ordinary page work. Five steps, each ending in a machine gate: (1) bump the pin and verify the *resolved* version, not the range typed — 0.x caret ranges never cross a minor below 1.0, the exact trap that froze remarque-starter at 0.10.x through 0.18.0; (2) discover newly-required tokens mechanically from `remarque-audit --json`'s `failures`, never by reading the CHANGELOG and guessing; (3) add missing tokens solved against *the consumer's own* `--color-bg`/`--color-surface`/`--color-code-bg` (keep-if-passing against the package default; the tsundoku#243 hue-collision case — the default viz "red" landing on top of that site's terracotta accent and its own `--color-error` — is the worked example for checking hue collisions as a distinct failure mode from contrast); (4) run `remarque-drift --json` and classify FAIL (undocumented core-tier override, fix it) / WARN (documented in `DESIGN-DEVIATIONS.md`/`DESIGN-NOTES.md`, ratified) / INFO (palette-tier personalization, expected); (5) a fixed PR-body contract (what changed, token decisions table, drift summary, gate results, anything explicitly declined). Acceptance throughout is pinned to `passed: true` in the JSON output, never agent judgment.
+- **Both skills now ship in the npm tarball.** `.claude/skills/{remarque,remarque-adopt}/SKILL.md` remain the ONE canonical, hand-authored copies (also what a Claude Code session working in this repo reads directly); `scripts/build-skills.mjs` copies them byte-for-byte into `skills/remarque/SKILL.md` and `skills/remarque-adopt/SKILL.md` for packaging — the same single-source-plus-generated-copy relationship `tokens.json` already has to the CSS tiers, kept fresh the same way (`--check` gates CI freshness; a `prepack` script hook runs the plain copy automatically on every `npm pack`/`npm publish`, so a stale packaged copy can't ship even if someone forgets to re-run the script by hand). New exports: `remarque-tokens/skills/remarque` and `remarque-tokens/skills/adopt`. `package.json`'s `files` gains `skills/`, `scripts/build-skills.mjs`, and `scripts/lib/skills.mjs`.
+- **README + AGENT_RULES.md: "Installing the skills"** — Claude Code only discovers skills from a project's own `.claude/skills/` (or `~/.claude/skills/`), never `node_modules`, so installing the npm package alone does nothing for a consumer's Claude Code session. Both docs now give the exact `cp -r node_modules/remarque-tokens/skills/<name> .claude/skills/<name>` pair and note the copies are versioned with the installed package, not auto-updating — re-copy on a MAJOR bump.
+- **`scripts/test-skills.mjs`** (enforce-not-instruct applied to the skills themselves, panel condition) — asserts, per skill: frontmatter parses with a non-empty `name`/`description`; every CLI flag referenced alongside a `remarque-audit`/`remarque-drift`/`remarque-theme` command line is grepped straight out of `scripts/audit.mjs`/`scripts/drift-check.mjs`/`scripts/theme.mjs`'s own arg parsing (not hand-maintained separately, so a renamed flag fails this test instead of shipping a stale doc); every backticked package-relative file path referenced (`*.md`/`*.mjs`/`*.js`/`*.json`/`*.css`, excluding consumer-side conventions like `DESIGN-DEVIATIONS.md`/`DESIGN-NOTES.md` and `node_modules`/subpath-export forms) resolves to a real file in this repo; the packaged `skills/<name>/SKILL.md` copy is byte-identical to the canonical file. Wired into `deploy.yml` alongside `scripts/build-skills.mjs --check`.
+- **`scripts/test-pack.mjs` extended** — the real npm-tarball smoke test now also asserts (via `tar -tzf`) that `package/skills/remarque/SKILL.md` and `package/skills/remarque-adopt/SKILL.md` land in the packed tarball, and that both resolve inside the scratch consumer's `node_modules/remarque-tokens/skills/` after a real `npm install` — proving the `prepack` hook actually fires during a real pack/publish, not just that the files exist in the working tree.
+- Version-only regeneration of `tokens.json`/`tokens.d.ts`/`tokens.schema.json` and `registry.json`/`registry/*.json` (no token or registry content changes this release).
+
 ## 0.24.0 — 2026-07-23
 
 `light-dark()` + `color-scheme` palette migration (closes #95) and a `:has()` zero-JS forms enhancement layer (closes #97) — the ratified program's last two items.

package/README.md

@@ -69,10 +69,32 @@ The agent rules define build order, non-negotiable rules, disallowed patterns, a
 
 Packaging for agent tooling:
 - **npm exports:** `remarque-tokens/agent-rules` (→ `AGENT_RULES.md`) and `remarque-tokens/spec` (→ `REMARQUE.md`), alongside the existing `remarque-tokens/tokens.json`, so a project can point an agent at `node_modules/remarque-tokens/AGENT_RULES.md` without hardcoding a filename.
-- **Claude Code skill:** [`.claude/skills/remarque/SKILL.md`](.claude/skills/remarque/SKILL.md) — triggers on "remarque" / "design system" / new-page work, loads all three files, and states the tier rules, the audit command, and the two build-time pitfalls (unlayered-token-import, string-form `@import`) that pass a green build while silently breaking.
+- **Claude Code skills (two):**
+  - [`.claude/skills/remarque/SKILL.md`](.claude/skills/remarque/SKILL.md) — triggers on "remarque" / "design system" / new-page work, loads all three files, and states the tier rules, the audit command, and the two build-time pitfalls (unlayered-token-import, string-form `@import`) that pass a green build while silently breaking.
+  - [`.claude/skills/remarque-adopt/SKILL.md`](.claude/skills/remarque-adopt/SKILL.md) — triggers on "bump remarque-tokens" / "upgrade the design system" / "adopt remarque in an existing site" / an audit that starts failing after a version bump. The consumer-conformance playbook (issue #107): verify the resolved version past the 0.x caret freeze, discover newly-required tokens from `remarque-audit --json` mechanically, solve missing values against the *consumer's own* backgrounds (keep-if-passing), classify `remarque-drift --json` output (FAIL/WARN/INFO), and report against a fixed PR-body contract. Every step ends in a machine gate — `passed: true`, not agent judgment.
+
+  Both ship in the npm tarball under `skills/` (see "Installing the skills" below) as well as living at `.claude/skills/` in this repo.
 - **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json**, and its schema at **https://williamzujkowski.github.io/remarque/tokens.schema.json** — a remote agent can fetch current token values (and validate their shape) directly instead of trusting training data.
 - **Markup-contract registry:** a shadcn-`registry-item.json`-shaped, version-pinned, hash-verified registry of known-good markup for the Essay/Broadsheet/Forms/Palette Deck modules — **https://williamzujkowski.github.io/remarque/registry.json** (index) and **https://williamzujkowski.github.io/remarque/registry/essay.json** (per item; also `broadsheet`/`forms`/`palette-deck`). Fetch and apply the markup instead of transcribing it from spec prose — see REMARQUE.md's "The Registry" and AGENT_RULES.md's "Prefer the Registry Over Transcribing Prose."
 
+### Installing the skills
+
+`npm install remarque-tokens` does not put anything into your project's
+`.claude/skills/` automatically — Claude Code only reads skills from
+there (or from `~/.claude/skills/`), never from `node_modules`. Copy them
+in explicitly, one `cp` per skill:
+
+```bash
+mkdir -p .claude/skills
+cp -r node_modules/remarque-tokens/skills/remarque .claude/skills/remarque
+cp -r node_modules/remarque-tokens/skills/remarque-adopt .claude/skills/remarque-adopt
+```
+
+The copies are versioned with whatever `remarque-tokens` version is
+installed at copy time, not auto-updating — re-run both `cp` commands
+after any MAJOR bump (and any time `AGENT_RULES.md`'s "Machine-Readable
+Output" shape changes) to pick up the current playbook.
+
 ## Files
 
 | File | Purpose |
@@ -89,6 +111,7 @@ Packaging for agent tooling:
 | `tokens.schema.json` | Generated JSON Schema (draft 2020-12) for `tokens.json`, published alongside it |
 | `registry.json` + `registry/` | Generated markup-contract registry index + per-item files for essay/broadsheet/forms/palette-deck (`scripts/build-registry.mjs`) — see REMARQUE.md "The Registry" |
 | `registry-item.schema.json` + `registry.schema.json` | Generated JSON Schemas (draft 2020-12) for the per-item and index registry files |
+| `skills/remarque/SKILL.md` + `skills/remarque-adopt/SKILL.md` | Generated packaging copies of the two Claude Code skills (`scripts/build-skills.mjs`) — canonical source is `.claude/skills/*/SKILL.md`; see "Installing the skills" above |
 | `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.json` | npm package manifest for `remarque-tokens` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "engines": {
     "node": ">=18"
   },
@@ -29,7 +29,8 @@
   },
   "scripts": {
     "audit": "node scripts/audit.mjs",
-    "drift": "node scripts/drift-check.mjs"
+    "drift": "node scripts/drift-check.mjs",
+    "prepack": "node scripts/build-skills.mjs"
   },
   "devDependencies": {
     "@williamzujkowski/oklch-terminal-themes": "0.5.0",
@@ -84,6 +85,8 @@
     "./registry-item.schema.json": "./registry-item.schema.json",
     "./registry.schema.json": "./registry.schema.json",
     "./registry/*": "./registry/*.json",
+    "./skills/remarque": "./skills/remarque/SKILL.md",
+    "./skills/adopt": "./skills/remarque-adopt/SKILL.md",
     "./package.json": "./package.json"
   },
   "files": [
@@ -117,6 +120,9 @@
     "registry-item.schema.json",
     "registry.schema.json",
     "scripts/build-registry.mjs",
-    "scripts/lib/registry-extract.mjs"
+    "scripts/lib/registry-extract.mjs",
+    "skills/",
+    "scripts/build-skills.mjs",
+    "scripts/lib/skills.mjs"
   ]
 }

package/registry/broadsheet.json

@@ -4,7 +4,7 @@
   "type": "remarque:contract",
   "title": "Broadsheet Pattern",
   "description": "The editorial Landing/archive pattern: masthead, lead article, numbered entry list, and post-header kicker. Entry numerals are generated from `data-entry-number` via `attr()`, never `counter()`, and every kicker/dateline row is true `font-variant-caps: all-small-caps`, never `text-transform: uppercase`.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "integrity": "sha256-BZea38PRdob4OfmdGN0eDw3U0adl7SEsdrjKgSewK9A=",
   "dependencies": [
     "remarque-tokens"

package/registry/essay.json

@@ -4,7 +4,7 @@
   "type": "remarque:contract",
   "title": "Essay Module",
   "description": "Sidenotes + sticky TOC rail for long-form Essay pages: margin notes relocated into real DOM order, right after the paragraph that cites them, numbered by CSS counter and labeled `aria-label=\"Note N\"` in the same order the counter advances — the mechanism that prevents the sidenote aria-label/DOM-order transcription bug found in the flagship migration (#89, williamzujkowski.github.io#380).",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "integrity": "sha256-zr04H0+0xf01OWLk6B2A9ziZOYJd4Sq5q5/cib65lbU=",
   "dependencies": [
     "remarque-tokens"

package/registry/forms.json

@@ -4,7 +4,7 @@
   "type": "remarque:contract",
   "title": "Forms Primitives",
   "description": "Native field/input/checkbox/radio/button primitives with state-color wiring. Every `.remarque-input` pairs `for`/`id` with its `.remarque-field-label`, and every `.remarque-field-message` is wired via `aria-describedby` on the control — the paint-layer `data-state` attribute is never the only signal; `aria-invalid`/`aria-describedby` on the input carry the real accessibility contract.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "integrity": "sha256-WfYjcf04Dxxx7X21U5b6DrY90Qw95p0zkCQszoh77tE=",
   "dependencies": [
     "remarque-tokens"

package/registry/palette-deck.json

@@ -4,7 +4,7 @@
   "type": "remarque:contract",
   "title": "Palette Deck (markup contract only — no executable content)",
   "description": "Markup/wiring contract for the Palette Deck: set `data-palette` on the same root element as `data-theme` and the two compose independently. This item ships ONLY that HTML fragment. `deck.js` — the runtime module itself, a dependency-free ~60-line ESM file — is deliberately NOT embedded here: the registry’s blocking no-executable-content condition is held to an unambiguous zero-`<script>`-tag bar across every item, so neither `deck.js` nor the FOUC-restore `<script>` sample documented alongside it in REMARQUE.md is included. Consume `deck.js` the normal way, via the `remarque-tokens/deck` package import (`dependencies` below); read the FOUC-restore snippet from the `docs` URL.",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "integrity": "sha256-WGgBZ2j0VnLPRAZlzv/4G1Wu9rKqTdXf1536dWWu8nU=",
   "dependencies": [
     "remarque-tokens"

package/registry.json

@@ -2,14 +2,14 @@
   "$schema": "https://williamzujkowski.github.io/remarque/registry.schema.json",
   "name": "remarque-tokens",
   "homepage": "https://williamzujkowski.github.io/remarque/",
-  "version": "0.24.0",
+  "version": "0.25.0",
   "items": [
     {
       "name": "essay",
       "type": "remarque:contract",
       "title": "Essay Module",
       "description": "Sidenotes + sticky TOC rail for long-form Essay pages: margin notes relocated into real DOM order, right after the paragraph that cites them, numbered by CSS counter and labeled `aria-label=\"Note N\"` in the same order the counter advances — the mechanism that prevents the sidenote aria-label/DOM-order transcription bug found in the flagship migration (#89, williamzujkowski.github.io#380).",
-      "version": "0.24.0",
+      "version": "0.25.0",
       "integrity": "sha256-zr04H0+0xf01OWLk6B2A9ziZOYJd4Sq5q5/cib65lbU=",
       "file": "registry/essay.json"
     },
@@ -18,7 +18,7 @@
       "type": "remarque:contract",
       "title": "Broadsheet Pattern",
       "description": "The editorial Landing/archive pattern: masthead, lead article, numbered entry list, and post-header kicker. Entry numerals are generated from `data-entry-number` via `attr()`, never `counter()`, and every kicker/dateline row is true `font-variant-caps: all-small-caps`, never `text-transform: uppercase`.",
-      "version": "0.24.0",
+      "version": "0.25.0",
       "integrity": "sha256-BZea38PRdob4OfmdGN0eDw3U0adl7SEsdrjKgSewK9A=",
       "file": "registry/broadsheet.json"
     },
@@ -27,7 +27,7 @@
       "type": "remarque:contract",
       "title": "Forms Primitives",
       "description": "Native field/input/checkbox/radio/button primitives with state-color wiring. Every `.remarque-input` pairs `for`/`id` with its `.remarque-field-label`, and every `.remarque-field-message` is wired via `aria-describedby` on the control — the paint-layer `data-state` attribute is never the only signal; `aria-invalid`/`aria-describedby` on the input carry the real accessibility contract.",
-      "version": "0.24.0",
+      "version": "0.25.0",
       "integrity": "sha256-WfYjcf04Dxxx7X21U5b6DrY90Qw95p0zkCQszoh77tE=",
       "file": "registry/forms.json"
     },
@@ -36,7 +36,7 @@
       "type": "remarque:contract",
       "title": "Palette Deck (markup contract only — no executable content)",
       "description": "Markup/wiring contract for the Palette Deck: set `data-palette` on the same root element as `data-theme` and the two compose independently. This item ships ONLY that HTML fragment. `deck.js` — the runtime module itself, a dependency-free ~60-line ESM file — is deliberately NOT embedded here: the registry’s blocking no-executable-content condition is held to an unambiguous zero-`<script>`-tag bar across every item, so neither `deck.js` nor the FOUC-restore `<script>` sample documented alongside it in REMARQUE.md is included. Consume `deck.js` the normal way, via the `remarque-tokens/deck` package import (`dependencies` below); read the FOUC-restore snippet from the `docs` URL.",
-      "version": "0.24.0",
+      "version": "0.25.0",
       "integrity": "sha256-WGgBZ2j0VnLPRAZlzv/4G1Wu9rKqTdXf1536dWWu8nU=",
       "file": "registry/palette-deck.json"
     }

package/scripts/build-skills.mjs

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+/*
+ * Packages the canonical Claude Code skills for npm distribution.
+ *
+ *   node scripts/build-skills.mjs          # (re)write skills/<name>/SKILL.md
+ *   node scripts/build-skills.mjs --check  # exit 1 if any packaged copy is stale (CI)
+ *
+ * `.claude/skills/<name>/SKILL.md` is the ONE hand-authored copy (also
+ * what a Claude Code session working in this repo reads directly, no
+ * indirection). This script copies it byte-for-byte into `skills/<name>/
+ * SKILL.md`, the location published in the npm tarball (package.json
+ * "files" + the "./skills/remarque" / "./skills/adopt" exports) — the
+ * same single-source-of-truth-plus-generated-copy relationship
+ * tokens.json has to tokens-core.css/tokens-palette.css (scripts/
+ * tokens-json.mjs --check), kept fresh by the same convention: run this
+ * script whenever a canonical SKILL.md changes, --check gates CI so a
+ * stale packaged copy can't ship silently.
+ */
+
+import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { SKILLS } from './lib/skills.mjs';
+
+const CHECK = process.argv.includes('--check');
+let bad = 0;
+
+for (const { name, canonical, packaged } of SKILLS) {
+  if (!existsSync(canonical)) {
+    console.error(`✗ ${name}: canonical file missing: ${canonical}`);
+    bad++;
+    continue;
+  }
+  const src = readFileSync(canonical, 'utf8');
+
+  if (CHECK) {
+    const current = existsSync(packaged) ? readFileSync(packaged, 'utf8') : null;
+    if (current === src) {
+      console.log(`✓ ${packaged} is fresh (matches ${canonical})`);
+    } else {
+      console.error(`✗ ${packaged} is STALE vs ${canonical} — run \`node scripts/build-skills.mjs\` and commit the result`);
+      bad++;
+    }
+    continue;
+  }
+
+  mkdirSync(dirname(packaged), { recursive: true });
+  writeFileSync(packaged, src);
+  console.log(`wrote ${packaged} (from ${canonical})`);
+}
+
+if (bad) {
+  console.error(`\nbuild-skills ${CHECK ? '--check' : ''} FAILED — ${bad} issue(s)`);
+  process.exit(1);
+}
+if (!CHECK) console.log('\nskills/ packaging copies up to date.');

package/scripts/lib/skills.mjs

@@ -0,0 +1,66 @@
+/*
+ * Shared table + tiny helpers for the two Claude Code skills this package
+ * ships and packages — used by scripts/build-skills.mjs (prepack copy +
+ * CI freshness gate) and scripts/test-skills.mjs (content validation).
+ *
+ * `.claude/skills/<name>/SKILL.md` is the ONE canonical, hand-authored
+ * copy of each skill (also what a local Claude Code session in this repo
+ * reads directly). `skills/<name>/SKILL.md` is a generated packaging
+ * copy — same relationship tokens.json has to the CSS tiers: one source
+ * of truth, a derived artifact kept fresh by a --check gate, never
+ * hand-edited independently.
+ */
+
+export const SKILLS = [
+  {
+    name: 'remarque',
+    canonical: '.claude/skills/remarque/SKILL.md',
+    packaged: 'skills/remarque/SKILL.md',
+    exportName: './skills/remarque',
+  },
+  {
+    name: 'remarque-adopt',
+    canonical: '.claude/skills/remarque-adopt/SKILL.md',
+    packaged: 'skills/remarque-adopt/SKILL.md',
+    exportName: './skills/adopt',
+  },
+];
+
+/*
+ * Minimal frontmatter reader — enough to check required keys are present
+ * and non-empty. Handles the one YAML shape these files actually use:
+ * plain `key: value` scalars, and a folded block scalar (`key: >`)
+ * followed by indented continuation lines, which is how both skills
+ * author their (long) `description` field.
+ */
+export function readFrontmatter(text) {
+  const m = text.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+  if (!m) return null;
+  const lines = m[1].split(/\r?\n/);
+  const fm = {};
+  let currentKey = null;
+  let buf = [];
+  const flush = () => {
+    if (currentKey) fm[currentKey] = buf.join(' ').trim();
+    buf = [];
+  };
+  for (const line of lines) {
+    const kv = line.match(/^([a-zA-Z0-9_-]+):\s*(.*)$/);
+    if (kv) {
+      flush();
+      currentKey = kv[1];
+      const rest = kv[2].trim();
+      if (rest === '>' || rest === '|' || rest === '>-' || rest === '|-') {
+        buf = [];
+      } else {
+        buf = rest ? [rest] : [];
+        flush();
+        currentKey = null;
+      }
+    } else if (currentKey && /^\s+\S/.test(line)) {
+      buf.push(line.trim());
+    }
+  }
+  flush();
+  return fm;
+}

package/skills/remarque/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: remarque
+description: >
+  Load the Remarque design system's implementation contract before building,
+  editing, or reviewing any page in a Remarque-based project — a
+  typography-first system for editorial, technical, and personal sites (17px
+  body floor, three-font system, four-then-seven page archetypes, strict
+  token tiers). Use when the user says "remarque", "design system", "build a
+  new page", "new archetype page", "style this like the site", or asks for
+  a page/component in a project that imports `remarque-tokens`. Also use
+  before reviewing a PR that touches design-system tokens or page layout in
+  such a project.
+license: MIT
+---
+
+# Remarque
+
+Remarque is a typography-first design system. This skill tells you which
+files define it, how to load them, and the two mistakes that cause the most
+downstream breakage.
+
+## Load these three files before writing or reviewing any page
+
+Prefer the installed package if this project depends on `remarque-tokens`;
+fall back to the repo root if you are working inside `williamzujkowski/remarque`
+itself.
+
+| File | Where (consumer project) | Where (this repo) | Purpose |
+|---|---|---|---|
+| `AGENT_RULES.md` | `node_modules/remarque-tokens/AGENT_RULES.md` (or `remarque-tokens/agent-rules`) | `./AGENT_RULES.md` | Implementation contract — build order, non-negotiable rules, disallowed patterns, quality checklist |
+| `REMARQUE.md` | `node_modules/remarque-tokens/REMARQUE.md` (or `remarque-tokens/spec`) | `./REMARQUE.md` | Full specification — philosophy, token tiers, page archetypes, acceptance criteria |
+| `tokens.json` | `node_modules/remarque-tokens/tokens.json` (or `remarque-tokens/tokens.json`) | `./tokens.json` | Machine-readable token values (both themes) — read this instead of guessing a hex/oklch value from memory |
+
+Read all three before generating code. `AGENT_RULES.md` says *how to build*;
+`REMARQUE.md` says *what the system is*; `tokens.json` says *what the
+current values actually are* — don't trust training data for token values,
+the CSS (and this generated file) is the single source of truth and it
+changes across releases.
+
+## Tier rules (non-negotiable)
+
+Tokens live in two tiers with different contracts — get this wrong and the
+project has silently forked the system:
+
+- **Core** (`tokens-core.css`): type scale, the 17px body floor, line
+  heights, tracking, weights, spacing scale, `--content-standard` /
+  `--content-wide`, radius ceiling, motion durations, prose/typography
+  machinery. **Never overridden.** A project that changes a core value is
+  no longer a Remarque project, by definition.
+- **Palette** (`tokens-palette.css`): font slots (`--font-display/body/mono`
+  — from the approved pairings only), all `--color-*`, `--content-reading`
+  (the measure, which moves with the body font). **Override freely** in a
+  stylesheet loaded after the tokens — this is the sanctioned
+  personalization surface.
+
+Every page must also map to one of the seven archetypes (Essay, Project
+Dossier, Notebook, Landing, Reference/Docs, Changelog, Gallery) — see
+`REMARQUE.md`'s "Page Archetypes" section. Do not invent an eighth.
+
+## Audit command (run after any palette change)
+
+- Inside this repo: `npm run audit`
+- Inside a consumer project: `npx remarque-audit --palette <file> --src <dir>`
+
+A palette change that doesn't pass the audit does not ship — contrast,
+gamut, font-size floors, and hardcoded-color checks are mechanical gates,
+not suggestions.
+
+## Pitfalls #6 and #7 (the two that cause silent, buildable breakage)
+
+These pass a normal build with no error and no warning, so verify them
+explicitly rather than trusting a green build:
+
+**#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 any import.
+
+**#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 — again, with no build error.
+
+## When you're unsure
+
+Apply `REMARQUE.md`'s decision protocol in order: more readable > more
+typographically disciplined > quieter > more tokenized/reusable > less
+visual noise. If still unsure, choose the option that looks more like a
+well-typeset book and less like a web application.

package/skills/remarque-adopt/SKILL.md

@@ -0,0 +1,124 @@
+---
+name: remarque-adopt
+description: >
+  Run the remarque-tokens consumer-conformance playbook — the exact
+  procedure for bumping a project's remarque-tokens pin and getting back
+  to a passing audit. Use when the user says "bump remarque-tokens",
+  "upgrade the design system", "adopt remarque in an existing site",
+  "update to the latest remarque-tokens", or when `remarque-audit`/`npm
+  run audit` starts failing after a version bump (missing-token
+  failures). Distinct from the `remarque` skill, which is the
+  build/review contract for pages already on the current version — load
+  this one specifically for the migration itself, then defer to
+  `remarque` for any actual page work the migration surfaces.
+license: MIT
+---
+
+# remarque-adopt
+
+Five steps, each ending in a machine gate. This codifies the playbook run
+across williamzujkowski.github.io#381, tsundoku#243/#237, and
+remarque-starter#7/#8 — read one of those PR bodies for the fullest worked
+example if a step below is unclear.
+
+## 1. Bump the pin
+
+Bump `remarque-tokens` in `package.json`, install, then **verify the
+RESOLVED version, not the range you typed.** This package is pre-1.0:
+caret ranges (`^0.NN.0`) never cross a minor below 1.0 (npm's own rule —
+`^0.24.0` means `>=0.24.0 <0.25.0`), so a stale `^0.1x.0` pin silently
+freezes a site for dozens of releases (remarque-starter#7 was frozen at
+0.10.x through 0.18.0). Bump the pin's own minor to the target, don't
+just re-run install against the old range.
+
+- Gate: `npm ls remarque-tokens` (or your lockfile) shows the exact
+  target version resolved — not just "install succeeded." A
+  lockfile-verified install (`npm ci` after committing the lockfile
+  change, not a bare `npm install` you never diff) is the acceptance;
+  see the panel's security condition in AGENT_RULES.md.
+
+## 2. Discover what's newly required — mechanically
+
+Do not read the CHANGELOG and guess which tokens are new. Run the audit
+against the site's current palette and let it tell you:
+
+```
+npx remarque-audit --palette <your-palette-file> --src <dir> --json
+```
+
+Parse `failures` (and `srcScans`) from the JSON — every missing/failing
+token family the new version requires shows up here. See
+AGENT_RULES.md's "Machine-Readable Output" for the full shape.
+
+- Gate: you have a concrete list of failing checks, not an impression
+  from prose.
+
+## 3. Add the missing tokens — solved against THIS site's backgrounds
+
+Start from the package's own default values (`tokens-palette.css` /
+`tokens.json` in the target version) and add them to every theme block
+the site's palette maintains. **Keep-if-passing:** if a default value
+already clears its required ratio against *this site's own*
+`--color-bg`/`--color-surface`/`--color-code-bg` (not the package demo's),
+keep it verbatim — most slots need no change at all (tsundoku#237: 16 of
+16 new tokens were the package default byte-for-byte). Only re-solve a
+value when the site's own backgrounds make the default fail (flagship#381:
+1 of 13 tokens needed a new lightness because that site's surface sits
+closer to its bg than the package demo's does).
+
+**Hue collisions are a second, distinct failure mode from contrast** —
+check for them even when contrast passes. A new categorical/state hue can
+land visually on top of a site's own accent or another semantic color.
+Worked example, tsundoku#243: the default viz "red" (H24.6 light / H25.4
+dark) sat almost on top of both tsundoku's terracotta accent (H35) and its
+`--color-error` (H25/H26) — a chart category would have read as "the
+accent" or "an error." Rotated to H350 (rose-red) in each theme
+independently, re-solving lightness to hold the same contrast band the
+untouched slots hit.
+
+- **Acceptance is pinned to the audit output, not agent judgment.** This
+  step ends when:
+  ```
+  npx remarque-audit --palette <file> --src <dir> --json
+  ```
+  reports `passed: true`. Not "looks close," not "should be fine" — the
+  JSON's `passed` field, checked.
+
+## 4. Run the drift check
+
+```
+npx remarque-drift --css-file <your-palette-file> --package-dir . --json
+```
+
+Classify every record per REMARQUE.md "Token Tiers" / AGENT_RULES.md
+"Machine-Readable Output":
+
+| Class | Tier | Meaning | Action |
+|---|---|---|---|
+| `fail` | core | Undocumented core-tier override — the site has forked Remarque | Fix: revert to the core value (never ship a FAIL) |
+| `warn` | core | Core-tier override, but the token name is mentioned in a `DESIGN-DEVIATIONS.md`/`DESIGN-NOTES.md` in the consumer | Ratified, documented deviation — not a build failure, but still surfaced |
+| `info` | palette | Palette-tier divergence from the package default | Sanctioned personalization — expected, not an error |
+
+Any new palette-tier value from step 3 that differs from the package
+default (the tsundoku hue rotation, the flagship lightness re-solve) will
+show up as `info` — that's correct, not a regression. If a value must
+diverge from a *core*-tier token (rare, and usually means step 3 touched
+the wrong tier), record it under a `--token-name` heading in the
+project's `DESIGN-DEVIATIONS.md` (or `DESIGN-NOTES.md`) *before* running
+drift again, so it reclassifies from `fail` to `warn`.
+
+- Gate: `passed: true` (zero `fail` records). `warn`/`info` never block.
+
+## 5. PR body contract
+
+Report, in this order — every consumer PR in the source list follows this
+shape:
+
+1. **What changed** — old pin → new pin, which token families were added and why (which version introduced the audit requirement).
+2. **Token decisions** — a table of any value that needed solving (not kept-as-default), with the before/after values and the contrast numbers that justified the change. Note any hue collision found and how it was resolved, even if unrelated to contrast.
+3. **Drift summary** — the `summary: {fail, warn, info}` counts, with a one-line explanation of any non-zero `warn`.
+4. **Gate results** — the project's own full local suite (typecheck/tests/build) plus this playbook's two gates (audit `passed: true`, drift `fail: 0`), each stated as pass/fail, not just "ran."
+5. **Anything explicitly declined** — a new token family evaluated but not adopted into existing UI (tsundoku#243 declined recoloring an ordinal chart with new categorical hues), or a related upgrade opportunity noted but out of scope for this bump.
+
+If any of steps 2-4's gates don't pass, the PR isn't ready — this
+playbook has no "close enough."

package/tokens.d.ts

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

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