@radicool/throughline 0.15.0 → 0.16.0

package/references/sync-adapters.md

@@ -35,16 +35,54 @@ user names one of these, use the vetted preset — high confidence, no guessing.
 | `tailwind` | tailwind theme config | `dark:` variant / class strategy | preserved (via CSS vars) | `colors.background` |
 | `mui` | JS theme object | `createTheme` palettes | preserved (object refs) | `palette.primary.main` |
 | `vanilla-css` | one CSS file | `:root` + `[data-theme]` | preserved | `--color-bg-default` |
-| `ios-swift` | Swift enum / asset catalog | light/dark asset variants | flattened | `Color.backgroundPrimary` |
-
-These five were chosen for coverage of this plugin's web-first, design-led
-audience: three React framework adapters (shadcn — the dominant new-project
-choice; standalone Tailwind — for the large Tailwind-without-shadcn population;
-MUI — the enterprise/Material standard), the universal `vanilla-css` escape
-hatch (plain CSS custom properties, no framework), and one native slot
-(`ios-swift`, the more standardized native pattern). Everything else —
-Ant Design, Chakra, HeroUI, Android/Kotlin, Flutter, React Native, etc. — is
-fully supported via Tier 2.
+| `ios-swift` | Swift enum constants (`Tokens.swift`) | one build per mode, one output directory per mode | flattened | `Tokens.textSm` |
+
+Four of the five cover this plugin's web-first, design-led audience: three React
+framework adapters (shadcn — the dominant new-project choice; standalone
+Tailwind — for the large Tailwind-without-shadcn population; MUI — the
+enterprise/Material standard), plus the universal `vanilla-css` escape hatch
+(plain CSS custom properties, no framework). `ios-swift` is the one native
+member, and it is curated because its configuration ships as tested code rather
+than as advice — see `${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`.
+Everything else — Ant Design, Chakra, HeroUI, Android/Kotlin, Flutter, React
+Native, etc. — is fully supported via Tier 2.
+
+**`ios-swift` was demoted, and has been restored.** Run against a real DTCG
+source under the *stock* transform group it emitted px-authored dimensions at
+×16 their authored value (valid, compiling Swift), leaked `color-mix()`
+expressions, and left dual-node aliases as bare `px` literals. The tier badge
+claimed a confidence the stock configuration had not earned, so it came off.
+
+The cause was the transform group, not the adapter concept. That configuration
+now ships as tested code at
+`${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs`, is installed into the
+consumer's repo, and is verified end to end against a real source (195 emitted
+symbols matched, zero rule failures under the shipping ruleset, on both light
+and dark builds). The badge is back on that basis.
+
+**What the badge does not cover: nothing is compiled.** Every emitted value is
+checked to be a well-formed Swift or Kotlin *literal* — `tokens:validate-output`'s
+`invalid-literal` rule parses each one and fails on anything that is not
+(#53) — but no `swiftc` or `kotlinc` runs, so a type mismatch or a call to an
+undefined symbol would still pass. String-valued tokens (`fontFamily`, `string`,
+keyword `fontWeight`) are quoted by the module's own transforms, and a value with
+no native form at all — a CSS `linear-gradient(...)` — is filtered out of native
+output rather than emitted broken. That drop is reported as an unemitted token,
+not hidden.
+
+`android-kotlin` uses the same module and stays Tier 2: its remaining unknowns
+are on the consumption side — Compose `dp`/`sp` behaviour against a real Compose
+app, resource-qualifier conventions, package layout — which building tokens does
+not exercise. The `dp`/`sp` split itself is no longer among them: font sizes and
+line heights whose role a DTCG source states — the `fontSize`, `letterSpacing`
+and `lineHeight` member names of §9.8's typography composite — now emit as
+`sp`. What remains is narrower and documented in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`: a bare scale
+primitive carries no role and stays `dp`, and an `em` letterSpacing is
+filtered out rather than emitted as `.em`.
+`tokens:validate-output` remains what decides whether any adapter can be
+trusted, and re-promotion is available to any adapter that passes it against a
+real source.
 
 `shadcn` vs `tailwind`: shadcn emits CSS vars *plus* the specific var names
 shadcn components expect; `tailwind` targets Tailwind used on its own, mapping
@@ -99,8 +137,52 @@ emit as references to primitive vars rather than flattened literals.
 - **Native adapters** (`ios-swift`, and generated native targets like
   Android/Kotlin): `outputReferences: false` — references resolve to literal
   values at build time, because the target language has no runtime var
-  indirection. Modes map to the platform's native mechanism (asset catalog
-  variants, resource qualifiers).
+  indirection. Modes map to **one build per mode, one output directory per
+  mode** — each build passing only that mode's sources, through `nativeSources`.
+  Asset-catalog variants and resource qualifiers are *not* implemented: nothing
+  here emits an `.xcassets` catalog or a `values-night/` resource tree.
+
+## What the stock configuration gets wrong
+
+These are all legal in a real DTCG source, and a **stock** Style Dictionary
+transform group mishandles every one of them silently — emitting output that
+compiles and is wrong, which is why `tokens:validate-output` exists.
+
+**None of these are Style Dictionary limitations.** All four are fixed by
+roughly 80 lines of preprocessor and transform code, which ships as a tested
+module at `${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs` and is documented in
+`${CLAUDE_PLUGIN_ROOT}/references/native-adapter-config.md`. Against a real
+322-token source it emitted 195 symbols that all map to a source token, 107 of
+them with their numeric magnitude additionally verified, with zero rule failures
+— colour and string values are matched by name only and are checked by no rule.
+**Import that module** rather than configuring a native adapter from a stock
+`transformGroup` or transcribing the reference doc.
+
+- **CSS expressions in a value** — `color-mix(in srgb, {color.brand.500} 12%,
+  transparent)` is a runtime CSS construct. Style Dictionary does no colour
+  math, so it resolves only the inner reference and leaves the function wrapper
+  in the output. *Fix: a transform that computes the blend to a literal.*
+- **Dual-node tokens** — a node carrying both a `$value` and children (`text.sm`
+  with `$value: "14px"` plus a `text.sm.lineHeight` child). Style Dictionary's
+  resolver will not traverse into one, so every alias to the child fails to
+  resolve and emits as a bare literal; its collector also stops there, so the
+  child is never emitted at all. *Fix: a preprocessor that resolves aliases and
+  hoists the children.*
+- **`%` and `em` dimensions** — parent-relative or container-relative, so there
+  genuinely is no build-time native magnitude. This one is a real limit rather
+  than a configuration gap. *Handling: filter them out of native builds — on the
+  authored value, since a `100%` token may be typed `string`, not `dimension`.*
+- **A third mode axis** — this reference models theme (`.dark` /
+  `[data-theme]`) and brand (`[data-brand]`). A viewport axis carrying its own
+  spacing and type scales is common and has no mapping here; on native it is
+  size classes and resource qualifiers, resolved by a different mechanism
+  entirely.
+
+**Native dimension transforms must read the authored unit.** The stock
+`ios-swift` and `compose` transform groups assume `rem` input and multiply by
+16. Against a `px`-authored source that silently produces output at sixteen
+times scale which compiles and ships. Emit 1:1 for `px` and unitless ratios;
+×16 only for `rem`.
 
 ## Brownfield value transforms
 

package/scripts/README.md

@@ -10,7 +10,11 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `validate-crosswalk.mjs` | Resolve every `newToken` against the DTCG token source; assert resolved value == `newValue`, N/N. The CI gate. | `tokens:validate` |
 | `build-reverse-index.mjs` | Emit a `codeToken -> newToken` map from the crosswalk to semi-automate SCSS/Tailwind swaps. | `tokens:reverse-index` |
 | `guard-token-removal.mjs` | Grep `.ts/.tsx` (minus generated + tests) for about-to-be-deleted symbols; blocks cleanup until zero references remain. | run during the cleanup phase |
+| `validate-token-output.mjs` | Assert generated native token output matches its DTCG source: authored-unit fidelity, no leaked CSS syntax, no bare unit literals, no mode collisions. Fails when no emitted symbol matches a source token, and reports match rate, unparsed lines, and unemitted tokens on every run. | `tokens:validate-output` |
 | `lib/crosswalk.mjs` | Shared loader + structural validation for `crosswalk.json` (used by the validator and reverse-index). | copied alongside |
+| `lib/dtcg.mjs` | Shared DTCG flatten + `{alias}` resolution. Dual-node aware: a node carrying both a `$value` and children yields its own value **and** is descended into. Used by `validate-crosswalk.mjs` and `validate-token-output.mjs`. | copied alongside both |
+| `lib/sd-native.mjs` | The Style Dictionary native configuration as code: unit-aware dimension transforms, `color-mix` computation, dual-node preprocessing, platform assembly, and a per-mode source guard. Style Dictionary is a parameter, never an import. | copied alongside `validate-token-output.mjs` |
+| `lib/native-literal.mjs` | Shared grammar for "is this a well-formed Swift or Kotlin literal": parses rather than pattern-matches, so an unquoted string, a raw CSS function, or any other unanticipated case fails the same way. Used by `sd-native.mjs`'s output filter and by `validate-token-output.mjs`'s invalid-literal rule. | copied alongside `validate-token-output.mjs` and `lib/sd-native.mjs` |
 | `crosswalk.schema.json` | The finalized JSON Schema for `crosswalk.json` (contract + editor support). | copied beside `crosswalk.json` |
 | `build-docs-digest.mjs` | Aggregate every `design-system/docs/components/*.doc.json` into `design-system/docs/index.json` + `llms.txt` for AI/human consumers. | `docs:digest` |
 | `docs-check.mjs` | Drift gate — verifies each component's doc surfaces still match its canonical record (via `lib/doc-record.mjs` fingerprints). Exits 1 on drift. | `docs:check` |
@@ -19,6 +23,7 @@ tested here; copied verbatim by `token-crosswalk-builder` into the user's
 | `lib/doc-card-render.figma.js` | Figma renderer template for the doc card's `Usage` band and header. Inlined into `references/doc-card-builder.md`; never executed as a module. | plugin-internal (not installed) |
 | `lib/doc-card-plan.mjs` | Pure layout planner for the doc card's `Usage` band + `DOC_CARD_RENDERER_VERSION` (single source of the layout version). Inlined into `references/doc-card-builder.md`; imported by `docs-check.mjs`. | copied alongside docs-check.mjs; also inlined into the generated builder |
 | `build-doc-card-builder.mjs` | Generate `references/doc-card-builder.md` from the planner + the Figma renderer template (`lib/doc-card-render.figma.js`). `--check` gates CI. | plugin-internal (not installed) |
+| `build-native-adapter-config.mjs` | Generate `references/native-adapter-config.md` by slicing `lib/sd-native.mjs` on its `@doc-section` markers and interleaving each fragment under its prose. Fails when module code falls outside every section, so the doc cannot silently ship incomplete. `--check` gates CI. | plugin-internal (not installed) |
 
 **Documentation scripts — install as a set.** Copying these files without
 registering them leaves a repo with a script on disk and no entry point, which
@@ -54,9 +59,9 @@ conflict, or remaining reference), `2` bad CLI arguments.
 
 ## How the skill installs these
 
-`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `validate-crosswalk.mjs`,
-`build-reverse-index.mjs`, `guard-token-removal.mjs`, and `crosswalk.schema.json`
-into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
+`token-crosswalk-builder` copies `lib/crosswalk.mjs`, `lib/dtcg.mjs`,
+`validate-crosswalk.mjs`, `build-reverse-index.mjs`, `guard-token-removal.mjs`, and
+`crosswalk.schema.json` into the user's `packages/tokens/scripts/` (schema beside `crosswalk.json`), then
 wires `packages/tokens/package.json`:
 
 ```jsonc
@@ -66,6 +71,12 @@ wires `packages/tokens/package.json`:
 }
 ```
 
+`token-sync-layer` copies `validate-token-output.mjs`, `lib/dtcg.mjs`,
+`lib/native-literal.mjs`, **and** `lib/sd-native.mjs`, and wires
+`"tokens:validate-output"`. All four travel together: `sd-native.mjs` and the
+validator both import `lib/dtcg.mjs` and `lib/native-literal.mjs`, so
+installing any one of them alone breaks at import time.
+
 The scripts version with the user's repo so their CI runs them locally — a path
 inside the plugin install would not be reachable from the user's CI.
 

package/scripts/build-native-adapter-config.mjs

@@ -0,0 +1,280 @@
+// Generates references/native-adapter-config.md from scripts/lib/sd-native.mjs.
+// The prose lives here, keyed by section id; the code is sliced out of the
+// module's real source between @doc-section markers and interleaved beneath its
+// prose. Mirrors build-doc-card-builder.mjs: run bare to write, --check to gate
+// CI. Zero dependencies.
+import { readFileSync, writeFileSync } from 'node:fs';
+import { join, dirname } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), '..');
+export const SOURCE = join(REPO_ROOT, 'scripts', 'lib', 'sd-native.mjs');
+export const OUT = join(REPO_ROOT, 'references', 'native-adapter-config.md');
+
+const OPEN = /^\s*\/\/\s*@doc-section\s+(\S+)\s*$/;
+const CLOSE = /^\s*\/\/\s*@doc-section-end\s+(\S+)\s*$/;
+
+export function sliceSections(source) {
+  const sections = new Map();
+  let open = null;
+  let buffer = [];
+  for (const line of source.split('\n')) {
+    const closeMatch = line.match(CLOSE);
+    if (closeMatch) {
+      if (!open) throw new Error(`@doc-section-end ${closeMatch[1]} with no open section`);
+      if (closeMatch[1] !== open) {
+        throw new Error(`@doc-section-end ${closeMatch[1]} does not close ${open}`);
+      }
+      sections.set(open, buffer.join('\n').trim());
+      open = null;
+      buffer = [];
+      continue;
+    }
+    const openMatch = line.match(OPEN);
+    if (openMatch) {
+      if (open) throw new Error(`unclosed @doc-section ${open}`);
+      if (sections.has(openMatch[1])) throw new Error(`duplicate @doc-section ${openMatch[1]}`);
+      open = openMatch[1];
+      continue;
+    }
+    if (open) buffer.push(line);
+  }
+  if (open) throw new Error(`unclosed @doc-section ${open}`);
+  return sections;
+}
+
+// Every line of module source must live inside some @doc-section pair, so that
+// adding a piece to the module without documenting it breaks CI rather than
+// silently shipping a doc whose code does not run. Legitimately outside: blank
+// lines, `//` comment lines (the file's leading banner), and the markers
+// themselves. Anything else — any line with executable code on it — is a gap.
+export function assertCovered(source) {
+  const uncovered = [];
+  let open = false;
+  source.split('\n').forEach((line, i) => {
+    if (CLOSE.test(line)) {
+      open = false;
+      return;
+    }
+    if (OPEN.test(line)) {
+      open = true;
+      return;
+    }
+    if (open) return;
+    const trimmed = line.trim();
+    if (trimmed === '' || trimmed.startsWith('//')) return;
+    uncovered.push(`  ${i + 1}: ${line}`);
+  });
+  if (uncovered.length === 0) return;
+  throw new Error(
+    `${uncovered.length} line(s) of ${SOURCE} fall outside every @doc-section pair.\n` +
+      'Only blank lines and // comments may sit outside a section; code must be\n' +
+      'inside one, or the generated doc shows code that cannot run.\n' +
+      uncovered.join('\n'),
+  );
+}
+
+// Section id -> the prose that introduces it. Order here is the doc's order.
+const PROSE = [
+  ['imports', `## Imports
+
+\`node:fs\` plus the siblings \`lib/dtcg.mjs\` and \`lib/native-literal.mjs\` this
+plugin already installs — nothing else. Style Dictionary is passed in as a
+parameter, never imported, which is what keeps this module installable into a
+consumer's repo.`],
+  ['unit-aware', `## 1. Read the authored unit
+
+**This replaces \`size/swift/remToCGFloat\` and the \`size/compose/*\` transforms,
+and it is the single most important piece.** Those assume every dimension is
+authored in \`rem\` and multiply by 16. Against a \`px\`-authored source that
+silently produces output at sixteen times scale which compiles and ships.`],
+  ['color-mix', `## 2. Compute \`color-mix()\` to a literal
+
+A CSS expression has no native equivalent, and Style Dictionary does no colour
+math. Native adapters resolve to literals; for a \`color-mix\` that means
+actually computing the blend. Register this **before** the platform's colour
+transform, so the colour transform receives a valid hex8 rather than a CSS
+function.`],
+  ['preprocess', `## 3. Resolve aliases and hoist dual-node children
+
+Style Dictionary's resolver will not traverse into a node that carries both a
+\`$value\` and children, and its collector stops there too. The dual-node pattern
+is invalid DTCG — the Design Tokens Format Module's 30 July 2026 draft, §6.1,
+requires tools to report it as an error, and §6.2's \`$root\` is the sanctioned
+way to pair a value with children. Figma-derived sources emit it anyway:
+\`text.sm\` holds \`$value: "14px"\` *and* a \`text.sm.lineHeight\` child. So every
+alias to such a child fails to resolve, and the child is never emitted at all.
+
+Both are fixed before Style Dictionary sees the tree.`],
+  ['platform', `## 4. Assemble the platform from the stock list
+
+Build the transform list from Style Dictionary's **stock group**, replacing only
+the rem-assuming size transforms. A hand-picked list silently drops whatever it
+forgets — three real defects arose exactly that way.
+
+**The \`dp\`/\`sp\` split is fixed here; two narrower Android-only limits remain.**
+Style Dictionary's Compose transforms select on \`$type\`, and DTCG's type set
+does not line up with what they expect — there is no \`fontSize\` type, because
+DTCG types font sizes as \`dimension\`. So the role is taken instead from the
+member names DTCG §9.8 fixes for the typography composite, stamped onto
+\`$extensions\` during preprocessing, and the two Compose transforms partition on
+that stamp. Measured against a real source: 39 declarations that emitted \`dp\`
+now emit \`sp\`, with the Swift output byte-identical.
+
+What remains:
+
+- **A bare scale primitive emits as \`dp\`.** \`text.base: "16px"\` is a font size
+  only to a human — no nominal or structural signal marks it — so it is not
+  stamped. The semantic tokens that reference it are, and those are what a
+  consumer should reach for.
+- **An \`em\` letter spacing reaches Compose but not Swift.** \`size/unit-aware/compose-em\`
+  emits it as a real \`.em\` TextUnit, parenthesised — \`(-0.03).em\` — because
+  \`-0.03.em\` parses as \`-(0.03.em)\` and needs an \`unaryMinus\` operator, while
+  the parenthesised form compiles regardless. iOS is excluded deliberately, not
+  pending: letter spacing there is an \`NSAttributedString\` kern in points,
+  which needs the font size the token does not carry, so no constant Swift
+  could emit would be right at every font size.
+
+The first is Android-only. \`size/unit-aware/swift\` filters
+\`dimension || fontSize\` and emits \`CGFloat\`, which carries no unit to be wrong
+about; iOS handles Dynamic Type at the use site via \`UIFontMetrics\`.
+\`tokens:validate-output\` passes in both cases: it checks magnitude, not unit.
+
+**A unitless value is no longer one of them.** DTCG §8.2.1 requires a dimension
+to carry a unit, §8.7's \`number\` is the type for a ratio, and §9.8 types
+\`lineHeight\` as one — so \`leading.normal: "1.5"\` typed \`dimension\` is malformed
+input. No size transform claims it: it emits bare on both platforms, which is
+byte-for-byte what a correctly typed \`number\` already produced, so correcting
+the source's \`$type\` changes no output. \`tokens:validate-output\` reports it as
+a \`unitless-dimension\` advisory, which does not gate — the emitted value is
+right under the ratio reading, and only the author can say whether a ratio is
+what was meant.
+
+**The stock list is accounted for, not transcribed.** \`PLATFORMS\` records the
+stock group each platform mirrors, and \`auditStockGroups\` checks at
+registration that every transform in that live group is either run here or
+declined in writing, with a reason. A stock transform this config has never
+decided about warns; it is never silently dropped. The check warns and never
+throws — a new stock transform is usually harmless, and the fatal direction, a
+transform we run being removed, already makes Style Dictionary throw on an
+unknown name. It runs in your build because that is the only place the
+installed Style Dictionary version is knowable: ThroughLine declares no
+dependency on it.`],
+  ['sources', `## 5. Guard the per-mode source list
+
+Style Dictionary deduplicates by dot-path, so one build over both a light and a
+dark definition of the same token keeps whichever file sorts last and drops the
+other mode with no diagnostic. Pass every build's sources through
+\`nativeSources\`, which returns them, so the check cannot be skipped by
+forgetting it.`],
+  ['register', `## 6. Register with Style Dictionary
+
+One call. Style Dictionary is a parameter, never an import, which is what lets
+this module install into a consumer's \`packages/tokens/scripts/lib/\`.`],
+];
+
+const HEADER = `# Native adapter configuration (GENERATED)
+
+> **GENERATED FILE — do not edit by hand.** Source: \`scripts/lib/sd-native.mjs\`,
+> which is unit-tested in Node and installed into the consumer's repo.
+> Regenerate with \`node scripts/build-native-adapter-config.mjs\`; CI gates
+> freshness with \`--check\`.
+
+The Style Dictionary configuration a native adapter (\`ios-swift\`,
+\`android-kotlin\`, or any generated native target) needs in order to emit
+**correct** output from a real DTCG token source.
+
+**Why this exists.** The stock \`ios-swift\` and \`compose\` transform groups
+produce output that compiles and is wrong. Run against a real source, the stock
+configuration emitted every \`px\`-authored dimension at ×16 its authored value,
+leaked \`color-mix()\` expressions into Swift, and left dual-node aliases as bare
+\`px\` literals — all at exit \`0\`. None of that is a Style Dictionary limitation.
+All of it is configuration.
+
+**You do not need to copy any of this.** It ships as
+\`\${CLAUDE_PLUGIN_ROOT}/scripts/lib/sd-native.mjs\`. Install it beside
+\`lib/dtcg.mjs\` and \`lib/native-literal.mjs\` and call it:
+
+\`\`\`js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of ['light', 'dark']) {
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: \`out/\${mode}/\` }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+\`\`\`
+
+The sections below are the module's own source, inlined so the configuration
+stays reviewable. Pair this with \`\${CLAUDE_PLUGIN_ROOT}/references/sync-adapters.md\`,
+which covers the adapter contract itself.
+`;
+
+const FOOTER = `## Verify, always
+
+Configuration this specific is exactly what regresses unnoticed, because every
+failure mode above produces output that compiles. Run \`tokens:validate-output\`
+against each generated file with the same source list that file's build used,
+and treat it as a gate rather than a spot check:
+
+\`\`\`
+node scripts/validate-token-output.mjs \\
+  --source tokens/color-primitives.json --source tokens/text-primitives.json \\
+  --output out/light/Tokens.swift --platform ios-swift --min-match 1
+\`\`\`
+
+A clean run reports 100% of emitted symbols matched with zero rule failures.
+Anything less means the configuration drifted — so **pass \`--min-match 1\`**.
+The flag's default is \`0.5\`, which is a floor against wholly unparseable output
+rather than the gate this doc describes; without it a 60% match rate exits \`0\`.
+See \`\${CLAUDE_PLUGIN_ROOT}/scripts/README.md\`.
+
+"Matched" means an emitted symbol's name resolved to a source token. Numeric
+magnitudes are additionally compared; colour and string values are matched by
+name only, and no rule checks that the output compiles.
+`;
+
+export function render(sections) {
+  const declared = PROSE.map(([id]) => id);
+  for (const id of declared) {
+    if (!sections.has(id)) throw new Error(`@doc-section ${id} is declared in PROSE but missing from ${SOURCE}`);
+  }
+  for (const id of sections.keys()) {
+    if (!declared.includes(id)) throw new Error(`@doc-section ${id} exists in ${SOURCE} but has no prose entry`);
+  }
+  const body = PROSE.map(([id, prose]) => `${prose}\n\n\`\`\`js\n${sections.get(id)}\n\`\`\`\n`).join('\n');
+  return `${HEADER}\n${body}\n${FOOTER}`;
+}
+
+function main() {
+  const check = process.argv.includes('--check');
+  const source = readFileSync(SOURCE, 'utf8');
+  assertCovered(source);
+  const rendered = render(sliceSections(source));
+  if (!check) {
+    writeFileSync(OUT, rendered);
+    console.log(`wrote ${OUT}`);
+    return;
+  }
+  const current = readFileSync(OUT, 'utf8');
+  if (current === rendered) {
+    console.log('references/native-adapter-config.md is up to date');
+    return;
+  }
+  console.error(
+    'references/native-adapter-config.md is stale.\n' +
+      'Run: node scripts/build-native-adapter-config.mjs',
+  );
+  process.exit(1);
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) main();

package/scripts/install.mjs

@@ -99,12 +99,13 @@ function stagePayload(srcRoot, destRoot, skip) {
   return written;
 }
 
-// Scripts that never run from a consuming repo: the installer itself, the
-// doc-card builder generator, and the renderer template it inlines (the
+// Scripts that never run from a consuming repo: the installer itself, the two
+// reference-doc generators, and the renderer template one of them inlines (the
 // renderer reaches Figma pre-inlined inside references/doc-card-builder.md).
 const PLUGIN_INTERNAL = new Set([
   'install.mjs',
   'build-doc-card-builder.mjs',
+  'build-native-adapter-config.mjs',
   'lib/doc-card-render.figma.js',
 ]);
 

package/scripts/lib/dtcg.mjs

@@ -0,0 +1,87 @@
+// Shared DTCG reading: flatten a token tree to dot-paths, resolve {alias} chains.
+// Zero dependencies. Consumed by validate-crosswalk.mjs and validate-token-output.mjs,
+// and copied alongside both when a skill installs either gate.
+
+const REF = /^\{([^}]+)\}$/;
+
+// Flatten nested DTCG groups into { "dot.path": rawValue }. Skips $-prefixed meta keys.
+//
+// A node carrying BOTH a $value and children yields its own value AND is descended
+// into — the dual-node pattern, where `text.sm` has `$value: "14px"` plus a
+// `text.sm.lineHeight` child. Stopping at the first $value drops those children,
+// which makes every alias to one unresolvable: the crosswalk gate reported them as
+// "missing from the DTCG source" though they exist, and the output validator could
+// not check them at all.
+export function flattenDtcg(obj, prefix = [], out = {}) {
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    if (!val || typeof val !== 'object') continue;
+    const path = [...prefix, key];
+    if ('$value' in val) out[path.join('.')] = val.$value;
+    flattenDtcg(val, path, out);
+  }
+  return out;
+}
+
+// Flatten nested DTCG groups into { "dot.path": effectiveType }, applying the
+// $type resolution of DTCG 5.2.2: a token's own $type wins, otherwise the
+// nearest ancestor GROUP's. A node carrying a $value is a token, not a group
+// (DTCG 6.1), so it is not an inheritance source for its children — the same
+// rule hoistDualNodes computes as `inherited`, and the two must agree or two
+// functions in this codebase disagree about the type of the same tree.
+//
+// Separate from flattenDtcg rather than folded into it: that function has four
+// consumers and both validators re-export it, so its return shape is fixed.
+//
+// LIMIT, stated rather than hidden: this reads the RAW source, so it cannot see
+// the $type carry hoistDualNodes applies during preprocessing. An untyped child
+// of a dimension-typed dual node with no enclosing group type is a dimension to
+// the pipeline and undefined here. Reference-derived typing (5.2.2 rule 1) is
+// likewise not resolved — an alias is undefined, but its referent is typed, and
+// the referent is the token an author edits.
+export function flattenDtcgTypes(obj, prefix = [], out = {}, groupType = undefined) {
+  const inherited = '$value' in obj ? groupType : (obj.$type ?? groupType);
+  for (const [key, val] of Object.entries(obj)) {
+    if (key.startsWith('$')) continue;
+    if (!val || typeof val !== 'object') continue;
+    const path = [...prefix, key];
+    if ('$value' in val) out[path.join('.')] = val.$type ?? inherited;
+    flattenDtcgTypes(val, path, out, inherited);
+  }
+  return out;
+}
+
+// Follow {alias} chains to a leaf literal. Throws on missing or circular refs.
+export function resolveValue(name, flat, seen = new Set()) {
+  if (!(name in flat)) throw new Error(`token "${name}" not found in DTCG source`);
+  const val = flat[name];
+  if (typeof val === 'string') {
+    const m = val.match(REF);
+    if (m) {
+      if (seen.has(name)) throw new Error(`circular reference at "${name}"`);
+      seen.add(name);
+      return resolveValue(m[1], flat, seen);
+    }
+  }
+  return val;
+}
+
+// A token path defined in more than one source file with differing values means
+// the build's source list spans modes. Style Dictionary dedupes these silently,
+// dropping one whole mode — 864 such collisions produced a light-only build from
+// a dark-default system.
+export function findModeCollisions(sources) {
+  const seen = new Map();
+  for (const { file, dtcg } of sources) {
+    for (const [path, value] of Object.entries(flattenDtcg(dtcg))) {
+      if (!seen.has(path)) seen.set(path, []);
+      seen.get(path).push({ file, value });
+    }
+  }
+  const collisions = [];
+  for (const [path, defs] of seen) {
+    const distinct = new Set(defs.map((d) => JSON.stringify(d.value)));
+    if (defs.length > 1 && distinct.size > 1) collisions.push({ path, defs });
+  }
+  return collisions;
+}