[design] The type scale has no floor — 148 sub-12px strings on Terminals, 9.9px body copy on Settings, nine sizes inside a 2px band

[serge-ivo]

Rendered text sizes, measured live at phone widths

Counting only leaf elements carrying real text inside <main>, computed font-size under 12px:

route	11.2px	10.4px	10.9px	9.9px
Terminals	148	4
Activity	100
Assistant / Board	39	13
Preferences	21
Settings (instance)	10		7	7
Usage	6	2
tmux / Terminal	4 (+8 at 11.8px)

Static confirmation from the source — the utilities that produce them:

111 × text-[0.7rem] → 11.2px
 19 × text-[0.68rem] → 10.9px
 17 × text-[0.65rem] → 10.4px
 3 × text-[0.66rem] 2 × text-[0.62rem] 2 × text-[0.6rem]
 2 × text-[0.55rem] → 8.8px

Nine of those values sit inside a 2px band (0.65 – 0.78rem). text-[0.68rem] versus
text-[0.7rem] is a 0.32px difference at a 16px root — not a decision anyone made, an artefact
of copying from whichever neighbour was nearest (#366 reached the same conclusion statically; this
is what it looks like rendered).

Why it matters more than "small text looks tidy"

• 9.9px and 10.4px are used for descriptive body copy under form controls, on the instance
  Settings tab and in chat — text a user is expected to read to make a decision, not a label they
  glance at. WCAG sets no absolute minimum, but every platform guideline puts body copy at ≥ 11pt
  (~14.6px); 11.2px is roughly 8.4pt.
• The console has a text-size control (Preferences → Appearance, 0.9× – 1.3×) which scales the
  root — so a user can enlarge it. That is a mitigation and it is also the tell: the control
  exists because the default is too small, and it is per-browser (localStorage), so it does not
  follow the user to their phone.
• Terminals renders 148 sub-12px strings on one screen and Activity 100. These are the two
  pages whose entire content is dense status text, i.e. exactly where legibility is the product.

What to do

This is the same root cause as #366 and should not be fixed by 168 mechanical edits:

1. Define the type scale in DESIGN-SYSTEM.md — the doc is descriptive today and records
   text-[…rem] as an observed contradiction; give it a prescriptive scale (e.g. Tailwind's
   text-xs 12px as the floor for anything a user reads, with a single documented exception for
   dense telemetry if one is genuinely wanted).
2. Collapse the nine values in the 2px band to one or two, in the component layer [design] The atomic layer under #187: 273 buttons in 14 shapes, 3 card geometries, 17 font sizes #366 proposes,
   not at the call sites.
3. Then lint text-[…] — a ban only works once there is somewhere for the decision to live.
   Doing the lint first relocates the problem into 168 edits and teaches nothing.

Suggested order is unchanged from #187's thread: #367 (system) → #366 (primitives + this scale) →
#187 (blocks).

Measured 2026-08-08 against production, WebKit, 320px and 390px, signed in. Companion to #389
(tap targets), same sweep.

[serge-ivo]

Delivered in 2f5ec29 (refactor(console,admin): a floor under the type scale and a floor under the touch targets (#390, #389)) earlier today, and live in production. Re-verified independently before closing rather than taken on the commit message's word.

The floor exists and is prescriptive. --text-2xs: 0.6875rem (11px) with its --text-2xs--line-height companion is declared in both @theme blocks — store/console/src/index.css and store/admin/src/index.css — and DESIGN-SYSTEM.md §2 is now the scale: text-2xs 11 · xs 12 · sm 14 · base 16 · lg/xl 18/20 · 2xl/3xl 24/30. That section is one of exactly two prescriptive rules in a document that is otherwise descriptive, and the opening paragraph states the principle taken: prescriptive only where the rule is enforced.

The sweep was one rule, not 224 opinions. Re-measured statically first (the ticket's rendered counts came from a real signed-in account and the e2e fixtures cannot reproduce them): 224 arbitrary bracketed sizes across the three trees that share one stylesheet — 190 in store/console/src across 17 rem values, 29 in agents/coder/web/src, 5 in store/admin/src. Collapsed by round to the nearest step; ties, and anything below the 11px floor, round UP. Largest change +2.2px (8.8 → 11), largest shrink −0.8px (12.8 → 12), and nothing a user reads got smaller — the 9.9px and 10.4px descriptive copy this ticket named came up to 11.

The guard is the part that lasts, and it bites. scripts/check-design-tokens.mjs gained a second rule beside #367's, sharing its tree walk and @theme parse — a gate at zero in all three trees, not a ratchet, which it could only be because the sweep went first. I confirmed it red rather than assuming: injecting one text-[0.68rem] into Notifications.tsx produces

✗ store/console: 1 font size(s) written as a value instead of a step:
 store/console/src/pages/Notifications.tsx:50 text-[0.68rem]

and it goes green again on revert. It also asserts every declared --text-* has its --line-height, so a step cannot half-exist — Tailwind emits line-height: var(--tw-leading, var(--text-2xs--line-height)) and a missing companion resolves to nothing and silently inherits. Pure logic in scripts/lib/design-tokens.mjs with its own tests; it matches length-valued brackets only, and blanks comments first so writing about this defect cannot regenerate one into the stylesheet.

Live in production, checked just now against https://proagentstore.online/console/: the shipped stylesheet carries --text-2xs:.6875rem and 8 text-2xs rules.

This ticket asked for the order #367 → #366 → this. That is not what happened and the reason is worth recording: #366 built the primitives and honestly reported the arbitrary-size count unchanged, because the sizes that drifted are not on controls — they are on labels, table cells and descriptive copy, which a Button has nothing to grip. So the type scale did not need the component layer; it needed a destination, and the step is the destination.

Left open, tracked in DESIGN-SYSTEM.md §6 rather than silently dropped:

• A text-2xs audit, one screen at a time. The sweep was arithmetic, so 173 sites landed on the 11px floor by rounding rather than because anyone decided that text is telemetry. Some of it is not — text-2xs under a form control on the Settings tab is descriptive copy and belongs at text-xs. That is a per-screen judgement, and §5 says explicitly that a lint must not pretend to check it. It is now cheap: moving a step is one class.
• Terminals and the Behaviour tab — the two routes this ticket measured worst — are the two the guards see least. Neither has a fixture rich enough to render its content, so both were fixed by rule and neither is held by a test. A fixture for them is the cheapest next increment.

Closing: the floor, the sweep and the enforcement all landed and are verified. The two items above are follow-on work with somewhere to live, not unfinished parts of this.