reviewed epic 9 stories

docs/stories/story-9.2-typography-system.md

@@ -3,6 +3,12 @@
 ## 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**,
@@ -32,8 +38,12 @@ So that **the platform feels polished and content is easy to read**.
 
 ## 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 */
+/* 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 {
@@ -60,13 +70,48 @@ html[lang="en"] body {
 }
 ```
 
+## 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
-- [ ] Fonts load correctly
-- [ ] Arabic fonts work with RTL
-- [ ] English fonts work with LTR
-- [ ] Font hierarchy applied
-- [ ] Performance optimized
-- [ ] Tests pass
+- [ ] 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