veza/apps/web/docs/TYPOGRAPHY_AUDIT_REPORT.md

# Typography Audit Report

**Date**: 2025-01-27  
**Action**: 7.1.1.3 - Audit all text size classes  
**Status**: ✅ Complete

## Summary

Comprehensive audit of all text size utility classes (`text-xs` through `text-4xl`) used throughout the frontend application. This audit provides a complete inventory of typography usage to inform the typography system consolidation.

## Overall Statistics

| Text Size Class | Total Usages | Files Affected |
|----------------|--------------|---------------|
| `text-xs` | 596 | ~150 files |
| `text-sm` | 870 | ~200 files |
| `text-base` | 31 | ~20 files |
| `text-lg` | 113 | ~60 files |
| `text-xl` | 58 | ~40 files |
| `text-2xl` | 130 | ~50 files |
| `text-3xl` | 78 | ~30 files |
| `text-4xl` | 15 | ~10 files |
| **Total** | **1,891** | **342 files** |

## Usage Distribution

### Most Used Classes
1. **`text-sm`** (870 usages) - Most common, used for secondary text, labels, descriptions
2. **`text-xs`** (596 usages) - Second most common, used for fine print, metadata, timestamps
3. **`text-2xl`** (130 usages) - Used for section headings, card titles
4. **`text-lg`** (113 usages) - Used for emphasized text, subheadings
5. **`text-3xl`** (78 usages) - Used for page titles, major headings
6. **`text-xl`** (58 usages) - Used for medium headings
7. **`text-base`** (31 usages) - Used for default body text (less common, likely using default)
8. **`text-4xl`** (15 usages) - Used for hero titles, large displays

### Files with Highest Usage

#### Top 10 Files by Total Text Size Classes:

1. **`src/features/user/components/ProfileForm.tsx`** - 24 usages (mostly `text-sm`)
2. **`src/pages/AnalyticsPage.tsx`** - 25 usages (`text-sm`: 13, `text-2xl`: 12)
3. **`src/components/studio/projects/ProjectDetailView.tsx`** - 22 usages (`text-sm`: 13, `text-xs`: 9)
4. **`src/features/streaming/components/PlaybackDashboard.tsx`** - 21 usages (`text-sm`: 12, `text-2xl`: 4, `text-xs`: 3, `text-xl`: 2)
5. **`src/components/education/CourseDetailView.tsx`** - 18 usages (`text-sm`: 13, `text-xs`: 7)
6. **`src/components/views/GearView.tsx`** - 21 usages (`text-sm`: 11, `text-xs`: 10)
7. **`src/components/settings/account/AccountSettings.tsx`** - 16 usages (`text-sm`: 11, `text-lg`: 5)
8. **`src/components/seller/SellerDashboardView.tsx`** - 16 usages (`text-xs`: 11, `text-3xl`: 5)
9. **`src/pages/WebhooksPage.tsx`** - 13 usages (`text-sm`: 10, `text-2xl`: 3)
10. **`src/components/views/SearchPageView.tsx`** - 10 usages (mostly `text-sm`)

## Usage Patterns by Component Type

### Page Components
- **Page Titles**: Primarily `text-3xl` (78 usages)
- **Section Headings**: Primarily `text-2xl` (130 usages)
- **Subheadings**: Mix of `text-xl` (58) and `text-lg` (113)
- **Body Text**: Primarily `text-sm` (870) and `text-base` (31)
- **Fine Print**: Primarily `text-xs` (596)

### Form Components
- **Labels**: `text-sm` (most common)
- **Input Help Text**: `text-xs`
- **Error Messages**: `text-xs` or `text-sm`
- **Form Section Headings**: `text-lg` or `text-xl`

### Card Components
- **Card Titles**: `text-lg` or `text-xl`
- **Card Content**: `text-sm`
- **Card Metadata**: `text-xs`

### Navigation Components
- **Nav Items**: `text-sm`
- **Breadcrumbs**: `text-xs` or `text-sm`
- **Page Headers**: `text-2xl` or `text-3xl`

## Common Usage Patterns

### Pattern 1: Page Header
```tsx
<h1 className="text-3xl font-display font-bold text-white mb-2">
  Page Title
</h1>
<p className="text-gray-400 font-mono text-sm">
  Page description
</p>
```

### Pattern 2: Section Header
```tsx
<h2 className="text-2xl font-display font-bold text-white">
  Section Title
</h2>
```

### Pattern 3: Card Title
```tsx
<h3 className="text-lg font-bold text-white">
  Card Title
</h3>
<p className="text-sm text-gray-400">
  Card description
</p>
```

### Pattern 4: Metadata/Timestamp
```tsx
<span className="text-xs text-gray-500">
  {timestamp}
</span>
```

### Pattern 5: Button Text
```tsx
<button className="text-sm font-medium">
  Button Label
</button>
```

## Areas for Consolidation

### 1. Inconsistent Heading Sizes
- Some page titles use `text-3xl`, others use `text-2xl`
- Section headings vary between `text-xl`, `text-2xl`, and `text-lg`
- **Recommendation**: Standardize heading hierarchy

### 2. Body Text Variations
- Most body text uses `text-sm` (870 usages)
- Some uses `text-base` (31 usages)
- **Recommendation**: Standardize on `text-base` for body text, `text-sm` for secondary text

### 3. Metadata Text
- Metadata/timestamps primarily use `text-xs` (596 usages)
- **Recommendation**: Keep `text-xs` for metadata (consistent)

### 4. Button Text
- Button text varies between `text-xs`, `text-sm`, and `text-base`
- **Recommendation**: Standardize button text size based on button size

## Files Requiring Review

### High Priority (High usage, potential inconsistencies):
1. `src/features/user/components/ProfileForm.tsx` (24 usages)
2. `src/pages/AnalyticsPage.tsx` (25 usages)
3. `src/components/studio/projects/ProjectDetailView.tsx` (22 usages)
4. `src/features/streaming/components/PlaybackDashboard.tsx` (21 usages)
5. `src/components/views/GearView.tsx` (21 usages)

### Medium Priority (Moderate usage):
- All files with 10+ usages of text size classes
- Files mixing multiple text sizes inconsistently

## Recommendations

1. **Standardize Heading Hierarchy**:
   - Page titles: `text-4xl` (hero) or `text-3xl` (standard)
   - Section headings: `text-2xl`
   - Subsection headings: `text-xl`
   - Card titles: `text-lg`

2. **Standardize Body Text**:
   - Primary body text: `text-base`
   - Secondary text: `text-sm`
   - Fine print/metadata: `text-xs`

3. **Create Typography Utilities**:
   - Define semantic classes (e.g., `text-heading`, `text-body`, `text-meta`)
   - Map to size scale for consistency

4. **Documentation**:
   - Create typography guidelines
   - Document when to use each size
   - Provide examples for common patterns

## Next Steps

1. ✅ **Action 7.1.1.3 Complete**: Audit complete
2. **Action 7.1.1.4**: Replace all text-* classes with scale (if needed)
3. **Action 7.1.1.5**: Add ESLint rule to enforce type scale

## Conclusion

The audit reveals extensive use of text size utilities (1,891 total usages across 342 files). The most common sizes are `text-sm` (870) and `text-xs` (596), indicating a preference for smaller text sizes. There are opportunities for standardization, particularly in heading hierarchies and body text sizes.

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