lego request: esa-app-shell — four defects (dead bar border, inert accent, no full-height rail, raw omnibox icon)

[newspaceracer]

Filed from firma2-design (ProjectFirma 2.0 spoke) · 2026-08-19
Found while composing the spoke's first prototype (/prototypes/projects) inside esa-app-shell.

Four independent defects in one component. Each verified against hub source and in a headless browser.

---

1. The bar's border-bottom rule never applies (Astro scoping)

esa-app-shell.astro declares:

.esa-app-shell__bar { flex: none; border-bottom: var(--border-width-default, 1px) solid var(--color-border-default-strong, #bbbbbb); }

It never matches. The shell renders <EsaAppBar tone="surface" as="header" class="esa-app-shell__bar">, and because EsaAppBar is a child .astro component its root <header> carries esa-app-bar's own scope id (data-astro-cid-ahjxwpid), not the shell's (data-astro-cid-za3k4dj5). The scoped selector selects nothing.

Verified in-browser — the tokens resolve fine, the rule simply doesn't land:

--border-width-default        -> 1px
--color-border-default-strong -> #b9bcb8
header computed border-bottom -> 0px none      ← rule never applied

Why it matters: the bar has no fill to fall back on. Hub defaults set --color-background-elevation-raised (what esa-app-bar paints) to var(--color-gray-1) — the same value as --color-background-default, the canvas. The border is the only thing separating app chrome from page, so the bar renders invisibly.

Probably affects any other rule the shell writes against a child component's root, not just this one — worth auditing together.

Note for whoever fixes it: re-pointing --color-background-elevation-raised so the bar gets its own value is not a viable spoke-side workaround. It drops two dataviz swatches below their contrast floor — check-themes.mjs goes 66/66 → 2 FAIL (dataviz-categorical-8 2.93:1, needs 3:1; dataviz-sequential-1 1.96:1, needs 2:1). That role carries dataviz backgrounds too, so it isn't free to move.

2. .esa-app-shell--accent {} is an empty stub

The accent prop is documented in the component header as adding "a faint brand-TINTED neutral wash to the bar (a color-mix, not a fill)". It is wired to .esa-app-shell--accent — which has no declarations. Passing accent does nothing.

This would have been the sanctioned fix for #1's invisible bar.

3. No full-height-sidenav layout variant

The shell hard-codes one arrangement: full-width bar stacked above a row containing the rail. The common alternative — rail owning full viewport height with the bar beside it — has no prop.

Working around it from a spoke means reaching into the shell's internals, because the nav is a grandchild (.esa-app-shell > .esa-app-shell__body > esa-sidebar-nav) and can't be placed by a grid on the shell:

.esa-app-shell       { display: grid; grid-template-columns: auto minmax(0,1fr); grid-template-rows: auto minmax(0,1fr); }
.esa-app-shell__body { display: contents; }   /* dissolve the wrapper */
.esa-app-shell__nav  { grid-column: 1; grid-row: 1 / 3; }
.esa-app-shell__bar  { grid-column: 2; grid-row: 1; }
.esa-app-shell__content { grid-column: 2; grid-row: 2; min-height: 0; }

A layout="rail-full-height" prop (or similar) would stop spokes needing to know that DOM shape.

4. The omnibox trigger's icon is a raw literal, off the icon ramp

Already filed as #27 — folded in here only so this list is complete. See that issue.

---

Workarounds currently shipping in firma2-design

All in src/layouts/AppLayout.astro, each commented as temporary and pointing here:

• Promotion path + generated component catalog #1 — the same declaration, same tokens, re-applied unscoped. (Since reverted; kept above as the reproduction.)
• lego request: esa-donut (value-split ring with center-label slot) #3 — the grid re-flow above.
• migrate-kit: spoke-driven Ecology migration plugin #4 / lego request: esa-app-shell omnibox icon collapses to ~8px — svg is the only shrinkable item in the trigger #27 — .esa-app-shell__search > svg { width: var(--icon-size-md); height: var(--icon-size-md); }
• Fix text/icon color tokens: use step-11 strong tokens throughout #2 — none.

Related

The same prototype surfaced a separate tokens-architecture gap (no tier-1 control-size ramp, so --sidenav-item-height and friends are raw px): #29

[newspaceracer]

Three more from the same spoke, all in esa-sidebar-nav rather than the shell itself. Happy to split these into their own issue if that triages better.

---

5. Row hover is invisible — and on the active row it is backwards

--_sidenav-item-bg-hover and --_sidenav-bg both read --color-background-elevation-sunken, so the hover wash is the same colour as the rail it sits on. --_sidenav-item-color-hover and --_sidenav-item-color are likewise both --color-content-default-secondary, so the text does not move either.

Measured in a browser (light scheme, rail #eff1ef):

row	resting bg	hover bg	text moves?	net effect
ordinary	transparent (rail shows through, #eff1ef)	#eff1ef	no	no visible change
active	#fbfefb (active tint)	#eff1ef	no	loses its active tint — appears to deactivate

The active case is a rule-scoping slip. In the stylesheet:

.link:hover:not(.link--disabled) { background: var(--_sidenav-item-bg-hover); }
.link:hover:not(.link--disabled):not(.link--active) { color: var(--_sidenav-item-color-hover); }

The colour rule is scoped off .link--active — with a comment saying so ("Scoped off the active row so it keeps its active colour while hovered"). The background rule is not, so hovering the current page replaces its tint with the rail colour.

The component-token file documents the intended behaviour as:

"Inherits the resting colour by default — the rail signals hover with the background wash alone."

That strategy is sound, but the wash it picks is identical to the rail's own background, so there is nothing left to signal with.

Suggested fix: give the hover wash its own step (or its own hook — see #7), and add :not(.link--active) to the background rule so the active row keeps its tint.

6. No way to re-skin the collapse toggle's glyph

The toggle hard-codes chevrons-left / chevrons-right from the icon registry. There is no part= on the button, no slot, and no token — so a spoke that wants a different mark has no supported route.

This spoke wanted the standard sidebar/panel glyph (the same mark esa-app-shell already draws inline on its own bar toggle, which isn't in the registry either). The only thing that works is appending a stylesheet to the shadow root that hides the chevron span and paints a masked ::before:

sheet.replaceSync(`
  .toggle > span { display: none; }
  .toggle::before { content:''; width: var(--icon-size-md); height: var(--icon-size-md);
    background-color: currentColor; mask: url("data:image/svg+xml,…") center/contain no-repeat; }
`);
root.adoptedStyleSheets = [...root.adoptedStyleSheets, sheet];

Markup injection is not an option — Lit re-renders that button whenever collapsed flips, wiping it on the first click. A part="toggle", or a toggle-icon prop taking a registry name, would remove the need for any of this.

7. The rail's geometry is themable; its palette is not

Of the 26 private customs the component derives, 10 read a public --sidenav-* hook and 16 read a tier-2 role or tier-1 primitive directly. The split is almost exactly geometry vs. colour:

Has a hook — --sidenav-width, --sidenav-width-collapsed, --sidenav-item-height, --sidenav-item-gap, --sidenav-icon-size, --sidenav-icon-size-collapsed, --sidenav-link-bg, --sidenav-active-border-width, --sidenav-section-margin-top, --sidenav-nested-gap

No hook — --_sidenav-bg, --_sidenav-border, --_sidenav-item-color, --_sidenav-item-color-hover, --_sidenav-item-color-active, --_sidenav-item-bg-hover, --_sidenav-item-bg-active, --_sidenav-active-border-color, --_sidenav-group-color, --_sidenav-item-weight-active, --_sidenav-item-radius, --_sidenav-item-padding, --_sidenav-icon-gap, --_sidenav-section-spacing, --_sidenav-nested-indent, --_sidenav-transition

So a spoke can resize the rail freely but cannot recolour it. --sidenav-link-bg is the single colour hook, and it only covers the resting row.

I understand --sidenav-bg was demoted deliberately (2026-08-16) so the three chrome surfaces move together as a value ramp — that reasoning is good and I am not asking to undo it. But it leaves no route between "move the whole ramp" and "nothing": re-pointing --color-background-elevation-sunken to recolour the rail also moves every table header and inset well in the spoke, and in this theme it is what the AG Grid header reads.

Ask: hooks for at least the row states — hover background, hover text, active background, active text — since those are what a brand actually needs to express, and #5 shows the current defaults collide. A rail-surface hook that is documented as moving with the ramp would cover the rest.

---

Nothing here is blocking: this spoke ships a workaround for #6 and lives with #5 and #7. Filing so the next spoke doesn't rediscover them.