start-vibing 4.2.0 → 4.3.1

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

package/template/.claude/skills/super-design/.schema-version

@@ -0,0 +1 @@
+1.0.0

package/template/.claude/skills/super-design/SKILL.md

@@ -8,7 +8,7 @@ description: >
   UX audit (WCAG 2.2 AA, Nielsen heuristics, Baymard, CWV), and synthesized
   overview. Re-audits only what changed since last run. On explicit user request,
   applies surgical fixes with full rollback.
-version: 0.5.0
+version: 0.6.1
 ---
 
 # super-design
@@ -18,16 +18,34 @@ version: 0.5.0
 Four-phase pipeline with 6 specialist agents:
 
 1. **Market research** (sd-research) — auto-detects niche from repo, finds 5–10
-   competitors, extracts design language, produces market-analysis.md.
-2. **UI/UX audit** (sd-audit) — drives browser via Playwright MCP directly,
-   applies Nielsen's 10 heuristics, WCAG 2.2 AA, Baymard (if e-commerce), and
-   Core Web Vitals. Produces findings.json with SHOT+QUOTE+SEL+VAL evidence.
-3. **Synthesis** (sd-synthesis) — unifies research + audit into overview.md.
+   competitors, extracts design language AND component vocabulary (buttons,
+   nav, cards, modals, forms, tokens — per competitor × mobile+desktop),
+   produces market-analysis.md + component-comparison.md.
+2. **UI/UX audit** (sd-audit) — drives browser via Playwright MCP directly.
+   Five layers:
+   - Route discovery + static snap (Nielsen + WCAG 2.2 AA + Baymard + CWV)
+   - **Step 2.5 component/modal/flow discovery** (Phase A inventory, B modal
+     enumeration, C flow exercising, D state matrix, E form coverage) — this
+     is where modal contents, empty/loading/error states, and flow errors
+     get real evidence instead of "checklist hypothetical".
+   - **Step 3g design-intelligence scoring** (17-category rubric → DIS 0–100)
+     catches implicit best practices checklists miss (cards-in-flex-col,
+     low density, weak CTA hierarchy, vibecode smell).
+   - **Step 3h mobile-native audit** (21-item Duolingo/Linear/Arc/Cash-App
+     checklist) — replaces "responsive-web-on-a-phone" thinking.
+   - C16 ≤ 4 → design-skill advisory finding citing typeui-* selection matrix.
+   Produces findings.json + design-intelligence.json with SHOT+QUOTE+SEL+VAL.
+3. **Synthesis** (sd-synthesis) — unifies research + audit + design-intelligence
+   into overview.md (per-page DIS table + executive summary).
 4. **Fix** (sd-fix + two-stage verify) — optional. Applies safe fixes with
    technical gates (types/lint/tests) AND semantic verification ("does this
-   fix actually resolve the finding, or just mask it?"). After each successful
-   fix, re-drives Playwright to capture an after-screenshot (full page +
-   element crop) and emits `docs/super-design/sessions/<id>/fix-report.md`:
+   fix actually resolve the finding, or just mask it?"). Template families:
+   A1-A15 a11y · V1-V8 design · U1-U10 ux · P1-P10 perf · **M1-M15 mobile**
+   (cards-in-flex-col → compact list, table-on-mobile → card-per-row,
+   centered-modal → bottom-sheet, etc.) · **DSC-1 design-skill advisory**
+   (proposes typeui-* direction, never auto-applies — HIGH risk). After each
+   successful fix, re-drives Playwright to capture an after-screenshot (full
+   page + element crop) and emits `docs/super-design/sessions/<id>/fix-report.md`:
    a self-contained visual diff with before/after images, file diffs,
    verification status, and commit SHA per finding.
 
@@ -68,9 +86,14 @@ Pass findings via files under `.super-design/sessions/<id>/`, not chat.
 
 ### Step 4: Write state + history
 
-- Atomic write `.audit-state.json` (.tmp then rename).
+- Atomic write `.audit-state.json` via `scripts/write-state.sh` (takes JSON
+  on stdin, writes `.tmp`, validates with `jq`, then renames). Do NOT write
+  the state file directly.
 - Append session to `audit-history.md`.
 - `git notes --ref=super-design add -f -m <json> HEAD`.
+- First-time notes setup (run once per clone, also in `setup-git-notes.sh`
+  if you extract it): `git config --add remote.origin.fetch '+refs/notes/super-design/*:refs/notes/super-design/*'`
+  — without this, notes don't round-trip across clones (artifact §7).
 
 ### Step 5: Return summary (≤5 sentences)
 
@@ -85,6 +108,7 @@ Do NOT paste overview into chat.
 - `--fix` — run sd-fix after audit
 - `--dry-run` — artifacts without committing state
 - `--ci` — non-interactive, create PR, exit non-zero on blockers
+- `--update-baselines` — Re-hash pages and tokens without re-auditing (use after accepted cosmetic drift)
 
 ## References (Read on demand)
 

package/template/.claude/skills/super-design/references/audit-methodology.md

@@ -187,6 +187,66 @@ The 2026 WebAIM Million report (released ~30 March 2026, https://webaim.org/proj
 
 **What automation CANNOT catch** (the manual 40–70%): keyboard trap detection beyond trivial cases; screen-reader announcement quality; meaningful alt text (tools detect missing, not quality); logical focus order when CSS reorders; error message clarity; appropriate heading structure (presence vs meaning); context-appropriate link text; video caption accuracy/sync; color meaning (1.4.1); reading order under CSS transforms; reflow at 320px (no tool); text-spacing override; focus-indicator quality (2.4.11 / 2.4.13); `prefers-reduced-motion` honoring; target size / spacing (partial); autocomplete correctness; captcha alternatives; content-on-hover persistence (1.4.13); page title descriptiveness; consistent navigation/identification (3.2.3 / 3.2.4).
 
+### 2.5 Tool triangulation for automated a11y (MANDATORY)
+
+axe-core alone catches only ~57% of WCAG issues by volume (Deque's own
+coverage study) and ~40% by Success Criterion count. Running a single
+engine guarantees blind spots. sd-audit MUST run axe **plus** at least two
+more engines and dedupe the merged results by `{rule, selector}`.
+
+**Engines to run in parallel (don't serialize — they're cheap):**
+
+```bash
+# 1. axe-core — inject via Playwright MCP (already done in sd-audit Step 2,
+#    with `experimental: true` so WCAG 2.2 rules fire).
+
+# 2. Pa11y — runs both htmlcs and axe runners for broader coverage
+pa11y "$URL" \
+  --standard WCAG2AA \
+  --runner axe \
+  --runner htmlcs \
+  --reporter json \
+  > "$SESSION_DIR/a11y/pa11y_<slug>_<vp>.json"
+
+# 3. WAVE API — WebAIM's detector, overlay-oriented, strong on contrast and ARIA
+curl -s "https://wave.webaim.org/api/request?key=$WAVE_KEY&url=$(printf %s "$URL" | jq -sRr @uri)&reporttype=4" \
+  > "$SESSION_DIR/a11y/wave_<slug>_<vp>.json"
+
+# 4. IBM Equal Access Accessibility Checker — ACT-rule aligned, ~140 rules
+achecker "$URL" \
+  --reportLevel violation,potentialviolation \
+  --outputFormat json \
+  --outputFolder "$SESSION_DIR/a11y/achecker_<slug>_<vp>/"
+```
+
+**Dedup and severity normalization:**
+
+```js
+// Pseudocode — run in sd-audit Step 3a after parsing all engine outputs.
+const key = (f) => `${f.rule}::${f.selector}`;
+const bucket = new Map();
+for (const engine of ['axe', 'pa11y', 'wave', 'achecker']) {
+  for (const f of findings[engine]) {
+    const k = key(f);
+    if (!bucket.has(k)) bucket.set(k, { ...f, engines: [] });
+    bucket.get(k).engines.push(engine);
+  }
+}
+// Confidence ladder:
+//   engines.length === 1 → single-source, keep but tag "unverified"
+//   engines.length >= 2 → triangulated, high confidence
+//   engines.length >= 3 → near-certain, promote severity +1 step
+```
+
+**Why each engine is non-redundant:**
+- **axe-core** — strongest on `4.1.2`, `1.4.3`, `1.1.1`, `1.3.1` subsets; experimental flag gates 2.2.
+- **Pa11y** — htmlcs runner catches rule shapes axe doesn't ship; dual-runner mode is unique.
+- **WAVE** — contrast slider tool + in-context overlay; different heuristics for ARIA landmarks; never marks a page "passed" (useful bias — never false-clean).
+- **IBM Equal Access** — ACT-Rules aligned (different normative base than axe); baseline-file regression; severity categories (`violation / potentialviolation / recommendation / manual`) map onto Nielsen 0–4.
+
+Record per-finding `source_engines: [...]` so sd-synthesis can promote
+triangulated issues and down-weight single-engine noise.
+
 ### 2.4 Regulatory context
 
 **European Accessibility Act** (Directive (EU) 2019/882) enforceable **28 June 2025** for new products/services; 28 June 2030 deadline for pre-existing. References **EN 301 549** (currently WCAG 2.1 AA baseline; being updated to 2.2). Extraterritorial.
@@ -201,6 +261,64 @@ The 2026 WebAIM Million report (released ~30 March 2026, https://webaim.org/proj
 
 Baymard (Copenhagen, founded ~2009) is used by 71% of Fortune 500 e-commerce companies. Research: 54 rounds of benchmarking, 327 top-grossing US/EU sites, 275,000+ manually assigned UX performance scores, 200,000+ research hours. Methodology page: https://baymard.com/research/methodology. Headline finding: the average large e-commerce site can gain **+35.26% conversion** through better checkout design — **$260B** in recoverable US+EU orders.
 
+### 3.0 Baymard sub-rule enumeration (finding code prefixes)
+
+The single blanket "Baymard" verdict is too coarse for a structured audit.
+Baymard organises findings by **surface** (checkout, PDP, search, etc.) and
+each surface has a bounded, enumerable set of sub-rules. Every Baymard
+finding raised by sd-audit MUST use one of the prefixes below so
+sd-synthesis can group them and so the fix-playbook can route to the right
+U-template. Rules that do not yet have an official Baymard number are
+prefixed by count only (e.g. `baymard-cc-01` … `baymard-cc-14`) with the
+source section cited.
+
+| Surface | Prefix | Count | Source (methodology §) |
+|---|---|---|---|
+| Credit card form | `baymard-cc-<NN>` | 14 rules | §3.3 + https://baymard.com/checkout-usability/credit-card-patterns |
+| Address form | `baymard-addr-<NN>` | 8 rules | §3.4 + https://baymard.com/blog/address-line-2 + https://baymard.com/blog/automatic-address-lookup |
+| Search | `baymard-search-<NN>` | 12 rules | §3.6 + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions |
+| Filter | `baymard-filter-<NN>` | 10 rules | §3.6 + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info |
+| Breadcrumbs | `baymard-bread-<NN>` | 6 rules | §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs |
+| PDP / Product Detail | `baymard-pdp-<NN>` | 18 rules | §3.8 + https://baymard.com/research/product-page |
+
+**`baymard-cc-*` — Credit card form (14 rules, §3.3):**
+1. `baymard-cc-01` auto-format spaces per card brand (4-4-4-4 / 4-6-5 AMEX / 4-4-4-4-3 19-digit)
+2. `baymard-cc-02` auto-detect card type via IIN ranges (adapt length limit, CVV help, spacing)
+3. `baymard-cc-03` expiration as single MM/YY field with auto-inserted slash (NOT YYYY, NOT two dropdowns)
+4. `baymard-cc-04` CVV field with adaptive help image (3-digit back for Visa/MC, 4-digit front for AMEX)
+5. `baymard-cc-05` autocomplete tokens present: `cc-number`, `cc-name`, `cc-exp`, `cc-exp-month`, `cc-exp-year`, `cc-csc`
+6. `baymard-cc-06` `inputmode="numeric"` (never `type="number"`) on card number, expiration, CVV
+7. `baymard-cc-07` never clear CC number/CVV on validation error (preserve entered data)
+8. `baymard-cc-08` stored-card edit uses "fake editing" (delete + re-add) per PCI; clear messaging
+9. `baymard-cc-09` inline validation with 5%-abandonment guardrail (no vague "Card declined" without reason)
+10. `baymard-cc-10` fallback entry path when wallet (Apple Pay / Google Pay) fails
+11. `baymard-cc-11` accept pasted numbers; strip spaces/dashes server+client
+12. `baymard-cc-12` surface accepted card brands near the input (logo strip) before submit
+13. `baymard-cc-13` billing-address reuse: "Billing same as shipping" default-checked with editable prefill
+14. `baymard-cc-14` error messages identify which field failed + how to fix (not "Payment failed")
+
+> Source: §3.3 bullets + https://baymard.com/checkout-usability/credit-card-patterns. Rules 10–14 derived from §3.3 narrative; number them in this table and supersede with Baymard's official IDs when available.
+
+**`baymard-addr-*` — Address form (8 rules, §3.4):**
+1. `baymard-addr-01` country selector FIRST (drives all subsequent field formats/validation)
+2. `baymard-addr-02` single "Address Line 1" + optional "Address Line 2" labeled "Apt, Suite — optional" (never omit Line 2)
+3. `baymard-addr-03` automatic address autocomplete preferred (9% manual-entry typo rate without it)
+4. `baymard-addr-04` postal-code autodetect of city/state (28% mobile sites fail)
+5. `baymard-addr-05` US state as dropdown (not free text); UK optional county; hide for countries without subdivisions
+6. `baymard-addr-06` autocomplete tokens: `street-address`, `address-line1`, `address-line2`, `address-level1/2`, `postal-code`, `country`
+7. `baymard-addr-07` "Billing same as shipping" default-checked with editable prefilled fields (also WCAG 3.3.7 Redundant Entry)
+8. `baymard-addr-08` name inputs accept Unicode, hyphens, apostrophes, single-name users, >20 chars
+
+> Source: §3.4.
+
+**`baymard-search-*` — Search (12 rules, §3.6):** placeholders for 12 rules covering autocomplete presence, scope suggestions in autocomplete, search-within-current-category, autodirect on category match, query-term pluralization tolerance, typo tolerance, "no results" with recovery options, recent-searches memory, sort-vs-filter separation, faceted-search state in URL, submit-without-suggestion-selection, voice search on mobile. Rules `baymard-search-01` … `baymard-search-12`. Source: §3.6 bullets + https://baymard.com/ecommerce-design-examples/34-autocomplete-suggestions. Enumerate the exact wording when next Baymard PDF is purchased.
+
+**`baymard-filter-*` — Filter (10 rules, §3.6):** placeholders `baymard-filter-01` … `baymard-filter-10` covering: promote top filters above the product grid; truncate long value lists >10 with styled "More" link; category-specific filters (megapixels, temperature rating); filters for every attribute displayed in list items; expand/collapse icons right-aligned; applied-filter pills visible and individually removable; "clear all" affordance; range sliders with keyboard + numeric input; multi-select affordance obvious; result count live-updated via `aria-live`. Source: §3.6 bullets + https://baymard.com/blog/promoting-product-filters + https://baymard.com/blog/have-filters-for-list-item-info.
+
+**`baymard-bread-*` — Breadcrumbs (6 rules, §3.7):** placeholders `baymard-bread-01` … `baymard-bread-06` covering: present on all non-home pages; implement BOTH hierarchy-based AND history-based (68% of top 50 sub-par, 45% only hierarchy, 23% none); present on mobile (65% mobile fail); no "hidden in more" collapse on desktop without reveal; last crumb non-clickable; structured-data markup (`BreadcrumbList`). Source: §3.7 + https://baymard.com/blog/ecommerce-breadcrumbs.
+
+**`baymard-pdp-*` — PDP / Product Detail (18 rules, §3.8):** placeholders `baymard-pdp-01` … `baymard-pdp-18` covering: single dominant Add-to-Cart (no 3–6 competing colorful buttons); shipping cost/ETA visible on PDP (64% of users look for it); total visible before checkout (24% abandon otherwise); accordion over horizontal tabs (67% of accordion users mis-implement; 28% use worst-performing tabs); UGC visuals present (67% lack them); minimum 3–5 images + zoom + variant-driven imagery; swatches not dropdowns for variants; out-of-stock variants visible-but-disabled (not removed); star ratings above the fold (up to +18% conversion with verified badges); stock urgency without dark patterns; delivery-date estimator; returns policy on PDP; size guide inline (not in a separate page); Q&A / reviews with filtering; cross-sell without shoving below CTA; "notify me" flow for OOS; price history for discount honesty; country/currency switcher persisted. Source: §3.8 + https://baymard.com/research/product-page.
+
 ### 3.1 Cart abandonment
 **70.19% average abandonment** across 49 studies 2006–2023, range 55–84.27% (https://baymard.com/lists/cart-abandonment-rate). By device: mobile 77.06%, tablet 66.39%, desktop 70.01%. **Reasons** (excluding 43% "just browsing"): extra costs 48%; forced account creation 24%; slow delivery 19%; distrust with CC 18–19%; too long/complicated 17–18%; couldn't see total up front 16%; errors/crashes 13%; returns policy 12%; declined CC 9%; limited payment methods 7%.