How Font Size and Typography Tokens Scale in Omarchy Themes

Font size and typography tokens in Omarchy themes scale through a multiplicative font.scale token defined in 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 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.

# 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 and computes the effective size at runtime:

// 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 with an elevated scale value:

# 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 and reload the UI:

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, 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 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 files.

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

Yes. Create a 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 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}