@wildmason/aegis 1.12.0 → 1.14.0

package/dist/types/wildmason-aegis.d.ts

@@ -1,6 +1,6 @@
 import * as _angular_core from '@angular/core';
 import { ElementRef, AfterViewInit, TemplateRef, OnDestroy } from '@angular/core';
-import { ConnectedPosition } from '@angular/cdk/overlay';
+import { ScrollStrategy, OverlayRef, ConnectedPosition } from '@angular/cdk/overlay';
 import { ControlValueAccessor } from '@angular/forms';
 import * as rxjs from 'rxjs';
 
@@ -110,6 +110,26 @@ interface SelectOption {
     disabled?: boolean;
 }
 
+/**
+ * A scroll strategy that keeps a connected overlay anchored to its trigger,
+ * including when the thing that scrolled was an ordinary `overflow: auto`
+ * element rather than the document.
+ *
+ * CDK's own reposition strategy does the right thing and is simply never told:
+ * it listens through `ScrollDispatcher`, which cannot hear a scroll from a
+ * container that is not marked `cdkScrollable`. See `onViewportChange` for the
+ * full account. This strategy listens in the capture phase instead, so the
+ * consumer annotates nothing.
+ */
+declare class WmAnchoredScrollStrategy implements ScrollStrategy {
+    private overlayRef;
+    private release;
+    attach(overlayRef: OverlayRef): void;
+    enable(): void;
+    disable(): void;
+    detach(): void;
+}
+
 /**
  * WmSelect — Accessible dropdown select built on Angular CDK Overlay.
  *
@@ -143,6 +163,16 @@ interface SelectOption {
  *  - Always pair with a visible label via <wm-label> or aria-label on the host
  */
 declare class WmSelect {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Array of options to display. */
     options: _angular_core.InputSignal<SelectOption[]>;
     /** The currently selected value. Two-way bindable. */
@@ -202,6 +232,16 @@ declare class WmSelect {
  *    Import WmAutoFocus from @wildmason/aegis/components and add it to your component's imports.
  */
 declare class WmPopover {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Whether the panel is currently open. */
     readonly isOpen: _angular_core.InputSignal<boolean>;
     /** Panel width in pixels, or 'auto' to match content. */
@@ -306,7 +346,7 @@ declare class WmButton {
     readonly variant: _angular_core.InputSignal<ButtonVariant>;
     readonly size: _angular_core.InputSignal<ButtonSize>;
     readonly disabled: _angular_core.InputSignal<boolean>;
-    readonly type: _angular_core.InputSignal<"button" | "submit" | "reset">;
+    readonly type: _angular_core.InputSignal<"reset" | "submit" | "button">;
     /** Makes the button square (equal width/height). Use for icon-only buttons. */
     readonly iconOnly: _angular_core.InputSignal<boolean>;
     /** Accessible label forwarded to the inner <button>. Required for icon-only buttons. */
@@ -595,6 +635,16 @@ declare class ComboboxPanel {
  *   <wm-combobox formControlName="tag" [options]="tags" />
  */
 declare class WmCombobox implements ControlValueAccessor, OnDestroy {
+    /**
+     * Keeps the panel anchored to its trigger while an ancestor scrolls.
+     *
+     * One instance per component, because a ScrollStrategy holds a single
+     * overlayRef and could not tell two open overlays apart. Without it the
+     * panel takes CDK's default, which cannot hear a scroll from any container
+     * that is not marked `cdkScrollable` - so in a fixed-height shell the panel
+     * keeps the coordinates it was born with while the trigger scrolls away.
+     */
+    protected readonly scrollStrategy: WmAnchoredScrollStrategy;
     /** Full option list (before filtering). */
     readonly options: _angular_core.InputSignal<ComboboxOption[]>;
     /** Selected value (single-select). Two-way bindable. */
@@ -774,6 +824,164 @@ declare class WmToastContainer implements OnDestroy {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmToastContainer, "wm-toast-container", never, {}, {}, never, never, true, never>;
 }
 
+/** Where the panel sits relative to its host, before any viewport fallback. */
+type WmTooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+/**
+ * How the panel is related to the host for assistive technology.
+ *
+ * `description` points the host at the panel with `aria-describedby`. Use it
+ * when the host already has a name and the tooltip adds detail — an icon with
+ * an `aria-label`, a truncated cell, a status mark.
+ *
+ * `label` uses `aria-labelledby` instead, for an icon-only control whose only
+ * name is the tooltip. Do not use it alongside an `aria-label` on the same
+ * host: `aria-labelledby` wins, and the two texts then disagree about what the
+ * control is called depending on whether the tooltip happens to be open.
+ */
+type WmTooltipRelation = 'description' | 'label';
+/**
+ * WmTooltip — accessible floating explanation for any element.
+ *
+ * ```html
+ * <button class="wm-btn btn-icon-only" aria-label="Undo" [wmTooltip]="'Undo the last commit'">…</button>
+ * ```
+ *
+ * Why this exists next to the CSS `[data-tooltip]` chip: that chip is a
+ * pseudo-element on the host, so it cannot escape an ancestor's
+ * `overflow: hidden`, cannot wrap, and is invisible to assistive technology —
+ * it is a visual hint that must be paired with an `aria-label` saying the same
+ * thing twice. Reach for the chip for a one-to-five word label on a toolbar
+ * button. Reach for this directive when the text explains something, when the
+ * host sits inside a scrolling container, or when the explanation must be part
+ * of the accessible description rather than a duplicate of it.
+ *
+ * Accessibility:
+ *  - The panel carries `role="tooltip"` and a generated id.
+ *  - While open, the host points at that id with `aria-describedby` (default)
+ *    or `aria-labelledby`. The id is appended to whatever the host already
+ *    referenced and removed again on hide, so an application's own description
+ *    survives untouched.
+ *  - Opens on hover and on `:focus-visible`, so a mouse click that moves focus
+ *    to a button does not leave a tooltip hanging behind the pointer.
+ *  - WCAG 1.4.13 (Content on Hover or Focus): Escape dismisses without moving
+ *    focus; the pointer can travel into the panel and read it without it
+ *    closing; nothing auto-dismisses on a timer.
+ *
+ * Keyboard reachability is the caller's responsibility. A tooltip on an element
+ * that cannot take focus is unreachable by keyboard, so set
+ * `wmTooltipFocusable` to make the host a tab stop — but NOT inside a
+ * roving-tabindex container (tree, listbox, grid, tablist). There the container
+ * is a single tab stop by design, and adding one stop per row is worse for
+ * keyboard users than the gap it closes. Put the tooltip on the row itself, or
+ * expose it from a control the roving focus already reaches.
+ */
+declare class WmTooltip {
+    /** Tooltip body. Blank or absent means the tooltip never opens. */
+    readonly wmTooltip: _angular_core.InputSignal<string>;
+    /** Preferred side. Flips automatically when the viewport has no room. */
+    readonly wmTooltipPosition: _angular_core.InputSignal<WmTooltipPosition>;
+    /** Milliseconds a pointer must rest on the host before the panel opens. */
+    readonly wmTooltipDelay: _angular_core.InputSignal<number>;
+    /** Suppress the tooltip without unbinding it — for a control whose explanation only applies in some states. */
+    readonly wmTooltipDisabled: _angular_core.InputSignal<boolean>;
+    /** Whether the panel describes the host or names it. See WmTooltipRelation. */
+    readonly wmTooltipRelation: _angular_core.InputSignal<WmTooltipRelation>;
+    /**
+     * Make a non-focusable host a tab stop so a keyboard user can reach the
+     * tooltip. Only applied when the host is not already focusable, and never
+     * safe inside a roving-tabindex container — see the class comment.
+     */
+    readonly wmTooltipFocusable: _angular_core.InputSignal<boolean>;
+    private readonly host;
+    private readonly injector;
+    private readonly renderer;
+    private readonly panelId;
+    private overlayRef;
+    private panelRef;
+    private portal;
+    private showTimer;
+    private hideTimer;
+    private raiseFrame;
+    private pointerOnHost;
+    private pointerOnPanel;
+    private hostFocused;
+    private detachDocumentListeners;
+    /**
+     * Elements between the host and the document that can clip it, resolved
+     * once per open. They cannot change while the panel is up, and walking the
+     * ancestor chain on every scroll event would be work done per frame.
+     */
+    private clippingAncestors;
+    constructor();
+    /** Open the tooltip immediately, bypassing the hover delay. */
+    show(): void;
+    /** Close the tooltip immediately, without the pointer grace period. */
+    hideNow(): void;
+    /** True while the panel is attached. Exposed for tests and for callers driving it manually. */
+    get isOpen(): boolean;
+    protected onPointerEnterHost(): void;
+    protected onPointerLeaveHost(): void;
+    protected onFocusHost(): void;
+    protected onBlurHost(): void;
+    private text;
+    private scheduleShow;
+    private scheduleHide;
+    private clearTimer;
+    private ensureOverlay;
+    private positions;
+    private readonly onPointerEnterPanel;
+    private readonly onPointerLeavePanel;
+    private attachDocumentListeners;
+    private releaseDocumentListeners;
+    /**
+     * Follow the host, or give up on it.
+     *
+     * Repositioning alone is not enough. Once the host has scrolled out of its
+     * container the panel would be pushed against the container edge and left
+     * explaining a row the reader can no longer see - worse than not being there,
+     * because it now appears to describe whatever it happens to cover.
+     */
+    private reanchor;
+    /** Every ancestor that can clip the host, nearest first. */
+    private resolveClippingAncestors;
+    /** True once no part of the host is inside every container that clips it. */
+    private isHostClipped;
+    private relationAttribute;
+    private linkHostToPanel;
+    private unlinkHostFromPanel;
+    private isNativelyFocusable;
+    private matchesFocusVisible;
+    private teardown;
+    static ɵfac: _angular_core.ɵɵFactoryDeclaration<WmTooltip, never>;
+    static ɵdir: _angular_core.ɵɵDirectiveDeclaration<WmTooltip, "[wmTooltip]", ["wmTooltip"], { "wmTooltip": { "alias": "wmTooltip"; "required": false; "isSignal": true; }; "wmTooltipPosition": { "alias": "wmTooltipPosition"; "required": false; "isSignal": true; }; "wmTooltipDelay": { "alias": "wmTooltipDelay"; "required": false; "isSignal": true; }; "wmTooltipDisabled": { "alias": "wmTooltipDisabled"; "required": false; "isSignal": true; }; "wmTooltipRelation": { "alias": "wmTooltipRelation"; "required": false; "isSignal": true; }; "wmTooltipFocusable": { "alias": "wmTooltipFocusable"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+}
+
+/**
+ * Notify a handler whenever anything that can move an anchored overlay moves.
+ *
+ * This exists because of one property of the DOM that CDK's `ScrollDispatcher`
+ * does not account for: **`scroll` does not bubble.**
+ *
+ * `ScrollDispatcher` has exactly two sources. It listens for `scroll` on the
+ * document in the *bubbling* phase, which therefore only ever hears the
+ * document itself scrolling; and it hears containers that registered
+ * themselves through a `cdkScrollable` directive. In an application shell that
+ * is a fixed-height frame with an inner scrolling element — which is every
+ * Wildmason product — the document never scrolls and nothing is registered, so
+ * both sources are empty and any scroll strategy built on the dispatcher is a
+ * silent no-op. The overlay keeps the coordinates it was born with while its
+ * trigger scrolls out from under it.
+ *
+ * A **capture-phase** listener on the document sees the event from any
+ * descendant, so nothing has to be annotated. Requiring every consumer to mark
+ * their scroll containers — and failing invisibly when they forget — is not a
+ * contract a design system should hand out.
+ *
+ * @param handler called on any scroll or resize while the subscription is live
+ * @returns a function that removes exactly what was added
+ */
+declare function onViewportChange(handler: () => void): () => void;
+
 interface LicenseStatus {
     valid: boolean;
     org: string | null;
@@ -843,5 +1051,5 @@ declare class WmLicenseDialog {
     static ɵcmp: _angular_core.ɵɵComponentDeclaration<WmLicenseDialog, "wm-license-dialog", never, { "visible": { "alias": "visible"; "required": true; "isSignal": true; }; }, { "dismiss": "dismiss"; }, never, never, true, never>;
 }
 
-export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService };
-export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, LicenseStatus, SelectOption, Toast, ToastType, WmDeclaredUseType };
+export { Checkbox, GhostField, NumberInput, PageHeader, Toggle, WmAnchoredScrollStrategy, WmAutoFocus, WmButton, WmCombobox, WmDialog, WmLicenseDialog, WmLicenseNudge, WmLicenseService, WmModal, WmPopover, WmSelect, WmTab, WmTabs, WmToastContainer, WmToastService, WmTooltip, onViewportChange };
+export type { ButtonSize, ButtonVariant, ComboboxOption, DialogSize, LicenseStatus, SelectOption, Toast, ToastType, WmDeclaredUseType, WmTooltipPosition, WmTooltipRelation };

package/fonts/CascadiaCode-OFL.txt

@@ -1,94 +1,94 @@
-Copyright (c) 2019 - Present, Microsoft Corporation,
-with Reserved Font Name Cascadia Code.
-
-This Font Software is licensed under the SIL Open Font License, Version 1.1.
-This license is copied below, and is also available with a FAQ at:
-http://scripts.sil.org/OFL
-
-
------------------------------------------------------------
-SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
------------------------------------------------------------
-
-PREAMBLE
-The goals of the Open Font License (OFL) are to stimulate worldwide
-development of collaborative font projects, to support the font creation
-efforts of academic and linguistic communities, and to provide a free and
-open framework in which fonts may be shared and improved in partnership
-with others.
-
-The OFL allows the licensed fonts to be used, studied, modified and
-redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
-redistributed and/or sold with any software provided that any reserved
-names are not used by derivative works. The fonts and derivatives,
-however, cannot be released under any other type of license. The
-requirement for fonts to remain under this license does not apply
-to any document created using the fonts or their derivatives.
-
-DEFINITIONS
-"Font Software" refers to the set of files released by the Copyright
-Holder(s) under this license and clearly marked as such. This may
-include source files, build scripts and documentation.
-
-"Reserved Font Name" refers to any names specified as such after the
-copyright statement(s).
-
-"Original Version" refers to the collection of Font Software components as
-distributed by the Copyright Holder(s).
-
-"Modified Version" refers to any derivative made by adding to, deleting,
-or substituting -- in part or in whole -- any of the components of the
-Original Version, by changing formats or by porting the Font Software to a
-new environment.
-
-"Author" refers to any designer, engineer, programmer, technical
-writer or other person who contributed to the Font Software.
-
-PERMISSION & CONDITIONS
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of the Font Software, to use, study, copy, merge, embed, modify,
-redistribute, and sell modified and unmodified copies of the Font
-Software, subject to the following conditions:
-
-1) Neither the Font Software nor any of its individual components,
-in Original or Modified Versions, may be sold by itself.
-
-2) Original or Modified Versions of the Font Software may be bundled,
-redistributed and/or sold with any software, provided that each copy
-contains the above copyright notice and this license. These can be
-included either as stand-alone text files, human-readable headers or
-in the appropriate machine-readable metadata fields within text or
-binary files as long as those fields can be easily viewed by the user.
-
-3) No Modified Version of the Font Software may use the Reserved Font
-Name(s) unless explicit written permission is granted by the corresponding
-Copyright Holder. This restriction only applies to the primary font name as
-presented to the users.
-
-4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
-Software shall not be used to promote, endorse or advertise any
-Modified Version, except to acknowledge the contribution(s) of the
-Copyright Holder(s) and the Author(s) or with their explicit written
-permission.
-
-5) The Font Software, modified or unmodified, in part or in whole,
-must be distributed entirely under this license, and must not be
-distributed under any other license. The requirement for fonts to
-remain under this license does not apply to any document created
-using the Font Software.
-
-TERMINATION
-This license becomes null and void if any of the above conditions are
-not met.
-
-DISCLAIMER
-THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
-OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
-COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
-INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
-DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
-FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
-OTHER DEALINGS IN THE FONT SOFTWARE.
+Copyright (c) 2019 - Present, Microsoft Corporation,
+with Reserved Font Name Cascadia Code.
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "@wildmason/aegis",
-  "version": "1.12.0",
+  "version": "1.14.0",
   "description": "Aegis design system \u00e2\u20ac\u201d CSS tokens and Angular component library",
   "scripts": {
     "check:offline-fonts": "node scripts/check-offline-fonts.mjs",
-    "build": "npm run check:offline-fonts && npm run check:destructive-contrast && npm run check:semantic-contrast && ng-packagr -p ng-package.json",
+    "build": "npm run check:offline-fonts && npm run check:destructive-contrast && npm run check:semantic-contrast && npm run check:tooltip-contrast && ng-packagr -p ng-package.json",
     "prepublishOnly": "npm run build",
     "check:destructive-contrast": "node scripts/check-destructive-contrast.mjs",
-    "check:semantic-contrast": "node scripts/check-semantic-contrast.mjs"
+    "check:semantic-contrast": "node scripts/check-semantic-contrast.mjs",
+    "check:tooltip-contrast": "node scripts/check-tooltip-contrast.mjs"
   },
   "files": [
     "dist",

package/themes.css

@@ -275,14 +275,38 @@
   --wm-color-warning-readable: var(--wm-color-warning);
   --wm-color-success-readable: var(--wm-color-success);
 
-  /* "Readable" accent — used in `color:` (text) contexts where WCAG AA
-     contrast (4.5:1) must be met against bg-base / bg-raised / bg-float.
-     Defaults to the theme's --wm-color-accent so most themes need no
-     override; themes whose accent is too low-contrast for body text
-     (currently Stone & Moss) override this to a lighter sibling while
-     keeping --wm-color-accent itself for fills, focus rings, and other
-     non-text usages where 3:1 (WCAG 1.4.11) is sufficient. Falls back
-     to --wm-color-accent at use-time via CSS variable evaluation. */
+  /* "Readable" accent — the accent in `color:` (text) contexts: active tab
+     labels, current nav items, link-style buttons, the selected option in
+     `wm-select`. `--wm-color-accent` itself stays the interactive fill, where
+     3:1 (WCAG 1.4.11) is the bar.
+
+     The bar here is APCA Lc 60 AND WCAG AA 4.5:1, against bg-base, bg-raised
+     and bg-float, and against each of those wearing the accent's own 10% tint
+     — `--wm-bg-active`, which is exactly what `.wm-select-option.is-selected`
+     paints behind this colour.
+
+     APCA is the binding one, and it is the reason every theme now carries an
+     override. This token was tuned to WCAG alone, and on that bar it looked
+     healthy: the worst reading across all twelve themes was 4.52:1, comfortably
+     passing. On APCA, ELEVEN of the twelve failed Lc 60 on a bare surface, and
+     all twelve failed once the tint was included — including the two themes
+     that already carried a hand-tuned override for the WCAG failure. The two
+     models disagree here in the opposite direction to the destructive button,
+     where WCAG was the strict one: WCAG 2.x's luminance formula is generous to
+     mid-tone coloured text on a mid-tone ground, which is precisely this case.
+     Both bars are held rather than one being argued away.
+
+     `--wm-bg-float` binds on ten of the twelve. `sage-linen` binds on
+     bg-raised instead, because a light theme's sidebar is conventionally darker
+     than its canvas and its float is the lighter surface.
+
+     Each value is the nearest colour to the theme's own accent that clears
+     Lc 61, found by holding hue and chroma in OKLCH and walking lightness only,
+     so it stays that theme's blue, pink or sage. The target is 61 rather than
+     the 60 that is actually required: tuning to the bar exactly put
+     posh-sandalwood on Lc 60.0, which the guard read as a failure and which a
+     single hex rounding would have flipped either way. Guarded by
+     scripts/check-semantic-contrast.mjs. */
   --wm-color-accent-readable: var(--wm-color-accent);
 }
 
@@ -317,6 +341,7 @@
   --wm-color-accent: #105987;
   --wm-color-accent-hover: #2aa198;
   --wm-color-accent-text: #ffffff;
+  --wm-color-accent-readable: #004066;
 
   /* Semantic */
   --wm-color-success: #485600;
@@ -386,6 +411,7 @@
   --wm-color-accent: #1b4a9e;
   --wm-color-accent-hover: #3061af;
   --wm-color-accent-text: #ffffff;
+  --wm-color-accent-readable: #033285;
 
   /* Semantic */
   --wm-color-success: #085a50;
@@ -461,6 +487,7 @@
   --wm-color-accent: #8fc4d3;
   --wm-color-accent-hover: #81a1c1;
   --wm-color-accent-text: #2e3440;
+  --wm-color-accent-readable: #a5dbea;
 
   /* Semantic */
   --wm-color-success: #b5cf9a;
@@ -537,6 +564,7 @@
   --wm-color-accent: #c9a7fa;
   --wm-color-accent-hover: #ff79c6;
   --wm-color-accent-text: #282a36;
+  --wm-color-accent-readable: #dcc6fe;
 
   /* Semantic */
   --wm-color-success: #50fa7b;
@@ -611,6 +639,7 @@
   --wm-color-accent: #f5986a;
   --wm-color-accent-hover: #f08458;
   --wm-color-accent-text: #1c1d2e;
+  --wm-color-accent-readable: #fead85;
 
   /* Semantic */
   --wm-color-success: #5cbfa0;
@@ -686,6 +715,7 @@
   --wm-color-accent: #c4a8d8;
   --wm-color-accent-hover: #9e7abf;
   --wm-color-accent-text: #1a1715;
+  --wm-color-accent-readable: #d8bced;
 
   /* Semantic */
   --wm-color-success: #7ac4a0;
@@ -756,6 +786,7 @@
   --wm-color-accent: #185c78;
   --wm-color-accent-hover: #1e6e96;
   --wm-color-accent-text: #ffffff;
+  --wm-color-accent-readable: #00374c;
 
   /* Semantic */
   --wm-color-success: #006036;
@@ -831,13 +862,9 @@
   --wm-color-accent: #f92672;
   --wm-color-accent-hover: #fd971f;
   --wm-color-accent-text: #1c1c15;
-  /* Lighter pink sibling for "accent as text" contexts (active nav
-     items, tab labels, link-style buttons). #f92672 fails WCAG AA
-     4.5:1 on bg-float (2.9:1) and on the accent-tinted settings-nav
-     background (3.6:1); #ff8ac4 clears 5.03:1 on bg-float while
-     staying in the hot-pink hue family. Used wherever components
-     reference --wm-color-accent-readable instead of --wm-color-accent. */
-  --wm-color-accent-readable: #ff8ac4;
+  /* #ff8ac4 was chosen for the WCAG failure (#f92672 is 2.9:1 on bg-float) and
+     cleared 5.03:1, but measures APCA Lc 51.4 there. See the note in :root. */
+  --wm-color-accent-readable: #ffabd1;
 
   /* Semantic */
   --wm-color-success: #a6e22e;
@@ -913,6 +940,7 @@
   --wm-color-accent: #c09d06;
   --wm-color-accent-hover: #b15000;
   --wm-color-accent-text: #060810;
+  --wm-color-accent-readable: #dcb83a;
 
   /* Semantic */
   --wm-color-success: #4aba80;
@@ -989,6 +1017,7 @@
   --wm-color-accent: #3fb950;
   --wm-color-accent-hover: #58a6ff;
   --wm-color-accent-text: #0d1117;
+  --wm-color-accent-readable: #5dd46a;
 
   /* Semantic */
   --wm-color-success: #3fb950;
@@ -1065,12 +1094,9 @@
   --wm-color-accent: #82a682;
   --wm-color-accent-hover: #94b894;
   --wm-color-accent-text: #161817;
-  /* Brighter sage variant for "accent as text" contexts (active tab
-     labels, current nav items, link-style buttons). #82a682 fails
-     WCAG AA 4.5:1 against bg-float (3.30:1); #9bc99b clears 4.74:1
-     while staying in the moss-green hue family. Used wherever components
-     reference --wm-color-accent-readable instead of --wm-color-accent. */
-  --wm-color-accent-readable: #9bc99b;
+  /* #9bc99b was chosen for the WCAG failure (#82a682 is 3.30:1 on bg-float) and
+     cleared 4.74:1, but measures APCA Lc 54.3 there. See the note in :root. */
+  --wm-color-accent-readable: #abdaab;
 
   /* Semantic */
   --wm-color-success: #a0c5a0;
@@ -1140,6 +1166,7 @@
   --wm-color-accent: #3a5a43;
   --wm-color-accent-hover: #2c4733;
   --wm-color-accent-text: #eaf0e7;
+  --wm-color-accent-readable: #203f2a;
 
   /* Semantic */
   --wm-color-success: #3a6b48;