stylegallery 0.1.12 → 0.1.13

package/consumer-reference/agent-native/v2/schema/admission-policy.schema.json

@@ -13,8 +13,8 @@
     "media_type": { "const": "text/markdown" },
     "allowed_materials": {
       "type": "array",
-      "minItems": 180,
-      "maxItems": 180,
+      "minItems": 193,
+      "maxItems": 193,
       "items": {
         "type": "object",
         "additionalProperties": false,

package/design-engineering/evidence-patterns/autocomplete.md

@@ -0,0 +1,83 @@
+---
+type: Domain Guide
+title: Autocomplete Acceptance
+description: Distinguish typed text, active suggestion, and accepted identity without stealing editing or composition keys.
+aliases: ["autocomplete","typeahead suggestions","suggestion acceptance","manual combobox selection"]
+questions: ["When should an autocomplete suggestion become the accepted value?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Autocomplete Acceptance
+
+Primary role: suggestion acceptance and recovery guide.
+
+## Repository Boundary
+
+This page specifies acceptance choices on top of [Native Interaction Contracts](../native-interaction-contracts.md). It does not duplicate the full combobox keyboard model. [Text Input](../text-input-and-internationalization.md) owns IME; [Latest Request Wins](../state-management/patterns/latest-request-wins.md) owns asynchronous suggestion authority.
+
+## Reusable Method
+
+### Problem And Use
+
+A highlighted suggestion may be mistaken for a committed value, or a label may survive after its entity changes. Use autocomplete when suggestions reduce effort across a large meaningful set. Avoid custom autocomplete when a native select, datalist, or ordinary search-results page meets the task.
+
+### Recommended Rules
+
+1. Declare whether arbitrary text is valid or a known entity is required. Keep draft text, active option, and accepted ID distinct.
+2. Local starting point: manual acceptance. Arrow navigation previews a candidate; Enter or pointer activation commits it. Choose automatic acceptance only with its documented blur behavior.
+3. For a custom editable combobox with a listbox popup, keep DOM focus in the input, expose expanded state and controlled popup, and use an active descendant only for an existing option.
+4. Escape dismisses suggestions without discarding the draft under the local manual policy. Do not let composition-confirming Enter also commit a suggestion or submit.
+5. Zero suggestions is not a failed request. Keep a normal submit/recovery path and reject obsolete suggestion responses.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [APG combobox](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) | Living guidance, read 2026 | Defines four autocomplete behaviors and distinguishes manual from automatic selection, including automatic acceptance on blur. Specifies focus, editing, and popup relationships. No measured optimum suggestion count or debounce delay. |
+
+### Example
+
+Native suggestions are sufficient when arbitrary text is valid. This local example deliberately avoids pretending that datalist guarantees a known entity or equivalent behavior in every screen reader.
+
+```html
+<form action="/search" method="get">
+  <label for="topic">Topic</label>
+  <input id="topic" name="q" list="topics">
+  <datalist id="topics">
+    <option value="Accessibility"></option>
+    <option value="Navigation"></option>
+    <option value="Forms"></option>
+  </datalist>
+  <button>Search</button>
+</form>
+```
+
+For an entity-only field, validate the accepted identity at submission and explain when edited text has invalidated it. A custom replacement must implement the full selected APG contract, not just copy roles.
+
+## Opinionated Guidance
+
+Keep candidate browsing reversible. Treat a suggestion count such as 5 or a delay such as 200 ms as a measured product choice if used, not a number supplied by APG.
+
+## Platform-Specific Guidance
+
+Native datalist presentation/support differs across browsers and assistive technologies. Test the actual mobile keyboard, IME, touch acceptance, and focus behavior before adopting it.
+
+## Unsupported Absolutes
+
+Highlighted does not always mean accepted. `aria-autocomplete` does not implement filtering. APG permits several valid models; manual acceptance is a local default, not universal proof of superiority.
+
+## Verification Contract
+
+Proposed checks: edit after selection, duplicate labels with distinct IDs, stale response, zero suggestions, network error, keyboard acceptance, pointer acceptance, Escape, and real IME composition. Accessibility requires a persistent name, coherent popup state, preserved editing keys, and verified announcements. No consumer execution is claimed. Re-review when acceptance or suggestion identity changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and example; APG rechecked 2026-10-19. No upstream implementation copied. `consumer_reference: not_applicable` because no consumer combobox record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Breadcrumb Hierarchy](breadcrumbs.md).

package/design-engineering/evidence-patterns/bottom-navigation.md

@@ -0,0 +1,78 @@
+---
+type: Domain Guide
+title: Bottom Navigation Destinations
+description: Reserve persistent bottom navigation for peer destinations and keep actions and temporary task steps separate.
+aliases: ["bottom navigation","bottom tab bar","primary destinations","mobile navigation bar"]
+questions: ["Which destinations belong in a bottom navigation bar?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Bottom Navigation Destinations
+
+Primary role: primary destination selection guide.
+
+## Repository Boundary
+
+This page owns product destination selection, not a native tab-bar implementation. [Adaptive Navigation](../../platform-guides/adaptive-navigation.md) owns presentation changes; Layout owns sticky/fixed scroll constraints. Web links do not inherit a native platform's Back stack.
+
+## Reusable Method
+
+### Problem And Use
+
+A bar mixing navigation, creation, and workflow steps has unpredictable state. Use bottom navigation for frequently revisited peer destinations. Avoid it for linear checkout steps, contextual commands, or a large unprioritized sitemap.
+
+### Recommended Rules
+
+1. Start from the platform recommendation of 3-5 peer destinations when adapting Android's navigation bar. This is not a universal web mandate or measured optimal count.
+2. Keep destination names and ordering stable. Do not replace an empty destination with a command just because it has no content yet.
+3. On the web, use named navigation with ordinary links and indicate the current destination. Do not assign `tab` roles to route links solely to copy a native appearance.
+4. Local proposal: retain visible text labels; familiar icons alone can still be ambiguous. Preserve access at larger text sizes and in translated content.
+5. If fixed to the bottom, reserve content space and honor safe-area/keyboard behavior. Verify that the bar does not obscure focus or the final action.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [Android layouts and navigation](https://developer.android.com/design/ui/mobile/guides/layout-and-content/layout-and-nav-patterns?hl=en) | Living official guidance, read 2026 | Recommends 3-5 same-hierarchy destinations and adaptation to a rail on large screens. Convention guidance, not an experimental comparison or CSS breakpoint specification. |
+| [APG tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/) | Living guidance, read 2026 | Defines tabs as layered content panels. That definition distinguishes a tab widget from ordinary destination links; no bottom-bar performance measurement. |
+
+### Example
+
+Local route-link fragment. It intentionally does not claim native navigation-stack behavior.
+
+```html
+<nav aria-label="Main">
+  <a href="/overview" aria-current="page">Overview</a>
+  <a href="/projects">Projects</a>
+  <a href="/activity">Activity</a>
+  <a href="/account">Account</a>
+</nav>
+```
+
+## Opinionated Guidance
+
+Prioritize destinations by task evidence, not to fill five slots. Put Create or Delete in the relevant task surface rather than disguising them as destinations.
+
+## Platform-Specific Guidance
+
+Android navigation bars, Apple tab bars, and browser links have different host behavior. Preserve selected identity and drafts during a bar-to-rail transformation; record OS/browser and safe-area assumptions separately.
+
+## Unsupported Absolutes
+
+Bottom placement is not universally easier for every device or motor ability. Five destinations is not a WCAG limit. Hiding a label does not make an ambiguous icon self-explanatory.
+
+## Verification Contract
+
+Proposed checks: direct destination link, Back/Forward, selected state, preserved draft, empty destination, virtual keyboard, short viewport, and large text. Accessibility requires named links, visible focus, logical reading order, and unobscured controls. Check target-size requirements separately in [Input And Focus](../../platform-guides/input-and-focus.md). No consumer execution is claimed. Re-review when hierarchy or persistence changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and fragment; official sources rechecked 2026-10-19. No native artwork or code copied. `consumer_reference: not_applicable` because no consumer navigation record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Dark Mode Contrast](dark-mode-contrast.md).

package/design-engineering/evidence-patterns/breadcrumbs.md

@@ -0,0 +1,78 @@
+---
+type: Domain Guide
+title: Breadcrumb Hierarchy
+description: Expose a stable parent path without confusing hierarchy with browser history or search-filter state.
+aliases: ["breadcrumb hierarchy","parent navigation","breadcrumb semantics","location trail"]
+questions: ["Should breadcrumbs represent page hierarchy or browsing history?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Breadcrumb Hierarchy
+
+Primary role: hierarchy navigation guide.
+
+## Repository Boundary
+
+This page owns breadcrumb meaning. [Breadcrumb Layout](../../patterns/in-line-grouping/breadcrumb.md) owns wrapping; [Adaptive Navigation](../../platform-guides/adaptive-navigation.md) separates Parent/Up from Back; URL state owns filter history.
+
+## Reusable Method
+
+### Problem And Use
+
+A visitor arriving by a direct link lacks navigation history but still needs a parent route. Use breadcrumbs when a meaningful hierarchy helps orientation. Avoid fabricating a hierarchy for a flat task or using a sequence of recently visited pages as though it were ancestry.
+
+### Recommended Rules
+
+1. List parent destinations in hierarchical order, not chronological history.
+2. Use one labeled navigation landmark for the trail. Use ordinary links for ancestors; no custom arrow-key widget is needed.
+3. If the current page is linked, expose `aria-current="page"`. For unlinked current text, APG makes that attribute optional.
+4. Local proposal: choose one coherent parent path for a multiply categorized item, or explain the selected context. Do not silently change a canonical path based on accidental browsing history.
+5. At narrow widths, retain useful parent access and the current location. Test wrapping or a labeled collapse rather than shrinking targets or clipping names.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [APG breadcrumb](https://www.w3.org/WAI/ARIA/apg/patterns/breadcrumb/) | Living guidance, read 2026 | Defines hierarchical parent links, a labeled navigation landmark, and current-page semantics. No comparative study or proven maximum depth. |
+
+### Example
+
+```html
+<nav aria-label="Breadcrumb">
+  <ol>
+    <li><a href="/library">Library</a></li>
+    <li><a href="/library/reports">Reports</a></li>
+    <li><a href="/library/reports/annual" aria-current="page">Annual report</a></li>
+  </ol>
+</nav>
+```
+
+The links remain normal document navigation. Decorative separators belong to consumer presentation and must not become confusing accessible names.
+
+## Opinionated Guidance
+
+Keep breadcrumbs secondary to the page heading and primary navigation. A short trail can be useful; an arbitrary "at least three levels" requirement is not supported by this source.
+
+## Platform-Specific Guidance
+
+On mobile, keep parent links usable under text scaling. A native Back action may leave the hierarchy entirely; do not label a history action as a parent link.
+
+## Unsupported Absolutes
+
+Breadcrumbs are not a substitute for primary navigation. A filter chip is not necessarily a hierarchical ancestor. No evidence here establishes a universal separator, depth limit, or single-line requirement.
+
+## Verification Contract
+
+Proposed checks: direct deep link, browser Back from an unrelated origin, multiple categories, long labels, RTL, zoom, and collapsed trail expansion. Accessibility requires a named landmark, correct current-page indication, ordinary keyboard links, and logical order. No consumer execution is claimed. Re-review when hierarchy or canonical routes change.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and example; APG rechecked 2026-10-19. No source samples copied. `consumer_reference: not_applicable` because no consumer navigation record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Bottom Navigation Destinations](bottom-navigation.md).

package/design-engineering/evidence-patterns/dark-mode-contrast.md

@@ -0,0 +1,83 @@
+---
+type: Domain Guide
+title: Dark Mode Contrast
+description: Measure text and meaningful controls in each actual theme and state instead of assuming a dark palette is accessible.
+aliases: ["dark mode contrast","theme contrast","non-text contrast","contrast ratios"]
+questions: ["Which contrast ratios apply to a dark theme?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Dark Mode Contrast
+
+Primary role: theme contrast verification guide.
+
+## Repository Boundary
+
+This page owns product theme verification, not shared color tokens. [Preferences And Accessibility](../../platform-guides/preferences-and-accessibility.md) owns preference resolution; [Accessibility Evidence](../../quality/evidence/accessibility.md) owns claim admissibility. Layout receives no palette values from this guide.
+
+## Reusable Method
+
+### Problem And Use
+
+Inverting a light palette can make muted text, borders, and focus disappear. Use this method for each authored theme and meaningful state. Avoid assuming that a system dark-mode preference also requests high contrast or reduced motion.
+
+### Recommended Rules
+
+1. At WCAG AA, ordinary text needs at least 4.5:1 and large-scale text at least 3:1, with SC 1.4.3 exceptions. Large-scale means at least 18pt regular or 14pt bold, approximately 24 or 18.67 CSS px.
+2. Under SC 1.4.11, visual information needed to identify controls/states and meaningful graphical parts needs at least 3:1 against adjacent colors, subject to its exceptions. Not every decorative border is required.
+3. Measure the actual foreground/background pair after opacity and layering, including hover, selected, error, focus, and placeholder text.
+4. Local proposal: keep a contrast inventory for both light and dark themes, plus forced-colors verification. No universal surface-brightness ladder follows from these criteria.
+5. Do not communicate error or selection by color alone. A passing ratio does not establish the separate requirements for focus visibility, focus obstruction, or text resizing.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [Contrast Minimum, SC 1.4.3](https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html) | 2024 Recommendation; living explanation read 2026 | Specifies 4.5:1/3:1 text thresholds and exceptions. These are conformance thresholds, not a dark-theme preference study. |
+| [Non-text Contrast, SC 1.4.11](https://www.w3.org/WAI/WCAG22/Understanding/non-text-contrast.html) | 2024 Recommendation; living explanation read 2026 | Specifies 3:1 for required visual identification and meaningful graphics with exceptions. Does not require every control to have a border. |
+
+### Example
+
+Local consumer CSS illustrates explicit theme pairs, not a reusable palette. Black/white opaque text pairs have 21:1 contrast; real component states still need measurement.
+
+```css
+.theme_sample {
+  background: #fff;
+  color: #000;
+}
+
+@media (prefers-color-scheme: dark) {
+  .theme_sample {
+    background: #000;
+    color: #fff;
+  }
+}
+```
+
+## Opinionated Guidance
+
+Review contrast where it fails most easily: secondary copy, disabled-looking but active controls, overlays, and thin focus indicators. Disabled/inactive exceptions do not justify making active help or error text unreadable.
+
+## Platform-Specific Guidance
+
+Dark appearance and forced colors are separate inputs. Verify browser/system adjustments rather than disabling them to preserve a screenshot. Native color roles do not prove equivalent authored web colors.
+
+## Unsupported Absolutes
+
+Dark mode is not inherently accessible or proven better for everyone. A contrast preference is not a contrast measurement. A static palette calculation does not prove every composited state.
+
+## Verification Contract
+
+Proposed checks: computed pairs in both themes, transparency over varying content, hover/focus/error/selection, forced colors, text scaling, and runtime theme changes in open overlays. Accessibility requires ratios within scope plus non-color meaning and operable visible focus. Record pairs, ratios, state, and tool; do not round a failing ratio up. No consumer execution is claimed. Re-review when palette, opacity, typography, or layers change.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and example; W3C sources rechecked 2026-10-19. No platform colors copied. `consumer_reference: not_applicable` because no consumer palette record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Loading, Progress, And Feedback](../loading-and-feedback.md).

package/design-engineering/evidence-patterns/data-tables.md

@@ -0,0 +1,86 @@
+---
+type: Domain Guide
+title: Data Table Interaction
+description: Preserve comparison and table semantics while adding truthful sorting, usable density, and bounded sticky headers.
+aliases: ["data tables","sortable table","table density","sticky table header"]
+questions: ["How should a data table expose sorting and retain headers?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Data Table Interaction
+
+Primary role: tabular task and interaction guide.
+
+## Repository Boundary
+
+This page owns table meaning, sorting, and comparison decisions. Layout owns scroll constraints and [sticky mechanics](../../patterns/viewport-shell/sticky-header.md). Density is consumer styling, not permission to decorate reusable Layout CSS.
+
+## Reusable Method
+
+### Problem And Use
+
+Dense records become hard to compare when headers vanish or sorting is unexplained. Use a table for meaningful row/column relationships and comparison. Avoid a table solely to align unrelated cards; use a grid widget only when its composite interaction is genuinely needed.
+
+### Recommended Rules
+
+1. Start with `table`, caption, and header cells. Use native interactive controls inside headers rather than making an entire header an unlabeled click target.
+2. Local default: one primary sorted column, with its actual `aria-sort` state. A multi-sort product needs an explicit priority order and explanation.
+3. Specify numeric/text/date ordering and null placement. A remote sort must sort the declared dataset, not silently only the current page.
+4. Keep a header visible when long comparison tasks need it, but name the scroll container and ensure sticky rows never hide focused controls.
+5. Offer comfortable versus compact density only if it serves a real task. No source establishes a universal row height; interactive targets must independently meet the applicable target-size criterion.
+6. Keep stable record identity and selection through sorting. For virtualized rows, verify exposed row counts/indices and real assistive-technology navigation.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [NN/g four table tasks](https://www.nngroup.com/articles/data-tables/) | 2022 | Workplace task observations, including an eye-tracking example, support comparison, locating records, editing, and actions. Recommends frozen headers for large tables; does not report a universal density threshold or controlled time saving. |
+| [APG table](https://www.w3.org/WAI/ARIA/apg/patterns/table/) | Living guidance, read 2026 | Distinguishes a static table with interactive descendants from a composite grid; describes sort and virtual-row semantics. No experiment. |
+
+### Example
+
+Local server-sorted response: following the header link requests ascending order. The displayed rows and `aria-sort` describe the currently descending result, not the next action.
+
+```html
+<table>
+  <caption>Open invoices, highest amount first</caption>
+  <thead><tr>
+    <th scope="col">Invoice</th>
+    <th scope="col" aria-sort="descending">
+      <a href="/invoices?sort=amount&amp;direction=asc">Amount: sort ascending</a>
+    </th>
+  </tr></thead>
+  <tbody>
+    <tr><th scope="row"><a href="/invoices/27">INV-27</a></th><td>$90.00</td></tr>
+    <tr><th scope="row"><a href="/invoices/31">INV-31</a></th><td>$45.00</td></tr>
+  </tbody>
+</table>
+```
+
+## Opinionated Guidance
+
+Place related comparison columns near one another. A row editor should not obscure adjacent reference data unless modality is justified.
+
+## Platform-Specific Guidance
+
+On narrow screens, preserve required comparison relationships and indicate horizontal scrolling. Do not assume visually stacked cells still expose correct headers.
+
+## Unsupported Absolutes
+
+More rows per screen does not prove better productivity. `role="grid"` does not implement arrow-key navigation. A sticky header is not inherently accessible.
+
+## Verification Contract
+
+Proposed checks: equal sort keys, nulls, negative amounts, server pagination, sorting selected rows, 320px width, zoom, long headers, and focus under sticky rows. Accessibility requires header relationships, named sort controls, accurate sort state, and operable scroll. No consumer execution is claimed. Re-review on sort scope, virtualization, or density changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and fragment; sources rechecked 2026-10-19. No upstream examples copied. `consumer_reference: not_applicable` because no consumer table record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Tabs And Segmented Controls](tabs-and-segmented-controls.md).

package/design-engineering/evidence-patterns/empty-states.md

@@ -0,0 +1,80 @@
+---
+type: Domain Guide
+title: Empty States And No Results
+description: Distinguish first use, completed zero matches, cleared collections, denied access, and failed loading.
+aliases: ["empty states","no results","zero matches","first use onboarding"]
+questions: ["What should users see when a search returns no results?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Empty States And No Results
+
+Primary role: empty-state diagnosis and recovery guide.
+
+## Repository Boundary
+
+This page owns the explanation and next action for absent content. [Loading And Feedback](../loading-and-feedback.md) owns pending/failure truth; [Faceted Filters](faceted-filters.md) owns query scope. Onboarding here is contextual help, not an implementation of account setup.
+
+## Reusable Method
+
+### Problem And Use
+
+A blank panel gives no reason for absence. Use an empty state after the state owner can explain it. Avoid "No records" while a request is still pending or when permission is insufficient to know whether records exist.
+
+### Recommended Rules
+
+1. Local classification: distinguish at least first use, completed zero matches, deliberately cleared content, permission limitation, and failure. They require different next actions.
+2. For first use, explain what belongs here and provide one primary path to create/import it, if authorized. Contextual help can replace a forced introductory tour.
+3. For zero matches, retain the exact query and applied filters. Offer edit/remove constraints, not an unrelated create action.
+4. For an intentionally cleared inbox, acknowledge completion rather than pushing onboarding again.
+5. Keep failure retry and access-request actions truthful. An empty state must not imply a successful read when the request failed.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [NN/g empty-state design](https://www.nngroup.com/articles/empty-state-interface-design/) | 2021 | Practitioner analysis and observed application examples of confusion, contextual learning cues, and direct task pathways. No controlled effect size or universal action-count optimum reported. |
+| [Status Messages, SC 4.1.3](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html) | 2024 Recommendation; living explanation read 2026 | Dynamic result statuses need programmatically determinable semantics without taking focus when they meet the criterion's status-message definition. No usability experiment. |
+
+### Example
+
+Local server-rendered completed search. The clear-filter URL retains the query, rather than silently resetting the whole task.
+
+```html
+<section aria-labelledby="results-title">
+  <h2 id="results-title">Search results</h2>
+  <p>No matches for "ceramic" with color: blue.</p>
+  <a href="/catalog?q=ceramic">Remove the color filter</a>
+  <a href="/catalog">Start a new search</a>
+</section>
+```
+
+For an in-place update, keep an existing concise `role="status"` region and update its text after accepting the response. Do not make every result card a live region or automatically move focus on each query.
+
+## Opinionated Guidance
+
+Prefer an actionable explanation over decorative apology. Demo data can help first use only when clearly labeled and distinguishable from user-owned records.
+
+## Platform-Specific Guidance
+
+An offline cache, native permission state, and an empty server response are distinct. Preserve that distinction through app suspension, navigation, and retry.
+
+## Unsupported Absolutes
+
+An empty list is not always an error. One primary action is a local hierarchy proposal, not a measured law. A successful onboarding illustration does not establish task completion.
+
+## Verification Contract
+
+Proposed checks: new account, filtered zero, last item removed, denied access, pending read, offline cache, failed request, and Back to a previous query. Accessibility requires a meaningful heading, keyboard recovery actions, retained focus for passive updates, and correctly scoped status semantics. No consumer run is claimed. Re-review when data ownership or empty-state classification changes.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and fragment; sources rechecked 2026-10-19. No upstream prose or artwork copied. `consumer_reference: not_applicable` because no consumer collection record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Data Table Interaction](data-tables.md).

package/design-engineering/evidence-patterns/error-recovery.md

@@ -0,0 +1,84 @@
+---
+type: Domain Guide
+title: Error Messages And Recovery Summaries
+description: Explain actionable field errors and make failed submissions discoverable without losing input.
+aliases: ["error summary","form error messages","adaptive errors","validation recovery"]
+questions: ["How should a form show errors after submission?"]
+domain: design-engineering
+lifecycle: experimental
+provenance_kind: local
+reviewed_on: 2026-10-19
+---
+
+# Error Messages And Recovery Summaries
+
+Primary role: form error recovery guide.
+
+## Repository Boundary
+
+This page owns explanatory errors and their recovery route. [Inline Validation](inline-validation.md) owns timing; [Loading And Feedback](../loading-and-feedback.md) distinguishes confirmed failure from an unknown operation outcome. Shared [accessibility evidence](../../quality/evidence/accessibility.md) remains authoritative.
+
+## Reusable Method
+
+### Problem And Use
+
+A generic failure leaves users guessing which value to change. Use field errors for input rejection and an overall summary when a submitted form has errors that may be offscreen. Avoid blaming a field for network failure, permission denial, or an uncertain payment outcome.
+
+### Recommended Rules
+
+1. Identify the field and the actual violated rule; give a known correction, subject to security and purpose exceptions in SC 3.3.3.
+2. Local proposal: one summary at the start of the rejected form, with one link per erroneous field in reading order. A single obvious inline error may need less scaffolding.
+3. Preserve accepted entries. On server-rendered failure, expose failure in the page title/main heading; on dynamic failure, choose a deliberate focus or announcement strategy.
+4. Keep summary and inline errors synchronized. Remove corrected entries or update the summary on the next validation boundary.
+5. Use the real constraint in a numeric message, such as "Choose between 1 and 8 seats", only when that is the actual product limit. Do not invent a universal message count.
+
+### Evidence
+
+| Source | Year | What was measured or specified |
+| --- | --- | --- |
+| [Baymard adaptive errors](https://baymard.com/research-articles/adaptive-validation-error-messages) | 2023 | Checkout observations include users taking up to five minutes to resolve simple errors with vague messages. This is an observed extreme, not a mean or causal estimate. The 98% generic-message figure is site prevalence, not user failure rate. |
+| [Error suggestion, SC 3.3.3](https://www.w3.org/WAI/WCAG22/Understanding/error-suggestion.html) | 2024 Recommendation; living explanation read 2026 | Known correction suggestions required at AA unless security or purpose would be jeopardized; no measured effect size. |
+| [WAI form notifications](https://www.w3.org/WAI/tutorials/forms/notifications/) | Living tutorial, read 2026 | Informative guidance on summaries, links, inline relationships, titles, and notifications; not an experimental comparison. |
+
+### Example
+
+Local server-rendered rejected-form fragment; the server must populate only actual current errors and retain the submitted value safely.
+
+```html
+<section aria-labelledby="errors">
+  <h2 id="errors">Check your booking</h2>
+  <ul><li><a href="#seats">Seats: choose between 1 and 8.</a></li></ul>
+</section>
+<form action="/booking" method="post">
+  <label for="seats">Seats</label>
+  <input id="seats" name="seats" type="number" min="1" max="8"
+    value="9" aria-invalid="true" aria-describedby="seats-error">
+  <p id="seats-error">Choose between 1 and 8 seats.</p>
+  <button>Review booking</button>
+</form>
+```
+
+## Opinionated Guidance
+
+Use a focused summary for a dynamic failed submission when it helps recovery, but do not combine focus movement and duplicate assertive announcements blindly. Baymard's 4-7 messages for complex inputs is a checkout heuristic, not a requirement to manufacture errors.
+
+## Platform-Specific Guidance
+
+Native validation bubbles, server navigation, and live updates expose different notification paths. Verify summary-link focus and scroll with sticky headers and zoom.
+
+## Unsupported Absolutes
+
+An error summary is not explicitly mandated by WCAG for every form. Account-existence disclosure is not justified by a general preference for specific errors.
+
+## Verification Contract
+
+Proposed checks: multiple offscreen errors, one error, long localized copy, corrected dependency, server rejection, keyboard summary links, and 400% zoom. Accessibility requires associated inline text, meaningful heading order, visible focus, and no color-only indication. Record actual speech rather than assuming `role="alert"` guarantees it. No consumer execution is claimed. Re-review when constraints, error codes, or notification ownership change.
+
+## Source, License, And Attribution
+
+Locally authored synthesis and fragment; sources rechecked 2026-10-19, no source implementation copied. `consumer_reference: not_applicable` because no consumer error record is selected.
+
+## IA Navigation
+
+Parent: [Evidence Patterns](index.md).
+Next: [Persistent Form Labels](form-labels.md).