# Story 9.2: Typography System

## Epic Reference
**Epic 9:** Design & Branding Implementation

## Dependencies
- **Story 9.1 (Color System)** must be complete - this story extends the existing `@theme` block in `resources/css/app.css`

## PRD Reference
- **Section 7.1.C:** Typography specifications (font families, weights, hierarchy)

## User Story
As a **user**,
I want **professional, readable typography**,
So that **the platform feels polished and content is easy to read**.

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

### Performance
- [ ] Line height: 1.6 body, 1.3 headings
- [ ] font-display: swap
- [ ] Preload critical fonts

## Technical Notes

**Target File:** `resources/css/app.css`

**Implementation:** Add the font imports and extend the existing `@theme` block from Story 9.1 with typography variables.

```css
/* Google Fonts import - add at top of file */
@import url('https://fonts.googleapis.com/css2?family=Cairo:wght@300;400;600;700&family=Montserrat:wght@300;400;600;700&display=swap');

@theme {
  --font-arabic: 'Cairo', 'Tajawal', sans-serif;
  --font-english: 'Montserrat', 'Lato', sans-serif;

  --font-size-xs: 0.75rem;
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;
  --font-size-xl: 1.25rem;
  --font-size-2xl: 1.5rem;
  --font-size-3xl: 2rem;
  --font-size-4xl: 2.5rem;
}

/* Dynamic font selection */
html[lang="ar"] body {
  font-family: var(--font-arabic);
}

html[lang="en"] body {
  font-family: var(--font-english);
}
```

## Testing Approach

### Visual Verification
- [ ] Font hierarchy renders at correct sizes (H1=40px, H2=32px, H3=24px, Body=16px, Small=14px)
- [ ] Line heights display correctly (1.6 for body, 1.3 for headings)
- [ ] Font weights display correctly (Light 300, Regular 400, SemiBold 600, Bold 700)

### RTL/LTR Testing
- [ ] Arabic pages (`html[lang="ar"]`) use Cairo/Tajawal font family
- [ ] English pages (`html[lang="en"]`) use Montserrat/Lato font family
- [ ] Language toggle switches fonts correctly without page reload issues

### Performance Testing
- [ ] Network tab confirms `font-display=swap` in Google Fonts URL
- [ ] No FOIT (Flash of Invisible Text) - text displays with fallback then swaps
- [ ] Font files load from Google Fonts CDN successfully

### Browser Compatibility
- [ ] Fonts render correctly in Chrome, Firefox, Safari, Edge
- [ ] Fallback fonts (`sans-serif`) work if Google Fonts fails to load

## Definition of Done
- [ ] Font imports added to `resources/css/app.css`
- [ ] Typography variables added to `@theme` block
- [ ] Dynamic font selection CSS rules implemented
- [ ] Arabic fonts render correctly with RTL layout
- [ ] English fonts render correctly with LTR layout
- [ ] Font hierarchy visually verified on test pages
- [ ] Performance optimized (font-display: swap confirmed)
- [ ] All testing scenarios above pass
- [ ] Code formatted with Pint
- [ ] Assets rebuilt with `npm run build`

## Assumptions
- Google Fonts CDN is acceptable for font hosting (no self-hosting requirement)
- The `html[lang]` attribute is already set by the existing i18n system
- Story 9.1's `@theme` block is in place and working

## Notes for Developer
- **Extend, don't replace:** Add font variables to the existing `@theme` block from Story 9.1
- **Import order matters:** Place Google Fonts `@import` before the `@import "tailwindcss"` statement
- **Fallback fonts:** The CSS includes fallbacks (`'Tajawal'`, `'Lato'`, `sans-serif`) - these are intentional for graceful degradation

## Estimation
**Complexity:** Medium | **Effort:** 3 hours