Problem

Onboarding uses custom modal/focus behavior, does not reliably restore focus or make the background inert, and only partially respects reduced motion. It can advance based on object existence instead of runtime readiness and mutates some live defaults while the user is still exploring. The final step lacks Back, and dismissal is difficult to resume.

Some approval/privacy copy is more absolute than actual conditional behavior.

Relevant code

• apps/desktop/src/ui/onboarding/DesktopOnboarding.tsx
• apps/desktop/src/app/store.actions/onboarding.ts
• Provider/workspace readiness state
• Developer/Diagnostics re-entry path

Implementation outline

• Move onboarding to the shared accessible Dialog primitive.
• Trap focus correctly, mark background inert, focus each new step intentionally, and restore prior focus.
• Honor reduced motion for every CSS and Framer transition.
• Stage choices locally and commit only when the user finishes.
• Validate provider/model/workspace/runtime readiness before completion.
• Add Back on the final step and preserve choices through navigation.
• Provide a resumable setup checklist/banner after dismissal.
• Make setup re-entry visible outside Diagnostics.
• Replace absolute approval/privacy statements with accurate conditional language.
• Explain that prompts are sent to the selected model provider.

Acceptance criteria

• Focus stays within onboarding and returns to the launcher.
• Background controls are inert to pointer and assistive technology.
• Reduced-motion mode removes nonessential transitions.
• Closing before Finish does not partially mutate live configuration.
• Unready runtime/provider states block completion with a direct repair action.
• Every step, including the final step, supports appropriate Back navigation.
• Dismissed setup can be resumed from a visible product surface.
• Security/privacy copy matches actual behavior.

Required tests

• Keyboard focus loop, step focus, and restoration.
• Background inertness and Axe checks for every step.
• Reduced-motion snapshots.
• Forward/back navigation with staged settings.
• Close-before-finish state assertion.
• Not-ready and successful completion paths.

Additional scope from the July UI audit

• Reduce the primary onboarding journey to roughly three clear beats that end in a usable live chat; move optional configuration into the resumable checklist.
• Escape/close must never strand the user in a half-configured app. If setup is incomplete, keep an obvious persistent Finish setup action.
• Add starter prompts to the first usable New Chat state rather than limiting examples to onboarding.