docs(30): UI design contract

2026-04-12 20:01:24 +02:00
parent fd0a7eef47
commit febc43a074
1 changed files with 219 additions and 0 deletions
--- a/.planning/phases/30-onboarding-redesign/30-UI-SPEC.md
+++ b/.planning/phases/30-onboarding-redesign/30-UI-SPEC.md
@@ -0,0 +1,219 @@
+---
+phase: 30
+slug: onboarding-redesign
+status: draft
+shadcn_initialized: false
+preset: none
+created: 2026-04-12
+---
+
+# Phase 30 — UI Design Contract
+
+> Visual and interaction contract for the onboarding redesign. Generated by gsd-ui-researcher, verified by gsd-ui-checker.
+
+---
+
+## Design System
+
+| Property | Value |
+|----------|-------|
+| Tool | none |
+| Preset | not applicable |
+| Component library | none (pure Tailwind) |
+| Icon library | Lucide via `LucideIcon` from `lib/iconData` |
+| Font | System font stack (Tailwind default) |
+
+---
+
+## Spacing Scale
+
+Declared values (must be multiples of 4):
+
+| Token | Value | Usage |
+|-------|-------|-------|
+| xs | 4px | Icon gaps, inline badge padding |
+| sm | 8px | Compact element spacing, tag gaps |
+| md | 16px | Default element spacing, card padding |
+| lg | 24px | Section padding, step content margins |
+| xl | 32px | Step container padding |
+| 2xl | 48px | Major section breaks between steps |
+| 3xl | 64px | Page-level vertical padding (step centering) |
+
+Exceptions: Hobby cards use 20px internal padding (5 in Tailwind) for visual balance with icons.
+
+---
+
+## Typography
+
+| Role | Size | Weight | Line Height | Tailwind Class |
+|------|------|--------|-------------|----------------|
+| Body | 14px | 400 (normal) | 1.5 | `text-sm text-gray-500` |
+| Label | 12px | 500 (medium) | 1.25 | `text-xs font-medium text-gray-400` |
+| Heading | 18px | 600 (semibold) | 1.33 | `text-lg font-semibold text-gray-900` |
+| Display | 30px | 700 (bold) | 1.2 | `text-3xl font-bold text-gray-900` |
+| Step Subtitle | 16px | 400 (normal) | 1.5 | `text-base text-gray-500` |
+
+---
+
+## Color
+
+| Role | Value | Usage |
+|------|-------|-------|
+| Dominant (60%) | `#FFFFFF` / `white` | Full-screen backgrounds, step containers |
+| Secondary (30%) | `#F9FAFB` / `gray-50` | Card backgrounds, hobby card default state, item grid background |
+| Accent (10%) | `#374151` / `gray-700` | Primary CTA buttons, active step indicator, selected hobby card border |
+| Destructive | `#DC2626` / `red-600` | Not used in onboarding (no destructive actions) |
+
+Accent reserved for: Primary "Get Started" / "Confirm" / "Continue" buttons, active progress indicator segment, selected hobby card outline ring.
+
+### Selection States
+
+| State | Visual Treatment |
+|-------|-----------------|
+| Hobby card default | `bg-gray-50 border border-gray-200 rounded-2xl` |
+| Hobby card hover | `border-gray-300 shadow-sm` |
+| Hobby card selected | `border-gray-700 ring-2 ring-gray-700/20 bg-white` |
+| Item card default | `bg-white border border-gray-100 rounded-xl` |
+| Item card hover | `border-gray-200 shadow-sm` |
+| Item card selected | `border-gray-700 ring-2 ring-gray-700/20` with checkmark overlay |
+
+---
+
+## Copywriting Contract
+
+| Element | Copy |
+|---------|------|
+| Welcome heading | "Welcome to GearBox" |
+| Welcome body | "Tell us what you're into, and we'll help you set up your collection with gear that people actually use." |
+| Primary CTA (welcome) | "Let's go" |
+| Hobby picker heading | "What are you into?" |
+| Hobby picker body | "Pick one or more — we'll show you popular gear for each." |
+| Item browser heading | "Popular gear for {hobby}" |
+| Item browser body | "Tap items you already own. We'll add them to your collection." |
+| Item browser empty state heading | "No gear cataloged yet" |
+| Item browser empty state body | "We're still building our catalog for this hobby. You can skip this step and add gear manually later." |
+| Review heading | "Your starting collection" |
+| Review body | "{N} items ready to add" |
+| Review CTA | "Add to my collection" |
+| Review empty | "No items selected — you can always add gear later from the catalog." |
+| Skip link | "Skip this step" |
+| Done heading | "You're all set!" |
+| Done body | "Your collection is ready. Browse the catalog anytime to discover more gear." |
+| Done CTA | "Start exploring" |
+
+---
+
+## Component Inventory
+
+### OnboardingFlow (top-level)
+
+Full-screen overlay replacing the current `OnboardingWizard`. Renders when `onboardingComplete !== "true"` and user is authenticated.
+
+```
+Layout: fixed inset-0 z-50 bg-white
+Step container: flex flex-col items-center justify-center min-h-screen px-8
+Max content width: max-w-2xl (672px) for text steps, max-w-5xl (1024px) for item grid
+```
+
+### Step Indicator
+
+Full-width horizontal progress bar at the top of every step.
+
+```
+Container: fixed top-0 left-0 right-0 h-1 bg-gray-100
+Progress fill: h-1 bg-gray-700 transition-all duration-500
+Steps: Welcome=25%, Hobby=50%, Browse=75%, Review/Done=100%
+```
+
+### HobbyCard
+
+Visual card for hobby selection. Displays icon + name + short descriptor.
+
+```
+Layout: w-40 h-40 flex flex-col items-center justify-center gap-3 p-5 rounded-2xl cursor-pointer transition-all
+Icon: LucideIcon size={32}
+Name: text-sm font-semibold text-gray-900
+Descriptor: text-xs text-gray-400
+Grid: flex flex-wrap justify-center gap-4
+```
+
+Hobby card data:
+
+| Hobby | Icon | Descriptor |
+|-------|------|------------|
+| Bikepacking | `bike` | Ride & camp |
+| Hiking | `mountain` | Trail gear |
+| Climbing | `mountain-snow` | Vertical kit |
+| Cycling | `circle-dot` | Road & gravel |
+| Camping | `tent` | Base camp |
+| Running | `footprints` | Run light |
+
+### SelectableItemCard
+
+Extends `GlobalItemCard` visual pattern with selection overlay.
+
+```
+Layout: Same as GlobalItemCard (bg-white rounded-xl border border-gray-100)
+Selection overlay: absolute top-2 right-2, 24x24 circle
+Unselected: border-2 border-gray-200 bg-white rounded-full
+Selected: bg-gray-700 border-gray-700 rounded-full with white check icon (size 14)
+Grid: grid grid-cols-2 sm:grid-cols-3 lg:grid-cols-4 gap-4
+```
+
+### ReviewList
+
+Summary of selected items grouped by category.
+
+```
+Category heading: text-xs font-medium text-gray-400 uppercase tracking-wide
+Item row: flex items-center gap-3 py-2 border-b border-gray-50
+Item image: w-10 h-10 rounded-lg object-cover bg-gray-50
+Item name: text-sm text-gray-900
+Remove button: text-gray-300 hover:text-red-500, X icon (size 16)
+```
+
+---
+
+## Transitions
+
+Step transitions use CSS transitions (no framer-motion dependency):
+
+```
+Enter: opacity-0 translate-y-4 → opacity-100 translate-y-0 (duration-300 ease-out)
+Exit: opacity-100 translate-y-0 → opacity-0 -translate-y-4 (duration-200 ease-in)
+```
+
+Implementation: conditionally render steps with Tailwind transition classes and a brief `setTimeout` for exit animation before switching step state.
+
+---
+
+## Responsive Behavior
+
+| Breakpoint | Behavior |
+|------------|----------|
+| Mobile (<640px) | Single column item grid, hobby cards 2-across, step content full-width with px-6 |
+| Tablet (640-1024px) | 2-3 column item grid, hobby cards 3-across |
+| Desktop (>1024px) | 4-column item grid, hobby cards in single centered row |
+
+---
+
+## Registry Safety
+
+| Registry | Blocks Used | Safety Gate |
+|----------|-------------|-------------|
+| No external registries | none | not required |
+
+All components are custom Tailwind — no shadcn or third-party UI blocks.
+
+---
+
+## Checker Sign-Off
+
+- [ ] Dimension 1 Copywriting: PASS
+- [ ] Dimension 2 Visuals: PASS
+- [ ] Dimension 3 Color: PASS
+- [ ] Dimension 4 Typography: PASS
+- [ ] Dimension 5 Spacing: PASS
+- [ ] Dimension 6 Registry Safety: PASS
+
+**Approval:** pending