V2 UI Implementation TODO

Status: Awaiting wireframes Tier: S (Full GTD) Branch: feat/v2-fact-engine

Phase 1: Design Token Extraction

Extract colors, typography, and spacing from Figma wireframes into code tokens.

  • Define warm neutral color palette (warm grays + warm accent) in packages/shared/styles/tokens.css
  • Map palette to Tailwind v4 theme variables in packages/shared/styles/theme.css
  • Confirm typography scale (Red Hat Text primary, Sometype Mono code/data)
  • Define spacing scale (consistent gaps for sections, cards, page margins)
  • Define border/radius tokens (border-first hierarchy, no ambient shadows)
  • Define functional status colors (red/amber/green only)
  • Verify contrast ratios meet WCAG AA for all text/background combos

Files touched:

  • packages/shared/styles/tokens.css
  • packages/shared/styles/theme.css

Phase 2: Navigation Shell

Build the top bar navigation component that wraps every authenticated page.

  • Create TopNav component (logo, nav items, auth state)
  • Implement desktop layout (1280px+ primary target)
  • Wire up active route highlighting
  • Add user menu / avatar dropdown
  • Integrate into apps/web/app/feed/layout.tsx (or app-level layout)
  • Ensure focus states and keyboard navigation (reuse packages/shared/styles/focus.css)

Files touched:

  • packages/ui/src/components/top-nav.tsx (new)
  • apps/web/app/feed/layout.tsx (update)
  • apps/web/app/layout.tsx (possibly update)

Phase 3: Fact Card Component

Redesign the core card component to match Figma editorial card style with feature images.

  • Design card layout: image, title, summary, metadata, topic badge
  • Implement default state
  • Implement hover state (border-first, no shadow)
  • Implement "Insight Reveal" animation (upward fade)
  • Ensure card uses only design tokens (no hardcoded colors/spacing)
  • Add loading skeleton variant
  • Add empty state variant

Files touched:

  • apps/web/app/feed/ (existing FactCard — redesign)
  • Possibly extract to packages/ui/src/components/fact-card.tsx if shared

Phase 4: Feed Page

Implement the card grid layout with filtering and infinite scroll.

  • Build responsive card grid (desktop-first, then mobile adaptation)
  • Integrate topic/category filtering
  • Preserve infinite scroll behavior (existing CardFeed)
  • Implement empty state ("No facts yet")
  • Implement loading state (skeleton grid)
  • Apply spacing patterns from design tokens

Files touched:

  • apps/web/app/feed/page.tsx (restyle)
  • apps/web/app/feed/layout.tsx (restyle)

Phase 5: Card Detail Page

Build the deep-dive view for a single fact, including soft paywall boundary.

  • Implement card detail layout (hero image, full content, sources)
  • Implement paywall boundary (teaser visible, gentle upgrade prompt)
  • Add source attribution display
  • Add related facts section
  • Implement back navigation
  • Responsive check at 375px, 768px, 1280px, 1440px

Files touched:

  • apps/web/app/card/[slug]/page.tsx (new or update)

Phase 6: Public Homepage

Implement the marketing landing page for apps/public.

  • Redesign SiteNav component (logo, nav items, CTA)
  • Build hero section
  • Build feature highlights / value proposition sections
  • Build public fact card preview (limited, soft paywall teaser)
  • Build footer
  • Responsive adaptation (desktop-first → mobile)

Files touched:

  • apps/public/app/page.tsx (redesign)
  • apps/public/app/_components/site-nav.tsx (redesign)
  • apps/public/app/_components/ (new components as needed)

Phase 7: Documentation

Capture implemented design specs for future reference.

  • Document color palette with usage guidelines
  • Document typography scale
  • Document spacing system
  • Document component catalog (card, nav, buttons, badges)
  • Document animation patterns (Insight Reveal, transitions)
  • Document paywall boundary pattern

Output:

  • docs/design-system/ files (tokens, components, patterns)

Verification Checklist (Per Phase)

Run after completing each phase:

  • Visual comparison against Figma wireframe
  • Responsive check: 375px, 768px, 1280px, 1440px
  • Component reuse audit (no duplicated styles)
  • Token compliance (all colors/spacing use CSS variables)
  • Accessibility: focus states, contrast ratios, touch targets
  • bun run typecheck passes
  • bun run lint passes

Design Decisions (Locked)

These are settled and should not be revisited during implementation:

DecisionChoice
NavigationTop bar
Color paletteWarm neutrals (warm grays + warm accent)
ThemeLight mode first
ViewportDesktop-first
Card styleEditorial with feature images
PaywallSoft (teaser → gentle upgrade prompt)
HierarchyBorder-first (no ambient shadows)
Color usageFunctional only (status = red/amber/green)
Signature animation"Insight Reveal" (upward fade)
FontsRed Hat Text (primary) + Sometype Mono (code/data)
DensityBalanced — scan first, read second

Existing Components to Reuse

ComponentLocationStatus
Button (8 sizes, 7 variants)packages/ui/src/components/button.tsxReady
Badge (5 variants)packages/ui/src/components/badge.tsxReady
Dialog/Modalpackages/ui/src/components/dialog.tsxReady
Tabspackages/ui/src/components/tabs.tsxReady
Input, Select, Checkboxpackages/ui/src/components/Ready
Toast (Sonner)packages/ui/src/components/sonner.tsxReady
Focus ringspackages/shared/styles/focus.cssReady
Accessibility layerpackages/shared/styles/accessibility.cssReady
Motion systempackages/shared/styles/motion.cssReady

Wireframe Handoff

Waiting for Figma wireframes. Accepted formats:

  1. Figma URL — share file/frame link
  2. Screenshots — paste images directly
  3. Page by page — iterative handoff