1---
2name: computing-golden-ratio-typography
3description: 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.
4compatibility: Requires Python 3. Font-file measurement requires fontTools; WOFF2 input may require brotli support.
5license: LicenseRef-MutuaL-1.2
6metadata:
7 author: Amolith <amolith@secluded.site>
8---
9
10Computes Golden Ratio Typography values for one font or metric set and one
11geometry at a time.
12
13## Workflow
14
151. Identify the typography target: font, font size, and either the content
16 measure in CSS px or the desired characters per line.
172. Prefer a real font file with `--font`. Use `--mu` only when the font is not
18 available but the character constant is known.
193. For body prose, the default English-prose weights are fine. For code,
20 non-English text, UI labels, or a distinctive writing style, pass
21 representative text with `--sample-text` or `--sample-file`.
224. Run `scripts/compute_grt.py` once. Do not batch fonts or geometries; rerun
23 the command for each separate decision.
245. Choose a line-height candidate. `h_base` is the uncorrected GRT line height
25 and is a fully legitimate default. `h_corrected` multiplies `h_base` by
26 `x_ratio * phi` (the code prints this as `x-ratio / 1/phi`); the correction is
27 1.0 at the golden x-ratio `1/phi` (about 0.618), raises leading for fonts above
28 it, and lowers leading for fonts below it. For high-x-height fonts the
29 correction is large and `h_corrected` can overshoot, so prefer `h_base` unless
30 you have a specific reason to apply the correction. See "Reading the output"
31 for the sanity band.
326. Transcribe the values into the project's existing CSS custom properties,
33 design tokens, or typography settings. Keep the project's naming scheme.
34
35## Commands
36
37```bash
38# Font file + known measure
39python3 SCRIPTS_DIR/compute_grt.py \
40 --font path/to/font.woff2 \
41 --size 16 \
42 --width 640
43
44# Font file + target line length; measure is derived
45python3 SCRIPTS_DIR/compute_grt.py \
46 --font path/to/font.woff2 \
47 --size 16 \
48 --cpl 65
49
50# Use representative text instead of the default English-prose weights
51python3 SCRIPTS_DIR/compute_grt.py \
52 --font path/to/font.woff2 \
53 --sample-file sample-prose.txt \
54 --size 16 \
55 --width 640
56
57# No font file available: provide mu and optional x-height correction data
58python3 SCRIPTS_DIR/compute_grt.py \
59 --mu 2.04 \
60 --x-ratio 0.72 \
61 --size 16 \
62 --cpl 65
63```
64
65If font measurement fails because `fontTools` is missing, install it in the
66environment used for this one-off calculation:
67
68```bash
69python3 -m pip install fonttools brotli
70```
71
72## Inputs worth choosing deliberately
73
74- `--width` / `--measure`: the line length actually read, in CSS px. This is the
75 measure text wraps to, NOT a container `max-width`; if real lines wrap shorter
76 than the container, pass the shorter value, or use `--cpl` instead. Prefer
77 `--cpl` for UI labels, captions, buttons, and other short or framed text.
78- `--cpl`: target characters per line when the measure should be derived.
79- `--sample-text` / `--sample-file`: representative text for weighted average
80 advance. This matters for monospace code views, localisation, or punctuation-
81 heavy UI copy.
82- `--x-ratio` or `--x-height` + `--cap-height`: overrides measured x-height data
83 or supplies correction data with `--mu`.
84- `--spacing-source base|corrected`: chooses whether spacing units derive from
85 `h_base` or `h_corrected`; default is `base` to match the GRT formula before
86 x-height correction. Derive the spacing scale once from your PRIMARY reading
87 surface's line-height, not from an outlier surface (do not compute spacing off
88 a chat-bubble measure and reuse it app-wide).
89- `--reference-cpl 45 55 65 75`: chooses which readable-measure references to
90 print. Pass `--reference-cpl` with no values to omit this section.
91
92## Reading the output
93
94- `mu` is the character constant: units per em divided by weighted average
95 advance.
96- `coverage` shows how much of the selected weighting text existed in the font.
97 Low coverage means the sample text is not representative for that font.
98- `h_base` is the GRT line height before x-height correction.
99- `h_corrected` applies `x-ratio / (1 / phi)` (equivalently `x-ratio * phi`) when
100 x-ratio data is available. The correction is 1.0 at the golden x-ratio `1/phi`
101 (about 0.618), raises leading for fonts above it, and lowers it for fonts
102 below. For high-x-height fonts the bump is large and `h_corrected` can overshoot
103 badly; `h_base` is often the better practical default.
104- `Measure reference` maps each requested CPL target back to a CSS-pixel measure
105 for the chosen font size and character constant.
106
107Body line-height ratios usually land around 1.4 to 1.7. A ratio above about 1.8
108almost always means the measure is too wide, or the x-height correction is large
109for a high-x-height font; re-check `--width`/`--cpl` and consider `h_base` before
110using it. The script prints a non-fatal advisory to stderr when
111`max(h_base, h_corrected) / size` exceeds 1.9.
112
113GRT models long-form prose columns, and leading rises with the measure for
114return-sweep comfort. For short, ragged, or framed text (chat bubbles, UI labels,
115captions, buttons, table cells), tune to the line length ACTUALLY read (a smaller
116CPL) and expect a value at or below `h_base`; do not feed it a wide column
117measure.