Type scale naming for small design systems

Type scale naming for small design systems

A four-person product team at a B2B SaaS company recently opened its Figma library and realized it had eleven type sizes, four of them within two pixels of each other, and three different ways of labeling the same heading level. The designer who built the library had left the company, the engineers had copy-pasted values from old branches, and the marketing site used yet another naming scheme. Rebuilding the type ramp took less than a week, but the conversation about what to call each step took longer than the ramp itself. Type scale naming for small design systems is mostly a decisions problem, and the right answer is the one your team can actually keep using.

This guide is for designers and developers working on a single product, a marketing site, or a small multi-product portfolio where one or two people own the system and the rest consume it. It covers the practical decisions: how to choose names, how to organize tokens, how to balance clarity with brevity, and how to keep the scale stable as the product grows. It draws on common patterns from open source systems, real-world style guides, and the day-to-day constraints that show up when a small team needs a type scale that survives the next six months without a second round of cleanup.

What “small” means in a type system

Before naming anything, it helps to define what “small” actually means. Most product teams call their system small when a few of the following are true:

• One to four products share the system, often built by a single design-engineering pair.
• The team has fewer than twenty engineers, designers, and writers combined.
• The library has fewer than three hundred components and fewer than fifty design tokens.
• Decisions get reviewed in a single Slack channel or weekly design crit, not a formal governance board.
• Releases happen weekly or faster, so renaming tokens means coordinating a deploy, not a quarterly plan.

These are not strict thresholds. A startup with eight people can have a more complex type system than a fifty-person product team, depending on the product surface and the number of locales. But if a single human can read the entire type scale on one printed page and explain it in under a minute, the system is almost certainly in the small range, and the naming approach in this guide is a good fit.

Large systems, in contrast, often need a formal taxonomy, a published governance process, version numbers, and deprecation rules that take months to execute. The naming patterns below deliberately stay flexible so that a small system can grow into a medium one without a full migration.

Why naming matters more than the scale itself

Most type scales fail in production because of naming, not because the ramp values are wrong. Designers and engineers rarely argue about whether 24 pixels or 28 pixels is the right body text size. They argue about whether the level above body should be called h3, heading-md, text-title, or title-100. When the names drift, the tokens drift with them. Three months later, the codebase has --font-h3-sm, --font-body-title, and --font-title-default, all pointing to the same value, and the team has lost the ability to reason about typography as a system.

Good naming is a forcing function. It makes the system easier to discuss, easier to extend, and easier to defend when a stakeholder asks why a particular text size is on a particular screen. It also makes handoffs cleaner. A developer who joins the project can read the token list and predict the visual hierarchy, even before opening a Figma file.

Two main naming patterns

There are two broad patterns used in production design systems, and most small systems sit somewhere on the spectrum between them. Choosing between them is the first real decision.

Semantic naming

Semantic names describe the role a piece of text plays in the interface. Examples include heading-xl, heading-md, body-lg, body-md, caption, and overline. The name tells you how the token is meant to be used, not what it looks like.

Semantic naming is the most common approach in established systems such as Material Design, IBM Carbon, and Atlassian Design System. It works well when the design intent is stable, when the same role appears in many components, and when the team is comfortable with the rule that a token’s name should not change just because the visual treatment does.

The main risk is that semantic names can lie. A caption token that gets reused for a primary call to action because it happens to be the right size is a failure of the system, not a feature. Semantic naming also struggles when one product needs two visually distinct elements that share the same role, for example a marketing-style hero heading and an in-app dashboard heading.

T-shirt naming

T-shirt names describe the size relative to other sizes, not the role. Examples include font-size-2xs, font-size-xs, font-size-sm, font-size-md, font-size-lg, font-size-xl, and font-size-2xl. The names are abstract, and the design system documentation maps each size to one or more use cases.

T-shirt naming is popular in engineering-driven systems because the tokens are easy to iterate on. If the product needs an extra-large body size, the team can add font-size-3xl without rewriting a single semantic rule. Tailwind CSS, which has heavily influenced design system practice over the last few years, popularized this pattern. The main risk is that consumers have to memorize the mapping between md and “the body text I want”, which can hurt designer adoption.

Hybrid naming

Most small systems end up using a hybrid. T-shirt tokens describe the raw size, and semantic aliases describe the recommended role. A developer might write var(--font-size-md) directly in a low-level component and var(--font-text-body) in a product-level component. Both point to the same value, and the mapping lives in the token definition file.

Hybrid naming is more work to set up but pays off once the system has more than a handful of components. The team gets the iteration speed of t-shirt tokens and the documentation clarity of semantic tokens, at the cost of one extra layer of indirection.

Pattern	Best for	Risk	Example
Semantic only	Stable product surface, design-led team	Tokens can lie if reused outside their role	heading-md
T-shirt only	Engineering-led team, fast iteration	Consumers must learn the mapping	font-size-md
Hybrid	Growing product, multiple consumers	Extra layer, two names per value	font-size-md aliased to text-body

Designing the scale before naming it

Naming is easier when the underlying scale is stable. Before deciding on labels, lock down the actual sizes, weights, and line heights. A few practical steps help:

1. Audit the current text in the product. Pull screenshots, list the sizes, group by visual role, and ignore the existing names.
2. Decide on the number of steps. Most small systems need between five and nine steps. More than nine usually means at least two steps are too similar to be useful.
3. Pick a modular ratio or a hand-tuned ramp. Common ratios include 1.125 (major second), 1.2 (minor third), 1.25 (major third), 1.333 (perfect fourth), and 1.5 (perfect fifth). A hand-tuned ramp is often better for dense product UI because product text is read for long stretches.
4. Choose a base size. Sixteen pixels is the most common body size for desktop web. Fourteen pixels is common for dense data tools. Mobile-first systems often anchor on fifteen or sixteen pixels.
5. Round to half pixels or to whole pixels, depending on what the rendering engine actually shows. Half-pixel rounding usually looks better on retina displays and looks acceptable on standard displays.
6. Define line height per step or as a global rule. Many systems use a line height that is roughly 1.2 to 1.5 times the font size, with longer line heights at smaller sizes and shorter line heights at larger sizes.

Once the scale is stable, the naming conversation becomes a question of labeling, not of negotiation. This is the part of the process that saves the most rework.

A practical naming recipe for small systems

The following recipe is what we recommend as a default for a small product team. It is intentionally conservative, opinionated, and easy to extend. To place this section in context, the Cadence Design offers a concise background reference.

Step 1: pick a prefix

Every type token should start with a prefix that signals the category. font- is the most common. text- is a popular alternative. type- is also fine. The prefix is what lets the team filter the token list and find every type-related value in one place. A common mistake is to mix font-size- and text-size- in the same project, which makes the system feel improvised.

Step 2: choose between size-only and role-first names

If the team is small and the products share a strong visual language, role-first names are usually clearer. If the team is small but the products are visually diverse, size-first names are usually safer. For most early-stage product teams, role-first names win, because the team is more likely to ask “what role is this” than “what is the next size up”.

Step 3: define a fixed list of roles

Most small systems can be covered by a fixed list of between six and ten roles. A reasonable starting list looks like this:

• display for the largest marketing or hero text, used once or twice per page.
• heading-lg for top-level section headings.
• heading-md for second-level headings.
• heading-sm for third-level headings and dense list headers.
• body-lg for the most important body text, such as article leads or modal descriptions.
• body-md for standard body text.
• body-sm for secondary text, captions, and supporting copy.
• caption for labels, helper text, and small print.
• overline for small, uppercase, letter-spaced labels.
• code for inline and block code.

The exact list is less important than the discipline of keeping the list short and stable. Each role should correspond to a real use case in the product, and each use case should map to a single role.

Step 4: decide on token grammar

Token grammar is the rule that turns a role into a full token name. Three common grammars work well for small systems:

• font-{role}, for example font-heading-md. Short, role-first, easy to scan.
• font-size-{role}, for example font-size-heading-md. More explicit, but verbose.
• text-{role}, for example text-body-sm. Common when the design system is built around utility classes, as in Tailwind-style systems.

The grammar should match the rest of the token system. If the team already uses color- and spacing- prefixes, sticking with font- keeps the system consistent. Mixing text- and font- is a frequent source of inconsistency and is worth resolving early.

Step 5: separate size, weight, and line height

Every text style is a combination of size, weight, line height, letter spacing, and sometimes a font family. Most small systems express this either as a single composite token or as a set of base tokens plus a style token.

A composite token looks like text-body-md and bundles size, weight, and line height. A base-plus-style approach looks like font-size-md + font-weight-regular + line-height-md. The composite approach is friendlier for designers and front-end developers. The base-plus-style approach is friendlier for design tools and theme switching.

For a small system, the composite approach is almost always the right default. It cuts the cognitive load on consumers, who do not need to know which weight pairs with which size. It also makes it harder to combine tokens in a way that the design system does not support.

Role	Size (px)	Weight	Line height	Token
display	48	700	1.1	font-display
heading-lg	32	700	1.2	font-heading-lg
heading-md	24	600	1.3	font-heading-md
heading-sm	20	600	1.3	font-heading-sm
body-lg	18	400	1.5	font-body-lg
body-md	16	400	1.5	font-body-md
body-sm	14	400	1.5	font-body-sm
caption	12	500	1.4	font-caption
overline	12	600	1.2	font-overline
code	14	400	1.6	font-code

Common naming pitfalls and how to avoid them

Most naming problems show up in the same handful of ways. The following list covers the ones that cost the most time to fix later.

Mixing numeric and t-shirt scales

It is tempting to label a scale with both font-size-100 through font-size-900 and font-size-sm through font-size-xl. Pick one. Numeric scales are easier to sort in a token list. T-shirt scales are easier to extend. The team should choose the one that fits the workflow and stop there.

Naming tokens after screens

Tokens called font-dashboard-title or font-pricing-hero tie the system to specific screens. As soon as the design changes, the token names lie. Roles are more durable than screens.

Using heading levels from HTML

Some teams name tokens h1, h2, and so on. This can be convenient, but it bakes an assumption into the system that the visual hierarchy will always match the document hierarchy. In product UI, that is rarely true. A card title might be an h3 in the DOM but visually larger than the page h2. Role names decouple the visual scale from the heading levels.

Overloading the word “default”

Tokens like font-body-default and font-body-md tend to point to the same value, and the team slowly forgets which one is the canonical name. Pick one name per role. If the team is not sure which is the default, the system is not finished.

Adding a token for every new use case

If a new feature needs an oddly specific size, the temptation is to add a token for it. Resist this for as long as possible. Most “one-off” sizes turn out to be either a step in the existing scale or a sign that the scale needs one more step. Adding a token for every exception produces a library of thirty sizes that no one can navigate. Another relevant reference is the cadence taps ai technology to speed, which adds context without changing the practical guidance here.

How naming connects to accessibility and components

Type scale naming has real consequences for accessibility. A semantic name like body-md sets an expectation: this token is for reading, so its contrast, line height, and size should all support that. A t-shirt name like font-size-md sets a different expectation: this is a building block, and the consumer is responsible for using it in an accessible way.

In practice, this means that semantic naming nudges the design system itself to enforce accessibility, while t-shirt naming pushes the responsibility to the consumer. Neither is wrong, but the team should make the choice on purpose, not by accident. The practical guide to inclusive design on this site is a useful companion read for teams that want to make sure their type scale supports real users.

Type scale naming also affects how components are organized. A button component, for example, often has a label size that depends on the button’s size and the surrounding context. If the design system has clear role names, the button can document which role is used for each variant. If the names are t-shirt sizes, the button has to describe the relationship, which is more work and more error-prone.

When to introduce a hybrid layer

A small system does not need a hybrid layer on day one. A single set of well-named semantic tokens will cover most needs. The hybrid layer becomes useful when one of the following happens:

• The team starts building a second product that shares tokens but not all roles.
• The team realizes that the same role is being visually customized in too many components.
• The design system has to support multiple themes, such as a default theme and a high-contrast or compact theme.
• The engineering team wants to consume raw sizes for performance or animation reasons, and the design team wants to consume roles for clarity.

When that happens, introduce a layer of t-shirt or numeric tokens below the semantic layer, and have the semantic tokens reference the t-shirt tokens. The hybrid pattern is not a goal in itself. It is a tool the team can reach for when the system starts to bend under the weight of custom use cases.

A worked example: renaming a real scale

To make the recipe concrete, here is a short worked example. Imagine a small product with a design system that currently uses the following tokens, inherited from a marketing site, an admin tool, and a long-running prototype:

• font-hero
• font-title-big
• font-section-title
• font-card-title
• font-body-1
• font-body-2
• font-body-3
• font-caption
• font-label

Auditing the actual usage, the team finds that font-section-title and font-card-title are visually identical, that font-body-2 is the de facto standard body size, and that font-label is only used in one form. The team also finds that the marketing team wants a much larger display size for the homepage hero, which the current scale does not support.

After the audit, the team agrees on the following rules:

1. Every token will start with font-.
2. Every token will be named by role, not by screen or component.
3. Body sizes will be font-body-lg, font-body-md, and font-body-sm.
4. Heading sizes will be font-heading-lg, font-heading-md, and font-heading-sm.
5. Marketing-only text that does not appear in the product will use a separate font-display token, with a comment that it is not for in-product use.

The team rewrites the scale in this order: font-display, font-heading-lg, font-heading-md, font-heading-sm, font-body-lg, font-body-md, font-body-sm, font-caption, and font-code. Old tokens are kept as deprecated aliases that point to the new tokens for one release, then removed.

The migration takes two engineers a day. The longer benefit is that the next time a designer asks for a new heading size, the team has a clear rule to apply: pick a role, check the scale, and either reuse an existing token or add a new one with a role name.

Documentation that supports the names

Names are only useful if the team can look up what they mean. For a small system, a single page of documentation is enough. The page should answer four questions for every token:

1. What is the role of this text, and where should it appear?
2. What is the actual rendered size, weight, and line height?
3. What is the recommended use case, with one or two concrete examples?
4. What should the token not be used for?

The last question is the most important and the most often skipped. Saying that font-display should not be used inside dense product UI sets a guardrail that prevents the system from drifting. Without it, the next marketing hire will happily use the largest available size for a tooltip, because the documentation did not say not to.

Type scale naming for small design systems in practice

The most useful way to think about type scale naming for small design systems is as a short contract between designers and developers. The contract says: every piece of text in the product corresponds to a role, every role has a name, every name has a value, and every value has a documented use case. When the contract is broken, the system shows it: a label in the wrong size, a heading at the wrong weight, a caption used as a primary call to action.

Small systems benefit from this kind of contract because the people who write the code and the people who design the screens are often the same person, and the cost of a miscommunication is one afternoon, not one quarter. The naming rules in this guide are designed to keep that cost low by making the most common decisions obvious and the rarer decisions explicit.

Teams that work on a practical design system for product teams usually discover that the same naming rules apply to color, spacing, and elevation. The investment in a clear type scale pays off as a template for the rest of the system, especially when the next category the team has to design is a familiar one with its own set of “sm, md, lg” decisions.

A short checklist before you ship the names

Run through this list before declaring the type scale done. Each item is a question the team should be able to answer with a yes.

• Every token starts with the same prefix, and that prefix matches the rest of the token system.
• Each token name describes a role, not a screen, component, or visual feature.
• The list of tokens fits on one printed page, with no duplicates and no off-scale values.
• Every token has a documented size, weight, line height, and a one-sentence use case.
• Every token has a documented “do not use for” note, especially for the largest and smallest sizes.
• The naming pattern is consistent with the patterns used for color, spacing, and elevation.
• Old token names are deprecated with a clear plan for removal, not left in the codebase indefinitely.

If the team can answer yes to all seven, the type scale is ready. The next challenge is keeping it that way, and that is mostly a matter of saying no to new tokens for as long as the existing ones still do the job.

Frequently asked questions

How many steps should a small type scale have?

Most small type scales work well with between five and nine steps. Fewer than five tends to leave the team without enough room for hierarchy, and more than nine usually means the team has not yet agreed on which steps are actually distinct. Start with seven and adjust based on real product needs rather than theoretical cases.

Should I use semantic or t-shirt names for a small system?

For most small systems, semantic names are the better default. They tell consumers what the text is for, which is usually the question the consumer is trying to answer. T-shirt names are a good fit for engineering-heavy teams that prefer to iterate on raw values. A hybrid layer is worth introducing only when the system has clearly outgrown a single pattern.

Can I keep the existing h1, h2, h3 names from the marketing site?

You can, but it usually causes more problems than it solves. Heading levels from HTML describe document structure, while type scale roles describe visual hierarchy. In a product, the two often disagree. Renaming the tokens to roles is a small amount of work that pays off every time the product evolves.

What is the difference between font-size and font tokens?

A font-size- token holds a single value, usually in pixels or rems. A font- or text- token often bundles size, weight, and line height into one composite. Composite tokens are friendlier to consumers because they prevent inconsistent combinations of size and weight.

How do I handle marketing-only type styles in a product design system?

Give them a clearly named token such as font-display or font-marketing-hero, document that they are not for product use, and keep them in a separate file or layer if possible. The most important part is the documentation, because without it the marketing styles will quietly leak into the product.

Should line height be part of the type scale or a global rule?

For most small systems, line height is part of each style. A body-md token should know its own line height, because the right line height for body text is not the right line height for display headings. Some systems also expose a global line-height scale for cases where a component needs to override the default.

How do I keep the type scale from growing over time?

Make adding a new token a deliberate decision. Require a short justification, a real use case that the existing scale cannot cover, and a default token to be deprecated. The friction of the process is the point. It is much easier to add a token than to remove one.

What if my team already has a different scale for mobile?

That is normal. Many small systems define two scales, one for mobile and one for desktop, and let the consuming component pick the right one through a media query. The naming pattern can be shared, so the team still talks about font-body-md, but the value changes between breakpoints.

Do I need a separate token for monospace or code text?

Yes, in most systems it is worth a dedicated token. Code text usually has a different font family, and sometimes a different size, and lumping it into a generic body or caption token makes it hard to update later. A font-code token with a clear note about when to use it is usually enough.

How do I explain the naming pattern to a stakeholder who is not on the design team?

Show them a single page that lists every token, the rendered size, and one example. Keep the explanation to two or three sentences. Stakeholders usually do not need to memorize the names, only to understand that the names are stable and the team is intentional about them. A printed one-pager is often the most effective artifact.

Related reading

• Web accessibility: a practical guide to inclusive design
• Gaming setup: a practical guide to building a balanced station