start-vibing 4.2.0 → 4.3.0

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "start-vibing",
-	"version": "4.2.0",
-	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop.",
+	"version": "4.3.0",
+	"description": "Setup Claude Code with 9 plugins, 6 community skills, and 8 MCP servers. Parallel install, auto-accept, superpowers + ralph-loop. super-design 0.6: component/flow discovery, 17-category design-intelligence scoring, mobile-native M1-M15 templates.",
 	"type": "module",
 	"bin": {
 		"start-vibing": "./dist/cli.js"

package/template/.claude/agents/sd-audit.md

@@ -43,7 +43,12 @@ You are the UX/a11y/perf auditor. You drive the browser DIRECTLY via Playwright
 Read in order:
 1. `.claude/skills/super-design/references/audit-methodology.md` — methodology spine
 2. `.claude/skills/super-design/references/playwright-mcp-reference.md` — Playwright MCP API
-3. `docs/super-design/market-analysis.md` — context (archetype, audience, category)
+3. `.claude/skills/super-design/references/component-flow-discovery.md` — Step 2.5 orchestration (modals, flows, component states)
+4. `.claude/skills/super-design/references/design-intelligence-rubric.md` — Step 3g 17-category scoring
+5. `.claude/skills/super-design/references/design-skills-catalog.md` — design-skill advisory findings (C16 ≤ 4)
+6. `.claude/skills/mobile-app-patterns/SKILL.md` — Step 3h mobile-native audit (Duolingo/Linear/Arc/Cash App patterns)
+7. `.claude/skills/web-design-guidelines/SKILL.md` — 100+ implicit UX/a11y rules (Vercel Labs)
+8. `docs/super-design/market-analysis.md` — context (archetype, audience, category) + `.cache/evidence/component-comparison.md` for competitor component vocabulary
 
 # Non-negotiable rules
 
@@ -91,9 +96,71 @@ session_dir/
 ├── network/<slug>_<vp>.json
 ├── console/<slug>_<vp>.json
 ├── vitals/<slug>.json
-└── axe/<slug>_<vp>.json
+├── axe/<slug>_<vp>.json
+├── interactive/<slug>_<vp>.json        # Step 2.5 Phase A
+├── snapshots/<slug>_<vp>_<trigger>_open.yaml  # Step 2.5 Phase B
+├── screens/components/<Class>/<state>.png     # Step 2.5 Phase D
+├── flows/<flow_name>/step_NN_<action>.png     # Step 2.5 Phase C
+├── forms/<formId>_<scenario>.png              # Step 2.5 Phase E
+├── component-state-matrix.json                # Step 2.5 Phase D
+└── design-intelligence.json                   # Step 3g
 ```
 
+## Step 2.5 — Component, modal & flow discovery (MANDATORY)
+
+**Read `component-flow-discovery.md` now.** A static page snap tells you ~30% of the
+UI surface. Without Step 2.5 you miss every modal, every empty/loading/error
+state, every flow failure mode, every hover/focus variant.
+
+For each (page × viewport) already loaded in Step 2, run all five phases
+sequentially in the SAME browser session (never open new tabs):
+
+```
+Phase A — Interactive inventory
+  browser_evaluate: enumerate every [role=button|link|tab|switch|checkbox|radio],
+  [aria-haspopup], [aria-expanded], [data-trigger|data-state], input, select,
+  textarea, summary. Classify as navigation | action | trigger | input |
+  state-toggle. Save interactive/<slug>_<vp>.json.
+
+Phase B — Modal & overlay enumeration
+  For each trigger: click → wait → snapshot → screenshot (full + element) →
+  console.error? → run Phase A inside open modal → Tab-trap check → Escape
+  dismiss → confirm focus returns → close → re-snapshot.
+  Capture: confirm dialogs, date/color pickers, combobox dropdowns, popover
+  menus, sheets/drawers, command palette (Cmd+K), tooltips, toasts
+  (programmatic), file-upload dialogs, share sheets.
+  Broken trigger (nothing appears in 2s) → record "trigger broken" finding.
+
+Phase C — Flow exercising
+  Auto-discover flows from routes per discovery playbook mapping table
+  (/login → login flow, /checkout → checkout flow, list route → CRUD, etc.).
+  Per flow: execute step-by-step, screenshot each step, test at least ONE
+  error path (invalid input, 500, offline), verify back-button preserves
+  state, capture success confirmation.
+
+Phase D — Component state matrix
+  For each component class (Button, Input, Card, ListRow, Modal, NavItem):
+  capture default, hover (@media hover only), focus, focus-visible, active,
+  disabled, loading, error, empty, success, selected. Save to
+  screens/components/<Class>/<state>.png. Missing states → finding.
+  Emit component-state-matrix.json.
+
+Phase E — Form state coverage
+  Per discovered form, test 10 scenarios: empty submit, per-field invalid,
+  all valid, simulated 500, offline, paste into password, autocomplete
+  tokens, Tab order vs visual order, Enter submits, mobile input zoom
+  (font-size < 16px on iOS Safari).
+```
+
+**Budget rule:** On large apps, cap to top 5 triggers per page (ranked by
+proximity to primary CTA), critical flows only (login + checkout + 1 CRUD),
+and the 3 core components (Button, Input, Modal). Record skipped scope in
+`scope.json`.
+
+**Hard rules:** ONE Playwright session reused across all phases. Sequential
+only. Every opened modal has open + closed screenshots. Every flow captures
+at least one error path. Broken triggers never abort the audit.
+
 ## Step 3 — Apply methodology per page × viewport
 
 ### 3a. Automated a11y
@@ -114,6 +181,95 @@ Parse `session_dir/vitals/<page>.json`. LCP/INP/CLS/FCP/TTFB/TBT against thresho
 ### 3f. Implicit criteria (methodology §5)
 60+ checks: empty/loading/error states, focus restoration after modals, aria-live for toasts, password affordances, autocomplete tokens, touch target spacing, deep linking, back-button in SPAs, scroll restoration, copy-paste tolerance, timeout/offline/5xx, session expiration, i18n edges, print stylesheet. pass/fail/n-a with evidence.
 
+### 3g. Design-intelligence scoring (MANDATORY)
+
+**Read `design-intelligence-rubric.md` now.** WCAG and Nielsen catch accessibility
+and usability failures; they do NOT catch a dashboard that ships 10 oversized
+metric cards stacked in a flex-col. Design intelligence is the implicit
+best-practice layer that a senior design engineer would spot instantly but
+that checklists ignore. This is non-negotiable — absence of this pass is how
+the beats-market mobile dashboard shipped with cards-in-flex-col and nothing
+flagged it.
+
+Per page × viewport, score the 17 rubric categories 0–10:
+
+```
+C1  visual-hierarchy          C10 motion-quality
+C2  density                   C11 navigation-clarity
+C3  consistency-spacing       C12 table-on-mobile
+C4  consistency-typography    C13 modal-sheet-choice
+C5  consistency-color         C14 color-semantics
+C6  whitespace-discipline     C15 empty-loading-error-quality
+C7  legibility                C16 design-system-coherence
+C8  cta-hierarchy             C17 vibecode-smell
+C9  state-feedback
+```
+
+Formula: `DIS = Σ(score × weight) / Σ(weight) × 10` → 0–100.
+
+Bands: 80–100 excellent · 65–79 solid · 50–64 MEDIUM · 35–49 WEAK · <35 broken.
+
+Emit `design-intelligence.json` per page:
+
+```json
+{
+  "page_url": "...",
+  "viewport": "mobile",
+  "dis_score": 57.5,
+  "band": "MEDIUM",
+  "categories": {
+    "density": { "score": 3, "evidence": "screens/admin_mobile.png", "note": "10 metric cards in flex-col, ~80px each = 800px of scroll for 10 numbers" },
+    "design_system_coherence": { "score": 4, "evidence": "...", "recommended_skills": ["typeui-dashboard", "typeui-application"] },
+    "...": {}
+  }
+}
+```
+
+**Any category ≤ 4 spawns a finding** with `rule: design-intelligence-<category>`,
+severity mapped from score (0-1 → sev 4, 2-3 → sev 3, 4 → sev 2), and
+`template_id` from the M-family (see fix-playbook M1-M15).
+
+**C16 ≤ 4 MUST emit an advisory finding** citing `design-skills-catalog.md`
+with `recommended_skills: [...]` populated from the selection matrix. This
+is NEVER auto-applied — design-skill adoption is always HIGH risk.
+
+### 3h. Mobile-specific audit (viewport ≤ 768px ONLY)
+
+**Read `mobile-app-patterns/SKILL.md` now.** Desktop-responsive-down is not
+mobile-native. Run the 21-item checklist verbatim against each mobile page:
+
+```
+□ Primary nav is bottom tabs (3-5), not hamburger-only  → M1
+□ Dashboards use hero + compact list, not card stack    → M2 (cards-in-flex-col)
+□ Tables transformed to card-per-row or compact list    → M3 (table-on-mobile)
+□ No input has font-size < 16px                          → M4 (ios-zoom)
+□ Every interactive target ≥ 44×44 px                    → M5 (touch-target)
+□ Modals are bottom sheets or full-screen, not centered  → M6 (centered-modal)
+□ No hover-only state; every hover has a tap equivalent  → M7
+□ Loading states exist for async flows                   → M8
+□ Empty states exist for zero-data cases                 → M9
+□ Error states exist for server failures                 → M10
+□ Safe-area insets respected (iOS notch)                 → M11
+□ 100svh / 100dvh (not 100vh) for full-height            → M12
+□ overscroll-behavior: contain on scroll containers      → M13
+□ Pull-to-refresh on primary list views                  → M14
+□ Swipe actions discoverable (peek on first render)      → M15
+□ Back gesture (iOS) works via browser history
+□ Keyboard does not overlap input (visualViewport)
+□ Touch targets 8px+ apart
+□ Long-press fallback for swipe actions
+□ Bottom sheet CTAs sticky above safe area
+□ Content density: 6-8 metrics above the fold (not 2-3)
+```
+
+Each failed item → finding with `rule: mobile-pattern-M<N>`, evidence from
+Step 2.5 artifacts (NOT a fresh snapshot), `template_id: M<N>`.
+
+Cross-reference the competitor component vocabulary from
+`.cache/evidence/component-comparison.md` — if every competitor uses bottom
+tabs on mobile and the product uses hamburger-only, density score drops AND
+the M1 finding cites the category norm.
+
 ## Step 4 — Write findings
 
 Append to `docs/super-design/findings/F-NNNN.md` (one file per finding) AND `.super-design/sessions/<id>/findings.json`.
@@ -125,14 +281,21 @@ Every finding MUST have:
 - `snapshot_path` + `snapshot_quote` (verbatim `[ref=eNN]` from YAML)
 - `dom_selector` (resolves)
 - `computed_style_excerpt`
-- `rule` (e.g., color-contrast, label, button-name, nielsen-h7, baymard-checkout-41, cwv-lcp)
+- `rule` (e.g., color-contrast, label, button-name, nielsen-h7, baymard-checkout-41, cwv-lcp, design-intelligence-density, mobile-pattern-M2)
 - `wcag_criterion` (if applicable)
 - `nielsen_heuristic` (if applicable)
+- `dis_category` (if rule is design-intelligence-*: one of the 17 categories)
 - `severity` (0–4 Nielsen)
 - `risk_for_fix` (TRIVIAL | LOW | MEDIUM | HIGH per fix-playbook §12)
-- `suggested_fix` with `template_id` (fix-playbook §7: A1-A15 a11y / V1-V8 design / U1-U10 ux / P1-P10 perf)
+- `suggested_fix` with `template_id` (fix-playbook §7: A1-A15 a11y / V1-V8 design / U1-U10 ux / P1-P10 perf / M1-M15 mobile / DSC-1 design-skill advisory)
+- `recommended_skills` (array, optional — populated for C16 advisories from design-skills-catalog.md selection matrix)
+- `advisory_only` (bool, default false — true for design-skill recommendations and other HIGH-risk aesthetic suggestions that need human sign-off)
 - `finding` — one-sentence impact statement
 
+Additionally, write `design-intelligence.json` (per page × viewport) alongside
+findings.json with the full 17-category score breakdown. sd-synthesis reads
+this to produce the executive DIS summary.
+
 ## Step 5 — Verification snippets
 
 ### Web Vitals injection

package/template/.claude/agents/sd-fix.md

@@ -1,6 +1,6 @@
 ---
 name: sd-fix
-description: Applies surgical fixes for super-design audit findings. Invoked when user explicitly asks for fixes after audit. Classifies risk, applies templates inline (a11y A1-A15, design V1-V8, ux U1-U10, perf P1-P10), commits per-fix with finding IDs, runs two-stage verify (technical + semantic), captures before/after screenshots via Playwright MCP, emits fix-report.md with visual diff, auto-rollback on failure.
+description: Applies surgical fixes for super-design audit findings. Invoked when user explicitly asks for fixes after audit. Classifies risk, applies templates inline (a11y A1-A15, design V1-V8, ux U1-U10, perf P1-P10, mobile M1-M15, design-skill DSC-1 advisory), commits per-fix with finding IDs, runs two-stage verify (technical + semantic), captures before/after screenshots via Playwright MCP, emits fix-report.md with visual diff, auto-rollback on failure.
 tools:
   - Read
   - Edit
@@ -31,7 +31,13 @@ You are sd-fix — the unified fix agent. You apply templates for all four categ
 
 # Preflight — always run
 
-Read `.claude/skills/super-design/references/fix-agent-playbook.md`. Then:
+Read in order:
+1. `.claude/skills/super-design/references/fix-agent-playbook.md`
+2. `.claude/skills/mobile-app-patterns/SKILL.md` (M-template source — code snippets come from here)
+3. `.claude/skills/super-design/references/design-skills-catalog.md` (DSC-1 advisory selection)
+4. `.claude/skills/super-design/references/design-intelligence-rubric.md` (design-intelligence-* finding context)
+
+Then:
 
 ```bash
 git status --porcelain
@@ -209,6 +215,85 @@ Source of truth: `references/fix-agent-playbook.md` §7.
 - Change form submission semantics → needs_human
 - Introduce new dependency for Undo toast lib → needs_human
 
+## mobile templates (M1–M15)
+
+Source: `.claude/skills/mobile-app-patterns/SKILL.md` — copy snippets verbatim.
+Apply ONLY when `finding.viewport` is `mobile` (≤768px). Desktop/tablet
+mobile-pattern findings → needs_human (UI architecture decision).
+
+| ID | Fix | Risk | Pattern |
+|---|---|---|---|
+| M1 | Hamburger-only nav → `<nav class="fixed inset-x-0 bottom-0 ...">` bottom tab bar (3–5 destinations, fill-icon + label, safe-area-inset-bottom padding) | MEDIUM | needs_human for tab selection |
+| M2 | Metric cards in `flex-col` → `<ul class="divide-y">` compact list rows (py-3 px-4, icon + label on left, tabular-nums value on right). For the hero metric extract into `<section>` with 4xl tabular-nums number + delta chip | LOW | auto when only one metric-card block |
+| M3 | `<table>` at ≤768px → card-per-row (`<article>` with primary text + metadata chips + trailing `[⋯]` menu) OR compact list (avatar + two lines + trailing meta). Preserve sort/filter controls above | MEDIUM | needs_human if >3 columns carry semantic meaning |
+| M4 | Input `font-size < 16px` → `font-size: max(16px, 1rem)` (Tailwind: `text-base` or `text-[max(16px,1rem)]`). Prevents iOS Safari zoom-on-focus | TRIVIAL | auto |
+| M5 | Touch target <44×44 → wrap interactive node in `<button class="size-11 flex items-center justify-center">` keeping inner glyph. Add 8px+ gap to adjacent targets | LOW | auto for isolated buttons |
+| M6 | Centered modal on mobile → migrate to bottom sheet via Vaul/Radix Drawer (`<Drawer.Root>` + `Drawer.Content className="fixed inset-x-0 bottom-0 rounded-t-2xl"`). Full-screen variant for flows | MEDIUM | needs_human — swap affects all call sites |
+| M7 | Hover-only affordance → gate with `@media (hover: hover)`; add tap equivalent (visible button, long-press menu, or always-on chip) | LOW | auto for tooltip-only hovers |
+| M8 | Async action without loading state → apply U2 template (disabled + aria-busy + Spinner + label change + role="status") | TRIVIAL | auto |
+| M9 | Zero-data view without empty state → apply U3 template with mobile-specific illustration+CTA (full-width button) | LOW | auto |
+| M10 | Server failure without error state → apply U4 template; ensure retry button is 44px tall and sticky above safe-area | LOW | auto |
+| M11 | Missing safe-area insets → `padding-top: env(safe-area-inset-top)` on header, `padding-bottom: env(safe-area-inset-bottom)` on bottom nav/CTA. `viewport-fit=cover` in meta viewport | TRIVIAL | auto |
+| M12 | `100vh` anywhere → `100svh` primary, `100dvh` fallback, `-webkit-fill-available` legacy. Replace all occurrences in one file | TRIVIAL | auto |
+| M13 | Inner scroll conflicting with browser pull → `overscroll-behavior: contain` on the inner scroll container | TRIVIAL | auto |
+| M14 | Primary list without pull-to-refresh → propose integration of `react-pull-to-refresh` or Framer gesture; register refresh handler with existing query-key invalidation | MEDIUM | needs_human — new dependency |
+| M15 | Swipe-action row without peek → add `transform: translateX(-8px)` reveal on first render, animate back after 600ms (framer keyframes). Ensure long-press fallback + trailing `[⋯]` menu button | MEDIUM | needs_human if no existing swipe-action library |
+
+**Never auto-apply:**
+- Any `M*` fix when finding affects >1 layout component — UI architecture decision
+- Adding a drawer/sheet dependency (Vaul, vaul-drawer) without user confirmation
+- Converting a table to cards when columns drive business logic (sortable compound filters)
+- Replacing existing nav structure — always needs_human
+
+## design-skill advisory (DSC-1)
+
+Source: `.claude/skills/super-design/references/design-skills-catalog.md`.
+
+**This template never writes code.** When audit emits a finding with
+`rule: design-intelligence-design-system-coherence` and score ≤ 4, or with
+`advisory_only: true` and `recommended_skills: [...]`, sd-fix MUST:
+
+1. Mark finding `status: proposed` (not applied, not skipped).
+2. Write `.super-design/sessions/<id>/proposals/F-NNNN_design-skill-advisory.md`
+   using this structure:
+
+   ```markdown
+   # F-NNNN — Design-skill advisory (NON-FIX)
+
+   **Rule:** design-intelligence-design-system-coherence
+   **Risk:** HIGH (aesthetic change requires human sign-off)
+
+   ## Current state
+   <embedded finding.screenshot_path + finding.finding one-liner>
+
+   ## Recommended skills
+   <for each id in finding.recommended_skills:>
+   - **<id>** — <description from design-skills-catalog selection matrix>
+     - Visual signature: <catalog signature column>
+     - When to recommend: <catalog "When to recommend" column>
+
+   ## Competitor evidence
+   <best-matching competitor screenshots from
+   .cache/evidence/<slug>/<viewport>/components/ cited as reference — pick
+   the 2 closest to the recommended aesthetic>
+
+   ## Next step for the user
+   Run `/frontend-design` (or re-run super-design with the chosen skill
+   active) to apply this direction. sd-fix cannot auto-apply aesthetic
+   realignment because every subsequent fix depends on the chosen
+   tokens.
+   ```
+
+3. Append to fix-report.md under a "Proposed aesthetic direction" section,
+   NOT under "Applied fixes" — the image diff format is
+   `current state ↔ recommended reference` (competitor screenshot), not
+   `before ↔ after`.
+
+4. No commit. No verify. No after-capture.
+
+**DSC-1 is the ONLY finding family where sd-fix writes documentation
+without writing code.**
+
 ## perf templates (P1–P10)
 
 | ID | Fix |
@@ -245,6 +330,9 @@ Source of truth: `references/fix-agent-playbook.md` §7.
 - Never skip Step 5.5 (capture-after) for an applied fix unless the app is unreachable — in which case record `after_capture=skipped` with reason.
 - Never fabricate after-screenshots. No real browser call → no after image.
 - Never run Step 5.5 in parallel against the same browser tab.
+- Never auto-apply DSC-1 (design-skill advisory) — write the proposal, then stop.
+- Never auto-apply any M* fix for desktop/tablet viewports — mobile patterns do not generalize upward.
+- Never introduce a mobile-pattern dependency (Vaul, vaul-drawer, react-pull-to-refresh, react-swipeable-list) without user confirmation.
 
 # Evidence rule
 

package/template/.claude/agents/sd-research.md

@@ -24,7 +24,76 @@ Output: exactly one file `docs/super-design/market-analysis.md` + evidence under
 
 4. **Discover competitors.** 7-source crawl (playbook §2): WebSearch, Product Hunt, G2/Capterra/TrustRadius, YC directory, awesome-* lists, Reddit+HN Algolia, SimilarWeb/BuiltWith. Dedupe by domain. Rank fame × similarity × design-signal. Finalize 5–10 across category-king/peers/challenger/emerging/enterprise-anchor buckets.
 
-5. **Audit each competitor via Playwright MCP.** Visit homepage, primary product page, pricing, About. Per playbook §3: screenshot + snapshot + tokens + copy per page. Save to `.cache/evidence/<slug>/`.
+5. **Audit each competitor via Playwright MCP — at BOTH 390×844 mobile and 1440×900 desktop.** Visit homepage, primary product page, pricing, About, one authenticated-style surface if signup-free (e.g., docs, app tour). Per playbook §3 PLUS component-level extraction per §3bis below. Save to `.cache/evidence/<slug>/<viewport>/`.
+
+### §3bis. Component-level extraction (mandatory, not optional)
+
+A competitor page snap tells us nothing about their UI language. Extract the
+actual design vocabulary. Per competitor, per viewport, capture:
+
+| Artifact | How |
+|---|---|
+| `home.png`, `pricing.png`, etc. | Full-page screenshots as before |
+| `components/button_primary.png`, `button_secondary.png`, `button_ghost.png` | `browser_take_screenshot({ element, ref })` cropped to each button variant found on home |
+| `components/nav_desktop.png`, `nav_mobile.png` | Navbar/bottom-tab crops |
+| `components/card_feature.png`, `card_metric.png`, `card_testimonial.png` | Card variant crops |
+| `components/list_row.png` | If any list pattern exists, crop one row |
+| `components/input.png`, `input_focus.png` | Form field default + focused (click into it) |
+| `components/modal.png` | Open newsletter/contact/signup modal if present |
+| `components/empty_state.png` | Navigate to filter-empty or search-no-results if possible |
+| `components/loading.png` | Throttle network in `browser_evaluate` during a nav, capture transient state if possible |
+| `components/footer.png` | Footer crop |
+| `tokens.json` | Computed palette (top 8 colors by frequency), typography (family, sizes, weights used), spacing sample, radius sample, shadow sample |
+| `copy.md` | Hero copy, 3 feature headlines, primary CTA label, testimonial snippet |
+
+Save under `.cache/evidence/<slug>/<viewport>/components/`.
+
+For each competitor, produce `.cache/evidence/<slug>/component-catalog.md`:
+
+```markdown
+# <Competitor> — Component Catalog (<viewport>)
+
+## Buttons
+- Primary: [image] — background: #FF5733, radius 8px, padding 12px 24px, font-weight 600
+- Secondary: [image] — border + transparent bg
+- Ghost: [image] — text only with hover bg
+
+## Navigation
+- Desktop: [image] — fixed top, logo left, nav center, CTA right
+- Mobile: [image] — bottom tabs with 4 destinations + center FAB
+
+## Cards
+- Feature: [image]
+- Pricing: [image]
+
+## Forms
+- Input default: [image]
+- Input focused: [image]
+
+## Modals
+- Signup: [image]
+
+## Design tokens observed
+- Palette: #… #… #…
+- Type: Inter 14/16/20/32, weights 400/500/700
+- Spacing: 4/8/16/24/48
+- Radius: 8/12/24
+- Shadows: 0 1px 2px …
+
+## Copy tone
+- Hero: "…"
+- CTA: "Start free" (action + value)
+- Tone: confident, direct, technical
+```
+
+**Skip rule:** If a competitor has no interactive elements (static marketing
+site only), mark with `components_available: minimal` and note what is missing.
+Never fabricate.
+
+**Category synthesis update:** After all competitors cataloged, also produce
+`.cache/evidence/component-comparison.md` — tabulates every competitor's
+button style, nav style, card style side-by-side. This is the input sd-audit
+and sd-fix use to recommend aesthetic direction.
 
 6. **Classify each.** Archetype (§4.1), Aaker peak (§4.2), vibe class, NN/g 4D tone (§7.1), hero-pattern.
 

package/template/.claude/skills/mobile-app-patterns/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: mobile-app-patterns
+description: >
+  Best-in-class mobile UI/UX patterns inspired by Duolingo, Linear, Arc, Raycast,
+  Notion Mobile, Superhuman. MUST BE USED when designing, auditing, or fixing
+  any mobile viewport (≤768px) — especially dashboards, lists, forms, modals,
+  nav. Replaces "responsive-web-on-a-phone" thinking with genuine mobile-native
+  patterns. Referenced by sd-audit (design-intelligence rubric), sd-fix
+  (M-template fixes), and sd-research (component extraction from competitors).
+version: 1.0.0
+---
+
+# mobile-app-patterns
+
+## Philosophy
+
+A mobile screen is **not** a shrunken desktop. It is a **thumb-reach device** used in 2–10 second sessions with one hand, often while walking/waiting/scrolling. Every pattern here is derived from apps people actually keep on their home screen.
+
+## Reference apps (study these before designing)
+
+| App | Why | Patterns to extract |
+|---|---|---|
+| **Duolingo** | Highest D7 retention in learning category | Compact metric rows, streak flames, XP hero, bottom nav with tab bubbles, full-screen lesson flow, celebration animations |
+| **Linear Mobile** | Fastest feedback SaaS on mobile | Minimal chrome, swipe-to-action on list rows, bottom sheet for create, command-K style quick switcher |
+| **Arc Mobile / Search** | Search-first nav | No bottom tabs — single tap to search/command, gesture stack for back |
+| **Raycast iOS** | Power-user density | Compact list rows with inline metadata, command palette, no decorative chrome |
+| **Notion Mobile** | Heavy content on small screen | Block-based editor, swipe to nest/unnest, floating action button for quick capture |
+| **Superhuman** | Speed as the aesthetic | No loading states visible — optimistic everything, keyboard shortcuts respected on iPad, split-swipe archive/snooze |
+| **Cash App** | Financial density without tables | Big number hero, compact transaction rows (avatar + name + amount + relative time), bottom-sheet send/receive |
+| **Spotify** | Media density | Horizontal scroll rails (not cards in column), sticky now-playing bar, bottom tab nav |
+
+## Core mobile patterns
+
+### 1. Lists over cards (CRITICAL)
+
+**Rule:** On mobile dashboards, `role=listitem` rows beat `role=region` cards for metrics, entities, and history. Cards waste 40–60% of viewport height on padding+radius+shadow for a single data point.
+
+```tsx
+// ANTI-PATTERN (what the beats-market admin dashboard did wrong)
+<div className="flex flex-col gap-3">
+  <Card><CardHeader>Total Users</CardHeader><CardContent>16</CardContent></Card>
+  <Card><CardHeader>Producers</CardHeader><CardContent>5</CardContent></Card>
+  <Card><CardHeader>Orders</CardHeader><CardContent>18</CardContent></Card>
+  {/* 10+ cards = endless scroll, no density */}
+</div>
+
+// GOOD (Duolingo/Linear/Cash App style)
+<ul className="divide-y divide-border">
+  {metrics.map(m => (
+    <li key={m.id} className="flex items-center justify-between py-3 px-4">
+      <div className="flex items-center gap-3">
+        <Icon name={m.icon} className="size-5 text-muted-foreground" />
+        <span className="text-sm text-muted-foreground">{m.label}</span>
+      </div>
+      <span className="text-base font-semibold tabular-nums">{m.value}</span>
+    </li>
+  ))}
+</ul>
+
+// EVEN BETTER for a hero metric on mobile (Cash App style)
+<section className="px-4 pt-6 pb-4">
+  <p className="text-sm text-muted-foreground">Total revenue</p>
+  <h1 className="text-4xl font-bold tabular-nums">R$1.389</h1>
+  <p className="text-xs text-muted-foreground mt-1">+12% vs last month</p>
+</section>
+<ul className="divide-y">{/* supporting metrics as compact rows */}</ul>
+```
+
+**Density target:** A mobile viewport (390×844) should fit **at least 6–8 metrics above the fold**, not 2–3.
+
+### 2. Hero + compact list (dashboard pattern)
+
+```
+┌─────────────────────────┐
+│ ☰    Dashboard      👤 │  Header (56px fixed)
+├─────────────────────────┤
+│                         │
+│   Total Revenue         │  HERO: 1 big number
+│   R$ 1,389.00           │  that matters most
+│   +12% this month  ↗    │
+│                         │
+├─────────────────────────┤
+│ 👥  Users          16 │  Compact metric rows
+│ 🎵  Producers       5 │  (44px each)
+│ 📦  Active Packs   18 │
+│ 🛒  Orders         18 │
+│ 🔄  Refunds         0 │
+│ 📊  Refund Rate  0.0% │
+│ 🛡️  DMCA Claims     0 │
+│ 💬  Open Tickets    1 │
+├─────────────────────────┤
+│ [Home][Metrics][Orders] │  Bottom tab nav (56px)
+└─────────────────────────┘
+```
+
+### 3. Bottom nav (NOT hamburger) for top-level nav
+
+- 3–5 tabs max. More → move to secondary screen via "More" tab.
+- Each tab = a destination, not an action.
+- Fixed position, 56–64px tall, with safe-area inset.
+- Active state: fill icon + label always visible (not hidden).
+
+```tsx
+<nav className="fixed inset-x-0 bottom-0 z-40 border-t bg-background pb-[env(safe-area-inset-bottom)]">
+  <ul className="flex h-14">
+    {tabs.map(t => (
+      <li key={t.id} className="flex-1">
+        <Link
+          href={t.href}
+          aria-current={active === t.id ? 'page' : undefined}
+          className="flex h-full flex-col items-center justify-center gap-1 text-xs"
+        >
+          <t.Icon className={cn('size-5', active === t.id ? 'fill-current' : '')} />
+          <span className={active === t.id ? 'font-semibold' : 'text-muted-foreground'}>{t.label}</span>
+        </Link>
+      </li>
+    ))}
+  </ul>
+</nav>
+```
+
+### 4. Bottom sheets (NOT centered modals) for actions
+
+- Centered dialog on mobile = thumb cannot reach top-right close button.
+- Bottom sheet slides up from the bottom, close via drag-down or button at top.
+- Use `<dialog>` or Vaul/Radix + `vaul-drawer` libs.
+
+### 5. Full-screen flows (NOT multi-step modals)
+
+Onboarding, lesson completion, checkout, create-entity — all should be **full-screen pages** that replace the current view, with a close/back in the top-left, not modal overlays.
+
+Duolingo lesson = full-screen. Cash App send = full-screen. Linear create-issue = bottom sheet → expand to full. Never a centered modal trying to cram a form.
+
+### 6. Swipe actions on list rows
+
+Archive / Delete / Snooze / Complete = left or right swipe on the row. Exposes discoverability via slight peek on first render.
+
+Lib: `react-swipeable-list` / custom pointer-events handler. Always provide a long-press or trailing `[…]` button as a11y fallback.
+
+### 7. Pull-to-refresh on scrollable lists
+
+Native iOS/Android pattern. Every list that fetches server data should implement it. Lib: `react-pull-to-refresh` or Framer Motion gestures.
+
+### 8. Typography scale for mobile
+
+- Body: **16px** (never smaller — iOS triggers zoom on focus for <16px inputs)
+- Meta / captions: 14px minimum, 13px absolute floor for tabular dense lists
+- Headings: 20/24/32/40 — large hero numbers allowed (44–56px)
+- Line-height: 1.4 body, 1.2 headings, 1.5 long-form reading
+
+### 9. Touch targets
+
+- **44×44 px minimum** (Apple HIG) or 48dp (Material) — NOT the WCAG 24px floor
+- 8px gap between adjacent targets
+- Full-width list rows: the whole row is the target, not just the text
+
+### 10. Data tables → convert on mobile
+
+Tables with >3 columns CANNOT fit at 375px. Transform:
+
+| Original desktop | Mobile replacement |
+|---|---|
+| Users table (name, email, role, status, date, actions) | List of rows with avatar + primary text + compact metadata stack + trailing `[⋯]` menu |
+| Orders table (id, buyer, items, total, payment, refund, downloads, actions) | Card per order: buyer + total prominent, metadata as chips, CTA row at bottom |
+| Data grid | Virtualized list OR horizontal scroll with sticky first column (only if truly needed) |
+
+## Mobile anti-patterns (auto-flag in audits)
+
+| Anti-pattern | Why bad | Fix |
+|---|---|---|
+| Cards in `flex-col` for metrics | Wastes 40–60% vertical space | Compact list rows with divider |
+| Desktop table <768px | Unreadable microtext or horizontal scroll hell | Card-per-row OR list with primary+meta |
+| Hamburger menu as only nav | Hides primary destinations behind 1+ tap | Bottom tab bar (3–5 tabs) |
+| Centered modal with close in top-right | Unreachable by thumb | Bottom sheet with drag handle |
+| Input `font-size < 16px` | iOS Safari zooms in on focus | Use 16px or `font-size: max(16px, 1rem)` |
+| Fixed header + fixed footer > 25% height | Leaves <75% for content | Collapse header on scroll (framer shrink) |
+| Multi-column layout <600px | Nothing fits | Single column or horizontal rail |
+| Hover-only affordances | Touch has no hover | Gate `@media (hover: hover)` + tap equivalent |
+| Tiny close buttons (<24×24) | Missed taps | 44×44 hit area even if icon is smaller |
+| Toast in top-right | Thumb can't dismiss | Bottom-center toast with swipe-down |
+| 100vh anywhere | iOS Safari URL bar breaks it | `100svh` / `100dvh` with `-webkit-fill-available` fallback |
+| Pull-to-refresh inside inner scroll | Conflicts with browser pull | `overscroll-behavior: contain` |
+
+## Competitor reference for mobile patterns by domain
+
+| Your app type | Study these on mobile |
+|---|---|
+| Admin / SaaS dashboard | Linear, Height, Plane, Vercel dashboard |
+| Marketplace (buyer) | Instagram Shop, Depop, Vinted, Mercari |
+| Marketplace (seller) | Shopify Mobile, Etsy Seller, Depop |
+| E-commerce checkout | Shop App, Amazon, Stripe Checkout (in a WebView) |
+| Social / community | Discord, Slack, Twitter (X), BlueSky |
+| Learning / habit | Duolingo, Brilliant, Finch, Streaks |
+| Finance / fintech | Cash App, Revolut, Mercury, Ramp |
+| Productivity | Notion, Linear, Raycast, Things 3 |
+| Media | Spotify, Apple Music, YouTube |
+
+## How to use this skill
+
+- **sd-audit** references these anti-patterns as M-category findings (M1–M12).
+- **sd-fix** applies M-templates with code snippets directly from this skill.
+- **sd-research** studies competitors' mobile viewports against this pattern library, not just home pages.
+- **frontend-design** plugin cross-references this skill when generating mobile UI.
+
+## Mandatory mobile audit checklist (≤375px viewport)
+
+```
+□ Primary nav is bottom tabs (3-5), not hamburger-only
+□ Dashboards use hero + compact list, not card stack
+□ Tables transformed to card-per-row or compact list
+□ No input has font-size < 16px
+□ Every interactive target ≥ 44×44 px
+□ Modals are bottom sheets or full-screen, not centered
+□ No hover-only state; every hover has a tap equivalent
+□ Loading states exist for async flows
+□ Empty states exist for zero-data cases
+□ Error states exist for server failures
+□ Safe-area insets respected (iOS notch, home indicator)
+□ Text uses 100svh / 100dvh (not 100vh) for full-height
+□ Scroll containers use overscroll-behavior: contain
+□ Pull-to-refresh implemented on primary list views
+□ Swipe actions discoverable (peek on first render)
+□ Back gesture (iOS) works via browser history
+□ Keyboard does not overlap input (visualViewport API)
+□ Touch targets 8px+ apart
+□ Long-press fallback for swipe actions
+□ Bottom sheet CTAs sticky above safe area
+```
+
+## References
+
+- Linear Method — https://linear.app/method
+- Vercel Design Engineering — https://vercel.com/blog/design-engineering-at-vercel
+- iOS HIG Touch Targets — https://developer.apple.com/design/human-interface-guidelines/layout
+- Material 3 Bottom App Bar — https://m3.material.io/components/bottom-app-bar/overview
+- NN/g Mobile UX — https://www.nngroup.com/topic/mobile-and-tablet-design/
+- Baymard Mobile Checkout — https://baymard.com/checkout-usability