familysync/.planning/phases/12-initial-setup-wizard/12-UI-SPEC.md

---
phase: 12
slug: initial-setup-wizard
status: draft
shadcn_initialized: false
preset: none
created: 2026-06-14
---

# Phase 12 — UI Design Contract: Initial Setup Wizard

> Visual and interaction contract for the first-run setup wizard.
> Generated by gsd-ui-researcher. Verified by gsd-ui-checker.

---

## Context & Audience

This wizard is **operator-facing, not end-user-facing**. The operator is the person standing up
the self-hosted FamilySync instance on Unraid — technical enough to edit `docker-compose.yml`,
but not necessarily a developer. The wizard renders for an **unauthenticated visitor** (it is the
one screen in the app shown outside the Authelia/OIDC guard). It must be calm, legible, and
unintimidating.

This is the **only full-page standalone UI** in the app. It does NOT render inside the existing
AppNav + BottomTabBar shell. It owns its entire viewport.

All design tokens are inherited from the existing system (`apps/pwa/src/styles/tokens.css`).
No new tokens are introduced.

---

## Design System

| Property | Value |
|----------|-------|
| Tool | none (existing CSS custom properties) |
| Preset | not applicable |
| Component library | none (hand-rolled inline styles, project convention) |
| Icon library | lucide-react (already installed — `KeyRound`, `CheckCircle`, `AlertCircle`, `Loader2`, `Copy`, `Check`, `ShieldCheck`) |
| Font | system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif (var(--font-family-base)) |

Source: `apps/pwa/src/styles/tokens.css` — pre-populated from existing codebase.

---

## Spacing Scale

Uses the existing 4px-based scale. No new tokens. Values from `tokens.css`:

| Token | Value | Usage |
|-------|-------|-------|
| --space-1 | 4px | Icon gaps, label-to-input gap |
| --space-2 | 8px | Compact element spacing, badge gap |
| --space-3 | 12px | Input padding (vertical), row gaps |
| --space-4 | 16px | Default element spacing, card padding, input padding (horizontal) |
| --space-6 | 24px | Sheet/card padding, section gap |
| --space-8 | 32px | Between major sections |
| --space-12 | 48px | Page top/bottom padding (AdminPage pattern) |

Exceptions:
- Wizard card max-width: 540px (slightly wider than CredentialSheet 480px to accommodate
  multi-field steps and generated-secret blocks).
- Step indicator touch targets: 44px minimum (accessibility).
- Copy-to-clipboard button: 36px height is acceptable since it is paired with an adjacent
  textarea (which itself is large enough), but the copy button must have `minWidth: 44px`.

---

## Typography

All values from `tokens.css`. No new sizes or weights.

| Role | Size | Weight | Line Height | Variable |
|------|------|--------|-------------|----------|
| Body | 15px | 400 | 1.5 | var(--text-body-size) / var(--text-body-weight) / var(--text-body-line-height) |
| Label | 13px | 400 | 1.4 | var(--text-label-size) / var(--text-label-weight) / var(--text-label-line-height) |
| Heading | 18px | 600 | 1.25 | var(--text-heading-size) / var(--text-heading-weight) / var(--text-heading-line-height) |
| Display | 24px | 600 | 1.2 | var(--text-display-size) / var(--text-display-weight) / var(--text-display-line-height) |

Usage in this phase:
- Wizard page title ("FamilySync Setup"): Display (24px/600/1.2)
- Step heading (e.g. "Generate Secrets"): Heading (18px/600/1.25)
- Step description / helper text: Body (15px/400/1.5)
- Field labels, step counter, status badges: Label (13px/400/1.4) — labels use weight 600
- Generated secret value (monospace block): 13px/400/1.4 with `font-family: monospace` override
- Section labels (uppercase caps, e.g. "STEP 2 OF 5"): Label (13px/600) with
  `text-transform: uppercase; letter-spacing: 0.06em` (AdminPage `sectionLabelStyle` pattern)

---

## Color

All values from `tokens.css`. No new hex values.

| Role | Value | Variable | Usage |
|------|-------|----------|-------|
| Dominant (60%) | #ffffff | var(--color-surface) | Page background, card background |
| Secondary (30%) | #f7f7f8 | var(--color-surface-dim) | Step sidebar/tracker background, generated-secret block background, inactive step indicator |
| Accent (10%) | #4a90d9 | var(--color-member-0) | Primary CTA buttons, active step indicator fill, spinner, copy button, links |
| Destructive | #dc2626 | var(--color-destructive) | Validation failure border + helper text (same CredentialSheet pattern) |

Accent reserved for:
- Primary action buttons ("Continue", "Complete Setup") — filled background
- Active wizard step indicator (filled circle)
- Inline spinner (`Loader2`) during async validation
- Hyperlinks (e.g. "Get an app password")
- Copy-to-clipboard button icon
- Focus ring (`var(--color-focus-ring): #4a90d9`)

Additional semantic colors (not new — already in tokens.css):
- `var(--color-border)` #e2e4e9 — card border, input border (default), step connector line
- `var(--color-border-subtle)` #eceef2 — section dividers within steps
- `var(--color-text-primary)` #111318 — headings, field values
- `var(--color-text-secondary)` #6b7280 — descriptions, helper text, "Back" button
- `var(--color-text-muted)` #9ca3af — completed step labels, placeholder text, inactive step numbers

---

## Surface Architecture

The wizard is a **standalone full-page route** (`/setup`) mounted in a separate React root or
an App-level gate (see Interaction Contract). It renders none of the AppNav / BottomTabBar /
SetupBanner chrome.

### Surface 1 — Wizard Page Shell

The wizard page itself.

- Background: `var(--color-surface)` (#ffffff)
- Layout: vertically centered column, `min-height: 100dvh`
- Content column: `maxWidth: 540px`, `margin: 0 auto`,
  `padding: var(--space-12) var(--space-6)` (48px top/bottom, 24px sides)
- Page title "FamilySync Setup": Display (24px/600), `color: var(--color-text-primary)`,
  `marginBottom: var(--space-2)` (8px)
- Page subtitle "Let's get your instance ready.": Body (15px/400),
  `color: var(--color-text-secondary)`, `marginBottom: var(--space-8)` (32px)

### Surface 2 — Step Indicator

Linear step tracker shown above the active step card.

- Horizontal row of N step circles connected by lines
- Completed step: filled circle `var(--color-member-0)` with white `Check` icon (16px)
- Active step: filled circle `var(--color-member-0)` with white step number (13px/600)
- Upcoming step: circle with `var(--color-border)` 2px border, `var(--color-text-muted)` step
  number
- Connector line: 1px `var(--color-border)` between circles; completed segment fills to
  `var(--color-member-0)`
- Step label below each circle: 13px/400, `var(--color-text-muted)` (upcoming/completed),
  `var(--color-text-primary)` (active)
- Circle size: 28px diameter; connector height: 1px; minimum row height: 44px touch target
  achieved by centering in a 44px tall row

Step labels (5 steps total):
1. Welcome
2. Secrets
3. Database
4. OIDC
5. Calendar

### Surface 3 — Step Card

The active step's input/content area. One card rendered at a time.

- Background: `var(--color-surface)` (#ffffff)
- Border: `1px solid var(--color-border)` (#e2e4e9)
- Border-radius: 8px (2× `var(--space-2)`)
- Padding: `var(--space-6)` (24px) all sides
- Box-shadow: `0 1px 4px rgba(0,0,0,0.06)` (subtle lift)
- Step heading: Heading (18px/600), `color: var(--color-text-primary)`,
  `marginBottom: var(--space-2)` (8px)
- Step description: Body (15px/400), `color: var(--color-text-secondary)`, `lineHeight: 1.5`,
  `marginBottom: var(--space-6)` (24px)
- Field group spacing: `var(--space-4)` (16px) between fields

### Surface 4 — Generated-Secret Block

Used in Step 2 (Secrets) for values the operator must copy into env.

- Background: `var(--color-surface-dim)` (#f7f7f8)
- Border: `1px solid var(--color-border-subtle)` (#eceef2)
- Border-radius: 4px (`var(--space-1)`)
- Padding: `var(--space-3) var(--space-4)` (12px 16px)
- Secret value: monospace, 13px/400, `var(--color-text-primary)`, word-break: break-all
  (VAPID keys are long strings)
- Label above block: Label (13px/600), `var(--color-text-primary)`
- Copy button: icon-only (`Copy` icon 16px, `var(--color-member-0)`), positioned top-right
  inside the block, `minWidth: 44px`, `minHeight: 36px` (acceptable — paired with large block)
- After copy: icon swaps to `Check` (16px, `var(--color-member-0)`) for 2 seconds, then reverts
- Acknowledgement checkbox below each secret block: standard checkbox input, Label (13px/400),
  "I have copied this value into my `.env` file." — the Continue button is disabled until all
  checkboxes on the step are checked.

### Surface 5 — Validation State Row

Shown after the operator submits a validation step (DB / OIDC / CalDAV).

- Pending: `Loader2` icon (16px, `var(--color-member-0)`, `animation: spin 1s linear infinite`) +
  Body (15px/400) status text in `var(--color-text-secondary)` — inline row
- Success: `CheckCircle` icon (16px, `var(--color-text-secondary)`) + success text Body (15px/400)
  in `var(--color-text-secondary)`
- Failure: `AlertCircle` icon (16px, `var(--color-destructive)`) + error text Body (15px/400) in
  `var(--color-destructive)` — same pattern as CredentialSheet `FAILURE_TEXT`
- Layout: `display: flex; alignItems: center; gap: var(--space-2, 8px)` (CredentialSheet pattern)

### Surface 6 — Action Row

Bottom of each step card.

- Layout: `display: flex; justifyContent: flex-end; gap: var(--space-3, 12px)` (CredentialSheet
  pattern)
- "Back" button: ghost (no background, no border), Label (13px/600),
  `color: var(--color-text-secondary)`, `minHeight: 44px`, `padding: 0 var(--space-4)`
  — hidden on Step 1 (no back from Welcome)
- "Continue" / "Complete Setup" button: filled, `background: var(--color-member-0)` (#4a90d9),
  `color: #ffffff`, Label (13px/600), `minHeight: 44px`, `padding: 0 var(--space-6)`,
  `borderRadius: var(--space-1)` (4px), `transition: background 0.15s ease`
  — disabled state: `background: var(--color-border)` (#e2e4e9), `cursor: default`
  (AdminPage / CredentialSheet pattern)
- "Continue" label on steps 1–4; "Complete Setup" label on step 5

### Surface 7 — Terminal "Setup Complete" Screen

Replaces the wizard card after step 5 completes successfully.

- Icon: `ShieldCheck` (48px, `var(--color-member-0)`) centered
- Heading: "Setup complete" — Display (24px/600), centered, `marginTop: var(--space-4)`,
  `color: var(--color-text-primary)`
- Body: "Your FamilySync instance is ready. Sign in to continue." — Body (15px/400),
  `color: var(--color-text-secondary)`, centered, `marginTop: var(--space-2)`
- "Sign in" button: filled accent button (same style as Continue), centered,
  `marginTop: var(--space-6)`, navigates to `/` (triggers OIDC redirect)
- No step indicator visible on this screen (step indicator hidden once setup complete)

### Surface 8 — "Already Locked" Screen

Shown when the operator navigates to `/setup` after `setup_complete = true` (423 from API).

- Icon: `ShieldCheck` (48px, `var(--color-text-muted)`) centered
- Heading: "Setup already complete" — Heading (18px/600), centered,
  `color: var(--color-text-primary)`
- Body: "This instance has already been configured. Sign in to continue." — Body (15px/400),
  `color: var(--color-text-secondary)`, centered
- "Sign in" link: accent-colored text link (no button chrome), 15px/600,
  navigates to `/`

---

## Wizard Steps — Detailed Interaction Contract

### Step 1: Welcome

Purpose: orient the operator; no inputs; no validation.

- Heading: "Welcome to FamilySync Setup"
- Description: "This wizard will guide you through configuring your self-hosted instance.
  You'll need: your OIDC client credentials (Authelia), a Fastmail account with an app password,
  and a copy of your `docker-compose.yml` to paste generated secrets into. This takes about
  5 minutes."
- No input fields.
- Continue button: always enabled.

### Step 2: Generate Secrets

Purpose: display generated session secret, encryption key, and VAPID keypair; operator copies
each into env.

- Heading: "Generated Secrets"
- Description: "These values are generated once and displayed now. Copy each into your
  `docker-compose.yml` environment block before continuing. They will never be shown again and
  are not stored in the database."
- Four generated-secret blocks (Surface 4), each with acknowledgement checkbox:
  1. `SESSION_SECRET` — label "Session secret", 64-char hex string
  2. `APP_PASSWORD_ENCRYPTION_KEY` — label "Encryption key", 64-char hex string
  3. `VAPID_PUBLIC_KEY` — label "VAPID public key"
  4. `VAPID_PRIVATE_KEY` — label "VAPID private key"
- Continue button disabled until all 4 checkboxes are checked.
- No async validation on this step. Secrets are generated client-side or fetched from
  `POST /api/setup/generate` (backend choice — UI treats them as string values to display).

### Step 3: Database

Purpose: verify the DB connection configured in env is reachable.

- Heading: "Database Connection"
- Description: "Verify that the app can reach the MariaDB database configured in your
  environment. No changes are made — this is a read-only connectivity check."
- No operator input fields (DB creds come from env, not from this UI).
- "Test Connection" button (primary filled, full-width on this step — replace normal action row):
  triggers `POST /api/setup/validate/db`
- Validation state row (Surface 5) shown below the description during/after the test:
  - Pending: "Testing database connection…"
  - Success: "Database connection verified."
  - Failure: "Cannot reach the database. Check DB_HOST, DB_PORT, DB_USER, DB_PASSWORD in your
    `docker-compose.yml` and try again."
- Continue button appears after success; disabled during pending; hidden on failure (operator
  must retry first).
- Back is available.

### Step 4: OIDC & VAPID

Purpose: verify OIDC discovery resolves and the VAPID keypair in env is structurally valid.

- Heading: "OIDC & Push"
- Description: "Verify that the Authelia OIDC issuer is reachable and that the VAPID keypair
  you copied in Step 2 is in place."
- Two validation rows, triggered sequentially by "Validate" button:
  - OIDC: label "Authelia issuer discovery", `POST /api/setup/validate/oidc`
    - Pending: "Checking OIDC discovery…"
    - Success: "OIDC discovery resolved."
    - Failure: "OIDC discovery failed. Check OIDC_ISSUER in your environment and that Authelia
      is reachable."
  - VAPID: label "VAPID keypair", `POST /api/setup/validate/vapid`
    - Pending: "Checking VAPID keypair…"
    - Success: "VAPID keypair is valid."
    - Failure: "VAPID private key could not be verified. Ensure you copied both keys from Step 2
      into your environment and restarted the container."
- "Validate" button triggers both checks in sequence.
- Continue appears (and is enabled) only when both rows show success.
- Back is available.

### Step 5: Calendar Credential

Purpose: set the first member's Fastmail app password; validate against CalDAV PROPFIND.
Reuses the CredentialSheet interaction pattern (same fields, same validation feedback,
same copy).

- Heading: "Fastmail Credential"
- Description: "Add the Fastmail app password for the first household member. This credential
  is validated against Fastmail CalDAV before saving. The password is never stored in
  plain text."
- Fields (same as CredentialSheet):
  - Fastmail email (type="email", autoComplete="email", placeholder="user@fastmail.com")
  - App password (type="password", autoComplete="new-password")
- Helper text below fields: "Enter the Fastmail app password scoped to Calendars/CalDAV.
  [Get an app password](https://app.fastmail.com/settings/security/devicetokens) — choose
  the 'Calendars & Contacts (CalDAV)' scope."
  - Link: accent-colored, `text-decoration: underline`, opens in new tab
    `rel="noopener noreferrer"`
- Validation state row (Surface 5):
  - Pending: "Validating against CalDAV…" (Loader2 spinner)
  - Success: "Credential verified." — Continue becomes enabled
  - Failure: "Invalid password — CalDAV validation failed. Check the scope is 'Calendars &
    Contacts (CalDAV)' and try again." (in `var(--color-destructive)`)
- Continue button label on this step: "Complete Setup"
- On continue: `POST /api/setup/complete` — promotes operator to admin, sets
  `app_config.setup_complete`, redirects to Surface 7 (Terminal Screen)
- Back is available.

---

## Routing & App-Level Gate

The wizard lives at route `/setup`. App.tsx must add a gate at startup:

1. On app load, `GET /api/setup/status` is fetched (before any other /api route, mounts outside
   OIDC guard).
2. If response is `{ setupComplete: false }` → redirect entire app to `/setup` (full-page
   takeover, no AppNav/BottomTabBar rendered).
3. If response is `{ setupComplete: true }` → normal app boot continues.
4. If `/setup` is navigated directly after setup is complete (API returns 423) → render
   Surface 8 ("Already Locked").

The `/setup` route does NOT render inside the normal App shell. It replaces it entirely (or
is handled before `<BrowserRouter>` routes — implementation choice for planner, but the design
contract requires: no AppNav, no BottomTabBar, no SetupBanner, no PermissionDeniedBanner).

---

## Copywriting Contract

| Element | Copy |
|---------|------|
| Page title | "FamilySync Setup" |
| Page subtitle | "Let's get your instance ready." |
| Primary CTA (steps 1–4) | "Continue" |
| Primary CTA (step 5) | "Complete Setup" |
| Secondary action | "Back" |
| Terminal heading | "Setup complete" |
| Terminal body | "Your FamilySync instance is ready. Sign in to continue." |
| Terminal CTA | "Sign in" |
| Locked heading | "Setup already complete" |
| Locked body | "This instance has already been configured. Sign in to continue." |
| Locked link | "Sign in" |
| Step 1 heading | "Welcome to FamilySync Setup" |
| Step 1 description | "This wizard will guide you through configuring your self-hosted instance. You'll need: your OIDC client credentials (Authelia), a Fastmail account with an app password, and a copy of your `docker-compose.yml` to paste generated secrets into. This takes about 5 minutes." |
| Step 2 heading | "Generated Secrets" |
| Step 2 description | "These values are generated once and displayed now. Copy each into your `docker-compose.yml` environment block before continuing. They will never be shown again and are not stored in the database." |
| Step 2 acknowledgement | "I have copied this value into my `.env` file." |
| Step 3 heading | "Database Connection" |
| Step 3 description | "Verify that the app can reach the MariaDB database configured in your environment. No changes are made — this is a read-only connectivity check." |
| Step 3 CTA | "Test Connection" |
| Step 3 pending | "Testing database connection…" |
| Step 3 success | "Database connection verified." |
| Step 3 failure | "Cannot reach the database. Check DB_HOST, DB_PORT, DB_USER, DB_PASSWORD in your `docker-compose.yml` and try again." |
| Step 4 heading | "OIDC & Push" |
| Step 4 description | "Verify that the Authelia OIDC issuer is reachable and that the VAPID keypair you copied in Step 2 is in place." |
| Step 4 CTA | "Validate" |
| Step 4 OIDC pending | "Checking OIDC discovery…" |
| Step 4 OIDC success | "OIDC discovery resolved." |
| Step 4 OIDC failure | "OIDC discovery failed. Check OIDC_ISSUER in your environment and that Authelia is reachable." |
| Step 4 VAPID pending | "Checking VAPID keypair…" |
| Step 4 VAPID success | "VAPID keypair is valid." |
| Step 4 VAPID failure | "VAPID private key could not be verified. Ensure you copied both keys from Step 2 into your environment and restarted the container." |
| Step 5 heading | "Fastmail Credential" |
| Step 5 description | "Add the Fastmail app password for the first household member. This credential is validated against Fastmail CalDAV before saving. The password is never stored in plain text." |
| Step 5 helper text | "Enter the Fastmail app password scoped to Calendars/CalDAV." |
| Step 5 helper link text | "Get an app password" |
| Step 5 helper link suffix | " — choose the 'Calendars & Contacts (CalDAV)' scope." |
| Step 5 pending | "Validating against CalDAV…" |
| Step 5 success | "Credential verified." |
| Step 5 failure | "Invalid password — CalDAV validation failed. Check the scope is 'Calendars & Contacts (CalDAV)' and try again." |
| Empty state (none for wizard — every step has explicit content) | N/A |
| Error state (network/unexpected) | "Something went wrong. Please try again." (generic fallback, shown in Surface 5 failure style) |
| Destructive actions | None — wizard has no destructive actions. The "Complete Setup" action is irreversible in effect but not destructive; no confirmation dialog required. |

---

## Accessibility Contract

- `role="main"` on the wizard content column
- Step indicator: `role="list"` with each step as `role="listitem"`;
  active step has `aria-current="step"`
- Step card: `role="group"` with `aria-labelledby` pointing to the step heading `id`
- Heading hierarchy: `<h1>` for page title, `<h2>` for step heading
- All inputs: explicit `<label htmlFor>` association (same CredentialSheet pattern)
- Disabled buttons: `disabled` attribute (not just pointer-events: none)
- Copy button: `aria-label="Copy {field name}"`, swaps to `aria-label="Copied"` for 2 seconds
- Validation state row: `role="status"` with `aria-live="polite"` so screen readers announce
  results without focus movement
- Escape key: no sheet to close on this page; Escape has no effect in wizard
- Focus management: on step advance, focus moves to the new step heading (tabIndex={-1} pattern
  from CredentialSheet heading)
- Minimum touch targets: 44px on all interactive elements (`minHeight: 44px`, `minWidth: 44px`)
- Focus ring: `var(--color-focus-ring)` (#4a90d9), 2px outline, 2px offset on all focusable
  elements (same project convention)
- Secret textarea (if used instead of div): `readonly`, `aria-label="{field name} value"`

---

## Responsive Behavior

The wizard is desktop-first (operator is typically on a desktop browser when standing up
infrastructure), but must be usable on a phone if needed.

- Desktop (≥768px): card centered at maxWidth 540px; step indicator spans full card width
- Phone (<768px): card fills viewport minus 24px horizontal padding;
  step indicator uses short labels (1, 2, 3, 4, 5) or icon-only to avoid overflow;
  no bottom tab bar (not rendered at all on wizard page)
- No BottomTabBar, no AppNav on this page at any breakpoint

---

## Security Display Rules

These are hard UI rules, not implementation notes:

- Secret values in Surface 4 blocks: displayed in a readonly `<textarea>` or `<div>` with
  `userSelect: all` for easy selection — never in a `type="password"` input (they must be
  visible to copy)
- App password in Step 5: `type="password"` — never visible
- No `dangerouslySetInnerHTML` anywhere on this page (T-05-24 project convention)
- Acknowledgement checkboxes enforce operator intent before Continue is enabled; this is a UX
  gate only (not a security boundary — the secrets are already displayed)

---

## Registry Safety

| Registry | Blocks Used | Safety Gate |
|----------|-------------|-------------|
| shadcn official | none | not applicable |
| third-party | none | not applicable |

No third-party registries. All components are hand-rolled following existing project convention.
lucide-react icons are already installed (`KeyRound`, `ShieldCheck`, `Loader2`, `CheckCircle`,
`AlertCircle`, `Copy`, `Check` are all available or trivially added from the existing
lucide-react dependency).

---

## Pre-Population Sources

| Decision | Source | Value |
|----------|--------|-------|
| Spacing scale | apps/pwa/src/styles/tokens.css | --space-1 through --space-12 |
| Typography scale | apps/pwa/src/styles/tokens.css | 4 sizes (13/15/18/24px), 2 weights (400/600) |
| Color palette | apps/pwa/src/styles/tokens.css | All hex values |
| Component library | apps/pwa (convention) | Hand-rolled inline styles, no shadcn |
| Icon library | apps/pwa imports | lucide-react |
| Button style | CredentialSheet.tsx / AdminPage.tsx | Filled accent for primary, ghost for secondary |
| Input style | CredentialSheet.tsx | 12px/16px padding, 4px border-radius, destructive border on error |
| Section label style | AdminPage.tsx | 13px/600/uppercase/0.06em letter-spacing |
| Card padding | AdminPage.tsx | var(--space-12) top/bottom, var(--space-6) horizontal |
| Bottom sheet pattern | CredentialSheet.tsx | 12px 12px 0 0 radius, zIndex 301, backdrop 300 |
| Credential copy | CredentialSheet.tsx | Same field layout, same validation feedback pattern |
| Step 5 fields | CredentialSheet.tsx | Exact field structure, labels, helper text, link |

---

## 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