> ## Documentation Index
> Fetch the complete documentation index at: https://substrate.docs.unknowncreatives.studio/llms.txt
> Use this file to discover all available pages before exploring further.

# Typography Token Reference

> Substrate's continuous type system: one base size, a computed effective ratio, semantic text roles with fractional exponents — no named size ladder.

Substrate has **no named type-size tokens** — no `xs`/`sm`/`md` ladder. Font size is a continuous function: a base size raised to a power of a computed ratio, where the exponent comes from the element's **text role** and the ratio itself responds to the user's `typeScaleFactor` preference at runtime.

## The computed scale

The root of the system is one expression, from `generated/global/css/tokens.gen.css`:

```css theme={null}
--effective-ratio: calc(1 + (var(--scale-ratio) - 1) * var(--type-scale-factor));
```

* `--scale-ratio` is the brand's modular ratio (`typography.scale-ratio`; the demo brands ship values from 1.2 to 1.25).
* `--type-scale-factor` is the user's continuous type-scale preference (0.9 → 1.4, default 1).

Each surface then computes its size — this is real generated component CSS:

```css theme={null}
--_computed: round(nearest, calc(var(--font-size-base) * pow(var(--effective-ratio), var(--_font-scale))), var(--font-size-quantum, 0.25rem));
--surface-font-size: var(--_computed);
```

`--font-size-base` comes from `typography.base-font-size` — a **rem** number (every bundled demo brand uses `1`). Sizes are quantized to `--font-size-quantum` (0.25rem) so computed values land on a tidy grid.

## Text roles

The exponent (`--_font-scale`) comes from semantic text roles, not size names. The shipped roles and their fractional exponents:

| Role      | fontScale |
| --------- | --------- |
| `heading` | 3         |
| `body`    | 0         |
| `caption` | -0.75     |
| `label`   | -0.5      |
| `code`    | -0.25     |
| `kbd`     | -0.5      |

Fractional exponents are the point: a discrete integer ladder could never express `caption` at −0.75 steps. Roles also carry role-specific APCA foregrounds (`--ucs-{intent}-fg-l-{role}`) because contrast targets depend on rendered size and weight.

## Font families

Three stacks, from `typography.heading-family`, `body-family`, and optional `mono-family`:

| Token            | Source                      |
| ---------------- | --------------------------- |
| `--font-heading` | `typography.heading-family` |
| `--font-body`    | `typography.body-family`    |
| `--font-mono`    | `typography.mono-family`    |

There is no `--font-sans` and no `font:` config block.

## Density and contrast coupling

Typography participates in the continuous system twice more:

* `typography.density` supplies `font-size-k` and `font-weight-k` coefficients so type can respond to the user's density preference.
* `--weight-bump` adds font weight when `--contrast-factor` climbs past 1.2 — high-contrast users get sturdier strokes, not just darker ink:

```css theme={null}
--weight-bump: calc(clamp(0, (var(--contrast-factor) - 1.2) * 10000, 1) * 100);
```

## Fluid typography

Per-brand fluid behavior lives in `typography.fluid` (`rate`, optional `floor`, `ceiling`, `quantum`), with per-role envelopes in the generated text-role metrics. There is no top-level `viewport` config block.

<Card title="Config: Typography" icon="font" href="/brand-config/typography">
  How to author the typography section of a brand config.
</Card>