---
name: computing-golden-ratio-typography
description: Computes Golden Ratio Typography line heights, spacing units, type scales, and readable measures from a font file or explicit font metrics. Use when tuning typography, CSS design tokens, line height, x-height correction, readable line lengths, or when the user mentions GRT or golden ratio typography.
compatibility: Requires Python 3. Font-file measurement requires fontTools; WOFF2 input may require brotli support.
license: LicenseRef-MutuaL-1.2
metadata:
  author: Amolith <amolith@secluded.site>
---

Computes Golden Ratio Typography values for one font or metric set and one
geometry at a time.

## Workflow

1. Identify the typography target: font, font size, and either the content
   measure in CSS px or the desired characters per line.
2. Prefer a real font file with `--font`. Use `--mu` only when the font is not
   available but the character constant is known.
3. For body prose, the default English-prose weights are fine. For code,
   non-English text, UI labels, or a distinctive writing style, pass
   representative text with `--sample-text` or `--sample-file`.
4. Run `scripts/compute_grt.py` once. Do not batch fonts or geometries; rerun
   the command for each separate decision.
5. Choose a line-height candidate. `h_base` is the uncorrected GRT line height
   and is a fully legitimate default. `h_corrected` multiplies `h_base` by
   `x_ratio * phi` (the code prints this as `x-ratio / 1/phi`); the correction is
   1.0 at the golden x-ratio `1/phi` (about 0.618), raises leading for fonts above
   it, and lowers leading for fonts below it. For high-x-height fonts the
   correction is large and `h_corrected` can overshoot, so prefer `h_base` unless
   you have a specific reason to apply the correction. See "Reading the output"
   for the sanity band.
6. Transcribe the values into the project's existing CSS custom properties,
   design tokens, or typography settings. Keep the project's naming scheme.

## Commands

```bash
# Font file + known measure
python3 SCRIPTS_DIR/compute_grt.py \
  --font path/to/font.woff2 \
  --size 16 \
  --width 640

# Font file + target line length; measure is derived
python3 SCRIPTS_DIR/compute_grt.py \
  --font path/to/font.woff2 \
  --size 16 \
  --cpl 65

# Use representative text instead of the default English-prose weights
python3 SCRIPTS_DIR/compute_grt.py \
  --font path/to/font.woff2 \
  --sample-file sample-prose.txt \
  --size 16 \
  --width 640

# No font file available: provide mu and optional x-height correction data
python3 SCRIPTS_DIR/compute_grt.py \
  --mu 2.04 \
  --x-ratio 0.72 \
  --size 16 \
  --cpl 65
```

If font measurement fails because `fontTools` is missing, install it in the
environment used for this one-off calculation:

```bash
python3 -m pip install fonttools brotli
```

## Inputs worth choosing deliberately

- `--width` / `--measure`: the line length actually read, in CSS px. This is the
  measure text wraps to, NOT a container `max-width`; if real lines wrap shorter
  than the container, pass the shorter value, or use `--cpl` instead. Prefer
  `--cpl` for UI labels, captions, buttons, and other short or framed text.
- `--cpl`: target characters per line when the measure should be derived.
- `--sample-text` / `--sample-file`: representative text for weighted average
  advance. This matters for monospace code views, localisation, or punctuation-
  heavy UI copy.
- `--x-ratio` or `--x-height` + `--cap-height`: overrides measured x-height data
  or supplies correction data with `--mu`.
- `--spacing-source base|corrected`: chooses whether spacing units derive from
  `h_base` or `h_corrected`; default is `base` to match the GRT formula before
  x-height correction. Derive the spacing scale once from your PRIMARY reading
  surface's line-height, not from an outlier surface (do not compute spacing off
  a chat-bubble measure and reuse it app-wide).
- `--reference-cpl 45 55 65 75`: chooses which readable-measure references to
  print. Pass `--reference-cpl` with no values to omit this section.

## Reading the output

- `mu` is the character constant: units per em divided by weighted average
  advance.
- `coverage` shows how much of the selected weighting text existed in the font.
  Low coverage means the sample text is not representative for that font.
- `h_base` is the GRT line height before x-height correction.
- `h_corrected` applies `x-ratio / (1 / phi)` (equivalently `x-ratio * phi`) when
  x-ratio data is available. The correction is 1.0 at the golden x-ratio `1/phi`
  (about 0.618), raises leading for fonts above it, and lowers it for fonts
  below. For high-x-height fonts the bump is large and `h_corrected` can overshoot
  badly; `h_base` is often the better practical default.
- `Measure reference` maps each requested CPL target back to a CSS-pixel measure
  for the chosen font size and character constant.

Body line-height ratios usually land around 1.4 to 1.7. A ratio above about 1.8
almost always means the measure is too wide, or the x-height correction is large
for a high-x-height font; re-check `--width`/`--cpl` and consider `h_base` before
using it. The script prints a non-fatal advisory to stderr when
`max(h_base, h_corrected) / size` exceeds 1.9.

GRT models long-form prose columns, and leading rises with the measure for
return-sweep comfort. For short, ragged, or framed text (chat bubbles, UI labels,
captions, buttons, table cells), tune to the line length ACTUALLY read (a smaller
CPL) and expect a value at or below `h_base`; do not feed it a wide column
measure.