BestBuds UI Migration Plan

Overview

The migration should be test-led. First capture the current prototype and website behavior, then extract the design system into modules/design, then replace the existing Compose UI screen by screen.

Source Of Truth

Use this precedence order when code disagrees.

1. targets/appWeb/src/website_main.tsx and targets/appWeb/src/App.css for desktop website theme, palette tokens, typography, sticky prototype presentation, waitlist UX, and palette persistence.
2. prototype/*.jsx for full mobile prototype behavior, route inventory, screen-level interaction patterns, local state, stage language, cards, top bars, tab bars, campaign/chat/event/profile flows.
3. modules/app/src/commonMain/kotlin/ai/bestbuds/app for real app graph topology, repositories, route bindings, analytics, auth, and native behavior.
4. modules/design as the final shared implementation home.

Current State

appWeb

The active appWeb entry points are src/main.tsx, src/App.tsx, src/website_main.tsx, src/App.css, src/prototype-inline.jsx, and src/SurfaceBackground.tsx.

Prototype

The standalone mobile prototype is the richest app reference. It includes onboarding, lobby, campaign, chat, picks, friends, events, create, search, notifications, invite, profile, settings, and home routes.

modules/design

The current design module is being replaced by a scoped atomic design surface. Public screen code should use Theme.Components { Card(...) }, Text, Chip, SearchBar, Event, and TopBar. Legacy wrapper names are not part of the migration path.

modules/app

The real app is graph-driven and should remain that way. The root route is /, onboarding is /onboarding, home is /home, top-level tabs include Chat, Campaign, Discover, and optional Events, with overflow graphs for Friends, Profile, and Dev.

Discrepancies

Testing Plan

Add richer tests under tests/bestbudsWeb before extraction and migration.

Recommended test shape

tests/bestbudsWeb/playwright/
  landing-desktop.spec.ts
  prototype-mobile.spec.ts
  landing-mobile-smoke.spec.ts
  helpers/
    consoleErrors.ts
    localStorage.ts
    waitlistMocks.ts
    iframe.ts

Commands

npm run test:bestbudsWeb:playwright
npm run test:bestbudsWeb:maestro
npm run test:bestbudsWeb

Atomic Design Extraction

Token layer

Create canonical token files in modules/design/src/commonMain/kotlin/ai/bestbuds/design/tokens.

BestBudsPalette.kt
BestBudsTypography.kt
BestBudsSpacing.kt
BestBudsRadii.kt
BestBudsStage.kt
BestBudsElevation.kt

Suggested model: BestBudsPaletteName, BestBudsPalette, BestBudsTokens, BestBudsStage, BestBudsStageStyle, and BestBudsThemeState. Include helpers for color alpha, readable-on color, card radius, and stage accent selection.

Scoped component API

Use a CompositionLocal-backed component set rather than public BB* component names. Screens should enter the design scope and write product-generic component calls such as Card, Text, Chip, SearchBar, Event, and TopBar. The current bridge is Theme.Components { ... }, backed by LocalBestBudsComponentSet and BestBudsComponentSet.

themed {
  Components {
    Card {
      Text("Coffee crawl")
      Chip("Matched")
      PrimaryButton("Open Chat")
    }
  }
}

Do not keep previous public component APIs as migration adapters. New atoms, molecules, and templates can use BestBuds-prefixed file/class names when useful, but their screen-facing component functions should be scoped and unprefixed.

React And Karakum

Use commonMain for portable design data and Compose components. Use jsMain only for React-specific wrappers.

modules/design/src/commonMain/kotlin/ai/bestbuds/design/
  tokens/
  theme/
  components/atoms/
  components/molecules/
  components/templates/

modules/design/src/jsMain/kotlin/ai/bestbuds/design/react/
  BestBudsReactTokens.kt
  ReactAtoms.kt
  ReactPrototypeHost.kt

modules/design/ts/
  package.json
  tsconfig.json
  karakum.config.json
  index.ts
  karakum.ts
  src/

Follow the reaktor-graph convention: TypeScript package in ts/, build: tsc -b, postbuild: karakum --config karakum.config.json, generated externals into ts/import, and Dependeasy web {} includes ts/import in jsMain.

Migration Sequence

1. Baseline tests: expand Playwright desktop and mobile coverage, add fixtures for console errors, localStorage reset, iframe access, and waitlist mocks.
2. Token-first design rewrite: replace current design token base with appWeb/prototype tokens, remove legacy wrappers, and document native font fallback strategy.
3. Shared primitives: build wordmark, avatar, avatar stack, pills, buttons, icon buttons, cards, stage badges/tracks, day/trust rings, top bar, tab bar, event cards, and campaign cards.
4. React/web pieces: move reusable appWeb pieces into modules/design/jsMain and modules/design/ts where useful, including palette serialization and prototype host wrappers.
5. Real app screens: restyle StartScreen, onboarding, campaigns, discover, chats, chat, events, friends, profile, and dev in that order.
6. Clean up: remove old gradient tokens, delete unused duplicate UI, update READMEs, and refresh generated JS only intentionally.

Screen Notes

Acceptance And Risks

Immediate Next Steps

1. Finish replacing direct Material/profile helper usage in ProfileScreen, FriendProfileScreen, GroupProfileScreen, DevScreen, event scaffolds, chat views, and remaining home shells.
2. Move generic loading, profile placeholder, editable field, info row, avatar, and empty/error states behind the scoped component API instead of public helper functions.
3. Keep feature behavior stable while changing presentation: auth, graph routes, chat actions, analytics, work tasks, and profile navigation should keep the same Maestro-observable semantics.
4. Run the final validation gate after app migration: npm run maestro:android, npm run maestro:ios, npm run test:bestbudsWeb, plus target builds for Android, Darwin, Desktop, and app web.