Role Naming

Role naming is the practice of labeling every font size by its functional purpose in the interface instead of its pixel value or visual position in a list. You create names like caption for tiny legal text, body for default reading copy, lead for introductory paragraphs, h4 for subsection titles, h3 for section titles, h2 for major sections, h1 for page titles, and display for hero statements. These names become the contract. Designers select from a locked list of text styles in Figma that use these exact names. Engineers import the matching classes or tokens in code. The modular scale with its chosen ratio and base size generates the actual rem values but those values stay hidden behind the role. Update the scale in December 2024 and every button, card, heading, and paragraph picks up the new sizes without anyone touching the component files. This approach mirrors how music uses named intervals instead of raw frequencies. The role tells you the job. The token delivers the execution. Material 3 uses display, headline, title, body, and label with large, medium, and small variants inside each role. Apple uses Large Title, Title 1, Headline, Body, Caption 1. Both companies have maintained these systems across multiple OS releases because the roles stay stable even as the underlying sizes shift with new hardware and accessibility needs.

Role naming is not t-shirt sizing. Tailwind launched with text-xs to text-9xl in 2017 and that system still dominates many codebases in 2024 but it describes only relative scale not purpose. A designer cannot tell an engineer to use text-2xl for a card title because text-2xl might map to something completely different after the next scale tweak. Role naming is not naming by raw output either. Calling something font-size-400 because it is the fourth step in your scale ties the name to an implementation detail that should remain free to change. It is not documentation theater where you list roles in a Notion page but never enforce them in the tools. Without variables and tokens the names become polite suggestions that get ignored the first time a deadline hits. It is not optional flavor text added after the scale exists. The roles must drive the scale creation from the beginning so the names shape the decisions instead of decorating them after the fact.

Concrete examples prove the difference. Stripe rebuilt their design system in 2023 around role names including ui-sm, ui, paragraph, heading, display, and hero. The roles connect directly to their 1.25 major third scale with 16px base. When they increased the base to 17px for better readability on their new billing pages the change required one token update. Every dashboard card title using the heading role updated instantly across hundreds of screens. No developer had to open 47 different components to hunt for hardcoded sizes. Vercel took the opposite tight approach with a 1.125 ratio for their 2022 dashboard refresh. Their roles include caption, label, body, subtitle, title, and display. The tight ratio keeps attention on data tables while the role names let their marketing site borrow the same system with different density modes. Linear.app in 2024 ships with an even more opinionated set. Roles like text-default, text-secondary, text-tertiary for body copy and specific heading roles allow them to adjust contrast and density per customer preference without rewriting any React components. Compare those wins to a typical Series B SaaS company in 2021. Their Figma files used freeform font sizes. Their codebase had 38 different rem values for headings alone. The quarterly redesign meeting always circled back to the same complaint. Nobody could defend why one heading was 22px and another 27px. After they finally adopted role naming in 2022 their governance meetings shrank from 90 minutes to 15 because the roles made every deviation visible and debatable. Exceptions received temporary names like hero-marketing-q3-2024 and got reviewed at the end of the quarter for promotion or deletion.

Use role naming the day you decide your type scale matters. Wire the roles into your semantic token layer between the raw sizes and the component specific bindings so components reference text-body and text-h3 instead of raw sizes. Use it when you have designers and engineers who need to speak the same language across multiple products or when you plan to support light, dark, and compact modes. The roles stay constant while the values shift underneath. Do not use it for one-off campaign microsites that get archived after launch. The contract adds overhead those projects never recoup. Avoid it if your team has no intention of using design tokens or linting rules because roles without enforcement tools turn into shelfware. Never run role names alongside Tailwind t-shirt classes in the same project. Pick one language destroy the other or watch them fight forever in code reviews. Review the role list every quarter. If a new use case appears add a new role through the governance process instead of letting anonymous sizes multiply.

Role naming turns your type scale from disposable numbers into the unbreakable contract that keeps your product typography consistent for years.