@cparkerwebm/webmonterey 1.0.0

package/src/design/__fixtures__/tokens-v1.4.1.css

@@ -0,0 +1,227 @@
+/*
+ * webm.tokens — the design system. THIS FILE IS THE SOURCE OF TRUTH.
+ *
+ * Edit values here. Every colour, size, space, radius, shadow, z-index, duration and easing
+ * used anywhere in the site must come from one of these custom properties — component CSS
+ * contains no literal values.
+ *
+ * To retheme a client, the usual move is to override the token in src/styles/custom/ under
+ * @layer webm.overrides — one declaration cascades everywhere at once, and it keeps the
+ * client's palette in one place someone can find later.
+ *
+ * Editing this file directly is allowed too. A client repo is a copy of the starter and never
+ * pulls a later version forward, so these tokens are the client's to set outright; where the
+ * whole palette differs, changing the values here beats shadowing every one of them from
+ * custom/. Neither choice costs anything at build time — pick the one that will read more
+ * clearly to whoever opens the repo next.
+ */
+
+@layer webm.tokens {
+  :root {
+    /* --- base palette ------------------------------------------------------ */
+    /* Raw neutrals. Everything semantic below points at these, not the other way round. */
+    --webm-base-100: #ffffff;
+    --webm-base-300: #f1eae8;
+    --webm-base-500: #3f3f3f;
+    --webm-base-700: #222222;
+    --webm-base-900: #000000;
+
+    /* --- action ------------------------------------------------------------ */
+    /* The brand colour. Retheming a client usually starts and ends here. */
+    --webm-action: #006abe;
+    --webm-action-dark: #003e80;
+    --webm-action-light: #6bc7ff;
+
+    /* --- surface ----------------------------------------------------------- */
+    --webm-surface: var(--webm-base-100);
+    --webm-surface-alt: var(--webm-base-300);
+    --webm-surface-accent: var(--webm-action-light);
+    --webm-surface-inverse: var(--webm-base-900);
+    --webm-surface-raised: var(--webm-base-100);
+
+    /* --- text -------------------------------------------------------------- */
+    --webm-text: var(--webm-base-700);
+    --webm-text-muted: var(--webm-base-500);
+    --webm-text-strong: var(--webm-base-900);
+    --webm-text-inverse: var(--webm-base-100);
+    --webm-text-on-action: var(--webm-base-100);
+
+    /* --- link -------------------------------------------------------------- */
+    --webm-link: var(--webm-action);
+    --webm-link-hover: var(--webm-action-dark);
+    --webm-link-visited: var(--webm-action-dark);
+
+    /* --- border ------------------------------------------------------------ */
+    --webm-border-subtle: #dcd3d0;
+    --webm-border-interactive: var(--webm-base-500);
+    --webm-border-strong: var(--webm-base-700);
+
+    /* --- state ------------------------------------------------------------- */
+    --webm-state-success: #0f7b3f;
+    --webm-state-warning: #9a6700;
+    --webm-state-danger: #b3261e;
+    --webm-state-info: var(--webm-action);
+
+    /* --- font -------------------------------------------------------------- */
+    /*
+     * System stack by default — zero network cost, no layout shift, no dependency.
+     * To use a real typeface, put the woff2 in public/fonts/, declare @font-face in
+     * src/styles/custom/, and prepend the family here.
+     */
+    --webm-font-sans: system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif;
+    --webm-font-mono: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+
+    /* --- font-size --------------------------------------------------------- */
+    /* Fluid scale. Each step interpolates between a mobile and a desktop size. */
+    --webm-font-size-2xs: clamp(0.6944rem, 0.6859rem + 0.0426vw, 0.72rem);
+    --webm-font-size-xs: clamp(0.8333rem, 0.8111rem + 0.1111vw, 0.9rem);
+    --webm-font-size-sm: clamp(1rem, 0.9583rem + 0.2083vw, 1.125rem);
+    --webm-font-size-md: clamp(1.2rem, 1.1312rem + 0.3438vw, 1.406rem);
+    --webm-font-size-lg: clamp(1.44rem, 1.3341rem + 0.5297vw, 1.758rem);
+    --webm-font-size-xl: clamp(1.728rem, 1.5716rem + 0.7821vw, 2.197rem);
+    --webm-font-size-2xl: clamp(2.074rem, 1.8493rem + 1.1216vw, 2.747rem);
+    --webm-font-size-3xl: clamp(2.488rem, 2.1734rem + 1.5748vw, 3.433rem);
+    --webm-font-size-4xl: clamp(2.986rem, 2.5508rem + 2.1759vw, 4.292rem);
+
+    /* --- leading ----------------------------------------------------------- */
+    --webm-leading-tight: 1.1;
+    --webm-leading-snug: 1.25;
+    --webm-leading-normal: 1.5;
+    --webm-leading-loose: 1.7;
+
+    /* --- tracking ---------------------------------------------------------- */
+    --webm-tracking-tight: -0.02em;
+    --webm-tracking-normal: 0em;
+    --webm-tracking-wide: 0.06em;
+
+    /* --- weight ------------------------------------------------------------ */
+    --webm-weight-regular: 400;
+    --webm-weight-medium: 500;
+    --webm-weight-semibold: 600;
+    --webm-weight-bold: 700;
+
+    /* --- space ------------------------------------------------------------- */
+    --webm-space-3xs: 0.25rem;
+    --webm-space-2xs: 0.5rem;
+    --webm-space-xs: 0.75rem;
+    --webm-space-sm: 1rem;
+    --webm-space-md: 1.5rem;
+    --webm-space-lg: 2rem;
+    --webm-space-xl: 3rem;
+    --webm-space-2xl: 4rem;
+    --webm-space-3xl: 6rem;
+    --webm-space-4xl: 8rem;
+
+    /* --- space, fluid ------------------------------------------------------ */
+    --webm-space-fluid-sm: clamp(1rem, 0.8333rem + 0.8333vw, 1.5rem);
+    --webm-space-fluid-md: clamp(1.5rem, 1.25rem + 1.25vw, 2.25rem);
+    --webm-space-fluid-lg: clamp(2rem, 1.6667rem + 1.6667vw, 3rem);
+    --webm-space-fluid-xl: clamp(3rem, 2.5rem + 2.5vw, 4.5rem);
+    --webm-space-fluid-2xl: clamp(4rem, 3.3333rem + 3.3333vw, 6rem);
+    --webm-space-fluid-3xl: clamp(6rem, 5rem + 5vw, 9rem);
+
+    /* --- section rhythm ---------------------------------------------------- */
+    --webm-section-sm: clamp(2rem, 1.6667rem + 1.6667vw, 3rem);
+    --webm-section-md: clamp(3rem, 2rem + 5vw, 6rem);
+    --webm-section-lg: clamp(4rem, 2.6667rem + 6.6667vw, 8rem);
+    --webm-section-xl: clamp(6rem, 4rem + 10vw, 12rem);
+
+    /* --- gutter ------------------------------------------------------------ */
+    --webm-gutter: clamp(1rem, 0.3333rem + 3.3333vw, 3rem);
+
+    /* --- width ------------------------------------------------------------- */
+    --webm-width-max: 1920px;
+    --webm-width-wide: 1600px;
+    --webm-width-content: 1280px;
+    --webm-width-narrow: 960px;
+    --webm-width-text: 68ch;
+
+    /* --- radius ------------------------------------------------------------ */
+    --webm-radius-none: 0;
+    --webm-radius-xs: 0.125rem;
+    --webm-radius-sm: 0.25rem;
+    --webm-radius-md: 0.5rem;
+    --webm-radius-lg: 1rem;
+    --webm-radius-xl: 1.5rem;
+    --webm-radius-pill: 62.4375rem;
+    --webm-radius-circle: 50%;
+
+    /* --- border-width ------------------------------------------------------ */
+    --webm-border-width-0: 0;
+    --webm-border-width-1: 1px;
+    --webm-border-width-2: 2px;
+    --webm-border-width-4: 4px;
+
+    /* --- shadow ------------------------------------------------------------ */
+    --webm-shadow-xs: 0 1px 2px 0 rgb(34 34 34 / 0.06);
+    --webm-shadow-sm: 0 1px 3px 0 rgb(34 34 34 / 0.1), 0 1px 2px -1px rgb(34 34 34 / 0.1);
+    --webm-shadow-md: 0 4px 6px -1px rgb(34 34 34 / 0.1), 0 2px 4px -2px rgb(34 34 34 / 0.1);
+    --webm-shadow-lg: 0 10px 15px -3px rgb(34 34 34 / 0.1), 0 4px 6px -4px rgb(34 34 34 / 0.1);
+    --webm-shadow-xl: 0 20px 25px -5px rgb(34 34 34 / 0.12), 0 8px 10px -6px rgb(34 34 34 / 0.1);
+
+    /* --- z-index ----------------------------------------------------------- */
+    /* Named layers only. Never write a raw z-index in component CSS. */
+    --webm-z-below: -1;
+    --webm-z-base: 0;
+    --webm-z-raised: 10;
+    --webm-z-sticky: 100;
+    --webm-z-header: 200;
+    --webm-z-drawer: 300;
+    --webm-z-overlay: 400;
+    --webm-z-modal: 500;
+    --webm-z-toast: 600;
+    --webm-z-tooltip: 700;
+    --webm-z-skiplink: 900;
+
+    /* --- duration ---------------------------------------------------------- */
+    --webm-duration-instant: 75ms;
+    --webm-duration-fast: 150ms;
+    --webm-duration-normal: 250ms;
+    --webm-duration-slow: 400ms;
+    --webm-duration-slower: 600ms;
+
+    /* --- easing ------------------------------------------------------------ */
+    --webm-ease-linear: linear;
+    --webm-ease-out: cubic-bezier(0.16, 1, 0.3, 1);
+    --webm-ease-in: cubic-bezier(0.7, 0, 0.84, 0);
+    --webm-ease-in-out: cubic-bezier(0.65, 0, 0.35, 1);
+    --webm-ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
+
+    /* --- scroll reveal ------------------------------------------------------
+     * Defaults for .webm-reveal. Overridable per element with data-reveal-delay
+     * and data-reveal-duration, which observe.ts writes as inline properties. */
+    /*
+     * NOT var(--webm-duration-slow), and not a card-sized distance.
+     *
+     * The motion scale tops out at 400ms, which is tuned for a button, a panel, a dropdown —
+     * something small moving a short way. A reveal is a whole content group arriving, and at
+     * 400ms over 1.5rem it reads as a twitch rather than a movement.
+     *
+     * 7.5rem over 1500ms was arrived at on a real client homepage, not picked. Raising the
+     * duration alone did nothing: --webm-ease-out front-loads the curve, covering most of the
+     * distance in the first third, so extra time only stretches the settle and the element
+     * still appears to arrive at the same moment. Raising distance alone lurched. Both had to
+     * grow together. 5rem at this duration shipped briefly and was pulled — a shorter travel
+     * spends proportionally longer on the settle and reads as drifting into place.
+     *
+     * Reveals therefore get their own duration rather than borrowing from the scale. Reduced
+     * motion is still covered — animations.css forces `transition: none !important` under
+     * `reduce`, so decoupling from the scale's own reduced-motion override costs nothing.
+     */
+    --webm-reveal-duration: 1500ms;
+    --webm-reveal-delay: 0ms;
+    --webm-reveal-distance: 7.5rem;
+    --webm-reveal-ease: var(--webm-ease-out);
+    --webm-reveal-blur: 8px;
+    /* Gap between staggered siblings. The data-delay ladder is multiples of this. */
+    --webm-reveal-stagger-step: 80ms;
+
+    /* --- focus ------------------------------------------------------------- */
+    --webm-focus-width: 3px;
+    --webm-focus-offset: 2px;
+    --webm-focus-color: var(--webm-action);
+
+    /* --- composites -------------------------------------------------------- */
+    --webm-focus-ring: var(--webm-focus-width) solid var(--webm-focus-color);
+  }
+}

package/src/design/brand.ts

@@ -0,0 +1,49 @@
+/*
+ * The brand-context output: what Claude reads when writing for a client.
+ *
+ * This is the thing that makes generated copy look like the client instead of like a chatbot,
+ * and it is why `brand.voice` lives in design.json rather than in a prompt somewhere. A social
+ * post, a report and the site itself all draw from one file.
+ *
+ * Consumed by the platform MCP server, so it must stay serialisable and free of anything that
+ * only makes sense inside a build.
+ */
+import { resolve } from './resolve.ts';
+import { compile } from './compile.ts';
+import type { DesignSystem } from './types.ts';
+
+export interface BrandContext {
+  name?: string;
+  voice?: string;
+  rules: string[];
+  logo?: { primary?: string; mark?: string };
+  /** Resolved literals, keyed without the --webm- prefix. */
+  palette: Record<string, string>;
+  fonts: { sans: string; mono: string };
+}
+
+export function brandContext(design: DesignSystem = {}): BrandContext {
+  const tokens = resolve(compile(design));
+  const get = (n: string) => tokens.get(n) ?? '';
+
+  return {
+    name: design.brand?.name,
+    voice: design.brand?.voice,
+    rules: design.brand?.rules ?? [],
+    logo: design.brand?.logo,
+    palette: {
+      action: get('--webm-action'),
+      actionDark: get('--webm-action-dark'),
+      actionLight: get('--webm-action-light'),
+      surface: get('--webm-surface'),
+      surfaceAlt: get('--webm-surface-alt'),
+      surfaceInverse: get('--webm-surface-inverse'),
+      text: get('--webm-text'),
+      textMuted: get('--webm-text-muted'),
+      textStrong: get('--webm-text-strong'),
+      textInverse: get('--webm-text-inverse'),
+      border: get('--webm-border-subtle'),
+    },
+    fonts: { sans: get('--webm-font-sans'), mono: get('--webm-font-mono') },
+  };
+}

package/src/design/compile.test.ts

@@ -0,0 +1,98 @@
+/*
+ * The load-bearing test is the first one: an empty design.json must reproduce webm-astro
+ * v1.4.1's tokens.css exactly, value for value.
+ *
+ * It reads the real file, checked in as a fixture, rather than a copy of defaults.ts - which
+ * would make it tautological. Edit defaults.ts and this fails until the fixture is updated
+ * deliberately, which is the point. The fixture is frozen history, not a live file.
+ */
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import { compile, toCss, compileToCss, DesignError } from './compile.ts';
+
+const FIXTURE = new URL('./__fixtures__/tokens-v1.4.1.css', import.meta.url);
+
+/** Pull `--webm-x: value;` pairs out of a stylesheet, ignoring comments. */
+function parseTokens(css: string): Map<string, string> {
+  const withoutComments = css.replace(/\/\*[\s\S]*?\*\//g, '');
+  const out = new Map<string, string>();
+  for (const m of withoutComments.matchAll(/(--webm-[\w-]+)\s*:\s*([^;]+);/g)) {
+    out.set(m[1]!, m[2]!.trim());
+  }
+  return out;
+}
+
+const flat = (design = {}) => {
+  const out = new Map<string, string>();
+  for (const g of compile(design)) for (const t of g.tokens) out.set(t.name, t.value);
+  return out;
+};
+
+test('an empty design.json reproduces tokens.css v1.4.1 exactly', () => {
+  const expected = parseTokens(readFileSync(FIXTURE, 'utf8'));
+  const actual = flat();
+
+  assert.equal(actual.size, expected.size, 'token count differs from v1.4.1');
+  for (const [name, value] of expected) {
+    assert.equal(actual.get(name), value, `${name} differs from v1.4.1`);
+  }
+});
+
+test('the compiled stylesheet round-trips through the same parser', () => {
+  const expected = parseTokens(readFileSync(FIXTURE, 'utf8'));
+  const actual = parseTokens(compileToCss());
+  assert.deepEqual([...actual.entries()].sort(), [...expected.entries()].sort());
+});
+
+test('a structured field replaces its token in place', () => {
+  const tokens = flat({ color: { action: { base: '#bfb23b' } } });
+  assert.equal(tokens.get('--webm-action'), '#bfb23b');
+  // Siblings are untouched.
+  assert.equal(tokens.get('--webm-action-dark'), '#003e80');
+});
+
+test('overrides win over a structured field naming the same token', () => {
+  const tokens = flat({
+    color: { action: { base: '#111111' } },
+    overrides: { '--webm-action': '#222222' },
+  });
+  assert.equal(tokens.get('--webm-action'), '#222222');
+});
+
+test('an override outside the --webm- prefix is a build error', () => {
+  assert.throws(
+    () => compile({ overrides: { '--brand-color': 'red' } }),
+    (e: unknown) =>
+      e instanceof DesignError && /must start with --webm-/.test((e as Error).message),
+  );
+});
+
+test('an override naming an unknown token is kept, in its own group', () => {
+  const groups = compile({ overrides: { '--webm-hero-height': '80vh' } });
+  const extra = groups.at(-1)!;
+  assert.equal(extra.title, 'site tokens');
+  assert.deepEqual(extra.tokens, [{ name: '--webm-hero-height', value: '80vh' }]);
+});
+
+test('a non-string value is a build error rather than a silent cast', () => {
+  assert.throws(
+    () => compile({ color: { action: { base: 0x006abe as unknown as string } } }),
+    DesignError,
+  );
+});
+
+test('the layer wrapper is emitted, because membership is what keeps tokens below components', () => {
+  const css = compileToCss();
+  assert.match(css, /^@layer webm\.tokens \{/);
+  assert.match(css, /\n {2}:root \{/);
+  assert.ok(css.trimEnd().endsWith('}'));
+});
+
+test('group order is preserved on emit', () => {
+  const css = toCss(compile());
+  const order = [...css.matchAll(/--- ([a-z0-9, -]+?) -+ \*\//g)].map((m) => m[1]);
+  assert.equal(order[0], 'base palette');
+  assert.equal(order[1], 'action');
+  assert.equal(order.at(-1), 'composites');
+});

package/src/design/compile.ts

@@ -0,0 +1,155 @@
+/*
+ * design.json -> CSS custom properties.
+ *
+ * Pure. No I/O, no Astro, no dependencies - which is why it lives behind the `./design` subpath
+ * and can be tested with `node --test` alone. Rule 1 applies to the framework as much as to a
+ * client site: there is no test framework here either.
+ *
+ * The contract that matters: compiling an EMPTY design.json must reproduce webm-astro v1.4.1's
+ * tokens.css exactly. That equivalence is what makes this a refactor of where values live rather
+ * than a redesign of the token system, and it is asserted in compile.test.ts.
+ */
+import { DEFAULTS, TOKEN_NAMES } from './defaults.ts';
+import type { DesignSystem, TokenGroup } from './types.ts';
+
+/**
+ * Where each design.json field lands, as [path, token name] pairs.
+ *
+ * Declarative on purpose. Adding a field to design.json should be one line here plus one line
+ * in types.ts, not a new branch in the merge.
+ */
+export const MAPPING: ReadonlyArray<readonly [path: readonly string[], token: string]> = [
+  [['color', 'base', '100'], '--webm-base-100'],
+  [['color', 'base', '300'], '--webm-base-300'],
+  [['color', 'base', '500'], '--webm-base-500'],
+  [['color', 'base', '700'], '--webm-base-700'],
+  [['color', 'base', '900'], '--webm-base-900'],
+  [['color', 'action', 'base'], '--webm-action'],
+  [['color', 'action', 'dark'], '--webm-action-dark'],
+  [['color', 'action', 'light'], '--webm-action-light'],
+  [['color', 'border', 'subtle'], '--webm-border-subtle'],
+  [['color', 'state', 'success'], '--webm-state-success'],
+  [['color', 'state', 'warning'], '--webm-state-warning'],
+  [['color', 'state', 'danger'], '--webm-state-danger'],
+  [['color', 'state', 'info'], '--webm-state-info'],
+  [['font', 'sans'], '--webm-font-sans'],
+  [['font', 'mono'], '--webm-font-mono'],
+  [['radius', 'none'], '--webm-radius-none'],
+  [['radius', 'xs'], '--webm-radius-xs'],
+  [['radius', 'sm'], '--webm-radius-sm'],
+  [['radius', 'md'], '--webm-radius-md'],
+  [['radius', 'lg'], '--webm-radius-lg'],
+  [['radius', 'xl'], '--webm-radius-xl'],
+  [['radius', 'pill'], '--webm-radius-pill'],
+  [['radius', 'circle'], '--webm-radius-circle'],
+];
+
+function at(source: unknown, path: readonly string[]): unknown {
+  let node: unknown = source;
+  for (const key of path) {
+    if (node === null || typeof node !== 'object') return undefined;
+    node = (node as Record<string, unknown>)[key];
+  }
+  return node;
+}
+
+export class DesignError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'DesignError';
+  }
+}
+
+/**
+ * Merge a design.json over the defaults, returning the full grouped token set.
+ *
+ * Overrides that name a token already in a group REPLACE it in place, so the compiled file keeps
+ * its grouping rather than growing an "overrides" tail that separates a value from its siblings.
+ * An override naming a token that does not exist is appended to its own group - legitimate, since
+ * a client may add a token their own components read.
+ */
+export function compile(design: DesignSystem = {}): TokenGroup[] {
+  const patch = new Map<string, string>();
+
+  for (const [path, token] of MAPPING) {
+    const value = at(design, path);
+    if (value === undefined || value === null) continue;
+    if (typeof value !== 'string') {
+      throw new DesignError(`design.json: ${path.join('.')} must be a string, got ${typeof value}`);
+    }
+    patch.set(token, value);
+  }
+
+  /*
+   * Overrides are applied after the mapping, so `overrides` wins over a structured field naming
+   * the same token. That ordering is deliberate: the escape hatch is the more specific statement.
+   */
+  const extra: string[] = [];
+  for (const [name, value] of Object.entries(design.overrides ?? {})) {
+    if (!name.startsWith('--webm-')) {
+      throw new DesignError(
+        `design.json: override "${name}" must start with --webm-. ` +
+          `A property outside the prefix is set but never read, and the page looks untouched.`,
+      );
+    }
+    if (typeof value !== 'string') {
+      throw new DesignError(`design.json: override "${name}" must be a string`);
+    }
+    patch.set(name, value);
+    if (!TOKEN_NAMES.has(name)) extra.push(name);
+  }
+
+  const groups: TokenGroup[] = DEFAULTS.map((group) => ({
+    ...group,
+    tokens: group.tokens.map((t) => (patch.has(t.name) ? { ...t, value: patch.get(t.name)! } : t)),
+  }));
+
+  if (extra.length) {
+    groups.push({
+      title: 'site tokens',
+      note: 'Declared in design.json overrides and not part of the default set.',
+      tokens: extra.map((name) => ({ name, value: patch.get(name)! })),
+    });
+  }
+
+  return groups;
+}
+
+/** Wrap a note as a CSS comment, indented to sit inside :root. */
+function comment(text: string, indent: string): string {
+  const lines = text.split('\n');
+  if (lines.length === 1) return `${indent}/* ${text} */`;
+  return [
+    `${indent}/*`,
+    ...lines.map((l) => (l ? `${indent} * ${l}` : `${indent} *`)),
+    `${indent} */`,
+  ].join('\n');
+}
+
+/**
+ * Emit the compiled token set as a stylesheet.
+ *
+ * The `@layer webm.tokens` wrapper is REQUIRED, not cosmetic. Layer membership is what keeps
+ * these declarations below components in the cascade; a bare :root block would out-rank a
+ * component rule at equal specificity. Layer ORDER is a separate problem and is held by the
+ * inline statement in base.astro - see the layer-order trap.
+ */
+export function toCss(groups: TokenGroup[]): string {
+  const out: string[] = ['@layer webm.tokens {', '  :root {'];
+
+  groups.forEach((group, i) => {
+    if (i > 0) out.push('');
+    const rule = `/* --- ${group.title} ${'-'.repeat(Math.max(1, 68 - group.title.length))} */`;
+    out.push(`    ${rule}`);
+    if (group.note) out.push(comment(group.note, '    '));
+    for (const t of group.tokens) out.push(`    ${t.name}: ${t.value};`);
+  });
+
+  out.push('  }', '}', '');
+  return out.join('\n');
+}
+
+/** design.json in, stylesheet out. The whole compiler, for callers that want one call. */
+export function compileToCss(design: DesignSystem = {}): string {
+  return toCss(compile(design));
+}