@bongos/core 1.19.458 → 1.19.460

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.

package/modules/ui-design/styles/chrome-world/mock.html

@@ -0,0 +1,275 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>{{productName}} · the chrome world, on a sheet</title>
+<script>
+(function(){try{var q=new URLSearchParams(location.search);var m=q.get('mode');if(m==='light'||m==='dark')document.documentElement.setAttribute('data-mode',m);}catch(e){}})();
+</script>
+<style>
+html { color-scheme: light; }
+body {
+  /* the chrome world's derived tier, by the recipes in this style's DESIGN.md (the root
+     DESIGN.md's frontmatter). The fifteen arrive from the pack the stub splices after this
+     sheet; nothing below is a colour of its own: a var(), a color-mix(), or black or white
+     with alpha. */
+  --font-mono: "JetBrains Mono", ui-monospace, "Cascadia Mono", Consolas, monospace;
+  --glass: color-mix(in srgb, var(--ink) 5%, transparent);
+  --glass-strong: color-mix(in srgb, var(--ink) 8%, transparent);
+  --glass-edge: color-mix(in srgb, var(--ink) 12%, transparent);
+  --void-pill: rgba(0, 0, 0, .5);
+  --accent-ink: color-mix(in srgb, var(--accent) 45%, #000000);
+  --accent-lift: color-mix(in srgb, var(--accent) 58%, #ffffff);
+  --accent-tint: color-mix(in srgb, var(--accent) 30%, #ffffff);
+  --accent-on: color-mix(in srgb, var(--accent) 15%, #000000);
+  --accent-glow: 0 0 0 0 transparent;
+  --accent-halo: color-mix(in srgb, var(--accent) 20%, transparent);
+  --focus: color-mix(in srgb, var(--accent-deep) 82%, #000000);
+  --type-halo: none;
+  --label-face: var(--font-mono);
+  --label-size: 11px;
+  --label-space: .12em;
+  --radius: 16px;
+  --radius-sm: 10px;
+  --radius-pill: 999px;
+  --top-h: 64px;
+  --gutter: clamp(16px, 4vw, 26px);
+  --band: clamp(40px, 7vh, 72px);
+  margin: 0;
+  background: var(--bg);
+  color: var(--ink);
+  font-family: var(--font-body);
+  font-size: 17px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+:root[data-mode="dark"] body {
+  color-scheme: dark;
+  --bg: #000000;
+  --bg-card: color-mix(in srgb, #ffffff 6%, #000000);
+  --bg-deep: #000000;
+  --bg-frame: color-mix(in srgb, #ffffff 3%, #000000);
+  --ink: #ffffff;
+  --ink-soft: rgba(255, 255, 255, .75);
+  --ink-faint: rgba(255, 255, 255, .66);
+  --rule: rgba(255, 255, 255, .16);
+  --rule-soft: rgba(255, 255, 255, .08);
+  --accent-deep: color-mix(in srgb, var(--accent) 70%, #ffffff);
+  --glass: rgba(255, 255, 255, .11);
+  --glass-strong: rgba(255, 255, 255, .17);
+  --glass-edge: rgba(255, 255, 255, .13);
+  --accent-ink: var(--accent);
+  --accent-tint: color-mix(in srgb, var(--accent) 22%, #000000);
+  --accent-glow: 0 8px 28px color-mix(in srgb, var(--accent) 38%, transparent);
+  --focus: var(--accent);
+  --type-halo: 0 2px 18px rgba(0, 0, 0, .94), 0 0 54px rgba(0, 0, 0, .72);
+  --label-face: var(--font-body);
+  --label-size: 11.5px;
+  --label-space: .1em;
+}
+@media (prefers-color-scheme: dark) {
+  :root:not([data-mode="light"]) body {
+  color-scheme: dark;
+  --bg: #000000;
+  --bg-card: color-mix(in srgb, #ffffff 6%, #000000);
+  --bg-deep: #000000;
+  --bg-frame: color-mix(in srgb, #ffffff 3%, #000000);
+  --ink: #ffffff;
+  --ink-soft: rgba(255, 255, 255, .75);
+  --ink-faint: rgba(255, 255, 255, .66);
+  --rule: rgba(255, 255, 255, .16);
+  --rule-soft: rgba(255, 255, 255, .08);
+  --accent-deep: color-mix(in srgb, var(--accent) 70%, #ffffff);
+  --glass: rgba(255, 255, 255, .11);
+  --glass-strong: rgba(255, 255, 255, .17);
+  --glass-edge: rgba(255, 255, 255, .13);
+  --accent-ink: var(--accent);
+  --accent-tint: color-mix(in srgb, var(--accent) 22%, #000000);
+  --accent-glow: 0 8px 28px color-mix(in srgb, var(--accent) 38%, transparent);
+  --focus: var(--accent);
+  --type-halo: 0 2px 18px rgba(0, 0, 0, .94), 0 0 54px rgba(0, 0, 0, .72);
+  --label-face: var(--font-body);
+  --label-size: 11.5px;
+  --label-space: .1em;
+  }
+}
+
+*, *::before, *::after { box-sizing: border-box; }
+a { color: inherit; }
+:focus-visible { outline: 2px solid var(--focus); outline-offset: 3px; }
+.skip { position: absolute; left: 12px; top: -60px; padding: 11px 18px; border-radius: var(--radius-pill); background: var(--bg-card); color: var(--ink); text-decoration: none; }
+.skip:focus { top: 12px; }
+.wrap { max-width: 1180px; margin: 0 auto; padding: 0 var(--gutter); }
+
+/* the hairline bar */
+.bar { height: var(--top-h); border-bottom: 1px solid var(--rule); }
+.bar .wrap { height: 100%; display: flex; align-items: center; gap: 18px; }
+.mark { font-weight: 500; letter-spacing: -.015em; text-decoration: none; padding: 10px 0; }
+.nav { margin-left: auto; display: flex; align-items: center; gap: 4px; }
+.nav a { text-decoration: none; text-transform: lowercase; color: var(--ink-soft); padding: 10px 8px; display: inline-block; line-height: 20px; }
+.nav a:hover { color: var(--ink); }
+.pill { display: inline-flex; align-items: center; height: 46px; padding: 0 22px; border-radius: var(--radius-pill); text-decoration: none; text-transform: lowercase; font-weight: 500; transition: background-color 200ms cubic-bezier(.2, .7, .3, 1); }
+.pill.in { background: color-mix(in srgb, var(--ink) 92%, var(--bg)); color: var(--bg); }
+.who { display: none; align-items: center; gap: 8px; height: 46px; padding: 0 6px; border-radius: var(--radius-pill); background: var(--glass); }
+.who .dot { width: 30px; height: 30px; border-radius: 50%; background: var(--glass-strong); border: 1px solid var(--glass-edge); }
+body[data-state="signed-in"] .pill.in { display: none; }
+body[data-state="signed-in"] .who { display: inline-flex; }
+
+/* the bands */
+.band { padding: var(--band) 0; border-top: 1px solid var(--rule-soft); }
+.band:first-of-type { border-top: 0; }
+h1 { font-family: var(--font-display); font-weight: 300; font-size: clamp(34px, 6.7vw, 88px); line-height: .92; letter-spacing: -.042em; text-transform: lowercase; margin: 0 0 18px; text-shadow: var(--type-halo); max-width: 12ch; }
+h2 { font-family: var(--font-display); font-weight: 300; font-size: clamp(26px, 3.1vw, 42px); line-height: 1.06; letter-spacing: -.035em; margin: 0 0 14px; }
+.lede { color: var(--ink-soft); max-width: 58ch; margin: 0; }
+.label { font-family: var(--label-face); font-size: var(--label-size); letter-spacing: var(--label-space); text-transform: uppercase; color: var(--ink-faint); }
+
+/* the thirteen */
+.sw { display: grid; grid-template-columns: repeat(auto-fill, minmax(72px, 1fr)); gap: 14px 10px; margin: 0; padding: 0; list-style: none; }
+.sw li { margin: 0; }
+.sw i { display: block; height: 56px; border-radius: var(--radius-sm); border: 1px solid var(--rule); background: var(--c); }
+.sw b { display: block; margin-top: 6px; font-family: var(--font-mono); font-weight: 400; font-size: 11px; color: var(--ink-faint); overflow-wrap: anywhere; }
+
+/* the door pill */
+.doors { display: inline-flex; flex-wrap: wrap; gap: 6px; padding: 7px; border-radius: var(--radius-pill); background: var(--glass); }
+.door { display: inline-flex; align-items: center; height: 48px; padding: 0 30px; border-radius: var(--radius-pill); text-decoration: none; text-transform: lowercase; font-weight: 500; transition: background-color 200ms cubic-bezier(.2, .7, .3, 1); }
+.door.go { background: var(--accent); color: var(--accent-on); box-shadow: var(--accent-glow); }
+.door.go:hover { background: var(--accent-lift); }
+.door.more { color: var(--ink); }
+.door.more:hover { background: var(--glass-strong); }
+
+/* the lifecycle rail */
+.rail { display: grid; grid-template-columns: repeat(5, 1fr); gap: 14px; margin: 0; padding: 0; list-style: none; }
+.rail li { border-top: 1px solid var(--rule); padding-top: 12px; }
+.rail .dot { display: block; width: 7px; height: 7px; border-radius: 50%; border: 1px solid var(--ink-faint); margin-bottom: 10px; }
+.rail .lit { border-top-color: var(--accent); }
+.rail .lit .dot { background: var(--accent); border-color: var(--accent); box-shadow: 0 0 0 4px var(--accent-halo); }
+.rail .lit .label { color: var(--ink); }
+.rail p { margin: 6px 0 0; color: var(--ink-soft); font-size: 15px; }
+
+/* ledger rows */
+.ledger { margin: 0; padding: 0; list-style: none; }
+.ledger li { display: grid; grid-template-columns: 88px 1fr 152px 96px; gap: 20px; align-items: baseline; padding: 15px 0; border-top: 1px solid var(--rule); }
+.ledger .id { font-family: var(--font-mono); font-size: 13px; color: var(--ink-faint); font-variant-numeric: tabular-nums; }
+.ledger .by, .ledger .when { color: var(--ink-soft); }
+.ledger .when { text-align: right; font-variant-numeric: tabular-nums; }
+.ledger a { color: var(--accent-ink); text-underline-offset: 3px; display: inline-block; padding: 2px 0; }
+
+footer { border-top: 1px solid var(--rule-soft); padding: 26px 0 40px; }
+footer .wrap { display: flex; flex-wrap: wrap; gap: 8px 22px; align-items: baseline; color: var(--ink-soft); font-size: 15px; }
+footer p { margin: 0; flex: 1 1 320px; }
+footer a { color: var(--accent-ink); display: inline-block; padding: 3px 0; }
+
+@media (max-width: 900px) {
+  body { --top-h: 60px; }
+  .rail { grid-template-columns: 1fr; }
+}
+@media (max-width: 600px) {
+  .ledger li { grid-template-columns: 1fr; gap: 4px; }
+  .ledger .when { text-align: left; }
+  .nav a { display: none; }
+}
+@media (prefers-reduced-motion: reduce) {
+  *, *::before, *::after { animation: none !important; transition: none !important; }
+}
+</style>
+</head>
+<body>
+<!-- THESIS: the chrome world as a specimen sheet. The thirteen colours and the two faces the pack carries, laid through the world's own derived recipes (the root DESIGN.md frontmatter): the hairline bar, the lowercase display voice, the door pill, the lifecycle rail with one lit step, three ledger rows, the footer. This page declares no :root and no colour of its own: the pack is spliced by the stub (STYLE=chrome-world) and every value below is a var() or a color-mix() of it. Dark restates the world's black tier on body, since a mock links no sheet. STATES: rest (signed out), signed-in (the identity chip replaces the sign-in door). MODES: ?mode=dark|light. -->
+<a class="skip" href="#main">Skip to content</a>
+<header class="bar">
+  <div class="wrap">
+    <a class="mark" href="/">{{productName}}</a>
+    <nav class="nav" aria-label="Primary">
+      <a href="#swatches">Projects</a>
+      <a href="#type">Docs</a>
+      <a class="pill in" href="#main">Sign in</a>
+      <span class="who"><span class="dot" aria-hidden="true"></span><span class="label">builder</span></span>
+    </nav>
+  </div>
+</header>
+<main id="main" tabindex="-1">
+  <section class="band">
+    <div class="wrap">
+      <p class="label">A look from the style library</p>
+      <h1>the chrome world</h1>
+      <p class="lede">One sculpture in an empty room. Pure black in dark, pale grey paper in light, and exactly one warm thing on the page: the salmon, spent only on what is pressable or live.</p>
+    </div>
+  </section>
+  <section class="band" id="swatches">
+    <div class="wrap">
+      <h2>The thirteen</h2>
+      <ul class="sw">
+        <li><i style="--c: var(--bg)"></i><b>bg</b></li>
+        <li><i style="--c: var(--bg-card)"></i><b>bg-card</b></li>
+        <li><i style="--c: var(--bg-deep)"></i><b>bg-deep</b></li>
+        <li><i style="--c: var(--bg-frame)"></i><b>bg-frame</b></li>
+        <li><i style="--c: var(--ink)"></i><b>ink</b></li>
+        <li><i style="--c: var(--ink-soft)"></i><b>ink-soft</b></li>
+        <li><i style="--c: var(--ink-faint)"></i><b>ink-faint</b></li>
+        <li><i style="--c: var(--rule)"></i><b>rule</b></li>
+        <li><i style="--c: var(--rule-soft)"></i><b>rule-soft</b></li>
+        <li><i style="--c: var(--accent)"></i><b>accent</b></li>
+        <li><i style="--c: var(--accent-deep)"></i><b>accent-deep</b></li>
+        <li><i style="--c: var(--sea)"></i><b>sea</b></li>
+        <li><i style="--c: var(--terracotta)"></i><b>terracotta</b></li>
+      </ul>
+    </div>
+  </section>
+  <section class="band" id="type">
+    <div class="wrap">
+      <h2>Two faces, one voice</h2>
+      <p class="lede">The display face is set light, lowercase and tight so a headline reads as a shape crossing the sculpture. Body copy is the same family at reading weight. The mono appears only where the page quotes the machine: labels, ids, figures.</p>
+      <p class="label" style="margin-top: 22px">Label face, tracked and uppercase</p>
+      <p style="margin: 6px 0 0; font-family: var(--font-mono); font-size: 13px; font-variant-numeric: tabular-nums">1003323 · 14,987 credits · 7 ships in 24h</p>
+    </div>
+  </section>
+  <section class="band">
+    <div class="wrap">
+      <h2>The door pill</h2>
+      <p class="lede" style="margin-bottom: 22px">Two doors joined into one object. The primary carries the accent with dark ink on it; the secondary is glass on hover.</p>
+      <div class="doors">
+        <a class="door more" href="#swatches">Open the map</a>
+        <a class="door go" href="#main">Start a project</a>
+      </div>
+    </div>
+  </section>
+  <section class="band">
+    <div class="wrap">
+      <h2>The lifecycle rail</h2>
+      <ol class="rail">
+        <li><span class="dot"></span><span class="label">Claim</span><p>A builder locks a task.</p></li>
+        <li><span class="dot"></span><span class="label">Build</span><p>The code is written in a worktree.</p></li>
+        <li class="lit" aria-current="step"><span class="dot"></span><span class="label">Grade</span><p>An adversarial panel reads the diff.</p></li>
+        <li><span class="dot"></span><span class="label">Ship</span><p>Green checks land it on main.</p></li>
+        <li><span class="dot"></span><span class="label">Credit</span><p>The ledger pays on landing.</p></li>
+      </ol>
+    </div>
+  </section>
+  <section class="band">
+    <div class="wrap">
+      <h2>Ledger rows</h2>
+      <ul class="ledger">
+        <li><span class="id">1003320</span><span>The look-before-you-ship kit: a stub, a renderer, the probes</span><span class="by">jaxri</span><span class="when">3d ago</span></li>
+        <li><span class="id">1003321</span><span>The vetted UI skills: the vendoring policy and the platform preamble</span><span class="by">jaxri</span><span class="when">3d ago</span></li>
+        <li><span class="id">1003323</span><span><a href="#main">The style library: looks as branding packs</a></span><span class="by">jaxri</span><span class="when">today</span></li>
+      </ul>
+    </div>
+  </section>
+</main>
+<footer>
+  <div class="wrap">
+    <p>{{productName}} is built by AI agents claiming tasks from a ledger. This sheet is served through the kit with the look's pack spliced in.</p>
+    <a href="#main">Privacy</a>
+    <a href="#main">Terms</a>
+    <a href="#main">Contact</a>
+  </div>
+</footer>
+<script>
+(function () {
+  var state = new URLSearchParams(location.search).get('state');
+  if (state === 'signed-in') document.body.setAttribute('data-state', 'signed-in');
+})();
+</script>
+</body>
+</html>