Files
llama.cpp/ui/apps/chat/scripts/design-md.js
T
Aleksander Grygier 65758d01f5 ui: Storybook follow-ups: generated DESIGN.md tokens, shared helpers and one Llama Mono (#32523)
* ui: generate DESIGN.md's token sections from the CSS

Add scripts/design-md.js in ui/apps/chat (npm run design:tokens, and npm
run check:design in CI), which writes the colors, typography and rounded
sections of DESIGN.md's front matter from llama-brand's colors.css and
Llama UI's primitives, semantic tokens and font stacks. The front matter
had drifted: it gave Matte's surfaces as the light base and system-ui for
every text role. Twins are now written wherever a token resolves
differently in dark mode (-dark) or in Matte (-matte).

Describe the floating panel's rim as the CSS draws it, on the border,
and say which parts of DESIGN.md are generated and which are kept by hand.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: say the Storybooks show accessibility findings without enforcing them

Both Storybooks keep a11y test 'todo': under 'error' 98 of the stories
fail, most on colour contrast of the muted foreground and on nested
interactive controls, which need design changes. Reword the Uses tile
and record the reason next to the setting.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: list every Llama Chat group in the Introduction's Sections figure

The figure said it was in sidebar order but left out Forms, Actions,
Badges, Misc, Servers and PWA. Its list moves to sections.ts, and a unit
test checks it against storySort in .storybook/preview.ts, which has to
stay inline there because Storybook parses it as written.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: load the package's Llama Mono in both Storybooks

The library's Storybook declared Llama Mono a second time from
tests/stories/brand/fonts, a 72276-byte file that differs from the
76896-byte one the package ships, so its pages showed a Llama Mono that
does not ship. Drop both Storybooks' copies: theme.css already loads the
package's font.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: take Llama Chat's shared Storybook helpers from Llama UI

Llama Chat kept copies of the Editorial, Chapters, StateGallery,
StateGalleryItem, svx.d.ts and docs.css that live with the library's
stories. Its stories now import them as $llama-ui-stories/..., an alias
its Storybook config and tsconfig.json map onto ui/lib/ui/tests/stories,
the way it already compiles the library from source; docs.css and
svx.d.ts are referenced by path. The library's Editorial takes Llama
Chat's newer list numbering. An empty svelte.config.js next to the
stories keeps Llama Chat's svelte-check from loading the library's
vite.config.ts, as src/svelte.config.js does for the sources.

Assisted-by: Claude (Opus 5.5 Medium)

* ui: pin the library's Storybook to Llama Chat's versions

ui/lib/ui used ^10.6.2 with @storybook/addon-mcp at 10.6.2, while
ui/apps/chat pins 10.6.6, so one tree had two Storybooks. Pin the
library's Storybook packages exactly to Llama Chat's: 10.6.6,
addon-svelte-csf 5.1.6 and @chromatic-com/storybook 5.5.1.

Assisted-by: Claude (Opus 5.5 Medium)
2026-11-18 09:45:36 +01:00

302 lines
9.9 KiB
JavaScript

#!/usr/bin/env node
/**
* Writes the token sections of DESIGN.md's front matter (`colors`, `typography` and `rounded`) from the CSS they
* mirror, so the file agents read cannot drift from the code:
*
* - the brand's colours, @ggml-org/llama-brand's css/colors.css,
* - Llama UI's primitives and semantic tokens, ui/lib/ui/src/lib/styles/tokens/{primitives,semantic}.css,
* - Llama UI's font stacks, ui/lib/ui/src/lib/styles/theme.css.
*
* Everything else in DESIGN.md, the `spacing` and `components` sections and the prose, is written by hand.
*
* Usage: node scripts/design-md.js [--check]
*
* --check writes nothing and exits with 1 if DESIGN.md is not current, for CI (`npm run check:design`).
*/
import { readFileSync, writeFileSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
const app = new URL('../', import.meta.url);
const styles = new URL('../../../lib/ui/src/lib/styles/', import.meta.url);
const DESIGN_MD = fileURLToPath(new URL('DESIGN.md', app));
const SOURCES = {
brand: fileURLToPath(new URL('node_modules/@ggml-org/llama-brand/css/colors.css', app)),
primitives: fileURLToPath(new URL('tokens/primitives.css', styles)),
semantic: fileURLToPath(new URL('tokens/semantic.css', styles)),
theme: fileURLToPath(new URL('theme.css', styles))
};
// the selectors of the themes a semantic token may change in, and the suffix its twin takes here
const THEMES = [
{ selector: '.theme-matte:not(.dark)', suffix: '-matte' },
{ selector: '.dark', suffix: '-dark' }
];
// the type roles, by the @theme names Tailwind turns into text-body, text-label-sm, ...: a size with a line height
const TYPE_ROLE = /^--text-([a-z]+(?:-[a-z]+)*)$/;
// code takes the body-sm role in the mono stack (see `:where(code, pre, kbd, samp)` in theme.css)
const CODE_ROLE = 'body-sm';
// Tailwind's own `rounded-full`, for lamps, avatars and round buttons; the other corners are roles in semantic.css
const ROUNDED_FULL = '9999px';
// the sections this script owns, in the order they appear in the front matter; the next one is written by hand
const SECTIONS = ['colors', 'typography', 'rounded'];
const NEXT_SECTION = 'spacing';
/** @param {string} css @returns {string} */
function stripComments(css) {
return css.replace(/\/\*[\s\S]*?\*\//g, '');
}
/**
* The custom properties declared in each top-level block, by the block's selector (or at-rule).
* @param {string} css
* @returns {Map<string, Map<string, string>>}
*/
function parseBlocks(css) {
/** @type {Map<string, Map<string, string>>} */
const blocks = new Map();
const source = stripComments(css);
let depth = 0;
let start = 0;
let selector = '';
for (let i = 0; i < source.length; i++) {
const char = source[i];
if (char === '{') {
if (depth === 0) {
selector = source.slice(start, i).trim().split(';').pop()?.trim() ?? '';
start = i + 1;
}
depth++;
} else if (char === '}') {
depth--;
if (depth === 0) {
const declarations = blocks.get(selector) ?? new Map();
for (const [, name, value] of source
.slice(start, i)
.matchAll(/(--[\w-]+)\s*:\s*([^;]+);/g)) {
declarations.set(name, value.replace(/\s+/g, ' ').trim());
}
blocks.set(selector, declarations);
start = i + 1;
}
}
}
return blocks;
}
/** @param {string} path @returns {Map<string, Map<string, string>>} */
function readBlocks(path) {
return parseBlocks(readFileSync(path, 'utf8'));
}
/** @param {string} value */
const isColorLiteral = (value) =>
/^#[0-9a-f]{3,8}$/i.test(value) ||
value === 'transparent' ||
/^(oklch|oklab|rgb|hsl)\([^()]*\)$/.test(value);
/** @param {string} value */
const isColorMix = (value) => /^color-mix\(.*\)$/.test(value) && !/\)\s*,/.test(value);
/** @param {string} value */
const varName = (value) => /^var\(--([\w-]+)\)$/.exec(value)?.[1];
function build() {
const brand = readBlocks(SOURCES.brand).get(':root') ?? new Map();
const primitiveBlocks = readBlocks(SOURCES.primitives);
const primitives = new Map([...brand, ...(primitiveBlocks.get(':root') ?? [])]);
const semanticBlocks = readBlocks(SOURCES.semantic);
const semantic = semanticBlocks.get(':root') ?? new Map();
const inline = semanticBlocks.get('@theme inline') ?? new Map();
const theme = readBlocks(SOURCES.theme);
/** @type {Map<string, string>} name (no dashes) to literal colour */
const primitiveColors = new Map();
for (const [name, value] of primitives) {
if (isColorLiteral(value)) primitiveColors.set(name.slice(2), value);
}
/** @param {string} value @param {Map<string, string>} scope */
const isColor = (value, scope) => {
if (isColorLiteral(value) || isColorMix(value)) return true;
const ref = varName(value);
if (!ref) return false;
if (primitiveColors.has(ref)) return true;
const next = scope.get(`--${ref}`);
return next !== undefined && isColor(next, scope);
};
const semanticColors = [...semantic].filter(([, value]) => isColor(value, semantic));
const semanticNames = new Set(semanticColors.map(([name]) => name.slice(2)));
/**
* A token's value as the front matter writes it: a reference to another token, a literal, or a mix of them. A
* primitive faded with transparent (`color-mix(in oklch, var(--neutral-100) 30%, transparent)`) is written as the
* colour it is, with its alpha (`oklch(0.97 0 0 / 0.3)`).
* @param {string} value
* @param {(name: string) => string} ref the front matter name a token reference points at
*/
const render = (value, ref) => {
const faded = /^color-mix\(in oklch, var\(--([\w-]+)\) (\d+(?:\.\d+)?)%, transparent\)$/.exec(
value
);
const base = faded && primitiveColors.get(faded[1]);
if (faded && base && /^oklch\([^/]*\)$/.test(base)) {
return `${base.slice(0, -1)} / ${Number(faded[2]) / 100})`;
}
return value.replace(/var\(--([\w-]+)\)/g, (_, name) => `{colors.${ref(name)}}`);
};
/** @type {[string, string][]} */
const colors = [['primary', '{colors.action-primary}']];
for (const [name, value] of primitiveColors) colors.push([name, value]);
/** @type {Map<string, string>} */
const base = new Map();
for (const [name, value] of semanticColors) {
const rendered = render(value, (n) => n);
base.set(name, rendered);
colors.push([name.slice(2), rendered]);
}
// a twin per theme wherever the token resolves differently there, directly or through a token it points at
for (const { selector, suffix } of THEMES) {
const overrides = semanticBlocks.get(selector) ?? new Map();
/** @type {Set<string>} */
const twins = new Set();
/** @type {Map<string, string>} */
const rendered = new Map();
// twins resolve in dependency order: a reference to a token that has a twin points at the twin
/** @param {string} name */
const resolve = (name) => {
if (rendered.has(name)) return /** @type {string} */ (rendered.get(name));
const value = overrides.get(name) ?? semantic.get(name) ?? '';
for (const [, ref] of value.matchAll(/var\(--([\w-]+)\)/g)) {
if (semanticNames.has(ref)) resolve(`--${ref}`);
}
const result = render(value, (n) => (twins.has(n) ? `${n}${suffix}` : n));
rendered.set(name, result);
if (result !== base.get(name)) twins.add(name.slice(2));
return result;
};
for (const [name] of semanticColors) resolve(name);
for (const [name] of semanticColors) {
if (twins.has(name.slice(2)))
colors.push([`${name.slice(2)}${suffix}`, rendered.get(name) ?? '']);
}
}
const firstFamily = (/** @type {string | undefined} */ stack) =>
stack?.split(',')[0].trim().replace(/^'|'$/g, '') ?? 'system-ui';
const sans = firstFamily(theme.get('@theme inline')?.get('--font-sans'));
const mono = firstFamily(theme.get(':root')?.get('--font-mono'));
/** @param {string | undefined} value */
const length = (value) => {
const name = value && varName(value);
return (name && primitives.get(`--${name}`)) ?? value ?? '';
};
/** @type {[string, Record<string, string>][]} */
const typography = [];
for (const [name, value] of inline) {
const role = TYPE_ROLE.exec(name)?.[1];
if (!role || !inline.has(`${name}--line-height`)) continue;
typography.push([
role,
{
fontFamily: sans,
fontSize: length(value),
fontWeight: length(inline.get(`${name}--font-weight`)),
lineHeight: length(inline.get(`${name}--line-height`))
}
]);
}
const code = typography.find(([role]) => role === CODE_ROLE);
if (code) typography.push(['code', { ...code[1], fontFamily: mono }]);
/** @type {[string, string][]} */
const rounded = [];
for (const [name, value] of inline) {
const role = /^--radius-([a-z-]+)$/.exec(name)?.[1];
if (role) rounded.push([role, length(value)]);
}
rounded.push(['full', ROUNDED_FULL]);
/** @param {string} value */
const quote = (value) => (/^[\w.-]+$/.test(value) ? value : `'${value.replace(/'/g, "''")}'`);
const lines = ['colors:'];
for (const [name, value] of colors) lines.push(` ${name}: '${value.replace(/'/g, "''")}'`);
lines.push('typography:');
for (const [role, style] of typography) {
lines.push(` ${role}:`);
for (const [key, value] of Object.entries(style)) lines.push(` ${key}: ${quote(value)}`);
}
lines.push('rounded:');
for (const [role, value] of rounded) lines.push(` ${role}: ${value}`);
return lines.join('\n') + '\n';
}
const check = process.argv.includes('--check');
const current = readFileSync(DESIGN_MD, 'utf8');
const start = current.indexOf(`\n${SECTIONS[0]}:\n`) + 1;
const end = current.indexOf(`\n${NEXT_SECTION}:\n`) + 1;
if (!current.startsWith('---\n') || start <= 0 || end <= start) {
console.error(`DESIGN.md: no front matter with ${SECTIONS[0]}: ... ${NEXT_SECTION}: in it`);
process.exit(1);
}
const next = current.slice(0, start) + build() + current.slice(end);
if (check) {
if (next !== current) {
console.error(
'DESIGN.md is out of date with the tokens: run `npm run design:tokens` in ui/apps/chat and commit it.'
);
process.exit(1);
}
console.log('DESIGN.md is current.');
} else if (next !== current) {
writeFileSync(DESIGN_MD, next);
console.log('DESIGN.md updated.');
} else {
console.log('DESIGN.md is already current.');
}