How to typography css variables: naming conventions reference
- Step 1Generate with the default Tailwind names — Run the tool — it emits `--font-size-xs` through `--font-size-3xl` (more at higher step counts) by default. These are Tailwind-style size labels. There's no option to switch convention in the tool itself.
- Step 2Pick your target convention — Tailwind size names if your team uses Tailwind utilities; Material roles if you ship apps; Carbon's numbered hybrid for enterprise; or a custom semantic scheme. Decide before you remap so you only do it once.
- Step 3Remap the prefix with find-replace — Paste the output into your editor. For Tailwind-utility alignment, `--font-size-` → `--text-`. For Material, you'll instead alias roles to the size steps (Material is role-based, not a prefix swap).
- Step 4For role-based systems, alias rather than rename — Material/Carbon roles don't map 1:1 to size steps. Keep the generated `--font-size-*` as the value layer and add role tokens: `--md-sys-typescale-headline-medium: var(--font-size-2xl)`. The reference tables give sensible alias targets.
- Step 5Lock the case convention — CSS custom properties are case-sensitive and conventionally kebab-case (`--font-size-base`) — which is what the tool emits. If you also need camelCase (JS) or snake_case (Android), derive those in your build, not in the tool.
- Step 6Document the mapping — Record the generator's source names and your target names in design-system docs. Because regenerating is deterministic, the mapping stays valid across rebuilds.
What this generator names by default
The exact prefixes and labels the tool emits. There is no naming option and no rename UI — this is the starting point you remap from.
| Group | Prefix | Labels |
|---|---|---|
| Sizes | --font-size- | xs, sm, base, lg, xl, 2xl, 3xl, 4xl, 5xl, 6xl, 7xl, 8xl (up to your step count) |
| Weights | --font-weight- | light, regular, medium, semibold, bold, extrabold |
| Line heights | --line-height- | tight, snug, normal, relaxed, loose |
| Letter spacings | --letter-spacing- | tighter, tight, normal, wide, wider |
| Families | --font-family- | base, mono |
Major convention catalogue
How the big systems name type tokens. Use this to choose a target, then remap the generator's Tailwind-style output to it.
| System | Style | Example tokens |
|---|---|---|
| Tailwind | Size-based (matches generator) | text-xs (12px), text-base (16px), text-2xl (24px), text-4xl (36px) |
| Material Design 3 | Role-based, verbose | md-sys-typescale-display-large, headline-medium, body-large, label-small |
| IBM Carbon | Hybrid, numbered | body-01, heading-01–04, expressive-heading-01–06 |
| Atlassian | Functional | font-size-100, font-size-200, font-weight-bold |
| This tool | Size-based (Tailwind-style) | --font-size-base, --font-size-2xl, --font-weight-bold |
Mapping the generator's sizes to other systems
Suggested aliases from the generated Tailwind labels to each convention. Role systems alias; prefix systems find-replace. Sizes assume default 16px / Major Third.
| Generated | Tailwind | Material (role) | Carbon (role) |
|---|---|---|---|
--font-size-sm (0.8rem) | --text-sm | body-small | label-01 |
--font-size-base (1rem) | --text-base | body-large | body-01 |
--font-size-lg (1.25rem) | --text-lg | title-medium | heading-01 |
--font-size-2xl (1.953rem) | --text-2xl | headline-medium | heading-03 |
--font-size-3xl (2.441rem) | --text-3xl | display-small | heading-04 |
Cookbook
Remapping recipes. The generated output is always Tailwind-style; here's how to land it in any convention.
Generated default (Tailwind-style)
ExampleOut of the box. Size-based labels on the --font-size- prefix.
:root {
--font-size-xs: 0.640rem;
--font-size-sm: 0.800rem;
--font-size-base: 1.000rem;
--font-size-lg: 1.250rem;
--font-size-xl: 1.563rem;
--font-size-2xl: 1.953rem;
--font-size-3xl: 2.441rem;
}Remap to Tailwind --text- prefix
ExampleA single find-replace to align with Tailwind's utility naming. Purely mechanical.
# in your editor: replace `--font-size-` with `--text-`
:root {
--text-xs: 0.640rem;
--text-sm: 0.800rem;
--text-base: 1.000rem;
--text-lg: 1.250rem;
--text-2xl: 1.953rem;
}Alias to Material Design roles
ExampleMaterial is role-based, so you alias rather than rename. Keep the generated value layer; add a role layer on top.
/* keep generated values */
:root { --font-size-base: 1rem; --font-size-2xl: 1.953rem; --font-size-3xl: 2.441rem; }
/* add Material role tokens that point at them */
:root {
--md-sys-typescale-body-large: var(--font-size-base);
--md-sys-typescale-headline-medium: var(--font-size-2xl);
--md-sys-typescale-display-small: var(--font-size-3xl);
}Alias to IBM Carbon numbered roles
ExampleCarbon uses numbered roles. Same alias pattern; numbers map roughly to scale steps.
:root {
--body-01: var(--font-size-base);
--heading-01: var(--font-size-lg);
--heading-03: var(--font-size-2xl);
--heading-04: var(--font-size-3xl);
}Derive other cases for non-CSS targets
ExampleCSS stays kebab-case. JS/Android need other cases — derive them in your build, not the tool.
CSS (generated): --font-size-base JS (camelCase): fontSizeBase Android (snake): font_size_base # A build transform produces all three from the kebab source.
Edge cases and what actually happens
Every row below was probed against the live API. Some documented requirements (alphabetical axis order, numerical tuple order) are not actually enforced in practice — useful to know if you've been blaming the wrong thing for a 400.
Expecting a convention dropdown in the tool
Not supportedThere's no naming-convention option among the four controls (Family, Base size, Ratio, Steps). The output is always Tailwind-style size labels. Switch conventions by remapping after copy — find-replace for prefix systems, aliasing for role systems.
Looking for a rename button in the output
Read-onlyThe output panel is read-only; there's no in-tool rename or reorder. Copy or download the block, then rename in your editor. This is by design — the tool computes values, your editor handles naming.
Role count exceeds available size steps
Generate more stepsMaterial has many roles (display/headline/title/body/label, each large/medium/small). If you alias roles to steps and run out (only 7 steps generated), raise Steps up to 12 so larger labels exist, or alias multiple roles to the same step where sizes genuinely match.
Mixing conventions causes drift
AvoidHalf your components on --text-lg and half on --md-sys-typescale-title-medium is the worst outcome — nobody knows the canonical name. Pick one convention, remap the generator output to it once, and document it. The tool's consistent prefix makes the one-time remap easy.
Case mismatch breaks var() lookups
Case-sensitiveCSS custom property names are case-sensitive: --Font-Size-Base and --font-size-base are different properties. The generator emits lowercase kebab-case. If you derive camelCase for JS, do it in a build step — don't mix cases in CSS or var() will silently resolve to nothing.
2xl/3xl numeric labels in selectors
Valid--font-size-2xl starts a token name segment with a digit, which is fine for custom property names (they're not identifiers in the strict sense). It works in var(--font-size-2xl) everywhere. No need to rename 2xl to xxl unless your convention prefers it.
Atlassian-style numeric scale wanted
Remap by aliasAtlassian uses font-size-100/200/.... Alias the generated labels: --font-size-100: var(--font-size-sm), --font-size-200: var(--font-size-base), etc. The numeric system is just another alias layer over the same values.
Weight/line-height names don't match your system
Remap tooThe fixed groups use regular/medium/bold and tight/normal/loose. If your system uses numeric weights as token names or different leading labels, remap those prefixes/labels in your editor the same way you remap sizes — find-replace or alias.
Frequently asked questions
What naming convention does the tool output?
Tailwind-style size labels: --font-size-xs, sm, base, lg, xl, 2xl, 3xl (up to 8xl at higher step counts), plus fixed --font-weight-, --line-height-, and --letter-spacing- groups. There's no option to change the convention in the tool.
Can I rename tokens inside the tool?
No — the output panel is read-only. Copy or download the block and rename in your editor. For prefix conventions (Tailwind --text-), one find-replace does it; for role conventions (Material), you alias instead.
How do I convert to Material Design names?
Material is role-based, so alias rather than rename. Keep the generated --font-size-* as the value layer and add role tokens like --md-sys-typescale-headline-medium: var(--font-size-2xl). The mapping table gives sensible targets.
Which convention should I pick?
Tailwind if your team uses Tailwind utilities (it matches the generator out of the box). Material if you ship apps. A custom semantic scheme for full control. The worst choice is mixing — pick one and remap the generator output to it consistently.
Does changing names change the sizes?
No. Renaming or aliasing only changes labels; the rem values are untouched. You can migrate between conventions without recomputing the scale — same numbers, different names.
What about case conventions (kebab vs camel vs snake)?
CSS is kebab-case (--font-size-base), which is what the tool emits and what var() requires. camelCase for JS and snake_case for Android XML are derived in your build pipeline, not in the tool.
Are numeric labels like 2xl valid in custom properties?
Yes. --font-size-2xl is a valid custom property name and works in var(--font-size-2xl). Custom property names allow digits in segments. Rename to xxl only if your convention prefers it.
How do I map to IBM Carbon's numbered roles?
Alias the generated labels to Carbon roles: --body-01: var(--font-size-base), --heading-03: var(--font-size-2xl), etc. The numbered system sits as an alias layer over the generated values.
Can I map between conventions during a migration?
Yes. Keep both name sets pointing at the same generated values during the transition (--md-sys-typescale-body-large: var(--font-size-base)), migrate components, then drop the old names. The sizes never change.
Does the tool emit weight/line-height names too?
Yes — fixed groups: --font-weight-{light…extrabold}, --line-height-{tight…loose}, --letter-spacing-{tighter…wider}. If your convention names these differently, remap them in your editor the same way as sizes.
How many size labels can I get?
Up to 12, named xs through 8xl, controlled by the Steps slider (3–12). The base label always sits at scale index 2 regardless of how many steps you pick.
Is the naming reproducible across regenerations?
Yes — the labels and value formula are deterministic. Same inputs, same names and numbers, so a documented mapping stays valid whenever you regenerate.
Privacy first
Every JAD Font tool runs entirely in your browser using opentype.js and the wawoff2 WASM Brotli encoder. Your fonts never leave your device — verified by zero outbound network requests during processing.