GearBox/.planning/milestones/v2.2-phases/30-onboarding-redesign/30-UI-SPEC.md

phase, slug, status, shadcn_initialized, preset, created

phase	slug	status	shadcn_initialized	preset	created
30	onboarding-redesign	draft	false	none	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