@astryxdesign/core 0.4.2 → 0.4.3-canary.00bed29

package/src/theme/expandColorScale.ts

@@ -6,8 +6,8 @@
  * @output Token overrides for derivable color tokens
  * @position Theme utility; consumed by defineTheme.ts
  *
- * Generates color token overrides from a single accent color using the
- * HCT perceptual color model. Only produces tokens that meaningfully
+ * Generates color token overrides from an accent seed using the HCT
+ * perceptual color model. Only produces tokens that meaningfully
  * derive from the accent — status colors, categorical hues, and fixed
  * tokens (on-dark/on-light) fall through to colorDefaults.
  *
@@ -15,11 +15,19 @@
  * ramp (seeded from the default accent's hue) while the accent tokens
  * themselves fall through to colorDefaults, same as the tokens above.
  *
+ * `accent` also accepts a `[light, dark]` tuple (matching `TokenValue` in
+ * defineTheme). A tuple seeds each color scheme from its own half: the
+ * light side of every generated `light-dark()` pair derives from the light
+ * accent's palettes, the dark side from the dark accent's. A plain string
+ * seeds both sides identically, token for token the same output as before
+ * tuples existed.
+ *
  * WCAG contrast guarantees (asserted in expandColorScale.test.ts):
  * - Text tones are guaranteed >= 4.5:1 against their surfaces by tone
  *   spacing alone — HCT tone is CIE L*, which fixes relative luminance
  *   regardless of hue/chroma, so the fixed tone assignments hold for any
- *   accent/neutralStyle (WCAG 1.4.3).
+ *   accent/neutralStyle (WCAG 1.4.3), and each half of a tuple pairs with
+ *   surfaces derived from that same seed.
  * - --color-border-emphasized (form-control boundaries) is tone-bumped
  *   until it reaches >= 3:1 against the generated surface (WCAG 1.4.11).
  * - --color-border, --color-skeleton, and --color-track are intentionally
@@ -46,6 +54,9 @@ import {hexToHct, hctToHex, tonalPalette, hexWithAlpha} from './hct';
  * // Minimal — just a seed color
  * { accent: '#0064E0' }
  *
+ * // Per-scheme seeds: light palettes from '#0064E0', dark from '#48CAE4'
+ * { accent: ['#0064E0', '#48CAE4'] }
+ *
  * // With customization
  * { accent: '#B7410E', neutralStyle: 'warm', contrast: 'high' }
  *
@@ -55,14 +66,18 @@ import {hexToHct, hctToHex, tonalPalette, hexWithAlpha} from './hct';
  */
 export interface ColorScaleConfig {
   /**
-   * Seed accent color as hex (#RRGGBB). Everything derives from this.
+   * Seed accent color. Everything derives from this.
+   *
+   * Either a single hex (#RRGGBB) used for both color schemes, or a
+   * `[light, dark]` hex tuple: the light scheme's palettes derive from
+   * the light seed and the dark scheme's palettes from the dark seed.
    *
    * Optional. When omitted, the neutral palettes are seeded from the
    * default accent's hue and the accent tokens (--color-accent,
    * --color-accent-muted, --color-on-accent) are not generated — they
    * fall through to colorDefaults.
    */
-  accent?: string;
+  accent?: string | [light: string, dark: string];
 
   /**
    * Neutral tone warmth. Controls how much of the seed's hue bleeds
@@ -159,6 +174,11 @@ export function ensureContrastTone(
  * --color-on-dark/on-light) are NOT generated — they fall through
  * to colorDefaults.
  *
+ * A `[light, dark]` tuple accent seeds each scheme separately: the light
+ * half of every generated `light-dark()` pair comes from the light seed's
+ * palettes, the dark half from the dark seed's. A string accent seeds both
+ * halves from the same palettes, exactly as before tuples were supported.
+ *
  * Without an `accent`, the accent tokens join that fall-through set: the
  * neutrals are seeded from the default accent's hue, and --color-accent,
  * --color-accent-muted and --color-on-accent keep their colorDefaults values.
@@ -168,6 +188,9 @@ export function ensureContrastTone(
  * const tokens = expandColorScale({ accent: '#0064E0' });
  * // tokens['--color-accent'] === 'light-dark(#..., #...)'
  *
+ * const perScheme = expandColorScale({ accent: ['#0064E0', '#48CAE4'] });
+ * // light half derives from #0064E0, dark half from #48CAE4
+ *
  * const neutralOnly = expandColorScale({ neutralStyle: 'warm' });
  * // neutralOnly['--color-accent'] === undefined
  * ```
@@ -175,16 +198,33 @@ export function ensureContrastTone(
 export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const {accent, neutralStyle = 'cool', contrast = 'standard'} = config;
 
-  const seed = hexToHct(accent ?? DEFAULT_ACCENT_SEED);
-  const seedHue = seed.hue;
+  // Normalize to per-scheme seeds. A string accent (or an absent one) uses
+  // the same seed for both halves, which keeps single-seed output identical
+  // to the pre-tuple implementation.
+  const [lightAccent, darkAccent] = Array.isArray(accent)
+    ? accent
+    : [accent, accent];
+
+  const lightSeed = hexToHct(lightAccent ?? DEFAULT_ACCENT_SEED);
+  const sameSeed = darkAccent === lightAccent;
+  const darkSeed = sameSeed
+    ? lightSeed
+    : hexToHct(darkAccent ?? DEFAULT_ACCENT_SEED);
 
-  const primaryChroma = Math.max(seed.chroma, 48);
   const neutralChroma = NEUTRAL_CHROMA[neutralStyle] ?? 5;
   const neutralVariantChroma = NEUTRAL_VARIANT_CHROMA[neutralStyle] ?? 8;
 
-  const P = tonalPalette(seedHue, primaryChroma);
-  const N = tonalPalette(seedHue, neutralChroma);
-  const NV = tonalPalette(seedHue, neutralVariantChroma);
+  // Palette naming: *L palettes feed the light (first) half of each ld()
+  // pair below, *D palettes the dark (second) half. With a single seed the
+  // D palettes alias the L ones.
+  const PL = tonalPalette(lightSeed.hue, Math.max(lightSeed.chroma, 48));
+  const NL = tonalPalette(lightSeed.hue, neutralChroma);
+  const NVL = tonalPalette(lightSeed.hue, neutralVariantChroma);
+  const PD = sameSeed
+    ? PL
+    : tonalPalette(darkSeed.hue, Math.max(darkSeed.chroma, 48));
+  const ND = sameSeed ? NL : tonalPalette(darkSeed.hue, neutralChroma);
+  const NVD = sameSeed ? NVL : tonalPalette(darkSeed.hue, neutralVariantChroma);
 
   const isHigh = contrast === 'high';
 
@@ -209,19 +249,19 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
   const borderEmphasizedStartDark = isHigh ? 50 : 30;
   const borderEmphasized = ld(
     ensureContrastTone(
-      seedHue,
+      lightSeed.hue,
       neutralVariantChroma,
       borderEmphasizedStartLight,
       -1,
-      N[99],
+      NL[99],
       NON_TEXT_MIN_CONTRAST,
     ),
     ensureContrastTone(
-      seedHue,
+      darkSeed.hue,
       neutralVariantChroma,
       borderEmphasizedStartDark,
       1,
-      N[10],
+      ND[10],
       NON_TEXT_MIN_CONTRAST,
     ),
   );
@@ -234,7 +274,7 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
     // seed above, so a supplied-but-malformed accent keeps its old behavior.
     ...(accent != null
       ? {
-          '--color-accent': ld(P[40], P[80]),
+          '--color-accent': ld(PL[40], PD[80]),
           // Derived accent tokens reference --color-accent instead of baking its
           // resolved hex, so a scoped override of the base token re-accents the
           // whole subtree at runtime. --color-on-accent stays baked: it is a
@@ -243,65 +283,70 @@ export function expandColorScale(config: ColorScaleConfig): ColorScaleTokens {
             accentWithAlpha(0.2),
             accentWithAlpha(0.25),
           ),
-          '--color-on-accent': ld(P[100], P[20]),
+          '--color-on-accent': ld(PL[100], PD[20]),
         }
       : null),
-    '--color-neutral': ld(hexWithAlpha(N[10], 0.1), hexWithAlpha(N[90], 0.2)),
-    '--color-background-surface': ld(N[99], N[10]),
-    '--color-background-body': ld(N[95], N[5]),
-    '--color-overlay': ld(hexWithAlpha(N[10], 0.4), hexWithAlpha(N[10], 0.6)),
+    '--color-neutral': ld(hexWithAlpha(NL[10], 0.1), hexWithAlpha(ND[90], 0.2)),
+    '--color-background-surface': ld(NL[99], ND[10]),
+    '--color-background-body': ld(NL[95], ND[5]),
+    '--color-overlay': ld(hexWithAlpha(NL[10], 0.4), hexWithAlpha(ND[10], 0.6)),
     '--color-overlay-hover': ld(
-      hexWithAlpha(N[10], 0.05),
-      hexWithAlpha(N[100], 0.05),
+      hexWithAlpha(NL[10], 0.05),
+      hexWithAlpha(ND[100], 0.05),
     ),
     '--color-overlay-pressed': ld(
-      hexWithAlpha(N[10], 0.1),
-      hexWithAlpha(N[100], 0.1),
+      hexWithAlpha(NL[10], 0.1),
+      hexWithAlpha(ND[100], 0.1),
     ),
     '--color-background-muted': ld(
-      hexWithAlpha(N[10], 0.05),
-      hexWithAlpha(N[10], 0.5),
+      hexWithAlpha(NL[10], 0.05),
+      hexWithAlpha(ND[10], 0.5),
     ),
 
     // Text
-    '--color-text-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
+    '--color-text-primary': ld(
+      NL[textPrimaryLightTone],
+      ND[textPrimaryDarkTone],
+    ),
     '--color-text-secondary': ld(
-      NV[textSecondaryLightTone],
-      NV[textSecondaryDarkTone],
+      NVL[textSecondaryLightTone],
+      NVD[textSecondaryDarkTone],
     ),
-    '--color-text-disabled': ld(NV[60], NV[40]),
+    '--color-text-disabled': ld(NVL[60], NVD[40]),
     '--color-text-accent': 'var(--color-accent)',
 
     // Icon
     '--color-icon-accent': 'var(--color-accent)',
-    '--color-icon-primary': ld(N[textPrimaryLightTone], N[textPrimaryDarkTone]),
+    '--color-icon-primary': ld(
+      NL[textPrimaryLightTone],
+      ND[textPrimaryDarkTone],
+    ),
     '--color-icon-secondary': ld(
-      NV[textSecondaryLightTone],
-      NV[textSecondaryDarkTone],
+      NVL[textSecondaryLightTone],
+      NVD[textSecondaryDarkTone],
     ),
-    '--color-icon-disabled': ld(NV[60], NV[40]),
+    '--color-icon-disabled': ld(NVL[60], NVD[40]),
 
     // Surface variants
-    '--color-background-card': ld(N[99], N[10]),
-    '--color-background-popover': ld(N[99], N[20]),
-    '--color-background-inverted': ld(N[10], N[99]),
+    '--color-background-card': ld(NL[99], ND[10]),
+    '--color-background-popover': ld(NL[99], ND[20]),
+    '--color-background-inverted': ld(NL[10], ND[99]),
 
-    // Border
     // Border
     // Decorative hairline — not a WCAG 1.4.11 boundary. High contrast
     // doubles the alpha so structural boundaries stay perceivable.
     '--color-border': ld(
-      hexWithAlpha(N[10], borderSubtleAlpha),
-      hexWithAlpha(N[95], borderSubtleAlpha),
+      hexWithAlpha(NL[10], borderSubtleAlpha),
+      hexWithAlpha(ND[95], borderSubtleAlpha),
     ),
     '--color-border-emphasized': borderEmphasized,
 
     // Effects
-    '--color-skeleton': ld(NV[70], NV[30]),
+    '--color-skeleton': ld(NVL[70], NVD[30]),
     // Channel-on-body surface (ProgressBar/Slider tracks, Switch off-state).
     // Defaults to the same NV[70]/NV[30] ramp stop as --color-skeleton.
-    '--color-track': ld(NV[70], NV[30]),
-    '--color-shadow': ld(hexWithAlpha(N[0], 0.1), hexWithAlpha(N[0], 0.3)),
+    '--color-track': ld(NVL[70], NVD[30]),
+    '--color-shadow': ld(hexWithAlpha(NL[0], 0.1), hexWithAlpha(ND[0], 0.3)),
     '--color-tint-hover': ld('black', 'white'),
   };
 }

package/src/theme/extensibleAxes.test.ts

@@ -0,0 +1,365 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/* eslint-disable @typescript-eslint/no-require-imports */
+/**
+ * @file Guards the EXTENSIBLE prop axes — the `*Map` interfaces a theme
+ *   augments — against the theming surface that has to carry them.
+ * @input Component sources (*.tsx/*.ts) and their `{Name}.doc.mjs` files.
+ * @output Vitest failures naming each map whose axis a theme cannot reach.
+ * @position Third sibling of derivedVarRegistry.test.ts (`vars`, `derived`) and
+ *   themingTargets.test.ts (`targets`). Those two check what a component
+ *   RENDERS against what it DOCUMENTS. Neither one looks at the open prop
+ *   unions, so nothing did.
+ *
+ * An extensible axis is a promise made in three places at once, and it is only
+ * kept if all three agree:
+ *
+ *   1. `export interface FooVariantMap` in `Foo/index.ts` — the augmentation
+ *      point. A consumer writes `declare module '@astryxdesign/core/Foo'`
+ *      against THAT subpath, and `astryx theme build` looks for the literal
+ *      interface there when it emits `<theme>.variants.d.ts`. A map declared
+ *      in a sibling file and only re-exported is invisible to both.
+ *   2. `themeProps('foo', {variant})` — the axis reaching the DOM. Without it
+ *      a custom variant renders no selector, so there is nothing to style.
+ *   3. `visualProps: ['variant']` on the doc's theming target — discovery, and
+ *      the reason `theme build` does not reject `'foo': {'variant:custom': …}`
+ *      as an unknown prop.
+ *
+ * Miss (2) and the type says yes while the CSS says nothing: TreeList shipped
+ * `TreeListVariantMap`, with a module-augmentation example in its own JSDoc,
+ * while `themeProps('tree-list', {density})` never passed `variant` — so an
+ * augmented variant type-checked, rendered, and could not be themed.
+ */
+
+import {describe, it, expect} from 'vitest';
+import {readdirSync, readFileSync, existsSync} from 'node:fs';
+import {join, relative} from 'node:path';
+import ts from 'typescript';
+import {stableClassName} from '../naming';
+
+const SRC_DIR = join(__dirname, '..');
+
+// ---------------------------------------------------------------------------
+// Source scanning
+// ---------------------------------------------------------------------------
+
+/**
+ * An extensible axis, keyed by the map that owns it.
+ *
+ * The OWNER is the component whose index declares the interface — that is the
+ * subpath a consumer augments and the component that has to reflect the prop.
+ * Other components may declare a prop of the same type (`AlertDialog`'s
+ * `actionVariant: ButtonVariant`, every field's `statusVariant`); they forward
+ * the value to the owner and are not separately accountable for it.
+ */
+interface ExtensibleAxis {
+  /** Component directory under src/ whose index declares the map. */
+  dir: string;
+  /** Interface name, e.g. 'TreeListVariantMap'. */
+  mapName: string;
+  /** The prop it types, read off the interface name, e.g. 'variant'. */
+  prop: string;
+}
+
+function sourceFilesUnder(dir: string, out: string[] = []): string[] {
+  for (const entry of readdirSync(dir, {withFileTypes: true})) {
+    const full = join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (entry.name === 'node_modules' || entry.name === '__tests__') {continue;}
+      sourceFilesUnder(full, out);
+    } else if (/\.tsx?$/.test(entry.name) && !entry.name.includes('.test.')) {
+      out.push(full);
+    }
+  }
+  return out;
+}
+
+function parse(file: string): ts.SourceFile {
+  return ts.createSourceFile(
+    file,
+    readFileSync(file, 'utf8'),
+    ts.ScriptTarget.Latest,
+    true,
+    file.endsWith('.tsx') ? ts.ScriptKind.TSX : ts.ScriptKind.TS,
+  );
+}
+
+/**
+ * Every `type Alias = keyof SomethingMap` in the tree, as alias -> map name.
+ * This is the shape that makes a union OPEN: augmenting the interface widens
+ * the alias, which is the whole mechanism a theme package uses.
+ */
+function collectKeyofAliases(files: string[]): Map<string, string> {
+  const aliases = new Map<string, string>();
+
+  /** `keyof FooMap`, and the `keyof FooMap & string` narrowing form. */
+  const mapBehind = (type: ts.TypeNode): string | null => {
+    if (ts.isIntersectionTypeNode(type)) {
+      for (const member of type.types) {
+        const found = mapBehind(member);
+        if (found != null) {return found;}
+      }
+      return null;
+    }
+    if (
+      ts.isTypeOperatorNode(type) &&
+      type.operator === ts.SyntaxKind.KeyOfKeyword &&
+      ts.isTypeReferenceNode(type.type) &&
+      ts.isIdentifier(type.type.typeName) &&
+      type.type.typeName.text.endsWith('Map')
+    ) {
+      return type.type.typeName.text;
+    }
+    return null;
+  };
+
+  for (const file of files) {
+    const visit = (node: ts.Node): void => {
+      if (ts.isTypeAliasDeclaration(node)) {
+        const map = mapBehind(node.type);
+        if (map != null) {aliases.set(node.name.text, map);}
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(parse(file));
+  }
+  return aliases;
+}
+
+/**
+ * Maps whose alias types a prop on some `*Props` interface — i.e. the open
+ * union is a COMPONENT PROP, which is what makes it a theming axis.
+ *
+ * This is the line between the two kinds of augmentable map in the tree.
+ * `ButtonVariantMap` widens `<Button variant>`, a visual prop that reaches the
+ * DOM and gets styled. `IndicatorMap` widens the set of registered indicator
+ * NAMES — a different extension mechanism (the theme's `indicators` field,
+ * swapping a React component), with no selector and no visual prop. Holding
+ * the second to the theming contract below would be a category error.
+ */
+function mapsTypingAProp(
+  files: string[],
+  aliases: Map<string, string>,
+): Set<string> {
+  const used = new Set<string>();
+  for (const file of files) {
+    const visit = (node: ts.Node): void => {
+      if (ts.isInterfaceDeclaration(node) && node.name.text.endsWith('Props')) {
+        for (const member of node.members) {
+          if (!ts.isPropertySignature(member) || member.type == null) {continue;}
+          const typeNode = ts.isArrayTypeNode(member.type)
+            ? member.type.elementType
+            : member.type;
+          if (
+            ts.isTypeReferenceNode(typeNode) &&
+            ts.isIdentifier(typeNode.typeName)
+          ) {
+            const map = aliases.get(typeNode.typeName.text);
+            if (map != null) {used.add(map);}
+          }
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(parse(file));
+  }
+  return used;
+}
+
+/**
+ * Every map that is (a) an open union — some `type X = keyof <Map>` exists, so
+ * augmenting it widens a real type — and (b) declared in a component index.
+ *
+ * The prop name is read off the interface, which is the same convention
+ * `astryx theme build` uses to find an augmentation point:
+ * `<Prefix><Prop>Map`. `TextColorMap` -> Text, `color`.
+ * `AvatarStatusDotVariantMap` -> Avatar, `variant`.
+ */
+function collectExtensibleAxes(
+  files: string[],
+  aliases: Map<string, string>,
+  propMaps: Set<string>,
+): ExtensibleAxis[] {
+  const open = propMaps;
+  const axes: ExtensibleAxis[] = [];
+  for (const file of files) {
+    if (!/\/index\.tsx?$/.test(file)) {continue;}
+    const dir = relative(SRC_DIR, file).split('/')[0];
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isInterfaceDeclaration(node) &&
+        node.name.text.endsWith('Map') &&
+        open.has(node.name.text)
+      ) {
+        const bare = node.name.text.slice(0, -'Map'.length);
+        // The trailing PascalCase word is the prop.
+        const match = /([A-Z][a-z0-9]*)$/.exec(bare);
+        if (match == null) {return;}
+        const prop = match[1].charAt(0).toLowerCase() + match[1].slice(1);
+        axes.push({dir, mapName: node.name.text, prop});
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(parse(file));
+  }
+  return axes;
+}
+
+/** Every `themeProps('name', {...})` site, as class -> the prop keys it passes. */
+function collectThemePropsSites(files: string[]): Map<string, Set<string>> {
+  const sites = new Map<string, Set<string>>();
+  for (const file of files) {
+    const visit = (node: ts.Node): void => {
+      if (
+        ts.isCallExpression(node) &&
+        ts.isIdentifier(node.expression) &&
+        node.expression.text === 'themeProps'
+      ) {
+        const [nameArg, propsArg] = node.arguments;
+        if (nameArg != null && ts.isStringLiteralLike(nameArg)) {
+          const cls = stableClassName(nameArg.text);
+          const keys = sites.get(cls) ?? new Set<string>();
+          if (propsArg != null && ts.isObjectLiteralExpression(propsArg)) {
+            for (const prop of propsArg.properties) {
+              const name = prop.name;
+              if (
+                name != null &&
+                (ts.isIdentifier(name) || ts.isStringLiteralLike(name))
+              ) {
+                keys.add(name.text);
+              }
+            }
+          }
+          sites.set(cls, keys);
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    visit(parse(file));
+  }
+  return sites;
+}
+
+// ---------------------------------------------------------------------------
+// Docs
+// ---------------------------------------------------------------------------
+
+interface DocTarget {
+  className: string;
+  visualProps: string[];
+}
+
+function collectDocTargets(dir: string): Map<string, DocTarget[]> {
+  const byDir = new Map<string, DocTarget[]>();
+  const walk = (current: string): void => {
+    for (const entry of readdirSync(current, {withFileTypes: true})) {
+      const full = join(current, entry.name);
+      if (entry.isDirectory()) {
+        if (entry.name === 'node_modules' || entry.name === '__tests__') {
+          continue;
+        }
+        walk(full);
+      } else if (entry.name.endsWith('.doc.mjs')) {
+        const componentDir = relative(SRC_DIR, full).split('/')[0];
+        let doc;
+        try {
+          doc = require(full).docs;
+        } catch {
+          continue;
+        }
+        const targets = (doc?.theming?.targets ?? [])
+          .filter(
+            (t: unknown): t is {className: string} =>
+              typeof (t as {className?: unknown})?.className === 'string',
+          )
+          .map((t: {className: string; visualProps?: string[]}) => ({
+            className: t.className,
+            visualProps: t.visualProps ?? [],
+          }));
+        byDir.set(componentDir, [
+          ...(byDir.get(componentDir) ?? []),
+          ...targets,
+        ]);
+      }
+    }
+  };
+  walk(dir);
+  return byDir;
+}
+
+// ---------------------------------------------------------------------------
+
+const files = sourceFilesUnder(SRC_DIR);
+const aliases = collectKeyofAliases(files);
+const propMaps = mapsTypingAProp(files, aliases);
+const axes = collectExtensibleAxes(files, aliases, propMaps);
+const themePropsSites = collectThemePropsSites(files);
+const docTargets = collectDocTargets(SRC_DIR);
+
+/** The target a component's own name maps to, e.g. TreeList -> astryx-tree-list. */
+function ownTargets(axis: ExtensibleAxis): DocTarget[] {
+  return docTargets.get(axis.dir) ?? [];
+}
+
+describe('extensible prop axes are reachable by a theme', () => {
+  it('finds the axes at all (guards the guard)', () => {
+    // If the AST walk silently stopped matching, every assertion below would
+    // pass on an empty list.
+    expect(axes.length).toBeGreaterThan(10);
+    expect(axes.map(a => a.mapName)).toContain('ButtonVariantMap');
+  });
+
+  it('every open prop union is declared in an index a consumer can augment', () => {
+    // Module augmentation only widens the module where the interface is
+    // DECLARED, and the CLI greps the public subpath for that literal
+    // declaration. A map in a sibling file, re-exported, satisfies neither:
+    // `declare module '@astryxdesign/core/<Component>'` would create a new,
+    // unrelated interface and `theme build` would emit no augmentation.
+    // `collectExtensibleAxes` only reads indexes, so anything open and
+    // declared elsewhere is missing from `axes` entirely — compare against
+    // every open map in the tree to catch that.
+    const declaredInAnIndex = new Set(axes.map(a => a.mapName));
+    const notAugmentable = [...propMaps].filter(m => !declaredInAnIndex.has(m));
+    expect(
+      notAugmentable,
+      'these maps type an open union but are not declared in a component index, ' +
+        'so no consumer can augment them at @astryxdesign/core/<Component>',
+    ).toEqual([]);
+  });
+
+  it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(
+    '%s reaches the DOM through themeProps',
+    (_label, axis) => {
+      // The axis is extensible, so a consumer can add a value we have never
+      // seen. The only way their CSS can select it is if the component
+      // reflects the prop.
+      const targets = ownTargets(axis);
+      const reflected = targets.some(t =>
+        themePropsSites.get(t.className)?.has(axis.prop),
+      );
+      expect(
+        reflected,
+        `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
+          `themeProps() call passes \`${axis.prop}\` — a custom value renders no selector, ` +
+          `so it cannot be styled. Pass it: themeProps('<target>', {${axis.prop}}).`,
+      ).toBe(true);
+    },
+  );
+
+  it.each(axes.map(a => [`${a.dir}.${a.prop} (${a.mapName})`, a] as const))(
+    '%s is documented as a visual prop',
+    (_label, axis) => {
+      // Undocumented, it is undiscoverable — and `theme build` rejects
+      // `'<target>': {'<prop>:custom': …}` as an unknown prop, because its
+      // known-prop set is built from exactly this field.
+      const targets = ownTargets(axis);
+      const documented = targets.some(t => t.visualProps.includes(axis.prop));
+      expect(
+        documented,
+        `${axis.dir} lets a theme add \`${axis.prop}\` values via ${axis.mapName}, but no ` +
+          `theming target documents \`${axis.prop}\` in visualProps — a theme author cannot ` +
+          `discover the axis, and \`astryx theme build\` warns "Unknown prop" on it.`,
+      ).toBe(true);
+    },
+  );
+});

package/src/theme/mergeComponents.ts

@@ -0,0 +1,59 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Component style-map merging
+ *
+ * One merge rule for component overrides, shared by every layer that composes
+ * them: `extends` inheritance, generated type-scale rules, and the on-media
+ * (`onDark`/`onLight`) surfaces. Merging is per style key, so a child that
+ * restates one property of `button.base` keeps the rest of the base's.
+ *
+ * @input two ComponentStyleMaps — the base and the overrides that win
+ * @output a merged ComponentStyleMap
+ * @position packages/core/src/theme/mergeComponents.ts
+ */
+
+import type {ComponentStyleMap} from './defineTheme';
+
+/**
+ * Deep-merge component style maps: `overrides` wins per style key, and every
+ * component and key the base declared that the overrides do not mention is
+ * carried through untouched.
+ */
+export function deepMergeComponents(
+  base?: ComponentStyleMap,
+  overrides?: ComponentStyleMap,
+): ComponentStyleMap | undefined {
+  if (!base && !overrides) {
+    return undefined;
+  }
+  if (!base) {
+    return overrides;
+  }
+  if (!overrides) {
+    return base;
+  }
+
+  const result: ComponentStyleMap = {};
+
+  // Start with all base entries
+  for (const [component, rules] of Object.entries(base)) {
+    result[component] = {...rules};
+  }
+
+  // Merge overrides on top
+  for (const [component, rules] of Object.entries(overrides)) {
+    if (!result[component]) {
+      result[component] = {...rules};
+    } else {
+      for (const [key, styles] of Object.entries(rules)) {
+        result[component][key] = {
+          ...result[component][key],
+          ...styles,
+        };
+      }
+    }
+  }
+
+  return result;
+}