[DRAFT][PLAN] Scorecard: add subtitle prop #225

[DRAFT][PLAN] Scorecard: add subtitle prop

Plan for parent issue #223.

Reference files mapped

• packages/ui/src/components/Scorecard.tsx — component to modify. Already colocates ScorecardLabelText, ScorecardTrendText, ScorecardAffixText as private createComponent(TamaguiText, ...) styled sub-components — subtitle follows the identical pattern.
• examples/storybook/src/stories/design-system/Scorecard.stories.tsx — story to modify.
• tests/design-system/smoke.spec.ts — existing 'Scorecard/Default story renders...' test; design-system components use this convention (not tests/widgets/).
• packages/ui/src/createComponent.ts — confirms the styled-component wrapper pattern (read-only reference).
• packages/ui/src/index.ts — already exports Scorecard/ScorecardProps; no edit needed since subtitle extends the existing exported type.

No new @GoodDollar packages needed — reuses tamagui's Text/styled, ../createComponent, and existing constants (SECONDARY_SIZE_PX, VALUE_TO_TREND_GAP_PX) already in Scorecard.tsx. No new dependencies.

New component mapping: ScorecardSubtitleText, colocated inside Scorecard.tsx (not a new file, not a new package) — it's a private sub-component of Scorecard's own render tree with no reuse elsewhere, matching the precedent of ScorecardLabelText/ScorecardTrendText/ScorecardAffixText already colocated there. Correctly belongs in packages/ui, not a widget-specific package, since Scorecard itself is already a shared design-system primitive (consumed cross-widget, e.g. the AI-Credits-analytics PR #179).

Required states, flows, and behaviors

• With trend + with subtitle: Label → Value row → Trend row → Subtitle
• With trend, no subtitle: unchanged, byte-for-byte
• No trend + with subtitle: Label → Value row → Subtitle
• No trend, no subtitle: unchanged (current layout), byte-for-byte
• All 3 sizes (sm/md/lg) and both variants (bare/card)
• Cross-platform: React web, React Native, Web Components — guaranteed by the existing TamaguiText/createComponent pattern, no platform branching needed

Execution plan

1. Scorecard.tsx
   • Add subtitle?: string to ScorecardProps, after trendLabel.
   • Add ScorecardSubtitleText via createComponent(TamaguiText, ...): color: '$placeholderColor', fontWeight: '400', textAlign: 'center', variants.size → SECONDARY_SIZE_PX[size], defaultVariants: { size: 'md' } (same shape as ScorecardLabelText).
   • Destructure subtitle in ScorecardContent.
   • Render {subtitle ? <ScorecardSubtitleText size={size} marginTop={VALUE_TO_TREND_GAP_PX}>{subtitle}</ScorecardSubtitleText> : null} as the last child in ScorecardFrame, after the existing trend block — one conditional naturally satisfies both render-position rules (after trend row when present, after value row when absent).
2. Scorecard.stories.tsx
   • Add subtitle to argTypes (control: 'text').
   • Add subtitle to one MOCK_ROWS entry with a trend and one without, in the existing Default story (no new story block needed to satisfy "with and without trend").
   • Add subtitle: '' to Controllable args.
3. tests/design-system/smoke.spec.ts
   • Extend the existing Scorecard test to assert subtitle visibility on the updated rows; re-capture story-scorecard-default.png.
4. Manual QA: scoped typecheck/lint, visual check across sizes/variants/trend combos, run smoke spec, commit refreshed baseline.

Acceptance criteria

• subtitle prop accepted, renders below trend row (or value row if no trend)
• No subtitle → no extra whitespace, layout unchanged
• Subtitle uses $placeholderColor, SECONDARY_SIZE_PX, fontWeight: '400', centered
• Gap above subtitle = VALUE_TO_TREND_GAP_PX
• Works in all 3 sizes and both variants
• Works with and without trend
• Storybook story demonstrates subtitle with and without trend
• ScorecardSubtitleText via createComponent, no new dependencies
• tests/design-system/smoke.spec.ts updated with subtitle assertions, baseline screenshot refreshed and committed

Human-reviewer checklist

• Render-position rule verified visually for all size × variant × trend combos
• No-subtitle layout is pixel-identical to pre-change (diff the baseline screenshot)
• Only Scorecard.tsx, Scorecard.stories.tsx, and tests/design-system/smoke.spec.ts (+ its baseline PNG) changed — no edits to Card.ts, index.ts, theme files, or other components
• No new dependencies in package.json/lockfile