[PLAN] Governance homepage components

[L03TJ3]

[PLAN] Governance homepage components

Parent issue: #46

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: [Feature]: Governance homepage components #46
• Parent UI implementation reference section: [Feature]: Governance homepage components #46 (comment)
• Parent user flows, states and behaviours section: [Feature]: Governance homepage components #46 (comment)

Draft smart-contract reference (reference only, not yet a strict implementation contract):

• GoodProtocol PR #299: Implement GoodDaoHouses MVP smart contract build GoodProtocol#299
• The GoodDaoHouses / FlowSplitter contract work is still draft and may change. Use it only to understand likely future data shape and naming, not as a stable API that the component plan should tightly couple to yet.

Required states, flows, and behaviors

• This issue is planning-only for standalone presentational governance homepage components.
• Do not wire runtime smart-contract reads, subgraph data, or wallet interactions in this pass.
• Use the parent issue for full component screenshots, design direction, and broader UX scope.
• Prefer existing @goodwidget/ui primitives for shared layout, cards, typography, spacing, buttons, icons, tokens, and theming.
• Keep governance-specific composites local to the new widget package unless they are clearly reusable outside governance.
• Storybook coverage must include mocked values for every component variant and screenshot-ready states for Playwright smoke coverage.
• All components must support light theme, dark theme, and mobile-friendly layouts.

Component expectations to preserve from parent issue

Impact card

• Includes a title, two side-by-side metric boxes, description copy, and CTA.
• Each metric box should support either a static token amount or a running stream amount.
• Required states include CTA present/disabled, long title/description handling, light theme, dark theme, and mobile stacking.
• Expected future prop shape should still allow title, metrics, description, CTA label, and CTA handler semantics.

Balance card

• Includes header row with icon/title, amount row, and metadata row.
• Amount may represent token value or raw count.
• Metadata may represent growth/trend or a time-window indicator.
• Required states include token amount vs raw count, growth metadata vs time-window metadata, truncation handling, light theme, dark theme, and compact/mobile layout.

Alignment voting proposal card

• Includes category/status pill, navigation affordance, multi-line title, vote summary label, and ranked options list.
• Ranked options should support label, percentage, and progress bar.
• Required states include default, long title, multiple ranked options, capped visible options, light theme, dark theme, and tappable navigation affordance.

Optimistic voting proposal card

• Includes category/status pill, navigation affordance, multi-line title, quorum/progress summary, stacked quorum bar, voter preview, and vote breakdown legend.
• Required states include high quorum, low quorum, mixed vote distribution, avatar fallbacks, remaining-count pill, light theme, dark theme, and tappable navigation affordance.

Funding distribution chart

• Includes donut chart, center total amount, project allocation segments, and legend.
• Total amount should support a streaming amount display.
• Required states include populated distribution, zero/empty distribution, long project labels, light theme, dark theme, and mobile-safe legend layout.
• Interaction should allow chart segment or legend item navigation in mocked/demo form.

Execution plan

1. Map the implementation against repository boundaries in ARCHITECTURE.md, keeping generic theming and primitives in packages/ui and governance-specific composites in a new widget package.
2. Use these GoodWidget references while planning and implementing:
   • packages/ui/src/components/Card.ts
   • packages/ui/src/components/TokenAmount.tsx
   • packages/ui/src/components/Icon.tsx
   • packages/ui/src/createComponent.ts
   • packages/citizen-claim-widget/src/CitizenClaimWidget.tsx
   • packages/claim-widget-theme-demo/src/ClaimWidget.tsx
   • examples/storybook/src/stories/citizen-claim-widget/CitizenClaimWidget.stories.tsx
   • examples/storybook/src/stories/design-system/ThemePlayground.stories.tsx
   • tests/widgets/citizen-claim-widget/states.spec.ts
   • docs/demo-environment.md
3. Use these GoodProtocol references from PR #299 only as draft context for likely future data shape, not as a stable implementation contract for this issue:
   • contracts/governance/GoodDaoHouses.sol
   • contracts/governance/IFlowSplitter.sol
   • test/governance/GoodDaoHouses.test.ts
4. Normalize future component inputs around domain concepts that are likely to survive contract iteration, such as member status, minimum stake, member metadata, vote timing, recipients, weighted vote units, and funding distribution metadata.
5. Avoid overfitting presentational props to the current draft smart-contract naming if doing so would make the components harder to evolve when the contract changes.
6. Create the new governance package with exported standalone composites for ImpactCard, BalanceCard, AlignmentVotingProposalCard, OptimisticVotingProposalCard, and FundingDistributionChart, plus any private governance-only subcomponents needed to compose them.
7. Prefer existing UI primitives for layout and visuals; keep likely single-use pieces such as proposal status pills, ranked-option rows, quorum segment bars, voter preview groups, and project-allocation legends local to packages/governance-widget for this issue.
8. Only promote a new primitive to packages/ui if it becomes clearly reusable across multiple widgets during implementation; otherwise keep scope local to governance.
9. Add Storybook stories under examples/storybook/src/stories/governance-widget/ covering light/dark variants and all required mock states for each component.
10. Add Playwright smoke coverage under tests/widgets/governance-widget/ with screenshot captures for each required component state and store committable evidence in tests/widgets/governance-widget/test-results/.
11. Keep the output as skeleton/presentational components only, with prop contracts ready for a later adapter/integration pass.

human-reviewer checklist

• Planned sub-issue title and scope match parent issue [Feature]: Governance homepage components #46.
• Parent issue [Feature]: Governance homepage components #46 is clearly linked as the source of truth for screenshots, UX scope, and required component behavior.
• GoodProtocol PR #299 is treated as draft reference material only and not as a stable contract/API dependency for this planning issue.
• Package-boundary decisions follow ARCHITECTURE.md and keep governance-specific UI out of packages/ui unless clearly reusable.
• Storybook and Playwright deliverables follow docs/demo-environment.md folder conventions.
• Proposed component states cover light theme, dark theme, mobile behavior, and empty/error/long-content cases where applicable.
• The plan is execution-ready, but still clearly marked [PLAN] and not an implementation task yet.