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

<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

<h2 className="text-2xl font-display font-bold text-white">
  Section Title
</h2>

Pattern 3: Card Title

<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

<span className="text-xs text-gray-500">
  {timestamp}
</span>

Pattern 5: Button Text

<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