# Product Requirements Document

## Validation Checklist

- [x] All required sections are complete
- [x] No [NEEDS CLARIFICATION] markers remain
- [x] Problem statement is specific and measurable
- [x] Problem is validated by evidence (not assumptions)
- [x] Context → Problem → Solution flow makes sense
- [x] Every persona has at least one user journey
- [x] All MoSCoW categories addressed (Must/Should/Could/Won't)
- [x] Every feature has testable acceptance criteria
- [x] Every metric has corresponding tracking events
- [x] No feature redundancy (check for duplicates)
- [x] No contradictions between sections
- [x] No technical implementation details included
- [x] A new team member could understand this PRD

---

## Product Overview

### Vision
A unified, maintainable CSS design system that enables developers to build consistent, modern admin interfaces in a fraction of the time while ensuring visual cohesion across all BuyerKiosk admin pages.

### Problem Statement
**Current Pain Points:**

1. **CSS Sprawl**: The admin panel has 143 CSS files totaling ~28,714 lines with ~1.3MB of legacy Bootstrap 3 code vs only ~294K of modern CSS. This makes maintenance costly and error-prone.

2. **Inconsistent UI**: Legacy pages use Bootstrap 3 patterns (flat design, blue color scheme, sharp corners) while modern pages (Backstock, Comeback Cash) use the new design language (gradients, purple branding, rounded corners). Users experience visual whiplash navigating between areas.

3. **Color Chaos**: The same purple primary color (`#7c3aed`) is hardcoded in 8+ files instead of using CSS variables. Bootstrap legacy colors (`#337ab7`, `#5cb85c`) conflict with brand colors.

4. **No Reference**: Developers have a comprehensive STYLE_GUIDE.md document but no living example page to see components in action, copy code patterns, or validate implementations.

5. **Missing Theme File**: The referenced `theme.css` file doesn't exist in the repository, yet templates depend on it.

**Business Impact:**
- Developer onboarding takes longer due to unclear patterns
- UI inconsistencies erode user trust and perceived quality
- Maintenance overhead from dual CSS systems
- Risk of styling bugs when modifying legacy pages

### Value Proposition
This Bootstrap 5 migration and design system consolidation will:

1. **Reduce development time** by leveraging Bootstrap 5's modern components and providing a reference page
2. **Ensure visual consistency** by migrating from Bootstrap 3 to Bootstrap 5 with brand customizations
3. **Simplify maintenance** with Bootstrap 5's CSS variable system and a thin customization layer
4. **Enable future theming** through Bootstrap 5's built-in dark mode support and CSS variables
5. **Improve code quality** through industry-standard framework with community support
6. **Enable advanced layouts** with Masonry integration for variable-height card grids

## User Personas

### Primary Persona: BuyerKiosk Developer
- **Demographics:** Internal or contractor developer working on the BuyerKiosk codebase; familiar with PHP, Twig, and frontend technologies
- **Goals:**
  - Build new admin pages that match the existing look and feel quickly
  - Update legacy pages to modern styling without breaking functionality
  - Find the right CSS classes and patterns without digging through multiple files
- **Pain Points:**
  - Uncertainty about which CSS file to look in for existing patterns
  - Inconsistent naming between legacy (`.panel`, `.label`) and modern (`.card`, `.badge`) components
  - No visual reference to validate implementations match the design
  - Fear of breaking existing pages when consolidating styles

### Secondary Personas

#### Store Manager (End User)
- **Demographics:** Non-technical retail store manager using admin panel daily
- **Goals:** Navigate admin seamlessly with a consistent, professional interface
- **Pain Points:** Visual inconsistency between pages feels unprofessional and confusing

#### Admin (BuyerKiosk Support)
- **Demographics:** BuyerKiosk support staff who help store managers
- **Goals:** Guide users through the admin interface confidently
- **Pain Points:** Different styling between pages makes training and support harder

## User Journey Maps

### Primary User Journey: Developer Building a New Admin Page
1. **Awareness:** Developer is assigned a new feature requiring an admin interface
2. **Consideration:** Developer needs to match existing UI patterns - checks STYLE_GUIDE.md for documentation
3. **Adoption:** Developer opens the Style Guide Reference Page to see live component examples
4. **Usage:**
   - Browses component library for needed elements (stat cards, buttons, tables, badges)
   - Copies HTML/CSS code snippets directly from the reference page
   - Applies to their new page with confidence it matches the design system
   - Validates their implementation against the reference page visually
5. **Retention:** Reference page becomes the go-to resource for all future UI work

### Secondary User Journeys

#### Developer Migrating a Legacy Page
1. Developer identifies a legacy page using Bootstrap 3 patterns (`.panel`, `.btn-default`)
2. Opens Style Guide Reference Page to find modern equivalents
3. Uses side-by-side comparison section showing legacy → modern mappings
4. Updates page HTML classes, removing Bootstrap 3 dependencies
5. Validates the updated page matches the design system

#### Developer Debugging Style Issues
1. Page displays unexpected styling
2. Developer opens Style Guide Reference Page to verify correct class usage
3. Compares their implementation against the documented pattern
4. Identifies and fixes the deviation

## Feature Requirements

### Must Have Features

#### Feature 1: Bootstrap 5 Migration with Brand Customization Layer
- **User Story:** As a developer, I want to use Bootstrap 5 with BuyerKiosk brand customizations so that I can leverage a modern, well-documented framework while maintaining our visual identity
- **Acceptance Criteria:**
  - [ ] Bootstrap 5.3 CSS is loaded as the base framework
  - [ ] Brand customization layer (`admin-theme.css`) overrides Bootstrap defaults with BuyerKiosk colors
  - [ ] All design tokens (colors, spacing, typography, shadows) are defined as CSS variables in `tokens.css`
  - [ ] Variables integrate with Bootstrap 5's CSS variable system
  - [ ] Conductor CLI command (`build-css`) concatenates customization files into `admin-theme.min.css`
  - [ ] Legacy Bootstrap 3 CSS files are completely removed (hard cutover)
  - [ ] Masonry.js is included for variable-height card grid layouts

#### Feature 2: Style Guide Reference Page
- **User Story:** As a developer, I want a living reference page that displays all available components with copy-paste code snippets so that I can build consistent interfaces quickly
- **Acceptance Criteria:**
  - [ ] Page is accessible at `/admin/style-guide` (admin-only route)
  - [ ] Displays all color swatches with hex values and CSS variable names
  - [ ] Shows all typography styles with rendered examples
  - [ ] Demonstrates all button variants (primary, secondary, ghost, destructive, sizes)
  - [ ] Shows all badge/status indicator variants
  - [ ] Displays stat card component with color variants
  - [ ] Shows event/item card component patterns
  - [ ] Displays form input variants (default, focus, error, disabled)
  - [ ] Shows table styling with DataTables integration
  - [ ] Includes modal pattern example
  - [ ] Includes tab navigation pattern
  - [ ] Each component section includes HTML code snippet that can be copied
  - [ ] Page uses the actual design system CSS (dogfooding)

#### Feature 3: Bootstrap 3 → 5 Template Migration
- **User Story:** As a developer, I want legacy Bootstrap 3 components replaced with Bootstrap 5 equivalents so that the entire admin panel has a consistent, modern look
- **Acceptance Criteria:**
  - [ ] All `.panel` usage replaced with Bootstrap 5 `.card` component
  - [ ] All `.label-*` usage replaced with Bootstrap 5 `.badge` component
  - [ ] All `.btn-default` replaced with `.btn-secondary` (or `.btn-outline-secondary`)
  - [ ] All `.form-group` replaced with `.mb-3` spacing
  - [ ] All `.pull-left`/`.pull-right` replaced with `.float-start`/`.float-end`
  - [ ] All hardcoded colors replaced with CSS variable references
  - [ ] Legacy Bootstrap 3 CSS files removed from build
  - [ ] Bootstrap 5 JavaScript bundle loaded (for modals, dropdowns, etc.)
  - [ ] Font Awesome consolidated to single version (v6)

#### Feature 4: Core Design Token System
- **User Story:** As a developer, I want a single source of truth for design tokens so that changing a brand color updates everywhere automatically
- **Acceptance Criteria:**
  - [ ] All colors defined as CSS variables (matching STYLE_GUIDE.md)
  - [ ] All spacing values defined as CSS variables
  - [ ] All typography values defined as CSS variables
  - [ ] All border-radius values defined as CSS variables
  - [ ] All shadow values defined as CSS variables
  - [ ] All transition timing values defined as CSS variables
  - [ ] Dark mode foundation variables structured (even if not implemented)

### Should Have Features

#### Feature 5: Legacy to Modern Mapping Documentation
- **User Story:** As a developer, I want a reference mapping legacy class names to their modern equivalents so that I can migrate pages efficiently
- **Acceptance Criteria:**
  - [ ] Style Guide Reference Page includes "Migration Guide" section
  - [ ] Shows table mapping `.panel` → `.card`, `.label` → `.badge`, etc.
  - [ ] Includes before/after HTML examples

#### Feature 6: Icon Library Consolidation
- **User Story:** As a developer, I want a single icon library so that I don't have to worry about which Font Awesome version to use
- **Acceptance Criteria:**
  - [ ] Font Awesome 6 is the only icon library loaded
  - [ ] Legacy Font Awesome (v4, v5) imports removed
  - [ ] Icon usage documented in Style Guide Reference Page

### Could Have Features

#### Feature 7: Utility Classes
- **User Story:** As a developer, I want utility classes for common spacing and display needs so that I don't have to write custom CSS for simple layouts
- **Acceptance Criteria:**
  - [ ] Margin utilities (`.m-1` through `.m-6`, `.mt-*`, `.mb-*`, etc.)
  - [ ] Padding utilities (`.p-1` through `.p-6`, `.pt-*`, `.pb-*`, etc.)
  - [ ] Display utilities (`.d-flex`, `.d-grid`, `.d-none`)
  - [ ] Text utilities (`.text-center`, `.text-muted`, `.text-primary`)

#### Feature 8: Animation Library
- **User Story:** As a developer, I want reusable animation classes so that I can add consistent micro-interactions
- **Acceptance Criteria:**
  - [ ] Fade-in animation class
  - [ ] Slide-up animation class
  - [ ] Pop/bounce animation class
  - [ ] Shake/error animation class

#### Feature 9: Masonry Grid Layouts
- **User Story:** As a developer, I want variable-height cards to display without gaps so that event listings and dashboards look polished
- **Acceptance Criteria:**
  - [ ] Masonry.js library is loaded on pages with variable-height card grids
  - [ ] Event card grids (Comeback Cash, Backstock Events) use Masonry layout
  - [ ] Masonry integrates with Bootstrap 5 grid system via `data-masonry` attribute
  - [ ] Fallback to standard CSS Grid when JavaScript is disabled

### Won't Have (This Phase)

1. **Full Dark Mode Implementation** - Bootstrap 5 supports it, but actual dark theme customization is out of scope
2. **CSS-in-JS Migration** - Staying with traditional CSS approach
3. **Tailwind CSS Adoption** - Using Bootstrap 5 instead
4. **Public-Facing Page Styling** - Focus is on admin panel only (`/admin/*`, `/workspace/*`)
5. **React/Vue Component Framework** - CSS/HTML only; JS behavior remains in existing jQuery files
6. **Automated Visual Regression Testing** - Manual validation for this phase
7. **Bootstrap Sass Customization** - Using CSS variable overrides instead of Sass compilation

## Detailed Feature Specifications

### Feature: Style Guide Reference Page
**Description:** A single admin-accessible page that serves as the definitive visual reference for all design system components. The page displays live examples of every component alongside copyable HTML code snippets. It is organized into logical sections matching the component library structure.

**User Flow:**
1. Developer navigates to `/admin/style-guide`
2. System displays the Style Guide Reference Page with navigation
3. Developer browses sections: Colors, Typography, Buttons, Cards, Badges, Forms, Tables, Modals, Tabs
4. Developer finds the component they need
5. Developer views the live rendered example
6. Developer clicks "Copy Code" to copy the HTML snippet to clipboard
7. Developer pastes into their template and customizes as needed

**Page Sections:**
1. **Colors** - All color swatches organized by category (Primary, Secondary, Semantic, Neutral)
2. **Typography** - Font family, sizes, weights with rendered examples
3. **Spacing** - Visual representation of spacing scale
4. **Buttons** - All variants (primary, secondary, ghost, destructive) in all sizes
5. **Badges** - Status badges for all semantic states
6. **Stat Cards** - KPI card component with all color variants
7. **Event Cards** - Multi-section card pattern with header/body/footer
8. **Forms** - Input fields, selects, checkboxes in all states
9. **Tables** - DataTables integration with modern styling
10. **Modals** - Modal dialog pattern with gradient header
11. **Tabs** - Horizontal tab navigation pattern
12. **Migration Guide** - Legacy → Modern class mappings

**Business Rules:**
- Rule 1: Page is only accessible to authenticated admin users
- Rule 2: All component examples must use actual design system CSS (no inline styles)
- Rule 3: Code snippets must be complete and copy-paste ready (no placeholders)
- Rule 4: Color swatches must show both hex value and CSS variable name

**Edge Cases:**
- Scenario 1: User without admin access attempts to view page → Expected: Redirect to login or show 403
- Scenario 2: CSS build fails → Expected: Page should gracefully degrade with basic styling
- Scenario 3: Code copy fails (clipboard API not supported) → Expected: Show fallback text selection

## Success Metrics

### Key Performance Indicators

- **CSS File Reduction:** Target reduction from 143 files to <30 organized files
- **Code Size Reduction:** Target reduction from ~1.5MB total CSS to <200KB minified admin bundle
- **Consistency Score:** 100% of admin pages using design system components (no legacy Bootstrap 3)
- **Developer Adoption:** Style Guide Reference Page viewed by developers when building new features
- **Bug Reduction:** Decrease in styling-related bug reports after rollout

### Tracking Requirements

| Event | Properties | Purpose |
|-------|------------|---------|
| `style_guide_page_view` | `user_id`, `timestamp`, `referrer` | Measure developer adoption of reference page |
| `style_guide_copy_snippet` | `component_type`, `user_id` | Track which components are most used |
| `style_guide_section_view` | `section_name`, `time_spent` | Identify which sections need improvement |
| `legacy_class_usage` (build warning) | `class_name`, `file_path` | Track legacy class elimination progress |

---

## Constraints and Assumptions

### Constraints
- **Framework Migration:** Bootstrap 3 → Bootstrap 5; must work within existing PHP/Slim/Twig stack
- **Browser Support:** Must support Chrome, Firefox, Safari, Edge (latest 2 versions) - Bootstrap 5 requirement
- **Hard Cutover Risk:** Removing Bootstrap 3 CSS may break pages if migration is incomplete
- **Build Process:** Conductor CLI for theme CSS; Bootstrap 5 loaded via CDN or local files
- **Admin Panel Scope:** Changes limited to admin routes; public-facing pages out of scope
- **jQuery Dependency:** Bootstrap 5 removes jQuery dependency, but existing app JS still uses jQuery

### Assumptions
- Developers will reference the Style Guide Page rather than inventing new patterns
- The existing STYLE_GUIDE.md document accurately represents desired design direction
- Modern pages (Backstock, Comeback Cash) represent the target visual language
- Bootstrap 5's CSS variable system will integrate with our custom tokens
- Bootstrap 5 JavaScript components (modals, dropdowns) will work with existing event handlers
- Masonry.js will handle variable-height card layouts without performance issues

## Risks and Mitigations

| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| Breaking existing pages during hard cutover | High | Medium | Comprehensive testing of all admin pages before deploy; staging environment validation |
| Developers not adopting design system | Medium | Low | Make Style Guide Page easily discoverable; communicate change through team channels |
| Missing edge cases in component library | Medium | Medium | Build components based on actual existing usage patterns; iterate based on feedback |
| Build process complexity delays project | Medium | Low | Use simple concatenation script; avoid complex tooling |
| Dark mode foundation adds scope creep | Low | Medium | Strictly enforce "foundation only" - variables structure without actual dark styles |

## Open Questions

- [x] What is the primary purpose of the Style Guide page? → **Developer Reference**
- [x] How should we handle legacy CSS migration? → **Hard Cutover**
- [x] Which CSS architecture approach? → **Modular Components**
- [x] Should dark mode be included? → **Foundation Only**
- [ ] Should the Style Guide page be accessible to all admins or just developers?
- [ ] Is there a preferred CSS minification tool already in the deployment pipeline?

---

## Supporting Research

### Competitive Analysis
**Design System Industry Standards:**
- **Shopify Polaris:** Modular component library with live examples, copy-paste code, variable-based theming
- **Material Design:** Comprehensive token system, clear component documentation, accessibility-first
- **Bootstrap 5:** CSS variables throughout, modular Sass files, utility classes

**Key Learnings:**
- Living documentation (actual rendered components) is more valuable than static docs
- CSS variables enable theming and are now industry standard
- Modular architecture with clear naming conventions improves maintainability

### User Research
**Developer Pain Points (from codebase analysis):**
- 143 CSS files make it hard to find existing patterns
- Legacy Bootstrap 3 styles conflict with modern design
- No visual reference to validate implementations
- Hardcoded colors repeated across files

**Modern Page Success Stories:**
- Backstock home page demonstrates successful stat card pattern
- Comeback Cash shows effective card-based layouts with status badges
- Workspace pages show full CSS variable adoption with dark mode support

### Market Data
**Relevant Industry Trends:**
- CSS custom properties (variables) have 97%+ browser support globally
- Design systems reduce development time by 20-50% according to industry studies
- Component-based CSS architecture is the dominant approach for modern applications
- Single-source-of-truth design tokens are considered best practice