# Product typography

## Placeholder typography

Placeholder text always uses normal font weight (400), never Medium (500), semibold, or bold. Set placeholder weight explicitly rather than inheriting an emphasized input style. Apply this to search hints, empty-field prompts, and editable template placeholders; distinguish them with appropriate contrast, not weight.


## Title and label casing

Use sentence case for authored titles, headings, section labels, overlines, and other interface or content labels. Do not use all caps or CSS/text styling that forces uppercase for emphasis. For example, write “Research / Evidence brief”, not “RESEARCH / EVIDENCE BRIEF”. Preserve legitimate acronyms, proper names, identifiers, and case-sensitive scientific notation; do not mechanically lowercase them.

Read [shared fonts and glyph coverage](../../../shared/fonts.md) for font files and scientific fallback. The scale below governs Fractal product interfaces and reports that explicitly reuse it.

## Type Scale

The system uses **four size tiers** plus **two display sizes**:

| Size | Rem | Px (at 16px base) | Tier |
|------|-----|--------------------|------|
| 1.75rem | 28px | Display |
| 1.25rem | 20px | Display |
| 1rem | 16px | 01 — chat/messaging only |
| 0.875rem | 14px | 02 — primary app UI |
| 0.75rem | 12px | 03 — small/dense UI |
| 0.625rem | 10px | 04 — incidental metadata (mono only) |

**Important:** Tier 01 (1rem) is reserved for chat message content — user messages, agent messages, and their associated headers. Everything else in the app uses tier 02 (0.875rem) or lower. Tier 04 (0.625rem) is restricted to monospaced, non-interactive metadata — values the user glances at to confirm, not reads.

---

## Token Reference

### Display

| Token | Family | Size | Weight | Line-height | Extra |
|-------|--------|------|--------|-------------|-------|
| `display-01` | sans | 1.75rem | 600 | 1.2 | letter-spacing: -0.02em |
| `display-02` | sans | 1.25rem | 600 | 1.3 | — |

Use for hero text, welcome screens, and page-level headings. These are rare in the app — most section headings should use `header-01` or `header-02`.

### Headers

| Token | Family | Size | Weight | Line-height |
|-------|--------|------|--------|-------------|
| `header-01` | sans | 1rem | 500 | 1.4 |
| `header-02` | sans | 0.875rem | 500 | 1.4 |
| `header-03` | sans | 0.75rem | 500 | 1.4 |

Headers use weight 500 (Medium) to distinguish from body text at the same size. `header-01` is for chat context only. `header-02` is the default for all app UI headers.

### Body

| Token | Family | Size | Weight | Line-height |
|-------|--------|------|--------|-------------|
| `body-01` | sans | 1rem | 400 | 1.5 |
| `body-02` | sans | 0.875rem | 400 | 1.4 |

`body-01` has line-height 1.5 (not 1.4) because it is used in chat messages where longer-form reading benefits from more breathing room. `body-02` is the workhorse — use it for all general app text.

### Caption

| Token | Family | Size | Weight | Line-height |
|-------|--------|------|--------|-------------|
| `caption-01` | sans | 0.75rem | 400 | 1.4 |

Use for timestamps, metadata, footnotes, and secondary information.

### Label

| Token | Family | Size | Weight | Line-height | Extra |
|-------|--------|------|--------|-------------|-------|
| `label-01` | sans | 0.75rem | 600 | 1.4 | sentence case, normal letter-spacing |

Use for compact overline labels. Distinguish them through placement and weight, using sentence case and normal letter spacing. Status pills and metadata tags default to normal weight (400) unless another weight is explicitly specified. They use Mirror Sans (`--font-sans`) in sentence case, with normal letter spacing; they do not use the semibold `label-01` treatment or Geist Mono. Use the 12px dense UI tier and inspect the Chip implementation for exact metrics.

### Meta

| Token | Family | Size | Weight | Line-height |
|-------|--------|------|--------|-------------|
| `meta-01` | mono | 0.625rem | 400 | 1.4 |

Use for incidental metadata — supplementary numeric/technical detail that the user glances at to confirm a known value, not to learn new information. Examples: timestamps, file sizes, lattice parameters, coordinate readouts, hex values, log entry metadata. Always monospaced. Never used for interactive or actionable text.

### Code

| Token | Family | Size | Weight | Line-height |
|-------|--------|------|--------|-------------|
| `code-01` | mono | 1rem | 400 | 1.5 |
| `code-02` | mono | 0.875rem | 400 | 1.4 |
| `code-03` | mono | 0.75rem | 400 | 1.4 |

Code tokens mirror the sans tiers. `code-01` is for code blocks within chat messages. `code-02` is for code in the app UI (editors, previews). `code-03` is for dense contexts (tool call results, inline code in captions).

---

## Usage Rules

### Tier discipline

- **Tier 01 (1rem):** `body-01`, `header-01`, `code-01` — chat messages and their immediate context only.
- **Tier 02 (0.875rem):** `body-02`, `header-02`, `code-02` — the default for all app UI.
- **Tier 03 (0.75rem):** `caption-01`, `header-03`, `code-03`, `label-01` — secondary info, dense UI, small metadata.
- **Tier 04 (0.625rem):** `meta-01` — incidental metadata only. Mono, non-interactive, reference-not-reading.
- **Display:** `display-01`, `display-02` — hero/welcome screens, page-level headings. Use sparingly.

### Weight discipline

Only three weights are used in Fractal product UI. **The maximum is SemiBold (600). Never use Bold (700).** Presentation authoring is a separate, non-Fractal brand context and follows its own evidence.

| Weight | Name | Used in |
|--------|------|---------|
| 400 | Regular | body, caption, code |
| 500 | Medium | headers |
| 600 | SemiBold | labels, display tokens, table headers — the heaviest UI weight allowed |

Do not use weight 300 (Light), 700 (Bold), 800 (Heavy), or 900 (Black). Keep the weight range tight.

In Fractal UI CSS, write `font-weight: 600` explicitly—never `font-weight: bold`, which most browsers map to 700.

**`<strong>` and `<b>` tags** inherit the browser default of 700 (Bold) — which is **not allowed** in this system. Any page that uses inline `<strong>` (this includes generated summary-website outputs and any standalone HTML) must include a global override:

```css
strong, b { font-weight: 600; }
```

This belongs in the page's `<style>` block alongside the `html, body { overflow-x: clip }` and `*, *::before, *::after { box-sizing: border-box }` guardrails. Without it the emphasis renders heavier than the design system permits and competes with `display-01` / `header-01` for the eye.

### Pairing rules

- A header and its adjacent body text should be the same tier: `header-02` pairs with `body-02`, `header-01` pairs with `body-01`.
- Code within body text should match: `code-02` inside `body-02` contexts, `code-01` inside `body-01` contexts.
- Captions and labels always sit below their parent context — use `caption-01` beneath `body-02` elements.

### Form-control typography

Buttons, dropdown triggers, and single-line inputs use the shared size metrics in the layout guide: 12px dense or 14px primary-app text with an explicit 16px or 20px line box. These metrics reuse the existing size tiers; they are not new general text roles. The explicit line box prevents browser defaults from changing the height of a button relative to an input. Larger controls add padding while ordinary app text stays within tier 02.

Persistent form labels match their control size's text metrics at weight 500 with sentence case and a shared label gap. Form labels are not the semibold overline `label-01` role. Use the same label treatment for search, dropdown, text, and number fields in a group.

### Line-height rationale

| Line-height | Used in | Reason |
|-------------|---------|--------|
| 1.2 | `display-01` | Tight — large text needs less leading |
| 1.3 | `display-02` | Slightly looser for mid-size headings |
| 1.4 | Most tokens | Default — compact but readable for UI text |
| 1.5 | `body-01`, `code-01` | Generous — chat messages are longer-form reading |

---

## Mapping Old Classes to Tokens

For reference, here is how the previous custom classes map to the new token system:

| Old Class | Token |
|-----------|-------|
| `.chat-content-user`, `.chat-content-assistant`, `.chat-input` | `body-01` |
| `.chat-header-tab`, `.session-starting-text`, `.mp-label` | `header-02` |
| `.tool-call-name` | `header-02` |
| `.chat-message-system`, `.mp-input`, `.tool-call-preview` | `body-02` |
| `.terminal-welcome-text` | `display-01` |
| `.chat-welcome-hero h2` | `display-02` |
| `.code-editor`, `.terminal-input`, `.terminal-input-prompt` | `code-02` |
| `.terminal-indented`, `.terminal-tool-param`, `.claude-session-path` | `code-03` |
| `.tool-call-result-content` | `code-03` |
| `.mp-badge` | Mirror Sans, sentence case for status/metadata tags; use package Chip metrics |
| `.mp-footer`, `.terminal-tool-label` | `caption-01` |
| `.markdown-content code`, `.chat-pre-content` | `code-02` |

---

## Adding New Tokens

Before adding a new typographic token, check if an existing one covers the use case. The system is intentionally small — 13 tokens should cover the vast majority of UI needs.

If a new token is genuinely needed:

1. **It must fit the size tiers.** Do not introduce arbitrary sizes like 13px or 15px. Use the established scale: 0.625rem, 0.75rem, 0.875rem, 1rem, 1.25rem, 1.75rem.
2. **It must use an existing weight.** 400, 500, or 600 only.
3. **It must follow the naming convention.** `{category}-{tier}` where category is one of: display, header, body, caption, label, meta, code.
4. **It must have a clear, distinct role.** If you can't explain how it differs from an existing token in one sentence, it's probably not needed.
5. **Document it** by adding it to this guide in the appropriate section.
