remarque-tokens 0.19.0 → 0.20.0

package/AGENT_RULES.md

@@ -227,6 +227,91 @@ Before considering any implementation complete, verify:
 
 ---
 
+## Machine-Readable Output
+
+Two tools emit structured JSON for agents/tooling instead of colored
+stdout — pass `--json` and parse stdout as a single JSON document. Exit
+codes are unchanged in both cases; `--json` only changes what stdout
+contains (all human progress lines, including error lines normally on
+stderr, are suppressed — nothing but the JSON document is written).
+
+### `remarque-audit --json`
+
+```
+node scripts/audit.mjs --palette <file> --src <dir> --json
+npx remarque-audit --palette <file> --src <dir> --json
+```
+
+```ts
+{
+  version: string;       // the remarque-tokens package version running the audit
+  palette: string;       // the --palette path as given
+  src: string;            // the --src path as given
+  passed: boolean;       // true iff failures.length === 0
+  contrast: Array<{
+    theme: 'light' | 'dark';
+    fg: string;            // fg token name, no leading --
+    bg: string;            // bg token name, no leading --
+    label: string;         // human label from the CHECKS table (e.g. "primary text")
+    required: number;      // minimum ratio (e.g. 4.5, 7.0, 3.0)
+    actual: number | null; // computed ratio rounded to 2dp, or null if fg/bg was unresolvable
+    ok: boolean;
+    error?: string;        // present only when actual is null (unresolved var()/missing token)
+  }>;
+  gamut: Array<{
+    theme: 'light' | 'dark';
+    token: string;          // token name, no leading --
+    value: string;          // e.g. "oklch(0.5 0.14 250)"
+    ok: boolean;            // false = outside sRGB gamut (browsers will clip it)
+  }>;
+  srcScans: {
+    fontFloor: Array<{ file: string; line: number; size: number; unit: 'rem' | 'px' }>;
+    unverifiableFontSize: Array<{ file: string; line: number; snippet: string }>;
+    hardcodedColors: Array<{ file: string; line: number; snippet: string }>;
+    oklchLiteral: Array<{ file: string; line: number; snippet: string }>;
+  };
+  failures: string[];      // every failure as a human-readable message, same text the non-JSON run prints
+}
+```
+
+`contrast` and `gamut` list EVERY check performed (passing and failing);
+only `srcScans` and `failures` are violation-only lists, since a source
+scan that finds nothing has nothing to report per line.
+
+### `remarque-drift --json`
+
+```
+node scripts/drift-check.mjs --css-file <path> --package-dir <dir> --json
+npx remarque-drift --css-file <path> --package-dir <dir> --json
+```
+
+```ts
+{
+  cssFile: string;
+  packageDir: string;          // resolved node_modules/remarque-tokens path
+  installedVersion: string;    // version of the INSTALLED remarque-tokens being checked against
+  deviationDoc: string | null; // path to DESIGN-DEVIATIONS.md / DESIGN-NOTES.md, or null if none found
+  passed: boolean;             // true iff fail.length === 0
+  fail: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
+  warn: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string; doc: string }>;
+  info: Array<{ name: string; theme: 'light' | 'dark'; canonical: string; value: string }>;
+  summary: { fail: number; warn: number; info: number }; // counts of distinct TOKENS with an entry, not records (one token can produce two records — light + dark)
+}
+```
+
+`fail`/`warn`/`info` are one record per (token, theme) mismatch — see
+`scripts/drift-check.mjs`'s doc comment and REMARQUE.md's "Token Tiers"
+for the FAIL/WARN/INFO classification these mirror.
+
+### `tokens.json` / `tokens.schema.json`
+
+`remarque-tokens/tokens.json` is always machine-readable (no flag
+needed) and now ships with a published JSON Schema — see REMARQUE.md
+"DTCG Conformance" for the schema's location, the `$schema` pointer, and
+the documented DTCG divergences.
+
+---
+
 ## How to Reference This System
 
 In prompts, issues, or agent instructions, use:

package/CHANGELOG.md

@@ -4,6 +4,18 @@ 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.20.0 — 2026-07-23
+
+Machine-readable surface: `--json` for `remarque-audit`/`remarque-drift`, and a published JSON Schema for `tokens.json` (closes #98, closes #99).
+
+### Added
+- **`--json` on `remarque-audit`** (issue #98). Suppresses all human console output (both the progress lines and the error lines normally on stderr) and emits ONE JSON document to stdout instead — exit codes unchanged. Shape: `{ version, palette, src, passed, contrast: [{theme,fg,bg,label,required,actual,ok,error?}], gamut: [{theme,token,value,ok}], srcScans: {fontFloor,unverifiableFontSize,hardcodedColors,oklchLiteral}, failures: [] }`. `contrast`/`gamut` list every check performed (pass and fail); `srcScans`/`failures` are violation-only. Documented in `AGENT_RULES.md` ("Machine-Readable Output") — agents are the intended audience, parsing structure instead of scraping colored stdout.
+- **`--json` on `remarque-drift`** (issue #98). Same suppression contract; emits `{ cssFile, packageDir, installedVersion, deviationDoc, passed, fail: [], warn: [], info: [], summary: {fail,warn,info} }` — one record per (token, theme) mismatch, mirroring the FAIL/WARN/INFO classification the human report already prints.
+- **`tokens.schema.json`** (issue #99). JSON Schema (draft 2020-12) describing `tokens.json`'s actual shape, generated by `scripts/tokens-json.mjs` in the same pass as `tokens.json`/`tokens.d.ts`, same `--check` freshness gate. Token *names* are open (`patternProperties` on the kebab-case grammar); the `$value`/`$type`/light-dark VALUE shapes are fixed. Published as the `remarque-tokens/tokens.schema.json` export, shipped in `files`, and served by the demo site at `/tokens.schema.json` (alongside the existing `/tokens.json`) via an extended `site/scripts/copy-tokens-json.mjs` — shadcn's schema-URL precedent. `tokens.json` now carries a `"$schema"` pointer to that URL.
+- **DTCG conformance note** (issue #99, ratified option ii). `tokens.json`'s `$extensions.remarque.dtcg` documents that the file is conformant in spirit with the Design Tokens Community Group format (`$value`/`$type` on every token) with two **deliberate** divergences — color values as `oklch()` CSS strings (not DTCG's structured color object) and per-token `light`/`dark` nesting (DTCG has no ratified multi-mode/resolver mechanism yet) — each with a named ratification trigger, so a future agent can't "fix" `tokens.json` toward an unratified target. Same argument restated for humans in REMARQUE.md's new "DTCG Conformance" section (under "Token Tiers").
+- **Schema validation in CI** (`scripts/test-types.mjs`). Real JSON-Schema validation of `tokens.json` against `tokens.schema.json` via `ajv` (new devDependency, pinned to a version with zero known advisories; the `$data` option that the one applicable ajv CVE requires is never used) — plus three negative fixtures (unknown `$extensions` key, invalid `$type` enum value, missing required `dark` side) proving the schema actually rejects malformed input rather than accepting anything.
+- **`--json` fixture coverage** (`scripts/test-audit.mjs`, `scripts/test-drift.mjs`). Parses the JSON output of a passing and a must-fail fixture for each tool; asserts the documented shape and that the must-fail fixture's offending pairing/token is actually present with `ok`/`passed: false`.
+
 ## 0.19.0 — 2026-07-23
 
 Palette Deck module (closes #56).

package/README.md

@@ -44,6 +44,8 @@ Copy the `fonts/` woff2 files from `node_modules/remarque-tokens/fonts/` into yo
 npx remarque-audit --palette src/styles/my-palette.css --src src
 ```
 
+Add `--json` to either `remarque-audit` or `remarque-drift` for a single structured JSON document on stdout instead of colored console output (exit codes unchanged) — for agents and CI tooling to parse rather than scrape. Shape documented in `AGENT_RULES.md` ("Machine-Readable Output").
+
 **Tailwind v4** projects add the shipped adapter — utilities that track the tokens through every theme switch, no value duplication:
 
 ```css
@@ -52,7 +54,7 @@ npx remarque-audit --palette src/styles/my-palette.css --src src
 @import "remarque-tokens/theme.css";
 ```
 
-**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).
+**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, with a published JSON Schema at `remarque-tokens/tokens.schema.json` (also referenced by tokens.json's own `$schema` field) so tooling can validate it structurally instead of hand-parsing. tokens.json is conformant in spirit with the [Design Tokens Community Group](https://www.designtokens.org/) format (`$value`/`$type` on every token), with two deliberate divergences — see REMARQUE.md's "DTCG Conformance" section. 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
 
@@ -68,7 +70,7 @@ 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.
-- **Live tokens endpoint:** the demo site serves the current `tokens.json` at **https://williamzujkowski.github.io/remarque/tokens.json** — a remote agent can fetch current token values directly instead of trusting training data.
+- **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.
 
 ## Files
 
@@ -80,7 +82,10 @@ Packaging for agent tooling:
 | `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 |
+| `scripts/audit.mjs` | `npm run audit` — enforces the spec's contrast/gamut/font-floor/no-hardcoded-color checklist (`--json` for structured output) |
+| `scripts/drift-check.mjs` | `npx remarque-drift` — token drift check for consumers (`--json` for structured output) |
+| `tokens.json` + `tokens.d.ts` | Generated machine-readable token inventory + TypeScript types (`scripts/tokens-json.mjs`) |
+| `tokens.schema.json` | Generated JSON Schema (draft 2020-12) for `tokens.json`, published alongside it |
 | `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/REMARQUE.md

@@ -68,6 +68,17 @@ Package subpaths for consumers: `remarque-tokens` (aggregator), `remarque-tokens
 
 This makes compliance mechanical: a site that overrides only palette-tier tokens is *authored*; one that touches core-tier tokens has *forked*. `tokens.css` imports both tiers, so existing consumers are unaffected.
 
+### DTCG Conformance
+
+`tokens-core.css` and `tokens-palette.css` remain the single source of truth; `scripts/tokens-json.mjs` regenerates `tokens.json`, `tokens.d.ts`, and `tokens.schema.json` from them in one pass (`node scripts/tokens-json.mjs`; `--check` gates CI freshness). `tokens.json` carries a `$schema` pointer to the published schema (served by the demo site at `/tokens.schema.json`, alongside `/tokens.json` — also exported as `remarque-tokens/tokens.schema.json`).
+
+`tokens.json` is **conformant in spirit** with the [Design Tokens Community Group (DTCG)](https://www.designtokens.org/) format — every token carries `$value`/`$type` — with two **deliberate** structural divergences, documented in the generated file itself (`$extensions.remarque.dtcg`) so a future regeneration can't lose the rationale:
+
+1. **Color values are `oklch()` CSS strings**, not the DTCG structured color object (`{ colorSpace, components, alpha }`). Remarque's color pipeline (audit, drift-check, `remarque-theme`) is built entirely on parsing/emitting `oklch(L C H)` strings; adopting the structured form would mean carrying two color representations in parallel for no present benefit. **Gated on:** the DTCG color `$type` structured-value format ratifying.
+2. **Palette-tier tokens nest per-token `light`/`dark` groups**, each with its own `$value`, rather than a single `$value` plus a modes/resolver mechanism. The DTCG spec has no ratified multi-mode/theming primitive yet; this repo's own theming (`@media (prefers-color-scheme: dark)`, `[data-theme="dark"]`, the Palette Deck's `[data-palette]` scoping) predates any such draft. **Gated on:** the DTCG multi-mode / resolver draft ratifying.
+
+Full DTCG conformance is gated on those two drafts ratifying — a named, checkable trigger, not "someday." Until then, do not "fix" `tokens.json` toward either unratified draft; the CSS is the source of truth, and both divergences are load-bearing for the tooling that already depends on this shape.
+
 ---
 
 ## Color Providers
@@ -706,7 +717,8 @@ for the value-by-value mapping).
     <h2 id="section-one">Section One</h2>
     <p>
       A claim worth a citation<a href="#note-1" id="note-1-ref"
-        class="remarque-sidenote-ref" aria-describedby="note-1"></a>.
+        class="remarque-sidenote-ref" aria-label="Note 1"
+        aria-describedby="note-1"></a>.
     </p>
     <aside class="remarque-sidenote" id="note-1" role="note">
       The note text, in real DOM order right after the paragraph that
@@ -729,6 +741,13 @@ Requirements the CSS depends on:
   `.remarque-sidenote` after it; later citations of the same note use
   `.remarque-sidenote-ref--repeat` (styled identically, does not advance
   the counter) so the shared numbering doesn't skip.
+- `aria-label="Note N"` on every `.remarque-sidenote-ref`, numbered in
+  the same order the CSS counter advances — the ref's visible digit is
+  counter-generated, so the anchor itself has no text content, and an
+  empty focusable link with no accessible name fails WCAG 4.1.2 / 2.4.4
+  (axe: `link-name`). Because both the label and the counter derive from
+  DOM order, they cannot drift apart. (Found in the flagship's migration,
+  williamzujkowski.github.io#380.)
 - `role="note"` on every `.remarque-sidenote` — `<aside>`'s implicit role
   is `complementary`, a landmark; an essay with several notes would
   otherwise scatter that many unlabeled landmark regions through the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.19.0",
+  "version": "0.20.0",
   "engines": {
     "node": ">=18"
   },
@@ -33,6 +33,7 @@
   },
   "devDependencies": {
     "@williamzujkowski/oklch-terminal-themes": "0.4.0",
+    "ajv": "^8.20.0",
     "culori": "^4.0.2"
   },
   "peerDependencies": {
@@ -64,6 +65,7 @@
       "default": "./tokens.json"
     },
     "./tokens.d.ts": "./tokens.d.ts",
+    "./tokens.schema.json": "./tokens.schema.json",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
     "./print": "./print.css",
@@ -97,6 +99,7 @@
     "theme.css",
     "tokens.json",
     "tokens.d.ts",
+    "tokens.schema.json",
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",

package/scripts/audit.mjs

@@ -2,7 +2,7 @@
 /*
  * remarque audit — enforces REMARQUE.md's checklist mechanically.
  *
- *   node scripts/audit.mjs [--palette tokens-palette.css] [--src <dir>]
+ *   node scripts/audit.mjs [--palette tokens-palette.css] [--src <dir>] [--json]
  *   npx remarque-audit --palette your-palette.css --src src
  *
  * Checks (exit 1 on any failure):
@@ -19,6 +19,11 @@
  *   2. FONT FLOOR — no font-size declaration below 0.8125rem / 13px in src.
  *   3. NO HARDCODED COLORS — no hex/rgb()/hsl() literals in src styles;
  *      oklch() literals are allowed only in token files.
+ *
+ * --json: suppresses all human console output and emits ONE JSON document
+ * to stdout instead (exit codes unchanged) — for agents/tooling to parse
+ * instead of scraping colored stdout. Shape documented in AGENT_RULES.md
+ * ("Machine-Readable Output — remarque-audit --json").
  */
 
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
@@ -33,11 +38,35 @@ function argOf(flag, dflt) {
 }
 const PALETTE = argOf('--palette', 'tokens-palette.css');
 const SRC = argOf('--src', existsSync('site/src') ? 'site/src' : '.');
+const JSON_MODE = args.includes('--json');
+
+// The audit's OWN package version (this script's remarque-tokens, resolved
+// via import.meta.url so it is correct whether run in this repo or as
+// npx remarque-audit from a consumer's node_modules/remarque-tokens) —
+// not the consumer project's package.json.
+const PKG_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+const PKG_VERSION = JSON.parse(readFileSync(join(PKG_ROOT, 'package.json'), 'utf8')).version;
+
+const report = {
+  version: PKG_VERSION,
+  palette: PALETTE,
+  src: SRC,
+  passed: false,
+  contrast: [],
+  gamut: [],
+  srcScans: { fontFloor: [], unverifiableFontSize: [], hardcodedColors: [], oklchLiteral: [] },
+  failures: [],
+};
+
+function log(...a) {
+  if (!JSON_MODE) console.log(...a);
+}
 
 let failures = 0;
 function fail(msg) {
   failures++;
-  console.error(`  ✗ ${msg}`);
+  report.failures.push(msg);
+  if (!JSON_MODE) console.error(`  ✗ ${msg}`);
 }
 
 if (!existsSync(PALETTE)) {
@@ -48,6 +77,9 @@ if (!existsSync(SRC)) {
   console.error(`src directory not found: ${SRC} (use --src <dir>)`);
   process.exit(1);
 }
+// These two checks are fatal usage errors (exit 1) unrelated to the
+// checked project's compliance, so they print unconditionally even in
+// --json mode — there is no report to emit yet.
 
 /* ── OKLCH → sRGB → WCAG luminance ──────────────────────── */
 
@@ -139,11 +171,14 @@ const CHECKS = [
 ];
 
 for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {
-  console.log(`\n${themeName} theme (${PALETTE})`);
+  log(`\n${themeName} theme (${PALETTE})`);
   // gamut check on every color-valued token
   for (const name of Object.keys(decls)) {
     const r = resolveColor(decls, name);
-    if (r.color && !inGamut(oklchToLinearSrgb(...r.color))) {
+    if (!r.color) continue; // unresolvable tokens are covered by the contrast checks' own error path
+    const ok = inGamut(oklchToLinearSrgb(...r.color));
+    report.gamut.push({ theme: themeName, token: name, value: `oklch(${r.color.join(' ')})`, ok });
+    if (!ok) {
       fail(`--${name} oklch(${r.color.join(' ')}) is outside sRGB gamut — browsers will clip it; author an in-gamut value`);
     }
   }
@@ -151,12 +186,16 @@ for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {
     const fg = resolveColor(decls, fgName);
     const bg = resolveColor(decls, bgName);
     if (fg.err || bg.err) {
+      report.contrast.push({ theme: themeName, fg: fgName, bg: bgName, label, required: min, actual: null, ok: false, error: fg.err || bg.err });
       fail(`${fgName}/${bgName} (${label}): ${fg.err || bg.err}`);
       continue;
     }
     const r = ratio(fg.color, bg.color);
-    if (r < min) fail(`${fgName}/${bgName} = ${r.toFixed(2)}:1 < ${min}:1 (${label})`);
-    else console.log(`  ✓ ${fgName}/${bgName} = ${r.toFixed(2)}:1 (${label})`);
+    const actual = Math.round(r * 100) / 100;
+    const ok = r >= min;
+    report.contrast.push({ theme: themeName, fg: fgName, bg: bgName, label, required: min, actual, ok });
+    if (!ok) fail(`${fgName}/${bgName} = ${r.toFixed(2)}:1 < ${min}:1 (${label})`);
+    else log(`  ✓ ${fgName}/${bgName} = ${r.toFixed(2)}:1 (${label})`);
   }
 }
 
@@ -171,7 +210,7 @@ function* walk(dir) {
   }
 }
 
-console.log(`\nsource scans (${SRC})`);
+log(`\nsource scans (${SRC})`);
 const FONT_FLOOR_REM = 0.8125, FONT_FLOOR_PX = 13;
 // tokens.astro is the token *reference page* — its job is displaying literal
 // values (issue #48 tracks generating it from a machine-readable source).
@@ -198,26 +237,36 @@ for (const file of walk(SRC)) {
     for (const m of line.matchAll(/font-size:\s*([\d.]+)(rem|px)/g)) {
       const v = parseFloat(m[1]);
       if ((m[2] === 'rem' && v < FONT_FLOOR_REM) || (m[2] === 'px' && v < FONT_FLOOR_PX)) {
+        report.srcScans.fontFloor.push({ file: rel, line: i + 1, size: v, unit: m[2] });
         fail(`${rel}:${i + 1} font-size ${m[1]}${m[2]} below the 13px floor`);
       }
     }
     if (!isTokenFile(rel) && /font-size:\s*(clamp\(|[\d.]+%)/.test(line)) {
+      report.srcScans.unverifiableFontSize.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} statically unverifiable font-size (clamp/%) — use var(--text-*) tokens: ${line.trim().slice(0, 80)}`);
     }
     // 3. hardcoded colors (hex / rgb / hsl anywhere; oklch outside token files).
     // Note: hex fills/strokes in inline SVG are flagged deliberately —
     // Remarque icons use currentColor, per the no-hardcoded-colors rule.
     if (/(#[0-9a-fA-F]{3,8}\b(?![0-9a-zA-Z]))|(\brgba?\()|(\bhsla?\()/.test(line) && !/xmlns|href|url\(#|\{#/.test(line)) {
+      report.srcScans.hardcodedColors.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} hardcoded hex/rgb/hsl color: ${line.trim().slice(0, 80)}`);
     }
     if (!isTokenFile(rel) && /\boklch\(/.test(line) && !line.includes('var(--')) {
+      report.srcScans.oklchLiteral.push({ file: rel, line: i + 1, snippet: line.trim().slice(0, 80) });
       fail(`${rel}:${i + 1} oklch() literal outside token files: ${line.trim().slice(0, 80)}`);
     }
   });
 }
 
-if (failures) {
+report.passed = failures === 0;
+
+if (JSON_MODE) {
+  console.log(JSON.stringify(report, null, 2));
+} else if (failures) {
   console.error(`\naudit FAILED — ${failures} problem(s)\n`);
-  process.exit(1);
+} else {
+  console.log('\naudit passed ✓\n');
 }
-console.log('\naudit passed ✓\n');
+
+if (failures) process.exit(1);

package/scripts/drift-check.mjs

@@ -2,7 +2,7 @@
 /*
  * remarque-drift — token drift check for consumers of remarque-tokens.
  *
- *   node scripts/drift-check.mjs --css-file <path> --package-dir <dir>
+ *   node scripts/drift-check.mjs --css-file <path> --package-dir <dir> [--json]
  *   npx remarque-drift --css-file src/styles/global.css --package-dir .
  *
  * Compares a consumer's stylesheet against the INSTALLED remarque-tokens
@@ -27,6 +27,11 @@
  *
  * Exit code: 1 iff there is at least one undocumented (FAIL) core-tier
  * mismatch. WARN and INFO never fail the build.
+ *
+ * --json: suppresses all human console output and emits ONE JSON document
+ * to stdout instead (exit codes unchanged) — records mirror the FAIL/
+ * WARN/INFO classification above. Shape documented in AGENT_RULES.md
+ * ("Machine-Readable Output — remarque-drift --json").
  */
 
 import { readFileSync, existsSync } from 'node:fs';
@@ -41,6 +46,7 @@ function argOf(flag, dflt) {
 
 const CSS_FILE = argOf('--css-file', null);
 const PACKAGE_DIR = resolve(argOf('--package-dir', '.'));
+const JSON_MODE = args.includes('--json');
 
 if (!CSS_FILE) {
   console.error('usage: drift-check.mjs --css-file <path> --package-dir <dir>');
@@ -162,6 +168,27 @@ for (const [name, tok] of Object.entries(tokens.palette || {})) {
 
 /* ── Report ─────────────────────────────────────────────────────────── */
 
+if (JSON_MODE) {
+  // Flatten the internal per-token fails/warns/infos (each may bundle a
+  // light+dark mismatch) into one record per theme mismatch — the FAIL/
+  // WARN/INFO records the human report prints one line per, above.
+  const fail = fails.flatMap((f) => f.mismatches.map((m) => ({ name: f.name, theme: m.theme, canonical: f.canonical, value: m.value })));
+  const warn = warns.flatMap((w) => w.mismatches.map((m) => ({ name: w.name, theme: m.theme, canonical: w.canonical, value: m.value, doc: w.doc })));
+  const info = infos.flatMap((i) => i.diffs.map((d) => ({ name: i.name, theme: d.theme, canonical: d.theme === 'light' ? i.canonicalLight : i.canonicalDark, value: d.value })));
+  console.log(JSON.stringify({
+    cssFile: CSS_FILE,
+    packageDir: PKG_ROOT,
+    installedVersion,
+    deviationDoc: deviationDocPath,
+    passed: fails.length === 0,
+    fail,
+    warn,
+    info,
+    summary: { fail: fails.length, warn: warns.length, info: infos.length },
+  }, null, 2));
+  process.exit(fails.length ? 1 : 0);
+}
+
 console.log('remarque-drift — token drift check');
 console.log(`  consumer stylesheet: ${CSS_FILE}`);
 console.log(`  installed remarque-tokens: ${installedVersion} (${PKG_ROOT})`);

package/scripts/tokens-json.mjs

@@ -1,16 +1,21 @@
 #!/usr/bin/env node
 /*
- * Generates tokens.json (W3C design-tokens flavored) and tokens.d.ts
- * (TypeScript literal-union types) FROM the CSS — tokens-core.css and
- * tokens-palette.css remain the single source of truth; both files
+ * Generates tokens.json (DTCG/W3C design-tokens flavored), tokens.d.ts
+ * (TypeScript literal-union types), and tokens.schema.json (JSON Schema
+ * draft 2020-12 for tokens.json) FROM the CSS — tokens-core.css and
+ * tokens-palette.css remain the single source of truth; all three files
  * here are derived output for tooling, AI agents, and TS editors.
  *
- *   node scripts/tokens-json.mjs           # (re)write tokens.json + tokens.d.ts
- *   node scripts/tokens-json.mjs --check   # exit 1 if either is stale (CI)
+ *   node scripts/tokens-json.mjs           # (re)write tokens.json + tokens.d.ts + tokens.schema.json
+ *   node scripts/tokens-json.mjs --check   # exit 1 if any of the three 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).
+ * (the DTCG/W3C spec has no native theming; this follows its $extensions
+ * escape hatch conservatively). tokens.json is CONFORMANT IN SPIRIT with
+ * the Design Tokens Community Group format ($value/$type on every token)
+ * but has two deliberate divergences — see the `dtcg` block below and
+ * REMARQUE.md's "DTCG Conformance" section for the full rationale and the
+ * named ratification triggers that would close each gap.
  */
 
 import { readFileSync, writeFileSync, existsSync } from 'node:fs';
@@ -37,13 +42,41 @@ function valueFor(type, value) {
   return value;
 }
 
+// Published alongside tokens.json/tokens.schema.json by the demo site
+// (site/scripts/copy-tokens-json.mjs) — issue #99's "shadcn schema-URL
+// precedent". Bump the path only in lockstep with an actual site move.
+const SCHEMA_URL = 'https://williamzujkowski.github.io/remarque/tokens.schema.json';
+
 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);
 
+// DTCG conformance note (issue #99, ratified option ii): documented IN the
+// generated artifact, not just in prose, so a future agent regenerating
+// tokens.json can't lose it. Two deliberate divergences from the Design
+// Tokens Community Group draft, each with a named ratification trigger —
+// full conformance is gated on those drafts landing, not "someday soon."
+const DTCG_NOTE = {
+  conformance: 'partial — $value/$type present on every token (conformant in spirit); two deliberate structural divergences below',
+  divergences: [
+    {
+      aspect: 'color-value-encoding',
+      detail: 'Color $value is an oklch() CSS string, not the DTCG structured color object ({ colorSpace, components, alpha }).',
+      gatedOn: 'DTCG color $type structured-value format ratifying',
+    },
+    {
+      aspect: 'multi-mode-theming',
+      detail: 'Palette-tier tokens nest per-token { light: {$value}, dark: {$value} } groups instead of a single $value plus a modes/resolver mechanism.',
+      gatedOn: 'DTCG multi-mode / resolver draft ratifying',
+    },
+  ],
+  note: 'Deliberate, not oversight — see REMARQUE.md "DTCG Conformance" for the argument. Do not "fix" these toward the current unratified drafts; re-derive from the CSS via scripts/tokens-json.mjs instead.',
+};
+
 const out = {
+  $schema: SCHEMA_URL,
   $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: {
@@ -52,6 +85,7 @@ const out = {
         core: 'immutable identity — overriding forks the system',
         palette: 'sanctioned personalization surface — override freely, then run remarque-audit',
       },
+      dtcg: DTCG_NOTE,
     },
   },
   core: {},
@@ -171,6 +205,7 @@ export interface RemarquePaletteTokenEntry {
  * below applying, etc).
  */
 export interface RemarqueTokensFile {
+  readonly $schema: string;
   readonly $description: string;
   readonly $extensions: {
     readonly remarque: {
@@ -179,6 +214,16 @@ export interface RemarqueTokensFile {
         readonly core: string;
         readonly palette: string;
       };
+      /** DTCG conformance note (issue #99) — see REMARQUE.md "DTCG Conformance". */
+      readonly dtcg: {
+        readonly conformance: string;
+        readonly divergences: ReadonlyArray<{
+          readonly aspect: string;
+          readonly detail: string;
+          readonly gatedOn: string;
+        }>;
+        readonly note: string;
+      };
     };
   };
   readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };
@@ -212,19 +257,155 @@ declare module 'remarque-tokens/tokens.json' {
 
 const dts = renderDts(out, version);
 
+/* ── tokens.schema.json ────────────────────────────────────────────────
+ * JSON Schema draft 2020-12 describing tokens.json's ACTUAL shape —
+ * generated (not hand-maintained) so it can never drift from what this
+ * script emits. Token *names* are open (patternProperties on the
+ * kebab-case grammar every generated name follows) rather than an
+ * enumerated list of the current token set, so adding/removing a token
+ * in the CSS doesn't require a schema edit — only its documented VALUE
+ * shape ($value/$type, the light/dark palette grouping, the $extensions
+ * escape hatches) is fixed.
+ */
+function renderSchema() {
+  const kebabName = '^[a-z][a-z0-9-]*$';
+  const scalarValue = { oneOf: [{ type: 'string' }, { type: 'number' }] };
+  return {
+    $schema: 'https://json-schema.org/draft/2020-12/schema',
+    $id: SCHEMA_URL,
+    title: 'Remarque design tokens (tokens.json)',
+    description:
+      'JSON Schema for remarque-tokens\' generated tokens.json — GENERATED by scripts/tokens-json.mjs, do not hand-edit. ' +
+      'Conformant in spirit with the Design Tokens Community Group format ($value/$type on every token), with two ' +
+      'deliberate divergences (oklch()-string color values; per-token light/dark nesting) — see the tokens.json ' +
+      '$extensions.remarque.dtcg block and REMARQUE.md "DTCG Conformance" for the full rationale and ratification triggers.',
+    type: 'object',
+    additionalProperties: false,
+    required: ['$description', '$extensions', 'core', 'palette'],
+    properties: {
+      // No format: 'uri' keyword — ajv's strict mode rejects unknown
+      // formats without the separate ajv-formats package, and this
+      // project deliberately keeps the schema-validation devDependency
+      // surface to ajv alone (see scripts/test-types.mjs).
+      $schema: { type: 'string' },
+      $description: { type: 'string' },
+      $extensions: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['remarque'],
+        properties: {
+          remarque: {
+            type: 'object',
+            additionalProperties: false,
+            required: ['version', 'tiers', 'dtcg'],
+            properties: {
+              version: { type: 'string' },
+              tiers: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['core', 'palette'],
+                properties: { core: { type: 'string' }, palette: { type: 'string' } },
+              },
+              dtcg: {
+                type: 'object',
+                additionalProperties: false,
+                required: ['conformance', 'divergences', 'note'],
+                properties: {
+                  conformance: { type: 'string' },
+                  divergences: {
+                    type: 'array',
+                    items: {
+                      type: 'object',
+                      additionalProperties: false,
+                      required: ['aspect', 'detail', 'gatedOn'],
+                      properties: {
+                        aspect: { type: 'string' },
+                        detail: { type: 'string' },
+                        gatedOn: { type: 'string' },
+                      },
+                    },
+                  },
+                  note: { type: 'string' },
+                },
+              },
+            },
+          },
+        },
+      },
+      core: {
+        type: 'object',
+        additionalProperties: false,
+        patternProperties: { [kebabName]: { $ref: '#/$defs/coreEntry' } },
+      },
+      palette: {
+        type: 'object',
+        additionalProperties: false,
+        patternProperties: { [kebabName]: { $ref: '#/$defs/paletteEntry' } },
+      },
+    },
+    $defs: {
+      tokenType: {
+        type: 'string',
+        enum: ['color', 'dimension', 'number', 'fontFamily', 'fontWeight', 'duration', 'string'],
+      },
+      coreEntry: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['$value', '$type'],
+        properties: { $value: scalarValue, $type: { $ref: '#/$defs/tokenType' } },
+      },
+      paletteSideValue: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['$value'],
+        properties: {
+          $value: scalarValue,
+          $extensions: {
+            type: 'object',
+            additionalProperties: false,
+            properties: {
+              remarque: {
+                type: 'object',
+                additionalProperties: false,
+                properties: { inheritedFromLight: { type: 'boolean' } },
+              },
+            },
+          },
+        },
+      },
+      paletteEntry: {
+        type: 'object',
+        additionalProperties: false,
+        required: ['$type', 'light', 'dark'],
+        properties: {
+          $type: { $ref: '#/$defs/tokenType' },
+          light: { $ref: '#/$defs/paletteSideValue' },
+          dark: { $ref: '#/$defs/paletteSideValue' },
+        },
+      },
+    },
+  };
+}
+
+const schema = JSON.stringify(renderSchema(), null, 2) + '\n';
+
 if (process.argv.includes('--check')) {
   const currentJson = existsSync('tokens.json') ? readFileSync('tokens.json', 'utf8') : '';
   const currentDts = existsSync('tokens.d.ts') ? readFileSync('tokens.d.ts', 'utf8') : '';
+  const currentSchema = existsSync('tokens.schema.json') ? readFileSync('tokens.schema.json', 'utf8') : '';
   const staleJson = currentJson !== json;
   const staleDts = currentDts !== dts;
-  if (staleJson || staleDts) {
+  const staleSchema = currentSchema !== schema;
+  if (staleJson || staleDts || staleSchema) {
     if (staleJson) console.error('tokens.json is stale — run: node scripts/tokens-json.mjs');
     if (staleDts) console.error('tokens.d.ts is stale — run: node scripts/tokens-json.mjs');
+    if (staleSchema) console.error('tokens.schema.json is stale — run: node scripts/tokens-json.mjs');
     process.exit(1);
   }
-  console.log('tokens.json and tokens.d.ts are fresh ✓');
+  console.log('tokens.json, tokens.d.ts, and tokens.schema.json are fresh ✓');
 } else {
   writeFileSync('tokens.json', json);
   writeFileSync('tokens.d.ts', dts);
-  console.log(`tokens.json + tokens.d.ts written — ${Object.keys(out.core).length} core + ${Object.keys(out.palette).length} palette tokens (v${version})`);
+  writeFileSync('tokens.schema.json', schema);
+  console.log(`tokens.json + tokens.d.ts + tokens.schema.json written — ${Object.keys(out.core).length} core + ${Object.keys(out.palette).length} palette tokens (v${version})`);
 }

package/tokens.d.ts

@@ -1,6 +1,6 @@
 /*
  * Remarque design tokens — GENERATED from tokens.json by
- * scripts/tokens-json.mjs (v0.19.0). Do not edit — the CSS
+ * scripts/tokens-json.mjs (v0.20.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
@@ -152,6 +152,7 @@ export interface RemarquePaletteTokenEntry {
  * below applying, etc).
  */
 export interface RemarqueTokensFile {
+  readonly $schema: string;
   readonly $description: string;
   readonly $extensions: {
     readonly remarque: {
@@ -160,6 +161,16 @@ export interface RemarqueTokensFile {
         readonly core: string;
         readonly palette: string;
       };
+      /** DTCG conformance note (issue #99) — see REMARQUE.md "DTCG Conformance". */
+      readonly dtcg: {
+        readonly conformance: string;
+        readonly divergences: ReadonlyArray<{
+          readonly aspect: string;
+          readonly detail: string;
+          readonly gatedOn: string;
+        }>;
+        readonly note: string;
+      };
     };
   };
   readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };

package/tokens.json

@@ -1,11 +1,28 @@
 {
+  "$schema": "https://williamzujkowski.github.io/remarque/tokens.schema.json",
   "$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.19.0",
+      "version": "0.20.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"
+      },
+      "dtcg": {
+        "conformance": "partial — $value/$type present on every token (conformant in spirit); two deliberate structural divergences below",
+        "divergences": [
+          {
+            "aspect": "color-value-encoding",
+            "detail": "Color $value is an oklch() CSS string, not the DTCG structured color object ({ colorSpace, components, alpha }).",
+            "gatedOn": "DTCG color $type structured-value format ratifying"
+          },
+          {
+            "aspect": "multi-mode-theming",
+            "detail": "Palette-tier tokens nest per-token { light: {$value}, dark: {$value} } groups instead of a single $value plus a modes/resolver mechanism.",
+            "gatedOn": "DTCG multi-mode / resolver draft ratifying"
+          }
+        ],
+        "note": "Deliberate, not oversight — see REMARQUE.md \"DTCG Conformance\" for the argument. Do not \"fix\" these toward the current unratified drafts; re-derive from the CSS via scripts/tokens-json.mjs instead."
       }
     }
   },

package/tokens.schema.json

@@ -0,0 +1,210 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://williamzujkowski.github.io/remarque/tokens.schema.json",
+  "title": "Remarque design tokens (tokens.json)",
+  "description": "JSON Schema for remarque-tokens' generated tokens.json — GENERATED by scripts/tokens-json.mjs, do not hand-edit. Conformant in spirit with the Design Tokens Community Group format ($value/$type on every token), with two deliberate divergences (oklch()-string color values; per-token light/dark nesting) — see the tokens.json $extensions.remarque.dtcg block and REMARQUE.md \"DTCG Conformance\" for the full rationale and ratification triggers.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "$description",
+    "$extensions",
+    "core",
+    "palette"
+  ],
+  "properties": {
+    "$schema": {
+      "type": "string"
+    },
+    "$description": {
+      "type": "string"
+    },
+    "$extensions": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "remarque"
+      ],
+      "properties": {
+        "remarque": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": [
+            "version",
+            "tiers",
+            "dtcg"
+          ],
+          "properties": {
+            "version": {
+              "type": "string"
+            },
+            "tiers": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "core",
+                "palette"
+              ],
+              "properties": {
+                "core": {
+                  "type": "string"
+                },
+                "palette": {
+                  "type": "string"
+                }
+              }
+            },
+            "dtcg": {
+              "type": "object",
+              "additionalProperties": false,
+              "required": [
+                "conformance",
+                "divergences",
+                "note"
+              ],
+              "properties": {
+                "conformance": {
+                  "type": "string"
+                },
+                "divergences": {
+                  "type": "array",
+                  "items": {
+                    "type": "object",
+                    "additionalProperties": false,
+                    "required": [
+                      "aspect",
+                      "detail",
+                      "gatedOn"
+                    ],
+                    "properties": {
+                      "aspect": {
+                        "type": "string"
+                      },
+                      "detail": {
+                        "type": "string"
+                      },
+                      "gatedOn": {
+                        "type": "string"
+                      }
+                    }
+                  }
+                },
+                "note": {
+                  "type": "string"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "core": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "$ref": "#/$defs/coreEntry"
+        }
+      }
+    },
+    "palette": {
+      "type": "object",
+      "additionalProperties": false,
+      "patternProperties": {
+        "^[a-z][a-z0-9-]*$": {
+          "$ref": "#/$defs/paletteEntry"
+        }
+      }
+    }
+  },
+  "$defs": {
+    "tokenType": {
+      "type": "string",
+      "enum": [
+        "color",
+        "dimension",
+        "number",
+        "fontFamily",
+        "fontWeight",
+        "duration",
+        "string"
+      ]
+    },
+    "coreEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "$value",
+        "$type"
+      ],
+      "properties": {
+        "$value": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "$type": {
+          "$ref": "#/$defs/tokenType"
+        }
+      }
+    },
+    "paletteSideValue": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "$value"
+      ],
+      "properties": {
+        "$value": {
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "number"
+            }
+          ]
+        },
+        "$extensions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "remarque": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "inheritedFromLight": {
+                  "type": "boolean"
+                }
+              }
+            }
+          }
+        }
+      }
+    },
+    "paletteEntry": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "$type",
+        "light",
+        "dark"
+      ],
+      "properties": {
+        "$type": {
+          "$ref": "#/$defs/tokenType"
+        },
+        "light": {
+          "$ref": "#/$defs/paletteSideValue"
+        },
+        "dark": {
+          "$ref": "#/$defs/paletteSideValue"
+        }
+      }
+    }
+  }
+}