docs: five component doc pages reference deleted/stale tokens (one documents a sub-3:1 focus ring)

[newspaceracer]

Requesting spoke: firma2-design · Date: 2026-08-19

What's wrong

Five doc pages under apps/site/src/pages/components/ document tokens that were
deleted or re-pointed by the removed-hooks / rename migrations. Because spokes are
scaffolded from these pages verbatim, every stale reference propagates downstream —
firma2-design inherited all six of the issues below.

The six

Page	Stale	Should be
esa-app-bar.astro	const tokens = [...] documenting --app-bar-gap, --app-bar-pad-x, --app-bar-pad-y	deleted by app-bar-hooks-removed (removed, no alias). Dead array — nothing renders it
esa-container.astro	whole "Gutter" section: --container-gutter, plus a live demo style="--container-gutter: 0"	removed by container-hooks-removed; esa-container.astro:26 hardcodes padding-inline: var(--spacing-600, 2rem). The demo is a guaranteed no-op that renders identically to the box beside it
esa-map.astro	--color-border	--color-border-default
esa-grid.astro	--grid-border-color → --color-border	→ --color-border-default (per component-tokens.css:340)
esa-grid.astro	--grid-font-size → --font-size-ui-md, --grid-header-font-size → --font-size-ui-sm	--typography-label-md-font-size, --typography-label-xs-font-size (sm maps to label-xs)
esa-rich-text-editor.astro	--form-border-color → --color-border; dividers --color-border	--color-border-default (per component-tokens.css:206)

The one worth prioritising

esa-rich-text-editor.astro states twice that focus-within uses
--form-border-color-focus → --color-background-brand. The real chain is
--form-border-color-focus → --color-border-default-focus, which is the brand ramp
one step up (component-tokens.css:208; dist/tokens.css:1143 → --color-grass-10).

Per the comment block at component-tokens.css:270-297, that walk was the 2026-08-17
contrast fix: the brand fill measured 2.95:1 on raised/canvas and 2.66:1 on sunken,
all short of the 3:1 SC 1.4.11 requires, because step 9 clears 3:1 as a solid fill and a
focus ring needs it as a hairline.

So the page documents the exact value that was rejected for failing contrast. Two things
make it likely to be acted on:

1. No esa-rich-text-editor exists in the lego catalog — the page's Tokens list reads as
   build instructions for whoever implements it.
2. It is invisible in dark mode. In firma2's theme both tokens resolve to brand-9 in dark
   (theme-firma2.css:186-187) and diverge only in light (:60-61, brand-10 vs brand-9),
   so eyeball-testing in dark shows nothing wrong.

No codemod catches this one — it is a correct token name for the wrong role, not a rename.
migrate-tokens does catch the four --color-border / --font-size-ui-* cases.

Workaround meanwhile

All six fixed locally in firma2-design (hand edits, not the codemod). Note that
migrate-tokens --write is not safe on a spoke's ported doc pages: it reports 61
replacements, of which 55 target esa-icon-button.astro / esa-icon-link.astro — the pages
that exist specifically to document those deprecated components. The codemod cannot tell a
page documenting esa-icon-link from a page using it, so it rewrites the documentation
into its own successor. Worth a guard or an ignore-path for pages/components/ in the hub too.