veza/apps/web/docs/H1_ELEMENTS_AUDIT_REPORT.md

# H1 Elements Audit Report

**Date**: 2025-01-27  
**Action**: 7.1.2.1 - Audit all h1 elements  
**Status**: ✅ Complete

## Summary

Comprehensive audit of all `<h1>` elements used throughout the frontend application. This audit provides a complete inventory of h1 usage to inform heading standardization.

## Overall Statistics

| Metric | Count |
|--------|-------|
| **Total h1 elements** | 55 |
| **Files containing h1** | 52 |
| **Unique files** | 52 |

## Size Distribution

| Text Size Class | Count | Percentage | Notes |
|----------------|-------|------------|-------|
| `text-3xl` | 26 | 47.3% | Most common - used for page titles |
| `text-2xl` | 16 | 29.1% | Second most common - used for section titles |
| `text-4xl` | 10 | 18.2% | Used for hero/feature titles |
| `text-5xl` | 2 | 3.6% | Used for large displays |
| `text-6xl` | 2 | 3.6% | Used for very large displays (responsive) |
| `text-lg` | 1 | 1.8% | **Inconsistent** - Header logo (should be different) |
| **No explicit size** | 5 | 9.1% | Test files and some components |

## Usage Patterns

### Most Common Pattern: `text-3xl` (26 instances)
Used primarily for page titles:
- `AnalyticsView.tsx`
- `NotificationsView.tsx`
- `PurchasesView.tsx`
- `QueueView.tsx`
- `PlaylistsView.tsx`
- `DeveloperDashboardView.tsx`
- `WishlistView.tsx`
- `GoLiveView.tsx`
- `MyCoursesView.tsx`
- `CourseDetailView.tsx`
- `GroupDetailView.tsx`
- `LibraryPage.tsx`
- `DashboardPage.tsx`
- `WebhooksPage.tsx`
- `AnalyticsPage.tsx`
- `AdminDashboardPage.tsx`
- `SettingsPage.tsx` (multiple)
- `TrackDetailPage.tsx`
- `NotificationsPage.tsx`
- `MarketplaceHome.tsx`
- `SearchPage.tsx`

### Second Most Common: `text-2xl` (16 instances)
Used for:
- Section titles within pages
- Smaller page titles
- Sub-headings
- Examples:
  - `LiveView.tsx`
  - `LazyComponent.tsx`
  - `CourseLearningView.tsx`
  - `LiveStreamDetailView.tsx`
  - `DeveloperPage.tsx`
  - `QueuePage.tsx`
  - `ProfilePage.tsx`
  - `SocialPage.tsx`
  - `GearPage.tsx`
  - `SettingsPage.tsx`
  - `LivePage.tsx`
  - `EducationPage.tsx`

### Hero/Large Displays: `text-4xl` (10 instances)
Used for:
- Hero titles
- Feature highlights
- Large displays
- Examples:
  - `ProfileView.tsx` (responsive: `text-3xl md:text-4xl`)
  - `PlaylistDetailView.tsx` (responsive: `text-4xl md:text-6xl`)
  - `ProductDetailView.tsx` (responsive: `text-4xl md:text-5xl`)
  - `FullPlayer.tsx` (responsive: `text-4xl md:text-6xl`)
  - `EquipmentDetailView.tsx`
  - `CertificateModal.tsx`
  - `RegisterPage.tsx`
  - `LoginPage.tsx`
  - `DashboardPage.tsx`

### Very Large Displays: `text-5xl` and `text-6xl` (4 instances)
Used for:
- Design system demo
- Large hero displays (responsive)
- Examples:
  - `DesignSystemDemoPage.tsx` (`text-5xl`)
  - `PlaylistDetailView.tsx` (responsive: `md:text-6xl`)
  - `FullPlayer.tsx` (responsive: `md:text-6xl`)

### Inconsistent: `text-lg` (1 instance)
- `Header.tsx` - Logo text (should not be h1, or should use different size)

### No Explicit Size (5 instances)
- Test files (`accessibility.test.tsx`)
- Some components with inline styles or default sizes
- `DesignSystemDemo.tsx` (uses inline styles)
- `PlaylistHeader.tsx` (may use default)
- `AuthLayout.tsx` (may use default)

## Responsive Patterns

Several h1 elements use responsive text sizes:
- `text-3xl md:text-4xl` - ProfileView, CourseDetailView
- `text-4xl md:text-5xl` - ProductDetailView
- `text-4xl md:text-6xl` - PlaylistDetailView, FullPlayer
- `text-2xl sm:text-3xl` - ProfilePage

## Inconsistencies Identified

1. **Size Variation**: h1 elements use 6 different sizes (`text-lg`, `text-2xl`, `text-3xl`, `text-4xl`, `text-5xl`, `text-6xl`)
2. **Context Inconsistency**: Same contexts use different sizes:
   - Page titles: mix of `text-2xl`, `text-3xl`, `text-4xl`
   - Section titles: mix of `text-2xl`, `text-3xl`
3. **Header Logo**: Uses `text-lg` which is too small for h1 semantic meaning
4. **Missing Sizes**: Some h1 elements don't have explicit text size classes

## Files with Multiple h1 Elements

1. **`src/features/settings/pages/SettingsPage.tsx`** - 3 h1 elements
   - Line 122: `text-2xl`
   - Line 146: `text-2xl`
   - Line 178: `text-3xl`

2. **`src/pages/DesignSystemDemo.tsx`** - 2 h1 elements (inline styles)

## Recommendations

### Standardization Strategy

1. **Primary Page Titles**: Standardize to `text-3xl` (most common, 26 instances)
   - This is already the most common pattern
   - Good balance between prominence and readability

2. **Hero/Feature Titles**: Keep `text-4xl` for special hero sections
   - Use for landing pages, feature highlights
   - Can use responsive variants (`text-3xl md:text-4xl`)

3. **Section Titles**: Standardize to `text-2xl` for h2, not h1
   - If using h1 for sections, consider using h2 instead
   - Or standardize section h1 to `text-2xl`

4. **Very Large Displays**: Keep `text-5xl`/`text-6xl` for special cases
   - Design system demos
   - Large hero displays (with responsive fallbacks)

5. **Fix Inconsistencies**:
   - Header logo: Change from h1 with `text-lg` to appropriate semantic element or larger size
   - Add explicit sizes to h1 elements without them
   - Standardize page titles to `text-3xl`

## Files Requiring Standardization

### High Priority (Page Titles - Should be `text-3xl`):
1. `src/components/views/LiveView.tsx` - Currently `text-2xl`
2. `src/components/ui/LazyComponent.tsx` - Currently `text-2xl`
3. `src/pages/DeveloperPage.tsx` - Currently `text-2xl`
4. `src/pages/QueuePage.tsx` - Currently `text-2xl`
5. `src/pages/ProfilePage.tsx` - Currently `text-2xl sm:text-3xl` (should be `text-3xl`)
6. `src/pages/SocialPage.tsx` - Currently `text-2xl`
7. `src/pages/GearPage.tsx` - Currently `text-2xl`
8. `src/pages/SettingsPage.tsx` - Currently `text-2xl` (multiple)
9. `src/pages/LivePage.tsx` - Currently `text-2xl`
10. `src/pages/EducationPage.tsx` - Currently `text-2xl`
11. `src/features/settings/pages/SettingsPage.tsx` - Mix of `text-2xl` and `text-3xl`

### Medium Priority (Hero Titles - Review if should be `text-4xl`):
1. `src/pages/DashboardPage.tsx` - Currently `text-4xl` (may be appropriate)
2. `src/pages/RegisterPage.tsx` - Currently `text-4xl` (may be appropriate)
3. `src/pages/LoginPage.tsx` - Currently `text-4xl` (may be appropriate)

### Low Priority (Special Cases - May keep as-is):
1. `src/components/layout/Header.tsx` - `text-lg` (logo - should review semantic structure)
2. `src/pages/DesignSystemDemoPage.tsx` - `text-5xl` (demo page - acceptable)
3. Responsive hero titles (`text-4xl md:text-6xl`) - May keep for visual impact

## Next Steps

1. ✅ **Action 7.1.2.1 Complete**: Audit complete
2. **Action 7.1.2.2**: Standardize h1 across pages to `text-3xl` (with exceptions for hero sections)
3. **Action 7.1.2.3**: Standardize h2-h6 elements
4. **Action 7.1.2.4**: Standardize paragraph text sizes

## Conclusion

The audit reveals **significant inconsistency** in h1 element sizes:
- 6 different sizes used (`text-lg` through `text-6xl`)
- Most common is `text-3xl` (47.3%), which should be the standard
- 16 instances use `text-2xl` which may be too small for h1 semantic importance
- 1 instance uses `text-lg` which is clearly inconsistent

**Recommendation**: Standardize most page title h1 elements to `text-3xl`, with `text-4xl` reserved for hero sections and special displays.

**Action 7.1.2.1 Status**: ✅ Complete - Comprehensive audit documented