@tyroneross/build-loop 0.30.3

package/skills/ui-design/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: ui-design
+description: Use when build-loop needs UI design direction, visual style selection, UI guidance inventory, a .build-loop/app-contract/ui.md design contract, or non-trivial web/mobile/native UI planning. Build-loop-owned design route for design-contract-specialist; selects from project tokens, recent structures, UI Guidance, IBR artifacts, Mockup Gallery, and research based on product/workflow/data/platform fit.
+user-invocable: false
+---
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Design
+
+Build-loop-owned guidance for choosing UI direction. This skill is the design selection layer; `design-contract-specialist` is the agent that writes the resulting contract.
+
+For broader communication and information-design artifacts such as writing, images, decks, documents, reports, spreadsheets, PDFs, or UI-generated exports, start from `references/universal-design-principles.md`, then load the medium-specific skill.
+
+## Runtime Contract
+
+Use this skill when `uiTarget != null` and the work is not copy-only:
+
+1. Load the UI input/output contract from the plan.
+2. Load `references/universal-design-principles.md` when the surface presents information, contains charts/tables/reports, creates document/deck/image-like outputs, or needs continuity, wayfinding, process visibility, or graceful degradation.
+3. Apply Calm Precision as the structural foundation: hierarchy, grouping, disclosure, action weight, touch targets, motion restraint, copy clarity, and functional integrity.
+4. Run a Calm Precision core-consideration pass before selecting style: name the principles most relevant to the surface, the perceptual foundation behind each one, and the concrete implication for this build.
+5. Load project-local visual evidence: current screens, screenshots, tokens, components, selected mockups, and existing `.build-loop/app-contract/ui.md`.
+6. Select only the guidance sources needed for the surface from `references/ui-guidance-sources.md`.
+7. Choose the design direction from product fit: user job, workflow frequency, data shape, information density, platform, accessibility risk, error cost, and the Calm Precision core-consideration pass.
+8. Have `design-contract-specialist` write the decision to `.build-loop/app-contract/ui.md`.
+
+## Design Layers
+
+Think in layers, not competing design systems:
+
+1. **Product contract** — the UI input/output contract, user job, platform, data shape, and risk.
+2. **Universal communication and experience design** — answer-first structure, one primary focus, continuity, wayfinding, process visibility, graceful degradation, MECE grouping, hierarchy, source integrity, native primitives, accessibility, and visual QA across UI, writing, images, decks, docs, operational workflows, and data artifacts.
+3. **Calm Precision core considerations** — the baseline rules and perceptual-science foundations that every design direction must satisfy or explicitly except.
+4. **Project surface** — existing tokens, components, brand, screenshots, and selected mockups.
+5. **Structure or style mode** — recent design structures such as Conversational Command Surface, Bento Operating Dashboard, Pipeline Wizard, Outcome Ledger, Pyramid Detail, Glass Workspace, Warm Craft, Data Narrative, native mobile, or AI Artifact Canvas.
+6. **Validation evidence** — `ui-validator`, design-rule scanner, browser/simulator screenshots, and contract traceability.
+
+Calm Precision is not just one optional theme or reference. It is a core design gate. Every non-trivial UI decision should be checked against the relevant Calm Precision principles before selecting structure, style mode, token treatment, motion, or interaction behavior. A Glass, Warm Craft, Aurora, Data Narrative, or native mobile direction can change surface treatment, density, and mood, but it must not override Calm Precision's hierarchy, accessibility, motion, interaction, and real-data rules unless the app contract records an explicit exception.
+
+## Source Priority
+
+Resolve conflicts in this order:
+
+1. Explicit user requirement for this build.
+2. Current product/workflow/data/platform need.
+3. Existing project tokens, components, and current UI conventions.
+4. `.build-loop/app-contract/ui.md` and the plan's UI input/output contract.
+5. Universal information-design principles from `references/universal-design-principles.md`.
+6. Calm Precision structural rules.
+7. Build-loop references: `skills/build-loop/references/ui-io-contract.md`, `skills/build-loop/references/recent-design-structures.md`, and `skills/build-loop/templates/ui-subagent-prompt.md`.
+8. Local guidance sources from `references/ui-guidance-sources.md`.
+9. Research or vault material, summarized into a concrete decision before implementers receive it.
+
+## Required Output
+
+The design decision must be written into `.build-loop/app-contract/ui.md` before implementation for non-trivial UI work. Include:
+
+- `selected_structure` and why it fits.
+- At least one rejected structure and why it was rejected.
+- Source refs used, with absolute paths when outside the repo.
+- `calm_precision_core_considerations`: relevant principles, perceptual foundations, implications for the surface, and any explicit exceptions.
+- Density, hierarchy, surface model, typography roles, token source, action hierarchy, visual non-goals, and validation implications.
+
+Implementers should read the app contract and UI input/output contract, not the whole guidance corpus.
+
+## Guardrails
+
+- Do not route to IBR unless the user explicitly asks for IBR, Interface Built Right, or an IBR-specific artifact.
+- Do not force recent structures. They are options, not requirements.
+- Do not treat Calm Precision as a citation, theme, or surface style. Use it as the shared baseline and decision gate under the selected mode.
+- Do not load broad vault/research folders into implementation prompts. Select one to three relevant sources and synthesize them.
+- Do not introduce mock data, fake affordances, arbitrary palettes, or decorative visual complexity that does not serve the workflow.
+- If a major UI build lacks enough visual evidence, ask the orchestrator for mockup/screenshot/design-tool artifacts; keep the final design decision in `.build-loop/app-contract/ui.md`.
+- When gathering evidence from owned/reference apps, route token-extraction to source-of-truth reads and interaction-texture (motion, haptics, render gradients, transition states) to live IBR capture — see `references/evidence-capture-policy.md`.

package/skills/ui-design/references/design-patterns-multi.md

@@ -0,0 +1,165 @@
+# Multi-Pattern Token Framework — Feasibility Draft
+
+> **DEPRECATION SHIM (one release cycle).** Canonical source migrated to the `ui-guidance` plugin → load via `Skill("ui-guidance:tokens")`. This file remains in build-loop as a transition aid; future updates land in the plugin. *(Renamed from `multi-pattern-tokens` in ui-guidance v0.2.0.)*
+>
+> **Status:** DRAFT — exploration only. Not active, not loaded by ui-design. Decision pending the Feasibility verdict at the bottom.
+>
+> **Source attribution:** Adapted from Google Labs' DESIGN.md spec at <https://github.com/google-labs-code/design.md> (fetched 2026-05-26 from the raw README at `main`, 337 lines). DESIGN.md proposes a YAML-front-matter + markdown-prose hybrid: tokens are normative, prose tells agents *why* they exist. This document explores whether the same hybrid can extend to **multi-pattern** tokens — i.e., one design language expressing different concrete values per form factor (mobile / tablet / web / watch) without forking the system.
+
+## The motivating problem
+
+Calm Precision currently states sizes, spacing, and color in single concrete values:
+
+- `44px mobile, 24px desktop touch` (two values, hard-coded into the principle line).
+- `4.5:1 contrast` (one value, universal).
+- `8pt grid` (one value, universal).
+- `Title (14-16px bold) → Description (12-14px) → Metadata (11-12px muted)` (ranges, but flat — no per-form-factor resolution).
+
+When the same agent ships across iPhone, iPad, macOS, and web, it has to *interpret* these ranges every time. A typography token like `body-md: 16px` means one thing in a tablet reading view, another in a watch glance, another in a desktop dashboard. Today this interpretation lives in the agent's head — re-derived per surface, drift-prone, easy to get wrong on the small or far-from-default surface.
+
+A multi-pattern framework lets the design system *declare* the resolution once, as a structured token, and ship the same `DESIGN.md` everywhere.
+
+## The format
+
+Three patterns are proposed. Each extends DESIGN.md's existing YAML-front-matter shape — none of them require a new top-level concept; they expand what a token *value* can be.
+
+### Pattern 1 — `pattern: scale`  (responsive scalar)
+
+A single token resolves to different concrete values per named breakpoint or form factor. The consumer picks the value based on its render context.
+
+```yaml
+typography:
+  body-md:
+    pattern: scale
+    fontFamily: Public Sans
+    fontSize:
+      watch: 13px       # 38mm-44mm Apple Watch — small viewport, denser scale
+      mobile: 16px      # iPhone default
+      tablet: 17px      # iPad — bumped one step for reading-distance
+      web: 16px         # desktop browser, 1280px+
+    lineHeight: 1.5     # universal — does not vary
+```
+
+Consumer behavior: an iOS app picks `mobile`, an iPad app picks `tablet`, a watch app picks `watch`. Tokens that don't declare a `pattern: scale` shape fall back to a single value (back-compat with DESIGN.md alpha).
+
+### Pattern 2 — `pattern: ladder`  (semantic step with named rungs)
+
+A token is a *step* on a named ladder rather than a fixed value. The ladder definition lives once at the top of the doc; tokens reference rungs by name. Lets a designer change "what `space-loose` means on tablet" once and have every consuming token pick it up.
+
+```yaml
+ladders:
+  spacing:
+    tight: { mobile: 4px, tablet: 6px, web: 8px }
+    snug:  { mobile: 8px, tablet: 12px, web: 12px }
+    loose: { mobile: 16px, tablet: 24px, web: 24px }
+    roomy: { mobile: 24px, tablet: 32px, web: 40px }
+
+components:
+  card:
+    pattern: ladder
+    padding: "{ladders.spacing.snug}"   # resolves to 8/12/12 depending on surface
+    gap:     "{ladders.spacing.tight}"  # resolves to 4/6/8
+```
+
+Compared to Pattern 1, Pattern 2 separates *naming* from *value*. The cost is one extra layer of indirection; the benefit is changing all `snug` paddings across the system in one edit.
+
+### Pattern 3 — `pattern: condition`  (state-driven token)
+
+A token resolves to different values based on a runtime condition the consumer reports — not just form factor. Useful for accessibility-sensitive properties (contrast, motion, density), dark/light mode, and reduced-motion preferences.
+
+```yaml
+colors:
+  primary-text:
+    pattern: condition
+    default: "#1A1C1E"
+    when:
+      colorScheme=dark: "#F2F2F2"
+      contrastLevel=high: "#000000"     # WCAG AAA-locked surface
+      reduceTransparency=true: "#1A1C1E"
+
+motion:
+  card-enter-duration:
+    pattern: condition
+    default: 240ms
+    when:
+      reduceMotion=true: 0ms
+      density=compact: 160ms
+```
+
+Consumers report their condition bag at render time; the token resolver picks the most-specific match (with a documented precedence order).
+
+### Pattern 4 — `pattern: composite` (cross-token resolution)
+
+A component token resolves multiple sub-tokens together to enforce internal consistency. The composite shape is the unit of legal variation, not the individual sub-tokens.
+
+```yaml
+components:
+  button-primary:
+    pattern: composite
+    variants:
+      mobile:
+        backgroundColor: "{colors.tertiary}"
+        textColor: "{colors.on-tertiary}"
+        padding: 12px
+        minHeight: 44px        # iOS touch target
+      tablet:
+        backgroundColor: "{colors.tertiary}"
+        textColor: "{colors.on-tertiary}"
+        padding: 14px
+        minHeight: 48px
+      web:
+        backgroundColor: "{colors.tertiary}"
+        textColor: "{colors.on-tertiary}"
+        padding: 10px 16px
+        minHeight: 36px        # desktop hover-driven, not touch
+```
+
+Pattern 4 is the most opinionated and the most useful for the touch-target case: the touch-vs-pointer split is a *composite* concern (size + padding + minHeight all change together), and expressing it as one variant block makes the intent legible.
+
+## Calm Precision compatibility
+
+The four patterns are extensions, not replacements. Calm Precision principles map directly:
+
+| Calm Precision rule | Today | Multi-pattern expression |
+|---|---|---|
+| `44px mobile, 24px desktop touch` | inline two-value statement | Pattern 4 (composite `button-primary` with mobile/web variants) |
+| `Title 14-16px bold → Description 12-14px → Metadata 11-12px` | range, agent interprets | Pattern 1 (scale by form factor) or Pattern 2 (ladder rungs) |
+| `4.5:1 contrast` | universal | Pattern 3 (condition: high-contrast surface picks AAA values) |
+| `8pt grid` | universal | unchanged — no pattern needed |
+| `Status = text color only, no background badges` | universal rule | unchanged — qualitative, not a token |
+
+Two non-negotiables stay outside the framework because they are *behavioral*, not numeric: "No fake buttons / backend must exist before UI" and "Real data default — mock requires explicit permission". The framework expresses values, not data contracts.
+
+## Implementation risk
+
+| Risk | Severity | Mitigation |
+|---|---|---|
+| Token resolution becomes a build-time dependency every consumer needs | **High** | Ship a stdlib-only Python resolver (≤200 LOC) in `ui-design/scripts/` so consumers can shell out. No JS toolchain required for read-only consumers. |
+| Conditions can interact (dark + high-contrast + reduceMotion all true) | **Medium** | Declared precedence order in spec; resolver picks most-specific then falls back. Test matrix at the resolver level. |
+| Naming sprawl — ladders + patterns + components overlap | **Medium** | One pattern per use case; document a decision tree (form factor → scale; cross-token consistency → composite; runtime state → condition; named tiers → ladder). |
+| Drift from DESIGN.md upstream — they may evolve the spec | **Medium** | Keep our extension namespaced as `pattern: <name>`; if upstream ships native support we can deprecate ours. Track the upstream repo at v0.x and re-evaluate on each minor bump. |
+| Tokens become opaque at the source — readers can't tell what value an agent will pick | **Medium** | Resolver MUST emit a "resolved view" markdown file as a build artifact, showing what each token resolves to on each declared form factor. Reviewable in PRs. |
+| Adoption cost across 8 existing apps is non-trivial | **Low** | Pattern adoption is opt-in per project; existing single-value tokens keep working. |
+
+## Build-time complexity
+
+- **Resolver**: ~200 LOC Python, stdlib-only (yaml parsing via `PyYAML` already in build-loop deps). Pure function: `(token_path, form_factor, conditions) → value`.
+- **Linter extension**: extend DESIGN.md's existing `lint` command to recognize the four new `pattern:` values and validate their internal shape (e.g., a `scale` token MUST declare at least 2 form factors).
+- **Diff tool**: extend `diff` to compare resolved values per form factor, not just raw token values — otherwise diffs would miss the case where the `mobile` value changed but `tablet` didn't.
+- **CI integration**: every consuming app's CI runs the resolver and asserts the resolved view matches a checked-in snapshot. Drift becomes a PR-time signal, not a runtime surprise.
+
+Estimated effort to ship a v0.1 of all four patterns + resolver + linter extension: M (medium). Estimated effort to retrofit Calm Precision's three numeric rules: S (small) — three token files.
+
+## Feasibility verdict
+
+**Verdict: ITERATE.** The pattern shapes are compatible with Calm Precision and address a real drift problem (the touch-target rule, the typography range rule, the dark-mode color rule). But the implementation risk concentrates in two places — *token opacity at the source* (readers can't see what an agent will pick) and *condition-interaction ambiguity* — that would burn trust if shipped without a resolved-view artifact and a precedence test matrix.
+
+**Recommended next step (NOT executed in this build):** prototype Pattern 4 (composite) only, on Calm Precision's touch-target rule, in one app (TruePace — iPad-primary with iPhone secondary, so it actually exercises the variant resolution). Measure: does the composite token reduce the per-form-factor interpretation work an agent has to do? If yes, expand to Pattern 1. If no, the abstraction isn't paying for its complexity.
+
+**Rejected today:** shipping all four patterns to active use simultaneously. The composite case is the highest-value, lowest-risk entry point; the other three patterns should be gated on the composite prototype's outcome.
+
+**Not adopted, not rejected:** patterns themselves are sound; the question is sequencing and prototype evidence, not design correctness. This document stays as a draft until a single-pattern prototype confirms or denies the value claim.
+
+---
+
+*Drafted in build-loop run 2026-05-26 against the universal-design enrichment intent. Re-evaluate when the Pattern 4 prototype lands or when DESIGN.md upstream releases a `pattern:` shape natively.*

package/skills/ui-design/references/design-preferences-from-owned-apps.md

@@ -0,0 +1,150 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+> **DEPRECATION SHIM (one release cycle).** Canonical source migrated to the `ui-guidance` plugin → load via `Skill("ui-guidance:preferences")`. This file remains in build-loop as a transition aid; future updates land in the plugin. *(Renamed from `design-preferences-evidence` in ui-guidance v0.2.0.)*
+
+# Design Preferences — Sourced from Owned Apps
+
+> Sourced from `.build-loop/design-evidence/*.md` (8 apps scanned 2026-05-26). Every claim in this file traces to a specific evidence file. The evidence files are the ground truth — when this doc and an evidence file disagree, the evidence file wins.
+>
+> **Primary preferred references** (per intent.md): Sample Voice iOS, Sample Timer (iPad primary), Sample Reader, Sample Product App.
+> **Secondary / directional** (note what works AND what user dislikes): Secrets Vault macOS, Sample Decision App, Sample Offline iOS, Sample Onboarding App.
+
+---
+
+## 1. Typography: tokenized three-line hierarchy, not inline pixel sizes
+
+**Universal non-negotiable:** *"Visual hierarchy is one-glance recoverable"* (alt doc §2.12) + Calm Precision's *"Title (14-16px bold) → Description (12-14px) → Metadata (11-12px muted)"*.
+
+**What works (primary apps):**
+- **Secrets Vault** — verbatim CP 6.4.1 implementation in `VaultTypography.swift` (evidence: `secrets-vault-macos.md`). Token comment in source code: *"L1: Title 15px medium high contrast → L2: Description 13px regular medium contrast → L3: Metadata 11px regular low contrast."* This is the textbook reference.
+- **Sample Timer App** — `TextRole` enum (`Theme.swift:689-721` per `sample-timer.md`) ladders seven named roles (display/title/headline/subheadline/body/caption/micro) with explicit baseSize + defaultWeight per rung. Tokens cite role purpose: *"display: 30pt — single largest element on a screen."*
+- **Sample Voice App** — nine named typography tokens (`Theme.swift:31-35,70-75` per `sample-voice-ios.md`) including `fontTabular` (10pt mono-equivalent for numerics) — a use-case that single-purpose token sets miss.
+
+**Anti-pattern (secondary apps):**
+- **Sample Onboarding App** — typography is **inline pixel sizes scattered across call sites**: `.font(.system(size: 34))`, `.system(size: 20)`, `.system(size: 18)`, `.system(size: 16)`, `.system(size: 15)`, `.system(size: 14)`, `.system(size: 13)`, `.system(size: 12)` — all in `SetupView.swift` alone (evidence: `sample-onboarding-app.md`). Cannot grep for "title size." Cannot bump the scale once. The ladder is not a ladder; it is a pile.
+
+**Preference recorded:** **define a typography token enum (TextRole-style) before writing the first view.** Inline pixel sizes are tolerated only when the role doesn't yet exist in the enum — and that gap becomes a follow-up to extend the enum, not a permanent state.
+
+---
+
+## 2. Color: single accent, hierarchical text, status-as-text
+
+**Universal non-negotiable:** *"Visual hierarchy is one-glance recoverable [...] If color is removed, the hierarchy still holds"* (alt doc §2.12) + Calm Precision's *"Status = text color only, no background badges."*
+
+**What works (primary apps):**
+- **Sample Product App** — strictest single-accent enforcement in inventory: `--primary === --accent === --ring === #f0b65e` (`index.css:18,22,26` per `sample-product.md`). The entire palette is warm-monochromatic; the only "second color" is `--success: #7bc67e` (muted sage) and `--destructive: #e06356` (warm red-orange, not pure red — palette discipline holds even on error).
+- **Sample Reader** — explicit semantic separation: `--color-error-bg` and `--color-error-border` exist for tinted alert containers, but they are tokens distinct from `--status-error` (the foreground text color). Container surfaces are gated to reading flow where text-color-only would underread (`sample-reader.md` cites the divergence with rationale).
+- **Secrets Vault** — three-tier text contrast (`textPrimary / textSecondary / textMuted` = stone-900 / stone-600 / stone-400 in light; stone-100 / stone-300 / stone-450 in dark, per `secrets-vault-macos.md`). Each tier maps directly to L1/L2/L3 of the typography ladder — text size + text contrast move together.
+
+**Anti-pattern (secondary apps):**
+- **Sample Decision App theme-toggle pattern** — three switchable themes (F default, A "Case File," B "Conversation") via `[data-theme="A"|"B"]` on `<html>` (evidence: `sample-decision-app.md`). Each theme owns the same 6 token names but different brand colors. *Works for*: keeping semantic meaning constant across visual presentation. *Fails for*: brand identity — a brand that can become blue or terracotta or red is brand-fungible. Likely user-dislike: the existence of the toggle dilutes the canonical voice (Theme F).
+- **Sample Reader tinted error containers** — divergence from Calm Precision noted above. **Not always a flaw** — the sample reader justifies it by reading-flow density, and the divergence is contained to status containers — but it is a divergence, and absent a similar rationale, default to text-color-only.
+
+**Preference recorded:** **one accent color per app. Status uses text color first; tinted containers only when reading-flow density justifies and the divergence is documented in the token file's comments.**
+
+---
+
+## 3. Touch targets: tokenized at component layer, never per-view
+
+**Universal non-negotiable:** *"Interaction targets match input precision"* (alt doc §2 visual-craft inheritance) + Calm Precision's *"44px mobile, 24px desktop touch."*
+
+**What works (primary apps):**
+- **Sample Product App** — `.btn-primary` class explicitly enforces `min-h-[44px] min-w-[44px]` at the **component layer** (`index.css:52` per `sample-product.md`). Every primary button passes the Calm Precision touch target without any per-view code.
+- **Sample Voice App** — primary CTA is 52pt height (`HomeView.swift:92` per `sample-voice-ios.md`), exceeds the 44pt floor, and the tab bar uses a 100pt reserve token (`Theme.tabBarReserve`) so list items never clip behind the iOS 26 floating bar.
+
+**Cited Calm Precision compliance via system defaults:**
+- **Sample Offline iOS** — uses Apple system `List` rows and `.plus` button — both meet 44pt via Apple defaults. Demonstrates that *"system primitives over visual fakes"* (alt doc §2.14) can be the touch-target win — but only when the app doesn't need brand-distinct controls.
+
+**Preference recorded:** **encode touch-target minimums in the component class itself, not in per-view padding math.** When using system primitives, prefer them — Apple has already done the work.
+
+---
+
+## 4. Responsive form factor: token-scaled, not per-platform fork
+
+**Universal non-negotiable:** *"Content fits its container, or the container fits the content"* (alt doc §2.11).
+
+**What works (gold standard — Sample Timer App):**
+- Single typography hierarchy multiplied by `\.viewportScale` env var (`sample-timer.md` cites `Theme.swift:689-836`):
+  - iPhone compact size class: 1.0×
+  - iPad / Mac regular-width: 1.5×
+  - Mac live window resize: `max(0.85, min(1.5, shorterEdge / 600))`
+  - iPad sheets: additional 1.15× uplift over canvas (1.5 × 1.15 = 1.725×)
+- Watch palette has its own warm/cool dual mode: cool primary palette when display is active, warm `Dim` variants when `isLuminanceReduced == true` (Always-On Display) — circadian-safe >560nm tones.
+- Mode accents (timer / flow / adaptive / break) ship as `GradientColorSet` with **7 distinct color slots** per mode (core + 5-stop dark gradient + 5-stop light gradient + blob primary + blob secondary + warm target + ring end).
+
+**What doesn't work (anti-pattern — none in inventory, but absence noted):**
+- No app in the inventory ships separate iPhone and iPad themes as forked codepaths. The closest is Sample Timer App's `#if os(watchOS)` block which uses a separate warm-cool palette for watch — but that is platform-isolated, not a fork.
+
+**Preference recorded:** **viewport-scale tokens that read a single env var. iPad is the iPhone hierarchy × 1.5; Mac is the iPad math but live-window-resize-aware; Watch is its own palette but the same role names.** Forking iPhone and iPad theme files is the failure mode; the multi-pattern framework draft (`design-patterns-multi.md`) Pattern 1 / Pattern 4 are the formal expression of this preference.
+
+---
+
+## 5. Motion: respect-reduce-motion is mandatory, anti-flicker is intentional
+
+**Universal non-negotiable:** *"Motion serves comprehension, not decoration"* (alt doc §2 visual-craft inheritance).
+
+**What works (primary apps):**
+- **Sample Decision App** — `@media (prefers-reduced-motion: reduce)` overrides all animations to 0.01ms at the globals level (`app/globals.css:65-71` per `sample-decision-app.md`). Single CSS rule covers the whole app.
+- **Sample Voice App** — `@Environment(\.accessibilityReduceMotion)` honored on HomeView; first-time onboarding animation gated to once per AppStorage flag (`HomeView.swift:16,47` per `sample-voice-ios.md`).
+- **Secrets Vault** — stagger animation capped at 400ms total (`60ms × N items, max 400ms`) — prevents the long-list "wave" anti-pattern (per project CLAUDE.md cited in `secrets-vault-macos.md`).
+- **Sample Onboarding App** — StatusBanner's `phase label itself stays visible briefly after a stage transition so the user sees the most recent phase without flicker` (verbatim from `StatusBanner.swift` per `sample-onboarding-app.md`). Anti-flicker is a documented design decision, encoded in code comments.
+
+**Preference recorded:** **`prefers-reduced-motion` / `accessibilityReduceMotion` must be respected by default, not opt-in. Stagger animations have a total-time cap, not just a per-item interval. Anti-flicker behavior is a first-class design concern, not an afterthought.**
+
+---
+
+## 6. Voice + error UX: verb+object, what→why→fix, calm degradation
+
+**Universal non-negotiable:** *"When something fails, explain what happened, preserve context, give a next step"* (alt doc §1.5 Recover) + *"Resilient to imperfect input"* (alt doc §2.9).
+
+**What works (primary apps):**
+- **Secrets Vault** — explicit three-part error pattern named in project CLAUDE.md (cited `secrets-vault-macos.md`): *"Errors: what → why → fix pattern."* Plus voice rule: *"Verb+Object labels, contextual loading ('Deriving encryption key…')"* — loading messages name the actual operation.
+- **Sample Offline iOS** — *"Errors surface inline (red footnote) without removing cached rows — offline still shows the last good list"* (`CampsListView.swift` code comment per `sample-offline-ios.md`). On error, the cache is preserved — graceful degradation in action.
+- **Sample Voice App** — `Haptics.impact(.light)` paired with state change on every CTA tap (`HomeView.swift:81` per `sample-voice-ios.md`) — action feedback via haptic + visible state, not just one or the other.
+
+**Preference recorded:** **errors are calm and informative (what / why / fix); they never wipe state; loading is named ('Deriving encryption key…' not 'Loading…'); actions get both haptic + visual confirmation on mobile.**
+
+---
+
+## 7. Anti-pattern roundup (avoid these by default)
+
+| Anti-pattern | Source | Why it fails |
+|---|---|---|
+| Inline pixel-size typography | `sample-onboarding-app.md` | Ladder not enforceable, scale bump not greppable, accessibility uplift impossible at scale |
+| Theme-toggle for brand color | `sample-decision-app.md` | Brand fungibility — *"design-toggle app"* not *"Decision Doctor"* |
+| Tinted error containers without rationale | (sample reader gets a pass with rationale) | Default fails Calm Precision's text-color-only rule; needs reading-flow density justification when used |
+| System-default with no brand voice | `sample-offline-ios.md` | Indistinct from any other camp-management list; appropriate for offline-first utility, inappropriate for a brand-led product |
+| Off-grid spacing without flag | (Sample Timer App handles this well — off-grid values are noted as "exotic" in code comments per `sample-timer.md`) | Drift cause; the discipline is the comment, not the value |
+
+---
+
+## 8. What this means for new builds
+
+A new app in this ecosystem should, in priority order:
+
+1. **Token files first** — `Theme/Colors`, `Theme/Typography` (or `index.css`-equivalent for web) before the first view is written. Use Sample Voice App / Sample Timer App / Secrets Vault as templates.
+2. **One accent. Single. Don't theme-toggle.** Sample Product App is the strictest example.
+3. **Three-line text hierarchy** baked into the typography enum. Secrets Vault's `VaultTypography.title/.description/.metadata` is the textbook.
+4. **Touch targets at the component layer.** Sample Product App's `.btn-primary` is the example.
+5. **`prefers-reduced-motion` / `accessibilityReduceMotion` from day one.** The sample decision app's single-CSS-rule approach is the cheapest implementation.
+6. **Errors are calm, informative, non-destructive.** The sample offline app's offline-preserves-cache + Secrets Vault's what→why→fix pattern combine into a single rule.
+7. **Multi-form-factor via viewport-scale tokens, not forked themes.** Sample Timer App's `\.viewportScale` is the reference; the multi-pattern framework draft (`design-patterns-multi.md`) is where this becomes formal if/when prototyped.
+
+When deviating: name the deviation in the token file's comments, the way Sample Timer App flags off-grid spacing and Sample Reader flags tinted error containers. The discipline is the comment.
+
+---
+
+## 9. Live-Capture Addendum (2026-05-26)
+
+Live IBR captures on the 4 primaries surfaced texture observations source-read could not:
+
+- **Tokens extend to haptics.** Sample Voice App's `HapticVocabulary.swift` (`.confirm/.reward/.warn/.progress/.selection`) is a semantic layer above UIKit feedback generators, parallel to `Theme.fontDisplay` above `Font.system(...)`. Treat haptics as first-class tokens on mobile. Evidence: `sample-voice-ios.md` §Live IBR Capture.
+- **Selection signaling is NOT consistent across primaries.** Sample Voice App uses solid-fill on selected (filter pills, tab); Sample Timer App uses 1pt border + glyph check on selected mode card. Both legitimate; choose per surface density and decision weight, not by a single rule. Evidence: `sample-voice-ios.md` + `sample-timer.md`.
+- **Empty states diverge by intent.** Sample Voice App floats SF Symbol + copy (first-use); Sample Timer App renders milestone ladder (unlock-progression); Sample Product App uses text label (transient load). Match vocabulary to user reason-for-emptiness.
+- **AI-assist lives inside input when input is the primary action.** Sample Product App's sparkle "Enhance" sat inside the textarea (`sample-product.md` §Live IBR Capture, 2026-05-03). Generalizable. (As of 2026-05-26 refresh, Sample Product App's landing has been redesigned to headline+CTA-first; the input-with-Enhance pattern moved one click deeper. Pattern still holds, citation is historical.)
+- **Brand-identity-in-chrome is universal, treatment is product-specific.** All 4 primary apps have distinct brand chrome — no two alike. System-default brand chrome is the explicit deviation.
+- **Two-speed motion on a single control.** Sample Product App primary CTA: `transition: background 0.2s, transform 0.15s` — geometry settles 50ms faster than color for snappier press feedback while color carries texture. When a control shifts both color and shape, tune per channel. (`sample-product.md` §Fresh Live IBR Capture)
+- **Error-state restraint mirrors main-app restraint.** Sample Product App 404 = 5 elements (icon, title, body, CTA, card). No illustration, no error code, no search. Empty space carries the signal. Pattern: error/empty states inherit the app's restraint discipline; do not overcompensate.
+- **Friction-removal microcopy has a stable shape:** short / two-clause / bulleted (`·`) / muted ≤12pt, placed under a CTA when account/cost/lock-in friction is the user concern. Sample Product App uses the same recipe on the landing CTA (`No account required · Free to try`) and the auth card (`No account · Groq Llama 3.3`).
+
+These supersede any prior synthesis claim that read selection-signaling or empty-state vocabulary as universal. The `evidence-capture-policy.md` reference codifies why source-read alone could not produce these observations.

package/skills/ui-design/references/evidence-capture-policy.md

@@ -0,0 +1,55 @@
+# Evidence Capture Policy
+
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+> **DEPRECATION SHIM (one release cycle).** Canonical source migrated to the `ui-guidance` plugin → load via `Skill("ui-guidance:evidence-policy")`. This file remains in build-loop as a transition aid; future updates land in the plugin. *(Renamed from `evidence-capture-policy` in ui-guidance v0.2.0.)*
+
+How to gather design evidence from owned apps. Routes a build-loop dispatch to the right collection method based on what's being asked.
+
+## Two evidence types, two methods
+
+### 1. Token extraction — source-of-truth read is canonical
+
+For numbers, role names, palette values, breakpoints, type ladders, spacing units, and any other tokenized design primitive:
+
+- Read the source-of-truth file directly: `Theme.swift`, `globals.css`, `tailwind.config.{ts,js}`, `tokens.json`, `design-tokens/*.scss`, equivalent.
+- This is cheaper, more accurate, version-locked to the commit, and immune to render-time variation (theme overrides, accessibility scaling, dynamic type).
+- A screenshot of a rendered button cannot tell you whether its corner radius is 8pt or 9pt; the token file can.
+
+### 2. Interaction texture — live IBR capture is mandatory
+
+For motion timing, haptic feedback intensity, real-render gradients / shadows / blur, hit-target responsiveness, scroll feel, transition mid-states, and any moment where the rendered output may diverge from what the token file predicts:
+
+- Boot the simulator / start the dev server / open the binary.
+- Capture screens via IBR (`ibr:native-testing`, `ibr:screenshot`) or simctl + idb for iOS, or browser screenshot for web.
+- Augment (do not replace) the source-read evidence with observed render behavior.
+- Source files cannot show: a glow shadow that renders subtler than its parameters predict; a haptic vocabulary layer above the visual tokens; a selection state that uses border+glyph instead of fill; an empty-state ladder pattern that has no token representation.
+
+## Decision rule for build-loop dispatches
+
+When a build's evidence requirement is:
+
+| Question | Method |
+|---|---|
+| "What are the tokens?" | Source-read only |
+| "How does it feel?" | Live capture only |
+| Both | Both, with explicit chunks per evidence type in the plan |
+
+Default: when in doubt, do both. Source-read is cheap; live capture surfaces what source-read structurally cannot.
+
+## Failure protocol
+
+Live capture failures are non-blocking. Record verbatim in the evidence file:
+
+- The specific error string (`xcodebuild` output, `npm run dev` stderr, `idb` failure).
+- What was attempted (commands run, env probed).
+- What would unblock (missing env var, missing Postgres, missing sim).
+- The capture date of any pre-existing IBR artifacts used as fallback live-render evidence (with a freshness window — typically ≤30 days under no-functional-changes conditions).
+
+A documented failure block is acceptable evidence. The synthesis layer must not silently treat missing live capture as "no observation."
+
+## Cross-reference
+
+This policy supersedes the Phase 6 Learn entry from the prior universal-design enrichment run, which reported a "scan-attempt vs source-read tradeoff" as if they were substitutes. They are not substitutes — they are complementary, and a build-loop dispatch must choose explicitly per evidence type. The prior recurring-pattern entry should be re-tagged: "source-read is canonical for tokens, live capture is mandatory for texture; do not collapse one into the other."
+
+When this policy and another reference disagree about evidence sourcing, this policy wins for token-vs-texture routing.