8 KiB
| phase | slug | status | shadcn_initialized | preset | created |
|---|---|---|---|---|---|
| 30 | hardware-detection-mode-selection | draft | true | new-york / neutral / css-variables | 2026-04-02 |
Phase 30 — UI Design Contract
Visual and interaction contract for Phase 30: Hardware Detection + Mode Selection. Generated by gsd-ui-researcher. Verified by gsd-ui-checker.
Design System
| Property | Value | Source |
|---|---|---|
| Tool | shadcn/ui | components.json detected |
| Style | new-york | components.json |
| Base color | neutral | components.json |
| CSS variables | yes | components.json |
| Component library | radix-ui | package.json |
| Icon library | lucide-react (v0.574.0) | package.json |
| Font | system sans-serif (Tailwind default) | index.css — no custom font declared |
Spacing Scale
Declared values (must be multiples of 4):
| Token | Value | Usage |
|---|---|---|
| xs | 4px | Icon gaps, inline padding (gap-1) |
| sm | 8px | Compact element spacing (gap-2, p-2) |
| md | 16px | Default element spacing (gap-4, p-4) |
| lg | 24px | Section padding (gap-6, p-6) |
| xl | 32px | Card padding, layout gaps (p-8) |
| 2xl | 48px | Major section breaks |
| 3xl | 64px | Page-level spacing |
Exceptions:
- Mode selector cards:
p-4(16px) internal padding — consistent with existing shadcn card pattern - Hardware stat rows:
gap-2(8px) between icon and value - Wizard dialog:
p-8(32px) outer padding — matches NexusOnboardingWizard.tsx
Source: NexusOnboardingWizard.tsx spacing patterns (p-8, gap-6, gap-4, gap-2)
Typography
| Role | Size | Weight | Line Height | Usage |
|---|---|---|---|---|
| Body | 14px (text-sm) |
400 (regular) | 1.5 | Descriptions, form labels, mode card titles, stat labels, muted helper text |
| Heading | 24px (text-2xl) |
600 (semibold) | 1.2 | Step heading ("Choose your mode") |
| Caption | 12px (text-xs) |
400 (regular) | 1.4 | Mode card descriptions, hardware sub-labels |
Source: NexusOnboardingWizard.tsx uses text-2xl font-semibold for heading, text-sm for body, text-xs text-muted-foreground for captions. No 4th size needed beyond these three roles.
Color
All values are CSS variable references to the project's dual-theme token set (Catppuccin Latte light / Catppuccin Mocha dark, Tokyo Night dark variant also present).
| Role | Light value | Dark value | Usage |
|---|---|---|---|
| Dominant (60%) | --background #eff1f5 |
#1e1e2e | Dialog backdrop, page surface |
| Secondary (30%) | --card #e6e9ef |
#181825 | Mode selector cards, hardware info card, stat rows |
| Accent (10%) | --primary #1e66f5 |
#89b4fa | Selected mode card border + tint, active step indicator, spinner |
| Destructive | --destructive #d20f39 |
#f38ba8 | Error messages only |
Accent reserved for:
- Selected mode card:
border-primary bg-primary/5(identical to RESEARCH.md Pattern 5) - Primary CTA button background
- Spinner/loading indicator while probe is in-flight
- Focus ring (
--ring= same as--primary)
No second semantic color beyond destructive. Success states (hardware probe OK) use muted text color, not a success green — consistent with wizard's existing error pattern that uses text-destructive not a new semantic color.
Source: index.css CSS custom properties; NexusOnboardingWizard.tsx color class patterns
Component Inventory
New components to build for this phase:
| Component | Path | Shadcn primitives used |
|---|---|---|
ModeSelector |
ui/src/components/onboarding/ModeSelector.tsx |
none (raw buttons + cn utility) |
HardwareSummaryStep |
ui/src/components/onboarding/HardwareSummaryStep.tsx |
Skeleton, Badge (optional) |
NexusOnboardingWizard |
ui/src/components/NexusOnboardingWizard.tsx |
Dialog/DialogPortal, Button, Input (already imported) |
Existing shadcn components already installed and usable without re-adding:
button, input, dialog, skeleton, badge, card, separator, tabs, tooltip
States and Interactions
ModeSelector
| State | Visual |
|---|---|
| Unselected | border-border hover:border-muted-foreground/50 — subtle hover |
| Selected | border-primary bg-primary/5 — primary accent border + tinted fill |
| Default selection | "Both (recommended)" pre-selected on mount |
HardwareSummaryStep
| State | Visual |
|---|---|
| Probing (in-flight) | Three Skeleton rows (GPU/RAM/Tier), each h-4 w-full rounded — matches shadcn Skeleton usage |
| Probe success — GPU tier | GPU name + VRAM GB labeled "GPU VRAM", tier badge "GPU-accelerated" |
| Probe success — Apple Silicon | Unified memory GB labeled "Unified memory" (never "VRAM"), tier badge "Apple Silicon" |
| Probe success — CPU-only | RAM labeled "System RAM", muted warning "Slower than GPU-accelerated models — cloud AI recommended" |
| Probe error / timeout | Inline error row: "Could not detect hardware. You can still continue." — uses text-muted-foreground, not text-destructive (non-blocking) |
Privacy frame (ONBD-07 — shown when local AI tier is viable, i.e. gpu or apple_silicon):
Local AI (recommended for privacy)
Runs entirely on your machine.
No accounts. No tracking. Works offline.
Rendered as: heading text-sm font-medium + two-line body text-xs text-muted-foreground. No icon required — copy is the signal.
Onboarding Wizard Step Flow
Steps added to the existing NexusOnboardingWizard:
- Hardware detection (auto-runs, no user input) —
HardwareSummaryStep - Mode selection —
ModeSelector - Root directory (existing step — moved to step 3)
Step indicator: simple numbered dots or text "Step N of 3" using text-xs text-muted-foreground. No progress bar component needed at this phase.
Probe timeout: 5 seconds maximum (ONBD-02 success criterion). If probe does not resolve within 5s, show error state and continue.
Copywriting Contract
| Element | Copy | Source |
|---|---|---|
| Wizard heading (step 1) | "Detecting your hardware…" | Default (probe in-flight) |
| Wizard heading (step 1 resolved) | "Your hardware" | Default |
| Wizard heading (step 2) | "Choose your mode" | RESEARCH.md mode labels |
| Mode: Personal AI | "Personal AI Assistant" / "Always available, persistent memory, private." | RESEARCH.md Pattern 5 verbatim |
| Mode: Project Builder | "Project Builder" / "Brainstorm → PM → Engineer → shipped product." | RESEARCH.md Pattern 5 verbatim |
| Mode: Both | "Both (recommended)" / "A conversation becomes a project with one click." | RESEARCH.md Pattern 5 verbatim |
| Local AI privacy frame | "Local AI (recommended for privacy) — Runs entirely on your machine. No accounts. No tracking. Works offline." | ONBD-07 PRD copy verbatim |
| CPU-only warning | "Slower than GPU-accelerated models — cloud AI recommended" | RESEARCH.md Pattern 6 display rules |
| Hardware probe error | "Could not detect hardware. You can still continue." | Default — non-blocking |
| Primary CTA (step 2 → step 3) | "Continue" | Default |
| Primary CTA (step 3 — final) | "Get Started" | Existing wizard copy preserved |
| Empty state heading | not applicable — hardware probe always returns a result (even degraded) | — |
| Error state | "Setup failed. Please try again." | Existing wizard pattern preserved |
Destructive actions in this phase: none. Mode selection is reversible; no confirmation dialogs required.
No "company", "CEO", or "mission" language. VOCAB.appName is the only brand token allowed.
Registry Safety
| Registry | Blocks Used | Safety Gate |
|---|---|---|
| shadcn official | button, input, dialog, skeleton, badge | not required |
| third-party | none | not applicable |
No third-party registries declared for this phase.
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