@felloinnovations/brand-kit 0.4.0 → 0.5.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@felloinnovations/brand-kit",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "Fello brand tokens, the house stylesheet (fello.css), React components and the design system guide. One source of truth for every GTM app.",
   "license": "UNLICENSED",
   "private": false,
@@ -18,6 +18,8 @@
   ],
   "files": [
     "dist",
+    "scripts/check-palette.mjs",
+    "scripts/token-model.mjs",
     "tokens",
     "design-system",
     "assets",
@@ -36,31 +38,45 @@
       "types": "./dist/toast.d.ts",
       "import": "./dist/toast.js"
     },
+    "./scoped": {
+      "types": "./dist/scoped.d.ts",
+      "import": "./dist/scoped.js"
+    },
     "./fello.css": "./dist/fello.css",
+    "./fello.scoped.css": "./dist/fello.scoped.css",
     "./tokens.css": "./tokens/tokens.css",
     "./tokens.root.css": "./tokens/tokens.root.css",
     "./shadcn-compat.css": "./tokens/shadcn-compat.css",
+    "./shadcn-compat.hsl.css": "./tokens/shadcn-compat.hsl.css",
     "./tokens": {
       "types": "./dist/tokens.d.ts",
       "import": "./dist/tokens.js"
     },
+    "./palettes": {
+      "types": "./dist/palettes.d.ts",
+      "import": "./dist/palettes.js"
+    },
     "./design-tokens.json": "./tokens/design-tokens.json",
     "./AGENTS.md": "./AGENTS.md",
     "./tokens.md": "./tokens/tokens.md",
     "./design-system/*": "./design-system/*"
   },
   "scripts": {
-    "tokens": "node scripts/generate-tokens.mjs",
+    "bundle": "node scripts/build-bundle.mjs",
+    "tokens": "node scripts/build-bundle.mjs && node scripts/generate-tokens.mjs",
     "build": "yarn tokens && tsup",
     "dev": "tsup --watch",
     "typecheck": "tsc --noEmit",
     "prepublishOnly": "yarn build",
     "site": "vite",
-    "build:site": "node scripts/build-skill.mjs && node scripts/build-assets.mjs && vite build && node scripts/build-hosted.mjs",
+    "build:site": "node scripts/build-bundle.mjs && node scripts/build-skill.mjs && node scripts/build-assets.mjs && vite build && node scripts/build-hosted.mjs",
     "verify": "yarn tokens && yarn typecheck && bunx tsup && bunx vite build",
     "skill": "node scripts/build-skill.mjs",
     "assets": "node scripts/build-assets.mjs",
-    "hosted": "node scripts/build-hosted.mjs"
+    "hosted": "node scripts/build-hosted.mjs",
+    "check:geometry": "node scripts/check-geometry.mjs",
+    "check:scope": "node scripts/check-scope.mjs",
+    "check:palette": "node scripts/check-palette.mjs"
   },
   "dependencies": {
     "@radix-ui/react-tabs": "^1.1.21",

package/scripts/check-palette.mjs

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+/**
+ * check-palette: proves a palette keeps the kit's promises (D15). A palette is a set of values for the contract
+ * (tokens/design-tokens.json "palette"); this applies it over the kit, resolves every token in light, night and the
+ * navy ground, and checks what the kit checks for itself.
+ *
+ *   node scripts/check-palette.mjs                  the built-ins (tokens/_palettes.css), and that every colour a
+ *                                                   component reads follows the contract; generate-tokens runs the first
+ *   node scripts/check-palette.mjs my-palette.css   an app's own palette file(s), written as
+ *                                                   [data-palette="name"] { ... } for light and
+ *                                                   [data-palette="name"][data-theme="dark"] { ... } for dark
+ *   node scripts/check-palette.mjs --emit my-palette.css > my-palette.shipped.css
+ *                                                   checks it, then writes the CSS to ship: the built-ins' own form, so
+ *                                                   the palette works on <html> or any container, nested either way, in
+ *                                                   light and dark, in fello.css and fello.scoped.css, before or after the
+ *                                                   kit; a dark value it leaves out is the kit's, derived from the dark
+ *                                                   inputs (the report goes to stderr, and it writes nothing on an error)
+ *   node scripts/check-palette.mjs --selftest       planted bad palettes and a planted leftover, each caught for its reason
+ *
+ * Errors (exit 1):
+ *   contract        a token outside the contract (the nearest contract token is suggested)
+ *   word            a word token under 4.5:1 on a ground it can sit on, or a word under 4.5:1 on its own tint
+ *   focus           the focus ring under 3:1 on any ground
+ *   act             the act fill (the heading colour) under 3:1 on a ground a button sits on
+ *   chart-distinct  two chart tones closer than CIEDE2000 10
+ *   chart-contrast  a chart tone under 3:1 on the chart ground (a tone drawn with its word is reported instead)
+ *   leftover        (the kit's own check) a colour a component reads that no contract token moves, in light or dark
+ * Reports (no exit): a dark value the palette leaves out, and what dark paints instead; a file that is not in the
+ * shipped form.
+ */
+import { readFileSync, readdirSync, existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import {
+  root, tokens, night, known, contract, CONTRACT, resolved, ratio, deltaE, GROUNDS, WORDS, PAIRS, parsePalettes, builtIns,
+  paletteCss, parseColour,
+} from './token-model.mjs';
+
+const LIGHT = Object.fromEntries(tokens);
+const NIGHT = Object.fromEntries(night);
+const KIT = resolved();
+const CHART = contract.filter((t) => t.group === 'chart');
+const ACT_GROUNDS = ['--color-bg-page', '--color-surface', '--ws-raised', '--ws-tray'];
+const CHART_GROUND = '--color-bg-page';
+const THEMES = ['light', 'dark', 'navy'];
+const fx = (r) => r.toFixed(2);
+
+const refs = (v = '') => [...v.matchAll(/var\(\s*(--[a-z0-9-]+)/g)].map(([, n]) => n);
+/** The contract tokens a kit token derives from in one theme's map, through every var() it reads. */
+function inputsOf(name, map = LIGHT, seen = new Set()) {
+  if (CONTRACT.has(name)) return [name];
+  if (seen.has(name)) return [];
+  seen.add(name);
+  return [...new Set(refs(map[name]).flatMap((r) => inputsOf(r, map, seen)))];
+}
+const distance = (a, b) => {
+  const d = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    let prev = d[0]++;
+    for (let j = 1; j <= b.length; j++) [prev, d[j]] = [d[j], Math.min(d[j] + 1, d[j - 1] + 1, prev + (a[i - 1] === b[j - 1] ? 0 : 1))];
+  }
+  return d[b.length];
+};
+function suggest(name) {
+  const from = known.has(name) ? inputsOf(name) : [];
+  if (from.length) return `it derives from ${from.join(', ')}: set ${from.length > 1 ? 'those' : 'that'} instead`;
+  const words = (n) => new Set(n.slice(2).split('-'));
+  const shared = (a, b) => [...words(a)].filter((w) => words(b).has(w)).length;
+  const near = [...CONTRACT].sort((a, b) => shared(name, b) - shared(name, a) || distance(name, a) - distance(name, b))[0];
+  return `the nearest contract token is ${near}`;
+}
+
+/**
+ * Checks palettes ({ name: { light, dark } } of token -> value) as they paint once shipped in the built-ins' form (the
+ * generator for a built-in, `--emit` for an app): a dark value left out takes the kit's dark expression, and a contract
+ * token the kit derives (the focus ring from the heading) recomputes from the palette's inputs unless it sets it.
+ * `shipped: false` (an app's file not written by --emit) adds a report that it should be.
+ */
+export function checkPalettes(palettes, { shipped = true } = {}) {
+  const out = { palettes: {}, errors: [], reports: [] };
+  for (const [id, p] of Object.entries(palettes)) {
+    const errors = [], reports = [];
+    const err = (kind, text) => errors.push({ kind, text });
+    const set = new Set([...Object.keys(p.light), ...Object.keys(p.dark)]);
+    for (const n of set) if (!CONTRACT.has(n)) err('contract', `${n} is not in the palette contract (${known.has(n) ? 'a derived token' : 'not a token'}); ${suggest(n)}`);
+    const light = Object.fromEntries(Object.entries(p.light).filter(([n]) => CONTRACT.has(n)));
+    const dark = Object.fromEntries(Object.entries(p.dark).filter(([n]) => CONTRACT.has(n)));
+    const R = resolved({ light, dark });
+    for (const n of Object.keys(light).filter((n) => !(n in dark)))
+      reports.push(`dark: no ${n}, so it takes the kit's dark ${n} (${R.dark[n]}), derived from the dark inputs`);
+    if (!shipped && set.size)
+      reports.push(`not in the shipped form: as written, its light values also paint in dark wherever the theme sits on another element than the palette; ship the output of \`check-palette --emit\``);
+
+    for (const theme of THEMES) {
+      const v = R[theme];
+      const at = (n) => `${n} ${v[n]}`;
+      /** One line per colour that fails: on how many grounds, and the worst. */
+      const onGrounds = (kind, what, fg, grounds, min) => {
+        const low = grounds.map(([g, label]) => [label, g, ratio(v[fg], v[g])]).filter(([, , r]) => r < min).sort((a, b) => a[2] - b[2]);
+        if (low.length)
+          err(kind, `${theme}: ${what} ${v[fg]} is ${low.length === 1 ? '' : `under ${min}:1 on ${low.length} grounds, lowest `}${fx(low[0][2])}:1 on the ${low[0][0]} (${at(low[0][1])})${low.length === 1 ? `, under ${min}` : ''}`);
+      };
+      for (const w of WORDS) onGrounds('word', w, w, Object.entries(GROUNDS), 4.5);
+      for (const [w, g] of PAIRS) {
+        const r = ratio(v[w], v[g]);
+        if (r < 4.5) err('word', `${theme}: ${at(w)} on ${at(g)} is ${fx(r)}:1, under 4.5`);
+      }
+      onGrounds('focus', 'the focus ring', '--ws-focus-color', Object.entries(GROUNDS), 3);
+      onGrounds('act', 'the act fill', '--color-text-heading', ACT_GROUNDS.map((g) => [g, GROUNDS[g]]), 3);
+      for (let i = 0; i < CHART.length; i++) {
+        const a = CHART[i];
+        const r = ratio(v[a.name], v[CHART_GROUND]);
+        if (r < 3) {
+          // a tone drawn beside its word: reported when the palette moves it, the kit's own two are said once below
+          if (a.withWords) v[a.name] !== KIT[theme][a.name] && reports.push(`${theme}: ${at(a.name)} is ${fx(r)}:1 on the chart ground, drawn with its word (reported, not required)`);
+          else err('chart-contrast', `${theme}: ${at(a.name)} on the chart ground (${at(CHART_GROUND)}) is ${fx(r)}:1, under 3`);
+        }
+        for (const b of CHART.slice(i + 1)) {
+          const d = deltaE(v[a.name], v[b.name], v[CHART_GROUND]);
+          if (d < 10) err('chart-distinct', `${theme}: ${at(a.name)} and ${at(b.name)} are CIEDE2000 ${d.toFixed(1)} apart, under 10`);
+        }
+      }
+    }
+    out.palettes[id] = { set: [...set], errors, reports };
+    out.errors.push(...errors.map((e) => ({ ...e, palette: id })));
+    out.reports.push(...reports.map((text) => ({ palette: id, text })));
+  }
+  return out;
+}
+
+/** The built-ins plus the kit itself as "default" (no attribute), held to the same checks. */
+export const withDefault = (palettes) => ({ default: { light: {}, dark: {} }, ...palettes });
+
+export function formatReport(result) {
+  const lines = [];
+  for (const [id, r] of Object.entries(result.palettes)) {
+    lines.push(`${id}: ${r.errors.length ? `${r.errors.length} errors` : 'passes'} (sets ${r.set.length}: ${r.set.join(', ') || 'nothing'})`);
+    for (const e of r.errors) lines.push(`  error ${e.kind}: ${e.text}`);
+    for (const t of r.reports) lines.push(`  report: ${t}`);
+  }
+  const n = Object.keys(result.palettes).length;
+  const withWords = CHART.filter((t) => t.withWords).map((t) => `${t.name} ${fx(ratio(KIT.light[t.name], KIT.light[CHART_GROUND]))}:1`);
+  lines.push(`${n} palette${n === 1 ? '' : 's'}: ${result.errors.length} errors, ${result.reports.length} reports. Checked in light, night and navy: every word AA on every ground, the focus ring and the act fill 3:1, the chart tones CIEDE2000 10 apart and 3:1 on the chart ground (the kit's ${withWords.join(' and ')} are drawn beside their words, so their ratio is reported, not required).`);
+  return lines.join('\n');
+}
+
+/** The CSS to ship for a file's palettes (what --emit writes): each in the built-ins' own form. */
+export function emitPalettes(palettes, file = 'a palette file') {
+  return [
+    `/* Generated by check-palette --emit from ${file}. Ship this file, not the source: it works on <html> or on any`,
+    `   container, nested either way, in light and dark, in fello.css and fello.scoped.css, loaded before or after the kit. */`,
+    ...Object.entries(palettes).map(([id, p]) => paletteCss(id, p, 'root', { navy: true })),
+    '',
+  ].join('\n');
+}
+
+/* ---- leftovers: every colour a component reads follows the contract, in light and dark (D15) ----
+   For each token a component's style.css (or _house.css) reads, in light and in night: if it paints a colour, the
+   contract tokens it derives from, through every var(). One with none is a kit constant no palette can move. The
+   deliberate ones are ruled below: brand marks that keep the brand, and pairs whose words would lose AA if their
+   ground moved. A transparent value, or black at any alpha (a drop), is not a colour here. */
+const KEEP = {
+  '--ws-mask': [null, 'the opaque stop of a mask: only its alpha is read, it never paints'],
+  // brand marks, read only by the marketing set
+  '--color-brand-navy': [['KitButton', 'Cover'], 'the brand navy: the logo, and the words on the salmon act'],
+  '--color-brand-salmon': [['Cover'], 'the brand salmon logo mark'],
+  '--color-brand-mid-blue': [['KitButton'], "the brand navy act's gradient"],
+  '--color-button-border': [['KitButton'], "the salmon act's foot"],
+  '--gradient-btn-primary': [['KitButton'], 'the brand salmon act'],
+  '--color-white': [['KitButton'], 'white words on the brand navy act'],
+  // the navy ground's fields: white with navy words, a brand pair (read under the navy ground only)
+  '--color-gray-2': [['Combobox'], "a chip inside the navy ground's white field, a brand pair with its navy words"],
+};
+const KEEP_DARK = {
+  '--ws-inverse': [null, 'the toast, note and footer navy in dark: a brand pair with white words (D12)'],
+  '--ws-on-inverse': [null, 'white words on that navy, the other half of the pair'],
+};
+const kept = (rules, n, file) => rules[n] && (!rules[n][0] || rules[n][0].some((c) => file.startsWith(`${c}/`)));
+const paints = (value) => {
+  const cols = [...(value || '').matchAll(/#[0-9a-f]{3,8}\b|rgba?\([^()]*\)/gi)].map(([c]) => parseColour(c)).filter(Boolean);
+  return cols.some(([r, g, b, a]) => a > 0 && (r || g || b));
+};
+export function leftovers(parts) {
+  const DARK = { ...LIGHT, ...NIGHT };
+  const found = [];
+  for (const [file, css] of parts) {
+    const read = new Set(refs(css.replace(/\/\*[\s\S]*?\*\//g, '')).filter((n) => known.has(n)));
+    for (const n of read)
+      for (const [theme, map] of [['light', LIGHT], ['dark', DARK]]) {
+        if (CONTRACT.has(n) || kept(KEEP, n, file) || (theme === 'dark' && kept(KEEP_DARK, n, file))) continue;
+        if (!paints(KIT[theme][n])) continue;
+        if (!inputsOf(n, map).length) found.push(`${file}: ${n} paints ${KIT[theme][n].slice(0, 60)} in ${theme} and no contract token moves it`);
+      }
+  }
+  return [...new Set(found)];
+}
+/** The kit's own parts: _house.css and every component's style.css, as files (the package ships them). */
+export function componentParts() {
+  const dir = join(root, 'design-system/components');
+  return [['_house.css', readFileSync(join(dir, '_house.css'), 'utf8')],
+    ...readdirSync(dir, { withFileTypes: true }).filter((d) => d.isDirectory() && existsSync(join(dir, d.name, 'style.css')))
+      .map((d) => [`${d.name}/style.css`, readFileSync(join(dir, d.name, 'style.css'), 'utf8')])];
+}
+
+/* ---- the self-test: planted bad palettes, each caught for the reason it was planted ---- */
+function selftest() {
+  const planted = `
+    [data-palette="outside"] { --ws-surface-sunk: #f0f0f0; --ws-trey: #dddddd; }
+    [data-palette="muted"] { --color-text-muted: #9a9a9a; }
+    [data-palette="muted"][data-theme="dark"] { --color-text-muted: #8494a5; }
+    [data-palette="focus"] { --ws-focus-color: #d0d0d0; }
+    [data-palette="focus"][data-theme="dark"] { --ws-focus-color: #1a2631; }
+    [data-palette="act"] { --color-text-heading: #c8c8c8; }
+    [data-palette="act"][data-theme="dark"] { --color-text-heading: #e8edf3; }
+    [data-palette="close"] { --ws-chart-past-half: #2f6189; }
+    [data-palette="close"][data-theme="dark"] { --ws-chart-past-half: #9a84ee; }
+    [data-palette="faint"] { --ws-chart-navy-light: #d4e2ee; }
+    [data-palette="faint"][data-theme="dark"] { --ws-chart-navy-light: #6e9cc4; }
+    [data-palette="nodark"] { --ws-edge: #e0e0e0; }
+    [data-palette="clean"] { --color-text-interactive: #093555; }
+    [data-palette="clean"][data-theme="dark"] { --color-text-interactive: #e8edf3; }
+  `;
+  const { palettes } = parsePalettes(planted);
+  const r = checkPalettes(palettes);
+  const kinds = (id) => new Set(r.palettes[id].errors.map((e) => e.kind));
+  const fails = [];
+  const expect = (cond, what) => cond || fails.push(what);
+  const outside = r.palettes.outside.errors.map((e) => e.text).join(' ');
+  expect(kinds('outside').has('contract') && /--color-bg-page/.test(outside), 'a derived token is refused, pointing at the contract token it derives from');
+  expect(/nearest contract token is --ws-tray\b/.test(outside), 'an unknown token gets the nearest contract name');
+  expect(kinds('muted').has('word') && !kinds('muted').has('contract'), 'a muted word under AA is an error');
+  expect(kinds('focus').has('focus') && r.palettes.focus.errors.some((e) => e.text.startsWith('dark:')), 'a weak focus ring is caught in light and in dark');
+  expect(kinds('act').has('act'), 'a pale act fill is caught');
+  expect(kinds('close').has('chart-distinct') && !kinds('close').has('chart-contrast'), 'two chart tones too close are caught');
+  expect(kinds('faint').has('chart-contrast'), 'a faint chart tone is caught');
+  expect(!r.palettes.nodark.errors.length && r.palettes.nodark.reports.some((t) => /^dark: no --ws-edge, so it takes the kit's dark --ws-edge \(#1e2a36\)/.test(t)), 'a missing dark value is reported and falls back to the kit\'s dark, not the light one');
+  expect(!r.palettes.clean.errors.length, 'a sound palette passes');
+  // what --emit writes reads back as the same palette, and nests on the theme around it and inside it
+  const emitted = emitPalettes(palettes, 'the self-test');
+  const back = parsePalettes(emitted).palettes;
+  expect(JSON.stringify(back.clean) === JSON.stringify({ light: palettes.clean.light, dark: palettes.clean.dark }), 'an emitted palette parses back to itself');
+  expect(back.nodark.dark['--ws-edge'] === NIGHT['--ws-edge'], 'an emitted palette fills a missing dark value with the kit\'s dark one');
+  expect(/@scope \(\[data-theme="dark"\]\) \{\n {2}\[data-palette="clean"\]/.test(emitted) && /@scope \(\[data-palette="clean"\]\) \{\n {2}\[data-theme="dark"\]/.test(emitted), 'an emitted palette carries the @scope rules that let it nest');
+  const built = checkPalettes(withDefault(builtIns()));
+  expect(!built.errors.length, 'the built-in palettes pass');
+  // the leftover check: a planted part that reads two kit constants is caught, a part that reads the contract is not
+  const plantedLeft = leftovers([['Planted/style.css', '.ws-planted { background: var(--color-gray-1); border-color: var(--color-ai-cyan); color: var(--color-text-body); box-shadow: var(--ws-shadow-pop); }']]);
+  expect(['--color-gray-1', '--color-ai-cyan'].every((n) => plantedLeft.some((l) => l.includes(n))) && plantedLeft.every((l) => /--color-gray-1|--color-ai-cyan/.test(l)), `a planted leftover is caught, and only it (got ${JSON.stringify(plantedLeft)})`);
+  expect(leftovers([['Planted/style.css', '.ws-planted { color: var(--color-brand-salmon) }']]).length === 2, 'a brand constant ruled for one component is a leftover in another');
+  const kit = leftovers(componentParts());
+  expect(!kit.length, `the kit has no leftover (got ${kit.length}: ${kit.slice(0, 3).join('; ')})`);
+  if (fails.length) {
+    console.error(`check-palette self-test failed:\n  ${fails.join('\n  ')}\n\n${formatReport(r)}`);
+    process.exit(1);
+  }
+  console.log(`check-palette self-test: ${Object.keys(palettes).length} planted palettes, each caught for its reason; emitted palettes parse back and carry their @scope rules; a planted leftover is caught; the built-ins pass and the kit has no leftover`);
+}
+
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+  const args = process.argv.slice(2);
+  if (args.includes('--selftest')) selftest();
+  else if (args.includes('--emit')) {
+    const files = args.filter((a) => a !== '--emit');
+    if (!files.length) { console.error('--emit takes a palette file'); process.exit(2); }
+    const all = {};
+    for (const file of files) Object.assign(all, parsePalettes(readFileSync(file, 'utf8')).palettes);
+    const r = checkPalettes(all);
+    console.error(formatReport(r));
+    if (r.errors.length || !Object.keys(all).length) process.exit(1);
+    process.stdout.write(emitPalettes(all, files.join(', ')));
+  } else if (!args.length) {
+    const r = checkPalettes(withDefault(builtIns()));
+    console.log(formatReport(r));
+    const left = leftovers(componentParts());
+    console.log(left.length ? `${left.length} leftovers:\n  ${left.join('\n  ')}` : `leftovers: 0 (every colour a component reads follows a contract token in light and dark; ${Object.keys(KEEP).length + Object.keys(KEEP_DARK).length} brand constants ruled)`);
+    if (r.errors.length || left.length) process.exit(1);
+  } else {
+    let failed = false;
+    for (const file of args) {
+      const css = readFileSync(file, 'utf8');
+      const { palettes, other } = parsePalettes(css);
+      console.log(`== ${file}`);
+      if (!Object.keys(palettes).length) {
+        console.log('  error: no [data-palette="name"] block');
+        failed = true;
+        continue;
+      }
+      for (const sel of other) console.log(`  report: "${sel}" is not a palette block, so it is not checked`);
+      const r = checkPalettes(palettes, { shipped: /@scope\s*\(\s*\[data-palette/.test(css) });
+      console.log(formatReport(r));
+      failed ||= r.errors.length > 0;
+    }
+    if (failed) process.exit(1);
+  }
+}