# Form Coach — Design Rationale

**Product:** Barbell squat form coach (iPhone post-set review + Apple Watch sensor/remote)  
**Deliverable:** iOS 26–native HTML/CSS mockup site  
**Date:** 2026-07-09  
**Revision:** Post-REVIEW.md REVISE pass (P0 product surfaces + P1 HIG/a11y)

---

## 1. Design language chosen

**Name:** *Gym-native Liquid Glass* — dark-first performance UI with iOS 26 materials, not a marketing fitness gradient deck.

### Why this language

1. **iOS 26 is Liquid Glass.** Apple’s WWDC25 redesign unifies iOS, watchOS, and the rest of the platform stack around a translucent material that *reflects and refracts* surroundings, floats as a **functional layer above content**, and morphs with context. Our mockup treats chrome (tab bars, pills, sheets, watch status cards) as glass and keeps **content opaque and legible**.

2. **Gym context demands dark-first.** Phone sits on a tripod under gym lighting; Watch is glanceable mid-set under a bar. Dark surfaces reduce glare, match Fitness+/Activity ring conventions, and keep REC red and Ready green readable from distance. Light mode is supported as a second appearance, not the primary gym mode.

3. **Premium fitness apps win on restraint + metrics hierarchy**, not purple AI gradients. WHOOP’s score dashboards, Gentler Streak’s calm recovery UI, Oura’s readiness rings, and Fitness+ session summaries all share: oversized key numbers, muted secondary chrome, sparse color reserved for status, and honest confidence—not fake “100 perfect form” scores.

4. **Not AI-slop.** No Inter/Roboto/Space Grotesk, no evenly distributed pastel cards, no decorative mesh blobs. Typography is the **SF Pro / -apple-system** stack; radii nest concentrically with device bezels; motion is spring-short and purposeful.

---

## 2. Research summary (cited)

### 2.1 iOS 26 / Liquid Glass / HIG Materials

| Finding | Implication for Form Coach | Source |
| --- | --- | --- |
| Liquid Glass is a **new digital meta-material** that bends light, adapts light/dark, and reacts with specular highlights | Simulate with `backdrop-filter`, layered semi-white borders, soft specular gradients—not flat `#FFFFFF22` boxes | [Apple Newsroom, June 9 2025](https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/) |
| Glass is a **functional layer** for controls/navigation that floats above content; content scrolls underneath | Tab bar, nav chrome, checklist pills, sheets = glass. Camera preview, review media, charts = solid content | [HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials); [WWDC25 219 Meet Liquid Glass](https://developer.apple.com/videos/play/wwdc2025/219/); [Liquid Glass technology overview](https://developer.apple.com/documentation/technologyoverviews/liquid-glass) |
| **Don’t use Liquid Glass in the content layer** (except transient controls) | Session cards, rep lists, metric tables, Raw Session charts use standard elevated materials (`#1C1C1E`-class fills), not heavy blur | [HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials) |
| **Clear vs regular glass** for legibility over complex backgrounds | Camera overlays use darker “clear” frosted pills (`glass-clear` / dark 72% fill) so Ready chips stay readable over gym floor video | [HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials) |
| **Increase Contrast / Reduce Transparency** variants | Gallery “↑ Contrast” toggle drops blur and hardens glass fills (mock of system accessibility materials) | [HIG — Materials](https://developer.apple.com/design/human-interface-guidelines/materials); [HIG — Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) |
| Tab bars are **primary app sections** (typically 3–5), always-available destinations | History · New Set · Settings — **distinct** routes; only one tab active; Setup is New Set’s modal stack, not Settings | [HIG — Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars) |
| Tab bars **shrink on scroll**, expand when scrolling up; Liquid Glass treatment in iOS 26 | Mockup tab bar uses compact floating glass capsule; content gets focus | [Apple Newsroom](https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/) |
| Concentric radii: UI curvature aligns with hardware bezels | iPhone screen radius ~55px inner; sheets 28; cards ~16–18; nested chips full pill | [WWDC25 356 Get to know the new design system](https://developer.apple.com/videos/play/wwdc2025/356/) |
| Safe areas: content must clear Dynamic Island / home indicator | `--safe-top: 54px` / `--safe-bottom: 34px`; camera chrome re-applies top inset | [HIG — Layout](https://developer.apple.com/design/human-interface-guidelines/layout) |
| System colors refined for Liquid Glass; typography bolder, often left-aligned | Status greens/ambers use system-like hues; large titles left-aligned | [WWDC25 356](https://developer.apple.com/videos/play/wwdc2025/356/) |
| SF Pro is system type; Dynamic Type Body 17 / Large Title 34 at default | Font stack: `-apple-system…`; type scale in **rem**; gallery **Large Type** sets `html` to 20px (~125%) for review after set | [HIG — Accessibility (Dynamic Type)](https://developer.apple.com/design/human-interface-guidelines/accessibility) |
| Control sizes: **default 44×44 pt**, minimum 28×28 | Glass icon buttons, tabs, toggles (expanded hit), Watch START/STOP all ≥44 | [HIG — Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) |
| Sufficient contrast ~**4.5:1** for text (App Store accessibility criteria) | Secondary labels use ≥0.68 alpha; tertiary raised to ~0.48 for readable captions; decoration-only uses quaternary 0.28 | [App Store Connect — Sufficient Contrast](https://developer.apple.com/help/app-store-connect/manage-app-accessibility/sufficient-contrast-evaluation-criteria) |
| watchOS 26 shares Liquid Glass across the ecosystem | Watch status cards use the same glass language at higher contrast for glanceability | [Apple Newsroom](https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/) |

### 2.2 Fitness / health app craft

| Pattern | Borrowed | Source / exemplar |
| --- | --- | --- |
| **Score-first hierarchy** — one number or status, then supporting rows | Set summary headline faults; Watch rep count | WHOOP home — [WHOOP Locker](https://www.whoop.com/us/en/thelocker/the-all-new-whoop-home-screen/) |
| **Calm coaching voice** vs performative hustle | Copy: “Possible loss of neutral (estimated)” not “BAD FORM” | Gentler Streak — [App Store](https://apps.apple.com/us/app/gentler-streak-workout-tracker/id1576857102) |
| **Activity rings discipline** — don’t recolor system rings | Confidence/identity are **custom** status pills | [HIG — Activity rings](https://developer.apple.com/design/human-interface-guidelines/activity-rings) |
| **Post-workout summary as primary value** | Landing after analysis is Set Summary | [HIG — Workouts](https://developer.apple.com/design/human-interface-guidelines/workouts) |
| Dark performance dashboards with selective accent | Mint Ready/Locked; amber F1; red only for REC | WHOOP / Fitness+ session chrome |

### 2.3 Product truth (from refs)

Screens map to `ref-post-set-ux.md` and `ref-watch.md`, including recovery paths added in this revise:

- Home → Setup → Live framing gate → REC → Analyzing → **Summary** *or* **Raw Session**  
- Incomplete package → **Raw Session** (Analyze / Export / Discard) — not Analyzing-as-placeholder  
- Summary → Reps → Rep Detail → **Fault evidence sheet**  
- Settings is a **real** tab (units, defaults, delete data) — **not** Setup  
- Identity fail (Assist On): block Ready + **Continue without identity** override (`ref-watch.md` §3.5)  
- Watch REC: **“Logging IMU · fuse after set”** — sensor/remote, not live coach  

---

## 3. Design system

### 3.1 Color (dark primary / light secondary)

| Token | Dark | Light | Role |
| --- | --- | --- | --- |
| `--bg` | `#000000` | `#F2F2F7` | App canvas |
| `--bg-elevated` | `#1C1C1E` | `#FFFFFF` | Content cards (standard material) |
| `--bg-secondary` | `#2C2C2E` | `#E5E5EA` | Grouped list inset |
| `--label` | `#FFFFFF` | `#000000` | Primary text |
| `--label-secondary` | `rgba(235,235,245,0.68)` | `rgba(60,60,67,0.68)` | Secondary (**≥4.5:1** on dark) |
| `--label-tertiary` | `rgba(235,235,245,0.48)` | `rgba(60,60,67,0.50)` | Captions / footnotes still AA |
| `--label-quaternary` | `rgba(235,235,245,0.28)` | `rgba(60,60,67,0.30)` | Non-text decoration only |
| `--accent` | `#0A84FF` | `#007AFF` | Interactive |
| `--ready` | `#30D158` | `#34C759` | Ready / locked |
| `--caution` | `#FF9F0A` | `#FF9500` | F1 / suspected |
| `--fault` | `#FF453A` | `#FF3B30` | Destructive / REC |
| `--depth` | `#64D2FF` | `#5AC8FA` | Depth / info |

**Fault chips (dual-encoded: SF Symbol–style icon + text + color):**

| Code | Chip | Icon |
| --- | --- | --- |
| F1 suspected | Amber fill + label | Curve / spine proxy glyph |
| F1 N/A | Gray “Back N/A” | Slash in circle |
| F2 heel | Coral | Foot / heel up |
| F3 valgus | Coral | Knees-in |
| Depth | Cyan | Chevron down |
| Clean | Green | Checkmark |

### 3.2 Typography (Dynamic Type–friendly)

```
font-family: -apple-system, BlinkMacSystemFont, "SF Pro Display", "SF Pro Text",
             "Helvetica Neue", system-ui, sans-serif;
```

| Style | rem (default 16px root) | Use |
| --- | --- | --- |
| Large Title | `--text-large-title` 2.125rem | History, Settings |
| Title 1 | 1.75rem | Summary exercise |
| Title 2 | 1.375rem | Section / analyzing |
| Body / Headline | 1.0625rem | Lists, buttons |
| Subhead | 0.9375rem | Meta, secondary |
| Footnote | 0.8125rem | Badges, evidence table |
| Caption | 0.75–0.6875rem | Chips, timeline |

**Large Type demo:** `html[data-text-size="large"] { font-size: 20px }` scales rem-based UI (~125%) for post-set review (ref §13). Gallery control: **Large Type**.

### 3.3 Spacing & controls

| Token | Value | Notes |
| --- | --- | --- |
| Base unit | 4 pt | 4 / 8 / 12 / 16 / 20 / 24 / 32 |
| Screen margin | 16–20 pt | Content edge |
| Touch target | **≥44×44 pt** | Glass icons use 44 hit with 36 visual circle |
| Tab bar height | 56 + floating inset | Glass capsule |
| List row | 48–60 pt | Grouped inset |

### 3.4 Liquid Glass recipe (chrome only)

**Content material (standard):**

```css
background: var(--bg-elevated);
border: 0.5px solid var(--separator);
```

**Liquid Glass (tab bar, floating chrome):**

```css
backdrop-filter: blur(40px) saturate(180%);
border: 0.5px solid rgba(255,255,255,0.22);
box-shadow: inset 0 0.5px 0 rgba(255,255,255,0.35), /* specular */
            0 8px 32px rgba(0,0,0,0.35);
```

**Clear glass over camera:** darker 72% fill + blur for legibility (not stacked content glass panels).

### 3.5 Motion

| Moment | Spec |
| --- | --- |
| Screen enter | 320 ms ease-out, 10 px fade-up |
| REC pulse | 1.2 s opacity |
| Sheet present | Spring from bottom + scrim |
| Reduce motion | `prefers-reduced-motion` collapses animations |

### 3.6 Component kit

| Component | Notes |
| --- | --- |
| **Floating tab bar** | History · New Set · Settings — one active |
| **Settings** | Defaults, Watch, privacy/delete, about |
| **Raw Session** | Hip chart, filmstrip, Analyze / Export / Discard |
| **Evidence sheet** | Rule + metrics + joints + lumbar honesty |
| **Export sheet** | Share package / summary / delete (⋯) |
| **Identity override** | “Continue without identity” on Adjust when Assist On |
| **Fault chips** | Icon + text (not color alone) |
| **Confidence / Identity badges** | Always visible post-analysis |

---

## 4. Screen inventory (mapped to refs)

### iPhone (`ref-post-set-ux.md`)

| # | Screen | Ref § | Status |
| --- | --- | --- | --- |
| 1 | Onboarding / permissions | BRIEF + HealthKit | Present |
| 2 | Home / History | §1 | Present · incomplete → Raw |
| 3 | Setup configuration | §2 | Present · New Set flow |
| S | **Settings** | §1 Settings | **Present** (tab + gear) |
| 4 | Live Setup + Ready gate | §3 | Present · key checks labeled |
| 4b | Live Adjust + **identity override** | Watch §3.5 | Present |
| 5 | Recording (minimal) | §5 | Present · no fault overlays |
| 6 | Analyzing… | §6 | Present · fail → Raw |
| 6.1 | **Raw Session viewer** | §6.1, §11.3 | **Present** |
| 7 | Set Summary | §7 | Present · ⋯ export |
| 8 | Per-rep cards | §8 | Present · icon chips |
| 9 | Rep Detail | §9 | Present |
| 10 | **Fault evidence sheet** | §10 | **Present** |
| 11.2 | **Export sheet** | §11.2 | **Present** |

### Apple Watch (`ref-watch.md` + post-set §4)

| # | State | Content |
| --- | --- | --- |
| W1 | Adjust | Large status + one fail reason |
| W2 | Ready | Green Ready + START |
| W3 | Countdown | 3 → 2 → 1 |
| W4 | Recording | REC · rep · **Logging IMU · fuse after set** · STOP |
| W5 | Ended | Done — see iPhone |
| W6 | Future haptics | Pattern catalog (Phase 4) |

### Tab information architecture

| Tab | Destination | Notes |
| --- | --- | --- |
| History | `home` | Review stacks return here via Done |
| New Set | `setup` | Only this tab highlights for setup/live/record |
| Settings | `settings` | **Never** opens Setup |

Tab bar visible on History + Settings (primary roots). Camera / analyze / review use full-screen stacks with back chrome (native modal/stack pattern).

---

## 5. Accessibility & honesty

- **Contrast:** Secondary/tertiary tokens meet ~4.5:1 for readable text; quaternary for decoration only.  
- **Hit targets:** All interactive chrome ≥44×44 (glass icons, tabs, toggles, Watch START/STOP).  
- **Dynamic Type:** rem type scale + Large Type demo control for post-set review.  
- **Color not sole channel:** Fault chips carry SF Symbol–style icons + text + `aria-label`.  
- **Semantics:** Session/rep cards are real `button`s; toggles use `role="switch"` + `aria-checked`; sheets are `role="dialog"`.  
- **Reduced motion:** Honored globally.  
- **F1 honesty:** Catalog copy; evidence sheet lumbar disclaimer; no perfect-score theater.  
- **Watch honesty:** REC copy is logging/fusion only — not live coaching.

---

## 6. What we deliberately rejected

| Rejected | Why |
| --- | --- |
| Purple/violet AI brand gradients | Generative-UI cliché |
| Inter / Space Grotesk | Breaks native screenshot illusion |
| Live fault overlays during REC | Product forbids mid-set phone coaching |
| Settings tab → Setup | Broken IA (REVIEW P0) |
| Incomplete → Analyzing only | Misrepresents recovery (needs Raw Session) |
| “Tempo live · fused post-set” on Watch REC | Reads as live coaching |
| Marketing multi-hue gallery wash / CTA hero gradient | Softened toward opaque elevated + system blue tint |
| Glass on content cards | Violates HIG Materials content rule |

---

## 7. Implementation notes

- Static only: `index.html`, `css/styles.css`, `js/app.js` — open in browser, no build.  
- Device frames pure CSS (Dynamic Island + Watch crown).  
- Gallery controls: screen selects, theme, Large Type, Increase Contrast.  
- Keyboard: `1–9` screens, `0` Adjust, `R` Raw, `S` Settings, `E` Evidence, `L` theme.  

---

## 8. Source list

1. Apple Newsroom — Liquid Glass (June 9 2025): https://www.apple.com/newsroom/2025/06/apple-introduces-a-delightful-and-elegant-new-software-design/  
2. WWDC25 219 *Meet Liquid Glass*: https://developer.apple.com/videos/play/wwdc2025/219/  
3. WWDC25 356 *Get to know the new design system*: https://developer.apple.com/videos/play/wwdc2025/356/  
4. HIG — Materials: https://developer.apple.com/design/human-interface-guidelines/materials  
5. Liquid Glass technology overview: https://developer.apple.com/documentation/technologyoverviews/liquid-glass  
6. HIG — Tab bars: https://developer.apple.com/design/human-interface-guidelines/tab-bars  
7. HIG — Layout: https://developer.apple.com/design/human-interface-guidelines/layout  
8. HIG — Accessibility (Dynamic Type, 44×44): https://developer.apple.com/design/human-interface-guidelines/accessibility  
9. App Store Connect — Sufficient Contrast: https://developer.apple.com/help/app-store-connect/manage-app-accessibility/sufficient-contrast-evaluation-criteria  
10. HIG — Activity rings: https://developer.apple.com/design/human-interface-guidelines/activity-rings  
11. HIG — Workouts: https://developer.apple.com/design/human-interface-guidelines/workouts  
12. Product refs: `ref-post-set-ux.md`, `ref-watch.md`, `BRIEF.md`, `REVIEW.md`  

---

*End of rationale. Visual system in `css/styles.css`; screens in `index.html`; interactions in `js/app.js`.*
