Color: relax text floors as a priced policy, not an absolute bar

[mehdibha]

Priority: P1 — blocks #484. Found comparing text-fg-muted against shadcn (2026-08-04).

dotUI currently cannot reproduce shadcn's muted text, and won't be able to at any setting of the #464 text axis. The engine's text bars are absolute, and shadcn sits below them.

The gap

BARS.text900 = { wcag: 4.5, lc: 60 }, enforced by solveText against the worst of steps 25/50/100. Measured on shadcn's own surfaces:

	on --background	on --muted
shadcn light --muted-foreground	4.73	4.34 — below AA
shadcn dark --muted-foreground	Lc 51.1	Lc 48.1 — below the Lc 60 bar

Both fail. The lightest tone our bars permit in light mode is oklch 0.5375; shadcn is 0.556. Blocked by 0.019 of lightness.

Per CLAUDE.md's north star — "if a user can't reproduce the look of a Material-, Geist-, or Linear-style system, an axis is missing" — this is a real gap, and shadcn is the most-copied system in the space.

Why the bar is not paranoid

Worth stating plainly, because the instinct is to just drop step 100 from the bar set. Two components put text-fg-muted directly on bg-muted, same element:

• www/src/registry/ui/kbd/styles.ts:10 — bg-muted … text-fg-muted
• www/src/registry/ui/segmented-control/styles.ts:8 — bg-muted p-[3px] text-fg-muted (root, rest-state labels)

neutral-900 → --color-fg-muted, neutral-100 → --color-muted. The bar is measuring a pairing that genuinely ships. Cost of each tone, on the Kbd label:

	Kbd label on bg-muted
today (L* 42)	5.31
the #464 default bump (L* 46)	4.50 — exactly AA
shadcn's tone	4.17 — below

So relaxing has a nameable price: Kbd and SegmentedControl labels drop below AA.

Proposal

Extend the guaranteePolicy that already exists rather than inventing a mechanism. Today relaxed "prices border-floor misses as warnings" — do the same for text floors.

• Default stays strict. Flexible ≠ lax by default; relaxed remains opt-in, exactly as for borders.
• relaxed lets solveText honor a target past its bar, and reports the miss instead of clamping.
• Warnings must name the pairing, not the rung. "neutral-900 misses its bar" is unactionable and gets dismissed. "Kbd label 4.17:1 on bg-muted — below AA" gets fixed. The engine knows rungs; only the semantic layer knows Kbd puts those two together.

The real work: a rung → token → component map

Requirement 3 is the substance here. That mapping doesn't exist today — --color-fg-muted alone has 609 call sites across 229 files, so the chain has to be derived, not hand-written.

It's the same map the Ladder inspector needs (linked below). Build once, use twice:

• warnings that name the affected component
• the inspector's "Feeds" column

Preset leak

If a shadcn-fidelity preset ships relaxed, every user who picks it silently inherits sub-AA muted text without ever making that choice. The policy has to be visible on the preset itself, not only in the contrast panel. Needs a decision as part of #484.

Links

• Color axis: text depth (muted-text darkness beyond the solved minimum) #464 — the text axis this unblocks
• High-fidelity presets: recreate popular design systems for real #484 — high-fidelity presets, the consumer
• Color Lab: ladder inspector — what each rung is and what governs it #604 — ladder inspector, shares the rung→token→component map

[mehdibha]

APCA levels checked — the bar is lenient for our sizes, not strict. This makes relaxation harder to justify, not easier.

The issue body floats relaxing BARS.text900.lc below 60. I went to the published APCA levels to check whether 60 is even the right bar for a secondary-text role. It is not — but the error runs the opposite way from what I assumed when filing this.

The published levels

Source: APCA in a Nutshell.

Lc	role	smallest qualifying text
90	body text, preferred	18px/300, 14px/400
75	body text, minimum	24px/300, 18px/400, 16px/500, 14px/700
60	content text that is not body/column/block	48px/200 … 16px/700
45	headlines & large text	36px/400 or 24px/700
30	spot-readable text & icons — absolute minimum for any other text	—
15	non-semantic non-text (dividers)	—

The levels are size- and weight-indexed. Lc 60 does not mean "secondary text is fine at 60" — it means text no smaller than 16px/700 (or larger at lighter weights).

What we actually render muted text at

Co-occurring size classes with text-fg-muted across www/src/registry/ui and www/src/components:

class	px	count
text-sm	14	79
text-xs	12	41
text-lg	18	4

120 of 124 are 12–14px, predominantly weight 400. At 14px/400, APCA's body-text minimum is Lc 75. Nothing at 12–14px/400 qualifies for the Lc 60 tier at all.

So the current bar is already more permissive than APCA's own table would license for these sizes. Today's values against Lc 75:

	on app bg	on bg-muted
light fg-muted	78.6 ✅	71.5 ❌
dark fg-muted	62.7 ❌	61.5 ❌

Consequence for this issue

Relaxing toward shadcn's tone (Lc ~48 on its own muted surface) would put 12–14px text into APCA's spot-readable band — Lc 30–45, explicitly not for text meant to be read fluently. The warning proposed in this issue would then be firing on genuine small-text legibility, not on a technicality. That is a materially different decision from the one this issue was filed to describe, and I want it recorded before anyone implements the relaxation.

To be explicit: my "maybe 60 is the wrong bar for a secondary role" framing was wrong. The data says 60 is generous for 12–14px, and the honest reading is that shadcn's muted text is hard to read at small sizes — not that our engine is over-strict.

The actual structural problem

One token, one bar, 124 call sites spanning 12px → 18px and several distinct roles — card descriptions and helper text that people genuinely read, alongside timestamps, Kbd glyphs, and shortcut hints that are legitimately spot-readable. A single size-blind bar cannot be correct for both groups. That mismatch — not the bar's value — is what actually needs solving.

So this issue should probably resolve one of two ways, and neither is "lower the number":

(a) Accept the fidelity gap. Keep the bars absolute; dotUI does not reproduce shadcn's muted tone, and #484 records that as a deliberate, documented divergence rather than a missing axis.

(b) Make the bar role-aware. Split the muted-text role by intended size/weight so spot-readable uses (Kbd, shortcut hints, timestamps) can sit lower while read-me text holds Lc 75. Considerably larger than what this issue currently proposes, and it likely wants its own token, not just a relaxed bar.

The warning design in the original body (name the pairing, not the rung) survives either way and remains the prerequisite work.

Note on the light-mode default in #464

42 → 46 moves light fg-muted from Lc 78.6 → ~73.7 on the app background. That crosses just under APCA's Lc 75 body-text minimum for 14px/400. Worth knowing before landing it — though shadcn ships 72.9 there, so the change lands us in line with common practice rather than out on our own. Flagging it as a conscious trade, not a silent regression.