RealTask · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026 · Oct 13, 2026
diff --git a/README.md b/README.md
@@ -101,7 +101,7 @@ MAX-DESIGN reads only the specialist playbooks relevant to a task and combines t
 
 ## 🔎 Searchable design knowledge
 
-The catalog is a curated, offline-first knowledge base covering product profiles, visual directions, page patterns, interaction patterns, density, color strategies, typography systems, motion recipes, UX/accessibility rules, chart patterns, and stack guidance. It uses original MAX-DESIGN guidance shaped by a comparative review of public UI/UX knowledge taxonomies; it does not bundle UI/UX Pro Max data files or scripts.
+The merged, offline-first knowledge base combines `knowledge/design-patterns.json` with `knowledge/advanced-patterns.json`. It covers visual directions, product profiles, page and interaction patterns, adaptive density, semantic color, typography, motion, UX/accessibility, charts, stack guidance, AI streaming and failure states, privacy and permissions, account/billing flows, search/filter persistence, data quality, and evidence-based performance review. The guidance is authored for MAX-DESIGN; it does not bundle UI/UX Pro Max data files or scripts. Research references and limits are documented in `docs/knowledge-sources.md`.
 
 Run these commands **from the installed `max-design` directory**:
 
@@ -115,6 +115,10 @@ node scripts/search-design-knowledge.mjs "form errors" --domain ux
 node scripts/search-design-knowledge.mjs "chart accessibility" --domain chart
 node scripts/search-design-knowledge.mjs "responsive charts" --domain stack
 node scripts/search-design-knowledge.mjs "responsive charts" --require-all --limit 5
+node scripts/search-design-knowledge.mjs "modal focus lifecycle" --domain ux
+node scripts/search-design-knowledge.mjs "offline retry" --domain ux
+node scripts/search-design-knowledge.mjs "subscription invoice" --domain page
+node scripts/search-design-knowledge.mjs "Core Web Vitals" --domain stack
 ```
 
 Domains: `all`, `direction`, `page`, `interaction`, `density`, `product`, `style`, `color`, `typography`, `motion`, `ux`, `chart`, and `stack`. Use `--json` for structured output. Search uses weighted fields, related terms, Unicode normalization, related-term expansion, and stable ordering. Matches are contextual starting points, not automatic style prescriptions; verify colors, APIs, accessibility, and framework-version assumptions against the actual project.
@@ -152,7 +156,9 @@ Domains: `all`, `direction`, `page`, `interaction`, `density`, `product`, `style
 - `docs/preflight-checklist.md` — before-delivery checklist
 - `examples/design-brief.md` — reusable brief and acceptance-criteria template
 - `examples/design-tokens.json` — illustrative semantic token structure
-- `knowledge/design-patterns.json` — local searchable design-knowledge catalog across 12 domains
+- `knowledge/design-patterns.json` — core local searchable catalog across 12 domains
+- `knowledge/advanced-patterns.json` — 30 supplementary production patterns and implementation checks
+- `docs/knowledge-sources.md` — research provenance, authoritative references, and evidence limits
 - `scripts/validate-skills.mjs` — toolkit structure, token, catalog, and search smoke checks
 - `scripts/search-design-knowledge.mjs` — local design-knowledge search CLI
 

diff --git a/SKILL.md b/SKILL.md
@@ -46,9 +46,13 @@ node scripts/search-design-knowledge.mjs "reduced motion" --domain motion
 node scripts/search-design-knowledge.mjs "chart accessibility" --domain chart
 node scripts/search-design-knowledge.mjs "responsive charts" --domain stack
 node scripts/search-design-knowledge.mjs "responsive charts" --require-all --limit 5
+node scripts/search-design-knowledge.mjs "modal focus lifecycle" --domain ux
+node scripts/search-design-knowledge.mjs "offline retry" --domain ux
+node scripts/search-design-knowledge.mjs "subscription invoice" --domain page
+node scripts/search-design-knowledge.mjs "Core Web Vitals" --domain stack
 ```
 
-Available domains: `all`, `direction`, `page`, `interaction`, `density`, `product`, `style`, `color`, `typography`, `motion`, `ux`, `chart`, and `stack`. Use `--json` for machine-readable results. The catalog is at `knowledge/design-patterns.json`; the search implementation is at `scripts/search-design-knowledge.mjs`. Search remains local and requires no network connection or third-party runtime dependency.
+Available domains: `all`, `direction`, `page`, `interaction`, `density`, `product`, `style`, `color`, `typography`, `motion`, `ux`, `chart`, and `stack`. Use `--json` for machine-readable results. The search loader merges `knowledge/design-patterns.json` and `knowledge/advanced-patterns.json`; the search implementation is at `scripts/search-design-knowledge.mjs`. The supplementary records include advanced product workflows, AI streaming, account and billing, privacy and permissions, resilient network states, ARIA widget behavior, WCAG 2.2 checks, chart data integrity, and evidence-based performance review. Research provenance and source limitations are documented in `docs/knowledge-sources.md`. Search remains local and requires no network connection or third-party runtime dependency.
 
 ### 4. Select a specific direction
 

diff --git a/docs/knowledge-catalog.md b/docs/knowledge-catalog.md
@@ -1,6 +1,6 @@
 # Searchable knowledge catalog
 
-MAX-DESIGN ships an offline-first JSON catalog at `knowledge/design-patterns.json`. It is designed for retrieval by an AI coding agent without a network connection or third-party runtime dependency.
+MAX-DESIGN ships an offline-first, merged JSON catalog sourced from `knowledge/design-patterns.json` and `knowledge/advanced-patterns.json`. The search utility loads both catalogs locally, so retrieval works without network access or third-party runtime dependencies.
 
 ## Knowledge domains
 
@@ -21,6 +21,13 @@ MAX-DESIGN ships an offline-first JSON catalog at `knowledge/design-patterns.jso
 
 Use `--domain all` (the default) for cross-domain retrieval, `--json` for structured results, `--explain` to see search matches, and `--require-all` only when every query term must match.
 
+
+## Advanced coverage
+
+The supplementary catalog adds original decision records for AI generation and streaming states, account and subscription settings, search-first catalogs, operational data workspaces, command palettes, optimistic updates and rollback, persistent filter state, permission requests, privacy-aware authentication, network failures, status announcements, destructive-action recovery, empty versus missing versus stale data, WCAG 2.2 focus and target checks, modal focus lifecycle, combobox keyboard behavior, Core Web Vitals evidence, and accessible time-series/chart alternatives.
+
+Keep specialist catalog entries task-specific: explain when a pattern fits, the expected behavior, edge states, risks, and how to verify it. A URL in a record is a research reference, not a claim that the entire design is certified or universally appropriate. Review [knowledge sources and research notes](knowledge-sources.md) when extending the catalog.
+
 ## Examples
 
 ```bash
@@ -50,7 +57,7 @@ Quality rules:
 
 ## Research and originality
 
-The knowledge structure was informed by a comparative review of public UI/UX catalog categories, including [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), whose project documents structured guidance for styles, product reasoning, palettes, typography, UX checks, motion, charts, icons, and framework stacks. MAX-DESIGN's records and search implementation are authored for this repository; the upstream project's data tables, catalog text, and scripts are not bundled here.
+The knowledge structure was informed by a comparative review of public UI/UX catalog categories, including [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), and checked against primary accessibility and platform documentation where relevant. MAX-DESIGN's records and search implementation are authored for this repository; upstream data tables, catalog text, and scripts are not bundled here. See [knowledge-sources.md](knowledge-sources.md) for source roles and limits.
 
 ## Verification
 

diff --git a/docs/knowledge-sources.md b/docs/knowledge-sources.md
@@ -0,0 +1,50 @@
+# Design-knowledge research notes and sources
+
+Reviewed for this catalog update: 13 October 2026.
+
+This document records the role and limits of the external references used to shape MAX-DESIGN's original guidance. It is intentionally separate from the catalog records: agents should use concise, task-specific decision records, while humans can audit their evidence basis here.
+
+## Research method
+
+1. Compare public UI/UX catalog taxonomies to identify missing decision areas, not to copy datasets. The comparison reference was [UI/UX Pro Max](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill), including its public guidance on product reasoning, design-system selection, styles, typography, UX checks, charts, and stack-aware recommendations.
+2. Check accessibility and widget-behavior guidance against primary standards and maintainer documentation where available.
+3. Translate those findings into original MAX-DESIGN records: when a pattern fits, what behavior it implies, which failure states matter, what to verify, and common risks.
+4. Keep measurements, claims of conformance, platform recommendations, and heuristics distinct. A reference link does not certify a product or implementation.
+
+## Source map
+
+| Topic | Primary reference | How MAX-DESIGN uses it | Evidence limits |
+| --- | --- | --- | --- |
+| Web accessibility requirements | [W3C Web Content Accessibility Guidelines (WCAG) 2.2](https://www.w3.org/TR/WCAG22/) | Focus visibility and obstruction, target-size checks, contrast, keyboard access, and verification planning | WCAG is normative guidance for its stated scope. A catalog record or automated scan alone cannot establish conformance. |
+| Custom widget behavior | [WAI-ARIA Authoring Practices Guide (APG)](https://www.w3.org/WAI/ARIA/apg/) | Expected keyboard behavior and semantics for dialogs, comboboxes, tabs, and similar widgets | APG is implementation guidance; use the applicable pattern and test real browser/assistive-technology behavior. Do not copy ARIA roles without their behavior. |
+| Modal dialog lifecycle | [APG: Dialog (Modal) Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/) | Focus entry, containment while modal, close behavior, and focus restoration | The appropriate initial focus and dismissal rules depend on the task and dialog content. |
+| Search suggestions | [APG: Combobox Pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/) | Keyboard handling, active option, suggestion behavior, and async result states | Combobox variants have different interaction models; choose one intentionally rather than mixing patterns. |
+| Native semantics and ARIA | [MDN: ARIA](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA) | Prefer native HTML controls; use ARIA to express additional semantics and state where needed | ARIA does not implement interaction logic or make a nonfunctional custom widget accessible by itself. |
+| Keyboard access | [MDN: Keyboard accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility/Guides/Understanding_WCAG/Keyboard) | Logical focus order, visible focus, and keyboard equivalence for pointer actions | Static source review does not prove every key path works in a rendered page. |
+| Performance metrics | [web.dev: Web Vitals](https://web.dev/articles/vitals) | Encourage explicit measurement of loading, responsiveness, and visual stability; identify field versus lab evidence | Metrics vary by measurement source and context. Never invent results or generalize from a single run. Check current metric definitions and thresholds on the source. |
+| Platform-aware motion | [Apple Human Interface Guidelines: Motion](https://developer.apple.com/design/human-interface-guidelines/motion) | Purposeful, brief, optional motion; reduce unnecessary movement; keep interactions responsive | Apple guidance is platform-specific inspiration, not automatically a web standard or a substitute for reduced-motion checks. |
+| Inclusive platform design | [Apple Human Interface Guidelines: Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) | Larger text support, multiple ways to perceive status, accessible control size, and motion sensitivity considerations | Use guidance appropriate to the target platform; do not transfer platform-specific dimensions to web WCAG claims without checking the relevant standard. |
+| Catalog taxonomy and retrieval ideas | [UI/UX Pro Max repository](https://github.com/nextlevelbuilder/ui-ux-pro-max-skill) | Comparative review of topics such as product profiles, styles, typography, UX, charts, and stack guidance | Used for topic discovery only. MAX-DESIGN does not bundle its datasets, catalog text, or scripts. |
+
+## Evidence labels for future records
+
+Use these distinctions while adding knowledge:
+
+- **Normative requirement:** explicitly required by a named standard within its scope. State the standard and relevant criterion when practical.
+- **Authoring guidance:** a recommended implementation pattern from a standards body or platform owner.
+- **Measured result:** an observed value with tool, scope, environment, and method. Do not store fabricated or context-free metrics.
+- **Practical heuristic:** an original recommendation whose usefulness depends on the product, audience, and context.
+- **Assumption:** a temporary choice made because project evidence is missing; label it and verify it.
+
+A sensible default is to link to primary sources rather than embed large excerpts from them. Re-check source pages when standards or platform guidance evolve, particularly before making normative claims.
+
+## Updating this research
+
+When extending the catalog:
+
+1. Search the existing records first to avoid duplicates and synonym collisions.
+2. Read the relevant primary source and record only the claims needed for the decision.
+3. Add a unique kebab-case ID, task-oriented tags, applicable states, risks, and verification steps.
+4. Link the source with the affected record; never use a reference as a substitute for testing.
+5. Run `npm test`, including search smoke tests for new tags and domain coverage.
+6. Inspect the final search results for misleading matches, duplicate records, or a heuristic that sounds like a universal rule.