# Fonts and scientific glyph coverage

Shared font assets and glyph coverage. Domains select their own primary typeface and scale; this file does not impose product-UI typography on presentations or other brands.

---

## Fonts

| Variable | Family | Weights | Use |
|----------|--------|---------|-----|
| `--font-sans` | Mirror Sans, **Noto Sans Math**, system-ui, sans-serif | 400 (Regular), 500 (Medium), 600 (SemiBold) | All Fractal product UI text |
| `--font-mono` | Geist Mono, **Noto Sans Math**, monospace | 100–900 (variable) | Code, terminal, technical content (presentations override to Courier New — see [`presentations/presentations-guide.md`](../domains/presentations/references/presentations-guide.md)) |

**Noto Sans Math is a glyph-coverage fallback, not a design choice.** Mirror Sans (and Geist Mono) have no glyphs for Greek letters or math operators, so Noto Sans Math sits *after* the primary face in every stack and is reached per-glyph only for symbols the primary face lacks. It never changes how normal text looks. This is a hard requirement for scientific / chemistry content — see [Math & Greek Fallback](#math--greek-fallback) below.

### Hosted Font Files

Mirror Sans is Fractal’s canonical sans-serif typeface, licensed under the SIL Open Font License. Uppercase I has equal top and bottom bars at 136% of the first prototype’s width; its cap height and bar thickness match T across the weight axis. Lowercase l is unchanged. Original copyright and license remain in [`MirrorSans-OFL.txt`](../assets/typography/MirrorSans-OFL.txt). Fractal owns the canonical files; downstream products must use these assets. See [`MirrorSans-README.md`](../assets/typography/MirrorSans-README.md) for regeneration details.

| Weight axis | File | Hosted URL |
|-------------|------|------------|
| 300–900 (variable) | `MirrorSans-Variable.ttf` | `https://design.mirrorphysics.com/assets/typography/MirrorSans-Variable.ttf` |
| 300–900 (variable, web) | `MirrorSans-Variable.woff2` | `https://design.mirrorphysics.com/assets/typography/MirrorSans-Variable.woff2` |
| 100–900 (variable) | `GeistMono-VariableFont_wght.ttf` | `https://design.mirrorphysics.com/assets/typography/GeistMono-VariableFont_wght.ttf` |
| 400 (Regular) | `NotoSansMath-Regular.ttf` | `https://design.mirrorphysics.com/assets/typography/NotoSansMath-Regular.ttf` |

> If `MirrorSans-Variable.ttf` is missing from `assets/typography/`, the hosted URL will 404 and `--font-sans` will fall back to `system-ui`. Drop the file in to enable the hosted version. `NotoSansMath-Regular.ttf` is hosted the same way and is the Greek / math fallback described in [Math & Greek Fallback](#math--greek-fallback).

#### For web / CSS

```css
@font-face {
  font-family: 'Mirror Sans';
  src: url('https://design.mirrorphysics.com/assets/typography/MirrorSans-Variable.woff2') format('woff2');
  font-weight: 300 900;
  font-style: normal;
  font-display: swap;
}
```

#### For matplotlib / Python

Download the variable font and register it with matplotlib's font manager:

```python
from matplotlib import font_manager
import matplotlib as mpl
import urllib.request, os, tempfile

FONT_DIR = os.path.join(tempfile.gettempdir(), 'fractal_fonts')
os.makedirs(FONT_DIR, exist_ok=True)

# Register Mirror Sans (primary) AND Noto Sans Math (Greek / math fallback).
# Both must be registered — Mirror Sans has no Greek letters or math operators.
for name in ('MirrorSans-Variable.ttf', 'NotoSansMath-Regular.ttf'):
    path = os.path.join(FONT_DIR, name)
    if not os.path.exists(path):
        urllib.request.urlretrieve(
            f'https://design.mirrorphysics.com/assets/typography/{name}', path
        )
    font_manager.fontManager.addfont(path)

# font.family must be a LIST so matplotlib (≥3.6) falls back per-glyph:
# Mirror Sans renders Latin text, Noto Sans Math fills in α, β, ∑, ∫, … .
mpl.rcParams['font.family'] = ['Mirror Sans', 'Noto Sans Math']
```

After registration, matplotlib resolves `'Mirror Sans'` first and borrows `'Noto Sans Math'` for any glyph Mirror Sans lacks. The shipped [`fractal.mplstyle`](../resources/visualization/fractal.mplstyle) already lists Noto Sans Math after Mirror Sans in `font.sans-serif`, so a chart that loads the style sheet and registers both font files gets the fallback automatically.

---

## Math & Greek Fallback

Scientific and chemistry reports are full of Greek letters (α, β, γ, Δ, λ, μ, π, σ, Ω) and math operators (∑, ∏, ∫, ∂, ∇, ≈, ≠, ±, ≤, ≥, ∞, √, ∈, ∝, ⋅). **Mirror Sans and Geist Mono contain none of these glyphs** — left alone they render as tofu (□) or a mismatched system-fallback face, which silently corrupts reports.

The fix is a **per-glyph fallback font, Noto Sans Math**, placed *after* the primary face in every font stack:

- It is reached only for the specific glyphs the primary face is missing. All Latin text, digits, and punctuation still render in Mirror Sans / Geist Mono — Noto Sans Math never changes the look of normal text.
- It is a coverage backstop, **not** a typeface choice. Do not set Noto Sans Math as a primary `font-family`, and do not apply it as an explicit face to ordinary text. (This is about font *selection* — it has nothing to do with which *characters* you may type; see below.)

### Use the real glyphs — this is the intended behavior, not a rule violation

**Write Greek letters and math operators as their actual Unicode characters, directly in your text, labels, and tables.** The fallback exists precisely so they render correctly everywhere. Reaching a non-Mirror Sans glyph is the *designed* behavior — it does **not** violate the "use Mirror Sans" rules, which only forbid choosing a different *primary typeface* for ordinary text. There is no longer any reason to avoid, spell out, or ASCII-approximate scientific notation.

| Do — type the real glyph | Don't — avoid or approximate |
|---|---|
| `ΔG`, `Δδ` | `Delta G`, `dG`, `delta-G` |
| `ρ = -0.49` (Spearman) | `rho = -0.49`, `r_s` |
| `8 µM`, `pH ≈ 7.4` | `8 uM`, `pH ~= 7.4`, `pH approx 7.4` |
| `2.69 Å` | `2.69 Angstrom`, `2.69 A` |
| `α-helix`, `β-sheet`, `λ_max` | `alpha-helix`, `beta-sheet`, `lambda_max` |
| `K_d`, `ΣΔE`, `∫ρ dr`, `∂E/∂x` | spelling these out in prose |
| `≤ ≥ ≠ → × ± ∞ √ ∈` | `<= >= != -> x +/- inf sqrt in` |

This applies to every author surface — HTML/CSS reports, chart titles and axis labels (matplotlib), tables, and inline notation. Spelled-out or ASCII-mangled notation in a scientific report is now a **defect to fix**, not a safe default.

This is **mandatory wherever scientific content can appear** — body text, chart labels, tables, inline notation. The two surfaces that consume Mirror Sans must both carry the fallback:

**Web / CSS** — already wired into the tokens. `--font-sans` and `--font-mono` in [`typography.css`](../resources/tokens/typography.css) end with `'Noto Sans Math'` before the generic family, and the `@font-face` for it is declared alongside Mirror Sans. Any element using a typographic token (or `var(--font-sans)`) inherits the fallback with no extra work. Just ensure `NotoSansMath-Regular.ttf` is present in `assets/typography/` (or reachable at its hosted URL).

**matplotlib / Python** — register both font files and set `font.family` to the list `['Mirror Sans', 'Noto Sans Math']`, exactly as shown in the [matplotlib registration snippet](#for-matplotlib--python) above. Per-glyph fallback requires matplotlib ≥ 3.6.

> Presentations are exempt — decks override to Arial / Courier New (see [`presentations/presentations-guide.md`](../domains/presentations/references/presentations-guide.md)), which already ship with Greek and the common math operators on every viewer platform.

---
