# Epic 9: Design & Branding Implementation

> **Note:** The color palette defined in this epic (Navy+Gold) has been superseded.
> Epic 10 (Brand Color Refresh) updated all colors to Charcoal+Warm Gray palette.
> See `docs/brand.md` for current brand specifications.

## Epic Goal

Implement the complete visual design system with professional branding, ensuring a polished, elegant, and accessible user experience across all pages and devices.

## Epic Description

### Business Context

Libra Law Firm requires a highly professional aesthetic that reflects legal excellence and attention to detail. The design must balance sophistication with usability, supporting bilingual (Arabic/English) audiences with proper RTL/LTR layouts.

### Technical Context

- **Colors:** Dark Navy Blue (#0A1F44) + Gold (#D4AF37)
- **Fonts:** Cairo/Tajawal (Arabic), Montserrat/Lato (English)
- **Framework:** Tailwind CSS 4, Flux UI Free
- **Accessibility:** WCAG AA compliance
- **Responsive:** Mobile-first design

### Success Criteria

- [ ] Brand colors consistently applied
- [ ] Logo properly integrated throughout
- [ ] Typography hierarchy implemented
- [ ] RTL/LTR layouts perfect
- [ ] Responsive on all breakpoints
- [ ] WCAG AA contrast compliance
- [ ] Professional, polished finish
- [ ] Smooth animations and transitions

---

## Stories

### Story 9.1: Color System Implementation

**Description:** Implement the complete color palette as Tailwind CSS theme.

**Acceptance Criteria:**
- [ ] **Primary Colors:**
  - Dark Navy Blue: #0A1F44 (backgrounds, headers)
  - Gold/Brass: #D4AF37 (accents, buttons, links)
- [ ] **Supporting Colors:**
  - Light Gold: #F4E4B8 (hover states)
  - Off-White/Cream: #F9F7F4 (text, cards)
  - Charcoal Gray: #2C3E50 (secondary text)
  - Success Green: #27AE60 (approved status)
  - Warning Red: #E74C3C (rejected, errors)
  - Pending Yellow: #F39C12 (pending status)
- [ ] Custom Tailwind colors configured
- [ ] Dark mode consideration (optional)
- [ ] Color variables for easy maintenance

**Technical Notes:**
- Configure in Tailwind CSS 4 @theme directive
- Create semantic color aliases (primary, accent, etc.)

---

### Story 9.2: Typography System

**Description:** Implement typography with proper font loading and hierarchy.

**Acceptance Criteria:**
- [ ] **Arabic Fonts:**
  - Primary: Cairo or Tajawal (Google Fonts)
  - Weights: Light (300), Regular (400), SemiBold (600), Bold (700)
- [ ] **English Fonts:**
  - Primary: Montserrat or Lato
  - Weights: Light (300), Regular (400), SemiBold (600), Bold (700)
- [ ] **Font Hierarchy:**
  - H1: Bold, 2.5rem (40px)
  - H2: SemiBold, 2rem (32px)
  - H3: SemiBold, 1.5rem (24px)
  - Body: Regular, 1rem (16px)
  - Small: Regular, 0.875rem (14px)
- [ ] Line height: 1.6 body, 1.3 headings
- [ ] Font-display: swap for performance
- [ ] Preload critical fonts
- [ ] Consistent across all pages

**Technical Notes:**
- Import from Google Fonts
- Configure Tailwind font-family
- Use @font-face for fallbacks

---

### Story 9.3: Logo Integration

**Description:** Integrate Libra scales logo throughout the application.

**Acceptance Criteria:**
- [ ] **Logo Placement:**
  - Navigation: Top left (desktop), centered (mobile)
  - Footer: Smaller version
  - Email templates: Header
  - PDF exports: Header
- [ ] **Logo Specifications:**
  - Minimum size: 120px (desktop), 80px (mobile)
  - Clear space: 20px padding minimum
- [ ] **Format Support:**
  - SVG primary (scalable)
  - PNG fallback
- [ ] **Color Variations:**
  - Full color (gold on navy)
  - Reversed (navy on light)
  - Monochrome gold
- [ ] Responsive sizing
- [ ] Accessible alt text

**Technical Notes:**
- Use SVG for scalability
- Blade component for reuse
- Dynamic color based on background

---

### Story 9.4: Component Styling - Buttons

**Description:** Style all button types per brand guidelines.

**Acceptance Criteria:**
- [ ] **Primary Button:**
  - Background: Gold (#D4AF37)
  - Text: Dark Navy Blue
  - Hover: Light Gold (#F4E4B8)
  - Border-radius: 6px
  - Padding: 12px 24px
- [ ] **Secondary Button:**
  - Background: Transparent
  - Border: 2px solid Gold
  - Text: Gold
  - Hover: Gold background, Navy text
- [ ] **Disabled State:**
  - Background: #CCCCCC
  - Text: #666666
  - No hover effect
  - Cursor: not-allowed
- [ ] **Danger Button:**
  - Background: #E74C3C
  - Text: White
- [ ] Loading states with spinner
- [ ] Focus states for accessibility
- [ ] Flux UI button integration

**Technical Notes:**
- Extend Flux UI button component
- Create Tailwind component classes
- Ensure consistent sizing

---

### Story 9.5: Component Styling - Forms

**Description:** Style all form elements consistently.

**Acceptance Criteria:**
- [ ] **Input Fields:**
  - Border: Charcoal Gray
  - Focus: Gold border
  - Border-radius: 6px
  - Padding: 12px 16px
- [ ] **Textareas:**
  - Same styling as inputs
  - Minimum height: 120px
- [ ] **Select Dropdowns:**
  - Custom styled (not native)
  - Consistent with inputs
- [ ] **Checkboxes & Radios:**
  - Custom styled with gold accent
  - Clear checked state
- [ ] **Labels:**
  - SemiBold weight
  - Required indicator (*)
- [ ] **Error States:**
  - Red border
  - Error message below field
- [ ] RTL support for all fields
- [ ] Flux UI field integration

**Technical Notes:**
- Use Flux UI form components
- Ensure proper RTL alignment
- Validate error message positioning

---

### Story 9.6: Component Styling - Cards & Containers

**Description:** Style cards and container elements.

**Acceptance Criteria:**
- [ ] **Card Styling:**
  - Background: Off-white/cream
  - Box-shadow: 0 2px 8px rgba(0,0,0,0.1)
  - Border-radius: 8px
  - Padding: 24px
- [ ] **Gold Border Highlight:**
  - Optional gold top/left border
  - For featured/important cards
- [ ] **Hover States:**
  - Subtle lift effect
  - Shadow increase
- [ ] **Dashboard Stat Cards:**
  - Icon with gold accent
  - Large number display
  - Trend indicator
- [ ] **List Cards:**
  - Consistent item spacing
  - Clear click targets
- [ ] Container max-width: 1200px

**Technical Notes:**
- Create Blade card component
- Variant props for different styles

---

### Story 9.7: Navigation & Footer Styling

**Description:** Style the navigation bar and footer.

**Acceptance Criteria:**
- [ ] **Navigation Bar:**
  - Fixed top position
  - Navy blue background
  - Logo left (desktop), centered (mobile)
  - Gold text for links
  - Active link indicator
  - Language toggle styled
  - Responsive mobile menu
- [ ] **Mobile Menu:**
  - Full-width dropdown/slide
  - Navy background
  - Clear touch targets (44px+)
  - Smooth animation
- [ ] **Footer:**
  - Navy blue background
  - Logo and firm info
  - Contact details
  - Links to Terms/Privacy
  - Social links (if any)
  - Copyright notice
- [ ] Sticky footer (always at bottom)

**Technical Notes:**
- Use Flux navbar if available
- Alpine.js for mobile menu toggle

---

### Story 9.8: RTL/LTR Layout Perfection

**Description:** Ensure perfect RTL layout for Arabic and LTR for English.

**Acceptance Criteria:**
- [ ] **RTL (Arabic):**
  - Text aligns right
  - Navigation mirrors (logo right)
  - Form labels on right
  - Icons/arrows flip appropriately
  - Margins/paddings swap
- [ ] **LTR (English):**
  - Standard left-to-right layout
  - Proper text alignment
- [ ] Seamless language toggle
- [ ] No layout breaks on switch
- [ ] Calendar RTL support
- [ ] Tables RTL support
- [ ] All components tested in both

**Technical Notes:**
- Use Tailwind RTL plugin
- dir="rtl" on html element
- Logical properties (start/end vs left/right)

---

### Story 9.9: Responsive Design Implementation

**Description:** Ensure all pages work perfectly on all device sizes.

**Acceptance Criteria:**
- [ ] **Breakpoints:**
  - Mobile: < 576px
  - Tablet: 576px - 991px
  - Desktop: 992px - 1199px
  - Large Desktop: >= 1200px
- [ ] **Mobile Optimizations:**
  - Touch-friendly targets (44px+)
  - Readable font sizes
  - Single column layouts
  - Collapsible sections
- [ ] **Tablet Optimizations:**
  - Two-column where appropriate
  - Sidebar collapsible
- [ ] **Desktop Optimizations:**
  - Full layouts with sidebars
  - Multi-column grids
- [ ] All forms usable on mobile
- [ ] Calendar usable on mobile
- [ ] Tables scroll horizontally

**Technical Notes:**
- Mobile-first approach
- Test on real devices
- Use responsive utilities

---

### Story 9.10: Accessibility Compliance

**Description:** Ensure WCAG AA accessibility compliance.

**Acceptance Criteria:**
- [ ] **Color Contrast:**
  - Body text: 4.5:1 minimum
  - Large text: 3:1 minimum
  - UI elements: 3:1 minimum
- [ ] **Focus Indicators:**
  - Visible focus outline (gold)
  - Not just color change
- [ ] **Keyboard Navigation:**
  - All interactive elements reachable
  - Logical tab order
  - Skip to main content link
- [ ] **Screen Readers:**
  - Proper heading hierarchy
  - Alt text for images
  - ARIA labels where needed
  - Form labels associated
- [ ] **Motion:**
  - Respect prefers-reduced-motion
  - No auto-playing animations

**Technical Notes:**
- Use accessibility testing tools
- Test with screen reader
- Document any exceptions

---

### Story 9.11: Animations & Micro-interactions

**Description:** Add subtle, professional animations and transitions.

**Acceptance Criteria:**
- [ ] **Transitions:**
  - Button hover: 150ms ease
  - Card hover: 200ms ease
  - Modal open/close: 200ms
  - Page transitions (optional)
- [ ] **Loading States:**
  - Skeleton loaders for content
  - Spinner for actions
  - Progress indicators
- [ ] **Feedback Animations:**
  - Success checkmark
  - Error shake
  - Toast slide-in
- [ ] **Hover Effects:**
  - Links: Color transition
  - Cards: Lift effect
  - Buttons: Background transition
- [ ] All animations subtle, professional
- [ ] Respect reduced-motion preference

**Technical Notes:**
- Use Tailwind transition utilities
- Keep animations under 300ms
- Avoid distracting effects

---

## Dependencies

| Epic | Dependency |
|------|------------|
| Epic 1 | Base Tailwind/Flux setup |
| All Epics | This epic applies styling to all features |

## Risks & Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Logo not provided in vector | Medium | Request SVG, create placeholder |
| RTL edge cases | Medium | Thorough testing, RTL checklist |
| Browser inconsistencies | Low | Cross-browser testing |
| Accessibility issues discovered late | Medium | Test early and often |

## Definition of Done

- [ ] All stories completed with acceptance criteria met
- [ ] Brand colors consistent throughout
- [ ] Typography proper and readable
- [ ] Logo integrated correctly
- [ ] All components styled
- [ ] RTL layout perfect
- [ ] Responsive on all breakpoints
- [ ] WCAG AA compliant
- [ ] Animations smooth and subtle
- [ ] Cross-browser tested
- [ ] Code formatted with Pint