# 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 PDF export 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
- Documentation updated to reflect new colors

---

## Stories

### Story 10.1: Core Color System Update

**Description:** Update the Tailwind CSS theme configuration and core color variables.

**Acceptance Criteria:**
- [ ] Update `resources/css/app.css` `@theme` block with new colors:
  - `--color-charcoal: #4A4A42` (replaces navy)
  - `--color-warm-gray: #C9C4BA` (replaces gold)
  - `--color-off-white: #E8E4DC` (replaces cream/gold-light)
  - `--color-deep-black: #1A1A1A` (replaces old charcoal)
- [ ] Create semantic aliases for backward compatibility during transition
- [ ] Update `.prose-navy` to `.prose-charcoal` or equivalent
- [ ] Verify WCAG AA contrast ratios for all color combinations
- [ ] Update Flux UI accent color configuration
- [ ] Test dark mode colors if applicable

**Technical Notes:**
- Keep status colors (success, danger, warning) unchanged
- Consider creating aliases like `--color-primary` → `--color-charcoal` for semantic usage
- Run contrast checker on all text/background combinations

---

### Story 10.2: Component & Page Color Migration

**Description:** Update all components and pages to use the new color palette.

**Acceptance Criteria:**
- [ ] **Navigation & Footer:**
  - Update background from navy to charcoal
  - Update text/links from gold to warm-gray/off-white
  - Update logo component colors
- [ ] **Buttons:**
  - Primary: Charcoal background, off-white text
  - Secondary: Warm-gray border, charcoal text
  - Hover states updated accordingly
- [ ] **Forms:**
  - Focus ring: warm-gray instead of gold
  - Border colors updated
- [ ] **Cards & Containers:**
  - Background: off-white
  - Borders/accents: warm-gray
- [ ] **Public Pages:** Home, booking, posts
- [ ] **Admin Dashboard:** All admin pages and charts
- [ ] **Client Portal:** All client pages
- [ ] **PDF Exports:** Users, consultations, timelines, monthly report
- [ ] All hardcoded hex values replaced with CSS variables

**Technical Notes:**
- Use find/replace carefully for hex values
- Test RTL layout after changes
- Verify responsive appearance on all breakpoints

---

### Story 10.3: Documentation & Asset Update

**Description:** Update all documentation and static assets to reflect new brand colors.

**Acceptance Criteria:**
- [ ] Update `docs/prd.md` color specifications
- [ ] Update `docs/architecture.md` design references
- [ ] Update `CLAUDE.md` color guidance
- [ ] Update Epic 9 story references (mark as superseded or update)
- [ ] Update any remaining story files with old color references
- [ ] Ensure logo files are current (reference `docs/brand.md` guidelines)
- [ ] Update `resources/views/components/app-logo.blade.php` if needed
- [ ] Verify favicon/app icons align with new branding

**Technical Notes:**
- Use grep to find all documentation references to old hex values
- Consider adding note in Epic 9 that colors were updated in Epic 10

---

## 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

- **Primary Risk:** Missing color references causing inconsistent appearance
- **Mitigation:** Comprehensive grep search for all hex values; systematic testing of each area
- **Rollback Plan:** Git revert to pre-epic commit; CSS variables make rollback straightforward

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] Existing functionality verified through visual testing
- [ ] All pages render correctly with new colors
- [ ] PDF exports display new branding
- [ ] Documentation reflects new color palette
- [ ] No regression in existing features
- [ ] Code formatted with Pint
- [ ] All tests passing

---

## Story Manager Handoff

"Please develop detailed user stories for this brownfield epic. Key considerations:

- This is a brand color refresh for an existing Laravel 12 + Tailwind CSS 4 + Livewire 3 application
- Integration points: CSS `@theme` variables, 58+ Blade/Volt files, PDF templates, documentation
- Existing patterns to follow: Current Tailwind CSS variable approach in `resources/css/app.css`
- Critical compatibility requirements: WCAG AA contrast ratios, RTL layout integrity, responsive design
- Each story must include verification that existing functionality remains intact
- Reference `docs/brand.md` for authoritative color values

The epic should maintain system integrity while delivering the updated LIBRA for Rights brand identity."
