# TextPair

## 2026-08-18 — New atom: owns the gap between a heading and its sub-line

**Prompted by:** Clint Howen

### What changed
- New `TextPair` atom: a strong line (`primary`) with a quiet line under it (`secondary`).
- Three sizes (`sm` / `md` / `lg`) that change only the typography pairing, never the gap.
- The gap is the new `--spacing-text-pair` token, not a per-screen utility class.

### Rules this component encodes

| Rule | Behaviour |
|---|---|
| `size` → typography | `sm` = `text-label-small` + `text-caption`; `md` = `text-label-medium` + `text-body-small`; `lg` = `text-h5` + `text-body-small`. Default `md`. |
| Gap is constant | All three sizes use `gap-text-pair` (4px). The gap deliberately does **not** scale with type size — one relationship, one value. Change `--spacing-text-pair` if the rhythm is wrong. |
| Either slot omitted | Renders nothing at all, not an empty line. The same guard applies to `primary` and `secondary`. Omitted means `null`, `undefined`, `""`, or **any boolean** — `x={cond && value}` yields `false` and must not leak the gap. `0` **is** rendered; it is a legitimate value. |
| Overflow | Long unbroken strings wrap (`break-words`) and the container may shrink (`min-w-0`) rather than widening its parent. |
| Colour | `primary` is `text-foreground`, `secondary` is `text-muted-foreground`. Override per instance via `primaryClassName` / `secondaryClassName`, never by wrapping in a coloured span. |

### Why
- An audit of the committed library found the same visual relationship built 58 times
  at 8 different gaps, from 2px to 24px. A spacing correction made on one screen could
  not propagate because there was nothing underneath it to change.
- The design system defined `--typography-*-leading` (line-height inside a text block)
  but had no token for the space between elements, so that space defaulted to Tailwind's
  own scale rather than to anything WealthX had decided.

### Affected tokens / files
- `packages/shadcn/src/styles/globals.css` — new `--spacing-text-pair`, `--spacing-field`,
  `--spacing-stack`, `--spacing-section`
- `packages/shadcn/src/components/ui/text-pair.tsx`
- `apps/docs/stories/shadcn/atoms/text-pair.stories.tsx`