* 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)
302 lines
9.9 KiB
JavaScript
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.');
|
|
}
|