Cover onboarding appearance regressions (codex)

[numnx]

🧩 Task: Cover onboarding appearance regressions

Automated task PR opened by Code UX for T03.

📋 Summary

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

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 10:09:37 UTC
Finished	2026-07-07 10:13:38 UTC
Duration	4m 1s

📊 Token Usage

Metric	Value
Input tokens	61,845
Cached input tokens	749,184
Output tokens	7,062
Total tokens	818,091
Invocations	1
Tool calls	31
Active time	3m 22s

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

✅ 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
Add regression coverage for the Jira-reported onboarding appearance behavior so dark-mode elements do not leak into Light mode and unsaved background changes preview immediately.

## Scope
- Edit `tests/dashboard/onboarding/onboarding-flow.test.tsx`
- Optionally adjust the existing `DeepOceanBackground` mock in that file to expose received props
- Verify `dashboard/src/v2/lib/__tests__/apply-appearance.test.ts` still covers root theme behavior
- Relevant assertions: `document.documentElement.classList`, `codeux:appearance-preview` event detail, Appearance step controls, mocked background `forceDark`

## Implementation Requirements
1. Add or update an onboarding test that loads settings with `defaults.appearance.theme: "DARK"`, navigates to the Appearance step, clicks the Light theme choice, and asserts the document root no longer has `dark` plus the onboarding background mock receives a non-dark state.
2. Add a test that switches Background Mode to `STATIC`, optionally changes `Static Color`, and asserts a `codeux:appearance-preview` event is emitted with `appearance.backgroundMode === "STATIC"` and the expected `staticBackgroundColor`.
3. Add cleanup coverage that closing or unmounting onboarding emits a preview with `appearance: null` so the root dashboard background does not stay stuck on onboarding's unsaved draft.
4. Update stale assertions from the current appearance test: Background Mode is now intentionally present in onboarding, while Animation Style, Pattern Overlay, Custom Background Image, and Upload Image remain absent.
5. Keep mocks deterministic: mock `fetchSystemSettings`/`saveSystemSettings` through `dashboard/src/v2/lib/settings-api.js`, mock `/api/user/onboarding` and `/api/onboarding/readiness`, and avoid real GSAP timing.

## Constraints
- Do not assert brittle Tailwind class strings except where needed to identify a specific regression surface; prefer semantic controls, events, root classes, and test ids from mocks.
- Do not require WebGL, real Three.js rendering, Docker, or a running dashboard server in unit tests.
- Preserve existing onboarding tests for readiness, Git mode, defaults, and introduction content.
- Keep the tests compatible with the existing jsdom Vitest environment in this file.

## Verification
- Run `pnpm exec vitest run tests/dashboard/onboarding/onboarding-flow.test.tsx dashboard/src/v2/lib/__tests__/apply-appearance.test.ts`.
- Run `pnpm run test:dashboard`.
- Success means the tests fail on the old hard-dark onboarding behavior and pass with immediate theme/background preview plus cleanup.

🌿 Branch Info

Base: feature/CODUX-171-onboarding-light-mode
Head: task/feature-codux-171-onboarding-light-mode-t03-codex-mrahm48k

---

🤖 Generated by Code UX