libra/docs/stories/epic-12-branding-refresh.md

# Epic 12: Branding Refresh - Logo and Color Scheme Update

## Epic Goal

Update the LIBRA for Rights brand identity by implementing the new square logo with Palestinian tatreez patterns and transitioning the color scheme to a refined dark charcoal and warm gold palette that creates an elegant, professional aesthetic.

## Epic Description

### Existing System Context

- **Current relevant functionality:** The application uses a square PNG logo in navbar and footer, with a color scheme that needs updating
- **Technology stack:** Laravel 12, Livewire 3, Tailwind CSS 4, Flux UI components
- **Integration points:** Logo appears in navbar, footer, emails, and favicon. Colors are defined in Tailwind config and used throughout Blade components.

### Enhancement Details

**What's being added/changed:**

1. Update color palette to dark charcoal and warm gold theme
2. Adjust CSS for new color scheme
3. Update all brand assets colors (emails, PDFs)

**New Color Palette:**

| Color Name | Hex | Usage |
|------------|-----|-------|
| Primary (Dark Charcoal) | `#1B1D1A` | Header/Footer backgrounds |
| CTA (Warm Gold) | `#A68966` | Buttons, links, accents |
| Background (Warm Cream) | `#F4F1EA` | Main page background |
| Text (Forest Green) | `#2D322A` | Headings, body text |
| Card (Pure White) | `#FFFFFF` | Card backgrounds |
| Active (Olive Green) | `#4A5D23` | Active states, language toggle |

**Color Variants (for hover/active states):**

| Variant | Hex | Usage |
|---------|-----|-------|
| Primary Light | `#2D322A` | Primary hover state |
| CTA Hover | `#8A7555` | Button hover state |
| CTA Light | `#C4A882` | Light accent |
| Active Hover | `#5A7030` | Active state hover |

**How it integrates:**

- Tailwind CSS color configuration will be updated
- Existing Blade components will automatically use new colors via CSS variables

**Success criteria:**

- Color scheme consistently uses new palette across all pages
- Professional, elegant appearance maintained
- No visual regressions in existing UI components

## Stories

### Story 12.1: Logo Asset Deployment and CSS Layout Updates
**File:** `story-12.1-logo-asset-deployment.md`
**Status:** ✅ Completed (no changes needed - logo already deployed)

Deploy the new square logo files and update CSS to accommodate square dimensions in navbar, footer, and auth pages. Includes favicon and mobile app icon deployment.

### Story 12.2: Core CSS Theme Update - Dark Charcoal & Warm Gold Palette
**File:** `story-12.2-core-css-theme-update.md`
**Status:** 🔄 Needs Reimplementation

Update Tailwind CSS theme variables to new dark charcoal and warm gold palette. Add color variants for hover, active, and light states.

### Story 12.3: Blade Component Color Migration
**File:** `story-12.3-blade-component-color-migration.md`
**Status:** 🔄 Needs Reimplementation

Update all Blade components and pages to use the new color palette. Includes navigation, footer, cards, public pages, admin dashboard, and client dashboard components.

### Story 12.4: Email Template Color Update
**File:** `story-12.4-email-template-color-update.md`
**Status:** 🔄 Needs Reimplementation

Update email templates to use new colors. Includes theme CSS, header/footer components, button styles, and all notification emails.

### Story 12.5: PDF Template Color Update
**File:** `story-12.5-pdf-template-color-update.md`
**Status:** 🔄 Needs Reimplementation

Update PDF export templates to use new colors. Includes users export, consultations export, timelines export, and monthly report. Update chart colors in MonthlyReportService.

### Story 12.6: Brand Documentation Update
**File:** `story-12.6-documentation-update.md`
**Status:** ⏳ Blocked (after 12.2-12.5)

Update brand documentation (`docs/brand.md`, `CLAUDE.md`, etc.) to reflect new color palette. Update test color assertions. Final cleanup and verification.

## Compatibility Requirements

- [x] Existing APIs remain unchanged
- [x] Database schema changes are backward compatible (N/A - no DB changes)
- [x] UI changes follow existing patterns
- [x] Performance impact is minimal

## Risk Mitigation

- **Primary Risk:** Color changes may affect accessibility (contrast ratios)
- **Mitigation:** Test all color combinations for WCAG AA compliance; adjust shades if needed
- **Rollback Plan:** Git revert to previous commit; old logo files preserved in git history

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] New logo displays correctly across all pages and devices
- [ ] Color scheme is consistent throughout the application
- [ ] Brand documentation is updated
- [ ] No regression in existing features
- [ ] Visual QA completed on major pages

## Technical Notes

### Color Values for Implementation

```css
/* New Dark Charcoal & Warm Gold Palette */
--color-primary: #1B1D1A;      /* Dark Charcoal - Header/Footer backgrounds */
--color-cta: #A68966;          /* Warm Gold - Buttons, links, accents */
--color-background: #F4F1EA;   /* Warm Cream - Main page background */
--color-text: #2D322A;         /* Forest Green - Headings, body text */
--color-card: #FFFFFF;         /* Pure White - Card backgrounds */
--color-active: #4A5D23;       /* Olive Green - Active states */

/* Color variants for UI states */
--color-primary-light: #2D322A;   /* Primary hover state */
--color-cta-hover: #8A7555;       /* Button hover state */
--color-cta-light: #C4A882;       /* Light accent */
--color-active-hover: #5A7030;    /* Active state hover */
```

### Color Usage Guidelines

| Element | Color | Hex |
|---------|-------|-----|
| Header/Footer Background | Primary | `#1B1D1A` |
| Main Page Background | Background | `#F4F1EA` |
| Card Backgrounds | Card | `#FFFFFF` |
| CTA Buttons | CTA | `#A68966` |
| Button Hover | CTA Hover | `#8A7555` |
| Headings & Text | Text | `#2D322A` |
| Active Language Toggle | Active | `#4A5D23` |
| Links | CTA | `#A68966` |
| Link Hover | CTA Hover | `#8A7555` |

## Dependencies

- Logo files already deployed
- No external dependencies required