@bongos/core 1.24.54 → 1.24.56

package/modules/ui-design/scripts/gen-design-reference.js

@@ -0,0 +1,354 @@
+#!/usr/bin/env node
+'use strict';
+// modules/ui-design/scripts/gen-design-reference.js — build the public design-system
+// reference page, modules/ui-design/public/brand.html, served at /brand on the hub
+// (task 1005083, goal 1000138; DESIGN.md "Naming" → the reference is public).
+//
+// WHY GENERATED. A hand-written reference drifts from the sheets the day after it is
+// written. Nothing on the page is typed by hand except its own layout and the short
+// headings: every value is read from the file that owns it, every component is drawn by
+// the shared rule that every hall page uses.
+//
+//   the thirteen colours + the two faces ← config/branding.neutral.json theme.ui
+//   their dark values, the derived tier,  ← modules/hall-ui/public/style.css (the hall's
+//     the status vocabulary, the mono face   :root and its html[data-theme="dark"] twin)
+//   type, spacing, line, corners, shadow, ← modules/ui-design/public/tokens.css (--ds-*,
+//     motion, layers                         and its dark block for the shadow)
+//   buttons, field, pill, dialog, toast…  ← drawn live by modules/hall-ui/public/style.css
+//                                           + controls.css; each class is checked to exist
+//   task statuses, toast durations        ← modules/hall-ui/public/dom-utils.js (the one map)
+//   the logo files                        ← modules/ui-design/public/brand/ + the file list
+//                                           in scripts/bongos/gen-brand.js
+//   the naming rule                       ← DESIGN.md "## Naming"
+//
+//   node modules/ui-design/scripts/gen-design-reference.js           write the page
+//   node modules/ui-design/scripts/gen-design-reference.js --check   exit 1 if it is stale
+//
+// Guarded by tests/design_reference.mjs. The kit renders it with
+// modules/ui-design/public/brand.states.json.
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const ROOT = path.resolve(__dirname, '..', '..', '..');
+const P = (...a) => path.join(ROOT, ...a);
+const SRC = Object.freeze({
+  pack: P('config', 'branding.neutral.json'),
+  sheet: P('modules', 'ui-design', 'public', 'tokens.css'),
+  hall: P('modules', 'hall-ui', 'public', 'style.css'),
+  controls: P('modules', 'hall-ui', 'public', 'controls.css'),
+  domUtils: P('modules', 'hall-ui', 'public', 'dom-utils.js'),
+  brandDir: P('modules', 'ui-design', 'public', 'brand'),
+  genBrand: P('scripts', 'bongos', 'gen-brand.js'),
+  design: P('DESIGN.md'),
+});
+const OUT = P('modules', 'ui-design', 'public', 'brand.html');
+const BRAND_URL = '/modules/ui-design/public/brand/';
+
+// the hall's one escaper (dom-utils.js also loads under require(); fitness: one escaper per side)
+const esc = (s) => require(SRC.domUtils).escapeHtml(String(s));
+const kebab = (k) => '--' + k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+const stripComments = (css) => css.replace(/\/\*[\s\S]*?\*\//g, '');
+
+// The declarations of the first block whose selector matches `selectorRe`, in source
+// order, as [[prop, value], …]. Values are whitespace-collapsed.
+function blockVars(css, selectorRe, what) {
+  const m = stripComments(css).match(new RegExp(selectorRe.source + '\\s*\\{([^}]*)\\}'));
+  if (!m) throw new Error(`${what}: no block matching ${selectorRe}`);
+  const out = [];
+  for (const decl of m[1].split(';')) {
+    const d = decl.match(/^\s*(--[a-z0-9-]+)\s*:\s*([\s\S]+?)\s*$/i);
+    if (d) out.push([d[1], d[2].replace(/\s+/g, ' ')]);
+  }
+  return out;
+}
+
+// Turn a DESIGN.md line's inline markdown (**bold**, `code`) into escaped HTML.
+function inline(md) {
+  return esc(md).replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>').replace(/`([^`]+)`/g, '<code>$1</code>');
+}
+
+// DESIGN.md "## Naming", up to its first sub-heading: the lead paragraph and the bullets.
+function readNaming(design) {
+  const m = design.match(/\n## Naming\n([\s\S]*?)(?=\n### |\n## |$)/);
+  if (!m) throw new Error('DESIGN.md: no "## Naming" chapter');
+  const lines = m[1].split('\n').map((l) => l.trim()).filter(Boolean);
+  const lead = lines.filter((l) => !l.startsWith('- ')).map(inline);
+  const rules = lines.filter((l) => l.startsWith('- ')).map((l) => inline(l.slice(2)));
+  if (!rules.length) throw new Error('DESIGN.md: the Naming chapter has no rules');
+  return { lead, rules };
+}
+
+// The logo files and what each is for, from gen-brand.js's own header (the one list
+// of what it writes), kept only where the file is actually on disk.
+function readBrandFiles(genBrand, dir) {
+  const files = [];
+  for (const line of genBrand.split('\n')) {
+    const m = line.match(/^\/\/\s{2,}([a-z-]+\.(?:svg|png))\s{2,}(.+?)\s*$/);
+    if (!m || !fs.existsSync(path.join(dir, m[1]))) continue;
+    // the first column of the description only; drop a build note "(--png …)" and an
+    // aside the header continues on the next line (an unclosed "(")
+    const what = m[2].split(/\s{2,}/)[0].replace(/\s*\(--png[^)]*\)/, '').replace(/\s*\([^)]*$/, '')
+      .replace(/\s*\(task \d+\)/, '').replace(/[:;,]\s*$/, '');
+    files.push({ file: m[1], what });
+  }
+  if (!files.length) throw new Error('gen-brand.js: no file list found in its header');
+  return [{ file: 'mark.svg', what: 'the one source: drawn inline by reference, coloured by the page' }, ...files];
+}
+
+// The classes the components section draws with: each must exist in the hall's sheets,
+// so a renamed rule fails the generator instead of shipping an unstyled specimen.
+const NEEDS = ['.btn', '.btn--ghost', '.btn--danger', '.btn--sm', '.btn--text', '.status-pill', '.status-pill--sm',
+  '.scroll', '.scroll--quiet', '.scroll__h', '.scroll__lede', '.empty-state', '.empty-state__action', '.hall-loading',
+  '.hall-loading--inline', '.toast', '.kit-tabs', '.setup__tab', '.count-pill', '.viewtoggle', '.viewtoggle__btn',
+  '.hall-dialog', '.hall-dialog__head', '.hall-dialog__title', '.hall-dialog__body', '.hall-dialog__actions'];
+
+// Which hall :root props count as the derived COLOUR tier: anything whose value is a
+// colour expression (not a length, a face, a gradient veil or a plate).
+const COLOURISH = /^(#|rgba?\(|color-mix\()/;
+const STATUS = ['--ok', '--ok-weak', '--warn', '--warn-weak', '--danger', '--danger-weak', '--info', '--info-weak'];
+
+function read() {
+  return {
+    pack: JSON.parse(fs.readFileSync(SRC.pack, 'utf8')),
+    sheet: fs.readFileSync(SRC.sheet, 'utf8'),
+    hall: fs.readFileSync(SRC.hall, 'utf8'),
+    controls: fs.readFileSync(SRC.controls, 'utf8'),
+    design: fs.readFileSync(SRC.design, 'utf8'),
+    genBrand: fs.readFileSync(SRC.genBrand, 'utf8'),
+    otb: require(SRC.domUtils),
+  };
+}
+
+// ---- the page's parts ---------------------------------------------------------------
+
+const row = (cells, cls = '') => `<li class="ref-row${cls ? ' ' + cls : ''}">${cells.join('')}</li>`;
+const name = (prop) => `<code class="ref-name">${esc(prop)}</code>`;
+const val = (label, v) => `<span class="ref-val"><span class="ref-val__k">${label}</span> <code>${esc(v)}</code></span>`;
+const swatch = (prop) => `<span class="ref-swatch" style="background: var(${prop})" aria-hidden="true"></span>`;
+const list = (rows, cls = '') => `<ul class="ref-list${cls ? ' ' + cls : ''}" role="list">${rows.join('')}</ul>`;
+function section(id, title, lede, body) {
+  return `<section class="scroll ref-sec" id="${id}" aria-labelledby="${id}-h">
+    <h2 class="scroll__h" id="${id}-h">${esc(title)}</h2>
+    ${lede ? `<p class="scroll__lede">${lede}</p>` : ''}
+    ${body}
+  </section>`;
+}
+
+function colourRows(entries) {
+  return entries.map(({ prop, light, dark }) => row([
+    swatch(prop), name(prop), val('light', light), val('dark', dark),
+  ], 'ref-row--colour'));
+}
+
+function build(src = read()) {
+  const ui = src.pack.theme && src.pack.theme.ui;
+  if (!ui || !ui.colors || !ui.fonts) throw new Error('branding.neutral.json: theme.ui has no colours or fonts');
+  const hallRoot = new Map(blockVars(src.hall, /(?:^|\n|\})\s*:root/, 'style.css'));
+  const hallDark = new Map(blockVars(src.hall, /html\[data-theme="dark"\]/, 'style.css'));
+  const ds = blockVars(src.sheet, /(?:^|\n|\})\s*:root/, 'tokens.css');
+  const dsDark = new Map(blockVars(src.sheet, /html\[data-theme="dark"\], :root\[data-mode="dark"\]/, 'tokens.css'));
+  const allCss = src.hall + '\n' + src.controls;
+  for (const cls of NEEDS) {
+    if (!new RegExp(cls.replace(/[.[\]-]/g, '\\$&') + '(?![a-z0-9_-])').test(allCss)) throw new Error(`the hall's sheets no longer define ${cls}`);
+  }
+  const product = (src.pack.identity && src.pack.identity.productName) || '';
+  const naming = readNaming(src.design);
+  const files = readBrandFiles(src.genBrand, SRC.brandDir);
+  const OTB = src.otb;
+
+  // 1. the pack's thirteen
+  const packKeys = Object.keys(ui.colors);
+  const pack = packKeys.map((k) => {
+    const prop = kebab(k);
+    if (!hallRoot.has(prop)) throw new Error(`style.css :root does not declare ${prop} (pack colour ${k})`);
+    return { prop, light: ui.colors[k], dark: hallDark.get(prop) || 'same as light' };
+  });
+  const packProps = new Set(pack.map((c) => c.prop));
+  // 2. the status vocabulary
+  const status = STATUS.map((prop) => {
+    if (!hallRoot.has(prop)) throw new Error(`style.css :root does not declare ${prop}`);
+    return { prop, light: hallRoot.get(prop), dark: hallDark.get(prop) || hallRoot.get(prop) };
+  });
+  // 3. the rest of the derived colour tier
+  const derived = [...hallRoot].filter(([prop, v]) => !packProps.has(prop) && !STATUS.includes(prop) && COLOURISH.test(v))
+    .map(([prop, light]) => ({ prop, light, dark: hallDark.get(prop) || light }));
+
+  // the scales, grouped by their prefix in tokens.css
+  const group = (re) => ds.filter(([p]) => re.test(p));
+  const text = group(/^--ds-text-/);
+  const space = group(/^--ds-space-/);
+  const line = group(/^--ds-line$/);
+  const radius = group(/^--ds-radius-/);
+  const shadow = group(/^--ds-shadow-/);
+  const motion = group(/^--ds-(dur|stagger|ease)/);
+  const layers = group(/^--ds-z-/);
+  const covered = new Set([...text, ...space, ...line, ...radius, ...shadow, ...motion, ...layers].map(([p]) => p));
+  const loose = ds.filter(([p]) => !covered.has(p));
+  if (loose.length) throw new Error(`tokens.css declares ${loose.map(([p]) => p).join(', ')} in no group the reference shows: add its group here`);
+
+  const faces = [
+    { prop: '--font-display', v: ui.fonts.display, role: 'display' },
+    { prop: '--font-body', v: ui.fonts.body, role: 'body' },
+    { prop: '--font-mono', v: hallRoot.get('--font-mono'), role: 'mono' },
+  ];
+
+  const sample = 'Claim the next task';
+  const parts = [];
+
+  parts.push(section('ref-logo', 'Logo and name', 'The mark is one file every page draws from. The ring and the planet take the ink; the moon takes the accent.', `
+    <div class="ref-lockup">
+      <svg class="ref-lockup__mark" viewBox="0 0 200 200" aria-hidden="true"><use href="${BRAND_URL}mark.svg#mark"/></svg>
+      <span class="ref-lockup__name">${esc(product.toLowerCase())}</span>
+    </div>
+    <div class="ref-naming">
+      ${naming.lead.map((p) => `<p>${p}</p>`).join('\n      ')}
+      <ul>
+        ${naming.rules.map((r) => `<li>${r}</li>`).join('\n        ')}
+      </ul>
+    </div>
+    <h3 class="ref-sub">The files</h3>
+    ${list(files.map((f) => row([`<a class="ref-file" href="${BRAND_URL}${esc(f.file)}"><code>${esc(f.file)}</code></a>`, `<span class="ref-what">${esc(f.what)}</span>`], 'ref-row--file')))}`));
+
+  parts.push(section('ref-colour', 'Colour', 'The thirteen colours of the branding pack. An instance replaces them in its own pack; in dark mode only the neutrals flip, and the accent, sea and terracotta stay the pack’s.', `
+    ${list(colourRows(pack))}
+    <h3 class="ref-sub">The status vocabulary</h3>
+    <p class="ref-note">Fixed, not taken from the pack, and the one exception to the fifteen tokens: a status is always a word as well as a colour.</p>
+    ${list(colourRows(status))}
+    <h3 class="ref-sub">Derived colours</h3>
+    <p class="ref-note">Mixed from the thirteen, never typed as a new colour. Black and white with alpha appear only as a scrim, a shadow or glass.</p>
+    ${list(colourRows(derived))}`));
+
+  parts.push(section('ref-type', 'Type', 'Two faces from the pack and one mono face for what the machine says: task ids, labels, figures.', `
+    ${list(faces.map((f) => row([name(f.prop), `<span class="ref-face" style="font-family: var(${f.prop})">${esc(sample)}</span>`, val(f.role, f.v)], 'ref-row--face')))}
+    <h3 class="ref-sub">The type scale</h3>
+    ${list(text.map(([p, v]) => row([name(p), val('size', v), `<span class="ref-sample" style="font-size: var(${p})">${esc(sample)}</span>`], 'ref-row--type')))}`));
+
+  parts.push(section('ref-space', 'Spacing', 'The rhythm every gap and padding is taken from.', `
+    ${list(space.map(([p, v]) => row([name(p), val('size', v), `<span class="ref-bar" style="width: var(${p})" aria-hidden="true"></span>`], 'ref-row--space')))}
+    <h3 class="ref-sub">The hairline</h3>
+    ${list(line.map(([p, v]) => row([name(p), val('width', v), '<span class="ref-hair" aria-hidden="true"></span>'], 'ref-row--space')))}`));
+
+  parts.push(section('ref-shape', 'Corners and shadow', 'A control is a pill or square; a panel and a tile take their own corner. The one shadow is spent only on what floats.', `
+    ${list(radius.map(([p, v]) => row([`<span class="ref-corner" style="border-radius: var(${p})" aria-hidden="true"></span>`, name(p), val('radius', v)], 'ref-row--shape')))}
+    ${list(shadow.map(([p, v]) => row([`<span class="ref-float" style="box-shadow: var(${p})" aria-hidden="true"></span>`, name(p), val('light', v), val('dark', dsDark.get(p) || v)], 'ref-row--shape')))}`));
+
+  parts.push(section('ref-motion', 'Motion and layers', 'State changes take the one easing; an entrance takes the slow ease-out. With reduced motion asked for, every duration is zero.', `
+    ${list(motion.map(([p, v]) => row([name(p), val('value', v)], 'ref-row--plain')))}
+    <h3 class="ref-sub">Stacking layers, low to high</h3>
+    ${list(layers.map(([p, v]) => row([name(p), val('z', v)], 'ref-row--plain')))}`));
+
+  const pills = OTB.STATUS_TONES.map((t) => OTB.statusPill(t, { tone: t })).join(' ');
+  const pillsSm = OTB.STATUS_TONES.map((t) => OTB.statusPill(t, { tone: t, small: true })).join(' ');
+  const taskPills = Object.keys(OTB.STATUS_TONE).map((s) => OTB.statusPill(s)).join(' ');
+  const toasts = [['info', 'Copied the prompt.'], ['ok', 'Task claimed.'], ['warn', 'The board is paused while the owner reviews it.'], ['error', 'Could not reach the server: try again in a moment.']]
+    .map(([k, msg]) => `<p class="toast ref-toast" data-visible="1" data-kind="${k}">${esc(OTB.plainMessage(msg))} <span class="ref-toast__k">(${k}, ${OTB.TOAST_MS[k] / 1000}s)</span></p>`).join('\n      ');
+
+  parts.push(section('ref-components', 'Components', 'Drawn by the same shared rules every page of the hall loads, in each of their states.', `
+    <h3 class="ref-sub">Buttons</h3>
+    <div class="ref-specimen">
+      <button type="button" class="btn">claim it</button>
+      <button type="button" class="btn btn--ghost">later</button>
+      <button type="button" class="btn btn--danger">release</button>
+      <button type="button" class="btn" disabled>claimed</button>
+    </div>
+    <div class="ref-specimen">
+      <button type="button" class="btn btn--sm">claim</button>
+      <button type="button" class="btn btn--ghost btn--sm">release</button>
+      <button type="button" class="btn btn--text">read the brief</button>
+    </div>
+    <h3 class="ref-sub">Fields</h3>
+    <div class="ref-fields">
+      <label class="ref-field">A field <input type="text" value="A sentence someone typed"></label>
+      <label class="ref-field">A choice <select><option>ready</option><option>active</option></select></label>
+      <label class="ref-field">A longer answer <textarea rows="2">Two lines of what changed.</textarea></label>
+      <label class="ref-field">Not open yet <input type="text" value="Read only" disabled></label>
+    </div>
+    <h3 class="ref-sub">Status pills</h3>
+    <div class="ref-specimen" data-ref="tones">${pills}</div>
+    <div class="ref-specimen" data-ref="tones-sm">${pillsSm}</div>
+    <p class="ref-note">A task’s status, from the one map:</p>
+    <div class="ref-specimen" data-ref="task-statuses">${taskPills}</div>
+    <h3 class="ref-sub">Tabs and the view toggle</h3>
+    <div class="kit-tabs" role="tablist" aria-label="Example tabs">
+      <button type="button" class="setup__tab is-active" role="tab" aria-selected="true">ready <span class="count-pill">4</span></button>
+      <button type="button" class="setup__tab" role="tab" aria-selected="false">active</button>
+      <button type="button" class="setup__tab" role="tab" aria-selected="false">done</button>
+    </div>
+    <div class="viewtoggle" role="group" aria-label="View">
+      <button type="button" class="viewtoggle__btn" aria-pressed="true">rows</button>
+      <button type="button" class="viewtoggle__btn" aria-pressed="false">cards</button>
+    </div>
+    <h3 class="ref-sub">Panel, tile and the empty state</h3>
+    <div class="scroll scroll--quiet ref-tile"><p class="ref-note">This section is a panel; a quiet tile inside it recedes by tone.</p></div>
+    <div class="empty-state"><p>Nothing is waiting for you.</p><a class="empty-state__action" href="#ref-components">See the whole queue</a></div>
+    <h3 class="ref-sub">Loading</h3>
+    <p class="hall-loading" role="status">Reading the queue…</p>
+    <p class="ref-specimen"><span class="hall-loading hall-loading--inline" role="status">Saving…</span></p>
+    <h3 class="ref-sub">Toasts</h3>
+    <div class="ref-toasts">
+      ${toasts}
+    </div>
+    <h3 class="ref-sub">Dialog</h3>
+    <div class="ref-dialog">
+      <div class="hall-dialog" role="dialog" aria-modal="false" aria-labelledby="ref-dialog-t">
+        <div class="hall-dialog__head"><h4 class="hall-dialog__title" id="ref-dialog-t">Release this task?</h4></div>
+        <div class="hall-dialog__body"><p>It returns to the queue and no credits are earned.</p></div>
+        <div class="hall-dialog__actions"><button type="button" class="btn btn--ghost">cancel</button><button type="button" class="btn btn--danger">release</button></div>
+      </div>
+    </div>`));
+
+  const sources = Object.values(SRC).map((f) => `<li><code>${esc(path.relative(ROOT, f).split(path.sep).join('/'))}</code></li>`).join('\n        ');
+
+  return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>{{productName}} — Design system</title>
+  <meta name="description" content="The colours, type, spacing, corners, motion and shared components every {{productName}} page is drawn from.">
+  <!-- GENERATED by node modules/ui-design/scripts/gen-design-reference.js (task 1005083); do not edit by hand.
+       Every value is read from its source file; every component is drawn by the hall's shared rules.
+       kit-ignore: tell: tiny type (the type scale shows its smallest step at its own size) -->
+  <link rel="stylesheet" href="/modules/hall-ui/public/style.css">
+  <link rel="stylesheet" href="/modules/ui-design/public/brand.css">
+</head>
+<body data-page="brand">
+<header class="ref-head">
+  <a class="ref-head__brand" href="/"><svg class="ref-head__mark" viewBox="0 0 200 200" aria-hidden="true"><use href="${BRAND_URL}mark.svg#mark"/></svg><span>${esc(product.toLowerCase())}</span></a>
+</header>
+<main class="ref-main">
+  <h1 class="ref-title">Design system</h1>
+  <p class="ref-lede">The colours, type, spacing, corners, motion and shared components every {{productName}} page is drawn from. This page is generated from those same files, so it cannot drift from them. It follows your device’s light or dark setting; each value is shown for both.</p>
+  <nav class="ref-toc" aria-label="On this page">
+    <a href="#ref-logo">Logo</a><a href="#ref-colour">Colour</a><a href="#ref-type">Type</a><a href="#ref-space">Spacing</a><a href="#ref-shape">Corners</a><a href="#ref-motion">Motion</a><a href="#ref-components">Components</a>
+  </nav>
+  ${parts.join('\n  ')}
+  <section class="ref-sources" aria-labelledby="ref-sources-h">
+    <h2 class="ref-sources__h" id="ref-sources-h">Generated from</h2>
+    <ul>
+        ${sources}
+    </ul>
+  </section>
+</main>
+</body>
+</html>
+`;
+}
+
+module.exports = { build, blockVars };
+
+if (require.main === module) {
+  const next = build();
+  const current = fs.existsSync(OUT) ? fs.readFileSync(OUT, 'utf8') : '';
+  if (process.argv.includes('--check')) {
+    if (current === next) process.stdout.write('brand.html: current\n');
+    else {
+      process.stderr.write('modules/ui-design/public/brand.html is STALE: run node modules/ui-design/scripts/gen-design-reference.js\n');
+      process.exitCode = 1;
+    }
+  } else {
+    if (current !== next) fs.writeFileSync(OUT, next);
+    process.stdout.write((current === next ? 'brand.html: unchanged' : 'brand.html: written') + '\n');
+  }
+}

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.54",
+  "version": "1.24.56",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.24.54",
+      "version": "1.24.56",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.24.54",
+  "version": "1.24.56",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11295,5 +11295,17 @@
       "id": "1005086",
       "text": "A task's status now looks the same on every hall page: one pill with six colours, chosen in one place. Error pop-up messages stay longer and never show a server's address, and a new specimen page shows every shared piece in ev"
     }
+  ],
+  "1.24.55": [
+    {
+      "id": "1005083",
+      "text": "There is now a public design-system page at /brand on cloudbongos.com showing every colour, size, corner and shared building block, with light and dark values. It is built automatically from the same files the site uses, so it"
+    }
+  ],
+  "1.24.56": [
+    {
+      "id": "1005087",
+      "text": "The Studio, the thinking sky, the tweak editor, the city, approvals, the atlas and the welcome screen now take their colours and fonts from the project's own branding, so a re-branded project sees them in its own colours; the"
+    }
   ]
 }

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.24.54'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.24.56'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/src/platform-server.js

@@ -165,6 +165,7 @@ function landingAssetCache(urlPath, v) {
   return null;
 }
 
+let _brandHtml; // the /brand reference, branded once (task 1005083); '' if the file is absent
 const _landingPages = new Map(); // memoized per file; '' if absent (instance ships no landing)
 function landingPage(file) {
   if (!_landingPages.has(file)) {
@@ -317,6 +318,23 @@ function buildPlatformApp() {
       res.type('html').send(html);
     });
   }
+  // THE DESIGN-SYSTEM REFERENCE (task 1005083; DESIGN.md "Naming": the reference is
+  // public). A generated page — modules/ui-design/scripts/gen-design-reference.js writes
+  // modules/ui-design/public/brand.html from the token sheets and the shared components —
+  // served signed-out at /brand, branding-stamped like the footer doors. It describes the
+  // platform's own world, so it is the hub's alone (platform-identity IS the hub flag, as
+  // for /account below) and needs ui-design on, the module that ships it.
+  app.get('/brand', (req, res, next) => {
+    if (!isApexHost(req) || !isModuleEnabled('platform-identity') || !isModuleEnabled('ui-design')) return next();
+    if (_brandHtml === undefined) {
+      try {
+        _brandHtml = injectBrandingGlobal(fs.readFileSync(path.join(__dirname, '..', 'modules', 'ui-design', 'public', 'brand.html'), 'utf8'));
+      } catch { _brandHtml = ''; }
+    }
+    if (!_brandHtml) return next();
+    res.set('Cache-Control', 'public, max-age=300');
+    res.type('html').send(_brandHtml);
+  });
   // THE RAISE PAGE (task 1004847, ADR 0384): the instance's investor page at
   // /raise, served by the raise module through its `raise.web` port — looked up
   // per request, because modules mount inside mountInternalSurfaces above. No

package/tests/design_reference.mjs

@@ -0,0 +1,175 @@
+// tests/design_reference.mjs — the public design-system reference (task 1005083, goal
+// 1000138): modules/ui-design/public/brand.html is GENERATED from the files that own
+// each value, and the hub serves it signed-out at /brand.
+//
+// Pins:
+//   1. the committed page is exactly what the generator writes (a hand edit, or a
+//      token change nobody regenerated, fails here; task 1005093 adds the ship gate);
+//   2. every --ds-* token, every pack colour with its light AND dark value, and the
+//      status vocabulary are on the page — read from the sheets, not a copy;
+//   3. a source change reaches the page, and a source losing what the page needs is
+//      an error rather than a silent gap;
+//   4. the page keeps the platform floors: no page :root, no colour literal in its
+//      layout sheet, a states file the kit can render in both modes;
+//   5. the route: 200 signed-out on the hub's apex, stamped; never on a child
+//      instance, the builders host or the status host.
+//
+// DB-free. Run:  node --test tests/design_reference.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import http from 'node:http';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const gen = require(path.join(ROOT, 'modules', 'ui-design', 'scripts', 'gen-design-reference.js'));
+const PUB = path.join(ROOT, 'modules', 'ui-design', 'public');
+const PAGE = fs.readFileSync(path.join(PUB, 'brand.html'), 'utf8');
+const SHEET = fs.readFileSync(path.join(PUB, 'tokens.css'), 'utf8');
+const HALL = fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'style.css'), 'utf8');
+const PACK = JSON.parse(fs.readFileSync(path.join(ROOT, 'config', 'branding.neutral.json'), 'utf8'));
+
+function sources() {
+  return {
+    pack: JSON.parse(JSON.stringify(PACK)),
+    sheet: SHEET,
+    hall: HALL,
+    controls: fs.readFileSync(path.join(ROOT, 'modules', 'hall-ui', 'public', 'controls.css'), 'utf8'),
+    design: fs.readFileSync(path.join(ROOT, 'DESIGN.md'), 'utf8'),
+    genBrand: fs.readFileSync(path.join(ROOT, 'scripts', 'bongos', 'gen-brand.js'), 'utf8'),
+    otb: require(path.join(ROOT, 'modules', 'hall-ui', 'public', 'dom-utils.js')),
+  };
+}
+
+// ── 1. generated ─────────────────────────────────────────────────────────────
+
+test('the committed page is exactly what the generator writes', () => {
+  assert.equal(PAGE, gen.build(),
+    'modules/ui-design/public/brand.html is stale or hand-edited: run node modules/ui-design/scripts/gen-design-reference.js');
+});
+
+// ── 2. every value is on the page ────────────────────────────────────────────
+
+// the text of the row a token's name opens (one <li> per token)
+function rowOf(html, prop) {
+  const m = html.match(new RegExp(`<li class="ref-row[^"]*">(?:(?!</li>).)*?<code class="ref-name">${prop}</code>(?:(?!</li>).)*</li>`));
+  assert.ok(m, `the page has a row for ${prop}`);
+  return m[0];
+}
+
+test('every --ds-* token of the shared sheet is on the page with its value', () => {
+  const vars = gen.blockVars(SHEET, /(?:^|\n|\})\s*:root/, 'tokens.css');
+  assert.ok(vars.length > 40, 'the sheet was read');
+  for (const [prop, v] of vars) assert.ok(rowOf(PAGE, prop).includes(`<code>${v}</code>`), `${prop} shows ${v}`);
+  // the one mode-dependent scale shows its dark twin too
+  assert.match(rowOf(PAGE, '--ds-shadow-pop'), /dark<\/span> <code>0 18px 40px rgba\(0, 0, 0, \.62\)<\/code>/);
+});
+
+test('every pack colour shows its light value and its dark value; the status vocabulary both modes', () => {
+  for (const [key, light] of Object.entries(PACK.theme.ui.colors)) {
+    const prop = '--' + key.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase());
+    const r = rowOf(PAGE, prop);
+    assert.ok(r.includes(`light</span> <code>${light}</code>`), `${prop} light ${light}`);
+    assert.match(r, /dark<\/span> <code>[^<]+<\/code>/, `${prop} has a dark value`);
+  }
+  assert.ok(rowOf(PAGE, '--bg').includes('dark</span> <code>#000000</code>'), 'the dark ground is read from the hall\'s dark tier');
+  assert.ok(rowOf(PAGE, '--ok').includes('light</span> <code>#187444</code>') && rowOf(PAGE, '--ok').includes('dark</span> <code>#4ade80</code>'));
+  for (const s of ['--warn', '--danger', '--info', '--ok-weak', '--warn-weak', '--danger-weak', '--info-weak']) rowOf(PAGE, s);
+});
+
+test('the shared components, the logo and the naming rule are on the page', () => {
+  for (const sel of ['class="btn"', 'class="btn btn--ghost"', 'class="btn btn--danger"', 'class="btn btn--text"', 'class="hall-dialog"',
+    'data-kind="error"', 'class="viewtoggle"', 'class="hall-loading"', '<select>', '<textarea']) {
+    assert.ok(PAGE.includes(sel), `the page draws ${sel}`);
+  }
+  assert.equal((PAGE.match(/data-ref="tones"[^>]*>(.*?)<\/div>/) || [])[1].match(/status-pill--/g).length, 6, 'six tones');
+  assert.match(PAGE, /<use href="\/modules\/ui-design\/public\/brand\/mark\.svg#mark"\/>/, 'the mark is drawn from its one source');
+  assert.match(PAGE, /<span class="ref-lockup__name">cloud bongos<\/span>/, 'the wordmark is lowercase (DESIGN.md Naming)');
+  assert.match(PAGE, /Never &quot;CloudBongos&quot;/, 'the naming rule is read from DESIGN.md');
+  for (const f of ['mark-light.svg', 'mark-dark.svg', 'mark-mono.svg', 'favicon.svg']) assert.ok(PAGE.includes(`brand/${f}"`), `lists ${f}`);
+});
+
+// ── 3. the sources drive it ──────────────────────────────────────────────────
+
+test('a source change reaches the page (the generator reads the sources, not a copy)', () => {
+  const src = sources();
+  src.sheet = src.sheet.replace('--ds-space-hair:          6px;', '--ds-space-hair:          7px;');
+  src.pack.theme.ui.colors.accent = '#ff8855';
+  src.design = src.design.replace('- The domain is written', '- A new naming rule.\n- The domain is written');
+  const html = gen.build(src);
+  assert.ok(rowOf(html, '--ds-space-hair').includes('<code>7px</code>'));
+  assert.ok(rowOf(html, '--accent').includes('<code>#ff8855</code>'));
+  assert.match(html, /<li>A new naming rule\.<\/li>/);
+});
+
+test('a source losing what the page needs is an error, not a silent gap', () => {
+  const lostRule = sources();
+  lostRule.controls = lostRule.controls.split('.btn--danger').join('.btn--gone');
+  assert.throws(() => gen.build(lostRule), /no longer define \.btn--danger/);
+  const lostNaming = sources();
+  lostNaming.design = lostNaming.design.replace('\n## Naming\n', '\n## Names\n');
+  assert.throws(() => gen.build(lostNaming), /Naming/);
+  const newGroup = sources();
+  newGroup.sheet = newGroup.sheet.replace('--ds-line: 1px;', '--ds-line: 1px;\n  --ds-blur-glass: 18px;');
+  assert.throws(() => gen.build(newGroup), /--ds-blur-glass in no group/);
+});
+
+// ── 4. the floors ────────────────────────────────────────────────────────────
+
+test('no page :root, no colour literal in the layout sheet, and a kit states file for both modes', () => {
+  const css = fs.readFileSync(path.join(PUB, 'brand.css'), 'utf8').replace(/\/\*[\s\S]*?\*\//g, '');
+  assert.doesNotMatch(css, /:root/);
+  assert.doesNotMatch(css, /#[0-9a-f]{3,8}\b|rgba?\(/i, 'every colour is a token');
+  assert.doesNotMatch(PAGE, /<style>/, 'the page carries no style block of its own');
+  assert.doesNotMatch(PAGE, /cloudbongos\.com"/, 'no baked apex link');
+  const lib = require(path.join(ROOT, 'modules', 'ui-design', 'kit', 'lib.js'));
+  const states = JSON.parse(fs.readFileSync(path.join(PUB, 'brand.states.json'), 'utf8'));
+  assert.deepEqual(lib.validateStatesFile(states).errors || [], []);
+  assert.equal(states.page, '/brand');
+  assert.equal(states.modes, undefined, 'both modes: the page follows the device');
+});
+
+// ── 5. the route ─────────────────────────────────────────────────────────────
+
+const { buildPlatformApp } = require('../src/platform-server.js');
+const modules = require('../src/modules.js');
+let server;
+let port;
+before(async () => {
+  server = http.createServer(buildPlatformApp());
+  await new Promise((resolve) => server.listen(0, '127.0.0.1', resolve));
+  port = server.address().port;
+});
+after(async () => {
+  modules.setModuleOverrides({});
+  await new Promise((resolve) => server.close(resolve));
+});
+function get(pathname, host) {
+  return new Promise((resolve, reject) => {
+    http.get({ host: '127.0.0.1', port, path: pathname, headers: { Host: host } }, (res) => {
+      let body = '';
+      res.on('data', (c) => (body += c));
+      res.on('end', () => resolve({ status: res.statusCode, body }));
+    }).on('error', reject);
+  });
+}
+
+test('GET /brand: 200 signed-out on the hub\'s apex, branded; never on a child, the builders or status host', async () => {
+  modules.setModuleOverrides({ 'platform-identity': false });
+  assert.equal((await get('/brand', 'game.test.local')).status, 404, 'a child instance serves no platform reference');
+  modules.setModuleOverrides({ 'platform-identity': true, 'ui-design': true });
+  const hub = await get('/brand', 'game.test.local');
+  assert.equal(hub.status, 200, 'reachable with no session cookie');
+  assert.match(hub.body, /— Design system<\/title>/);
+  assert.match(hub.body, /window\.__BRANDING__=/, 'the pack is spliced, so the swatches take the instance colours');
+  assert.doesNotMatch(hub.body, /\{\{[a-zA-Z]+\}\}/, 'every token stamps');
+  for (const host of ['builders.test.local', 'status.test.local']) {
+    assert.doesNotMatch((await get('/brand', host)).body, /— Design system<\/title>/, `${host} must not serve /brand`);
+  }
+  const css = await get('/modules/ui-design/public/brand.css', 'game.test.local');
+  assert.equal(css.status, 200, 'the layout sheet is served at its module path');
+});

package/tests/hall_catalog_world.mjs

@@ -168,10 +168,15 @@ test('the shell no longer aliases .mod-chip onto the pill', () => {
 
 test('atlas: the nine semantic colours stay fixed literals, and nothing else in the sheet is one', () => {
   const css = read('atlas.css');
-  for (const t of ['--ab-sun', '--ab-sky', '--ab-coral', '--ab-paper', '--ab-good', '--ab-core', '--ab-db', '--ab-ghost', '--ab-danger']) {
+  for (const t of ['--ab-sun', '--ab-sky', '--ab-coral', '--ab-paper', '--ab-ghost']) {
     assert.match(css, new RegExp(`${t}:#[0-9a-f]{6}`), `${t} is a fixed literal (ADR 0094)`);
   }
-  const rest = decomment(css).replace(/--ab-(sun|sky|coral|paper|good|core|db|ghost|danger):#[0-9a-f]{6}/g, '');
+  // task 1005087: the four STATE colours are the hall's status vocabulary — fixed per instance
+  // (never the pack's), so ADR 0094's no-scramble invariant still holds, and no longer Tailwind's.
+  for (const [t, tok] of [['--ab-good', '--ok'], ['--ab-core', '--warn'], ['--ab-db', '--danger'], ['--ab-danger', '--danger']]) {
+    assert.match(css, new RegExp(`${t}:var\\(${tok}\\)`), `${t} is the hall's ${tok}`);
+  }
+  const rest = decomment(css).replace(/--ab-(sun|sky|coral|paper|ghost):#[0-9a-f]{6}/g, '');
   assert.deepEqual(rest.match(/#[0-9a-f]{3,8}\b/gi) || [], [], 'no other literal colour');
   noAlias(css, 'atlas.css');
   tokensDefined(css, 'atlas.css');