How to audit typography in a legacy codebase

This guide walks through audit typography in a legacy codebase in enough detail that you can do it on a real project today, not just read about it.

Before you start, agree on the goal. A pragmatic checklist that surfaces drift, dead weights and accessibility debt in a day. If you cannot answer 'what would success look like in one sentence?', stop and write that sentence first — every later decision will come back to it.

Set up your environment. You want a clean working file, a way to preview the result in context, and a small representative sample of real content. Designing in lorem ipsum will mislead you almost every time.

Start with the smallest viable scope. Pick one screen, one wordmark, one page of body copy. Solving it there means you can roll the answer outward with confidence, instead of refactoring the whole system mid-stream.

Make the first decision deliberately. Whether that is the base size, the master weight, or the headline font, treat it as a hypothesis you will defend with examples. Write the reason in a comment or sticky next to the artefact.

Now iterate against real content. Resize the browser. Switch devices. Read the page out loud. The defects you cannot see at desk distance are the ones that ship and embarrass you later.

Pay specific attention to the edges. Long names, short labels, numbers in tables, RTL examples, dark mode. The middle of the distribution is easy; the tails are where typography quietly breaks.

Bring in a second set of eyes early. A teammate who has never seen the work will spot the things you have stopped noticing. Five minutes of fresh feedback saves an afternoon of solo doubt.

Document the decision before you ship. A two-line note in the design system — 'we use this font at this size for this reason' — is what stops the next person from undoing your work in six months.

Ship a small version, then live with it. Most typographic mistakes only become obvious after a week of real use. Build the muscle of revisiting decisions instead of treating them as final.

Measure where you can. Page weight, render time, contrast ratios and reading speed are all quantifiable, even informally. Numbers turn taste arguments into design conversations.

Finally, share what you learned. A short internal write-up, a tweet, a paragraph in your team wiki — the act of explaining the decision cements it for you and helps the people who come next.

If you spend any time looking at finished work you admire, you start to notice that the typography is rarely accidental. How to audit typography in a legacy codebase is part of that quiet discipline, and it lives at the intersection of taste and the craft of using type well.

Designers, founders and developers all benefit from getting this right. A quick spin through Montserrat is usually enough to see how much variety there is between families that look superficially similar — and how much that variety changes the feel of a finished interface.

The mistake is treating typography decisions as one-off choices. In reality they compound. The font you pick today drives the rhythm of every screen, every email and every PDF you ship for the next several years. Thinking with Type by Ellen Lupton is a good outside read on why those early calls matter so much.

Imagine you are redesigning the landing page of a small SaaS product. You have a hero, a feature grid, a pricing table and a footer.

Applying the ideas from How to audit typography in a legacy codebase starts with a single decision and ripples outward. You pick a primary family — often something proven like the sans-serif collection — lock in a small set of weights, and define how those weights map to roles in the interface. Headlines get one weight, body another, captions a third. Nothing else is allowed without an explicit reason.

From there you tune the scale. Set a comfortable body size for your audience — usually 16 to 18 pixels on the web, larger on long-form sites — and build a modular scale upward. Use weight and colour to handle secondary hierarchy instead of inventing new sizes. The result feels disciplined without feeling rigid.

Finally, test in context. Open the design at multiple viewports, in light and dark modes, with realistic content rather than lorem ipsum. If a candidate fails the real-content test, swap it for an alternative from the Microsoft typography glossary and try again — typography decisions that look elegant in a Figma mockup sometimes collapse the moment real headlines arrive.

Once you start paying attention, the same handful of mistakes show up in almost every project that drifted off course. They are easy to fix once you notice them, and even easier to avoid the next time — and MDN's text styling fundamentals catalogues several of them with examples worth bookmarking.

Mixing too many families. Two is usually plenty; three is occasionally justified; four is almost always a mistake. The more families you add, the more accidental visual noise you create.

Forgetting about numerics. Tabular figures keep tables aligned; proportional figures look better in running text. Most quality families ship both, and most designers never switch them on.

Loading too many weights. Every additional file slows the page and dilutes the system. Audit your real usage and cut anything you cannot point to in a layout.

None of these pitfalls are dramatic on their own. The trouble is that they accumulate quietly until one day the design feels tired and nobody can point to a single reason why. A short, regular audit catches all of them.

Before you ship the next iteration of your design, run through a short checklist. It takes five minutes and prevents most of the typography regressions that creep in over time.

First, count your fonts. If you cannot justify every family and every weight in one sentence, remove the ones you cannot defend — the Microsoft typography glossary is a useful reference to sanity-check what each family actually offers. Second, verify your hierarchy by squinting at a representative screen — the most important element should still be the most prominent, even at low fidelity.

Third, check the long content. Open the longest paragraph in the product and read it out loud. If you stumble, the line-height, measure or size is probably wrong. Fourth, test at extremes — the longest possible heading, the shortest possible label, an empty state, a localized translation. Typography that survives the extremes survives everything else.

Fifth and last, make sure the system is documented. A single page that lists your fonts, weights, sizes and rules saves more design time than any tool — the Google Fonts knowledge base has a thoughtful take on writing those rules down without turning the doc into a chore.

In a mature design system, typography is one of the first tokens to stabilise and one of the last to get revisited. That makes sense — once your team has agreed on a scale and a set of roles, those decisions touch every product surface and every channel. They become part of design systems in general rather than a layer painted on top.

Tokens give you the leverage. Instead of hard-coding pixel sizes everywhere, you define a token like text-body or text-heading-lg and let components reference it. When you decide to bump body up by one step — or swap the underlying family for something from Type Together's articles — you change one number and ship.

Roles matter more than sizes. Two tokens that happen to be the same size today might diverge tomorrow because they represent different intentions. Naming by role — caption, body, lede, headline — protects you from the temptation to merge them whenever the numbers happen to align.

Finally, write down the why. A token system without documentation eventually drifts. A token system with a paragraph next to each entry survives team changes, redesigns and rebrands.