@taprootio/espalier 4.18.0 → 4.20.0

package/CHANGELOG.md

@@ -1,3 +1,26 @@
+# 4.20.0
+
+Sections and pages stop failing accessibility audits they should pass: section decoration becomes an explicit opt-in, and page asides become landmarks only when they have content, each with its own name.
+
+- **Fixed: every `esp-section` caused a false color-contrast failure in axe-core and Lighthouse.** Each section painted a full-bleed decoration plane in its heading color and hid it with a fully transparent mask. Neither auditor models `mask-image`, so both measured every line of section text against that invisible plane: body text in a light section against the heading color, and text in a `context="inverted"` section, including text inside a child component's shadow root, against the zone's near-white heading color instead of its dark canvas. The pages looked correct and failed anyway. An undecorated section now renders no decorative layer at all, so audits measure its text against the band behind it. Nothing changes visually.
+- **New: the `decoration` attribute on `esp-section` (reflected boolean property `decoration`).** It turns on the decorative mask plane. **The `--esp-section-decoration-image`, `-color`, `-position`, `-size` and `-opacity` hooks now take effect only on a section that carries it**, so a section that sets the image hook without the attribute paints no decoration. Add `decoration` wherever you set the image: `<esp-section decoration style="--esp-section-decoration-image: url(...)">`. This is a minor release rather than a major one on purpose: every site that uses the hook is owner-managed and picks up the attribute when it moves to this version. With the attribute, a decorated section looks exactly as it did before. The contract is to set it together with an image, never on its own: a `decoration` section whose image is absent or `none` still paints nothing you can see, but auditors read its tint as the background again. Auditors treat a decorated section as though the tint covered it edge to edge, so text that passes an audit also reads where it crosses the mark. Keep `--esp-section-decoration-opacity` low (for example `0.09`): at its default of `1`, auditors measure the section's text against the solid tint.
+- The other users of the shared overlay layers, `esp-footer` and `esp-image`, are unaffected. Neither paints a layer that only a transparent mask hides: the footer's overlay paints its real background color, and image textures are visible gradients, masked only (and partially) for halftone.
+- **Fixed: every `esp-page` exposed two empty, unnamed complementary landmarks, failing axe-core's `landmark-unique` audit.** The page always rendered its left and right asides, whether or not anything was slotted into `sidebar` or `right`, and gave neither a name. Screen reader users met two indistinguishable, empty regions on every page, and Lighthouse flagged them. An aside whose slot is empty is now not a landmark at all (`role="none"`). It keeps its element and grid track and still collapses to zero width, so layout is unchanged. The aside becomes a landmark again as soon as content is slotted, and drops the role again when the content is removed.
+- **New: `sidebar-label` and `right-label` on `esp-page` (reflected string properties `sidebarLabel` and `rightLabel`).** They name the left and right asides' complementary landmarks while the aside has content, the same way `preview-label` names the preview. The defaults are `Sidebar` and `Related`. If you rename one, keep the two different so the landmarks stay distinguishable.
+
+# 4.19.0
+
+Filled action labels meet their contrast target, and the theme fit report says when a brand colour did not survive the compile.
+
+- **The default filled action changed colour in the light scheme, and this is visible on any site that has not pinned it.** `--esp-color-action-background` resolved to the `raised3` ramp stop in both schemes, which is L 0.80 in the light ramp — a lightness where no ink, not even pure black, reaches the Lc 75 that APCA asks of a button label. Contrast enforcement walked the label to black and stopped 3.7 short, so the stock light theme shipped a button it could not make legible. The mapping is now chosen per scheme: `muted` in light, giving a mid-band surface with a pale label at Lc 76.0, and `raised3` in dark, which is what it already was — **the dark scheme's action pair is unchanged**, at Lc 81.6. Those are the stops a theme declaring an `action` role has always compiled to, so naming a role no longer moves the button either. A theme that pins `semanticMappings.actionBackground` is unaffected.
+- The date picker now reads each of its inks against the surface it sits on. Its focus rings take `--esp-color-text`, which is enforced against the page ground the calendar paints on; they had been taking `--esp-color-action-text`, which is only guaranteed on a filled action and happened to match only while the light theme's action label was near-black. A ring drawn *inside* a selected day is the exception — that cell paints the action surface, so its ring takes `--esp-color-action-text`, and so does today's marker when today is the selected day, where it previously took `--esp-color-border`. A selected day now paints the action pair itself — `--esp-color-action-background` under `--esp-color-action-text` — which is the one surface/ink pairing the engine enforces, reaching Lc 76.0 in light where the old layer-3 ground left its label at 71.3 with nothing guaranteeing it. **A selected day is a deeper, filled swatch in the light scheme as a result.** The dark scheme is unchanged: there the layer-3 and action surfaces resolve to the same colour.
+- `themeFitLints()` gains **`action-anchor-inversion`**. It fires when a filled action renders the opposite way round from the swatches it names — a surface whose swatch wants dark ink took light ink instead, or a declared `action.color`/`action.ink` pair's lightness order reversed. This is the one case where reading the report's per-token deltas does not help: an action's ramp stop is chosen by the engine rather than named by the theme, so re-seating the ramp — the remedy for every other anchored token — cannot move it, and the fix is to pin the token. A brand whose action colour is a light gold or a pastel is the case to watch.
+- `themeFitLints()` gains **`apca-target-unmet`**. It fires when enforcement moved a text token as far as its ramp allows and the pair still missed the legibility floor. The message says which of two things went wrong, measured rather than assumed: the emitted ink is on the weaker side when the opposite pole would have cleared that ground, or the ground itself cannot carry the floor under any ink. It judges against the token's own tier or Lc 75, whichever is lower, so a caption that misses the preferred Lc 90 tier on a tinted wash stays quiet while genuinely illegible text does not.
+- **Both lints are gated.** `espalier theme check` already exits non-zero on any lint, so a theme that trips either one will start failing that command. The per-surface `lints` arrays are part of the committed `--expect` tables, so a theme whose action pair or contrast floor is affected needs one reviewed `--update-expect` refresh.
+- `ThemeFitToken` gains `pairing`, `"declared"` or `"derived"`, on a role-paired ink. `action.ink` defaults to the canvas colour, so an ink that was *derived* is the page ground by contract and is re-lit to the far end of the ramp on purpose — its large `anchor.deltaE` is the contract working, not a brand that went missing. The field is what lets `action-anchor-inversion` leave that case alone. It validates as optional, so a fit table written before this release reports the addition as ordinary drift rather than an unreadable-file error.
+- A theme that declares `action.ink` now derives that ink's ramp stop from the action surface it actually sits on, the same way an undeclared ink already did. Naming the slot still chooses the colour family; the ramp still supplies the lightness. In a light scheme both rules already agreed, so nothing moves there. In a dark scheme the named slot used to start on the wrong side of the ramp and rely on enforcement to carry it back, emitting a weaker label than the ramp could give.
+- The lightness-ramp guide now says which stop its seating procedure cannot reach, and why pinning a light action swatch may still not give you a legible button: under APCA the Lc 75 label tier is unreachable across a mid band of roughly L 0.55 to L 0.83, so a swatch inside it cannot hold a button label at its own lightness — though pinning the stop just past the band often can.
+
 # 4.18.0
 
 A brand logo holds its place before it loads, the header's menu button is one button, and a stored theme's declared roles finally take effect.