# Epic 10: Brand Color Refresh - Brownfield Enhancement

## Epic Goal

Update the application's color system to align with the new LIBRA for Rights brand identity, transitioning from the Navy Blue + Gold palette to the new Charcoal + Warm Gray earth-tone palette defined in `docs/brand.md`.

## Epic Description

### Existing System Context

- **Current functionality:** Full color system implemented in Tailwind CSS 4 `@theme` directive with Navy (#0A1F44), Gold (#D4AF37), and supporting colors
- **Technology stack:** Laravel 12, Tailwind CSS 4, Livewire 3, Flux UI Free
- **Integration points:** CSS variables used across 58+ files including public pages, admin dashboard, client portal, PDF exports, email templates, and documentation

### Enhancement Details

**What's being changed:**

| Old Color | Old Hex | New Color | New Hex |
|-----------|---------|-----------|---------|
| Navy Blue | `#0A1F44` | Charcoal | `#4A4A42` |
| Gold | `#D4AF37` | Warm Gray | `#C9C4BA` |
| Gold Light | `#F4E4B8` | Off-White | `#E8E4DC` |
| Cream | `#F9F7F4` | Off-White | `#E8E4DC` |
| Charcoal | `#2C3E50` | Deep Black | `#1A1A1A` |

**Brand Identity Source:** `docs/brand.md`

**How it integrates:**
- Update CSS custom properties in `resources/css/app.css`
- Update component color references across all Blade views
- Update SVG logo files with new brand design
- Update PDF export templates
- Update email templates
- Update documentation (PRD, architecture, stories, CLAUDE.md)

**Success criteria:**
- All pages render with new color palette
- WCAG AA contrast ratios maintained
- Consistent appearance across all areas (public, admin, client)
- PDF exports reflect new branding
- Email templates reflect new branding
- Logo displays correctly throughout application
- Documentation updated to reflect new colors

---

## Stories

| Story | Title | Description | Status |
|-------|-------|-------------|--------|
| 10.1 | [Core CSS Theme Update](../stories/story-10.1-core-css-theme-update.md) | Update Tailwind CSS theme variables and semantic aliases | Complete |
| 10.2 | [Blade Component Color Migration](../stories/story-10.2-blade-component-color-migration.md) | Update 16 Blade files with 64 color class occurrences | Complete |
| 10.3 | [Email Template Color Update](../stories/story-10.3-email-template-color-update.md) | Update email theme CSS and template components | Complete |
| 10.4 | [PDF Template Color Update](../stories/story-10.4-pdf-template-color-update.md) | Update 4 PDF export templates | Complete |
| 10.5 | [Logo and SVG Assets Update](../stories/story-10.5-logo-assets-update.md) | Update/replace logo SVG files for new brand | Complete |
| 10.6 | [Documentation Update](../stories/story-10.6-documentation-update.md) | Update PRD, CLAUDE.md, architecture docs, and story files | Complete |

### Story Dependencies

```
10.1 (CSS Theme) ──┬──> 10.2 (Blade Components)
                   ├──> 10.3 (Email Templates)
                   └──> 10.4 (PDF Templates)

10.5 (Logo Assets) ──> Can run in parallel with 10.1

10.6 (Documentation) ──> Should run last, after 10.1-10.5
```

### Recommended Implementation Order

1. **Story 10.5** - Logo Assets (can start immediately if assets available)
2. **Story 10.1** - Core CSS Theme (foundation for other stories)
3. **Stories 10.2, 10.3, 10.4** - Can run in parallel after 10.1
4. **Story 10.6** - Documentation (final step)

---

## Compatibility Requirements

- [x] Existing APIs remain unchanged
- [x] Database schema changes: None required
- [x] UI changes follow existing Tailwind/Flux patterns
- [x] Performance impact: Minimal (CSS only)

## Risk Mitigation

| Risk | Likelihood | Impact | Mitigation |
|------|------------|--------|------------|
| Missing color references causing inconsistent appearance | Medium | Medium | Comprehensive grep search for all hex values; systematic testing of each area |
| Logo assets not available | Medium | High | Coordinate with client early; can update colors first and logo later |
| Contrast issues with new palette | Low | Medium | Verify WCAG AA compliance in Story 10.1 before proceeding |
| RTL layout breaks | Low | Medium | Test Arabic layout after each story |

**Rollback Plan:** Git revert to pre-epic commit; CSS variables make rollback straightforward

## Definition of Done

- [x] Story 10.1: Core CSS theme updated with new colors
- [x] Story 10.2: All Blade components using new palette
- [x] Story 10.3: Email templates updated
- [x] Story 10.4: PDF templates updated
- [x] Story 10.5: Logo files updated/replaced
- [x] Story 10.6: All documentation updated
- [x] All pages render correctly with new colors
- [x] WCAG AA contrast compliance verified
- [x] RTL layout displays correctly
- [x] Responsive design intact across breakpoints
- [x] PDF exports display new branding
- [x] Email templates display new branding
- [x] Code formatted with Pint
- [x] All existing tests passing
- [ ] Visual QA completed on all major pages

---

## Affected Files Summary

| Category | File Count | Notes |
|----------|------------|-------|
| CSS Theme | 1 | `resources/css/app.css` |
| Blade Components | 16 | 64 color class occurrences |
| Email Templates | 6+ | Theme CSS + components |
| PDF Templates | 4 | Export templates |
| Logo/SVG Assets | 4 | SVG + PNG files |
| Documentation | 44+ | PRD, CLAUDE.md, stories |

**Total estimated files to modify:** ~70 files

---

## Testing Checklist

### Visual Testing
- [ ] Home page
- [ ] Booking page
- [ ] Posts listing and detail
- [ ] Login/Auth pages
- [ ] Admin dashboard
- [ ] Admin user management
- [ ] Admin booking management
- [ ] Admin timeline management
- [ ] Client dashboard
- [ ] Client consultations view
- [ ] Client timelines view
- [ ] Settings pages

### Export Testing
- [ ] Users PDF export
- [ ] Consultations PDF export
- [ ] Timelines PDF export
- [ ] Monthly report PDF

### Email Testing
- [ ] Welcome email
- [ ] Booking submitted email
- [ ] Booking approved email
- [ ] Booking rejected email
- [ ] Consultation reminders
- [ ] Timeline update email

### Cross-Browser Testing
- [ ] Chrome
- [ ] Firefox
- [ ] Safari
- [ ] Edge

### Responsive Testing
- [ ] Mobile (< 576px)
- [ ] Tablet (576px - 991px)
- [ ] Desktop (992px+)

### RTL Testing
- [ ] Arabic language layout
- [ ] Navigation RTL
- [ ] Forms RTL
- [ ] Tables RTL
