remarque-tokens 0.2.0

package/scripts/audit.mjs

@@ -0,0 +1,236 @@
+#!/usr/bin/env node
+/*
+ * remarque audit — enforces REMARQUE.md's checklist mechanically.
+ *
+ *   node scripts/audit.mjs [--palette tokens-palette.css] [--src <dir>]
+ *   npx remarque-audit --palette your-palette.css --src src
+ *
+ * Checks (exit 1 on any failure):
+ *   1. CONTRAST — extracts custom properties from the palette file with a
+ *      brace-aware scanner (light = top-level :root; dark = :root inside
+ *      @media (prefers-color-scheme: dark) and/or [data-theme="dark"],
+ *      cascaded over the light values), resolves var() aliases, and
+ *      computes WCAG 2.x ratios via OKLCH → linear sRGB (Ottosson
+ *      matrices, gamut-clipped) → relative luminance. Thresholds come
+ *      from the spec's Enforcement Checklist. Unresolvable tokens in a
+ *      required pairing are failures, not skips.
+ *      Also fails on out-of-sRGB-gamut colors (browsers clip them, so
+ *      the authored value is not what renders).
+ *   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.
+ */
+
+import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+const args = process.argv.slice(2);
+function argOf(flag, dflt) {
+  const i = args.indexOf(flag);
+  return i !== -1 && args[i + 1] ? args[i + 1] : dflt;
+}
+const PALETTE = argOf('--palette', 'tokens-palette.css');
+const SRC = argOf('--src', existsSync('site/src') ? 'site/src' : '.');
+
+let failures = 0;
+function fail(msg) {
+  failures++;
+  console.error(`  ✗ ${msg}`);
+}
+
+if (!existsSync(PALETTE)) {
+  console.error(`palette file not found: ${PALETTE} (use --palette <file>)`);
+  process.exit(1);
+}
+if (!existsSync(SRC)) {
+  console.error(`src directory not found: ${SRC} (use --src <dir>)`);
+  process.exit(1);
+}
+
+/* ── OKLCH → sRGB → WCAG luminance ──────────────────────── */
+
+function oklchToLinearSrgb(L, C, H) {
+  const h = (H * Math.PI) / 180;
+  const a = C * Math.cos(h), b = C * Math.sin(h);
+  const l_ = L + 0.3963377774 * a + 0.2158037573 * b;
+  const m_ = L - 0.1055613458 * a - 0.0638541728 * b;
+  const s_ = L - 0.0894841775 * a - 1.2914855480 * b;
+  const l = l_ ** 3, m = m_ ** 3, s = s_ ** 3;
+  return [
+    +4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s,
+    -1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s,
+    -0.0041960863 * l - 0.7034186147 * m + 1.7076147010 * s,
+  ];
+}
+const inGamut = (rgb) => rgb.every((x) => x >= -0.0005 && x <= 1.0005);
+const clip = (x) => Math.min(1, Math.max(0, x));
+const luminance = (rgb) => {
+  const [r, g, b] = rgb.map(clip);
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+};
+function ratio(c1, c2) {
+  const l1 = luminance(oklchToLinearSrgb(...c1));
+  const l2 = luminance(oklchToLinearSrgb(...c2));
+  const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1];
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/* ── Brace-aware CSS block extraction ───────────────────── */
+/* Returns [{ prelude, body, context }] where context is the enclosing
+   at-rule prelude ('' at top level). One level of at-rule nesting is
+   supported — enough for token files; deeper nesting is flattened with
+   its outermost context. Comments are stripped first. */
+
+function extractBlocks(css) {
+  const src = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const blocks = [];
+  function scan(text, context) {
+    let i = 0;
+    while (i < text.length) {
+      const open = text.indexOf('{', i);
+      if (open === -1) break;
+      const prelude = text.slice(i, open).trim().replace(/^[;\s]+/, '');
+      let depth = 1, j = open + 1;
+      while (j < text.length && depth > 0) {
+        if (text[j] === '{') depth++;
+        else if (text[j] === '}') depth--;
+        j++;
+      }
+      const body = text.slice(open + 1, j - 1);
+      if (prelude.startsWith('@')) {
+        scan(body, prelude);
+      } else {
+        blocks.push({ prelude, body, context });
+      }
+      i = j;
+    }
+  }
+  scan(src, '');
+  return blocks;
+}
+
+function declsOf(blocks, filterFn) {
+  const decls = {};
+  for (const b of blocks) {
+    if (!filterFn(b)) continue;
+    for (const m of b.body.matchAll(/--([a-z0-9-]+)\s*:\s*([^;]+);/g)) {
+      decls[m[1]] = m[2].trim();
+    }
+  }
+  return decls;
+}
+
+const blocks = extractBlocks(readFileSync(PALETTE, 'utf8'));
+const lightDecls = declsOf(blocks, (b) => b.context === '' && b.prelude.includes(':root'));
+const darkOverrides = declsOf(blocks, (b) =>
+  (b.context.includes('prefers-color-scheme') && b.context.includes('dark') && b.prelude.includes(':root')) ||
+  b.prelude.includes('[data-theme="dark"]')
+);
+if (Object.keys(lightDecls).length === 0) fail(`no top-level :root declarations found in ${PALETTE}`);
+if (Object.keys(darkOverrides).length === 0) fail(`no dark-theme declarations found in ${PALETTE} (@media prefers-color-scheme: dark or [data-theme="dark"])`);
+// CSS cascade: dark blocks override light; unset dark tokens inherit light values.
+const darkDecls = { ...lightDecls, ...darkOverrides };
+
+/* Resolve a token to [L, C, H], following var(--x) chains. Returns null
+   (and records why) when unresolvable. */
+function resolveColor(decls, name, seen = new Set()) {
+  if (seen.has(name)) return { err: `circular var() chain at --${name}` };
+  seen.add(name);
+  const raw = decls[name];
+  if (raw === undefined) return { err: `--${name} is not defined` };
+  const varRef = raw.match(/^var\(\s*--([a-z0-9-]+)\s*\)$/);
+  if (varRef) return resolveColor(decls, varRef[1], seen);
+  const ok = raw.match(/^oklch\(\s*([\d.]+)\s+([\d.]+)\s+([\d.]+)\s*\)$/);
+  if (ok) return { color: [+ok[1], +ok[2], +ok[3]] };
+  return { err: `--${name} has unsupported value "${raw}" (expected oklch(L C H) or var(--token))` };
+}
+
+/* ── Contrast checks (from REMARQUE.md Enforcement Checklist) ── */
+
+const CHECKS = [
+  // [fg-token, bg-token, min-ratio, label]
+  ['color-fg', 'color-bg', 4.5, 'primary text'],
+  ['color-fg', 'color-surface', 4.5, 'primary text on surface'],
+  ['color-fg-muted', 'color-bg', 7.0, 'secondary text (spec AAA line)'],
+  ['color-muted', 'color-bg', 4.5, 'tertiary text'],
+  ['color-muted', 'color-surface', 4.5, 'tertiary text on surface'],
+  ['color-accent', 'color-bg', 4.5, 'links'],
+  ['color-accent-hover', 'color-bg', 4.5, 'link hover'],
+  ['color-code-fg', 'color-code-bg', 4.5, 'code text'],
+  ['color-border-bold', 'color-bg', 3.0, 'functional borders (WCAG 1.4.11)'],
+  ['color-selection-fg', 'color-selection-bg', 4.5, 'selected text'],
+];
+
+for (const [themeName, decls] of [['light', lightDecls], ['dark', darkDecls]]) {
+  console.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))) {
+      fail(`--${name} oklch(${r.color.join(' ')}) is outside sRGB gamut — browsers will clip it; author an in-gamut value`);
+    }
+  }
+  for (const [fgName, bgName, min, label] of CHECKS) {
+    const fg = resolveColor(decls, fgName);
+    const bg = resolveColor(decls, bgName);
+    if (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})`);
+  }
+}
+
+/* ── Source scans ───────────────────────────────────────── */
+
+function* walk(dir) {
+  for (const name of readdirSync(dir)) {
+    const p = join(dir, name);
+    if (name === 'node_modules' || name === 'dist' || name.startsWith('.')) continue;
+    if (statSync(p).isDirectory()) yield* walk(p);
+    else if (/\.(css|astro|svelte|jsx|tsx|html)$/.test(name)) yield p;
+  }
+}
+
+console.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).
+const isTokenFile = (p) => /tokens(-core|-palette)?\.css$|fonts\.css$|globals\.css$|pages[\/\\]tokens\.astro$/.test(p);
+
+for (const file of walk(SRC)) {
+  const rel = relative('.', file);
+  const text = readFileSync(file, 'utf8');
+  const lines = text.split('\n');
+  lines.forEach((line, i) => {
+    // 2. font-size floor (static rem/px values), plus statically
+    // unverifiable sizes (% / clamp) outside token files — those bypass
+    // any floor check, so require the type-scale tokens instead.
+    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)) {
+        fail(`${rel}:${i + 1} font-size ${m[1]}${m[2]} below the 13px floor`);
+      }
+    }
+    if (!isTokenFile(rel) && /font-size:\s*(clamp\(|[\d.]+%)/.test(line)) {
+      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)) {
+      fail(`${rel}:${i + 1} hardcoded hex/rgb/hsl color: ${line.trim().slice(0, 80)}`);
+    }
+    if (!isTokenFile(rel) && /\boklch\(/.test(line) && !line.includes('var(--')) {
+      fail(`${rel}:${i + 1} oklch() literal outside token files: ${line.trim().slice(0, 80)}`);
+    }
+  });
+}
+
+if (failures) {
+  console.error(`\naudit FAILED — ${failures} problem(s)\n`);
+  process.exit(1);
+}
+console.log('\naudit passed ✓\n');

package/tailwind.config.js

@@ -0,0 +1,144 @@
+/**
+ * Remarque — Tailwind CSS Configuration
+ * ──────────────────────────────────────
+ * This config extends Tailwind with Remarque's design tokens.
+ *
+ * TAILWIND VERSION STORY (one canonical answer):
+ *   - Tailwind v3.x → use this file as your tailwind.config.js.
+ *   - Tailwind v4.x → do NOT use this file. Write an @theme block in CSS
+ *     using the values from tokens.css (see site/src/styles/globals.css in
+ *     this repo for the reference @theme; a shipped theme.css subpath export
+ *     is tracked in issue #48).
+ *
+ * Tokens are defined in tokens.css as CSS custom properties; this config
+ * maps them into Tailwind utilities (font-display, text-title, etc.).
+ */
+
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx,mdx,astro}",
+    "./pages/**/*.{js,ts,jsx,tsx,mdx,astro}",
+    "./components/**/*.{js,ts,jsx,tsx,mdx,astro}",
+    "./app/**/*.{js,ts,jsx,tsx,mdx,astro}",
+  ],
+
+  // Match Remarque's actual theming mechanism ([data-theme] attribute).
+  // The bare "class" strategy only matches a literal `dark` class, which
+  // Remarque never sets — dark: utilities would silently never activate.
+  darkMode: ["selector", '[data-theme="dark"]'],
+
+  theme: {
+    extend: {
+
+      /* ─── Font Families ──────────────────────────────── */
+      fontFamily: {
+        display: ["Newsreader", "Georgia", "Times New Roman", "serif"],
+        body: ["Inter", "ui-sans-serif", "system-ui", "-apple-system", "sans-serif"],
+        mono: ["JetBrains Mono", "ui-monospace", "Cascadia Code", "Fira Code", "monospace"],
+      },
+
+      /* ─── Font Sizes ─────────────────────────────────── */
+      /* Maps to: text-display, text-title, text-section, etc. */
+      fontSize: {
+        "display": ["var(--text-display)", { lineHeight: "var(--leading-display)", letterSpacing: "var(--tracking-display)" }],
+        "title": ["var(--text-title)", { lineHeight: "var(--leading-title)", letterSpacing: "var(--tracking-title)" }],
+        "section": ["var(--text-section)", { lineHeight: "var(--leading-section)", letterSpacing: "var(--tracking-title)" }],
+        "body-lg": ["var(--text-body-lg)", { lineHeight: "var(--leading-body)" }],
+        "body": ["var(--text-body)", { lineHeight: "var(--leading-body)" }],
+        "meta": ["var(--text-meta)", { lineHeight: "var(--leading-meta)", letterSpacing: "var(--tracking-meta)" }],
+        "micro": ["var(--text-micro)", { lineHeight: "var(--leading-meta)" }],
+      },
+
+      /* ─── Spacing ────────────────────────────────────── */
+      /*
+       * Namespaced under remarque-* so Tailwind's default numeric scale is
+       * NEVER overridden (mt-12 stays 3rem). Use mt-remarque-9 (6rem) etc.
+       * for Remarque's generous editorial spacings, or var(--space-N)
+       * directly in arbitrary values: mt-[var(--space-9)].
+       */
+      spacing: {
+        "remarque-1": "var(--space-1)",
+        "remarque-2": "var(--space-2)",
+        "remarque-3": "var(--space-3)",
+        "remarque-4": "var(--space-4)",
+        "remarque-5": "var(--space-5)",
+        "remarque-6": "var(--space-6)",
+        "remarque-7": "var(--space-7)",
+        "remarque-8": "var(--space-8)",
+        "remarque-9": "var(--space-9)",
+        "remarque-10": "var(--space-10)",
+        "remarque-11": "var(--space-11)",
+        "remarque-12": "var(--space-12)",
+      },
+
+      /* ─── Max Widths ─────────────────────────────────── */
+      /*
+       * Width-constraint utilities ONLY — they do not center.
+       * Per AGENT_RULES.md, page sections must use the .content-reading /
+       * .content-standard classes from tokens.css (which add
+       * margin-inline: auto). Reach for max-w-reading only on elements
+       * that are intentionally left-aligned inside an already-constrained
+       * container (e.g. a lead paragraph).
+       */
+      maxWidth: {
+        "reading": "var(--content-reading)",      // 46rem — prose
+        "standard": "var(--content-standard)",    // 72rem — project pages
+        "wide": "var(--content-wide)",            // 88rem — outer container
+      },
+
+      /* ─── Colors ─────────────────────────────────────── */
+      /* Maps CSS custom properties so Tailwind utilities track theme changes */
+      colors: {
+        bg: {
+          DEFAULT: "var(--color-bg)",
+          subtle: "var(--color-bg-subtle)",
+        },
+        fg: {
+          DEFAULT: "var(--color-fg)",
+          muted: "var(--color-fg-muted)",
+        },
+        muted: "var(--color-muted)",
+        border: {
+          DEFAULT: "var(--color-border)",
+          bold: "var(--color-border-bold)",
+        },
+        surface: "var(--color-surface)",
+        accent: {
+          DEFAULT: "var(--color-accent)",
+          hover: "var(--color-accent-hover)",
+          subtle: "var(--color-accent-subtle)",
+        },
+        code: {
+          bg: "var(--color-code-bg)",
+          fg: "var(--color-code-fg)",
+        },
+      },
+
+      /* ─── Border Radius ──────────────────────────────── */
+      borderRadius: {
+        sm: "var(--radius-sm)",
+        md: "var(--radius-md)",
+        none: "0",
+      },
+
+      /* ─── Border Color ───────────────────────────────── */
+      borderColor: {
+        DEFAULT: "var(--color-border)",
+        bold: "var(--color-border-bold)",
+      },
+
+      /* ─── Transitions ────────────────────────────────── */
+      transitionDuration: {
+        fast: "var(--motion-fast)",
+        normal: "var(--motion-normal)",
+      },
+
+      transitionTimingFunction: {
+        remarque: "var(--motion-easing)",
+      },
+    },
+  },
+
+  plugins: [],
+};