/typography-audit

name: typography-audit
description: 'Use when asked to audit typography across a codebase. Produces a file:line report with concrete fixes ordered by impact and flags unverifiable rules. Not for building a type system or token scale.'

Typography audit

Contract

| Field | Bound contract | |---|---| | Trigger | User says audit my typography, fix the fonts, review my type, font pairing, type scale, or web typography | | Authority | Human-gated: applies fixes only when the user explicitly requests them; otherwise read-only with no file, VCS, credential, paid, published, deployed, or remote mutation. | | Side effect | Chat output: file:line findings with concrete CSS/HTML fix suggestions, plus not-verifiable-from-source verdicts for rules that need rendered metrics | | Done | Report covers all 10 categories; every finding is either a verified file:line violation with a concrete fix or a not-verifiable-from-source verdict naming the rendered metric that would decide it; findings are ordered by impact with no fabricated file:line violations |

Inputs

• Project directory or file set to audit (required). Accept a path, glob, or the current working directory.
• Optional: brand guidelines, style guide, or design tokens file if available.
• Optional: specific category filter (e.g., only spacing, only font) to narrow scope.

Procedure

1. Collect all CSS, SCSS, Less, HTML, JSX, TSX, Vue, and Svelte files in scope. Skip node_modules, dist, build, vendor, and .git directories. **Done when:** every in-scope source file is collected or reported unreadable. 2. For each file, extract font-family declarations, font-size values, line-height values, letter-spacing values, color declarations on text elements, @font-face blocks, font-feature-settings, and typographic HTML elements (h1-h6, p, blockquote, ul, ol, li, em, strong, small, sup, sub, abbr, cite, q, dl, dt, dd). **Done when:** every collected file has its typographic surface extracted. 3. Audit against the following 10-category rule set. For each violation found, record the file path, line number, rule name, severity (critical/high/medium/low), and a concrete CSS or HTML fix. When a rule's verdict depends on rendered metrics that static source cannot decide, record the finding as not-verifiable-from-source: name the rule, the files and declarations examined, and the rendered metric that would decide it. Rules that commonly need rendered facts include size-line-length (measure depends on font metrics and container width), layout-widows-orphans and layout-optical-balance (line breaking), pairing-contrast-harmony and pairing-stress-skeleton (x-height and stress need glyph or font-metric inspection), brand-dark-backgrounds (contrast when colors resolve through custom properties the scan cannot statically resolve), display-grid-breaking (baseline rhythm is rendered), and display-drop-caps (rendered cap metrics). Never force a file:line verdict for a rendered-metric rule. **Done when:** all 10 categories have been checked, with every finding either verified at file:line or recorded as not-verifiable-from-source.

Category 1: brand identity

1. **brand-capitalization**: Check that brand names use their canonical casing. Flag all-caps or all-lowercase brand names in user-facing text. 2. **brand-color**: Verify text colors align with brand palette. Flag hardcoded colors that deviate from declared brand tokens or CSS custom properties. 3. **brand-cross-medium**: Ensure typographic choices work across screen and print. Flag pixel-only units in @media print blocks. 4. **brand-dark-backgrounds**: Check that text on dark backgrounds meets contrast requirements (WCAG AA 4.5:1 for body, 3:1 for large text). Flag insufficient contrast. 5. **brand-equity**: Verify that brand typeface is used consistently for primary headings and identity elements. Flag mixing of competing display faces. 6. **brand-identifiable-body**: Ensure the body typeface is distinct from the brand/display typeface to maintain visual hierarchy. 7. **brand-licensing**: Flag @font-face declarations that reference fonts without verifiable licensing (e.g., fonts served from unauthorized CDNs or local paths without license documentation). 8. **brand-logo-typeface**: Verify that logo text or wordmarks use the designated brand typeface or are set as SVG/images, not restyled body fonts.

Category 2: display and headlines

1. **display-drop-caps**: Flag drop-cap implementations that use font-size alone without adjusting float, line-height, and margin. Suggest ::first-letter with proper metrics. 2. **display-grid-breaking**: Check that display text respects grid baselines. Flag headline sizes that break vertical rhythm without compensating margin. 3. **display-headline-opentype**: Verify headlines enable stylistic alternates or ligatures when the typeface provides display-specific features. Flag raw text that misses available opentype display features. 4. **display-headline-spacing**: Flag headlines with default tracking. Display text at large sizes typically needs tightened letter-spacing (e.g., -0.01em to -0.03em). 5. **display-large-type**: Check that text above 48px uses appropriate line-height (1.0-1.2) and adjusted letter-spacing. Flag body-style line-height on display text. 6. **display-lead-paragraph**: Verify lead/intro paragraphs have distinct styling (larger size, lighter weight, or increased line-height) from body text. 7. **display-swashes**: Flag swash characters or stylistic sets applied to body text. Swashes belong only in display contexts with controlled line breaks.

Category 3: font selection and setup

1. **font-body-selection**: Verify body text uses a typeface designed for sustained reading (e.g., Georgia, Merriweather, Source Serif, Inter). Flag decorative or display faces on body text. 2. **font-condensed-extended**: Flag condensed or extended widths used for body text. These belong in display or UI contexts only. 3. **font-face-setup**: Check @font-fa