# How Font Size and Typography Tokens Scale in Omarchy Themes

> Learn how font size and typography tokens scale in Omarchy themes using shell.toml. Discover consistent text rendering across all UI elements.

- Repository: [37signals/omarchy](https://github.com/basecamp/omarchy)
- Tags: deep-dive
- Published: 2026-08-28

---

**Font size and typography tokens in Omarchy themes scale through a multiplicative `font.scale` token defined in [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml), which the `Style` QML singleton applies to a base point size to render text consistently across panel titles, window decorations, and notifications.**

Omarchy, the open-source desktop environment from Basecamp, implements a deterministic, token-driven approach to typography through its theme system. The scaling mechanism centers on the **[`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml)** configuration file, generated from **`default/themed/shell.toml.tpl`**, which defines a base font size and a scale multiplier. This architecture ensures that every textual element—from lock screen labels to menu items—derives its final size from a single source of truth, enabling fine-grained visual control without hard-coded values.

## The Typography Configuration Pipeline

Typographic tokens originate in the theme template before being rendered into active configuration files.

The **`default/themed/shell.toml.tpl`** template contains a **`[font]`** section that establishes the base parameters. Theme authors define a `size` value in points and a `scale` multiplier that acts as the dynamic scaling factor.

```toml

# default/themed/shell.toml.tpl (rendered → shell.toml)

[font]
family = "Inter"
size   = 14            # base font size in points

scale  = 1.0           # multiplier applied to `size`

```

When a theme is activated, the shell renders this template into `themes/<name>/shell.toml`. The resulting file serves as the canonical source for the **font family**, **base size**, and **scale factor** used throughout the session.

## How the Font Scale Multiplier Works

The scaling logic is strictly multiplicative. The final rendered font size equals the base size multiplied by the scale token.

This calculation occurs at the QML layer within the **`shell/Commons/Style.qml`** singleton. The singleton exposes a `fontScale` property read from [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and computes the effective size at runtime:

```qml
// shell/Commons/Style.qml (excerpt)
property real fontSize: baseFontSize * fontScale
// Example: baseFontSize = 14, fontScale = 1.2 → 16.8 pt

```

All UI components—including panel titles, window decorations, menu items, and notification text—reference this computed `fontSize` property. By centralizing the calculation in the **Style** singleton, Omarchy guarantees typographic consistency across disparate interface surfaces without requiring individual elements to parse configuration files.

## Per-Section Font Overrides

Omarchy supports granular typographic control through section-specific configuration files. If a theme provides a custom **`shell.<section>.toml`** file, it can override the `[font]` section for that specific surface without redefining the entire theme.

For example, to increase legibility on the lock screen while maintaining standard sizes elsewhere, create [`shell.lock.toml`](https://github.com/basecamp/omarchy/blob/main/shell.lock.toml) with an elevated scale value:

```toml

# themes/my-theme/shell.lock.toml

[font]
family = "Inter"
size   = 14
scale  = 1.2           # 20% larger for the lock screen

```

The shell loads this override when rendering the lock surface, applying the 1.2 multiplier only to that context. The same **Style** singleton logic applies, but it draws from the section-specific `font.scale` value rather than the global default.

## Activating and Testing Theme Changes

After modifying typographic tokens, apply the theme to regenerate [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and reload the UI:

```bash
omarchy-theme-set my-theme

```

This command renders the template, loads the updated `font.scale` value into the **Style** singleton, and immediately updates all active textual elements. No manual restart of the shell is required for font scaling changes to take effect.

## Summary

- **Configuration source**: Typography tokens reside in the `[font]` section of [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml), generated from `default/themed/shell.toml.tpl`.
- **Scaling mechanism**: The `font.scale` token multiplies the base `size` value (e.g., 14 pt) to produce the final point size used at runtime.
- **Runtime implementation**: The `Style` QML singleton in `shell/Commons/Style.qml` calculates `baseFontSize * fontScale` and exposes the result to all UI components.
- **Override capability**: Section-specific files like [`shell.lock.toml`](https://github.com/basecamp/omarchy/blob/main/shell.lock.toml) allow targeted font scaling for individual surfaces without modifying the global theme.
- **Activation**: Run `omarchy-theme-set <theme-name>` to apply changes immediately.

## Frequently Asked Questions

### What is the default base font size in Omarchy?

The default template at `default/themed/shell.toml.tpl` defines a base font `size` of **14 points** with a `scale` of **1.0**, resulting in a 14 pt effective size for standard UI text. Theme authors can modify these values in their custom [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) files.

### Can I set different font sizes for the lock screen versus the main desktop?

Yes. Create a **[`shell.lock.toml`](https://github.com/basecamp/omarchy/blob/main/shell.lock.toml)** file in your theme directory containing a `[font]` section with a distinct `scale` value. The shell applies this override only when rendering the lock surface, allowing per-section typographic tuning while sharing the same base configuration.

### How does Omarchy handle font scaling for HiDPI displays?

Omarchy relies on the `font.scale` multiplier rather than automatic DPI detection. Users or theme authors must adjust the `scale` value (e.g., setting it to `1.5` or `2.0`) in [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) to increase text size for high-density screens. The **Style** singleton applies this factor uniformly across all interface elements.

### Where does the live font scale value live in the source code?

The active scale factor is read from [`shell.toml`](https://github.com/basecamp/omarchy/blob/main/shell.toml) and stored in the **`Style`** singleton defined in `shell/Commons/Style.qml`. This file contains the `fontScale` property and the calculation logic (`baseFontSize * fontScale`) that determines the pixel values used by QML components.