[PLAN] Governance UI onboarding components

[L03TJ3]

[PLAN] Governance UI onboarding components

Full scope, design references, and UX details live in the parent issue and should be treated as the source of truth for this planning issue.

Parent issue: #55

Required states, flows, and behaviors

• Build a 5-step governance onboarding UI flow for the existing governance widget and keep it UI-only for now: no transaction wiring, no smart-contract execution, and no production data integration yet.
• Reuse the page sequence, screenshots, and field expectations from parent issue [Feature]: Governance UI Onboarding components #55 as the source-of-truth breakdown for this planning issue.
• Keep a horizontal page stepper visible across the full flow and clearly mark the active step on every page.
• All onboarding screens and shared flow primitives must cleanly support both light and dark theme handling, following the existing governance/dashboard styling direction and shared design-token usage.
• Include Storybook coverage and Playwright smoke coverage for the onboarding flow states, following the repository’s existing widget story/test conventions.

Per-page breakdown

Page 1 — Welcome + identity verification

• Render the welcome/onboarding introduction state shown in parent issue [Feature]: Governance UI Onboarding components #55.
• Support both identity states:
  • verified state with positive confirmation styling and enabled proceed CTA
  • unverified state with warning styling, verify CTA, and disabled proceed CTA
• Keep the page wizard header/stepper visible on this screen.
• Support light/dark theme parity for the main card, status messaging, and CTA hierarchy.

Page 2 — House selection

• Render the house selection view from parent issue [Feature]: Governance UI Onboarding components #55.
• Support both selectable paths and persist the selected house into later steps:
  • House of Citizenship
  • House of Alignment
• Support selected, unselected, hover/press, and disabled presentation states as needed for the card/button treatment.
• Keep the stepper visible and preserve theme-correct surfaces, borders, and selection affordances in light/dark mode.

Page 3 — House-specific profile flow

• Render the profile form screen variant based on the house selected on page 2, matching the parent issue screenshots and flow split.
• Support both step-3 variants:
  • House of Citizenship profile fields shaped around name and socialLinks
  • House of Alignment profile fields shaped around name, projectWebpage, missionStatement, and distributionStrategy
• Display the required G$ stake amount inside the profile flow and show the warning copy about wallet balance and locked stake duration.
• Support empty, editing, validation/error, and ready-to-continue states for the form experience.
• Preserve readable field, helper, error, and emphasis styling across light and dark themes.

Page 4 — Stake transaction progress tracker

• Reuse the transaction-stepper pattern for the stake journey screen shown in parent issue [Feature]: Governance UI Onboarding components #55.
• Support the main transaction states the onboarding flow must communicate:
  • pending / waiting to start
  • active / in progress
  • completed / confirmed
  • failed / retry-needed
• Keep the screen presentational only for now, but shape it so future runtime integration can drive the step statuses.
• Preserve theme-aware colors and status emphasis so progress, success, warning, and failure remain clear in both light and dark modes.

Page 5 — Success state

• Render the final success screen/modal/card from parent issue [Feature]: Governance UI Onboarding components #55.
• Support one or more CTA/redirect actions.
• Support copy/layout variants needed for a successful onboarding completion state.
• Ensure the final celebratory/success styling remains visually clean and readable in both light and dark themes.

Execution plan

1. Map the reference surface before implementation:
   • Parent scope: [Feature]: Governance UI Onboarding components #55
   • GoodWidget governance styling reference: PR feat(governance-widget): finalize governance dashboard components (#50) #54 files under packages/governance-widget/src/*, examples/storybook/src/stories/governance-widget/GovernanceWidget.stories.tsx, and tests/widgets/governance-widget/states.spec.ts
   • Transaction stepper reference: PR Create staking migration widget with Fuse approval flow, unified migration journey states, coverage, and demo app integration #43 packages/ui/src/components/Stepper.tsx, examples/storybook/src/stories/design-system/Stepper.stories.tsx, and the related widget smoke-test patterns under tests/widgets/staking-migration-widget/
   • Page wizard reference: https://gist.github.com/L03TJ3/b8dfb1d6d2da91a4f82293bcd632fb06
   • Contract input-shape reference: Implement GoodDaoHouses MVP smart contract build GoodProtocol#299, especially contracts/governance/GoodDaoHouses.sol
2. Extend the reusable design-system layer in packages/ui with the generic flow primitives required by multiple widgets:
   • add a reusable PageWizard shell/provider pattern for horizontal step flows
   • add the duplicated transaction Stepper pattern in packages/ui if the current exported stepper still does not match the onboarding reference exactly
   • keep only broadly reusable layout/progress primitives in packages/ui
3. Keep onboarding-specific screens and composition inside packages/governance-widget:
   • welcome/identity card
   • house selection card(s)
   • house-specific profile form screens
   • onboarding transaction-progress screen
   • success card/modal content
4. Define clear widget state contracts for the onboarding flow so stories and future integration can drive:
   • selected house
   • identity status
   • form draft values
   • displayed stake amount
   • transaction progress state
   • final CTA configuration
5. Add Storybook stories under examples/storybook/src/stories/governance-widget/ that cover the main onboarding screens and their important state variants.
6. Add Playwright smoke coverage under tests/widgets/governance-widget/ with screenshots for each major onboarding step/state.
7. Reuse existing @goodwidget/ui, @goodwidget/core, and other existing @GoodDollar workspace packages instead of introducing parallel abstractions.
8. Leave contract/network integration for a follow-up execution issue once the UI skeleton is approved.

human-reviewer checklist

• Reusable vs widget-specific component ownership is correct.
• The onboarding flow still matches the parent issue screenshots and sequence.
• The mapped field shapes align with GoodProtocol#299.
• The plan is still UI-only and does not expand into contract wiring.
• Storybook and Playwright coverage expectations are explicit.
• Light/dark theme handling is explicitly covered across the full flow.
• The issue is ready to be reviewed before execution starts.