Skip to content

Qwen3.8-Flash-Next on any consumer hardware: one-click install for Windows / Linux. Strata inference engine, OpenAI/Anthropic API on localhost, optional image input.

C++
16.5 KB
Raw Blame
#!/usr/bin/env node
/**
 * Strata UI audit.
 *
 *   node scripts/audit-ui.mjs
 *
 * Static checks over the app's own stylesheet and the synced kit copy. Everything
 * it asserts is a rule from src/styles/app.css's header comment or
 * docs/interaction-guidelines.md, so a failure means one of those documents and
 * the code disagree.
 *
 * Exits non-zero when anything fails, so it can gate a release.
 */
import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
const APP = join(ROOT, 'src/styles/app.css');
const KIT_SRC = join(ROOT, '..', 'ui');
const KIT_COPY = join(ROOT, 'src/styles/kit');

const KIT_SCALES = {
  radius: new Set(['8px', '14px', '20px', '24px', '9999px', '999px', '50%', '6px', '10px', '12px', '15px', '16px', '2px', '1.5px', 'inherit', '0']),
  fontSize: new Set(['11px', '12px', '13px', '14px', '15px', '16px', '17px', '18px', '19px', '22px', '24px', '30px', '32px', '40px', 'inherit']),
  shadow: [
    /^var\(--st-sh-(card|bar|pop)\)/, // the kit's three elevation tokens
    /^var\(--st-accent-surface-shadow\)/, // the accent-filled surfaces' own elevation
    /^none$/,
    /^inset/, // specular edges and focus rings
    /^0 0 0 \d+px var\(--st-/, // halo rings
  ],
};

/** Durations that belong to a looping indicator, not to a transition. */
const LOOP_DURATION_OK = new Set([
  '1s', '720ms', '1.1s', '1.15s', '1.4s', '1.6s', '1.8s',
  '420ms', '560ms', '260ms', // spring pops and the step marker
]);

/** The only infinite animations allowed, and why. */
const INFINITE_OK = new Set([
  'st-slide',  // indeterminate progress
  'st-pulse',  // busy dot
  'st-typing', // assistant is composing
  'st-blink',  // text caret
  'st-scan',   // hardware probe sweep (first run only)
  'st-spin',   // install stage spinner
  'st-ripple', // "ready" ring, first run only
]);

/** Layout properties that must never be transitioned (they thrash layout). */
const LAYOUT_PROPS = ['width', 'height', 'top', 'left', 'right', 'bottom', 'margin', 'padding', 'font-size'];

/**
 * Surfaces allowed to carry a material. Every one of them overlays content that
 * moves underneath; anything else would pay for a compositor pass and show
 * nothing.
 */
const BLUR_ALLOWED = new Set([
  '.main__head',
  '.focusbar',
  '.composer',
  '.slashmenu',
  '.select__pop',
  '.menu',
  '.telepop',
  '.scrim',
  '.config-savebar', // floating commit controls
  '.mobile-bar', // compact navigation controls
  '.st-toast--toned',
]);

/**
 * Surfaces that genuinely float above the page, and so may carry an elevation
 * shadow. A card sitting on the page background does not float: its shadow only
 * added a second edge next to the hairline.
 */
const ELEVATION_ALLOWED = new Set([
  '.modal',
  '.dialog-surface', // modal content sheet
  '.message-overflow[open] > div', // floating message menu
  '.app[data-nav-open=\'true\'] > .nav', // dismissible navigation sheet
  '.st-tab[aria-checked=\'true\']', // selected segmented control
  '.nav-new', // primary action affordance
  '.st-drawer.sheet',
  '.slashmenu',
  '.select__pop',
  '.menu',
  '.telepop',
  '.setup__panel',
  '.setupmodal__surface',
  '.st-tablewrap',
  '.st-toast--toned',
  // The jump-to-latest pill sits above a scrolling transcript, so it genuinely
  // overlaps moving content — the same test the other entries pass.
  '.jumplatest',
  '.st-btn--primary', // the accent fill's own lift
  '.st-slider::-webkit-slider-thumb', // a control affordance: the thumb needs to read against its track
  '.st-toggle::after', // same: the knob needs to read against its track
]);

/**
 * Controls, which Liquid Glass specifies as capsules. A control is something you
 * press or type into; a surface is something content sits on, and those stay on
 * the kit's 8/14/20/24 scale.
 */
const CAPSULE_CONTROLS = ['.st-btn', '.st-input', '.st-tab', '.navitem', '.navsession', '.slashmenu__item', '.treerow'];

/** Literal colours that are deliberate and documented. */
const DOCUMENTED_LITERALS = ['#05261b', '#12c68e', '#0a7a55'];

const failures = [];
const notes = [];
const fail = (file, line, message) => failures.push(`${file}:${line}  ${message}`);

/* ------------------------------------------------------------ app.css ---- */

const css = readFileSync(APP, 'utf8');
const lines = css.split('\n');
let selector = '(top level)';
let inKeyframes = false;

lines.forEach((raw, i) => {
  const line = raw.replace(/\/\*.*?\*\//g, '');
  const n = i + 1;

  const sel = line.match(/^([^@{}\s][^{}]*)\{$/);
  if (sel) selector = sel[1].trim();
  if (/@keyframes/.test(line)) inKeyframes = true;
  if (inKeyframes && /^\}/.test(line)) inKeyframes = false;

  for (const [, prop, rawValue] of line.matchAll(/([a-z-]+)\s*:\s*([^;]+);/g)) {
    const value = rawValue.trim();

    // --- static design-system rules -------------------------------------
    if (prop === 'border-radius') {
      for (const part of value.split(/\s+/)) {
        if (!KIT_SCALES.radius.has(part) && !part.startsWith('var(') && !part.includes('%')) {
          fail('app.css', n, `off-scale radius "${part}" in ${selector}`);
        }
      }
    }
    if (prop === 'font-size' && !value.startsWith('var(') && !value.includes('clamp') && !KIT_SCALES.fontSize.has(value)) {
      fail('app.css', n, `off-scale font-size "${value}" in ${selector}`);
    }
    if (prop === 'box-shadow' && !KIT_SCALES.shadow.some((re) => re.test(value))) {
      fail('app.css', n, `shadow is not a kit token: "${value}" in ${selector}`);
    }
    if (/gradient|radial|conic/.test(value) && prop.startsWith('background')) {
      fail('app.css', n, `gradient in ${selector} — the system is flat`);
    }
    if (/^(color|background|background-color|border-color)$/.test(prop)) {
      const literals = value.match(/#[0-9a-fA-F]{3,8}\b|rgba?\([^)]*\)/g);
      if (literals && !value.includes('data:image') && !value.includes('currentColor')
          && !DOCUMENTED_LITERALS.some((d) => value.includes(d))) {
        fail('app.css', n, `literal colour "${value}" in ${selector} — use a token`);
      }
    }

    // --- motion rules ----------------------------------------------------
    // --- materials ------------------------------------------------------
    // Values must be a --st-material-* token: that is what collapses the blur
    // under reduced transparency, so gating cannot be forgotten.
    if (prop === 'backdrop-filter' || prop === '-webkit-backdrop-filter') {
      if (!/^var\(--st-material-(thin|regular|thick)\)$/.test(value) && !(selector === '.scrim' && value === 'none !important')) {
        fail('app.css', n, `blur must use a --st-material-* token (it carries the gating): "${value}"`);
      }
      if (!BLUR_ALLOWED.has(selector)) {
        fail('app.css', n, `material on "${selector}", which is not an approved surface — it does not overlay moving content`);
      }
    }
    if (prop === 'box-shadow' && /var\(--st-sh-(card|bar|pop)\)/.test(value) && !ELEVATION_ALLOWED.has(selector)) {
      fail('app.css', n, `elevation shadow on "${selector}" — shadows are reserved for surfaces that overlap content`);
    }

    if (prop === 'transition') {
      if (/^\d/.test(value) || /(^|[\s,])\d+m?s\b/.test(value)) {
        fail('app.css', n, `raw duration in transition — use a --st-t-* token: "${value}"`);
      }
      for (const part of value.split(',')) {
        const prop0 = part.trim().split(/\s+/)[0];
        if (LAYOUT_PROPS.includes(prop0)) {
          fail('app.css', n, `transition on layout property "${prop0}" in ${selector}`);
        }
      }
    }
    if (prop === 'transition-property') {
      for (const p of value.split(',').map((v) => v.trim())) {
        if (LAYOUT_PROPS.includes(p)) fail('app.css', n, `transition on layout property "${p}" in ${selector}`);
      }
    }
    if (prop === 'animation' || prop === 'animation-name') {
      const name = value.match(/^(st-[a-z-]+)/)?.[1];
      const infinite = /infinite/.test(value);
      if (infinite && name && !INFINITE_OK.has(name)) {
        fail('app.css', n, `looping animation "${name}" is not on the allowlist — nothing loops while idle`);
      }
      const duration = value.match(/\b(\d+(?:\.\d+)?m?s)\b/)?.[1];
      if (duration && !LOOP_DURATION_OK.has(duration)) {
        fail('app.css', n, `raw animation duration "${duration}" in ${selector} — use a --st-t-* token`);
      }
    }
    if (prop === 'animation-duration' && /^\d/.test(value) && !LOOP_DURATION_OK.has(value)) {
      fail('app.css', n, `raw animation-duration "${value}" in ${selector}`);
    }
  }
});

/* ------------------------------------------------- kit sync + motion scale -- */

for (const file of ['tokens.css', 'components.css']) {
  const a = join(KIT_SRC, file);
  const b = join(KIT_COPY, file);
  if (!existsSync(a) || !existsSync(b)) {
    fail('kit', 0, `${file} missing on one side`);
    continue;
  }
  // The sync rewrites @font-face URLs to absolute; everything else must match.
  const norm = (t) => t.replace(/url\((["']?)\/fonts\//g, 'url($1fonts/').trim();
  if (norm(readFileSync(a, 'utf8')) !== norm(readFileSync(b, 'utf8'))) {
    fail('kit', 0, `${file} has drifted from ../ui — run npm run sync:kit`);
  }
}

// Which selectors have been given the capsule radius.
const capsuled = new Set();
{
  const rules = css.replace(/\/\*[\s\S]*?\*\//g, '');
  for (const [, sel, body] of rules.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
    if (!/border-radius:\s*var\(--st-r-pill\)/.test(body)) continue;
    for (const part of sel.split(',')) capsuled.add(part.trim());
  }
}
for (const c of CAPSULE_CONTROLS) {
  if (!capsuled.has(c)) {
    fail('app.css', 0, `${c} is a control but not a capsule — Liquid Glass specifies capsule-shaped controls`);
  }
}

/* ------------------------------------------------------------ source rules -- */

// The popup of a native <select> is drawn by the OS and shares nothing with the
// design system — it was the single most out-of-place surface in the app.
for (const file of [...readdirSync(join(ROOT, 'src'), { recursive: true })].filter((f) => /\.tsx?$/.test(String(f)))) {
  const full = join(ROOT, 'src', String(file));
  if (!statSync(full).isFile()) continue;
  // Strip comments first: the Select component's own doc comment *describes*
  // the native element it replaces, and matching prose would be a false alarm.
  const text = readFileSync(full, 'utf8')
    .replace(/\/\*[\s\S]*?\*\//g, '')
    .replace(/^\s*\/\/.*$/gm, '');
  if (/<select[\s>]/.test(text)) {
    fail(`src/${file}`, 0, 'native <select> — use the Select component, whose popup we control');
  }
}

// Every <Icon name="..."> must resolve to a symbol in the sprite, or it renders
// as an empty box at runtime.
const sprite = readFileSync(join(ROOT, 'public/icons/sprite.svg'), 'utf8');
const symbols = new Set([...sprite.matchAll(/id="i-([a-z-]+)"/g)].map((m) => m[1]));
const referenced = new Set();
for (const file of [...readdirSync(join(ROOT, 'src'), { recursive: true })].filter((f) => /\.tsx$/.test(String(f)))) {
  const full = join(ROOT, 'src', String(file));
  if (!statSync(full).isFile()) continue;
  for (const m of readFileSync(full, 'utf8').matchAll(/name="([a-z-]+)"/g)) referenced.add(m[1]);
}
for (const name of referenced) {
  if (!symbols.has(name)) fail('src', 0, `icon "${name}" is referenced but not in the sprite — run npm run sync:kit`);
}

/* ---------------------------------------------------------- undefined classes -- */

// A class a component uses that no stylesheet defines renders unstyled and fails
// silently. An earlier "dead CSS" sweep deleted three of these because the sweep
// looked for `className="..."` literals and missed other spellings; the app
// shipped with unstyled metric sub-lines and toast bodies.
{
  const allCss = [];
  for (const dir of ['src/styles', 'src/styles/kit']) {
    for (const f of readdirSync(join(ROOT, dir))) {
      if (f.endsWith('.css')) allCss.push(readFileSync(join(ROOT, dir, f), 'utf8'));
    }
  }
  // Strip comments first: the note explaining this very check names the classes
  // it is about, and matching prose would satisfy the rule it exists to enforce.
  const cssCode = allCss.join('\n').replace(/\/\*[\s\S]*?\*\//g, '');
  const defined = new Set([...cssCode.matchAll(/\.([a-z][a-z0-9_-]*)/g)].map((m) => m[1]));
  const used = new Map();
  for (const file of [...readdirSync(join(ROOT, 'src'), { recursive: true })].filter((f) => /\.tsx$/.test(String(f)))) {
    const full = join(ROOT, 'src', String(file));
    if (!statSync(full).isFile()) continue;
    const text = readFileSync(full, 'utf8');
    // Any quoted class-shaped token, wherever it appears — className literals,
    // cx() arguments, ternaries. Missing a spelling is what caused the bug.
    for (const m of text.matchAll(/['"`]([a-z][a-z0-9_-]*(?:__|--)[a-z0-9_-]+)['"`]/g)) {
      used.set(m[1], String(file));
    }
  }
  for (const [cls, file] of used) {
    if (!defined.has(cls)) {
      fail(`src/${file}`, 0, `class "${cls}" is used but defined in no stylesheet — it renders unstyled`);
    }
  }
}

/* ------------------------------------------------------- undefined tokens -- */

// A `var(--st-…)` with no definition is not an error the browser reports: the
// declaration is simply dropped. `--st-accent-line` sat in a reduced-motion
// rule for several rounds, so the border it set never applied and the rule
// looked deliberate. Only kit-prefixed tokens are checked, since app-local
// custom properties are defined and consumed in the same file.
{
  const appCss = readdirSync(join(ROOT, 'src/styles'))
    .filter((f) => f.endsWith('.css'))
    .map((f) => readFileSync(join(ROOT, 'src/styles', f), 'utf8'))
    .join('\n');
  const kitCss = readdirSync(join(ROOT, 'src/styles/kit'))
    .filter((f) => f.endsWith('.css'))
    .map((f) => readFileSync(join(ROOT, 'src/styles/kit', f), 'utf8'))
    .join('\n');
  const all = `${appCss}\n${kitCss}`.replace(/\/\*[\s\S]*?\*\//g, '');
  const declared = new Set([...all.matchAll(/(--st-[a-z0-9-]+)\s*:/g)].map((m) => m[1]));
  /* Some tokens are set at runtime rather than written in a stylesheet —
     `--st-content-fs` follows the reading-size preference. Without this the
     rule reports a legitimate token, which is how a check earns being ignored. */
  for (const file of [...readdirSync(join(ROOT, 'src'), { recursive: true })].filter((f) => /\.tsx?$/.test(String(f)))) {
    const full = join(ROOT, 'src', String(file));
    if (!statSync(full).isFile()) continue;
    for (const m of readFileSync(full, 'utf8').matchAll(/setProperty\(\s*['"`](--st-[a-z0-9-]+)/g)) declared.add(m[1]);
  }
  const used = new Map();
  for (const m of all.matchAll(/var\((--st-[a-z0-9-]+)/g)) {
    if (!used.has(m[1])) used.set(m[1], true);
  }
  for (const name of used.keys()) {
    if (!declared.has(name)) {
      fail('src/styles/app.css', 0, `var(${name}) has no definition — the declaration using it is silently dropped`);
    }
  }
  notes.push(`tokens: every var(--st-*) resolves to a declaration`);
}

const tokens = new Set([...css.matchAll(/--st-t-[a-z]+:/g)].map((m) => m[0].slice(0, -1)));
const used = new Set([...css.matchAll(/var\((--st-t-[a-z]+)\)/g)].map((m) => m[1]));
for (const u of used) {
  if (!tokens.has(u)) fail('app.css', 0, `uses ${u}, which is not declared in the motion scale`);
}
const SCALE = ['--st-t-micro', '--st-t-control', '--st-t-local', '--st-t-surface', '--st-t-choreo'];
notes.push(`motion scale: ${SCALE.filter((t) => tokens.has(t)).length}/5 tokens declared, ${used.size} in use`);
notes.push(`kit copy: in sync with ../ui`);

/* ------------------------------------------------------------------ report -- */

const keyframes = (css.match(/@keyframes/g) ?? []).length;
notes.push(`keyframes: ${keyframes} (was 23 before consolidation)`);
notes.push(`materials: ${BLUR_ALLOWED.size} approved surfaces, all token-gated`);
notes.push(`elevation: ${ELEVATION_ALLOWED.size} floating surfaces, ${(css.match(/var\(--st-sh-(card|bar|pop)\)/g) ?? []).length} shadow uses`);
notes.push(`capsules: ${CAPSULE_CONTROLS.length}/${CAPSULE_CONTROLS.length} controls, surfaces untouched`);
notes.push(`icons: ${referenced.size} referenced, all present in a ${symbols.size}-symbol sprite`);
notes.push(`dropdowns: no native <select> in src/`);
notes.push(`classes: every class a component uses is defined in a stylesheet`);

if (failures.length) {
  console.log(`ui audit: ${failures.length} failure(s)\n`);
  for (const f of failures) console.log(`  ${f}`);
  console.log();
  for (const n of notes) console.log(`  · ${n}`);
  process.exit(1);
}
console.log('ui audit: clean\n');
for (const n of notes) console.log(`  · ${n}`);