remarque-tokens 0.11.0 → 0.12.0

package/CHANGELOG.md

@@ -4,6 +4,35 @@ 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.12.0 — 2026-07-23
+
+TypeScript types and a README "Used By" section (closes #34, closes #35).
+
+### Added
+- **`tokens.d.ts`** — generated from `tokens.json` by `scripts/tokens-json.mjs`
+  (regenerates in the same run as `tokens.json`; `--check` verifies both are
+  fresh, wired into the same `deploy.yml` CI step). Ships literal-union types
+  for every token name (`RemarqueCoreToken`, `RemarquePaletteToken`,
+  `RemarqueToken`), a `RemarqueCssVar` template-literal type
+  (`` `--${RemarqueToken}` ``), structural interfaces matching tokens.json's
+  actual shape (`RemarqueTokensFile`, `RemarqueCoreTokenEntry`,
+  `RemarquePaletteTokenEntry`), a `RemarqueTokenValues` interface with the
+  live value of every token as a literal type, and an ambient
+  `declare module 'remarque-tokens/tokens.json'` so
+  `import tokens from 'remarque-tokens/tokens.json'` is precisely typed
+  without depending on the consumer's `resolveJsonModule`. This package has
+  no JS entry point — the types exist for editors/TS consumers who author
+  Remarque token names or read `tokens.json` programmatically.
+  `package.json` wires `types`, an `./tokens.d.ts` export, and a `types`
+  condition on the existing `./tokens.json` export; `scripts/test-types.mjs`
+  gates token-name coverage, the exported type surface, and the
+  `package.json` wiring (string assertions, no `typescript` dependency
+  added).
+- **README "Used By" section** — the demo site, `williamzujkowski.github.io`
+  (core-tier npm consumer), `tsundoku` (full-palette npm consumer, custom
+  accent hue), and `remarque-starter` (template repo), one line each on how
+  they consume the package.
+
 ## 0.11.0 — 2026-07-23
 
 Palette golden gate: the default palette is now bound, by CI, to the

package/README.md

@@ -19,6 +19,13 @@ Most developer sites inherit the visual language of SaaS dashboards or component
 - **Self-hosted fonts** — no Google CDN dependency. Strict CSP. GDPR-compliant.
 - **AI-native** — designed to be consumed by Claude Code, Cursor, Copilot, and other AI coding tools with zero aesthetic drift.
 
+## Used By
+
+- **[Remarque demo site](https://williamzujkowski.github.io/remarque/)** — the `site/` directory in this repo; reference implementation of all four demoed archetypes, deployed to GitHub Pages.
+- **[williamzujkowski.github.io](https://github.com/williamzujkowski/williamzujkowski.github.io)** — flagship personal site; core-tier npm consumer (`remarque-tokens/core` from npm, hand-authored palette layer on top).
+- **[tsundoku](https://github.com/williamzujkowski/tsundoku)** — bookshelf/reading-log site; full-palette npm consumer, custom terracotta "book cloth" accent hue over the default palette for its card-catalog identity.
+- **[remarque-starter](https://github.com/williamzujkowski/remarque-starter)** — template repo; Astro scaffold pulling `remarque-tokens` from npm with the audit wired into CI, meant to be forked.
+
 ## Install
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "remarque-tokens",
-  "version": "0.11.0",
+  "version": "0.12.0",
   "engines": {
     "node": ">=18"
   },
@@ -21,6 +21,7 @@
   },
   "homepage": "https://williamzujkowski.github.io/remarque/",
   "main": "tokens.css",
+  "types": "./tokens.d.ts",
   "bin": {
     "remarque-audit": "scripts/audit.mjs",
     "remarque-drift": "scripts/drift-check.mjs",
@@ -43,7 +44,10 @@
     }
   },
   "exports": {
-    ".": "./tokens.css",
+    ".": {
+      "types": "./tokens.d.ts",
+      "default": "./tokens.css"
+    },
     "./tokens": "./tokens.css",
     "./tokens.css": "./tokens.css",
     "./core": "./tokens-core.css",
@@ -55,7 +59,11 @@
     "./tailwind": "./tailwind.config.js",
     "./theme.css": "./theme.css",
     "./theme": "./theme.css",
-    "./tokens.json": "./tokens.json",
+    "./tokens.json": {
+      "types": "./tokens.d.ts",
+      "default": "./tokens.json"
+    },
+    "./tokens.d.ts": "./tokens.d.ts",
     "./prose": "./prose.css",
     "./prose.css": "./prose.css",
     "./print": "./print.css",
@@ -80,6 +88,7 @@
     "CHANGELOG.md",
     "theme.css",
     "tokens.json",
+    "tokens.d.ts",
     "scripts/tokens-json.mjs",
     "prose.css",
     "print.css",

package/scripts/tokens-json.mjs

@@ -1,11 +1,12 @@
 #!/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.
+ * 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
+ * here are derived output for tooling, AI agents, and TS editors.
  *
- *   node scripts/tokens-json.mjs           # (re)write tokens.json
- *   node scripts/tokens-json.mjs --check   # exit 1 if tokens.json is stale (CI)
+ *   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)
  *
  * Multi-theme values use per-token light/dark groups with $value on each
  * (the W3C spec has no native theming; this follows its $extensions
@@ -70,14 +71,159 @@ for (const [name, value] of Object.entries(lightDecls)) {
 
 const json = JSON.stringify(out, null, 2) + '\n';
 
+/* ── tokens.d.ts ──────────────────────────────────────────────────────
+ * Literal-union types + a typed shape for tokens.json, generated from
+ * the same in-memory `out` object that produces tokens.json — so the
+ * two derived files can never disagree with each other, only (briefly,
+ * until regenerated) with the CSS. The package ships no JS entry point;
+ * this file exists purely for editors/TS consumers that either author
+ * Remarque token names (`RemarqueToken`, `RemarqueCssVar`) or read
+ * tokens.json programmatically (`RemarqueTokensFile`, wired via the
+ * ambient `declare module 'remarque-tokens/tokens.json'` below).
+ */
+function tsLiteral(value) {
+  return typeof value === 'number' ? String(value) : JSON.stringify(value);
+}
+
+function renderDts(tokens, pkgVersion) {
+  const coreNames = Object.keys(tokens.core);
+  const paletteNames = Object.keys(tokens.palette);
+
+  const coreUnion = coreNames.map((n) => `  | '${n}'`).join('\n');
+  const paletteUnion = paletteNames.map((n) => `  | '${n}'`).join('\n');
+
+  const coreValues = coreNames
+    .map((n) => `    readonly '${n}': ${tsLiteral(tokens.core[n].$value)};`)
+    .join('\n');
+  const paletteValues = paletteNames
+    .map((n) => {
+      const t = tokens.palette[n];
+      return `    readonly '${n}': {\n      readonly light: ${tsLiteral(t.light.$value)};\n      readonly dark: ${tsLiteral(t.dark.$value)};\n    };`;
+    })
+    .join('\n');
+
+  return `/*
+ * Remarque design tokens — GENERATED from tokens.json by
+ * scripts/tokens-json.mjs (v${pkgVersion}). 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
+ *
+ * This package has no JS entry point — these types exist for editors
+ * and TypeScript consumers that either author Remarque token names
+ * (RemarqueToken, RemarqueCssVar) or read tokens.json programmatically
+ * (RemarqueTokensFile / RemarqueTokenValues, and the ambient module
+ * declaration below for \`import tokens from 'remarque-tokens/tokens.json'\`).
+ */
+
+/** All core-tier token names (tokens-core.css). Never overridden. */
+export type RemarqueCoreToken =
+${coreUnion};
+
+/** All palette-tier token names (tokens-palette.css). The sanctioned personalization surface. */
+export type RemarquePaletteToken =
+${paletteUnion};
+
+/** Every Remarque token name, core + palette. */
+export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
+
+/** A Remarque token name as its CSS custom-property form, e.g. \`--text-body\`. */
+export type RemarqueCssVar = \`--${'$'}{RemarqueToken}\`;
+
+/** W3C design-tokens \`$type\` values used across tokens.json. */
+export type RemarqueTokenType =
+  | 'color'
+  | 'dimension'
+  | 'number'
+  | 'fontFamily'
+  | 'fontWeight'
+  | 'duration'
+  | 'string';
+
+/** Shape of a single core-tier entry in tokens.json's \`core\` map. */
+export interface RemarqueCoreTokenEntry {
+  readonly $value: string | number;
+  readonly $type: RemarqueTokenType;
+}
+
+/** Shape of one theme side (\`light\`/\`dark\`) of a palette-tier entry. */
+export interface RemarquePaletteTokenSideValue {
+  readonly $value: string | number;
+  readonly $extensions?: {
+    readonly remarque?: {
+      readonly inheritedFromLight?: boolean;
+    };
+  };
+}
+
+/** Shape of a single palette-tier entry in tokens.json's \`palette\` map. */
+export interface RemarquePaletteTokenEntry {
+  readonly $type: RemarqueTokenType;
+  readonly light: RemarquePaletteTokenSideValue;
+  readonly dark: RemarquePaletteTokenSideValue;
+}
+
+/**
+ * Typed shape of tokens.json's default export — the whole generated
+ * file, structurally. Use this when reading tokens.json dynamically
+ * (\`JSON.parse\`, a bundler JSON import without the ambient module
+ * below applying, etc).
+ */
+export interface RemarqueTokensFile {
+  readonly $description: string;
+  readonly $extensions: {
+    readonly remarque: {
+      readonly version: string;
+      readonly tiers: {
+        readonly core: string;
+        readonly palette: string;
+      };
+    };
+  };
+  readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };
+  readonly palette: { readonly [K in RemarquePaletteToken]: RemarquePaletteTokenEntry };
+}
+
+/**
+ * The actual current value of every token, as literal types — precise
+ * autocomplete for "what is \`--text-body\` right now", not just "what
+ * are its shape and type". Regenerated alongside tokens.json, so these
+ * literals track the live CSS across releases.
+ */
+export interface RemarqueTokenValues {
+  readonly core: {
+${coreValues}
+  };
+  readonly palette: {
+${paletteValues}
+  };
+}
+
+// Precise types for \`import tokens from 'remarque-tokens/tokens.json'\`
+// (and any other bundler-JSON-import path resolving through this
+// subpath) without depending on the consumer's \`resolveJsonModule\`.
+declare module 'remarque-tokens/tokens.json' {
+  const tokens: RemarqueTokensFile;
+  export default tokens;
+}
+`;
+}
+
+const dts = renderDts(out, version);
+
 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');
+  const currentJson = existsSync('tokens.json') ? readFileSync('tokens.json', 'utf8') : '';
+  const currentDts = existsSync('tokens.d.ts') ? readFileSync('tokens.d.ts', 'utf8') : '';
+  const staleJson = currentJson !== json;
+  const staleDts = currentDts !== dts;
+  if (staleJson || staleDts) {
+    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');
     process.exit(1);
   }
-  console.log('tokens.json is fresh ✓');
+  console.log('tokens.json and tokens.d.ts are 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})`);
+  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})`);
 }

package/tokens.d.ts

@@ -0,0 +1,299 @@
+/*
+ * Remarque design tokens — GENERATED from tokens.json by
+ * scripts/tokens-json.mjs (v0.12.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
+ *
+ * This package has no JS entry point — these types exist for editors
+ * and TypeScript consumers that either author Remarque token names
+ * (RemarqueToken, RemarqueCssVar) or read tokens.json programmatically
+ * (RemarqueTokensFile / RemarqueTokenValues, and the ambient module
+ * declaration below for `import tokens from 'remarque-tokens/tokens.json'`).
+ */
+
+/** All core-tier token names (tokens-core.css). Never overridden. */
+export type RemarqueCoreToken =
+  | 'text-display'
+  | 'text-title'
+  | 'text-section'
+  | 'text-body-lg'
+  | 'text-body'
+  | 'text-meta'
+  | 'text-micro'
+  | 'leading-display'
+  | 'leading-title'
+  | 'leading-section'
+  | 'leading-body'
+  | 'leading-meta'
+  | 'tracking-display'
+  | 'tracking-title'
+  | 'tracking-body'
+  | 'tracking-meta'
+  | 'tracking-caps'
+  | 'weight-regular'
+  | 'weight-medium'
+  | 'weight-semibold'
+  | 'space-1'
+  | 'space-2'
+  | 'space-3'
+  | 'space-4'
+  | 'space-5'
+  | 'space-6'
+  | 'space-7'
+  | 'space-8'
+  | 'space-9'
+  | 'space-10'
+  | 'space-11'
+  | 'space-12'
+  | 'content-standard'
+  | 'content-wide'
+  | 'radius-sm'
+  | 'radius-md'
+  | 'radius-none'
+  | 'border-width'
+  | 'border-style'
+  | 'motion-fast'
+  | 'motion-normal'
+  | 'motion-easing';
+
+/** All palette-tier token names (tokens-palette.css). The sanctioned personalization surface. */
+export type RemarquePaletteToken =
+  | 'font-display'
+  | 'font-body'
+  | 'font-mono'
+  | 'content-reading'
+  | 'weight-display'
+  | 'color-bg'
+  | 'color-bg-subtle'
+  | 'color-fg'
+  | 'color-fg-muted'
+  | 'color-muted'
+  | 'color-border'
+  | 'color-border-bold'
+  | 'color-surface'
+  | 'color-accent'
+  | 'color-accent-hover'
+  | 'color-accent-subtle'
+  | 'color-link'
+  | 'color-link-hover'
+  | 'color-focus-ring'
+  | 'color-selection-bg'
+  | 'color-selection-fg'
+  | 'color-code-bg'
+  | 'color-code-fg';
+
+/** Every Remarque token name, core + palette. */
+export type RemarqueToken = RemarqueCoreToken | RemarquePaletteToken;
+
+/** A Remarque token name as its CSS custom-property form, e.g. `--text-body`. */
+export type RemarqueCssVar = `--${RemarqueToken}`;
+
+/** W3C design-tokens `$type` values used across tokens.json. */
+export type RemarqueTokenType =
+  | 'color'
+  | 'dimension'
+  | 'number'
+  | 'fontFamily'
+  | 'fontWeight'
+  | 'duration'
+  | 'string';
+
+/** Shape of a single core-tier entry in tokens.json's `core` map. */
+export interface RemarqueCoreTokenEntry {
+  readonly $value: string | number;
+  readonly $type: RemarqueTokenType;
+}
+
+/** Shape of one theme side (`light`/`dark`) of a palette-tier entry. */
+export interface RemarquePaletteTokenSideValue {
+  readonly $value: string | number;
+  readonly $extensions?: {
+    readonly remarque?: {
+      readonly inheritedFromLight?: boolean;
+    };
+  };
+}
+
+/** Shape of a single palette-tier entry in tokens.json's `palette` map. */
+export interface RemarquePaletteTokenEntry {
+  readonly $type: RemarqueTokenType;
+  readonly light: RemarquePaletteTokenSideValue;
+  readonly dark: RemarquePaletteTokenSideValue;
+}
+
+/**
+ * Typed shape of tokens.json's default export — the whole generated
+ * file, structurally. Use this when reading tokens.json dynamically
+ * (`JSON.parse`, a bundler JSON import without the ambient module
+ * below applying, etc).
+ */
+export interface RemarqueTokensFile {
+  readonly $description: string;
+  readonly $extensions: {
+    readonly remarque: {
+      readonly version: string;
+      readonly tiers: {
+        readonly core: string;
+        readonly palette: string;
+      };
+    };
+  };
+  readonly core: { readonly [K in RemarqueCoreToken]: RemarqueCoreTokenEntry };
+  readonly palette: { readonly [K in RemarquePaletteToken]: RemarquePaletteTokenEntry };
+}
+
+/**
+ * The actual current value of every token, as literal types — precise
+ * autocomplete for "what is `--text-body` right now", not just "what
+ * are its shape and type". Regenerated alongside tokens.json, so these
+ * literals track the live CSS across releases.
+ */
+export interface RemarqueTokenValues {
+  readonly core: {
+    readonly 'text-display': "clamp(2.75rem, 5.5vw, 5rem)";
+    readonly 'text-title': "clamp(1.875rem, 3.5vw, 3rem)";
+    readonly 'text-section': "clamp(1.375rem, 2.25vw, 2rem)";
+    readonly 'text-body-lg': "1.1875rem";
+    readonly 'text-body': "1.0625rem";
+    readonly 'text-meta': "0.875rem";
+    readonly 'text-micro': "0.8125rem";
+    readonly 'leading-display': 1.05;
+    readonly 'leading-title': 1.15;
+    readonly 'leading-section': 1.2;
+    readonly 'leading-body': 1.75;
+    readonly 'leading-meta': 1.5;
+    readonly 'tracking-display': "-0.02em";
+    readonly 'tracking-title': "-0.015em";
+    readonly 'tracking-body': "0em";
+    readonly 'tracking-meta': "0.02em";
+    readonly 'tracking-caps': "0.06em";
+    readonly 'weight-regular': 400;
+    readonly 'weight-medium': 500;
+    readonly 'weight-semibold': 600;
+    readonly 'space-1': "0.25rem";
+    readonly 'space-2': "0.5rem";
+    readonly 'space-3': "0.75rem";
+    readonly 'space-4': "1rem";
+    readonly 'space-5': "1.5rem";
+    readonly 'space-6': "2rem";
+    readonly 'space-7': "3rem";
+    readonly 'space-8': "4rem";
+    readonly 'space-9': "6rem";
+    readonly 'space-10': "8rem";
+    readonly 'space-11': "10rem";
+    readonly 'space-12': "12rem";
+    readonly 'content-standard': "72rem";
+    readonly 'content-wide': "88rem";
+    readonly 'radius-sm': "0.25rem";
+    readonly 'radius-md': "0.5rem";
+    readonly 'radius-none': "0";
+    readonly 'border-width': "1px";
+    readonly 'border-style': "solid";
+    readonly 'motion-fast': "120ms";
+    readonly 'motion-normal': "180ms";
+    readonly 'motion-easing': "ease-out";
+  };
+  readonly palette: {
+    readonly 'font-display': {
+      readonly light: "\"Newsreader\", Georgia, \"Times New Roman\", serif";
+      readonly dark: "\"Newsreader\", Georgia, \"Times New Roman\", serif";
+    };
+    readonly 'font-body': {
+      readonly light: "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif";
+      readonly dark: "\"Inter\", ui-sans-serif, system-ui, -apple-system, sans-serif";
+    };
+    readonly 'font-mono': {
+      readonly light: "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace";
+      readonly dark: "\"JetBrains Mono\", ui-monospace, \"Cascadia Code\", \"Fira Code\", monospace";
+    };
+    readonly 'content-reading': {
+      readonly light: "46rem";
+      readonly dark: "46rem";
+    };
+    readonly 'weight-display': {
+      readonly light: 400;
+      readonly dark: 500;
+    };
+    readonly 'color-bg': {
+      readonly light: "oklch(0.975 0.005 80)";
+      readonly dark: "oklch(0.16 0.01 80)";
+    };
+    readonly 'color-bg-subtle': {
+      readonly light: "oklch(0.955 0.005 80)";
+      readonly dark: "oklch(0.19 0.01 80)";
+    };
+    readonly 'color-fg': {
+      readonly light: "oklch(0.18 0.01 80)";
+      readonly dark: "oklch(0.90 0.005 80)";
+    };
+    readonly 'color-fg-muted': {
+      readonly light: "oklch(0.43 0.015 80)";
+      readonly dark: "oklch(0.70 0.01 80)";
+    };
+    readonly 'color-muted': {
+      readonly light: "oklch(0.54 0.01 80)";
+      readonly dark: "oklch(0.60 0.01 80)";
+    };
+    readonly 'color-border': {
+      readonly light: "oklch(0.88 0.005 80)";
+      readonly dark: "oklch(0.25 0.005 80)";
+    };
+    readonly 'color-border-bold': {
+      readonly light: "oklch(0.62 0.01 80)";
+      readonly dark: "oklch(0.50 0.01 80)";
+    };
+    readonly 'color-surface': {
+      readonly light: "oklch(0.965 0.005 80)";
+      readonly dark: "oklch(0.19 0.01 80)";
+    };
+    readonly 'color-accent': {
+      readonly light: "oklch(0.50 0.14 250)";
+      readonly dark: "oklch(0.68 0.12 250)";
+    };
+    readonly 'color-accent-hover': {
+      readonly light: "oklch(0.42 0.11 250)";
+      readonly dark: "oklch(0.75 0.12 250)";
+    };
+    readonly 'color-accent-subtle': {
+      readonly light: "oklch(0.95 0.02 250)";
+      readonly dark: "oklch(0.22 0.04 250)";
+    };
+    readonly 'color-link': {
+      readonly light: "var(--color-accent)";
+      readonly dark: "var(--color-accent)";
+    };
+    readonly 'color-link-hover': {
+      readonly light: "var(--color-accent-hover)";
+      readonly dark: "var(--color-accent-hover)";
+    };
+    readonly 'color-focus-ring': {
+      readonly light: "var(--color-accent)";
+      readonly dark: "var(--color-accent)";
+    };
+    readonly 'color-selection-bg': {
+      readonly light: "oklch(0.92 0.04 250)";
+      readonly dark: "oklch(0.30 0.06 250)";
+    };
+    readonly 'color-selection-fg': {
+      readonly light: "var(--color-fg)";
+      readonly dark: "oklch(0.92 0.005 80)";
+    };
+    readonly 'color-code-bg': {
+      readonly light: "oklch(0.945 0.005 80)";
+      readonly dark: "oklch(0.20 0.005 80)";
+    };
+    readonly 'color-code-fg': {
+      readonly light: "var(--color-fg)";
+      readonly dark: "oklch(0.88 0.005 80)";
+    };
+  };
+}
+
+// Precise types for `import tokens from 'remarque-tokens/tokens.json'`
+// (and any other bundler-JSON-import path resolving through this
+// subpath) without depending on the consumer's `resolveJsonModule`.
+declare module 'remarque-tokens/tokens.json' {
+  const tokens: RemarqueTokensFile;
+  export default tokens;
+}

package/tokens.json

@@ -2,7 +2,7 @@
   "$description": "Remarque design tokens — GENERATED from tokens-core.css + tokens-palette.css by scripts/tokens-json.mjs. Do not edit; the CSS is the source of truth.",
   "$extensions": {
     "remarque": {
-      "version": "0.11.0",
+      "version": "0.12.0",
       "tiers": {
         "core": "immutable identity — overriding forks the system",
         "palette": "sanctioned personalization surface — override freely, then run remarque-audit"