@bongos/core 1.19.457 → 1.19.459

package/modules/hall-ui/public/watch.states.json

@@ -46,6 +46,52 @@
     },
     "out": {
       "auth": false
+    },
+    "operations": {
+      "auth": true,
+      "actions": [
+        [
+          "wait",
+          700
+        ],
+        [
+          "click",
+          "#tab-operations"
+        ],
+        [
+          "wait",
+          300
+        ]
+      ],
+      "expect": {
+        "visible": [
+          "#pane-operations",
+          "#sessions-stats"
+        ]
+      }
+    },
+    "security": {
+      "auth": true,
+      "actions": [
+        [
+          "wait",
+          700
+        ],
+        [
+          "click",
+          "#tab-security"
+        ],
+        [
+          "wait",
+          300
+        ]
+      ],
+      "expect": {
+        "visible": [
+          "#pane-security",
+          "#watch-scroll"
+        ]
+      }
     }
   },
   "reducedMotion": {
@@ -56,5 +102,6 @@
         600
       ]
     ]
-  }
+  },
+  "_states": "task 1003469: the three tabs are three states, so the Operations figure bands and the recent-sessions ledger, and the Security panel's four groups, are each measured and not only the People tab the page opens on."
 }

package/modules/ui-design/kit/README.md

@@ -3,11 +3,13 @@
 The stub, the renderer/auditor, the interaction probes, the mock checker and the contrast probe any builder points at any surface of any instance ([task 1003320](https://cloudbongos.com/builders#/task/1003320), [ADR 0197](../../../docs/adr/<redacted>.md)). Plain Node; the browser is the system Edge or Chrome via `playwright-core` (a devDependency — nothing is downloaded).
 
 ```
-node modules/ui-design/kit/serve.js                     # the stub (SURFACE, PREFIX, AUTH=1, CHILD=1, LIVE=…, FAIL=…, STUB_PORT)
-node modules/ui-design/kit/render.js --page /projects   # every state × 1440/390/320 × dark/light, audited against the floors
-node modules/ui-design/kit/probe.js  --page /projects   # the interaction contract as PASS/FAIL lines
-node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html
-node modules/ui-design/kit/contrast.js --pack | --url <url> [--glyphs sel,sel]
+node modules/ui-design/kit/serve.js                     # the stub (SURFACE, PREFIX, AUTH=1, CHILD=1, LIVE=…, FAIL=…, STYLE=<look>, STUB_PORT)
+node modules/ui-design/kit/render.js --page /projects   # every state × 1440/390/320 × dark/light, audited against the floors (--style <look>)
+node modules/ui-design/kit/probe.js  --page /projects   # the interaction contract as PASS/FAIL lines (--style <look>)
+node modules/ui-design/kit/check-mock.js --file docs/design/mocks/hub/v2.html          # (--pack <look> for a style's own mock)
+node modules/ui-design/kit/contrast.js --pack [look] | --url <url> [--glyphs sel,sel]
 ```
 
+A **look** is a branding pack from the module's style library (`modules/ui-design/styles/<name>/`, task 1003323): `STYLE=<name>` lays it over the instance's own pack through `GDS_BRANDING_FILE`, so any surface renders under any look with no page edit.
+
 A surface describes itself in two JSON files beside it — `<page>.states.json` and `<page>.probes.json` — in the vocabularies `lib.js` defines and validates. The full loop, the file shapes and the failure table: [`docs/recipes/ui-look-before-you-ship.md`](../../../docs/recipes/ui-look-before-you-ship.md). Exit codes everywhere: 0 clean · 1 problems · 2 a broken file or usage · 3 no browser.

package/modules/ui-design/kit/check-mock.js

@@ -14,8 +14,10 @@
 //     shadow). The em dash ban is Cloud Bongos's, not the platform's: an instance
 //     whose DESIGN.md never mentions it is not held to it.
 //
-//   node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys THESIS,BAR] [--design <DESIGN.md>] [--no-taste]
+//   node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys THESIS,BAR] [--design <DESIGN.md>] [--no-taste] [--pack <style>]
 //
+// `--pack <style>` checks a style's mock against that look's own colours (the pinned-literal
+// rule) and, unless --design says otherwise, its own DESIGN.md bans (task 1003323).
 // Prints PASS/FAIL/WARN per rule; exit 1 on any FAIL, 2 on usage.
 const fs = require('node:fs');
 const path = require('node:path');
@@ -89,7 +91,8 @@ function checkMock(html, { bans = new Set(), packColors = {}, states = [], keys
   ok('no literal hex colour (the fifteen via var()/color-mix(); black or white with alpha only)', hexes.length === 0, hexes.length ? [...new Set(hexes)].slice(0, 12).join(',') : '');
   const rgbLit = [...css.matchAll(/rgba?\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)/g)].filter((x) => !((x[1] === '0' && x[2] === '0' && x[3] === '0') || (x[1] === '255' && x[2] === '255' && x[3] === '255')));
   ok('rgb() literals only as black or white with alpha', rgbLit.length === 0, rgbLit.length ? `${rgbLit.length} found` : '');
-  const pinned = Object.entries(packColors).filter(([, v]) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v) && new RegExp(v.replace('#', '#'), 'i').test(css)).map(([k]) => k);
+  // a pack whose card is pure white (the expedition's) must not turn the one legal literal into a pin
+  const pinned = Object.entries(packColors).filter(([, v]) => typeof v === 'string' && /^#[0-9a-f]{6}$/i.test(v) && !BLACK_OR_WHITE.test(v.slice(1).toLowerCase()) && new RegExp(v.replace('#', '#'), 'i').test(css)).map(([k]) => k);
   ok('no pack colour pinned as a literal (a var() of the contract token instead)', pinned.length === 0, pinned.join(','));
 
   // ── the taste bans the instance declared ──
@@ -126,16 +129,20 @@ function checkMock(html, { bans = new Set(), packColors = {}, states = [], keys
 function main() {
   const args = process.argv.slice(2);
   const file = lib.argOf(args, '--file', null);
-  if (!file || lib.hasFlag(args, '--help')) { process.stderr.write('usage: node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys A,B] [--design <DESIGN.md>] [--no-taste]\n'); process.exit(lib.EXIT.USAGE); }
+  if (!file || lib.hasFlag(args, '--help')) { process.stderr.write('usage: node modules/ui-design/kit/check-mock.js --file <mock.html> [--states a,b] [--keys A,B] [--design <DESIGN.md>] [--no-taste] [--pack <style>]\n'); process.exit(lib.EXIT.USAGE); }
   if (!fs.existsSync(file)) { process.stderr.write(`check-mock: not found: ${file}\n`); process.exit(lib.EXIT.USAGE); }
-  const designPath = lib.argOf(args, '--design', path.join(lib.REPO_ROOT, 'DESIGN.md'));
+  const styleArg = lib.argOf(args, '--pack', null);
+  const style = styleArg ? lib.resolveStyle(styleArg) : null;
+  if (styleArg && !style) { process.stderr.write(`check-mock: --pack "${styleArg}" is not a style under modules/ui-design/styles/ (${lib.listStyles().join(', ') || 'none'})\n`); process.exit(lib.EXIT.USAGE); }
+  const designPath = lib.argOf(args, '--design', style ? path.join(style.dir, 'DESIGN.md') : path.join(lib.REPO_ROOT, 'DESIGN.md'));
   let bans = new Set();
   if (!lib.hasFlag(args, '--no-taste')) {
     if (fs.existsSync(designPath)) bans = readDesignBans(fs.readFileSync(designPath, 'utf8'));
     else process.stdout.write(`WARN taste bans off: no DESIGN.md at ${designPath} (the platform rules still apply)\n`);
   }
   let packColors = {};
-  try { packColors = lib.packColors(lib.instancePack()); } catch { packColors = {}; }
+  if (style) packColors = lib.packColors(style.pack);
+  else { try { packColors = lib.packColors(lib.instancePack()); } catch { packColors = {}; } }
   const results = checkMock(fs.readFileSync(file, 'utf8'), { bans, packColors, states: lib.listArg(args, '--states', []), keys: lib.listArg(args, '--keys', []) });
   for (const [s, rule, detail] of results) process.stdout.write(`${s.padEnd(4)} ${rule}${detail ? '  (' + detail + ')' : ''}\n`);
   const fails = results.filter((r) => r[0] === 'FAIL').length;

package/modules/ui-design/kit/contrast.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 'use strict';
 // contrast.js — the contrast probe (task 1003320, ADR 0197), three ways:
-//   --pack                 the instance's branding pack: every ink on every ground,
-//                          light values from the pack (pure; no browser)
+//   --pack [name]          the instance's branding pack — or, named, a look from the
+//                          style library (modules/ui-design/styles/<name>/pack.json, or a
+//                          pack.json path): every ink on every ground, light values
+//                          from the pack (pure; no browser)
 //   --url <url> | --file <html>   walk every visible text element in dark + light
 //                          and compute the real WCAG ratio against its COMPOSITED
 //                          background (the degraded static detector cannot do this)
@@ -11,7 +13,7 @@
 //                          ground's median — for text over a moving or textured
 //                          ground where the stylesheet cannot say what is under it
 //
-//   node modules/ui-design/kit/contrast.js --pack
+//   node modules/ui-design/kit/contrast.js --pack [expedition]
 //   node modules/ui-design/kit/contrast.js --url http://127.0.0.1:3412/projects [--modes dark,light] [--glyphs "#projTrig,.foot a"]
 //   node modules/ui-design/kit/contrast.js --file docs/design/mocks/hub/v2.html
 //
@@ -110,12 +112,17 @@ async function glyphContrast(page, selector) {
 
 async function main() {
   const args = process.argv.slice(2);
-  if (lib.hasFlag(args, '--help')) { process.stderr.write('usage: node modules/ui-design/kit/contrast.js --pack | --url <url> | --file <html> [--modes dark,light] [--glyphs sel,sel]\n'); process.exit(lib.EXIT.USAGE); }
+  if (lib.hasFlag(args, '--help')) { process.stderr.write('usage: node modules/ui-design/kit/contrast.js --pack [name] | --url <url> | --file <html> [--modes dark,light] [--glyphs sel,sel]\n'); process.exit(lib.EXIT.USAGE); }
   const url = lib.argOf(args, '--url', null), file = lib.argOf(args, '--file', null);
   let failures = 0;
   if (lib.hasFlag(args, '--pack') || (!url && !file)) {
-    const rows = packContrast(lib.instancePack());
-    process.stdout.write('the pack (light values):\n');
+    // `--pack` alone is the instance's; `--pack <name>` is a look from the style library
+    const packArg = lib.argOf(args, '--pack', null);
+    const named = packArg && !packArg.startsWith('--') ? packArg : null;
+    const style = named ? lib.resolveStyle(named) : null;
+    if (named && !style) { process.stderr.write(`contrast: --pack "${named}" is not a style under modules/ui-design/styles/ (${lib.listStyles().join(', ') || 'none'}) nor a pack.json path\n`); process.exit(lib.EXIT.USAGE); }
+    const rows = packContrast(style ? style.pack : lib.instancePack());
+    process.stdout.write(`${style ? `the ${style.name} pack` : 'the pack'} (light values):\n`);
     for (const r of rows) { process.stdout.write(`  ${r.ok === null ? 'SKIP' : r.ok ? 'PASS' : 'FAIL'} ${String(r.fg).padEnd(11)} on ${String(r.bg).padEnd(8)} ${r.ratio === null ? r.note : r.ratio + ':1 (need ' + r.need + ')'}\n`); if (r.ok === false) failures++; }
     if (!url && !file) { process.stdout.write(failures ? `\n${failures} pack pair(s) below the floor\n` : '\nPACK CLEAN\n'); process.exit(failures ? lib.EXIT.PROBLEMS : lib.EXIT.CLEAN); }
   }

package/modules/ui-design/kit/lib.js

@@ -10,12 +10,14 @@
 // Exit codes shared by every kit CLI: 0 clean · 1 problems/FAILs · 2 usage or a
 // contract error (a bad file, a missing page) · 3 no browser / no playwright-core.
 const fs = require('node:fs');
+const os = require('node:os');
 const path = require('node:path');
 const net = require('node:net');
 const { spawn } = require('node:child_process');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
 const KIT_DIR = __dirname;
+const STYLES_DIR = path.join(__dirname, '..', 'styles');
 const EXIT = Object.freeze({ CLEAN: 0, PROBLEMS: 1, USAGE: 2, NO_BROWSER: 3 });
 
 // The floors (modules/ui-design/CLAUDE.md "The platform's floors"). The names are
@@ -342,10 +344,11 @@ function freePort() {
     s.listen(0, '127.0.0.1', () => { const p = s.address().port; s.close(() => resolve(p)); });
   });
 }
-async function startStub({ surface, auth = false, port, prefix, child = false, fixtures } = {}) {
+async function startStub({ surface, auth = false, port, prefix, child = false, fixtures, style } = {}) {
   const p = port || await freePort();
   const env = { ...process.env, STUB_PORT: String(p), AUTH: auth ? '1' : '0', CHILD: child ? '1' : '0' };
   if (surface) env.SURFACE = surface;
+  if (style) env.STYLE = style;
   if (prefix) env.PREFIX = prefix;
   if (fixtures) env.FIXTURE_ALIAS = JSON.stringify(fixtures);
   const proc = spawn(process.execPath, [path.join(KIT_DIR, 'serve.js')], { env, stdio: ['ignore', 'pipe', 'pipe'] });
@@ -375,6 +378,39 @@ function composite(fg, bg) { const a = fg[3] == null ? 1 : fg[3]; return [fg[0]
 function luminance(c) { const f = (v) => { v /= 255; return v <= 0.03928 ? v / 12.92 : Math.pow((v + 0.055) / 1.055, 2.4); }; return 0.2126 * f(c[0]) + 0.7152 * f(c[1]) + 0.0722 * f(c[2]); }
 function contrastRatio(a, b) { const l1 = luminance(a), l2 = luminance(b); const [hi, lo] = l1 > l2 ? [l1, l2] : [l2, l1]; return (hi + 0.05) / (lo + 0.05); }
 
+// ── the style library (task 1003323) ──────────────────────────────────────────
+// A look is a branding-pack overlay under modules/ui-design/styles/<name>/pack.json
+// (theme.ui: the thirteen colours + the two font stacks), never a fork of a sheet.
+function listStyles(dir = STYLES_DIR) {
+  return fs.existsSync(dir) ? fs.readdirSync(dir).filter((n) => fs.existsSync(path.join(dir, n, 'pack.json'))).sort() : [];
+}
+// A style by NAME (a dir under styles/) or by PATH (a pack.json anywhere) → { name, dir, file, pack }, or null.
+function resolveStyle(nameOrPath, dir = STYLES_DIR) {
+  if (!nameOrPath || typeof nameOrPath !== 'string') return null;
+  const byName = /^[a-z0-9][a-z0-9-]*$/.test(nameOrPath) ? path.join(dir, nameOrPath, 'pack.json') : null;
+  const file = byName && fs.existsSync(byName) ? byName : (nameOrPath.endsWith('.json') && fs.existsSync(nameOrPath) ? path.resolve(nameOrPath) : null);
+  if (!file) return null;
+  const pack = readJson(file);
+  return { name: pack.name || path.basename(path.dirname(file)), dir: path.dirname(file), file, pack };
+}
+// The pack the stub serves under a style: the instance's own pack (config/branding.json,
+// where it has one) with the style's theme.ui laid over it, written to a temp file the
+// core-side transform reads through GDS_BRANDING_FILE (src/branding.js's fixed knob — the
+// one that lets one checkout run two instances). The instance's identity strings stay;
+// only the fifteen change, which is the whole point: a look is a pack, never a page edit.
+function styleBrandingFile(style, root = REPO_ROOT) {
+  const instanceFile = path.join(root, 'config', 'branding.json');
+  const instance = fs.existsSync(instanceFile) ? readJson(instanceFile) : {};
+  const theme = instance.theme || {};
+  const merged = { ...instance, theme: { ...theme, ui: { ...(theme.ui || {}), ...((style.pack.theme || {}).ui || {}) } } };
+  // a pack.json loaded by PATH names itself; the temp file takes a slug of that name, never the name
+  const slug = String(style.name).replace(/[^a-z0-9-]/gi, '_').slice(0, 64) || 'style';
+  const out = path.join(os.tmpdir(), 'ui-design-kit', 'styles', `${slug}.branding.json`);
+  fs.mkdirSync(path.dirname(out), { recursive: true });
+  fs.writeFileSync(out, JSON.stringify(merged));
+  return out;
+}
+
 // The instance's resolved branding pack through the doorway — the only core
 // reach the kit makes (task 1003320). Loaded lazily: the pure helpers above never
 // touch it, so the test pins them without booting the doorway.
@@ -391,9 +427,10 @@ function packColors(pack) {
 }
 
 module.exports = {
-  REPO_ROOT, KIT_DIR, EXIT, FLOORS, SIZES, MODES, CHANNELS, SETTLE_MS, ACTIONS, EXPECT_KEYS,
+  REPO_ROOT, KIT_DIR, STYLES_DIR, EXIT, FLOORS, SIZES, MODES, CHANNELS, SETTLE_MS, ACTIONS, EXPECT_KEYS,
   argOf, hasFlag, listArg, pageName, normalizePageArg, resolveSurfaceDir, sidecarPath, readJson,
   validateActions, runActions, validateExpect, factsInPage, expectProblems, auditFloors, reducedMotionProblems,
   validateStatesFile, validateProbesFile, NoBrowserError, launchBrowser, attachCollectors, withMode,
   freePort, startStub, parseColor, composite, luminance, contrastRatio, instancePack, packColors,
+  listStyles, resolveStyle, styleBrandingFile,
 };

package/modules/ui-design/kit/probe.js

@@ -10,6 +10,7 @@
 // dialog yields Escape; signed out nothing throws.
 //
 //   node modules/ui-design/kit/probe.js --page /projects [--surface <dir|key>] [--probes <file>] [--only <substring>]
+//     --style <name>                     drive the page under a look from the style library (task 1003323)
 //     --base-out <url> --base-in <url>   use running stubs instead of starting two
 //
 // A probe with `continue: true` keeps the previous probe's page (a contract is a
@@ -52,7 +53,9 @@ async function main() {
 
   const stubs = [];
   let baseOut = lib.argOf(args, '--base-out', null), baseIn = lib.argOf(args, '--base-in', null);
-  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child, fixtures: json.stub && json.stub.fixtures };
+  const style = lib.argOf(args, '--style', null);
+  if (style && !lib.resolveStyle(style)) usage(`--style "${style}" is not a style under modules/ui-design/styles/ (${lib.listStyles().join(', ') || 'none'})`);
+  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child, fixtures: json.stub && json.stub.fixtures, style };
   if (!baseOut) { const s = await lib.startStub({ ...stubOpts, auth: false }); stubs.push(s); baseOut = s.base; }
   if (!baseIn) { const s = await lib.startStub({ ...stubOpts, auth: true }); stubs.push(s); baseIn = s.base; }
   const stop = () => stubs.forEach((s) => s.stop());

package/modules/ui-design/kit/render.js

@@ -12,6 +12,7 @@
 //   node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui
 //   node modules/ui-design/kit/render.js --states <file>               (explicit file)
 //     --modes dark,light  --sizes 1440,390,320  --only a,b  --out <dir>
+//     --style <name>      render under a look from the style library (STYLE= on the stubs; task 1003323)
 //     --base-out <url> --base-in <url>   use running stubs instead of starting two
 //
 // Exit 0 ALL CLEAN · 1 problems · 2 usage/contract · 3 no browser.
@@ -21,7 +22,7 @@ const path = require('node:path');
 const lib = require('./lib.js');
 
 function usage(msg) {
-  process.stderr.write(`render: ${msg}\n  node modules/ui-design/kit/render.js --page /projects [--surface <dir|key>] [--states <file>] [--modes dark,light] [--sizes 1440,390,320] [--only a,b] [--out <dir>] [--base-out <url> --base-in <url>]\n`);
+  process.stderr.write(`render: ${msg}\n  node modules/ui-design/kit/render.js --page /projects [--surface <dir|key>] [--states <file>] [--modes dark,light] [--sizes 1440,390,320] [--only a,b] [--style <name>] [--out <dir>] [--base-out <url> --base-in <url>]\n`);
   process.exit(lib.EXIT.USAGE);
 }
 
@@ -71,12 +72,14 @@ async function main() {
   const only = lib.listArg(args, '--only', null);
   const names = Object.keys(json.states).filter((n) => !only || only.includes(n));
   if (!names.length) usage(`--only names no state of ${path.basename(file)}`);
-  const out = path.resolve(lib.argOf(args, '--out', path.join(os.tmpdir(), 'ui-design-kit', surface.replace(/[\\/]/g, '_'), lib.pageName(json.page))));
+  const style = lib.argOf(args, '--style', null);
+  if (style && !lib.resolveStyle(style)) usage(`--style "${style}" is not a style under modules/ui-design/styles/ (${lib.listStyles().join(', ') || 'none'})`);
+  const out = path.resolve(lib.argOf(args, '--out', path.join(os.tmpdir(), 'ui-design-kit', surface.replace(/[\\/]/g, '_'), lib.pageName(json.page) + (style ? `@${style}` : ''))));
   fs.mkdirSync(out, { recursive: true });
 
   const stubs = [];
   let baseOut = lib.argOf(args, '--base-out', null), baseIn = lib.argOf(args, '--base-in', null);
-  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child, fixtures: json.stub && json.stub.fixtures };
+  const stubOpts = { surface, prefix: json.stub && json.stub.prefix, child: json.stub && json.stub.child, fixtures: json.stub && json.stub.fixtures, style };
   if (!baseOut) { const s = await lib.startStub({ ...stubOpts, auth: false }); stubs.push(s); baseOut = s.base; }
   if (!baseIn) { const s = await lib.startStub({ ...stubOpts, auth: true }); stubs.push(s); baseIn = s.base; }
   const stop = () => stubs.forEach((s) => s.stop());
@@ -85,7 +88,7 @@ async function main() {
   try { browser = await lib.launchBrowser(); }
   catch (e) { stop(); process.stderr.write(`render: ${e.message}\n`); process.exit(e instanceof lib.NoBrowserError ? lib.EXIT.NO_BROWSER : lib.EXIT.USAGE); }
 
-  const report = { page: json.page, surface, out, renders: {}, reducedMotion: {} };
+  const report = { page: json.page, surface, style: style || null, out, renders: {}, reducedMotion: {} };
   const problems = [];
   const collectorOpts = { ignoreRequests: json.ignoreRequests, ignoreConsole: json.ignoreConsole };
   try {

package/modules/ui-design/kit/serve.js

@@ -21,6 +21,8 @@
 //   CHILD=1                       the child-instance shape: apex-only regions stripped
 //   LIVE=1 | LIVE=<origin>        proxy the public feeds to the pack's public origin (or the named one)
 //   FAIL=<feed,feed>              those feeds answer 500 (the names in FEEDS below)
+//   STYLE=<name | pack.json>      serve under a look from the style library (modules/ui-design/
+//                                 styles/<name>/pack.json laid over the instance's pack; task 1003323)
 //
 // Exit 2 on a surface that does not resolve. Prints ONE line when listening
 // ("stub on http://…") — render.js and probe.js wait for it.
@@ -40,6 +42,7 @@ const AUTH = process.env.AUTH === '1';
 const CHILD = process.env.CHILD === '1';
 const LIVE = process.env.LIVE || '';
 const FAIL = new Set(String(process.env.FAIL || '').split(',').map((s) => s.trim()).filter(Boolean));
+const STYLE = process.env.STYLE || '';
 // a states file may point a fixture NAME at another FILE (stub.fixtures, task 1003345) — the
 // way the mine view's empty state is rendered without a second stub shape
 const ALIAS = JSON.parse(process.env.FIXTURE_ALIAS || '{}');
@@ -51,6 +54,10 @@ const DIR = lib.resolveSurfaceDir(SURFACE, ROOT);
 if (!DIR) { process.stderr.write(`serve: SURFACE "${SURFACE}" is neither a directory of ${ROOT} nor a module key with a webSurfaces dir\n`); process.exit(lib.EXIT.USAGE); }
 if (!PREFIX.startsWith('/') || !PREFIX.endsWith('/')) { process.stderr.write('serve: PREFIX must start and end with "/"\n'); process.exit(lib.EXIT.USAGE); }
 if (!fs.existsSync(TRANSFORM)) { process.stderr.write(`serve: the transform command is missing: ${TRANSFORM}\n`); process.exit(lib.EXIT.USAGE); }
+const style = STYLE ? lib.resolveStyle(STYLE) : null;
+if (STYLE && !style) { process.stderr.write(`serve: STYLE "${STYLE}" is neither a style under modules/ui-design/styles/ (${lib.listStyles().join(', ') || 'none'}) nor a pack.json path\n`); process.exit(lib.EXIT.USAGE); }
+// the transform resolves the pack itself (src/branding.js); under a style it reads the merged file
+const TRANSFORM_ENV = style ? { ...process.env, GDS_BRANDING_FILE: lib.styleBrandingFile(style, ROOT) } : process.env;
 
 const MIME = {
   '.html': 'text/html; charset=utf-8', '.css': 'text/css; charset=utf-8', '.js': 'application/javascript', '.mjs': 'application/javascript',
@@ -61,7 +68,7 @@ const MIME = {
 
 // The real transforms, as the instance runs them (see ui-kit-transform.js).
 function transform(file) {
-  const r = spawnSync(process.execPath, [TRANSFORM, path.join(DIR, file), ...(CHILD ? ['--child'] : []), '--json'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  const r = spawnSync(process.execPath, [TRANSFORM, path.join(DIR, file), ...(CHILD ? ['--child'] : []), '--json'], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, env: TRANSFORM_ENV });
   if (r.status !== 0) throw new Error(`ui-kit-transform exited ${r.status}: ${(r.stderr || r.stdout || '').trim().slice(0, 600)}`);
   return JSON.parse(r.stdout);
 }
@@ -303,5 +310,5 @@ const server = http.createServer((req, res) => {
 });
 server.listen(PORT, '127.0.0.1', () => {
   const port = server.address().port;
-  process.stdout.write(`stub on http://127.0.0.1:${port}${PREFIX}  surface=${path.relative(ROOT, DIR) || '.'} auth=${AUTH} child=${CHILD} live=${LIVE || '-'} fail=${[...FAIL].join(',') || '-'}\n`);
+  process.stdout.write(`stub on http://127.0.0.1:${port}${PREFIX}  surface=${path.relative(ROOT, DIR) || '.'} auth=${AUTH} child=${CHILD} live=${LIVE || '-'} fail=${[...FAIL].join(',') || '-'} style=${style ? style.name : '-'}\n`);
 });

package/modules/ui-design/styles/README.md

@@ -1,3 +1,55 @@
-# `modules/ui-design/styles/` — reserved home for the style library
+# `modules/ui-design/styles/` — the style library: looks as branding packs
 
-Lands with [task 1003323](https://cloudbongos.com/builders#/task/1003323): looks shipped as branding packs (the fifteen host-overridable tokens plus a `DESIGN.md` per look), with two alternates beside the chrome world, so an instance picks a world instead of inheriting Cloud Bongos's. A look is a pack; it is never a page's private palette.
+A **look** is something a builder or an instance owner picks for a new surface or a whole instance. The library ships looks as **branding packs** ([task 1003323](https://cloudbongos.com/builders#/task/1003323), [ADR 0219](../../../docs/adr/<redacted>.md)): the thirteen colours and the two font stacks of `theme.ui` (the fifteen host-overridable tokens, [ADR 0062 §3](../../../docs/adr/<redacted>.md) / [ADR 0196](../../../docs/adr/<redacted>.md)), a `DESIGN.md` of the look's derived recipes in the frontmatter shape the chrome world uses, and one specimen mock. **Never a fork of a sheet.** The drift tests already prove every served sheet reads only the contract, so a look that needs a sixteenth token is a contract change and an ADR, not a style.
+
+## The catalogue
+
+| Style | `pack.json` | What it is | Origin |
+|---|---|---|---|
+| `chrome-world` | the neutral pack, byte for byte | The canonical entry: one iridescent chrome sculpture in a black void, pale grey paper in light, one warm salmon that lights only the pressable and the live. Its recipes are the repo-root [`DESIGN.md`](../../../DESIGN.md); [`chrome-world/DESIGN.md`](chrome-world/DESIGN.md) points there. | the world round's pick (task 1003296 → 1003298) |
+| `expedition` | warm paper, lamp yellow, Archivo | A printed field journal: a halftone screen over the paper, hairline frames instead of a grid, big heavy uppercase headlines, the yellow as a fill only. [`expedition/DESIGN.md`](expedition/DESIGN.md) | `docs/design/mocks/world/natgeo-editorial` (kept in round 1) |
+| `grove` | pale sage, tan, sea green, Nunito | A sculpted paper garden: soft corners on everything that holds content, tinted shadows, the sea as a slab a whole band sits on, the tan as the one lit thing. [`grove/DESIGN.md`](grove/DESIGN.md) | `docs/design/mocks/world/organic-cards` (kept in round 1) |
+
+The owner looked at both alternates on the sheet on 2026-09-01 and kept them ("styles look good for a start"). Both alternates were **retuned against the contract**, which is a measurement and not a taste: a pack's thirteen are laid through three sheets that already exist (the landing's `world.css`, the hub's `cosmos.css`, the hall's `style.css`) and every pair those sheets paint must clear AA under it. The grove's sage ground lifted and its inks deepened until the hub's fixed status vocabulary and the hall's chips cleared; the expedition's `ink-faint` deepened one step. What a pack cannot carry is **dark**: the contract is light values only, and every sheet's dark tier is its own black, which a look reaches through its accent and its faces. So the grove's green dark ground stays in the world round's mock and does not travel.
+
+## What a style dir is (the contract `tests/ui_design_styles.mjs` enforces)
+
+```
+modules/ui-design/styles/<name>/
+  pack.json    { name, title, summary, origin, theme: { ui: { colors: <the thirteen>, fonts: { display, body, links } } } }
+  DESIGN.md    frontmatter: colors (the thirteen, value for value with pack.json; the dark facts; the derived recipes),
+               typography, rounded, spacing, components; then the look's prose in the root DESIGN.md's sections
+  mock.html    the specimen: no :root, tokens on body, dark written twice, every colour a var()/color-mix() of the pack,
+               one header / main / h1, a skip link, ?state= and ?mode=, served through the stub with the pack spliced in
+```
+
+- `name` is the dir name, kebab-case. `theme.ui.colors` carries **exactly** the thirteen keys of the neutral pack, `fonts` the two stacks and a `links` line for the faces.
+- `chrome-world/pack.json` equals `config/branding.neutral.json`'s `theme.ui` and is pinned to it.
+- Every pack clears the pack floor (every ink on every ground at 4.5:1) and the three token suites in both modes; every mock passes `check-mock`'s platform rules under its own colours and its own `DESIGN.md` bans.
+- The roster above, the module's [`CLAUDE.md`](../CLAUDE.md) and [`/design`](../../../.claude/skills/design/SKILL.md) name every style; a dir that is not named is not a look.
+
+## Using a look
+
+**On the kit** (any surface, any look, no page edit): `STYLE=<name>` on the stub lays the pack over the instance's own (its identity strings stay; only the fifteen change) through `GDS_BRANDING_FILE`, the fixed knob `src/branding.js` already has for running one checkout as two instances.
+
+```
+STYLE=grove node modules/ui-design/kit/serve.js                            # the front door under the grove
+node modules/ui-design/kit/render.js --page / --style expedition           # every state × width × mode, audited
+node modules/ui-design/kit/render.js --page /builders/ranks --surface hall-ui --style grove
+node modules/ui-design/kit/probe.js --page /projects --style grove
+node modules/ui-design/kit/contrast.js --pack expedition                   # the pack floor, no browser
+node modules/ui-design/kit/check-mock.js --file modules/ui-design/styles/grove/mock.html --pack grove
+SURFACE=modules/ui-design/styles/expedition STYLE=expedition node modules/ui-design/kit/serve.js   # the specimen at /mock
+```
+
+**On an instance** (the switch is the contract, not a page): copy the look's `pack.json` `theme` into `config/branding.json`, the file `cloudbongos init` writes ([`docs/branding-contract.md`](../../../docs/branding-contract.md) §Branding a new instance). Every served page re-themes at once, because the server splices `theme.ui` into `:root` at the end of `<head>` and every sheet reads only that. To leave a look, remove the block: the neutral pack (the chrome world) resolves.
+
+**What stays the platform's, whichever look is on:** the dark ground (black), the hall's fixed green / amber / red **verification** vocabulary and the status ledger's pillars (a look must not repaint a status chip, ADR 0196 Context §2), the derived recipes each sheet carries (a corner radius, a shadow, a glass are a sheet's tier, not a pack's), and the platform floors.
+
+## Adding a look
+
+1. Make the dir with the three files; start from the alternate nearest to it.
+2. `node modules/ui-design/kit/contrast.js --pack <name>` until the floor is clean; then `node --test tests/ui_design_styles.mjs`, which runs the world / cosmos / hall suites under the pack and tells you the exact pair that fails. Tune the thirteen, never the sheets.
+3. `node modules/ui-design/kit/check-mock.js --file modules/ui-design/styles/<name>/mock.html --pack <name>` until ALL RULES PASS.
+4. `node modules/ui-design/kit/render.js --page / --style <name>` and look at the shots; the hall's `/builders/ranks` shows the light tier.
+5. Add the row above, the line in the module's `CLAUDE.md` and in `/design`. Ship under a claimed task.

package/modules/ui-design/styles/chrome-world/DESIGN.md

@@ -0,0 +1,56 @@
+---
+name: The Chrome World
+description: One iridescent chrome sculpture in a black void, one warm accent that lights only what is pressable or live. The canonical entry of the style library; its recipes are the repo-root DESIGN.md.
+colors:
+  # ---- contract tier, LIGHT: the thirteen this look's pack.json carries, value for value
+  # (tests/ui_design_styles.mjs holds the two in lockstep). The other two host-overridable
+  # tokens are the font stacks, under `typography`.
+  bg: "#edecee"
+  bg-card: "#fbfafc"
+  bg-deep: "#e2e1e4"
+  bg-frame: "#f6f5f7"
+  ink: "#17181a"
+  ink-soft: "#55565a"
+  ink-faint: "#65656a"
+  rule: "#c6c6c8"
+  rule-soft: "#dcdbdd"
+  accent: "#fb9569"
+  accent-deep: "#a3481a"
+  sea: "#5b6fd0"
+  terracotta: "#c9512c"
+typography:
+  display:  { fontFamily: "Manrope, Segoe UI, system-ui, -apple-system, sans-serif", fontSize: "clamp(34px, 6.7vw, 96px)", fontWeight: 300, lineHeight: 0.92, letterSpacing: "-0.042em", textTransform: "lowercase" }
+  body:     { fontFamily: "Manrope, Segoe UI, system-ui, -apple-system, sans-serif", fontSize: "17px", fontWeight: 400, lineHeight: 1.5 }
+  label:    { fontFamily: "JetBrains Mono, ui-monospace, Cascadia Mono, Consolas, monospace", fontSize: "11px", fontWeight: 400, letterSpacing: "0.12em", textTransform: "uppercase" }
+rounded:
+  pill: "999px"
+  panel: "16px"
+  tile: "10px"
+---
+
+# Style: The Chrome World (the canonical look)
+
+This is the look Cloud Bongos itself runs on and the **first entry** of the style library ([task 1003323](https://cloudbongos.com/builders#/task/1003323)). It is the canonical one in a precise sense: its `pack.json` is byte-for-byte the `theme.ui` block of [`config/branding.neutral.json`](../../../../config/branding.neutral.json), the neutral pack every instance resolves over, and its recipes are **not restated here**. The world's derived tiers, faces, materials, motion grammar, components, Do's and Don'ts and accessibility floors are the repo-root [`DESIGN.md`](../../../../DESIGN.md), recorded from the built landing ([ADR 0196](../../../../docs/adr/<redacted>.md)). Read that file; this one only holds the thirteen so the catalogue's lockstep test has something to hold.
+
+## What this entry is for
+
+- **The reference every alternate is measured against.** An alternate is a different set of the same fifteen tokens laid through the same sheets; the chrome world is what those sheets were built for, so `STYLE=chrome-world` on the kit's stub is the same render as no `STYLE=` at all on a neutral instance.
+- **The specimen.** [`mock.html`](mock.html) beside this file is the world's specimen sheet (the hairline bar, the lowercase display voice, the door pill, the lifecycle rail, three ledger rows), served through the stub with the pack spliced in:
+
+```
+SURFACE=modules/ui-design/styles/chrome-world STYLE=chrome-world node modules/ui-design/kit/serve.js
+# http://127.0.0.1:3412/mock   (?mode=light · ?state=signed-in)
+```
+
+## Do's and Don'ts
+
+The root `DESIGN.md`'s, restated here only so the kit reads the look's bans from this dir (`check-mock.js --pack chrome-world`); the root file is the authority.
+
+### Don't
+
+- **Don't** use an em dash or en dash in visible copy, an emoji, gradient text, a coloured text glow, or a box shadow under content.
+- **Don't** declare a `:root` in a page, pin the accent in a dark block, or spend the accent on anything that is not pressable or live.
+
+## Adopting it
+
+An instance that starts from the neutral pack already has this look; there is nothing to copy. An instance that adopted an alternate and wants back: copy this `pack.json`'s `theme` into its `config/branding.json` (or delete the `theme.ui` override so the neutral values resolve). No page changes: the sheets read the contract and nothing else.