@radicool/throughline 0.14.0 → 0.16.0

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.14.0",
+  "version": "0.16.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/component-doc-archetypes.md

@@ -12,14 +12,16 @@ These are **seeds, not gospel** — the user's approval and the actual built
 component override them. Sources: W3C ARIA Authoring Practices Guide (roles +
 keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
 
+Seeds are clause-style shorthand; the authoring pipeline expands them into full sentences per references/doc-writing-standard.md before they enter a record.
+
 ## Button
 
 - **whenToUse:** trigger an action or event (submit, confirm, open a dialog).
-- **whenNotToUse:** navigation between pages/URLs — use a Link.
+- **whenNotToUse:** navigation between pages/URLs (use a Link).
 - **dos:** lead the label with a verb; keep one primary (highest-emphasis) button
   per view; keep labels short (≤ ~3 words).
-- **donts:** don't use a button for navigation; don't stack multiple primary
-  buttons; don't disable without telling the user why.
+- **donts:** don't use a button for navigation (use a Link); don't stack multiple
+  primary buttons (keep one per view); don't disable without telling the user why.
 - **accessibility (w3c-apg):** role `button`; Enter and Space activate; an
   icon-only button needs an `aria-label`; disabled buttons are not focusable.
 
@@ -30,8 +32,8 @@ keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
   text (use Textarea).
 - **dos:** always pair with a visible label; show format hints as helper text;
   reserve space for error text to avoid layout shift.
-- **donts:** don't use placeholder text as the only label; don't validate on every
-  keystroke before first blur.
+- **donts:** don't use placeholder text as the only label (pair with a visible
+  label); don't validate on every keystroke before first blur.
 - **accessibility (w3c-apg):** every input has a programmatically associated
   `<label>`; error state sets `aria-invalid` and links the message via
   `aria-describedby`.
@@ -42,8 +44,8 @@ keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
 - **whenNotToUse:** a single either/or action that takes effect immediately with no
   save (prefer a toggle) vs. a form choice (prefer radio/checkbox).
 - **dos:** label the control, not just the group; make the label clickable.
-- **donts:** don't use a radio group for multi-select; don't use a toggle for
-  choices that only apply after a separate Save.
+- **donts:** don't use a radio group for multi-select (use checkboxes); don't use
+  a toggle for choices needing a separate Save (use radio/checkbox).
 - **accessibility (w3c-apg):** roles `checkbox` / `radio` / `switch`; Space
   toggles; radio groups navigate with arrow keys; state exposed via
   `aria-checked`.
@@ -51,7 +53,8 @@ keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
 ## Card
 
 - **whenToUse:** group related content and actions about a single subject.
-- **whenNotToUse:** primary page layout scaffolding; a bare list of text.
+- **whenNotToUse:** primary page layout scaffolding (use a layout/grid component); a
+  bare list of text (use a List).
 - **dos:** make the primary action obvious; keep one main call-to-action per card.
 - **donts:** don't nest cards more than one level; don't make the whole card AND an
   inner button separately clickable in conflicting ways.
@@ -71,10 +74,11 @@ keyboard), Material 3, Shopify Polaris (content/usage), IBM Carbon (usage).
 ## Badge / chip / tag
 
 - **whenToUse:** short status, count, or category label (badge); a removable/
-  selectable token (chip).
+  selectable item (chip).
 - **whenNotToUse:** interactive primary actions (use a Button).
-- **dos:** keep text to a word or two; bind color to a semantic tone token.
-- **donts:** don't rely on color alone to convey status — include text/icon.
+- **dos:** keep text to a word or two; match badge color to its semantic meaning
+  (success, warning, error).
+- **donts:** don't rely on color alone to convey status (include text or an icon).
 - **accessibility:** a removable chip's remove control needs an accessible name
   (e.g. "Remove <label>"); status conveyed with text, not color only (WCAG 1.4.1).
 

package/references/component-doc-schema.md

@@ -58,9 +58,17 @@ deterministically. JSON is equally machine-legible for AI consumers.
 - **Lifecycle:** `status` (`draft`|`beta`|`stable`|`deprecated`), `updatedAt` (ISO date).
 - **`provenance`** — per-block author source, one of `imported`, `ai-inferred`,
   `best-practice`, `w3c-apg`, `framework`, `user`, or a `+`-joined combination
-  (e.g. `best-practice+user`). Regeneration re-infers `ai-inferred`/`framework`
-  blocks and **never overwrites** a block whose provenance includes `user` or
-  `imported`.
+  (e.g. `best-practice+user`). Regeneration **re-infers** a block whose
+  provenance includes `ai-inferred`, `framework`, `best-practice`, or `w3c-apg`,
+  and **never overwrites** one whose provenance includes `user` or `imported`.
+  Every value is assigned to exactly one of those two tiers: generated content is
+  re-inferred, human input (`user`) and pre-existing external content
+  (`imported`) are protected. Protection takes precedence: a combination that
+  contains both — `best-practice+user`, say — is protected. A block is
+  re-inferred only when it carries no `user` or `imported` marker at all. A
+  protected block may still be rewritten when the user approves the rewrite at
+  the record-approval gate; the result is stamped `imported+user`, which is
+  protected from then on and never re-proposed.
 
 Deferred to a later version (do not emit in v1): `anatomy`, `content` (writing
 guidelines), `examples`.
@@ -84,7 +92,7 @@ Figma-connected skill computing the identical hash over the description content.
 |---|---|---|---|---|
 | summary, description | ✔ | ✔ | ✔ | ✔ |
 | whenToUse / whenNotToUse | ✔ | ✔ | ✔ | ✔ |
-| variants, states (meanings) | ✔ compact | ✔ legend | ✔ argTypes | ✔ |
+| variants, states (meanings) | — | ✔ legend | ✔ argTypes | ✔ |
 | dos / donts | ✔ | ✔ | ✔ | ✔ |
 | accessibility | ✔ | ✔ | ✔ | ✔ |
 | tokensUsed | — | — | ✔ | ✔ |
@@ -105,7 +113,7 @@ The manifest stores pointers + per-surface fingerprints, never content:
     "fingerprint": "<canonical fingerprint at last render>",
     "surfaces": {
       "figmaDescription": { "src": "<fp>", "render": "<hash of description text>" },
-      "docCard":          { "src": "<fp>", "render": "<hash of card content>" },
+      "docCard":          { "src": "<fp>", "render": "<hash of card content>", "renderer": "4" },
       "storybookMdx":     { "src": "<fp>", "render": "<hash of mdx file>", "file": "packages/ui/src/Button/Button.mdx" }
     }
   }
@@ -116,6 +124,11 @@ The manifest stores pointers + per-surface fingerprints, never content:
 - `render` — a hash of the surface's rendered content at render time (detects
   **edited**, for surfaces the tooling can re-read).
 - `file` — repo-relative path for code surfaces so `docs:check` can re-read them.
+- `renderer` — (docCard only) the layout version of the builder that last
+  rendered the card: `DOC_CARD_RENDERER_VERSION` in `scripts/lib/doc-card-plan.mjs`,
+  currently `"4"`. Additive and optional — absence means the card predates the
+  versioned builder. Stamped from the builder's returned summary, never by
+  re-reading the card.
 
 ## Drift + reconciliation contract
 
@@ -123,6 +136,11 @@ The manifest stores pointers + per-surface fingerprints, never content:
 - **canonical-changed** — the `.doc.json` fingerprint ≠ `doc.fingerprint`.
 - **stale** — `surface.src` ≠ current canonical fingerprint.
 - **edited** — a re-readable surface's current content hash ≠ `surface.render`.
+- **layout-upgrade-available** — informational, never failing, docCard only:
+  `surfaces.docCard.renderer` is missing or lower than the current
+  `DOC_CARD_RENDERER_VERSION`. The card's content is not in drift — its layout
+  predates the current builder. Re-render on next touch (no unprompted Figma
+  writes; untouched brownfield cards must not generate a standing warning wall).
 - **missing-surface** — a repo surface that declares a `file` which is now gone.
   Failing, and distinct from `edit-unverified`: the surface *was* re-readable and
   its rendered output has been deleted, not merely unreadable this run.