Make onboarding honor appearance previews (codex)

[numnx]

🧩 Task: Make onboarding honor appearance previews

Automated task PR opened by Code UX for T02.

📋 Summary

Sprint: Sprint 171 · Onboarding light mode · Task: T02

Fix onboarding appearance so light mode and background choices render immediately inside the onboarding experience, with shared preview behavior, regression coverage, and updated docs.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 09:43:19 UTC
Finished	2026-07-07 09:56:04 UTC
Duration	12m 45s

📊 Token Usage

Metric	Value
Input tokens	167,579
Cached input tokens	5,151,104
Output tokens	23,600
Total tokens	5,342,283
Invocations	1
Tool calls	76
Active time	12m 14s

Included usage estimate (subscription/local login): $4.12

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Make the active onboarding experience respond immediately to Appearance step choices, including Light/Dark/System theme and background mode/static color changes.

## Scope
- Edit `dashboard/src/v2/components/onboarding/OnboardingExperience.tsx`
- Edit `dashboard/src/v2/components/onboarding/OnboardingAppearanceStep.tsx`
- Consume `dashboard/src/v2/lib/appearance-preview.ts` from T01
- Relevant symbols: `updateAppearance`, `DeepOceanBackground`, `OnboardingAppearanceStep`, `applyAndClose`, `markOnboardingCompleted`, `settings.defaults.appearance`

## Implementation Requirements
1. Replace the inline `active.id === "appearance"` JSX in `OnboardingExperience.tsx` with the dedicated `OnboardingAppearanceStep` component so there is one active Appearance step implementation.
2. In `updateAppearance`, merge the draft appearance into `settings.defaults.appearance`, call `applyAppearanceSettings(nextAppearance)`, and publish the same `nextAppearance` through the shared preview helper from T01 so `dashboard/src/main.tsx` updates `BackgroundManager` while onboarding remains open.
3. Publish the loaded draft appearance after `fetchSystemSettings()` succeeds while onboarding is open, and clear the preview when onboarding closes, is canceled, completes, or unmounts.
4. Remove hard-coded dark-only onboarding chrome: stop forcing `DeepOceanBackground forceDark`, derive the background dark state from the draft theme/system preference or root `dark` class, and add light-mode classes for the backdrop, shell overlay, sidebar, step navigation, footer, and decorative gradients so Light mode does not retain dark-only panels.
5. Update `OnboardingAppearanceStep.tsx` to expose the needed background controls for onboarding preview: theme, navigation mode, reduced motion, background mode, static color when `STATIC`, and Electron zoom when supported; keep removed advanced controls such as animation style, pattern overlay, and custom image out of onboarding.
6. Use precise TypeScript types instead of `as any` for appearance updates, matching `SystemSettings["defaults"]["appearance"]` unions.

## Constraints
- Do not change onboarding persistence endpoint behavior; final save must still use `saveSystemSettings(settings)` and completion state must still use `/api/user/onboarding/*` through `useOnboardingState`.
- Do not introduce new UI libraries or global state managers.
- Do not re-add advanced Settings-only controls: animation style, pattern overlay, and custom background image remain Settings-page features.
- Preserve existing onboarding provider, Git, Jira, defaults, automation, intro, and dashboard tour behavior.
- Respect reduced motion and avoid introducing continuous decorative animation beyond existing background components.

## Verification
- Run `pnpm exec vitest run tests/dashboard/onboarding/onboarding-flow.test.tsx` after T03 coverage is present or update the focused tests in the same branch if running before T03.
- Run `pnpm run typecheck:dashboard`.
- Run `pnpm run dev`, open `http://localhost:4444`, reset/reopen onboarding from Settings -> General -> Onboarding, switch Appearance theme to Light and Dark, switch Background Mode to Static, and confirm the onboarding shell/background updates immediately without saving.

🌿 Branch Info

Base: feature/CODUX-171-onboarding-light-mode
Head: task/feature-codux-171-onboarding-light-mode-t02-codex-mrago9te

---

🤖 Generated by Code UX