Work Order: Storybook Component Parity Across All Divisions

Status: Planned (Paused for Documentation Migration)
Priority: High
Branch: feat/component-layering (resume on this branch)
Owner: TBD
Created: October 16, 2025
Target Completion: TBD (After feat/astro-starlight-docs completion)
Estimated Duration: 3-5 sessions

---

Objective

Ensure every app division in the monorepo has at least:

• ✅ One web component documented in Storybook
• ✅ One mobile component documented in Storybook

This establishes a baseline for component library maturity, ensures Storybook configuration is correct for all divisions, and provides templates for future component additions.

---

Business Context

Our monorepo contains multiple app divisions (Pride City, Stay Match, Guestroom, etc.), each with their own design system and component libraries. Currently, component documentation in Storybook is inconsistent—some divisions have many components, others have none.

Goals:

1. Standardization: Every division follows the same Storybook documentation pattern
2. Discoverability: Developers can find division-specific components easily
3. Quality Baseline: Minimum documentation standard for all UI packages
4. Template Creation: First components serve as templates for adding more

---

App Divisions & Component Packages

Division List (from workspace structure)

1. Alt Finder (apps/altFinder/)

   • UI Package: packages/ui-altfinder/ (or similar)
   • Status: TBD

2. Bonjour Services (apps/bonjour_services/)

   • UI Package: TBD
   • Status: TBD

3. Greenhost (apps/greenhost/)

   • UI Package: TBD
   • Status: TBD

4. Guestroom (apps/guestroom/)

   • UI Package: TBD
   • Status: TBD

5. Homestay (apps/homestay/)

   • UI Package: TBD
   • Status: TBD

6. Hostguest (apps/hostguest/)

   • UI Package: TBD
   • Status: TBD

7. Pride City (apps/pride_city/)

   • UI Package: packages/ui-pride-city/ ✅
   • Web: LeafletMap ✅ (17 stories created)
   • Mobile: TBD ❌
   • Status: 50% complete

8. Room LGBT (apps/room_lgbt/)

   • UI Package: TBD
   • Status: TBD

9. Roommate (apps/roommate/)

   • UI Package: TBD
   • Status: TBD

10. Stay Match (apps/stay_match/)

    • UI Package: TBD
    • Status: TBD

---

Phase 1: Discovery & Inventory

Objective: Identify all UI packages and existing components

Tasks

• 1.1 - List all packages/ui-* directories in monorepo

  ls -la packages/ | grep "ui-"

• 1.2 - For each UI package, check for:

  • src/components/ directory
  • Existing component files
  • Package.json configuration
  • TypeScript/React setup

• 1.3 - Scan existing Storybook stories

  find packages/storybook/stories -name "*.stories.tsx" | sort

• 1.4 - Create inventory spreadsheet/table:

  Division	UI Package	Existing Components	Web Story	Mobile Story	Notes
  Pride City	ui-pride-city	LeafletMap, …	✅	❌	Need mobile
  …	…	…	…	…	…

• 1.5 - Identify divisions with NO UI package yet

  • Plan: Create packages/ui-{division}/ following established pattern

Deliverables

• Complete inventory document (Markdown table)
• Gap analysis: which divisions need packages/components
• Priority ranking based on app importance

---

Phase 2: Package Scaffolding

Objective: Create missing UI packages following monorepo conventions

Tasks

• 2.1 - For divisions without UI packages, create:

  packages/ui-{division}/
  ├── src/
  │   ├── components/
  │   ├── index.ts
  ├── package.json
  ├── tsconfig.json
  ├── README.md

• 2.2 - Configure each package.json:

  • Name: @cloudalt-frontend/ui-{division}
  • Dependencies: React, TypeScript, etc.
  • Exports: ./src/index.ts
  • Peer dependencies: React version consistency

• 2.3 - Add to workspace root package.json or Nx configuration

• 2.4 - Verify packages can be imported:

  import { Component } from '@cloudalt-frontend/ui-{division}';

Deliverables

• All divisions have packages/ui-{division}/ structure
• All packages buildable and importable
• Documentation on package naming/structure conventions

---

Phase 3: Web Component Selection & Creation

Objective: Add or document one web component per division

Component Selection Criteria

Choose components that are:

1. Representative - Typical of the division’s UI patterns
2. Reusable - Used in multiple places or screens
3. Simple - Not overly complex (button, card, input, etc.)
4. Visual - Demonstrates styling/branding

Suggested Component Types by Division

Division	Suggested Web Component	Rationale
Pride City	LeafletMap ✅	Already created, map-based apps
Stay Match	SearchCard	Core to booking/search flow
Guestroom	RoomCard	Primary content type
Homestay	ListingCard	Primary content type
Room LGBT	ProfileCard	Community-focused UI
Roommate	MatchCard	Core matching feature
Alt Finder	AlternativeCard	Search result display
Bonjour Services	ServiceCard	Service listing display
Greenhost	PropertyCard	Eco-friendly property display
Hostguest	BookingCard	Reservation display

Tasks

For each division:

• 3.1 - Create component file:

  packages/ui-{division}/src/components/{ComponentName}/{ComponentName}.tsx

• 3.2 - Implement component with:

  • TypeScript props interface
  • JSDoc comments
  • Default export
  • Sensible prop defaults

• 3.3 - Export from package index:

  export { ComponentName } from './components/ComponentName/ComponentName';

• 3.4 - Create Storybook story:

  packages/storybook/stories/{ComponentName}.stories.tsx

• 3.5 - Add multiple story variants:

  • Default
  • With custom props
  • Edge cases (long text, no data, etc.)
  • Interactive controls

• 3.6 - Test in Storybook locally:

  yarn storybook

• 3.7 - Build Storybook to verify no errors:

  yarn build-storybook

Deliverables (per division)

• One working web component
• Component exported from UI package
• Storybook story with 3+ variants
• Documentation in story description
• Screenshots for reference

---

Phase 4: Mobile Component Selection & Creation

Objective: Add or document one React Native component per division

Component Selection Criteria

Choose components that are:

1. Mobile-appropriate - Takes advantage of mobile patterns (gestures, etc.)
2. Cross-platform - Works on iOS and Android
3. Reusable - Common pattern in the app
4. Testable - Can be demonstrated in Storybook or React Native Web

Suggested Mobile Component Types

Division	Suggested Mobile Component	Rationale
Pride City	LocationPicker	Map interaction
Stay Match	DateRangePicker	Booking dates
Guestroom	BottomSheet	Mobile modal pattern
Homestay	ImageGallery	Property photos
Room LGBT	ProfileAvatar	User identity
Roommate	SwipeCard	Match swiping
Alt Finder	FilterDrawer	Search refinement
Bonjour Services	ServiceListItem	Touch-friendly list
Greenhost	RatingStars	User reviews
Hostguest	NotificationBadge	Alert indicator

Tasks

For each division:

• 4.1 - Create mobile component file:

  packages/ui-{division}/src/components/{ComponentName}/{ComponentName}.mobile.tsx

• 4.2 - Implement with React Native:

  • Use React Native components (View, Text, TouchableOpacity, etc.)
  • TypeScript props interface
  • Platform-specific code if needed
  • Accessibility props

• 4.3 - Export from package index

• 4.4 - Create Storybook story:

  • Use @storybook/react-native if needed
  • Or use React Native Web for web-based Storybook

• 4.5 - Test rendering:

  • In Storybook if using RN Web
  • Or document with screenshots from simulator

• 4.6 - Add usage documentation

Deliverables (per division)

• One working mobile component
• Component exported from UI package
• Storybook story or screenshot documentation
• Usage guide with code example

---

Phase 5: Documentation & Standards

Objective: Document the component creation pattern for future additions

Tasks

• 5.1 - Create component template files:

  • Web component boilerplate
  • Mobile component boilerplate
  • Storybook story boilerplate

• 5.2 - Write component authoring guide:

  • File structure conventions
  • Naming patterns
  • Props interface standards
  • Export patterns
  • Story creation steps

• 5.3 - Document division-specific patterns:

  • Color schemes
  • Typography
  • Spacing/layout conventions
  • Icon usage

• 5.4 - Create checklist for new components:

  • Component implementation
  • TypeScript types
  • Default props
  • Storybook story
  • Multiple variants
  • Documentation
  • Accessibility
  • Tests (if required)

• 5.5 - Update main README with links to:

  • Component libraries
  • Storybook deployment
  • Authoring guide

Deliverables

• Component authoring guide document
• Template files in repo
• Updated project README
• Contributor checklist

---

Phase 6: Storybook Organization

Objective: Organize Storybook sidebar for easy navigation

Tasks

• 6.1 - Review Storybook config:

  packages/storybook/.storybook/main.ts

• 6.2 - Implement sidebar structure:

  Design System/
  ├── Icons Gallery/
  │   ├── Heroicons
  │   ├── Tabler Icons
  │   └── Icon Gallery (react-native-vector-icons)
  ├── Ionicons/
  └── Lucide Icon/
  
  UI Components/
  ├── Alt Finder/
  │   ├── Web/
  │   │   └── AlternativeCard
  │   └── Mobile/
  │       └── FilterDrawer
  ├── Pride City/
  │   ├── Web/
  │   │   └── LeafletMap (17 stories)
  │   └── Mobile/
  │       └── LocationPicker
  ├── Stay Match/
  │   ├── Web/
  │   └── Mobile/
  └── ... (all divisions)

• 6.3 - Update story titles in all .stories.tsx files:

  const meta: Meta<typeof Component> = {
    title: 'UI Components/{Division}/{Platform}/{ComponentName}',
    component: Component,
  };

• 6.4 - Add meta descriptions to each story

• 6.5 - Test navigation in Storybook

• 6.6 - Build and deploy Storybook static site

Deliverables

• Organized Storybook sidebar
• Consistent naming across all stories
• Deployed Storybook with all components

---

Quality Checklist

Before marking any division as “complete,” verify:

Per Component

• Component renders without errors
• TypeScript types are correct and exported
• Props are documented with JSDoc
• Default props make sense
• Component is exported from package index
• At least 3 story variants exist
• Story has description and controls
• Component follows division style guide

Per Division

• UI package exists and is configured
• One web component ✅
• One mobile component ✅
• Both components in Storybook
• Sidebar organization correct
• README documents the components
• Package can be imported by apps

Overall Project

• All divisions have parity (1 web + 1 mobile each)
• Storybook builds successfully
• Navigation is intuitive
• Documentation is complete
• Templates exist for future additions
• CI/CD builds Storybook on every PR

---

Success Metrics

Metric	Target	Current	Status
Divisions with UI package	10/10	TBD	❓
Divisions with web component	10/10	1/10 (Pride City)	🟡
Divisions with mobile component	10/10	0/10	🔴
Total Storybook stories	30+	20+	🟡
Documentation coverage	100%	60%	🟡

---

Dependencies & Prerequisites

Technical

• ✅ Storybook configured and working
• ✅ React + TypeScript setup
• ✅ Nx or Yarn workspaces configured
• ✅ Package structure patterns established (ui-pride-city example)
• ⚠️ React Native Web (if using for mobile stories)

Organizational

• Component naming conventions agreed
• Division maintainers identified
• Design system guidelines documented
• Icon libraries selected (✅ Heroicons, Tabler)

---

Risks & Mitigation

Risk	Impact	Likelihood	Mitigation
Some divisions don’t have UI packages yet	High	High	Create packages as part of Phase 2
Mobile components hard to demo in Storybook	Medium	Medium	Use React Native Web or screenshot docs
Inconsistent component quality	Medium	Medium	Create templates and checklists
No clear component owner per division	Low	Medium	Assign during kickoff; defaults to platform team
Storybook build time increases	Low	Low	Optimize with lazy loading if needed

---

Timeline Estimate

Fast Track (Aggressive)

• Phase 1 (Discovery): 1 session
• Phase 2 (Scaffolding): 1 session
• Phase 3 (Web Components): 1-2 sessions
• Phase 4 (Mobile Components): 1-2 sessions
• Phase 5 (Documentation): 0.5 session
• Phase 6 (Organization): 0.5 session

Total: 5-7 sessions

Realistic (Recommended)

• Add buffer for iterations: 3-5 sessions
• Weekly cadence: 3-5 weeks

---

Current Status

Completed

• ✅ Pride City: LeafletMap web component (17 stories)
• ✅ Storybook configured and building
• ✅ Icon libraries installed (Heroicons, Tabler)
• ✅ Component pattern established

In Progress

• 🔄 None (paused for documentation migration)

Blocked

• ⏸️ Entire work order paused until feat/astro-starlight-docs completion

---

Resumption Plan

When resuming this work:

1. Checkout branch:

   git checkout feat/component-layering
   git pull origin feat/component-layering

2. Verify Storybook still builds:

   yarn storybook

3. Start with Phase 1 (Discovery):

   • Run inventory of existing UI packages
   • Create the component matrix table

4. Pick lowest-hanging fruit first:

   • Divisions that already have components: just add stories
   • Simple components: buttons, cards, badges

5. Iterate quickly:

   • Don’t aim for perfection on first pass
   • Get baseline coverage, then refine

---

Related Documentation

After Migration to Astro/Starlight

This work order will move to:

• apps/docs/src/content/docs/how-to/storybook-component-creation.mdx
• apps/docs/src/content/docs/reference/ui-packages.mdx
• apps/docs/src/content/docs/roadmaps/component-parity-plan.mdx

Current Locations

• Component examples: packages/ui-pride-city/src/components/
• Storybook stories: packages/storybook/stories/
• Storybook config: packages/storybook/.storybook/

---

Notes

• This work order is critical for establishing component library maturity across the platform
• Not urgent but important for long-term maintainability
• Provides clear templates for future component additions
• Deferred to prioritize documentation consolidation
• Mobile components may need React Native Web or alternative documentation approach

---

Next Actions (When Resuming)

1. Complete Phase 1 discovery inventory
2. Present findings and get division priority ranking
3. Create missing UI packages (Phase 2)
4. Begin web component creation for top 3 priority divisions
5. Set up regular check-ins for progress review

---

Document Version: 1.0
Last Updated: October 16, 2025
Resume After: feat/astro-starlight-docs completion
Estimated Start Date: TBD (Late October 2025)