@tyroneross/build-loop 0.30.3

package/skills/ui-design/references/ui-guidance-sources.md

@@ -0,0 +1,330 @@
+<!-- SPDX-FileCopyrightText: 2025-2026 Tyrone Ross, Jr <46267523+tyroneross@users.noreply.github.com> | SPDX-License-Identifier: Apache-2.0 -->
+
+# UI Guidance Source Map
+
+Canonical build-loop entrypoint:
+
+- Skill: `build-loop:ui-design`
+- Agent: `agents/design-contract-specialist.md`
+- Runtime contract: `.build-loop/app-contract/ui.md`
+- Universal principles: `skills/ui-design/references/universal-design-principles.md`
+- Implementer prompt: `skills/build-loop/templates/ui-subagent-prompt.md`
+- Input/output contract: `skills/build-loop/references/ui-io-contract.md`
+- Recent structure picker: `skills/build-loop/references/recent-design-structures.md`
+- Validator: `agents/ui-validator.md`
+
+Use this file to choose sources. Do not paste the whole map into implementer prompts.
+
+## Design Guidance Model
+
+Use the guidance as a layered model:
+
+| Layer | Role | Examples |
+|---|---|---|
+| Product contract | Defines the user job, inputs, outputs, operations, platform, data shape, and risk | `ui-io-contract.md`, `.build-loop/app-contract/ui.md` |
+| Universal communication and experience design | Governs answer-first structure, one primary focus, continuity, wayfinding, process visibility, graceful degradation, MECE grouping, semantic hierarchy, evidence integrity, native primitives, accessibility, and rendered QA across UI, writing, images, decks, docs, operational workflows, reports, spreadsheets, and PDFs | `universal-design-principles.md` |
+| Structural foundation | Governs cognitive predictability and implementation discipline | Calm Precision |
+| Project surface | Preserves current app conventions and brand | tokens, theme files, components, screenshots, selected mockups |
+| Structure or style mode | Selects the layout/mood that fits the current surface | Conversational Command, Bento Dashboard, Pipeline Wizard, Outcome Ledger, Pyramid Detail, Glass Workspace, Warm Craft, Data Narrative, native mobile, AI Artifact Canvas |
+| Validation | Proves the result works and renders | `ui-validator`, scanner, browser/simulator screenshots, contract traceability |
+
+Do not treat every source as equal. Universal communication principles are the cross-medium baseline. Calm Precision is the UI structural baseline, not a competing mode. Recent structures and style systems are selected after the product contract is known.
+
+## Build-Loop Runtime Guidance
+
+Load these first for active builds:
+
+- `skills/build-loop/references/ui-io-contract.md` - required UI plan contract.
+- `skills/ui-design/references/universal-design-principles.md` - cross-medium doctrine for app UI, writing, images, operational workflows, decks, docs, reports, spreadsheets, PDFs, and other communication or information artifacts.
+- `skills/build-loop/references/recent-design-structures.md` - compact recent structure library; options, not mandates.
+- `skills/build-loop/templates/ui-subagent-prompt.md` - prompt preamble for UI implementers.
+- `skills/build-loop/phases/ui-validation.md` - validation gates and visual evidence requirements.
+- `skills/build-loop/fallbacks.md` - degraded UI tooling path.
+- `references/ui-spotcheck-protocol.md` - visual spot-check protocol.
+- `docs/rfcs/2026-05-ui-validator-agent.md` - ui-validator rationale.
+
+## Universal Design Principles
+
+`skills/ui-design/references/universal-design-principles.md` is the detailed overview for principles that should apply across every generated or reviewed artifact, not only app UI.
+
+Boundary:
+
+- Universal principles define the invariant decision process: orient, focus, connect, progress, recover, resolve.
+- Routers classify the artifact or workflow and narrow defaults. Use Calm Precision router-style sources for this layer.
+- Domain skills provide the exact primitive: UI component, writing transition, image composition, slide pattern, document style, data chart, or operational checkpoint.
+
+What it controls:
+
+- Purpose before presentation: audience, job, context, decision, output, and risk.
+- Answer-first structure: governing thought, primary state, recommendation, or conclusion visible early.
+- One primary focus per viewport, slide, section, page, chart, table, or artifact unit.
+- Wayfinding: current state, prior context, next step, and return path.
+- Continuity: transitions that preserve orientation across writing, UI, images, decks, docs, and data.
+- Process visibility: purpose, start state, target end state, route, current step, checkpoints, and safe stop for rapidly changing workflows.
+- Graceful degradation: clear message and recovery path when the preferred route fails.
+- MECE grouping and reader-question discipline.
+- Hierarchy before decoration: position, grouping, type, contrast, spacing, and order before visual effects.
+- Functional and evidence integrity: real interactions, real data, sourceable claims, and no fake production-looking proof.
+- Native primitives: semantic UI components, PowerPoint placeholders/bullets, Word styles/numbering/tables, formulas, chart objects, headings, and alt text.
+- Accessibility, state/recovery treatment, and rendered visual QA.
+
+Use it before medium-specific guidance for writing, images, decks, documents, reports, spreadsheets, PDFs, and UI surfaces that present dense or decision-bearing information.
+
+## Calm Precision
+
+Calm Precision is the default structural doctrine for build-loop UI work.
+
+Calm Precision router sources checked:
+
+- `calm-precision-v1-1/0_Router.md`
+- `calm-precision-v1-1/1_Navigation_Structure.md`
+- `calm-precision-v1-1/5_Motion_States_Identity.md`
+
+Reusable router pattern:
+
+- Classify archetype first.
+- Apply defaults before loading a domain file.
+- Ask only at high-impact or ambiguous choice points.
+- Count steps and validate optional additions.
+- Flag decisions made without asking.
+- Keep component option catalogs in domain files, not in universal guidance.
+
+Where build-loop uses it:
+
+- `skills/build-loop/templates/ui-subagent-prompt.md` requires `calm-precision` for all UI implementers.
+- `skills/build-loop/phases/ui-validation.md` lists `calm-precision` beside `build-loop:ui-design` and `design-contract-specialist` for web, mobile, and native UI routing.
+- `skills/build-loop/fallbacks.md` carries a condensed Calm Precision fallback when the external skill is unavailable.
+- `agents/implementer.md` uses Calm Precision examples for usability queue fixes such as replacing background status pills with text-color status.
+- `agents/synthesis-critic.md` treats Calm Precision copy tone and subjective UI claims as reviewable synthesis dimensions.
+
+What it controls:
+
+- Visual hierarchy and one clear L1 anchor.
+- Grouping, borders, dividers, and content-to-chrome ratio.
+- Action weight, touch targets, and card/button affordance.
+- Disclosure depth, loading/empty/error states, and copy clarity.
+- Motion restraint and reduced-motion compliance.
+- Functional integrity: no fake buttons, no real-looking mock data, real handlers for interactive UI.
+- Perceptual-science traceability: every Calm Precision rule should map to a named foundation such as Gestalt, Fitts' Law, Hick's Law, Cognitive Load, Signal-to-Noise Ratio, Affordance Theory, Temporal Gestalt, Dual-Coding, Pragmatic Inference, Attentional Cascade, the Cooperative Principle, Fault Tolerance, or Information Scent/Density. This is what lets design-contract output defend choices as evidence-backed rather than taste-based.
+
+What it does not decide by itself:
+
+- Whether the surface should use Glass Workspace, Warm Craft, Aurora Deep, Data Narrative, or another style mode.
+- Product brand personality, token palette, or final typography roles when a project-specific design system exists.
+- Native platform conventions that Apple/Web/etc. impose.
+
+In practice: start with Calm Precision for structure, then select the mode that fits the product. For example, Aurora Glass can layer translucent surfaces over a Calm Precision layout; Warm Craft can change warmth and texture while preserving hierarchy and action discipline; Data Narrative adds evidence/storytelling patterns while keeping decision-first labels and source traceability.
+
+## ui-guidance plugin (canonical home, 2026-05-27+)
+
+The cross-project design library is now available as the `ui-guidance` plugin. Prefer qualified Skill invocations over absolute paths:
+
+| What you need | Invocation |
+|---|---|
+| Cross-medium doctrine (UI + writing + decks + ops workflows) | `Skill("ui-guidance:principles")` |
+| Owned-app design preferences (typography, color, touch targets, motion, error UX) | `Skill("ui-guidance:preferences")` |
+| Multi-pattern token framework (mobile / tablet / web / watch resolution) | `Skill("ui-guidance:tokens")` |
+| Source-read vs live-IBR-capture routing | `Skill("ui-guidance:evidence-policy")` |
+| 4 design modes (Atmospheric / Glass Workspace / Warm Craft / Data Narrative) | Load `references/modes/<mode>.md` directly (catalog, not skill) |
+| Chart / KPI / table / sparkline / timeline patterns | `Skill("ui-guidance:data-viz")` |
+| Wayfinding, tab/stack/drawer/sheet selection, breadcrumbs | `Skill("ui-guidance:navigation")` |
+| L1/L2/L3 ladder, luminance tiers, type scale | `Skill("ui-guidance:hierarchy")` |
+| Form factors, breakpoints, viewport-scale tokens, watch glance | `Skill("ui-guidance:responsive")` |
+| Action feedback, haptics, loading, confirmation, error UX | `Skill("ui-guidance:feedback")` |
+| Motion, transitions, stagger, prefers-reduced-motion | `Skill("ui-guidance:motion")` |
+| iOS / iPhone / iPad / SwiftUI | `Skill("ui-guidance:ios")` |
+| macOS / Mac native / menu bar / NSToolbar | `Skill("ui-guidance:macos")` |
+| Web / Next.js / React / ARIA / WCAG 2.1 AA | `Skill("ui-guidance:web")` |
+
+**ui-guidance v0.2.0** is a flat-but-grouped IA: 10 cross-platform topic skills + 3 platform skills + design-mode catalog. The bulky reference files (`ios/references/full.md`, `web/references/full.md`, `data-viz/references/full.md`) load on demand via the skill body — do not paste them into implementer prompts.
+
+**Bundled in the plugin under `references/`** (organized for cross-reference, not for direct path-based access from outside the plugin):
+
+- `references/design-evidence/` — 8 owned-app evidence files
+- `references/screenshots/{sample-voice, sample-timer, sample-product}/` — 16 live IBR captures (2026-05-26)
+- `references/style-modes/` — `aurora-deep.md`, `aurora-glass.md`, `warm-craft.md` catalog briefs
+- `references/tools/mockup-gallery-reviewer.html` — mockup-rating browser tool
+- `references/historical/universal-design-principles-original.md` — pre-migration 365-line original
+
+Mockup-gallery session data (`.mockup-gallery/selections.json`, `mockups/` rated HTML files) still live at the repo root for the mockup-gallery plugin's own use; the canonical guidance synthesized from those mockups lives in the skills above.
+
+### Build-loop transition shims (one release cycle)
+
+The four reference files at `skills/ui-design/references/{universal-design-principles.alt.md, design-preferences-from-owned-apps.md, design-patterns-multi.md, evidence-capture-policy.md}` are now deprecation shims pointing at the plugin. Remove after one release cycle. The plugin is the canonical source.
+
+Current pattern families visible here:
+
+- **Calm Precision** - structural default for professional tools and mobile-first workflows.
+- **Glass Workspace / Aurora Glass** - structured workspace personality; often a reversible surface layer over Calm Precision.
+- **Aurora Deep** - primary dark developer/data workspace when dense atmosphere is useful.
+- **Warm Craft** - reflective writing, knowledge work, and human-in-the-loop planning.
+- **Data Narrative** - charts, research, trends, market intelligence, and decision-first evidence.
+- **Atmospheric / immersive variants** - focus, timer, wellness, and state/mood-driven surfaces.
+- **Decision Doctor structures** - Sunrise Hero, Electric Mint, Pipeline Wizard, Bento Dashboard, Bloom Organic, Outcome Ledger, and Pyramid Detail.
+
+## Interface Built Right
+
+IBR has rich design and validation material, but build-loop does not auto-route through IBR.
+
+Additional router sources checked:
+
+- `interface-built-right/references/web-design/0_router.md`
+- `interface-built-right/references/ios-design/0_router.md`
+- `interface-built-right/skills/ios-design-router/SKILL.md`
+- `interface-built-right/.codex-plugin/skills/ui-ux-guidance/SKILL.md`
+
+These reinforce the same split: archetype/router first, then platform/domain references, then validation contract.
+
+High-signal sources:
+
+- `interface-built-right/.codex-plugin/skills/design/SKILL.md`
+- `interface-built-right/.codex-plugin/skills/ui-ux-guidance/SKILL.md`
+- `interface-built-right/skills/design-director/SKILL.md`
+- `interface-built-right/skills/design-guidance/SKILL.md`
+- `interface-built-right/skills/design-implementation/SKILL.md`
+- `interface-built-right/skills/design-reference/SKILL.md`
+- `interface-built-right/skills/design-system/SKILL.md`
+- `interface-built-right/skills/design-validation/SKILL.md`
+- `interface-built-right/skills/ui-guidance-library/SKILL.md`
+- `interface-built-right/references/web-design/`
+- `interface-built-right/references/ios-design/`
+- `interface-built-right/mobile-ui/`
+- `interface-built-right/templates/patterns/`
+- `interface-built-right/src/ui-guidance/`
+
+Use only when the user explicitly asks for IBR or when a selected IBR artifact is passed to the specialist as evidence. Do not make IBR the default build route.
+
+## Mockup Gallery
+
+Use for mockup drafting, selection, or review:
+
+- `mockup-gallery/COMMON.md`
+- `mockup-gallery/DESIGN.md`
+- `mockup-gallery/DESIGN-SELECTED.md`
+- `mockup-gallery/AGENTS.md`
+- `mockup-gallery/commands/mockup-gallery.md`
+- `mockup-gallery/skills/mockup-review/SKILL.md`
+- `mockup-gallery/.agents/skills/mockup-review/SKILL.md`
+- `mockup-gallery/memories/global/design-preferences.md`
+
+Mockup Gallery helps create and judge candidate visuals. Build-loop still records the selected direction in `.build-loop/app-contract/ui.md`.
+
+Checked sources confirm Mockup Gallery is a lifecycle and approval system, not a universal principle source. Reusable universal lessons are scratch-first exploration, state visibility, rating semantics, approved-target guardrails, implementation tracking, and versioning instead of overwriting.
+
+## Documents, Decks, And Information Artifacts
+
+These sources are not UI routes, but they contain reusable information-design guidance that applies to Build Loop artifacts and UI-generated outputs.
+
+Claude local session sources inspected:
+
+- `deck-builder/SKILL.md` (local Claude session snapshot; path redacted)
+- `calm-precision-pptx/SKILL.md` (local Claude session snapshot; path redacted)
+- `design-system/SKILL.md` (local Claude session snapshot; path redacted)
+- `accessibility-review/SKILL.md` (local Claude session snapshot; path redacted)
+- `storyline-builder/SKILL.md` (local Claude session snapshot; path redacted)
+- `pyramid-principle-core/SKILL.md` (local Claude session snapshot; path redacted)
+- `pptx-design/SKILL.md` (local Claude session snapshot; path redacted)
+- `docx/SKILL.md` (local Claude session snapshot; path redacted)
+
+Codex runtime sources inspected:
+
+- `openai-primary-runtime/documents/.../skills/documents/SKILL.md` (Codex runtime snapshot; path redacted)
+- `openai-primary-runtime/presentations/.../skills/presentations/SKILL.md` (Codex runtime snapshot; path redacted)
+- `openai-primary-runtime/presentations/.../skills/presentations/subagent-instructions.md` (Codex runtime snapshot; path redacted)
+
+Reusable guidance captured into `universal-design-principles.md`:
+
+- Storyline and governing thought before rendering.
+- Pyramid/MECE logic and answer-first structure.
+- One assertion per slide or artifact unit.
+- Cross-medium continuity, wayfinding, and graceful degradation.
+- Template, preset, and project-system inheritance before overrides.
+- Native Office/document primitives instead of visual fakes.
+- Claim, metric, source, and asset provenance.
+- Rendered visual QA for decks and docs, not only structural extraction.
+- Accessibility as a design baseline across UI and documents.
+
+Note: Local Claude session paths are intentionally redacted from this public package. Use the host's current plugin/session lookup rather than copying historical absolute paths.
+
+## Research And Vault Corpus
+
+Use for background, trend history, or long-term preference synthesis. Summarize before passing to implementers.
+
+High-signal local research:
+
+- `research/topics/design/`
+- `research/projects/<project>/design-brief-2026-04-20.md`
+
+High-signal vault folders:
+
+- `vault/raw/engineering/ui-design-research-corpus-2026/`
+- `vault/raw/engineering/ui-ux-calm-precision/`
+- `vault/raw/engineering/ui-ux-central-library/`
+- `vault/raw/engineering/ui-ux-ibr-references/`
+- `vault/raw/engineering/ui-ux-spec-review-input-output-coverage-2026/`
+- `vault/raw/engineering/native-ios-watchos-ui-research-2026/`
+- `vault/raw/engineering/calm-precision-v1-1/`
+- `vault/raw/engineering/calm-precision-native-apple-platforms-v1-1-2026/`
+- `vault/raw/engineering/ui-ux-private-ios-guidance/`
+- `vault/raw/engineering/ui-ux-misc-app-design/`
+- `vault/outputs/drafts/2026-05-10-ui-preferences-mobile-first-web-apps-aggregate.md`
+- `vault/outputs/drafts/2026-05-10-private-product-mobile-first-ui-guidance.md`
+
+## Build-Loop-Memory
+
+Durable long-term design memory belongs here:
+
+- `build-loop-memory/design/README.md`
+- `build-loop-memory/decisions/build-loop/0094-2026-05-24-build-loop-design-structure-memory-policy.md`
+- `build-loop-memory/projects/<project>/design/` when project-specific design memory exists.
+- `build-loop-memory/indexes/` for discovery after the migration structure settles.
+
+Build-loop's runtime references should be refreshed from build-loop-memory when a design structure becomes repeatedly used, explicitly selected/rejected, or materially changes the selection policy.
+
+## Project-Local Hidden Sources
+
+Check the target project before cross-repo sources:
+
+- `<project>/.build-loop/app-contract/ui.md`
+- `<project>/.build-loop/research/*ui*`
+- `<project>/.build-loop/research/*design*`
+- `<project>/.build-loop/coordination/*ui*`
+- `<project>/.build-loop/coordination/*design*`
+- `<project>/.research/` when present.
+- `<project>/docs/**` for design-system, UX, UI, accessibility, mockup, or visual guidance.
+- `<project>/.mockup-gallery/selected.json`, `ratings.json`, `implemented.json`, or `selections.json`.
+
+These override generic guidance when they represent the current project contract.
+
+## Generated Or Non-Canonical Sources
+
+Do not treat these as canonical design guidance unless a plan explicitly names a generated artifact as evidence:
+
+- `.ibr/`
+- `.navgator/`
+- `.bookmark/`
+- `.claude/bookmarks/`
+- `node_modules/`
+- `.next/`, `dist/`, `build/`
+- Playwright reports, screenshots, logs, caches, and `tsconfig.tsbuildinfo`
+- Swift `.build/`, DerivedData, module caches, and package artifacts
+
+## Refresh Scan
+
+Use targeted scans instead of broad full-disk loads:
+
+```bash
+rg -l --hidden \
+  --glob '!**/.git/**' --glob '!**/node_modules/**' --glob '!**/.next/**' \
+	  --glob '!**/dist/**' --glob '!**/build/**' --glob '!**/.build/**' \
+	  -i '(ui guidance|ui/ux|ux guidance|design guidance|design system|calm precision|interface built right|visual style|design direction|mockup|wireframe|interaction|accessibility|touch target|design contract|app-contract|recent design|data visualization)' \
+	  "$BUILD_LOOP_REPO" \
+	  "$BUILD_LOOP_MEMORY_REPO" \
+	  "$INTERFACE_BUILT_RIGHT_REPO" \
+	  "$UI_GUIDANCE_REPO" \
+	  "$MOCKUP_GALLERY_REPO" \
+	  "$RESEARCH_ROOT" \
+	  "$VAULT_ROOT"
+```
+
+Record newly durable structures in build-loop-memory; record runtime choices in `.build-loop/app-contract/ui.md`.

package/skills/ui-design/references/universal-design-principles.alt.md

@@ -0,0 +1,182 @@
+<!-- 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:principles")`. This file remains in build-loop as a transition aid; future updates land in the plugin. *(Renamed from `universal-experience-principles` in ui-guidance v0.2.0.)*
+
+# Universal Experience Principles
+
+Cross-medium doctrine for any artifact that has to communicate, guide a person through an experience, or expose a changing process. Applies to app UI, writing, images, native screens, slides, documents, spreadsheets, reports, charts, version control, deploys, sync, automation, and design handoff. Build Loop is the runtime home; the principles are not Build Loop-specific.
+
+Core rule: **medium changes the primitive; the principle stays stable.**
+
+## 1. Universal Experience Model
+
+Every artifact does the same six jobs. If a job is missing, the user has to do it themselves.
+
+1. **Orient** — make where they are, why it matters, and the frame they are in obvious.
+2. **Focus** — make the primary message, object, decision, or action obvious.
+3. **Connect** — show how this piece relates to what came before and what comes next.
+4. **Progress** — make movement through the story, task, workflow, or system visible.
+5. **Recover** — when something fails, explain what happened, preserve context, give a next step.
+6. **Resolve** — end with a conclusion, action, saved state, handoff, source, or intentional stop.
+
+Continuity primitives differ by medium (transition phrase, breadcrumb, motion, visual path, branch state) but the requirement does not.
+
+## 2. Non-Negotiables
+
+These ten apply to every artifact produced or reviewed.
+
+1. **Purpose before presentation.** Name user, job, context, time budget, decision, and output before choosing layout, style, or tool.
+2. **Answer first.** The governing thought or primary state is visible early. Support comes after, not before.
+3. **One primary focus.** Per viewport, slide, section, page, screen, table, or chart. Competing primaries are a design failure.
+4. **Wayfinding is mandatory.** The user knows where they are, what changed, what's next, how to get back. Landmarks stay consistent across the artifact; there are no dead ends.
+5. **Process visibility.** Anything that changes in stages exposes purpose, start state, target end state, current step, checkpoint, and recovery.
+6. **MECE structure.** Peer ideas are the same kind of thing, non-overlapping, collectively sufficient for the parent claim.
+7. **The system tells the truth about its own state.** Interactive controls work or are clearly labeled non-production. Data, metrics, and visual proof are real, sourced, or labeled illustrative — no mock-as-real. Loading, empty, error, stale, permission, and partial-result states are designed, not afterthoughts.
+8. **Every action gets perceivable feedback.** Any user action — click, tap, submit, send, commit, run, save, edit, schedule — is acknowledged immediately and the resulting state change is perceivable. Disabled until pre-conditions are met; visibly enabled when actionable; in-progress during work; result confirmed at completion. No silent success, no ambiguous in-flight. Use whichever channels the medium offers: **visual** (state change, animation, toast, indicator), **haptic** (tap / impact / notification on mobile and wearable), **audible** (system sounds, voice confirmation), and **textual** (status line, echo, receipt). On mobile and wearable, haptic is often the primary confirmation when the visual change is small or briefly off-screen; pair it with a visible change wherever possible. Respect platform conventions (iOS `UIImpactFeedbackGenerator` semantic levels, watchOS haptic types, Android `HapticFeedbackConstants`, reduce-motion / silent-mode preferences).
+    - *Cited precedent:* Sample Voice App CTA pairs `Haptics.impact(.light)` with visible state + two-layer `glowShadow()` — see `sample-voice-ios.md`. Sample Product App enforces 44pt touch target at the `.btn-primary` component class — see `sample-product.md`.
+9. **Resilient to imperfect input.** Accept multiple shapes (string / object / markdown / null; title / headline / name). Prefer partial results with warnings over total failure. Degrade along documented fallback paths. Don't reject what can reasonably be interpreted.
+10. **Separation is earned.** Borders, boxes, dividers, and backgrounds only when they encode a real relationship break. Whitespace and alignment carry structure first; chrome only when whitespace fails.
+    - *Cited precedent:* Sample Product App uses a single accent (`--primary === --accent === --ring === #f0b65e`) and warm-monochromatic palette discipline — strictest single-accent in inventory. See `sample-product.md`. Counter-pattern: the sample decision app's three-theme toggle (`[data-theme="A"|"B"]`) preserves semantic meaning across visual presentation but dilutes brand voice — see `sample-decision-app.md`.
+11. **Content fits its container, or the container fits the content.** Clipping, truncation without recovery, awkward wraps, and overflow are design failures. Decide which side flexes (fixed container with overflow recovery, or fluid container that grows). Critical content never shrinks below its reading threshold to fit.
+12. **Visual hierarchy is one-glance recoverable.** A user reading at speed knows what is most important, what is next, what is supporting — from position, size, weight, contrast, and spacing alone. If color is removed, the hierarchy still holds.
+    - *Cited precedent:* Secrets Vault's `VaultTypography.title/.description/.metadata` (15/13/11pt) maps role names directly to L1/L2/L3 — see `.build-loop/design-evidence/secrets-vault-macos.md`. Anti-pattern: the sample onboarding app's inline pixel sizes across one view (12/13/14/15/16/18/20/34) — see `sample-onboarding-app.md`.
+13. **Fit form to information.** Prose, bullets, table, chart, diagram, checklist, form, callout, or slide rhythm chosen for the reading task — not the template.
+14. **Native primitives over visual fakes.** Use the medium's semantic structures: UI components, slide placeholders, document styles, table geometry, chart objects, alt text, headings, source notes. Don't fake them with glyphs, manual spacing, or screenshots.
+15. **Verify the rendered artifact.** Inspect the real output surface before declaring done. Screenshots for UI; rendered pages for docs and decks; live render for charts.
+
+**Visual-craft inheritance.** Detailed grouping, spacing, type scale, semantic color, progressive disclosure, action weight, and accessibility numbers are inherited from the underlying design system. The default is **Calm Precision**; deviations need a named exception in the artifact contract. Two universal pointers worth naming explicitly:
+
+- **Interaction targets match input precision.** Touch needs more area than mouse; mouse more than keyboard focus; watch, remote, and voice each have their own envelope. The principle: a target the user can hit on the first try, comfortably, with the device in hand. Specific minimums live in platform skills (`accessibility-review`, platform HIGs).
+- **Motion serves comprehension, not decoration.** Animate when it explains origin, destination, or state change. Duration short enough not to delay, long enough to be perceived. Respects reduced-motion preferences.
+  - *Cited precedent:* The sample decision app's single CSS rule overrides all animations to 0.01ms under `prefers-reduced-motion` (`app/globals.css:65-71`) — see `sample-decision-app.md`. Secrets Vault caps stagger at 400ms total (60ms × N items) — see `secrets-vault-macos.md`. The sample onboarding app documents anti-flicker behavior in code comments — see `sample-onboarding-app.md`.
+- **Multi-form-factor via viewport-scale tokens.** When one codebase ships across iPhone, iPad, Mac, and Watch, scale a single hierarchy by a runtime env var rather than forking themes per platform.
+  - *Cited precedent:* Sample Timer App's `\.viewportScale` env (1.0× iPhone → 1.5× iPad → live-window-resize Mac → separate watch palette + AOD dim variants); see `sample-timer.md`. Formalized as Pattern 1 / Pattern 4 in the multi-pattern framework draft at `skills/ui-design/references/design-patterns-multi.md`.
+
+## 3. Medium Adapters
+
+Same six jobs; different primitives.
+
+| Medium | Continuity | Recovery | Proof |
+|---|---|---|---|
+| **Writing** | Topic sentences, transition phrases, repeated terms, parallel structure, SCQA | State the supported conclusion, name the assumption, name the next input needed | Claims, citations, examples, line of reasoning |
+| **Images / media** | Visual path, framing, focal hierarchy, captions, before/after pairing | Alt text, fallback caption, role label (concept / reference / production) | Source image, generation prompt, provenance |
+| **App UI** | Breadcrumbs, nav state, preserved scroll, inline expansion, side drawer, bottom sheet, progress stepper, motion that explains origin/destination | Loading / empty / error / stale / permission / offline / retry / saved-state / partial-result / fallback states | Real data, working handlers, source labels, interaction tests, screenshots |
+| **Decks** | Claim spine, action titles, section dividers, agenda markers, repeated footer grammar | Mark missing inputs, move unsupported numbers to appendix, preserve template rhythm | Source footnotes, proof objects, rendered slide QA |
+| **Documents / reports** | Heading ladder, lead paragraphs, captions, cross-references, page furniture | Explain constraints, preserve edit trail, route unresolved items to appendix | Citations, styles, numbering, table geometry, rendered page QA |
+| **Spreadsheets / data** | Frozen headers, stable dimensions/measures, filters, summary-to-detail flow | Formula warnings, missing-data treatment, source flags, named assumptions | Formulas, source lineage, audit checks, charts/tables tied to decisions |
+| **Operational workflows** | Purpose, start state, target end state, current step, checkpoint, owner, status delta, next action | Rollback path, retry path, partial-completion note, blocked reason, safe stopping point | Git status, diff, commit SHA, test result, deploy target, migration log, sync record |
+
+## 4. One Idea, Across Media
+
+Two worked examples showing the same principle expressed in seven media.
+
+**Graceful recovery** (principle: preserve context, name what happened, offer a next step):
+
+- **Writing:** "The source does not support that claim yet. Supported conclusion: X. Assumption: Y. Next input needed: Z."
+- **Image:** Caption reads "Concept render — labels and quantities not verified."
+- **App UI:** Toast: "Refresh failed. Showing last saved version from 14:02. Retry · Switch source · Continue with cached."
+- **Deck:** Footnote: "Metric not available from public source as of 2026-05; kept qualitative pending research."
+- **Document:** Margin note: "Render check failed; layout unverified. Content edits complete."
+- **Spreadsheet:** Cell: `=IF(ISBLANK(A2), "missing source — flagged", LOOKUP(...))` with a visible flag column.
+- **Operational:** "Commit blocked: 2 tests failed. Files unchanged on disk. Branch position unchanged. Fix failing tests, unstage, or stop."
+
+**Action feedback** (principle: action acknowledged immediately, state change perceivable, no silent success):
+
+- **Writing:** Reply opens with "Received your X — answering Y below." Reader knows the question landed.
+- **Image:** Selection ring + filename pinned on hover; no ambiguity about which asset is active.
+- **App UI (desktop / web):** Submit button → spinner with label → success toast + the new row appearing in the list. Disabled until form valid; visibly enabled when ready.
+- **App UI (mobile / wearable):** Tap → light haptic on press, success haptic on completion + visible state change (button collapses to checkmark, toast fades in). Long-press, swipe-to-action, and pull-to-refresh each have their own haptic signature so the gesture is confirmed even when the visual change is small or briefly off-screen.
+- **Deck:** Click on agenda item dims others, advances to that section, breadcrumb updates in footer.
+- **Document:** Track Changes shows the inserted text + author + timestamp; the change is the receipt.
+- **Spreadsheet:** Recalc indicator while formulas resolve; updated cells flash briefly so the user sees what moved.
+- **Operational:** Command echoes input, prints stepwise progress, exits with status code + summary. No silent commands.
+
+The principle is identical across rows; the primitive is whatever the medium has natively.
+
+## 5. Strict Versus Flexible
+
+**Strict** (do not violate without a named exception):
+
+- Named audience, job, and output.
+- Governing thought or primary state is clear early.
+- User oriented in current state and next step.
+- Changing workflows show purpose, start, target, route, checkpoint, safe stop.
+- Transitions preserve continuity or mark the break.
+- Peer items are same-kind and ordered.
+- Claims, numbers, and data visuals have provenance.
+- Interactive controls and generated outputs are functional or labeled non-production.
+- Degraded states explain what happened and how to recover.
+- Accessibility and visual QA done before "complete."
+- Medium primitives are semantic, not visual fakes.
+
+**Flexible** (choose for the project):
+
+- Visual style, mood, density, surface treatment.
+- Structure shape: dashboard, narrative, wizard, ledger, canvas, memo, slide sequence.
+- The continuity primitive: phrase, heading, animation, drawer, sheet, caption, breadcrumb, drilldown.
+- The recovery primitive: inline message, note, fallback, retry, appendix, caveat, cached result.
+- The process primitive: status line, checklist, branch summary, progress marker, deploy URL, commit SHA, sync record.
+- Token palette, type family, illustration style, layout rhythm when no system exists.
+- Polish level, justified by audience, lifespan, and risk.
+
+## 6. Conflict Order
+
+When sources disagree, resolve in this order:
+
+1. Explicit user requirement for the current artifact.
+2. Current project or artifact contract.
+3. Router classification and archetype defaults.
+4. Domain skill or reference for the medium.
+5. These universal principles as the floor.
+
+A deliberate exception names the reason in the artifact's contract, not just the visual preference. The host orchestrator (e.g., `build-loop:ui-design`) may layer additional precedence rules above this floor; defer to the host when present.
+
+## 7. Operating Notes
+
+For an artifact:
+
+1. Capture audience, task, decision, purpose, current state, target end state, route, and risk.
+2. Apply §1 and §2.
+3. Load the medium-specific adapter (§3 row).
+4. Render and verify (§2 rule 10).
+5. Record deliberate exceptions in the contract with a stated reason.
+
+For a host runtime: classify the use case first (router), apply defaults, route to domain references only when needed, ask at high-impact choice points, flag any choice made without asking.
+
+## 8. Source Anchors
+
+Synthesized from these skills and references. Use them by name; the host runtime resolves paths.
+
+| Source (by name) | What it contributes |
+|---|---|
+| `calm-precision` skill | Cognitive predictability, grouping, hierarchy, disclosure, action weight, state/error rules, functional integrity |
+| `calm-precision-v1-1` (Router, Navigation, Motion/States/Identity) | Router pattern; task economy and step counting; purposeful motion and state-context matching |
+| `build-loop:ui-design` (SKILL + `ui-guidance-sources` reference) | Build Loop design route, source map, runtime priority order |
+| `interface-built-right` web router | Web archetypes, density defaults, validation-focus risk by surface |
+| `interface-built-right` iOS router | iOS archetype router and domain-reference split |
+| `interface-built-right` ui-ux-guidance (Codex plugin shape) | Compact guidance order, target roles, imagegen gates, interaction states, validation contract |
+| `UI Guidance` library (cross-platform, data-viz) | Cross-platform mode selection, content/chrome ratio, motion, status, responsive structure; decision-first data, chart-title discipline, direct labeling, source attribution |
+| `mockup-gallery` (COMMON + mockup-review) | Mockup state model, scratch-first lifecycle, selection/implementation tracking |
+| `deck-builder` and `calm-precision-pptx` | Storyline-first deck workflow, template inheritance, native PowerPoint primitives, action titles, one assertion per slide |
+| `storyline-builder` and `pyramid-principle-core` | Audience brief, governing thought, SCQA, MECE key line, vertical question/answer logic, horizontal deductive/inductive logic |
+| `pptx-design` and `docx` | Encoded deck design systems, density by purpose, visual QA; document presets, real styles/numbering/tables, render-and-inspect workflow |
+| `design-system` and `accessibility-review` | Tokens, components, patterns, versioning, migration discipline; WCAG 2.1 AA baseline (contrast, keyboard, focus, touch targets, name/role/value) |
+
+Absolute paths are resolved by the host runtime's skill index; this file does not hard-code per-machine locations.
+
+## 9. Cited Precedents (Live-Capture Addendum, 2026-05-26)
+
+Live IBR captures on the 4 primary apps surfaced texture observations that source-read could not. The principles above hold, with these qualifications:
+
+- **Tokens extend beyond visuals.** Sample Voice App's `HapticVocabulary.swift` defines 5 semantic haptic events (`.confirm/.reward/.warn/.progress/.selection`) that layer atop UIKit feedback generators the same way `Theme.fontDisplay` layers atop `Font.system(...)`. Treat haptics as first-class tokens when the platform supports them, not as call-site decisions.
+- **Selection signaling is platform- and density-specific, not universal.** Sample Voice App (filter pills, tab bar) uses solid-fill on selected; Sample Timer App (mode cards in modal sheet) uses 1pt border + glyph check. Both are legitimate; the choice is governed by surface density and decision weight, not a single rule. Avoid "selection = fill" claims absent context.
+- **Empty-state vocabulary diverges intentionally.** Sample Voice App floats a muted SF Symbol + two-line copy (`history-empty`); Sample Timer App renders a 3-stop milestone ladder with connecting line (`focus-journal-insights-empty`); Sample Product App uses a text-only loading label (`loading next question…`). Pick the vocabulary that matches the user's reason-for-emptiness — first-use vs unlock-progression vs transient-load — not a single house pattern.
+- **AI-assist as input-affordance is preferred when input is the primary action.** Sample Product App's sparkle "Enhance" CTA lives inside the textarea, not adjacent. Conserves vertical real estate and signals AI assistance via universal glyph. Pattern: when typing is the action, AI helpers live inside the field; when picking is the action, helpers can sit alongside.
+- **Brand-identity-in-chrome is universal, treatment is product-specific.** All 4 primaries differentiate their header brand: Sample Voice App plain text title, Sample Timer App custom wordmark asset, the sample reader plain text + theme toggle, Sample Product App 2-color wordmark + diamond glyph. No primary uses a generic system-font header alone. Treatment should match product voice; avoid system-default brand chrome unless the app is intentionally voice-neutral.
+- **Live capture is mandatory for these observations.** Source files cannot reveal selection-signaling divergence, empty-state-vocabulary divergence, or input-affordance placement — all are render-time decisions. See `evidence-capture-policy.md`.
+- **Two-speed motion on a single control is a deliberate language, not noise.** Sample Product App's primary CTA uses `transition: background 0.2s, transform 0.15s` — geometry settles 50ms faster than color. When a button shifts both color and shape on hover/press, the faster channel feels snappier (responsiveness) while the slower channel adds texture (settling). Avoid "one transition for everything"; tune per channel.
+- **Restraint extends to error states, not just primary surfaces.** Sample Product App's 404 has 5 elements total (icon + title + body + CTA + card). No illustration, no error code, no "did you mean", no search. Empty space IS the signal — "go back, this isn't the path." Pattern: **error/empty states inherit the same restraint as the main app; do not overcompensate with chrome.**
+- **Friction-removal microcopy has a stable shape.** Sample Product App's landing CTA and auth card both pair a primary action with a short / two-clause / bulleted / muted-color qualifier underneath (`No account required · Free to try` and `No account · Groq Llama 3.3`). When a CTA carries friction concern (cost, account, lock-in), follow with two short clauses separated by `·` in muted ≤12pt. Pattern travels — same recipe, two surfaces.
+- **Citation freshness matters.** Lines 171–172 cite Sample Product App's text-only loading label and sparkle "Enhance" inside-textarea pattern; both observed 2026-05-03. The 2026-05-26 capture confirms the landing has been redesigned to a headline-then-CTA model; the textarea-with-Enhance pattern moved one click deeper. The principles still hold; the live citations are as-of-2026-05-03.
+
+Evidence: `.build-loop/design-evidence/{sample-voice-ios, sample-timer, sample-reader, sample-product}.md` §"Live IBR Capture (2026-05-26)" — sample product section refreshed 2026-05-26 on port 3155.