Skip to main content
skill CX Codex

typography-audit — Claude Code skill: typography audit

typography-audit reviews fonts, type scales, spacing, punctuation, and text layout. Use it for a focused typography check in a project or pull request.

MIT 1,200 installs ★ 216 updated 2026-10-24

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add mblode/agent-skills --skill typography-audit -a claude-code
Open on GitHub

What typography-audit does

typography-audit reviews web typography with 78 rules across 10 categories. It covers font loading and weights, text sizing and measure, rendered punctuation, spacing, hierarchy, layout, OpenType features, brand type, typeface pairing, and display text. Each finding includes a file, line, rule ID, and concrete fix.

The skill starts by scoping changed files or a requested full sweep. It maps code signals to rule prefixes, runs higher-impact groups first, then repeats only the rules that produced findings after changes. Pull request checks use the actual merge-base diff and can filter CSS, SCSS, HTML, TSX, JSX, and template files.

This stays within typography. It does not perform a broad UI review or choose a new type system; those requests belong to ui-design Audit or Direction. When a result depends on the font that actually loaded, verification through ui-verification is required.

What it helps with

  • audit font loading and available weights
  • spot bad type sizes and text measure
  • find incorrect punctuation in rendered copy
  • check hierarchy and spacing across text styles
  • review OpenType settings and font pairings

Example prompts for the agent

  • Audit the typography in the files changed by this pull request and report each issue with its file, line, rule, and fix.
  • Run a full typography review for font loading, text width, and line spacing.
  • After I apply the fixes, rerun only the rules that found issues and produce the final report.

How to install typography-audit

1Skills CLI (Vercel)

npx skills add mblode/agent-skills --skill typography-audit -a claude-code

2Manually: put the files in place

~/.claude/skills/typography-audit/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/typography-audit/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about typography-audit

How do I install typography-audit in Claude Code?

Run npx skills add mblode/agent-skills --skill typography-audit -a claude-code. The skill file will be at ~/.claude/skills/typography-audit/SKILL.md.

What does typography-audit do?

It checks web typography against 78 rules covering fonts, sizing, spacing, punctuation, hierarchy, layout, and related type details. Findings include the source location, rule ID, and a specific fix.

How is typography-audit different from ui-design Audit?

typography-audit is limited to typography. ui-design Audit covers broader frontend concerns such as accessibility, forms, and navigation.

Source text

SKILL.md · MIT
---
name: typography-audit
description: Audits font loading, type scales, measure, spacing, OpenType, and rendered punctuation with 78 scoped rules. Use when asked to "audit typography", "fix the fonts", or "review my type system". For a new visual direction use ui-design Direction; for general UI defects use ui-design Audit.
---

# Typography Audit

78 rules in 10 categories for web typography. Every finding names file, rule, and fix.

- **IS:** typography only: font loading, sizing, punctuation, spacing, hierarchy, text layout, OpenType features, typeface pairing, brand type, display type.
- **IS NOT:** broad UI review (accessibility, forms, navigation: use `ui-design` Audit mode), or a redesign (new typefaces, scales: use `ui-design` Direction mode).

## Audit Workflow

Track this checklist:

```text
Audit progress:
- [ ] Step 1: Scope. List changed files (or full sweep), map signals to categories
- [ ] Step 2: Run CRITICAL rules in scope (font-, size-, punct-)
- [ ] Step 3: Run HIGH rules in scope (spacing-)
- [ ] Step 4: Run remaining in-scope categories by descending priority
- [ ] Step 5: Report per the contract; every finding has file:line, rule ID, fix
```

1. Scope to changed files unless a full sweep is requested. For a PR, use the diff against its actual base merge-base, including committed changes, filtered to `.css`, `.scss`, `.html`, `.tsx`/`.jsx`, and template files.
2. Map code to categories via the signal table; skip categories with no signal.
3. Load rule files by prefix (`rules/font-*.md`, etc.), only for the categories the signals selected.
4. Run categories in priority order so CRITICAL findings surface even if the audit is cut short.
5. After fixes, re-run only the rules that produced findings, then finalize the report.

## Scoping Signals → Categories

| Signal in code | Categories to load |
|--------------------|--------------------|
| `@font-face`, `font-family`, font files, variable fonts, `font-stretch`, `transform: scaleX` on text | `font-` |
| `font-size`, `clamp()`, media-query type changes, `max-width` on text, `<em>`/`<strong>`, `text-decoration` | `size-` |
| Copy in HTML/JSX (headings, paragraphs, labels) | `punct-` |
| `line-height`, `letter-spacing`, `word-spacing`, `margin` on text, `text-transform: uppercase` | `spacing-` |
| Heading elements, type scale tokens, `--text-*` properties | `hierarchy-` |
| `text-align`, lists, blockquotes, multi-column text | `layout-` |
| `font-feature-settings`, `font-variant-*`, figures/fractions in copy | `opentype-` |
| Logo/wordmark styles, brand tokens, text color tokens, license comments | `brand-` |
| Two or more distinct `font-family` values | `pairing-` |
| Hero/display sizes, drop caps, `initial-letter` | `display-` |

## Rule Categories by Priority

| Priority | Category | Impact | Prefix | Rules |
|----------|----------|--------|--------|-------|
| 1 | Font Selection & Weights | CRITICAL | `font-` | 11 |
| 2 | Sizing & Measure | CRITICAL | `size-` | 6 |
| 3 | Punctuation & Special Characters | CRITICAL | `punct-` | 12 |
| 4 | Spacing & Rhythm | HIGH | `spacing-` | 8 |
| 5 | Hierarchy & Scale | MEDIUM-HIGH | `hierarchy-` | 8 |
| 6 | Alignment & Layout | MEDIUM | `layout-` | 6 |
| 7 | OpenType Features | MEDIUM | `opentype-` | 7 |
| 8 | Brand & Identity | MEDIUM | `brand-` | 8 |
| 9 | Typeface Pairing | MEDIUM | `pairing-` | 5 |
| 10 | Display & Headlines | LOW-MEDIUM | `display-` | 7 |

Category map and impact rationale: `rules/_sections.md`. Each rule file gives why it matters plus an incorrect and a correct example. Category impact reflects the category's worst-case rules; report findings with the rule's own frontmatter `impact`, which frequently differs (e.g. `brand-color` is HIGH inside the MEDIUM `brand-` category because it holds the WCAG contrast floor).

## Review Output Contract

Report findings as:

```markdown
## Typography Audit Findings

### path/to/file.css
- [CRITICAL] `punct-smart-quotes` (file.css:42): Straight quotes in heading copy.
  - Fix: Replace `"` with `&ldquo;`/`&rdquo;` (or UTF-8 curly quotes).
- [CRITICAL] `size-line-height` (file.css:18): `line-height: 20px`, a fixed value the 48px `h1` inherits, so its lines overlap.
  - Fix: Use unitless `line-height: 1.5`.

### path/to/clean-file.css
- ✓ pass
```

- Group by file; order by impact within file.
- Every finding: impact tag, rule ID, `file:line`, one-line issue, fix.
- Include clean files as `✓ pass` so coverage is visible.
- End with a summary: counts per impact level.

## Gotchas

- Don't preload every rule file. Load only the prefixes the signal table selects; a full load spends the budget on categories with no signal in scope.
- Report the rule's frontmatter `impact`, never the category's. Two rules get misreported most: `brand-color` is HIGH (an accessibility floor, not a brand nicety) and `punct-daggers` is LOW-MEDIUM (decoration, despite sitting in a CRITICAL category).
- Punctuation rules apply to rendered copy only. Flagging straight quotes or `--` inside `<code>`, `<pre>`, or JS/TS string literals is a false positive; "fixing" them breaks the code.
- Confirm the rendered font and computed styles through `ui-verification` when a finding depends on them. A CSS declaration alone does not prove which face loaded.
- Don't flag missing OpenType features without confirming the loaded font ships them. Browsers silently ignore unsupported `font-feature-settings` tags, so the fix does nothing.
- Every finding needs `file:line` and a concrete fix; an unactionable finding forces a redo.
- An audit is not a redesign. Proposing new pairings or scales turns a 10-minute review into a design project; flag the issue and route redesign asks to `ui-design`.
- Don't equalize priorities. A LOW-MEDIUM `display-` nit above a CRITICAL faux-bold finding buries what actually looks broken.

## Related Skills

- `ui-design` Audit mode: broad frontend quality (accessibility, forms, navigation, motion); its typography coverage is shallower.
- `ui-design` Direction mode: choosing typefaces, scales, and visual direction from scratch; run when a finding becomes a redesign request.
- `ghostwriter`: heading and label wording. This skill governs only the casing of that copy (`punct-case-rules`).

Maintenance only: `evals/evals.json` contains regression scenarios for changes to this skill; it does not load during a user task.

© mblode · MIT · mblode/agent-skills

Similar skills

All skills for Frontend and UI →

From the same set28

The whole set →
ui-animation This skill designs, reviews and measures interface motion, from springs and gestures to scroll effects. Use it when implementing or diagnosing UI animation. CX Codex +1 11,100installs multi-tenant-architecture multi-tenant-architecture designs tenant isolation, hostname routing, custom domains, and plan limits on Cloudflare or Vercel. Helps build multi-tenant SaaS and white-label platforms. CX Codex +1 1,900installs ui-design ui-design — a Claude Code skill that picks visual direction, builds React, Next and Tailwind interfaces, and audits shipped UI for defects. It also stress-tests components with worst-case data. CX Codex +1 1,600installs agent-skills-creator agent-skills-creator is a Claude Code skill for building and auditing portable Agent Skills. It tunes routing descriptions, removes redundant rules, and validates directories. CX Codex +1 1,100installs presentation-creator presentation-creator builds slide decks with narrative structure, slide copy, and speaker notes from raw ideas or docs. Outputs Marp markdown by default or web deck code. CX Codex +1 1,000installs product-design product-design — a skill that settles interaction choices, action scope, reversibility and reachable states before anyone builds the UI. Useful when a flow is still undecided. CX Codex +1 951installs agents-md A skill for Claude Code and five other agent tools. Audits instruction files, checks repository commands, and migrates projects to AGENTS.md as the shared source of rules. CX Codex +1 927installs scaffold-nextjs scaffold-nextjs scaffolds a complete Next.js Turborepo monorepo with Blode UI, Ultracite, workspace hooks, and Vercel deployment. CX Codex +1 817installs

Project sponsors

Companies that keep this analytics open