SKILL.md

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

# 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:

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.