@luigisbox/luma 0.0.0-stage → 0.1.0

package/docs/ACCESSIBILITY.md

@@ -0,0 +1,502 @@
+# Accessibility
+
+For contributors and integrators. What the law asks of the shops Luma runs
+on, what the previous-generation Luma did about it, what Luma guarantees now, what an
+integration's templates must do themselves, the high-contrast mode, how all
+of it is tested, and how an integration checks itself (`yarn luma a11y`, §8).
+Paths are relative to the package root; `core/…`, `widgets/…`, `api/…` are under `src/`.
+
+## 1. The requirement
+
+Luma runs inside e-commerce sites. Since **28 June 2025** those sites are in
+scope of the **European Accessibility Act**, Directive (EU) 2019/882:
+
+| | |
+|---|---|
+| Scope | Art. 2(2)(f): "e-commerce services" are one of the covered services. |
+| Date | Art. 31(2): Member States "shall apply those measures from 28 June 2025". |
+| Obligation | Art. 4(3): every covered service complies with Annex I, Section III. Art. 4(5): micro-enterprises that provide services are exempt. |
+| Websites | Annex I, Section III(c): websites, related online applications and mobile services must be accessible "by making them perceivable, operable, understandable and robust". Section IV adds requirements specific to e-commerce (e.g. identification and payment). |
+| Colour | Annex I, Section I, point 2(d) (products, the same principle): where colour conveys information, indicates an action or identifies elements, an alternative to colour is provided; 2(c): flexible magnification, brightness and contrast. |
+| How to show conformity | Art. 15(1): conforming to harmonised standards cited in the Official Journal gives a presumption of conformity. |
+
+The standard is **EN 301 549**. V3.2.1 (2021) applies WCAG 2.1 A and AA to web
+content and is what the Web Accessibility Directive uses. **V4.1.1** (adopted
+24 August 2026, published 2 September 2026) is the first version written for
+the EAA: it moves web content to **WCAG 2.2 A and AA** and maps clauses to the
+Act in its Annex ZB. Its presumption of conformity applies once the Official
+Journal cites it (expected December 2026). Clause 11.7 ("User preferences")
+asks software that is not isolated from its platform to follow the platform's
+colour, contrast, font and focus settings. Web content is assessed under
+WCAG, but a page that follows the OS contrast settings (`prefers-contrast`,
+`forced-colors`) is what that clause asks of software.
+
+So the target is **WCAG 2.2 AA**. The criteria Luma's widgets touch:
+
+| WCAG 2.2 | What it means here |
+|---|---|
+| 1.3.1 Info and relationships (A) | listbox/option/group, fieldsets, a named region, headings |
+| 1.4.1 Use of colour (A) | a selected row, ticked filter or active sort is not shown by colour alone |
+| 1.4.3 Contrast, minimum (AA) | text at 4.5:1 (3:1 large) |
+| 1.4.4 Resize text, 1.4.10 Reflow (AA) | 200% text, 320 CSS px wide (400% zoom) without horizontal scrolling |
+| 1.4.11 Non-text contrast (AA) | borders of controls, focus rings, selection indicators at 3:1 |
+| 2.1.1 Keyboard, 2.1.2 No keyboard trap (A) | every control by keyboard; the drawer's focus trap releases on Escape and close |
+| 2.3.3 Animation from interactions (AAA) | motion off under `prefers-reduced-motion` (AAA, cheap to honour) |
+| 2.4.3 Focus order (A), 2.4.7 Focus visible (AA), 2.4.11 Focus not obscured (AA) | focus moves into a drawer and back, never lost to `<body>` |
+| 2.5.2 Pointer cancellation (A) | actions on `click` (up event), never on `pointerdown` |
+| 2.5.8 Target size, minimum (AA) | 24 x 24 CSS px, or the spacing exception |
+| 4.1.2 Name, role, value (A) | the combobox on the host's input, `aria-expanded`, `aria-selected`, slider values |
+| 4.1.3 Status messages (AA) | result counts, "No results", errors, announced politely without moving focus |
+
+Sources: [Directive (EU) 2019/882](https://eur-lex.europa.eu/eli/dir/2019/882/oj/eng)
+(read via [legislation.gov.uk's copy](https://www.legislation.gov.uk/eudr/2019/882/contents): Art. 2, 4, 15, 31, Annex I),
+[EN 301 549 V4.1.1](https://www.etsi.org/deliver/etsi_en/301500_301599/301549/04.01.01_60/en_301549v040101p.pdf),
+[its publication and OJ timing](https://www.dwt.com/insights/2026/09/european-accessibility-act-ict-standards-update),
+[WCAG 2.2](https://www.w3.org/TR/WCAG22/), [technique G174](https://www.w3.org/WAI/WCAG22/Techniques/general/G174)
+(a control that switches to a sufficient-contrast presentation),
+[WAI-ARIA APG combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+
+## 2. The previous-generation high-contrast mode
+
+The previous-generation Luma had an opt-in "High-contrast mode" switch: a
+button, visually hidden unless the OS asked for a contrast preference, that
+turned the widget grayscale and forced black text on white, plus automatic
+attribute changes (guessed labels and alt text, `tabindex="0"` and
+`role="button"` on button-like elements). Luma's mode (§4) keeps what was
+right about it (WCAG technique G174 for 1.4.3: a control to a presentation
+with sufficient contrast) and differs where WCAG asks for more: no grayscale (a product's
+colour, stock dots are information: 1.4.1), no focusable invisible switch
+(2.4.7), no blanket roles or tab stops on non-interactive elements (4.1.2), no
+guessed alt text, and forced colours and the OS setting are honoured.
+
+## 3. What Luma guarantees
+
+### Autocomplete (`widgets/autocomplete/index.ts`)
+
+- **The host's input is the combobox** (WAI-ARIA APG, list autocomplete):
+  `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`,
+  `aria-controls` (the dropdown, `#lbx-ac-overlay` or the integration's
+  `hostId`), and in light DOM `aria-activedescendant` (the selected option's
+  id, `lbx-ac-<i>`). Set when the input gets focus, **put back as they were**
+  when focus leaves it (`borrow`, `core/a11y.ts`), also when the input is in a
+  shadow root and focus moves to a control beside it there (that focusout
+  never leaves the root: Luma listens on the input's shadow roots). An attribute the host
+  changes meanwhile is the host's current truth and is not overwritten on
+  restore: a framework that manages ARIA on its own input keeps it. No
+  attribute is set while the input is not focused; the value is never touched.
+- **Shadow DOM:** an ID reference never crosses a shadow boundary. An id
+  inside our shadow root (the default dropdown) cannot be referenced from
+  anywhere else, so there is no `aria-activedescendant` (never a dangling
+  one); the selected option's text is announced through our status region
+  instead. A light-DOM dropdown (`dom: 'light'`) has both for an input in the
+  document. For a host input inside a shadow root (a web-component header)
+  the dropdown's id would name nothing from the input's tree, so the option
+  is referenced by element reflection (`input.ariaActiveDescendantElement`,
+  feature-detected; the attribute reads `""` then): the
+  document encloses the input's shadow root, which reflection allows. An
+  engine without it gets the announcement, never an id.
+- **The listbox** (the house design's templates): `role="listbox"` named
+  "Search suggestions", one `role="group"` per section named by its heading
+  (phrases, each other type, "Top product", "Products"), options that are not
+  tab stops (`tabindex="-1"`: focus stays in the input) with `aria-selected`
+  following the keyboard and the pointer. "Show all products", "Powered by"
+  (`aria-hidden`) and the "No results" message are outside the options; with
+  no results, the phrases to try and the links are a listbox of their own,
+  the fallback products another, named by their heading and the note that
+  they are not results; the help box's phone link is a plain link. "Show all
+  products" is a real link (`href`: the
+  search page the site's form would submit to) and the open dropdown's one
+  tab stop: Tab from the input reaches it, Shift+Tab goes back, Escape closes
+  and goes back, Tab moves on to the page's next control after the input.
+- **Status messages**: "Suggestions: N" or "No results for “…”", in a polite
+  `role="status"` region inside the dropdown, once typing pauses (700 ms), and
+  only when it changes within an opening (not per keystroke).
+- **Keys** as before: arrows move the selection, Enter picks it (or is the
+  host's search), Escape closes ours first, as whole gestures. Focus never
+  leaves the input on a click or a tap (`pointerdown` on the dropdown is
+  prevented); only Tab moves it, to "Show all products".
+- **Colours**: the host's text and accent colours are sampled only where they
+  read at 4.5:1 on our white panel (`readable`, `core/a11y.ts`; a dark site's
+  light text or a pale brand colour falls back); text on an accent fill is
+  white or near-black by the accent's luminance. Headings, the muted text
+  (`--lbx-muted`, fg 66% in white) and "No results" are 4.5:1. The selection is
+  never a faint colour alone: an accent fill (pills), or the tint with an
+  accent ring (cards) or edge (rows). Tokens an integration sets
+  (`autocomplete.tokens`, its CSS) are its own to keep at 4.5:1 (`yarn luma a11y`).
+- **The phone sheet** (house design, viewport up to 600 px): its own input is
+  the combobox (`aria-controls` the listboxes on screen,
+  `aria-activedescendant` the selected option: the same shadow root); the
+  site's input is left as it was. The back button is named "Close search",
+  the clear button "Clear"; the type tabs are a `tablist` (arrow keys move
+  between them); Tab is the browser's; targets are 44 px; Escape and the
+  browser's Back close it.
+- **Forced colours**: the selection in `Highlight`/`HighlightText` with an
+  outline, the panel (and the sheet) keep a `CanvasText` border, pills,
+  chips and "Show all products" an outline.
+
+### Listings (`widgets/listing/element.ts`)
+
+- **A named region**: `<lbx-search>` / `<lbx-plp>` get `role="region"` and
+  `aria-label` ("Search results" / "Products", translations `search.label`,
+  `plp.label`), server-rendered too, and `tabindex="-1"` (focus target only).
+- **Status messages** in our own polite region (`[data-lbx-a11y]`, first in
+  the element, outside the templates): after every render the visitor caused
+  (a filter, a sort, back/forward, a new query in place: "N results for “q”"
+  or the route's `results`; show more: "Showing N of M"; an empty result; an
+  error). Not on the page's first render, not on a background revalidation.
+  Announced once ours is shown (a hidden region is not read). Templates need no
+  `aria-live` of their own (the built-in header's was removed: two would speak).
+- **Busy**: `aria-busy="true"` on the element while a fetch runs; it is cleared
+  before the render that announces.
+- **Focus is never lost**: "show more" from the keyboard moves focus to the
+  first new tile's main control (the tile itself when it is a link, else its
+  first control in the Tab order that is not `aria-hidden`: never a picture
+  link marked `tabindex="-1"`); a render that removed the focused control (a
+  chip, the last "show more") moves it to the region, not `<body>`. A mouse
+  click keeps focus where it is.
+- **Menus** (`[data-lbx-menu]` with `[data-lbx-toggle]`, the integration's
+  markup): `aria-expanded` on the menu's button (the toggle with
+  `aria-haspopup`/`aria-expanded`, else the first toggle) in every state;
+  opened from the keyboard, focus goes to its selected item
+  (`aria-selected`/`aria-current`/`aria-checked`), else the first; arrows move
+  through its items; Escape closes it and focus returns to the button; picking
+  an item returns focus to the button; Tab out of it closes it.
+- **The drawer** (`[data-lbx-drawer="open|close"]`): `aria-expanded` on its
+  openers. With a panel marked `[data-lbx-drawer-panel]`, while open, the panel
+  is a modal dialog (`role="dialog"`, `aria-modal="true"`, named "Filters",
+  translation `search.drawer`, unless the markup names it), focus moves to its
+  first control, Tab and Shift+Tab stay inside, Escape closes it, and focus
+  returns to the opener. Closed, the attributes are removed (on wide screens
+  the same markup is a sidebar). A change inside it updates it in place,
+  focus staying on the control. With `facetsApply: 'staged'` its
+  changes wait for `[data-lbx-drawer="apply"]`; closing it otherwise discards
+  them (the scope's `pending` says whether there is anything to apply).
+- **Facet groups** (built-in template): each group's title is a `<button
+  aria-expanded aria-controls>` controlling its values (WAI-ARIA APG
+  accordion), focus staying on it. A group's search box
+  (`facetGroups.search`) is a labelled `type="search"` input ("Search in
+  Colour", translation `search.facetSearch`), the count of matches next to
+  it (`aria-describedby`) and said in the listing's status region once typing
+  pauses; Escape clears it (and does not close the drawer), Enter submits
+  nothing.
+- **Range facets** (built-in `search-range-default`): two native range
+  inputs (role `slider`, `aria-valuemin`/`max`/`now` from the input itself),
+  named "Price: minimum" / "Price: maximum" (`search.rangeMin`,
+  `search.rangeMax`), `aria-valuetext` in the facet's unit ("120 €",
+  `search.units.<facet>`), inside the group's `fieldset`; the number inputs
+  beside them named "Price from" / "Price to" (`search.rangeFrom`,
+  `search.rangeTo`). Keys: arrows a step, Page Up / Page Down a tenth, Home /
+  End the end a thumb may reach (never past the other thumb), the same on
+  every engine; a platform's adjust gesture (VoiceOver's swipe) moves it as
+  well. Nothing is requested while a thumb moves: a pause after the keys,
+  Enter, focus leaving or the pointer's release commits. The focused thumb
+  carries its own ring (both inputs span the track); targets 24 px tall
+  (the thumb 24 px by default, `--lbx-range-thumb-size`); forced colours
+  map the track, fill and thumbs to system colours.
+- **Chips** (built-in template): a group named "Selected filters", each chip
+  a link named "Remove filter: Colour: White".
+- **Enter and Space on `role="button"` markup** (a `div` copied from a site,
+  `role="option"` list items, …) inside our element click it, as a button
+  would; native controls and links keep their own keys.
+- Built-in templates: the pager is a native "Show more" button with a
+  "Showing N of M" line (no numbered pages); tile pictures are decorative
+  (`alt=""`: the link reads as its title and price once); targets of at least
+  24 px; no fade under reduced motion; tiles reflow to one column at 320 px.
+
+### Recommenders (`widgets/recommender/`)
+
+- Inline: a `section` named by its title (default "Recommended for you",
+  `recommender.title`), tiles are links in a scrolling row (Tab reaches each).
+- Popup: `role="dialog"` named by its title, a 44 px close button named
+  "Close", Escape closes it. It is not modal and does not take focus (it
+  appears after the shopper's own add-to-cart click; moving focus there would
+  pull them away from the host's notice).
+
+### Every widget
+
+- **Focus ring**: `:focus-visible` gets an outline in our subtrees (`@layer
+  lbx`, so the site's own focus styles win); in forced colours and in the
+  high-contrast mode a 3 px ring with `!important` (a site's `outline: none`
+  reset cannot remove it there).
+- **Reduced motion**: the hold's loading bar stands still, the listing's
+  dim while a re-render loads comes without its fade and the new results
+  without their fade-in, no smooth scrolling of ours.
+- `.lbx-sr-only`: a class for text that only screen readers read (e.g. "Was"
+  before an old price), defined for every widget and in server-rendered CSS.
+
+## 4. The high-contrast mode
+
+**On automatically** with the visitor's OS setting `prefers-contrast: more`
+(macOS "Increase contrast", Windows/GNOME high-contrast preferences), **in
+CSS**: no script runs for it. **Forced colours** (Windows contrast themes,
+`forced-colors: active`) are the browser's own mode: our CSS keeps state
+visible there (system colours, outlines, borders instead of shadows).
+
+**The palette** is a set of custom properties on `:root` (`core/a11y.ts`,
+`CONTRAST_CSS`), defined only while the mode is on:
+
+| Property | Value | Used for |
+|---|---|---|
+| `--lbx-c` | `1` | "the mode is on" |
+| `--lbx-c-fg`, `--lbx-c-bg` | `#000`, `#fff` | text, panels |
+| `--lbx-c-line` | `#000` | borders |
+| `--lbx-c-muted` | `#000` | what is normally muted (section headings, "No results") |
+| `--lbx-c-accent` | `#000` | links in brand colour |
+| `--lbx-c-sel-fg`, `--lbx-c-sel-bg` | `#fff`, `#000` | a selected row (inverted) |
+| `--lbx-c-border` | `2px` | border width |
+| `--lbx-c-ring` | `3px` | focus ring width |
+| `--lbx-c-dim` | `1` | no dimming of a busy listing |
+| `--lbx-c-underline` | `underline` | tile titles underlined |
+
+Every rule of ours reads them with its normal value as the fallback
+(`color: var(--lbx-c-muted, color-mix(...))`). Unlike the previous-generation mode it does
+not grayscale (product colours are information) and it keeps images.
+
+**The toggle** (opt-in, as the previous generation had it): `_global.contrastToggle: true`
+puts a "High-contrast mode" button (`aria-pressed`, translation `contrast`)
+first in every listing. It is visually hidden until it has focus, unless the
+OS asks for a contrast preference or the mode is on (as before, but
+never an invisible focused button). The choice is remembered in
+`localStorage` (`lbx:contrast`: `more`, or `off` to override the OS setting);
+switching back to what the OS says forgets it.
+
+**State for integrations' CSS**: once a widget has started, `<html>` carries
+`data-lbx-contrast="more"` while the mode is on (the toggle or the OS
+setting: one selector for both) and `"off"` when the visitor switched it off
+against their OS setting. Without JavaScript (a server-rendered listing before
+its bundle) only the custom properties apply.
+
+### Adopting it in an integration
+
+An integration's templates copy the site's markup, so Luma's palette does not
+reach their colours. Add rules for the classes the template uses:
+
+```css
+/* The mode (OS setting or toggle): their greys and brand colour as black on white,
+   states drawn, not only coloured. */
+:root[data-lbx-contrast="more"] lbx-plp .price-old { color: #000 !important; }
+:root[data-lbx-contrast="more"] lbx-plp input:checked ~ .checkmark { background: #000 !important; }
+/* Or read Luma's palette where a value can fall back to the site's: */
+.facet-chip { border-color: var(--lbx-c-line, #ccc); }
+/* Windows contrast themes: backgrounds are dropped, so a custom checkbox loses
+   its fill; draw state in system colours. */
+@media (forced-colors: active) {
+  lbx-plp input:checked ~ .checkmark { forced-color-adjust: none; background: Highlight; }
+}
+```
+
+A production integration's rules typically cover its custom checkboxes, sort
+tabs, chips, range slider and the site's greys.
+
+## 5. What integrations must do in their templates
+
+Luma owns the input's ARIA, the status messages, focus, keys, menus and the
+drawer. The markup is the integration's, so:
+
+- **Autocomplete in light DOM** (`dom: 'light'`): render a `role="listbox"`
+  with an `aria-label` around the options, options as `role="option"` with
+  `id="lbx-ac-<i>"` (Luma's `aria-activedescendant` points there) and
+  `aria-selected`, `tabindex="-1"`; sections as `role="group"` named by their
+  heading; wrappers in between `role="presentation"`; nothing but options and
+  groups inside the listbox (a pointer-only "show all" duplicate of Enter:
+  `aria-hidden="true"`, no tab stop). Decorative pictures `alt=""`.
+- **Listings**: filter groups as `fieldset` + `legend` (or `role="group"`
+  with a name); native checkboxes, or links with `role="checkbox"` and
+  `aria-checked` (never `aria-checked` on a plain link); chips named by what
+  they remove (`aria-label=${t('removeFilter', { label })}`: "Remove filter:
+  Acme", the "×" `aria-hidden`); a range's two thumbs named ("Price min" /
+  "Price max") with `aria-valuetext` in real units when the input's own scale
+  is not; collapsible groups with `aria-expanded` on their buttons.
+- **Menus**: the trigger is a `<button>` with `aria-haspopup`; items are
+  focusable (links, buttons, or `role="option"` + `tabindex="0"`) and the
+  current one carries `aria-selected`/`aria-current`; a close button has a name.
+- **The drawer**: put `data-lbx-drawer-panel` on the panel; the opener may be
+  a `role="button"` div (Luma adds the keys) but a `<button>` is better.
+- **Tiles**: one link name (the picture `alt=""` when the title is in the same
+  link); a struck-through old price says so (`<span class="lbx-sr-only">Was
+  </span>`), and the current one "Now" next to it.
+- **Colour**: text at 4.5:1, states not by colour alone, 24 px targets; adopt
+  the high-contrast mode (§4) for the colours your CSS sets.
+- **Don't** add `aria-live` to counts (Luma announces), set `tabindex="0"` on
+  non-interactive elements, or remove focus outlines without a replacement.
+
+## 6. Audit (2026-10-01)
+
+On the test harness hosts (MPA, the framework suites) and a production
+integration (its templates on its stub page with the site's stylesheet and the
+live Luigi's Box AI API). Severity: **critical** blocks a task for some users,
+**serious** a WCAG AA failure, **moderate** a usability issue.
+
+| Widget | Finding | Severity | Status |
+|---|---|---|---|
+| Autocomplete | host input had no combobox semantics (no role, expanded, controls, active option): screen readers did not know a popup opened or what was selected | critical | fixed (Luma) |
+| Autocomplete | listbox without a name; `h3` headings and "See all" inside the listbox (axe `aria-required-children`, critical) | critical | fixed (built-in; the integration's template) |
+| Autocomplete | result count / "No results" never announced | serious | fixed (Luma) |
+| Autocomplete | the sampled host colours could be unreadable on our white panel (dark sites, pale accents); headings at opacity .6 (4.3:1) | serious | fixed (Luma) |
+| Autocomplete | selection by a 12% tint only; invisible in forced colours | serious | fixed (Luma; the integration's own styles in forced colours / contrast mode) |
+| Autocomplete | options were tab stops; an integration's "Show all" was a nested `role=button` pair of tab stops | moderate | fixed |
+| All | an integration's template: a site palette grey under 4.5:1 copied for section headings, tile sub-headers, old prices, empty filter values | serious | contrast mode only; the site's palette (site-wide) |
+| Listings | counts announced only where a template had `aria-live`, and inside a busy region | serious | fixed (Luma status region) |
+| Listings | focus lost to `<body>` when a render removed the focused chip or "show more" | serious | fixed (Luma) |
+| Listings | sort menu and drawer: no `aria-expanded`, no focus management, no Escape; drawer not a dialog, no trap or return | serious | fixed (Luma + `data-lbx-drawer-panel`) |
+| Listings | `role="button"` divs (an integration's filter button, sort list items, sheet items) not operable by keyboard | serious | fixed (Luma keys; sheet items focusable in the integration) |
+| Listings | test integration: `aria-checked` on plain links (axe critical); chips named "Acme ×" | critical | fixed (fixture) |
+| Listings | an integration's template: range inputs 6 px tall (target size); thumb values read as 0-1000 | serious | fixed (integration) |
+| Listings | an integration's template: a filter group's expander a `span` (mouse only); clear-range button named "Close"; chips named by their label only; tile link name doubled by the picture's alt; old price read without "was" | serious | fixed (integration) |
+| Listings | busy fade and transitions ignored `prefers-reduced-motion` | moderate | fixed |
+| Recommender | inline box was not a named region; popup close button 31 px | moderate | fixed |
+| Recommender | an integration's template: arrows' disabled state only as a class; smooth scroll under reduced motion | moderate | fixed (integration) |
+| All | no high-contrast mode; no forced-colours handling | serious (EN 301 549 11.7 spirit, 1.4.3 via G174) | fixed (§4) |
+| Hold | loading bar animation under reduced motion | moderate | fixed |
+
+**What remains (the host's, or a design decision):**
+
+- A site palette grey under 4.5:1 (headings in the dropdown, tile sub-headers,
+  old prices, empty filter values) site-wide; the integration copies it to
+  stay 1:1 with the site's pages. The mode fixes it; normal mode needs the
+  site's design.
+- A light-DOM dropdown that copies the site's own design can show the keyboard
+  selection by colour (a coloured title, a grey pill) in normal mode, as the
+  site's own dropdown did (an outline in forced colours and the mode).
+- The recommender popup is not modal and does not take focus (by design).
+- The host's own header, menus and focus resets (`*:focus { outline: none }`)
+  outside our nodes; their search input's label.
+- Touch screen readers: VoiceOver iOS and TalkBack navigate the dropdown by
+  swiping (it is in the top layer, after the page); not automated here.
+
+## 7. How it is tested
+
+Luma's own suites (not part of the package). In short:
+
+- A browser harness runs the pinned `axe-core` (offline) over our nodes only
+  (WCAG 2.0-2.2 A/AA tags) and keeps what fails a test; it computes contrast
+  ratios as rendered and reads the input's attributes and focus.
+- Axe on every widget state (dropdown open with a
+  selection and with no results, in shadow and light DOM; listings with
+  filters and chips, Luma's built-in templates, the drawer open, forced
+  colours; recommender inline and popup), the combobox lifecycle and the
+  host's own ARIA kept, announcements (typing pauses, filter, show more,
+  in-place query, error), focus (show more, removed chip, menu, drawer trap and
+  return), media features (`emulateMedia`: forced colours, `contrast: more`,
+  reduced motion) by computed styles, contrast ratios, reflow at 320 px,
+  target sizes, the toggle.
+- The host contract: a combobox and a listing accessibility check run on
+  every host suite (MPA, the SPA template, Angular, Vue, Nuxt, React, …).
+- `yarn luma a11y`'s flows (§8) on a test shop: the test integration passes
+  them all, planted faults fail per criterion; its report has its own tests.
+- Unit tests: contrast maths and the readable-colour guard,
+  `borrow`'s restore rules, Enter/Space on `role="button"`, the status
+  region's timing, the mode's state, the loading bar's reduced-motion rule.
+- By hand, before a release on a client: a screen reader pass (VoiceOver on
+  macOS and iOS, NVDA on Windows) through typing, picking a suggestion,
+  filtering, the drawer and show more; Windows contrast themes; 400% zoom.
+
+## 8. Checking an integration: `yarn luma a11y`
+
+For the developer of an integration: one command answers "does it pass
+WCAG 2.2 AA?" (the level EN 301 549 V4.1.1 asks for the European
+Accessibility Act, §1) for Luma's widgets as the integration renders them.
+From the integration repository: `yarn luma a11y`
+(README, "Tools for an integration repository": the one `luma` script). The
+storefront's host name is its `luma.config.mjs` `host` (`LBX_HOST` overrides it;
+the browser token is minted for that origin). Its dependencies come with Luma
+(Playwright, axe-core; with the `luma/` submodule: `yarn --cwd luma install`
+once); the browser is Playwright's Chromium or the installed Chrome,
+`LBX_CHROMIUM_PATH` otherwise.
+
+```bash
+yarn luma a11y                                   # /, the search page, the configured category and product pages
+yarn luma a11y /search?q=shoes /some-category /some-product
+yarn luma a11y --html                            # + a11y-report.html (self-contained)
+yarn luma a11y --only autocomplete,search --query shoes
+yarn luma a11y --dev                             # from yarn dev (https://localhost:8069), no build
+```
+
+**What it does.** It builds the integration (`yarn build`; `--no-build` uses
+`dist/` as it is), opens Chromium on the storefront's host name with Luma as a customer
+installs it: the early-hold snippet first in `<head>`, then the build as the
+platform's loader imports it (`parity/hold.mjs`; Luigi's Box's CDNs blocked, so
+only the build under test runs), on the integration's stub page
+(`luma.config.mjs` `stubPage`, the site's markup and stylesheet) with the live
+Luigi's Box AI API. `--origin live` (or `LBX_ORIGIN=https://…`) loads the real
+storefront instead; a bot challenge, a block or a rate limit is never worked
+around: the run falls back to the stub page and says so in the report. Then it
+drives the real widgets, by keyboard where a shopper would:
+
+| Widget | States |
+|---|---|
+| autocomplete | typed into `_global.inputSelector`: open, two ArrowDowns, forced colours, `prefers-contrast: more`, no results, Escape, focus gone |
+| search | reached through the header's search form; shown, Tab through it, a filter ticked from the keyboard, the sort menu (Enter, Escape), phone width (375 px) with the sort menu and the filter drawer, 320 px, `prefers-contrast: more`, forced colours, reduced motion |
+| category pages | the same, on `luma.config.mjs` `fixtures.category` (or a path given) |
+| recommenders | inline boxes on `luma.config.mjs` `fixtures.product` (scrolled into view): shown, Tab, 320 px, contrast modes, reduced motion. The popup opens on an add-to-cart click, which the command never makes (nor a wishlist or comparison click) |
+
+On every state: axe-core (pinned, the same runner as Luma's suites,
+`a11y/axe.mjs`) with the WCAG 2.0, 2.1 and 2.2 A and AA rules, **scoped to
+Luma's nodes** (`lbx-search`, `lbx-plp`, `lbx-reco`, the dropdown); the same
+run over the rest of the page is **the host page's**, reported for information
+only (it never fails the run). Then what axe cannot decide:
+
+| Check | WCAG |
+|---|---|
+| the input is a combobox while open (`role`, `aria-expanded`, `aria-autocomplete`), `aria-controls` names the dropdown, one option `aria-selected` and `aria-activedescendant` on it (light DOM; from an input in a shadow root, `ariaActiveDescendantElement`), focus stays in the input, Escape closes, the input's ARIA as the host had it once focus leaves | 4.1.2, 2.1.1, 2.4.3 |
+| the count announced (dropdown; listing after a filter) | 4.1.3 |
+| a filter applied from the keyboard; focus not lost to `<body>` after the re-render | 2.1.1, 2.4.3 |
+| Tab through each widget: focus visible on every stop (its look changes); controls by role that cannot get focus; checkboxes `display:none` behind a drawn box | 2.4.7, 2.1.1 |
+| the sort menu: `aria-expanded`, focus in, Escape back to its button | 4.1.2, 2.4.3 |
+| the drawer: a named modal dialog, focus in and kept, Escape back to the opener | 4.1.2, 2.1.2, 2.4.3 |
+| 24 px targets (axe's `target-size`, with the spacing exception) | 2.5.8 |
+| reflow at 320 CSS px: nothing of ours past the viewport (a scrolling row of its own excepted) | 1.4.10 |
+| `prefers-contrast: more`: axe again, a focus ring; forced colours: the selected suggestion and a ticked custom checkbox still look so, a focus ring | 1.4.3, 1.4.11, 1.4.1, 2.4.7 |
+| `prefers-reduced-motion`: transitions of position, animations, smooth scrolling of ours | advice (2.3.3 is AAA) |
+
+**The report**, per success criterion: failed ones with each issue (rule,
+impact, the states it was seen in, up to five nodes with their markup, a
+**hint to the file and line** of the template or style that renders the node,
+and how to fix it in an integration), then the criteria that passed, advice,
+axe's "needs review" items, the host page's issues, and the criteria no
+automated check decides (a screen reader pass covers what is left, §7).
+`--html [file]` writes the same as a page, `--json <file>` as data.
+
+**Exit code**: 0 when nothing fails on Luma's widgets, 1 when something does,
+2 when no widget could be exercised (a build that does not boot, a stub page
+without the anchors). In CI: `yarn luma a11y --html`,
+the report as an artifact.
+
+**Reading it.** A failure in a node the hint maps to `integration/` is the
+integration's to fix (§5 lists what templates must do); one in Luma's built-in
+templates (`src/widgets/` in the package) or in Luma's own checks with no template
+involved (the combobox, focus, status messages) is Luma's: report it with the
+output. A site-wide palette (a grey the integration copied to stay 1:1 with
+the site's own pages) fails 1.4.3 in normal mode even when the high-contrast
+mode fixes it (§4): that is a design decision for the shop, and the report
+says so rather than passing it. What it does not cover: a screen reader's
+actual speech, touch screen readers, 200 % text zoom with the site's own CSS,
+content the host renders around ours.
+
+Example output (illustrative):
+
+```
+Checked
+  autocomplete: open, keyboard selection, forced colours, prefers-contrast: more, no results, closed, focus left the input
+  search: shown, keyboard (Tab through), filter applied (keyboard), sort menu (keyboard), phone width (375 px), sort menu (phone), filter drawer (phone), reflow (320 px), prefers-contrast: more, forced colours, reduced motion
+  plp: …the same…
+  recommender mlt: shown, keyboard (Tab through), reflow (320 px), prefers-contrast: more, forced colours, reduced motion
+  recommender popup: not checked (opens on an add-to-cart click, which this command never makes)
+
+Failed: 1 success criteria
+
+✗ 1.4.3 Contrast (minimum) (AA)
+    color-contrast [serious] Elements must meet minimum color contrast ratio thresholds
+      - #lbx-ac-g-brand > .group-title
+        → integration/autocomplete/template-autocomplete.ts:42 (.group-title)
+        Element has insufficient color contrast of 2.85 (foreground color: #999999, background color: #ffffff, …)
+      …
+Passed: 15 success criteria
+  ✓ 1.1.1 Non-text content … ✓ 4.1.3 Status messages
+
+FAIL: 1 success criteria, 1 issue on Luma's widgets.
+```
+
+Code: `a11y/run.mjs` (options, the browser, the build), `a11y/audit.mjs`
+(the flows), `a11y/report.mjs` (verdict, hints, text and HTML),
+`a11y/wcag.mjs` (the criteria, axe tags, fix texts). Tests: §7.