@hegemonart/get-design-done 1.33.6 → 1.34.2

package/connections/xcode-simulator.md

@@ -0,0 +1,108 @@
+# Xcode Simulator — Connection Specification
+
+This file is the connection specification for the **Xcode iOS Simulator** within the get-design-done pipeline. Its role is to provide *rendered* evidence for native-iOS work: it lets the verify stage capture a SwiftUI snapshot from a booted simulator so a native screen can be audited against its design intent, the same way `connections/preview.md` provides browser screenshots for web. It is the iOS half of the native-verify connection pair (the Android half is `connections/android-emulator.md`).
+
+**It is OPTIONAL.** Most users — and CI — have no Xcode installed. Per **D-03** this connection is **never hard-required**: when it is absent the verify stage degrades gracefully to code-only structural verification, and no blocker is raised unless a `must_have` explicitly demands rendered evidence. The `swift-executor` agent generates compilable SwiftUI **without** any simulator (D-04/D-10); the simulator only adds rendered confirmation when it happens to be available.
+
+See `connections/preview.md` for the sibling browser-preview connection this spec mirrors. (The connection index + capability matrix is maintained separately as part of phase closeout, not by this doc.)
+
+---
+
+## Setup
+
+**Prerequisites (all OPTIONAL — absence is the common, supported case):**
+
+- **macOS** — the iOS Simulator runs only on macOS. On Linux/Windows this connection is permanently `not_configured`; that is expected and never an error.
+- **Xcode** (full app, not just the Command Line Tools) — provides the Simulator runtimes.
+- **`simctl`** — Apple's simulator-control CLI, available once Xcode is installed.
+
+**Why it is optional:** GDD's default test suite and the typical design user have no Xcode. Hard-requiring a simulator would block native-iOS work for the majority of environments. The pipeline therefore treats rendered iOS evidence as an **enhancement, not a requirement** (mirroring `connections/preview.md`'s stance) — exactly the D-03 guarantee.
+
+---
+
+## Tools
+
+This connection is driven by Apple's simulator CLI rather than an MCP server.
+
+| Capability | Command (illustrative) | Returns | Pipeline use |
+|------------|------------------------|---------|--------------|
+| Availability check | list installed simulator devices | device list (may be empty) | **Lightweight probe** — see below |
+| Boot a device | boot a named device by UDID | boot confirmation | Bring a simulator up before snapshot capture (verify stage only) |
+| Capture a snapshot | screenshot the booted device | PNG image | Rendered evidence for the verify stage |
+| Shut down | shut down the booted device | confirmation | Clean up after capture |
+
+The **availability check** is preferred for probing because it does not boot a device — it only reports whether the toolchain and runtimes are present. Booting and capture happen **only** in the verify stage, **only** when a `must_have` calls for rendered evidence and the probe reported `available`.
+
+> The default `npm test` suite **never** invokes these commands. Static validation of the native executors is hermetic (D-10) — frontmatter + reference checks only, no Xcode, no simulator, no spawn.
+
+---
+
+## Which Stages Use This Connection
+
+| Stage | Skill/Agent | Purpose | Simulator required? |
+|-------|------------|---------|---------------------|
+| design | `agents/swift-executor.md` | Generate compilable SwiftUI views | **No** — code generation needs no simulator (D-04/D-10) |
+| verify | `agents/design-verifier.md` (native-verify branch) | Rendered SwiftUI snapshot audit **when available**, else degrade | No — optional; degrades per Fallback below |
+
+This connection feeds the **34.1-05 native-verify branch**: verify probes it at stage entry and either captures a rendered snapshot (if `available`) or follows the degrade path. The `swift-executor` (design stage) never touches it.
+
+---
+
+## Availability Probe
+
+Probe **before** any boot/capture, and write the result to `.design/STATE.md` `<connections>` immediately.
+
+```
+Step P1 — toolchain check:
+  detect whether Xcode + the simulator CLI are present on this machine
+  → not macOS, or Xcode absent          → xcode-simulator: not_configured
+  → present                             → proceed to Step P2
+
+Step P2 — runtime/device check:
+  list installed simulator devices (does NOT boot one)
+  → list returns successfully (even empty)   → xcode-simulator: available
+  → command errors / permission denied       → xcode-simulator: unavailable
+```
+
+**Three-value status schema** (mirrors `connections/preview.md`'s three-value model):
+
+| Value | Meaning |
+|-------|---------|
+| `available` | Xcode + the simulator CLI are present and the device-list command succeeded (array, even empty). Rendered snapshots are possible. |
+| `unavailable` | The toolchain is present but the device-list command errored (no runtimes installed, permission denied, internal error). Treat as no-simulator. |
+| `not_configured` | Not macOS, or Xcode is not installed. The common, fully-supported case — never an error. |
+
+Write the result to `.design/STATE.md`:
+
+```xml
+<connections>
+preview: available
+xcode-simulator: not_configured
+</connections>
+```
+
+---
+
+## Fallback Behavior
+
+When `xcode-simulator` is `not_configured` or `unavailable`, the verify stage **degrades gracefully — no error is raised, no blocker is appended** (the D-03 guarantee: this connection **never hard-requires a simulator**). The degrade is a two-step ladder, exactly mirroring how `connections/preview.md` falls back when no browser is available:
+
+1. **Snapshot-diff on a supplied screenshot** — if the brief/context provides a reference screenshot of the intended iOS screen, the verify stage diffs against that supplied image (using the Phase-23 visual primitives). No live simulator is needed.
+2. **Code-only structural audit** — if no screenshot exists either, the verify stage falls back to a **code-only** audit of the generated SwiftUI: structural checks against `reference/platforms.md` (safe-area handling present, no left-edge gesture conflict, Dynamic Type styles used, no sub-11pt text) and token-bridge conformance, with **no rendered evidence**. The native screen is verified **without a simulator**.
+
+Phase-4B-style rendered-evidence checks are marked `[SKIPPED — simulator not available]`; the verifier continues to gap analysis with partial scores. **No `<blocker>` is appended for a missing simulator** — rendered iOS evidence is an enhancement, not a requirement. The **only** exception: if a `must_have` *explicitly* requires simulator-rendered evidence, THEN (and only then) the verifier appends a blocker noting the simulator is unavailable.
+
+---
+
+## STATE.md Integration
+
+Every stage that uses this connection writes its probe result to `.design/STATE.md` under `<connections>` (see schema above). The verify stage **re-probes at stage entry** rather than blindly trusting a prior status, because toolchain availability can change between sessions — however, a status already written earlier in the **same session** can be trusted for the rest of that session (mirroring `connections/preview.md`).
+
+---
+
+## Caveats and Pitfalls
+
+1. **Absence is the default, not a failure.** On the vast majority of machines this connection is `not_configured`. That is the supported, expected state — the pipeline produces SwiftUI and verifies it code-only without ever touching a simulator (D-03/D-10). Never treat `not_configured` as an error or a reason to block.
+2. **The probe must not boot a device.** Use the device-**list** command for probing; booting a simulator just to check availability is slow and unnecessary. Boot only in the verify stage, only when rendered evidence is actually required and the probe said `available`.
+3. **Snapshots are screenshots — save by path.** A captured simulator snapshot is a full PNG. Save it to `.design/screenshots/<screen>.png` and reference it by path in markdown; do not embed base64 inline. `.design/` is gitignored, so snapshots are not committed.
+4. **The default test suite never spawns a simulator.** All native-executor validation is structural and hermetic (D-10). A live simulator is exclusively the verify stage's opt-in, degraded-mode enhancement (D-03) — it is never part of `npm test`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hegemonart/get-design-done",
-  "version": "1.33.6",
+  "version": "1.34.2",
   "description": "A design-quality pipeline for AI coding agents: brief, plan, implement, and verify UI work against your design system.",
   "author": "Hegemon",
   "homepage": "https://github.com/hegemonart/get-design-done",

package/reference/email-design.md

@@ -0,0 +1,219 @@
+# Email Design — Constraint Catalogue
+
+This reference is the **email-constraint catalogue**: the hard email-client rules an
+email template MUST honor. Email is a *constrained* HTML/CSS surface — the modern
+HTML/CSS the web executor emits (flexbox, grid, `<style>` sheets, `position`) is
+dropped or mis-rendered by most email clients. This file is the **authority** that the
+email-executor (Phase 34.2-02) generates against and the design-verifier's email branch
+(34.2-03) audits against; neither re-derives these rules. The deterministic subset of
+this catalogue is checked by [`scripts/lib/email/validate-email-html.cjs`](../scripts/lib/email/validate-email-html.cjs),
+whose emitted `rule` ids are the constraint-ids defined below (the spec is the authority).
+
+It is the sibling of [`reference/platforms.md`](./platforms.md). The two files have
+distinct jobs and must not be confused:
+
+| File | Job |
+| --- | --- |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge for native/web screens. |
+| `reference/email-design.md` (Phase 34.2, this file) | The email **constraint catalogue** — table-based layout, inline styles, MSO conditional comments, dark-mode `color-scheme`, ~600px max-width, image/alt rules, and top-20-client quirks. *Structural* knowledge an email template implements. |
+
+Per **D-02** there is **no `mjml` runtime dependency**: MJML source is the agent's
+canonical artifact and the HTML is derived by the agent, not a build step. Per **D-03**
+email verify is this catalogue's *static* validator plus an *optional* Litmus /
+Email-on-Acid render-test connection that degrades to the static validator when absent.
+Per **D-10** the static checks are deterministic (same HTML string → same result), with
+no network and no `mjml`, so the default `npm test` stays green on any machine.
+
+Each constraint carries a **rule-id** (`EM-<CLASS>-NN`). Section 8 marks exactly which
+ids the static validator asserts versus which are render-tested guidance only.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references*; Phase 23 shipped the token engine; Phase 34.1
+added native generators. Email is the remaining untouched product surface, and its
+constraints are unlike both web and native: a fifteen-year-old rendering engine
+(Outlook/Word), aggressive `<head>` stripping (Gmail), and a long tail of per-client
+quirks. Instead of each email being authored from memory, the constraints live once
+here (the catalogue) and once in the validator (the statically-checkable subset), and
+the executor + verifier consume them. This file is the single SC#9-email authority.
+
+The catalogue is **prose + tables**, not an implementation. Illustrative snippets are
+kept to 2–3 lines. The implementation is `validate-email-html.cjs`.
+
+---
+
+## 2. Layout — tables, not flexbox/grid/position
+
+Email layout uses nested `role="presentation"` **tables**, never the modern CSS box
+primitives. `display:flex`, `display:grid`, and `position:absolute|fixed|sticky` are
+dropped or mis-rendered by Outlook (Word engine), older Gmail, and many mobile clients,
+collapsing a layout to a single column or off-screen elements.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-LAYOUT-01** | Layout is built from `role="presentation"` tables. The forbidden modern primitives — `display:flex`, `display:grid`, `position:absolute`, `position:fixed` (and `position:sticky`) — MUST NOT appear in any `style`. *(Statically checkable: their presence is flagged.)* |
+| EM-LAYOUT-02 | Body content sits in a fixed-/max-width container of ~**600px** (the safe width across the desktop preview pane and most mobile clients). Wider tables clip in Outlook and force horizontal scroll on mobile. |
+| EM-LAYOUT-03 | Use `cellpadding="0" cellspacing="0" border="0"` on layout tables and prefer cell `padding` over margins (margins are inconsistently honored). |
+| EM-LAYOUT-04 | Single primary column on mobile; multi-column desktop layouts degrade to stacked rows. Do not rely on `float` for columns (use side-by-side `<td>`s or `align`). |
+| EM-LAYOUT-05 | Set explicit `width` on tables/cells; never assume an intrinsic content width. Outlook ignores CSS `max-width` on many elements — pair it with a `<!--[if mso]>` ghost table (see §4). |
+
+```html
+<table role="presentation" width="600" cellpadding="0" cellspacing="0" border="0"
+       style="max-width:600px;margin:0 auto;"><tr><td>…</td></tr></table>
+```
+
+---
+
+## 3. Styling — inline, not a `<style>` block
+
+Visual styling lives in **inline `style="…"` attributes** on each element, NOT in a
+`<head><style>` sheet. Gmail (and several webmail clients) strip or heavily limit
+`<head>` styles, so any rule that *must* apply is inlined. A `<style>` block is
+**tolerated only** for progressive enhancement that degrades gracefully — chiefly
+`@media` queries for responsive/dark-mode — never as the primary styling mechanism.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-STYLE-01** | Core/visual styling is inline. A `<style>` block used as the PRIMARY styling mechanism (non-`@media` rules, or a large sheet) is forbidden because Gmail strips it. *(Statically checkable: a non-trivial `<style>` block carrying non-`@media` rules is flagged; a small `@media`-only block is tolerated.)* |
+| EM-STYLE-02 | Avoid CSS shorthand that clients mangle (`background` shorthand, unitless line-heights in some clients); prefer longhand (`background-color`). |
+| EM-STYLE-03 | No external stylesheets (`<link rel="stylesheet">`) and no `@import` — clients strip them. |
+| EM-STYLE-04 | A small `@media`-only `<style>` for responsive breakpoints / dark-mode is the one accepted `<style>` use; it must enhance, not be required for, a readable layout. |
+
+---
+
+## 4. Outlook / MSO conditional comments
+
+Outlook on Windows renders with Microsoft Word's HTML engine. It needs **MSO
+conditional comments** to apply Outlook-specific fallbacks (ghost tables for centering
+and width, VML for background images and bulletproof buttons) and to hide modern markup
+it would mangle.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-MSO-01** | A full email document MUST include at least one MSO conditional comment — `<!--[if mso]> … <![endif]-->` and/or `<!--[if !mso]><!--> … <!--<![endif]-->`. *(Statically checkable: absence in a full-email document is flagged.)* |
+| EM-MSO-02 | Use `<!--[if mso]>` **ghost tables** to give Outlook an explicit fixed width and centering that it would otherwise drop from CSS `max-width`/`margin:auto`. |
+| EM-MSO-03 | Use **VML** (`<v:roundrect>`, `<v:fill>`) inside `<!--[if mso]>` for rounded "bulletproof" buttons and background images, since Outlook ignores `border-radius` and CSS `background-image`. |
+| EM-MSO-04 | Add the MSO DPI/namespace head fixes (`o:OfficeDocumentSettings`, `xmlns:v`/`xmlns:o`, `mso-line-height-rule:exactly`) to stabilize spacing and image scaling. |
+
+```html
+<!--[if mso]><table role="presentation" width="600"><tr><td><![endif]-->
+  <!-- modern markup here -->
+<!--[if mso]></td></tr></table><![endif]-->
+```
+
+---
+
+## 5. Dark mode
+
+Clients invert or remap colors in dark mode inconsistently (Outlook.com fully inverts;
+Apple Mail and Gmail partially; some not at all). Declare a **`color-scheme`** signal so
+clients keep the intended palette, and use `prefers-color-scheme` for explicit dark
+overrides.
+
+| Rule-id | Constraint |
+| --- | --- |
+| **EM-DARK-01** | Declare a `color-scheme` signal: a `<meta name="color-scheme" content="light dark">` and/or a `color-scheme: light dark;` CSS declaration and/or a `@media (prefers-color-scheme: dark)` block. At least one MUST be present. *(Statically checkable: total absence of any color-scheme signal is flagged. A `<meta name="color-scheme">` alone satisfies it — decoupled from any `<style>` block.)* |
+| EM-DARK-02 | Pair `color-scheme` with `supported-color-schemes` (meta) for Apple Mail / Outlook. |
+| EM-DARK-03 | Beware forced color inversion: set explicit `background-color` AND `color` on text containers so an inverting client cannot produce unreadable low-contrast pairs. |
+| EM-DARK-04 | Provide dark-mode-friendly logos (transparent PNG or a `prefers-color-scheme` image swap) so a dark background does not hide a dark logo. |
+
+---
+
+## 6. Images & accessibility
+
+Images are often blocked by default and must degrade gracefully; accessibility rules
+prevent broken layouts and unreadable content. *(Guidance — not all statically
+asserted; see §8.)*
+
+| Rule-id | Constraint |
+| --- | --- |
+| EM-IMG-01 | Every `<img>` carries explicit `width` and `height` attributes (Outlook needs them; prevents reflow when images load). |
+| EM-IMG-02 | Every `<img>` carries meaningful `alt` text (shown when images are blocked) and `display:block` to avoid the baseline gap below images. |
+| EM-IMG-03 | Serve retina images at 2× and constrain with `width`/`height` so they render crisp without breaking the layout. |
+| EM-IMG-04 | Buttons are **bulletproof** (table/`<a>` with padding + VML fallback for Outlook), never an image-only CTA that vanishes when images are blocked. |
+| EM-A11Y-01 | Set the document `lang`, a real `<title>`, and a logical heading/reading order; ensure WCAG-AA text contrast that survives dark-mode inversion. |
+
+---
+
+## 7. Top-20 client quirks
+
+The top-20-by-market-share email clients and their headline quirks. *(Catalogue —
+most are render-tested via the optional Litmus / Email-on-Acid connection (34.2-02),
+NOT statically checkable; see §8.)*
+
+| Rule-id | Client | Headline quirk |
+| --- | --- | --- |
+| EM-CLIENT-01 | Apple Mail (iOS) | Most standards-compliant; honors `<style>` + media queries; auto-scales text — set `meta viewport`. |
+| EM-CLIENT-02 | Apple Mail (macOS) | WebKit-based, robust; respects `prefers-color-scheme`; watch auto-link of dates/addresses. |
+| EM-CLIENT-03 | Gmail (web) | **Strips `<head>` styles** beyond a limited `<style>`; clips messages over ~102KB ("[Message clipped]"); requires inline styles. |
+| EM-CLIENT-04 | Gmail (mobile app, default account) | Supports a `<style>` block + media queries; same ~102KB clip; no `:hover` reliability. |
+| EM-CLIENT-05 | Gmail (mobile, non-default / IMAP "GANGA") | **Strips `<style>` entirely** — only inline styles survive; the strictest Gmail mode. |
+| EM-CLIENT-06 | Outlook 2016–2021 (Windows) | **Word engine**: no flexbox/grid/`position`, ignores `max-width`/`border-radius`/CSS `background-image`; needs ghost tables + VML + `mso-line-height-rule:exactly`. |
+| EM-CLIENT-07 | Outlook (Microsoft 365, Windows) | Word engine like 2016/2019; DPI scaling bugs — set explicit image `width`/`height`. |
+| EM-CLIENT-08 | Outlook.com (web) | Different (better) engine than desktop; **aggressive dark-mode color inversion**; rewrites some colors. |
+| EM-CLIENT-09 | Outlook (macOS) | WebKit-based (unlike Windows); far more capable; still test buttons/spacing. |
+| EM-CLIENT-10 | Outlook (mobile, iOS/Android) | Largely fine; respects media queries; watch link color overrides. |
+| EM-CLIENT-11 | Yahoo Mail | Supports media queries; strips/rewrites some `class`/`id`; avoid unsupported pseudo-classes. |
+| EM-CLIENT-12 | AOL Mail | Shares Yahoo's engine; similar class/id handling. |
+| EM-CLIENT-13 | Samsung Mail (Android) | Webview-based; media-query support varies by version; test stacking. |
+| EM-CLIENT-14 | Android default / Gmail-for-non-Gmail | Inline-only safe mode; treat like the strict Gmail IMAP mode. |
+| EM-CLIENT-15 | Thunderbird | Gecko-based, capable; honors most CSS; test dark theme. |
+| EM-CLIENT-16 | Windows 10/11 Mail | EdgeHTML/Chromium-ish; generally capable; watch padding. |
+| EM-CLIENT-17 | Proton Mail | Sanitizes aggressively; strips remote content until approved; inline-safe. |
+| EM-CLIENT-18 | Fastmail | Standards-friendly; respects media queries and dark mode. |
+| EM-CLIENT-19 | Zoho Mail | Reasonable CSS support; test buttons + dark mode. |
+| EM-CLIENT-20 | GMX / Web.de | EU webmail; limited CSS; lean on inline styles + tables. |
+
+---
+
+## 8. Statically-checkable vs render-tested
+
+This table is the **contract** the validator's `rule` ids map to. The four rule-ids
+below are the deterministic subset that `scripts/lib/email/validate-email-html.cjs`
+asserts via regex/string analysis of the supplied HTML string. Every other rule-id in
+this catalogue is **render-tested guidance** — verified by the optional Litmus /
+Email-on-Acid render-test connection (34.2-02), never asserted by the static validator.
+
+| Rule-id | Check | Statically checked by the validator? | How verified otherwise |
+| --- | --- | --- | --- |
+| **EM-LAYOUT-01** | No `display:flex` / `display:grid` / `position:absolute\|fixed` in any `style` | **YES** — presence flagged | — |
+| **EM-STYLE-01** | No `<style>` block as the PRIMARY styling mechanism (non-`@media` rules / large sheet); inline styling expected | **YES** — a non-trivial `<style>` block flagged; a small `@media`-only block tolerated | — |
+| **EM-MSO-01** | An MSO conditional comment (`<!--[if mso]>` / `<!--[if !mso]>`) is present in a full-email document | **YES** — absence flagged | — |
+| **EM-DARK-01** | A `color-scheme` signal is present (meta `color-scheme` and/or CSS `color-scheme` and/or `prefers-color-scheme`) | **YES** — total absence flagged (a `<meta name="color-scheme">` alone satisfies it) | — |
+| EM-LAYOUT-02..05 | ~600px width, cellpadding, single-column, explicit widths | No | Render test (Litmus) |
+| EM-STYLE-02..04 | Longhand props, no external CSS, tolerated `@media` | No | Render test |
+| EM-MSO-02..04 | Ghost tables, VML, DPI/namespace head | No | Render test (Outlook) |
+| EM-DARK-02..04 | `supported-color-schemes`, explicit bg+color, dark logos | No | Render test (dark mode) |
+| EM-IMG-01..04, EM-A11Y-01 | width/height, alt, display:block, bulletproof buttons, lang/contrast | No | Render test + a11y review |
+| EM-CLIENT-01..20 | Per-client headline quirks | No | Render test (cross-client screenshots) |
+
+Notes on the four statically-checked rules:
+
+- **EM-STYLE-01 heuristic (deterministic).** A `<style>…</style>` block is flagged as the
+  primary styling mechanism when, after removing `@media { … }` groups and `@font-face`
+  from the block, residual CSS rules remain **or** the block exceeds a generous size
+  threshold. A small dark-mode/responsive `@media`-only block (per EM-STYLE-04) is
+  therefore tolerated and does NOT trip the check.
+- **EM-DARK-01 is decoupled from `<style>`.** A `<meta name="color-scheme" content="…">`
+  in `<head>` satisfies EM-DARK-01 on its own, so a fully-inline email with only a
+  color-scheme meta (and no `<style>` at all) passes both EM-STYLE-01 and EM-DARK-01.
+- **EM-MSO-01 fires only on a full email.** A document is treated as a full email when it
+  has `<html>`/`<body>` or a layout `<table>`; a bare fragment is not flagged for a
+  missing MSO comment.
+
+---
+
+## 9. Cross-references
+
+- [`reference/platforms.md`](./platforms.md) — the interaction-conventions sibling
+  (navigation, safe areas, gestures). The email-executor reads **this** file for the
+  email constraints, that file for general platform behavior.
+- [`scripts/lib/email/validate-email-html.cjs`](../scripts/lib/email/validate-email-html.cjs)
+  — the deterministic static validator that asserts the §8 subset; its `rule` ids are
+  the constraint-ids defined here.
+- [`reference/registry.json`](./registry.json) — this catalogue is registered as the
+  `email-design` entry (type `heuristic`, phase `34.2`) so the registry round-trip test
+  (`test/suite/reference-registry.test.cjs`) stays green (D-05, the 33.5-01 / 34.1-01
+  lesson).

package/reference/native-platforms.md

@@ -0,0 +1,273 @@
+# Native Platforms — Token-Bridge Spec
+
+This reference is the **token→native-code bridge**: it specifies how the canonical
+CSS-token form produced by the Phase-23 token engine
+(`scripts/lib/design-tokens/`) maps onto the three native theme systems —
+SwiftUI, Jetpack Compose, and Flutter — and pins down the **precision contract**
+that defines what "token identity preserved" means for the deterministic
+round-trip (`reference/native-platforms.md` is the authority that
+`test/suite/native-token-bridge.test.cjs` asserts against).
+
+It is the sibling of [`reference/platforms.md`](./platforms.md). Those two files
+have distinct jobs and must not be confused:
+
+| File | Job |
+| --- | --- |
+| `reference/platforms.md` (Phase 19) | Interaction **conventions** — navigation, safe areas, gestures, native typography, haptics. *Behavioral* knowledge the executors reference when laying out a screen. |
+| `reference/native-platforms.md` (Phase 34.1, this file) | The token→theme **bridge** — how a design token (`#3B82F6`, `16px`, `Inter`) becomes a SwiftUI `Color` / Compose `Color(0x…)` / Flutter `Color(0x…)`, plus the precision contract for the round-trip. *Structural* knowledge the emitters implement. |
+
+Per **D-02** the bridge **extends** the Phase-23 engine with three new emitters
+(`scripts/lib/design-tokens/{swift,compose,flutter}.cjs`) rather than forking a
+separate native IR. There is one canonical token form (below) and one set of
+readers; the native emitters are additional *sinks* on the same facade. Per
+**D-10** the round-trip operates at the **token level** — deterministic emit +
+re-extract with documented precision — never full-view parsing and never a live
+simulator, so the default `npm test` stays green on any machine.
+
+---
+
+## 1. Purpose
+
+Phase 19 shipped platform *references* but zero generators; Phase 23 shipped a
+multi-source token reader (`css-vars` / `js-const` / `tailwind` / `figma`) that
+all normalise to a single flat `{ tokens: Record<string, string> }` map. Phase
+34.1 crosses from platform-knowledge into platform-execution: instead of each
+native executor re-deriving "how does `#3B82F6` become a SwiftUI `Color`", the
+mapping lives once here (the spec) and once in the emitters (the
+implementation), and the executors consume it. This amortizes the Phase-23 token
+investment across SwiftUI / Compose / Flutter.
+
+The canonical CSS-token form is the **single input** to all three native
+emitters. This spec maps that one input to three native theme systems and states
+the precision each mapping preserves.
+
+---
+
+## 2. Canonical input shape
+
+The emitters consume the exact map shape the Phase-23 readers return: a **flat
+`{ tokens: Record<string, string> }` object** whose keys are the design-token
+names with the leading `--` stripped (exactly as `css-vars.cjs` returns) and
+whose values are the raw token values as strings.
+
+```js
+{ tokens: { "color-primary": "#3B82F6", "space-4": "16px", "font-family-body": "Inter, system-ui" } }
+```
+
+Each emitter accepts either the full Phase-23 `TokenSet`
+(`{ tokens, source?, format? }`) **or** a bare `{ tokens }` object — it reads
+`tokenSet.tokens` and throws a `TypeError` only when no `.tokens` object is
+present.
+
+### Prefix → category inference
+
+Token **category** is inferred from the key prefix. The emitters use this table
+to decide whether a value is a color, a dimension, or a string:
+
+| Key prefix | Category | Native treatment |
+| --- | --- | --- |
+| `color-` | color | hex → native channel form (§3–§5, §6 COLOR) |
+| `space-`, `spacing-` | dimension | px → pt / dp / logical px (§6 DIMENSION) |
+| `radius-` | dimension | px → pt / dp / logical px |
+| `size-` | dimension | px → pt / dp / logical px |
+| `font-`, `text-` | typography | string pass-through (family / weight / named size) |
+| `shadow-` | other | string pass-through (composite values are non-mappable) |
+| *(anything else)* | other | value-sniffed: a `#…` value is treated as color, an `Npx` value as dimension, otherwise string pass-through |
+
+A value is **always** re-sniffed regardless of prefix, so a `#…` value under a
+non-color prefix is still emitted as a color and a `Npx` value under a non-space
+prefix is still emitted as a dimension. The prefix is the hint; the value is the
+authority. This keeps the bridge robust against arbitrary token-naming schemes.
+
+---
+
+## 3. SwiftUI mapping
+
+Target: a Swift source string exposing an `enum` of static theme constants
+(`enum GDDTheme { … }`) — colors as `Color`, dimensions as `CGFloat` points,
+typography families as `String` (and an optional `Font` helper).
+
+| Token | SwiftUI form |
+| --- | --- |
+| color `#RRGGBB` | `Color(red: R/255.0, green: G/255.0, blue: B/255.0, opacity: A/255.0)` from the 8-bit channels |
+| dimension `Npx` | `CGFloat` point literal — integer `N` (pt) |
+| font-family | `String` literal (`"Inter, system-ui"`) |
+
+Illustrative (2-line) snippet:
+
+```swift
+static let colorPrimary = Color(red: 59.0/255.0, green: 130.0/255.0, blue: 246.0/255.0, opacity: 255.0/255.0)
+static let space4: CGFloat = 16
+```
+
+SwiftUI uses normalized `0.0…1.0` channel fractions; to keep the round-trip
+**exact** the emitter writes each channel as the 8-bit numerator over `255.0`
+(e.g. `59.0/255.0`) rather than a pre-divided decimal — the re-extractor reads
+the numerator back as the integer channel, avoiding float drift. The `Color` /
+`Font` / `ViewModifier` consumption pattern (applying the constants to views) is
+the executor's job; this emitter produces the *constants*.
+
+---
+
+## 4. Jetpack Compose mapping
+
+Target: a Kotlin source string with `Color` vals, a `Shapes` block (from
+`radius-` tokens), a `Typography` block (from `font-`/`text-` tokens), and a
+`MaterialTheme` wiring (`object GDDTheme { val Colors… ; val Shapes… ; val Typography… }`).
+
+| Token | Compose form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` long literal (alpha-first, 8 hex digits) |
+| dimension `Npx` | `N.dp` (integer dp) |
+| radius `Npx` | `RoundedCornerShape(N.dp)` inside `Shapes` |
+| typography family | `String` (fed into a `TextStyle.fontFamily` slot / `Typography`) |
+
+Illustrative (2-line) snippet:
+
+```kotlin
+val colorPrimary = Color(0xFF3B82F6)
+val space4 = 16.dp
+```
+
+Compose packs ARGB into a single `0xAARRGGBB` long; alpha is the high byte. The
+re-extractor reads the 8 hex digits straight back to the channels.
+
+---
+
+## 5. Flutter mapping
+
+Target: a Dart source string building a `ThemeData` whose `colorScheme`
+(`ColorScheme`) carries the color tokens and whose `textTheme` (`TextTheme`)
+carries the typography tokens, plus a constants class
+(`class GDDTheme { … }`).
+
+| Token | Flutter form |
+| --- | --- |
+| color `#RRGGBB` | `Color(0xAARRGGBB)` (alpha-first, 8 hex digits) |
+| dimension `Npx` | logical-px **double** — `N.0` |
+| typography family | `String` (`fontFamily: 'Inter'`) |
+
+Illustrative (2-line) snippet:
+
+```dart
+static const colorPrimary = Color(0xFF3B82F6);
+static const space4 = 16.0;
+```
+
+Flutter measures in logical pixels and keeps the value as a `double` (`16.0`),
+so — unlike pt/dp — Flutter dimensions are **not** rounded to integers; the
+fractional part survives.
+
+---
+
+## 6. PRECISION CONTRACT
+
+This section is the crux. It defines, per value category, exactly what
+information the emit → re-extract round-trip preserves. The test asserts token
+identity **within this precision** — not bit-exact floats, not lossy
+approximation. An emitter is correct **iff** `reextract(emit({tokens}))`
+reproduces every token in the identity set under these rules.
+
+### COLOR — 8-bit-per-channel, EXACT
+
+- Accepted input forms: `#RGB`, `#RRGGBB`, `#RGBA`, `#RRGGBBAA` (case-insensitive).
+- `#RGB` / `#RGBA` shorthand **expands** to `#RRGGBB` / `#RRGGBBAA` by
+  duplicating each nibble (`#3af` → `#33aaff`). This expansion is part of the
+  contract: the re-extractor recovers the **expanded** `#RRGGBB(AA)` form, so
+  `#3af` round-trips to `#33aaff` (canonically equal, the documented identity).
+- Each channel is an 8-bit integer (0–255) and is preserved **exactly** — no
+  channel may be off by one. SwiftUI stores channels as `N.0/255.0` numerators;
+  Compose/Flutter store them in a `0xAARRGGBB` literal. Both forms recover the
+  identical 8-bit channels.
+- **Alpha:** when the input has no alpha (`#RGB`/`#RRGGBB`) the emitted color is
+  **opaque** — alpha byte `0xFF` (Compose/Flutter) / `opacity: 255.0/255.0`
+  (SwiftUI). The re-extractor emits an alpha channel **only when the original
+  had one**: a 6-digit input round-trips to a 6-digit `#RRGGBB` (the implied
+  opaque alpha is dropped on the way back); an 8-digit input round-trips to the
+  8-digit `#RRGGBBAA`. This keeps `#3B82F6 → #3B82F6` an exact identity.
+
+### DIMENSION — integer pt/dp, logical-px double
+
+- Accepted input: `Npx` or a bare unit-less number (`16px`, `16`). The unit is
+  normalised to `px` on the canonical side.
+- **iOS (pt) / Android (dp):** rounded to the nearest integer, **round-half-up**
+  (`15.5px` → `16`). Because rounding is lossy for non-integers, the round-trip
+  **identity set** is restricted to integer-px dimensions (e.g. `16px`), which
+  recover exactly: `16px → 16 (pt/dp) → 16px`.
+- **Flutter (logical px):** kept as a `double` (`16px` → `16.0`), so Flutter
+  does **not** round and a fractional dimension survives. The re-extractor
+  recovers `Npx` by stripping the trailing `.0` for whole numbers.
+- The re-extractor always recovers the canonical `Npx` string form, so the
+  emit→re-extract identity for an integer dimension is `"16px" === "16px"`.
+
+### `rem` / `em` — passed through verbatim (non-mappable)
+
+`rem`/`em` values depend on a root/element font-size that the token map does not
+carry, so they are **not** converted. They are treated as **non-mappable**
+(below): emitted verbatim into a raw slot and **excluded** from the round-trip
+identity set. (A future plan may add an explicit base-size option; until then,
+verbatim pass-through is the stated, deterministic behavior.)
+
+### TYPOGRAPHY / NAMED VALUES — string pass-through
+
+`font-family`, `font-weight`, named sizes, and any other string token are
+emitted **verbatim** as a string literal and recovered **string-equal**
+(`"Inter, system-ui" → "Inter, system-ui"`). No normalisation, no quoting
+changes that alter the recovered string.
+
+### NON-MAPPABLE — verbatim, EXCLUDED from the identity set
+
+Values the emitter cannot represent as a native primitive — CSS `var(--x)`
+references, `calc(…)` expressions, gradients (`linear-gradient(…)`), and `rem`/
+`em` dimensions — are **passed through verbatim** into a raw-string slot
+(a trailing comment such as `// non-mappable: <name> = <value>` or the language
+equivalent) so no information is lost, and are **explicitly excluded** from the
+round-trip identity assertion. The contract documents them as
+"verbatim / not round-tripped": the test asserts the verbatim value appears in
+the emitted source, and does **not** assert it survives re-extraction as a typed
+token.
+
+---
+
+## 7. The round-trip (what the test locks)
+
+For each emitter the bridge guarantees:
+
+1. **Determinism.** `emit(x) === emit(x)` byte-for-byte. Keys are iterated in a
+   stable sorted order; no `Date`, no `process.env`, no filesystem, no network in
+   the emit path (D-10).
+2. **Identity within precision.** For the identity set (color + integer
+   dimension + typography), `reextract(emit({tokens}))` deep-equals `{tokens}`
+   under the precision rules above (8-bit color channels exact with `#RGB`
+   expansion; integer pt/dp; logical-px double; family/weight string-equal).
+3. **Verbatim exclusion.** Non-mappable values appear verbatim in the source and
+   are not part of the identity assertion.
+
+Each emitter module exports a symmetric re-extractor
+(`reextractSwift` / `reextractCompose` / `reextractFlutter`) that parses the
+emitted native source back into a `{ tokens }` map, so the round-trip is
+deterministic and bijective on the identity set and reusable by the Phase-34.1
+regression baseline.
+
+---
+
+## 8. Registration
+
+This reference is registered in
+[`reference/registry.json`](./registry.json) as the `native-platforms` entry
+(type `heuristic`, phase `34.1`) so the registry round-trip test
+(`test/suite/reference-registry.test.cjs`) stays green — every `reference/*.md`
+must be registered and resolve (D-05, the 33.5-01 lesson).
+
+---
+
+## 9. Cross-references
+
+- [`reference/platforms.md`](./platforms.md) — the interaction-conventions
+  sibling (navigation, safe areas, gestures, native typography). Executors read
+  **both**: this file for the token→theme bridge, that file for layout/behavior.
+- `scripts/lib/design-tokens/` — the Phase-23 token engine this bridge extends
+  (`index.cjs` facade + `css-vars` / `js-const` / `tailwind` / `figma` readers +
+  the new `swift` / `compose` / `flutter` emitters).
+- `test/fixtures/mapper-outputs/tokens.json` — the canonical token fixture the
+  round-trip test derives its map from.

package/reference/registry.json

@@ -888,6 +888,20 @@
       "type": "data",
       "phase": 33.6,
       "description": "Phase 33.6 catalog-derived OpenRouter price sub-table — per-model prompt/completion $/tok snapshot of .design/cache/openrouter-models.json; derived view, the dynamic catalog is the source of truth (D-11 registry round-trip)."
+    },
+    {
+      "name": "native-platforms",
+      "path": "reference/native-platforms.md",
+      "type": "heuristic",
+      "phase": 34.1,
+      "description": "Phase 34.1 token-bridge spec — maps the canonical CSS-token form (Phase 23) to SwiftUI Color/Font/ViewModifier, Jetpack Compose Color/Shapes/Typography/MaterialTheme, and Flutter ThemeData/ColorScheme/TextTheme, with the precision contract (color hex→8-bit channels exact, dimension px→pt/dp/logical px) defining token-identity for the round-trip."
+    },
+    {
+      "name": "email-design",
+      "path": "reference/email-design.md",
+      "type": "heuristic",
+      "phase": 34.2,
+      "description": "Phase 34.2 email-constraint catalogue — table-based layout (not flexbox/grid/position), inline styles (not a <style> block), MSO conditional comments for Outlook, dark-mode color-scheme/prefers-color-scheme handling, ~600px max-width, image/alt rules, and top-20-client quirks; the authority the email-executor generates against and the design-verifier email branch audits against, and the rule-id source for scripts/lib/email/validate-email-html.cjs."
     }
   ]
 }