@transtyle/exporter-primeng 0.1.0-alpha.0

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@transtyle/exporter-primeng",
+  "version": "0.1.0-alpha.0",
+  "description": "Transtyle exporter for PrimeNG design-token presets (definePreset over Aura). Not yet registered in the CLI — see docs/plan/component-tier.md C6.",
+  "type": "module",
+  "main": "./src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "dependencies": {
+    "@transtyle/ir": "0.1.0-alpha.0"
+  },
+  "transtyle": {
+    "kind": "exporter",
+    "name": "primeng",
+    "irSpec": "v0-draft",
+    "pluginApi": "0",
+    "targets": {
+      "primeng": [
+        "*"
+      ]
+    },
+    "modes": [
+      "color-scheme"
+    ],
+    "capabilities": [
+      "build"
+    ]
+  },
+  "files": [
+    "src",
+    "surface-inventory.json"
+  ],
+  "publishConfig": { "access": "public" },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/transtyle/transtyle.git",
+    "directory": "packages/exporter-primeng"
+  },
+  "homepage": "https://github.com/transtyle/transtyle#readme",
+  "bugs": "https://github.com/transtyle/transtyle/issues",
+  "license": "MIT"
+}

package/src/archetypes.js

@@ -0,0 +1,162 @@
+/**
+ * Exporter-private archetype helpers (docs/proposals/0002-component-theming-primeng.md
+ * §2.3, §2.8, §4; docs/plan/component-tier.md C5). Per C1's cross-ecosystem
+ * study (docs/findings/component-tier-study.md), `field`/`list`/`navigation`/
+ * `overlay` are PrimeNG-specific groupings, not convergent vocabulary — they
+ * live here, permanently, reading straight from existing catalog cells.
+ * Nothing here is a catalog addition; every value below is `get(map, ...)`
+ * against a slot that already exists in `semantic.*`.
+ *
+ * Each helper returns `{ structural, colorScheme }` — verified against real
+ * PrimeNG source (`aura/base/index.ts`, fetched 2026-07-21), which itself
+ * splits every one of these groups the same way: a mode-invariant object
+ * (padding/gap/radius/focusRing-shape) at the top level, and a SEPARATE
+ * `colorScheme.{light,dark}.<group>` object for anything color-ish. This
+ * isn't a stylistic choice on our end — PrimeNG's own DesignTokens TypeScript
+ * types reject color fields on the top-level object and reject dimensional
+ * fields on the colorScheme-scoped one, so index.js calls each helper once
+ * per mode and assembles both halves into the shape PrimeNG's types require.
+ */
+
+const get = (map, path) => map.get(`semantic.${path}`)?.value;
+/** Component-tier read (AL2) — the promoted shared interactive-control slots. */
+const comp = (map, path) => map.get(`component.${path}`)?.value;
+
+export function field(map) {
+  return {
+    structural: {
+      // AL2: the shared control geometry is catalog vocabulary now, so an
+      // authored `component.control.*` reaches PrimeNG's formField (and, via
+      // buildButton, its Button) exactly as it reaches Bootstrap's
+      // $input-btn-*. Unauthored, these resolve to the same space.4/space.2/
+      // radius.control this helper read directly before.
+      paddingX: comp(map, 'control.padding-x'),
+      paddingY: comp(map, 'control.padding-y'),
+      borderRadius: comp(map, 'control.radius'),
+      transitionDuration: get(map, 'duration.fast'),
+      sm: { paddingX: get(map, 'space.3'), paddingY: get(map, 'space.1') },
+      lg: { paddingX: get(map, 'space.5'), paddingY: get(map, 'space.3') },
+    },
+    colorScheme: {
+      background: get(map, 'color.elevation.0.surface'),
+      disabledBackground: get(map, 'color.neutral.tint'),
+      filledBackground: get(map, 'color.elevation.1.surface'),
+      borderColor: get(map, 'color.neutral.outline'),
+      hoverBorderColor: get(map, 'color.neutral.outline-hover'),
+      focusBorderColor: get(map, 'color.primary.solid'),
+      invalidBorderColor: get(map, 'color.danger.solid'),
+      color: get(map, 'color.text.base'),
+      disabledColor: get(map, 'color.text.disabled'),
+      placeholderColor: get(map, 'color.text.muted'),
+      shadow: 'none', // no direct grid cell for a form-field elevation shadow; PrimeNG's own Aura default is flat too
+    },
+  };
+}
+
+export function list(map) {
+  return {
+    structural: {
+      padding: get(map, 'space.1'),
+      gap: get(map, 'space.0'),
+      header: { padding: get(map, 'space.2') },
+      option: { padding: get(map, 'space.2'), borderRadius: get(map, 'radius.control') },
+      optionGroup: {
+        padding: get(map, 'space.2'),
+        fontWeight: String(get(map, 'type.weight.semibold')),
+      },
+    },
+    colorScheme: {
+      option: {
+        focusBackground: get(map, 'color.primary.tint'),
+        selectedBackground: get(map, 'color.primary.tint-active'),
+        selectedFocusBackground: get(map, 'color.primary.tint-active'),
+        color: get(map, 'color.text.base'),
+        focusColor: get(map, 'color.text.base'),
+        selectedColor: get(map, 'color.primary.on-tint'),
+        selectedFocusColor: get(map, 'color.primary.on-tint'),
+      },
+      optionGroup: { background: 'transparent', color: get(map, 'color.text.muted') },
+    },
+  };
+}
+
+export function navigation(map) {
+  return {
+    structural: {
+      list: { padding: get(map, 'space.1'), gap: get(map, 'space.0') },
+      item: {
+        padding: get(map, 'space.2'),
+        borderRadius: get(map, 'radius.control'),
+        gap: get(map, 'space.2'),
+      },
+      submenuLabel: {
+        padding: get(map, 'space.2'),
+        fontWeight: String(get(map, 'type.weight.semibold')),
+      },
+    },
+    colorScheme: {
+      item: {
+        focusBackground: get(map, 'color.primary.tint'),
+        activeBackground: get(map, 'color.primary.tint-active'),
+        color: get(map, 'color.text.base'),
+        focusColor: get(map, 'color.text.base'),
+        activeColor: get(map, 'color.text.base'),
+        icon: { color: get(map, 'color.text.muted'), focusColor: get(map, 'color.text.base') },
+      },
+      submenuLabel: { background: 'transparent', color: get(map, 'color.text.muted') },
+    },
+  };
+}
+
+/** kind: 'popover' | 'modal' | 'navigation' | 'select' — each picks an elevation level. */
+const OVERLAY_LEVEL = { select: 2, popover: 2, modal: 3, navigation: 2 };
+
+export function overlay(map, kind, ctx) {
+  const n = OVERLAY_LEVEL[kind] ?? 2;
+  const shadow = map.get(`semantic.color.elevation.${n}.shadow`)?.value;
+  const shadowStr = shadow
+    ? `${shadow.offsetX} ${shadow.offsetY} ${shadow.blur} ${shadow.spread} ${ctx.formatColor(shadow.color)}`
+    : undefined;
+  return {
+    // borderRadius/shadow are mode-invariant at this position in PrimeNG's own
+    // type (verified: aura/base's top-level `overlay.*` carries no background/color at
+    // all) — `shadow` is computed from whichever map is passed; callers pass the light
+    // map once for this half, matching PrimeNG's own single (non-mode-varying) shadow.
+    // `padding` is NOT part of this object — verified it belongs on each component's
+    // own `content.padding` (Popover/Dialog), not on the shared semantic.overlay.* shape.
+    structural: {
+      ...(kind !== 'navigation' && {
+        borderRadius: get(map, kind === 'modal' ? 'radius.container' : 'radius.field'),
+      }),
+      shadow: shadowStr,
+    },
+    padding:
+      kind === 'navigation' || kind === 'select'
+        ? undefined
+        : get(map, kind === 'modal' ? 'space.6' : 'space.3'),
+    // navigation has no colorScheme-scoped entry in real PrimeNG (Menu's root reads
+    // `content.*` for its own background/color instead) — callers skip this for 'navigation'.
+    colorScheme:
+      kind === 'navigation'
+        ? undefined
+        : {
+            background: get(map, `color.elevation.${n}.surface`),
+            borderColor: get(map, 'color.neutral.outline'),
+            color: get(map, 'color.text.base'),
+          },
+  };
+}
+
+/** Card/Panel-style containers (§4: "content needs no helper" — inline, kept as one function for call-site symmetry). */
+export function content(map) {
+  return {
+    structural: { borderRadius: get(map, 'radius.field') },
+    colorScheme: {
+      background: get(map, 'color.elevation.1.surface'),
+      hoverBackground: get(map, 'color.elevation.1.surface'),
+      borderColor: get(map, 'color.neutral.outline'),
+      color: get(map, 'color.text.base'),
+      hoverColor: get(map, 'color.text.base'),
+    },
+  };
+}

package/src/descriptors.js

@@ -0,0 +1,468 @@
+/**
+ * Per-component builders (docs/plan/component-tier.md C4). Each reads either
+ * `mapSeverityGrid` (severity-colored components) or a plain semantic alias
+ * (primary-anchored components) or an archetype helper (field/list/navigation/
+ * overlay consumers) — zero per-component mapping *logic*, only which cells
+ * a component's real shape (verified against source, fetched 2026-07-21) asks
+ * for. See docs/worklog/2026-07-21-component-tier-c3-c5.md for what was
+ * verified and what this deliberately does not cover yet.
+ *
+ * Every builder takes `(light, dark, ctx)` — two per-mode token maps — and
+ * returns `{ tokens, coverage }` with `tokens.colorScheme = { light, dark }`
+ * wherever the real PrimeNG type requires that split (verified: it's not
+ * optional — PrimeNG's own DesignTokens types reject an unwrapped colorScheme
+ * object, confirmed by compiling the emitted preset against them directly).
+ *
+ * A real, corrective finding from verifying source rather than assuming
+ * proposal 0002's ~25-35 estimate (§5.2): most components proposal 0002
+ * expected to be severity-colored are NOT. Only Button, Tag, Badge, Message,
+ * and InlineMessage actually carry the `variant x severity x part` (or flat
+ * `severity x part`) shape. Checkbox, RadioButton, ToggleSwitch, SelectButton,
+ * ToggleButton, and SplitButton are `field`-shaped (single primary + neutral
+ * surfaces, no severity axis). ProgressBar, Slider, Knob, and Rating are
+ * primary-anchored only — and, verified against source, carry NO colorScheme
+ * block at all; their real Aura default literally writes token-reference
+ * strings like `'{primary.color}'`/`'{text.muted.color}'` rather than
+ * resolving a color, and PrimeNG's own alias engine resolves those per the
+ * active mode — so this file reuses that exact convention for them (a
+ * resolved literal would be mode-wrong: there's no per-mode slot to put it
+ * in). Chip has no brand color at all (plain neutral surface, not covered
+ * in this pass).
+ */
+
+import { mapSeverityGrid } from './severity-grid.js';
+import { field, list, navigation, overlay, content } from './archetypes.js';
+
+const get = (map, path) => map.get(`semantic.${path}`)?.value;
+
+// ---------- severity-colored components (the generic mapper, called once per mode) ----------
+
+function buildButtonColorScheme(map) {
+  const g = mapSeverityGrid(map, {
+    variants: [
+      {
+        name: 'root',
+        parts: {
+          background: 'solid',
+          hoverBackground: 'solid-hover',
+          activeBackground: 'solid-active',
+          borderColor: 'solid',
+          hoverBorderColor: 'solid-hover',
+          activeBorderColor: 'solid-active',
+          color: 'on-solid',
+          hoverColor: 'on-solid',
+          activeColor: 'on-solid',
+          focusRingColor: 'solid',
+        },
+      },
+      {
+        name: 'outlined',
+        parts: {
+          hoverBackground: 'tint',
+          activeBackground: 'tint-active',
+          borderColor: 'outline',
+          color: 'text',
+        },
+      },
+      {
+        name: 'text',
+        parts: { hoverBackground: 'tint', activeBackground: 'tint-active', color: 'text' },
+      },
+    ],
+  });
+  const scheme = { root: {}, outlined: {}, text: {} };
+  for (const severity of [
+    'primary',
+    'secondary',
+    'success',
+    'info',
+    'warn',
+    'danger',
+    'contrast',
+  ]) {
+    scheme.root[severity] = {
+      background: g.get('root', severity, 'background'),
+      hoverBackground: g.get('root', severity, 'hoverBackground'),
+      activeBackground: g.get('root', severity, 'activeBackground'),
+      borderColor: g.get('root', severity, 'borderColor'),
+      hoverBorderColor: g.get('root', severity, 'hoverBorderColor'),
+      activeBorderColor: g.get('root', severity, 'activeBorderColor'),
+      color: g.get('root', severity, 'color'),
+      hoverColor: g.get('root', severity, 'hoverColor'),
+      activeColor: g.get('root', severity, 'activeColor'),
+      focusRing: { color: g.get('root', severity, 'focusRingColor'), shadow: 'none' },
+    };
+    scheme.outlined[severity] = {
+      hoverBackground: g.get('outlined', severity, 'hoverBackground'),
+      activeBackground: g.get('outlined', severity, 'activeBackground'),
+      borderColor: g.get('outlined', severity, 'borderColor'),
+      color: g.get('outlined', severity, 'color'),
+    };
+    scheme.text[severity] = {
+      hoverBackground: g.get('text', severity, 'hoverBackground'),
+      activeBackground: g.get('text', severity, 'activeBackground'),
+      color: g.get('text', severity, 'color'),
+    };
+  }
+  return {
+    scheme,
+    coverage: g.coverage.map((c) => ({ ...c, variable: `button.colorScheme.${c.variable}` })),
+  };
+}
+
+export function buildButton(light, dark, ctx) {
+  const l = buildButtonColorScheme(light);
+  const d = buildButtonColorScheme(dark);
+  const f = field(light).structural;
+  // AL2 parity fix: Button reads the BUTTON layer (which defaults from
+  // control), not the shared field object directly. Before this, an authored
+  // `component.button.radius` moved Bootstrap but not PrimeNG — the two
+  // targets disagreed about what authoring a button token meant.
+  const btn = (t) => light.get(`component.button.${t}`)?.value;
+  return {
+    tokens: {
+      root: {
+        borderRadius: btn('radius'),
+        paddingX: btn('padding-x'),
+        paddingY: btn('padding-y'),
+        gap: get(light, 'space.2'),
+        transitionDuration: f.transitionDuration,
+      },
+      colorScheme: { light: l.scheme, dark: d.scheme },
+      ...(ctx.roleArchetypeExtend ? { extend: ctx.roleArchetypeExtend } : {}),
+    },
+    coverage: l.coverage,
+  };
+}
+
+function buildFlatSeverity(map, { variants, severities, path }) {
+  const g = mapSeverityGrid(map, { variants, severities });
+  const scheme = {};
+  for (const severity of severities) {
+    scheme[severity] = {};
+    for (const field of Object.keys(variants[0].parts))
+      scheme[severity][field] = g.get(variants[0].name, severity, field);
+  }
+  return {
+    scheme,
+    coverage: g.coverage.map((c) => ({ ...c, variable: `${path}.colorScheme.${c.variable}` })),
+  };
+}
+
+export function buildTag(light, dark) {
+  const opts = {
+    variants: [{ name: 'root', parts: { background: 'tint', color: 'text' } }],
+    severities: ['primary', 'secondary', 'success', 'info', 'warn', 'danger', 'contrast'],
+    path: 'tag',
+  };
+  const l = buildFlatSeverity(light, opts);
+  const d = buildFlatSeverity(dark, opts);
+  return { tokens: { colorScheme: { light: l.scheme, dark: d.scheme } }, coverage: l.coverage };
+}
+
+export function buildBadge(light, dark) {
+  const opts = {
+    variants: [{ name: 'root', parts: { background: 'solid', color: 'on-solid' } }],
+    severities: ['primary', 'secondary', 'success', 'info', 'warn', 'danger', 'contrast'],
+    path: 'badge',
+  };
+  const l = buildFlatSeverity(light, opts);
+  const d = buildFlatSeverity(dark, opts);
+  return { tokens: { colorScheme: { light: l.scheme, dark: d.scheme } }, coverage: l.coverage };
+}
+
+/** Message nests severity-major (colorScheme.<mode>.<severity>.{filled fields, outlined:{}, simple:{}}) — the opposite variant/severity order from Button. Verified against source, not assumed. No `primary` severity (info/success/warn/danger/secondary/contrast only) — a real PrimeNG inconsistency with Button/Tag/Badge, not ours. */
+function buildMessageColorScheme(map) {
+  const g = mapSeverityGrid(map, {
+    severities: ['info', 'success', 'warn', 'danger', 'secondary', 'contrast'],
+    variants: [
+      { name: 'filled', parts: { background: 'tint', borderColor: 'outline', color: 'text' } },
+      { name: 'outlined', parts: { color: 'text', borderColor: 'text' } },
+      { name: 'simple', parts: { color: 'text' } },
+    ],
+  });
+  const scheme = {};
+  for (const severity of ['info', 'success', 'warn', 'danger', 'secondary', 'contrast']) {
+    const key = severity === 'danger' ? 'error' : severity; // real PrimeNG naming inconsistency (verified against source), not ours
+    scheme[key] = {
+      background: g.get('filled', severity, 'background'),
+      borderColor: g.get('filled', severity, 'borderColor'),
+      color: g.get('filled', severity, 'color'),
+      outlined: {
+        color: g.get('outlined', severity, 'color'),
+        borderColor: g.get('outlined', severity, 'borderColor'),
+      },
+      simple: { color: g.get('simple', severity, 'color') },
+    };
+  }
+  return {
+    scheme,
+    coverage: g.coverage.map((c) => ({ ...c, variable: `message.colorScheme.${c.variable}` })),
+  };
+}
+
+export function buildMessage(light, dark) {
+  const l = buildMessageColorScheme(light);
+  const d = buildMessageColorScheme(dark);
+  return { tokens: { colorScheme: { light: l.scheme, dark: d.scheme } }, coverage: l.coverage };
+}
+
+/** Flat like Tag/Badge but uses `danger`-as-`error` naming (real PrimeNG inconsistency) plus a `shadow` field, approximated from the role's solid color at fixed low alpha (PrimeNG's own convention: `color-mix(..., transparent 96%)`). */
+function buildInlineMessageColorScheme(map, ctx) {
+  const g = mapSeverityGrid(map, {
+    severities: ['info', 'success', 'warn', 'danger', 'secondary', 'contrast'],
+    variants: [
+      { name: 'root', parts: { background: 'tint', borderColor: 'outline', color: 'text' } },
+    ],
+  });
+  const scheme = {};
+  const coverage = [...g.coverage];
+  const roleFor = {
+    info: 'info',
+    success: 'success',
+    warn: 'warning',
+    danger: 'danger',
+    secondary: 'secondary',
+  };
+  for (const severity of ['info', 'success', 'warn', 'danger', 'secondary', 'contrast']) {
+    const solid =
+      severity === 'contrast'
+        ? map.get('semantic.color.neutral.text-strong')?.value
+        : map.get(`semantic.color.${roleFor[severity]}.solid`)?.value;
+    const key = severity === 'danger' ? 'error' : severity;
+    scheme[key] = {
+      background: g.get('root', severity, 'background'),
+      borderColor: g.get('root', severity, 'borderColor'),
+      color: g.get('root', severity, 'color'),
+      shadow: solid ? `0px 4px 8px 0px ${ctx.formatColor({ ...solid, alpha: 0.04 })}` : undefined,
+    };
+    if (solid)
+      coverage.push({
+        variable: `inlinemessage.colorScheme.${severity}.shadow`,
+        slot: '—',
+        class: 'approximated',
+        note: "fixed low-alpha tint of the role solid color, matching PrimeNG's own color-mix(..., transparent 96%) convention — not a colorimetric shadow derivation",
+      });
+  }
+  return {
+    scheme,
+    coverage: coverage.map((c) =>
+      c.variable?.startsWith('inlinemessage')
+        ? c
+        : { ...c, variable: `inlinemessage.colorScheme.${c.variable}` },
+    ),
+  };
+}
+
+export function buildInlineMessage(light, dark, ctx) {
+  const l = buildInlineMessageColorScheme(light, ctx);
+  const d = buildInlineMessageColorScheme(dark, ctx);
+  return { tokens: { colorScheme: { light: l.scheme, dark: d.scheme } }, coverage: l.coverage };
+}
+
+// ---------- primary-anchored components: verified to have NO colorScheme block in real
+// PrimeNG at all — their own Aura default writes a bare token-reference string, which
+// PrimeNG's own alias engine resolves per the active mode. We reuse those exact strings
+// rather than resolving a literal (a literal would be mode-wrong: there is no per-mode
+// slot to put a second value in). Not mode-dependent, so a single build suffices. ----------
+
+export function buildProgressBar() {
+  return {
+    tokens: {
+      value: { background: '{primary.color}' },
+      label: { color: '{primary.contrastColor}' },
+    },
+    coverage: [
+      {
+        variable: 'progressbar.value.background',
+        slot: 'PrimeNG preset {primary.color} (runtime alias, not an IR path)',
+        class: 'native',
+      },
+    ],
+  };
+}
+
+export function buildRating() {
+  return {
+    tokens: {
+      icon: {
+        color: '{text.mutedColor}',
+        hoverColor: '{primary.color}',
+        activeColor: '{primary.color}',
+      },
+    },
+    coverage: [
+      {
+        variable: 'rating.icon.hoverColor',
+        slot: 'PrimeNG preset {primary.color} (runtime alias, not an IR path)',
+        class: 'native',
+      },
+    ],
+  };
+}
+
+// ---------- archetype-consumer components (§4/§5, C5) ----------
+
+export function buildListbox(light, dark) {
+  const fl = field(light),
+    fd = field(dark);
+  const ll = list(light),
+    ld = list(dark);
+  return {
+    tokens: {
+      root: {
+        borderRadius: fl.structural.borderRadius,
+        transitionDuration: fl.structural.transitionDuration,
+      },
+      colorScheme: {
+        light: {
+          root: {
+            background: fl.colorScheme.background,
+            disabledBackground: fl.colorScheme.disabledBackground,
+            borderColor: fl.colorScheme.borderColor,
+            invalidBorderColor: fl.colorScheme.invalidBorderColor,
+            color: fl.colorScheme.color,
+            disabledColor: fl.colorScheme.disabledColor,
+          },
+          option: ll.colorScheme.option,
+        },
+        dark: {
+          root: {
+            background: fd.colorScheme.background,
+            disabledBackground: fd.colorScheme.disabledBackground,
+            borderColor: fd.colorScheme.borderColor,
+            invalidBorderColor: fd.colorScheme.invalidBorderColor,
+            color: fd.colorScheme.color,
+            disabledColor: fd.colorScheme.disabledColor,
+          },
+          option: ld.colorScheme.option,
+        },
+      },
+      list: {
+        padding: ll.structural.padding,
+        gap: ll.structural.gap,
+        header: ll.structural.header,
+      },
+      option: ll.structural.option,
+      optionGroup: ll.structural.optionGroup,
+    },
+    coverage: [
+      { variable: 'listbox.root.*', slot: 'exporter-private: field()', class: 'derived' },
+      { variable: 'listbox.option.*', slot: 'exporter-private: list()', class: 'derived' },
+    ],
+  };
+}
+
+export function buildMenu(light, dark, ctx) {
+  const nl = navigation(light),
+    nd = navigation(dark);
+  const cl = content(light),
+    cd = content(dark);
+  const shadow = light.get('semantic.color.elevation.2.shadow')?.value;
+  return {
+    tokens: {
+      root: {
+        borderRadius: cl.structural.borderRadius,
+        shadow: shadow
+          ? `${shadow.offsetX} ${shadow.offsetY} ${shadow.blur} ${shadow.spread} ${ctx.formatColor(shadow.color)}`
+          : undefined,
+      },
+      colorScheme: {
+        // Menu's own component-level `item` type is narrower than the shared
+        // semantic.navigation.item group (verified against source: no active*
+        // fields at the component level — only focus, since Menu has no active state).
+        light: {
+          root: {
+            background: cl.colorScheme.background,
+            borderColor: cl.colorScheme.borderColor,
+            color: cl.colorScheme.color,
+          },
+          item: {
+            focusBackground: nl.colorScheme.item.focusBackground,
+            color: nl.colorScheme.item.color,
+            focusColor: nl.colorScheme.item.focusColor,
+            icon: nl.colorScheme.item.icon,
+          },
+          submenuLabel: nl.colorScheme.submenuLabel,
+        },
+        dark: {
+          root: {
+            background: cd.colorScheme.background,
+            borderColor: cd.colorScheme.borderColor,
+            color: cd.colorScheme.color,
+          },
+          item: {
+            focusBackground: nd.colorScheme.item.focusBackground,
+            color: nd.colorScheme.item.color,
+            focusColor: nd.colorScheme.item.focusColor,
+            icon: nd.colorScheme.item.icon,
+          },
+          submenuLabel: nd.colorScheme.submenuLabel,
+        },
+      },
+      list: nl.structural.list,
+      item: nl.structural.item,
+      submenuLabel: nl.structural.submenuLabel,
+    },
+    coverage: [
+      { variable: 'menu.item.*', slot: 'exporter-private: navigation()', class: 'derived' },
+    ],
+  };
+}
+
+export function buildPopover(light, dark, ctx) {
+  const ol = overlay(light, 'popover', ctx),
+    od = overlay(dark, 'popover', ctx);
+  return {
+    tokens: {
+      root: { ...ol.structural },
+      colorScheme: { light: { root: ol.colorScheme }, dark: { root: od.colorScheme } },
+      content: { padding: ol.padding },
+    },
+    coverage: [
+      { variable: 'popover.root.*', slot: 'exporter-private: overlay(popover)', class: 'derived' },
+    ],
+  };
+}
+
+export function buildDialog(light, dark, ctx) {
+  const ol = overlay(light, 'modal', ctx),
+    od = overlay(dark, 'modal', ctx);
+  return {
+    tokens: {
+      root: { ...ol.structural },
+      colorScheme: { light: { root: ol.colorScheme }, dark: { root: od.colorScheme } },
+      header: { padding: ol.padding },
+      content: { padding: ol.padding },
+      footer: { padding: ol.padding },
+    },
+    coverage: [
+      { variable: 'dialog.root.*', slot: 'exporter-private: overlay(modal)', class: 'derived' },
+    ],
+  };
+}
+
+/**
+ * Structural residue (§5.2 / C5): components with no severity-colored surface
+ * and not yet given a real builder above. Honest `unsupported` coverage,
+ * matching every other exporter's convention — not silently dropped.
+ */
+export const STRUCTURAL_RESIDUE = [
+  'datatable',
+  'galleria',
+  'tree',
+  'treetable',
+  'splitter',
+  'timeline',
+  'organizationchart',
+  'carousel',
+  'dataview',
+  'orderlist',
+  'picklist',
+  'paginator',
+  'stepper',
+  'steps',
+  'tabs',
+  'tabview',
+  'accordion',
+];