@cparkerwebm/webmonterey 1.0.0

package/src/design/defaults.ts

@@ -0,0 +1,315 @@
+/*
+ * THE DESIGN SYSTEM'S DEFAULT TOKEN SET.
+ *
+ * Ported verbatim from webm-astro v1.4.1 src/styles/tokens.css, which is the reference the
+ * compiler is checked against: compiling an empty design.json must produce the same values that
+ * file declared. That equivalence is what makes the move from a hand-edited stylesheet to
+ * generated CSS a refactor rather than a redesign.
+ *
+ * Groups exist so compiled output stays readable. Order is preserved on emit.
+ *
+ * WHAT BELONGS HERE vs in design.json: anything a client would sensibly change is exposed in
+ * design.json and merged over these. Everything else - spacing, widths, z-index, durations,
+ * easings, shadows - is the system. A client wanting a different spacing scale is nearly always
+ * a client who wants a different value in one component.
+ */
+import type { TokenGroup } from './types.ts';
+
+export const DEFAULTS: TokenGroup[] = [
+  {
+    title: 'base palette',
+    note: 'Raw neutrals. Everything semantic below points at these, not the other way round.',
+    tokens: [
+      { name: '--webm-base-100', value: '#ffffff' },
+      { name: '--webm-base-300', value: '#f1eae8' },
+      { name: '--webm-base-500', value: '#3f3f3f' },
+      { name: '--webm-base-700', value: '#222222' },
+      { name: '--webm-base-900', value: '#000000' },
+    ],
+  },
+  {
+    title: 'action',
+    note: 'The brand color. Retheming a client usually starts and ends here.',
+    tokens: [
+      { name: '--webm-action', value: '#006abe' },
+      { name: '--webm-action-dark', value: '#003e80' },
+      { name: '--webm-action-light', value: '#6bc7ff' },
+    ],
+  },
+  {
+    title: 'surface',
+    tokens: [
+      { name: '--webm-surface', value: 'var(--webm-base-100)' },
+      { name: '--webm-surface-alt', value: 'var(--webm-base-300)' },
+      { name: '--webm-surface-accent', value: 'var(--webm-action-light)' },
+      { name: '--webm-surface-inverse', value: 'var(--webm-base-900)' },
+      { name: '--webm-surface-raised', value: 'var(--webm-base-100)' },
+    ],
+  },
+  {
+    title: 'text',
+    tokens: [
+      { name: '--webm-text', value: 'var(--webm-base-700)' },
+      { name: '--webm-text-muted', value: 'var(--webm-base-500)' },
+      { name: '--webm-text-strong', value: 'var(--webm-base-900)' },
+      { name: '--webm-text-inverse', value: 'var(--webm-base-100)' },
+      { name: '--webm-text-on-action', value: 'var(--webm-base-100)' },
+    ],
+  },
+  {
+    title: 'link',
+    tokens: [
+      { name: '--webm-link', value: 'var(--webm-action)' },
+      { name: '--webm-link-hover', value: 'var(--webm-action-dark)' },
+      { name: '--webm-link-visited', value: 'var(--webm-action-dark)' },
+    ],
+  },
+  {
+    title: 'border',
+    tokens: [
+      { name: '--webm-border-subtle', value: '#dcd3d0' },
+      { name: '--webm-border-interactive', value: 'var(--webm-base-500)' },
+      { name: '--webm-border-strong', value: 'var(--webm-base-700)' },
+    ],
+  },
+  {
+    title: 'state',
+    tokens: [
+      { name: '--webm-state-success', value: '#0f7b3f' },
+      { name: '--webm-state-warning', value: '#9a6700' },
+      { name: '--webm-state-danger', value: '#b3261e' },
+      { name: '--webm-state-info', value: 'var(--webm-action)' },
+    ],
+  },
+  {
+    title: 'font',
+    note: [
+      '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 set font.sans in design.json.',
+    ].join('\n'),
+    tokens: [
+      {
+        name: '--webm-font-sans',
+        value: "system-ui, -apple-system, 'Segoe UI', Roboto, Helvetica, Arial, sans-serif",
+      },
+      {
+        name: '--webm-font-mono',
+        value: 'ui-monospace, SFMono-Regular, Menlo, Consolas, monospace',
+      },
+    ],
+  },
+  {
+    title: 'font-size',
+    note: 'Fluid scale. Each step interpolates between a mobile and a desktop size.',
+    tokens: [
+      { name: '--webm-font-size-2xs', value: 'clamp(0.6944rem, 0.6859rem + 0.0426vw, 0.72rem)' },
+      { name: '--webm-font-size-xs', value: 'clamp(0.8333rem, 0.8111rem + 0.1111vw, 0.9rem)' },
+      { name: '--webm-font-size-sm', value: 'clamp(1rem, 0.9583rem + 0.2083vw, 1.125rem)' },
+      { name: '--webm-font-size-md', value: 'clamp(1.2rem, 1.1312rem + 0.3438vw, 1.406rem)' },
+      { name: '--webm-font-size-lg', value: 'clamp(1.44rem, 1.3341rem + 0.5297vw, 1.758rem)' },
+      { name: '--webm-font-size-xl', value: 'clamp(1.728rem, 1.5716rem + 0.7821vw, 2.197rem)' },
+      { name: '--webm-font-size-2xl', value: 'clamp(2.074rem, 1.8493rem + 1.1216vw, 2.747rem)' },
+      { name: '--webm-font-size-3xl', value: 'clamp(2.488rem, 2.1734rem + 1.5748vw, 3.433rem)' },
+      { name: '--webm-font-size-4xl', value: 'clamp(2.986rem, 2.5508rem + 2.1759vw, 4.292rem)' },
+    ],
+  },
+  {
+    title: 'leading',
+    tokens: [
+      { name: '--webm-leading-tight', value: '1.1' },
+      { name: '--webm-leading-snug', value: '1.25' },
+      { name: '--webm-leading-normal', value: '1.5' },
+      { name: '--webm-leading-loose', value: '1.7' },
+    ],
+  },
+  {
+    title: 'tracking',
+    tokens: [
+      { name: '--webm-tracking-tight', value: '-0.02em' },
+      { name: '--webm-tracking-normal', value: '0em' },
+      { name: '--webm-tracking-wide', value: '0.06em' },
+    ],
+  },
+  {
+    title: 'weight',
+    tokens: [
+      { name: '--webm-weight-regular', value: '400' },
+      { name: '--webm-weight-medium', value: '500' },
+      { name: '--webm-weight-semibold', value: '600' },
+      { name: '--webm-weight-bold', value: '700' },
+    ],
+  },
+  {
+    title: 'space',
+    tokens: [
+      { name: '--webm-space-3xs', value: '0.25rem' },
+      { name: '--webm-space-2xs', value: '0.5rem' },
+      { name: '--webm-space-xs', value: '0.75rem' },
+      { name: '--webm-space-sm', value: '1rem' },
+      { name: '--webm-space-md', value: '1.5rem' },
+      { name: '--webm-space-lg', value: '2rem' },
+      { name: '--webm-space-xl', value: '3rem' },
+      { name: '--webm-space-2xl', value: '4rem' },
+      { name: '--webm-space-3xl', value: '6rem' },
+      { name: '--webm-space-4xl', value: '8rem' },
+    ],
+  },
+  {
+    title: 'space, fluid',
+    tokens: [
+      { name: '--webm-space-fluid-sm', value: 'clamp(1rem, 0.8333rem + 0.8333vw, 1.5rem)' },
+      { name: '--webm-space-fluid-md', value: 'clamp(1.5rem, 1.25rem + 1.25vw, 2.25rem)' },
+      { name: '--webm-space-fluid-lg', value: 'clamp(2rem, 1.6667rem + 1.6667vw, 3rem)' },
+      { name: '--webm-space-fluid-xl', value: 'clamp(3rem, 2.5rem + 2.5vw, 4.5rem)' },
+      { name: '--webm-space-fluid-2xl', value: 'clamp(4rem, 3.3333rem + 3.3333vw, 6rem)' },
+      { name: '--webm-space-fluid-3xl', value: 'clamp(6rem, 5rem + 5vw, 9rem)' },
+    ],
+  },
+  {
+    title: 'section rhythm',
+    tokens: [
+      { name: '--webm-section-sm', value: 'clamp(2rem, 1.6667rem + 1.6667vw, 3rem)' },
+      { name: '--webm-section-md', value: 'clamp(3rem, 2rem + 5vw, 6rem)' },
+      { name: '--webm-section-lg', value: 'clamp(4rem, 2.6667rem + 6.6667vw, 8rem)' },
+      { name: '--webm-section-xl', value: 'clamp(6rem, 4rem + 10vw, 12rem)' },
+    ],
+  },
+  {
+    title: 'gutter',
+    tokens: [{ name: '--webm-gutter', value: 'clamp(1rem, 0.3333rem + 3.3333vw, 3rem)' }],
+  },
+  {
+    title: 'width',
+    tokens: [
+      { name: '--webm-width-max', value: '1920px' },
+      { name: '--webm-width-wide', value: '1600px' },
+      { name: '--webm-width-content', value: '1280px' },
+      { name: '--webm-width-narrow', value: '960px' },
+      { name: '--webm-width-text', value: '68ch' },
+    ],
+  },
+  {
+    title: 'radius',
+    tokens: [
+      { name: '--webm-radius-none', value: '0' },
+      { name: '--webm-radius-xs', value: '0.125rem' },
+      { name: '--webm-radius-sm', value: '0.25rem' },
+      { name: '--webm-radius-md', value: '0.5rem' },
+      { name: '--webm-radius-lg', value: '1rem' },
+      { name: '--webm-radius-xl', value: '1.5rem' },
+      { name: '--webm-radius-pill', value: '62.4375rem' },
+      { name: '--webm-radius-circle', value: '50%' },
+    ],
+  },
+  {
+    title: 'border-width',
+    tokens: [
+      { name: '--webm-border-width-0', value: '0' },
+      { name: '--webm-border-width-1', value: '1px' },
+      { name: '--webm-border-width-2', value: '2px' },
+      { name: '--webm-border-width-4', value: '4px' },
+    ],
+  },
+  {
+    title: 'shadow',
+    tokens: [
+      { name: '--webm-shadow-xs', value: '0 1px 2px 0 rgb(34 34 34 / 0.06)' },
+      {
+        name: '--webm-shadow-sm',
+        value: '0 1px 3px 0 rgb(34 34 34 / 0.1), 0 1px 2px -1px rgb(34 34 34 / 0.1)',
+      },
+      {
+        name: '--webm-shadow-md',
+        value: '0 4px 6px -1px rgb(34 34 34 / 0.1), 0 2px 4px -2px rgb(34 34 34 / 0.1)',
+      },
+      {
+        name: '--webm-shadow-lg',
+        value: '0 10px 15px -3px rgb(34 34 34 / 0.1), 0 4px 6px -4px rgb(34 34 34 / 0.1)',
+      },
+      {
+        name: '--webm-shadow-xl',
+        value: '0 20px 25px -5px rgb(34 34 34 / 0.12), 0 8px 10px -6px rgb(34 34 34 / 0.1)',
+      },
+    ],
+  },
+  {
+    title: 'z-index',
+    note: 'Named layers only. Never write a raw z-index in component CSS.',
+    tokens: [
+      { name: '--webm-z-below', value: '-1' },
+      { name: '--webm-z-base', value: '0' },
+      { name: '--webm-z-raised', value: '10' },
+      { name: '--webm-z-sticky', value: '100' },
+      { name: '--webm-z-header', value: '200' },
+      { name: '--webm-z-drawer', value: '300' },
+      { name: '--webm-z-overlay', value: '400' },
+      { name: '--webm-z-modal', value: '500' },
+      { name: '--webm-z-toast', value: '600' },
+      { name: '--webm-z-tooltip', value: '700' },
+      { name: '--webm-z-skiplink', value: '900' },
+    ],
+  },
+  {
+    title: 'duration',
+    tokens: [
+      { name: '--webm-duration-instant', value: '75ms' },
+      { name: '--webm-duration-fast', value: '150ms' },
+      { name: '--webm-duration-normal', value: '250ms' },
+      { name: '--webm-duration-slow', value: '400ms' },
+      { name: '--webm-duration-slower', value: '600ms' },
+    ],
+  },
+  {
+    title: 'easing',
+    tokens: [
+      { name: '--webm-ease-linear', value: 'linear' },
+      { name: '--webm-ease-out', value: 'cubic-bezier(0.16, 1, 0.3, 1)' },
+      { name: '--webm-ease-in', value: 'cubic-bezier(0.7, 0, 0.84, 0)' },
+      { name: '--webm-ease-in-out', value: 'cubic-bezier(0.65, 0, 0.35, 1)' },
+      { name: '--webm-ease-spring', value: 'cubic-bezier(0.34, 1.56, 0.64, 1)' },
+    ],
+  },
+  {
+    title: 'scroll reveal',
+    note: [
+      '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, tuned for a button or 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.',
+      '',
+      '7.5rem over 1500ms was arrived at on a real client homepage, not picked. Raising duration',
+      'alone did nothing: --webm-ease-out front-loads the curve, so extra time only stretches the',
+      'settle. Raising distance alone lurched. Both had to grow together.',
+    ].join('\n'),
+    tokens: [
+      { name: '--webm-reveal-duration', value: '1500ms' },
+      { name: '--webm-reveal-delay', value: '0ms' },
+      { name: '--webm-reveal-distance', value: '7.5rem' },
+      { name: '--webm-reveal-ease', value: 'var(--webm-ease-out)' },
+      { name: '--webm-reveal-blur', value: '8px' },
+      { name: '--webm-reveal-stagger-step', value: '80ms' },
+    ],
+  },
+  {
+    title: 'focus',
+    tokens: [
+      { name: '--webm-focus-width', value: '3px' },
+      { name: '--webm-focus-offset', value: '2px' },
+      { name: '--webm-focus-color', value: 'var(--webm-action)' },
+    ],
+  },
+  {
+    title: 'composites',
+    tokens: [
+      { name: '--webm-focus-ring', value: 'var(--webm-focus-width) solid var(--webm-focus-color)' },
+    ],
+  },
+];
+
+/** Every default token name, for validation and for `webm doctor`. */
+export const TOKEN_NAMES: ReadonlySet<string> = new Set(
+  DEFAULTS.flatMap((g) => g.tokens.map((t) => t.name)),
+);

package/src/design/index.ts

@@ -0,0 +1,18 @@
+/*
+ * @cparkerwebm/webmonterey/design
+ *
+ * One input, four outputs. design.json compiles to:
+ *
+ *   CSS custom properties  -> the website and web app, via a Vite virtual module
+ *   email-safe literals    -> transactional mail, where var() does not exist
+ *   brand context          -> Cowork and the platform MCP server
+ *   resolved palette       -> social graphics and client reports
+ *
+ * No Astro imports anywhere under this subpath. That is what keeps it testable with
+ * `node --test` and usable from the platform without pulling a framework in to read a color.
+ */
+export { DEFAULTS, TOKEN_NAMES } from './defaults.ts';
+export { compile, toCss, compileToCss, DesignError } from './compile.ts';
+export { resolve, emailPalette, ResolveError } from './resolve.ts';
+export { brandContext } from './brand.ts';
+export type { DesignSystem, Token, TokenGroup, Color } from './types.ts';

package/src/design/resolve.test.ts

@@ -0,0 +1,80 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { compile } from './compile.ts';
+import { resolve, emailPalette, ResolveError } from './resolve.ts';
+import { brandContext } from './brand.ts';
+import type { TokenGroup } from './types.ts';
+
+const group = (tokens: Record<string, string>): TokenGroup[] => [
+  { title: 'test', tokens: Object.entries(tokens).map(([name, value]) => ({ name, value })) },
+];
+
+test('a var() chain resolves to a literal', () => {
+  const out = resolve(
+    group({
+      '--webm-a': '#123456',
+      '--webm-b': 'var(--webm-a)',
+      '--webm-c': 'var(--webm-b)',
+    }),
+  );
+  assert.equal(out.get('--webm-c'), '#123456');
+});
+
+test('the default set resolves with no var() left anywhere', () => {
+  for (const [name, value] of resolve(compile())) {
+    assert.ok(!value.includes('var('), `${name} still contains var(): ${value}`);
+  }
+});
+
+test('a composite with several references resolves all of them', () => {
+  const out = resolve(compile());
+  assert.equal(out.get('--webm-focus-ring'), '3px solid #006abe');
+});
+
+test('a circular reference throws rather than looping', () => {
+  assert.throws(
+    () => resolve(group({ '--webm-a': 'var(--webm-b)', '--webm-b': 'var(--webm-a)' })),
+    (e: unknown) => e instanceof ResolveError && /Circular/.test((e as Error).message),
+  );
+});
+
+test('an undefined reference with a fallback uses the fallback', () => {
+  const out = resolve(group({ '--webm-a': 'var(--webm-missing, 1rem)' }));
+  assert.equal(out.get('--webm-a'), '1rem');
+});
+
+test('an undefined reference without a fallback throws, rather than emitting empty', () => {
+  assert.throws(() => resolve(group({ '--webm-a': 'var(--webm-missing)' })), ResolveError);
+});
+
+test('the email palette is literals only, keyed without the prefix', () => {
+  const palette = emailPalette(compile({ color: { action: { base: '#bfb23b' } } }));
+  assert.equal(palette.action, '#bfb23b');
+  assert.equal(palette.link, '#bfb23b', 'link points at action and must arrive resolved');
+  for (const [k, v] of Object.entries(palette)) {
+    assert.ok(!k.startsWith('--'), `${k} kept its prefix`);
+    assert.ok(!v.includes('var('), `${k} still contains var()`);
+  }
+});
+
+test('the email palette omits fluid sizes no mail client understands', () => {
+  for (const v of Object.values(emailPalette(compile()))) {
+    assert.ok(!v.includes('clamp('), `a clamp() reached the email palette: ${v}`);
+  }
+});
+
+test('brand context carries voice and rules alongside a resolved palette', () => {
+  const ctx = brandContext({
+    brand: { name: 'Autire', voice: 'Direct.', rules: ['Gold is a fill only.'] },
+    color: { action: { base: '#bfb23b' } },
+    overrides: { '--webm-text-on-action': 'var(--webm-base-700)' },
+  });
+  assert.equal(ctx.name, 'Autire');
+  assert.deepEqual(ctx.rules, ['Gold is a fill only.']);
+  assert.equal(ctx.palette.action, '#bfb23b');
+  assert.ok(!JSON.stringify(ctx).includes('var('), 'brand context must be fully resolved');
+});
+
+test('brand context defaults rules to an empty array, never undefined', () => {
+  assert.deepEqual(brandContext().rules, []);
+});

package/src/design/resolve.ts

@@ -0,0 +1,108 @@
+/*
+ * Flatten var() chains to literal values.
+ *
+ * This is the email output. Email HTML has no cascade, no classes and no custom properties -
+ * Outlook has enforced that for fifteen years - so every style must be inlined as a literal.
+ * `--webm-link: var(--webm-action)` is useless in a mail client; `#006abe` is not.
+ *
+ * Also the "resolved palette" used for social graphics and reports, where a renderer wants a
+ * color rather than a reference.
+ */
+import type { TokenGroup } from './types.ts';
+
+export class ResolveError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ResolveError';
+  }
+}
+
+/** Matches one var() call, capturing the name and an optional fallback. */
+const VAR = /var\(\s*(--[\w-]+)\s*(?:,\s*([^()]*(?:\([^()]*\)[^()]*)*))?\)/;
+
+/**
+ * Resolve every token to a literal, following var() references.
+ *
+ * A reference to an undefined token resolves to its fallback if one is written, and throws
+ * otherwise - a silently-empty value in an email is worse than a failed build, because nobody
+ * sees it until a client forwards the mail asking why it looks broken.
+ */
+export function resolve(groups: TokenGroup[]): Map<string, string> {
+  const raw = new Map<string, string>();
+  for (const g of groups) for (const t of g.tokens) raw.set(t.name, t.value);
+
+  const done = new Map<string, string>();
+
+  const expand = (name: string, seen: string[]): string => {
+    const cached = done.get(name);
+    if (cached !== undefined) return cached;
+
+    if (seen.includes(name)) {
+      throw new ResolveError(`Circular token reference: ${[...seen, name].join(' -> ')}`);
+    }
+    const value = raw.get(name);
+    if (value === undefined) {
+      throw new ResolveError(`Token ${name} is referenced but never defined`);
+    }
+
+    let out = value;
+    for (let guard = 0; guard < 50; guard++) {
+      const m = VAR.exec(out);
+      if (!m) break;
+      const [whole, ref, fallback] = m;
+      let replacement: string;
+      if (raw.has(ref!)) {
+        replacement = expand(ref!, [...seen, name]);
+      } else if (fallback !== undefined) {
+        replacement = fallback.trim();
+      } else {
+        throw new ResolveError(
+          `Token ${name} references ${ref}, which is not defined and has no fallback`,
+        );
+      }
+      out = out.slice(0, m.index) + replacement + out.slice(m.index + whole!.length);
+    }
+
+    done.set(name, out);
+    return out;
+  };
+
+  for (const name of raw.keys()) expand(name, []);
+  return done;
+}
+
+/**
+ * The subset an email template actually reaches for, resolved flat.
+ *
+ * Deliberately narrow. An email primitive needs colors, a font stack and a couple of sizes -
+ * handing it 124 tokens invites someone to inline a fluid clamp() into a table cell, which no
+ * mail client understands.
+ */
+export function emailPalette(groups: TokenGroup[]): Record<string, string> {
+  const all = resolve(groups);
+  const want = [
+    '--webm-surface',
+    '--webm-surface-alt',
+    '--webm-surface-inverse',
+    '--webm-text',
+    '--webm-text-muted',
+    '--webm-text-strong',
+    '--webm-text-inverse',
+    '--webm-text-on-action',
+    '--webm-action',
+    '--webm-action-dark',
+    '--webm-link',
+    '--webm-border-subtle',
+    '--webm-font-sans',
+    '--webm-radius-md',
+    '--webm-space-sm',
+    '--webm-space-md',
+    '--webm-space-lg',
+  ];
+  const out: Record<string, string> = {};
+  for (const name of want) {
+    const value = all.get(name);
+    if (value !== undefined) out[name.replace('--webm-', '')] = value;
+  }
+  return out;
+}

package/src/design/types.ts

@@ -0,0 +1,96 @@
+/*
+ * The shape of design.json.
+ *
+ * DELIBERATELY SMALL. tokens.css in generation 2 was ~150 custom properties, but only about
+ * fifteen of them ever changed between clients: the neutral ramp, the action color, borders,
+ * state colors and the two font stacks. Everything else - spacing, widths, z-index, durations,
+ * easings, shadows - is the design SYSTEM, not the brand, and a client who edits them is
+ * usually making a mistake.
+ *
+ * So design.json carries what varies and the compiler emits the rest from defaults. A client
+ * file is ~30 lines rather than ~200, and the diff between two clients is legible.
+ *
+ * `overrides` is the escape hatch for the remainder: any --webm-* property, set raw. Reach for
+ * it when the token system genuinely does not express what a client needs, not to avoid
+ * learning where a value lives.
+ */
+
+/** A CSS color, in any notation CSS accepts. Not validated beyond being a string. */
+export type Color = string;
+
+export interface DesignSystem {
+  /** Ignored by the compiler; present so editors can offer completion. */
+  $schema?: string;
+
+  /** Bumped only for a breaking change to this shape. */
+  version?: 1;
+
+  /**
+   * The words half of the design system, and the half that travels furthest: site copy,
+   * social posts, and anything written in the client's name.
+   *
+   * Not consumed by the CSS compiler. Served to the platform and to Cowork as brand context.
+   */
+  brand?: {
+    /** Display name. Falls back to `client` in webmonterey.json. */
+    name?: string;
+    /** How this client writes. One or two sentences, concrete. */
+    voice?: string;
+    /**
+     * Hard rules a writer or a generator must not break. Phrase each as an instruction.
+     * e.g. "Gold is a fill only - never gold text or links on white."
+     */
+    rules?: string[];
+    logo?: {
+      /** Full lockup. Repo-relative or absolute. */
+      primary?: string;
+      /** Icon-only mark, for favicons and tight spaces. */
+      mark?: string;
+    };
+  };
+
+  color?: {
+    /**
+     * The neutral ramp. Everything semantic points at these, never the other way round.
+     * 100 is lightest, 900 darkest - the direction does not invert for a dark design.
+     */
+    base?: Partial<Record<'100' | '300' | '500' | '700' | '900', Color>>;
+    /** The brand color. Retheming a client usually starts and ends here. */
+    action?: { base?: Color; dark?: Color; light?: Color };
+    border?: { subtle?: Color };
+    state?: Partial<Record<'success' | 'warning' | 'danger' | 'info', Color>>;
+  };
+
+  font?: {
+    /**
+     * Full CSS font stacks, not family names - the compiler does not append fallbacks.
+     * A self-hosted face still needs its @font-face declared in src/styles/custom/.
+     */
+    sans?: string;
+    mono?: string;
+  };
+
+  /** Partial: name only the steps that differ from the defaults. */
+  radius?: Partial<Record<'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'pill' | 'circle', string>>;
+
+  /**
+   * Raw token overrides, applied last and unvalidated beyond the name prefix.
+   * Keys must start with `--webm-`; anything else is a build error, because a typo here is
+   * otherwise silent - the property is set, nothing reads it, and the page looks untouched.
+   */
+  overrides?: Record<string, string>;
+}
+
+/** One emitted custom property. */
+export interface Token {
+  name: string;
+  value: string;
+}
+
+/** A titled run of tokens. Groups exist to keep compiled CSS readable, nothing more. */
+export interface TokenGroup {
+  title: string;
+  /** Emitted as a comment above the group. Omit for self-evident groups. */
+  note?: string;
+  tokens: Token[];
+}