@radicool/throughline 0.15.0 → 0.17.0

package/README.md

@@ -205,7 +205,8 @@ Future improvements and planned capabilities. Have a request? **[Open an issue](
 - **Expanded component starters** — a larger foundational kit out of the box.
 - **Richer status & auditing** — more from `/design-system-status`, including drift detection between Figma and code.
 - **Built-in accessibility checks** — automatic a11y validation when tokens and components are created, so modes can't be built with poor color contrast and components can't ship with accessibility gaps. Catches issues at creation time rather than in review.
-- **One library, many platforms** — support a single Figma token library that syncs to multiple platforms at once (React, Android, iOS), with a component lifecycle flexible enough to target per platform — every platform, or native-only components that don't need a React counterpart.
+- **Token fan-out to more platforms** — the DTCG token source is platform-neutral, and web targets are in daily use. Native targets are **validated per build, not assumed** — iOS/Swift is a curated adapter whose Style Dictionary configuration ships as tested code, and Android/Kotlin uses the same configuration through the Tier 2 protocol — `tokens:validate-output` checks generated native output against its source, because the stock transforms have been measured emitting wrong-but-compiling values.
+- **Native component code generation** — producing a SwiftUI view or a Compose composable the way Storybook components are produced for React. This does not exist yet; it is a separate, larger effort than token fan-out, and the two were previously described as one roadmap item.
 
 Versioning follows [Semantic Versioning](https://semver.org). The current version lives in [`.claude-plugin/plugin.json`](.claude-plugin/plugin.json); every release is recorded in [`CHANGELOG.md`](CHANGELOG.md).
 

package/adapters/codex/prompts/token-crosswalk-builder.md

@@ -65,6 +65,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 (they are zero-dependency and version with the user's repo so their CI can run them):
 
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
+  `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`

package/adapters/codex/prompts/token-sync-layer.md

@@ -44,8 +44,8 @@ Ask which platform(s) the user is building for. Read
 - **Curated (Tier 1):** `shadcn`, `tailwind`, `mui`, `vanilla-css`, `ios-swift`.
   Vetted presets — high confidence.
 - **Generated (Tier 2):** any other framework (Ant Design, Chakra, HeroUI,
-  Android/Kotlin, Flutter, etc.). The skill generates an adapter and verifies it
-  against a real component before trusting it.
+  Android/Kotlin, Flutter, etc.). The skill generates an adapter and
+  verifies it against a real component before trusting it.
 
 **Always tell the user which tier they're on.** If they name a curated one, say
 it'll be solid. If they name anything else, be honest: "That's not one I have a
@@ -139,11 +139,53 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
+**Native targets import the shipped configuration; they do not transcribe it.**
+Copy `.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/` (see Step 4) and call it. The stock `ios-swift`
+and `compose` transform groups emit every `px`-authored dimension at ×16 its
+value — valid, compiling, silently wrong — and mishandle `color-mix()` and
+dual-node DTCG the same way. Never build a native platform from a stock
+`transformGroup`.
+
+```js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of MODES) {                     // e.g. ['light', 'dark']
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),    // guards against a mode collapse
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: `ios/${mode}/` }),
+      // android also requires packageName:
+      // android: nativePlatform({ platform: 'android-kotlin',
+      //   buildPath: `android/${mode}/`, packageName: 'com.example.tokens' }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+```
+
+**One build per mode combination, and never a glob.** Style Dictionary dedupes
+by dot-path, so a single build over the whole token directory collapses light
+and dark into whichever file sorted last, silently dropping a mode. Passing each
+mode's sources through `nativeSources` turns that into a thrown error naming the
+colliding paths. The `dtcg/resolve-dual-node` preprocessor throws too, on its
+own collision: a dual node's hoisted child renamed to a camel-joined name that
+an existing sibling or an earlier hoist in the same pass already has. Then run
+`tokens:validate-output` against each generated file with that same source
+list. See `.throughline/references/native-adapter-config.md`.
+
 **Execution model — subagent dispatch with model routing.** Generating each
 platform's output is independent and verifiable. If your host supports subagent
 dispatch, dispatch **one `code-executor` per adapter** — each produces its
-platform's files and verifies them (the config builds, the expected files
-appear, references resolve for web / flatten for native) — then a **`reviewer`**
+platform's files and verifies them (for web: the config builds, the expected
+files appear, references resolve; for native: `tokens:validate-output` passes —
+"the config builds" is not verification, it is the condition under which all
+four known native failure modes ship silently) — then a **`reviewer`**
 to check each before combining. Choose each subagent's model from its role tier
 per `.throughline/references/agent-routing.md` (`code-executor` → fast,
 `reviewer` → balanced), and only dispatch once each adapter's spec is complete
@@ -159,6 +201,24 @@ as **build artifacts** — regenerated every sync, never hand-edited. Wire
 `packages/tokens/package.json` to export them so the UI package, Storybook, and
 any future app consume them.
 
+**Install the native token toolkit — all four files, as a set.** Copy
+`.throughline/scripts/validate-token-output.mjs` into
+`packages/tokens/scripts/`, and
+`.throughline/scripts/lib/dtcg.mjs`,
+`.throughline/scripts/lib/native-literal.mjs`, and
+`.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/`. `sd-native.mjs` and the validator both import
+`dtcg.mjs` and `native-literal.mjs`, so copying any of them without the others
+breaks at import. Then register the gate so it stays live on every future sync:
+
+```json
+"tokens:validate-output": "node scripts/validate-token-output.mjs --min-match 1"
+```
+
+Invoke it once per native output file, passing the same `--source` list that
+file's build used. `--min-match 1` is what makes it a gate: the flag defaults to
+`0.5`, so without it a 60% match rate exits `0`.
+
 ## Step 4.5 — Icon code sync (install check + custom SVGR)
 
 Icons reach code differently from tokens, so handle them here if the system has

package/adapters/cursor/.cursor/rules/token-crosswalk-builder.mdc

@@ -69,6 +69,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 (they are zero-dependency and version with the user's repo so their CI can run them):
 
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
+  `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`

package/adapters/cursor/.cursor/rules/token-sync-layer.mdc

@@ -48,8 +48,8 @@ Ask which platform(s) the user is building for. Read
 - **Curated (Tier 1):** `shadcn`, `tailwind`, `mui`, `vanilla-css`, `ios-swift`.
   Vetted presets — high confidence.
 - **Generated (Tier 2):** any other framework (Ant Design, Chakra, HeroUI,
-  Android/Kotlin, Flutter, etc.). The skill generates an adapter and verifies it
-  against a real component before trusting it.
+  Android/Kotlin, Flutter, etc.). The skill generates an adapter and
+  verifies it against a real component before trusting it.
 
 **Always tell the user which tier they're on.** If they name a curated one, say
 it'll be solid. If they name anything else, be honest: "That's not one I have a
@@ -143,11 +143,53 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
+**Native targets import the shipped configuration; they do not transcribe it.**
+Copy `.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/` (see Step 4) and call it. The stock `ios-swift`
+and `compose` transform groups emit every `px`-authored dimension at ×16 its
+value — valid, compiling, silently wrong — and mishandle `color-mix()` and
+dual-node DTCG the same way. Never build a native platform from a stock
+`transformGroup`.
+
+```js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of MODES) {                     // e.g. ['light', 'dark']
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),    // guards against a mode collapse
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: `ios/${mode}/` }),
+      // android also requires packageName:
+      // android: nativePlatform({ platform: 'android-kotlin',
+      //   buildPath: `android/${mode}/`, packageName: 'com.example.tokens' }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+```
+
+**One build per mode combination, and never a glob.** Style Dictionary dedupes
+by dot-path, so a single build over the whole token directory collapses light
+and dark into whichever file sorted last, silently dropping a mode. Passing each
+mode's sources through `nativeSources` turns that into a thrown error naming the
+colliding paths. The `dtcg/resolve-dual-node` preprocessor throws too, on its
+own collision: a dual node's hoisted child renamed to a camel-joined name that
+an existing sibling or an earlier hoist in the same pass already has. Then run
+`tokens:validate-output` against each generated file with that same source
+list. See `.throughline/references/native-adapter-config.md`.
+
 **Execution model — subagent dispatch with model routing.** Generating each
 platform's output is independent and verifiable. If your host supports subagent
 dispatch, dispatch **one `code-executor` per adapter** — each produces its
-platform's files and verifies them (the config builds, the expected files
-appear, references resolve for web / flatten for native) — then a **`reviewer`**
+platform's files and verifies them (for web: the config builds, the expected
+files appear, references resolve; for native: `tokens:validate-output` passes —
+"the config builds" is not verification, it is the condition under which all
+four known native failure modes ship silently) — then a **`reviewer`**
 to check each before combining. Choose each subagent's model from its role tier
 per `.throughline/references/agent-routing.md` (`code-executor` → fast,
 `reviewer` → balanced), and only dispatch once each adapter's spec is complete
@@ -163,6 +205,24 @@ as **build artifacts** — regenerated every sync, never hand-edited. Wire
 `packages/tokens/package.json` to export them so the UI package, Storybook, and
 any future app consume them.
 
+**Install the native token toolkit — all four files, as a set.** Copy
+`.throughline/scripts/validate-token-output.mjs` into
+`packages/tokens/scripts/`, and
+`.throughline/scripts/lib/dtcg.mjs`,
+`.throughline/scripts/lib/native-literal.mjs`, and
+`.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/`. `sd-native.mjs` and the validator both import
+`dtcg.mjs` and `native-literal.mjs`, so copying any of them without the others
+breaks at import. Then register the gate so it stays live on every future sync:
+
+```json
+"tokens:validate-output": "node scripts/validate-token-output.mjs --min-match 1"
+```
+
+Invoke it once per native output file, passing the same `--source` list that
+file's build used. `--min-match 1` is what makes it a gate: the flag defaults to
+`0.5`, so without it a 60% match rate exits `0`.
+
 ## Step 4.5 — Icon code sync (install check + custom SVGR)
 
 Icons reach code differently from tokens, so handle them here if the system has

package/adapters/generic/skills/token-crosswalk-builder/SKILL.md

@@ -65,6 +65,8 @@ Copy these from `.throughline/scripts/` into the user's repo **verbatim**
 (they are zero-dependency and version with the user's repo so their CI can run them):
 
 - `lib/crosswalk.mjs` → `packages/tokens/scripts/lib/crosswalk.mjs`
+- `lib/dtcg.mjs` → `packages/tokens/scripts/lib/dtcg.mjs` (required by
+  `validate-crosswalk.mjs` — copying the validator without it breaks the gate at import)
 - `validate-crosswalk.mjs` → `packages/tokens/scripts/validate-crosswalk.mjs`
 - `build-reverse-index.mjs` → `packages/tokens/scripts/build-reverse-index.mjs`
 - `guard-token-removal.mjs` → `packages/tokens/scripts/guard-token-removal.mjs`

package/adapters/generic/skills/token-sync-layer/SKILL.md

@@ -44,8 +44,8 @@ Ask which platform(s) the user is building for. Read
 - **Curated (Tier 1):** `shadcn`, `tailwind`, `mui`, `vanilla-css`, `ios-swift`.
   Vetted presets — high confidence.
 - **Generated (Tier 2):** any other framework (Ant Design, Chakra, HeroUI,
-  Android/Kotlin, Flutter, etc.). The skill generates an adapter and verifies it
-  against a real component before trusting it.
+  Android/Kotlin, Flutter, etc.). The skill generates an adapter and
+  verifies it against a real component before trusting it.
 
 **Always tell the user which tier they're on.** If they name a curated one, say
 it'll be solid. If they name anything else, be honest: "That's not one I have a
@@ -139,11 +139,53 @@ register the platform, transform group, format, and `outputReferences`
 flattens). Web adapters emit `:root`/`.dark` (or `[data-theme]`); the shadcn
 adapter also emits a Tailwind preset.
 
+**Native targets import the shipped configuration; they do not transcribe it.**
+Copy `.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/` (see Step 4) and call it. The stock `ios-swift`
+and `compose` transform groups emit every `px`-authored dimension at ×16 its
+value — valid, compiling, silently wrong — and mishandle `color-mix()` and
+dual-node DTCG the same way. Never build a native platform from a stock
+`transformGroup`.
+
+```js
+import StyleDictionary from 'style-dictionary';
+import { registerNativeTransforms, nativePlatform, nativeSources }
+  from './scripts/lib/sd-native.mjs';
+
+registerNativeTransforms(StyleDictionary);
+
+for (const mode of MODES) {                     // e.g. ['light', 'dark']
+  const sd = new StyleDictionary({
+    source: nativeSources(sourcesFor(mode)),    // guards against a mode collapse
+    preprocessors: ['dtcg/resolve-dual-node'],
+    platforms: {
+      ios: nativePlatform({ platform: 'ios-swift', buildPath: `ios/${mode}/` }),
+      // android also requires packageName:
+      // android: nativePlatform({ platform: 'android-kotlin',
+      //   buildPath: `android/${mode}/`, packageName: 'com.example.tokens' }),
+    },
+  });
+  await sd.buildAllPlatforms();
+}
+```
+
+**One build per mode combination, and never a glob.** Style Dictionary dedupes
+by dot-path, so a single build over the whole token directory collapses light
+and dark into whichever file sorted last, silently dropping a mode. Passing each
+mode's sources through `nativeSources` turns that into a thrown error naming the
+colliding paths. The `dtcg/resolve-dual-node` preprocessor throws too, on its
+own collision: a dual node's hoisted child renamed to a camel-joined name that
+an existing sibling or an earlier hoist in the same pass already has. Then run
+`tokens:validate-output` against each generated file with that same source
+list. See `.throughline/references/native-adapter-config.md`.
+
 **Execution model — subagent dispatch with model routing.** Generating each
 platform's output is independent and verifiable. If your host supports subagent
 dispatch, dispatch **one `code-executor` per adapter** — each produces its
-platform's files and verifies them (the config builds, the expected files
-appear, references resolve for web / flatten for native) — then a **`reviewer`**
+platform's files and verifies them (for web: the config builds, the expected
+files appear, references resolve; for native: `tokens:validate-output` passes —
+"the config builds" is not verification, it is the condition under which all
+four known native failure modes ship silently) — then a **`reviewer`**
 to check each before combining. Choose each subagent's model from its role tier
 per `.throughline/references/agent-routing.md` (`code-executor` → fast,
 `reviewer` → balanced), and only dispatch once each adapter's spec is complete
@@ -159,6 +201,24 @@ as **build artifacts** — regenerated every sync, never hand-edited. Wire
 `packages/tokens/package.json` to export them so the UI package, Storybook, and
 any future app consume them.
 
+**Install the native token toolkit — all four files, as a set.** Copy
+`.throughline/scripts/validate-token-output.mjs` into
+`packages/tokens/scripts/`, and
+`.throughline/scripts/lib/dtcg.mjs`,
+`.throughline/scripts/lib/native-literal.mjs`, and
+`.throughline/scripts/lib/sd-native.mjs` into
+`packages/tokens/scripts/lib/`. `sd-native.mjs` and the validator both import
+`dtcg.mjs` and `native-literal.mjs`, so copying any of them without the others
+breaks at import. Then register the gate so it stays live on every future sync:
+
+```json
+"tokens:validate-output": "node scripts/validate-token-output.mjs --min-match 1"
+```
+
+Invoke it once per native output file, passing the same `--source` list that
+file's build used. `--min-match 1` is what makes it a gate: the flag defaults to
+`0.5`, so without it a 60% match rate exits `0`.
+
 ## Step 4.5 — Icon code sync (install check + custom SVGR)
 
 Icons reach code differently from tokens, so handle them here if the system has

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@radicool/throughline",
-  "version": "0.15.0",
+  "version": "0.17.0",
   "description": "Build a complete design system end to end — author in Figma, sync tokens to code, generate Storybook. Usable from Claude Code, Cursor, Codex, or any AGENTS.md agent.",
   "type": "module",
   "bin": {

package/references/manifest-schema.md

@@ -291,8 +291,8 @@ bailing or running silently.
 
 ### `sync`
 - `platforms` — array of adapter targets configured, e.g.
-  `["shadcn", "ios-swift"]`. Curated adapters map to vetted presets; any other
-  name is a generated (Tier 2) adapter.
+  `["shadcn", "android-kotlin"]`. Curated adapters map to vetted presets; any
+  other name is a generated (Tier 2) adapter.
 - `customAdapters` — names of validated generated adapters saved to
   `packages/tokens/adapters/` for reuse, so future syncs don't regenerate them.
 - `lastRun` — ISO timestamp the sync command last ran.