From facee6120b72b830ea21522cb17c9c575805ef0e Mon Sep 17 00:00:00 2001
From: Minsu Lee <1964421+amondnet@users.noreply.github.com>
Date: Fri, 30 Oct 2026 15:46:30 +0900
Subject: [PATCH] fix(modern-web-guidance): vendor plugin into the marketplace

Install the modern-web-guidance and chrome-extensions skills from
GoogleChrome/modern-web-guidance@4f2b13e via skills.sh into
plugins/modern-web-guidance and switch the marketplace source to the
local path, so installing the plugin (or frontend@passionfactory, which
depends on it) no longer clones the upstream repo. The skills-lock.json
puts it under the weekly update-skills.yml refresh. The upstream
Apache-2.0 LICENSE is kept; upstream ships no NOTICE file.

The version continues upstream's 0.0.196 so existing installs never see
a lower version.
---
 .agents/plugins/marketplace.json              |   4 +-
 .claude-plugin/marketplace.json               |   5 +-
 .cursor-plugin/marketplace.json               |   5 +
 .release-please-manifest.json                 |   1 +
 README.md                                     |   6 +
 .../.agents/skills/chrome-extensions/SKILL.md | 530 ++++++++++++++
 .../references/extensions/api-calling.md      |  72 ++
 .../references/extensions/auth-identity.md    | 141 ++++
 .../references/extensions/content-scripts.md  | 112 +++
 .../references/extensions/context-menus.md    |  72 ++
 .../references/extensions/csp-sandbox.md      | 177 +++++
 .../extensions/declarative-net-request.md     | 112 +++
 .../references/extensions/devtools.md         | 102 +++
 .../references/extensions/icons.md            | 101 +++
 .../references/extensions/media-capture.md    | 140 ++++
 .../references/extensions/message-passing.md  | 136 ++++
 .../references/extensions/omnibox.md          |  83 +++
 .../references/extensions/permissions.md      | 113 +++
 .../references/extensions/popup-ui.md         |  94 +++
 .../references/extensions/prompt-api.md       | 117 +++
 .../references/extensions/service-worker.md   | 148 ++++
 .../references/extensions/side-panel.md       | 147 ++++
 .../references/extensions/storage.md          |  65 ++
 .../references/extensions/tab-management.md   | 132 ++++
 .../references/extensions/user-scripts.md     | 273 +++++++
 .../webstore/chromewebstore-template.md       | 178 +++++
 .../references/webstore/privacy-policy.md     | 128 ++++
 .../references/webstore/review-checklist.md   | 145 ++++
 .../references/webstore/store-listing.md      | 201 +++++
 .../skills/modern-web-guidance/SKILL.md       | 136 ++++
 .../guides/accessibility/accessibility.md     | 585 +++++++++++++++
 .../accessible-error-announcement.md          | 208 ++++++
 .../accessible-generated-content.md           |  23 +
 .../accessibility/respect-os-text-scale.md    | 127 ++++
 .../guides/built-in-ai/language-detection.md  |  91 +++
 .../guides/built-in-ai/language-model.md      | 368 ++++++++++
 .../guides/built-in-ai/prompt-api.md          | 368 ++++++++++
 .../guides/built-in-ai/summarizer.md          | 156 ++++
 .../guides/built-in-ai/translator.md          | 189 +++++
 .../guides/css/animate-to-intrinsic-sizes.md  | 128 ++++
 .../guides/css/atrule-support-conditionals.md | 148 ++++
 .../css/calculate-with-intrinsic-sizes.md     | 199 +++++
 .../guides/css/child-state-based-styling.md   | 103 +++
 .../guides/css/content-based-styling.md       | 120 +++
 .../guides/css/css-layout.md                  | 317 ++++++++
 .../modern-web-guidance/guides/css/css.md     | 250 +++++++
 .../guides/css/design-token-reactivity.md     | 176 +++++
 .../guides/css/dynamic-sibling-styling.md     |  97 +++
 .../guides/css/fluid-scaling.md               |  80 ++
 .../css/individual-transform-properties.md    |  94 +++
 .../guides/css/overflow-clipping-control.md   | 181 +++++
 .../guides/css/reduce-style-repetition.md     |  87 +++
 .../guides/css/responsive-design.md           |  16 +
 .../css/selector-atrule-combinations.md       | 150 ++++
 .../guides/css/size-aware-styling.md          | 106 +++
 .../guides/css/style-parent-with-has.md       | 200 +++++
 .../css/usage-aware-component-variations.md   | 108 +++
 .../guides/forms/animated-select-picker.md    | 179 +++++
 .../guides/forms/autofill-address-form.md     |  82 +++
 .../guides/forms/autofill-highlight-inputs.md |  45 ++
 .../guides/forms/autofill-payment-form.md     | 138 ++++
 .../guides/forms/autofill-sign-in-form.md     | 141 ++++
 .../guides/forms/autofill-sign-up-form.md     | 151 ++++
 .../guides/forms/brand-consistent-forms.md    | 255 +++++++
 .../guides/forms/branded-select-styling.md    | 115 +++
 .../forms/custom-select-picker-layouts.md     | 166 +++++
 .../form-fields-automatically-fit-contents.md | 122 ++++
 .../modern-web-guidance/guides/forms/forms.md | 380 ++++++++++
 .../guides/forms/ime-safe-enter-submit.md     | 115 +++
 .../guides/forms/required-field-feedback.md   | 214 ++++++
 .../guides/forms/rich-media-picker.md         | 133 ++++
 .../guides/forms/select-menu-interaction.md   | 178 +++++
 .../guides/forms/slider.md                    | 182 +++++
 .../guides/forms/sms-otp-form.md              | 208 ++++++
 .../guides/forms/switch.md                    |  60 ++
 .../forms/validate-input-after-interaction.md | 258 +++++++
 .../guides/html/accessible-web-components.md  |  61 ++
 .../guides/html/custom-elements.md            | 122 ++++
 .../html/form-associated-custom-elements.md   |  73 ++
 .../modern-web-guidance/guides/html/html.md   | 409 +++++++++++
 .../html/prerendering-custom-elements.md      |  64 ++
 .../guides/html/shadow-dom.md                 |  79 ++
 .../guides/html/styling-web-components.md     | 130 ++++
 .../guides/html/web-components.md             |  50 ++
 .../js/calculate-event-differentials.md       | 117 +++
 .../js/capture-location-agnostic-data.md      | 149 ++++
 .../guides/js/coordinate-global-events.md     |  80 ++
 .../js/sort-high-precision-timestamps.md      |  92 +++
 .../js/support-global-calendar-systems.md     | 103 +++
 .../performance/batch-analytics-events.md     | 154 ++++
 .../guides/performance/break-up-long-tasks.md |  62 ++
 .../calculate-total-foreground-time.md        |  69 ++
 .../conditional-async-dependencies.md         |  74 ++
 .../defer-rendering-heavy-content.md          | 106 +++
 .../defer-work-until-scroll-ends.md           |  78 ++
 .../deliver-optimized-decorative-images.md    |  51 ++
 .../deprioritize-background-fetches.md        |  37 +
 .../detect-initial-visibility-state.md        | 101 +++
 .../efficient-background-processing.md        | 117 +++
 .../faster-spa-view-transitions.md            |  79 ++
 .../flicker-free-client-side-ab-testing.md    | 168 +++++
 .../performance/full-session-analytics.md     | 135 ++++
 .../performance/identify-heavy-scripts.md     |  69 ++
 .../guides/performance/identify-inp-causes.md | 105 +++
 .../improve-next-page-load-performance.md     | 121 +++
 .../performance/interaction-paint-timing.md   | 200 +++++
 .../interactions-in-complex-layouts.md        |  78 ++
 .../performance/lazy-load-video-and-audio.md  | 192 +++++
 .../performance/optimize-image-priority.md    |  73 ++
 .../performance/optimize-preload-priority.md  |  41 ++
 .../performance/optimize-script-priority.md   |  38 +
 .../out-of-order-html-streaming.md            | 144 ++++
 .../guides/performance/performance.md         | 384 ++++++++++
 .../resolution-optimized-pseudo-elements.md   |  49 ++
 .../performance/schedule-tasks-by-priority.md |  61 ++
 .../guides/privacy/privacy.md                 | 247 +++++++
 .../guides/pwa/migrate-web-app-origin.md      |  98 +++
 .../guides/security/client-side-encryption.md | 302 ++++++++
 .../guides/security/digital-signatures.md     | 235 ++++++
 .../guides/security/local-network-access.md   | 192 +++++
 .../guides/security/passkey-authentication.md | 205 ++++++
 .../security/passkey-conditional-create.md    | 134 ++++
 .../guides/security/passkey-management.md     | 235 ++++++
 .../security/passkey-reauthentication.md      | 128 ++++
 .../guides/security/passkey-registration.md   | 181 +++++
 .../guides/security/passkeys.md               |  39 +
 .../guides/security/quick-sign-ins.md         | 242 ++++++
 .../security/restrict-outbound-connections.md | 169 +++++
 .../security/sanitize-untrusted-html.md       | 105 +++
 .../security/secure-external-subresources.md  | 202 +++++
 .../guides/security/security.md               | 380 ++++++++++
 .../guides/security/trusted-types.md          | 140 ++++
 .../guides/security/validate-origins.md       | 197 +++++
 .../guides/security/verify-email-ownership.md | 235 ++++++
 .../guides/ui-atoms/carousel-slide-effects.md | 187 +++++
 .../component-specific-light-dark-theme.md    | 179 +++++
 .../guides/ui-atoms/icons.md                  | 290 ++++++++
 .../ui-atoms/position-aware-tooltips.md       | 158 ++++
 .../guides/ui-atoms/pull-to-reveal.md         |  83 +++
 .../guides/ui-atoms/responsive-table.md       | 121 +++
 .../scroll-position-aware-elements.md         | 130 ++++
 .../ui-atoms/scroll-progress-indicator.md     | 133 ++++
 .../scrollability-affordance-hints.md         | 126 ++++
 .../ui-atoms/shrinking-header-on-scroll.md    | 126 ++++
 .../ui-atoms/state-aware-sticky-headers.md    | 139 ++++
 .../ui-atoms/viewport-aware-dropdowns.md      | 134 ++++
 .../guides/ui-behaviors/2d-panning.md         | 151 ++++
 .../anchor-positioning-tab-underline.md       |  99 +++
 .../animate-element-entry-exit.md             | 192 +++++
 .../ui-behaviors/animate-to-from-top-layer.md | 240 ++++++
 .../ui-behaviors/carousel-snap-highlights.md  | 138 ++++
 .../consistent-cross-document-transitions.md  | 259 +++++++
 .../cross-document-transitions.md             | 129 ++++
 .../ui-behaviors/custom-button-actions.md     | 180 +++++
 .../declarative-dialog-popover-control.md     | 232 ++++++
 .../directional-navigation-transitions.md     | 128 ++++
 .../guides/ui-behaviors/drag.md               |  84 +++
 .../dynamic-sibling-animations.md             |  53 ++
 .../ui-behaviors/group-element-transitions.md | 126 ++++
 .../ui-behaviors/highlight-text-ranges.md     | 130 ++++
 .../interactive-content-reveal.md             | 120 +++
 .../interest-triggered-action-previews.md     |  93 +++
 .../interest-triggered-tooltips.md            | 179 +++++
 .../ui-behaviors/light-dismiss-a-dialog.md    |  86 +++
 .../guides/ui-behaviors/motion.md             | 102 +++
 .../move-dom-element-without-losing-state.md  |  59 ++
 .../ui-behaviors/parallax-scroll-effects.md   | 230 ++++++
 .../ui-behaviors/persistent-top-layer-ui.md   |  50 ++
 .../ui-behaviors/physics-based-easing.md      | 120 +++
 .../platform-controls-dismiss-dialog.md       |  40 +
 .../prevent-page-scroll-under-modal-dialog.md |  59 ++
 .../ui-behaviors/same-document-transitions.md | 177 +++++
 .../scoped-component-transitions.md           | 229 ++++++
 .../ui-behaviors/scroll-completion-effects.md |  97 +++
 .../ui-behaviors/scroll-entry-exit-effects.md | 173 +++++
 .../scroll-snap-realtime-feedback.md          | 156 ++++
 .../ui-behaviors/scroll-snap-state-sync.md    |  95 +++
 .../ui-behaviors/scroll-target-on-load.md     |  56 ++
 .../guides/ui-behaviors/scrollytelling.md     | 181 +++++
 .../ui-behaviors/search-hidden-content.md     | 141 ++++
 .../guides/ui-behaviors/spatial-navigation.md |  56 ++
 .../guides/ui-behaviors/swipe-to-remove.md    | 544 ++++++++++++++
 .../guides/ui-behaviors/swipe-to-reveal.md    | 164 +++++
 .../guides/ui-components/card.md              | 132 ++++
 .../guides/ui-components/checkbox.md          | 142 ++++
 .../guides/ui-components/dark-mode-toggle.md  | 138 ++++
 .../guides/ui-components/dialog.md            | 226 ++++++
 .../guides/ui-components/hovercard.md         | 279 +++++++
 .../guides/ui-components/menu.md              | 410 +++++++++++
 .../guides/ui-components/navigation-drawer.md | 365 ++++++++++
 .../ui-components/persistent-app-tours.md     | 137 ++++
 .../persistent-toast-notifications.md         |  64 ++
 .../guides/ui-components/progress-ring.md     | 181 +++++
 .../guides/ui-components/progress.md          | 181 +++++
 .../guides/ui-components/scrollspy.md         | 127 ++++
 .../guides/ui-components/spinner.md           | 169 +++++
 .../guides/ui-components/stack-drill-down.md  | 689 ++++++++++++++++++
 ...adapt-scrollbar-to-contrast-preferences.md |  74 ++
 .../visual-design/apply-webgl-shaders.md      | 278 +++++++
 .../visual-design/browser-ui-theming.md       |  39 +
 .../guides/visual-design/color.md             |  43 ++
 .../guides/visual-design/complex-shapes.md    |  75 ++
 .../guides/visual-design/contrast-color.md    | 187 +++++
 .../visual-design/custom-text-decorations.md  | 337 +++++++++
 ...customize-scrollbar-color-and-thickness.md |  59 ++
 .../guides/visual-design/dark-mode.md         | 339 +++++++++
 .../visual-design/equal-width-text-lines.md   |  97 +++
 .../export-html-media-from-canvas.md          | 327 +++++++++
 ...pose-canvas-content-to-browser-features.md | 433 +++++++++++
 .../improve-text-layout-and-legibility.md     |  77 ++
 .../interactive-content-in-3d-scenes.md       | 448 ++++++++++++
 .../visual-design/precise-text-alignment.md   |  99 +++
 .../guides/visual-design/shaped-cutouts.md    | 148 ++++
 .../visual-design/soft-edge-content-fade.md   |  64 ++
 .../guides/visual-design/typography.md        |  38 +
 .../guides/visual-design/visual-effects.md    | 100 +++
 .../visually-stable-font-fallbacks.md         |  51 ++
 .../visually-stable-mixed-fonts.md            |  63 ++
 .../visual-design/visually-texture-content.md |  78 ++
 .../guides/wasm/cpp-on-the-web.md             |  74 ++
 .../guides/webmcp/agentic-forms.md            | 127 ++++
 .../guides/webmcp/agentic-javascript-tools.md | 423 +++++++++++
 .../guides/webmcp/webmcp.md                   |  45 ++
 .../.claude-plugin/plugin.json                |  20 +
 .../.codex-plugin/plugin.json                 |  33 +
 .../.cursor-plugin/plugin.json                |  25 +
 plugins/modern-web-guidance/LICENSE           | 202 +++++
 plugins/modern-web-guidance/plugin.json       |  20 +
 plugins/modern-web-guidance/skills-lock.json  |  17 +
 release-please-config.json                    |  26 +
 230 files changed, 34308 insertions(+), 6 deletions(-)
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/SKILL.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/api-calling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/auth-identity.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/content-scripts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/context-menus.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/csp-sandbox.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/declarative-net-request.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/devtools.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/icons.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/media-capture.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/message-passing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/omnibox.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/permissions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/popup-ui.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/prompt-api.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/service-worker.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/side-panel.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/storage.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/tab-management.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/user-scripts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/chromewebstore-template.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/privacy-policy.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/review-checklist.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/store-listing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/SKILL.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessibility.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-error-announcement.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-generated-content.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/respect-os-text-scale.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-detection.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-model.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/prompt-api.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/summarizer.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/translator.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/atrule-support-conditionals.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/calculate-with-intrinsic-sizes.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/child-state-based-styling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/content-based-styling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css-layout.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/design-token-reactivity.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/dynamic-sibling-styling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/fluid-scaling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/individual-transform-properties.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/overflow-clipping-control.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/reduce-style-repetition.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/responsive-design.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/selector-atrule-combinations.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/size-aware-styling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/style-parent-with-has.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/usage-aware-component-variations.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/animated-select-picker.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-address-form.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-highlight-inputs.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-payment-form.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-in-form.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-up-form.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/brand-consistent-forms.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/branded-select-styling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/custom-select-picker-layouts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/form-fields-automatically-fit-contents.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/forms.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/ime-safe-enter-submit.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/required-field-feedback.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/rich-media-picker.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/select-menu-interaction.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/slider.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/sms-otp-form.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/switch.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/validate-input-after-interaction.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/accessible-web-components.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/custom-elements.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/form-associated-custom-elements.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/html.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/prerendering-custom-elements.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/shadow-dom.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/styling-web-components.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/web-components.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/calculate-event-differentials.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/capture-location-agnostic-data.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/coordinate-global-events.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/sort-high-precision-timestamps.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/support-global-calendar-systems.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/batch-analytics-events.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/break-up-long-tasks.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/calculate-total-foreground-time.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/conditional-async-dependencies.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-rendering-heavy-content.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-work-until-scroll-ends.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deliver-optimized-decorative-images.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deprioritize-background-fetches.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/detect-initial-visibility-state.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/efficient-background-processing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/faster-spa-view-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/flicker-free-client-side-ab-testing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/full-session-analytics.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-heavy-scripts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-inp-causes.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/improve-next-page-load-performance.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interaction-paint-timing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interactions-in-complex-layouts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/lazy-load-video-and-audio.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-image-priority.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-preload-priority.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-script-priority.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/out-of-order-html-streaming.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/performance.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/resolution-optimized-pseudo-elements.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/schedule-tasks-by-priority.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/privacy/privacy.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/pwa/migrate-web-app-origin.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/client-side-encryption.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/digital-signatures.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/local-network-access.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-authentication.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-conditional-create.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-management.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-reauthentication.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-registration.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkeys.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/quick-sign-ins.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/restrict-outbound-connections.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/sanitize-untrusted-html.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/secure-external-subresources.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/security.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/trusted-types.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/validate-origins.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/verify-email-ownership.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/carousel-slide-effects.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/component-specific-light-dark-theme.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/icons.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/position-aware-tooltips.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/pull-to-reveal.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/responsive-table.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-position-aware-elements.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-progress-indicator.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scrollability-affordance-hints.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/shrinking-header-on-scroll.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/state-aware-sticky-headers.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/viewport-aware-dropdowns.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/2d-panning.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/anchor-positioning-tab-underline.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-element-entry-exit.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-to-from-top-layer.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/carousel-snap-highlights.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/consistent-cross-document-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/cross-document-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/custom-button-actions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/declarative-dialog-popover-control.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/directional-navigation-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/drag.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/dynamic-sibling-animations.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/group-element-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/highlight-text-ranges.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interactive-content-reveal.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-action-previews.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-tooltips.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/light-dismiss-a-dialog.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/motion.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/move-dom-element-without-losing-state.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/parallax-scroll-effects.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/persistent-top-layer-ui.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/physics-based-easing.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/platform-controls-dismiss-dialog.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/prevent-page-scroll-under-modal-dialog.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/same-document-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scoped-component-transitions.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-completion-effects.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-entry-exit-effects.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-realtime-feedback.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-state-sync.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-target-on-load.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scrollytelling.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/search-hidden-content.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/spatial-navigation.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-remove.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-reveal.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/card.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/checkbox.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dark-mode-toggle.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dialog.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/hovercard.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/menu.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/navigation-drawer.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-app-tours.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-toast-notifications.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress-ring.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/scrollspy.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/spinner.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/stack-drill-down.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/adapt-scrollbar-to-contrast-preferences.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/apply-webgl-shaders.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/browser-ui-theming.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/color.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/complex-shapes.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/contrast-color.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/custom-text-decorations.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/customize-scrollbar-color-and-thickness.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/dark-mode.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/equal-width-text-lines.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/export-html-media-from-canvas.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/expose-canvas-content-to-browser-features.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/improve-text-layout-and-legibility.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/interactive-content-in-3d-scenes.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/precise-text-alignment.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/shaped-cutouts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/soft-edge-content-fade.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/typography.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visual-effects.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-font-fallbacks.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-mixed-fonts.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-texture-content.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/wasm/cpp-on-the-web.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-forms.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md
 create mode 100644 plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/webmcp.md
 create mode 100644 plugins/modern-web-guidance/.claude-plugin/plugin.json
 create mode 100644 plugins/modern-web-guidance/.codex-plugin/plugin.json
 create mode 100644 plugins/modern-web-guidance/.cursor-plugin/plugin.json
 create mode 100644 plugins/modern-web-guidance/LICENSE
 create mode 100644 plugins/modern-web-guidance/plugin.json
 create mode 100644 plugins/modern-web-guidance/skills-lock.json

diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json
index 79f7c3ec..e584b0b1 100644
--- a/.agents/plugins/marketplace.json
+++ b/.agents/plugins/marketplace.json
@@ -983,8 +983,8 @@
     {
       "name": "modern-web-guidance",
       "source": {
-        "source": "url",
-        "url": "https://github.com/GoogleChrome/modern-web-guidance.git"
+        "source": "local",
+        "path": "./plugins/modern-web-guidance"
       },
       "policy": {
         "installation": "AVAILABLE",
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4cc58d51..b7f1c670 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -1369,10 +1369,7 @@
       "category": "development",
       "keywords": ["web", "best-practices", "chrome", "baseline", "css", "performance"],
       "tags": ["skill", "web"],
-      "source": {
-        "source": "github",
-        "repo": "GoogleChrome/modern-web-guidance"
-      },
+      "source": "./plugins/modern-web-guidance",
       "homepage": "https://github.com/GoogleChrome/modern-web-guidance"
     },
     {
diff --git a/.cursor-plugin/marketplace.json b/.cursor-plugin/marketplace.json
index e4ef0ac8..a6a0239f 100644
--- a/.cursor-plugin/marketplace.json
+++ b/.cursor-plugin/marketplace.json
@@ -324,6 +324,11 @@
       "source": "./plugins/genkit",
       "description": "Official Genkit skills - build AI-powered applications with Genkit in JavaScript/TypeScript, Go, Dart/Flutter, and Python: flows, generation, prompts, tool calling, agents, and model providers"
     },
+    {
+      "name": "modern-web-guidance",
+      "source": "./plugins/modern-web-guidance",
+      "description": "Keep your coding agent up to date with the latest web best practices from the Google Chrome team"
+    },
     {
       "name": "java-development",
       "source": "./plugins/java-development",
diff --git a/.release-please-manifest.json b/.release-please-manifest.json
index ba8b9e65..d1e0441a 100644
--- a/.release-please-manifest.json
+++ b/.release-please-manifest.json
@@ -20,6 +20,7 @@
   "plugins/vue": "1.3.3",
   "plugins/vueuse": "1.3.2",
   "plugins/web-design": "1.4.3",
+  "plugins/modern-web-guidance": "0.0.196",
   "plugins/mastra": "1.7.4",
   "plugins/nuxt-ui": "1.6.5",
   "plugins/firebase": "1.1.3",
diff --git a/README.md b/README.md
index d23cf32c..ccd2cb4e 100644
--- a/README.md
+++ b/README.md
@@ -492,6 +492,12 @@ End-to-end typesafe APIs with oRPC v2 — the core `os` builder, routers, middle
 
 **Install:** `/plugin install orpc@pleaseai` | **Source:** [plugins/orpc](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/orpc)
 
+#### Modern Web Guidance
+
+Keep your coding agent up to date with the latest web best practices from the Google Chrome team — modern HTML/CSS/JS patterns (`modern-web-guidance`) and Manifest V3 Chrome extensions (`chrome-extensions`). Vendored from [GoogleChrome/modern-web-guidance](https://github.com/GoogleChrome/modern-web-guidance) (Apache-2.0) and refreshed weekly by `update-skills.yml`.
+
+**Install:** `/plugin install modern-web-guidance@pleaseai` | **Source:** [plugins/modern-web-guidance](https://github.com/pleaseai/claude-code-plugins/tree/main/plugins/modern-web-guidance)
+
 #### evlog
 
 Wide-event logging for TypeScript with [evlog](https://www.evlog.dev): review logging patterns and guide evlog adoption (`review-logging-patterns`), design tamper-aware audit trails (`build-audit-logs`), and debug from `.evlog/logs/` output (`analyze-logs`). Bundles the read-only evlog docs MCP server (`https://www.evlog.dev/mcp`) for current docs pages and log-cost estimates.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/SKILL.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/SKILL.md
new file mode 100644
index 00000000..91a915cd
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/SKILL.md
@@ -0,0 +1,530 @@
+---
+name: chrome-extensions
+description: >
+  Build and publish Chrome Extensions using Manifest V3 best practices. Use this skill
+  whenever the user asks to create, modify, debug, or understand Chrome browser extensions,
+  add-ons, or anything involving the Chrome Extensions API. Trigger on mentions of: 'Chrome
+  extension', 'browser extension', 'manifest.json', 'content script', 'service worker' (in
+  browser context), 'popup' (in browser extension context), 'side panel', 'chrome.* API',
+  'declarativeNetRequest', 'omnibox', 'context menu' (in extension context), 'userScripts',
+  'user script', 'script manager', or any request to build functionality that integrates with
+  the Chrome browser UI. Also trigger for publishing to the Chrome Web Store: 'publish
+  extension', preparing an extension for publishing, responding to a review rejection, writing
+  permission justifications, or drafting a privacy policy.
+---
+
+# Chrome Extensions
+
+Build production-quality Chrome extensions using Manifest V3 and publish them to the Chrome Web Store.
+
+## Part 1 — Building Extensions
+
+### Mandatory Rules
+
+These address the most common causes of broken extensions. Violating any produces a non-functional build.
+
+#### 1. Icons: only reference files you create — or omit icons entirely
+
+```
+❌ BROKEN — referencing files that don't exist or reusing one file for all sizes:
+   "icons": { "16": "icon.png", "48": "icon.png", "128": "icon.png" }
+
+✅ CORRECT — each size is a separate file at the correct pixel dimensions:
+   "icons": { "16": "icons/icon-16.png", "48": "icons/icon-48.png", "128": "icons/icon-128.png" }
+   (where icon-16.png is 16×16px, icon-48.png is 48×48px, icon-128.png is 128×128px)
+
+✅ ALSO CORRECT — omit icons from manifest if you cannot generate real PNG files:
+   (just remove the "icons" and "default_icon" fields — Chrome uses a default icon)
+```
+
+**If you include icon references, you MUST create the actual image files.** Generate them with a script (see `references/extensions/icons.md`) or leave them out. Never reference non-existent files.
+
+#### 2. Side panel: you MUST provide a way to open it
+
+Defining `"side_panel": {"default_path": "..."}` does NOT make it openable. Add a trigger:
+
+```js
+// In service-worker.js — open side panel on extension icon click
+// IMPORTANT: chrome.action.onClicked ONLY fires when there is NO default_popup
+chrome.action.onClicked.addListener(async (tab) => {
+  await chrome.sidePanel.open({ windowId: tab.windowId });
+});
+```
+
+If the extension has both a popup AND side panel, add a button in the popup that calls `chrome.sidePanel.open()`. Alternatively, use `chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true })` — but the property is `openPanelOnActionClick`, NOT `openPanelOnActionIconClick`; the "Icon" variant causes a synchronous TypeError that silently aborts the service worker. Do NOT also define `default_popup` when using `setPanelBehavior`. See `references/extensions/side-panel.md`.
+
+#### 3. Code execution: sandboxed iframes ONLY
+
+Extension CSP blocks `eval()`, `new Function()`, inline `<script>` in all extension pages.
+
+```js
+// ❌ BROKEN — direct iframe DOM access throws SecurityError
+iframe.contentDocument.write(html);
+
+// ❌ BROKEN — eval in extension page
+eval(userCode); // CSP blocks this
+
+// ✅ OPTION A: Sandbox in manifest + postMessage
+// manifest.json: { "sandbox": { "pages": ["sandbox.html"] } }
+iframe.contentWindow.postMessage({ html, css, js }, '*');
+// sandbox.html receives and runs:
+window.addEventListener('message', (e) => { eval(e.data.js); /* allowed in sandbox */ });
+
+// ✅ OPTION B: Blob URL (creates separate origin, bypasses extension CSP)
+iframe.src = URL.createObjectURL(new Blob([doc], { type: 'text/html' }));
+
+// ✅ OPTION C: srcdoc
+iframe.srcdoc = `<style>${css}</style>${html}<script>${js}<\/script>`;
+```
+
+See `references/extensions/csp-sandbox.md` for full details.
+
+#### 4. `tab.url` requires the `tabs` permission
+
+Without it, `tab.url` silently returns `undefined` — no error thrown. See
+`references/extensions/permissions.md`.
+
+#### 5. Always use async/await — never `.then()` chains
+
+```js
+// ❌ BAD
+chrome.tabs.query({active: true, currentWindow: true}).then(tabs => {
+  chrome.scripting.executeScript({target: {tabId: tabs[0].id}, files: ['content.js']}).then(() => {});
+});
+
+// ✅ GOOD
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+await chrome.scripting.executeScript({ target: { tabId: tab.id }, files: ['content.js'] });
+```
+
+For `runtime.onMessage` listeners that do async work:
+
+```js
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  (async () => {
+    const data = await chrome.storage.local.get('key');
+    sendResponse({ data });
+  })();
+  return true; // keeps channel open
+});
+```
+
+#### 6. Content scripts: don't block the main thread
+
+When modifying many DOM elements, batch with `requestAnimationFrame` and yield between batches:
+
+```js
+async function highlightAll(elements) {
+  const BATCH = 20;
+  for (let i = 0; i < elements.length; i += BATCH) {
+    await new Promise(r => requestAnimationFrame(() => {
+      elements.slice(i, i + BATCH).forEach(el => el.style.backgroundColor = 'yellow');
+      r();
+    }));
+    if (globalThis.scheduler?.yield) await scheduler.yield();
+  }
+}
+```
+
+See `references/extensions/content-scripts.md`.
+
+#### 7. Service workers are ephemeral — never store state in variables
+
+```js
+// ❌ BROKEN — state lost when SW terminates (~30s of inactivity)
+let count = 0;
+chrome.tabs.onUpdated.addListener(() => { count++; });
+
+// ✅ CORRECT — persist in chrome.storage, read on every event
+chrome.tabs.onUpdated.addListener(async (tabId, changeInfo) => {
+  if (changeInfo.status !== 'complete') return;
+  const { count = 0 } = await chrome.storage.local.get('count');
+  await chrome.storage.local.set({ count: count + 1 });
+  await chrome.action.setBadgeText({ text: String(count + 1) });
+});
+```
+
+Use `chrome.alarms` instead of `setTimeout`/`setInterval`. See `references/extensions/service-worker.md`.
+
+#### 8. chrome.identity: extension ID differs between dev and production
+
+When using Google sign-in, the OAuth client_id is tied to a specific extension ID. The ID changes between unpacked development and the Chrome Web Store.
+
+To stabilize the ID during development, add a `"key"` field to manifest.json:
+1. Pack the extension once (chrome://extensions → Pack)
+2. Extract the public key from the .crx
+3. Add `"key": "MIIBIjANBgkqh..."` to manifest.json
+
+Always document: "After publishing to the Chrome Web Store, update the OAuth client with the store-assigned extension ID." See `references/extensions/auth-identity.md`.
+
+#### 9. Context menus: show user feedback after action
+
+When a context menu item performs an action (save, copy, etc.), confirm it to the user. Use a notification, badge flash, or injected toast — don't let actions happen silently. See `references/extensions/context-menus.md` for a complete toast implementation.
+
+#### 10. Prompt API: available in service workers, popup, and side panel
+
+The `LanguageModel` API works in all extension contexts — service worker, popup, and side panel — with no additional manifest permissions required. Extensions also get `LanguageModel.params()`, which is unavailable on the web:
+
+```js
+const params = await LanguageModel.params();
+// { defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2 }
+```
+
+For general Prompt API patterns (availability checks, session creation, streaming), use the `modern-web-guidance` skill. See `references/extensions/prompt-api.md` for the extension-specific wiring example.
+
+#### 11. `chrome.action` API requires `action` in manifest
+
+Using `chrome.action.setBadgeText`, `chrome.action.setIcon`, or `chrome.action.onClicked` requires
+an `"action"` key in manifest.json — even if it's empty. Without it, `chrome.action` is `undefined`.
+
+```js
+// ❌ BROKEN — manifest has no "action" key
+await chrome.action.setBadgeText({ text: '5' });
+// TypeError: Cannot read properties of undefined (reading 'setBadgeText')
+
+// ✅ FIX — add "action" to manifest.json (at minimum an empty object)
+{ "action": {} }
+// or with a popup:
+{ "action": { "default_popup": "popup/popup.html" } }
+```
+
+#### 12. `activeTab` only works on direct user gestures — not from side panels
+
+`activeTab` grants temporary access to the current tab ONLY on a direct user gesture (action
+icon click, context menu item, keyboard shortcut, omnibox suggestion) — NOT from a button click
+inside a side panel or popup. Use `tabs` + `host_permissions` instead. See
+`references/extensions/permissions.md` and `references/extensions/side-panel.md`.
+
+#### 13. DevTools panel URLs are relative to the extension root
+
+When creating a DevTools panel, the panel HTML path is relative to the **extension root**, NOT
+relative to the devtools page that calls `chrome.devtools.panels.create()`.
+
+```js
+// ❌ BROKEN — path relative to devtools/ directory
+chrome.devtools.panels.create("My Panel", "", "panel/panel.html");
+
+// ✅ CORRECT — full path from extension root
+chrome.devtools.panels.create("My Panel", "", "devtools/panel/panel.html");
+```
+
+See `references/extensions/devtools.md`.
+
+#### 14. Offscreen documents have NO access to most chrome.* APIs
+
+Offscreen documents (`chrome.offscreen`) are **severely restricted**. Most `chrome.*` APIs
+are unavailable, including `chrome.downloads`, `chrome.tabs`, `chrome.action`, and others.
+
+```js
+// ❌ BROKEN — chrome.downloads is undefined in offscreen documents
+chrome.downloads.download({ url, filename: 'recording.webm' }); // TypeError
+
+// ❌ BROKEN — chrome.action is undefined in offscreen documents
+chrome.action.setBadgeText({ text: 'REC' }); // TypeError
+```
+
+**The only APIs available in offscreen documents are:**
+- `chrome.runtime.sendMessage` / `chrome.runtime.onMessage`
+- `chrome.runtime.getURL`
+- Standard Web APIs (DOM, fetch, MediaRecorder, Canvas, Web Audio, etc.)
+
+**Rule of thumb:** Offscreen documents do the Web API work (recording, parsing, audio). The service worker does all chrome.* API work (downloads, badge updates, notifications). Use `chrome.runtime.sendMessage` to bridge between them. See `references/extensions/message-passing.md`.
+
+#### 15. Notifications and badge icons must reference real image files
+
+`chrome.notifications.create()` requires a valid `iconUrl` pointing to an actual image file.
+If the file doesn't exist or the path is wrong, the call fails with `"Unable to download all specified images."`
+
+```js
+// ❌ BROKEN — icon file doesn't exist
+chrome.notifications.create('reminder', {
+  type: 'basic',
+  iconUrl: 'icons/icon-128.png', // File not in extension!
+  title: 'Reminder',
+  message: 'Time is up!'
+});
+
+// ✅ Generate a data URL at runtime via OffscreenCanvas — no file needed.
+// See `references/extensions/icons.md` for a reusable implementation.
+const iconUrl = await getIconDataUrl();
+chrome.notifications.create('reminder', { type: 'basic', iconUrl, title: 'Reminder', message: 'Time is up!' });
+```
+
+This applies to ALL image references in chrome.* APIs — notifications, `chrome.action.setIcon`,
+context menu icons, etc. **If you reference a file, it must exist.**
+
+#### 16. Tab capture: guard against double-start with state locking
+
+`chrome.tabCapture.getMediaStreamId()` fails with `"Cannot capture a tab with an active stream"`
+if called while a previous capture is still active. Fast double-clicks on the extension icon
+easily trigger this. Use explicit state locking:
+
+```js
+// ❌ BROKEN — no guard against rapid clicks
+let isRecording = false;
+chrome.action.onClicked.addListener(async (tab) => {
+  if (isRecording) { stopRecording(); isRecording = false; }
+  else { isRecording = true; startRecording(tab); } // Second click = "active stream" error
+});
+
+// ✅ CORRECT — use transitional states to lock out concurrent operations
+// State machine: 'idle' → 'starting' → 'recording' → 'stopping' → 'idle'
+// Store state in chrome.storage.session (survives SW restart, cleared on browser close)
+chrome.action.onClicked.addListener(async (tab) => {
+  const { recordingState = 'idle' } = await chrome.storage.session.get('recordingState');
+
+  if (recordingState === 'starting' || recordingState === 'stopping') return;
+
+  if (recordingState === 'idle') {
+    await chrome.storage.session.set({ recordingState: 'starting' });
+    try {
+      await startRecording(tab);
+      await chrome.storage.session.set({ recordingState: 'recording' });
+      await chrome.action.setBadgeText({ text: 'REC' });
+      await chrome.action.setBadgeBackgroundColor({ color: '#FF0000' });
+    } catch (err) {
+      console.error('Failed to start recording:', err);
+      await chrome.storage.session.set({ recordingState: 'idle' });
+    }
+  } else if (recordingState === 'recording') {
+    await chrome.storage.session.set({ recordingState: 'stopping' });
+    try { await stopRecording(); }
+    finally {
+      await chrome.storage.session.set({ recordingState: 'idle' });
+      await chrome.action.setBadgeText({ text: '' });
+    }
+  }
+});
+```
+
+This pattern applies to any chrome API that manages exclusive resources:
+`chrome.tabCapture`, `chrome.desktopCapture`, `chrome.offscreen.createDocument` (only one
+offscreen document allowed at a time). See `references/extensions/media-capture.md`.
+
+#### 17. `chrome.desktopCapture` requires a target tab with URL access
+
+When calling `chrome.desktopCapture.chooseDesktopMedia()` from a service worker, you must pass
+the active tab as the `targetTab` parameter. The tab object must have its `url` field populated,
+which requires the `"tabs"` permission.
+
+```js
+// ❌ BROKEN — called without targetTab from service worker
+chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], (streamId) => { ... });
+// Error: "A target tab is required when called from a service worker context."
+
+// ❌ BROKEN — tab doesn't have url field (missing "tabs" permission)
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], tab, (streamId) => { ... });
+// Error: "targetTab doesn't have URL field set."
+
+// ✅ CORRECT — "tabs" permission in manifest + pass tab object
+// manifest.json: { "permissions": ["tabs", "desktopCapture"] }
+const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], tab, (streamId) => {
+  if (!streamId) return; // User cancelled
+});
+```
+
+**Note:** Prefer `chrome.tabCapture.getMediaStreamId()` for tab-only recording. Use `chrome.desktopCapture` only when the user should choose which screen/window to capture. See `references/extensions/media-capture.md`.
+
+#### 18. User scripts: four non-obvious pitfalls
+
+`chrome.userScripts` runs **user-provided code** at runtime. Use it for script managers and
+user automation — not for extension-bundled scripts.
+
+- **API throws on property access if not enabled.** Chrome 138+ requires the user to toggle "Allow User Scripts" on the extension's details page; Chrome < 138 requires Developer mode. Always call `isUserScriptsAvailable()` before any `chrome.userScripts.*` call and show an error UI when it returns false.
+- **Registered scripts are cleared on extension update.** Persist configs in `chrome.storage`; re-register them in `runtime.onInstalled` for the `"update"` reason.
+- **Messaging requires explicit opt-in.** Call `configureWorld({ messaging: true })` first; listen on `runtime.onUserScriptMessage`, not `runtime.onMessage`.
+- **`ScriptSource` constraint:** each `js` entry must have exactly one of `code` or `file`. **`id` constraint:** cannot start with `_`.
+
+See `references/extensions/user-scripts.md`.
+
+#### 19. `chrome.windows` has NO `.query()` method — use `getAll`, `getLastFocused`, or `getCurrent`
+
+Unlike `chrome.tabs.query()`, the `chrome.windows` API does NOT have a `.query()` method.
+
+```js
+// ❌ BROKEN — chrome.windows.query does not exist
+const windows = await chrome.windows.query({ focused: true });
+// TypeError: chrome.windows.query is not a function
+
+// ✅ CORRECT — use the right method for your need
+const focused = await chrome.windows.getLastFocused({ populate: true });
+const current = await chrome.windows.getCurrent({ populate: true });
+const all     = await chrome.windows.getAll({ populate: true });
+```
+
+**`chrome.windows` methods:** `getAll`, `getLastFocused`, `getCurrent`, `get(windowId)`, `create`, `update`, `remove`. See `references/extensions/tab-management.md`.
+
+#### 20. `chrome.permissions.request()` in the service worker must be called with no `await` before it in the message listener
+
+A user gesture from a UI context (side panel, popup) does propagate across `chrome.runtime.sendMessage`
+to the service worker's `onMessage` listener — but only for that one synchronous turn. If the
+listener does an `await` (even a short delay) before calling `chrome.permissions.request()`, the
+gesture is gone and the call throws `"This function must be called during a user gesture"`. Call
+it as the first thing in the listener, with nothing awaited before it — see
+`references/extensions/permissions.md`.
+
+### Always Manifest V3
+
+Never generate Manifest V2 code.
+- `background.service_worker` not `background.scripts`
+- `chrome.action` not `chrome.browserAction`
+- `chrome.scripting.executeScript` not `chrome.tabs.executeScript`
+- `host_permissions` is separate from `permissions`
+- No inline scripts in HTML — use `<script src="file.js">`
+- No inline event handlers — use `addEventListener`
+
+---
+
+## Part 2 — Publishing to the Chrome Web Store
+
+Manage `CHROMEWEBSTORE.md` — the single source of truth for all Chrome Web Store listing
+metadata, permissions justifications, privacy disclosures, version history, and publishing
+readiness for a Chrome extension project.
+
+### Core Workflow
+
+Every time you touch a Chrome extension project in a way that affects its store presence,
+update (or create) `CHROMEWEBSTORE.md` in the project root. The file tracks everything the
+developer needs to fill out in the Chrome Developer Dashboard, so they can copy-paste from
+a single doc instead of scrambling at publish time.
+
+#### When to create CHROMEWEBSTORE.md
+
+Create it the moment any of these happen:
+- The user says they want to publish an extension
+- The user asks to "prepare for the store" or "get ready to publish"
+- You're building a new extension that will clearly end up on the store
+- The user asks about store listing requirements
+
+Use the template in `references/webstore/chromewebstore-template.md` as your starting point. Read it
+before generating the file.
+
+#### When to update CHROMEWEBSTORE.md
+
+Update it whenever:
+- **User-facing changes**: Bump the "Last Updated" date, update the feature list in
+  descriptions, and add an entry to Version History
+- **manifest.json changes**: If permissions, host_permissions, or content_scripts changed,
+  update the Permissions Justification section — every permission needs a plain-English
+  reason the review team can understand
+- **New release**: Add a Version History entry with version number, date, and summary
+- **Privacy-relevant changes**: If data collection, storage, or transmission changed,
+  update the Privacy & Data Use section and the privacy policy
+- **Asset changes**: If icons or UI changed, note which screenshots need refreshing
+- **Rejection response**: If the user reports a CWS rejection, update the file with the
+  fix and add a note to Version History
+
+### How to fill it out
+
+For each section, pull information from the actual project files:
+1. Read `manifest.json` to extract name, version, description, permissions, host_permissions
+2. Scan the codebase for data collection (storage, fetch calls, analytics)
+3. Check for icon files and their dimensions
+4. Look at the extension's UI to understand features for the description
+
+Write store-facing copy in a tone that is specific, honest, and benefit-oriented. The Chrome
+Web Store review team rejects vague descriptions. "Makes your life easier" will be rejected.
+"Highlights search results on any webpage and lets you save highlights to a local list" will
+pass.
+
+**Never mention implementation details.** Users care what the extension does for them, not
+how it was built. Strip any mention of APIs, libraries, frameworks, or code patterns:
+
+| ❌ Implementation detail (cut it) | ✅ User benefit (keep it) |
+|-----------------------------------|--------------------------|
+| "Uses a MutationObserver to detect page changes" | "Automatically detects new content as you browse" |
+| "Built with custom elements and Shadow DOM" | "Works seamlessly without affecting page styles" |
+| "Powered by a service worker for background processing" | "Runs quietly in the background without slowing your browser" |
+| "Leverages the chrome.storage.sync API" | "Your settings sync across all your devices" |
+| "Implements declarativeNetRequest for filtering" | "Blocks ads and trackers without reading your page content" |
+
+### CHROMEWEBSTORE.md Sections
+
+Read `references/webstore/chromewebstore-template.md` before generating the file — it defines
+what each section covers and how to fill it out. The highest-risk section is Permissions
+Justification: write a specific plain-English reason per permission and per host_permission.
+"Needed for the extension to work" will be rejected. Read `references/webstore/privacy-policy.md`
+for guidance on generating a privacy policy.
+
+### Pre-Publish Checklist
+
+Before submission, run through `references/webstore/review-checklist.md`. The most common
+first-submission failures:
+- Every permission and host_permission must have a specific justification (not "needed to work")
+- Privacy policy URL must be live and match the data use disclosure form
+- At least 1 screenshot at 1280×800 or 640×400
+- ZIP must exclude `.git/`, `node_modules/`, `.env`, `CHROMEWEBSTORE.md`
+
+### Store Listing Copy Guidelines
+
+For copy guidelines and common rejection reasons, see `references/webstore/store-listing.md`.
+Key rule: lead with function ("Highlights search terms on any webpage"), not feeling ("Enjoy
+searching again").
+
+---
+
+## Reference Files
+
+For detailed API patterns and publishing guidance, read the relevant file BEFORE writing code or content:
+
+| Topic | Reference |
+|-------|-----------|
+| Permissions | `references/extensions/permissions.md` |
+| Side panels | `references/extensions/side-panel.md` |
+| Content scripts & DOM | `references/extensions/content-scripts.md` |
+| Popups | `references/extensions/popup-ui.md` |
+| Service worker lifetime | `references/extensions/service-worker.md` |
+| Code execution & CSP | `references/extensions/csp-sandbox.md` |
+| API calls | `references/extensions/api-calling.md` |
+| Declarative Net Request | `references/extensions/declarative-net-request.md` |
+| Chrome Prompt API | `references/extensions/prompt-api.md` |
+| DevTools panels | `references/extensions/devtools.md` |
+| Authentication | `references/extensions/auth-identity.md` |
+| Context menus | `references/extensions/context-menus.md` |
+| Omnibox | `references/extensions/omnibox.md` |
+| Storage | `references/extensions/storage.md` |
+| Tab & window management | `references/extensions/tab-management.md` |
+| Tab/desktop capture | `references/extensions/media-capture.md` |
+| User scripts | `references/extensions/user-scripts.md` |
+| Message passing | `references/extensions/message-passing.md` |
+| Icons | `references/extensions/icons.md` |
+| CHROMEWEBSTORE.md template | `references/webstore/chromewebstore-template.md` |
+| Privacy policy guidance | `references/webstore/privacy-policy.md` |
+| Pre-publish review checklist | `references/webstore/review-checklist.md` |
+| Store listing tips & rejections | `references/webstore/store-listing.md` |
+
+## Output Checklist
+
+Verify EVERY item before delivering:
+
+- [ ] `manifest_version: 3` — no V2 APIs anywhere
+- [ ] All icon files referenced in manifest exist as real files with correct dimensions — or icons are omitted
+- [ ] Side panel has an explicit open trigger (not just a manifest declaration)
+- [ ] Code execution uses sandbox/blob/srcdoc — no `eval()` in extension pages
+- [ ] `tabs` permission declared if `tab.url` or `tab.title` is accessed
+- [ ] All code uses `async`/`await` — no `.then()` chains
+- [ ] Content scripts batch DOM updates with `requestAnimationFrame`
+- [ ] Service worker stores NO state in global variables — uses `chrome.storage`
+- [ ] No inline scripts or event handlers in HTML
+- [ ] Context menu actions show user confirmation
+- [ ] `"action": {}` (or more) present in manifest if using `chrome.action.*` APIs
+- [ ] If reading/scripting tabs from a side panel: use `tabs` + `host_permissions` (NOT `activeTab`)
+- [ ] DevTools panel paths in `chrome.devtools.panels.create()` are relative to extension root
+- [ ] Offscreen documents use ONLY `chrome.runtime` messaging — no `chrome.downloads`, `chrome.action`, etc.
+- [ ] All image refs in `chrome.notifications`, `chrome.action.setIcon`, etc. point to real files (or use data URLs)
+- [ ] Tab/desktop capture uses state locking to prevent double-start errors
+- [ ] `chrome.desktopCapture.chooseDesktopMedia` passes `targetTab` with `tabs` permission
+- [ ] `chrome.windows` calls use `getAll`/`getLastFocused`/`getCurrent` — NOT `.query()` (it doesn't exist)
+- [ ] `chrome.permissions.request()` in a service worker `onMessage` listener is called with no `await` before it (gesture is lost after the first async gap)
+- [ ] `chrome.userScripts` availability checked before use (API throws if user hasn't enabled it)
+- [ ] User script configs persisted in `chrome.storage` and restored on `runtime.onInstalled` `"update"` reason
+- [ ] `configureWorld({ messaging: true })` called before user scripts send messages; listening on `onUserScriptMessage` not `onMessage`
+- [ ] `ScriptSource` entries each have exactly one of `code` or `file` (not both, not neither)
+- [ ] User script `id` values do not start with underscore
+- [ ] `sidePanel.setPanelBehavior` uses `openPanelOnActionClick` — NOT `openPanelOnActionIconClick`
+- [ ] Error handling on all async operations
+- [ ] `host_permissions` scoped to specific domains (not `<all_urls>` unless needed)
+- [ ] `return true` in `onMessage` listeners with async responses
+- [ ] Any use of `"tab"` in `chrome.contextMenus` `contexts` requires Chrome M150+
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/api-calling.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/api-calling.md
new file mode 100644
index 00000000..d1cfba5b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/api-calling.md
@@ -0,0 +1,72 @@
+# Calling External APIs from Extensions
+
+## Permissions
+
+Ordinarily, fetch requests made by extensions follow normal CORS rules.
+
+To determine if this is sufficient, use `curl` to call the API with a test origin. For example:
+
+```
+curl -H "Origin: https://example.com" -I https://api.openweathermap.org/data/2.5/weather?q=London&appid=KEY`
+```
+
+If the response includes either `*` or `https://example.com` as the value for the `Access-Control-Allow-Origin` header, the API supports CORS.
+
+If the API does not support CORS, request host permissions to bypass these restrictions:
+
+```json
+{
+  "host_permissions": [
+    "https://no-cors-api.example.com/*"
+  ]
+}
+```
+
+**Do NOT use `<all_urls>` just for API calls.** Scope to the specific API domains.
+
+## Where to Make API Calls
+
+API calls work from any extension context (service worker, popup, side panel, content scripts):
+
+```js
+// From popup or service worker
+const response = await fetch('https://api.openweathermap.org/data/2.5/weather?q=London&appid=KEY');
+const data = await response.json();
+```
+
+**Content scripts** can also make fetch calls, but they follow the web page's CORS rules.
+
+## Error Handling Pattern
+
+```js
+async function callAPI(url) {
+  try {
+    const response = await fetch(url);
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}: ${response.statusText}`);
+    }
+    return await response.json();
+  } catch (err) {
+    if (err instanceof TypeError) {
+      // Network error (offline, DNS failure, etc.)
+      console.error('Network error:', err.message);
+    } else {
+      console.error('API error:', err.message);
+    }
+    return null;
+  }
+}
+```
+
+## API Keys
+
+- Never hardcode API keys in published extensions
+- Use `chrome.storage.local` for user-provided keys
+- For your own backend, use `chrome.identity` to authenticate instead of embedding keys
+- Mark placeholder keys clearly: `const API_KEY = 'YOUR_API_KEY_HERE';`
+
+## Service Worker Considerations
+
+If making API calls from the service worker, remember it can terminate. For long-polling or
+webhook-style patterns, use `chrome.offscreen` to create an offscreen document that stays alive,
+or use `chrome.alarms` for periodic polling.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/auth-identity.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/auth-identity.md
new file mode 100644
index 00000000..bc819714
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/auth-identity.md
@@ -0,0 +1,141 @@
+# Authentication with chrome.identity
+
+## Setup
+
+```json
+{
+  "permissions": ["identity"],
+  "oauth2": {
+    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
+    "scopes": [
+      "https://www.googleapis.com/auth/userinfo.profile",
+      "https://www.googleapis.com/auth/userinfo.email"
+    ]
+  }
+}
+```
+
+## Getting an OAuth Token
+
+```js
+async function signIn() {
+  return new Promise((resolve, reject) => {
+    chrome.identity.getAuthToken({ interactive: true }, (token) => {
+      if (chrome.runtime.lastError) {
+        reject(new Error(chrome.runtime.lastError.message));
+      } else {
+        resolve(token);
+      }
+    });
+  });
+}
+```
+
+Or with the promise-based API (Chrome 116+):
+```js
+const { token } = await chrome.identity.getAuthToken({ interactive: true });
+```
+
+## Fetching User Profile
+
+```js
+async function getUserProfile(token) {
+  const response = await fetch('https://www.googleapis.com/oauth2/v3/userinfo', {
+    headers: { Authorization: `Bearer ${token}` }
+  });
+  if (!response.ok) throw new Error('Failed to fetch profile');
+  return response.json();
+  // Returns: { sub, name, given_name, family_name, picture, email, email_verified }
+}
+```
+
+## Sign Out
+
+```js
+async function signOut(token) {
+  // Remove cached token
+  await chrome.identity.removeCachedAuthToken({ token });
+
+  // Optionally revoke the token server-side
+  await fetch(`https://accounts.google.com/o/oauth2/revoke?token=${token}`);
+}
+```
+
+## Error Handling
+
+```js
+try {
+  const { token } = await chrome.identity.getAuthToken({ interactive: true });
+  const profile = await getUserProfile(token);
+  displayProfile(profile);
+} catch (err) {
+  if (err.message.includes('canceled')) {
+    showMessage('Sign-in was cancelled');
+  } else if (err.message.includes('not granted')) {
+    showMessage('Permission was denied');
+  } else {
+    showMessage('Sign-in failed: ' + err.message);
+  }
+}
+```
+
+## Setting Up Google Cloud Console
+
+1. Go to console.cloud.google.com
+2. Create a project (or select existing)
+3. Enable "Google People API" or "Google OAuth2 API"
+4. Create OAuth 2.0 credentials → Chrome Extension type
+5. Set the Application ID to your extension's ID
+6. Copy the client_id to your manifest.json
+
+### Extension ID: Development vs Production
+
+**This is critical and often missed.** The OAuth `client_id` is tied to a specific extension ID.
+The extension ID changes depending on how you load the extension:
+
+| Context | How ID is determined |
+|---------|---------------------|
+| Unpacked (development) | Derived from the extension's directory path — changes if you move the folder |
+| Packed (.crx) | Derived from the private key used to pack |
+| Chrome Web Store | Assigned by the store, permanent |
+
+**To get a stable ID during development**, add a `"key"` field to your manifest.json.
+This ensures the same extension ID regardless of directory path:
+
+1. Pack your extension once (`chrome://extensions` → Pack Extension)
+2. Open the generated `.crx` as a ZIP, extract the `key` from its manifest
+3. Add that key to your development manifest:
+
+```json
+{
+  "key": "MIIBIjANBgkqhk...your-public-key-here...",
+  "manifest_version": 3,
+  "name": "My Extension"
+}
+```
+
+Alternatively, note your unpacked extension's ID from `chrome://extensions` and configure
+the OAuth client for that specific ID. Just be aware it will change if the folder moves.
+
+**Always tell users:** "After publishing to the Chrome Web Store, update your OAuth client
+configuration with the store-assigned extension ID."
+
+## Non-Google OAuth (launchWebAuthFlow)
+
+For third-party OAuth providers (GitHub, Twitter, etc.):
+
+```js
+const redirectUrl = chrome.identity.getRedirectURL();
+// Returns: https://<extension-id>.chromiumapp.org/
+
+const authUrl = `https://github.com/login/oauth/authorize?client_id=XXX&redirect_uri=${redirectUrl}`;
+
+const responseUrl = await chrome.identity.launchWebAuthFlow({
+  url: authUrl,
+  interactive: true
+});
+
+// Parse the token from responseUrl
+const url = new URL(responseUrl);
+const code = url.searchParams.get('code');
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/content-scripts.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/content-scripts.md
new file mode 100644
index 00000000..d87c58d4
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/content-scripts.md
@@ -0,0 +1,112 @@
+# Content Scripts & DOM Manipulation
+
+## Two Ways to Inject
+
+### 1. Static (manifest declaration)
+```json
+{
+  "content_scripts": [{
+    "matches": ["<all_urls>"],
+    "js": ["content/content.js"],
+    "css": ["content/content.css"],
+    "run_at": "document_idle"
+  }]
+}
+```
+
+### 2. Programmatic (from service worker or popup)
+```js
+// Requires "scripting" permission and host access
+chrome.scripting.executeScript({
+  target: { tabId: tabId },
+  files: ['content/content.js']
+});
+
+// Or inject a function directly
+chrome.scripting.executeScript({
+  target: { tabId: tabId },
+  func: (param) => {
+    document.body.style.backgroundColor = param;
+  },
+  args: ['yellow']
+});
+```
+
+Use `activeTab` permission for on-click injection (no host_permissions needed):
+```json
+{
+  "permissions": ["activeTab", "scripting"]
+}
+```
+
+## Isolated World
+
+Content scripts run in an isolated world:
+- They share the DOM with the page but NOT JavaScript variables
+- They can access chrome.runtime messaging APIs
+- The page's CSP does NOT restrict content script code
+- `window` refers to the content script's isolated world
+
+## Message Passing from Content Scripts
+
+```js
+// content.js → service worker
+chrome.runtime.sendMessage({ type: 'DATA', payload: data }, (response) => {
+  console.log('Got response:', response);
+});
+
+// service worker → content script in a specific tab
+chrome.tabs.sendMessage(tabId, { type: 'UPDATE', data: newData });
+
+// content.js: listen for messages
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === 'GET_CONTENT') {
+    const text = document.body.innerText;
+    sendResponse({ text });
+  }
+  return true; // Keep channel open for async sendResponse
+});
+```
+
+## DOM Manipulation Best Practices
+
+- **Avoid blocking the main thread** when modifying many DOM elements. Use `requestAnimationFrame`
+  to batch visual updates and `scheduler.yield()` to break up long-running tasks:
+
+```js
+// ❌ BAD: Blocks the main thread while processing hundreds of elements
+const emails = document.body.innerText.match(/[\w.+-]+@[\w-]+\.[\w.]+/g);
+emails.forEach(email => {
+  // ... find and highlight each email (can freeze the page)
+});
+
+// ✅ GOOD: Process in batches using requestAnimationFrame
+async function highlightEmails(elements) {
+  const BATCH_SIZE = 20;
+  for (let i = 0; i < elements.length; i += BATCH_SIZE) {
+    const batch = elements.slice(i, i + BATCH_SIZE);
+    await new Promise(resolve => requestAnimationFrame(() => {
+      batch.forEach(el => el.style.backgroundColor = 'yellow');
+      resolve();
+    }));
+    // Yield to the main thread between batches
+    if (typeof scheduler !== 'undefined' && scheduler.yield) {
+      await scheduler.yield();
+    }
+  }
+}
+```
+
+- Use `MutationObserver` for dynamic pages (SPAs, infinite scroll)
+- Namespace your CSS classes to avoid conflicts (e.g., `myext-highlight`)
+- Use Shadow DOM for complex UI injected into pages
+- Clean up on removal: `chrome.runtime.onMessage` listeners persist until the content script context is destroyed
+- Use `TreeWalker` or `document.createNodeIterator` instead of regex on `innerHTML` for finding text in the DOM — this is more reliable and doesn't break event listeners
+
+## `run_at` Timing
+
+| Value | When |
+|-------|------|
+| `document_start` | Before DOM is constructed (useful for blocking) |
+| `document_idle` | After DOM is ready but before all resources load (default, recommended) |
+| `document_end` | After DOM is complete but before images/subframes |
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/context-menus.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/context-menus.md
new file mode 100644
index 00000000..d04b3e7d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/context-menus.md
@@ -0,0 +1,72 @@
+# Context Menus
+
+## Setup
+
+```json
+{ "permissions": ["contextMenus"] }
+```
+
+## Creating Menus
+
+Create in the service worker, typically in `onInstalled` (menus persist, but re-creating is idempotent):
+
+```js
+chrome.runtime.onInstalled.addListener(() => {
+  chrome.contextMenus.create({
+    id: 'save-link',
+    title: 'Save to Reading List',
+    contexts: ['link']        // Only show on right-click of links
+  });
+
+  chrome.contextMenus.create({
+    id: 'translate-selection',
+    title: 'Translate "%s"',   // %s = selected text
+    contexts: ['selection']
+  });
+
+  // M150+: Context menu for the tab strip (right-clicking a tab)
+  chrome.contextMenus.create({
+    id: 'duplicate-tab',
+    title: 'Custom Duplicate Tab',
+    contexts: ['tab']
+  });
+});
+```
+
+## Handling Clicks
+
+```js
+chrome.contextMenus.onClicked.addListener((info, tab) => {
+  switch (info.menuItemId) {
+    case 'save-link':
+      saveLink(info.linkUrl, info.selectionText || info.linkUrl);
+      break;
+    case 'translate-selection':
+      translateText(info.selectionText, tab.id);
+      break;
+    case 'duplicate-tab':
+      chrome.tabs.duplicate(tab.id); // 'tab' parameter is the clicked tab
+      break;
+  }
+});
+```
+
+## Context Types
+
+`all`, `page`, `frame`, `selection`, `link`, `editable`, `image`, `video`, `audio`, `launcher`, `browser_action`, `action`, `tab` (M150+)
+
+## Submenus
+
+```js
+chrome.contextMenus.create({ id: 'parent', title: 'My Extension', contexts: ['page'] });
+chrome.contextMenus.create({ id: 'child1', parentId: 'parent', title: 'Option 1', contexts: ['page'] });
+chrome.contextMenus.create({ id: 'child2', parentId: 'parent', title: 'Option 2', contexts: ['page'] });
+```
+
+## Dynamic Updates
+
+```js
+chrome.contextMenus.update('save-link', { title: 'New Title' });
+chrome.contextMenus.remove('save-link');
+chrome.contextMenus.removeAll();
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/csp-sandbox.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/csp-sandbox.md
new file mode 100644
index 00000000..3a19438c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/csp-sandbox.md
@@ -0,0 +1,177 @@
+# CSP & Sandboxed Code Execution
+
+## Extension CSP Restrictions
+
+Chrome Extensions enforce a strict Content Security Policy that cannot be relaxed for extension
+pages (popup, side panel, options, new tab, etc.).
+
+Blocked by default:
+- `eval()`, `new Function()`, `setTimeout("string")`
+- Inline `<script>` tags
+- Inline event handlers (`onclick="..."`, `onload="..."`, etc.)
+- `javascript:` URLs
+
+## HTML Best Practices
+
+```html
+<!-- ❌ BAD: Inline script -->
+<script>
+  document.getElementById('btn').onclick = () => alert('hi');
+</script>
+
+<!-- ❌ BAD: Inline event handler -->
+<button onclick="doThing()">Click</button>
+
+<!-- ✅ GOOD: External script file -->
+<script src="popup.js"></script>
+```
+
+In `popup.js`:
+```js
+document.getElementById('btn').addEventListener('click', () => {
+  // Handle click
+});
+```
+
+## Executing User Code (Code Playground Pattern)
+
+If you need to execute arbitrary code (e.g., a CodePen-like playground), you MUST use one of these
+approaches. **Extension CSP completely blocks `eval()`, `new Function()`, and inline scripts in
+normal extension pages.** There is no way around this — you need sandboxing.
+
+### Option 1: Sandboxed Page in Manifest (Recommended)
+
+Declare a sandboxed page in manifest.json. Sandboxed pages have a relaxed CSP that allows
+`eval()` and inline scripts, but they cannot access chrome.* APIs.
+
+```json
+{
+  "sandbox": {
+    "pages": ["sandbox.html"]
+  }
+}
+```
+
+Use an iframe in your extension page to embed the sandbox:
+
+```html
+<!-- playground.html (extension page) -->
+<iframe id="preview" src="sandbox.html"></iframe>
+```
+
+**CRITICAL:** Communication between the extension page and the sandboxed iframe MUST use
+`postMessage`. You CANNOT access `iframe.contentDocument` or `iframe.contentWindow.document`
+directly — this will throw:
+
+```
+SecurityError: Blocked a frame with origin "chrome-extension://..." from accessing a cross-origin frame.
+```
+
+Correct pattern:
+
+```js
+// playground.js — send code to sandbox
+const iframe = document.getElementById('preview');
+iframe.contentWindow.postMessage({
+  html: htmlCode,
+  css: cssCode,
+  js: jsCode
+}, '*');
+
+// sandbox.js — receive and execute
+window.addEventListener('message', (event) => {
+  const { html, css, js } = event.data;
+  // Clear previous content
+  document.body.innerHTML = '';
+  document.head.querySelectorAll('style.user-style').forEach(s => s.remove());
+
+  // Apply HTML
+  const container = document.createElement('div');
+  container.innerHTML = html;
+  document.body.appendChild(container);
+
+  // Apply CSS
+  const style = document.createElement('style');
+  style.className = 'user-style';
+  style.textContent = css;
+  document.head.appendChild(style);
+
+  // Execute JS (eval is allowed in sandbox!)
+  try {
+    eval(js);
+  } catch (e) {
+    const errEl = document.createElement('pre');
+    errEl.style.color = 'red';
+    errEl.textContent = e.message;
+    document.body.appendChild(errEl);
+  }
+});
+```
+
+### Option 2: Blob URL in iframe
+
+Create a self-contained HTML document via blob URL:
+
+```js
+function updatePreview(htmlCode, cssCode, jsCode) {
+  const html = `
+<!DOCTYPE html>
+<html>
+<head><style>${cssCode}</style></head>
+<body>
+  ${htmlCode}
+  <script>${jsCode}<\/script>
+</body>
+</html>
+`;
+  const blob = new Blob([html], { type: 'text/html' });
+  const url = URL.createObjectURL(blob);
+  const iframe = document.getElementById('preview');
+  // Revoke previous URL
+  if (iframe.dataset.blobUrl) URL.revokeObjectURL(iframe.dataset.blobUrl);
+  iframe.dataset.blobUrl = url;
+  iframe.src = url;
+}
+```
+
+### Option 3: srcdoc Attribute
+
+```js
+const iframe = document.getElementById('preview');
+iframe.srcdoc = `
+  <!DOCTYPE html>
+  <style>${cssCode}</style>
+  ${htmlCode}
+  <script>${jsCode}<\/script>
+`;
+```
+
+Both blob URLs and srcdoc create a separate origin, so they bypass the extension's CSP.
+However, they also cannot access chrome.* APIs, and you cannot access their DOM directly
+from the extension page (same cross-origin restriction as sandbox).
+
+### What NOT to Do
+
+```js
+// ❌ WILL FAIL: Trying to set iframe content directly
+iframe.contentDocument.open();
+iframe.contentDocument.write(html);
+iframe.contentDocument.close();
+
+// ❌ WILL FAIL: Accessing cross-origin sandbox DOM
+const doc = iframe.contentWindow.document;
+doc.body.innerHTML = html;
+
+// ❌ WILL FAIL: eval in a normal extension page
+eval(userCode); // CSP blocks this
+```
+
+## CSP for Remote Resources
+
+Extension pages cannot load remote scripts by default. If you need external libraries:
+
+1. **Bundle them** — download and include in your extension
+2. **Use chrome.scripting to inject into web pages** — web pages have their own CSP
+
+For content scripts injected into web pages, the web page's CSP does NOT apply to the
+content script's own code. Content scripts run in an isolated world.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/declarative-net-request.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/declarative-net-request.md
new file mode 100644
index 00000000..6a24a67b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/declarative-net-request.md
@@ -0,0 +1,112 @@
+# Declarative Net Request (Content Filtering)
+
+## Setup
+
+```json
+{
+  "permissions": ["declarativeNetRequest"],
+  "declarative_net_request": {
+    "rule_resources": [{
+      "id": "ruleset_1",
+      "enabled": true,
+      "path": "rules/rules.json"
+    }]
+  }
+}
+```
+
+Add `"declarativeNetRequestFeedback"` permission to use `onRuleMatchedDebug` (dev only).
+
+## Rule Format
+
+`rules/rules.json`:
+```json
+[
+  {
+    "id": 1,
+    "priority": 1,
+    "action": { "type": "block" },
+    "condition": {
+      "urlFilter": "doubleclick.net",
+      "resourceTypes": ["script", "image", "xmlhttprequest", "sub_frame"]
+    }
+  },
+  {
+    "id": 2,
+    "priority": 1,
+    "action": { "type": "block" },
+    "condition": {
+      "urlFilter": "google-analytics.com",
+      "resourceTypes": ["script", "xmlhttprequest"]
+    }
+  }
+]
+```
+
+### Rule Fields
+
+- `id`: Unique integer per rule
+- `priority`: Higher priority rules win conflicts
+- `action.type`: `"block"`, `"redirect"`, `"allow"`, `"modifyHeaders"`, `"allowAllRequests"`, `"upgradeScheme"`
+- `condition.urlFilter`: Pattern matching (supports `*`, `||`, `|`, `^`)
+- `condition.resourceTypes`: Array of resource types to match
+
+### URL Filter Patterns
+
+| Pattern | Matches |
+|---------|---------|
+| `"doubleclick.net"` | Any URL containing "doubleclick.net" |
+| `"||doubleclick.net"` | Domain starts with doubleclick.net |
+| `"||example.com/ads/*"` | Specific path pattern |
+| `*://*.tracking.com/*` | Subdomain matching |
+
+### Resource Types
+
+`main_frame`, `sub_frame`, `stylesheet`, `script`, `image`, `font`, `object`, `xmlhttprequest`,
+`ping`, `csp_report`, `media`, `websocket`, `webtransport`, `webbundle`, `other`
+
+## Dynamic Rules (runtime)
+
+```js
+// Add rules at runtime
+await chrome.declarativeNetRequest.updateDynamicRules({
+  addRules: [{
+    id: 1000,
+    priority: 1,
+    action: { type: 'block' },
+    condition: { urlFilter: 'ads.example.com' }
+  }],
+  removeRuleIds: [] // IDs to remove
+});
+```
+
+## Tracking Blocked Requests
+
+`onRuleMatchedDebug` only works in dev (unpacked) and requires `declarativeNetRequestFeedback`:
+
+```js
+chrome.declarativeNetRequest.onRuleMatchedDebug.addListener((info) => {
+  // info.request, info.rule
+});
+```
+
+For production, count via `webRequest` (observe only) or maintain counts with `webNavigation`:
+
+```js
+// Alternative: Use webRequest to observe (requires host_permissions)
+chrome.webRequest.onBeforeRequest.addListener(
+  (details) => {
+    // Count requests to known tracking domains
+    if (isTrackerDomain(new URL(details.url).hostname)) {
+      incrementBlockCount(details.tabId);
+    }
+  },
+  { urls: ["<all_urls>"] }
+);
+```
+
+## Limits
+
+- Static rules: 30,000 guaranteed per extension, plus an additional 300,000 from a pool shared between extensions
+- Dynamic rules: 30,000
+- Session rules: 5,000
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/devtools.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/devtools.md
new file mode 100644
index 00000000..6c99e83c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/devtools.md
@@ -0,0 +1,102 @@
+# DevTools Panels
+
+## Setup
+
+```json
+{
+  "devtools_page": "devtools/devtools.html"
+}
+```
+
+The devtools page runs ONLY when DevTools is open. It's invisible — its job is to create panels.
+
+## Creating a Panel
+
+`devtools/devtools.html`:
+```html
+<!DOCTYPE html>
+<html>
+<body>
+  <script src="devtools.js"></script>
+</body>
+</html>
+```
+
+`devtools/devtools.js`:
+```js
+chrome.devtools.panels.create(
+  'My Panel',                    // Title shown in DevTools tab
+  'icons/icon-16.png',           // Icon (optional, can be empty string)
+  'devtools/panel/panel.html',   // Panel content page — RELATIVE TO EXTENSION ROOT
+  (panel) => {
+    // panel.onShown.addListener((window) => { ... });
+    // panel.onHidden.addListener(() => { ... });
+  }
+);
+```
+
+**CRITICAL: The panel path is relative to the extension root**, NOT relative to the devtools.js
+file. This is the most common DevTools extension bug.
+
+```js
+// ❌ WRONG — resolves to <ext-root>/panel/panel.html (file not found)
+chrome.devtools.panels.create("My Panel", "", "panel/panel.html");
+
+// ✅ CORRECT — resolves to <ext-root>/devtools/panel/panel.html
+chrome.devtools.panels.create("My Panel", "", "devtools/panel/panel.html");
+```
+
+## Panel Content
+
+`devtools/panel/panel.html` is a regular extension page with full chrome.* API access.
+
+## Accessing DevTools APIs
+
+Only available in the devtools page and panels:
+
+```js
+// Get inspected window's tab ID
+const tabId = chrome.devtools.inspectedWindow.tabId;
+
+// Evaluate JS in the inspected page
+chrome.devtools.inspectedWindow.eval('document.title', (result, isException) => {
+  console.log('Page title:', result);
+});
+
+// Monitor network requests
+chrome.devtools.network.onRequestFinished.addListener((request) => {
+  // request.request.url, request.response.status, etc.
+  // HAR entry format
+});
+
+// Get all captured requests
+chrome.devtools.network.getHAR((harLog) => {
+  harLog.entries.forEach((entry) => { /* process */ });
+});
+```
+
+## Communication Architecture
+
+DevTools pages/panels CANNOT directly talk to the service worker via `chrome.runtime.sendMessage`
+in all cases. Use a connection pattern:
+
+```js
+// In panel JS — connect to service worker
+const port = chrome.runtime.connect({ name: 'devtools-panel' });
+port.postMessage({ type: 'INIT', tabId: chrome.devtools.inspectedWindow.tabId });
+port.onMessage.addListener((msg) => { /* handle */ });
+
+// In service worker
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name === 'devtools-panel') {
+    port.onMessage.addListener((msg) => { /* handle */ });
+  }
+});
+```
+
+## Important Notes
+
+- DevTools pages exist per-DevTools-window (one per inspected tab)
+- They are destroyed when DevTools closes
+- `chrome.devtools.*` APIs are ONLY available in the devtools page context, not in the service worker
+- Panels can inject scripts into the inspected page via `chrome.devtools.inspectedWindow.eval()`
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/icons.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/icons.md
new file mode 100644
index 00000000..a2340867
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/icons.md
@@ -0,0 +1,101 @@
+# Generating Extension Icons
+
+## Quick: Omit icons
+
+If generating real icon files is impractical, **omit `icons` and `default_icon` from manifest.json entirely**. Chrome uses a default puzzle-piece icon. This is always better than referencing files that don't exist.
+
+## Generate with Python (Pillow)
+
+```python
+# generate_icons.py
+from PIL import Image, ImageDraw
+import os
+
+os.makedirs('icons', exist_ok=True)
+
+for size in [16, 48, 128]:
+    img = Image.new('RGBA', (size, size), (0, 0, 0, 0))
+    draw = ImageDraw.Draw(img)
+    margin = max(1, size // 16)
+    draw.rounded_rectangle(
+        [margin, margin, size - margin, size - margin],
+        radius=size // 4,
+        fill='#4688F1'
+    )
+    # Add a letter
+    font_size = size // 2
+    draw.text((size // 2, size // 2), 'E', fill='white', anchor='mm')
+    img.save(f'icons/icon-{size}.png')
+    print(f'Created icons/icon-{size}.png ({size}x{size})')
+```
+
+## Generate with Node.js (canvas)
+
+```js
+const { createCanvas } = require('canvas');
+const fs = require('fs');
+const path = require('path');
+
+fs.mkdirSync('icons', { recursive: true });
+
+for (const size of [16, 48, 128]) {
+  const canvas = createCanvas(size, size);
+  const ctx = canvas.getContext('2d');
+  const r = size / 4;
+  
+  // Rounded rectangle
+  ctx.beginPath();
+  ctx.roundRect(1, 1, size - 2, size - 2, r);
+  ctx.fillStyle = '#4688F1';
+  ctx.fill();
+  
+  // Letter
+  ctx.fillStyle = 'white';
+  ctx.font = `bold ${size / 2}px sans-serif`;
+  ctx.textAlign = 'center';
+  ctx.textBaseline = 'middle';
+  ctx.fillText('E', size / 2, size / 2);
+  
+  fs.writeFileSync(`icons/icon-${size}.png`, canvas.toBuffer('image/png'));
+  console.log(`Created icons/icon-${size}.png (${size}x${size})`);
+}
+```
+
+## Generate with pure SVG (no dependencies)
+
+Create SVGs and use them directly (Chrome supports SVG icons in some contexts) or convert:
+
+```bash
+for SIZE in 16 48 128; do
+  cat > "icons/icon-${SIZE}.svg" << EOF
+<svg xmlns="http://www.w3.org/2000/svg" width="${SIZE}" height="${SIZE}" viewBox="0 0 ${SIZE} ${SIZE}">
+  <rect width="${SIZE}" height="${SIZE}" rx="$((SIZE/4))" fill="#4688F1"/>
+  <text x="50%" y="52%" text-anchor="middle" dominant-baseline="middle"
+        fill="white" font-family="sans-serif" font-weight="bold" font-size="$((SIZE/2))">E</text>
+</svg>
+EOF
+done
+```
+
+Note: For Chrome Web Store submission, PNG is required. SVG works for development.
+
+## Manifest reference
+
+```json
+{
+  "icons": {
+    "16": "icons/icon-16.png",
+    "48": "icons/icon-48.png",
+    "128": "icons/icon-128.png"
+  },
+  "action": {
+    "default_icon": {
+      "16": "icons/icon-16.png",
+      "48": "icons/icon-48.png",
+      "128": "icons/icon-128.png"
+    }
+  }
+}
+```
+
+Each file MUST match its declared size: icon-16.png = 16×16 pixels, etc.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/media-capture.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/media-capture.md
new file mode 100644
index 00000000..21333ebf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/media-capture.md
@@ -0,0 +1,140 @@
+# Media Capture (Tab & Desktop)
+
+## Choosing the Right API
+
+| Need | API |
+|------|-----|
+| Record the active tab's audio/video | `chrome.tabCapture.getMediaStreamId()` |
+| Let the user choose a screen, window, or tab | `chrome.desktopCapture.chooseDesktopMedia()` |
+
+Prefer `tabCapture` when you only need the current tab — it requires no user chooser dialog and
+no `"tabs"` permission. Use `desktopCapture` only when the user must select what to capture.
+
+## Tab Capture
+
+### Permissions
+
+```json
+{ "permissions": ["tabCapture"] }
+```
+
+### Pattern
+
+`chrome.tabCapture.getMediaStreamId()` runs in the **service worker** and returns a stream ID.
+The actual `getUserMedia()` call must happen in an **offscreen document** (the SW cannot access
+media streams directly).
+
+```js
+// service-worker.js
+chrome.action.onClicked.addListener(async (tab) => {
+  const streamId = await chrome.tabCapture.getMediaStreamId({ targetTabId: tab.id });
+  // Pass the ID to the offscreen document to call getUserMedia
+  await chrome.runtime.sendMessage({ type: 'START_CAPTURE', streamId });
+});
+
+// offscreen.js
+chrome.runtime.onMessage.addListener((msg) => {
+  if (msg.type !== 'START_CAPTURE') return;
+  (async () => {
+    const stream = await navigator.mediaDevices.getUserMedia({
+      audio: { mandatory: { chromeMediaSource: 'tab', chromeMediaSourceId: msg.streamId } },
+      video: { mandatory: { chromeMediaSource: 'tab', chromeMediaSourceId: msg.streamId } }
+    });
+    const recorder = new MediaRecorder(stream, { mimeType: 'video/webm' });
+    // ... handle recorder events
+  })();
+});
+```
+
+## Desktop Capture
+
+### Permissions
+
+```json
+{ "permissions": ["tabs", "desktopCapture"] }
+```
+
+`"tabs"` is **required** — `chooseDesktopMedia` needs a `targetTab` with its `url` field
+populated, which requires the `"tabs"` permission.
+
+### Pattern
+
+```js
+// service-worker.js
+chrome.action.onClicked.addListener(async (tab) => {
+  // ❌ BROKEN — no targetTab
+  // chrome.desktopCapture.chooseDesktopMedia(['screen', 'window'], cb);
+
+  // ✅ CORRECT — pass the active tab
+  chrome.desktopCapture.chooseDesktopMedia(['screen', 'window', 'tab'], tab, (streamId) => {
+    if (!streamId) return; // User cancelled
+    // Send streamId to offscreen document for getUserMedia
+    chrome.runtime.sendMessage({ type: 'START_DESKTOP_CAPTURE', streamId });
+  });
+});
+```
+
+## State Locking — Prevent Double-Start Errors
+
+Both APIs fail if called while a previous capture is still active:
+- `tabCapture`: `"Cannot capture a tab with an active stream"`
+- `desktopCapture`: opens a second chooser dialog on top of the first
+
+Use a state machine stored in `chrome.storage.session` (survives service worker restarts,
+cleared on browser close):
+
+```js
+// State: 'idle' → 'starting' → 'recording' → 'stopping' → 'idle'
+chrome.action.onClicked.addListener(async (tab) => {
+  const { recordingState = 'idle' } = await chrome.storage.session.get('recordingState');
+
+  // Ignore clicks during transitions
+  if (recordingState === 'starting' || recordingState === 'stopping') return;
+
+  if (recordingState === 'idle') {
+    await chrome.storage.session.set({ recordingState: 'starting' });
+    try {
+      await startRecording(tab);
+      await chrome.storage.session.set({ recordingState: 'recording' });
+      await chrome.action.setBadgeText({ text: 'REC' });
+      await chrome.action.setBadgeBackgroundColor({ color: '#FF0000' });
+    } catch (err) {
+      console.error('Failed to start recording:', err);
+      await chrome.storage.session.set({ recordingState: 'idle' });
+    }
+  } else if (recordingState === 'recording') {
+    await chrome.storage.session.set({ recordingState: 'stopping' });
+    try { await stopRecording(); }
+    finally {
+      await chrome.storage.session.set({ recordingState: 'idle' });
+      await chrome.action.setBadgeText({ text: '' });
+    }
+  }
+});
+```
+
+This same pattern applies to `chrome.offscreen.createDocument` (only one offscreen document
+is allowed at a time) and any other API that manages an exclusive resource.
+
+## Saving Recordings
+
+Offscreen documents cannot call `chrome.downloads` — send the blob back to the service worker:
+
+```js
+// offscreen.js — when recording stops
+recorder.ondataavailable = (e) => chunks.push(e.data);
+recorder.onstop = async () => {
+  const blob = new Blob(chunks, { type: 'video/webm' });
+  const url = URL.createObjectURL(blob);
+  // Service worker handles the download
+  await chrome.runtime.sendMessage({ type: 'SAVE_RECORDING', url });
+};
+
+// service-worker.js
+chrome.runtime.onMessage.addListener((msg) => {
+  if (msg.type !== 'SAVE_RECORDING') return;
+  chrome.downloads.download({ url: msg.url, filename: 'recording.webm' });
+});
+```
+
+See `references/extensions/message-passing.md` for the full offscreen document messaging pattern.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/message-passing.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/message-passing.md
new file mode 100644
index 00000000..7846ac49
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/message-passing.md
@@ -0,0 +1,136 @@
+# Message Passing
+
+## Basic patterns
+
+### One-way message (fire and forget)
+
+```js
+// sender (popup, content script, etc.)
+chrome.runtime.sendMessage({ type: 'LOG', data: 'hello' });
+
+// receiver (service worker)
+chrome.runtime.onMessage.addListener((message, sender) => {
+  if (message.type === 'LOG') console.log(message.data);
+});
+```
+
+### Request/response — IIFE + return true (most compatible)
+
+```js
+// sender
+const response = await chrome.runtime.sendMessage({ type: 'GET_DATA' });
+console.log(response.data);
+
+// receiver — IIFE keeps the channel open until sendResponse is called
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  if (message.type === 'GET_DATA') {
+    (async () => {
+      const data = await chrome.storage.local.get('key');
+      sendResponse({ data });
+    })();
+    return true; // REQUIRED — tells Chrome to keep the channel open
+  }
+});
+```
+
+### Request/response — return a Promise (Chrome 99+)
+
+Returning a Promise directly from the listener is now supported and cleaner than the IIFE pattern:
+
+```js
+chrome.runtime.onMessage.addListener((message, sender) => {
+  if (message.type === 'GET_DATA') {
+    return chrome.storage.local.get('key'); // returned promise resolves the response
+  }
+  // Return nothing (or undefined) for messages this listener doesn't handle
+});
+```
+
+**Note:** Requires Chrome 99+, only use when minimum Chrome version is set to 99.
+**Note:** Do NOT mix the two styles. If you return a Promise, do NOT also call `sendResponse` or `return true`.
+
+## Content script ↔ service worker
+
+```js
+// content script → service worker
+const result = await chrome.runtime.sendMessage({ type: 'FETCH_DATA', url: location.href });
+
+// service worker → specific tab's content script
+await chrome.tabs.sendMessage(tabId, { type: 'HIGHLIGHT', selector: '.important' });
+```
+
+## Service worker → content script (targeted)
+
+Always check that the tab exists and the content script is injected:
+
+```js
+async function sendToContentScript(tabId, message) {
+  try {
+    return await chrome.tabs.sendMessage(tabId, message);
+  } catch (err) {
+    // Content script not injected yet, or tab navigated away
+    console.warn('Could not reach content script:', err.message);
+    return null;
+  }
+}
+```
+
+## Long-lived connections (ports)
+
+Use ports when you need a persistent channel (e.g., streaming data, DevTools panel):
+
+```js
+// opener (popup or content script)
+const port = chrome.runtime.connect({ name: 'my-channel' });
+port.postMessage({ type: 'START' });
+port.onMessage.addListener((msg) => console.log('received:', msg));
+port.onDisconnect.addListener(() => console.log('disconnected'));
+
+// receiver (service worker)
+chrome.runtime.onConnect.addListener((port) => {
+  if (port.name !== 'my-channel') return;
+  port.onMessage.addListener((msg) => {
+    if (msg.type === 'START') {
+      port.postMessage({ status: 'ok' });
+    }
+  });
+});
+```
+
+## Common mistakes
+
+### Missing `return true` causes response to never arrive
+
+```js
+// ❌ BROKEN — async work completes but channel is already closed
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  fetchSomething().then(data => sendResponse(data)); // too late
+  // missing: return true
+});
+
+// ✅ CORRECT
+chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
+  fetchSomething().then(data => sendResponse(data));
+  return true;
+});
+```
+
+### Sending to a tab before the content script is ready
+
+Content scripts are injected after the page loads. If the service worker sends a message immediately on `tabs.onUpdated`, the content script may not be listening yet. Use a handshake or retry:
+
+```js
+// content script — announce it's ready
+chrome.runtime.sendMessage({ type: 'CONTENT_READY' });
+
+// service worker — wait for CONTENT_READY before sending
+chrome.runtime.onMessage.addListener((msg, sender) => {
+  if (msg.type === 'CONTENT_READY' && sender.tab) {
+    chrome.tabs.sendMessage(sender.tab.id, { type: 'INIT_DATA', ... });
+  }
+});
+```
+
+### Multiple listeners responding
+
+Only one listener should respond to a given message type. If multiple listeners call `sendResponse`, only the first one wins and the rest are silently ignored.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/omnibox.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/omnibox.md
new file mode 100644
index 00000000..0d9816e3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/omnibox.md
@@ -0,0 +1,83 @@
+# Omnibox Integration
+
+## Setup
+
+```json
+{
+  "omnibox": { "keyword": "wiki" }
+}
+```
+
+User types `wiki` + Space in the address bar to activate.
+
+## Providing Suggestions
+
+```js
+chrome.omnibox.onInputChanged.addListener(async (text, suggest) => {
+  if (text.length < 2) return;
+
+  try {
+    const response = await fetch(
+      `https://en.wikipedia.org/w/api.php?action=opensearch&search=${encodeURIComponent(text)}&limit=5&format=json`
+    );
+    const [, titles, , urls] = await response.json();
+
+    const suggestions = titles.map((title, i) => ({
+      content: urls[i],
+      description: `${title} - <url>${urls[i]}</url>`
+    }));
+
+    suggest(suggestions);
+  } catch (err) {
+    console.error('Search failed:', err);
+  }
+});
+```
+
+## Handling Selection
+
+```js
+chrome.omnibox.onInputEntered.addListener((text, disposition) => {
+  const url = text.startsWith('http') ? text
+    : `https://en.wikipedia.org/wiki/${encodeURIComponent(text)}`;
+
+  switch (disposition) {
+    case 'currentTab':
+      chrome.tabs.update({ url });
+      break;
+    case 'newForegroundTab':
+      chrome.tabs.create({ url });
+      break;
+    case 'newBackgroundTab':
+      chrome.tabs.create({ url, active: false });
+      break;
+  }
+});
+```
+
+## Description Formatting
+
+Suggestions support XML-like formatting:
+- `<url>text</url>` — renders as URL style
+- `<match>text</match>` — bold match highlighting
+- `<dim>text</dim>` — dimmed/secondary text
+
+## Default Suggestion
+
+```js
+chrome.omnibox.onInputChanged.addListener((text, suggest) => {
+  chrome.omnibox.setDefaultSuggestion({
+    description: `Search Wikipedia for "<match>${text}</match>"`
+  });
+  // ... fetch and suggest
+});
+```
+
+## Required host_permissions
+
+If fetching suggestions from an API, declare:
+```json
+{
+  "host_permissions": ["https://en.wikipedia.org/*"]
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/permissions.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/permissions.md
new file mode 100644
index 00000000..c104bef7
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/permissions.md
@@ -0,0 +1,113 @@
+# Permissions
+
+## `permissions` vs `host_permissions`
+
+These are separate manifest keys — don't conflate them:
+
+```json
+{
+  "permissions": ["tabs", "scripting", "storage"],
+  "host_permissions": ["https://api.example.com/*"]
+}
+```
+
+- `permissions` grants access to chrome.* APIs (`tabs`, `storage`, `scripting`, `desktopCapture`, etc.)
+- `host_permissions` grants access to specific origins for `fetch`, `chrome.scripting.executeScript`, and reading tab URLs cross-origin
+
+Scope `host_permissions` to specific domains rather than `<all_urls>` unless the extension genuinely needs to run on every site — broad host permissions draw extra Chrome Web Store review scrutiny.
+
+## `tab.url` requires the `tabs` permission
+
+Without it, `tab.url` and `tab.title` silently return `undefined` — no error thrown.
+
+```js
+// manifest.json — REQUIRED if you read tab.url or tab.title anywhere:
+{ "permissions": ["tabs"] }
+```
+
+See `references/extensions/tab-management.md` for the full tabs/windows API.
+
+## `activeTab` only works on direct user gestures — not from side panels
+
+`activeTab` grants temporary access to the current tab ONLY when triggered by:
+- Clicking the extension action icon
+- A context menu item (including the `"tab"` context)
+- A keyboard shortcut from the `commands` API
+- Accepting an omnibox suggestion
+
+It does **NOT** grant access when clicking a button in a side panel, a popup button that opens
+later, or any programmatic trigger.
+
+```js
+// ❌ BROKEN — activeTab does NOT work from a side panel button click
+document.getElementById('summarize').addEventListener('click', async () => {
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  await chrome.scripting.executeScript({ target: { tabId: tab.id }, func: () => document.body.innerText });
+});
+
+// ✅ FIX — use "tabs" permission + specific host_permissions instead
+// manifest.json: { "permissions": ["tabs", "scripting"], "host_permissions": ["<all_urls>"] }
+```
+
+See `references/extensions/side-panel.md` for the side-panel-specific writeup.
+
+## `chrome.permissions.request()` needs a user gesture — the gesture survives one `sendMessage` hop, but not an `await` after that
+
+`chrome.permissions.request()` (for optional/dynamic permissions) only works within a user
+gesture (a click, keypress, etc.). A gesture from a UI context (side panel, popup) **does**
+propagate across `chrome.runtime.sendMessage` to the service worker's `onMessage` listener — but
+it's only good for that one synchronous turn. If the listener `await`s anything (a timer, a
+storage read, another message round-trip) before calling `chrome.permissions.request()`, the
+gesture is gone and the call throws `"This function must be called during a user gesture, such
+as an onclick handler"`.
+
+```js
+// side-panel.js
+button.addEventListener('click', () => {
+  chrome.runtime.sendMessage({ type: 'REQUEST_PERMISSION' }, (granted) => { ... });
+});
+
+// service-worker.js
+
+// ❌ BROKEN — an await before chrome.permissions.request() burns the gesture window
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
+  if (msg.type === 'REQUEST_PERMISSION') {
+    (async () => {
+      await chrome.storage.local.get('someSetting'); // gesture is gone after this
+      const granted = await chrome.permissions.request({ permissions: ['downloads'] });
+      sendResponse(granted);
+    })();
+    return true;
+  }
+});
+
+// ✅ CORRECT — call chrome.permissions.request() as the first thing in the listener,
+// nothing awaited before it
+chrome.runtime.onMessage.addListener((msg, sender, sendResponse) => {
+  if (msg.type === 'REQUEST_PERMISSION') {
+    chrome.permissions.request({ permissions: ['downloads'] }).then(sendResponse);
+    return true; // fine to await the *result* — the call itself already happened synchronously
+  }
+});
+```
+
+**Rule of thumb:** call `chrome.permissions.request()` (or anything else gated on a user
+gesture, like `activeTab`) as the very first statement of the message listener that receives the
+click-triggered message — before any other `await`. Awaiting the *returned* promise afterward is
+fine; awaiting anything *before* the call is what breaks it.
+
+## Checking and removing permissions
+
+```js
+// Check whether an optional permission is currently granted
+const hasIt = await chrome.permissions.contains({ permissions: ['downloads'] });
+
+// Remove a previously granted optional permission
+await chrome.permissions.remove({ permissions: ['downloads'] });
+```
+
+Declare optional permissions in the manifest so they're eligible to be requested at runtime:
+
+```json
+{ "optional_permissions": ["downloads"] }
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/popup-ui.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/popup-ui.md
new file mode 100644
index 00000000..8e152843
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/popup-ui.md
@@ -0,0 +1,94 @@
+# Popup UI
+
+## Setup
+
+```json
+{
+  "action": {
+    "default_popup": "popup/popup.html",
+    "default_icon": {
+      "16": "icons/icon-16.png",
+      "48": "icons/icon-48.png",
+      "128": "icons/icon-128.png"
+    },
+    "default_title": "My Extension"
+  }
+}
+```
+
+## Key Constraints
+
+- Popup closes when the user clicks outside it — don't rely on it staying open
+- Default max size: 800x600 px. Set size via CSS on body/html
+- All scripts must be external files (CSP — no inline scripts)
+- All event listeners must use `addEventListener` (no inline handlers)
+
+## Popup HTML Template
+
+```html
+<!DOCTYPE html>
+<html>
+<head>
+  <meta charset="utf-8">
+  <style>
+    body { width: 350px; min-height: 200px; padding: 16px; font-family: system-ui; }
+  </style>
+</head>
+<body>
+  <h1>My Extension</h1>
+  <div id="content"></div>
+  <script src="popup.js"></script>
+</body>
+</html>
+```
+
+## Persistence
+
+Popup state is lost when closed. Use `chrome.storage` for persistence:
+
+```js
+// Save on change
+document.getElementById('input').addEventListener('input', (e) => {
+  chrome.storage.local.set({ savedInput: e.target.value });
+});
+
+// Restore on open
+document.addEventListener('DOMContentLoaded', async () => {
+  const { savedInput = '' } = await chrome.storage.local.get('savedInput');
+  document.getElementById('input').value = savedInput;
+});
+```
+
+Note: `localStorage` technically works in popups (they have a persistent origin), but
+`chrome.storage` is strongly preferred because it works across all extension contexts
+and supports sync.
+
+## Communicating with Service Worker
+
+```js
+// From popup
+const response = await chrome.runtime.sendMessage({ type: 'GET_STATUS' });
+
+// Long-lived connection
+const port = chrome.runtime.connect({ name: 'popup' });
+port.postMessage({ type: 'INIT' });
+port.onMessage.addListener((msg) => { /* handle */ });
+```
+
+## Dynamic Popup vs No Popup
+
+If you want the action click to do something instead of showing a popup, remove
+`default_popup` and use `chrome.action.onClicked`:
+
+```js
+// In service worker — only fires if NO popup is set
+chrome.action.onClicked.addListener((tab) => {
+  // Open side panel, inject script, etc.
+});
+```
+
+You can toggle between popup and no-popup dynamically:
+```js
+chrome.action.setPopup({ popup: 'popup/popup.html' }); // Enable popup
+chrome.action.setPopup({ popup: '' }); // Disable popup (enables onClicked)
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/prompt-api.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/prompt-api.md
new file mode 100644
index 00000000..bda04cd0
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/prompt-api.md
@@ -0,0 +1,117 @@
+# Chrome Prompt API (LanguageModel) — Extension-Specific Notes
+
+The `LanguageModel` API (Prompt API) works in all extension contexts — service worker, popup,
+side panel, and other extension pages — with no additional manifest permissions required.
+
+For general Prompt API usage (availability checks, session creation, streaming, session
+management), use the `modern-web-guidance` skill.
+
+## Deprecated namespace
+
+Extensions that used the origin trial may still have the old API surface. Remove it:
+
+```js
+// ❌ OLD — deprecated
+const session = await self.ai.languageModel.create();
+
+// ✅ CURRENT (Chrome 138+)
+const session = await LanguageModel.create({ ... });
+```
+
+Also remove the expired permission from manifest.json:
+```json
+"permissions": ["aiLanguageModelOriginTrial"]  // ❌ remove this
+```
+
+## Extension-only: `LanguageModel.params()`
+
+Extensions have access to `LanguageModel.params()`, which returns model constraints not
+available on the web:
+
+```js
+const params = await LanguageModel.params();
+// { defaultTopK: 3, maxTopK: 128, defaultTemperature: 1, maxTemperature: 2 }
+
+const session = await LanguageModel.create({
+  temperature: 0.7,
+  topK: 5
+});
+```
+
+## Complete extension example: page summarizer
+
+A full wiring example showing manifest + service worker + side panel together.
+Note the use of `tabs` + `host_permissions` instead of `activeTab` — side panel button
+clicks do NOT activate `activeTab` (see Rule 12).
+
+### manifest.json
+```json
+{
+  "manifest_version": 3,
+  "name": "AI Page Summarizer",
+  "version": "1.0",
+  "permissions": ["sidePanel", "tabs", "scripting"],
+  "host_permissions": ["<all_urls>"],
+  "background": { "service_worker": "service-worker.js" },
+  "side_panel": { "default_path": "sidepanel/sidepanel.html" },
+  "action": { "default_title": "Summarize Page" }
+}
+```
+
+### service-worker.js
+```js
+chrome.action.onClicked.addListener(async (tab) => {
+  await chrome.sidePanel.open({ windowId: tab.windowId });
+});
+```
+
+### sidepanel/sidepanel.js
+```js
+const statusEl = document.getElementById('status');
+const summaryEl = document.getElementById('summary');
+
+document.getElementById('summarize').addEventListener('click', async () => {
+  if (!globalThis.LanguageModel) {
+    statusEl.textContent = 'Prompt API not available in this browser.';
+    return;
+  }
+
+  const availability = await LanguageModel.availability({
+    expectedInputs: [{ type: "text", languages: ["en"] }],
+    expectedOutputs: [{ type: "text", languages: ["en"] }]
+  });
+  if (availability === 'unavailable') {
+    statusEl.textContent = 'AI model not available on this device.';
+    return;
+  }
+
+  // Requires "tabs" + "host_permissions" — activeTab does NOT work from a side panel button
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  const [{ result: pageText }] = await chrome.scripting.executeScript({
+    target: { tabId: tab.id },
+    func: () => {
+      const body = document.body.cloneNode(true);
+      body.querySelectorAll('script, style, nav, footer, header').forEach(el => el.remove());
+      return body.innerText.substring(0, 4000);
+    }
+  });
+
+  const session = await LanguageModel.create({
+    expectedInputs: [{ type: "text", languages: ["en"] }],
+    expectedOutputs: [{ type: "text", languages: ["en"] }],
+    initialPrompts: [{ role: 'system', content: 'Summarize web page content in 3-5 bullet points.' }],
+    monitor(m) {
+      m.addEventListener('downloadprogress', (e) => {
+        const pct = e.total ? Math.floor((e.loaded / e.total) * 100) : 0;
+        statusEl.textContent = `Downloading model: ${pct}%`;
+      });
+    }
+  });
+
+  summaryEl.textContent = '';
+  for await (const chunk of session.promptStreaming(`Summarize:\n\n${pageText}`)) {
+    summaryEl.textContent += chunk; // APPEND — do not replace
+  }
+  session.destroy();
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/service-worker.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/service-worker.md
new file mode 100644
index 00000000..20b88c69
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/service-worker.md
@@ -0,0 +1,148 @@
+# Service Worker Lifetime & State Management
+
+## The Core Problem
+
+Chrome terminates extension service workers after ~30 seconds of inactivity. Unlike Manifest V2
+persistent background pages, you CANNOT rely on in-memory state.
+
+## Rules
+
+1. **Never store state in global variables** — treat every event handler as if the SW just started
+2. **Use chrome.storage for all persistent state** — read on demand, write after changes
+3. **Use chrome.alarms for timers** — not setTimeout/setInterval (these die with the SW)
+4. **Use chrome.storage.session for ephemeral session state** — survives SW restart but not browser restart
+
+## Storage Tier Selection
+
+| Need | Use |
+|------|-----|
+| Survives browser restart, syncs across devices | `chrome.storage.sync` (8KB/item, 100KB total) |
+| Survives browser restart, local only | `chrome.storage.local` (10MB default) |
+| Survives SW restart only | `chrome.storage.session` (10MB default) |
+| Never persisted (avoid) | Global variables ❌ |
+
+## Pattern: State Read-on-Demand
+
+```js
+// ❌ BAD: State in memory
+let count = 0;
+chrome.webNavigation.onCompleted.addListener(() => {
+  count++;
+  chrome.action.setBadgeText({ text: String(count) });
+});
+
+// ✅ GOOD: State in storage
+chrome.webNavigation.onCompleted.addListener(async (details) => {
+  if (details.frameId !== 0) return; // Main frame only
+  const data = await chrome.storage.local.get({ visitCount: 0 });
+  data.visitCount++;
+  await chrome.storage.local.set(data);
+  chrome.action.setBadgeText({ text: String(data.visitCount) });
+});
+```
+
+## Pattern: Alarms Instead of Timers
+
+```js
+// ❌ BAD: Timer dies when SW terminates
+setInterval(() => checkForUpdates(), 60000);
+
+// ✅ GOOD: Alarm persists
+chrome.alarms.create('check-updates', { periodInMinutes: 1 });
+chrome.alarms.onAlarm.addListener((alarm) => {
+  if (alarm.name === 'check-updates') {
+    checkForUpdates();
+  }
+});
+```
+
+Minimum alarm interval: 0.5 minutes.
+
+## Pattern: One-Time Initialization
+
+```js
+// Set up defaults and context menus on install
+chrome.runtime.onInstalled.addListener(async (details) => {
+  if (details.reason === 'install') {
+    await chrome.storage.local.set({ settings: defaultSettings });
+  }
+  // Context menus must be re-created (they persist, but re-creating is idempotent)
+  chrome.contextMenus.create({
+    id: 'myItem',
+    title: 'My Context Menu Item',
+    contexts: ['selection']
+  });
+});
+```
+
+## Pattern: Keeping the SW Alive (When Necessary)
+
+Occasionally you need the SW alive for a long-running operation. Use one of:
+
+1. **chrome.offscreen** — create an offscreen document for long tasks
+2. **Periodic storage writes** — each chrome.storage call resets the idle timer
+3. **Active port connections** — an open port keeps the SW alive
+
+```js
+// Port-based keepalive from popup/side panel
+const port = chrome.runtime.connect({ name: 'keepalive' });
+// The SW stays alive as long as this port is open
+```
+
+⚠️ Do NOT abuse keepalive patterns. Chrome may enforce stricter limits in future versions.
+
+## Pattern: Event Registration
+
+All event listeners MUST be registered synchronously at the top level of the service worker.
+Chrome replays events to a restarted SW, but only for listeners that were registered synchronously.
+
+```js
+// ✅ GOOD: Top-level registration
+chrome.runtime.onMessage.addListener(handleMessage);
+chrome.tabs.onUpdated.addListener(handleTabUpdate);
+chrome.webNavigation.onCompleted.addListener(handleNavigation);
+
+// ❌ BAD: Conditional or async registration
+async function setup() {
+  const { enabled } = await chrome.storage.local.get('enabled');
+  if (enabled) {
+    chrome.tabs.onUpdated.addListener(handleTabUpdate); // Too late!
+  }
+}
+setup();
+```
+
+Instead, register all listeners and check conditions inside them:
+
+```js
+chrome.tabs.onUpdated.addListener(async (tabId, changeInfo, tab) => {
+  const { enabled } = await chrome.storage.local.get('enabled');
+  if (!enabled) return;
+  // Process...
+});
+```
+
+## Date-Based Resets
+
+For daily counters, store the date alongside the count:
+
+```js
+function getToday() {
+  return new Date().toISOString().split('T')[0]; // "2025-01-15"
+}
+
+async function incrementDailyCount() {
+  const { dailyCount = 0, countDate = '' } = await chrome.storage.local.get(['dailyCount', 'countDate']);
+  const today = getToday();
+
+  if (countDate !== today) {
+    // New day — reset
+    await chrome.storage.local.set({ dailyCount: 1, countDate: today });
+    return 1;
+  } else {
+    const newCount = dailyCount + 1;
+    await chrome.storage.local.set({ dailyCount: newCount });
+    return newCount;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/side-panel.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/side-panel.md
new file mode 100644
index 00000000..5a1e5b76
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/side-panel.md
@@ -0,0 +1,147 @@
+# Side Panel
+
+## Setup
+
+Add to manifest.json:
+```json
+{
+  "permissions": ["sidePanel"],
+  "side_panel": {
+    "default_path": "sidepanel/sidepanel.html"
+  }
+}
+```
+
+## Opening the Side Panel — REQUIRED
+
+**A side panel definition alone does NOT make it openable.** You MUST provide an explicit
+trigger to open it. Without one of these, users have no way to access the panel:
+
+### Most common: Open on action icon click
+
+If the extension's primary function is the side panel, remove `default_popup` from the action
+and use `chrome.action.onClicked` to open the side panel:
+
+```js
+// service-worker.js
+chrome.action.onClicked.addListener(async (tab) => {
+  await chrome.sidePanel.open({ windowId: tab.windowId });
+});
+```
+
+⚠️ `chrome.action.onClicked` only fires when there is NO `default_popup` set. If you have both
+a popup and a side panel, open the side panel from the popup via a button, or use a different
+trigger.
+
+### Alternative triggers
+
+```js
+// Open from a context menu item
+chrome.contextMenus.onClicked.addListener(async (info, tab) => {
+  if (info.menuItemId === 'open-panel') {
+    await chrome.sidePanel.open({ windowId: tab.windowId });
+  }
+});
+
+// Open from a keyboard shortcut (defined in manifest commands)
+chrome.commands.onCommand.addListener(async (command) => {
+  if (command === 'open-side-panel') {
+    const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+    await chrome.sidePanel.open({ windowId: tab.windowId });
+  }
+});
+```
+
+You can also open it for a specific tab:
+```js
+await chrome.sidePanel.open({ tabId: tab.id });
+```
+
+### Simplest: Auto-open via setPanelBehavior
+
+If the side panel should open whenever the user clicks the extension icon, use `setPanelBehavior`
+as a one-liner instead of an `onClicked` listener:
+
+```js
+// service-worker.js
+chrome.sidePanel.setPanelBehavior({ openPanelOnActionClick: true });
+```
+
+⚠️ **The property is `openPanelOnActionClick` — NOT `openPanelOnActionIconClick`.**
+Using the wrong name causes a synchronous TypeError that silently aborts the service worker.
+
+When using `setPanelBehavior`, do NOT also define `default_popup` — the popup takes priority.
+
+## Setting Panel Per-Tab
+
+```js
+// Different side panel content for different tabs
+chrome.tabs.onUpdated.addListener(async (tabId, changeInfo, tab) => {
+  if (tab.url?.includes('github.com')) {
+    await chrome.sidePanel.setOptions({
+      tabId,
+      path: 'sidepanel/github-panel.html',
+      enabled: true
+    });
+  }
+});
+```
+
+## Communication with Side Panel
+
+The side panel is an extension page, so it can use all chrome.* APIs directly and communicate
+with the service worker via `chrome.runtime.sendMessage` / `chrome.runtime.onMessage`.
+
+To get data from the active tab's content script:
+
+```js
+// In side panel JS
+async function getPageContent() {
+  const [tab] = await chrome.tabs.query({ active: true, currentWindow: true });
+  const response = await chrome.tabs.sendMessage(tab.id, { type: 'GET_CONTENT' });
+  return response;
+}
+```
+
+Or use `chrome.scripting.executeScript` from the side panel (requires `scripting` and `activeTab` permissions):
+
+```js
+const [{ result }] = await chrome.scripting.executeScript({
+  target: { tabId: tab.id },
+  func: () => document.body.innerText
+});
+```
+
+## Side Panel vs Popup
+
+| Feature | Side Panel | Popup |
+|---------|-----------|-------|
+| Stays open | Yes | Closes when clicking away |
+| Resizable | Yes (by user) | Fixed size |
+| Coexists with page | Yes (side by side) | Overlays page |
+| Use when | Extended interaction, reading | Quick actions, settings |
+
+## Important Notes
+
+- The side panel shares a single instance per window — opening it replaces existing content
+- Use `chrome.sidePanel.setOptions({ enabled: false })` to disable for specific tabs
+- Side panel HTML files have full access to chrome.* APIs
+- The side panel persists across tab switches (per-window)
+
+### ⚠️ `activeTab` does NOT work from side panel interactions
+
+`activeTab` only grants tab access on direct user gestures: clicking the extension icon, context
+menu items, keyboard shortcuts, or omnibox suggestions. **Clicking a button inside a side panel
+does NOT activate `activeTab`.**
+
+If your side panel needs to read or modify page content (e.g., a "Summarize" button), use
+`tabs` + `host_permissions` instead:
+
+```json
+{
+  "permissions": ["tabs", "scripting", "sidePanel"],
+  "host_permissions": ["<all_urls>"]
+}
+```
+
+Do NOT rely on `activeTab` for side panel functionality.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/storage.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/storage.md
new file mode 100644
index 00000000..0909440b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/storage.md
@@ -0,0 +1,65 @@
+# Chrome Storage API
+
+## Storage Areas
+
+| Area | Persists | Syncs | Quota | Use For |
+|------|----------|-------|-------|---------|
+| `chrome.storage.local` | Yes | No | 10 MB | Most extension data |
+| `chrome.storage.sync` | Yes | Yes (across devices) | 100 KB total, 8 KB/item | User preferences, small data |
+| `chrome.storage.session` | Until browser close | No | 10 MB | Ephemeral state, survives SW restart |
+
+Permission required: `"storage"`
+
+## Basic Operations
+
+```js
+// Set
+await chrome.storage.local.set({ key: 'value', count: 42, items: [1,2,3] });
+
+// Get (with defaults)
+const { key = 'default', count = 0 } = await chrome.storage.local.get(['key', 'count']);
+
+// Get all
+const allData = await chrome.storage.local.get(null);
+
+// Remove
+await chrome.storage.local.remove('key');
+await chrome.storage.local.remove(['key1', 'key2']);
+
+// Clear all
+await chrome.storage.local.clear();
+```
+
+## Change Listener (Works Across All Contexts)
+
+```js
+chrome.storage.onChanged.addListener((changes, areaName) => {
+  for (const [key, { oldValue, newValue }] of Object.entries(changes)) {
+    console.log(`${areaName}.${key}: ${oldValue} → ${newValue}`);
+  }
+});
+```
+
+## storage.sync Quotas
+
+Be aware of limits when using sync:
+- `QUOTA_BYTES_PER_ITEM`: 8,192 bytes per key-value pair
+- `MAX_ITEMS`: 512 items
+- `QUOTA_BYTES`: 102,400 bytes total
+- `MAX_WRITE_OPERATIONS_PER_HOUR`: 1,800
+- `MAX_WRITE_OPERATIONS_PER_MINUTE`: 120
+
+For large data, split across multiple keys or use `chrome.storage.local`.
+
+## storage.session Notes
+
+- Only available in MV3
+- Cleared when the browser closes (not just when SW terminates)
+- Accessible from service worker, popup, side panel, etc.
+- Good for: auth tokens, temporary caches, in-progress operations
+
+## Why Not localStorage?
+
+`localStorage` works in popup and extension pages but NOT in service workers.
+`chrome.storage` works everywhere and supports the cross-context change listener.
+Always prefer `chrome.storage`.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/tab-management.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/tab-management.md
new file mode 100644
index 00000000..c86855a3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/tab-management.md
@@ -0,0 +1,132 @@
+# Tab Management & Groups
+
+## Permissions
+
+```json
+{
+  "permissions": ["tabs", "tabGroups"]
+}
+```
+
+Note: `tabs` permission gives access to `url`, `title`, `favIconUrl` on Tab objects.
+Without it, you can still use `chrome.tabs` but won't see sensitive tab properties.
+
+## Querying Tabs
+
+```js
+// All tabs
+const allTabs = await chrome.tabs.query({});
+
+// Active tab in current window
+const [activeTab] = await chrome.tabs.query({ active: true, currentWindow: true });
+
+// Tabs matching a URL pattern
+const gmailTabs = await chrome.tabs.query({ url: '*://mail.google.com/*' });
+```
+
+## Tab Operations
+
+```js
+// Create
+const tab = await chrome.tabs.create({ url: 'https://example.com', active: true });
+
+// Update
+await chrome.tabs.update(tabId, { url: 'https://new-url.com', pinned: true });
+
+// Close
+await chrome.tabs.remove(tabId);
+await chrome.tabs.remove([tabId1, tabId2]); // Multiple
+
+// Move
+await chrome.tabs.move(tabId, { index: 0 }); // Move to first position
+
+// Reload
+await chrome.tabs.reload(tabId);
+```
+
+## Tab Groups
+
+```js
+// Create a group from tabs
+const groupId = await chrome.tabs.group({ tabIds: [tabId1, tabId2] });
+
+// Customize the group
+await chrome.tabGroups.update(groupId, {
+  title: 'Work',
+  color: 'blue',     // grey, blue, red, yellow, green, pink, purple, cyan, orange
+  collapsed: false
+});
+
+// Move tab into existing group
+await chrome.tabs.group({ tabIds: [newTabId], groupId: existingGroupId });
+
+// Ungroup
+await chrome.tabs.ungroup(tabId);
+```
+
+## Grouping by Domain
+
+```js
+async function groupByDomain() {
+  const tabs = await chrome.tabs.query({ currentWindow: true });
+  const byDomain = {};
+
+  for (const tab of tabs) {
+    try {
+      const domain = new URL(tab.url).hostname;
+      (byDomain[domain] ??= []).push(tab.id);
+    } catch { /* ignore tabs without URLs */ }
+  }
+
+  for (const [domain, tabIds] of Object.entries(byDomain)) {
+    if (tabIds.length > 1) {
+      const groupId = await chrome.tabs.group({ tabIds });
+      await chrome.tabGroups.update(groupId, {
+        title: domain.replace('www.', ''),
+        color: 'blue'
+      });
+    }
+  }
+}
+```
+
+## Events
+
+```js
+chrome.tabs.onCreated.addListener((tab) => { /* new tab */ });
+chrome.tabs.onUpdated.addListener((tabId, changeInfo, tab) => { /* tab changed */ });
+chrome.tabs.onRemoved.addListener((tabId, removeInfo) => { /* tab closed */ });
+chrome.tabs.onActivated.addListener(({ tabId, windowId }) => { /* tab focused */ });
+chrome.tabGroups.onUpdated.addListener((group) => { /* group changed */ });
+```
+
+## Windows
+
+⚠️ **`chrome.windows` has NO `.query()` method.** Unlike `chrome.tabs.query()`, there is no
+`chrome.windows.query()`. Use the correct method for your need:
+
+```js
+// ❌ BROKEN
+const windows = await chrome.windows.query({ focused: true });
+// TypeError: chrome.windows.query is not a function
+
+// ✅ CORRECT
+const focused = await chrome.windows.getLastFocused({ populate: true }); // includes tabs array
+const current = await chrome.windows.getCurrent({ populate: true });
+const all     = await chrome.windows.getAll({ populate: true });
+const single  = await chrome.windows.get(windowId, { populate: true });
+```
+
+Full API: `getAll`, `getLastFocused`, `getCurrent`, `get(windowId)`, `create`, `update`, `remove`.
+Pass `{ populate: true }` to include the `tabs` array on the returned window object.
+
+```js
+// Create a new window with specific tabs
+const win = await chrome.windows.create({ url: 'https://example.com', focused: true });
+
+// Move current window to a specific position/size
+await chrome.windows.update(windowId, { left: 0, top: 0, width: 800, height: 600 });
+
+// Minimise / maximise
+await chrome.windows.update(windowId, { state: 'minimized' }); // 'normal' | 'minimized' | 'maximized' | 'fullscreen'
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/user-scripts.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/user-scripts.md
new file mode 100644
index 00000000..ec9dff89
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/extensions/user-scripts.md
@@ -0,0 +1,273 @@
+# User Scripts API
+
+The `chrome.userScripts` API lets extensions run **arbitrary code provided by the user** at
+runtime — code that cannot be shipped as part of the extension package. This is fundamentally
+different from content scripts (which are bundled with the extension) and `chrome.scripting`
+(which executes extension-owned code programmatically).
+
+**Use userScripts when:** you are building a script manager, custom automation tool, or any
+feature where the user supplies JavaScript that should run on web pages.  
+**Use content scripts when:** the injected code is written by you and ships with the extension.  
+**Use `chrome.scripting.executeScript` when:** you need one-off execution of known, extension-owned code.
+
+## Manifest
+
+```json
+{
+  "manifest_version": 3,
+  "minimum_chrome_version": "120",
+  "permissions": ["userScripts"],
+  "host_permissions": ["https://example.com/*"]
+}
+```
+
+- `"userScripts"` permission is required — without it `chrome.userScripts` is undefined.
+- `host_permissions` must cover the sites where scripts will be injected.
+
+## User Enablement — CRITICAL
+
+**The `chrome.userScripts` API requires explicit user opt-in. Without it, the API throws on
+property access.** Behavior differs by Chrome version:
+
+| Chrome version | Requirement |
+|----------------|-------------|
+| < 138 | User must enable **Developer mode** at `chrome://extensions` |
+| ≥ 138 | User must toggle **"Allow User Scripts"** on the extension's details page |
+
+```js
+// ❌ BROKEN — crashes if user hasn't enabled the API
+await chrome.userScripts.register([{ id: 'foo', matches: [...], js: [...] }]);
+// TypeError: Cannot read properties of undefined
+
+// ✅ CORRECT — always guard before any chrome.userScripts.* call
+function isUserScriptsAvailable() {
+  try {
+    chrome.userScripts; // throws if not enabled
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+if (!isUserScriptsAvailable()) {
+  document.getElementById('warning').style.display = 'block';
+  document.getElementById('main-ui').style.display = 'none';
+  return;
+}
+```
+
+## Execution Worlds
+
+| World | Constant | Behavior |
+|-------|----------|----------|
+| **USER_SCRIPT** (default) | `ExecutionWorld.USER_SCRIPT` | Isolated from host page JS; exempt from page CSP |
+| **MAIN** | `ExecutionWorld.MAIN` | Shares JS context with the host page; can access page variables |
+
+Use `USER_SCRIPT` (the default) for safety. Use `MAIN` only when the user's script explicitly
+needs to interact with the host page's JavaScript environment.
+
+Chrome 133+ supports multiple isolated worlds via `worldId`, letting different user scripts
+run in separate execution environments without interfering with each other.
+
+## Registering Scripts (Persistent)
+
+`register()` / `update()` / `getScripts()` / `unregister()` manage scripts that persist across
+page loads and browser sessions. Registered scripts survive the service worker being terminated.
+
+```js
+// ❌ BROKEN — both code and file specified (ScriptSource must have exactly one)
+await chrome.userScripts.register([{
+  id: 'my-script',
+  matches: ['https://example.com/*'],
+  js: [{ code: 'alert(1)', file: 'user-script.js' }] // Error: specify code OR file, not both
+}]);
+
+// ❌ BROKEN — id starts with underscore (reserved prefix)
+await chrome.userScripts.register([{ id: '_my-script', ... }]);
+// Error: User script IDs must not start with '_'
+
+// ✅ CORRECT — register from a file bundled with the extension
+await chrome.userScripts.register([{
+  id: 'my-user-script',
+  matches: ['https://example.com/*'],
+  js: [{ file: 'user-script.js' }],
+  runAt: 'document_idle'  // optional, this is the default
+}]);
+
+// ✅ CORRECT — register inline code supplied by the user
+await chrome.userScripts.register([{
+  id: 'my-user-script',
+  matches: ['https://example.com/*'],
+  js: [{ code: userProvidedCode }]
+}]);
+```
+
+Always check before calling `register()` vs `update()` — registering an already-existing ID
+throws an error:
+
+```js
+const existing = await chrome.userScripts.getScripts({ ids: ['my-user-script'] });
+if (existing.length > 0) {
+  await chrome.userScripts.update([{ id: 'my-user-script', js: [{ code: updatedCode }] }]);
+} else {
+  await chrome.userScripts.register([{
+    id: 'my-user-script',
+    matches: ['https://example.com/*'],
+    js: [{ code: userProvidedCode }]
+  }]);
+}
+
+// Remove a specific script
+await chrome.userScripts.unregister({ ids: ['my-user-script'] });
+
+// Remove all registered user scripts
+await chrome.userScripts.unregister();
+```
+
+## Persistence: Restore on Extension Update
+
+**Registered user scripts are cleared when the extension updates.**
+
+```js
+// ❌ BROKEN — scripts registered once at install time are lost on every update
+chrome.runtime.onInstalled.addListener(({ reason }) => {
+  if (reason === 'install') {
+    chrome.userScripts.register([{ id: 'foo', matches: [...], js: [...] }]);
+    // After the next extension update, 'foo' is gone — no re-registration
+  }
+});
+
+// ✅ CORRECT — persist configs in storage, restore on both install and update
+chrome.runtime.onInstalled.addListener(async ({ reason }) => {
+  if (reason === chrome.runtime.OnInstalledReason.UPDATE) {
+    const { scripts = {} } = await chrome.storage.local.get('scripts');
+    for (const s of Object.values(scripts)) {
+      await chrome.userScripts.register([s]).catch(() => {});
+    }
+  }
+});
+```
+
+Save the full script config (id, matches, js) to `chrome.storage` whenever the user saves
+a script, so it can be restored after an update.
+
+## One-Off Injection (Chrome 135+)
+
+`execute()` injects a script immediately into a specific tab/frame without registering it. It
+does not persist across page loads.
+
+```js
+// Requires Chrome 135+
+const results = await chrome.userScripts.execute({
+  target: { tabId: tabId },
+  js: [{ code: userProvidedCode }],
+  world: 'USER_SCRIPT'  // optional, default
+});
+
+for (const result of results) {
+  if (result.error) {
+    console.error('Injection failed in frame', result.frameId, result.error);
+  } else {
+    console.log('Result from frame', result.frameId, result.result);
+  }
+}
+```
+
+Guard for Chrome 135+ availability:
+
+```js
+if (typeof chrome.userScripts.execute === 'function') {
+  await chrome.userScripts.execute({ ... });
+} else {
+  // Fall back to register-based approach
+}
+```
+
+## Messaging from User Scripts
+
+User scripts run in the `USER_SCRIPT` world which has no access to `chrome.runtime` by
+default. Messaging requires an explicit opt-in.
+
+```js
+// ❌ BROKEN — messaging not enabled; chrome.runtime is undefined in the user script
+// sw.js
+chrome.runtime.onMessage.addListener((msg) => { ... }); // Never fires from user scripts
+
+// user script code (running in the page)
+chrome.runtime.sendMessage({ type: 'hello' }); // TypeError: chrome is not defined
+
+// ✅ CORRECT — opt in first, then use the dedicated listener
+// sw.js (run once, e.g. on install)
+await chrome.userScripts.configureWorld({ messaging: true });
+
+// sw.js — listen on the dedicated handler, not onMessage
+chrome.runtime.onUserScriptMessage.addListener((message, sender, sendResponse) => {
+  sendResponse({ ok: true });
+  return true; // keep channel open for async responses
+});
+
+// user script code — chrome.runtime is now available
+chrome.runtime.sendMessage({ type: 'FROM_USER_SCRIPT', data: 42 });
+```
+
+For long-lived connections use `chrome.runtime.onUserScriptConnect` (analogous to
+`runtime.onConnect` for content scripts).
+
+Chrome 133+ supports per-world messaging with `worldId`:
+
+```js
+await chrome.userScripts.configureWorld({ worldId: 'my-world', messaging: true });
+```
+
+## `configureWorld()` — CSP and Messaging
+
+```js
+await chrome.userScripts.configureWorld({
+  csp: "script-src 'self'",  // custom CSP for the world
+  messaging: true             // enable chrome.runtime messaging
+});
+
+// Chrome 133+: configure a named world
+await chrome.userScripts.configureWorld({
+  worldId: 'my-world',
+  messaging: true
+});
+
+// Chrome 133+: reset a world's configuration
+await chrome.userScripts.resetWorldConfiguration('my-world');
+
+// Chrome 133+: list all world configurations
+const configs = await chrome.userScripts.getWorldConfigurations();
+```
+
+## Complete Script Manager Pattern
+
+```js
+// options.js — save user's script and (re)register it
+async function saveScript(id, matches, code) {
+  // Persist the config so we can restore it after extension updates
+  const { scripts = {} } = await chrome.storage.local.get('scripts');
+  scripts[id] = { id, matches, js: [{ code }] };
+  await chrome.storage.local.set({ scripts });
+
+  // Register or update the live script
+  const existing = await chrome.userScripts.getScripts({ ids: [id] });
+  if (existing.length > 0) {
+    await chrome.userScripts.update([{ id, matches, js: [{ code }] }]);
+  } else {
+    await chrome.userScripts.register([{ id, matches, js: [{ code }] }]);
+  }
+}
+```
+
+## Key Differences from Content Scripts
+
+| | Content Scripts | userScripts |
+|--|-----------------|-------------|
+| Code source | Bundled with extension | Provided by user at runtime |
+| Persistence | Automatic (manifest) | Manual (register + restore on update) |
+| Arbitrary code | No | Yes |
+| User opt-in | No | Yes (Developer Mode / Allow User Scripts) |
+| Messaging | `runtime.sendMessage` | `runtime.onUserScriptMessage` (after `configureWorld`) |
+| CSP exemption | Yes | Yes (USER_SCRIPT world) |
+| Multiple worlds | No | Yes (Chrome 133+ with `worldId`) |
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/chromewebstore-template.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/chromewebstore-template.md
new file mode 100644
index 00000000..976e9a57
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/chromewebstore-template.md
@@ -0,0 +1,178 @@
+# CHROMEWEBSTORE.md Template
+
+Copy this template into the project root as `CHROMEWEBSTORE.md` and fill in each section.
+Fields marked `[REQUIRED]` must be completed before submission. Fields marked `[RECOMMENDED]`
+are optional but improve listing quality and approval odds.
+
+---
+
+```markdown
+# Chrome Web Store Listing — [Extension Name]
+
+> Last Updated: YYYY-MM-DD
+
+## Store Listing
+
+**Extension Name** [REQUIRED]
+<!-- Must match manifest.json "name". Max 75 characters. -->
+
+
+**Short Description** [REQUIRED]
+<!-- Max 132 characters. Shown in search results and tiles. Be specific about function. -->
+
+
+**Detailed Description** [REQUIRED]
+<!-- Max 16,000 characters. Structure recommendation:
+     Line 1: One-sentence summary of what the extension does
+     Paragraph 2: Key features (use line breaks, not bullet points — CWS strips markdown)
+     Paragraph 3: How to use it (step-by-step)
+     Paragraph 4: Privacy/permissions note (builds trust)
+     Paragraph 5: Support/feedback info
+
+     WRITE FROM A USER'S PERSPECTIVE — what the extension does FOR them, not HOW it works.
+     Never mention implementation details: APIs used, libraries, frameworks, code patterns.
+
+     ❌ "Uses a MutationObserver and custom elements to track page changes"
+     ✅ "Automatically detects new content as you scroll"
+
+     ❌ "Powered by a service worker for background processing"
+     ✅ "Runs quietly in the background without slowing your browser"
+
+     ❌ "Implements declarativeNetRequest for network filtering"
+     ✅ "Blocks ads and trackers without reading your page content"
+-->
+
+
+**Category** [REQUIRED]
+<!-- Pick one: Accessibility, Blogging, Developer Tools, Fun, News & Weather,
+     Photos, Productivity, Search Tools, Shopping, Social & Communication, Sports -->
+
+
+**Single Purpose** [REQUIRED]
+<!-- One sentence. Narrow and easy to understand.
+     Good: "Highlights and saves text selections on web pages"
+     Bad:  "Productivity tool that helps you work better" -->
+
+
+**Primary Language** [REQUIRED]
+<!-- e.g., English, German, etc. -->
+
+
+## Graphics & Assets
+
+| Asset | Dimensions | Status | Filename |
+|-------|-----------|--------|----------|
+| Store Icon [REQUIRED] | 128×128 PNG | ⬜ Not created | |
+| Screenshot 1 [REQUIRED] | 1280×800 or 640×400 | ⬜ Not created | |
+| Screenshot 2 [RECOMMENDED] | 1280×800 or 640×400 | ⬜ Not created | |
+| Screenshot 3 [RECOMMENDED] | 1280×800 or 640×400 | ⬜ Not created | |
+| Screenshot 4 | 1280×800 or 640×400 | ⬜ Not created | |
+| Screenshot 5 | 1280×800 or 640×400 | ⬜ Not created | |
+| Small Promo Tile [RECOMMENDED] | 440×280 | ⬜ Not created | |
+| Marquee Promo Tile | 1400×560 | ⬜ Not created | |
+
+<!-- Status options: ⬜ Not created | 🟡 Needs update | ✅ Ready -->
+
+### Screenshot Notes
+<!-- Describe what each screenshot should show. Good screenshots demonstrate the extension
+     in action, not just the popup. Include annotations if helpful. -->
+
+
+## Permissions Justification
+
+<!-- Every permission in manifest.json needs a justification. The review team reads these.
+     Be specific about WHY the permission is needed and WHAT user-facing feature uses it.
+     "Required for functionality" will be rejected. -->
+
+| Permission | Type | Justification |
+|------------|------|---------------|
+| | permissions | |
+| | host_permissions | |
+
+<!-- Type is either "permissions" or "host_permissions" -->
+
+
+## Privacy & Data Use
+
+<!-- These map to the CWS data use disclosure form. Be exhaustive and accurate —
+     mismatches between what you declare and what the code does cause rejection. -->
+
+### Data Collection
+
+**Does the extension collect user data?** Yes / No
+
+<!-- If Yes, fill in the table below. If No, skip to the certification. -->
+
+| Data Type | Collected? | Transmitted Off-Device? | Purpose | Shared with Third Parties? |
+|-----------|-----------|------------------------|---------|---------------------------|
+| Personally identifiable info | | | | |
+| Health info | | | | |
+| Financial info | | | | |
+| Authentication info | | | | |
+| Personal communications | | | | |
+| Location | | | | |
+| Web history | | | | |
+| User activity | | | | |
+| Website content | | | | |
+
+### Data Use Certification
+<!-- Check all that apply: -->
+- [ ] Data is NOT sold to third parties
+- [ ] Data is NOT used for purposes unrelated to the extension's core functionality
+- [ ] Data is NOT used for creditworthiness or lending purposes
+
+
+## Privacy Policy
+
+**Privacy Policy URL** [REQUIRED]
+
+<!-- Host this at a publicly accessible URL. GitHub Pages, your website, or a
+     Notion page all work. See references/webstore/privacy-policy.md for a template. -->
+
+
+## Distribution
+
+**Visibility**: Public / Unlisted / Private
+**Regions**: All regions / [List specific regions]
+
+## Developer Info
+
+**Publisher Name** [REQUIRED]
+
+**Contact Email** [REQUIRED]
+<!-- Displayed publicly on the store listing. -->
+
+**Support URL / Email** [RECOMMENDED]
+<!-- Where users go for help. Can be a GitHub Issues page, email, or support site. -->
+
+**Homepage URL** [RECOMMENDED]
+
+
+## Version History
+
+<!-- Add an entry for every version submitted to the Chrome Web Store.
+     Most recent first. -->
+
+| Version | Date | Changes | Status |
+|---------|------|---------|--------|
+| | | | Draft |
+
+<!-- Status options: Draft | Submitted | In Review | Published | Rejected -->
+
+
+## Review Notes
+
+<!-- Track rejection reasons, communication with the review team, and fixes applied.
+     This section is for your records, not published to the store. -->
+
+### Known Issues / Limitations
+<!-- Document anything reviewers might flag or users should know about. -->
+
+
+### Rejection History
+<!-- If applicable:
+| Date | Reason | Fix Applied | Resubmitted |
+|------|--------|-------------|-------------|
+-->
+
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/privacy-policy.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/privacy-policy.md
new file mode 100644
index 00000000..77153760
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/privacy-policy.md
@@ -0,0 +1,128 @@
+# Privacy Policy Guidance
+
+## When is a Privacy Policy Required?
+
+A privacy policy URL is **required** if your extension:
+- Handles personal or sensitive user data (as defined by CWS policies)
+- Uses any of these permissions: `identity`, `cookies`, `webRequest`, `browsingData`,
+  `history`, `bookmarks`, `topSites`, `<all_urls>` host permission
+- Collects any form of analytics or telemetry
+- Transmits any data off the user's device
+
+A privacy policy is **recommended** for all extensions, even if no data is collected.
+It demonstrates professionalism and can prevent delays if a reviewer flags your extension.
+
+## Where to Host It
+
+The privacy policy must be at a publicly accessible URL. Options:
+- **GitHub Pages**: Free, version-controlled. Create a `privacy.md` in a `docs/` branch.
+- **GitHub Gist**: Quick and dirty. Create a public gist and link to the raw URL.
+- **Project website**: If you have one, add a `/privacy` page.
+- **Notion / Google Sites**: Free hosted pages. Stable URLs.
+
+Avoid hosting on a URL that might go down or change. The CWS review team checks the link.
+
+## What to Include
+
+### Minimal Policy (No Data Collection)
+
+If your extension genuinely collects no data, the policy can be short:
+
+```
+Privacy Policy for [Extension Name]
+
+Last updated: [Date]
+
+[Extension Name] does not collect, store, or transmit any personal data or
+browsing information. All data stays on your device.
+
+This extension does not use cookies, analytics, or third-party services.
+
+If you have questions, contact [email].
+```
+
+### Standard Policy (Some Data Collection)
+
+If your extension stores or transmits data, cover these topics:
+
+1. **What data is collected** — Be specific. "User preferences" is not enough.
+   Say "Your selected theme preference (light/dark) and saved highlight colors."
+
+2. **How data is stored** — Local storage only? Synced via chrome.storage.sync?
+   Sent to a server?
+
+3. **Why data is collected** — Tie each data type to a specific feature.
+
+4. **Third-party services** — If you use any APIs (analytics, auth, etc.), name them
+   and link to their privacy policies.
+
+5. **Data sharing** — State whether data is shared with third parties. If yes, with
+   whom and why. If no, say so explicitly.
+
+6. **Data retention** — How long is data kept? Can the user delete it?
+
+7. **User controls** — How can users access, export, or delete their data?
+   If the extension has a "clear data" button, mention it.
+
+8. **Changes to the policy** — State that you'll update the policy if practices change
+   and how users will be notified.
+
+9. **Contact** — Email or URL for privacy questions.
+
+### Template
+
+```
+Privacy Policy for [Extension Name]
+
+Last updated: [Date]
+
+## What Data We Collect
+
+[Describe each type of data collected and the feature that requires it.]
+
+## How Data Is Stored
+
+[Describe storage mechanism — local only, synced, or server-side.]
+
+## How Data Is Used
+
+[Describe each use case. Tie to specific features.]
+
+## Third-Party Services
+
+[List any third-party services used. Link to their privacy policies.
+If none, state "This extension does not use any third-party services."]
+
+## Data Sharing
+
+[State whether data is shared. If yes, with whom and why.]
+
+## Data Retention and Deletion
+
+[How long data is kept. How users can delete it.]
+
+## Changes to This Policy
+
+[How and when the policy may be updated. How users will be notified.]
+
+## Contact
+
+[Email or support URL for privacy inquiries.]
+```
+
+## Common Mistakes
+
+- **Policy doesn't match the data disclosure form**: The CWS data disclosure form and your
+  privacy policy must be consistent. If the form says "no data collected" but the policy
+  mentions analytics, you'll be rejected.
+
+- **Policy is too vague**: "We may collect some data" is not acceptable. Be specific.
+
+- **Dead link**: If your privacy policy URL returns a 404, the submission is auto-rejected.
+  Verify the link before submitting.
+
+- **Missing data types**: If your extension uses `chrome.storage.sync`, that data goes to
+  Google's servers — disclose this. If you make any `fetch()` calls, disclose what's sent.
+
+- **No contact information**: The CWS requires a way for users to reach you about privacy
+  concerns. Include an email address at minimum.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/review-checklist.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/review-checklist.md
new file mode 100644
index 00000000..0ad374a3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/review-checklist.md
@@ -0,0 +1,145 @@
+# Pre-Publish Review Checklist
+
+Run through this checklist before every submission to the Chrome Web Store. Each item
+corresponds to a common rejection reason or publishing failure.
+
+## Manifest & Package
+
+- [ ] **manifest_version is 3** — Manifest V2 is no longer accepted for new submissions.
+- [ ] **Version bumped** — CWS rejects uploads with a version ≤ the currently published
+      version. Use semver: bump patch for fixes, minor for features, major for breaking
+      changes.
+- [ ] **Name matches CHROMEWEBSTORE.md** — The `name` field in manifest.json must exactly
+      match what you put in the store listing.
+- [ ] **Description in manifest ≤ 132 chars** — This is the short description shown in
+      chrome://extensions. It should match or be close to your CWS short description.
+- [ ] **No unnecessary files in ZIP** — Exclude: `.git/`, `node_modules/`, `.env`,
+      `*.map`, test files, build configs, `CHROMEWEBSTORE.md` itself, `README.md`,
+      `.DS_Store`, `thumbs.db`. Use a build script or `.cws-ignore`-style exclusion.
+- [ ] **ZIP under 2GB** — Maximum package size. Most extensions should be under 10MB.
+- [ ] **No absolute file paths** — All paths in manifest.json must be relative.
+
+## Permissions
+
+- [ ] **Minimum permissions** — Only request what you need. `<all_urls>` is a red flag.
+      Use specific host_permissions like `*://*.example.com/*` when possible.
+- [ ] **Every permission justified** — Check the Permissions Justification section in
+      CHROMEWEBSTORE.md. The CWS dashboard has a field for each permission — you'll need
+      to fill these in during submission.
+- [ ] **activeTab preferred over tabs + <all_urls>** — If you only need access to the
+      current tab when the user clicks your icon, `activeTab` is the right permission.
+- [ ] **No unused permissions** — If you removed a feature that used a permission, remove
+      the permission from manifest.json too. Leftover permissions cause rejection.
+- [ ] **host_permissions justified** — Explain which features need access to which domains
+      and why.
+
+## Store Listing Content
+
+- [ ] **Detailed description is specific** — Describes exactly what the extension does.
+      No vague marketing language. The review team reads this.
+- [ ] **Single purpose is narrow** — One sentence that clearly states the primary function.
+      "Manages bookmarks into categorized folders" not "Productivity enhancement tool."
+- [ ] **No misleading claims** — Don't claim features you don't have. Don't exaggerate
+      performance claims.
+- [ ] **No keyword stuffing** — Don't repeat keywords unnaturally in the description.
+- [ ] **No trademark violations** — Don't use other companies' names, logos, or trademarks
+      in your extension name, description, or screenshots unless you have authorization.
+- [ ] **Contact email is valid** — The email shown on the listing must be monitored. Google
+      sends important notifications (takedowns, policy changes) to this address.
+
+## Graphics
+
+- [ ] **Store icon**: 128×128 PNG, no transparency issues, readable at small sizes.
+- [ ] **At least 1 screenshot**: 1280×800 or 640×400 pixels. Shows the extension in action.
+- [ ] **Screenshots are current** — Match the current version of the extension UI. Outdated
+      screenshots can trigger rejection.
+- [ ] **No misleading screenshots** — Screenshots must accurately represent the extension.
+- [ ] **No phone/tablet mockups** — Unless the extension actually works on those devices.
+- [ ] **Small promo tile** (recommended): 440×280 PNG or JPEG. Used for featured placements.
+
+## Privacy & Compliance
+
+- [ ] **Data disclosure form matches reality** — The CWS data use disclosure checkboxes
+      must accurately reflect what the extension code actually does. Mismatch = rejection.
+- [ ] **Privacy policy URL is live** — Visit the URL yourself. Confirm it loads and
+      contains an actual privacy policy, not a 404 or placeholder.
+- [ ] **Privacy policy matches disclosure** — The text of the policy must be consistent
+      with what you declared in the disclosure form.
+- [ ] **chrome.storage.sync disclosed** — If you use `chrome.storage.sync`, data is
+      transmitted to Google's servers. This counts as off-device transmission.
+- [ ] **Remote code prohibition** — Extensions cannot execute remotely hosted code.
+      All JS must be bundled in the extension package. No loading scripts from CDNs
+      at runtime (Manifest V3 enforces this, but verify).
+- [ ] **No obfuscated code** — Minification is fine. Obfuscation (intentionally making
+      code unreadable) is prohibited and will cause rejection.
+
+## Functionality
+
+- [ ] **Extension works** — Load it unpacked in Chrome, test all features. Check the
+      console for errors.
+- [ ] **No crashes or blank popups** — Test popup, side panel, options page, content
+      scripts. All should load without errors.
+- [ ] **Works on intended sites** — If the extension targets specific websites, verify
+      it works on current versions of those sites.
+- [ ] **Graceful degradation** — The extension should handle edge cases (no internet,
+      empty data, restricted pages like chrome:// URLs) without crashing.
+- [ ] **Uninstall is clean** — No persistent side effects after the extension is removed.
+- [ ] **No excessive resource use** — The extension shouldn't noticeably slow down
+      browsing. Content scripts in particular should be lightweight.
+
+## Updates (for existing extensions)
+
+- [ ] **CHROMEWEBSTORE.md version history updated** — New entry with version, date, and
+      summary of changes.
+- [ ] **Last Updated date bumped** — If any user-facing changes were made.
+- [ ] **Feature list in descriptions updated** — If new features were added.
+- [ ] **Permissions justification updated** — If manifest.json permissions changed.
+- [ ] **Screenshots refreshed** — If the UI changed significantly.
+- [ ] **Privacy disclosures updated** — If data practices changed.
+
+## Packaging Script
+
+To create a clean ZIP for submission, use a script like:
+
+```bash
+#!/bin/bash
+# package-extension.sh — Creates a clean ZIP for Chrome Web Store submission
+
+EXTENSION_NAME="my-extension"
+VERSION=$(node -p "require('./manifest.json').version")
+OUTPUT="${EXTENSION_NAME}-v${VERSION}.zip"
+
+# Remove old package
+rm -f "$OUTPUT"
+
+# Create ZIP excluding dev files
+zip -r "$OUTPUT" . \
+  -x ".git/*" \
+  -x "node_modules/*" \
+  -x ".env" \
+  -x "*.map" \
+  -x "tests/*" \
+  -x "__tests__/*" \
+  -x "*.test.*" \
+  -x "*.spec.*" \
+  -x ".eslintrc*" \
+  -x ".prettierrc*" \
+  -x "tsconfig.json" \
+  -x "package.json" \
+  -x "package-lock.json" \
+  -x "webpack.config.*" \
+  -x "vite.config.*" \
+  -x "rollup.config.*" \
+  -x "CHROMEWEBSTORE.md" \
+  -x "README.md" \
+  -x "CHANGELOG.md" \
+  -x ".DS_Store" \
+  -x "Thumbs.db" \
+  -x "*.sh" \
+  -x "store-assets/*"
+
+echo "Packaged: $OUTPUT ($(du -h "$OUTPUT" | cut -f1))"
+```
+
+Customize the exclusion list for your project. The key principle: ship only what Chrome
+needs to run the extension.
diff --git a/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/store-listing.md b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/store-listing.md
new file mode 100644
index 00000000..46c75037
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/chrome-extensions/references/webstore/store-listing.md
@@ -0,0 +1,201 @@
+# Store Listing Tips & Common Rejections
+
+## Writing Effective Descriptions
+
+### Short Description (132 chars max)
+
+This appears in search results and category pages. It's your elevator pitch. Rules:
+
+- Start with a verb or the extension's function: "Blocks ads on all websites" not "Ad blocker"
+- Be specific: "Translates selected text into 50+ languages" not "Translation tool"
+- Include the primary keyword naturally
+- Don't waste characters on "Chrome extension" — the user already knows
+
+**Good examples:**
+- "Save articles to read later with one click. Works offline."
+- "Replace new tab with a minimal dashboard showing weather and tasks"
+- "Highlight and annotate text on any webpage. Export notes as Markdown."
+
+**Bad examples:**
+- "The best productivity tool for Chrome!" (vague, marketing-speak)
+- "Extension for helping you do things better" (says nothing)
+- "NEW! Amazing tab manager extension tool app for Chrome browser" (keyword stuffing)
+
+### Detailed Description (16,000 chars max)
+
+The CWS strips all markdown formatting. Use plain text with line breaks. Structure:
+
+```
+[One sentence: what does this extension do?]
+
+FEATURES
+• Feature 1 — brief explanation
+• Feature 2 — brief explanation
+• Feature 3 — brief explanation
+
+HOW TO USE
+1. Click the extension icon in the toolbar
+2. [Next step]
+3. [Next step]
+
+PRIVACY
+This extension does not collect any personal data. Your [data type] is stored
+locally on your device and never transmitted to any server.
+
+PERMISSIONS
+• "Read and change data on sites you visit" — needed to [specific feature].
+  The extension only activates when you [trigger action].
+
+SUPPORT
+Found a bug? Have a suggestion? Email [email] or open an issue at [URL].
+
+Version [X.Y.Z] — [Brief changelog for latest version]
+```
+
+### The Implementation-Detail Rule
+
+**Never describe how the extension is built.** Potential users are not developers evaluating your stack — they want to know what the extension does for them.
+
+Strip all of the following from every piece of copy:
+
+- Web API names: `MutationObserver`, `IntersectionObserver`, `Service Worker`, `Shadow DOM`, `IndexedDB`, `WebSockets`
+- Chrome API names: `chrome.storage`, `declarativeNetRequest`, `chrome.scripting`, `offscreen document`
+- Framework/library names: React, custom elements, Lit, Webpack, TypeScript
+- Architecture descriptions: "background processing", "event-driven", "declarative"
+
+**Transform every implementation sentence into a user benefit:**
+
+| Before (implementation) | After (user benefit) |
+|-------------------------|----------------------|
+| "Uses a MutationObserver to detect page changes" | "Automatically detects new content as you browse" |
+| "Built with custom elements and Shadow DOM" | "Works seamlessly without affecting page styles" |
+| "Powered by a service worker" | "Runs quietly in the background" |
+| "Your settings are synced via chrome.storage.sync" | "Your settings sync across all your devices" |
+| "Implements declarativeNetRequest for filtering" | "Blocks ads and trackers without reading your page content" |
+
+### Why This Structure Works
+
+1. **One-sentence opener** — The reviewer and users both scan the first line. Make it count.
+2. **Features list** — Users scan for capabilities. Plain-text bullets (•) render well.
+3. **How to use** — Reduces support requests and proves the extension actually works.
+4. **Privacy section** — Pre-empts user concerns about permissions. Builds trust.
+5. **Permissions explanation** — Users see permission warnings during install. If you
+   explain them in the description, they're less likely to abort installation.
+6. **Support info** — Required by CWS policy ("meaningful customer support").
+7. **Latest version note** — Shows the extension is actively maintained.
+
+### Single Purpose Statement
+
+This is filled in the developer dashboard, not shown to users. The review team reads it
+carefully. It must be a single sentence that describes the extension's narrow purpose.
+
+**Approved examples:**
+- "Saves highlighted text from web pages to a local reading list"
+- "Replaces the new tab page with a customizable dashboard"
+- "Blocks cookie consent banners on websites"
+
+**Rejected examples:**
+- "Improves your browsing experience" (too vague)
+- "Productivity and organization tool" (too broad)
+- "Highlights text, saves bookmarks, manages tabs, and blocks ads" (not single purpose)
+
+If your extension does multiple things, focus on the primary function. The detailed
+description can cover secondary features.
+
+## Common Rejection Reasons
+
+### 1. Excessive Permissions
+
+**Symptom:** "Your extension requests more permissions than it needs."
+
+**Fix:**
+- Replace `<all_urls>` with specific host patterns
+- Replace `tabs` with `activeTab` if you only need the current tab on click
+- Remove permissions you're not using
+- Ensure every permission has a clear justification
+
+### 2. Missing or Inadequate Single Purpose
+
+**Symptom:** "Your item does not have a single, clear purpose."
+
+**Fix:**
+- Rewrite the single purpose field to be narrow and specific
+- If the extension truly does too many unrelated things, consider splitting it
+
+### 3. Misleading Description or Functionality
+
+**Symptom:** "Your extension does not provide the functionality described."
+
+**Fix:**
+- Ensure every feature listed in the description actually works
+- Remove claims about features you haven't built yet
+- Don't use superlatives ("the best", "the fastest") unless verifiable
+
+### 4. Privacy Policy Issues
+
+**Symptom:** "Your extension requires a privacy policy." or "Your privacy policy URL
+is not accessible."
+
+**Fix:**
+- Host the privacy policy at a stable, public URL
+- Ensure it's not behind a login wall
+- Make sure it covers all data the extension actually collects
+- Match the privacy policy with the data disclosure form
+
+### 5. Trademark Violation
+
+**Symptom:** "Your extension uses trademarked content without authorization."
+
+**Fix:**
+- Don't use other companies' names in your extension name (e.g., "YouTube Downloader")
+- Don't use logos or brand colors that imply affiliation
+- Use generic terms: "Video Downloader for [site]" might be fine, but check the site's terms
+
+### 6. Code Readability
+
+**Symptom:** "Your extension contains obfuscated code."
+
+**Fix:**
+- Minification is allowed; obfuscation is not
+- If using a bundler (webpack, rollup, vite), ensure source maps are NOT included but
+  the output is minified, not obfuscated
+- Don't use string encoding tricks to hide code intent
+
+### 7. Remote Code Execution
+
+**Symptom:** "Your extension executes remotely hosted code."
+
+**Fix:**
+- Bundle all JavaScript in the extension package
+- Don't load scripts from CDNs at runtime
+- Don't use `eval()` or `new Function()` with remote content
+- Fetching JSON data from APIs is fine; fetching and executing JS is not
+
+### 8. User Data Disclosure Mismatch
+
+**Symptom:** "Your extension's data usage does not match your disclosure."
+
+**Fix:**
+- Audit every `fetch()`, `XMLHttpRequest`, and `chrome.storage.sync` call
+- Remember that `chrome.storage.sync` transmits data to Google's servers
+- If you use any analytics library (even self-hosted), declare it
+- If you log errors to an external service, declare it
+
+## After Rejection
+
+When an extension is rejected:
+
+1. Read the rejection email carefully — it specifies which policy was violated
+2. Update CHROMEWEBSTORE.md with the rejection reason and fix
+3. Make the required changes to the extension code or listing
+4. Re-verify against the pre-publish checklist
+5. Resubmit through the developer dashboard
+6. Note: Repeated policy violations can result in account suspension
+
+## Review Timeline
+
+- First submission: typically 1–3 business days, can be longer
+- Updates to existing extensions: usually faster, often within 24 hours
+- Expedited review: not officially available; maintaining a clean track record helps
+- Deferred publishing: you can choose to publish manually after review passes,
+  giving you control over timing. Must publish within 30 days of approval.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/SKILL.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/SKILL.md
new file mode 100644
index 00000000..f4e0dbce
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/SKILL.md
@@ -0,0 +1,136 @@
+---
+name: modern-web-guidance
+description: |
+  Search tool for modern web development best practices. MANDATORY: Execute FIRST for all HTML/CSS and clientside JS tasks. Do NOT skip — web APIs evolve rapidly and training weights contain obsolete patterns.
+
+  Trigger immediately for:
+  - UI/Layout: Modals/dialogs/popovers, tables, dark mode, anchor positioning, container queries, `:has()`, etc.
+  - Scroll/Motion: View Transitions, Scroll-driven animations, parallax/reveals, etc.
+  - Performance: CWV (LCP, INP), content-visibility, Fetch Priority, image optimization, etc.
+  - System/APIs: Security, passkeys, HTML sanitization, Web Components, dates/timezones, Built-in AI, WebAssembly, etc.
+  - Frameworks: Standard HTML/CSS/DOM in React, Vue, Angular, etc.
+  - General Frontend: Forms, validation (`:user-valid`), autofill, accessibility, custom selects, scrollbars, etc.
+
+  DO NOT trigger for:
+  - Backend: SQL, ORMs, API routes, etc.
+  - Infra/Scripts: CI/CD, Docker, Actions, Python/Go, Git, etc.
+  - Tooling/Trivial: Vite, tsconfig, ESLint, tests, copy/renames, 3P docs, etc.
+---
+
+# Modern Web Guidance
+
+A skill to search for specific web development use cases and retrieve their corresponding best practice guides.
+
+## When to use
+
+Must use this skill:
+- At the **start** of implementing any web UI, CSS layout/animation, or client-side JS logic (dates/timezones, sanitization, performance, accessibility)—including when fixing UX symptoms (e.g., janky interactions, layout shifts).
+- Before creating or updating a component, to check if a standardized modern web pattern already exists.
+- To avoid implementing ad-hoc solutions or loading large dependencies unnecessarily.
+
+## Usage Instructions
+
+### Step 1. Search Use Cases
+
+Run `modern-web-guidance` directly with `npx` using a **2–5 word action-oriented query** for a **single web platform capability or UI pattern**:
+- **Keep queries focused and generic**: Describe the user-visible capability (`<verb> + <UI/platform object>`, optionally paired with the target HTML/CSS/JS feature name if known). Omit framework/library names (`React`, `Vue`, `Tailwind`, etc.) and app/domain nouns (product, route, or component/file names). Split multi-feature tasks into separate `search` calls.
+- **Example**: Search `"light dismiss dialog"` or `"responsive data table"`, **not** `"dialog"` (too terse), `"responsive table dark mode"` (compound — split into two searches), or `"close React settings modal on outside click"` (framework/app noise).
+
+```sh
+npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_10_16-6654652b
+```
+
+**Example Output**:
+```json
+[
+  {
+    "id": "optimize-image-priority",
+    "description": "Optimize the loading priority of Largest Contentful Paint (LCP) candidate images.",
+    "category": "performance",
+    "featuresUsed": [ "Fetch priority" ],
+    "tokenCount": 985,
+    "similarity": 0.7289
+  },
+  {
+    "id": "defer-rendering-heavy-content",
+    "description": "Reduce rendering times in content-heavy web pages by deferring rendering for offscreen content.",
+    "category": "performance",
+    "featuresUsed": [ "content-visibility", "hidden=\"until-found\"" ],
+    "tokenCount": 1250,
+    "similarity": 0.6961
+  }
+]
+```
+
+> **Note**: Judge results by their `description` fields (not raw `similarity` scores):
+> - **Match found**: Call `retrieve` directly—do not also run `list`.
+> - **No match on a web UI/CSS/DOM behavior (or broad UI audit)**: If `search` returns `[]` or unrelated descriptions because your phrasing differed from the catalog (or your task spans multiple categories), run `npx -y modern-web-guidance@latest list` once to check if the pattern is covered under more general terminology.
+> - **Topic not covered**: If no guide `description` directly matches your task, proceed with your implementation without retry loops or retrieving unrelated guides.
+
+---
+
+### Step 2. Retrieve Best Practices
+
+Once you have relevant `id`(s) from the search results, call `retrieve` to get the full guide(s)—including both specific use-case guides that match your task and any broader discipline guide (e.g., `html`, `css`, `forms`, `accessibility`, `color`, `performance`, `security`) that applies. You can pass multiple IDs separated by commas.
+
+```sh
+npx -y modern-web-guidance@latest retrieve "<id>"
+```
+
+If the output is truncated, you must repeat the command but redirect to a file and read that file.
+
+**Example Output**:
+`The markdown content of the guide describing implementation steps...`
+
+---
+
+### Step 3. Verify Guidance Compliance
+
+When generating or modifying code, cross-check the implementation against the retrieved guide before concluding:
+- **Applicable Guidance & Fallbacks**: Ensure the relevant modern patterns and necessary fallback strategies from the guide are correctly applied, without forcing unrequested features.
+- **Task Fulfillment**: Confirm that the implementation fully satisfies the user's request.
+
+### Step 4. Disclose Skill Usage
+
+When you consult `modern-web-guidance` for a task, end the response where you deliver those changes with a `### Modern Web Guidance` section:
+- **When retrieved guides shaped your code**: Write **one** bullet (1–2 sentences, ≤75 words) per newly applied `<id>` in first-person voice explaining the non-obvious implementation choices, CSS/API overrides, or fallbacks `<id>` required and the pitfall it prevented, anchored by a short verbatim quote of that specific rule or gotcha (never the guide's intro overview):
+  `- **\`<id>\`**: <Non-obvious APIs, overrides, or fallbacks applied and the pitfall prevented> ("<short verbatim quote of the specific rule or gotcha>").`
+  - **Never** guess `<id>`s or quotes from memory after context compaction (re-run `search`/`retrieve` if needed), and credit **only** guide-backed changes from the current turn.
+- **When searched/listed in this turn but zero guides applied**: Write one first-person sentence naming which topics or guides you checked in `modern-web-guidance` and why none applied (omit if any guide applied).
+
+## Using npx / pnpx
+
+- Prefer `pnpx` over `npx` if `pnpm` is available (note: `pnpx` does not use the `-y` flag).
+- When requesting tool permissions, allowlist `npx -y modern-web-guidance@latest *` specifically (or `pnpx modern-web-guidance@latest *`), never bare `npx *` or `pnpx *`.
+- IMPORTANT: on Windows, using `npx` may fail. Use `npx.cmd ...` instead.
+- Fetching and running `modern-web-guidance` requires outbound network access. If running in a sandboxed, permission-gated, or approval-based environment (e.g., Codex, Claude Code), **proactively request approval/allowlisting for the command with network access BEFORE executing it the first time**, avoiding sandbox network timeouts.
+- In sandboxed environments where `~/.npm` is read-only or restricted, set `NPM_CONFIG_CACHE=/tmp/npm-cache`.
+- If the command hangs due to being offline, try running again in offline mode: `npx --offline …`.
+- The `--skill-version` flag is used to determine if this SKILL.md is out of date. If it is, a warning message is logged to stderr.
+
+## Guidelines
+
+- Always search **first** to find the most relevant guides.
+- These guides use vanilla HTML/CSS/JS; adapt them to your framework without dropping the modern feature:
+  - **Types**: Spread/cast newly shipped HTML attributes (`{...({ popover: 'hint', interestfor: id, commandfor: id, switch: '' } as any)}`, `[attr.*]`) rather than removing them or merging `@types/react`.
+  - **SSR & Bundlers**: Guard `window`/`HTMLElement` in SSR and load polyfills via bare `import('<pkg>')` in client effects (or set Vite `build.target: 'esnext'` for top-level `await`)—never copy files from `node_modules`.
+  - **DOM, IDs & CSS**: Call `showModal()`/`moveBefore()` via refs on non-VDOM-managed nodes, generate per-instance IDs/`anchor-name`s (`useId()`), and keep `:root` and `@starting-style` top-level/unscoped.
+- Do not hallucinate guides or ignore them; they represent the preferred local standard for the user's project.
+
+## Interpreting Browser Support & Fallbacks
+
+* **Default Behavior**: All guides assume **Baseline Widely available** features are safe to use without fallbacks. For features that are not Baseline widely available, you **MUST** follow the fallback recommendations in the guide, unless the user has specified a custom browser support policy.
+* **Custom Policies**: If the user has already defined explicit browser support requirements, use the browser compatibility data in the guide to determine if a fallback can be safely ignored.
+  - For Baseline YYYY targets, a feature satisfies this target if its "Baseline since" date is <= YYYY.
+  - **Policy Examples**:
+    - _"Do not implement feature fallbacks."_ (for exploratory prototypes of the cutting-edge web)
+    - _"Safari 17.4+"_ (for internal tools targeting macOS or Tauri-based desktop apps)
+    - _"Never recommend or implement polyfills; if a Baseline Newly Available feature is required for core functionality, provide a lightweight custom fallback or redesign the approach."_ (to minimize bundle size and avoid technical debt)
+    - _"Assume a modern execution environment where Baseline Newly Available features can be used natively, provided they are strictly feature-detected and degrade gracefully."_ (for progressive enhancement strategies)
+* **Reactive Policy Discovery**: Watch for environmental cues to suggest documenting a policy in CLAUDE.md or AGENTS.md. Suggest this if the developer:
+  - Mentions building for a restricted runtime (e.g., Electron or Tauri).
+  - Explicitly excludes specific targets (e.g., "we don't support Desktop Chrome").
+  - Expresses hesitation about polyfill complexity, bundle size, or performance cost.
+  - Questions if a feature is safe to use without fallbacks.
+
+  No defined policy format. This is an example: `**Browser Support:** Allow Newly Available features, but only adopt custom fallback code that adds <= 20 lines and does not require external dependencies.`
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessibility.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessibility.md
new file mode 100644
index 00000000..00cb44a2
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessibility.md
@@ -0,0 +1,585 @@
+# Accessibility Coding Guidelines
+
+This guide provides actionable DOs and DON'Ts for AI coding agents to ensure web applications are accessible to all users, including those using assistive technologies.
+
+Keep these principles in mind throughout:
+
+- **Accessibility is the minimum, not the ceiling.** Conformance to standards is the floor; aim for genuine usability.
+- **Patterns are use-case specific.** No checklist replaces real testing — including testing with disabled users — to confirm a given implementation is actually accessible in context.
+
+Contents:
+
+- [1. Content Navigability and Structure](#1-content-navigability-and-structure)
+  - [Landmarks](#landmarks)
+  - [Headings](#headings)
+  - [Lists](#lists)
+  - [Tables](#tables)
+  - [Skip links](#skip-links)
+  - [Code example: good use of landmarks, headings, lists, tables, and a skip link](#code-example-good-use-of-landmarks-headings-lists-tables-and-a-skip-link)
+- [2. Semantic HTML and ARIA](#2-semantic-html-and-aria)
+  - [Prefer native HTML](#prefer-native-html)
+  - [ARIA roles and states](#aria-roles-and-states)
+- [3. Accessible Names and Descriptions](#3-accessible-names-and-descriptions)
+  - [Naming mechanisms](#naming-mechanisms)
+  - [Choosing the name](#choosing-the-name)
+  - [Descriptions](#descriptions)
+  - [Code Example: Visually Hidden Utility](#code-example-visually-hidden-utility)
+- [4. Document Metadata and Language](#4-document-metadata-and-language)
+  - [Language](#language)
+  - [Titles](#titles)
+  - [Iframes](#iframes)
+  - [Code Example: using the `<title>` and `<iframe>` elements](#code-example-using-the-title-and-iframe-elements)
+- [5. Keyboard and Focus Management](#5-keyboard-and-focus-management)
+  - [Tab order and focusability](#tab-order-and-focusability)
+  - [Keyboard handlers](#keyboard-handlers)
+  - [Focus indicators](#focus-indicators)
+  - [Target sizes](#target-sizes)
+- [6. Alternate Text and Media](#6-alternate-text-and-media)
+  - [Images](#images)
+  - [Inline SVGs](#inline-svgs)
+  - [Complex images and charts](#complex-images-and-charts)
+  - [Audio and video](#audio-and-video)
+  - [CSS generated content](#css-generated-content)
+  - [Content Visibility Decision Matrix](#content-visibility-decision-matrix)
+- [7. Forms and Input Controls](#7-forms-and-input-controls)
+  - [Labels and hints](#labels-and-hints)
+  - [Input assistance and validation](#input-assistance-and-validation)
+- [8. Live Regions](#8-live-regions)
+  - [Live Region Urgency Table](#live-region-urgency-table)
+  - [When to announce](#when-to-announce-live-regions)
+  - [Managing announcements](#managing-announcements)
+- [9. Color](#9-color)
+- [10. Typography](#10-typography)
+- [11. Motion and Preferences](#11-motion-and-preferences)
+- [12. Modals and Native Dialogs](#12-modals-and-native-dialogs)
+  - [Native `<dialog>`](#native-dialog)
+  - [Custom overlays](#custom-overlays)
+- [13. Testing Validations](#13-testing-validations)
+  - [Automated checks](#automated-checks)
+  - [Manual testing](#manual-testing)
+
+## 1. Content Navigability and Structure
+
+### Landmarks
+
+- **Place all content within landmarks:** Wrap each relevant part of the page in `<header>`, `<nav>`, `<main>`, `<aside>`, and `<footer>` elements so assistive-tech users can jump between regions. (1.3.6 Identify Purpose (Level AAA))
+- **Use the correct landmark:** Use the `<header>` element as a container for introductory content, the `<nav>` element as a container for site-wide or in-page navigation links, the `<main>` element as a container for the main content of the page, the `<aside>` element as a container for content that is tangentially related to the main content, and the `<footer>` element as a container for information about the related content, such as the author, copyright information, and links to related documents. (1.3.1 Info and Relationships (Level A))
+- **Use one `<main>` landmark per page:** Avoid using multiple `<main>` elements on a single page. (1.3.1 Info and Relationships (Level A))
+- **Provide distinguishable accessible names for navigation regions:** If a page contains multiple `<nav>` elements, apply the `aria-label` attribute to each element and set its value to a distinguishable accessible name for the region. For example: `<nav aria-label="Primary">`, `<nav aria-label="Secondary">`, and so on. (Best practice)
+- **Don't overuse landmarks:** Too many landmarks dilute their value. In particular, avoid labeling a `<section>` (which turns it into a `region` landmark) — `region` should be a last resort when no other landmark fits. (Best practice)
+
+### Headings
+
+- **Structure main content with headings:** Use `<h1>`–`<h6>` elements sequentially so screen reader users get a navigable outline. (1.3.1 Info and Relationships (Level A))
+- **Mandatory - Don't use "fake" headings:** Never use `<div>` or `<span>` elements to look like headings without standard `<h1>`–`<h6>` elements. (1.3.1 Info and Relationships (Level A))
+- **Avoid nesting headings incorrectly:** Make sure that, if a sub-heading is visually less important than its parent heading, its heading level is lower in the heading hierarchy. (1.3.1 Info and Relationships (Level A))
+- **Use one `<h1>` element per page:** Use the `<h1>` element for the page's main heading. Having more than one `<h1>` element on a page makes it difficult for screen reader users to identify the actual main heading. (Best Practice)
+  - **Caveat:** If a page includes a modal dialog that is marked up using the `<dialog>` element, `role="dialog"`, or `role="alertdialog"`, it is fine to mark up its main heading using the `<h1>` element because the dialog is a new window that is separate from the page.
+- **Avoid "skipped" heading levels:** Avoid jumping directly from (for example) `<h1>` → `<h4>` to avoid breaking the logical hierarchy. (Best Practice)
+- **Avoid placing headings inside the `<summary>` element:** Some browsers still expose this element as a button, which removes all roles from its children including headings. If a heading must act as a disclosure trigger, use an accordion or a disclosure implemented with ARIA where the heading element wraps the button, rather than use the `<details>` and `<summary>` elements. (Best Practice)
+
+### Lists
+
+- **Use lists for repeated, contiguous content:** `<ul>`/`<ol>` give assistive tech a count of listitems up front and let users skip the entire list. (1.3.1 Info and Relationships (Level A))
+- **Use the correct list element:** Use the `<ul>` element for unordered lists where the order of the items is **not** important (such as a list of related products), and use the `<ol>` element for ordered lists where the order of the content **is** important (such as a list of instructions). (1.3.1 Info and Relationships (Level A))
+- **Don't use lists for non-list content:** Do not use list markup to mark up separate paragraphs of text, as screen readers will announce list information when they encounter lists, therefore leading to a screen reader hearing potentially confusing and redundant information about the related content. (1.3.1 Info and Relationships (Level A))
+- **Don't use lists for checkboxes and radio buttons:** When marked up correctly, screen readers will already announce the number of checkboxes or radio buttons, as well as the number of the currently focused checkbox / radio button in the set, even though there is no list markup. Additional list markup will lead to duplication. (1.3.1 Info and Relationships (Level A))
+
+### Tables
+
+- **Do use the correct table elements:** Use the `<table>` element to identify the table, the `<caption>` element to provide a title and accessible name for the description, the `<tr>` element to identify individual rows in the table, and the `<th>` and `<td>` elements to identify header and data cells respectively. (1.3.1 Info and Relationships (Level A))
+- **Do use the `scope` attribute on `<th>` elements:** The `scope` attribute indicates whether the `<th>` element represents a row header (`<th scope="row">`) or a column header (`<th scope="col">`). (1.3.1 Info and Relationships (Level A))
+- **Mandatory - Don't use tables for layout:** Screen readers will announce redundant information about the layout, which may be confusing for screen reader users, while the use of tabular markup has an impact on the reading and keyboard focus order of content. Use CSS Grid/Flexbox for visual layouts instead. (1.3.1 Info and Relationships (Level A))
+- **Avoid overly-complex tables:** Spanned rows, spanned columns, nested tables, and expandable / collapsible rows can make sense visually and meet the related WCAG success criterion, but the overall structure can be disorienting and difficult to navigate for screen reader users. In such cases, break tables up into smaller tables that are easier and more efficient to navigate. (Best Practice)
+
+### Skip links
+
+- **Provide skip links** prior to repeated content like site headers with navigation or long/infinite lists, so that keyboard users can easily bypass them. (2.4.1 Bypass Blocks (Level A))
+  - **Caveat:** Sometimes screen magnifiers do not follow the focus when a skip link’s target is not normally focusable.
+    The recommended workaround is to make the target programmatically focusable, but not a part of the tab order, using `tabindex="-1"`.
+    If the target contains focusable elements, this creates another usability issue as clicking within the target will always set the **sequential focus navigation start point** to the target rather than at a point between focusable elements.
+    A solution that satisfies both user expectations is to make the first meaningful element within the intended target the actual target of the skip link with `tabindex="-1"`, for example a heading (`<h1 id="content" tabindex="-1">`).
+    Beware that any content prior to such an element will be skipped, including other relevant content within the targeted section, and this creates usability gaps for other assistive tech users.
+- **Avoid using skip links where they are not needed:** A set of pages whose only common element is a single link to the Home page does not need a skip link. (Best Practice)
+- **Avoid overusing skip links:** A single skip link, or two skip links to cover the primary and secondary sets of common navigation links, is usually sufficient on a single page. Multiple unnecessary skip links add to the number of <kbd>Tab</kbd> stops to a page, which causes frustration for people who use the keyboard alone for navigation. (Best Practice)
+
+```html
+<!-- Good: Skip to main content -->
+<a href="#content" class="skip-link">Skip to main content</a>
+<main id="content">...</main>
+```
+
+### Code Example: good use of landmarks, headings, lists, tables, and a skip link
+
+```html
+<!-- Good: Semantic landmarks, heading hierarchy, skip link -->
+<header>
+  <a href="#platform-dashboard" class="skip-link visually-hidden">Skip to content</a>
+  <nav aria-label="Primary">
+    <ul>
+      <li><a href="/">Home</a></li>
+    </ul>
+  </nav>
+</header>
+<main>
+  <h1 id="platform-dashboard" tabindex="-1">Platform Dashboard</h1>
+  <section>
+    <h2>User Statistics</h2>
+    <table>
+      <caption>Monthly active users</caption>
+      <thead>
+        <tr>
+          <th scope="col">Month</th>
+          <th scope="col">Users</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr>
+          <td>January</td>
+          <td>12,000</td>
+        </tr>
+      </tbody>
+    </table>
+    <h3>Notes</h3>
+    <ul>
+      <li>Results do not include users without active subscriptions</li>
+      <li>Results are accurate as of 31 December 2025</li>
+    </ul>
+  </section>
+</main>
+```
+
+## 2. Semantic HTML and ARIA
+
+### Prefer native HTML
+
+- **Prefer HTML elements and attributes to ARIA:** Avoid `<div role="button">` or `<a role="button">` and use `<button>` instead. Native HTML elements and attributes already have the correct role and behavior, including keyboard support, built-in by default. `<button>` already implies `role="button"`, `required` already implies `aria-required`, and no additional JavaScript is required to ensure the correct role and behavior is supported. (Best Practice)
+  - **Caveat:** ARIA is required when the related feature is not available in HTML, for example there are no HTML elements explicitly intended for building a tabbed navigation widget, but ARIA includes appropriate role and state properties for this purpose.
+- **Don't add redundant ARIA roles or properties:** Avoid `<ul role="list">`, `<nav role="navigation">`, and `<input required aria-required="true">`. (Best Practice)
+  - **Caveat:** Safari removes list semantics from `<ul>`/`<ol>` outside `<nav>` when `list-style: none` or `display: flex`/`grid` is applied. In that case `role="list"` is required to restore them.
+- **Don't apply interactive ARIA roles to structural HTML elements:** Use `<li><span role="button">Button in a list</span></li>`, not `<li role="button">Button in a list</li>`, to avoid breaking the container list semantics. (4.1.2 Name, Role, Value (Level A))
+  - **Caveat:** It is acceptable to apply ARIA roles to structural HTML elements that have similar semantics, for example a tree view: `<ul role="tree"><li role="treeitem">…</li>…</ul>`.
+
+### ARIA roles and states
+
+- **Match ARIA implementations to actual behavior:** When applying `role="tab"` to an element, it must then behave like a tab — including keyboard interactions. Many ARIA patterns can't be implemented in CSS alone and need JavaScript. (4.1.2 Name, Role, Value (Level A))
+- **Manage toggle states:** Utilize `aria-expanded` and `aria-pressed` to communicate toggle states for custom controls. (4.1.2 Name, Role, Value (Level A))
+- **Be deliberate about `disabled` vs `aria-disabled`:** `disabled` removes the element from the focus order entirely (and `tabindex="0"` won't bring it back), which is often wrong for toolbar buttons or links. `aria-disabled="true"` keeps the element focusable so users can land on it and learn it's disabled, but because it only communicates state to assistive technologies, you must also prevent activation (such as pointer clicks and keyboard triggers) in JavaScript. (4.1.2 Name, Role, Value (Level A))
+- **Mandatory - Don't hide interactive elements from screen readers:** Do not apply `aria-hidden="true"` to interactive elements that receive focus, or to their parent elements. (4.1.2 Name, Role, Value (Level A))
+- **Mandatory - Don't suppress the roles of interactive elements:** Applying `role="presentation"` or `role="none"` to an interactive element strips its semantics. The element will still be exposed to assistive technologies and announced by screen readers, but its role and any state information will not be, which results in confusion and potentially unexpected behavior. (4.1.2 Name, Role, Value (Level A))
+- **Don't assume custom elements have no ARIA:** Custom elements can attach ARIA via `ElementInternals`, which some automated test tools can't see — so the absence of `role`/`aria-*` attributes in markup doesn't prove the element has no semantics. Verify with the browser's accessibility-tree inspector. (Best Practice)
+
+## 3. Accessible Names and Descriptions
+
+Every interactive element and some landmarks need an accessible name, and many benefit from an accessible description. Names are short and identify the element; descriptions add context.
+
+### Naming mechanisms
+
+- **Prefer native naming mechanisms:** `<label>` for form controls, `<caption>` for `<table>`, `<legend>` for `<fieldset>`, `<figcaption>` for `<figure>`. (Best Practice)
+- **Explicitly associate `<label>` with its control via `for`/`id`:** As well as ensuring the control is appropriately labeled by the contents of the `<label>` element, this results in a larger target area for people to activate the label _or_ its related control to move focus to the control, which isn't globally supported with other forms of labeling (such as using the `aria-labelledby` attribute). Additionally, some assistive technologies, particularly voice recognition software, require the `for`/`id` relationship to be explicitly set, even if an equivalent accessibility-supported approach (such as nesting an `<input>` inside a `<label>`) is taken. (4.1.2 Name, Role, Value (Level A))
+- **Prefer `aria-labelledby` over `aria-label` when a visible label exists:** This avoids duplication, improves maintainability, and translates better. (Best Practice)
+- **Don't use `title` as a naming mechanism:** The value of this attribute is only displayed on mouse hover, and cannot be displayed or otherwise accessed using the keyboard in any browser. (Best Practice)
+  - **Caveat:** `<iframe>` is an exception, as the `title` attribute is the standard way of providing an accessible name for this element.
+- **Don't use `placeholder` as a naming mechanism:** While the value of this attribute is initially displayed inside an `<input>` or `<textarea>`, it disappears as soon as the user enters text into the field, meaning that there is no longer a visual cue as to what the field represents. The contrast between `placeholder` text and its background in most browsers is very low, and therefore is difficult for people to perceive. (3.3.2 Labels or Instructions (Level A))
+- **Don't put `aria-label`/`aria-labelledby` on elements that shouldn't be named:** Examples include plain `<div>`, `<span>`, and other custom elements without a role. These attributes are only intended for providing accessible names for elements that have explicit or implicit widget (for example, button, link, and tab), landmark, image, or iframe roles. (1.3.1 Info and Relationships (Level A))
+  - **Caveat:** Custom elements may have an implicit role set via `ElementInternals`, so the absence of a `role` attribute isn't conclusive.
+
+### Choosing the name
+
+- **Avoid inconsistent link text:** If multiple hyperlinks direct users to the same target page, make sure each link has the same accessible name, which should typically be the same as its visible link text. For example, if the target page for a link is `profile.html`, make sure that all links have an accessible name of "My Profile" **or** "Profile"; do not use "My Profile" in one instance, and "Profile" in the other. (Best Practice)
+- **Disambiguate controls that look visually identical but which perform different actions by their accessible name:** For example, a page may include multiple "Edit" buttons, each of which triggers functionality to perform a different action, such as edit the user's name, edit the user's password, and edit the user's address. While it may be visually obvious from the surrounding content what the purpose of these buttons might be, screen reader users may only hear "Edit, button". Techniques to resolve this include the following: (4.1.2 Name, Role, Value (Level A))
+  - **Use visually hidden text:** The text is included in the DOM but is visually hidden using CSS. For example `<button>Edit <span class="visually-hidden">first name</span></button>`. Refer to the [code example: visually hidden utility](#code-example-visually-hidden-utility) for the full CSS.
+  - **Apply the `aria-label` attribute to the control:** The value of this attribute should then include the visible text as well as important contextual information, for example `<button aria-label="Edit name">Edit</button>`, `<button aria-label="Edit address">Edit</button>`, and so on.
+  - **Use the `aria-labelledby` or `aria-describedby` attribute to associate the control with the content it relates to:** Chaining IDs in `aria-labelledby` appends the related text to the control's accessible name (for example, `<p id="firstName">First name</p> <button id="editFirstName" aria-labelledby="editFirstName firstName">Edit</button>`), whereas `aria-describedby` provides the context as an accessible description (`<p id="firstName">First name</p> <button aria-describedby="firstName">Edit</button>`).
+- **Do include a control's visible text in its accessible name:** Any visible text used to label a control must be included exactly as written in the control's accessible name. The accessible name can include additional information before or after the visible text, but the visible text itself must not differ. For example, the accessible name for a link containing the link phrase "Read more" can be "Read more about [subject]", because the visible text is included without modification. However, the accessible name cannot be "Read some more about [subject]", because the term "some" appears between the words "Read" and "more", which is not reflected in the visible text. (2.5.3 Label in Name (Level A))
+- **Don't reuse an accessible name across controls with different effects in the same view:** Make sure that each accessible name is disambiguated. (4.1.2 Name, Role, Value (Level A))
+  - **Caveat:** Having two separate buttons with the accessible name of "Close" in two separate dialog boxes is fine, because only one dialog box is reachable at a time; however, multiple "Edit" buttons for different effects in the same dialog box is not.
+- **Don't reuse an accessible name across hyperlinks that point to different `href` targets:** For example, avoid `<a href="annualreport2025.html">Annual Report</a>` and `<a href="annualreport2026.html">Annual Report</a>`. Use `<a href="annualreport2025.html">Annual Report 2025</a>` and `<a href="annualreport2026.html">Annual Report 2026</a>` (or an equivalent technique for disambiguating controls) instead.
+- **Don't pack descriptions, error messages, or instructions into the label:** Verbose labels confuse and frustrate people who use screen readers. Instead, use the `aria-describedby` attribute to programmatically associate any additional content with the field. For example: `<label for="yourComments">Your comments</label><p id="yourCommentsWarning">Please do not include any personal information in this field.</p><textarea id="yourComments" aria-describedby="yourCommentsWarning"></textarea>`. Screen readers will then announce the label first, followed by the control type, and only then announce additional information that a user can skip if they are already aware of it. (Best Practice)
+- **Don't repeat state information already exposed by ARIA inside the label:** Examples include information exposed via the `aria-expanded`, `aria-checked`, `aria-selected`, `aria-pressed`, and similar attributes. This creates duplication, redundancy, and ambiguity. (Best Practice)
+- **Don't include the role name in the label:** This will lead to duplication. For example, `<nav aria-label="Primary navigation">` will be read by screen readers as "Primary navigation, navigation". (Best Practice)
+
+### Descriptions
+
+- **Identify instructions, error messages, and any other important information explicitly related to a control as a description:** Examples of descriptions include: (1.3.1 Info and Relationships (Level A))
+  - A list of password requirements when creating an account
+  - An error message related to a field in a previously submitted form
+  - Additional instructions, such as "You must agree to the terms and conditions before you can submit the form"
+- **Make sure the description is available to assistive technologies when the related element receives focus:** Take one of the following approaches (1.3.1 Info and Relationships (Level A)):
+  - If the description is already visible on the page, programmatically associate it with the element using the `aria-describedby` attribute.
+  - If the description is not visible on the page and is explicitly for screen reader users (in other words, when providing a visible description is not appropriate or useful), apply the `aria-description` attribute to the element and use it to provide an appropriate description.
+- **Avoid including a description for every element:** if the primary label already provides sufficient information (such as "First name"), any additional description is likely to be redundant. (Best Practice)
+  - **Caveat:** Inline error messages associated with controls, such as error messages below / above text fields, as well as secondary labels that should be announced when the element receives focus, are exceptions.
+- **Avoid including information in the description that is already provided by attributes applied to the element:** For example, including "This is a required field" as a description for an `<input>` element that already includes the `required` attribute will lead to duplicate announcements. (Best Practice)
+  - **Caveat:** `aria-invalid="true"` is an exception; many screen readers announce "invalid" when they reach an `<input>` that includes this attribute set to `true`, which indicates that the field is in error. However, it does not indicate what the error is. In such cases, a description (the actual human readable error message) is required. This attribute should only be applied and set to true when the error message is present.
+- **Avoid including interactive elements in an `aria-describedby` target** unless the content of the element reads sensibly as a description on its own. For example: (Best Practice)
+  - This is acceptable, as the entire text string makes sense when announced: `<p id="description">I understand the <a href="tandc.html">terms and conditions</a>.</p>`
+  - This is not appropriate, as the description will be announced as "Please don't include personal information in this field. Learn more.", where "Learn more" will be announced out of its intended context: `<p id="description">Please don't include personal information in this field. <a href="…">Learn more</a></p>`. Instead, only include the plain text in the referenced description: `<p><span id="description">Please don't include personal information in this field.</span> <a href="…">Learn more</a></p>`.
+
+### Code Example: Visually Hidden Utility
+
+A `.visually-hidden` utility provides text for screen readers without rendering it visually. It's commonly used for skip links, additional context on icon-only buttons, and supplementary labels.
+
+```css
+/* Hides content visually but keeps it in the accessibility tree.
+   :focus-within / :active opt elements out — useful for skip links and
+   any focusable content wrapped in this class. */
+.visually-hidden:where(:not(:focus-within, :active)) {
+  position: absolute !important;
+  clip-path: inset(50%) !important;
+  overflow: hidden !important;
+  width: 1px !important;
+  height: 1px !important;
+  margin: -1px !important;
+  padding: 0 !important;
+  border: 0 !important;
+  white-space: nowrap !important;
+}
+```
+
+When the hidden content is focusable (skip links, focus-receiving wrappers), the `:focus-within`/`:active` exception lets it become visible. Style the visible state per situation, e.g. a skip link to the main content typically wants fixed positioning at the top-left of the viewport so the rest of the page doesn't shift.
+
+## 4. Document Metadata and Language
+
+### Language
+
+- **Do declare the page's human language:** Always apply the `lang` attribute to the page's `<html>` element, and always set it to the primary human language of the page's content. For example, `<html lang="en">`. (3.1.1 Language of Page (Level A))
+- **Do declare changes in the page's human language:** If there is a language change on the page, apply the `lang` attribute to the parent/container element for the affected content, and set the value of this attribute to the shortcode for the language of the affected content. For example: `<p>In Germany, you may be greeted by someone saying <span lang="de">Guten Morgen</span>.</p>`. (3.1.2 Language of Parts (Level AA))
+- **Don't set the value of the `lang` attribute to a value that doesn't match the human language of the content:** This causes screen readers and other text-to-speech software to announce the content in a non-understandable manner. (3.1.1 Language of Page (Level A), 3.1.2 Language of Parts (Level AA))
+
+### Titles
+
+- **Do include the `<title>` element in the `<head>` section for all pages:** This includes pages embedded into a document using an `<iframe>`. (2.4.2 Page Titled (Level A))
+- **Provide unique page titles:** Every page should have its own title that unambiguously reflects the page's purpose or content. (2.4.2 Page Titled (Level A))
+- **Front-load the page's `<title>` with unique content:** For example, `<title>Page Topic | Site Name</title>`. (Best Practice)
+- **Update single-page application (SPA) titles during page transitions:** For example, if the page title is `<title>Contact Us</title>` when a contact form is displayed, update the title to `<title>Thank you for contacting us!</title>` when the form is successfully submitted. (2.4.2 Page Titled (Level A))
+- **Don't include an empty `<title>` element in the `<head>` section of a page:** No matter how short or inconsequential a page appears, do not use `<title></title>`. Page titles appear in the browser tab, so pages are distinguishable when users have multiple tabs open, and are typically announced by screen readers when the page is opened. (2.4.2 Page Titled (Level A))
+- **Avoid using the same title for multiple pages, or using ambiguous page titles:** In such cases, pages are indistinguishable without reviewing the actual page content itself. (2.4.2 Page Titled (Level A))
+
+### Iframes
+
+- **Do provide a descriptive `title` for `<iframe>` elements:** All `<iframe>` elements should include a `title` attribute set to a value that unambiguously describes the contents of the `<iframe>`. (4.1.2 Name, Role, Value (Level A))
+- **Don't disable iframe scrolling** using `scrolling="no"` (deprecated) or `overflow: hidden` on iframes. Users who zoom in or enlarge text need to scroll to reach content that overflows. (1.4.4 Resize Text (Level AA), 1.4.10 Reflow (Level AA))
+
+### Code Example: using the `<title>` and `<iframe>` elements
+
+```html
+<!-- Good: Distinct title and language declaration -->
+<html lang="en">
+<head>
+  <title>Analytics Reports | Guidance Platform</title>
+</head>
+<body>
+  <p>The motto is <span lang="la">"Carpe diem"</span>.</p>
+  <iframe title="Interactive Sales Chart" src="/chart"></iframe>
+</body>
+</html>
+```
+
+## 5. Keyboard and Focus Management
+
+### Tab order and focusability
+
+- **Provide a logical tab order:** Make sure that the order in which elements receive focus follows an appropriate sequence. (2.4.3 Focus Order (Level A))
+  - **Caveat:** In left-to-right reading languages, the tab order is logical when focus moves from top-to-bottom and left-to-right. However, in right-to-left reading languages, the tab order is logical when focus moves from top-to-bottom and right-to-left.
+- **Use `tabindex` only when necessary:** Apply `tabindex="0"` to elements requiring focus where an appropriate interactive role has been applied but the element isn't focusable by default; for example, `<span role="button" tabindex="0">Print</span>` (2.4.3 Focus Order (Level A))
+- **Manage focus correctly to and from updated content:** For example, if a dialog box appears on the page, make sure that focus immediately moves to the dialog box, is restricted to the contents of the dialog box, and (when dismissed) returns to the element that originally triggered the dialog box. (2.4.3 Focus Order (Level A))
+- **Don't apply `tabindex="0"` to interactive elements that are already focusable by default:** Native elements like the `<button>`, `<a>` (only with the associated `href` attribute), and `<input>` elements are already keyboard focusable, and therefore do not require `tabindex="0"`. (2.4.3 Focus Order (Level A))
+- **Don't apply `tabindex="0"` to static, non-interactive, and hidden elements:** Only elements that (when activated) perform a specific action should be included in a page's tab order. Static, non-interactive, and hidden elements (whether hidden temporarily or permanently) must not be focusable. (2.4.3 Focus Order (Level A))
+- **Mandatory - Don't use positive `tabindex` values:** Never apply `tabindex="1"` (or any value > 0) to elements, as doing so imposes a tab order on the page that bears no resemblance to the intended or expected tab order. (2.4.3 Focus Order (Level A))
+
+### Keyboard handlers
+
+- **Attach <kbd>Enter</kbd>/<kbd>Space</kbd> handlers for custom simulated interactive elements:** When implementing a custom keyboard handler for button-like elements, <kbd>Enter</kbd> should be a `keydown` handler and <kbd>Space</kbd> should be a `keyup` handler (matching native `<button>` behavior where <kbd>Enter</kbd> repeats and <kbd>Space</kbd> triggers on release). (2.1.1 Keyboard (Level A))
+- **Don't attach keyboard handlers to native interactive elements:** Native elements such as the `<button>`, `<input>`, and `<a>` (with the required `href` attribute) elements already support the <kbd>Enter</kbd> and (except for the `<a>` element) the <kbd>Space</kbd> keys by default, so adding these keyboard handlers is redundant. (Best Practice)
+  - **Caveat:** if the `<a>` element is repurposed as a button through the inclusion of `role="button"`, a `keyup` handler is still required to support the <kbd>Space</kbd> key to match native `<button>` behavior.
+
+#### Code Example: Keyboard handlers
+
+```javascript
+// Good: Keyboard handlers for complex custom widgets (e.g., Tree items, tabs).
+// NOTE: This pattern applies ONLY to non-standard UI where no native HTML tag exists.
+// Always prioritize native <button> or <input> elements for standard interactions.
+// Elements MUST have the appropriate ARIA role (e.g., role="treeitem" or role="tab").
+customWidget.addEventListener('keydown', (e) => {
+  if (e.key === 'Enter') {
+    toggleWidgetState();
+  }
+  if (e.key === ' ') {
+    e.preventDefault(); // Prevent page scrolling on Spacebar keydown
+  }
+});
+
+customWidget.addEventListener('keyup', (e) => {
+  if (e.key === ' ') {
+    toggleWidgetState();
+  }
+});
+
+function toggleWidgetState() {
+  // E.g., Manage toggle/expanded states for custom controls
+  const isExpanded = customWidget.getAttribute('aria-expanded') === 'true';
+  customWidget.setAttribute('aria-expanded', !isExpanded);
+}
+```
+
+### Focus indicators
+
+- **Use `:focus-visible` when styling focus indicators:** When defining custom focus indicators, always style the `:focus-visible` state (not `:focus`) explicitly. (Best Practice)
+- **Prefer browser native focus indicators over custom focus indicators:** Leave focus indication to the browser unless custom focus styling is needed to meet contrast or design requirements. (Best Practice)
+- **Mandatory - Don't disable browser native focus indicators without providing a replacement custom focus indicator:** When using `outline: none;` to suppress the browser native focus indicator, provide an equivalent custom focus indicator that has a contrast ratio of at least `3:1` against adjacent content (2.4.7 Focus Visible (Level AA), 1.4.11 Non-text Contrast (Level AA)).
+- **Prefer `outline` over other properties for focus rings:** If `box-shadow` must be relied on for focus rings, provide an `outline`-based fallback for High Contrast Mode using the `forced-colors` media query. (Best Practice)
+- **Pair custom focus outlines with `outline-offset`:** This visually separates the ring from the element. (Best Practice)
+
+#### Code Example: Custom focus indication
+
+```css
+/* Good: High contrast focus border */
+:where(a:any-link, button):focus-visible {
+  outline: 3px solid #ff0055;
+  outline-offset: 3px;
+}
+```
+
+### Target sizes
+
+- **Do size interactive elements to have a target of at least 24x24 CSS pixels:** Enforce the target size of elements using `min-block-size` / `min-inline-size` or through padding rather than `width` / `height` so that content grows the target but not shrink it. (2.5.8 Target Size (Minimum) (Level AA))
+  - **Caveat:** Interactive elements _may_ have a target of less than 24x24 CSS pixels _as long as_ they are positioned in such a way that if a 24 CSS pixel diameter circle is centered on the bounding box of each element, the circles do not intersect nearby targets or circles for other targets that are less than 24x24 CSS pixels.
+- **Bump targets up on coarse pointers:** `@media (pointer: coarse) { … }`. (2.5.8 Target Size (Minimum) (Level AA))
+- **Don't use `touch-action: none;` for custom gestures:** This disables page scrolling through the element. Scope to the axis you actually need - `pan-y` for horizontal swipes (the page still scrolls vertically), and `pan-x` for vertical swipes. Reserve `none` for elements where no native touch behavior makes sense, such as a drawing canvas. (2.1.1 Keyboard (Level A))
+
+## 6. Alternate Text and Media
+
+### Images
+
+- **Mandatory - Apply the `alt` attribute to all `<img>` elements:** browsers replace the image with the value of this attribute for people who use screen readers. (1.1.1 Non-text Content (Level A))
+- **Do provide informative visual descriptions:** Describe the purpose of the image (for example, "Search", not "Magnifying glass"). (1.1.1 Non-text Content (Level A))
+- **Do apply `alt=""` to decorative visuals:** This prevents screen readers from announcing them. (1.1.1 Non-text Content (Level A))
+- **Don't use clichéd prefixes:** Avoid terms like "Image of…" and "Picture of…". (Best Practice)
+- **Don't use underscores in filenames:** Use dashes if the filename might be announced as fallback. (Best Practice)
+
+#### Code Example: Providing a text description for `<img>` elements
+
+```html
+<!-- Decorative -->
+<img src="divider.png" alt="">
+
+<!-- Informative (Functional) -->
+<a href="/search">
+  <img src="glass.png" alt="Search the platform">
+</a>
+```
+
+### Inline SVGs
+
+- **Do apply `role="img"` to the `<svg>` element for non-decorative SVGs:** This is so that they are globally exposed as images. (4.1.2 Name, Role, Value (Level A))
+- **Do provide a text description for non-decorative SVGs:** Use one of the following techniques: (1.1.1 Non-text Content (Level A))
+  - Include a nested `<title>` element as a child of the `<svg>` element that includes the text description. **or**
+  - Apply the `aria-label` attribute to the `<svg>` element and set its value to an appropriate text description.
+- **Do hide decorative SVGs from assistive technologies:** Apply `aria-hidden="true"` to decorative `<svg>` elements to prevent screen readers from announcing them. (1.1.1 Non-text Content (Level A))
+
+#### Code Example: Providing a text description for non-decorative SVGs using the `<title>` element
+
+```html
+<!-- Inline non-decorative SVG: example that uses the <title> element -->
+<svg role="img" viewBox="0 0 24 24">
+  <title>Home</title>
+  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
+</svg>
+```
+
+#### Code Example: Providing a text description for non-decorative SVGs using the `aria-label` attribute
+
+```html
+<!-- Inline non-decorative SVG: example that uses the aria-label attribute -->
+<svg role="img" viewBox="0 0 24 24" aria-label="Home">
+  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
+</svg>
+```
+
+#### Code Example: Identifying decorative SVGs
+
+```html
+<!-- Inline Decorative SVG (hide from assistive technologies) -->
+<svg aria-hidden="true" viewBox="0 0 24 24">
+  <path d="M10 20v-6h4v6h5v-8h3L12 3 2 12h3v8z"/>
+</svg>
+```
+
+### Complex images and charts
+
+- **Provide long descriptions for complex images:** Use `<figure>`/`<figcaption>` or `aria-describedby` for charts and infographics. (1.1.1 Non-text Content (Level A))
+- **Provide semantic data tables as alternatives:** Provide semantic data tables as accessible alternatives for charts and other complex visualizations. (1.1.1 Non-text Content (Level A))
+
+#### Code Example: Complex graph with figcaption
+
+```html
+<!-- Complex graph with figcaption -->
+<figure>
+  <img src="chart.png" alt="Sales growth graph 2024.">
+  <figcaption>Sales grew 20% in Q3 due to new platform launch.</figcaption>
+</figure>
+```
+
+### Audio and video
+
+- **Mandatory - Provide a transcript for audio-only content and combined video & audio content:** The transcript should be verbatim, and include all of the dialogue as well as text descriptions of important non-speech sounds such as sound effects. (1.2.1 Audio-only and Video-only (Prerecorded) (Level A), 1.2.3 Audio Description or Media Alternative (Prerecorded) (Level AA))
+- **Mandatory - Provide a text description or an audio track for video-only content:** Examples include text-based instructions for an animation on how to use a particular product, and a separate audio track that includes a description of the action in the video. (1.2.1 Audio-only and Video-only (Prerecorded) (Level A))
+- **Mandatory - Provide synchronous captions for videos:** Supply WebVTT captions for audio tracks within video content. The captions should be verbatim and synchronous with the audio track, and include all of the dialogue as well as meaningful non-speech content such as sound effects and other important information conveyed within the soundtrack (for example, "Ominous music plays"). (1.2.2 Captions (Prerecorded) (Level A))
+  - **Caveat:** Captions are not required if the video is a decorative alternative for text that is already present and is clearly identified as such.
+- **Do provide an audio description for videos:** Include an additional audio track within the video that augments the visual content displayed on-screen. The audio description should convey information about the scene that is not described or spoken in the main audio track, and should be conveyed during existing pauses in the dialogue. (1.2.3 Audio Description or Media Alternative (Prerecorded) (Level A), 1.2.5 Audio Description (Prerecorded) (Level AA))
+
+#### Code Example: Video and audio content with captions and transcript
+
+```html
+<!-- Video with Captions tracks -->
+<video controls>
+  <source src="intro.mp4" type="video/mp4">
+  <track src="caps.vtt" kind="captions" srclang="en" label="English">
+</video>
+
+<!-- Audio with expandable transcript details -->
+<audio controls src="podcast.mp3" aria-details="podcast-transcript"></audio>
+<details id="podcast-transcript">
+  <summary>View Transcript</summary>
+  <div class="transcript-content">
+    Welcome to the show...
+  </div>
+</details>
+```
+
+### CSS generated content
+
+- **Alt text for CSS generated content:** Use the alternative text argument of `content` (e.g. `content: url(icon.svg) / "Save";`) and keep meaningful text in the DOM. See `accessible-generated-content` (via `npx -y modern-web-guidance@latest retrieve "accessible-generated-content"`) for more details. (1.1.1 Non-text Content (Level A))
+
+### Content Visibility Decision Matrix
+
+| Intent | Visual | Screen Reader | Focusable | Structural Pattern |
+| :--- | :--- | :--- | :--- | :--- |
+| **Visible to all** | Yes | Yes | Yes | Standard rendering |
+| **Screen Reader only** | No | Yes | Yes (if interactive) | Visually hidden utility (e.g. `.visually-hidden`) |
+| **Visual only** | Yes | No | No | `aria-hidden="true"` |
+| **Hidden for all** | No | No | No | `hidden` attribute / `display: none` |
+
+**Heuristic Rule:** If an element can receive keyboard focus, it must not be hidden via `aria-hidden="true"`.
+
+**Note:** only use screen reader only content as a last resort. If content is important, it should be visible for everyone.
+
+## 7. Forms and Input Controls
+
+### Labels and hints
+
+- **Mandatory - Provide a label for all form controls:** Do not rely on the currently selected input or value as a way of labeling the control. (3.3.2 Labels or Instructions (Level A))
+- **Connect Labels Programmatically:** Use `<label for="id">` linked to `<input id="id">`. (1.3.1 Info and Relationships (Level A))
+- **Don't use placeholders as primary labels:** Placeholders are not persistent labels. Only use placeholders to provide  brief hints, such as an example of an appropriate input. (3.3.2 Labels or Instructions (Level A))
+- **Link hints to inputs via `aria-describedby`:** Associate help text with inputs, and place the hint above the input so autocomplete popovers don't cover it during editing. (1.3.1 Info and Relationships (Level A))
+
+#### Code Example: A labeled form control with a hint for passwords
+
+```html
+<!-- Good: Semantic forms with hints for passwords -->
+<form>
+  <label for="pwd">Password:</label>
+  <span id="pwd-hint">Must contain at least 8 characters.</span>
+  <input id="pwd" type="password" aria-describedby="pwd-hint" autocomplete="current-password" required>
+</form>
+```
+
+### Input assistance and validation
+
+- **Mandatory - Use the `autocomplete` attribute:** Apply the `autocomplete` attribute to `<input>`, `<textarea>`, and `<select>` elements that explicitly collect personal information about the user, and set it to the correct value (for example `"email"` or `"given-name"`). (1.3.5 Identify Input Purpose (Level AA))
+- **Provide form validation constraints:** Use `required` (or `aria-required="true"` only when `required` isn't applicable) to signal mandatory inputs. (4.1.2 Name, Role, Value (Level A))
+- **Don't trigger context shifts on focus changes:** Avoid auto-submitting forms or jumping pages on focus change events alone. (3.2.1 On Focus (Level A), 3.2.2 On Input (Level A))
+
+## 8. Live Regions
+
+Live regions let assistive tech announce content updates that aren't tied to navigation or focus changes. They're easy to misuse — too many regions, or noisy ones, quickly become spam for screen-reader users.
+
+### Live Region Urgency Table
+
+| Urgency | Visual Analogue | `aria-live` Value | Behavioral Impact | Example |
+| :--- | :--- | :--- | :--- | :--- |
+| **Critical** | Modal / Alert | `assertive` (or `role="alert"`) | Interrupts immediately, clears speech queue | Session timeout, API failure |
+| **Standard**| Toast / Banner | `polite` | Announces at next graceful break | Search results, "Saved" status |
+| **Passive**  | Silent text | `off` | Only if user navigates to it | Live character count |
+
+**Heuristic Rule:** Use `assertive` only for critical, time-sensitive updates that require immediate attention or prevent safe continuation (e.g., data loss, session timeouts, or network drops).
+
+### When to announce live regions
+
+- **Announce dynamic errors via live regions:** Use `aria-live` or shift focus to error lists (4.1.3 Status Messages (Level AA)).
+- **Don't use live regions for interstitial states** like "Loading…" or "Updating…" unless they're meaningfully informative — they usually just create noise. Use the HTML `<progress>` element or the ARIA `progressbar` role for this purpose instead. (Best Practice)
+
+```html
+<!-- Session Timeout Warning with controls -->
+<div role="alert" class="timeout-warning">
+  Your session will expire in 2 minutes.
+  <button type="button" onclick="extendSession()">Extend Session</button>
+</div>
+```
+
+### Managing announcements
+
+- **Centralize live regions for non-visible announcements:** A single `polite` region and a single `assertive` region per page (with whatever `aria-atomic` configuration you need) keeps announcements consistent and easier to maintain. Many frameworks ship their own announcer abstraction — use it. (Best Practice)
+- **Debounce frequently-changing regions:** If a region can update many times per second (e.g. a combobox's result count as the user types), debounce so users aren't spammed. (Best Practice)
+- **Delay slightly when other announcements may collide:** When the user is typing or focus is being managed, a small delay before announcing keeps live-region updates from overlapping other speech. (Best Practice)
+- **Don't add live-region updates to inert DOM:** When dialogs open or sections become `inert`, queued or debounced messages will be unannounced — or announced from DOM the user can't reach. Coordinate live-region updates with dialog/inert state changes. (4.1.3 Status Messages (Level AA))
+
+## 9. Color
+
+See `color` (via `npx -y modern-web-guidance@latest retrieve "color"`) for accessible color (contrast requirements, light and dark color schemes, Forced Colors Mode, etc).
+
+## 10. Typography
+
+See `typography` (via `npx -y modern-web-guidance@latest retrieve "typography"`) for readable typography.
+
+## 11. Motion and Preferences
+
+See `motion` (via `npx -y modern-web-guidance@latest retrieve "motion"`).
+
+## 12. Modals and Native Dialogs
+
+Modern browsers provide native solutions for creating modal dialogs which avoid the need for focus traps, managing the accessibility of outside content, ensuring the content is on top, and dimming the background content — all of which are error prone and require heavy JavaScript event tracking to maintain.
+
+### Native `<dialog>`
+
+- **Use the native `<dialog>` element:** Invoke the dialog using the `.showModal()` method to open it in a modal state. When in a modal state, the browser sets outside content as inert (i.e. the outside content is hidden from the accessibility tree and cannot be interacted with nor be focused). (1.3.2 Meaningful Sequence (Level A), 2.4.3 Focus Order (Level A), 4.1.2 Name, Role, Value (Level A))
+  - **Note:** it is still possible to navigate to the browser chrome when using the `<dialog>` element.
+- **Don't implement focus traps for native modal dialogs:** When a `<dialog>` element is opened in a modal state, browsers set outside content as inert which is sufficient for ensuring only the dialog’s content can be focused. (Best Practice)
+
+#### Code Example: HTML & JavaScript: Native `<dialog>` with standard close events
+
+```html
+<!-- Dialog opens natively with showModal() and locks focus -->
+<button id="open-btn">Open Dialog</button>
+
+<dialog id="accessible-modal" aria-labelledby="title-id">
+  <h2 id="title-id">Account Settings</h2>
+  <p>Update your details here.</p>
+  <button onclick="this.closest('dialog').close()">Close Dialog</button>
+</dialog>
+
+<script>
+  document.getElementById('open-btn').addEventListener('click', () => {
+    document.getElementById('accessible-modal').showModal();
+  });
+</script>
+```
+
+### Custom overlays
+
+- **Use the `inert` attribute for custom overlays:** When `<dialog>` cannot be used (e.g., some non-modal overlays, framework constraints, or layouts where `<dialog>`'s top-layer/positioning behavior conflicts with the design), apply `inert` to outside content to ensure it cannot be interacted with by keyboard, pointer, or assistive technology. This requires structuring elements in such a way that the custom overlay is not a descendant of the element with `inert` set on it. (1.3.2 Meaningful Sequence (Level A), 2.4.3 Focus Order (Level A))
+- **Apply `role="dialog"` to the custom overlay:** When applied to the element used as the container for the custom overlay, it ensures that it is exposed as a dialog box to assistive technologies. (4.1.2 Name, Role, Value (Level A))
+- **Move focus to the overlay:** Ensure keyboard and screen reader focus moves to the container for the overlay so that people using a screen reader and people using the keyboard alone can start navigating its contents. Don't leave focus in outside content. (1.3.2 Meaningful Sequence (Level A), 2.4.3 Focus Order (Level A))
+
+## 13. Testing Validations
+
+### Automated checks
+
+- **Run Automated checks via axe-core or Lighthouse audits:** Catch missing alt texts or low contrasts (e.g., via Lighthouse in Chrome DevTools MCP).
+- **Don't rely purely on scores:** A 100% score does not guarantee real usability.
+
+### Manual testing
+
+- **Validate Sequential Navigations using keyboards alone:** Using only keyboard shortcuts, such as <kbd>Tab</kbd> / <kbd>Shift</kbd> + <kbd>Tab</kbd>, arrow keys, <kbd>Enter</kbd>, <kbd>Space</kbd>, and <kbd>Esc</kbd>, confirm every interactive element is reachable and operable, and that focus never gets stuck.
+- **Test on Screen Readers with calibrated browsers:** Rely on standard bindings (e.g., JAWS with Chrome, NVDA with Firefox, Narrator with Edge, VoiceOver with Safari on macOS and iOS, TalkBack with Chrome for Android).
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-error-announcement.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-error-announcement.md
new file mode 100644
index 00000000..a20796e9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-error-announcement.md
@@ -0,0 +1,208 @@
+# Accessible Error Announcement
+
+## The Problem
+Standard HTML5 validation provides visual feedback (via `:invalid` or `:user-invalid`), but it doesn't automatically synchronize with accessibility attributes like `aria-invalid`. 
+
+If you use standard `:invalid` styling, screen readers might announce "Invalid entry" the moment a user tabs into a required field that is currently empty. This creates a disruptive experience for users using assistive technologies, as the error is announced before interaction has occurred.
+
+## The Solution
+We want the *programmatic* state (`aria-invalid="true"`) to be applied **at the exact same moment** the *visual* state (`:user-invalid`) applies. Since `:user-invalid` relies on the browser's internal "user-interacted" flag, we can use JavaScript to check that this selector matches during standard interaction events.
+
+See [MDN aria-invalid](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Attributes/aria-invalid) for more details.
+
+### Implementation Strategy
+
+1.  **Visual Layer**: Use CSS `:user-invalid` to show borders/icons.
+2.  **Accessibility Layer**: Use `aria-invalid` and `aria-errormessage` to communicate state to Assistive Technology (AT).
+3.  **Bridge Visual & Accessibility Layer**: Create a lightweight JavaScript utility that listens for `blur` and `input` events, checks if the element matches `:user-invalid`, and updates the ARIA attributes accordingly.
+
+## Implementation Guide
+
+### 1. HTML Structure
+Link your input to its error message using `aria-errormessage` (or `aria-describedby` for broader support).
+
+```html
+<form>
+  <div class="field">
+    <label for="email">Email</label>
+    <input 
+      type="email" 
+      id="email" 
+      required 
+      aria-errormessage="email-error"
+    >
+    <span id="email-error" class="error-msg">
+      Please enter a valid email address.
+    </span>
+  </div>
+</form>
+```
+
+### 2. CSS
+Control the visibility of the error message using the native pseudo-class `:user-invalid`.
+
+```css
+.error-msg {
+  display: none;
+  color: #d93025;
+}
+
+/* Show error message when input is user-invalid */
+input:user-invalid ~ .error-msg {
+  display: block;
+}
+
+/* Optional: Visual cues on the input itself */
+input:user-invalid {
+  border-color: #d93025;
+}
+```
+
+### 3. JavaScript
+Since there is no "UserInvalidChanged" event, hook into standard form events to check the state.
+
+```javascript
+const updateAriaState = (event) => {
+  const input = event.target;
+  if (!input.matches?.('input, textarea, select')) return;
+
+  // Check if the browser currently considers this input "user-invalid"
+  const isUserInvalid = input.matches(':user-invalid');
+  
+  if (isUserInvalid) {
+    input.setAttribute('aria-invalid', 'true');
+  } else {
+    input.removeAttribute('aria-invalid');
+  }
+};
+
+// Listen on the document to handle dynamically added fields.
+// 'blur' and 'focus' do not bubble, so we must use the capture phase (true).
+document.addEventListener('blur', updateAriaState, true);
+document.addEventListener('focus', updateAriaState, true);
+
+// Also update on input if we've already shown the error, 
+// so the error clears immediately when fixed.
+document.addEventListener('input', (event) => {
+  const input = event.target;
+  if (!input.matches?.('input, textarea, select')) return;
+
+  const hasAriaInvalid = input.hasAttribute('aria-invalid');
+  const ariaInvalid = input.getAttribute('aria-invalid');
+  if (hasAriaInvalid && ariaInvalid === 'true') {
+    updateAriaState(event);
+  }
+});
+```
+
+## Fallbacking & Browser Support
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### Feature Detection
+You can check for support in CSS and JavaScript.
+
+**JavaScript Check:**
+```javascript
+if (!CSS.supports('selector(:user-invalid)')) {
+  // Fallback logic here
+}
+```
+
+### CSS for Fallback
+To ensure your fallback logic is visually indistinguishable from the native behavior, you must apply your error styles to both the pseudo-class and your fallback class.
+
+```css
+/* Apply error styles to both native selector and fallback class */
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+/* Show error message for both cases */
+input:user-invalid ~ .error-msg,
+input.user-invalid-fallback ~ .error-msg {
+  display: block;
+}
+```
+
+### Fallback Logic
+If `:user-invalid` is missing manually track the interaction state using a `WeakMap`.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset' && input.matches?.('form')) {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.matches?.('input, textarea, select')) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = () => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    document.addEventListener('blur', handleEvent, true); // Capture phase required
+    document.addEventListener('input', handleEvent, true);
+    document.addEventListener('change', handleEvent, true);
+    document.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize globally
+UserInvalidFallback.init();
+```
+
+## Other Considerations
+
+1.  **`aria-live` vs. `aria-errormessage`**: 
+    *   `aria-errormessage` connects the input to the text, but screen readers might not announce it immediately upon appearance (only when focusing the input).
+    *   If you need *immediate* announcement when the error appears (e.g., on blur), consider adding `role="alert"` or `aria-live="polite"` to the error message container, but test thoroughly to avoid "double announcement" when the user focuses the field to fix it.
+
+2.  **Internationalization**:
+    *   Ensure the text content of your error message (`#email-error`) is translated. The logic remains the same.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-generated-content.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-generated-content.md
new file mode 100644
index 00000000..e1dcf23c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/accessible-generated-content.md
@@ -0,0 +1,23 @@
+# Accessible generated content
+
+- **DON'T** use `content` to convey meaningful text (labels, state, instructions) — keep that in the DOM (WCAG F87). The alt text argument is harm reduction for cases where decoration accidentally carries meaning, not a license.
+- Use the alternative text argument of `content` to provide alt text for screen readers. E.g. `content: url(cloud.svg) / "Save";`
+- Use `content: "text" / "";` to prevent purely decorative text from being announced to screen readers.
+- **DON'T** use an empty alt text argument for images — they're already presentational by default. E.g. this is wrong: `content: url(cloud.svg) / "";`.
+- **DON'T** use the alt text argument to describe emojis unless the description differs from the official emoji name. E.g. don't do `content: "🎉" / "celebration";`, but `content: "🎉" / "Yay!";` is fine.
+
+**ONLY** use the alt text argument when the text is different than the primary value and is not already present in the DOM. I.e. this is wrong:
+
+HTML:
+```html
+<button class="save">Save</button>
+```
+
+CSS:
+```css
+button.save::before {
+  content: url(cloud.svg) / "Save";
+}
+```
+
+A screen reader would read it out as "Save save".
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/respect-os-text-scale.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/respect-os-text-scale.md
new file mode 100644
index 00000000..4ed75063
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/accessibility/respect-os-text-scale.md
@@ -0,0 +1,127 @@
+# Respect Operating System Text Scale
+
+## Overview
+
+Users with visual impairments often configure text scaling at the operating system level (such as Dynamic Type on iOS or Font Size scaling on Android/ChromeOS). By default, mobile browsers ignore these OS-level accessibility settings to prevent legacy, fixed-pixel websites from breaking visually.
+
+Instead of keeping your page static or relying on custom, fragile JavaScript layout calculations, opt into native operating system text scaling using the `<meta name="text-scale">` tag. When active, the browser dynamically scales the root font size (`1rem`) to match the user's OS preference, allowing all relative (`rem`/`em`) font sizes, layouts, and spacing to scale automatically and gracefully.
+
+## Implementation
+
+### 1. Opt Into OS Text Scaling
+
+Place the `<meta name="text-scale">` element inside your document's `<head>`. This signals to supporting browsers that your layout is modern, adaptive, and safe to scale:
+
+```html
+<head>
+  <meta charset="UTF-8" />
+  <meta name="viewport" content="width=device-width" />
+  
+  <!-- Opt this page into OS-level dynamic type and accessibility text scaling -->
+  <meta name="text-scale" content="scale" />
+  
+  <title>Adaptive Accessibility Layout</title>
+</head>
+```
+
+### 2. Use Relative Typography & Spacing
+
+Define font sizes using relative units (`rem` or `em`) rather than fixed pixels (`px`). Use unitless values for line heights so they scale proportionally with each element's computed font size.
+
+Use relative units for margins and padding where the spacing is coupled to text size or must adapt as text is scaled. Spacing that is independent of text may use fixed units when appropriate, provided that scaling does not cause text clipping, overlap, loss of content, or an unusable layout:
+
+```css
+body {
+  font-family: system-ui, sans-serif;
+  /* Inherits the root font-size, which scales automatically with the OS setting */
+  line-height: 1.5;      /* Unitless so it scales proportionally with computed font-size */
+  padding: 1.5rem;       /* Scales proportionally to prevent dense crowding at larger scales */
+}
+
+h1 {
+  font-size: 2.25rem;    /* Scales proportionally to the root base */
+  margin-bottom: 1rem;
+}
+```
+
+Set the base text size on `body` only when the design needs a size different from the inherited browser default; otherwise, let it inherit. Set sizes on specific elements, such as headings, with relative units such as `rem` or `em`. Use `rem` for a size relative to the root font size, and `em` when the size should depend on the parent element's font size. Do not set a custom font size on `:root` or `html`.
+
+#### Fluid Typography
+
+Fluid typography MAY use viewport-relative units such as `vw`, provided that font sizes also include a font-relative component such as `rem` or `em`. For more fluid-scaling techniques, including container query units and `clamp()`, see `fluid-scaling` (via `npx -y modern-web-guidance@latest retrieve "fluid-scaling"`).
+
+Avoid sizing text exclusively with viewport units:
+
+```css
+/* ❌ DO NOT DO THIS: The font size does not respond fully to user text scaling */
+.heading {
+  font-size: 5vw;
+}
+```
+
+Instead, combine a font-relative value with viewport-relative scaling and use relative minimum and maximum bounds:
+
+```css
+.heading {
+  font-size: clamp(2rem, 1.25rem + 2vw, 4rem);
+}
+```
+
+Test that text can be resized to at least 200% of its default size without loss of content or functionality. For fluid typography, a useful rule of thumb is to keep the maximum font size no more than 2.5 times the minimum. Also test reflow at a 320 CSS-pixel viewport width (equivalent to 400% zoom from a 1280 CSS-pixel-wide viewport); content MUST remain available without two-dimensional scrolling, except where essential.
+
+### 3. Use Scalable Responsive Breakpoints
+
+Responsive breakpoints MUST NOT assume that text will remain at its default size. Where a breakpoint is intended to respond to available space for text, prefer content-driven layouts, container queries, or `em`-based media queries rather than fixed pixel thresholds.
+
+Test responsive layouts with operating system text scaling and browser zoom enabled. Text MUST remain readable and content MUST remain visible without overlap, clipping, or horizontal scrolling.
+
+### 4. Ensure Content Wrapping & Flexible Heights
+
+When text scales up, elements require more vertical and horizontal space to prevent truncation or overlap. To keep your components robust, design your layouts to expand dynamically around the content rather than forcing rigid coordinates:
+
+* **Allow Text Containers to Grow**: Text-containing components and containers MUST be able to grow to accommodate scaled text. Avoid fixed `height` or `block-size` values and restrictive `max-height` or `max-block-size` values that can cause clipping or overflow. Prefer content-driven sizing; use `min-height` or `min-block-size` only when a minimum size is needed.
+* **Allow Natural Wrapping**: Do not restrict inline-axis text wrapping with `white-space: nowrap` on blocks that contain sentences. Let text reflow to new lines naturally.
+* **Employ Flexible Flexbox & Grid wrapping (Optional Example)**: For multi-column card galleries, use reflowing columns like `repeat(auto-fit, minmax(min(100%, 16rem), 1fr))` so items stack vertically if their relative width thresholds are crossed:
+
+```css
+/* Card container using min-height to ensure expansion and auto-fit to reflow if needed */
+.card {
+  padding: 1.5rem;
+  border: 1px solid #ccc;
+  border-radius: 8px;
+  /* Use min-height so the box expands vertically when the font is enlarged */
+  min-height: 10rem;
+}
+```
+
+### 5. DO NOT Override the Root Font Size
+
+When opting in via the `<meta name="text-scale" content="scale">` element, **DO NOT** explicitly set the root `font-size` in your stylesheet. This includes declarations on either `:root` or `html`, and applies to absolute units, relative units, and calculated values.
+
+For example, do not override the root font size with a fixed value:
+
+```css
+/* ❌ DO NOT DO THIS: This can prevent the browser from applying text scaling */
+html {
+  font-size: 16px;
+}
+```
+
+Do not combine the `<meta name="text-scale" content="scale">` opt-in with `env(preferred-text-scale)` to apply operating system text scaling manually. The browser applies the scale through the meta opt-in, so using both can result in double-scaling:
+
+```css
+/* ❌ DO NOT DO THIS: The meta opt-in already applies the operating system text scale */
+:root {
+  font-size: calc(1rem * env(preferred-text-scale));
+}
+```
+
+Leave the root font size to the browser. The browser handles the operating system text scale automatically and applies it to content sized relative to the root font size.
+
+## Fallback Strategies
+
+Browser support for <meta name="text-scale">: Limited availability.
+Supported by: Chrome 146 (Mar 2026) and Edge 146 (Mar 2026).
+Unsupported in: Firefox and Safari.
+
+On browsers where `<meta name="text-scale" content="scale">` is unsupported, the layout degrades gracefully. The page will display the layout at the browser's standard default base font size (typically 16px), and the user can still utilize standard manual page zoom or pinch-to-zoom options.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-detection.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-detection.md
new file mode 100644
index 00000000..4c156bfa
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-detection.md
@@ -0,0 +1,91 @@
+# Language Detection
+
+The **Language Detector API** is a client-side web API designed to identify the language of a given text string. By performing detection locally in the browser, it enhances user privacy and reduces the need for heavy external libraries or costly server-side calls.
+
+## Key Use Cases
+
+- **Translation Prep:** Identifying the source language before sending text to a translator.
+- **Safety & Filtering:** Loading specific models for tasks like toxicity detection.
+- **Accessibility:** Labeling content with the correct `lang` attribute for screen readers.
+- **UI Localization:** Adjusting application interfaces based on the user's input language.
+
+## Hardware & System Requirements
+
+- **OS:** Windows 10/11, macOS 13+, Linux, or Chromebook Plus.
+- **Storage:** 22 GB free space (model is removed if space drops below 10 GB).
+- **RAM/CPU:** 16 GB RAM and 4+ CPU cores.
+- **VRAM:** 4 GB+ if using a GPU.
+
+## Implementation Guide
+
+### 1. Model Management & User Activation
+
+Check model availability before attempting to instantiate the detector or trigger download.
+
+**MANDATORY:** Instantiating the language detector or triggering a model download with `LanguageDetector.create()` **MUST** be initiated by a user gesture (such as a button click) to prevent a `NotAllowedError` when the model is in a `downloadable` or `downloading` state.
+
+```javascript
+// Check if the model is available or downloadable
+const availability = await LanguageDetector.availability();
+
+if (availability !== 'unavailable') {
+  button.addEventListener('click', async () => {
+    const detector = await LanguageDetector.create({
+      monitor(m) {
+        m.addEventListener('downloadprogress', (e) => {
+          console.log(`Downloaded ${e.loaded * 100}%`);
+        });
+      },
+    });
+  });
+}
+```
+
+### 2. Running Detection
+
+The API returns a ranked list of potential languages with a confidence score between `0.0` and `1.0`.
+
+```javascript
+const someUserText = 'Hallo und herzlich willkommen!';
+const results = await detector.detect(someUserText);
+
+for (const result of results) {
+  // result.detectedLanguage (e.g., 'de')
+  // result.confidence (e.g., 0.999)
+  console.log(result.detectedLanguage, result.confidence);
+}
+```
+
+Avoid using the detector on very short phrases or single words, as accuracy drops significantly.
+
+## Security and Environment
+
+- **Iframes:** Cross-origin iframes require an explicit Permissions Policy to access the API.
+  ```html
+  <iframe
+    src="https://cross-origin.example.com/"
+    allow="language-detector"
+  ></iframe>
+  ```
+- **Web Workers:** The API is **not** currently available in Web Workers due to Permission Policy complexities.
+- **Privacy:** No data is sent to Google or third parties during the detection process.
+
+## Fallback Strategy
+
+Browser support for Language detector: Limited availability.
+Supported by: Chrome 138 (Jun 2025) and Edge 148 (May 2026).
+Unsupported in: Firefox and Safari.
+
+Before use, check if the `LanguageDetector` object is available in the global scope:
+
+```javascript
+if ('LanguageDetector' in self) {
+  // The Language Detector API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the `LanguageDetector` API is unsupported or availability checks return `'unavailable'`, you must gracefully fall back:
+1. **Remote API Fallback**: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API) to identify the language.
+2. **Graceful Degradation**: Disable language detection elements/buttons and inform the user that client-side detection is currently unsupported in this browser, preventing any unhandled exceptions or crashes.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-model.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-model.md
new file mode 100644
index 00000000..88ec832b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/language-model.md
@@ -0,0 +1,368 @@
+# Language Model
+
+The Prompt API allows developers to run natural language processing tasks directly in the browser using **Gemini Nano**. This built-in AI approach ensures user privacy, reduces server costs, and enables offline functionality.
+
+## 1. Getting Started and Hardware Requirements
+
+The Prompt API is currently available in Chrome as of version 148 (Desktop) for Windows, macOS, Linux, and Chromebook Plus.
+
+### Hardware Prerequisites
+
+- **Storage**: 22 GB free space (for the initial profile and model).
+- **Memory/CPU**: 16 GB RAM and 4+ CPU cores.
+- **GPU**: 4 GB VRAM or more (Required for audio input).
+- **Network**: Required only for the initial model download.
+
+### Initializing the API
+
+Check model availability before triggering a download:
+
+```javascript
+const availability = await LanguageModel.availability();
+
+// Do not call create() when unavailable — the model cannot run on this device.
+if (availability !== 'unavailable') {
+	const session = await LanguageModel.create({
+		monitor(m) {
+			// Inform the user while the model downloads so the UI doesn't appear frozen.
+			m.addEventListener('downloadprogress', (e) => {
+				console.log(`Downloaded ${e.loaded * 100}%`);
+			});
+		},
+	});
+}
+```
+
+## 2. Core Prompting Capabilities
+
+Session examples in this section omit `session.destroy()` for brevity. Always call `session.destroy()` when a session is no longer needed to free device memory (see Section 5).
+
+### Basic and Streamed Output
+
+For short responses, use `prompt()`. For longer content, use `promptStreaming()` to provide a more responsive UI.
+
+**MANDATORY**: Never assign model output to `innerHTML`. Model output is untrusted and can contain injected markup. Always use `textContent` or a sanitizer.
+
+```javascript
+const session = await LanguageModel.create();
+
+// prompt() accumulates the full response before resolving — use for short, one-shot output.
+const result = await session.prompt('Write a haiku about coding.');
+// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
+outputEl.textContent = result;
+
+// promptStreaming() yields independent chunks that must be concatenated;
+// use for longer content so each chunk can be rendered progressively.
+const stream = session.promptStreaming('Write a long story about a robot.');
+let completeResult = '';
+for await (const chunk of stream) {
+	completeResult += chunk;
+	outputEl.append(chunk);
+}
+console.log('Full story:', completeResult);
+```
+
+### Multimodal Input
+
+The Prompt API supports text, audio, and visual inputs (images, canvas, video frames).
+
+```javascript
+const session = await LanguageModel.create({
+	// Declaring expected input types lets the browser optimize model loading.
+	expectedInputs: [{ type: 'text' }, { type: 'image' }],
+	expectedOutputs: [{ type: 'text' }],
+});
+
+const response = await session.prompt([
+	{
+		role: 'user',
+		content: [
+			{ type: 'text', value: 'What is in this image?' },
+			{ type: 'image', value: document.querySelector('canvas') },
+		],
+	},
+]);
+```
+
+## 3. Advanced Session Management
+
+Sessions allow the model to maintain context across multiple interactions.
+
+### Context and Quota
+
+Each session has a maximum token limit. You can monitor usage via `session.contextUsage` and `session.contextWindow`. If the window overflows, the oldest messages (except the system prompt) are dropped.
+
+### Cloning Sessions
+
+Cloning is efficient for starting parallel conversations that share the same initial context (like a "system" personality) without re-initializing.
+
+```javascript
+const mainSession = await LanguageModel.create({
+	initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
+});
+
+const branchA = await mainSession.clone();
+const branchB = await mainSession.clone();
+// Destroy the base after cloning — the clones own their own context from here.
+mainSession.destroy();
+```
+
+### Restoring Past Sessions
+
+While a native "restore" feature is in development, you can recreate a session by feeding previous history into `initialPrompts`.
+
+**Note**: `localStorage` is unencrypted and persistent. Stored conversation history may include user PII — consider the privacy implications before persisting chat history.
+
+```javascript
+// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
+const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
+const session = await LanguageModel.create({
+	initialPrompts: history, // Array of {role, content} objects
+});
+```
+
+## 4. Structured Output with JSON Schema
+
+To prevent the model from adding "chatter" (e.g., "Sure, here is your JSON:"), use a **JSON Schema** via the `responseConstraint` field. This ensures the output is valid JSON that can be parsed immediately.
+
+### Example: Sentiment Classification
+
+```javascript
+// Pass the schema as a plain object — do not JSON.stringify() it first.
+const schema = {
+	type: 'object',
+	properties: {
+		rating: { type: 'number', minimum: 1, maximum: 5 },
+		is_positive: { type: 'boolean' },
+	},
+	required: ['rating', 'is_positive'],
+};
+
+const result = await session.prompt(
+	"Rate the following feedback: 'The food was great!'",
+	{ responseConstraint: schema },
+);
+
+const data = JSON.parse(result);
+console.log(data.rating); // 5
+```
+
+### Constraints and Prefixes
+
+You can guide the model further by prefilling the assistant's response using `prefix: true`.
+
+````javascript
+const character = await session.prompt([
+	{ role: 'user', content: 'Create a character sheet' },
+	{ role: 'assistant', content: '```json\n', prefix: true },
+]);
+````
+
+## 5. Best Practices and Safety
+
+- **Resource Cleanup**: Always call `session.destroy()` when a conversation is finished to free up memory.
+- **Output Safety**: Model output is untrusted. Always write results to `textContent`, not `innerHTML`, to prevent XSS injection from malicious model output.
+- Use a sanitizer like the native Sanitizer API or DOMPurify if you need to allow limited HTML.
+- **Aborting Tasks**: Use `AbortController` to allow users to stop long-running generations. Pass the `signal` to `prompt()` or `promptStreaming()`, not to `LanguageModel.create()`.
+- **Security**: Use Permission Policies to control access in iframes: `<iframe src="..." allow="language-model"></iframe>`.
+- **Design**: Review the [People + AI Guidebook](https://pair.withgoogle.com/guidebook/) to ensure responsible AI implementation.
+
+By combining structured outputs with robust session management, developers can build complex, stateful AI applications that run entirely on the user's device.
+
+### Dos and Don'ts
+
+For the full detailed list of dos and don'ts, see https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt. Below is the gist:
+
+#### Prepare the model at a reasonable time
+
+*Applies to: all APIs, for example, Summarizer, Translator, and Writer.*
+
+**Do:** Initialize the session as soon as you've clearly established the user's intention to use the AI feature, for example, when a user navigates into a relevant AI tools surface, hovers over an AI workspace, or interacts with the feature's surrounding UI. Pre-warming the session allows the model to load into memory quietly in the background while the user is setting up their task, eliminating avoidable cold-start latency.
+Try to be one step ahead by starting the next most likely AI task as soon as you start rendering the current result, for example, if the feature is designed for iterative use.
+
+**Don't:** Unless necessary, don't wait for the user to click "Generate" to initialize the session. This leads to a cold start delay, because the model must first load into memory and prepare its execution pipeline.
+
+> [!CAUTION]
+> **Caution:** For the Prompt API, wait until you have the `initialPrompts` ready before calling `create()`, because these can only be set during session creation.
+
+#### Set initial prompts during creation
+
+*Applies to: Prompt API.*
+
+**Do:** Provide system instructions during session initialization to improve the
+speed of the first prompt.
+
+**Don't:** Start with an empty session and send system instructions as part of
+the first `prompt()` call. This increases latency because it forces the model to
+process those instructions at the last moment.
+
+#### Clone sessions for repetitive tasks
+
+*Applies to: Prompt API.*
+
+For the Prompt API, each session [tracks the context of the
+conversation](https://developer.chrome.com/docs/ai/prompt-api?content_ref=each+session+keeps+track+of+the+context+of+the+conversation+previous+interactions+are+taken+into+account+for+future+interactions+until+the+session+s+context+window+is+full),
+taking all previous interactions into account. Because a clone inherits
+everything from its parent session, including initial prompts and all
+interaction history up to the point of cloning, structure your usage to inherit
+only what you need.
+
+**Do:**
+
+- Create a base session: To handle unrelated tasks efficiently, create a base session that contains only your system instructions and no previous conversational context.
+- Clone the baseline: Use `clone()` on that base session for new tasks to save the overhead of re-parsing system instructions. This lets you create parallel conversations or reset a task to its baseline.
+
+**Don't:**
+
+- Don't reuse the same session for unrelated tasks, and avoid cloning any session that already contains unnecessary interaction history. Both patterns can cause unrelated previous context to interfere with your current task.
+- Don't repeatedly call `create()` with identical system instructions. Use the cloning pattern instead to optimize performance.
+
+#### Destroy unused sessions
+
+*Applies to: All APIs.*
+
+**Do:** Explicitly call [`destroy()`](https://developer.chrome.com/docs/ai/prompt-api#terminate_a_session) on
+sessions that you no longer need, to free up memory when a feature
+is no longer in use. If you use a cloning pattern, keep the base session and
+destroy the clones you no longer need.
+
+**Don't:** Keep multiple large sessions active. Each session consumes memory,
+which creates unnecessary resource usage and might become a problem. Sessions
+will be naturally cleaned up by the garbage collector, but calling `destroy()`
+frees up memory more quickly.
+
+#### Render streaming responses safely and efficiently
+
+*Applies to: All APIs with streaming support (Prompt, Summarizer, Writer,
+Rewriter, and Translator).*
+
+**Do:** Treat all LLM output as untrusted content. Sanitize the full combined
+output, not just chunks, because malicious code could be split across updates.
+Before rendering, use the [Sanitizer
+API](https://developer.mozilla.org/docs/Web/API/HTML_Sanitizer_API) where
+supported. To avoid a decrease in performance, use a streaming Markdown parser
+like [streaming-markdown](https://github.com/thetarnav/streaming-markdown).
+
+**Don't:** Directly set `innerHTML` on every chunk update. This is slow,
+especially with complex formatting like syntax highlighting, and vulnerable to
+injection.
+
+#### Optimize input for speed
+
+*Applies to: All APIs.*
+
+**Do:** Only pass to the model what's strictly needed. Strip everything that's
+irrelevant to the task at hand. For large datasets, provide a short overview and
+a small selection of relevant items.
+
+**Don't:** Send raw unprocessed text, unnecessary metadata, HTML tags, or large
+unfiltered lists to the APIs. Latency grows significantly with input size, which
+can make the AI feature seem broken on many devices.
+
+#### Use structured output for predictable results
+
+*Applies to: Prompt API.*
+
+**Do:** When you need the model to return data in a specific format, use
+[structured
+output](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api?content_ref=he+prompt+api+lets+you+specify+a+json+output+format+of+the+model+s+response+by+passing+a+json+schema+to+the+languagemodel+prompt+and+languagemodel+promptstreaming+methods)
+by providing a `responseConstraint` field to provide a JSON Schema. This ensures
+the output is predictable and prevents you from needing complex post-processing
+or manual parsing.
+
+**Don't:** Rely on natural language instructions (like "output only JSON")
+alone. Models might include conversational filler that breaks your parser.
+
+#### Decouple generation from length constraints
+
+*Applies to: Prompt API, as it's the only API that supports [structured output
+schemas](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api).*
+
+**Do:** Let the model generate its response naturally, and then use client-side
+logic to truncate the text to fit your UI.
+
+**Don't:** Enforce strict character limits like `maxLength: 125` using
+[structured output schemas](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api). When a
+model's response is longer than the limit you set, the model might switch to
+high-density tokens like foreign languages or emoji to compress meaning,
+resulting in nonsensical output.
+
+#### Keep the user informed
+
+*Applies to: All APIs.*
+
+**Do:** Depending on the complexity and expected duration of the task, use animations, visual cues, and progress indicators to keep the user informed. The
+optimal approach depends on your use case and the expected length of the API
+output. Some ideas:
+
+- Streaming for long content: For summaries or chat, streaming creates a per-token typewriter effect by default. This can feel natural and provide immediate feedback.
+- Non-streaming for short tasks (or long async tasks): For short outputs, for example, alt-text, non-streaming can create a more polished UI. It also provides time to speculatively prepare the next AI task while the current one renders. This approach also works for longer asynchronous or background tasks. If the user is not blocked on the output to continue their journey, there is no urgent need to produce the output as it happens. Signal that the process is ongoing in the UI.
+- Visual transitions for updates: When translating or rewriting text, use animations, for example, word-morphing.
+
+**Don't:** Update the UI without visual cues.
+
+#### Align with the user's mental model of time and work
+
+*Applies to: All APIs.*
+
+**Do:** Consider an artificial delay of one or two seconds if a response is
+nearly instant. Paradoxically, users might find results more trustworthy when
+they perceive a generation process that aligns with their perceived difficulty
+of the task. Use animations to signal that an AI process has occurred.
+
+**Don't:** Surprise users with instant UI replacements.
+
+#### Allow users to quickly navigate and undo AI edits
+
+*Applies to: All APIs.*
+
+**Do:** Equip your UI with a stepper or navigation history that lets users
+explore different results confidently, and let them quickly undo AI edits. This
+ensures that different versions are still readily available.
+
+**Don't:** Overwrite the user's previous draft, or an AI result they might have
+liked without a way to go back, revert, or compare versions.
+
+#### Empower user control and overrides
+
+*Applies to: All APIs.*
+
+**Do:** Make the user the final editor of all generated content. Provide intuitive overrides so the user maintains full ownership for the final output. The APIs may produce incorrect results.
+
+**Don't:** Force an AI-generated result as the only option.
+
+#### Cache results for repeated tasks
+
+*Applies to: All APIs.*
+
+**Do:** Implement a local result cache (for example, using `sessionStorage` or
+`IndexedDB`) for repeated inputs or queries. Normalize the input by trimming
+whitespace and lowercasing to increase cache hits. For heavy inputs, for
+example, images, generate a hash to use as a cache key. Set a conservative
+time to live (TTL) for your cache (or serve cached results while updating them
+in the background). Let the user trigger a fresh inference if the result is
+unsatisfying.
+
+**Don't:** Re-run the same inference for a repeated search query or identical data input where variability isn't desirable, for example when a user navigates back and forth between search results.
+This optimizes responsiveness and efficient use of local compute.
+
+## 6. Fallback strategies
+
+Browser support for LanguageModel: Limited availability.
+Supported by: Chrome 148 (May 2026).
+Unsupported in: Edge, Firefox, and Safari.
+
+Before use, check if the LanguageModel object is available in the global scope:
+
+```js
+if ('LanguageModel' in self) {
+  // The Prompt API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the Prompt API is unsupported or availability checks return 'unavailable', you must gracefully fall back:
+
+* Remote API Fallback: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API).
+* Local API Fallback: Redirect the detection request to a local endpoint, for example, using Transformers.js. 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/prompt-api.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/prompt-api.md
new file mode 100644
index 00000000..88ec832b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/prompt-api.md
@@ -0,0 +1,368 @@
+# Language Model
+
+The Prompt API allows developers to run natural language processing tasks directly in the browser using **Gemini Nano**. This built-in AI approach ensures user privacy, reduces server costs, and enables offline functionality.
+
+## 1. Getting Started and Hardware Requirements
+
+The Prompt API is currently available in Chrome as of version 148 (Desktop) for Windows, macOS, Linux, and Chromebook Plus.
+
+### Hardware Prerequisites
+
+- **Storage**: 22 GB free space (for the initial profile and model).
+- **Memory/CPU**: 16 GB RAM and 4+ CPU cores.
+- **GPU**: 4 GB VRAM or more (Required for audio input).
+- **Network**: Required only for the initial model download.
+
+### Initializing the API
+
+Check model availability before triggering a download:
+
+```javascript
+const availability = await LanguageModel.availability();
+
+// Do not call create() when unavailable — the model cannot run on this device.
+if (availability !== 'unavailable') {
+	const session = await LanguageModel.create({
+		monitor(m) {
+			// Inform the user while the model downloads so the UI doesn't appear frozen.
+			m.addEventListener('downloadprogress', (e) => {
+				console.log(`Downloaded ${e.loaded * 100}%`);
+			});
+		},
+	});
+}
+```
+
+## 2. Core Prompting Capabilities
+
+Session examples in this section omit `session.destroy()` for brevity. Always call `session.destroy()` when a session is no longer needed to free device memory (see Section 5).
+
+### Basic and Streamed Output
+
+For short responses, use `prompt()`. For longer content, use `promptStreaming()` to provide a more responsive UI.
+
+**MANDATORY**: Never assign model output to `innerHTML`. Model output is untrusted and can contain injected markup. Always use `textContent` or a sanitizer.
+
+```javascript
+const session = await LanguageModel.create();
+
+// prompt() accumulates the full response before resolving — use for short, one-shot output.
+const result = await session.prompt('Write a haiku about coding.');
+// textContent, not innerHTML — model output is untrusted and must not be parsed as markup.
+outputEl.textContent = result;
+
+// promptStreaming() yields independent chunks that must be concatenated;
+// use for longer content so each chunk can be rendered progressively.
+const stream = session.promptStreaming('Write a long story about a robot.');
+let completeResult = '';
+for await (const chunk of stream) {
+	completeResult += chunk;
+	outputEl.append(chunk);
+}
+console.log('Full story:', completeResult);
+```
+
+### Multimodal Input
+
+The Prompt API supports text, audio, and visual inputs (images, canvas, video frames).
+
+```javascript
+const session = await LanguageModel.create({
+	// Declaring expected input types lets the browser optimize model loading.
+	expectedInputs: [{ type: 'text' }, { type: 'image' }],
+	expectedOutputs: [{ type: 'text' }],
+});
+
+const response = await session.prompt([
+	{
+		role: 'user',
+		content: [
+			{ type: 'text', value: 'What is in this image?' },
+			{ type: 'image', value: document.querySelector('canvas') },
+		],
+	},
+]);
+```
+
+## 3. Advanced Session Management
+
+Sessions allow the model to maintain context across multiple interactions.
+
+### Context and Quota
+
+Each session has a maximum token limit. You can monitor usage via `session.contextUsage` and `session.contextWindow`. If the window overflows, the oldest messages (except the system prompt) are dropped.
+
+### Cloning Sessions
+
+Cloning is efficient for starting parallel conversations that share the same initial context (like a "system" personality) without re-initializing.
+
+```javascript
+const mainSession = await LanguageModel.create({
+	initialPrompts: [{ role: 'system', content: 'You speak like a pirate.' }],
+});
+
+const branchA = await mainSession.clone();
+const branchB = await mainSession.clone();
+// Destroy the base after cloning — the clones own their own context from here.
+mainSession.destroy();
+```
+
+### Restoring Past Sessions
+
+While a native "restore" feature is in development, you can recreate a session by feeding previous history into `initialPrompts`.
+
+**Note**: `localStorage` is unencrypted and persistent. Stored conversation history may include user PII — consider the privacy implications before persisting chat history.
+
+```javascript
+// || '[]' ensures JSON.parse never receives null when the key doesn't exist yet.
+const history = JSON.parse(localStorage.getItem('chat_history') || '[]');
+const session = await LanguageModel.create({
+	initialPrompts: history, // Array of {role, content} objects
+});
+```
+
+## 4. Structured Output with JSON Schema
+
+To prevent the model from adding "chatter" (e.g., "Sure, here is your JSON:"), use a **JSON Schema** via the `responseConstraint` field. This ensures the output is valid JSON that can be parsed immediately.
+
+### Example: Sentiment Classification
+
+```javascript
+// Pass the schema as a plain object — do not JSON.stringify() it first.
+const schema = {
+	type: 'object',
+	properties: {
+		rating: { type: 'number', minimum: 1, maximum: 5 },
+		is_positive: { type: 'boolean' },
+	},
+	required: ['rating', 'is_positive'],
+};
+
+const result = await session.prompt(
+	"Rate the following feedback: 'The food was great!'",
+	{ responseConstraint: schema },
+);
+
+const data = JSON.parse(result);
+console.log(data.rating); // 5
+```
+
+### Constraints and Prefixes
+
+You can guide the model further by prefilling the assistant's response using `prefix: true`.
+
+````javascript
+const character = await session.prompt([
+	{ role: 'user', content: 'Create a character sheet' },
+	{ role: 'assistant', content: '```json\n', prefix: true },
+]);
+````
+
+## 5. Best Practices and Safety
+
+- **Resource Cleanup**: Always call `session.destroy()` when a conversation is finished to free up memory.
+- **Output Safety**: Model output is untrusted. Always write results to `textContent`, not `innerHTML`, to prevent XSS injection from malicious model output.
+- Use a sanitizer like the native Sanitizer API or DOMPurify if you need to allow limited HTML.
+- **Aborting Tasks**: Use `AbortController` to allow users to stop long-running generations. Pass the `signal` to `prompt()` or `promptStreaming()`, not to `LanguageModel.create()`.
+- **Security**: Use Permission Policies to control access in iframes: `<iframe src="..." allow="language-model"></iframe>`.
+- **Design**: Review the [People + AI Guidebook](https://pair.withgoogle.com/guidebook/) to ensure responsible AI implementation.
+
+By combining structured outputs with robust session management, developers can build complex, stateful AI applications that run entirely on the user's device.
+
+### Dos and Don'ts
+
+For the full detailed list of dos and don'ts, see https://developer.chrome.com/docs/ai/built-in-ai-dos-donts.md.txt. Below is the gist:
+
+#### Prepare the model at a reasonable time
+
+*Applies to: all APIs, for example, Summarizer, Translator, and Writer.*
+
+**Do:** Initialize the session as soon as you've clearly established the user's intention to use the AI feature, for example, when a user navigates into a relevant AI tools surface, hovers over an AI workspace, or interacts with the feature's surrounding UI. Pre-warming the session allows the model to load into memory quietly in the background while the user is setting up their task, eliminating avoidable cold-start latency.
+Try to be one step ahead by starting the next most likely AI task as soon as you start rendering the current result, for example, if the feature is designed for iterative use.
+
+**Don't:** Unless necessary, don't wait for the user to click "Generate" to initialize the session. This leads to a cold start delay, because the model must first load into memory and prepare its execution pipeline.
+
+> [!CAUTION]
+> **Caution:** For the Prompt API, wait until you have the `initialPrompts` ready before calling `create()`, because these can only be set during session creation.
+
+#### Set initial prompts during creation
+
+*Applies to: Prompt API.*
+
+**Do:** Provide system instructions during session initialization to improve the
+speed of the first prompt.
+
+**Don't:** Start with an empty session and send system instructions as part of
+the first `prompt()` call. This increases latency because it forces the model to
+process those instructions at the last moment.
+
+#### Clone sessions for repetitive tasks
+
+*Applies to: Prompt API.*
+
+For the Prompt API, each session [tracks the context of the
+conversation](https://developer.chrome.com/docs/ai/prompt-api?content_ref=each+session+keeps+track+of+the+context+of+the+conversation+previous+interactions+are+taken+into+account+for+future+interactions+until+the+session+s+context+window+is+full),
+taking all previous interactions into account. Because a clone inherits
+everything from its parent session, including initial prompts and all
+interaction history up to the point of cloning, structure your usage to inherit
+only what you need.
+
+**Do:**
+
+- Create a base session: To handle unrelated tasks efficiently, create a base session that contains only your system instructions and no previous conversational context.
+- Clone the baseline: Use `clone()` on that base session for new tasks to save the overhead of re-parsing system instructions. This lets you create parallel conversations or reset a task to its baseline.
+
+**Don't:**
+
+- Don't reuse the same session for unrelated tasks, and avoid cloning any session that already contains unnecessary interaction history. Both patterns can cause unrelated previous context to interfere with your current task.
+- Don't repeatedly call `create()` with identical system instructions. Use the cloning pattern instead to optimize performance.
+
+#### Destroy unused sessions
+
+*Applies to: All APIs.*
+
+**Do:** Explicitly call [`destroy()`](https://developer.chrome.com/docs/ai/prompt-api#terminate_a_session) on
+sessions that you no longer need, to free up memory when a feature
+is no longer in use. If you use a cloning pattern, keep the base session and
+destroy the clones you no longer need.
+
+**Don't:** Keep multiple large sessions active. Each session consumes memory,
+which creates unnecessary resource usage and might become a problem. Sessions
+will be naturally cleaned up by the garbage collector, but calling `destroy()`
+frees up memory more quickly.
+
+#### Render streaming responses safely and efficiently
+
+*Applies to: All APIs with streaming support (Prompt, Summarizer, Writer,
+Rewriter, and Translator).*
+
+**Do:** Treat all LLM output as untrusted content. Sanitize the full combined
+output, not just chunks, because malicious code could be split across updates.
+Before rendering, use the [Sanitizer
+API](https://developer.mozilla.org/docs/Web/API/HTML_Sanitizer_API) where
+supported. To avoid a decrease in performance, use a streaming Markdown parser
+like [streaming-markdown](https://github.com/thetarnav/streaming-markdown).
+
+**Don't:** Directly set `innerHTML` on every chunk update. This is slow,
+especially with complex formatting like syntax highlighting, and vulnerable to
+injection.
+
+#### Optimize input for speed
+
+*Applies to: All APIs.*
+
+**Do:** Only pass to the model what's strictly needed. Strip everything that's
+irrelevant to the task at hand. For large datasets, provide a short overview and
+a small selection of relevant items.
+
+**Don't:** Send raw unprocessed text, unnecessary metadata, HTML tags, or large
+unfiltered lists to the APIs. Latency grows significantly with input size, which
+can make the AI feature seem broken on many devices.
+
+#### Use structured output for predictable results
+
+*Applies to: Prompt API.*
+
+**Do:** When you need the model to return data in a specific format, use
+[structured
+output](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api?content_ref=he+prompt+api+lets+you+specify+a+json+output+format+of+the+model+s+response+by+passing+a+json+schema+to+the+languagemodel+prompt+and+languagemodel+promptstreaming+methods)
+by providing a `responseConstraint` field to provide a JSON Schema. This ensures
+the output is predictable and prevents you from needing complex post-processing
+or manual parsing.
+
+**Don't:** Rely on natural language instructions (like "output only JSON")
+alone. Models might include conversational filler that breaks your parser.
+
+#### Decouple generation from length constraints
+
+*Applies to: Prompt API, as it's the only API that supports [structured output
+schemas](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api).*
+
+**Do:** Let the model generate its response naturally, and then use client-side
+logic to truncate the text to fit your UI.
+
+**Don't:** Enforce strict character limits like `maxLength: 125` using
+[structured output schemas](https://developer.chrome.com/docs/ai/structured-output-for-prompt-api). When a
+model's response is longer than the limit you set, the model might switch to
+high-density tokens like foreign languages or emoji to compress meaning,
+resulting in nonsensical output.
+
+#### Keep the user informed
+
+*Applies to: All APIs.*
+
+**Do:** Depending on the complexity and expected duration of the task, use animations, visual cues, and progress indicators to keep the user informed. The
+optimal approach depends on your use case and the expected length of the API
+output. Some ideas:
+
+- Streaming for long content: For summaries or chat, streaming creates a per-token typewriter effect by default. This can feel natural and provide immediate feedback.
+- Non-streaming for short tasks (or long async tasks): For short outputs, for example, alt-text, non-streaming can create a more polished UI. It also provides time to speculatively prepare the next AI task while the current one renders. This approach also works for longer asynchronous or background tasks. If the user is not blocked on the output to continue their journey, there is no urgent need to produce the output as it happens. Signal that the process is ongoing in the UI.
+- Visual transitions for updates: When translating or rewriting text, use animations, for example, word-morphing.
+
+**Don't:** Update the UI without visual cues.
+
+#### Align with the user's mental model of time and work
+
+*Applies to: All APIs.*
+
+**Do:** Consider an artificial delay of one or two seconds if a response is
+nearly instant. Paradoxically, users might find results more trustworthy when
+they perceive a generation process that aligns with their perceived difficulty
+of the task. Use animations to signal that an AI process has occurred.
+
+**Don't:** Surprise users with instant UI replacements.
+
+#### Allow users to quickly navigate and undo AI edits
+
+*Applies to: All APIs.*
+
+**Do:** Equip your UI with a stepper or navigation history that lets users
+explore different results confidently, and let them quickly undo AI edits. This
+ensures that different versions are still readily available.
+
+**Don't:** Overwrite the user's previous draft, or an AI result they might have
+liked without a way to go back, revert, or compare versions.
+
+#### Empower user control and overrides
+
+*Applies to: All APIs.*
+
+**Do:** Make the user the final editor of all generated content. Provide intuitive overrides so the user maintains full ownership for the final output. The APIs may produce incorrect results.
+
+**Don't:** Force an AI-generated result as the only option.
+
+#### Cache results for repeated tasks
+
+*Applies to: All APIs.*
+
+**Do:** Implement a local result cache (for example, using `sessionStorage` or
+`IndexedDB`) for repeated inputs or queries. Normalize the input by trimming
+whitespace and lowercasing to increase cache hits. For heavy inputs, for
+example, images, generate a hash to use as a cache key. Set a conservative
+time to live (TTL) for your cache (or serve cached results while updating them
+in the background). Let the user trigger a fresh inference if the result is
+unsatisfying.
+
+**Don't:** Re-run the same inference for a repeated search query or identical data input where variability isn't desirable, for example when a user navigates back and forth between search results.
+This optimizes responsiveness and efficient use of local compute.
+
+## 6. Fallback strategies
+
+Browser support for LanguageModel: Limited availability.
+Supported by: Chrome 148 (May 2026).
+Unsupported in: Edge, Firefox, and Safari.
+
+Before use, check if the LanguageModel object is available in the global scope:
+
+```js
+if ('LanguageModel' in self) {
+  // The Prompt API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the Prompt API is unsupported or availability checks return 'unavailable', you must gracefully fall back:
+
+* Remote API Fallback: Redirect the detection request to a server endpoint or a cloud API (such as the Vertex AI Gemini API).
+* Local API Fallback: Redirect the detection request to a local endpoint, for example, using Transformers.js. 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/summarizer.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/summarizer.md
new file mode 100644
index 00000000..f8c59265
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/summarizer.md
@@ -0,0 +1,156 @@
+# Summarizer
+
+The **Summarizer API** allows web developers to offer local, AI-powered text distillation directly within the browser using **Gemini Nano in Chrome or Phi in Edge**. This API supports various formats, including key points, headlines, and TL;DRs, while operating entirely on-device to ensure user privacy.
+
+---
+
+## Getting Started
+
+The Summarizer API is available starting in **Chrome and Edge 138**. It requires a one-time model download of Gemini Nano or Phi (respectively).
+
+
+### Hardware & Software Requirements
+
+- **OS**: Windows 10/11, macOS 13+, Linux, or ChromeOS (Chromebook Plus).
+- **Storage**: 22GB free space for the profile volume.
+- **RAM/CPU**: 16GB+ RAM and 4+ CPU cores.
+- **VRAM**: 4GB+ (if using GPU).
+
+### Model Download and Availability
+
+Check if the model is ready, needs downloading, or is unavailable. 
+
+**Mandatory Options Passing:** You must pass the identical configuration options object to both `Summarizer.availability(options)` and `Summarizer.create(options)`. Do NOT use the deprecated `window.ai.summarizer` API surface.
+
+**Mandatory Progress Monitoring:** You MUST implement a monitor for model download progress by providing a `monitor(m)` callback to `Summarizer.create()` and adding a listener for the `downloadprogress` event.
+
+**User Gesture Requirement:** When `availability` is `'downloadable'` or `'downloading'`, triggering the actual download via `Summarizer.create()` requires a user gesture (such as a user click). You must place the creation call inside an event listener rather than calling it unconditionally on page load to prevent `NotAllowedError`.
+
+```javascript
+const options = {
+  type: 'key-points',
+  format: 'plain-text',
+  length: 'medium'
+};
+
+const availability = await Summarizer.availability(options);
+
+if (availability === 'available') {
+  const summarizer = await Summarizer.create(options);
+  // Ready to use immediately
+} else if (availability === 'downloadable') {
+  // A user gesture is strictly required to start the download
+  document.getElementById('start-download-btn').addEventListener('click', async () => {
+    const summarizer = await Summarizer.create({
+      ...options,
+      monitor(m) {
+        m.addEventListener('downloadprogress', (e) => {
+          console.log(`Downloaded ${Math.round((e.loaded / e.total) * 100)}%`);
+        });
+      },
+    });
+  });
+}
+```
+
+## API Functions & Configuration
+
+When creating a summarizer via `Summarizer.create(options)`, you can customize
+the output:
+
+| Parameter    | Options                                    | Description                             |
+| :----------- | :----------------------------------------- | :-------------------------------------- |
+| `type`       | `key-points`, `tldr`, `teaser`, `headline` | Defines the summary strategy.           |
+| `format`     | `markdown`, `plain-text`                   | Output syntax style.                    |
+| `length`     | `short`, `medium`, `long`                  | Target length (e.g., 1 vs 5 sentences). |
+| `preference` | `auto`, `speed`, `capability`              | Balances latency vs. quality.           |
+
+### Example Configuration
+
+```javascript
+const options = {
+  sharedContext: 'This is a scientific article',
+  type: 'key-points',
+  format: 'markdown',
+  length: 'medium',
+};
+
+if (navigator.userActivation.isActive) {
+  const summarizer = await Summarizer.create(options);
+}
+```
+
+### Language Support
+
+You can specify expected languages to ensure the browser can handle the specific
+summary request.
+
+```javascript
+const summarizer = await Summarizer.create({
+  type: 'key-points',
+  expectedInputLanguages: ['en', 'ja'],
+  outputLanguage: 'es',
+});
+```
+
+## Summarization Methods
+
+### 1. Batch Summarization
+
+Processes the entire text at once and returns the result.
+
+```javascript
+const longText = document.querySelector('article').innerText;
+const summary = await summarizer.summarize(longText, {
+  context: 'This article is intended for a tech-savvy audience.',
+});
+console.log(summary);
+```
+
+### 2. Stream Summarization
+
+Returns results in real-time as the model generates them, providing a more
+responsive UI.
+
+```javascript
+const stream = summarizer.summarizeStreaming(longText);
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Security and Permissions
+
+- **Data Privacy**: No data is sent to Google; processing happens on the local
+  device.
+- **Cross-Origin**: Access can be granted to iframes using the Permission
+  Policy.
+  ```html
+  <iframe src="https://example.com/" allow="summarizer"></iframe>
+  ```
+- **Web Workers**: Currently not supported.
+
+## Fallback Strategy
+
+Browser support for Summarizer: Limited availability.
+Supported by: Chrome 138 (Jun 2025) and Edge 138 (Jun 2025).
+Unsupported in: Firefox and Safari.
+
+Before initializing or querying availability, check if the browser supports the `Summarizer` API:
+
+```javascript
+if ('Summarizer' in self) {
+  // The Summarizer API is supported.
+} else {
+  // Execute fallback strategy
+}
+```
+
+If the `Summarizer` API is unsupported or availability checks return `'unavailable'`, you must gracefully fall back.
+
+Recommended options:
+1. **Remote API Fallback**: Direct the distillation request to a server endpoint or remote API (such as the Vertex AI Gemini API) so that users still get summaries.
+2. **Graceful Degradation**: Visually disable the summarization controls in the UI, or hide the button while displaying a friendly message (e.g., `"Local summarization is currently unsupported in this browser"`). Do not allow interaction to trigger generic unhandled runtime exceptions.
+3. **Polyfill Fallback**: You can use community-maintained polyfills like `built-in-ai-task-apis-polyfills` or `prompt-api-polyfill` to emulate the API surface using remote services with models in the cloud or on-device inference with local models.
+
+> **Privacy and Cost Implications:** These polyfills possibly proxy requests to remote servers (such as Gemini API over the cloud). This completely nullifies the on-device privacy guarantees of the native Built-in AI APIs and will incur server-side API usage costs.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/translator.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/translator.md
new file mode 100644
index 00000000..a9b8229f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/built-in-ai/translator.md
@@ -0,0 +1,189 @@
+# Translator
+
+The **Translator API** allows developers to perform client-side text translation using built-in AI models in Chrome and Edge. This approach eliminates the need for cloud-based translation services for ephemeral content, reducing costs and improving privacy by keeping data on the user's device.
+
+
+## Prerequisites & Requirements
+
+### API Surface & Global Scope
+
+- **MANDATORY:** Access the Translator API exclusively via the global `Translator` interface (`window.Translator` / `self.Translator`).
+- **DO NOT** use or check the deprecated `window.ai.translator` namespace.
+
+### Browser Support
+
+- **Chrome:** Version 138+ (Desktop only).
+- **Edge:** Version 148+ (Desktop only).
+- **Not Supported:** Mobile (Android/iOS), Firefox, Safari.
+
+### Hardware Requirements
+
+To run Gemini Nano and associated models, the system needs:
+
+- **Operating System:** Windows 10/11, macOS 13+, Linux, or ChromeOS (Chromebook
+  Plus).
+- **Storage:** At least **22 GB** free on the profile volume.
+- **Memory/CPU:** 16 GB+ RAM and 4+ CPU cores.
+- **GPU:** 4 GB+ VRAM (Mandatory for Prompt API with audio).
+- **Network:** Required only for the initial download of language packs/models.
+
+## Implementation & Code Samples
+
+### 1. Checking Availability & Model Management
+
+**Mandatory Options Passing:** You must pass the identical configuration options object containing `sourceLanguage` and `targetLanguage` to both `Translator.availability(options)` and `Translator.create(options)`.
+
+**Recommended Progress Monitoring:** You should implement a monitor for model download progress by providing a `monitor(m)` callback to `Translator.create()` and adding a listener for the `downloadprogress` event, so the user can see model download progress.
+
+**User Gesture Requirement:** When calling `availability(options)` returns `'downloadable'` or `'downloading'`, calling `Translator.create()` triggers the download of the language pack and **strictly requires a user gesture** (such as a button click) to prevent a `NotAllowedError`.
+
+`Translator.availability(options)` returns one of four string statuses:
+- `'available'`: The language pair model is already downloaded on the device and ready for immediate translation.
+- `'downloadable'`: The language pair is supported, but the model needs to be downloaded. A user gesture is required to initiate `Translator.create()`.
+- `'downloading'`: The language pack is currently in the process of downloading. Calling `Translator.create()` with a user gesture attaches to the download.
+- `'unavailable'`: The language pair or device is not supported. Execute your fallback strategy.
+
+```javascript
+// Language pair options passed to both availability() and create()
+const options = {
+  sourceLanguage: 'es', // Example BCP 47 language code
+  targetLanguage: 'fr', // Example BCP 47 language code
+};
+
+// 1. Check availability for the language pair
+const availability = await Translator.availability(options);
+
+if (availability === 'available') {
+  // Model is ready immediately on device
+  const translator = await Translator.create(options);
+} else if (availability === 'downloadable' || availability === 'downloading') {
+  // User gesture is strictly required before create() triggers or attaches to download
+  document.getElementById('start-translation-btn').addEventListener('click', async () => {
+    const translator = await Translator.create({
+      ...options,
+      monitor(m) {
+        m.addEventListener('downloadprogress', (e) => {
+          console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
+        });
+      },
+    });
+  });
+} else if (availability === 'unavailable') {
+  // Language pair or hardware unsupported; execute fallback
+  console.warn('Translation model is unavailable on this device.');
+}
+```
+
+### 2. Executing Translations
+
+The API supports both static and streaming responses. Always include download progress monitoring when instantiating the translator.
+
+**Standard Translation:**
+
+```javascript
+// Default to including a progress monitor when creating translator
+const translator = await Translator.create({
+  sourceLanguage: 'en',
+  targetLanguage: 'fr',
+  monitor(m) {
+    m.addEventListener('downloadprogress', (e) => {
+      console.log(`Downloaded ${Math.round(e.loaded * 100)}%`);
+    });
+  },
+});
+
+const result = await translator.translate(
+  'Where is the next bus stop, please?',
+);
+console.log(result);
+// Output: "Où est le prochain arrêt de bus, s'il vous plaît ?"
+```
+
+**Streaming Translation (for long text):**
+
+```javascript
+const stream = translator.translateStreaming(longText);
+for await (const chunk of stream) {
+  console.log(chunk);
+}
+```
+
+## Supported Languages
+
+The API supports a wide range of BCP 47 language codes: Here are the languages supported by Chrome's implementation of the Translator API:
+
+- **ar**: Arabic
+- **bg**: Bulgarian
+- **bn**: Bengali
+- **cs**: Czech
+- **da**: Danish
+- **de**: German
+- **el**: Greek
+- **en**: English
+- **es**: Spanish
+- **fi**: Finnish
+- **fr**: French
+- **hi**: Hindi
+- **hr**: Croatian
+- **hu**: Hungarian
+- **id**: Indonesian
+- **it**: Italian
+- **he**: Hebrew
+- **ja**: Japanese
+- **kn**: Kannada
+- **ko**: Korean
+- **lt**: Lithuanian
+- **mr**: Marathi
+- **nl**: Dutch
+- **no**: Norwegian
+- **pl**: Polish
+- **pt**: Portuguese
+- **ro**: Romanian
+- **ru**: Russian
+- **sk**: Slovak
+- **sl**: Slovenian
+- **sv**: Swedish
+- **ta**: Tamil
+- **te**: Telugu
+- **th**: Thai
+- **tr**: Turkish
+- **uk**: Ukrainian
+- **vi**: Vietnamese
+- **zh**: Chinese
+- **zh-Hant**: Chinese (Traditional)
+
+## Security & Performance
+
+- **Permissions Policy:** Cross-origin iframes require explicit permission.
+  ```html
+  <iframe src="https://example.com/" allow="translator"></iframe>
+  ```
+- **Web Workers:** Currently **not supported** due to Permission Policy
+  complexities.
+- **Privacy:** No data is sent to Google servers during the translation process
+  once the model is downloaded.
+
+## Fallback Strategy
+
+Browser support for Translator: Limited availability.
+Supported by: Chrome 138 (Jun 2025) and Edge 148 (May 2026).
+Unsupported in: Firefox and Safari.
+
+Before use, check if the `Translator` object is available in the global scope:
+
+```javascript
+if ('Translator' in self) {
+  // The Translator API is supported.
+} else {
+  // Execute fallback strategy (do not fall back to window.ai.translator).
+}
+```
+
+If the `Translator` API is unsupported or availability checks return `'unavailable'`, you must gracefully fall back. 
+
+Recommended options:
+1. **Remote API Fallback**: Redirect the translation request to a server endpoint or cloud remote API (such as the Vertex AI Gemini API) to deliver translation functionality.
+2. **Graceful Degradation**: Visually disable translation control elements or buttons while showing an end-user friendly note (e.g., `"Client-side translation is currently unsupported in this browser"`). Do not allow unhandled exceptions.
+3. **Polyfill Fallback**: You can use community-maintained polyfills like `built-in-ai-task-apis-polyfills` or `prompt-api-polyfill` to emulate the API surface using remote services.
+
+> **Privacy and Cost Implications:** These polyfills possibly proxy requests to remote servers (such as Gemini API over the cloud), though local processing is an option, too. Remote processing completely nullifies the on-device privacy guarantees of the native Built-in AI APIs and will often incur server-side API usage costs.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md
new file mode 100644
index 00000000..5a94c61f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/animate-to-intrinsic-sizes.md
@@ -0,0 +1,128 @@
+# Animate to Intrinsic Sizes
+
+Animating elements to dynamic sizes like `block-size: auto` or `inline-size: max-content` has historically required JavaScript or fragile "max-height" hacks. The `interpolate-size` property and `calc-size()` function allow the browser to natively interpolate between fixed lengths and intrinsic sizing keywords.
+
+## Implementation steps
+
+1.  **Opt-in to keyword interpolation**: Apply `interpolate-size: allow-keywords` to a parent element (typically `:root`) to enable transitions for properties using intrinsic keywords.
+2.  **Define the transition**: Set a `transition` for the sizing property (e.g., `block-size`, `inline-size`) on the target element.
+3.  **Use intrinsic keywords**: Change the sizing property to a supported intrinsic keyword—`auto`, `min-content`, `max-content`, `fit-content`, or (for flex-basis) `content`—during an interaction (e.g., `:hover` or a state class).
+4.  **Perform calculations (Optional)**: Use `calc-size()` if you need to perform math on an intrinsic size (e.g., `auto + 2rem`). `calc-size()` also supports the `any` keyword for basis-agnostic calculations.
+
+## Example: Generic Expansion Pattern
+
+You can apply this pattern to any container (like a "Show More" section or a navigation menu) to transition between a restricted height and the element's natural size.
+
+```css
+/* Opt-in globally for all children */
+:root {
+  /* MANDATORY: Transitions to intrinsic keywords are disabled by default for compatibility */
+  interpolate-size: allow-keywords;
+}
+
+.expandable-container {
+  /* 1. Define a fixed initial size (or 0) and hide overflow */
+  block-size: 100px;
+  overflow: hidden;
+  
+  /* 2. Transition the sizing property */
+  transition: block-size 0.4s ease-out;
+}
+
+.expandable-container.is-expanded {
+  /* 3. Smoothly animate to the intrinsic natural height */
+  block-size: auto;
+}
+```
+
+## Example: Calculated Intrinsic Inline-Size
+
+```css
+.badge {
+  inline-size: 40px;
+  overflow: hidden;
+  white-space: nowrap;
+  transition: inline-size 0.3s ease;
+}
+
+.badge:hover {
+  /* calc-size(basis, calculation) */
+  /* 'size' refers to the evaluated basis (max-content in this case) */
+  inline-size: calc-size(max-content, size + 20px);
+}
+```
+
+## Example: Transition from Intrinsic to Fixed
+
+You can also animate in the opposite direction—starting from a natural size and collapsing to a specific length. This is useful for "dismissible" components.
+
+```css
+.collapsible-alert {
+  /* 1. Start with the natural content height */
+  block-size: auto;
+  overflow: hidden;
+  transition: block-size 0.5s ease-in-out, opacity 0.5s ease;
+}
+
+.collapsible-alert.is-dismissed {
+  /* 2. Smoothly collapse to zero */
+  block-size: 0;
+  opacity: 0;
+  pointer-events: none;
+}
+
+/* MANDATORY Copy-Paste Safety: Disable sizing animations for sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .expandable-container,
+  .badge,
+  .collapsible-alert {
+    transition: none !important;
+  }
+}
+```
+
+```javascript
+// MANDATORY Accessibility Synchronization: Ensure elements collapsed to zero dimensions are removed from the assistive technology tree, and sync aria-expanded states on triggers.
+const alertElement = document.querySelector('.collapsible-alert');
+alertElement.addEventListener('transitionend', (e) => {
+  if (e.propertyName === 'block-size' && alertElement.classList.contains('is-dismissed')) {
+    alertElement.hidden = true;
+  }
+});
+
+// Example trigger syncer
+const triggerBtn = document.querySelector('.accordion-trigger');
+triggerBtn?.addEventListener('click', () => {
+  const isExpanded = triggerBtn.getAttribute('aria-expanded') === 'true';
+  triggerBtn.setAttribute('aria-expanded', !isExpanded);
+});
+```
+
+## Key constraints
+
+*   **Keyword-to-Keyword Restriction**: You cannot animate between two different keywords directly (e.g., from `min-content` to `max-content`). One end of the transition must be a fixed length or percentage (e.g., `0` to `auto`).
+*   **Calc-size Syntax**: Inside `calc-size()`, you cannot mix different intrinsic keywords in the same expression. The first argument (the basis) defines what `size` represents.
+*   **Opt-in Requirement**: Transitions to intrinsic keywords are disabled by default (`numeric-only`) to maintain backward compatibility. You must apply `interpolate-size: allow-keywords` to the element or an ancestor. `calc-size()` acts as a per-property override, automatically enabling interpolation whenever it is used.
+
+## Fallback strategies
+
+Browser support for interpolate-size: Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+Browser support for calc-size(): Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+`interpolate-size` and `calc-size()` are progressive enhancements. Browsers that do not support them will perform an instant jump to the target size.
+
+*   **Graceful Degradation**: For simple `block-size: auto` transitions, standard browsers will simply toggle the size instantly, which is functional but less polished.
+*   **Manual keyword fallbacks**: When using `calc-size()`, always provide a standard keyword fallback for older browsers, as they will discard the entire `calc-size()` declaration.
+
+```css
+.card {
+  block-size: auto; /* Fallback for older browsers */
+  block-size: calc-size(auto, size); /* Modern browsers use this */
+  transition: block-size 0.3s ease;
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/atrule-support-conditionals.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/atrule-support-conditionals.md
new file mode 100644
index 00000000..b368095e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/atrule-support-conditionals.md
@@ -0,0 +1,148 @@
+# Conditionally Apply CSS Based on At-Rule Support
+
+Use `@supports at-rule(@<at-rule name>) {…}` to conditionally apply certain CSS rules or declarations only if a certain at-rule is supported by the browser.
+This can contain entire rules, or be used in conjunction with CSS nesting to conditionally apply certain declarations.
+
+```css
+.foo {
+  background: var(--accent-color);
+
+  @supports at-rule(@property) {
+    background-image: var(--rainbow-gradient);
+    animation: sliding-rainbow 1s linear infinite;
+  }
+}
+```
+
+Do NOT use `@supports at-rule()` to conditionally apply the at-rule being detected and nothing else.
+
+```css
+/* BAD: CSS already ignores rules the browser doesn't understand, so this is unnecessary */
+@supports at-rule(@starting-style) {
+  @starting-style {
+    /* ... */
+  }
+}
+```
+
+## Detecting support for at-rules when `@supports at-rule()` isn’t appropriate { #detecting-at-rules-without-supports-at-rule }
+
+When `at-rule()` is not an option, either due to browser support or because deeper detection is needed, you can use the guidance below.
+
+### Try properties, values, or selectors first
+
+`@supports` can already detect properties, values, and selectors (via `@supports selector(...)`).
+In many cases, you can use these to detect support for a feature without needing to check for the at-rule itself.
+
+For example, instead of `@supports at-rule(@function)` to detect supports for custom functions, you can use `@supports (color: --foo())`.
+
+In other cases there may be pseudo-classes or pseudo-elements that are only available when a certain at-rule is supported, which can be used to detect support.
+
+### Detecting container query types { #supports-container-types }
+
+`at-rule()` ONLY allows detection of at-rules by **name**.
+It does NOT allow detection of other syntax or descriptors.
+E.g. this will not work:
+
+```css
+@supports at-rule(@container style(--a: 1)) {
+  /* ... */
+}
+```
+
+For many types of container queries, you can use `container-type` with a suitable value.
+E.g. `@supports (container-type: scroll-state)` for scroll-state queries or `@supports (container-type: size)`container-type: anchored` for `anchored()` queries.
+
+However, there is no `container-type` for style queries.
+IMPORTANT: Do NOT try `@supports (container-type: style)` to detect support for style queries, as this will not work.
+
+Instead, you can try a style query that is always true:
+
+```css
+@container style(--a: 1) or (not (style(--a: 1))) {
+  /* Rules here will only be applied if style queries are supported */
+}
+```
+
+This will match in any browser that supports style queries, regardless of what property name or value you use, provided they are the same across both.
+
+### Registered custom properties (`@property`) { #supports-atproperty }
+
+In some cases, if the conditional CSS to apply can be reduced to a single property, you can use a dedicated custom property registered for this purpose:
+
+```css
+/* Use a custom property to conditionally include the dash animation */
+@property --progress-dash-animation {
+  syntax: "*";
+  inherits: false;
+  initial-value: , progress-dash 3s ease-in-out infinite;
+}
+
+.spinner {
+  /* The dash animation is only included if @property is supported */
+  animation:
+    progress-spin var(--_used-spinner-duration) linear infinite
+    var(--progress-dash-animation, );
+}
+```
+
+
+For a more general-purpose solution, you can register a non-inheriting property and set it to ` ` (a space) on the root element:
+
+{# Testcase: https://codepen.io/leaverou/pen/KwWzpVr #}
+
+```css
+@property --supports-atproperty {
+	syntax: "*";
+	inherits: false;
+}
+
+:root {
+	--supports-atproperty: ;
+}
+
+body {
+  /* The background is only applied if @property is supported */
+	background: var(--supports-atproperty, green);
+}
+```
+
+Notes:
+- Both of these only work if whitespace is an acceptable alternative. For other cases, you will need to use JS as described below.
+- The general-purpose solution depends on non-inheritance, so it will not work for declarations on the root element.
+
+### Using JavaScript as a last resort
+
+For entire at-rules, check for the presence of certain interfaces in JavaScript.
+For example, if `globalThis.CSSFunctionRule` is defined, then `@function` is supported.
+
+If you need to test more deeply (e.g. for certain preludes, nested rules, descriptors), you can set up a test and check how it was parsed:
+
+```js
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(`
+  @page {
+    @top-left {
+      content: "test";
+    }
+  }
+`);
+const SUPPORTS_PAGE_MARGINS = Boolean(sheet.cssRules[0]?.cssRules?.[0]);
+```
+
+IMPORTANT:
+- When using JS to detect support for CSS features, do NOT apply the styles from JS directly. Instead, apply a class to the root element and branch off that in CSS.
+- Do note that container queries are parsed even if the prelude is not recognized, and there is no way to detect support for certain types of container queries from the CSSOM structure.
+- Do NOT use `CSS.registerProperty` to detect support for `@property` as its support is slightly broader.
+
+## Fallback strategies
+
+Browser support for at-rule(): Limited availability.
+Supported by: Chrome 148 (May 2026), Edge 148 (May 2026), and Firefox 157 (Sep 2026).
+Unsupported in: Safari.
+
+Unless this is within your support target, **ONLY** use `@supports (at-rule())` to detect at-rules for which support is narrower than the `@supports (at-rule())` feature itself.
+
+To conditionally apply CSS based on support for at-rules that shipped before this feature, use [the guidance in the section above](#detecting-at-rules-without-supports-at-rule).
+
+To detect support for the `@supports at-rule()` feature _itself_, you can use an at-rule that is guaranteed to exist in all browsers that support `@supports at-rule()`, such as `@supports at-rule(@media) { ... }`.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/calculate-with-intrinsic-sizes.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/calculate-with-intrinsic-sizes.md
new file mode 100644
index 00000000..128620a0
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/calculate-with-intrinsic-sizes.md
@@ -0,0 +1,199 @@
+# Calculate With Intrinsic Sizes
+
+`calc-size()` is a CSS function for performing mathematical operations on intrinsic sizing keywords like `auto`, `min-content`, and `fit-content`. **MANDATORY**: Use `calc-size()` only when you need to modify an intrinsic size with a calculation or constraint; for simple keyword-based animations (e.g., `0` to `auto`), you must use `interpolate-size: allow-keywords`.
+
+## Implementation Steps
+
+1. **Identify the Intrinsic Basis**: Determine which intrinsic keyword (`auto`, `min-content`, etc.) should form the base of your calculation.
+2. **Define Constraints**: Use CSS math functions like `clamp()`, `min()`, or `max()` within the second argument to enforce design constraints on the intrinsic size.
+3. **MANDATORY: Provide a Fallback**: Always declare a standard sizing keyword or length immediately before the property using `calc-size()` to ensure the layout remains functional in unsupported browsers.
+4. **Apply Logical Properties**: Default to using logical properties like `inline-size` or `block-size` to ensure the calculations respect the document's writing mode.
+5. **Optional: Progressive Enhancement**: Wrap complex layout logic or animations in a `@supports (inline-size: calc-size(auto, size + 0px))` block to deliver advanced features only to capable browsers.
+
+## Basic Syntax
+
+```css
+/* calc-size(<calc-size-basis>, <calc-sum>) — mathematical operations on intrinsic sizing keywords */
+.element {
+  /* MANDATORY: Always provide a fallback for browsers that do not support calc-size() */
+  inline-size: min-content;
+  
+  /* DO: Use calc-size to modify an intrinsic basis with a calculation or function */
+  inline-size: calc-size(min-content, size + 2rem);
+}
+```
+
+### Valid Basis Arguments (`<calc-size-basis>`)
+The first argument defines the "base" size for the calculation.
+
+**Standard Keywords:**
+- `auto`: The default sizing for the element.
+- `min-content`: The smallest size the element can take without overflowing.
+- `max-content`: The size the element takes to fit all content on one line.
+- `fit-content`: Equivalent to `clamp(min-content, auto, max-content)`.
+- `content`: Only valid when `calc-size()` is used within the `flex-basis` property.
+
+**Special Arguments:**
+- `any`: A generic basis used when the specific intrinsic type is unknown or when nesting calculations.
+- Nested `calc-size()`: Allows for multi-step or conditional calculations.
+- `<calc-sum>`: A specific length, percentage, or mathematical expression (e.g., `100px` or `20%`). When a fixed value is used as the basis, the **`size` keyword is still available** (but only within the second argument) and represents the resolved value of that basis.
+
+**MANDATORY**: The `size` keyword is **not valid** within the first argument (`<calc-size-basis>`) itself. It is a local variable that only exists to refer back to the basis from within the second argument (`<calc-sum>`).
+
+### Valid Calculation Arguments (`<calc-sum>`)
+The second argument is the mathematical expression.
+- It typically uses the `size` keyword to refer to the value of the basis.
+- While the `size` keyword is technically optional, omitting it means the calculation will resolve to a fixed value, ignoring the basis entirely.
+- It can include standard math operators (`+`, `-`, `*`, `/`).
+- It can include CSS math functions like `clamp()`, `min()`, `max()`, and `round()`.
+- **MANDATORY**: `calc-size()` only allows a **single** intrinsic size value (the basis) in each calculation. You cannot mix intrinsic sizing keywords in the same `calc-size()` call.
+
+## Use Cases
+
+### Animating to and from Intrinsic Sizes
+By default, browsers cannot interpolate between a length (e.g., `0px`) and an intrinsic keyword (e.g., `auto`). Wrapping the keyword in `calc-size()` makes it an interpolatable value.
+
+#### Choosing the Right Tool for Animations
+- **MANDATORY: Use `interpolate-size: allow-keywords`**: For simple animations to or from intrinsic sizes (e.g., `height: 0` to `height: auto`) without any mathematical modifications. This is the required approach for simple keyword interpolation and should ideally be applied globally via `:root`.
+
+  ```css
+  :root {
+    /* Best practice: Enable keyword interpolation globally */
+    interpolate-size: allow-keywords;
+  }
+
+  .item {
+    height: 0;
+    transition: height 0.3s ease;
+  }
+
+  .item.open {
+    /* Simple interpolation from 0 to auto now works without calc-size() */
+    height: auto;
+  }
+  ```
+
+- **Use `calc-size()`**: ONLY when you need to perform mathematical calculations on an intrinsic size during a transition (e.g., adding padding or clamping the size).
+
+```css
+.accordion-content {
+  display: block;
+  overflow: hidden;
+  /* MANDATORY: Fallback value for closed state */
+  block-size: 0;
+  transition: block-size 0.3s ease-out;
+}
+
+.accordion-content.open {
+  /* MANDATORY: Fallback value for open state */
+  block-size: auto;
+
+  /* 
+    DO: Use calc-size(auto, ...) to enable animation from 0 to the element's 
+    intrinsic size while doing a calculation (in this case, adding a space of 2rem).
+  */
+  block-size: calc-size(auto, size + 2rem);
+}
+```
+
+**MANDATORY**: Interpolation between two intrinsic sizing keywords is not possible directly. One end of the transition must be a length or a percentage.
+
+#### Respecting User Motion Preferences
+Animations that change the size of large layout areas can be particularly disruptive for users with vestibular disorders. **MANDATORY**: Always respect user motion preferences by using the `prefers-reduced-motion` media query to simplify or minimize non-essential animations. Common strategies include disabling motion entirely, reducing duration, or replacing layout shifts with subtle opacity transitions.
+
+```css
+.accordion-content {
+  opacity: 0;
+  transition: block-size 0.3s ease, opacity 0.3s ease;
+}
+
+.accordion-content.open {
+  opacity: 1;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .accordion-content {
+    /* 
+       EXAMPLE: Replacing disruptive layout animations with a subtle fade-in.
+       Setting the block-size instantly and transitioning opacity 
+       provides a clear state change without large-scale motion.
+    */
+    transition: opacity 1.5s ease;
+  }
+
+  .accordion-content.open {
+    /* Jump the size instantly */
+    block-size: auto;
+  }
+}
+```
+
+
+### Applying Constraints to Intrinsic Sizes
+You can use `calc-size()` with any CSS math function—such as `min()`, `max()`, `clamp()`, or `round()`—to ensure an element's intrinsic size remains within design boundaries.
+
+```css
+.dynamic-container {
+  /* MANDATORY: Always provide a fallback for browsers that do not support calc-size() */
+  inline-size: fit-content;
+
+  /* 
+    DO: Establish a dynamic size based on content, while:
+    1. Enforcing boundaries using CSS math functions (min, clamp, etc.)
+    2. Modifying the intrinsic size with fixed or relative offsets
+  */
+  inline-size: calc-size(fit-content, min(size + var(--extra-space), var(--max-allowed)));
+}
+```
+
+## Critical Considerations
+
+- **Percentage Pitfalls**: Percentages inside the `<calc-sum>` are resolved against the **container's size**, not the `size` keyword. For example, `calc-size(auto, size + 10%)` adds 10% of the *parent's* width to the element's `auto` width, which may lead to unexpected results or overflows.
+- **Calculations requirement**: **MANDATORY**: Use `interpolate-size: allow-keywords` instead of `calc-size()` for simple animations (e.g., `0` to `auto`). `calc-size()` should only be used when the layout requires dynamic mathematical adjustments to the intrinsic base.
+- **Performance Note**: Animating box model properties like `inline-size` or `block-size` triggers layout recalculations, which can be expensive. Use `calc-size()` animations primarily for layout-critical elements where non-layout alternatives are insufficient.
+
+## Fallback strategies
+
+Browser support for calc-size(): Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+Browser support for interpolate-size: Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+`calc-size()` and `interpolate-size` are **progressive enhancements**. In browsers that do not support them, the properties will be ignored and the layout will remain functional, though animations to intrinsic keywords will jump instead of transitioning. Always provide a standard keyword or length as a fallback.
+
+```css
+.element {
+  /* Fallback for browsers that don't support calc-size() */
+  inline-size: fit-content; 
+  /* Modern browsers will override the fallback */
+  inline-size: calc-size(fit-content, size + 2rem);
+}
+```
+
+### Animation and Transition Fallbacks
+In browsers without support for `calc-size()` or `interpolate-size`, transitions involving intrinsic sizing keywords will fail to interpolate. 
+
+- **Graceful Degradation**: The default fallback is an "instant jump" between states (e.g., from `0` to `auto`). This is often acceptable as the layout remains functional.
+- **Enhanced Experience**: Use `@supports` to apply complex layout logic or additional styling that only makes sense when smooth intrinsic animations are possible.
+- **Avoid JS-based measurements**: While you could use JavaScript to measure elements and manually animate their dimensions, this is often unnecessary and can lead to layout thrashing. Relying on the native "instant jump" is the recommended fallback for modern web applications.
+
+For animations, the fallback experience will be an instant jump to the final size. To detect support in CSS or JavaScript:
+
+```css
+/* CSS Feature Detection */
+@supports (inline-size: calc-size(auto, size + 0px)) {
+  .element {
+    /* Apply advanced logic only when supported */
+  }
+}
+```
+
+```javascript
+/* JavaScript Feature Detection */
+if (CSS.supports('inline-size', 'calc-size(auto, size + 0px)')) {
+  // Apply advanced sizing or animations
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/child-state-based-styling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/child-state-based-styling.md
new file mode 100644
index 00000000..2c9a3143
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/child-state-based-styling.md
@@ -0,0 +1,103 @@
+# Child State Based Styling
+
+Historically, CSS selectors could only traverse downwards—you could style a child based on its parent, but not a parent based on its child. The `:has()` pseudo-class changes this, allowing you to conditionally style a container element depending on the presence or state of its descendants.
+
+By combining `:has()` with state pseudo-classes (like `:checked`, `:focus`, `:valid`, `:invalid`, or `:not()`), you can build complex, interactive UI components entirely in CSS, without needing JavaScript to toggle "modifier" classes (like `.is-active` or `.has-error`) on parent elements.
+
+This is particularly useful for components that need to respond to internal interactions, such as a localized theme toggle reacting to a checkbox (`:checked`), a form group highlighting an error (`:invalid`), or a card elevating when a child link is focused (`:focus-within`).
+
+### Implementing state-based container styling
+
+**MANDATORY**: You must use the `:has()` selector on the container element to detect the specific state (e.g., `:checked`, `:focus`, `:invalid`) of its interactive child element.
+
+To build a component that changes its styling based on a child's state:
+
+1. **Define the default styling**: Set CSS variables on the container to define its base state.
+2. **Apply state-based overrides**: Target the container with `:has([child-selector]:[state])` and redefine the CSS variables for the active or alternate state.
+
+*Example: A component that changes theme based on a child toggle.*
+
+```css
+/* 1. Define the default state on the component container */
+.theme-card {
+  /* Using custom properties makes state-switching cleaner */
+  --card-bg: #ffffff;
+  --card-text: #333333;
+  --card-border: #cccccc;
+
+  background-color: var(--card-bg);
+  color: var(--card-text);
+  border: 1px solid var(--card-border);
+
+  /* Use a transition for smooth state changes */
+  transition: background-color 0.3s, color 0.3s;
+}
+
+/* 2. Apply styles when the child enters the specific state */
+/* MANDATORY: Target the container and use :has() to check the descendant's state */
+.theme-card:has(.theme-toggle:checked) {
+  /* Override the properties for the active or alternate state */
+  --card-bg: #222222;
+  --card-text: #f0f0f0;
+  --card-border: #555555;
+}
+/* You can also combine :has() and :not() to target specific negative states */
+/* This selects a card that DOES NOT have a toggle in the checked state */
+.theme-card:not(:has(.theme-toggle:checked)) {
+  /* Optional: Explicit styles for the unchecked state if needed */
+}
+```
+
+```html
+<!-- The container element that receives the styling -->
+<div class="theme-card">
+  <!-- The child element whose state controls the parent -->
+  <label>
+    <input type="checkbox" class="theme-toggle">
+    Enable Dark Mode
+  </label>
+
+  <h2>Card Title</h2>
+  <p>The style of this entire card is controlled by the checkbox above.</p>
+</div>
+```
+
+**Performance tip**: When using `:has()`, scope the selector to the most specific container possible (like `.theme-card`). Avoid anchoring it to very high-level elements like `body:has(...)` if the styling changes are localized, as broad `:has()` queries can trigger more layout recalculations.
+
+### Fallback strategies
+
+Baseline status for :has(): Widely available. It's been Baseline since 2023-12-19.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 121 (Dec 2023), and Safari 15.4 (Mar 2022).
+
+If the state-based styling is critical to the user experience or page layout, you must provide a fallback for browsers that do not support the `:has()` selector. For purely decorative effects, `:has()` can be used as a progressive enhancement without a fallback.
+
+**MANDATORY**: When implementing a fallback for critical features, you must use `@supports not selector(:has(*))` in your CSS to define a traditional class-based fallback. If the critical state change relies on user interaction, you must also use a small inline script with `CSS.supports()` to toggle that class based on the equivalent JavaScript event (e.g., `change`, `focus`, `blur`) representing the state change.
+
+```css
+/* Fallback CSS for older browsers */
+/* We check if the browser DOES NOT support the :has() selector */
+@supports not selector(:has(*)) {
+  /* Define a traditional modifier class that applies the exact same overrides */
+  .theme-card.is-active {
+    --card-bg: #222222;
+    --card-text: #f0f0f0;
+    --card-border: #555555;
+  }
+}
+```
+
+```javascript
+/* Fallback JavaScript for older browsers */
+/* Check for support before running the script to avoid unnecessary work in modern browsers */
+if (!CSS.supports('selector(:has(*))')) {
+  const toggle = document.querySelector('.theme-toggle');
+  const card = document.querySelector('.theme-card');
+
+  if (toggle && card) {
+    // Manually toggle the fallback class when the input state changes
+    toggle.addEventListener('change', (e) => {
+      card.classList.toggle('is-active', e.target.checked);
+    });
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/content-based-styling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/content-based-styling.md
new file mode 100644
index 00000000..2841d56c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/content-based-styling.md
@@ -0,0 +1,120 @@
+# Content Based Styling
+
+Historically, applying different layouts to a component based on its content required either JavaScript or conditional logic in your HTML templating language to inject modifier classes (like `.card--has-image` or `.card--text-only`).
+
+The `:has()` pseudo-class eliminates this need by acting as a parent selector. It allows you to conditionally style a container element based on the presence or absence of specific descendant elements.
+
+Using `:has()`, you can easily define distinct layout variations entirely in CSS based on a component's actual DOM content. You can also optionally combine it with `:not()` to explicitly target the *absence* of content to define default layouts.
+
+### Implementing content-based container styling
+
+**MANDATORY**: You must use the `:has()` selector on the container element to detect the presence of specific child content.
+
+To build a component that changes its layout based on its content:
+
+1. **Define the default styling**: Apply the base layout styles to the container element (e.g., a simple single-column stack).
+2. **Apply content-based overrides**: Target the container with `:has([child-selector])` and apply the new layout styles for when that content is present (e.g., a multi-column grid).
+
+*Example: A card component that switches to a side-by-side layout if an image is present.*
+
+```css
+/* 1. Define the default state on the component container */
+/* This applies when there is NO image */
+.article-card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+  padding: 1.5rem;
+  border: 1px solid #ccc;
+  border-radius: 8px;
+}
+
+/* 2. Apply styles when a specific child element is present */
+/* MANDATORY: Target the container and use :has() to check for the descendant */
+.article-card:has(img) {
+  /* Change the layout to a row if an image exists */
+  flex-direction: row;
+  align-items: center;
+}
+
+/* Optional: Style the image itself (no :has() needed here) */
+.article-card img {
+  width: 150px;
+  height: auto;
+  border-radius: 4px;
+}
+
+/* You can also combine :has() and :not() to explicitly target the ABSENCE of content */
+/* This selects a card that DOES NOT have an image */
+.article-card:not(:has(img)) {
+  /* E.g., apply a different background color for text-only cards */
+  background-color: #f9f9f9;
+}
+```
+
+```html
+<!-- Assume an <h1> precedes these components in the document layout -->
+<!-- A card WITH an image (will use row layout) -->
+<article class="article-card">
+  <img src="thumbnail.jpg" alt="Article thumbnail" />
+  <div class="content">
+    <h2>Card With Image</h2>
+    <p>This card lays out its content horizontally.</p>
+  </div>
+</article>
+
+<!-- A card WITHOUT an image (will use default column layout) -->
+<article class="article-card">
+  <div class="content">
+    <h2>Text-Only Card</h2>
+    <p>This card lays out its content vertically, and gets its background color from the :not(:has()) rule.</p>
+  </div>
+</article>
+```
+
+**Performance tip**: When using `:has()`, scope the selector to the most specific component container possible (like `.article-card`). Avoid anchoring it to very high-level elements like `body:has(img)` if the styling changes are highly localized, as broad `:has()` queries can trigger more layout recalculations.
+
+### Fallback strategies
+
+Baseline status for :has(): Widely available. It's been Baseline since 2023-12-19.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 121 (Dec 2023), and Safari 15.4 (Mar 2022).
+
+If the content-based layout styling is critical to the user experience or page design, you must provide a fallback for browsers that do not support the `:has()` selector. For purely decorative effects, `:has()` can be used as a progressive enhancement without a fallback.
+
+**MANDATORY**: When implementing a fallback for critical layouts, you must use `@supports not selector(:has(*))` in your CSS to define a traditional class-based fallback (e.g., `.has-image`).
+
+Unlike interactive state-based styling, content presence is typically known at render time. The most robust fallback is to have your server-side templating engine (or static site generator) inject a class like `.has-image` onto the container if the child element (like an image) exists in the data.
+
+If server-side rendering is not an option, you must use a small script with `CSS.supports()` to detect the content and append the class on load or after dynamic content injection.
+
+```css
+/* Fallback CSS for older browsers */
+/* We check if the browser DOES NOT support the :has() selector */
+@supports not selector(:has(*)) {
+  /* Define a traditional modifier class that applies the exact same layout overrides */
+  .article-card.has-image {
+    flex-direction: row;
+    align-items: center;
+  }
+  
+  .article-card:not(.has-image) {
+    background-color: #f9f9f9;
+  }
+}
+```
+
+```javascript
+/* Fallback JavaScript for older browsers (if not using SSR to add the class) */
+/* Check for support before running the script to avoid unnecessary work in modern browsers */
+if (!CSS.supports('selector(:has(*))')) {
+  // Find all components that need checking
+  const cards = document.querySelectorAll('.article-card');
+  
+  cards.forEach(card => {
+    // If the critical content exists, manually add the fallback class
+    if (card.querySelector('img')) {
+      card.classList.add('has-image');
+    }
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css-layout.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css-layout.md
new file mode 100644
index 00000000..2a59b955
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css-layout.md
@@ -0,0 +1,317 @@
+# CSS Layouts and Responsive Design
+
+1. [1 Fundamentals](#1-fundamentals)
+   1. [Which layout mode to use?](#11-which-layout-mode-to-use)
+   2. [Working principles](#12-working-principles)
+2. [2 Flexbox](#2-flexbox)
+3. [3 Grid and subgrid](#3-grid-and-subgrid)
+   1. [Code example: grid and subgrid](#31-code-example-grid-and-subgrid)
+4. [4 Container queries](#4-container-queries)
+   1. [Code example: fluid typography using container query units](#41-code-example-fluid-typography-using-container-query-units)
+5. [5 Native overlays, anchor positioning, and stacking contexts](#5-native-overlays-anchor-positioning-and-stacking-contexts)
+6. [6 Overflow tracking and layout stability](#6-overflow-tracking-and-layout-stability)
+7. [7 Viewport mechanics and track distribution](#7-viewport-mechanics-and-track-distribution)
+8. [8 Grid lanes (aka masonry)](#8-grid-lanes-aka-masonry)
+
+## 1 Fundamentals
+
+Lean on the browser's layout engine when possible for better performance. Reach for intrinsic sizing, logical properties, and `aspect-ratio` before resorting to hardcoded dimensions or complicated media-queries.
+
+### 1.1 Which layout mode to use?
+
+Walk the decision tree top-to-bottom and stop at the first match. Note that layouts can be nested within each-other and each decision is based on the use-case for that container.
+
+1. **Is it a simple row OR column of items?** Use **flexbox** — 1D, content-first, content distributes along a single axis.
+2. **Does a nested element need to line up with its grandparent grid's tracks?** Use **subgrid** — 2D, relationship-first, inherits parent tracks so grandchildren can align across siblings.
+3. **Is it a complex page or component structure with rows AND columns?** Use **grid** — 2D, layout-first, you define the skeleton and content fills it.
+4. **Is the content a long flow of prose that should split into balanced columns?** Use **multi-column** — 1D flow, newspaper-style.
+5. **Are items of varied heights that need to be packed tightly?** Use **grid** with `grid-auto-flow: dense` today; reach for native masonry (aka "grid lanes") only when it ships in your Baseline target (see [§8](#8-grid-lanes-aka-masonry)).
+6. **Does an element need to float above the page and stay spatially tethered to a trigger, even across DOM boundaries or stacking contexts?** Use **anchor positioning** — `anchor-name` on the trigger, `position-anchor` on the overlay (see [§5](#5-native-overlays-anchor-positioning-and-stacking-contexts)).
+
+### 1.2 Working principles
+
+- Use logical properties (`inline-size`, `block-size`, `margin-inline`, `padding-block`, `inset-inline-start`) for layout dimensions and spacing — see `css` (via `npx -y modern-web-guidance@latest retrieve "css"`) for full coverage.
+- Apply the content-first vs layout-first mental model: flexbox when items dictate flow, grid when you define the skeleton first.
+- Use the `place-*` shorthands (`place-content`, `place-items`, `place-self`) to align across both axes in one declaration.
+- Reach for intrinsic sizing (`min-content`, `max-content`, `fit-content()`) and flexible tracks (`fr`, `minmax()`) before fixed `width`/`height` — fewer media queries, more resilient layouts.
+- Do NOT use `overflow: hidden` to mask layout issues — fix them at the source.
+For example certain replaced elements like `<canvas>`, `<img>`, `<svg>`, `<video>`, `<iframe>` use `display: inline` by default, which can add a gap in certain layouts. Instead of clipping the gap with `overflow`, remove it by applying a block display-outside value (e.g. `display: block`, `grid`, `flex` etc).
+- Use `aspect-ratio` to reserve space for media and prevent layout shift before assets load.
+
+```css
+.sidebar       { inline-size: max-content; }    /* Size to longest unbreakable token. */
+.main-content  { inline-size: fit-content; }    /* Grow to available space, no further. */
+.media         { aspect-ratio: 16 / 9; inline-size: 100%; block-size: auto; }
+body.centered  { display: grid; place-content: center; min-block-size: 100dvb; }
+```
+
+> For `calc-size()` and constraint-aware intrinsic sizing, see `calculate-with-intrinsic-sizes` (via `npx -y modern-web-guidance@latest retrieve "calculate-with-intrinsic-sizes"`).
+
+## 2 Flexbox
+
+Browser support for flex-wrap: balance: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+One-dimensional layout — items flow along a single **main** axis with alignment on the **cross** axis. Reach for it for navbars, toolbars, item rows, and any single-row-or-column distribution.
+
+**Do:**
+
+- Establish a context with `display: flex` and set the main axis with `flex-direction` (`row` default).
+- Use `flex-wrap: wrap` whenever overflow is a possibility — `nowrap` without `overflow: auto/hidden` will spill on narrow viewports.
+- Layer `flex-wrap: balance` after `flex-wrap: wrap` on wrapped rows of compact items (such as tag clouds, filter pills, button groups, or navigation links) to distribute items evenly across lines and prevent a single orphaned item on the final row; browsers without support fall back to `wrap`.
+- Use the `flex` shorthand `<grow> <shrink> <basis>` (e.g., `flex: 1 1 250px`) on items rather than setting `flex-grow`/`flex-shrink`/`flex-basis` individually.
+- Use `gap` (or the `row-gap`/`column-gap` longhand) for spacing between items instead of child margins.
+- Prefix positional alignment with `safe` (e.g., `align-items: safe center`) so focusable content isn't clipped when the container is narrower than its content.
+- Push a single item to the far end of the main axis with `margin-inline-start: auto` (or `margin-block-start: auto`) — that's the standard escape hatch.
+- Override cross-axis alignment per item with `align-self`.
+- Use `align-items` to center all items on the cross axis; use `margin: auto` on a single item to center it on both axes independently; use `align-content` only when the container wraps and has extra space across rows.
+- Set `min-inline-size: 0` (or `min-width: 0`) on flex items that contain long unbreakable content (URLs, code, long strings) — flex items won't shrink below their content size by default, causing overflow.
+
+**Do not:**
+
+- Don't reach for `justify-self` on flex items — it only works on grid, block, and absolutely-positioned layouts. Use auto margins instead.
+- Don't use `order` or `flex-direction: *-reverse` to reorder interactive content. They change visual order only; the DOM order still drives sequential focus, so keyboard tab flow won't match what the user sees.
+- Don't confuse `space-around` (half-gap at the ends) with `space-evenly` (equal gaps before, between, and after).
+- Don't forget the axis flip: when `flex-direction: column`, `justify-content` aligns on the block axis and `align-items` aligns on the inline axis — the opposite of the default.
+- Don't size both the container and its children to fill each other — that's a common source of overflow and surprising results. Give one side a definite size.
+- Don't set both `flex-basis` and `width`/`inline-size` on the same item — `flex-basis` takes precedence in a flex context and `width` is ignored. Use `flex-basis` (or the `flex` shorthand) as the single source of truth for sizing flex items.
+
+```css
+.card-grid        { display: flex; flex-flow: row wrap; gap: 1rem; }
+.card-item        { flex: 1 1 250px; }                  /* grow, shrink, basis */
+.card-item-action { margin-inline-start: auto; }        /* Push to main-axis end. */
+.toolbar          { display: flex; align-items: safe center; }
+.tag-list         { display: flex; flex-wrap: wrap; flex-wrap: balance; gap: 0.5rem; }
+```
+
+## 3 Grid and subgrid
+
+Baseline status for Subgrid: Widely available. It's been Baseline since 2023-09-15.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 71 (Dec 2019), and Safari 16 (Sep 2022).
+
+Two-dimensional layout — define rows AND columns explicitly, or let the engine derive them. Subgrid lets a nested grid inherit its parent's tracks so grandchildren align across siblings.
+
+**Choosing grid features:**
+
+- Do you know exactly how many columns you need?
+  - **Yes** — use explicit tracks (`grid-template-columns: 200px 1fr`, `repeat(3, 1fr)`, etc.)
+    - Do different columns need different sizes (sidebar + main, header spanning all)? → use `grid-template-areas` for named, readable regions
+    - Are all columns uniform or positioned purely by line number? → use `repeat(N, ...)` or named lines
+  - **No** (responsive, unknown item count) — use `repeat(auto-fit, minmax(min, 1fr))`
+    - Should items on the last row stretch to fill remaining space? → `auto-fit`
+    - Should empty last-row tracks hold their min size (preserving column ghost slots)? → `auto-fill`
+- Do you need to place an item at a specific location?
+  - **Yes** — use `grid-column: <start> / <end>` or `grid-area: <name>`
+  - **No** (just spanning multiple tracks, flow position doesn't matter) — use `grid-column: span <n>`
+- Do child elements need to inherit the parent grid's track sizes (ragged-edge alignment across siblings)?
+  - **Yes** — use subgrid on the affected axis
+    - Is the number of children per cell variable? → subgrid **one axis only**; use `grid-auto-rows`/`grid-auto-columns` for the other
+    - Is the child count fixed? → subgrid on both axes is fine
+  - **No** — standard grid, no subgrid needed
+
+**Do:**
+
+- Establish a context with `display: grid`.
+- Use `grid-template-areas` for complex page-level layouts — area names are self-documenting and the declaration can be aligned in rows and columns for at-a-glance readability.
+- Use `repeat(auto-fit, minmax(200px, 1fr))` for responsive card grids that stretch filled tracks to fill the row, or `auto-fill` to preserve empty repeated tracks at their min size.
+- Use `fr` for proportional track distribution and `minmax(min, max)` for flexible-but-bounded tracks.
+- Position items with `grid-column: span <n>` to size across tracks, `grid-column: <start> / <end>` to place at specific lines, or `grid-area: <name>` for named regions.
+- Use subgrid (`grid-template-columns: subgrid` or `grid-template-rows: subgrid`) to solve the "ragged edge" problem in card lists — internal elements like titles, metadata, and CTAs line up across siblings.
+- Pair a subgrid declaration with a preceding explicit `grid-template-rows`/`-columns` declaration as a same-cascade fallback for older browsers.
+
+**Do not:**
+
+- Don't expect `auto-fit`/`auto-fill` track size to come from item content — it comes from the `repeat()` size argument.
+- Don't use `grid-auto-flow: dense` on interactive content. It packs items efficiently but reorders them visually, breaking DOM-order keyboard tab flow.
+- Don't apply subgrid to both axes when the child count is variable. Extras land in the last track; use `grid-auto-rows`/`grid-auto-columns` for the implicit axis instead.
+- Don't confuse `justify-items`/`align-items` (aligns item content *within its track*) with `justify-content`/`align-content` (aligns the grid tracks *within the container*). Using the wrong one silently has no effect.
+- Don't use `repeat(auto-fit/auto-fill, ...)` without a definite `inline-size` on the container — inside `display: inline-grid` or an unsized flex item, the container has no width to divide, making track counts unpredictable.
+
+### 3.1 Code example: grid and subgrid
+
+Page shell: `<main class="page-layout">` contains `<header>`, `<aside>`, a `<section class="card-grid">` with `<div class="card">` children, and `<footer>`.
+
+```css
+/* Align grid-template-areas in rows and columns for readability. */
+.page-layout {
+  display: grid;
+  grid-template-columns: repeat(3, 1fr);
+  grid-template-areas:
+    "header  header  header"
+    "sidebar main    main"
+    "footer  footer  footer";
+  gap: 1.5rem;
+}
+
+header  { grid-area: header; }
+aside   { grid-area: sidebar; }
+footer  { grid-area: footer; }
+
+.card-grid {
+  grid-area: main;
+  display: grid;
+  grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+  grid-template-rows: auto 1fr; /* title block, body block */
+  gap: 1rem;
+}
+
+.card {
+  grid-row: span 2;
+  display: grid;
+  /* Same-cascade fallback: ignored when subgrid is supported. */
+  grid-template-rows: auto 1fr;
+  grid-template-rows: subgrid;
+}
+```
+
+## 4 Container queries
+
+Baseline status for Container queries (size): Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+Query the size (or computed style) of an ancestor container rather than the viewport. Mental model: container queries = component context; media queries = global page layout and user preferences (`prefers-color-scheme`, `prefers-reduced-motion`).
+
+**Do:**
+
+- Establish a containment context with `container-type: inline-size` (width-only queries) or `container-type: size` (both axes) on a wrapper before its descendants can be queried.
+- Name containers with `container-name` (or the `container` shorthand: `container: card / inline-size`) when nested contexts could collide.
+- Include container query units in calculating fluid type and spacing: `cqi`/`cqb` (logical inline/block), `cqw`/`cqh` (physical), `cqmin`/`cqmax`.
+- Give the container a definite `block-size` whenever `container-type: size` is used — without one, descendants collapse because size containment forces the container to ignore its content.
+
+**Do not:**
+
+- Don't use `block-size` as a `container-type` value — it isn't valid. Use `size` for both axes.
+- Don't expect children's intrinsic size to influence the container after declaring `container-type`. The container is computed as if it has no children once containment is active.
+- Don't rely on container query units inside descendants of a non-qualifying ancestor; they fall back to the small viewport (`svw`/`svh`).
+
+### 4.1 Code example: fluid typography using container query units
+
+```css
+.card-wrapper {
+  container: card / inline-size; /* shorthand for container-name / container-type */
+}
+
+@container card (inline-size > 400px) {
+  .content {
+    display: flex;
+    gap: 2rem;
+  }
+}
+
+.title {
+  /* Fluid type bound to the container width, not the viewport. */
+  font-size: clamp(1rem, 4cqi, 2rem);
+}
+```
+
+> For component-driven responsive styling patterns, see `size-aware-styling` (via `npx -y modern-web-guidance@latest retrieve "size-aware-styling"`) and `fluid-scaling` (via `npx -y modern-web-guidance@latest retrieve "fluid-scaling"`).
+
+## 5 Native overlays, anchor positioning, and stacking contexts
+
+Baseline status for <dialog>: Widely available. It's been Baseline since 2022-03-14.
+Supported by: Chrome 37 (Aug 2014), Edge 79 (Jan 2020), Firefox 98 (Mar 2022), and Safari 15.4 (Mar 2022).
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+**When to use each overlay primitive:**
+
+- Use `popover` for transient, non-modal UI (flyouts, toasts, tooltips) — lives in the top layer, no `z-index` management needed.
+- Use `<dialog>` with `.showModal()` for modal interactions that require focus trapping and an inert backdrop.
+- Don't combine `popover` and `.showModal()` on the same element — they're mutually exclusive runtime states.
+
+**Anchor positioning (spatial layout of overlays):**
+
+- Use `position-area` (or `anchor()` on insets) and `anchor-size()` to position and size an overlay relative to its trigger.
+- Use `position-try-fallbacks: flip-block` (or `flip-inline`) to let the browser reposition when the overlay overflows the viewport.
+- Don't mix physical and logical keywords in a single `position-area` value — pick one coordinate system.
+- Feature-detect with `@supports (anchor-name: --x)` and provide an absolute-position fallback.
+
+> For full implementation detail, polyfill strategies, and `popover` value reference, see `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`) and `position-aware-tooltips` (via `npx -y modern-web-guidance@latest retrieve "position-aware-tooltips"`). For anchor positioning applied to dropdowns, flyouts, and tab indicators, see `viewport-aware-dropdowns` (via `npx -y modern-web-guidance@latest retrieve "viewport-aware-dropdowns"`) and `anchor-positioning-tab-underline` (via `npx -y modern-web-guidance@latest retrieve "anchor-positioning-tab-underline"`).
+
+## 6 Overflow tracking and layout stability
+
+Baseline status for scrollbar-gutter: Newly available. It's been Baseline since 2024-12-11.
+Supported by: Chrome 94 (Sep 2021), Edge 94 (Sep 2021), Firefox 97 (Feb 2022), and Safari 18.2 (Dec 2024).
+
+line-clamp is not natively supported by any major browser yet.
+
+Manage layout shifts, scrollbars, and clipping predictably.
+
+**Do:**
+
+- Use `overflow: auto` so scrollbars appear only when content actually overflows.
+- Use `overflow: clip` to clip content **without** establishing a scroll container; opt into spillover with `overflow-clip-margin`.
+- Use `scrollbar-gutter: stable` to reserve space for scrollbars and prevent layout shifts when content grows.
+- Use `overscroll-behavior: contain` (or `none`) on nested scroll regions (such as sidebars, modals, and lists) to stop scroll chains from bubbling into the page, or `overscroll-behavior: chain` on intermediate scroll wrappers (such as swipe-to-reveal tracks) when excess scroll should propagate to an ancestor scroller without triggering a local rubber-band bounce.
+- Use the `-webkit-line-clamp` + `display: -webkit-box` + `-webkit-box-orient: vertical` triad for multi-line truncation — despite the prefix, this pattern is fully specified and not deprecated. Declare the unprefixed `line-clamp` shorthand alongside it; browsers that don't yet support it ignore the property harmlessly.
+**Do not:**
+
+- Don't use `overflow: scroll` when `auto` will do — `scroll` forces scrollbars even when there's nothing to scroll.
+- Don't reach for `overflow: hidden` when you only want to clip — `hidden` establishes a scroll container that can be programmatically scrolled.
+
+```css
+.scrollable-list {
+  max-block-size: 400px;
+  overflow-y: auto;
+  scrollbar-gutter: stable;       /* Reserve scrollbar space. */
+  overscroll-behavior: contain;   /* No scroll chaining into the page. */
+}
+
+.snippet {
+  display: -webkit-box;
+  -webkit-line-clamp: 3;
+  -webkit-box-orient: vertical;
+  line-clamp: 3;                  /* Ignored where unsupported. */
+  overflow: clip;
+}
+```
+
+> For `overflow: clip` and `overflow-clip-margin` in depth, see `overflow-clipping-control` (via `npx -y modern-web-guidance@latest retrieve "overflow-clipping-control"`). For nested scroll handoff with `overscroll-behavior: chain` in swipe-to-reveal UI, see `swipe-to-reveal` (via `npx -y modern-web-guidance@latest retrieve "swipe-to-reveal"`). For scrollbar color, sizing, and theming, see `customize-scrollbar-color-and-thickness` (via `npx -y modern-web-guidance@latest retrieve "customize-scrollbar-color-and-thickness"`), `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`), and `adapt-scrollbar-to-contrast-preferences` (via `npx -y modern-web-guidance@latest retrieve "adapt-scrollbar-to-contrast-preferences"`).
+
+## 7 Viewport mechanics and track distribution
+
+Baseline status for Small, large, and dynamic viewport units: Widely available. It's been Baseline since 2022-12-05.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 101 (May 2022), and Safari 15.4 (Mar 2022).
+
+- Use `dvh`/`dvw` for mobile layout containers that must account for browser UI shifting (URL bar collapse/expand).
+- Don't use `100vw` for full-width layout — it ignores scrollbar width and causes horizontal overflow. Use `100%`, `100dvw`, or `100svw` instead.
+
+> For the responsive design entry point (dynamic viewport units, reserving space for media, fluid typography), see `responsive-design` (via `npx -y modern-web-guidance@latest retrieve "responsive-design"`).
+
+## 8 Grid lanes (aka masonry)
+
+Grid lanes is not natively supported by any major browser yet.
+
+The specification is in development under the name "grid lanes" (e.g., `display: grid-lanes`), while earlier experimental prototypes used `grid-template-rows: masonry`.
+
+**Do:**
+
+- Use grid with `grid-auto-flow: dense` for tight packing today, accepting that DOM order may not match visual order.
+- Use multi-column (`columns: 3; column-gap: 1rem`) for content-heavy masonry-like flow when items are document fragments rather than equal-weight cards.
+- Treat `grid-template-rows: masonry` as a progressive enhancement only — feature-detect with `@supports`.
+
+**Do not:**
+
+- Don't ship `grid-template-rows: masonry` as a hard requirement until your Baseline target catches up.
+
+```css
+.gallery       { columns: 3 200px; column-gap: 1rem; }
+.gallery > *   { break-inside: avoid; margin-block-end: 1rem; }
+
+@supports (grid-template-rows: masonry) {
+  .gallery {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
+    grid-template-rows: masonry;
+    gap: 1rem;
+    columns: unset;
+  }
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css.md
new file mode 100644
index 00000000..b848c9f6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/css.md
@@ -0,0 +1,250 @@
+# CSS: Modern Architecture
+
+These guidelines provide a high-density reference for writing maintainable and standard-compliant CSS.
+
+- [1. Foundations](#1-foundations)
+- [2. Inheritance and The Cascade](#2-inheritance-and-the-cascade)
+- [3. Selectors and scoping](#3-selectors-and-scoping)
+  - [Prefer CSS selectors over JS for complex element targeting](#prefer-css-selectors-over-js-for-complex-element-targeting)
+  - [Use `:is()` (or `:where()`) instead of CSS rule duplication for fallbacks](#use-is-or-where-instead-of-css-rule-duplication-for-fallbacks)
+  - [Avoid overmatching](#avoid-overmatching)
+    - [Use `:not()` instead of overrides to exclude irrelevant states/targets](#use-not-instead-of-overrides-to-exclude-irrelevant-statestargets)
+    - [Prefer `@scope` over `:not()` for excluding (potentially deeply nested) subtrees](#prefer-scope-over-not-for-excluding-potentially-deeply-nested-subtrees)
+    - [Overrides are fine for specialization](#overrides-are-fine-for-specialization)
+    - [No global resets](#no-global-resets)
+  - [Nesting and scoping](#nesting-and-scoping)
+- [4. Interactivity](#4-interactivity)
+- [5. Design Tokens and Theming](#5-design-tokens-and-theming)
+  - [Theming](#theming)
+- [6. Responsive design](#6-responsive-design)
+- [7. Typography](#7-typography)
+- [8. Visual effects](#8-visual-effects)
+- [9. Shapes](#9-shapes)
+- [10. Transitions \& animations](#10-transitions--animations)
+- [11. Generated content](#11-generated-content)
+
+
+## 1. Foundations
+
+Be allergic to knowledge duplication. Prefer variables over repetition, but whenever possible, prefer built-in conventions such as:
+- `currentColor` instead of defining a variable and setting `color` to it
+- The `inherit` keyword instead of defining a variable on the parent and using it on the same property across parent and child.
+- `em` units instead of `font-size: var(--size)`
+- `cqw`/`cqh` (or their logical versions — `cqi`/`cqb`) units instead of repeating box model values.
+- Code duplication is not knowledge duplication. The goal is robustness and maintainability, not saving characters.
+- Prefer **logical properties and values** over physical ones (e.g. `margin-inline-start` instead of `margin-left`) so that styles adapt to different writing modes and orientations. Even if the page author does not plan to localize, external translation tools often display translated text in context.
+- Do not use logical properties indiscriminately — ask yourself "would I want this to flip in RTL?" — if the answer is no, use the physical property instead.
+- Consider different viewing modes (dark mode, high contrast mode), different viewport sizes, and different input modes (touch, keyboard, pointer).
+
+## 2. Inheritance and The Cascade
+
+**Avoid** introducing BEM naming conventions to manage specificity.
+Instead, use modern CSS features such as cascade layers and `:where()` to make cascade behavior predictable and follow author intent.
+
+Use cascade layers (`@layer`) to define explicit priority zones (e.g., `reset`, `base`, `theme`, `components`, `utilities`), and declare their order upfront (e.g. `@layer reset, base, theme, components, utilities;`).
+Within each layer, use `:where()` to make selectors only compete based on meaningful signals, not incidental filters (`:not()` edge cases, remote ancestors, etc.) or for one-off easily overridable defaults.
+
+Use keywords like `inherit`, `initial`, `unset`, or `revert` instead of explicit values to improve maintainability and better express intent.
+Examples:
+- When specifying a transition on a child that should match the parent's `transition-*` properties, instead of repeating the transition properties on the child, use `transition: inherit` (reduce duplication, improve maintainability)
+- Use `initial` to reset a property to its initial value instead of specifying the value explicitly (clearer expression of intent)
+
+## 3. Selectors and scoping
+
+Modern browser-native selectors reduce the need for preprocessors and complex state-tracking in JS.
+
+### Prefer CSS selectors over JS for complex element targeting
+
+- **DO** use `:has()` to style parents based on child state instead of managing classes in JS (e.g. `label:has(:checked)` instead of a manual `label.has-checked` class) For more information, see the guides at `child-state-based-styling` (via `npx -y modern-web-guidance@latest retrieve "child-state-based-styling"`) and `content-based-styling` (via `npx -y modern-web-guidance@latest retrieve "content-based-styling"`).
+- **DO NOT** nest `:has()` or use pseudo-elements inside it (browser API limitation)
+- Use `:nth-child(<An+B> of <selector>)` when you need to style every n-th element of a certain type. E.g. `details:nth-child(1 of [open])` will style the first open `<details>` element it finds, whereas `details[open]:first-child` would style only the first child if and only if it was open.
+
+### Use `:is()` (or `:where()`) instead of CSS rule duplication for fallbacks
+
+**DO NOT** duplicate CSS rules to provide fallbacks for pseudo-classes that may not be supported — use `:is()` or `:where()` instead and take advantage of their forgiving parsing rules.
+
+```css
+/* BAD: duplicate rules instead of using `:where()` */
+[popover]:popover-open {
+  /* styles for native popovers */
+}
+[popover].\:popover-open {
+  /* same styles again, for polyfilled popovers */
+}
+
+/* GOOD */
+[popover]:where(:popover-open, .\:popover-open) {
+  /* same styles in one rule */
+}
+```
+
+Do NOT use this for pseudo-elements, as they are not supported in `:is()` or `:where()`.
+
+### Avoid overmatching
+
+Write selectors in a way that expresses _intent_.
+
+#### Use `:not()` instead of overrides to exclude irrelevant states/targets
+
+When the intent is to exclude certain states or elements that are fundamentally irrelevant, use `:not()`.
+
+For example, to apply bottom borders between list items, don't do this:
+
+```css
+.fancy-list li {
+  border-bottom: 1px solid silver;
+}
+
+.fancy-list li:last-child {
+  border-bottom: none;
+}
+```
+
+This can unintentionally overwrite a desirable `border-bottom` set from another rule.
+The actual intent was to only apply the bottom border to the non-last `li`s. The code above is a workaround that poorly expresses this intent. Instead, this expresses intent more clearly:
+
+```css
+.fancy-list li:not(:last-child) {
+  border-bottom: 1px solid silver;
+}
+```
+
+Similarly, don't do this:
+
+```css
+button:hover {
+  background: var(--color-blue);
+}
+
+button:disabled {
+  background: var(--color-neutral);
+}
+```
+
+If we reorder the two rules, we will get a hover background on disabled buttons!
+Instead, do this:
+
+```css
+button:hover:not(:disabled) {
+  background: var(--color-blue);
+}
+
+button:disabled {
+  background: var(--color-neutral);
+}
+```
+
+This works regardless of reordering, as the first rule does not overmatch.
+
+If you _must_ use an override (e.g. you are using an experimental container query and the `not` case is also the fallback), in some cases you may be able to use the `revert-layer` keyword to remove the value without coupling the override to specific values.
+Note that this can only work if the value to fall back to is also layered.
+
+#### Prefer `@scope` over `:not()` for excluding (potentially deeply nested) subtrees
+
+While `:not()` + descendant selectors can exclude subtrees, this works poorly for deeply nested structures.
+For example, `.card :not(.content *)` will not work as expected for nested cards.
+`@scope` fixes this as it takes hierarchical proximity into account:
+
+```css
+@scope (.card) to (.content) {
+  /* styles for elements inside .card but not inside .content */
+}
+```
+
+This will work as expected even for nested cards.
+
+#### Overrides are fine for specialization
+
+This is fine:
+
+```css
+button {
+  background: var(--color-neutral);
+}
+
+button.primary {
+  background: var(--color-blue);
+}
+```
+
+Both rules express legitimate _intent_: buttons are generally neutral, but primary ones are blue.
+
+#### No global resets
+
+**DO NOT** use global resets (styles on `*`) as they cannot be overridden by web components or lower-priority cascade layers (without `!important`). Instead, apply reset styles to specific element types and/or conditions.
+
+### Nesting and scoping
+
+Use native CSS nesting to group related styles to the extent it improves maintainability and readability.
+
+Prefer `@scope` over nesting when proximity should matter more than pure specificity. This is common in selectors that can be nested in any order, but the closest matching one (in element -> ancestor order) should win, e.g. theming classes.
+
+For example this will not work as expected:
+```css
+.dark .invert { color-scheme: light }
+.light .invert { color-scheme: dark }
+```
+
+If `.invert` is nested within _both_ `.dark` and `.light`, it will always resolve to dark mode as both rules have the same specificity.
+Using `@scope` fixes this:
+
+```css
+@scope (.dark) {
+  .invert { color-scheme: light }
+}
+
+@scope (.light) {
+  .invert { color-scheme: dark }
+}
+```
+
+## 4. Interactivity
+
+See `accessibility` (via `npx -y modern-web-guidance@latest retrieve "accessibility"`) for focus rings, touch targets, and custom gestures.
+
+## 5. Design Tokens and Theming
+
+Use CSS custom properties on `:root` to define core design variables (colors, fonts, sizes, etc) used throughout the design, for visual consistency and to scale UI design across teams.
+**DO NOT** specify nontrivial styling values inline. E.g. `background: transparent` or `padding: 0` is ok, but `background: #f06` or `padding: .3em` are not.
+One exception is use cases where keeping code small and simple is far more important than long-term maintainability and evolution, such as testcases.
+
+Typically these are organized in tiers, with each tier building upon the previous one. For example:
+1. Tier 1: Literal design tokens (e.g. `--color-blue-10`, `--color-gray-90`, `--font-sans-serif`, `--size-xl` etc)
+2. Tier 2: Semantic design tokens (e.g. `--color-accent`, `--color-neutral`, `--font-body`, `--font-heading` etc)
+3. Tier 3: General UI design tokens (e.g. `--ui-border`, `--surface-bg-subtle` etc)
+4. Tier 4: Component-specific design tokens (e.g. `--button-bg-primary-hover`, `--button-border-color-secondary` etc)
+
+The smaller the scope of the use case, the fewer tiers it needs. E.g. a quick demo or toy app are fine with one tier. Do not overengineer.
+Check for any existing conventions around naming and levels before inventing your own.
+
+### Theming
+
+- Dark mode: see `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`) and `component-specific-light-dark-theme` (via `npx -y modern-web-guidance@latest retrieve "component-specific-light-dark-theme"`).
+- Forced Colors Mode: see `color` (via `npx -y modern-web-guidance@latest retrieve "color"`).
+- Generating tints and shades: see `color` (via `npx -y modern-web-guidance@latest retrieve "color"`).
+- Theming browser-generated UI (selection, scrollbars, form controls): see `browser-ui-theming` (via `npx -y modern-web-guidance@latest retrieve "browser-ui-theming"`).
+
+## 6. Responsive design
+
+See `responsive-design` (via `npx -y modern-web-guidance@latest retrieve "responsive-design"`) for components that adapt to the space they are given, layouts that survive mobile browser UI appearing and disappearing, reserving space for media before it loads, and text that scales with the viewport.
+
+## 7. Typography
+
+See `typography` (via `npx -y modern-web-guidance@latest retrieve "typography"`) for guidelines around readability, accessibility, and aesthetics of text on Web UIs.
+
+## 8. Visual effects
+
+See `visual-effects` (via `npx -y modern-web-guidance@latest retrieve "visual-effects"`) for look & feel enhancements such as conveying depth, texture, and elevation, blending layers, aesthetically pleasing gradients, and flexible pattern backgrounds.
+
+## 9. Shapes
+
+- Use `corner-shape: squircle` for more aesthetically pleasing curves as a progressive enhancement over regular rounded corners.
+- Use elliptical `border-radius` (e.g., `10px / 20px`) for proportional curves without extra elements.
+
+## 10. Transitions & animations
+
+See `motion` (via `npx -y modern-web-guidance@latest retrieve "motion"`). For rendering performance (`content-visibility`, containment), see `performance` (via `npx -y modern-web-guidance@latest retrieve "performance"`).
+
+## 11. Generated content
+See `accessible-generated-content` (via `npx -y modern-web-guidance@latest retrieve "accessible-generated-content"`) for adding decorative or supplementary content with CSS without breaking screen readers or copy-paste.
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/design-token-reactivity.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/design-token-reactivity.md
new file mode 100644
index 00000000..2d434606
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/design-token-reactivity.md
@@ -0,0 +1,176 @@
+# Design Token Reactivity
+
+## Background & Overview
+
+Often an author will need to make contextual changes to the design of a component. Historically authors would need to use selectors to apply such changes. This often meant that while many of their design tokens could exist as custom properties, higher-order design tokens could only be encoded as a selector pattern (i.e. using a class name or attribute convention) or as props/context in a JavaScript framework.
+
+**Container style queries** allow authors to style elements based on the computed custom property value of an ancestor element. This means authors can write meaningful design token values within their stylesheets rather than relying on markup or JavaScript for presentation.
+
+## How to implement
+
+Implementing a reactive design token using a container style query is quite straightforward:
+
+1. Set the higher-order design token as a custom property on a container. This does not need to be a registered custom property.
+2. Use the `@container style()` rule to query the value of that custom property.
+3. Apply the appropriate styles to a descendant element within the container.
+
+A few things to keep in mind:
+
+- The container being queried with a style query does not need to have a `container-type` or `container-name` set, however, a `container-name` can allow for more specific querying.
+- The container itself cannot be styled by the container style query.
+
+The following is a basic example of the above implementation steps.
+
+```html
+<div class="features">
+  <div class="card"></div>
+  <div class="card"></div>
+</div>
+<div class="bugs">
+  <div class="card"></div>
+  <div class="card"></div>
+  <div class="card"></div>
+  <div class="card"></div>
+</div>
+```
+
+```css
+.features {
+  --density: spacious;
+}
+
+.bugs {
+  --density: compact;
+}
+
+@container style(--density: compact) {
+  .card {
+    padding: 8px;
+  }
+}
+
+@container style(--density: spacious) {
+  .card {
+    padding: 24px;
+  }
+}
+```
+
+## Fallback strategies
+
+Baseline status for Container style queries: Newly available. It's been Baseline since 2026-05-19.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 151 (May 2026), and Safari 18 (Sep 2024).
+
+Until there is Baseline support for container style queries it is NOT RECOMMENDED that they be used for core features that must be available across all browsers, since it is not simple to create a fallback for them that does not take away from their benefits or that have their own limitations. For example, if a UI density user preference is not deemed to be a core feature that must be available across all experiences, then container style queries can be use to implement the feature without a fallback.
+
+### Using selectors instead
+
+For core features, an alternate approach using selectors should be used. This example uses a `data-density` attribute to encode the density design token in the markup rather than as a custom property:
+
+```html
+<div class="features" data-density="spacious">
+  <div class="card"></div>
+  <div class="card"></div>
+</div>
+<div class="bugs" data-density="compact">
+  <div class="card"></div>
+  <div class="card"></div>
+  <div class="card"></div>
+  <div class="card"></div>
+</div>
+```
+
+```css
+/* This example uses `:where()` to avoid increasing specificity */
+:where([data-density="compact"]) .card {
+  padding: var(--card-padding-compact);
+}
+
+:where([data-density="spacious"]) .card {
+  padding: var(--card-padding-spacious);
+}
+```
+
+A major limitation of this fallback approach is that it does not support nesting elements with the `data-density` attribute set, since the selector specificity is the same, order of appearance will be used to determine the styles (i.e. `[data-density="spacious"]` will always take precedence over `[data-density="compact"]`).
+
+### Using style queries as a progressive enhancement
+
+While it’s NOT RECOMMENDED, if you want to use style queries as a progressive enhancement for a core feature, then to avoid duplication you can create some custom properties, then include the style queries after. Make sure the fallback approach uses `:where()` when selecting the container elements to avoid increasing the specificity.
+
+```css
+.card {
+  --card-padding-compact: 8px;
+  --card-padding-spacious: 24px;
+}
+
+:where([data-density="compact"]) .card {
+  padding: var(--card-padding-compact);
+}
+
+:where([data-density="spacious"]) .card {
+  padding: var(--card-padding-spacious);
+}
+
+/* Use style queries as a progressive enhancement: same specificity, so order of appearance is used */
+
+@container style(--density: compact) {
+  .card {
+    padding: var(--card-padding-compact);
+  }
+}
+
+@container style(--density: spacious) {
+  .card {
+    padding: var(--card-padding-spacious);
+  }
+}
+```
+
+### Feature-checking with just CSS
+
+If you need to feature check container style queries to conditionally display some UI that relies on it, you can use a style query to do so:
+
+```css
+:root {
+  --style-queries-supported: check;
+}
+
+.density-toggle {
+  display: none;
+}
+
+@container style(--style-queries-supported) {
+  .density-toggle {
+    display: revert;
+  }
+}
+```
+
+### Feature-checking with JavaScript
+
+For feature-checking with JavaScript, it is slightly more complicated as the `CSSContainerRule` interface existed prior to the addition of container style queries, so it is unreliable for this purpose. Instead, you’ll need to check the computed value of a known property that is being set with a style query.
+
+This example uses a custom property as it will have no visual effect:
+
+```css
+:root {
+  --style-queries-supported: check;
+}
+
+@container style(--style-queries-supported: check) {
+  body {
+    --style-queries-supported: yes;
+  }
+}
+```
+
+Then check the computed value in JavaScript like this:
+
+```js
+if (getComputedStyle(document.body).getPropertyValue("--style-queries-supported") === "yes") {
+  // Use container style queries
+} else {
+  // Use fallback strategy
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/dynamic-sibling-styling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/dynamic-sibling-styling.md
new file mode 100644
index 00000000..637f2d5b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/dynamic-sibling-styling.md
@@ -0,0 +1,97 @@
+# Styling siblings based on count and index
+
+Historically, applying unique styles to each sibling in a list required complex `:nth-child` loops or JavaScript to inject inline styles. Modern CSS provides `sibling-index()` and `sibling-count()` to perform these calculations directly in your stylesheet, enabling dynamic layouts and color systems that automatically adapt as elements are added or removed.
+
+## Dynamic color systems
+
+You can create a color spectrum across a group of siblings by calculating a unique hue or lightness value for each child. This ensures a consistent gradient effect regardless of the number of items.
+
+```css
+.swatch {
+  /* Calculate hue by dividing the full 360deg circle by total siblings */
+  /* and multiplying by the current element's 1-based index */
+  background-color: hsl(
+    calc(360deg / sibling-count() * sibling-index()),
+    70%,
+    50%
+  );
+}
+```
+
+## Symmetrical layout and fan effects
+
+To create symmetrical effects (like a "fan" or centering items), use the total count to find the midpoint of the list.
+
+```css
+.card {
+  /* Find the center index (e.g., 3 if there are 5 siblings) */
+  --center: calc((sibling-count() + 1) / 2);
+
+  /* Rotate items away from the center: negative for left, positive for right */
+  /* center element gets 0deg rotation */
+  transform: rotate(calc(10deg * (sibling-index() - var(--center))));
+}
+```
+
+## Circular and complex positioning
+
+By combining these functions with CSS trigonometry (`sin()`, `cos()`), you can place elements in a perfect circle without any manual coordinates.
+
+```css
+.orb {
+  /* Calculate the angle for this item's position on a 360deg circle */
+  --angle: calc(360deg / sibling-count() * sibling-index());
+  --radius: 150px;
+
+  /* Set the pre-transformed position for all items to be centered */
+  position: absolute;
+  place-self: center;
+
+
+  /* Position each element around the parent center */
+  transform: translate(
+    calc(cos(var(--angle)) * var(--radius)),
+    calc(sin(var(--angle)) * var(--radius))
+  );
+}
+```
+
+### Fallback strategies
+
+Baseline status for sibling-count() and sibling-index(): Newly available. It's been Baseline since 2026-08-18.
+Supported by: Chrome 138 (Jun 2025), Edge 138 (Jun 2025), Firefox 154 (Aug 2026), and Safari 26.2 (Dec 2025).
+
+If `sibling-index()` and `sibling-count()` are not supported, provide a fallback by injecting CSS custom properties via JavaScript. **MANDATORY:** Use feature detection with `CSS.supports()` to ensure the script only runs when necessary.
+
+```js
+/* MANDATORY: Check for native support before applying fallback */
+if (!CSS.supports('top: calc(sibling-index() * 1px)')) {
+  const items = document.querySelectorAll('.item');
+  items.forEach((item, index) => {
+    /* MANDATORY: Injected index must be 1-based to match native function */
+    item.style.setProperty('--sibling-index', index + 1);
+    item.style.setProperty('--sibling-count', items.length);
+  });
+}
+```
+
+In your CSS, use these variables as a base and override them with native functions inside an `@supports` block. **MANDATORY:** You MUST wrap the native function overrides in `@supports` to ensure the variables remain valid in older browsers.
+
+```css
+.item {
+  /* 1. Set base values using variables (from JS fallback) */
+  --index: var(--sibling-index);
+  --count: var(--sibling-count);
+
+  /* 2. Use the computed variables - replace this with your implementation-specific styles */
+  background-color: hsl(calc(360deg / var(--count) * var(--index)), 70%, 50%);
+}
+
+@supports (top: calc(sibling-index() * 1px)) {
+  .item {
+    /* 3. Override with native functions ONLY if supported */
+    --index: sibling-index();
+    --count: sibling-count();
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/fluid-scaling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/fluid-scaling.md
new file mode 100644
index 00000000..8b91d5c6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/fluid-scaling.md
@@ -0,0 +1,80 @@
+# Fluid Scaling
+
+## Overview
+
+Fluid scaling allows components to adjust their internal proportions (like font sizes and spacing) based on their current dimensions. This creates a more cohesive design than jumping between fixed breakpoints.
+
+While fluid scaling was historically achieved using viewport units (scaling based on the screen size), modern container query units allow components to scale relative to their parent container instead. This ensures components look good regardless of where they are placed in a layout, promoting better component isolation and reusability.
+
+## Implementation
+
+### 1. Define a container
+
+To use container query units, you must first define a containment context on a parent element.
+
+```css
+.component-wrapper {
+  /* Define the container type. Use 'inline-size' for width-based scaling. */
+  /* You can also use 'size' for both width and height, but it requires explicit sizing. */
+  container-type: inline-size;
+  
+  /* Optional: Name the container for specific targeting */
+  container-name: fluid-card;
+}
+```
+
+### 2. Use container query units
+
+Use container query units (`cqi`, `cqb`, etc.) to set sizes relative to the container's dimensions.
+
+*   `cqi`: 1% of the container's inline size (width in horizontal writing modes).
+*   `cqb`: 1% of the container's block size (height in horizontal writing modes).
+
+**Note**: Container units can be used directly on any property without needing an `@container` query rule. They automatically resolve based on the nearest ancestor with a defined `container-type`.
+
+```css
+.component-title {
+  /* Scale font size based on container width */
+  /* 10cqi means 10% of the container's width */
+  font-size: 10cqi;
+}
+
+.component-body {
+  /* Scale padding based on container width */
+  padding: 5cqi;
+}
+```
+
+### 3. Constrain values with `clamp()`
+
+To prevent sizes from becoming too small or too large, use the CSS `clamp()` function. This impacts the user's ability to zoom or adjust their base font size. To ensure text meets accessibility guidelines, the maximum size must not be more than 2.5 times the minimum size.
+
+```css
+.component-title {
+  /* Clamp font size between 1rem and 2.5rem, scaling with 5% of container width */
+  font-size: clamp(1rem, 5cqi, 2.5rem);
+}
+```
+
+### Fallback strategies
+
+Baseline status for Container queries (size): Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+If container queries are not supported by the browser, you should provide a fallback using viewport units or standard media queries.
+
+```css
+.component-title {
+  /* Fallback for browsers that do not support container units */
+  font-size: clamp(1rem, 5vw, 2.5rem);
+}
+
+@supports (font-size: 1cqi) {
+  .component-title {
+    /* Use container units where supported */
+    font-size: clamp(1rem, 5cqi, 2.5rem);
+  }
+}
+```
+
+This fallback ensures that the text still scales, but it will be based on the screen width rather than the component's width. This should be tested to verify it works in your use case.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/individual-transform-properties.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/individual-transform-properties.md
new file mode 100644
index 00000000..728d0c98
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/individual-transform-properties.md
@@ -0,0 +1,94 @@
+# Individual Transform Properties
+
+The `transform` property allows you to apply multiple transformations in a specified order, but any changes to a single transformation require re-specifying the entire transformation chain. This makes it tricky to animate or transition a single transformation.
+
+The individual CSS transform properties (`translate`, `rotate`, and `scale`) allow you to apply transformations independently of the `transform` property. This approach makes it simpler to override a single transformation, for instance on `:hover`.
+
+### Key Implementation Details
+
+Individual transform properties are always applied in a **fixed order**, regardless of their order in your CSS:
+1. `translate`
+2. `rotate`
+3. `scale`
+4. `transform` (applied last)
+
+If you require a different order (e.g., scaling *before* rotating), you must continue using the `transform` property functions.
+
+Transform functions do not override the individual transform properties. In other words, `scale: 2; transform: scale(3);` will first scale by 2x, then again by 3x, for a total of 6x.
+
+### Preventing Unexpected Changes in Stacking Contexts and Containing Blocks
+
+The `transform` property and individual transform properties impact the layout and rendering of the page and may cause unexpected behavior with the z-index or anchor positioning. MANDATORY: If an element may have a transform applied as part of a state change like `:hover`, or a transition or animation, apply an identity transformation to the base element. This ensures that the element's stacking context and containment do not change when a transform is applied.
+
+```css
+.element{
+  /* MANDATORY: Apply identity transformations for properties that will
+     change on state changes (like :hover). This prevents unexpected layout
+     or z-index shifts caused by creating a new stacking context only on hover. */
+  translate: 0px;
+  rotate: 0deg;
+  scale: 1;
+}
+.element:hover{
+  translate: 10px 10px;
+  rotate: 20deg;
+  scale: 0.8;
+}
+```
+
+### Independent Animation and Transitions
+
+The primary benefit is the ability to define overlapping animations or transitions that target different properties without conflict.
+
+```css
+.card {
+  /* Define independent animations that don't overwrite each other */
+  animation: float 3s infinite ease-in-out;
+  
+  /* Transition only the scale property for hover states */
+  transition: scale 0.3s ease;
+
+  /* Establish the base scale to prevent a sudden stacking context shift when transitioning on hover. */
+  scale: 1;
+}
+
+.card:hover {
+  /* Only the scale changes; the 'float' animation (translate) continues uninterrupted */
+  scale: 1.05;
+}
+
+@keyframes float {
+  0%, 100% { translate: 0 0; }
+  50% { translate: 0 -10px; }
+}
+```
+
+### Fallback strategies
+
+Baseline status for Individual transform properties: Widely available. It's been Baseline since 2022-08-05.
+Supported by: Chrome 104 (Aug 2022), Edge 104 (Aug 2022), Firefox 72 (Jan 2020), Safari 14.1 (Apr 2021), and Safari iOS 14.5 (Apr 2021).
+
+For browsers that do not support individual transform properties, use the traditional `transform` property. Note that this requires re-declaring the entire transform stack if you want to modify one part in a different state.
+
+```css
+.element {
+  /* Base transform */
+  transform: translate(100px, 0) rotate(45deg);
+  /* Specify the identity for the scale property. */
+  scale: 1;
+}
+
+@supports not (translate: 0px) {
+  .element:hover {
+    /* Fallback: Must repeat translate and rotate even if only scale changes */
+    transform: translate(100px, 0) rotate(45deg) scale(1.1);
+  }
+}
+
+@supports (translate: 0px) {
+  .element:hover {
+    /* Modern: Only declare the change */
+    scale: 1.1;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/overflow-clipping-control.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/overflow-clipping-control.md
new file mode 100644
index 00000000..6c119149
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/overflow-clipping-control.md
@@ -0,0 +1,181 @@
+# Overflow Clipping Control
+
+While `overflow: hidden` is a "blunt instrument" that almost always clips content strictly at the padding-box, `overflow: clip` combined with `overflow-clip-margin` provides the "scalpel" for fine-grained layout control across block containers.
+
+Specify exactly where clipping occurs with `overflow: clip` and `overflow-clip-margin`. You can align the boundary precisely with inner box-model edges or extend the clipping boundary beyond the element's box by a specified offset (a safety margin). This modern approach is highly performant and eliminates the legacy requirement of adding extra wrapper containers with custom padding and negative margins just to let visual effects (like prominent child element shadows) render unclipped.
+
+Replaced elements (`<img>`, `<video>`, `<canvas>`, etc.) default to `overflow: clip` and `overflow-clip-margin: content-box`, giving you control to cleanly contain images that use `object-fit` or `border-radius`. 
+
+## How to Implement
+
+1. **Apply `overflow: clip`**: Ensure the target element has `overflow: clip` enabled. Setting `overflow: clip` is **mandatory** on block layout containers for `overflow-clip-margin` to take effect. If `overflow` is set to `hidden`, `auto`, or `scroll`, the `overflow-clip-margin` property is ignored by the browser. `overflow: clip` prevents all scrolling (both user-initiated and programmatic via JavaScript).
+2. **Align to a Box-Edge**: Use keywords to precisely align the clipping boundary to inner box-model edges:
+   - `content-box`: Clips content exactly where the content area begins, leaving the padding area completely clean. Content stops right at the padding's edge. Excellent for nested layout modules.
+   - `padding-box` (Default): Clips content at the inner edge of the border.
+   - `border-box`: Clips content at the outer edge of the border, allowing content to sit under or partially overlap a translucent border.
+3. **Define a Specified Offset (The Bleed)**: Provide a length value (e.g., `15px` or `5px`) to create a safety zone before cutting pixels. This allows prominent child element shadows to render unclipped past the boundary edge without expanding layout geometry.
+4. **Combine Box-Edge and Offset**: Specify both a box edge and a length offset simultaneously (e.g., `content-box 15px`) to offset from a specific box edge.
+
+## Example Code
+
+The following examples demonstrate dynamic container layout controls, showcasing automated inner content curve nested framing and child element shadow protection alongside progressive enhancement fallbacks.
+
+### Block Containers: Nested Rounded Curves
+
+* Apply `overflow-clip-margin: content-box` to a parent container with rounded corners and custom padding.
+* Apply similar rounded corners on inner child media and footer components along the concentric inner content box boundary, solving awkward nesting curves without custom `calc()` logic.
+
+```html
+<div class="nested-curve-parent">
+  <img src="avatar.jpg" alt="Nested Curve Demo">
+  <div class="nested-curve-footer">Card Footer</div>
+</div>
+```
+
+```css
+/**
+ * Standard block layout container with outer corner radii and padding.
+ * Keeps base level 1 fallback clipping roughly at the inner padding box.
+ */
+.nested-curve-parent {
+  /* Level 1 Fallback: clips child roughly at the padding box */
+  overflow: hidden;
+}
+
+/* Inner footer component with 12px rounded to visually demonstrate automatic concentric corner clipping */
+.nested-curve-footer {
+  background: #111;
+  color: #fff;
+}
+
+@supports (overflow-clip-margin: content-box) {
+  .nested-curve-parent {
+    /* MANDATORY: overflow: clip is required on non-replaced elements */
+    overflow: clip;
+    /* Automatically curves clipping edge to match inner content-box radius */
+    overflow-clip-margin: content-box;
+  }
+}
+```
+
+### Block Containers: Child Element Shadow Bleed
+
+* Apply `overflow: clip` and define an extended `overflow-clip-margin` length offset to create a visible safety zone permitting the child's shadow to render unclipped outside the parent container without altering layout geometry. Without this, the child's shadow is clipped at the parent's boundary.
+
+```html
+<div class="safety-zone-parent">
+  <h4>Clipped Container</h4>
+  <p>Inner content boundaries safely contained.</p>
+  <!-- Child button element positioned inside with a prominent shadow -->
+  <button class="demo-glowing-btn">Submit</button>
+</div>
+```
+
+```css
+/**
+ * Standard block layout container clipping inner content.
+ * Base fallback uses overflow: hidden, which abruptly slices child element shadows.
+ */
+.safety-zone-parent {
+  /* Level 1 Fallback: clips overflowing content but truncates child shadows */
+  overflow: hidden;
+}
+
+/* Child button element positioned inside with an expanded shadow */
+.demo-glowing-btn {
+  display: block;
+  box-shadow: 0 8px 13px rgba(229, 46, 113, 0.7);
+}
+
+@supports (overflow-clip-margin: 15px) {
+  .safety-zone-parent {
+    overflow: clip;
+    /* Establishes a visible safety zone allowing child element shadows to render safely outside */
+    overflow-clip-margin: 15px;
+  }
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** apply `overflow: clip` on target elements when utilizing `overflow-clip-margin`, as setting `overflow` strictly to `clip` is **mandatory** on standard block layout containers to activate custom or inner curved clip margins.
+- **DO** set `overflow-clip-margin: content-box` on padded containers with rounded corners to automatically clip unrounded internal child elements into mathematically perfect nested border curves without manual padding subtraction logic.
+- **DO** configure `overflow-clip-margin` with a specified length offset when applying external visual effects (like `filter: drop-shadow()`) to prevent sharp bounding box truncation without altering or expanding layout geometry.
+- **DO NOT** apply `overflow: clip` if the container requires programmatic scroll manipulation via JavaScript or serves as the immediate layout context for `position: sticky` elements, as `clip` completely disables scrolling.
+
+## Fallback Strategies
+
+Baseline status for overflow: clip: Widely available. It's been Baseline since 2022-09-12.
+Supported by: Chrome 90 (Apr 2021), Edge 90 (Apr 2021), Firefox 81 (Sep 2020), and Safari 16 (Sep 2022).
+
+Browser support for overflow-clip-margin: Limited availability.
+Supported by: Firefox 148 (Feb 2026).
+Unsupported in: Chrome, Edge, and Safari.
+
+For target environments lacking native support for `overflow: clip` or `overflow-clip-margin`, progressive enhancement fallback strategies depend directly on the visual intent:
+- Fallback to `overflow: hidden` as the base experience to guarantee core boundaries are maintained.
+- Fallback to `overflow: visible` on elements where drop-shadows or external corner badges must not be truncated.
+
+### Complete Progressive Enhancement Fallback Implementation
+
+```html
+<!-- 1. Nested rounded edges fallback -->
+<div class="demo-container-fallback">
+  <img src="example.jpg" alt="Nested Curve Fallback">
+  <div class="demo-footer-fallback">Footer</div>
+</div>
+
+<!-- 2. Child element shadow bleed fallback -->
+<div class="demo-safety-parent">
+  <h4>Container</h4>
+  <p>Inner boundaries contained.</p>
+  <button class="demo-glowing-btn">Submit</button>
+</div>
+```
+
+```css
+/**
+ * 1. Block Container Nested Curves Fallback
+ * Keeps base level 1 fallback clipping roughly at the inner padding box.
+ */
+.demo-container-fallback {  
+  /* Level 1 Fallback: clip child roughly at padding box */
+  overflow: hidden;
+}
+
+.demo-container-fallback img {
+  object-fit: cover;
+  display: block;
+}
+
+@supports (overflow-clip-margin: content-box) {
+  .demo-container-fallback {
+    overflow: clip;
+    overflow-clip-margin: content-box;
+  }
+}
+
+/**
+ * 2. Child Element Shadow Bleed Fallback
+ * Base fallback clips content using overflow: hidden, abruptly truncating child element shadows.
+ */
+.demo-safety-parent {  
+  /* Level 1 Fallback */
+  overflow: hidden;
+}
+
+.demo-glowing-btn {
+  display: block;
+  width: 100%;
+  padding: 6px 12px;
+  background: #e52e71;
+  box-shadow: 0 8px 13px rgba(229, 46, 113, 0.65);
+}
+
+@supports (overflow-clip-margin: 15px) {
+  .demo-safety-parent {
+    overflow: clip;
+    overflow-clip-margin: 15px;
+  }
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/reduce-style-repetition.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/reduce-style-repetition.md
new file mode 100644
index 00000000..4c8246dc
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/reduce-style-repetition.md
@@ -0,0 +1,87 @@
+# Reduce Style Repetition with CSS Functions
+
+Maintaining large stylesheets often leads to repetitive logic, especially when dealing with design system tokens like gradients or responsive layout patterns.
+
+The CSS `@function` at-rule allows you to encapsulate this logic into reusable, parameterized functions, making your CSS more maintainable, consistent and DRY (Don't Repeat Yourself).
+
+## The `@function` Syntax
+
+A custom function is defined using the `@function` rule followed by a dashed name and a list of parameters. The function returns a value using the `result` property. 
+
+```css
+@function --my-function(--input1 <length>, --input2: default-value) returns <length> {
+  /* Logic goes here */
+  result: var(--input1);
+}
+```
+
+### Key Concepts
+- **Parameters:** Must start with a double dash (`--`).
+- **Defaults:** You can provide default values using a colon (`:`).
+- **Result:** The `result` property determines the value the function returns. The last `result` declared in the function body wins.
+- **Scoping:** Parameters and variables defined inside the function are locally scoped.
+- **Types:** You can require parameters and the returned value to match a CSS type with bracket notation (e.g., `<color>`) and allow multiple types with the `type` function (e.g., `type(<number> | <percentage>)`).
+
+## Practical Examples
+
+### 1. Design System Tokens (Gradients)
+Ensure consistent color gradients across your app by encapsulating gradient logic. The `--angle` provides a default value to provide consistency that can be overridden.
+
+```css
+@function --fancy-gradient(--start-color <color>, --end-color <color>, --angle: 98deg) returns <image>{
+  result: linear-gradient(in oklab var(--angle), var(--start-color), var(--end-color) );
+}
+
+.card {
+  background: --fancy-gradient(#ed73d7, #5d87e9);
+}
+```
+
+### 2. Conditional Layout Logic
+You can use `@media` or other queries directly inside a function to return different values based on the environment. When using conditional logic in a function, note that the `@function` does not "return" at the first value of `result`, but rather follows the CSS cascade, and resolves to the last value that matches based on the screen size, container size, or other query.
+
+```css
+@function --grid-template(--count <number>){
+  /* MANDATORY: Put default value first. */
+  result: 1fr; /* Default: stack */
+  @media (min-width: 800px) {
+    result: repeat(var(--count), 1fr); /* Grid on larger screens */
+  }
+}
+
+main {
+  display: grid;
+  grid-template-columns: --grid-template(2);
+}
+```
+
+## Best Practices
+- **Use Dashed Names:** Always prefix your function names and parameters with `--`.
+- **Provide Defaults:** Make your functions more robust by providing sensible default values.
+- **Keep it Simple:** Use functions for logic that is actually repeated or complex. Don't over-engineer simple property-value pairs.
+- **Use Types:** Ensure your parameters and return values are the expected types.
+- **Consider Precompiled Alternatives:** For functions that do not depend on user input, media queries or other client-side variation, consider using a CSS precompiler to avoid doing unnecessary work on the client. 
+
+### Fallback strategies
+
+Browser support for @function: Limited availability.
+Supported by: Chrome 139 (Aug 2025) and Edge 139 (Aug 2025).
+Unsupported in: Firefox and Safari.
+
+In browsers that do not support CSS Functions, values set using CSS functions will be invalid. To support other browsers, provide a fallback value for the property first. This will be overridden in browsers with CSS function support.
+
+```css
+.card {
+  /* Provide fallback, in this case a solid color. */
+  background: #5d87e9;
+  background: --fancy-gradient(#ed73d7, #5d87e9);
+}
+
+main {
+  /* Provide fallback, in this case a simple stacked default. */
+  grid-template-columns: 1fr;
+  grid-template-columns: --grid-template(2);
+}
+```
+
+If it is a requirement to reduce style repetition while supporting other browsers, consider a CSS precompiler with functions, like Sass.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/responsive-design.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/responsive-design.md
new file mode 100644
index 00000000..5ea79aae
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/responsive-design.md
@@ -0,0 +1,16 @@
+# Responsive design
+
+## Overall best practices
+
+- Use `@container` queries to create component-driven responsive layouts that adapt to their parent container's size rather than the viewport. See `size-aware-styling` (via `npx -y modern-web-guidance@latest retrieve "size-aware-styling"`) for more details.
+- Use dynamic viewport units (`dvh`, `dvw`) instead of `vh`/`vw` to prevent layout breakage when mobile browser UI elements (like address bars) appear or disappear.
+- Use `aspect-ratio` for media elements (like `<img>` and `<video>`) to reserve space during loading and prevent Cumulative Layout Shift (CLS).
+
+For the layout mechanics behind responsive UI (flexbox, grid, container query units, viewport units), see `css-layout` (via `npx -y modern-web-guidance@latest retrieve "css-layout"`).
+
+## Responsive typography
+
+- **DO** combine viewport-relative and font-relative units in `clamp()` for font sizes that scale with the viewport size while ensuring they stay within a desired range. For example, `clamp(2rem, 1rem + 5vw, 4rem)`. Adjust the proportion of viewport-relative and font-relative units to control how quickly the font-size changes.
+- **DON'T** use `vw` alone for font-size without `clamp()`, as it can scale text too small or too large on extreme screens.
+
+To scale type and spacing with the container instead of the viewport, see `fluid-scaling` (via `npx -y modern-web-guidance@latest retrieve "fluid-scaling"`).
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/selector-atrule-combinations.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/selector-atrule-combinations.md
new file mode 100644
index 00000000..c6002f52
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/selector-atrule-combinations.md
@@ -0,0 +1,150 @@
+# Selector & @-rule Combinations
+
+## The problem
+
+We often need to combine filtering criteria of different types, e.g. selectors + media queries, media queries + container queries, and so on.
+
+For example, combining `(prefers-color-scheme: dark)` with a selector that targets color scheme overrides (e.g. `:root:has(> head > meta[name="color-scheme"][content="dark"])` or `:root.dark`) to apply certain styles in light/dark mode regardless of how the color scheme was set.
+
+The naive approach leads to duplicated code:
+
+```css
+/* Light mode styles */
+.card.featured {
+  font-weight: 400;
+}
+
+#logo-dark {
+  display: none;
+}
+
+@media (prefers-color-scheme: dark) {
+  /* Dark mode styles */
+  :root:not(.light) {
+    .card.featured {
+      font-weight: 300;
+    }
+
+    #logo-dark {
+      display: inline;
+    }
+
+    #logo {
+      display: none;
+    }
+  }
+}
+
+/* Dark mode styles, again */
+:root.dark {
+  .card.featured {
+    font-weight: 300;
+  }
+
+  #logo-dark {
+    display: inline;
+  }
+
+  #logo {
+    display: none;
+  }
+}
+```
+
+## What to do instead
+
+Store the result of the combined filter on a custom property, then use container style queries to set rules based on that property.
+
+IMPORTANT: Due to how container queries work, this technique only works if we can set the custom property on an ancestor of any rules that must be matched.
+
+### 1. Decouple selection logic from applied rules
+
+```css
+:root {
+  --color-scheme: light;
+
+  @media (prefers-color-scheme: dark) {
+    --color-scheme: dark;
+  }
+
+  &:has(> head > meta[name="color-scheme"][content="dark"]) {
+    --color-scheme: dark;
+  }
+
+  &:has(> head > meta[name="color-scheme"][content="light"]) {
+    --color-scheme: light;
+  }
+}
+```
+
+### 2. Key on the custom property for applied rules
+
+```css
+@container not style(--color-scheme: dark) {
+  .card.featured {
+    font-weight: 400;
+  }
+
+  #logo-dark {
+    display: none;
+  }
+}
+
+@container style(--color-scheme: dark) {
+  .card.featured {
+    font-weight: 300;
+  }
+
+  #logo {
+    display: none;
+  }
+}
+```
+
+### 3. OPTIONAL: Utility classes for toggling visibility
+
+A very common case is toggling visibility based on whether the criteria match.
+Utility classes must win over arbitrary component styles (hence `!important`) and their shown `display` is unknown, so they can't use overrides — gate them with `not style(...)`:
+
+```css
+@container not style(--color-scheme: dark) {
+  .if-dark {
+    display: none !important;
+  }
+}
+
+@container not style(--color-scheme: light) {
+  .if-light {
+    display: none !important;
+  }
+}
+```
+
+## Fallbacks
+
+Baseline status for Container style queries: Newly available. It's been Baseline since 2026-05-19.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 151 (May 2026), and Safari 18 (Sep 2024).
+
+There are two types of fallbacks, depending on how critical the branching is and what constitutes an acceptable fallback.
+
+1. For critical branching, where all states must work correctly even if style queries are not supported, you simply cannot use style queries.
+Instead, use the naive approach above, duplicating rules for each state.
+Utility classes can still be used, as long as they are also defined that way.
+2. For non-critical branching, where a default state is acceptable, you can define the base styles outside of any `@container` rule, and only use style queries as overrides.
+This preserves most of the spirit of this approach, its main downside being the coupling of values that overrides introduce.
+
+```css
+#logo-dark {
+  display: none;
+}
+
+@container style(--color-scheme: dark) {
+  #logo-dark {
+    display: inline; /* override */
+  }
+
+  #logo {
+    display: none;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/size-aware-styling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/size-aware-styling.md
new file mode 100644
index 00000000..5085d555
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/size-aware-styling.md
@@ -0,0 +1,106 @@
+# Size Aware Styling
+
+## Overview
+
+Size-aware styling allows components to change their layout or appearance based on the space available to them, rather than the size of the whole screen. This is useful for components like cards or navigation bars that might be placed in different parts of a layout (like a narrow sidebar or a wide main area).
+
+Using container queries is recommended because it makes components truly modular. You do not need to know where the component will live or write complex media queries to handle every possible layout.
+
+## Implementation
+
+### 1. Define the container
+
+MANDATORY: You must first tell the browser which element is the container to be measured.
+
+```css
+.card-container {
+  /* Define the container type. Use 'inline-size' for width-based queries. */
+  /* You can also use 'size' for both width and height, but it requires explicit sizing. */
+  container-type: inline-size;
+}
+```
+
+### 2. Apply styles based on container size
+
+Use the `@container` rule to apply styles when the container reaches a certain size.
+
+```css
+/* Default styles for small containers (stacked layout) */
+.card {
+  display: flex;
+  flex-direction: column;
+  gap: 1rem;
+}
+
+/* Styles for larger containers (side-by-side layout) */
+/* This triggers when the container is wider than 400px */
+@container (min-width: 400px) {
+  .card {
+    flex-direction: row;
+    align-items: center;
+  }
+  
+  .card-image {
+    width: 150px;
+    height: 150px;
+  }
+}
+```
+
+### 3. Conditionally show content
+
+You can also use container queries to hide or show extra details when there is more room.
+
+```css
+.card-details {
+  /* Hide extra details by default in small spaces */
+  display: none;
+}
+
+@container (min-width: 600px) {
+  .card-details {
+    /* Show details when there is plenty of room */
+    display: block;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for Container queries (size): Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+For browsers that do not support container queries, the best approach is to use a safe default layout (like the stacked vertical layout) and progressively enhance it using media queries if the general screen size allows it.
+
+```css
+/* Default safe stacked layout */
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Fallback using media queries for older browsers */
+@media (min-width: 600px) {
+  .card {
+    flex-direction: row;
+  }
+}
+
+/* Overwrite with container queries where supported */
+@supports (container-type: inline-size) {
+  @media (min-width: 600px) {
+    .card {
+      /* Reset media query fallback if needed, or let container query handle it */
+      flex-direction: column;
+    }
+  }
+  
+  @container (min-width: 400px) {
+    .card {
+      flex-direction: row;
+    }
+  }
+}
+```
+
+This ensures that users on older browsers still get a usable layout, even if it does not adapt perfectly to every specific container width.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/style-parent-with-has.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/style-parent-with-has.md
new file mode 100644
index 00000000..99e6f5ac
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/style-parent-with-has.md
@@ -0,0 +1,200 @@
+# Style Parent with :has()
+
+## The Problem
+Often, an error state requires styling elements *outside* the input itself—for example, changing the color of a parent `fieldset` border, highlighting the `<label>`, or showing a global error icon in the card header. Historically, this required JavaScript to toggle classes on parent elements.
+
+## The Solution
+By combining `:has()` with `:user-invalid`, we can declaratively style any ancestor based on the validity state of a specific descendant. This keeps all presentation logic in CSS.
+
+### Implementation Strategy
+
+1.  **Selector**: Use `.parent:has(:user-invalid)` to target the container.
+2.  **Scope**: Be specific to avoid performance issues. Target `.field-group` rather than `body`.
+3.  **Fallback**: Requires JS to toggle classes on the parent if `:has()` is not supported.
+
+## Implementation Guide
+
+### 1. HTML Structure
+```html
+<form>
+  <div class="card-section">
+    <div class="header">
+      <h3>Profile Settings</h3>
+      <span class="status-icon"></span>
+    </div>
+
+    <div class="field">
+      <label for="username">Username</label>
+      <input type="text" id="username" required>
+    </div>
+  </div>
+</form>
+```
+
+### 2. CSS
+```css
+/* Default State */
+.card-section {
+  border: 1px solid #ccc;
+  border-left: 4px solid #ccc;
+}
+
+/*
+  Parent Styling Logic:
+  If the card contains ANY user-invalid input, turn the whole card's edge red.
+*/
+.card-section:has(:user-invalid) {
+  border-left-color: #d93025;
+  background-color: #fff8f8;
+}
+
+/* Change the icon too */
+.card-section:has(:user-invalid) .status-icon::after {
+  content: "⚠️";
+}
+```
+
+## Fallbacking & Browser Support
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+We use a class `.has-error` on the parent to mimic the `:has()` behavior.
+
+```css
+/* Native */
+.card-section:has(:user-invalid) {
+  border-left-color: #d93025;
+}
+
+/* Fallback */
+.card-section.has-error-fallback {
+  border-left-color: #d93025;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+```js
+// 1. Initialize the generic fallback
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+
+// 2. Add specialized "parent styling" logic (Separate from fallback)
+// Listen for changes to form validity after interaction
+form.addEventListener('blur', (e) => {
+  if (!e.target.matches('input, select, textarea')) return;
+
+  // Find the container we want to style (sync with CSS)
+  const container = e.target.closest('.card-section');
+  if (!container) return;
+
+  // Check if ANY fallbacked input in this container is invalid
+  const hasError = container.querySelector('.user-invalid-fallback');
+  container.classList.toggle('has-error-fallback', !!hasError);
+}, true); // Capture phase to ensure we run after the fallback's blur listener
+
+// Also handle input events for immediate cleanup
+form.addEventListener('input', (e) => {
+  const container = e.target.closest('.card-section');
+  if (container) {
+    const hasError = container.querySelector('.user-invalid-fallback');
+    container.classList.toggle('has-error-fallback', !!hasError);
+  }
+});
+
+// Handle form resets
+form.addEventListener('reset', () => {
+  form.querySelectorAll('.has-error-fallback').forEach(el => {
+    el.classList.remove('has-error-fallback');
+  });
+});
+```
+
+## Other Considerations
+
+1.  **Accessibility**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/usage-aware-component-variations.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/usage-aware-component-variations.md
new file mode 100644
index 00000000..3d66a3fe
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/css/usage-aware-component-variations.md
@@ -0,0 +1,108 @@
+# Semantic Component Adaptation
+
+Use style queries (`@container style()`) to trigger contextual variations without hardcoding what produces or reacts to each context. This reduces design system coupling and improves extensibility and component encapsulation.
+
+For example, a `section.featured { --surface: featured }` rule can mark a context, and a landing page might also default to it via `main { --surface: featured }`. Components then opt in to react to `--surface: featured`: a card reveals a promotional badge, a button defaults to its filled variant, and so on.
+
+Style queries let **both sides stay decoupled**: the featured surfaces never name the elements that adapt to them, and the components never inspect what produced the context. Either side can be extended independently — new components, new featured surfaces — without touching the other. Descendant selectors (e.g., `.featured .button`) force the opposite: the selector must encode both sides of the relationship and must change whenever either side does.
+
+## When to use this guide
+
+This guide covers *behavioral* changes: a component deciding **what to render, how to arrange itself, or which variant to present** in response to its context — hiding or showing a badge, switching layout direction, or swapping a button variant.
+
+If instead you need *token-level* changes — density modes, themes, or other higher-order tokens that uniformly shift values like padding and color across many components — see `design-token-reactivity` (via `npx -y modern-web-guidance@latest retrieve "design-token-reactivity"`).
+
+## Choosing the right tool
+
+Reach for a style query when **both sides of a contextual relationship may change independently** — new elements may start producing the context, or new components may start reacting to it. The indirection pays for itself in extensibility and encapsulation, and style queries cross shadow DOM boundaries that descendant selectors cannot. When that flexibility isn't needed, prefer the simpler tool:
+
+- **Descendant selectors** (`.toolbar .button`): a fixed, one-off relationship that isn't reusable or extensible. YAGNI applies — don't add indirection you won't use.
+- **Size queries** (`@container (min-width: …)`): layout and density changes driven by available space, not semantic state.
+- **Style queries** (`@container style(…)`): semantic state — what a component should render, arrange, or present in a given context.
+
+## Implementation Directives
+
+1. Define a semantic context flag using a CSS custom property on a container.
+2. **DO NOT** set `container-type` for style queries; they query inherited custom properties on the nearest ancestor and don't require an explicit containment context.
+3. **MANDATORY**: Use `@container style(--property: value)` to apply conditional styles to descendant elements. Style queries cannot match the element the property is set on — only its descendants.
+4. **DO** prefer style queries over descendant selectors when the relationship must stay extensible or cross component/shadow DOM boundaries (see *Choosing the right tool* above) — but keep descendant selectors for fixed, one-off relationships where the indirection buys nothing.
+
+## Implementation Example
+
+```css
+/* 1. Set the context on a layout container */
+.featured {
+  --surface: featured; /* Semantic context flag for children */
+}
+
+/* 2. Component reacts to inherited flag */
+.button {
+  /* Default: Outlined informational style */
+  background: transparent;
+  border: 1px solid currentColor;
+}
+
+.badge {
+  /* Default: Hidden — only revealed in featured surfaces */
+  display: none;
+}
+
+@container style(--surface: featured) {
+  .button {
+    /* Automatic switch to Filled promotional style */
+    background: var(--brand-accent);
+    color: white;
+    border: none;
+  }
+
+  .badge {
+    /* Reveal decorative elements only in featured context */
+    display: block;
+  }
+}
+```
+
+## Fallback Strategies
+
+Baseline status for Container style queries: Newly available. It's been Baseline since 2026-05-19.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 151 (May 2026), and Safari 18 (Sep 2024).
+
+Until container style queries are widely available, layer them on as a progressive enhancement: ship a selector-based default that works everywhere, and let the style query override it when supported. Use `:where()` on the context selector so the style query (same specificity, later in source order) wins automatically.
+
+```css
+/* Default styles — work everywhere */
+.button {
+  background: transparent;
+  border: 1px solid currentColor;
+}
+
+.badge {
+  display: none;
+}
+
+/* Selector-based contextual styles — broad browser support */
+:where(.featured) .button {
+  background: var(--brand-accent);
+  color: white;
+  border: none;
+}
+
+:where(.featured) .badge {
+  display: block;
+}
+
+/* Progressive enhancement: style queries override when supported */
+@container style(--surface: featured) {
+  .button {
+    background: var(--brand-accent);
+    color: white;
+    border: none;
+  }
+
+  .badge {
+    display: block;
+  }
+}
+```
+
+The selector fallback ties the contextual styling to a class name, which couples the component to its DOM placement. Once style queries are widely supported, the `:where()` rule can be removed.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/animated-select-picker.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/animated-select-picker.md
new file mode 100644
index 00000000..f66fd413
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/animated-select-picker.md
@@ -0,0 +1,179 @@
+# Animated Select Picker
+
+The customizable select API offers a declarative, CSS-driven way to animate `<select>` elements and their dropdown pickers. By combining `appearance: base-select` with modern CSS animation techniques—such as `@starting-style` and the `allow-discrete` transition behavior—you can create fluid, premium UI transitions for top-layer elements without relying on heavy JavaScript libraries.
+
+Previously, animating native select dropdowns was impossible because their UI was rendered outside the accessible viewport constraints. With `appearance: base-select`, the picker becomes styleable and animatable like any other page element.
+
+## How to Implement
+
+To implement an animated select picker:
+
+1. **Opt-in to customization:** Apply `appearance: base-select` to both the `<select>` element and the `::picker(select)` pseudo-element.
+2. **Enable auto-sizing transitions (Optional):** Define `interpolate-size: allow-keywords` (usually on `:root`) to allow the browser to transition between discrete metric values like `height: auto` and `height: 0`.
+3. **Animate the top-layer container:** Apply standard entry/exit styles to `::picker(select)`. To make sure the opacity transition works when moving between `display: none` and `display: block`, you must use `transition-behavior: allow-discrete` (often written inline as `transition: display 0.3s allow-discrete`).
+4. **Hook into the opening state with `@starting-style`:** Use `@starting-style` to define the baseline styles the browser should compute *before* the transition begins. For example, if you want it to fade in, set the opacity to `0` inside the `@starting-style` block.
+5. **Rotate the icon:** Use pseudo-element focus or active selectors like `:open::picker-icon` to apply transitions (such as rotation or translation) to the arrow indicator.
+
+## Example Code: Smooth Select Scale and Fade
+
+The following example demonstrates a custom select styled with standard page animations for the picker container.
+
+```html
+<!-- Always use a <label> linked via 'for' to the select for accessibility -->
+<label for="theme-select">Visual Theme</label>
+<select id="theme-select" class="animated-select" name="theme">
+  <!-- The <button> inside <select> becomes the visible trigger when appearance: base-select is used -->
+  <button>
+    <!-- <selectedcontent> automatically displays the content of the chosen <option> -->
+    <selectedcontent></selectedcontent>
+  </button>
+  <option value="system">
+    <!-- MANDATORY: Decorative inline SVGs MUST set aria-hidden="true" to prevent redundant screen reader announcement -->
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
+      <line x1="8" y1="21" x2="16" y2="21"></line>
+      <line x1="12" y1="17" x2="12" y2="21"></line>
+    </svg>
+    System Default
+  </option>
+  <option value="light">
+    <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+      <circle cx="12" cy="12" r="5"></circle>
+      <line x1="12" y1="1" x2="12" y2="3"></line>
+      <line x1="12" y1="21" x2="12" y2="23"></line>
+      <line x1="4.22" y1="4.22" x2="5.64" y2="5.64"></line>
+      <line x1="18.36" y1="18.36" x2="19.78" y2="19.78"></line>
+      <line x1="1" y1="12" x2="3" y2="12"></line>
+      <line x1="21" y1="12" x2="23" y2="12"></line>
+      <line x1="4.22" y1="19.78" x2="5.64" y2="18.36"></line>
+      <line x1="18.36" y1="5.64" x2="19.78" y2="4.22"></line>
+    </svg>
+    Light UI
+  </option>
+</select>
+```
+
+```css
+/* Opt-in to customizable select */
+.animated-select,
+.animated-select::picker(select) {
+  appearance: base-select;
+}
+
+/* Enable auto-keyword transitions (usually set globally at :root) */
+:root {
+  interpolate-size: allow-keywords;
+}
+
+/* Style the visible trigger and icon rotation */
+.animated-select {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 0.875rem 1rem;
+  font-size: 1rem;
+  border-radius: 8px;
+  cursor: pointer;
+  transition: border-color 0.2s ease;
+}
+
+.animated-select::picker-icon {
+  transition: transform 0.3s cubic-bezier(0.16, 1, 0.3, 1);
+}
+
+.animated-select:open::picker-icon {
+  transform: rotate(180deg);
+}
+
+/*
+ * The Picker Container
+ * Uses top-layer animations with `allow-discrete` visibility hooks
+ */
+.animated-select::picker(select) {
+  background: white;
+  border-radius: 12px;
+  box-shadow: 0 10px 25px -3px rgba(0,0,0,0.1);
+  padding: 0.5rem;
+  margin-top: 0.25rem;
+  width: anchor-size(width);
+  overflow: hidden;
+
+  /* The crucial transition setting for popover animations */
+  transition:
+    display 0.4s allow-discrete,
+    overlay 0.4s allow-discrete,
+    opacity 0.4s cubic-bezier(0.16, 1, 0.3, 1),
+    height 0.4s cubic-bezier(0.16, 1, 0.3, 1);
+  opacity: 0;
+  height: 0;
+}
+
+/* Open State */
+.animated-select:open::picker(select) {
+  opacity: 1;
+  height: auto;
+}
+
+/* @starting-style to hook the transition on initial popover open */
+@starting-style {
+  .animated-select:open::picker(select) {
+    opacity: 0;
+    height: 0;
+  }
+}
+
+/* Support for SVG inside Options and Selected Content */
+.animated-select option svg,
+.animated-select selectedcontent svg {
+  flex-shrink: 0; /* Prevent icons from shrinking */
+  width: 1.25rem;
+  height: 1.25rem;
+}
+
+/* MANDATORY: Provide multiple indicators (e.g. bold font and distinct background) for the checked state to avoid color-only state communication */
+.animated-select option:checked {
+  font-weight: 700;
+  background-color: #f1f5f9;
+}
+
+/* Ensure copy-paste safety for users with motion sensitivities */
+@media (prefers-reduced-motion: reduce) {
+  .animated-select::picker(select),
+  .animated-select::picker-icon {
+    transition: none !important;
+  }
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `@starting-style` when you need animations to trigger exactly when an element transitions from `display: none` to visible.
+- **DO NOT** use ad-hoc scroll locking. Top-layer elements managed by ‘base-select’ should allow natural backdrop dismiss behaviors.
+- **DO** verify reduced motion preferences. Always wrap animation constraints in a `prefers-reduced-motion` media query to ensure accessible environments for those affected by motion sickness.
+- Test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- Ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+- Use standard `value` attributes on options to ensure form submission works exactly as before.
+
+## Fallback strategies
+
+### Fallbacks & browser support for Customizable <select>
+
+Browser support for Customizable <select>: Limited availability.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), and Safari 27 (Sep 2026).
+Unsupported in: Firefox.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-address-form.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-address-form.md
new file mode 100644
index 00000000..9050337f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-address-form.md
@@ -0,0 +1,82 @@
+# Build an address form that follows best practice
+
+Create a form that makes it as easy as possible for users to enter address data on desktop and mobile. Ensure the form makes the most of built-in browser features for autofill, validation and data entry constraints.
+
+## How to implement
+
+Outlined below are the most important guidelines for building successful address forms.
+
+### Use meaningful, valid HTML
+
+Make the most of the elements and attributes built for creating forms:
+
+-   `<form>`, `<input>`, `<label>`, and `<button>`
+-   `type`, `autocomplete`, and `inputmode`
+
+These enable built-in browser functionality, improve accessibility, and add meaning to markup.
+
+### Use the `<label>` element to label form fields for data entry
+
+To label an `<input>`, `<select>`, or `<textarea>`, use a `<label>`. Associate a label with an input by giving the label's `for` attribute the same value as the input's `id`.
+
+### Make the most of HTML attributes
+
+Make it easy for users to enter data, by using the appropriate `<input>` element `<type>` attribute to provide the right keyboard on mobile and enable basic built-in validation by the browser.
+
+Always use `type="email"` for email addresses and `type="tel"` for phone numbers.
+
+```html
+<!-- type="email"/"tel" gives mobile users the right keyboard and enables built-in validation -->
+<input type="email" id="email" name="email" autocomplete="email" required>
+<input type="tel" id="phone" name="phone" autocomplete="tel">
+```
+
+Every `<input>`, `<select>`, and `<textarea>` element SHOULD have an appropriate `autocomplete` attribute, to improve accessibility and help users avoid re-entering data.
+
+### Make buttons helpful
+
+Use `<button>` for buttons. You can also use `<input type="submit">`, but don't use a `div` or some other random element acting as a button. Button elements provide accessible behaviour, built-in form submission functionality, and can easily be styled.
+
+Give each form submit button a value that says what it does. For each step towards checkout, use a descriptive call-to-action that shows progress and makes the next step obvious. For example, label the submit button on your delivery address form **Proceed to Payment** rather than **Continue** or **Save**.
+
+### Use a single name input where possible
+
+Allow your users to enter their name using a single input, unless you have a good reason for separately storing given names, family names, honorifics, or other name parts. Using a single name input makes forms less complex, enables cut-and-paste, and makes autofill simpler.
+
+Allow international names. For validation, avoid using regular expressions that only match Latin characters. Latin-only excludes users with names or addresses that include characters that aren't in the Latin alphabet. Allow Unicode letter matching instead—and ensure your backend supports Unicode securely as both input and output. Unicode in regular expressions is well supported by modern browsers.
+
+### Allow for a variety of address formats
+
+When building an address form, be aware of the variety of address formats, even within a single country. Do not make assumptions about "normal" addresses.
+
+Use a single `<textarea>` element for the street address if possible.
+
+```html
+<!-- textarea handles multi-line international address formats that split inputs can't accommodate -->
+<textarea id="address" name="address" autocomplete="street-address" required></textarea>
+```
+
+This is the most flexible option for a variety of local and international address formats.
+
+If your data model needs separate address lines, use one `<input>` per line with the `address-line1`, `address-line2` (and, if needed, `address-line3`) `autocomplete` tokens so that autofill still works. Don't split the street address across inputs that lack these tokens, and make only the first line required.
+
+```html
+<!-- Alternative: one input per line, each with its own autocomplete token -->
+<input type="text" id="address-line1" name="address-line1" autocomplete="address-line1" required>
+<input type="text" id="address-line2" name="address-line2" autocomplete="address-line2">
+```
+
+### Help save users from accidentally missing data fields
+
+Add the `required` attribute to mandatory fields.
+
+```html
+<input type="text" id="city" name="city" autocomplete="address-level2" required>
+```
+
+### Fallback strategies
+
+Baseline status for the html.elements.input.autocomplete capability: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 14 (Sep 2011), Edge 12 (Jul 2015), Firefox 4 (Mar 2011), and Safari 6 (Jul 2012).
+
+Autofill is a progressive enhancement. In browsers that do not support autofill, users will simply need to manually enter their address details. The semantic HTML constraints (such as `type`, `inputmode`, and `required`) will still function appropriately as standard form validation.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-highlight-inputs.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-highlight-inputs.md
new file mode 100644
index 00000000..586192e5
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-highlight-inputs.md
@@ -0,0 +1,45 @@
+# Use the CSS :autofill pseudo-class to highlight form fields that have been autofilled by the browser and not edited by the user
+
+Use the CSS `:autofill` to highlight fields that have (or have not been) autofilled, to help guide the user to successful form completion.
+
+## How to implement
+
+To highlight a form field that has been autofilled by the browser (and not edited by the user) add a selector to your CSS using the `:autofill` class. This can be used for an `<input>`, `<select>`, or `<textarea>` element.
+
+When styling autofilled states, you must adhere to accessibility best practices:
+- **Multiple State Indicators**: Do not rely on border color alone to indicate the autofilled state. Use multiple indicators such as border thickness and custom background shading to ensure the state is perceivable.
+- **Preserve Focus Indicators**: Never remove focus outlines (`outline: none`) without providing a clear, high-contrast replacement for keyboard users.
+
+The following example uses `:autofill` to set a custom border and background, along with explicit focus styles:
+
+```css
+input:autofill,
+input:-webkit-autofill {
+  /* Multiple indicators: use both a distinct border and background color via box-shadow to avoid color-only state */
+  border: 2px solid #2e7d32;
+  box-shadow: 0 0 0 100vmax #e8f5e9 inset;
+}
+
+/* MANDATORY: Always provide an explicit focus indicator when styling autofilled states */
+input:autofill:focus-visible,
+input:-webkit-autofill:focus-visible {
+  outline: 3px solid #000;
+  outline-offset: 2px;
+}
+```
+
+As shown in this example, the `box-shadow` property is used to customize the background, since `background-color` cannot be overridden directly on autofilled fields.
+
+## Use the correct CSS pseudo-class name
+
+**Do not** use `:auto-fill`: this is incorrect.
+
+MANDATORY: Use `:autofill` as this is the correct pseudo-class name.
+
+### Fallback strategies
+
+Browser support for :autofill: Limited availability.
+Supported by: Chrome 110 (Feb 2023), Edge 110 (Feb 2023), and Safari 15 (Sep 2021).
+Unsupported in: Firefox.
+
+The `:autofill` pseudo-class is a progressive enhancement. In browsers that do not support it, the form will still function normally, but the inputs will simply not receive the custom autofill highlighting. Users will still be able to successfully complete the form. No additional JavaScript fallback should be used.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-payment-form.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-payment-form.md
new file mode 100644
index 00000000..7ba4e34d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-payment-form.md
@@ -0,0 +1,138 @@
+# Build a payment form that follows best practice
+
+Payment forms are the single most critical part of the checkout process. Poor payment form design is a common cause of shopping cart abandonment.
+
+Create a form that makes it as easy as possible for users to enter payment details on desktop and mobile. Ensure the form makes the most of built-in browser features for autofill, validation and data entry constraints.
+
+## How to implement
+
+Outlined below are the most important guidelines for building successful payment forms.
+
+### Use meaningful, valid HTML
+
+Make the most of the elements and attributes built for creating forms:
+
+-   `<form>`, `<input>`, `<label>`, and `<button>`
+-   `type`, `autocomplete`, and `inputmode`
+
+These enable built-in browser functionality, improve accessibility, and add meaning to markup.
+
+### Use the `<label>` element to label form fields for data entry
+
+To label an `<input>`, `<select>`, or `<textarea>`, use a `<label>`. Associate a label with an input by giving the label's `for` attribute the same value as the input's `id`.
+
+### Make the most of HTML attributes
+
+Make it easy for users to enter data, by using the appropriate `<input>` element `<type>` attribute to provide the right keyboard on mobile and enable basic built-in validation by the browser.
+
+Always use `type="email"` for email addresses and `type="tel"` for phone numbers.
+
+```html
+<!-- type="email"/"tel" gives mobile users the right keyboard and enables built-in validation -->
+<input type="email" id="email" name="email" autocomplete="email" required>
+<input type="tel" id="phone" name="phone" autocomplete="tel">
+```
+
+Every `<input>`, `<select>`, and `<textarea>` element SHOULD have an appropriate `autocomplete` attribute, to improve accessibility and help users avoid re-entering data.
+
+### Make buttons helpful
+
+Use `<button>` for buttons. You can also use `<input type="submit">`, but don't use a `div` or some other random element acting as a button. Button elements provide accessible behavior, built-in form submission functionality, and can easily be styled.
+
+Give each form submit button a value that says what it does. For each step toward checkout, use a descriptive call-to-action that shows progress and makes the next step obvious. For example, label the submit button on your delivery address form **Proceed to Payment** rather than **Continue** or **Save**.
+
+### Use a single name input where possible
+
+Allow your users to enter their name using a single input, unless you have a good reason for separately storing given names, family names, honorifics, or other name parts. Using a single name input makes forms less complex, enables cut-and-paste, and makes autofill simpler.
+
+Allow international names. For validation, avoid using regular expressions that only match Latin characters. Latin-only excludes users with names or addresses that include characters that aren't in the Latin alphabet. Allow Unicode letter matching instead—and ensure your backend supports Unicode securely as both input and output. Unicode in regular expressions is well supported by modern browsers.
+
+### Allow for a variety of address formats
+
+When adding form fields for an address in a payment form, be aware of the variety of address formats, even within a single country. Do not make assumptions about "normal" addresses.
+
+If possible within your data requirements, consider using a single `<textarea>` element for address. This is the most flexible option for a variety of local and international address formats.
+
+### Use autocomplete for billing address
+
+By default, set the billing address to be the same as the delivery address. Reduce visual clutter by providing a link to edit the billing address (or use summary and details elements) rather than displaying the billing address in a form.
+
+Use appropriate autocomplete values for the billing address, just as you do for shipping address, so the user doesn't have to enter data more than once. Add a prefix word to autocomplete attributes if you have different values for inputs with the same name in different sections. For example:
+
+```html
+<!-- Prefix with shipping or billing; note that the valid token is address-line1 (no hyphen before the digit) -->
+<input autocomplete="shipping address-line1" ...>
+...
+<input autocomplete="billing address-line1" ...>
+```
+
+### Show checkout progress
+
+For each step toward payment, use page headings and descriptive button values that make it clear what needs to be done now, and what checkout step is next.
+
+Use the `enterkeyhint` attribute on form inputs to set the mobile keyboard enter key label. For example, use `enterkeyhint="previous"` and `enterkeyhint="next"` within a multi-page form, `enterkeyhint="done"` for the final input in the form, and `enterkeyhint="search"` for a search input.
+
+### Help users avoid re-entering payment data
+
+Make sure to add appropriate `autocomplete` values in payment card forms. Without autocomplete, users may keep a physical record of payment card details or store them insecurely.
+
+```html
+<!-- cc-number tells autofill this is a card number, not a generic number field -->
+<!-- inputmode="numeric" gives a numeric keyboard without the increment/decrement spinner -->
+<!-- DO NOT use type="number" — it adds increment/decrement controls and strips leading zeros -->
+<input id="cc-number" name="cc-number" type="text" autocomplete="cc-number"
+       inputmode="numeric" maxlength="19" pattern="[\d ]{13,19}" required>
+
+<!-- cc-name autofills with the name exactly as it appears on the card; Unicode pattern allows international names -->
+<input id="cc-name" name="cc-name" type="text" autocomplete="cc-name"
+       maxlength="50" pattern="[\p{L} \-\.]+" required>
+
+<!-- cc-exp autofills the full expiry date as MM/YY -->
+<!-- MANDATORY: Place format hints above the input so autocomplete popovers or virtual keyboards do not obscure them during editing -->
+<span id="exp-hint" class="hint">Format: MM/YY</span>
+<input id="cc-exp" name="cc-exp" type="text" autocomplete="cc-exp"
+       aria-describedby="exp-hint" maxlength="5" required>
+
+<!-- cc-csc autofills the security code; DO NOT use type="password" here -->
+<input id="cc-csc" name="cc-csc" type="text" autocomplete="cc-csc"
+       inputmode="numeric" maxlength="4" pattern="[0-9]{3,4}" required>
+```
+
+### Show format hints above the input
+
+Where a field has a required format (for example the `MM/YY` expiry date), put the hint in a visible element **above** the input and link the two with `aria-describedby`, as in the `cc-exp` example above. Hints that sit below an input are easily hidden by the mobile keyboard or by the autofill popover at the moment the user needs them.
+
+Don't rely on the `placeholder` attribute as the only format hint, and never use it instead of a `<label>`: placeholder text is hidden as soon as the user starts typing, so it can't be checked against while editing. A placeholder is fine as an extra cue alongside the label and the persistent hint.
+
+### Don't mask the security code
+
+Use `type="text"` with `inputmode="numeric"` for the card security code, not `type="password"`. Users can't check a masked three- or four-digit code for typos, so a mistyped digit isn't caught until the payment is declined, and masking adds little protection because the code is printed on the card the user is holding.
+
+### Use a single input for payment card and phone numbers
+
+For payment card and phone numbers use a single input: don't split the number into parts. That makes it easier for users to enter data, makes validation simpler, and enables browsers to autofill. Consider doing the same for other numeric data such as PIN and bank codes.
+
+### Validate carefully
+
+You should validate data entry both in realtime and before form submission. One way to do this is by adding a pattern attribute to a payment card input. If the user attempts to submit the payment form with an invalid value, the browser displays a warning message and sets focus on the input.
+
+However, your pattern regular expression must be flexible enough to handle the range of payment card number lengths: from 14 digits (or possibly less) to 20 (or more). Card security codes (also known as CSC, CVC, CVV, or other names) consist of 3 or 4 digits.
+
+Allow users to include spaces when they're entering a new payment card number, since this is how numbers are displayed on physical cards. That's friendlier to the user (you won't have to tell them "they did something wrong"), less likely to interrupt conversion flow, and it's straightforward to remove spaces in numbers before processing.
+
+### Help save users from accidentally missing data fields
+
+Add the `required` attribute to mandatory fields. Modern browsers automatically prompt and set focus for missing data.
+
+## Fallback strategies
+
+Baseline status for enterkeyhint: Widely available. It's been Baseline since 2021-11-02.
+Supported by: Chrome 77 (Sep 2019), Edge 79 (Jan 2020), Firefox 94 (Nov 2021), Safari 13.1 (Mar 2020), and Safari iOS 13.4 (Mar 2020).
+
+Baseline status for Email, telephone, and URL <input> types: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 5 (May 2010), Edge 12 (Jul 2015), Firefox 4 (Mar 2011), Safari 5 (Jun 2010), and Safari iOS 3 (Jun 2009).
+
+Baseline status for inputmode: Widely available. It's been Baseline since 2021-12-07.
+Supported by: Chrome 66 (Apr 2018), Edge 79 (Jan 2020), Firefox 95 (Dec 2021), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Autofill is a progressive enhancement. In browsers that do not support autofill, users will simply need to manually enter their payment details. The semantic HTML constraints (such as `type`, `inputmode`, `pattern`, and `required`) will still function appropriately to validate user input and provide the correct virtual keyboards.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-in-form.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-in-form.md
new file mode 100644
index 00000000..2acf4427
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-in-form.md
@@ -0,0 +1,141 @@
+# Build a sign-in form that follows best practice
+
+Use cross-platform browser features to build sign-in forms that are secure, accessible and easy to use.
+
+If users ever need to sign in to your site, then good sign-in form design is critical. This is especially true for people on poor connections, on mobile, in a hurry, or under stress. Poorly designed sign-in forms get high bounce rates. Each bounce could mean a lost customer and a disgruntled user—not just a missed sign-in opportunity.
+
+## How to implement
+
+Outlined below are the most important guidelines for building successful sign-in forms.
+
+### Use meaningful, valid HTML
+
+Make the most of the elements and attributes built for creating forms:
+
+- `<form>`, `<input>`, `<label>`, and `<button>`
+- `type`, `autocomplete`, and `inputmode`
+
+These enable built-in browser functionality, improve accessibility, and add meaning to markup.
+
+### Use the `<label>` element to label form fields for data entry
+
+To label an `<input>`, `<select>`, or `<textarea>`, use a `<label>`. Associate a label with an input by giving the label's `for` attribute the same value as the input's `id`.
+
+### Make the most of HTML attributes
+
+Make it easy for users to enter data, by using the appropriate `<input>` element `<type>` attribute to provide the right keyboard on mobile and enable basic built-in validation by the browser.
+
+Always use `type="email"` for email addresses and `type="tel"` for phone numbers.
+
+Every `<input>`, `<select>`, and `<textarea>` element SHOULD have an appropriate `autocomplete` attribute, to improve accessibility and help users avoid re-entering data.
+
+Username and email inputs hold identifiers, not prose. Add `spellcheck="false"` so the browser does not rewrite them into something the account does not match. `autocorrect` and `autocapitalize` are always disabled for `input type="email"`, but are required for non-email usernames.
+
+### Make buttons helpful
+
+Use `<button>` for buttons. You can also use `<input type="submit">`, but don't use a `div` or some other random element acting as a button. Button elements provide accessible behaviour, built-in form submission functionality, and can easily be styled.
+
+Give each form submit button a value that says what it does. Use a clear, recognizable label. For example, use **Sign In** rather than **Continue** or **Submit**.
+
+### Use a single name input where possible
+
+Allow your users to enter their name using a single input, unless you have a good reason for separately storing given names, family names, honorifics, or other name parts. Using a single name input makes forms less complex, enables cut-and-paste, and makes autofill simpler.
+
+Allow international names. For validation, avoid using regular expressions that only match Latin characters. Latin-only excludes users with names or addresses that include characters that aren't in the Latin alphabet. Allow Unicode letter matching instead—and ensure your backend supports Unicode securely as both input and output. Unicode in regular expressions is well supported by modern browsers.
+
+### Show sign-in progress
+
+For each step towards sign-in, use page headings and descriptive button values that make it clear what needs to be done now, and what the next step is.
+
+Use the `enterkeyhint` attribute on form inputs to set the mobile keyboard enter key label. For example, use `enterkeyhint="previous"` and `enterkeyhint="next"` within a multi-page form, `enterkeyhint="done"` for the final input in the form, and `enterkeyhint="search"` for a search input.
+
+### Help users avoid re-entering sign-in data
+
+Make sure to add appropriate `autocomplete` values in sign-in forms.
+
+This enables browsers to help users by securely storing sign-in details and correctly entering form data. Without autocomplete, users may be more likely to keep a physical record of sign-in details, or store sign-in data insecurely on their device.
+
+### Validate carefully
+
+Validate data entry both in realtime and before form submission. Use `type="email"` for email inputs — the browser will validate the format automatically. Add the `required` attribute to mandatory fields to prevent empty submissions.
+
+### Put sign-in in its own `<form>` element
+
+Always use the `<form>` element when you're getting users to enter data
+
+Don't wrap inputs in a `<div>` and handle input data submission purely with JavaScript. It's generally better to use a `<form>` element. This makes your site accessible to screenreaders and other assistive devices, enables a range of built-in browser features, makes it simpler to build basic functional sign-in for older browsers, and can still work even if JavaScript fails.
+
+### Don't double up inputs
+
+Some sites force users to enter emails or passwords twice. That might reduce errors for a few users, but causes extra work for all users, and increases abandonment rates. Asking twice also makes no sense where browsers autofill email addresses or suggest strong passwords. It's better to enable users to confirm their email address (you'll need to do that anyway) and make it easy for them to reset their password if necessary.
+
+### Keep passwords private—but enable users to see them if they want
+
+Passwords inputs should have `type="password"` to hide password text and help the browser understand that the input is for passwords. (Note that browsers use a variety of techniques to understand input roles and decide whether or not to offer to save passwords.)
+
+You should add a **Show password** toggle to enable users to check the text they've entered—and don't forget to add a **Forgot password** link.
+
+### Give mobile users the right keyboard
+
+Use `<input type="email">` to give mobile users an appropriate keyboard and enable basic built-in email address validation by the browser… no JavaScript required!
+
+If you need to use a telephone number instead of an email address, `<input type="tel">` enables a telephone keypad on mobile. You can also use the `inputmode` attribute where necessary: `inputmode="numeric"` is ideal for PIN numbers.
+
+### Prevent mobile keyboard from obstructing the Sign in button
+
+If you're not careful, mobile keyboards may cover your form or, worse, partially obstruct the Sign in button. Users may give up before realizing what has happened.
+
+Where possible, avoid this by displaying only the email (or phone) and password inputs and Sign in button at the top of your sign-in page. Put other content underneath.
+
+### Help users to avoid re-entering data
+
+You can help browsers store data correctly and autofill inputs, so users don't have to remember to enter email and password values. This is particularly important on mobile, and crucial for email inputs, which get high abandonment rates. There are two parts to this:
+
+1.  The `autocomplete`, `name`, `id`, and `type` attributes help browsers understand the role of inputs in order to store data that can later be used for autofill. To allow data to be stored for autofill, modern browsers also require inputs to have a stable `name` or `id` value (not randomly generated on each page load or site deployment), and to be in a `<form>` element with a `submit` button.
+1.  The `autocomplete` attribute helps browsers correctly autofill inputs using stored data.
+
+For email inputs use `autocomplete="username"`, since `username` is recognized by password managers in modern browsers—even though you should use `type="email"` and you may want to use `id="email"` and `name="email"`. For password inputs, use the appropriate `autocomplete` value to help browsers differentiate between new and current passwords.
+
+### Use autocomplete="current-password" for an existing password
+
+MANDATORY: Use `autocomplete="current-password"` for the password input in a sign-in form. This tells the browser that you want it to use the current password that it has stored for the site.
+
+For a sign-in form:
+
+```
+<input type="password" autocomplete="current-password" id="current-password" …>
+```
+
+### Enable the browser to suggest a strong password
+
+Modern browsers use heuristics to decide when to show the password manager UI and suggest a strong password.
+
+Built-in browser password generators mean users and developers don't need to work out what a "strong password" is. Since browsers can securely store passwords and autofill them as necessary, there's no need for users to remember or enter passwords. Encouraging users to take advantage of built-in browser password generators also means they're more likely to use a unique, strong password on your site, and less likely to reuse a password that could be compromised elsewhere.
+
+### Help save users from accidentally missing inputs
+
+MANDATORY: Add the `required` attribute to both email and password fields. Modern browsers automatically prompt and set focus for missing data.
+
+```html
+<input type="email" id="email" name="email" autocomplete="username" required>
+<input type="password" id="password" name="password" autocomplete="current-password" required>
+```
+
+### Allow password pasting
+
+Some sites don't allow text to be pasted into password inputs.
+
+Disallowing password pasting annoys users, encourages passwords that are memorable (and therefore may be easier to compromise) and, according to organizations such as the UK National Cyber Security Centre, may actually reduce security. Users only become aware that pasting is disallowed after they try to paste their password, so disallowing password pasting doesn't avoid clipboard vulnerabilities.
+
+### Fallback strategies
+
+Baseline status for Email, telephone, and URL <input> types: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 5 (May 2010), Edge 12 (Jul 2015), Firefox 4 (Mar 2011), Safari 5 (Jun 2010), and Safari iOS 3 (Jun 2009).
+
+Baseline status for inputmode: Widely available. It's been Baseline since 2021-12-07.
+Supported by: Chrome 66 (Apr 2018), Edge 79 (Jan 2020), Firefox 95 (Dec 2021), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for autocorrect: Newly available. It's been Baseline since 2026-09-11.
+Supported by: Chrome 153 (Sep 2026), Edge 153 (Sep 2026), Firefox 136 (Mar 2025), Safari 14.1 (Apr 2021), and Safari iOS 14.5 (Apr 2021).
+
+Autofill is a progressive enhancement. In browsers that do not support autofill, users will simply need to manually enter their sign-in credentials. The semantic HTML constraints (such as `type`, `inputmode`, and `required`) will still function appropriately to validate user input and provide the correct virtual keyboards.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-up-form.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-up-form.md
new file mode 100644
index 00000000..251fbacd
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/autofill-sign-up-form.md
@@ -0,0 +1,151 @@
+# Build a sign-up form that follows best practice
+
+Use cross-platform browser features to build sign-up forms that are secure, accessible and easy to use.
+
+If users ever need to sign up to your site, then good sign-up form design is critical. This is especially true for people on poor connections, on mobile, in a hurry, or under stress. Poorly designed sign-up forms get high bounce rates. Each bounce could mean a lost customer and a disgruntled user—not just a missed sign-up opportunity.
+
+## How to implement
+
+Outlined below are the most important guidelines for building successful sign-up forms.
+
+### Use meaningful, valid HTML
+
+Make the most of the elements and attributes built for creating forms:
+
+-   `<form>`, `<input>`, `<label>`, and `<button>`
+-   `type`, `autocomplete`, and `inputmode`
+
+These enable built-in browser functionality, improve accessibility, and add meaning to markup.
+
+### Use the `<label>` element to label form fields for data entry
+
+To label an `<input>`, `<select>`, or `<textarea>`, use a `<label>`. Associate a label with an input by giving the label's `for` attribute the same value as the input's `id`.
+
+### Make the most of HTML attributes
+
+Make it easy for users to enter data, by using the appropriate `<input>` element `<type>` attribute to provide the right keyboard on mobile and enable basic built-in validation by the browser.
+
+Always use `type="email"` for email addresses and `type="tel"` for phone numbers.
+
+Every `<input>`, `<select>`, and `<textarea>` element SHOULD have an appropriate `autocomplete` attribute, to improve accessibility and help users avoid re-entering data.
+
+Username and email inputs hold identifiers, not prose. Add `spellcheck="false"` so the browser does not rewrite them into something the account does not match. `autocorrect` and `autocapitalize` are always disabled for `input type="email"`, but are required for non-email usernames.
+
+### Make buttons helpful
+
+Use `<button>` for buttons. You can also use `<input type="submit">`, but don't use a `div` or some other random element acting as a button. Button elements provide accessible behaviour, built-in form submission functionality, and can easily be styled.
+
+Give each form submit button a value that says what it does. Use a clear, recognizable label. For example, use **Create account** or **Sign up** rather than **Continue** or **Submit**.
+
+### Use a single name input where possible
+
+Allow your users to enter their name using a single input, unless you have a good reason for separately storing given names, family names, honorifics, or other name parts. Using a single name input makes forms less complex, enables cut-and-paste, and makes autofill simpler.
+
+Allow international names. For validation, avoid using regular expressions that only match Latin characters. Latin-only excludes users with names or addresses that include characters that aren't in the Latin alphabet. Allow Unicode letter matching instead—and ensure your backend supports Unicode securely as both input and output. Unicode in regular expressions is well supported by modern browsers.
+
+### Show sign-up progress
+
+For each step towards sign-up, use page headings and descriptive button values that make it clear what needs to be done now, and what the next step is.
+
+Use the `enterkeyhint` attribute on form inputs to set the mobile keyboard enter key label. For example, use `enterkeyhint="previous"` and `enterkeyhint="next"` within a multi-page form, `enterkeyhint="done"` for the final input in the form, and `enterkeyhint="search"` for a search input.
+
+### Help users avoid re-entering sign-up data
+
+Make sure to add appropriate `autocomplete` values in sign-up forms.
+
+This enables browsers to help users by securely storing sign-up details and correctly entering form data. Without autocomplete, users may be more likely to keep a physical record of sign-up details, or store sign-up data insecurely on their device.
+
+### Validate carefully
+
+Validate data entry both in realtime and before form submission. Use `type="email"` for email inputs — the browser will validate the format automatically. For passwords, use a `pattern` attribute to enforce strength requirements and provide clear error messages when validation fails. Add the `required` attribute to mandatory fields to prevent empty submissions.
+
+### Put sign-up in its own `<form>` element
+
+Always use the `<form>` element when you're getting users to enter data
+
+Don't wrap inputs in a `<div>` and handle input data submission purely with JavaScript. It's generally better to use a `<form>` element. This makes your site accessible to screenreaders and other assistive devices, enables a range of built-in browser features, makes it simpler to build basic functional sign-up for older browsers, and can still work even if JavaScript fails.
+
+### Don't double up inputs
+
+Some sites force users to enter emails or passwords twice. That might reduce errors for a few users, but causes extra work for all users, and increases abandonment rates. Asking twice also makes no sense where browsers autofill email addresses or suggest strong passwords. It's better to enable users to confirm their email address (you'll need to do that anyway) and make it easy for them to reset their password if necessary.
+
+### Keep passwords private—but enable users to see them if they want
+
+Passwords inputs should have `type="password"` to hide password text and help the browser understand that the input is for passwords. (Note that browsers use a variety of techniques to understand input roles and decide whether or not to offer to save passwords.)
+
+You should add a **Show password** toggle to enable users to check the text they've entered—and don't forget to add a **Forgot password** link.
+
+### Give mobile users the right keyboard
+
+Use `<input type="email">` to give mobile users an appropriate keyboard and enable basic built-in email address validation by the browser… no JavaScript required!
+
+If you need to use a telephone number instead of an email address, `<input type="tel">` enables a telephone keypad on mobile. You can also use the `inputmode` attribute where necessary: `inputmode="numeric"` is ideal for PIN numbers.
+
+### Prevent mobile keyboard from obstructing the Sign up button
+
+If you're not careful, mobile keyboards may cover your form or, worse, partially obstruct the Sign up button. Users may give up before realizing what has happened.
+
+Where possible, avoid this by displaying only the email (or phone) and password inputs and Sign up button at the top of your sign-up page. Put other content underneath.
+
+### Help users to avoid re-entering data
+
+You can help browsers store data correctly and autofill inputs, so users don't have to remember to enter email and password values. This is particularly important on mobile, and crucial for email inputs, which get high abandonment rates. There are two parts to this:
+
+1.  The `autocomplete`, `name`, `id`, and `type` attributes help browsers understand the role of inputs in order to store data that can later be used for autofill. To allow data to be stored for autofill, modern browsers also require inputs to have a stable `name` or `id` value (not randomly generated on each page load or site deployment), and to be in a `<form>` element with a `submit` button.
+1.  The `autocomplete` attribute helps browsers correctly autofill inputs using stored data.
+
+For email inputs use `autocomplete="username"`, since `username` is recognized by password managers in modern browsers—even though you should use `type="email"` and you may want to use `id="email"` and `name="email"`. For password inputs, use the appropriate `autocomplete` value to help browsers differentiate between new and current passwords.
+
+### Use autocomplete="new-password" for a new password
+
+MANDATORY: For a sign-up form, use `autocomplete="new-password"`.
+
+```html
+<!-- new-password prevents password managers from auto-filling an existing password into this field -->
+<input type="password" id="new-password" name="new-password" autocomplete="new-password" required>
+```
+
+### Enable the browser to suggest a strong password
+
+Modern browsers use heuristics to decide when to show the password manager UI and suggest a strong password.
+
+Built-in browser password generators mean users and developers don't need to work out what a "strong password" is. Since browsers can securely store passwords and autofill them as necessary, there's no need for users to remember or enter passwords. Encouraging users to take advantage of built-in browser password generators also means they're more likely to use a unique, strong password on your site, and less likely to reuse a password that could be compromised elsewhere.
+
+### Help save users from accidentally missing inputs
+
+Add the `required` attribute to both email and password fields. Modern browsers automatically prompt and set focus for missing data.
+
+### Allow password pasting
+
+Some sites don't allow text to be pasted into password inputs.
+
+Disallowing password pasting annoys users, encourages passwords that are memorable (and therefore may be easier to compromise) and, according to organizations such as the UK National Cyber Security Centre, may actually reduce security. Users only become aware that pasting is disallowed after they try to paste their password, so disallowing password pasting doesn't avoid clipboard vulnerabilities.
+
+### Offer third-party login
+
+Many users prefer to sign in to websites using an email address and password sign-up form. However, you should also enable users to sign in using a third-party identity provider, also known as federated login.
+
+This approach has several advantages. For users who create an account using federated login, you don't need to ask for, communicate, or store passwords.
+
+You may also be able to access additional verified profile information from federated login, such as an email address—which means the user doesn't have to enter that data and you don't need to do the verification yourself. Federated login can also make it much easier for users when they get a new device.
+
+### Take care with usernames
+
+Don't insist on a username unless (or until) you need one. Enable users to sign up and sign in with only an email address (or telephone number) and password—or federated login if they prefer. Don't force them to choose and remember a username.
+
+If your site does require usernames, don't impose unreasonable rules on them, and don't stop users from updating their username. On your backend you should generate a unique ID for every user account, not an identifier based on personal data such as username.
+
+Also make sure to use `autocomplete="username"` for usernames.
+
+### Fallback strategies
+
+Baseline status for Email, telephone, and URL <input> types: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 5 (May 2010), Edge 12 (Jul 2015), Firefox 4 (Mar 2011), Safari 5 (Jun 2010), and Safari iOS 3 (Jun 2009).
+
+Baseline status for inputmode: Widely available. It's been Baseline since 2021-12-07.
+Supported by: Chrome 66 (Apr 2018), Edge 79 (Jan 2020), Firefox 95 (Dec 2021), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for autocorrect: Newly available. It's been Baseline since 2026-09-11.
+Supported by: Chrome 153 (Sep 2026), Edge 153 (Sep 2026), Firefox 136 (Mar 2025), Safari 14.1 (Apr 2021), and Safari iOS 14.5 (Apr 2021).
+
+Autofill is a progressive enhancement. In browsers that do not support autofill, users will simply need to manually enter their sign-up credentials. The semantic HTML constraints (such as `type`, `inputmode`, and `required`) will still function appropriately to validate user input and provide the correct virtual keyboards.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/brand-consistent-forms.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/brand-consistent-forms.md
new file mode 100644
index 00000000..acec2225
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/brand-consistent-forms.md
@@ -0,0 +1,255 @@
+# Brand-Consistent Forms
+
+Customizing standard HTML form elements like checkboxes and radio buttons has historically been difficult. Developers often faced a choice between using the browser defaults or building custom components from scratch. Building custom controls is time-consuming and can easily lead to accessibility issues or missing states (like the indeterminate state for checkboxes).
+
+The CSS property `accent-color` provides a simple way to bring your brand color to built-in HTML form inputs with a single line of CSS, without sacrificing accessibility or built-in browser features.
+
+## How to Implement
+
+To apply your brand color to form controls:
+
+1. **Identify your brand color:** Choose a color that represents your brand.
+2. **Apply the `accent-color` property:** Add `accent-color` to the element or a container element (like `body` or a specific form) in your CSS.
+3. **Support Dark Mode (Optional but Recommended):** Use `color-scheme` to let the browser know your site supports dark mode, and adjust the `accent-color` if necessary for better contrast.
+
+## Example Code: Brand-Consistent Form Controls
+
+```css
+:root {
+  --brand-color: #6200ee;
+}
+
+/* Apply accent-color to the body or a specific container */
+body {
+  accent-color: var(--brand-color);
+}
+
+/* Optional: Adjust for dark mode if needed */
+@media (prefers-color-scheme: dark) {
+  :root {
+    --brand-color: #bb86fc; /* A lighter shade for dark mode */
+  }
+}
+```
+
+```html
+<form>
+  <!-- Checkbox -->
+  <label for="subscribe">
+    <input type="checkbox" id="subscribe" checked>
+    Subscribe to newsletter
+  </label>
+
+  <!-- Radio Buttons -->
+  <label for="plan-monthly">
+    <input type="radio" id="plan-monthly" name="plan" value="monthly">
+    Monthly
+  </label>
+  <label for="plan-yearly">
+    <input type="radio" id="plan-yearly" name="plan" value="yearly" checked>
+    Yearly
+  </label>
+
+  <!-- Range Slider -->
+  <label for="volume">Volume:</label>
+  <input type="range" id="volume" min="0" max="100" value="70">
+
+  <!-- Progress Bar -->
+  <label for="file">Upload Progress:</label>
+  <progress id="file" max="100" value="70">70%</progress>
+</form>
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `accent-color` to easily theme form controls to match your brand.
+- **DO NOT** blindly trust the browser to handle contrast. While browsers are supposed to automatically determine an eligible contrast color, known bugs in implementations like **Safari** (WebKit bug 244233) and **Android Chrome** (Chromium bug 343503163) can fail to invert checkmark colors, leading to invisible or hard-to-see controls when using colors that lack sufficient contrast against the background (e.g., light colors in light mode, or dark colors in dark mode).
+- **DO** combine `accent-color` with `color-scheme: light dark` to ensure form controls look good in both light and dark themes.
+- **DO NOT** use a color that is too close to the background color, even though browsers try to guarantee contrast, it's best to provide a color with good base contrast.
+- **DO NOT** assume `accent-color` works on all form elements. Currently, it only tints `checkbox`, `radio`, `range`, and `progress` elements.
+
+## Fallback Strategy
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+For browsers that do not support `accent-color`, the form controls fall back to the browser's default appearance. To ensure full brand consistency and high reliability across all environments, you MUST implement a custom fallback strategy using the established "visually hidden input" technique.
+
+### Progressive Enhancement with `@supports not`
+
+You MUST use the `@supports not` rule to apply custom fallback styles only when `accent-color` is not supported. This ensures you leverage the simplicity of `accent-color` for modern browsers while guaranteeing a consistent branded experience for older ones.
+
+#### 1. HTML Structure
+Ensure your labels wrap the text in a `<span>` to allow for sibling selectors in CSS:
+```html
+<label for="subscribe-fallback">
+  <input type="checkbox" id="subscribe-fallback" class="visually-hidden" checked>
+  <span>Subscribe to newsletter</span>
+</label>
+```
+
+#### 2. CSS Fallback
+Apply custom styles within a `@supports not` block:
+```css
+/* Fallback for older browsers without accent-color */
+@supports not (accent-color: var(--brand-color)) {
+  /* Visually hide the native input using the canonical accessible recipe */
+  form input[type="checkbox"].visually-hidden {
+    position: absolute !important;
+    clip-path: inset(50%) !important;
+    overflow: hidden !important;
+    width: 1px !important;
+    height: 1px !important;
+    margin: -1px !important;
+    padding: 0 !important;
+    border: 0 !important;
+    white-space: nowrap !important;
+  }
+
+  /* Style the wrapper label */
+  label {
+    position: relative;
+    padding-left: 2rem;
+    cursor: pointer;
+    display: inline-flex;
+    align-items: center;
+  }
+
+  /* Custom box for checkbox */
+  input[type="checkbox"] + span::before {
+    content: "";
+    position: absolute;
+    left: 0;
+    top: 50%;
+    transform: translateY(-50%);
+    width: 1.2rem;
+    height: 1.2rem;
+    border: 2px solid #ccc;
+    background: white;
+    border-radius: 4px;
+    box-sizing: border-box;
+    transition: all 0.2s ease;
+  }
+
+  /* Ensure custom checkbox shows focus for keyboard users */
+  input[type="checkbox"]:focus-visible + span::before {
+    outline: 2px solid #000;
+    outline-offset: 2px;
+  }
+
+  /* Checked State */
+  input[type="checkbox"]:checked + span::before {
+    background-color: var(--brand-color, #6200ee);
+    border-color: var(--brand-color, #6200ee);
+  }
+
+  /* Checkmark (Unicode) */
+  input[type="checkbox"]:checked + span::after {
+    content: "✓";
+    position: absolute;
+    left: 0.25rem;
+    top: 50%;
+    transform: translateY(-50%);
+    color: white;
+    font-weight: bold;
+    font-size: 0.9rem;
+  }
+
+  /* Fallback for Range Slider */
+  input[type="range"] {
+    -webkit-appearance: none;
+    appearance: none;
+    background: transparent;
+  }
+
+  /* Webkit (Chrome, Safari, Edge) */
+  input[type="range"]::-webkit-slider-runnable-track {
+    width: 100%;
+    height: 8px;
+    /* Use gradient to show progress for a static value (e.g., 70%) or update with JS */
+    background: linear-gradient(to right, var(--brand-color, #6200ee) 70%, #ccc 70%);
+    border-radius: 4px;
+  }
+
+  input[type="range"]::-webkit-slider-thumb {
+    -webkit-appearance: none;
+    appearance: none;
+    height: 16px;
+    width: 16px;
+    border-radius: 50%;
+    background: var(--brand-color, #6200ee);
+    cursor: pointer;
+    margin-top: -4px; /* Center vertically */
+  }
+
+  /* Firefox */
+  input[type="range"]::-moz-range-track {
+    width: 100%;
+    height: 8px;
+    background: #ccc;
+    border-radius: 4px;
+  }
+
+  input[type="range"]::-moz-range-thumb {
+    height: 16px;
+    width: 16px;
+    border-radius: 50%;
+    background: var(--brand-color, #6200ee);
+    cursor: pointer;
+  }
+
+  /* Firefox specific progress bar */
+  input[type="range"]::-moz-range-progress {
+    background-color: var(--brand-color, #6200ee);
+    height: 8px;
+    border-radius: 4px;
+  }
+
+  /* Fallback for Progress Bar */
+  progress {
+    -webkit-appearance: none;
+    -moz-appearance: none;
+    appearance: none;
+    border: none;
+    background: #ccc;
+    height: 8px;
+    border-radius: 4px;
+  }
+
+  progress::-webkit-progress-bar {
+    background-color: #ccc;
+    border-radius: 4px;
+  }
+
+  progress::-webkit-progress-value {
+    background-color: var(--brand-color, #6200ee);
+    border-radius: 4px;
+  }
+
+  progress::-moz-progress-bar {
+    background-color: var(--brand-color, #6200ee);
+    border-radius: 4px;
+  }
+}
+```
+
+### Dynamic Range Progress in Webkit Fallback
+
+To make the progress fill move with the thumb on a range slider in Webkit browsers (without `accent-color`), you can use a CSS variable and a small amount of JavaScript.
+
+1. **Update CSS**: Use a CSS variable for the gradient stop:
+```css
+input[type="range"]::-webkit-slider-runnable-track {
+  background: linear-gradient(to right, var(--brand-color) var(--progress, 0%), #ccc var(--progress, 0%));
+}
+```
+
+2. **Add JavaScript**: Update the variable on the `input` event:
+```javascript
+if (!CSS.supports('accent-color')) {
+  const slider = document.getElementById('volume');
+  slider.addEventListener('input', (e) => {
+    e.target.style.setProperty('--progress', `${e.target.value}%`);
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/branded-select-styling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/branded-select-styling.md
new file mode 100644
index 00000000..52be5a7b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/branded-select-styling.md
@@ -0,0 +1,115 @@
+# Branded Select Styling
+
+The customizable select API offers a declarative, CSS-driven way to style `<select>` elements to perfectly match your brand's design system. By opting into `appearance: base-select`, you gain access to the internal shadow DOM of the select element, allowing you to style the button, the options picker list, the arrow icon, and the checkmark indicator using standard CSS properties.
+
+Previously, achieving a fully branded select required rebuilding the control from scratch with JavaScript, which often broke accessibility, keyboard navigation, and native form integration. With `appearance: base-select`, you get a custom look while the browser handles focus management, top-layer rendering, and accessibility bindings.
+
+## How to Implement
+
+To implement branded select styling:
+
+1. **Opt-in to customization:** Apply `appearance: base-select` to both the `<select>` element and the `::picker(select)` pseudo-element (which targets the drop-down list of options).
+2. **Structure the custom button (Optional):** Define a `<button>` element directly inside the `<select>` to replace the default trigger. Use the `<selectedcontent>` element inside this button to represent the text or content of the currently selected option.
+3. **Style the Picker List:** Use the `::picker(select)` pseudo-element to apply typography, background colors, borders, and shadows to the dropdown list. The browser renders this in the top-layer, making `z-index` conflicts a thing of the past.
+4. **Style Internal Icons:**
+   - Use `select::picker-icon` to style or replace the arrow icon.
+   - Use `option::checkmark` to style the checkmark indicator next to the active option.
+5. **Style Options:** Apply styles to `<option>` elements for hover states, padding, and layout.
+
+## Example Code: Branded Courier Select
+
+The following example demonstrates a custom select styled with a monospace font and dashed borders to match a specific "parcel" brand aesthetic.
+
+```css
+/* Enable customization for the select and its picker */
+.brand-select,
+.brand-select::picker(select) {
+  appearance: base-select;
+}
+
+/* Style the visible trigger button */
+.brand-select {
+  font-family: 'Courier New', monospace;
+  background-color: #fffaf0;
+  color: #8b4513;
+  border: 2px dashed #8b4513;
+  border-radius: 4px;
+  padding: 0.75rem;
+  font-size: 1rem;
+  cursor: pointer;
+}
+
+/* Style the dropdown options list */
+.brand-select::picker(select) {
+  font-family: 'Courier New', monospace;
+  background-color: #fffaf0;
+  border: 2px dashed #8b4513;
+  border-radius: 4px;
+  padding: 0.5rem;
+}
+
+/* Customize internal part colors to match text */
+.brand-select::picker-icon {
+  color: #8b4513;
+}
+
+.brand-select option::checkmark {
+  color: #8b4513;
+}
+
+/* Style individual options and hover effects */
+.brand-select option {
+  padding: 0.5rem;
+  border-radius: 4px;
+  color: #8b4513;
+  cursor: pointer;
+}
+
+.brand-select option:hover {
+  background-color: #fdf5e6;
+}
+```
+
+```html
+<label for="preferences">Select shipping preference</label>
+<select class="brand-select" id="preferences" name="preferences">
+  <button>
+    <selectedcontent></selectedcontent>
+  </button>
+  <option value="standard">Standard Shipping</option>
+  <option value="express" selected>Express Shipping</option>
+  <option value="overnight">Overnight Delivery</option>
+</select>
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `appearance: base-select` when your design system requires high-fidelity, visual consistency across all form controls that cannot be achieved with standard cross-browser select overrides.
+- **DO NOT** use this if you rely on the operating system's native picker experience (e.g., the standard scroll wheel picker on iOS devices). Opting into `base-select` opts out of native mobile UI controls in favor of web-rendered top-layer menus.
+- **DO** verify that color contrast meets WCAG standards. The customizable picker allows you to set ad-hoc colors, but you are responsible for ensuring text remains legible against custom backgrounds.
+- Test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- Ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+- Use standard `value` attributes on options to ensure form submission works exactly as before.
+
+## Fallback strategies
+
+### Fallbacks & browser support for Customizable <select>
+
+Browser support for Customizable <select>: Limited availability.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), and Safari 27 (Sep 2026).
+Unsupported in: Firefox.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/custom-select-picker-layouts.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/custom-select-picker-layouts.md
new file mode 100644
index 00000000..65cb46c6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/custom-select-picker-layouts.md
@@ -0,0 +1,166 @@
+# Custom Select Picker Layouts
+
+The CSS property `appearance: base-select` unlocks the ability to style a `<select>` element and its picker (via `::picker(select)`) like regular HTML elements.
+Combined with modern CSS layout techniques like Grid or Flexbox, you can break away from the traditional stacked vertical list and create a rich visual experience without custom JS.
+For example, you can use `display: grid` to style the options as a 2D grid of cards.
+
+This is ideal for color pickers, emoji selectors, or product variants where a rich visual menu is more effective than a list.
+
+## How to Implement
+
+### 1. Activate Base Styling
+
+Apply `appearance: base-select` to both the `<select>` element and its internal picker pseudo-element `select::picker(select)`:
+
+```css
+select.grid-picker {
+  &, &::picker(select) {
+    appearance: base-select;
+  }
+}
+
+```
+
+### 2. Style the Picker Container
+
+Target `select:open::picker(select)` and apply `display: grid` (or `display: flex`).
+Define columns and gaps as you would for any container.
+
+```css
+select.grid-picker:open::picker(select) {
+  display: grid;
+  grid-template-columns: repeat(2, 1fr);
+  gap: 1rem;
+}
+```
+
+IMPORTANT: The `:open` is necessary. If you style `select::picker(select)`, it will make the picker visible even when the select is closed!
+
+### 3. Style the Options
+
+Target the `<option>` elements to style them as grid items or cards.
+You can add images, SVGs, or complex layouts inside them.
+
+```css
+/* Style options as grid cards */
+.grid-picker option {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* padding, border-radius, background, etc. */
+}
+```
+
+### 4. Style the selected option
+
+To style the selected *option*, use `option:checked`. For example:
+
+```css
+.grid-picker option:checked {
+  position: relative;
+  border: 2px solid var(--primary-color);
+  background-color: oklab(from var(--primary-color) l a b / 8%);
+}
+```
+
+As with any UI control, do not communicate state with color alone, and use multiple visual indicators (e.g. colors, border thickness, checkmark) to communicate which option is selected.
+
+### 5. (Optional) Style the selected option checkmark
+
+By default, the browser renders a checkmark as the first child of every `<option>`.
+
+It behaves like a `::before` with `content: "✓" / ""`, rendered before an author-provided `::before`, if one exists.
+
+If the option is not selected, the checkmark is hidden via `visibility: hidden`.
+
+You can style it using the `::checkmark` pseudo-element, or hide it entirely if you want to convey selection via styling alone or use a custom indicator.
+
+For example, to place it at the top-right corner of the option, you could do something like:
+
+```css
+select.grid-picker {
+  > option::checkmark {
+    /* Hide the checkmark for unselected options */
+    display: none;
+  }
+
+  > option:checked {
+    position: relative;
+
+    &::checkmark {
+      position: absolute;
+      inset-block-start: -.4em;
+      inset-inline-end: -.5em;
+      display: flex;
+      align-items: center;
+      justify-content: center;
+      box-sizing: border-box;
+      min-inline-size: 1.6em;
+      aspect-ratio: 1;
+      padding-right: 0.12em;
+      padding-left: 0.05em;
+      border-radius: 50%;
+      background: var(--primary-color);
+      color: white;
+      font-size: 70%;
+      font-weight: bold;
+    }
+  }
+}
+```
+
+**Tip:** When painting a container (e.g. a circle) around the checkmark, nudge it a little towards the top (as we did here with `padding-bottom` and `padding-left`) for optical centering that accounts for its shape.
+Do NOT use `padding-inline-start` or `padding-block-end` for this, as they will change depending on writing mode, whereas the shape of the checkmark does not.
+
+### 6. (Optional) Customize the selected option display
+
+By default, the `<select>` will show a text-only version of the selected option.
+To display rich content for the selected value, use `<selectedcontent>` inside a `<button>` and/or to display the selected option differently (e.g. hide certain details).
+
+Not **NOT** use `<selectedcontent>` without the `<button>` around it, as the `<selectedcontent>` will just become part of the picker, like any other content element.
+
+### Best practices
+
+- Test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- Ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+- Use standard `value` attributes on options to ensure form submission works exactly as before.
+
+## Accessibility
+
+<!-- See https://github.com/GoogleChrome/modern-web-guidance-src/pull/960#pullrequestreview-4880620093 -->
+
+A native `<select>` only handles linear Up/Down arrow navigation, so Left/Right do nothing in the open picker and Up/Down still navigate items sequentially, regardless of rows and columns.
+
+To implement spatial navigation that follows the grid, you can intercept `keydown` and route focus to the nearest option in the pressed direction (e.g. using `getBoundingClientRect()`) when arrow keys are used.
+To determine the appropriate next/previous item, use DOM methods that operate on actual geometry (e.g. `getBoundingClientRect()`) rather than parsing CSS strings like `grid-template-columns` or `grid-column`, which can be brittle and error-prone for complex grids, subgrid, RTL, and other layout scenarios.
+That said, do not unnecessarily overengineer; use what invariants you know are true about the layout to simplify this logic.
+
+**Note:** This _only_ addresses keyboard navigation. The `<select>` and its `::picker()` still have their default roles (`menu` or `listbox`), and these cannot be overridden, nor are they allowed to contain an element with `role="grid"`.
+Nesting a wrapper with `role="grid"` inside the picker works in practice, but is not valid, and may surprise AT users.
+In some cases, using `<optgroup>` to group options may produce a good screen reader UX without `role="grid"`.
+Otherwise, it may be ultimately necessary to switch to a custom solution using the popover API, anchor positioning, and `role="grid"` to achieve the desired UX for screen reader users.
+
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Customizable <select>
+
+Browser support for Customizable <select>: Limited availability.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), and Safari 27 (Sep 2026).
+Unsupported in: Firefox.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/form-fields-automatically-fit-contents.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/form-fields-automatically-fit-contents.md
new file mode 100644
index 00000000..ba3e6b58
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/form-fields-automatically-fit-contents.md
@@ -0,0 +1,122 @@
+# Form Fields Automatically Fit Contents
+
+By default, form controls like `<input>`, `<textarea>`, and `<select>` have fixed dimensions. Their sizes remain constant, regardless of the amount of content the user enters or selects.
+
+To allow these controls to automatically shrink or grow to fit their content (including placeholders), use the `field-sizing: content` CSS property.
+
+### Auto-sizing form controls
+
+Setting `field-sizing: content` on inputs, selects, or textareas allows them to resize dynamically as the user types or selects options. However, you must account for inherited styling, layout defaults, and minimum/maximum constraints to ensure a robust user experience.
+
+To prevent layout issues, it is recommended to set both `min-inline-size` (or `min-width`) and `max-inline-size` (or `max-width`) alongside `field-sizing: content` on text inputs. A minimum size prevents the input from collapsing to a width of zero when empty (making it unclickable), and a maximum size ensures it doesn't expand indefinitely and break the page layout.
+
+For textareas, allowing horizontal auto-sizing can cause a jarring UX (e.g., a textarea with a long placeholder will abruptly shrink horizontally when the user types a single character). To prevent this, apply an explicit width (like `width: 100%`) to the textarea. This forces the textarea to maintain a stable horizontal width while still auto-sizing vertically as content wraps.
+
+It is recommended to set a `max-inline-size` (or `max-width`) on `<select>` elements using `field-sizing: content` to ensure that extremely long selected options do not break the page layout.
+
+```css
+/* Applies horizontal auto-sizing to inputs */
+input {
+  /* Instructs the element to size itself to fit its content */
+  field-sizing: content;
+
+  /* Reset explicit width if inherited from global styles */
+  width: auto;
+
+  /* Prevents the input from collapsing and disappearing when empty */
+  min-inline-size: 15ch;
+
+  /* Prevents infinite horizontal growth */
+  max-inline-size: 50ch;
+}
+
+textarea {
+  /* Instructs the element to size itself to fit its content */
+  field-sizing: content;
+
+  /* Reset explicit height if inherited from global styles */
+  height: auto;
+
+  /* Use a fixed width to prevent jarring horizontal shifts when replacing a long placeholder */
+  width: 50ch; /* or 100% depending on your layout */
+
+  /* Sets a reasonable minimum height (e.g., 3 lines) for empty textareas */
+  min-block-size: 3lh;
+
+  /* Prevents infinite vertical growth. Once a textarea hits this */
+  /* height, it will stop growing and show a vertical scrollbar. */
+  max-block-size: 10lh;
+}
+
+select {
+  /* Sizes the select element to fit the active option only */
+  field-sizing: content;
+
+  /* Prevents the dropdown from expanding infinitely and breaking the layout */
+  max-inline-size: 50ch;
+}
+```
+
+IMPORTANT: Explicit `width` and `height` properties override `field-sizing: content` on all form controls. If your project's global CSS sets inputs, selects, or textareas to `width: 100%`, you must explicitly reset them to `width: auto` (or `width: fit-content`) on the elements using `field-sizing: content` for auto-sizing to work. Conversely, you should explicitly set `height: auto` on textareas if a fixed height was previously set globally.
+
+IMPORTANT: Grid and Flexbox layouts often implicitly stretch their children to fill available space. If any form control using `field-sizing: content` refuses to shrink, check its container's alignment properties and apply `align-self: start` or `justify-self: start` to the form control to override the stretching.
+
+### Fallback strategies
+
+Baseline status for field-sizing: Newly available. It's been Baseline since 2026-06-16.
+Supported by: Chrome 123 (Mar 2024), Edge 123 (Mar 2024), Firefox 152 (Jun 2026), and Safari 26.2 (Dec 2025).
+
+`field-sizing` should be treated as a progressive enhancement. In browsers that do not support the property, form controls gracefully degrade back to their default, fixed sizing behavior. Users will simply experience standard scrolling for overflowing content inside fixed-size inputs and textareas.
+
+If dynamically growing fields are absolutely required for older browsers, you must use feature detection and a complex workaround. The most robust fallback for textareas uses a CSS Grid trick where a hidden pseudo-element mirrors the user's input in real-time, forcing the grid container (and the textarea inside it) to expand.
+
+```html
+<!-- The textarea is wrapped in a container that will mirror its value -->
+<div class="growable-textarea" data-replicated-value="">
+  <textarea></textarea>
+</div>
+```
+
+```javascript
+// Only attach the fallback event listeners if field-sizing is unsupported
+if (!CSS.supports('field-sizing', 'content')) {
+  document.querySelectorAll('.growable-textarea > textarea').forEach(textarea => {
+    textarea.addEventListener('input', () => {
+      textarea.parentNode.dataset.replicatedValue = textarea.value;
+    });
+  });
+}
+```
+
+```css
+/* Only apply the fallback if field-sizing is NOT supported */
+@supports not (field-sizing: content) {
+  .growable-textarea {
+    display: grid;
+  }
+
+  /* The pseudo-element and textarea must share the exact same cell, font, and padding */
+  .growable-textarea::after,
+  .growable-textarea > textarea {
+    grid-area: 1 / 1 / 2 / 2;
+    font: inherit;
+    padding: 0.5rem;
+    border: 1px solid #999;
+  }
+
+  /* The pseudo-element renders the copied text invisibly to stretch the grid */
+  .growable-textarea::after {
+    /* The space is necessary for trailing empty lines to be rendered */
+    content: attr(data-replicated-value) " ";
+    white-space: pre-wrap;
+    visibility: hidden;
+  }
+
+  .growable-textarea > textarea {
+    resize: none;
+    overflow: hidden;
+  }
+}
+```
+
+Given the complexity of duplicating styles and synchronizing state across DOM nodes for every form control, relying on the default fallback behavior of fixed inputs is the recommended approach for most applications unless dynamic sizing is critical to the user experience.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/forms.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/forms.md
new file mode 100644
index 00000000..0409c179
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/forms.md
@@ -0,0 +1,380 @@
+# Forms
+
+## 1. Semantic Structure and Form Element
+
+### Guidelines
+
+- **DO** use the `<form>` element to wrap interactive controls for data collection.
+- **DO** use `method="POST"` for sensitive data and mutations; use `method="GET"` for idempotent requests (e.g., search).
+- **DO** specify the `action` attribute for the destination URL.
+- **DO** specify a `name` attribute for every form control to identify data on submission.
+- **DO** use semantic tags like `<button type="submit">`, `<textarea>`, and `<select>`.
+- **DO** use `<fieldset>` and `<legend>` to group related controls.
+- **DO** use actionable language on submit buttons (e.g., "Save changes").
+
+- **DON'T** use `GET` for sensitive data (it exposes data in history/logs).
+- **DON'T** use generic `<div>` or `<span>` for form controls.
+- **DON'T** use `type="button"` for primary submission buttons.
+- **DON'T** disable textarea resizing without alternate layout provisions.
+
+### Code Example
+
+```html
+<form action="/search" method="GET">
+  <fieldset>
+    <legend>Search Preferences</legend>
+    <label for="q">Query:</label>
+    <input type="text" id="q" name="q" required>
+    <button type="submit">Search</button>
+  </fieldset>
+</form>
+```
+
+### Selection Control Decision Matrix
+
+| Options Count | Choice Type | Recommended Element | Usability & Accessibility Logic |
+| :--- | :--- | :--- | :--- |
+| **1–5** | Single (Exclusive) | `<input type="radio">` | **Zero-click scanning**: All choices are immediately visible. Faster scan time. |
+| **6+** | Single (Exclusive) | `<select>` | **Space conservation**: Use only when vertical space is premium or the list is long. |
+| **10+ / Dynamic** | Single (Exclusive) | `<input list="id">` (`<datalist>`) | **Fuzzy Search**: Prevents scrolling fatigue in massive sets (e.g., countries). |
+| **Any** | Multi-select | `<input type="checkbox">` | **Standard semantics**: Native non-exclusive toggles. |
+
+**Single-Sentence Mental Model**: "Expose mutually exclusive options as visible radio buttons when choices are fewer than six; use `<select>` only when space is constrained or the list is long."
+
+## 2. Accessible Labeling and State
+
+### Guidelines
+
+- **DO** always associate `<label>` with its input using `for` and `id`.
+- **DO** place labels above form controls to enable faster scanning.
+- **DO** use visible labels; do not rely on `placeholder` alone.
+- **DO** ensure the vertical margin between a label and its input is less than the margin between form groups (**Gestalt Proximity Rule**).
+- **DO** use `aria-describedby` to link inputs with help text or error messages.
+- **DO** define the `lang` attribute on `<html>` for proper device translation.
+- **DO** use non-color visual cues (icons, text) to communicate state (don't rely on color alone).
+- **DO** indicate clearly which fields are required.
+- **DO** use `aria-live` for dynamic error announcements.
+
+- **DON'T** use `placeholder` as a replacement for labels.
+- **DON'T** use `aria-label` as the sole text description if translation is needed.
+- **DON'T** disable focus outlines without providing a high-contrast alternative.
+
+### Code Example
+
+```html
+<div class="field">
+  <label for="username">Username:</label>
+  <input type="text" id="username" name="username" aria-describedby="user-help" required>
+  <span id="user-help" class="hint">3-12 characters.</span>
+</div>
+
+<style>
+  input:focus-visible {
+    outline: 3px solid #0b57d0;
+    outline-offset: 2px;
+  }
+</style>
+```
+
+## 3. Autofill and Input Hints
+
+### Guidelines
+
+- **DO** use the `autocomplete` attribute to specify expected data (e.g., `email`, `tel`, `current-password`, `new-password`).
+- **DO** use `inputmode` to optimize on-screen keyboards (e.g., `inputmode="numeric"` for PINs).
+- **DO** use `enterkeyhint` to set the Enter key label (e.g., `next`, `done`).
+- **DO** turn off text correction on fields that hold identifiers rather than prose: `autocorrect="off"` (plus `autocapitalize="off"` and `spellcheck="false"`) on usernames, emails, URLs, codes, and search inputs. Leave the defaults on for free-text fields like messages and comments.
+- **DO** use single-field inputs for complex numbers (credit cards, phones) to help autofill.
+- **DO** use a single `<input type="text" inputmode="numeric" autocomplete="one-time-code">` and the WebOTP API for SMS one-time passcode verification. See guide `sms-otp-form` (via `npx -y modern-web-guidance@latest retrieve "sms-otp-form"`).
+
+- **DON'T** use `type="number"` for credit cards, ZIP codes, or one-time passcodes (causes UI scroll issues and removes leading zeros).
+
+### Code Example
+
+```html
+<label for="zip">ZIP Code:</label>
+<input type="text" id="zip" name="zip" autocomplete="postal-code" inputmode="numeric" pattern="\d{5}">
+
+<label for="username">Username:</label>
+<input type="text" id="username" name="username" autocomplete="username" autocorrect="off" autocapitalize="off" spellcheck="false">
+```
+
+## 4. Constraints and Validation
+
+### Guidelines
+
+- **DO** use native constraints: `required`, `minlength`, `maxlength`, `pattern`.
+- **DO** use CSS pseudo-classes `:invalid:user-invalid` for non-intrusive styling.
+- **DO** use the ValidityState API (`setCustomValidity`) for custom messaging.
+
+- **DON'T** disable submit buttons to block validation; let users submit and highlight errors. However, **DO** disable the button *after* a valid submission is clicked to prevent double-posts.
+
+### Code Example
+
+```html
+<label for="code">Activation Code (4 digits):</label>
+<input type="text" id="code" name="code" required pattern="\d{4}">
+
+<script>
+  const input = document.getElementById('code');
+  input.addEventListener('invalid', () => {
+    input.setCustomValidity('Please enter exactly 4 digits.');
+  });
+  input.addEventListener('input', () => {
+    input.setCustomValidity('');
+  });
+</script>
+```
+
+### Validation Event Timing Matrix
+
+| Event Trigger | Phase | Action Allowed | UX / Accessibility Logic |
+| :--- | :--- | :--- | :--- |
+| **`input`** | Active Typing | **Clear** existing errors only. | **Non-intrusive**: Do not yell at the user before they finish typing. |
+| **`blur` / `focusout`** | Exiting Field | **Run** check and show error. | **Contextual validation**: Validate once the user indicates they are "done" with a field. |
+| **`submit`** | Final Attempt | **Block** and route focus. | **Final gatekeeper**: Intercepts bad payloads and forces screen reader focus to the summary. |
+
+**Single-Sentence Mental Model**: "Validate on `blur` to avoid premature warnings while typing, and reset error states on `input` as soon as the user attempts a correction."
+
+**Security vs UX Scale**: Client-side validation is for User Experience; Server-side validation is for Security. Never treat browser constraints as a data integrity defense.
+
+## 5. Responsive Design and Typography
+
+### Guidelines
+
+- **DO** use single-column layouts for scanning.
+- **DO** set `font-size` to at least `1rem` (16px) to prevent iOS zoom.
+- **DO** expand clickable areas for mobile tap targets using padding tricks.
+- **DO** ensure tap targets are at least `48px`.
+- **DO** use units relative to root (`rem`) and unitless `line-height`.
+- **DO** use CSS logical properties (e.g., `margin-inline-start`) for RTL support.
+
+### Code Example
+
+```css
+.form-group {
+  margin-block-end: 1.5rem;
+}
+
+/* Expand clickable tap area without layout shift */
+label {
+  display: inline-block;
+  padding: 10px 0;
+  margin: -10px 0;
+}
+
+input {
+  font-size: 1rem;
+  padding: 0.75rem;
+  min-height: 48px;
+  box-sizing: border-box;
+}
+
+@media (pointer: coarse) {
+  input {
+    min-height: 52px;
+  }
+}
+```
+
+## 6. Styling Form Controls
+
+### Guidelines
+
+- **DO** use `accent-color` for quick branding of native radios/checkboxes.
+- **DO** use `appearance: none` for custom dropdown arrows without breaking semantics.
+- **DO** ensure inputs are clearly visible with adequate border contrast (e.g., `#ccc` or darker on white backgrounds).
+- **DO** hide inputs visually using the canonical `.visually-hidden` recipe (`clip-path: inset(50%)` with 1px dimensions) — NOT `display: none`, which removes them from the accessibility tree.
+
+### Code Example
+
+```html
+<div class="checkbox-container">
+  <input type="checkbox" id="sub" name="sub" class="visually-hidden">
+  <label for="sub" class="checkbox-label">Subscribe</label>
+</div>
+
+<style>
+  .visually-hidden {
+    position: absolute;
+    clip-path: inset(50%);
+    overflow: hidden;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    white-space: nowrap;
+  }
+  .checkbox-label::before {
+    content: "";
+    display: inline-block;
+    width: 1.25rem;
+    height: 1.25rem;
+    border: 2px solid #ccc;
+  }
+  input:focus-visible + .checkbox-label::before {
+    outline: 2px solid #0b57d0;
+  }
+</style>
+```
+
+## 7. JavaScript and AJAX
+
+### Guidelines
+
+- **DO** check `KeyboardEvent.isComposing` before treating the `Enter` key as a submit action in chat or text inputs to ensure IME text composition is not interrupted. See guide `ime-safe-enter-submit` (via `npx -y modern-web-guidance@latest retrieve "ime-safe-enter-submit"`).
+- **DO** prevent default navigation on form submit for AJAX (`e.preventDefault()`).
+- **DO** use `ValidityState` interfaces for real-time validation checks.
+- **DO** use `aria-expanded` and `aria-controls` for dynamic UI reveals.
+
+- **DON'T** block page submission if JS fails; ensure server-side fallback.
+
+### Code Example
+
+```js
+form.addEventListener('submit', (e) => {
+  e.preventDefault();
+  const data = new FormData(form);
+  // fetch('/submit', { method: 'POST', body: data });
+});
+```
+
+## 8. Identity, Payments, and Advanced Security
+
+### Guidelines
+
+- **DO** use `autocomplete="new-password"` for sign-up and `autocomplete="current-password"` for sign-in.
+- **DO** allow pasting into password fields.
+- **DO** provide a toggle capability allowing users to unmask password input.
+- **DO** indicate exact amounts on pay buttons (e.g., "Pay $100").
+- **DO** use `autocomplete="cc-number"`, `cc-exp`, `cc-csc`.
+- **DO** use HTTPS for all pages.
+- **DO** implement cryptographically secure anti-CSRF tokens for mutating actions (POST/PUT/DELETE).
+- **DO** sanitize user input (e.g., via DOMPurify) before injecting it into the DOM to prevent XSS.
+- **DO** implement spam protection (honeypots or CAPTCHA) for open forms.
+
+- **DON'T** utilize HTTP `GET` for endpoints executing state changes.
+- **DON'T** use inline JavaScript (e.g., `onclick="..."`) directly within form markup to satisfy strict Content Security Policies (CSP).
+
+### Code Example
+
+```html
+<form method="post">
+  <input type="hidden" name="csrf_token" value="secure_token_abc123">
+
+  <h1>Sign up</h1>
+
+  <div class="form-group">        
+    <label for="name">Full name</label>
+    <input id="name" name="name" autocomplete="name" required pattern="[\p{L}\.\- ]+">
+  </div>
+
+  <div class="form-group">        
+    <label for="email">Email</label>
+    <input id="email" name="email" type="email" autocomplete="username" required>
+  </div>
+
+  <div class="form-group">
+    <label for="password">Password</label>
+    <button id="toggle-password" type="button" aria-pressed="false" aria-label="Show password" aria-describedby="toggle-warning">
+      <img class="icon-eye" src="/icons/eye.svg" alt="" width="20" height="20">
+      <img class="icon-eye-off" src="/icons/eye-off.svg" alt="" width="20" height="20">
+    </button>
+    <span id="toggle-warning" class="visually-hidden">Warning: this will display your password on the screen.</span>
+    <input id="password" name="password" type="password" autocomplete="new-password" minlength="8" aria-describedby="password-constraints" required>
+    <div id="password-constraints">Eight or more characters.</div>
+  </div>
+
+  <button id="sign-up">Sign up</button>
+</form>
+```
+
+
+## 9. Address Collection
+
+### Guidelines
+
+- **DO** use a single field for names.
+- **DO** use `autocomplete="street-address"`.
+- If the site has users in different countries, **DO** use the `<textarea>` element for addresses, to accommodate different address formats in different geographical regions. If the form uses separate inputs for address parts (e.g. Street, City), **DO** use `autocomplete` values `address-line1`, `address-line2`, etc.
+- **DO** make postal codes optional.
+
+- **DON'T** split name inputs into rigid variables ("First", "Last") for global audiences.
+- **DON'T** enforce Latin-only characters for names and usernames.
+
+### Code Example
+
+```html
+<!-- Accessible Address Form with Autofill -->
+<form action="/save-address" method="POST">
+  <div class="form-group">
+    <label for="full-name">Full name</label>
+    <input type="text" id="full-name" name="full_name" maxlength="100" required autocomplete="name">
+  </div>
+
+  <div class="form-group">
+    <label for="address">Address</label>
+    <textarea id="address" name="address" required autocomplete="street-address" maxlength="300"></textarea>
+  </div>
+
+  <button type="submit">Save Address</button>
+</form>
+```
+
+
+## 10. Usability Testing and Analytics
+
+### Guidelines
+
+- **DO** test forms across multiple devices, browsers, and screen sizes.
+- **DO** test keyboard-only navigation (using `Tab` and `Shift+Tab`) and verify visual focus.
+- **DO** emulate various impairments (visual, motor) using browser tools.
+- **DO** use analytics to monitor form completion rates and bounce points.
+- **DO** track discrete events (e.g., field focus, click) to find micro-friction points.
+
+- **DON'T** rely solely on automated tools (Lighthouse) for usability; test with real users.
+- **DON'T** track sensitive personal data in standard event labels.
+
+### Code Example
+
+```html
+<form action="/submit" method="POST" id="track-form">
+  <label for="postal-code">ZIP or postal code</label>
+  <input type="text" id="postal-code" name="postal-code" autocomplete="postal-code" maxlength="20" required>
+  <button type="submit" id="submit-btn">Submit</button>
+</form>
+
+<script>
+  const trackForm = document.getElementById('track-form');
+  const trackBtn = document.getElementById('submit-btn');
+  
+  trackBtn.addEventListener('click', () => {
+    console.log('Analytics Event: Submit clicked');
+  });
+</script>
+```
+
+## 11. Multi-Page Forms
+
+### Guidelines
+
+- **DO** clearly display progress through a multi-page form with clear labels and progress indicators.
+- **DO** allow users to navigate backwards and forwards between pages.
+- **DO** use context-specific `enterkeyhint` values (e.g., `"previous"`, `"next"`) to guide navigation via on-screen keyboards.
+- **DO** design layouts so that the mobile keyboard does not obscure inputs or buttons (e.g., by placing them in the upper half of the viewport when focused or using CSS scroll-padding).
+
+### Code Example
+
+```html
+<nav aria-label="Progress">
+  <ol class="progress-tracker">
+    <li class="step-done">Step 1: Account</li>
+    <li class="step-active" aria-current="step">Step 2: Shipping</li>
+    <li class="step-todo">Step 3: Payment</li>
+  </ol>
+</nav>
+
+<button type="button" onclick="history.back()" enterkeyhint="previous">Previous</button>
+<button type="submit" enterkeyhint="next">Next</button>
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/ime-safe-enter-submit.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/ime-safe-enter-submit.md
new file mode 100644
index 00000000..a263a8e2
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/ime-safe-enter-submit.md
@@ -0,0 +1,115 @@
+# IME-safe enter-to-submit
+
+Many chat interfaces submit their message when the user presses `Enter` in a `<textarea>`.
+
+This works for users typing with direct Latin keyboard input (e.g. English), but breaks for users typing with an Input Method Editor (IME) to compose text in languages like Japanese, Chinese, or Korean.
+
+In these contexts, the `Enter`/`Return` key is used to confirm the current character conversion candidate. If custom JavaScript listens to `keydown` on `Enter` and submits immediately, the user's message is sent while they are still converting characters, resulting in incomplete, fragmented, or incorrect messages.
+
+The composition-active check applies to any custom `keydown` handler that acts on `Enter`, not only to multiline `<textarea>` fields. Single-line `<input>` fields with their own `Enter` handling, such as search and find bars, inline rename fields, modal dialog fields, and command palettes, receive the same IME-confirming `Enter` keydown as a `<textarea>` does, with `isComposing` set to `true`. Native implicit submission of a `<form>` from an `<input>` with no custom `Enter` handler needs no explicit handling, because browsers suppress implicit submission when the `Enter` keystroke is consumed by an IME.
+
+## Implementation strategy
+
+For a `<textarea>` or `<input>` with custom enter-to-submit, check the native `isComposing` property of the `KeyboardEvent` before submitting the content. Also call `event.preventDefault()`: the default action of `Enter` inserts a newline in a `<textarea>`, and in an `<input>` inside a `<form>` it triggers the browser's implicit submission, which would submit a second time.
+
+```html
+<form id="chat-form">
+  <label for="chat-input" class="visually-hidden">Message</label>
+  <textarea id="chat-input" placeholder="Type a message..."></textarea>
+  <button type="submit" id="send-button">Send</button>
+</form>
+```
+
+```js
+const textarea = document.getElementById('chat-input');
+const form = document.getElementById('chat-form');
+
+textarea.addEventListener('keydown', (event) => {
+  if (event.key === 'Enter' && !event.shiftKey) {
+    // Prevent the default action (newline in a textarea, implicit form submission in an input)
+    event.preventDefault();
+
+    // If the user is composing text, return early.
+    if (event.isComposing) {
+      return;
+    }
+
+    form.requestSubmit();
+  }
+});
+```
+
+For a single-line `<input>`, use the same handler without the `!event.shiftKey` condition, which exists only because `Shift+Enter` inserts a newline in a `<textarea>`.
+
+Note: Other custom submission shortcuts (such as `Cmd+Enter` or `Ctrl+Enter`) do not conflict with IME confirmation keys and do not require IME safety checks.
+
+## Accessibility and testing
+
+1. **Explicit submit button**: Always include a `<button type="submit">` element. Keyboard shortcuts are helpers; they must not replace native form submit paths.
+2. **Accessible inputs**: Ensure all `<input>` and `<textarea>` elements are programmatically associated with a `<label>` using matching `id` and `for` attributes.
+
+## Fallback strategies
+
+Browser support for the api.KeyboardEvent.isComposing capability: Limited availability.
+Supported by: Chrome 56 (Jan 2017), Edge 79 (Jan 2020), and Firefox 31 (Jul 2014).
+Unsupported in: Safari.
+
+In recent versions of Safari, an event-ordering issue (WebKit bug 165004) delivered `compositionend` to script handlers before the confirming `Enter` `keydown`, even though the underlying events were dispatched in the opposite order. By the time the keydown handler ran, `event.isComposing` had already been reset to `false`, meaning the standard check alone would have failed to prevent premature submission.
+
+If you need to support cross-browser compatibility across older versions of Safari and other platforms, adopt one of the following fallback strategies:
+
+### Strategy 1: Add a `keyCode === 229` check (recommended)
+
+By pairing `event.isComposing` with a check for `event.keyCode === 229`, you can reliably catch Safari's out-of-order confirming `Enter` keydown. Because this is nested under the `event.key === 'Enter'` gate, it is safe from mobile virtual keyboards that might use `229` for normal character layout entry.
+
+```js
+textarea.addEventListener('keydown', (event) => {
+  if (event.key === 'Enter' && !event.shiftKey) {
+    event.preventDefault();
+
+    // Block submission if composing natively or if keyCode is 229
+    if (event.isComposing || event.keyCode === 229) {
+      return;
+    }
+
+    form.requestSubmit();
+  }
+});
+```
+
+### Strategy 2: The `event.timeStamp` window workaround (alternative)
+
+For codebases that strictly forbid the use of deprecated APIs like `keyCode`, or if there are known issues with the `229` check in specific targeted environments, you can track the browser-reported event dispatch timestamp instead. 
+
+Because Safari dispatches the confirming `Enter` keydown event extremely close to the `compositionend` event (often within 5ms, and sometimes with the keydown timestamp being slightly *earlier* due to handler delivery order inversion), checking the time difference is highly reliable and is unlikely to trigger false-positives on mobile virtual keyboards under standard conditions.
+
+```js
+let lastCompositionEndAt = null;
+
+textarea.addEventListener('compositionend', (event) => {
+  // IMPORTANT: Always use event.timeStamp, not Date.now() or performance.now().
+  // Handler-time measurements are vulnerable to drift when the main thread is blocked.
+  lastCompositionEndAt = event.timeStamp;
+});
+
+textarea.addEventListener('keydown', (event) => {
+  if (event.key === 'Enter' && !event.shiftKey) {
+    event.preventDefault();
+
+    if (event.isComposing) {
+      return;
+    }
+
+    // Block submission if the event occurs within a 50ms window of composition ending.
+    // Math.abs handles Safari's inverted event delivery timing bug.
+    if (
+      lastCompositionEndAt !== null &&
+      Math.abs(event.timeStamp - lastCompositionEndAt) < 50
+    ) {
+      return;
+    }
+
+    form.requestSubmit();
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/required-field-feedback.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/required-field-feedback.md
new file mode 100644
index 00000000..6235172d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/required-field-feedback.md
@@ -0,0 +1,214 @@
+# Required Field Feedback
+
+## The Problem
+Marking required fields with an error state immediately upon page load can be confusing. Ideally, a required field should only look "invalid" if the user has attempted to fill it out and failed.
+
+## The Solution
+The `:user-invalid` pseudo-class solves this perfectly. For a required field, it will not match on page load. It will only match if:
+1.  The user interacts with the field (e.g., types a character and deletes it) and then leaves it (blur), leaving it empty.
+2.  The user attempts to submit the form while the field is empty.
+
+### Implementation Strategy
+
+1.  **HTML Constraint**: Add the `required` attribute to your inputs.
+2.  **Visual Feedback**: Use `:user-invalid` to style the border red and show a "Required" helper text.
+3.  **Timing**: Rely on the browser's native timing for visual feedback. You don't need `onBlur` handlers to add a `touched` class anymore, though some JavaScript is still needed to sync ARIA attributes (see below).
+
+## Implementation Guide
+
+### 1. HTML Structure
+```html
+<form id="feedback-form">
+  <div class="field">
+    <label for="full-name">Full Name</label>
+    <input
+      type="text"
+      id="full-name"
+      name="full-name"
+      required
+      aria-errormessage="name-error"
+    >
+    <!-- MANDATORY: Include an icon or distinct non-color indicator alongside error text -->
+    <div id="name-error" class="error-msg">
+      <span aria-hidden="true">❌</span> This field is required.
+    </div>
+  </div>
+</form>
+```
+
+### 2. CSS
+```css
+.error-msg {
+  display: none;
+  color: #d93025;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+/*
+  Only highlight empty required fields AFTER the user visits them.
+  MANDATORY: Provide multiple indicators (border shift + helper text/icon) to avoid color-only state communication.
+*/
+input:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg {
+  display: block;
+}
+
+/* Optional: Subtle indicator for required fields that are valid */
+input:required:user-valid {
+  border-color: #188038;
+  border-width: 2px;
+}
+```
+
+### 3. JavaScript State Synchronization
+
+MANDATORY: Because `:user-invalid` is a visual state, you MUST provide a JavaScript bridge to sync `aria-invalid="true"` dynamically for assistive technologies when a user blurs an invalid field or attempts submission.
+
+```javascript
+const form = document.getElementById('feedback-form');
+
+const syncAriaInvalid = (input) => {
+  if (!input.checkValidity()) {
+    input.setAttribute('aria-invalid', 'true');
+  } else {
+    input.removeAttribute('aria-invalid');
+  }
+};
+
+// Sync on blur when a user finishes interacting
+form.addEventListener('blur', (e) => {
+  if (e.target.matches('input[required]')) {
+    syncAriaInvalid(e.target);
+  }
+}, true);
+
+// Sync all required fields when submission is attempted
+form.addEventListener('submit', () => {
+  form.querySelectorAll('input[required]').forEach(syncAriaInvalid);
+});
+
+// Remove error state immediately upon correction
+form.addEventListener('input', (e) => {
+  if (e.target.matches('input[required]') && e.target.checkValidity()) {
+    e.target.removeAttribute('aria-invalid');
+  }
+});
+```
+
+## Fallbacking & Browser Support
+
+### Fallbacks & browser support for :user-valid and :user-invalid
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+
+```css
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg,
+input.user-invalid-fallback + .error-msg {
+  display: block;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+## Other Considerations
+
+1.  **Asterisks**: It is still best practice to indicate required fields visually (e.g., with an asterisk `*`) in the label, so users know what to expect *before* they interact.
+2.  **Submit Buttons**: Unlike `disabled` buttons, keep your submit button enabled. If the user clicks it, the browser will automatically trigger `:user-invalid` on all empty required fields and focus the first one. This is excellent for accessibility and UX.
+3.  **Accessibility**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/rich-media-picker.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/rich-media-picker.md
new file mode 100644
index 00000000..63c51f3a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/rich-media-picker.md
@@ -0,0 +1,133 @@
+# Rich Media Picker (Customizable Select)
+
+The native `<select>` element was historically difficult to style and could only contain plain text options. The `appearance: base-select` property offers a declarative, CSS-only way to opt into a customizable state for the `<select>` element. This allows developers to include rich HTML content—such as images, SVGs, and complex layouts—inside `<option>` elements, while retaining native keyboard accessibility and form integration. Use this pattern to replace heavy, custom-built select components with standard, native elements.
+
+## How to Implement
+
+To implement a rich media picker using the Customizable Select API:
+
+1. **Opt-in to base styles**: Apply `appearance: base-select` to both the `<select>` element and its internal picker using the `::picker(select)` pseudo-element. This changes the browser's HTML parser for the contents inside the `<select>`.
+2. **Define the Button Content**: Use standard `<button>` and `<selectedcontent>` elements inside the `<select>` to define what is shown when the picker is closed. The `<selectedcontent>` element automatically mirrors the content of the selected option. This is required if you want to display the currently selected rich content in the button.
+3. **Use Rich Content inside Options**: You can now place images, SVGs, and other HTML tags inside `<option>` tags. Prior to this API, the browser would strip tags from `<option>` tags and render only plain text.
+4. **Style the Popover**: Style the dropped-down options list by targeting the `::picker(select)` pseudo-element. It renders in the top layer, meaning you don't need to fight with `z-index`. Options are positioned using the Anchor Positioning API natively.
+
+## Example Code: Rich Role Picker
+
+```html
+<label for="role-picker">Select your role</label>
+<select class="custom-select" name="role" id="role-picker">
+  <button>
+    <selectedcontent></selectedcontent> <!-- Mirrors the selected option's content automatically so you do not need JS to update the button -->
+  </button>
+
+  <!-- Define concise aria-label values on options whose mirrored rich content would otherwise read awkwardly as a concatenated string -->
+  <option value="frontend" aria-label="Frontend Developer">
+    <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+      <rect x="2" y="3" width="20" height="14" rx="2" ry="2"></rect>
+    </svg>
+    <div class="option-text">
+      <span class="option-title">Frontend Developer</span>
+      <span class="option-desc">React, Vue, CSS</span>
+    </div>
+  </option>
+
+  <option value="backend" aria-label="Backend Developer">
+    <svg aria-hidden="true" width="24" height="24" viewBox="0 0 24 24" fill="none" stroke="currentColor">
+      <rect x="2" y="12" width="20" height="14" rx="2" ry="2"></rect>
+    </svg>
+    <div class="option-text">
+      <span class="option-title">Backend Developer</span>
+      <span class="option-desc">Node.js, Python</span>
+    </div>
+  </option>
+</select>
+```
+
+```css
+select.custom-select,
+select.custom-select::picker(select) {
+  appearance: base-select; /* MUST opt-in both the select and its picker to enable the customizable state, otherwise browser standard rendering applies */
+}
+
+select.custom-select {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  width: 100%;
+  padding: 12px;
+  background-color: #1e293b;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  color: #f1f5f9;
+  cursor: pointer;
+}
+
+select.custom-select::picker(select) {
+  background-color: #0f172a;
+  border: 1px solid #334155;
+  border-radius: 8px;
+  padding: 8px;
+  box-shadow: 0 10px 25px -5px rgba(0, 0, 0, 0.5);
+  width: anchor-size(width); /* Uses Anchor Positioning API to keep the dropdown precisely aligned to the button trigger width */
+}
+
+select.custom-select option {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 10px;
+  border-radius: 4px;
+  cursor: pointer;
+}
+
+select.custom-select option:hover {
+  background-color: #1e293b;
+}
+
+/* Remove standard OS checkmark for base-select */
+select.custom-select option::before {
+  display: none;
+}
+
+/* MANDATORY: Provide multiple visual indicators (e.g., prominent background color and bold title font) to communicate the checked state cleanly */
+select.custom-select option:checked {
+  background-color: #3b82f6;
+  color: #ffffff;
+}
+select.custom-select option:checked .option-title {
+  font-weight: 700;
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `appearance: base-select` when you need complex options layouts (icons, descriptions, images) that was previously only possible with heavy JavaScript UI frameworks.
+- **DO NOT** use ad-hoc elements if you notice performance lags; the browser handles native keyboard focus natively.
+- **DO** account for top-layer rendering. The picker renders in the top-layer, meaning it overrides relative `z-index` of page content.
+- **DO** hide secondary details (like descriptions) in the button state if they take too much space, by styling `.custom-select selectedcontent .option-desc { display: none; }`.
+- Test layout behavior. Setting `appearance: base-select` removes the default browser behavior of sizing the select based on its longest option width. You may need to set a fixed width or use flex/grid constraints to prevent layout shifts.
+- Ensure your `<select>` has a `name` attribute and an associated `<label>`. This ensures that even with a custom UI, the component remains accessible to screen readers and works correctly with standard form submissions.
+- Use standard `value` attributes on options to ensure form submission works exactly as before.
+
+## Fallback Strategies
+
+### Fallbacks & browser support for Customizable <select>
+
+Browser support for Customizable <select>: Limited availability.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), and Safari 27 (Sep 2026).
+Unsupported in: Firefox.
+
+For browsers that do not yet support `appearance: base-select`, the `<select>` element degrades gracefully to a standard operating system dropdown.
+
+- **Non-Text Content Ignored**: Older browsers strip HTML tags (like `<svg>` or `<div>`) inside `<option>` tags and render only the text nodes. Ensure the text content of the `<option>` is readable and meaningful on its own.
+- **HTML Structure Handling**: Standard parsers may ignore the `<button>` and `<selectedcontent>` tags inside `<select>` or treat them as invalid. No heavy JavaScript polyfills are strictly required for progressive enhancement if you view standard text as a readable fallback.
+
+
+```javascript
+document.addEventListener("DOMContentLoaded", () => {
+  // Check if browser supports base-select value
+  if (!CSS.supports("appearance", "base-select")) {
+    // Custom select overrides are not supported natively.
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/select-menu-interaction.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/select-menu-interaction.md
new file mode 100644
index 00000000..a7839988
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/select-menu-interaction.md
@@ -0,0 +1,178 @@
+# Select Menu Interaction
+
+## The Problem
+For mandatory dropdowns (e.g., "Choose a Country"), standard validation flags the field as invalid immediately if the default option has an empty value. This can create visual noise. We want to show the error only if the user opens the menu and closes it without choosing an option, or attempts to submit the form.
+
+## The Solution
+The `:user-invalid` pseudo-class works seamlessly with `<select>` elements. It respects the user's interaction flow: simply loading the page or focusing/blurring without making a change doesn't count as an interaction, so the field stays neutral until they actively attempt a selection.
+
+### Implementation Strategy
+
+1.  **HTML Constraint**: Use a `<select>` with `required`. The first option should have `value=""` and ideally be disabled/hidden to force a valid choice.
+2.  **Visual Feedback**: Use `:user-invalid` to style the select box border.
+3.  **Timing**: The browser considers the field "interacted" if the user changes the value (even back to the default invalid state) before they blur the control, or upon form submission.
+
+## Implementation Guide
+
+### 1. HTML Structure
+The "placeholder" option is key here.
+
+```html
+<form>
+  <div class="field">
+    <label for="country">Country</label>
+    <select
+      id="country"
+      name="country"
+      required
+      aria-errormessage="country-error"
+    >
+      <option value="" disabled selected>Select a country...</option>
+      <option value="us">United States</option>
+      <option value="ca">Canada</option>
+      <option value="uk">United Kingdom</option>
+    </select>
+    <div id="country-error" class="error-msg">
+      Please select a country.
+    </div>
+  </div>
+</form>
+```
+
+### 2. CSS
+```css
+.error-msg {
+  display: none;
+  color: #d93025;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+/*
+  Only show error after the user visits the select menu.
+*/
+select:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+select:user-invalid + .error-msg {
+  display: block;
+}
+
+select:user-valid {
+  border-color: #188038;
+}
+```
+
+## Fallbacking & Browser Support
+
+### Fallbacks & browser support for :user-valid and :user-invalid
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+
+```css
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg,
+input.user-invalid-fallback + .error-msg {
+  display: block;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+## Other Considerations
+
+1.  **Mobile behavior**: On mobile devices, "blur" might happen differently depending on the OS picker. Testing on actual devices is recommended.
+2.  **Accessibility**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/slider.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/slider.md
new file mode 100644
index 00000000..1e3cba1b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/slider.md
@@ -0,0 +1,182 @@
+# Brand-Consistent Range Slider
+
+## Use the native range input
+
+Use a labeled `<input type="range">` rather than recreating a slider with `<div>` elements or custom pointer handlers. The native control preserves keyboard and pointer interaction, touch behavior, and accessibility support. Configure `min`, `max`, `step`, and `value` for the use case.
+
+```html
+<label for="range-slider">Volume</label>
+<input type="range" id="range-slider" value="70"/>
+```
+
+If the value requires a formatted label or unit, expose it in ordinary DOM content and update `aria-valuetext` when changed. Do not use `::before` or `::after` on slider pseudo-elements, as generated content on form controls is not interoperable. If a tooltip that follows the thumb is required, use the `slider-tooltip` (via `npx -y modern-web-guidance@latest retrieve "slider-tooltip"`) guide.
+
+## Choose the styling approach
+
+For simple color customization, use `brand-consistent-forms` (via `npx -y modern-web-guidance@latest retrieve "brand-consistent-forms"`) and retain the browser’s native rendering:
+
+```css
+input[type="range"] {
+  accent-color: var(--brand-color);
+}
+```
+
+`accent-color` is not a complete slider styling API. Its effect on the thumb, track, and fill is user-agent-dependent. Use the pseudo-elements below when the track, thumb, dimensions, shape, or fill must be controlled.
+
+## Style the track and thumb
+
+Reset default OS styling with `appearance: none`, `margin: 0`, and `border: 0`. To normalize cross-browser rendering, declare WebKit and Firefox pseudo-elements in separate rule blocks, and center the WebKit thumb using `margin-block-start: calc((var(--slider-track-size) - var(--slider-thumb-size)) / 2)` (Firefox centers the thumb automatically). Keep consumer-facing values as custom properties on the input so themes do not target pseudo-elements directly.
+
+```css
+input[type="range"] {
+  --slider-track-size: 0.5rem;
+  --slider-thumb-size: 1.25rem;
+  --slider-track-radius: 999px;
+  --slider-thumb-radius: 50%;
+  --slider-track-color: #d9d9d9;
+  --slider-fill-color: #06c;
+  --slider-thumb-color: var(--slider-fill-color);
+  --slider-direction: to right;
+
+  /* reverse gradient direction for right-to-left layouts */
+  &:dir(rtl) {
+    --slider-direction: to left;
+  }
+
+  /* Read min and max from attributes; --control-value is synced by the script below. */
+  --attr-min: attr(min type(<number>), 0);
+  --attr-max: attr(max type(<number>), 100);
+  --control-value: attr(value type(<number>), 50);
+  --slider-progress: calc(
+    progress(var(--control-value), var(--attr-min), var(--attr-max)) * 100%
+  );
+
+  appearance: none;
+  inline-size: 100%;
+  block-size: 2.5rem; /* Preserve a generous interaction area. */
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: transparent;
+  cursor: pointer;
+}
+
+/* WebKit/Blink. */
+input[type="range"]::-webkit-slider-runnable-track {
+  block-size: var(--slider-track-size);
+  border: 0;
+  border-radius: var(--slider-track-radius);
+  background: linear-gradient(
+    var(--slider-direction),
+    var(--slider-fill-color) var(--slider-progress),
+    var(--slider-track-color) var(--slider-progress)
+  );
+}
+
+input[type="range"]::-webkit-slider-thumb {
+  -webkit-appearance: none;
+  appearance: none;
+  inline-size: var(--slider-thumb-size);
+  block-size: var(--slider-thumb-size);
+  margin-block-start: calc(
+    (var(--slider-track-size) - var(--slider-thumb-size)) / 2
+  );
+  border: 0;
+  border-radius: var(--slider-thumb-radius);
+  background: var(--slider-thumb-color);
+}
+
+/* Firefox. */
+input[type="range"]::-moz-range-track {
+  block-size: var(--slider-track-size);
+  border: 0;
+  border-radius: var(--slider-track-radius);
+  background: var(--slider-track-color);
+}
+
+input[type="range"]::-moz-range-progress {
+  block-size: var(--slider-track-size);
+  border-radius: var(--slider-track-radius);
+  background: var(--slider-fill-color);
+}
+
+input[type="range"]::-moz-range-thumb {
+  inline-size: var(--slider-thumb-size);
+  block-size: var(--slider-thumb-size);
+  border: 0;
+  border-radius: var(--slider-thumb-radius);
+  background: var(--slider-thumb-color);
+}
+```
+
+Always provide a visible keyboard focus indicator after removing the native appearance. Do not use color alone:
+
+```css
+input[type="range"]:focus-visible {
+  outline: 2px solid var(--slider-fill-color);
+  outline-offset: 4px;
+}
+```
+
+## Style the active track
+
+When the filled portion of the track is styled differently from the unfilled track, Firefox exposes it via `::-moz-range-progress`. WebKit/Blink do not provide an equivalent pseudo-element, so sync the live input value to `--control-value` on `input` events:
+
+```js
+const slider = document.querySelector('#range-slider');
+
+function syncSliderValue() {
+  slider.style.setProperty('--control-value', slider.value);
+}
+
+syncSliderValue();
+slider.addEventListener('input', syncSliderValue);
+```
+
+## Limitations
+
+- Do not combine WebKit and Firefox pseudo-selectors into a single comma-separated list (e.g. `::-webkit-slider-thumb, ::-moz-range-thumb`); browsers drop the entire rule if an unrecognized vendor pseudo-element is encountered.
+
+## Fallbacks
+
+### Fallbacks & browser support for accent-color
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+The `accent-color` property is progressive enhancement.
+Browsers that do not support this property will ignore it and use their default UI colors.
+
+### Fallbacks & browser support for `progress()` and `attr()`
+
+Baseline status for progress(): Newly available. It's been Baseline since 2026-09-01.
+Supported by: Chrome 138 (Jun 2025), Edge 138 (Jun 2025), Firefox 155 (Sep 2026), and Safari 26 (Sep 2025).
+
+When `progress()` is unsupported, compute `--slider-progress` with `calc()`:
+
+```css
+@supports not (opacity: progress(1, 0, 100)) {
+  input[type="range"] {
+    --slider-progress: calc(
+      (var(--control-value) - var(--attr-min)) /
+      (var(--attr-max) - var(--attr-min)) * 100%
+    );
+  }
+}
+```
+
+Browser support for attr(): Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 155 (Sep 2026).
+Unsupported in: Safari.
+
+When typed `attr()` is unsupported, sync `--attr-min` and `--attr-max` from the input's `min` and `max` attributes in JavaScript:
+
+```js
+function syncSliderValue() {
+  slider.style.setProperty('--attr-min', slider.min || 0);
+  slider.style.setProperty('--attr-max', slider.max || 100);
+  slider.style.setProperty('--control-value', slider.value);
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/sms-otp-form.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/sms-otp-form.md
new file mode 100644
index 00000000..284286fa
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/sms-otp-form.md
@@ -0,0 +1,208 @@
+# SMS OTP form verification
+
+Delivering a one-time passcode (OTP) via SMS is a common flow for phone number verification, account recovery, step-up authentication, and payment confirmation. Switching between a browser and an SMS messaging app to memorize or copy-paste a multi-digit code introduces user friction, increases drop-off rates, and leaves users vulnerable to phishing on spoofed domains.
+
+Combining semantic `<form>` markup, `<input autocomplete="one-time-code" inputmode="numeric">`, origin-bound SMS formatting (`@domain #code`), and the WebOTP API (`OTPCredential`) creates a layered, progressively enhanced verification flow:
+
+1. **Automatic extraction and submission**: Browsers supporting the WebOTP API verify the origin against the `@domain #code` line in the SMS, populate the `<input>`, and trigger verification with a single tap.
+2. **Origin-bound keyboard autofill**: Browsers and operating systems that support `autocomplete="one-time-code"` (such as Safari on iOS, iPadOS, and macOS) parse the `@domain #code` message and suggest the code in the keyboard autofill bar only when the domain matches.
+3. **Frictionless manual entry**: Users entering a code from another device receive a numeric virtual keypad via `inputmode="numeric"` without the usability hazards of `<input type="number">`.
+
+## Security considerations
+
+SMS OTP verifies possession of a phone number and provides convenient step-up verification, but SMS transport and phone numbers can be subject to SIM swapping, number recycling, and interception. Always pair client-side autofill and the WebOTP API with the origin-bound `@domain #code` SMS format so the browser and OS verify that the target domain matches before suggesting or delivering the code. For primary phishing-resistant authentication, prefer passkeys over SMS-based codes (see `passkeys` (via `npx -y modern-web-guidance@latest retrieve "passkeys"`)).
+
+## Semantic form markup
+
+Wrap the verification control in a semantic `<form>` element with `method="POST"` and an explicit `<button type="submit">`. Always use a single `<input>` element rather than splitting digits across multiple boxes.
+
+- **Use `type="text"` with `inputmode="numeric"`**: Never use `type="number"` for OTP codes. A one-time passcode is an identifier string that may contain leading zeros (such as `012345`), not a countable quantity. Using `type="number"` adds increment/decrement spinner buttons, can strip leading zeros, and allows accidental scroll-wheel value changes. Also avoid `type="tel"`, which is a legacy workaround intended for full telephone numbers. Pair `type="text"` with `inputmode="numeric"` to present a digits-only virtual keyboard on mobile devices.
+- **Add `autocomplete="one-time-code"`**: Instructs browsers and operating systems to suggest incoming SMS verification codes in the autofill bar when the `<input>` is focused.
+- **Place instructional hints above the `<input>`**: Associate a visible `<label>` using `for` and `id`, and place any format instructions (linked via `aria-describedby`) visually **above** the `<input>` so autofill popovers and mobile virtual keyboards never cover the instructions.
+- **Do not split digits across multiple `<input>` elements**: Multi-box OTP patterns (six separate `maxlength="1"` inputs) break native `autocomplete="one-time-code"` autofill in many browsers, hinder copy-pasting, and complicate screen reader navigation. If a segmented visual design is required, style a single `<input>` with `letter-spacing` and a monospace font.
+
+```html
+<form id="otp-form" action="/verify-otp" method="POST">
+  <div class="form-group">
+    <label for="otp-input">Verification code</label>
+    <!-- Place the hint above the input so autofill popovers and mobile keyboards do not obscure it -->
+    <p id="otp-format-hint" class="field-hint">
+      Enter the 6-digit code sent to your phone.
+    </p>
+    <!-- MANDATORY: Use a single input with type="text", inputmode="numeric", and autocomplete="one-time-code" -->
+    <input
+      type="text"
+      id="otp-input"
+      name="otp"
+      inputmode="numeric"
+      autocomplete="one-time-code"
+      pattern="\d{6}"
+      maxlength="6"
+      aria-describedby="otp-format-hint"
+      required>
+  </div>
+  <button type="submit">Verify code</button>
+</form>
+```
+
+```css
+/* Optional: Style a single input to visually space digits without splitting the DOM element */
+#otp-input {
+  font-family: ui-monospace, monospace;
+  font-size: 1.25rem; /* Example value: must be at least 1rem (16px) to prevent mobile browser auto-zoom */
+  letter-spacing: 0.35em;
+  min-height: 48px;
+  padding: 0.5rem 0.75rem;
+  box-sizing: border-box;
+}
+```
+
+## Origin-bound SMS message format
+
+For both the WebOTP API and Safari's domain-bound `autocomplete="one-time-code"` autofill to verify that the code belongs to your website, your backend SMS service must format the **last line** of the text message with the origin domain prefixed by `@` and the OTP prefixed by `#`:
+
+```text
+Your verification code is 123456.
+
+@example.com #123456
+```
+
+Enforce the following formatting rules on the outgoing SMS message:
+
+- **Include human-readable text first**: Always start the SMS with a clear human-readable sentence containing the code so users typing it manually on another device can read it easily.
+- **Place `@<domain> #<otp>` on the very last line**: The `@` character must be the first character of the final line, with no trailing lines or signature text after it.
+- **Use only the host domain**: Do not include a URL scheme (`https://` or `http://`), port (`:8080`), or path (`/verify`) in the `@domain` token.
+- **Separate tokens with a single space**: Place exactly one space between `@<domain>` and `#<otp>`, and never include whitespace inside the domain or between `#` and the code.
+
+## Integrating the WebOTP API into your verification flow
+
+The WebOTP API (`OTPCredential`) requires a Secure Context (`https://` in production, or `http://localhost` during local development). Instead of pasting a disconnected `DOMContentLoaded` script that queries the DOM and calls `form.submit()`, integrate `navigator.credentials.get()` directly into the lifecycle and submission handler of your verification UI:
+
+- **Tie the request lifecycle to the active OTP step**: Start listening for the OTP when the verification input is rendered and active (for example, when the OTP step mounts after the user requests an SMS code, and again whenever the user clicks a "Resend code" button).
+- **Manage an `AbortController` across all exit paths**: Pass an `AbortSignal` (`signal: ac.signal`) to `navigator.credentials.get()`. Call `ac.abort()` whenever:
+    - The user manually submits the form (or submits a code filled via `autocomplete="one-time-code"`).
+    - A new SMS code is requested ("Resend code"), aborting the previous controller before creating a new one.
+    - The verification component, dialog, or route unmounts.
+- **Trigger the application's submission handler (`form.requestSubmit()`)**: When `navigator.credentials.get()` resolves with `otp`, set `otpInput.value = otp.code` and call `form.requestSubmit()` (or invoke your verification function directly). Do **NOT** call `form.submit()`, because `form.submit()` bypasses `submit` event listeners (`event.preventDefault()` / `fetch()` handlers) and skips native constraint validation.
+
+```javascript
+const otpForm = document.getElementById('otp-form');
+const otpInput = document.getElementById('otp-input');
+
+let otpAbortController = null;
+
+function stopSmsOtpListener() {
+  if (otpAbortController) {
+    otpAbortController.abort();
+    otpAbortController = null;
+  }
+}
+
+async function startSmsOtpListener() {
+  // Feature-detect WebOTP support
+  if (!otpInput || !('OTPCredential' in window)) {
+    return;
+  }
+
+  // Cancel any previous pending WebOTP request (e.g., when re-sending an SMS code)
+  stopSmsOtpListener();
+  const ac = new AbortController();
+  otpAbortController = ac;
+
+  try {
+    const otp = await navigator.credentials.get({
+      otp: { transport: ['sms'] },
+      signal: ac.signal,
+    });
+
+    if (!otp) return;
+    otpInput.value = otp.code;
+
+    // Trigger standard form submission so submit event listeners and validation run
+    if (otpForm) {
+      otpForm.requestSubmit();
+    }
+  } catch (err) {
+    // Expected when aborted by manual submission, resend, unmount, or user dismissal
+    if (err && err.name === 'AbortError') {
+      return;
+    }
+    console.error('WebOTP verification error:', err);
+  }
+}
+
+otpForm.addEventListener('submit', async (event) => {
+  // MANDATORY: Abort any in-flight WebOTP request when the form is submitted
+  stopSmsOtpListener();
+
+  // Application-specific submission logic (e.g., AJAX fetch or native POST)
+  event.preventDefault();
+  const formData = new FormData(otpForm);
+  // await fetch(otpForm.action, { method: 'POST', body: formData });
+});
+
+// Start listening when the OTP verification step becomes active
+startSmsOtpListener();
+```
+
+## Cross-origin iframe verification
+
+Receiving an SMS OTP inside a cross-origin `<iframe>` is restricted by default and is primarily used for embedded payment confirmation flows (such as 3D Secure verification where `shop.example` embeds an issuer challenge from `bank.example`). Supporting WebOTP inside a cross-origin `<iframe>` requires three coordinated configurations:
+
+1. **Bind both origins on the last line of the SMS**: List the top-level embedding domain first (`@shop.example`), followed by `#<otp>`, followed by a space and the embedded iframe domain (`@bank.example`):
+
+```text
+Your verification code is 123456.
+
+@shop.example #123456 @bank.example
+```
+
+2. **Send the `Permissions-Policy` HTTP response header**: Delegate `otp-credentials` to the cross-origin iframe origin in the parent document's HTTP headers:
+
+```http
+Permissions-Policy: otp-credentials=(self "https://bank.example")
+```
+
+3. **Add `allow="otp-credentials"` to the `<iframe>` element**: Explicitly grant the permission policy on the `<iframe>` tag in the embedding page and include a descriptive `title` attribute for screen readers:
+
+```html
+<iframe
+  src="https://bank.example/verify"
+  allow="otp-credentials"
+  title="Payment verification">
+</iframe>
+```
+
+Inside the `<iframe>` document served by `https://bank.example`, run the same `<form>` markup and `navigator.credentials.get({ otp: { transport: ['sms'] }, signal: ac.signal })` verification lifecycle shown above.
+
+## Fallback strategies
+
+### WebOTP API fallback
+
+Browser support for WebOTP: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), and Safari 27 (Sep 2026).
+Unsupported in: Firefox.
+
+If your target browsers do not support the WebOTP API (`OTPCredential`), do not load a third-party JavaScript polyfill, as reading incoming SMS messages requires operating-system-level integration. Instead, rely on the three-tier progressive enhancement built into the `<input>` markup:
+
+- **Progressive enhancement experience**: Guard the `navigator.credentials.get({ otp: { transport: ['sms'] } })` call behind `if ('OTPCredential' in window)`. When `OTPCredential` is unavailable:
+    1. Browsers that support `autocomplete="one-time-code"` (such as Safari on iOS 14+, iPadOS, and macOS with iCloud SMS relay) parse the `@domain #code` SMS and present the code in the system keyboard autofill bar when the `<input>` is focused.
+    2. All other browsers fall back to manual entry in the single `<input type="text" inputmode="numeric" pattern="\d{6}" maxlength="6" required>`, displaying a numeric keypad on mobile devices and submitting via the `<button type="submit">`.
+
+### Permissions Policy fallback
+
+Browser support for Permissions policy: Limited availability.
+Supported by: Chrome 108 (Nov 2022) and Edge 108 (Dec 2022).
+Unsupported in: Firefox and Safari.
+
+If the browser does not support delegating `otp-credentials` via `Permissions-Policy` and `<iframe allow="otp-credentials">`, the embedded verification `<form>` inside the cross-origin `<iframe>` degrades gracefully to `autocomplete="one-time-code"` keyboard suggestions and manual numeric input without throwing unhandled exceptions.
+
+### Inputmode and AbortController support
+
+Baseline status for inputmode: Widely available. It's been Baseline since 2021-12-07.
+Supported by: Chrome 66 (Apr 2018), Edge 79 (Jan 2020), Firefox 95 (Dec 2021), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for AbortController and AbortSignal: Widely available. It's been Baseline since 2019-03-25.
+Supported by: Chrome 66 (Apr 2018), Edge 16 (Oct 2017), Firefox 57 (Nov 2017), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Both the HTML `inputmode` attribute and `AbortController` (`AbortSignal`) are supported across modern browsers and require no polyfill or fallback code.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/switch.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/switch.md
new file mode 100644
index 00000000..5e5151fb
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/switch.md
@@ -0,0 +1,60 @@
+# Build Accessible Switch Controls
+
+Use the HTML `switch` attribute on `<input type="checkbox" switch>` with an associated `<label>` to build a binary on/off toggle that preserves native form submission, keyboard navigation, and screen reader semantics (see `checkbox` (via `npx -y modern-web-guidance@latest retrieve "checkbox"`) and `forms` (via `npx -y modern-web-guidance@latest retrieve "forms"`)).
+
+## Markup
+
+Add the boolean `switch` attribute to a standard checkbox input:
+
+```html
+<label>
+  Enable notifications
+  <input id="notifications" type="checkbox" switch>
+</label>
+```
+
+- The label can wrap the input or be associated with `for`/`id`. All styling targets the input, so it doesn't depend on the label structure.
+- When checked, the input submits its standard checkbox value. In JavaScript, listen for `change` (or `input`) events and read `.checked` rather than `.value`.
+
+## Styling
+
+Customize the control's highlight color using `accent-color` (see `brand-consistent-forms` (via `npx -y modern-web-guidance@latest retrieve "brand-consistent-forms"`)) and ensure visible focus styling:
+
+```css
+input[type="checkbox"][switch] {
+  accent-color: var(--accent-color, #1769e0);
+  margin: 0;
+  cursor: pointer;
+}
+
+input[type="checkbox"][switch]:focus-visible {
+  outline: 3px solid var(--focus-color, #ff8c00);
+  outline-offset: 4px;
+}
+```
+
+## Fallback strategies
+
+### Fallbacks & browser support for switch-control
+
+Browser support for <input type="checkbox" switch>: Limited availability.
+Supported by: Safari 17.4 (Mar 2024).
+Unsupported in: Chrome, Edge, and Firefox.
+
+If your Baseline target does not support `<input type="checkbox" switch>`, load `input-switch-polyfill` only when `'switch' in HTMLInputElement.prototype` is `false`. Do not load the polyfill unconditionally. The polyfill enhances checkboxes with the `switch` attribute by setting `role="switch"`, applying switch styling (`appearance: none`), syncing computed `accent-color`, and providing pointer drag support.
+
+Use the package-loading approach appropriate to your project. The example below assumes your setup can resolve module specifiers:
+
+```javascript
+if (!('switch' in HTMLInputElement.prototype)) {
+  import('input-switch-polyfill');
+}
+```
+
+### Fallbacks & browser support for accent-color
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+The `accent-color` property is progressive enhancement.
+Browsers that do not support this property will ignore it and use their default UI colors.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/validate-input-after-interaction.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/validate-input-after-interaction.md
new file mode 100644
index 00000000..e880ed21
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/forms/validate-input-after-interaction.md
@@ -0,0 +1,258 @@
+# Validate Input After Interaction
+
+## The Problem
+
+Displaying validation errors the moment a user focuses on a field and starts typing is premature and distracting. For example, as a user types an email address (e.g., "user@gm") or a password with complex requirements, the field is technically invalid until completion. Standard `:invalid` styling results in an error state appearing immediately, frustrating the user.
+
+## The Solution
+
+The `:user-invalid` pseudo-class allows you to defer the error state until the user has "committed" to a value (by blurring the field) or attempted to submit the form. This ensures validation feedback is provided only after the user has finished interacting with the field.
+
+### Implementation Strategy
+
+1.  **HTML Constraint**: DO use standard HTML5 attributes like `type="email"`, `pattern`, and `required` to trigger the browser's built-in validation logic.
+2.  **Visual Feedback**: DO use `:user-invalid` to apply error styling only after interaction.
+3.  **Positive Reinforcement**: DO optionally use `:user-valid` to give a green "success" indicator once the requirements are met.
+4.  **Graceful Recovery**: As soon as the user corrects the input to a valid format, `:user-invalid` stops matching, removing the error state immediately.
+
+## Implementation Guide
+
+### Use Case 1: Email Validation
+
+MANDATORY: Rely on standard HTML5 attributes for email fields. The error message is hidden by default and only revealed when the browser determines the user has left the field in an invalid state.
+
+```html
+<form>
+  <div class="field">
+    <label for="email">Email Address</label>
+    <!-- MANDATORY: Place format hints above the input so autocomplete popovers don't cover them during editing -->
+    <span id="email-hint" class="hint">Format: you@example.com</span>
+    <!-- DO: Use standard HTML validation attributes like type="email" and required -->
+    <input
+      type="email"
+      id="email"
+      name="email"
+      required
+      autocomplete="email"
+      aria-describedby="email-hint"
+      aria-errormessage="email-error"
+    >
+    <div id="email-error" class="error-msg">
+      <span aria-hidden="true">❌</span> Please enter a valid email address.
+    </div>
+  </div>
+</form>
+```
+
+```css
+.hint {
+  display: block;
+  color: #5f6368;
+  font-size: 0.85rem;
+  margin-bottom: 0.25rem;
+}
+
+.error-msg {
+  display: none;
+  color: #d93025;
+  font-size: 0.875rem;
+  margin-top: 0.25rem;
+}
+
+/*
+  DO: Only show error styles after user interaction.
+  Use multiple indicators (border/background shift + icon/text) to avoid color-only states.
+*/
+input:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+/* DO: Reveal the error message using the adjacent sibling selector */
+input:user-invalid + .error-msg {
+  display: block;
+}
+
+/* DO: Provide a clear success indication on :user-valid */
+input:user-valid {
+  border-color: #188038;
+}
+```
+
+### Use Case 2: Password Complexity
+
+MANDATORY: Define the complexity rule using a Regex Lookahead pattern in the `pattern` attribute. The rules list is shown above the input to guide the user, and highlighted if there's an error.
+
+```html
+<form>
+  <div class="field">
+    <label for="password">New Password</label>
+    <!-- MANDATORY: Place hints and rules above the input so mobile keyboards do not obscure them -->
+    <ul id="password-rules" class="rules-list">
+      <li>At least 8 characters</li>
+      <li>One uppercase letter</li>
+      <li>One number</li>
+      <li>One special character</li>
+    </ul>
+    <!-- DO: Use pattern and minlength for complex password validation
+         DO: Match all constraints with lookaheads via pattern attribute
+     -->
+    <input
+      type="password"
+      id="password"
+      autocomplete="new-password"
+      required
+      pattern="(?=.*\d)(?=.*[a-z])(?=.*[A-Z])(?=.*[\W_]).{8,}"
+      minlength="8"
+      aria-describedby="password-rules"
+    >
+  </div>
+</form>
+```
+
+```css
+/* DO: State the default styling as neutral */
+.rules-list { 
+  color: #5f6368; 
+  margin-bottom: 0.5rem;
+}
+
+/* DO: Show invalid state (After interaction): Error */
+input:user-invalid {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+/* DO: Highlight rules list when error is shown using the modern :has() selector */
+.field:has(input:user-invalid) .rules-list {
+  color: #d93025;
+  font-weight: 600;
+}
+
+/* DO: Add success indications for :user-valid state */
+input:user-valid {
+  border-color: #188038;
+}
+
+/* DO: Hide rules once satisfied */
+.field:has(input:user-valid) .rules-list {
+  display: none;
+}
+```
+
+## Fallbacking & Browser Support
+
+### Fallbacks & browser support for :user-valid and :user-invalid
+
+Baseline status for :user-valid and :user-invalid: Widely available. It's been Baseline since 2023-11-02.
+Supported by: Chrome 119 (Oct 2023), Edge 119 (Nov 2023), Firefox 88 (Apr 2021), and Safari 16.5 (May 2023).
+
+### CSS for Fallback
+
+```css
+input:user-invalid,
+input.user-invalid-fallback {
+  border-color: #d93025;
+  background-color: #fce8e6;
+}
+
+input:user-invalid + .error-msg,
+input.user-invalid-fallback + .error-msg {
+  display: block;
+}
+```
+
+### JavaScript Fallback
+
+Use a reusable utility that tracks interaction state using a `WeakMap`. This avoids polluting the DOM with "dirty" classes or data attributes.
+
+```javascript
+const UserInvalidFallback = (() => {
+  const dirtyState = new WeakMap();
+
+  const updateState = (input) => {
+    const isValid = input.checkValidity();
+
+    // Update both visual and ARIA state
+    input.classList.toggle('user-invalid-fallback', !isValid);
+    input.classList.toggle('user-valid-fallback', isValid);
+
+    if (!isValid) {
+      input.setAttribute('aria-invalid', 'true');
+    } else {
+      input.removeAttribute('aria-invalid');
+    }
+  };
+
+  const handleEvent = (event) => {
+    const input = event.target;
+
+    if (event.type === 'reset') {
+      const controls = input.elements || [];
+      for (const control of controls) {
+        dirtyState.delete(control);
+        control.classList.remove('user-invalid-fallback');
+        control.classList.remove('user-valid-fallback');
+        control.removeAttribute('aria-invalid');
+      }
+      return;
+    }
+
+    if (!input.checkValidity) return;
+
+    if (event.type === 'input' || event.type === 'change') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasInteracted = true;
+      dirtyState.set(input, state);
+      if (state.hasBlurred) {
+        updateState(input);
+      }
+    } else if (event.type === 'blur') {
+      const state = dirtyState.get(input) || { hasInteracted: false, hasBlurred: false };
+      state.hasBlurred = true;
+      dirtyState.set(input, state);
+      if (state.hasInteracted) {
+        updateState(input);
+      }
+    }
+  };
+
+  const init = (root = document) => {
+    if (CSS.supports('selector(:user-invalid)')) return;
+
+    root.addEventListener('blur', handleEvent, true); // Capture phase
+    root.addEventListener('input', handleEvent);
+    root.addEventListener('change', handleEvent);
+    root.addEventListener('reset', handleEvent, true); // Capture resets
+  };
+
+  return { init };
+})();
+
+// Initialize for a specific form
+const form = document.querySelector('#demo-form');
+UserInvalidFallback.init(form);
+```
+
+## Other Considerations
+
+1.  **Accessibility**:
+    *   MANDATORY: Use `aria-describedby` to link the rules list to the input.
+    *   DO NOT: Hide rules lists entirely until the input is valid; users need to know what to type!
+2.  **Pattern Attribute Limits**: MANDATORY: The `pattern` attribute performs a full match (implied `^...$`). Ensure your password regex accounts for the entire string.
+3.  **Validation Strictness**: DO note that the browser's default `type="email"` validation is quite permissive (e.g., `user@localserver` might pass). If you need stricter validation, you may need to use a more robust validation library or a custom validation function alongside `type="email"`.
+4.  **Focus Management**: MANDATORY: If a user submits the form with an invalid field, the browser will automatically focus the first invalid field. Your `:user-invalid` styles will apply immediately because a submission attempt counts as an interaction.
+5. **Consistent ARIA Experience**: Native `:user-invalid` does not automatically sync with ARIA attributes. Add the following JavaScript to keep `aria-invalid` in sync with the visual state:
+
+```javascript
+// Sync aria-invalid with the CSS :user-invalid state
+const syncAria = (el) => {
+  el.setAttribute?.('aria-invalid', el.matches(':user-invalid') ? 'true' : 'false');
+};
+
+// Update on blur (to show error) and input (to clear it)
+document.addEventListener('blur', (e) => syncAria(e.target), true);
+document.addEventListener('input', (e) => {
+  if (e.target.hasAttribute('aria-invalid')) syncAria(e.target);
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/accessible-web-components.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/accessible-web-components.md
new file mode 100644
index 00000000..2eae4944
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/accessible-web-components.md
@@ -0,0 +1,61 @@
+# Accessible Web Components
+
+A shadow boundary changes how semantics and ARIA work. Two failures dominate: missing semantics inside the shadow tree, and ARIA references that silently break because they cannot cross shadow roots.
+
+Start from semantic markup: use real `<button>`, `<nav>`, `<ul>` inside the template so most semantics come for free, and reserve `ElementInternals`/ARIA for the gaps.
+
+## Default semantics via the ElementInternals ARIA mixin
+
+Set a custom element's role and ARIA state in JS through `ElementInternals`, rather than writing ARIA attributes onto the host. This keeps the semantics as defaults the component owns, while still letting a consumer override them with attributes in the Light DOM.
+
+```javascript
+class ToggleSwitch extends HTMLElement {
+  #internals;
+  constructor() {
+    super();
+    this.#internals = this.attachInternals();
+    this.#internals.role = 'switch';          // default role, no host attribute needed
+    this.#internals.ariaChecked = 'false';    // exposed to the accessibility tree
+    this.addEventListener('click', () => this.toggle());
+    this.addEventListener('keydown', (e) => {
+      if (e.key === ' ') { e.preventDefault(); this.toggle(); }
+    });
+  }
+  connectedCallback() {
+    // Put the host in the tab order on connect (setting tabIndex in the constructor throws on createElement).
+    if (!this.hasAttribute('tabindex')) this.tabIndex = 0;
+  }
+  toggle() {
+    const on = this.#internals.ariaChecked !== 'true';
+    this.#internals.ariaChecked = String(on);
+  }
+}
+customElements.define('toggle-switch', ToggleSwitch);
+```
+
+This avoids polluting the DOM with ARIA attributes and prevents consumers from accidentally clobbering them, while the accessibility tree still sees the correct role and state.
+
+## Focus management and `delegatesFocus`
+
+- When the **host element itself is the interactive control** and carries the role and state via `ElementInternals` (like `ToggleSwitch` above), put the host in the tab order inside `connectedCallback` (`if (!this.hasAttribute('tabindex')) this.tabIndex = 0` — never in the constructor, which throws on `document.createElement`) so focus lands on the host and assistive technology announces its role and state. Do not set `tabindex` on the host for static, non-interactive components (such as a callout or card).
+- Attach the shadow root with `delegatesFocus: true` when the component **wraps an internal focusable control** that owns the semantics (or on a form-associated custom element with `static formAssociated = true`). Focusing the host (and clicking an associated `<label>` for form-associated elements) then forwards focus to the first focusable child, and `:focus` matches the host. Do not combine `delegatesFocus: true` with a role/state on the host, or focus will land on the inner element and skip the host's state.
+- For roving focus or moving focus into a newly revealed region, give the target `tabindex="-1"` and call `.focus()`; make programmatically-focusable targets explicit rather than relying on tab order.
+
+## ARIA relationships across shadow roots
+
+- **MANDATORY**: an `id` referenced by `aria-labelledby`, `aria-describedby`, `aria-controls`, etc. resolves only within the referencing element's **own** tree. An `id`-based attribute in the Light DOM cannot point at an `id` inside a shadow tree, and vice versa; the reference is silently ignored.
+- To cross the boundary, use the reflected ARIA *element* properties (e.g. `ariaLabelledByElements`, `ariaDescribedByElements`, etc), which take direct JS element references instead of ids. They resolve **outward**: an element inside a shadow tree can point at a target in the Light DOM or any ancestor tree (including slotted content), so you can label a shadow-internal control from Light DOM content — something `id` references can't express.
+- They do **not** resolve **inward**: an element can't reference *into* a descendant shadow tree (e.g. a host can't be labeled by its own shadow content). For that direction the emerging **Reference Target** mechanism is the standards direction, but it is not yet broadly available.
+- When a relationship can't be expressed either way, keep it within one tree (render the label in the same tree) or use `aria-label` text instead of an `id` reference.
+
+## Fallback strategies
+
+Baseline status for ARIA attribute reflection: Widely available. It's been Baseline since 2023-10-24.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 119 (Oct 2023), and Safari 16.4 (Mar 2023).
+
+Where the `ElementInternals` ARIA mixin is unavailable, set the role and ARIA state as attributes on the host instead (`this.setAttribute('role', 'switch')`). It works everywhere, at the cost of putting attributes in the DOM that a consumer could override.
+
+Baseline status for the api.Element.ariaLabelledByElements capability: Newly available. It's been Baseline since 2025-04-04.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 136 (Mar 2025), and Safari 16.4 (Mar 2023).
+
+Where the reflected ARIA *element* properties are unavailable, use an `id`-based `aria-*` attribute for same-tree relationships; a cross-boundary label has no `id`-based equivalent, so fall back to `aria-label` text.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/custom-elements.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/custom-elements.md
new file mode 100644
index 00000000..6d1a4b9c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/custom-elements.md
@@ -0,0 +1,122 @@
+# Custom Elements
+
+A custom element is a class registered against a tag name via `customElements.define()`. Registration and basic lifecycle are well understood; the rules below target the parts routinely implemented incorrectly.
+
+## Lifecycle: the parts that get implemented wrong
+
+The callbacks themselves are well documented; these are the misconceptions that cause bugs:
+
+- **`connectedCallback` can run more than once.** It fires on every insertion, so moving the element re-runs it. Make setup idempotent — don't assume a single first run.
+- **`connectedMoveCallback` skips the disconnect/reconnect pair on a move.** When an element is relocated with `Node.moveBefore()`, this callback fires *instead of* `disconnectedCallback` → `connectedCallback`, so state, focus, and iframe/media playback survive the move. Define it when your setup or teardown is expensive or observably re-runs.
+- **Tear down in `disconnectedCallback`.** Remove global listeners, timers, and observers or you leak; but the element may be re-inserted, so don't treat teardown as permanent.
+- **Call `super()` first in the constructor, and do not depend on the full DOM being present.** Calling `super()` after touching `this` throws a `ReferenceError`. Attributes are usually (but not always) present; long lists of children may not have finished parsing. Use `connectedCallback` for one-shot initialization, `slotchange` to monitor direct children, and `attributeChangedCallback` to monitor attributes. `connectedCallback` may still fire before all children are parsed, so do not ignore subsequent `slotchange` / `attributeChangedCallback` calls.
+- **`attributeChangedCallback` fires only for `observedAttributes`,** and should stay cheap for attributes that don't affect output.
+- **Lifecycle hooks and `observedAttributes` are snapshotted at registration.** `customElements.define()` reads both once; adding a hook or extending `observedAttributes` on the class *after* the call is silently ignored. In particular, `attributeChangedCallback` never fires unless `observedAttributes` was already present at `define()` time.
+
+## Upgrade timing and `:defined`
+
+An element can exist in the DOM *before* its class is registered (in server-rendered HTML, or when the script loads late). Until defined it is an inert `HTMLElement` with none of your behavior; when `customElements.define()` runs, the browser **upgrades** every matching element already in the document, running its constructor and `connectedCallback` then.
+
+Two consequences models routinely miss:
+
+1. **Attributes and children may already be present** when your constructor/`connectedCallback` runs on upgrade. Read existing attributes in `connectedCallback` to sync initial state, and never assume the element started empty.
+2. **Children may still be missing** even in `connectedCallback` — the HTML parser can yield mid-parse of long child lists, so the callback sometimes runs before every child is attached. See the constructor bullet in *Lifecycle* above for the pattern (`slotchange` + `attributeChangedCallback`).
+
+Hide undefined elements to avoid a flash of unstyled content — but **fail open**, so the content stays reachable if the script never loads. Animate `opacity` with a delay rather than hard-hiding with `visibility: hidden`, so the element reveals itself after a timeout even when it is never upgraded:
+
+```css
+my-element:not(:defined) {
+  opacity: 0;
+  /* Reveal anyway after 2s, so a failed or slow script never hides content for good. */
+  animation: defined-fallback 0.2s 2s forwards;
+}
+@keyframes defined-fallback { to { opacity: 1; } }
+```
+
+Scope these guards to the elements that need them — or to a specific subtree via `:has(:not(:defined))` — rather than the whole `body`. One slow, non-critical widget (a share button, say) should not delay paint for the entire page.
+
+## Attribute ⇄ property reflection
+
+Keep the HTML attribute and the JS property in sync so the element is usable from both markup and script. Attribute values are **always strings**; coerce them.
+
+```javascript
+class MyToggle extends HTMLElement {
+  static observedAttributes = ['label', 'count', 'disabled'];
+
+  // String attribute reflected via getter/setter.
+  get label() { return this.getAttribute('label') ?? ''; }
+  set label(v) {
+    v ? this.setAttribute('label', v) : this.removeAttribute('label');
+  }
+
+  // Numeric attribute: coerce from string on read, serialize on write.
+  get count() { return Number(this.getAttribute('count')) || 0; }
+  set count(v) { this.setAttribute('count', String(v)); }
+
+  // Boolean attribute: present = true, absent = false. Never set it to "false".
+  get disabled() { return this.hasAttribute('disabled'); }
+  set disabled(on) { this.toggleAttribute('disabled', !!on); }
+
+  attributeChangedCallback(name, oldVal, newVal) {
+    if (oldVal !== newVal) this.render();
+  }
+}
+```
+
+### Where the value lives
+
+The example above keeps the **DOM as the source of truth** — each getter reads `getAttribute`. That's the right default for a handful of simple, string-ish attributes: there is only one place the state can live, so it can't desync.
+
+For richer components, keep the **source of truth in a JS field** and reflect *outward* to an attribute only when something else must see it — CSS targeting, or a consumer reading it. Reading a field is far cheaper than parsing and coercing an attribute on every access, and non-string values never round-trip through serialization. This is why libraries like Lit hold state in JS and reflect selectively rather than treating attributes as storage: reflect only what the outside world must observe, not every property.
+
+Pitfalls:
+
+- **`observedAttributes` discipline**: list only attributes whose change must re-render or trigger a side effect. Observing everything adds a callback to every mutation for no benefit.
+- **Reflection loops**: a setter that writes an attribute will re-enter `attributeChangedCallback`. Guard with an `oldVal !== newVal` check, as above.
+- **Style-only state**: for internal state that exists only to drive styling (loading, active, expanded), prefer **custom states** over reflecting a synthetic attribute — see [Custom states](#custom-states) below. Reflect to an attribute only when consumers must be able to set the state from markup.
+
+## Custom states
+
+Custom states are boolean flags an element exposes *about itself* for CSS to target, set through `ElementInternals` and matched with the `:state()` pseudo-class. Use them for internal, runtime UI state — `busy`, `expanded`, `invalid` — instead of reflecting a synthetic attribute: they can't collide with a consumer's attributes, never appear in the DOM, and are read-only from outside (a consumer can *style* `:state()` but can't forge it).
+
+```javascript
+class AsyncButton extends HTMLElement {
+  #internals;
+  #action = async () => {};
+
+  constructor() {
+    super();
+    this.#internals = this.attachInternals();
+  }
+
+  set action(fn) { this.#action = fn; } // host supplies the work to run
+
+  async run() {
+    if (this.#internals.states.has('busy')) return; // guard re-entry
+    this.#internals.states.add('busy');
+    this.#internals.states.delete('success');
+    try {
+      await this.#action();
+      this.#internals.states.add('success');
+    } catch {
+      this.#internals.states.add('error');
+    } finally {
+      this.#internals.states.delete('busy');
+    }
+  }
+}
+```
+
+`CustomStateSet` is a set, so independent states compose (`busy` plus `error`) without inventing a combined `data-status` enum.
+
+**Custom state is runtime-only.** It is not serialized to the DOM, so it does not survive a reload, the element being re-created, or server rendering. If the state must be set declaratively in markup or persist across loads, that is a job for an **attribute** (see [Where the value lives](#where-the-value-lives)) — restore it in `connectedCallback` from your source of truth. Rule of thumb: custom state for what the component derives and owns at runtime and only needs to *style*; an attribute for what must be set from markup or serialized.
+
+For styling these states — both inside the component and from a consumer's stylesheet — see `styling-web-components` (via `npx -y modern-web-guidance@latest retrieve "styling-web-components"`).
+
+## Naming conventions
+
+- True-private state: native `#` fields (`#count`) for hard encapsulation; a `_` prefix only when subclasses must still reach it. Note `#` fields are not inherited — a subclass cannot see a base class's private fields.
+- Symbol-keyed properties are a middle ground: hidden from ordinary enumeration, but reachable by any code holding the symbol (export it, or expose it as a `static` field on the class). Because each symbol is unique, two symbols sharing a description never collide — handy when a subclass or sibling needs controlled access that `#` fields can't provide.
+- Do **not** shadow global attributes (`style`, `class`, `id`, `slot`, `part`, `title`, `lang`, `dir`) with your own properties; doing so breaks their built-in behavior. Note `disabled` is only global on form controls; on other elements you must implement its effect yourself.
+
+When naming a new API surface, follow the platform's own conventions: use lowercase kebab-case with at least one hyphen for custom element tag names (for example `my-toggle`), `lowerCamelCase` for properties and methods, and lowercase attribute names synchronized with their corresponding properties.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/form-associated-custom-elements.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/form-associated-custom-elements.md
new file mode 100644
index 00000000..ae0ab6cf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/form-associated-custom-elements.md
@@ -0,0 +1,73 @@
+# Form-Associated Custom Elements
+
+Do not fall back to a hidden `<input>` to surface a custom control's value to a form. Use **Form-Associated Custom Elements** (FACE): with `formAssociated` and `ElementInternals`, the element submits its own value, participates in validation, and reflects form state natively.
+
+```javascript
+class RatingInput extends HTMLElement {
+  // MANDATORY: opt in. Without this, attachInternals() form APIs are unavailable.
+  static formAssociated = true;
+
+  #internals;
+  #value = '';
+
+  constructor() {
+    super();
+    this.#internals = this.attachInternals();
+    this.attachShadow({ mode: 'open', delegatesFocus: true });
+  }
+
+  connectedCallback() {
+    // Validate initial state once attributes (such as `required`) are present.
+    this.#validate();
+  }
+
+  get value() { return this.#value; }
+  set value(v) {
+    this.#value = v;
+    // Push the value into the owning <form> for submission.
+    this.#internals.setFormValue(v);
+    this.#validate();
+  }
+
+  #validate() {
+    if (this.hasAttribute('required') && !this.#value) {
+      // Mark invalid and supply the native validation message + anchor.
+      this.#internals.setValidity(
+        { valueMissing: true },
+        'Please choose a rating.',
+        this.shadowRoot.querySelector('[tabindex]'),
+      );
+    } else {
+      this.#internals.setValidity({}); // clear
+    }
+  }
+
+  // Optional FACE lifecycle hooks:
+  formResetCallback() { this.value = ''; }
+  formDisabledCallback(disabled) {
+    // Disable internal controls so they leave the tab order and ignore clicks.
+    // Do NOT toggle `disabled` on `this`, or a `<fieldset disabled>` toggle will
+    // leave the host permanently stuck with its own `disabled` attribute.
+    for (const el of this.shadowRoot.querySelectorAll('button')) {
+      el.disabled = disabled;
+    }
+  }
+  formStateRestoreCallback(state) { this.value = state; }
+}
+customElements.define('rating-input', RatingInput);
+```
+
+Key points:
+
+- `static formAssociated = true` is **MANDATORY**; it unlocks the form-related `ElementInternals` methods and the `formXxxCallback` lifecycle.
+- `setFormValue(value)` is what submits, with no hidden input required. Pass a `FormData` for multi-value controls.
+- `setValidity(flags, message, anchor)` integrates with native constraint validation: the form won't submit while invalid, `:invalid`/`:valid` apply, and the anchor element receives focus on report. Call `setValidity({})` to clear. The interaction-aware `:user-valid`/`:user-invalid` pseudo-classes are *not* consistently wired up for form-associated elements across browsers — verify support before relying on them rather than assuming they track user interaction the way they do for native controls.
+- Implement `formResetCallback`, `formDisabledCallback`, and `formStateRestoreCallback` so the element behaves like a native control on reset, `fieldset[disabled]`, and back/forward autofill restore. In `formDisabledCallback(disabled)`, disable internal controls (or remove them from the tab order and ignore input) rather than setting `disabled` on the host — setting the host attribute inside the callback prevents re-enabling when an ancestor `<fieldset>` is re-enabled, and the host already matches `:disabled` automatically.
+- Follow platform conventions for dispatched events and prefer the built-in `input` and `change` events over custom ones. `input` fires when the value changes as a direct result of user action (typing, dragging a slider); `change` fires once per stream of changes, when the user commits (releasing the slider, blurring the field). Construct them with `InputEvent` and `Event` respectively.
+
+## Fallback strategies
+
+Baseline status for Form-associated custom elements: Widely available. It's been Baseline since 2023-03-27.
+Supported by: Chrome 77 (Sep 2019), Edge 79 (Jan 2020), Firefox 98 (Mar 2022), and Safari 16.4 (Mar 2023).
+
+Feature-detect with `static formAssociated` support before relying on it: `'attachInternals' in HTMLElement.prototype && 'setFormValue' in ElementInternals.prototype`. Where it is unavailable, fall back to a visually-hidden native `<input>` synced to the control's value so the form still submits — the one case where the hidden-input pattern is justified.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/html.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/html.md
new file mode 100644
index 00000000..c13fce5e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/html.md
@@ -0,0 +1,409 @@
+# HTML
+
+## Table of Contents
+
+1. Fundamental Semantics and Validation
+2. Content Grouping and Attribution
+3. Resource Prioritization and Performance
+4. Native Overlays: Dialogs and Popovers
+5. Disclosures: Details and Summary
+6. Focus Boundaries and Visibility
+7. HTML APIs and Forms Grouping
+8. Native Media Elements
+9. Dynamic Styles and Interactivity
+
+## 1. Fundamental Semantics and Validation
+
+### Guidelines
+
+- **DO** use the standard HTML5 doctype `<!DOCTYPE html>` to prevent quirky rendering modes. 
+- **DO** set the `lang` attribute on the `<html>` element for screen reader pronunciation and translation tools.
+- **DO** use the `<meta name="viewport">` element with the `content` attribute set to `"width=device-width, initial-scale=1.0"` to ensure page responsiveness.
+- **DO** use a single `<h1>` per page/view representing the main topic. Exceptions can be made for modal dialogs, which can also use a single `<h1>`.
+- **DO** maintain a sequential, non-skipping heading hierarchy (`<h2>` to `<h3>`, but not `<h2>` to `<h4>`).
+- **DO** use semantic landmarks (`<header>`, `<nav>`, `<main>`, `<aside>`, `<footer>`) to create regional navigation for assistive technologies.
+- **DO** use `<search>` to enclose search and filtering mechanisms (eliminates the need for `role="search"`).
+- **DO** use `<button>` for triggered actions (JS, Modals, Forms) and `<a>` strictly for URL navigation. Set `type="button"` for non-submit buttons in forms to prevent unintended submission.
+- **DO** use `<ul>`, `<ol>`, and `<dl>` elements for list content. 
+- **DO** ensure that all interactive elements like links and buttons have accessible names.  
+- **DO** hide purely decorative SVG images from assistive technology using `aria-hidden="true"`. If using a decorative `<img>`, always include an empty `alt` attribute (e.g. `alt=""`). 
+- **DO** ensure that informative SVGs like logos, data visualizations, or icon buttons have a proper accessible name. 
+
+- **DON'T** use generic `<div>` or `<span>` when semantic elements exist, for instance for interactive elements, headings, or independently reusable self-contained content.
+- **DON'T** use boolean attributes with redundant values (e.g., use `disabled`, not `disabled="disabled"`).
+- **DON'T** use generic elements with added ARIA roles or states when native elements with built-in semantics and behavior exist.
+- **DON'T** change the native semantics of elements with ARIA unless it is a critical requirement. 
+- **DON'T** use `role="presentation"` or `aria-hidden="true"` on focusable elements or their parents and ancestors. 
+- **DON'T** disable page zooming capabilities.
+
+### Code Example
+
+```html
+<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Dashboard | Platform</title>
+</head>
+<body>
+  <header>
+    <nav>
+      <ul>
+        <li><a href="#">About</a></li>
+        <li><a href="#">Contact</a></li>
+      </ul>
+    </nav>
+  </header>
+  <main>
+     <h1>Analytics</h1>
+    <search>
+      <form action="/filter" method="GET">
+        <label for="search-input">Scan items:</label>
+        <input type="search" id="search-input" name="q">
+        <button type="submit">Search</button>
+      </form>
+    </search>
+    <article>
+      <h2>First post</h2>
+    </article>
+  </main>
+</body>
+</html>
+```
+
+## 2. Content Grouping and Attribution
+
+### Guidelines
+
+- **DO** use `<blockquote>` for extended quotations from another source, and use the `cite` attribute to provide a machine-readable URL for that source.
+- **DO** use `<figure>` to group self-contained content (images, code snippets, or quotes) that is referenced from the main flow but could be moved to an appendix or sidebar without affecting the document's meaning.
+- **DO** use `<figcaption>` as the first or last child of a `<figure>` to provide a human-readable caption or attribution.
+- **DO** use the `<cite>` element inside a caption or attribution to identify the **title** of a work (e.g., a book or website name), not the author's name.
+- **DO** use the `<code>` element for short fragments of computer code (e.g., variable names, file paths, or inline snippets).
+- **DO** wrap `<code>` inside a `<pre>` element when displaying blocks of code to preserve whitespace and line breaks.
+- **DO** ensure that code blocks are accessible by adding `tabindex="0"` to the `<pre>` element if it becomes scrollable, allowing keyboard users to reach the content.
+
+- **DON'T** use `<blockquote>` for purely visual indentation of non-quoted text.
+- **DON'T** use `<figure>` for every single image; use it only when a caption is required or when the content is a distinct, referenced unit.
+- **DON'T** use `<pre>` without `<code>` for code blocks; `<pre>` alone only preserves formatting but doesn't convey that the content is a computer language.
+
+### Code Example
+
+```html
+<!-- Quote with attribution using Figure -->
+<figure>
+  <blockquote cite="https://html.spec.whatwg.org/">
+    <p>The figure element represents some flow content, optionally with a caption, that is self-contained and is typically referenced as a single unit from the main flow of the document.</p>
+  </blockquote>
+  <figcaption>
+    Definition of the &lt;figure&gt; element from the <cite>HTML Living Standard</cite>
+  </figcaption>
+</figure>
+
+<!-- Image with caption -->
+<figure>
+  <img 
+    src="architecture-diagram.webp" 
+    alt="Diagram showing the flow between Client, API Gateway, and Microservices"
+    width="800"
+    height="450"
+    loading="lazy"
+  >
+  <figcaption>Figure 1: High-level system architecture overview.</figcaption>
+</figure>
+
+<!-- Code block with accessibility and language hint -->
+<figure>
+  <figcaption>Example configuration:</figcaption>
+  <pre tabindex="0"><code class="language-json">
+{
+  "name": "gemini-cli",
+  "version": "1.0.0",
+  "private": true
+}
+  </code></pre>
+</figure>
+
+<!-- Inline code -->
+<p>To initialize the project, run the <code>npm install</code> command.</p>
+```
+
+## 3. Resource Prioritization and Performance
+
+### Guidelines
+
+- **DO** use `fetchpriority="high"` for the Largest Contentful Paint (LCP) element (e.g., hero image) to elevate network priority.
+- **DO** use `<link rel="preload" as="image">` with `fetchpriority="high"` for LCP background images defined in CSS.
+- **DO** apply `loading="lazy"` to off-screen images and iframes to defer bandwidth.
+- **DO** specify `width` and `height` on all `<img>` tags to preserve aspect ratio and prevent Layout Shifts (CLS).
+- **DO** use the `srcset` attribute on `<img>`s for adding multiple versions of the same image at different sizes.
+- **DO** use the `<picture>` element with a fallback `<img>` for more fine-grained image control like switching between image formats, image sizes, and cropping images at different device sizes. 
+
+- **DON'T** apply `loading="lazy"` to above-the-fold or hero images. This delays LCP.
+- **DON'T** overuse `fetchpriority="high"`; prioritization is a zero-sum mechanism. Use `fetchpriority="low"` to demote non-critical trackers or later carousel items.
+
+### Code Example
+
+```html
+<!-- High-priority hero image with responsive sizes -->
+<img 
+  src="hero-large.webp" 
+  srcset="hero-small.webp 480w, hero-medium.webp 800w, hero-large.webp 1200w"
+  sizes="(max-width: 600px) 100vw, (max-width: 1200px) 80vw, 70vw"
+  alt="Main product view" 
+  fetchpriority="high" 
+  width="1200" 
+  height="600"
+>
+
+<!-- Art direction and format switching with <picture> -->
+<picture>
+  <!-- Mobile Art Direction: Different aspect ratio (square) and format (AVIF) -->
+  <source 
+    media="(max-width: 600px)" 
+    srcset="hero-mobile.avif 1x, hero-mobile-2x.avif 2x" 
+    type="image/avif"
+    width="600" 
+    height="600"
+  >
+  <source 
+    media="(max-width: 600px)" 
+    srcset="hero-mobile.webp 1x, hero-mobile-2x.webp 2x"
+    width="600" 
+    height="600"
+  >
+  
+  <!-- Desktop: Modern format for primary layout -->
+  <source srcset="hero-desktop.avif" type="image/avif">
+
+  <!-- Fallback img defines the default aspect ratio (2:1) -->
+  <img 
+    src="hero-desktop.webp" 
+    alt="Platform dashboard overview" 
+    width="1200" 
+    height="600"
+    loading="lazy"
+  >
+</picture>
+
+<!-- Low-priority decorative footer image -->
+<img 
+  src="footer-art.png" 
+  alt="" 
+  loading="lazy" 
+  width="200" 
+  height="100"
+>
+```
+
+## 4. Native Overlays: Dialogs and Popovers
+
+### Guidelines
+
+See `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`) for more info on fallback strategies for using the Popover API in a cross-browser way.
+- **DO** use `<dialog>` for modal overlays (requires JS `.showModal()`) to automatically trap focus, dim backgrounds, and support dismissing via `Esc`. Use the `closedby="any"` attribute to enable native "light-dismiss" (closing on backdrop click) without custom JavaScript.
+- **DO** utilize the Popover API (`popover` attribute) for non-modal UI (menus, tooltips) that do not require focus traps.
+- **DO** use `::backdrop` to style modal backgrounds.
+- **DO** use `<form method="dialog">` to dismiss dialogs without manual JS handlers. Combined button `formmethod="dialog"` yields the button's value to the dialog `.returnValue`.
+
+- **DON'T** use `show()` for modals where keyboard traps are expected (use `showModal()`).
+- **DON'T** call `showModal()` on elements possessing a `popover` attribute (they are mutually exclusive programmatic states). However, `<dialog popover="auto">` is a valid declarative architecture to combine dialog semantics with light-dismiss mechanics.
+
+### Code Example
+
+```html
+<!-- Popover (No JS required for toggle) -->
+<button popovertarget="help-menu">Info</button>
+<div id="help-menu" popover="auto">
+  <p>Standard help text.</p>
+</div>
+
+<!-- Modal Dialog with Form-based closing -->
+<button id="show-dialog">Open dialog</button>
+<dialog id="fav-modal">
+  <!-- method="dialog" closes the dialog natively and sets the returnValue -->
+  <form method="dialog">
+    <p>Confirm action?</p>
+    <button value="cancel">Cancel</button>
+    <button value="confirm">Confirm</button>
+  </form>
+</dialog>
+
+<script>
+  const dialog = document.getElementById("fav-modal");
+  const openModal = document.getElementById("show-dialog");
+  
+  // Show modal dialog
+  openModal.addEventListener('click', () => dialog.showModal());
+  
+  // Listen for the 'close' event to retrieve the user's choice (returnValue)
+  dialog.addEventListener('close', () => {
+    console.log(dialog.returnValue); // "confirm" or "cancel"
+  });
+</script>
+```
+
+### Native UI Overlay & Disclosure Matrix
+
+| Feature | Modality | Focus | Dismiss Mechanism | Use Case |
+| :--- | :--- | :--- | :--- | :--- |
+| **`<dialog>`** | Modal / Non-modal | Automatic trap (Modal) | Esc / Form / `closedby` | Critical Actions, Settings |
+| **`[popover]`** | Non-modal | Standard Tab flow | Light-dismiss (Click outside) | Menus, Tooltips, Toasts |
+| **`<details>`** | Inline Disclosure | Standard Tab flow | Toggle summary | Accordions, FAQs |
+
+**Heuristic Rule**: Use `<dialog>` for interruptions requiring user action, `popover` for transient info, and `<details>` for inline content expansion.
+
+## 5. Disclosures: Details and Summary
+
+### Guidelines
+
+- **DO** use `<details>` and `<summary>` for native accordions or revealable content without JS.
+- **DO** place `<summary>` as the *first* child of `<details>`.
+- If headings must be used within a `<summary>`, consider if the heading is essential for understanding or navigating the document structure. If it is, use a more robust disclosure approach that allows wrapping the disclosure trigger with the heading (e.g. `<h2><button type="button" aria-expanded="false" aria-controls="significant-section-content">Significant section</button></h2>`). This ensures the heading semantics aren’t lost, and the button and its state are announced.
+- **DO** use `details[open]` attribute for styling expanded states.
+- **DO** use `details::details-content` for styling the contents of the `<details>` element.
+- **DO** use the `name` attribute on multiple `<details>` elements to create exclusive accordions (opening one closes others).
+
+- **DON'T** nest other interactive elements (links, buttons) directly inside `<summary>` text as it acts as a button and breaks focus.
+- **DON'T** hide visible triangles via `list-style: none` without providing explicit directional cues (via `::before`/`::after` pseudo-elements).
+- **DON'T** use the `title` attribute to create tooltip effects. 
+
+### Code Example
+
+```html
+<!-- Exclusive Accordion Set -->
+<details name="faq">
+  <summary>Item 1</summary>
+  <p>Contents...</p>
+</details>
+<details name="faq">
+  <summary>Item 2</summary>
+  <p>Contents...</p>
+</details>
+```
+
+## 6. Focus Boundaries and Visibility
+
+### Guidelines
+
+- **DO** use the global `inert` attribute for entire hidden sections (off-screen menus, background while custom modal is open) to remove them from tab flows and accessibility trees.
+- **DO** pair `[inert]` with CSS (`opacity: 0.5`) to visually signify inactivity.
+- **DO** rely on natural DOM order for sequential navigation. 
+
+- **DON'T** use positive `tabindex` values (e.g., `1`, `2`). Use `0` to add element to tab flow, or `-1` for JS program focus.
+- **DON'T** alter focus flow using CSS properties (`flex-flow: row-reverse`, `order`) without aligning the DOM structure.
+- **DON'T** use `node.focus({ preventScroll: true })` without usability validation; it can hide the focused element off-screen.
+
+### Code Example
+
+```html
+<!-- De-tabbing a background app shell while custom drawer is open -->
+<main id="app-shell" inert>
+  <a href="/">Dashboard</a>
+</main>
+<aside id="drawer">
+  <button>Close</button>
+</aside>
+```
+
+```css
+[inert], [inert] * {
+  opacity: 0.5;
+  cursor: default;
+  user-select: none;
+}
+```
+
+## 7. HTML APIs and Forms Grouping
+
+### Guidelines
+
+See `forms` (via `npx -y modern-web-guidance@latest retrieve "forms"`) for more details on creating modern web forms.
+
+- **DO** utilize the `form="form-id"` attribute to decouple inputs from the physical `<form>` tree.
+- **DO** use `<datalist>` coupled with `<input list="id">` for lightweight auto-suggestions (note: visually unstylable and has screen-reader quirks). 
+- **DON'T** use `autocomplete="off"` on credential, address, payment, or contact fields. Browsers and password managers ignore it there by design. Use a specific token instead (`autocomplete="email"`, `"street-address"`, `"cc-number"`, etc.).
+- **DON'T** use `autocomplete="off"` unless handling highly sensitive tracking tokens (violates standard password manager overrides). Use standard inputs `type="email"`, `type="tel"`.
+- **DO** distinguish `autocomplete="current-password"` (sign-in) from `autocomplete="new-password"` (registration / password change) so password managers offer the right action.                                                    
+- **DO** match `autocomplete` tokens with appropriate `inputmode` and `type` (`type="email"` + `inputmode="email"` + `autocomplete="email"`). They control different things — keyboard, validation, and autofill respectively — and reinforce each other.
+
+### Code Example
+
+```html
+<form>
+  <fieldset>
+    <legend>Address Information</legend>
+    <label for="city">City:</label>
+    <input type="text" id="city" list="cities" autocomplete="address-level2">
+    <datalist id="cities">
+      <option value="New York">
+      <option value="London">
+    </datalist>
+  </fieldset>
+</form>
+```
+
+## 8. Native Media Elements
+
+### Guidelines
+
+- **DO** set `width` and `height` to prevent layout shifts (CLS) on `<video>` elements.
+- **DO** provide a `poster` image fallback for videos.
+- **DO** include subtitles and captions with `<track>`.
+- **DO** ensure background videos are `muted`, provide users with full control over playback, and use `role="none"` or `aria-hidden="true"`. The `controls` attribute must also be omitted to make sure the video is not focusable.  
+
+- **DON'T** rely on JS for basic video controls if native `controls` attribute is sufficient.
+- **DON'T** apply `role="none"` or `aria-hidden="true"` to focusable elements (such as embedded interactive `<iframe>` components). Hiding elements from the assistive technology tree while leaving them accessible to sequential keyboard navigation violates core accessibility heuristics. The background video exception holds solely because omitting the `controls` attribute renders the `<video>` element fully non-focusable.
+
+### Code Example
+
+```html
+<video 
+  controls 
+  width="800" 
+  height="450" 
+  poster="poster.webp"
+>
+  <source src="intro.webm" type="video/webm">
+  <source src="intro.mp4" type="video/mp4">
+  <track src="caps.vtt" kind="captions" srclang="en" label="English">
+</video>
+```
+
+## 9. Dynamic Styles and Interactivity
+
+### Guidelines
+- **DO** use the `style` attribute to pass state to CSS via **Custom Properties**. This keeps visual logic in your stylesheet while JavaScript provides the raw data.
+
+- **DON'T** use inline styles for static design (colors, padding, margins) that belong in a stylesheet.
+- **DON'T** use inline event handlers (e.g., `onclick`). Trigger actions using `addEventListener()`.
+
+### Code Example
+
+```html
+<body>
+  <!-- Progress with style-driven color data -->
+  <label for="upload-progress">Upload status:</label>
+  <progress id="upload-progress" class="loading-bar" value="0" max="100" style="--brand-hue: 200;"></progress>
+
+  <script>
+    const updateProgress = (percent, hue) => {
+      const bar = document.querySelector('.loading-bar');
+      bar.value = percent;
+      
+      // Update dynamic style variable 
+      if (hue) bar.style.setProperty('--brand-hue', hue);
+    };
+
+    // Example: Move to 85% and shift color to green (120)
+    setTimeout(() => updateProgress(85, 120), 1000);
+  </script>
+</body>
+```
+```css
+.loading-bar {
+  accent-color: hsl(var(--brand-hue, 200) 80% 50%);
+  transition: accent-color 0.3s ease;
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/prerendering-custom-elements.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/prerendering-custom-elements.md
new file mode 100644
index 00000000..dc5355d2
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/prerendering-custom-elements.md
@@ -0,0 +1,64 @@
+# Pre-rendering custom elements
+
+Pre-rendering means shipping a custom element's markup — including its shadow tree — from the server, so the component is styled and structured *before* any JavaScript runs. The main platform primitive for this is **Declarative Shadow DOM (DSD)**: the parser attaches the shadow root from HTML alone, and the element is later upgraded ("hydrated") by its class if one is registered. Use this pattern for server-side rendering, streaming, and avoiding a flash of unstyled content (FOUC).
+
+## Authoring a declarative shadow root
+
+Nest a `<template>` with the `shadowrootmode` attribute as the first child of the host. The parser attaches its content as a shadow root and removes the template; no script needed.
+
+```html
+<my-card>
+  <template shadowrootmode="open">
+    <style>
+      .card { border: 1px solid; border-radius: 8px; padding: 1rem; }
+    </style>
+    <div class="card">
+      <slot name="header"></slot>
+      <div class="body"><slot></slot></div>
+    </div>
+  </template>
+
+  <!-- Light DOM children are projected into the slots above. -->
+  <h2 slot="header">Server-rendered title</h2>
+  <p>Visible and styled before JS loads.</p>
+</my-card>
+```
+
+## Hydration timing
+
+When the matching class is registered, the browser upgrades the host. Because the shadow root **already exists**, the constructor must not blindly create a second one:
+
+```javascript
+class MyCard extends HTMLElement {
+  constructor() {
+    super();
+    // Reuse the server-rendered shadow root if present; only create one if absent.
+    if (!this.shadowRoot) {
+      this.attachShadow({ mode: 'open' });
+      this.shadowRoot.append(template.content.cloneNode(true));
+    }
+    // Hydrate in place: attach listeners once against existing markup (not unguarded
+    // in connectedCallback, which re-runs if the element moves in the DOM), and do
+    // NOT re-render; that would discard the server's DOM and flash.
+    this.shadowRoot.getElementById('toggle')
+      ?.addEventListener('click', () => this.toggleAttribute('open'));
+  }
+}
+```
+
+Set `shadowrootmode="open"` (not `closed`) for almost all cases, so scripts and tools can reach `this.shadowRoot` to hydrate. To serialize an existing shadow root back to HTML on the server or in tests, use `getHTML({ serializableShadowRoots: true })` and attach the root with `serializable: true`.
+
+## Avoiding FOUC
+
+DSD renders correctly on first paint only if styles ship inside the declarative template. To preserve that:
+
+- Put component CSS **inside** the `<template shadowrootmode>` (a `<style>` tag or a `<link>`), not in a separate script-loaded sheet.
+- Pair with `my-card:not(:defined) { … }` only for styles that must wait for JS — typically page-level guard rules like a fade-out on client-rendered instances that miss the SSR pass. These live in the light-DOM (page) stylesheet, since the shadow root doesn't yet exist there and `:host` selectors don't apply from outside. Structural styles inside the DSD template need no such guard.
+- Do not re-render the shadow tree on hydration. Treat the server markup as authoritative and attach behavior to it.
+
+## Fallback strategies
+
+Baseline status for Declarative shadow DOM: Widely available. It's been Baseline since 2024-02-20.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 123 (Feb 2024), and Safari 16.4 (Mar 2023).
+
+In engines that don't parse `shadowrootmode`, the template is inert and its content is not attached as a shadow root. Detect this (`Object.hasOwn(HTMLTemplateElement.prototype, 'shadowRootMode')`) and, if absent, attach the shadow root imperatively from the same markup during upgrade so the component still renders.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/shadow-dom.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/shadow-dom.md
new file mode 100644
index 00000000..5fd05d4e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/shadow-dom.md
@@ -0,0 +1,79 @@
+# Shadow DOM, Templates & Slots
+
+A shadow root is an encapsulated DOM subtree attached to a host element: styles inside it do not leak out, and page styles do not leak in (except inherited properties). Templates construct the tree efficiently; slots project Light DOM content into it.
+
+## Attaching a shadow root
+
+```javascript
+this.attachShadow({ mode: 'open', delegatesFocus: true });
+```
+
+`delegatesFocus: true` makes focusing the host move focus to the first focusable element inside the shadow tree, routes `:focus` styling to the host, and on form-associated custom elements (`static formAssociated = true`) forwards `<label>` clicks to the inner control. Set it whenever the component wraps focusable controls. Use `mode: 'open'` in almost all cases so dev tools, page scripts, and server hydration can reach `element.shadowRoot` (see `web-components` (via `npx -y modern-web-guidance@latest retrieve "web-components"`)).
+
+## Templates: construct the tree efficiently
+
+Define a `<template>` **once** (module scope or a static field) and clone it per instance. Cloning a parsed fragment is far faster than re-parsing an `innerHTML` string on every construction.
+
+```javascript
+const template = document.createElement('template');
+template.innerHTML = `
+  <div class="card">
+    <slot name="header"></slot>
+    <div class="body"><slot></slot></div>
+    <slot name="footer"></slot>
+  </div>
+`;
+
+class MyCard extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    // MANDATORY: deep-clone the template content so each instance gets its own nodes.
+    this.shadowRoot.append(template.content.cloneNode(true));
+  }
+}
+customElements.define('my-card', MyCard);
+```
+
+Keep templates lean. Deeply nested "div soup" and many levels of nested shadow roots both add measurable style-resolution and layout cost, a major performance hit at scale. Prefer a flat structure and semantic elements.
+
+## Slots: the parts that surprise people
+
+Default vs. named slots work as documented; these are the behaviors that bite:
+
+- **Whitespace counts.** Text nodes between elements (including pure whitespace) are assigned to the default slot, so a default slot is rarely truly "empty."
+- **DOM order is preserved, not slot order.** Projected nodes keep their original Light DOM order for `:first-child`/`:last-child` purposes, regardless of which slot they fill. A `::slotted(*:first-child)` rule targets the first *DOM* child, not the first child of that slot, so it often will not match what you expect.
+- **`slotchange` is the upgrade-timing signal.** It fires when assigned nodes change (including initial assignment) and is the reliable way to know Light DOM children have arrived after an upgrade, when they may not have existed during `connectedCallback`.
+
+```javascript
+this.shadowRoot.querySelector('slot[name="header"]')
+  .addEventListener('slotchange', (e) => {
+    const nodes = e.target.assignedElements();
+    this.toggleAttribute('has-header', nodes.length > 0);
+  });
+```
+
+## Loading stylesheets into a shadow root
+
+| Method | Pros | Cons |
+| :--- | :--- | :--- |
+| `<style>` in the template | Simple, fully encapsulated, works without JS. | Duplicated per instance; bloats the DOM at scale. |
+| `<link rel="stylesheet">` | Cacheable external file. | Extra request; risks a flash of unstyled content. |
+| `adoptedStyleSheets` | One shared `CSSStyleSheet` across all instances; fastest at scale. | Requires JS; constructed sheets don't support `@import`. |
+
+For many instances of one component, prefer a shared constructed stylesheet:
+
+```javascript
+const sheet = new CSSStyleSheet();
+sheet.replaceSync(`:host { display: block; }`);
+
+class MyCard extends HTMLElement {
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    // The same sheet object is reused by every instance; no per-instance parse.
+    this.shadowRoot.adoptedStyleSheets = [sheet];
+  }
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/styling-web-components.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/styling-web-components.md
new file mode 100644
index 00000000..93fb7dc6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/styling-web-components.md
@@ -0,0 +1,130 @@
+# Styling Web Components
+
+Shadow DOM is a style boundary: page rules don't reach in and component rules don't leak out, except **inherited** properties (including custom properties). Cross it deliberately through the channels below.
+
+## `:host`, `:host()`, `:host-context()`
+
+```css
+/* The component's own host element, styled from inside its shadow tree. */
+:host { display: block; }
+
+/* Only when the host matches a selector (e.g. a reflected state attribute). */
+:host([disabled]) { opacity: 0.5; pointer-events: none; }
+
+/* Based on an ancestor in the Light DOM; useful for theming. */
+:host-context([theme="dark"]) { background: #111; color: #eee; }
+```
+
+**Avoid `:host-context()`.** It reaches *outside* the boundary to test ancestors, but Firefox and Safari have declined to ship it and the CSSWG is leaning toward not developing it further — treat it as a Chromium-only dead end, not a forward-looking option. Theme through an inherited CSS custom property instead (below): the consumer sets the property on an ancestor and the component reads it across the boundary, which works everywhere and keeps both sides decoupled.
+
+## Inherited properties and custom properties cross the boundary
+
+Inherited CSS properties (`color`, `font-family`, `line-height`, and CSS custom properties) **do** pass through the shadow boundary. This makes custom properties the primary theming API: expose them with sensible fallbacks.
+
+```css
+:host {
+  /* Consumers override --card-bg from outside; the fallback keeps it usable. */
+  background: var(--card-bg, white);
+  color: var(--card-fg, black);
+}
+```
+
+A custom property *defined* on `:host` can only be overridden by rules targeting the host element specifically. To let it inherit and be overridable from anywhere up the tree, leave the public property unset on `:host` and rely on the fallback in each `var()`; do not seed the public property on `:host`.
+
+To keep the fallback declared once rather than repeated at every `var()`, define a private "shadow" property on `:host` that reads the public one, and reference the private property internally:
+
+```css
+:host {
+  --_card-bg: var(--card-bg, white);
+  --_card-fg: var(--card-fg, black);
+}
+.card { background: var(--_card-bg); color: var(--_card-fg); }
+```
+
+Consumers still override `--card-bg` from outside; the leading underscore signals the alias is internal, and the fallback lives in exactly one place.
+
+## `::slotted()`: styling projected Light DOM
+
+`::slotted(selector)` targets the **top-level** nodes assigned to a slot. It cannot reach their descendants, and it loses to any Light DOM rule (the consumer owns their own content), so use it for light touch-ups, not control. `::slotted(...) !important` can beat consumer rules, but doing so overrides styling the consumer is entitled to own — reserve it for structural fixes, not aesthetic overrides.
+
+```css
+/* Matches a slotted <p>, but NOT a <p> nested inside a slotted <div>. */
+::slotted(p) { margin: 0; }
+```
+
+## `::part()` and `exportparts`: expose internals for theming
+
+Mark an internal element with `part="name"` to let consumers style it with any property, without learning your internal structure.
+
+```html
+<!-- inside the shadow template -->
+<button part="submit">Submit</button>
+```
+
+```css
+/* consumer stylesheet */
+my-card::part(submit) { background: navy; color: white; }
+```
+
+Expose a few **high-level** parts (button, input, label), not every `<div>`; broad part surfaces become a brittle API. To re-expose a nested component's parts upward through your own component, forward them with `exportparts`:
+
+```html
+<inner-widget exportparts="submit: card-submit"></inner-widget>
+```
+
+Choose between the two channels deliberately: **custom properties** for a constrained, design-system-safe set of values; **parts** for unrestricted styling of a specific element.
+
+## Forwarding styles to a wrapped native element
+
+When a custom element wraps a native control (`<my-button>` around a real `<button>`), three things routinely trip people up:
+
+- **Form controls don't inherit typography.** `color` and custom properties cross the boundary, but `<button>`, `<input>`, and `<select>` take `font` and friends from the UA stylesheet, which does *not* inherit. The wrapped control therefore renders in the platform font, not the page font, until you set `font: inherit` (and usually `color: inherit`) on it inside the shadow tree. This is the single most common miss.
+- **`:host` styles don't reach the inner element.** Setting `background`/`border`/`padding` on `:host` styles the host box, not the control inside it. Forward deliberately: expose the control as a `::part` for open-ended styling, or pipe a fixed set of values through custom properties — a `:host` rule does not cascade into the wrapped element.
+- **`display: contents` + `all: inherit` is a real tradeoff, not a shortcut.** Collapsing the host with `display: contents` and resetting the inner control with `all: inherit` is currently the only generic way to pass arbitrary styles through to a wrapped native element without consumers learning per-component parts or custom properties — and removing the host's own box is usually *the point* of the pattern (composition compensating for a missing built-in inheritance). Two real caveats: `all: inherit` wipes UA defaults, so scope to specific properties or use `revert` when you want defaults back; and the concrete blocker — `getBoundingClientRect()` and `getClientRects()` return zero for `display: contents` elements, so anchor positioning against the host is broken. Reach for `::part` or custom properties when those tradeoffs don't fit.
+
+## `:state()`: style the component's own states
+
+A custom element can expose internal boolean states through `ElementInternals` via `this.#internals.states.add('busy')` and `.delete('busy')` (see `custom-elements` (via `npx -y modern-web-guidance@latest retrieve "custom-elements"`) for lifecycle usage), and those states become a styling channel across the boundary — like `::part` and custom properties, but for *state* rather than structure or values. Match them inside the shadow tree with `:host(:state(name))`, and from a consumer's stylesheet with `tag-name:state(name)`:
+
+```css
+/* Inside the component's shadow tree. */
+:host(:state(busy)) button { opacity: 0.6; pointer-events: none; }
+
+/* From the consumer's stylesheet — a read-only public hook. */
+favorite-button:state(favorited) { filter: drop-shadow(0 0 4px crimson); }
+```
+
+Unlike a reflected attribute, a custom state is **read-only to the outside**: consumers can style it but cannot set or forge it, so the component stays the sole writer. Prefer it over a `data-*` attribute whenever the state is owned by the component and only needs to be styled.
+
+## `@layer` and container queries inside components
+
+- **Cascade layers** (`@layer`) work inside a shadow root and are scoped to it; a layer name in the shadow tree is independent of a same-named layer in the page. Use them to order your own component styles (e.g. `@layer base, theme;`) so consumer overrides via custom properties and `::part` still win predictably.
+- **Container queries** are the right tool for responsive components: a component should respond to the space it's given, not the viewport. Declare the host or a wrapper as a container (giving `:host` a layout box such as `display: block`, since custom elements default to `display: inline` and size containment does not apply to `inline` or `contents` elements) and query it, so the same component adapts in a sidebar or a full-width region.
+
+```css
+:host {
+  display: block; /* Required: size containment does not apply to default display: inline */
+  container-type: inline-size;
+}
+
+@container (min-width: 30rem) {
+  .card { grid-template-columns: 1fr 2fr; }
+}
+```
+
+## Fallback strategies
+
+Baseline status for Shadow parts: Widely available. It's been Baseline since 2020-07-28.
+Supported by: Chrome 73 (Mar 2019), Edge 79 (Jan 2020), Firefox 72 (Jan 2020), Safari 13.1 (Mar 2020), and Safari iOS 13.4 (Mar 2020).
+
+Baseline status for Cascade layers: Widely available. It's been Baseline since 2022-03-14.
+Supported by: Chrome 99 (Mar 2022), Edge 99 (Mar 2022), Firefox 97 (Feb 2022), and Safari 15.4 (Mar 2022).
+
+Baseline status for Container queries (size): Widely available. It's been Baseline since 2023-02-14.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 110 (Feb 2023), and Safari 16 (Sep 2022).
+
+Browser support for :host-context(): Limited availability.
+Supported by: Chrome 54 (Oct 2016) and Edge 79 (Jan 2020).
+Unsupported in: Firefox and Safari.
+
+`::part`, cascade layers, and container queries are broadly available; theme primarily through inherited custom properties, which work even where these don't. As noted above, do **not** rely on `:host-context()` — it is effectively Chromium-only and not a forward-looking option.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/web-components.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/web-components.md
new file mode 100644
index 00000000..39319095
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/html/web-components.md
@@ -0,0 +1,50 @@
+# Web Components Orientation
+
+Web Components are Custom Elements, Shadow DOM, and HTML Templates: the platform primitives for reusable, framework-agnostic components whose markup and styles are encapsulated from the document. Use them for design systems, embeddable widgets, and self-contained UI.
+
+The rules below are cross-cutting. Retrieve the specific guide for the task at hand; each restates the context it needs and documents the APIs and pitfalls unique to it.
+
+## Decide whether you even need a custom element
+
+Reach for a custom element only when you need encapsulated behavior, lifecycle, or a reusable JS-backed API on a tag. Do **not** build one when:
+
+- A plain HTML element with CSS would do. A styled `<button>` or `<details>` is more accessible and cheaper than a re-implementation.
+- The thing is purely presentational with no behavior. A class on a native element is more performant, and scopable with `@layer` or `@scope`.
+- You only need style scoping on the server with no interactivity; a scoped stylesheet or Declarative Shadow DOM (without an upgrade) may be enough.
+
+Rebuilding native semantics (a custom `<my-button>` that re-creates focus, activation, and ARIA) is the most common misuse: you inherit the platform's accessibility for free only if you reuse the native element. When a `<my-button>`-style wrapper *is* warranted — usually for shared styling hooks, extra markup, or behavior a native element can't express — wrap the real `<button>` rather than re-implementing it (see `styling-web-components` (via `npx -y modern-web-guidance@latest retrieve "styling-web-components"`) for forwarding styles to an internal native element).
+
+The test is whether you need **encapsulated state, a scriptable API, or behavior the native element can't express** — not merely a different look. A like/favorite toggle qualifies: it carries latched domain state, exposes that state as a styling hook for the surrounding page, and dispatches its own `change` event — none of which a styled `<button>` gives you. A button that only changes color when pressed does not: reach for `<button>` + CSS. When you do build it, model its state with a custom state or attribute as appropriate (see `custom-elements` (via `npx -y modern-web-guidance@latest retrieve "custom-elements"`)).
+
+## Match the tool to the codebase
+
+Whether something *should* be a custom element depends on what the project already uses. Agents tend to over-abstract and reach for a new element too eagerly — when in doubt, the lighter option (native element, CSS, a server template) is usually right, and you can promote to a custom element later if reuse or behavior actually demands it. Heuristics, in rough priority:
+
+- **The codebase already has a component model (React, Vue, Svelte, …).** Default to that framework's component for in-app UI. Reach for a custom element only when the thing must escape or outlive the framework: a design-system primitive shared across apps or frameworks, a widget dropped into markup the framework doesn't control, or output that must work as plain HTML (email, CMS, SSR fragments). Don't stand up a parallel component system for ordinary in-app views.
+- **No tooling, mostly static markup.** Prefer plain HTML + CSS, or a server template/partial. A custom element earns its keep only where you genuinely need behavior, lifecycle, or a JS-backed API on the tag — not merely to share markup, which a server include or `<template>` does without shipping any JS.
+- **Static site generator with islands of interactivity.** Render the markup statically; reserve the custom element for the interactive part. For "lots of markup, a little interactivity," keep the markup in Light DOM (or Declarative Shadow DOM) and let a small custom element progressively enhance it, rather than re-rendering everything from JS.
+- **You could push a built-in element further instead.** Taking a native element as far as it goes (CSS, a few listeners, the occasional pseudo-element) is usually preferable to a custom element, because you keep the platform's accessibility and behavior for free. Cross over to a custom element when the workarounds stop being maintainable — when you'd be fighting the element's built-in behavior, or the authoring experience becomes worse than a clean component API would be. Needing a little JS on a built-in element is not, by itself, a reason to replace it.
+
+## Cross-cutting rules
+
+These hold across every guide below:
+
+- **MANDATORY**: the tag name must be kebab-case with at least one hyphen (e.g. `my-element`). This is what distinguishes custom elements from current and future built-ins.
+- **MANDATORY**: call `super()` first in the constructor, before touching `this`; calling it after any statement that reads or writes `this` throws.
+- **MANDATORY**: use semantic elements (`<button>`, `<nav>`, `<ul>`) inside shadow templates. Most accessibility failures in shadow trees come from non-semantic markup; a slot does not change the role of what it projects.
+- **MANDATORY**: ARIA `id` references (`aria-labelledby`, `aria-describedby`, `aria-controls`) cannot cross a shadow boundary; the referencing element and the `id` it points to must live in the same tree.
+- Prefer `attachShadow({ mode: 'open' })` so dev tools, page scripts, and server hydration can reach `element.shadowRoot`. Use `'closed'` only when you must hide internal structure from page scripts.
+- Avoid *customized built-in elements* (`extends HTMLButtonElement` with `is="…"`); Safari has permanently declined to ship them.
+
+## Use-case guide matrix
+
+Identify the task and retrieve its guide:
+
+| If you need to… | Retrieve |
+| :--- | :--- |
+| Define a new semantic tag with behavior and lifecycle | `custom-elements` (via `npx -y modern-web-guidance@latest retrieve "custom-elements"`) |
+| Scope styles and markup to a component, and project consumer content into it | `shadow-dom` (via `npx -y modern-web-guidance@latest retrieve "shadow-dom"`) |
+| Render a component's shadow tree on the server (SSR) without a flash of unstyled content | `prerendering-custom-elements` (via `npx -y modern-web-guidance@latest retrieve "prerendering-custom-elements"`) |
+| Style across the shadow boundary (theming, `::part`, custom properties) | `styling-web-components` (via `npx -y modern-web-guidance@latest retrieve "styling-web-components"`) |
+| Submit a custom control's value to a surrounding `<form>` | `form-associated-custom-elements` (via `npx -y modern-web-guidance@latest retrieve "form-associated-custom-elements"`) |
+| Make a custom element accessible (roles, focus, ARIA across shadow roots) | `accessible-web-components` (via `npx -y modern-web-guidance@latest retrieve "accessible-web-components"`) |
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/calculate-event-differentials.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/calculate-event-differentials.md
new file mode 100644
index 00000000..f40a7c39
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/calculate-event-differentials.md
@@ -0,0 +1,117 @@
+# Calculating Event Differentials and Formatting Durations with Temporal
+
+Calculating the time elapsed or remaining between events (such as trial expirations, subscription countdowns, or SLA windows) and presenting those spans in a localized, human-readable format has historically required manual math or external libraries. The legacy `Date` object only tracks epoch milliseconds, making calendar-month arithmetic, Daylight Saving Time (DST) transitions, and unit balancing error-prone.
+
+The `Temporal` API pairs `Temporal.ZonedDateTime` with `Temporal.Duration` and `Intl.DurationFormat` to provide DST-safe time differentials, configurable unit balancing, calendar-aware duration comparisons, and localized formatting.
+
+## How to Implement
+
+1. **Obtain `Temporal.ZonedDateTime` endpoints**: Use `Temporal.Now.zonedDateTimeISO()` for the current time in the system time zone, or pass an explicit IANA time zone string—`Temporal.Now.zonedDateTimeISO(timeZone)`—when the target event's time zone differs from the user's system default.
+2. **Calculate differentials with `.since()` and `.until()`**:
+   - Use `now.since(start, options)` to compute time elapsed since a past event.
+   - Use `now.until(end, options)` to compute time remaining until a future event.
+   - Pass `largestUnit` (e.g., `'year'`, `'month'`, `'day'`, `'hour'`) and `smallestUnit` (e.g., `'minute'`) to balance and round the resulting `Temporal.Duration`.
+3. **Balance or compare standalone `Temporal.Duration` objects**:
+   - Create standalone durations with `Temporal.Duration.from({ minutes: 90 })` and rebalance units with `duration.round({ largestUnit: 'hour' })` (supplying `relativeTo` when balancing across calendar months, years, or DST transitions).
+   - Compare two durations with `Temporal.Duration.compare(d1, d2, { relativeTo })`—passing a `PlainDate` or `ZonedDateTime` as `relativeTo` is required whenever either duration contains calendar units (`years`, `months`, `weeks`) or crosses DST boundaries.
+4. **Format for humans vs. machines**:
+   - Use `duration.toLocaleString(locale, options)` (which delegates to `Intl.DurationFormat`) for localized user-facing text.
+   - Use `duration.toString()` only for machine-readable ISO 8601 duration strings (such as `P1M2DT4H`).
+
+### Example: Trial Expiration Differential and Localized Formatting
+
+```javascript
+// 1. Get the current time in an explicit target IANA time zone (or omit the
+// argument to use the system's current time zone).
+const tz = 'America/New_York';
+const now = Temporal.Now.zonedDateTimeISO(tz);
+
+// 2. Combine separate date and time strings directly.
+// Do not build an ISO string with template literals; chain Temporal methods instead.
+const startDateStr = '2025-01-01';
+const startTimeStr = '12:00:00';
+const endDateStr = '2025-01-31';
+const endTimeStr = '12:00:00';
+
+const start = Temporal.PlainDate.from(startDateStr).toPlainDateTime(startTimeStr).toZonedDateTime(tz);
+const end = Temporal.PlainDate.from(endDateStr).toPlainDateTime(endTimeStr).toZonedDateTime(tz);
+
+// 3. Calculate differences using .since() and .until()
+// ZonedDateTime differences default to largestUnit: 'hour' (days are not a fixed
+// length across DST, so Temporal won't balance into days unless asked). Pass
+// largestUnit: 'day' or a calendar unit ('week', 'month', 'year') when you want a
+// human-scale breakdown instead of e.g. PT720H. smallestUnit rounds away
+// seconds and sub-second noise so the formatted string stays readable.
+const timeActive = now.since(start, { largestUnit: 'year', smallestUnit: 'minute' });
+const timeRemaining = now.until(end, { largestUnit: 'year', smallestUnit: 'minute' });
+
+// 4. Format durations for display with .toLocaleString() (Intl.DurationFormat)
+// instead of manually concatenating unit numbers and suffixes. 'en-US' is used
+// here for deterministic output; pass undefined to use the user's locale.
+console.log(`Active: ${timeActive.toLocaleString('en-US', { style: 'narrow' })}`);
+console.log(`Remaining: ${timeRemaining.toLocaleString('en-US', { style: 'long' })}`);
+
+// Use .toString() for ISO 8601 serialization (e.g., API payloads or <time datetime="...">)
+console.log(`ISO 8601: ${timeRemaining.toString()}`);
+
+// 5. Check status via .sign, and compare durations with Temporal.Duration.compare()
+const isExpired = timeRemaining.sign < 0;
+// Pass relativeTo when comparing durations that may include calendar months/years or DST shifts
+const isPastHalfway = Temporal.Duration.compare(timeActive, timeRemaining, { relativeTo: now }) > 0;
+```
+
+### Example: Balancing Standalone Durations (`round` and `Intl.DurationFormat`)
+
+```javascript
+// Convert a raw unit count (e.g., 90 minutes) into a balanced breakdown (1 hour, 30 minutes)
+const rawDuration = Temporal.Duration.from({ minutes: 90 });
+const balanced = rawDuration.round({ largestUnit: 'hour' });
+
+// Format via duration.toLocaleString() or directly with Intl.DurationFormat
+const formatter = new Intl.DurationFormat('en-US', { style: 'long' });
+console.log(formatter.format(balanced)); // "1 hour, 30 minutes"
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal.ZonedDateTime` for calculations involving real-world events that occur in specific time zones (like subscription renewals or event countdowns), and pass an explicit `timeZone` to `Temporal.Now.zonedDateTimeISO(timeZone)` when calculating against a zone other than the system default.
+- **DO** combine separate date and time strings with Temporal methods, e.g. `Temporal.PlainDate.from(dateStr).toPlainDateTime(timeStr).toZonedDateTime(tz)` or `Temporal.PlainDate.from(dateStr).toZonedDateTime({ timeZone: tz, plainTime: timeStr })`, instead of interpolating an ISO string like `` `${dateStr}T${timeStr}` ``.
+- **DO** pass `largestUnit` (e.g. `'day'`, `'month'`, `'year'`) in `.since()`, `.until()`, or `.round()` when you want durations balanced beyond hours; `ZonedDateTime` difference methods default to `'hour'`.
+- **DO** use `Temporal.Duration.compare(d1, d2, { relativeTo })` when comparing two durations, providing a `relativeTo` anchor whenever either duration involves calendar units (`months`, `years`) or time-zone-aware days.
+- **DO** format durations for user display using `duration.toLocaleString()` or `new Intl.DurationFormat(locale, { style })` (`'long'`, `'short'`, `'narrow'`, or `'digital'`) instead of manually interpolating `${duration.years}y ${duration.months}m...`.
+- **DO** use `duration.toString()` for machine-readable ISO 8601 duration strings (e.g., `PT1H30M`), never as user-facing copy.
+- **DO** render a `PlainTime` as `HH:MM` (e.g., for `<input type="time">`) using `.toPlainTime().toString({ smallestUnit: 'minute' })` rather than string `.slice(0, 5)`.
+- **DO NOT** modify instances directly; `Temporal` objects are **immutable**. Operations like `.add()`, `.subtract()`, `.round()`, or `.with()` return a *new* instance.
+- **DO NOT** fall back to `Date` / `.getTime()` arithmetic for the differential itself; `Date` has no time-zone-aware calendar math and only millisecond precision.
+- **DO** use the native `.sign` property of the computed `Temporal.Duration` (or `Temporal.ZonedDateTime.compare()`) to check if a duration represents a past/expired time point (`sign < 0`) or a future pending start.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Browser support for Temporal: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and dynamically load `temporal-polyfill` (~15 KB min+gz).
+
+Note that importing `temporal-polyfill` does not automatically assign the `Temporal` object to the global scope. Assign it explicitly if your code relies on `globalThis.Temporal`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import('https://esm.sh/temporal-polyfill');
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+  }
+  initializeApp();
+})();
+```
+
+### Intl.DurationFormat
+
+Baseline status for Intl.DurationFormat: Newly available. It's been Baseline since 2025-03-04.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 136 (Mar 2025), and Safari 16.4 (Mar 2023).
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/capture-location-agnostic-data.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/capture-location-agnostic-data.md
new file mode 100644
index 00000000..98cb37c9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/capture-location-agnostic-data.md
@@ -0,0 +1,149 @@
+# Capturing Location-Agnostic Data and Partial Dates with Temporal
+
+Recording chronological data that should remain identical regardless of the viewer's location—such as birthdates, daily alarms, credit card expirations, or monthly billing cycles—has historically been error-prone with the legacy `Date` object. Because a `Date` always represents a specific instant in time and is displayed using the viewer's local time zone, saving a date like `"1990-01-01"` can result in users west of UTC seeing `"1989-12-31"`, while modeling partial dates (like a month-only card expiry) forces arbitrary placeholder days that cause overflow bugs.
+
+The `Temporal` API provides a family of location-agnostic **"Plain" types** that carry no time zone offset and represent calendar dates and wall-clock times exactly as read off a calendar or clock:
+
+| Type | What It Models | Typical Use Cases |
+|---|---|---|
+| `Temporal.PlainDate` | Full calendar date (`year`, `month`, `day`) | Birthdates, event dates, subscription billing dates |
+| `Temporal.PlainTime` | Wall-clock time (`hour`, `minute`, `second`, ...) | Daily alarms (9:00 AM wherever the user is), store hours |
+| `Temporal.PlainDateTime` | Calendar date + wall-clock time without a time zone | Floating local schedules, combining a `PlainDate` and `PlainTime` before attaching a zone |
+| `Temporal.PlainMonthDay` | Month and day without a year | Recurring annual birthdays, anniversaries, fixed holidays |
+| `Temporal.PlainYearMonth` | Year and month without a day | Credit card expirations (`2027-12`), monthly billing periods |
+
+## How to Implement
+
+1. **Choose the narrowest `Temporal.Plain*` type that matches your data**:
+   - Use `Temporal.PlainDate.from()` for full calendar dates and `Temporal.PlainTime.from()` for wall-clock times.
+   - Use `Temporal.PlainDateTime.from()` (or `plainDate.toPlainDateTime(plainTime)`) when combining a calendar date and wall-clock time without binding to a time zone.
+   - Use `Temporal.PlainMonthDay.from()` for annual dates without a year, and convert to a `PlainDate` with `.toPlainDate({ year })` before performing date arithmetic.
+   - Use `Temporal.PlainYearMonth.from()` for year-and-month values so arbitrary day numbers never leak into calculations.
+2. **Note the `calendar` parameter when constructing Plain types**: ISO 8601 (`'iso8601'`) is the default calendar when parsing ISO strings or constructing with `PlainDate.from({ year, month, day })`. When constructing `PlainMonthDay` or `PlainYearMonth` from property bags—or when working with non-ISO calendars—pass `calendar` explicitly (e.g., `{ month: 10, day: 31, calendar: 'iso8601' }`).
+3. **Use `.add()` with `overflow` options for recurring calendar intervals**: Calling `plainDate.add({ months: 1 })` defaults to `{ overflow: 'constrain' }`, clamping month-end dates like Jan 31 to Feb 28/29. Pass `{ overflow: 'reject' }` when invalid target dates should throw a `RangeError` instead of clamping.
+
+### Example: Full Dates, Wall-Clock Times, and `PlainDateTime`
+
+```javascript
+// 1. Parse a calendar date and a wall-clock time from input strings
+const birthdate = Temporal.PlainDate.from('1990-01-01');
+const reminderTime = Temporal.PlainTime.from('09:00');
+
+// Combine into a location-agnostic PlainDateTime without string interpolation
+const localAppointment = birthdate.toPlainDateTime(reminderTime);
+
+// 2. Display without time zone conversion; outputs the same date in any time zone
+console.log(birthdate.toLocaleString('en-GB'));
+console.log(localAppointment.toString()); // "1990-01-01T09:00:00"
+
+// 3. Read calendar fields directly from the Plain type. A PlainDate already *is*
+// a calendar date, so there is no need for the formatToParts() workaround that
+// legacy Date code uses to recover year/month/day from an instant.
+const { year, month, day } = birthdate;
+```
+
+### Example: Partial Dates (`PlainMonthDay` and `PlainYearMonth`)
+
+```javascript
+// Annual recurring event (no year component)
+// Include explicit calendar when constructing from an object
+const annualHoliday = Temporal.PlainMonthDay.from({
+  month: 10,
+  day: 31,
+  calendar: 'iso8601',
+});
+
+const today = Temporal.Now.plainDateISO();
+const isToday = annualHoliday.equals(today.toPlainMonthDay());
+
+// Convert PlainMonthDay to a PlainDate with a specific year before doing arithmetic,
+// because month lengths (such as February) depend on whether the year is a leap year.
+const occurrenceThisYear = annualHoliday.toPlainDate({ year: today.year });
+
+// Monthly expiration (no day component, preventing day-of-month overflow bugs)
+const cardExpiry = Temporal.PlainYearMonth.from({
+  year: 2027,
+  month: 12,
+  calendar: 'iso8601',
+});
+const currentMonth = today.toPlainYearMonth();
+const isExpired = Temporal.PlainYearMonth.compare(cardExpiry, currentMonth) < 0;
+```
+
+### Example: Recurring Monthly Intervals (`overflow: 'constrain'` vs `'reject'`)
+
+```javascript
+const billingStart = Temporal.PlainDate.from('2024-01-31');
+
+// Default overflow: 'constrain' clamps Jan 31 + 1 month to the last valid day of February
+const nextBilling = billingStart.add({ months: 1 }, { overflow: 'constrain' });
+console.log(nextBilling.toString()); // "2024-02-29" (2024 is a leap year)
+
+// Use overflow: 'reject' to throw a RangeError when the target day does not exist
+try {
+  billingStart.add({ months: 1 }, { overflow: 'reject' });
+} catch (err) {
+  // RangeError: day 31 does not exist in February
+}
+```
+
+### Example: Interoperating with Legacy `Date`
+
+A legacy `Date` is a timestamp (an instant), not a calendar date. Storing `"1990-01-01"` as a `Date` forces you to pick *some* instant (typically midnight UTC), and reading it back in a time zone west of UTC yields `"31/12/1989"`. If a library or API still requires a `Date`, convert explicitly through `Temporal.Instant` rather than building ISO strings by hand:
+
+```javascript
+// PlainDate -> Date: attach a time zone (time of day defaults to the start of
+// that day) to get an Instant, then hand the epoch milliseconds to Date.
+// 'UTC' is a deliberate choice and must be documented; any zone would do,
+// but the stored instant depends on it.
+const instant = birthdate.toZonedDateTime('UTC').toInstant();
+const legacyDate = new Date(instant.epochMilliseconds);
+
+// Date -> PlainDate: go back through Instant (legacyDate.toTemporalInstant()
+// is equivalent), then project into an explicit time zone. The result depends
+// on the zone, which is exactly the drift risk.
+const viewedDate = Temporal.Instant.fromEpochMilliseconds(legacyDate.getTime())
+  .toZonedDateTimeISO('America/New_York')
+  .toPlainDate();
+
+// Compare Plain types with .equals() (or Temporal.PlainDate.compare), not strings.
+console.log(viewedDate.equals(birthdate)); // false: the calendar date drifted to 1989-12-31
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal.PlainDate` for full calendar dates, `Temporal.PlainTime` for wall-clock times, `Temporal.PlainDateTime` for local date-time pairs without a zone, `Temporal.PlainMonthDay` for recurring annual dates, and `Temporal.PlainYearMonth` for year-month expirations or billing periods.
+- **DO NOT** perform arithmetic directly on `Temporal.PlainMonthDay`; convert it to a `Temporal.PlainDate` first via `.toPlainDate({ year })` because month lengths vary by year.
+- **DO** use `.add()` on `Temporal.PlainDate` for recurring calendar intervals, relying on `overflow: 'constrain'` (the default) to clamp month-end dates or `overflow: 'reject'` to throw a `RangeError` on nonexistent dates.
+- **DO** specify `calendar` (e.g., `calendar: 'iso8601'`) when constructing `PlainMonthDay` or non-ISO Plain types from objects.
+- **DO NOT** use Plain types if you need to represent a specific moment in physical time (an instant). Use `Temporal.Instant` or `Temporal.ZonedDateTime` for logs, event timestamps, or cross-timezone scheduling.
+- **DO NOT** construct `Date` objects from hand-built ISO strings (such as `` `${date}T00:00:00Z` ``). Produce a `Date` from the `epochMilliseconds` of a `Temporal.Instant` or `Temporal.ZonedDateTime`, and read one back with `Temporal.Instant.fromEpochMilliseconds(date.getTime())` or `date.toTemporalInstant()`, so the time zone assumption is explicit.
+- **DO NOT** use `Intl.DateTimeFormat.prototype.formatToParts()` to extract or compare year, month, or day values. Read `.year`, `.month`, and `.day` directly from a Plain type, and compare with `.equals()`.
+- **DO** identify time zones by IANA name (e.g., `America/New_York`) and never by a fixed UTC offset. Offsets change with daylight saving time and legislation, so labels like `"UTC-5"` become wrong for part of the year.
+- **DO** remember that `Temporal` objects are **immutable**. Methods like `.add()`, `.subtract()`, or `.with()` always return a new instance with a new reference rather than mutating the original object in place, making them safe to store directly in reactive UI state.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Browser support for Temporal: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and dynamically load `temporal-polyfill` (~15 KB min+gz).
+
+Note that importing `temporal-polyfill` does not automatically assign the `Temporal` object to the global scope. Assign it explicitly if your code relies on `globalThis.Temporal`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import('https://esm.sh/temporal-polyfill');
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+  }
+  initializeApp();
+})();
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/coordinate-global-events.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/coordinate-global-events.md
new file mode 100644
index 00000000..83a5271f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/coordinate-global-events.md
@@ -0,0 +1,80 @@
+# Coordinating Global Events with Temporal
+
+Scheduling events across different time zones is notoriously difficult with the legacy `Date` object, especially around Daylight Saving Time (DST) transitions when hours can be skipped or repeated.
+
+The `Temporal` API provides `Temporal.ZonedDateTime` to represent a date and time in a specific time zone, handling DST transitions automatically and predictably.
+
+## How to Implement
+
+To coordinate global events and handle potential DST conflicts:
+
+1. **MANDATORY:** **Create a ZonedDateTime**: Use `Temporal.ZonedDateTime.from()` to create a time-zone-aware date-time object.
+2. **MANDATORY:** **Handle Ambiguity**: Use the `disambiguation` option to control behavior when a time is ambiguous or does not exist (e.g., during clock changes).
+3. **MANDATORY:** **Convert Time Zones**: Use `.withTimeZone()` to see the equivalent time in another location.
+
+### Example: Scheduling and Conflict Detection
+
+```javascript
+// 1. Define the event time and target time zone
+const date = "2025-03-09";
+const time = "02:30"; // This time is skipped in New York during Spring Forward
+const timeZone = "America/New_York";
+const inputStr = `${date}T${time}[${timeZone}]`;
+
+// 2. Detect conflicts using 'reject'
+let hasConflict = false;
+try {
+  // 'reject' throws RangeError if the time is ambiguous or does not exist
+  Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'reject' });
+} catch (e) {
+  if (e instanceof RangeError) {
+    hasConflict = true;
+    console.log("This time falls in a DST transition gap or overlap.");
+  }
+}
+
+// 3. Resolve the time safely using 'compatible' (default)
+// 'compatible' will resolve to a valid time even if skipped or repeated
+const hostTime = Temporal.ZonedDateTime.from(inputStr, { disambiguation: 'compatible' });
+console.log(`Resolved time: ${hostTime.toString()}`);
+
+// 4. Convert to another time zone (e.g., Tokyo)
+const tokyoTime = hostTime.withTimeZone("Asia/Tokyo");
+// Use toLocaleString() for user-facing display instead of manual hour/minute padding
+console.log(`Tokyo time: ${tokyoTime.toLocaleString('en-US', { hour: 'numeric', minute: '2-digit' })}`);
+```
+
+## Strategic Implementation & Best Practices
+
+-   **DO** use `Temporal.ZonedDateTime` for events that are bound to a specific geographical location (like a meeting in a specific city).
+-   **DO** use `disambiguation: 'reject'` if you need to detect and warn users about scheduling conflicts during DST transitions.
+-   **DO** use `disambiguation: 'compatible'` (the default) when you want the system to automatically pick a sensible time when conflicts occur.
+-   **DO NOT** use `Temporal.PlainDateTime` for global events, as it does not carry time zone information and cannot account for DST changes.
+-   **DO** use `.withTimeZone()` to calculate the equivalent time in other locations without mutating the original object (Temporal objects are immutable).
+-   **DO** use native `.toLocaleString()` formatting (such as `{ hour: 'numeric', minute: '2-digit' }`) for user-facing time displays instead of manual time calculations and padding.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Browser support for Temporal: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and dynamically load `temporal-polyfill` (~15 KB min+gz).
+
+Note that importing `temporal-polyfill` does not automatically assign the `Temporal` object to the global scope. Assign it explicitly if your code relies on `globalThis.Temporal`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import('https://esm.sh/temporal-polyfill');
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+  }
+  initializeApp();
+})();
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/sort-high-precision-timestamps.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/sort-high-precision-timestamps.md
new file mode 100644
index 00000000..95d88de1
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/sort-high-precision-timestamps.md
@@ -0,0 +1,92 @@
+# Sorting High-Precision Timestamps with Temporal.Instant
+
+Log viewers, audit timelines, and telemetry UIs often ingest events whose ISO 8601 timestamps were recorded with microsecond or nanosecond precision by a server, database, or native clock (for example, `2026-04-01T12:00:00.000123456Z`). Because the legacy `Date` object only stores milliseconds, parsing those strings with `new Date()` or `Date.parse()` silently truncates sub-millisecond digits, causing distinct events within the same millisecond to collide and sort in an unstable order.
+
+`Temporal.Instant` represents an exact point on the UTC timeline with nanosecond precision and no attached time zone. When parsing pre-recorded high-precision timestamps with `Temporal.Instant.from()`, it preserves the full nanosecond value, sorts deterministically with `Temporal.Instant.compare()`, and computes exact `Temporal.Duration` intervals between events. Note that in browsers, `Temporal.Now.instant()` is deliberately clamped to millisecond or microsecond resolution for Spectre timing-attack mitigation—use `Temporal.Instant.from()` to preserve nanosecond timestamps produced by external clocks, and use `performance.now()` when measuring sub-millisecond intervals locally in the client.
+
+## How to Implement
+
+To parse, sort, and measure intervals between high-precision timestamps:
+
+1. **Parse recorded timestamps as `Temporal.Instant`**: Use `Temporal.Instant.from(isoString)` on the timestamp string supplied by the server, database, or log line. Keep the timestamp the source recorded; do not replace it with `Temporal.Now.instant()` in the browser.
+2. **Sort events chronologically**: Use `Temporal.Instant.compare(a, b)` as the comparator passed to `Array.prototype.sort()` or `Array.prototype.toSorted()`. It compares the full nanosecond value so sub-millisecond ordering is preserved.
+3. **Calculate intervals**: Use `instant.since(previousInstant)` to get a `Temporal.Duration` between consecutive events. Use `a.equals(b)` to detect events with identical timestamps.
+4. **Display intervals with `toLocaleString()`**: Format the `Temporal.Duration` for users with `duration.toLocaleString()`, which delegates to `Intl.DurationFormat`. Do not convert to a single `Number` of nanoseconds for display.
+5. **Serialize for transmission**: Use `Temporal.Instant.prototype.toString()` to emit a standard ISO 8601 string (always in UTC with a `Z` suffix).
+
+## Example Code: Sorting High-Precision Timestamps
+
+```javascript
+// Events received with nanosecond-precision ISO 8601 timestamps.
+const rawEvents = [
+  { nodeId: 'api-2', eventType: 'db.query', ts: '2026-04-01T12:00:00.000123456Z' },
+  { nodeId: 'api-1', eventType: 'request.start', ts: '2026-04-01T12:00:00.000120000Z' },
+  { nodeId: 'api-2', eventType: 'request.end', ts: '2026-04-01T12:00:00.000987654Z' },
+];
+
+// 1. Parse recorded timestamps as Temporal.Instant (never `new Date(ts)`,
+// which drops everything below the millisecond).
+const events = rawEvents.map(evt => ({
+  ...evt,
+  timestamp: Temporal.Instant.from(evt.ts),
+}));
+
+// 2. Sort chronologically with the static compare() method
+function sequenceEvents(items) {
+  // Instant.compare returns -1, 0, or 1, which is what sort() expects.
+  return [...items].sort((a, b) => Temporal.Instant.compare(a.timestamp, b.timestamp));
+}
+
+// 3. Calculate and display the interval between consecutive events
+function analyzeTrace(sortedEvents) {
+  for (let i = 1; i < sortedEvents.length; i++) {
+    const prev = sortedEvents[i - 1];
+    const curr = sortedEvents[i];
+
+    // since() returns a Temporal.Duration that retains nanosecond precision.
+    const gap = curr.timestamp.since(prev.timestamp);
+
+    // 4. toLocaleString() formats the duration for people (e.g., "3μs 456ns").
+    // Avoid gap.total('nanoseconds'): spans over ~104 days exceed Number.MAX_SAFE_INTEGER.
+    // 'en-US' is used here for deterministic output; pass undefined to use the user's locale.
+    console.log(`${prev.eventType} → ${curr.eventType}: ${gap.toLocaleString('en-US', { style: 'narrow' })}`);
+  }
+}
+
+analyzeTrace(sequenceEvents(events));
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `Temporal.Instant.from()` for parsing high-precision timestamps recorded against a single clock (such as a server, database, or log pipeline) that need to be ordered or differenced. Unlike `Temporal.PlainDateTime`, `Temporal.Instant` represents an unambiguous point on the universal timeline.
+- **DO** keep the timestamp recorded by the source. In browsers, `Temporal.Now.instant()` is clamped to millisecond/microsecond precision for Spectre timing-attack and fingerprinting mitigation; use `performance.now()` / `performance.mark()` for local sub-millisecond client intervals, and `Temporal.Instant.from()` for parsing nanosecond timestamps from server or native clocks.
+- **DO** use `Temporal.Instant.compare()` for sorting and `a.equals(b)` for equality checks; do not check `Temporal.Instant.compare(a, b) === 0` or compare `.toString()` output.
+- **DO NOT** parse high-precision timestamp strings with `new Date()` or `Date.parse()` for ordering, because they truncate to milliseconds and produce collisions.
+- **DO NOT** collapse an interval to a single number for display. `duration.total('nanoseconds')` returns a `Number`, which exceeds `Number.MAX_SAFE_INTEGER` for spans longer than ~104 days and silently loses precision. Subtracting `epochNanoseconds` (a `BigInt`) is exact but discards unit structure; keep intervals as `Temporal.Duration` and format them with `.toLocaleString()`.
+- **DO** convert an `Instant` to `Temporal.ZonedDateTime` with `instant.toZonedDateTimeISO(timeZone)` when you need to display the localized wall-clock time of an event to a user.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Browser support for Temporal: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and dynamically load `temporal-polyfill` (~15 KB min+gz).
+
+Note that importing `temporal-polyfill` does not automatically assign the `Temporal` object to the global scope. Assign it explicitly if your code relies on `globalThis.Temporal`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import('https://esm.sh/temporal-polyfill');
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+  }
+  initializeApp();
+})();
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/support-global-calendar-systems.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/support-global-calendar-systems.md
new file mode 100644
index 00000000..b88d7d52
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/js/support-global-calendar-systems.md
@@ -0,0 +1,103 @@
+# Supporting Global Calendar Systems with Temporal
+
+The traditional JavaScript `Date` object is based on a proleptic Gregorian calendar, making it challenging to build applications for users who rely on other calendar systems, such as the Islamic (lunar), Hebrew (lunisolar), or Chinese (lunisolar) calendars. Developers previously had to rely on complex third-party libraries or manual calculations to support these systems.
+
+The `Temporal` API provides first-class support for multiple calendar systems. By associating a calendar identifier with date objects, Temporal handles the complex arithmetic and formatting required for different cultural contexts natively.
+
+## How to Implement
+
+To support global calendar systems using Temporal:
+
+1. **Associate a Calendar (Mandatory):** When creating or converting a Temporal object (like `Temporal.PlainDate`), you must specify the desired calendar system using `withCalendar()` to perform calendar-sensitive operations.
+2. **Use Stable Identifiers (Mandatory for Lunisolar Calendars):** You must use `monthCode` rather than the numeric `month` index to identify specific months across years in lunisolar calendars. Only use this for calendars that use leap months, such as the Hebrew and Chinese calendars.
+3. **Respect Calendar Invariants (Mandatory):** When iterating through months or days, you must not assume fixed values (like 12 months in a year or 31 days in a month). Use properties like `monthsInYear` and `daysInMonth` to ensure your code works across all calendars.
+4. **Use Calendar-Aware Comparisons (Mandatory):** When comparing dates within a specific calendar system, you must use `Temporal.PlainDate.compare()` instead of comparing year/month/day properties manually. This correctly handles chronological ordering within the calendar rules.
+
+## Example Code: Converting and Iterating Calendars
+
+```javascript
+// 1. Helper to check calendar support
+function isCalendarSupported(calendarId) {
+  try {
+    return Intl.supportedValuesOf('calendar').includes(calendarId);
+  } catch {
+    // Fallback for environments where supportedValuesOf is not available
+    return false;
+  }
+}
+
+// 2. Get current date in default ISO 8601 calendar
+const isoDate = Temporal.Now.plainDateISO();
+
+// 3. Convert to Hebrew calendar if supported
+const calendarId = 'hebrew';
+const targetDate = isCalendarSupported(calendarId) 
+  ? isoDate.withCalendar(calendarId)
+  : isoDate; // Fallback to ISO if not supported
+
+if (targetDate.calendar.id !== calendarId) {
+  console.warn(`Calendar ${calendarId} not supported; falling back to ISO 8601`);
+}
+
+// 4. Log properties specific to the calendar
+console.log(`Calendar: ${targetDate.calendar.id}`);
+console.log(`Year: ${targetDate.year}`);
+console.log(`Month Code: ${targetDate.monthCode}`); // Stable across leap years
+
+// 5. Safely iterate through months in the current year
+for (let m = 1; m <= targetDate.monthsInYear; m++) {
+  console.log(`Month ${m} has ${targetDate.with({ month: m }).daysInMonth} days.`);
+}
+
+// 6. Compare dates within the same calendar
+const today = Temporal.Now.plainDateISO().withCalendar(calendarId);
+const comparison = Temporal.PlainDate.compare(targetDate, today);
+const relative = comparison < 0 ? 'Past' : comparison > 0 ? 'Future' : 'Today';
+console.log(`Timeline: ${relative}`);
+
+// 7. Format for display using toLocaleString (including era for era-based calendars like 'japanese')
+const localizedDisplay = targetDate.toLocaleString('en-u-ca-hebrew', {
+  day: 'numeric',
+  month: 'long',
+  year: 'numeric',
+  era: 'long'
+});
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `monthsInYear` as the upper bound when looping through months, rather than assuming 12.
+- **DO** use `monthCode` for identifying specific months in calendars that use leap months (e.g., Hebrew or Chinese), regardless of the year.
+- **DO NOT** assume `date.month === 12` is the last month of the year. Use `date.month === date.monthsInYear`.
+- **DO NOT** assume `inLeapYear === true` implies the year is only one day longer. In lunisolar calendars, it may add a full leap month.
+- **DO** use `Temporal.PlainDate.compare()` when comparing two dates in a specific calendar system instead of comparing Year/Month/Day properties manually.
+- **DO** use `toLocaleString()` to format dates for users instead of manual string concatenation.
+- **DO** verify that the target calendar system is supported by the environment using `Intl.supportedValuesOf('calendar')` before creating calendar-specific Temporal objects.
+- **DO** be aware that some calendars (like variants of the Islamic calendar) may rely on visual observation rather than fixed calculations. The `Temporal` API follows the environment's `Intl` implementation, which usually uses calculated approximations. For critical cultural or religious date calculations, verify with domain experts or use specialized libraries.
+- **DO** account for era names when using calendars that use eras (e.g., Japanese, Buddhist), using `toLocaleString()`.
+
+## Fallback Strategy
+
+### Fallbacks & browser support for Temporal
+
+Browser support for Temporal: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 139 (May 2025).
+Unsupported in: Safari.
+
+For browsers that do not yet support the native `Temporal` API, use feature detection and dynamically load `temporal-polyfill` (~15 KB min+gz).
+
+Note that importing `temporal-polyfill` does not automatically assign the `Temporal` object to the global scope. Assign it explicitly if your code relies on `globalThis.Temporal`.
+
+```javascript
+// Check if Temporal is supported natively
+(async () => {
+  if (typeof Temporal === 'undefined') {
+    // Load the polyfill conditionally
+    const module = await import('https://esm.sh/temporal-polyfill');
+    globalThis.Temporal = module.Temporal;
+    // Extend Date.prototype if needed
+    Date.prototype.toTemporalInstant = module.toTemporalInstant;
+  }
+  initializeApp();
+})();
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/batch-analytics-events.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/batch-analytics-events.md
new file mode 100644
index 00000000..a5ca12ca
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/batch-analytics-events.md
@@ -0,0 +1,154 @@
+# Debounce and batch multiple analytics events
+
+Most analytics, telemetry, and Core Web Vitals analytics data is lower priority than responding to the user, so you can safely defer sending it until the user leaves the page. The exception to this is if you need to deliver real-time updates, in which case timeliness matters.
+
+The optimal way to provide real-time analytics updates, while still minimizing beacons, is to use `fetchLater()` with the `activateAfter` configuration option. This allows you to effectively debounce and batch all analytics events that occur within a given time window into a single beacon, that is reliably sent even if the user leaves the page before the timeout expires.
+
+## How to implement
+
+1. **Schedule the request:** As soon as any relevant analytics data is available, call `fetchLater()` with your data payload and pass an `activateAfter` value. This queues the data to be sent after that amount of time passes, or if the user leaves the page beforehand.
+
+2. **Batch multiple events together:** If a new analytics event occurs before the `activateAfter` timeout expires, abort the previously scheduled request and call `fetchLater()` again (with the same `activateAfter` value) with the full event queue in a single payload.
+
+3. **Reset the event queue when the timeout expires:** If a new analytics event occurs after the scheduled beacon has successfully sent (i.e. the `fetchLater()` result's `activated` value is `true`), reset the event queue.
+
+3. **Let the browser handle the rest:** If the user navigates away or closes the tab before the `activateAfter` timeout expires, the browser will still reliably send the payload from your most recent `fetchLater()` call.
+
+## Example code
+
+This code tracks all `load` and `click` events on a page, and batches together all events that occur within a 10-second timeout.
+
+```javascript
+// Replace with your analytics endpoint.
+const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';
+
+// Replace with a time window of your choice. All analytics events that
+// occur within this time window will be batched together.
+const BATCH_WINDOW = 10 * 1000;
+
+// The maximum number of events to batch. Pick a number that is unlikely
+// to overflow the fetchLater() quota for the page.
+const MAX_QUEUE_SIZE = 100;
+
+const eventQueue = [];
+let fetchLaterResult;
+let fetchLaterController;
+
+function trackEvent(eventData) {
+  // If the previously queued beacon has already been sent, or if the
+  // max queue size has been met, reset the queue.
+  if (fetchLaterResult?.activated || eventQueue.length > MAX_QUEUE_SIZE) {
+    fetchLaterController = null;
+    fetchLaterResult = null;
+    eventQueue.length = 0;
+  }
+
+  eventQueue.push(eventData);
+
+  // Abort any pending beacons before creating a new one.
+  if (fetchLaterController) {
+    fetchLaterController.abort();
+  }
+  fetchLaterController = new AbortController();
+
+  // Schedule a fetch for the events to be sent when the batch window expires.
+  // IMPORTANT: wrap the call in a try/catch to handle quota errors.
+  try {
+    fetchLaterResult = fetchLater(ANALYTICS_ENDPOINT, {
+      method: 'POST',
+      headers: {'content-type': 'application/json'},
+      body: JSON.stringify(eventQueue),
+      signal: fetchLaterController.signal,
+      activateAfter: BATCH_WINDOW,
+    });
+  } catch (error) {
+    // Handle errors as needed.
+  }
+}
+
+// Track page loads.
+window.addEventListener('load', () => {
+  trackEvent({type: 'page_load'});
+});
+
+// Track click events.
+window.addEventListener('click', (event) => {
+  trackEvent({type: 'click', target: serializeElement(event.target)});
+});
+```
+
+## Best Practices
+
+- **DO** use `fetchLater()` with the `activateAfter` option set to batch multiple analytics events that occur within close proximity of each other.
+- **DO** use an `AbortController` to cancel the pending fetch in cases where a new analytics event occurs.
+- **DO** check to ensure you do not batch too many events together and exceed the `fetchLater()` quota (currently roughly 64KB per origin).
+- **DO** wrap calls to `fetchLater()` in a `try/catch` to handle quota errors.
+- **DO** feature detect the presence of `fetchLater()` on `globalThis` and implement a fallback strategy for browsers that don't support the API.
+- **DO NOT** use a `ReadableStream` object for the request body, as that will error.
+
+## Browser support and fallback strategies
+
+Browser support for fetchLater: Limited availability.
+Supported by: Chrome 135 (Apr 2025) and Edge 135 (Apr 2025).
+Unsupported in: Firefox and Safari.. Therefore, a fallback strategy is typically required.
+
+However, given the improved reliability and performance benefits of this API, `fetchLater()` should be used if the browser supports it.
+
+### `fetchLater()` polyfill
+
+Use the following minimal `fetchLater()` polyfill, which implements the API as closely as possible in unsupporting browsers.
+
+The only notable behavior difference with this polyfill is instead of sending the payload when the user leaves the page, it sends it whenever the page's `visibilityState` changes to "hidden", since this is the most reliable end-of-session signal that's widely available today.
+
+```js
+globalThis.fetchLater ??= function fetchLater(url, init = {}) {
+  let timeoutHandle;
+  let activated = false;
+
+  function sendNow() {
+    if (!(init.signal && init.signal.aborted)) {
+      // Use fetch keepalive if the browser supports it or if custom fetch
+      // parameters are specified (e.g. custom headers or methods).
+      // Otherwise fall back to `navigator.sendBeacon()`.
+      if (
+        'keepalive' in Request.prototype ||
+        init.method !== 'POST' ||
+        init.headers
+      ) {
+        fetch(url, Object.assign({}, init, {keepalive: true}));
+        activated = true;
+      } else {
+        activated = navigator.sendBeacon(url, init.body);
+      }
+    }
+    destroy();
+  }
+
+  function destroy() {
+    document.removeEventListener('visibilitychange', sendNow);
+    clearTimeout(timeoutHandle);
+  }
+
+  if (document.visibilityState === 'hidden') {
+    // If the beacon was created while the page is already hidden, send data
+    // ASAP but wait until the next microtask to allow all sync code to run.
+    queueMicrotask(sendNow);
+  } else {
+    document.addEventListener('visibilitychange', sendNow);
+
+    if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
+      timeoutHandle = setTimeout(sendNow, init.activateAfter);
+    }
+  }
+
+  if (init.signal) {
+    init.signal.addEventListener('abort', destroy);
+  }
+
+  return {
+    get activated() {
+      return activated;
+    },
+  };
+};
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/break-up-long-tasks.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/break-up-long-tasks.md
new file mode 100644
index 00000000..23c216e1
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/break-up-long-tasks.md
@@ -0,0 +1,62 @@
+# Break Up Long Tasks
+
+Heavy computations or long loops can block the main thread, causing the page to become unresponsive. To prevent this, you should yield control back to the browser periodically. The `scheduler.yield()` API allows you to pause a long task and let the browser handle user input or rendering before continuing.
+
+### Breaking up long tasks
+
+Use `scheduler.yield()` inside async functions to break up work.
+
+```javascript
+async function processLargeArray(items) {
+  // DO: Set a time-based deadline 50 milliseconds into the future. 50
+  // milliseconds is the boundary for when a task becomes a long task.
+  let deadline = performance.now() + 50; // 50ms budget
+
+  for (const item of items) {
+    // Process the item
+    processItem(item);
+    
+    // MANDATORY: Yield to the main thread periodically to keep the UI
+    // responsive. This can be done by checking if the deadline set earlier
+    // has been exceeded. When it has been, yield, then reset the deadline
+    // another 50 milliseconds into the future.
+    if (performance.now() >= deadline) {
+      await scheduler.yield();
+      deadline = performance.now() + 50;
+    }
+  }
+}
+```
+
+### Fallback strategies
+
+Browser support for Scheduler API: Limited availability.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), and Firefox 142 (Aug 2025).
+Unsupported in: Safari.
+
+Some browsers may not support the `scheduler` API. You MUST implement a fallback using `setTimeout` to ensure code executes without breaking.
+
+#### Fallback for `scheduler.yield()`
+
+```javascript
+async function processLargeArrayWithFallback(items) {
+  // DO: Set a time-based deadline 50 milliseconds into the future.
+  let deadline = performance.now() + 50;
+
+  for (const item of items) {
+    processItem(item);
+    
+    // MANDATORY: Yield to the main thread periodically to keep the UI responsive.
+    if (performance.now() >= deadline) {
+      // DO: Feature detect scheduler.yield
+      if ('scheduler' in window && 'yield' in window.scheduler) {
+        await scheduler.yield();
+      } else {
+        // DO: Fallback to setTimeout for older browsers
+        await new Promise(resolve => setTimeout(resolve, 0));
+      }
+      deadline = performance.now() + 50;
+    }
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/calculate-total-foreground-time.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/calculate-total-foreground-time.md
new file mode 100644
index 00000000..d24cb256
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/calculate-total-foreground-time.md
@@ -0,0 +1,69 @@
+# Calculate total foreground time
+
+This guide details how to accurately calculate the total time a user spends actively viewing a page. Traditional metrics like time-on-page often incorrectly include time spent with the page in the background. By using the `VisibilityStateEntry` API, you can measure only the "foreground time," providing a better metric of user engagement.
+
+## Implementing foreground time calculation
+
+The `PerformanceTimeline` API exposes visibility state changes as performance entries. Rather than reacting to `visibilitychange` events and manually accumulating time throughout a session, you can query the entire visibility history at any time.
+
+MANDATORY: You must query the `visibility-state` performance entries to calculate the true foreground time.
+
+```javascript
+/**
+ * Calculates total time the page was in the visible state.
+ *
+ * @returns {number} Total foreground time in milliseconds.
+ */
+function getTotalForegroundTime() {
+  // MANDATORY: Query the visibility-state entries from the performance timeline.
+  const entries = performance.getEntriesByType('visibility-state');
+
+  // Fallback: If the browser does not support VisibilityStateEntry,
+  // the API will gracefully return an empty array.
+  if (entries.length === 0) {
+    // Return total time since navigation start as a fallback.
+    return performance.now();
+  }
+
+  let totalForegroundTime = 0;
+
+  for (let i = 0; i < entries.length; i++) {
+    // Only calculate duration for periods where the state was 'visible'
+    if (entries[i].name === 'visible') {
+      const start = entries[i].startTime;
+
+      // The end time is the start time of the next state change,
+      // or the current time if this is the final entry.
+      const end = i + 1 < entries.length
+          ? entries[i + 1].startTime
+          : performance.now();
+
+      totalForegroundTime += (end - start);
+    }
+  }
+
+  return totalForegroundTime;
+}
+```
+
+## Fallbacks & browser support
+
+Browser support for Page visibility state performance entries: Limited availability.
+Supported by: Chrome 115 (Jul 2023) and Edge 115 (Jul 2023).
+Unsupported in: Firefox and Safari.
+
+The `VisibilityStateEntry` API is a modern addition to the Performance Timeline and may not be supported in all browsers.
+
+Because `performance.getEntriesByType('visibility-state')` returns an empty array in unsupported browsers, feature detection is built into the calculation flow. You should always check if entries are returned before proceeding.
+
+If the API is unsupported, the recommended fallback is to return `performance.now()`. This represents the total time since navigation, which serves as a reasonable upper bound for engagement time when visibility state history is unavailable.
+
+```javascript
+const entries = performance.getEntriesByType('visibility-state');
+
+// If the array is empty, the API is likely unsupported.
+if (entries.length === 0) {
+  // Fallback: Return total time since page load.
+  return performance.now();
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/conditional-async-dependencies.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/conditional-async-dependencies.md
new file mode 100644
index 00000000..b75a7bba
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/conditional-async-dependencies.md
@@ -0,0 +1,74 @@
+# Conditional Async Dependencies
+
+Top-level `await` allows modules to act as asynchronous functions, meaning they can pause module execution to await promises. This is extremely useful for conditionally loading async dependencies—like polyfills or heavy secondary libraries—only when required by the browser. 
+
+By utilizing top-level await, you can encapsulate the conditional loading logic inside a single module, effectively preventing downstream consumer modules from executing until the dependency is fully loaded and ready.
+
+### Conditional polyfill pattern
+
+While top-level `await` can be used to conditionally load any async dependency that's a module, a good use of the conditional depenency loading pattern is to conditionally load polyfills for browsers that don't support a specific feature. This approach encapsulates feature detection and the dynamic import inside a single dependency module.
+
+In the following case, the `popover` attribute polyfill is conditionally loaded if it isn't present on `HTMLElement.prototype`:
+
+```javascript
+// conditionally-load-polyfill.js
+
+// Check if the feature is missing before doing work.
+// MANDATORY: Prefer checking HTMLElement.prototype over window or document
+// when checking for a global DOM attribute or property like popover.
+if (!('popover' in HTMLElement.prototype)) {
+  // Use top-level await to pause the execution of any module that imports this file 
+  // until the polyfill finishes downloading and executing.
+  await import('/path/to/popover-polyfill.js');
+}
+
+// Export a marker if needed by your application
+export const polyfillLoaded = true;
+```
+
+```javascript
+// main.js
+
+// MANDATORY: Because conditionally-load-polyfill.js uses top-level await, 
+// this import will block execution of main.js until the polyfill is ready.
+import './conditionally-load-polyfill.js';
+
+// Now it is safe to use the feature (e.g., showing a popover)
+const myPopover = document.getElementById('my-popover');
+if (myPopover) {
+  myPopover.showPopover();
+}
+```
+
+### Sequencing module imports and avoiding the pre-Safari 27 bug
+
+**MANDATORY:** You must structure your module graph so the top-level `await` module is imported from a single entry point and completes before downstream modules evaluate:
+
+* **DO NOT place sibling static imports in an entry file** (for example, `import './conditionally-load-polyfill.js'; import './app.js';`). Per the ECMAScript module evaluation specification, top-level `await` only suspends the parent module that imports it—not sibling static imports—so `./app.js` will evaluate concurrently in all browsers before the polyfill finishes loading.
+* **DO NOT import the top-level `await` module from multiple sibling modules simultaneously** (for example, having both `a.js` and `b.js` statically import `./conditionally-load-polyfill.js`). While [Safari 27 fixed WebKit's module loader](https://webkit.org/blog/18227/fixing-top-level-await-in-safari/) to support concurrent imports of top-level `await` modules per spec, Safari 15–26.6 fails when multiple modules simultaneously import a module containing a top-level `await` (see [MDN browser compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#browser_compatibility)).
+
+Instead, choose one of two patterns depending on your module structure:
+
+1. **Single entry module (shown in `main.js` above):** If your entry module runs the dependent initialization logic directly, statically import `./conditionally-load-polyfill.js` at the top of that module and run your code in its body.
+2. **Bootstrapping separate application modules:** If your entry module delegates to downstream application modules (such as `./app.js`), chain dynamic `import()` calls with top-level `await` so `./app.js` is only fetched and evaluated after the polyfill module resolves:
+
+```javascript
+// main.js
+
+// MANDATORY: Chain dynamic imports with top-level await when bootstrapping separate
+// application modules so './app.js' waits for the polyfill to finish loading.
+// DO NOT use sibling static imports (`import './conditionally-load-polyfill.js'; import './app.js';`),
+// which evaluate concurrently and execute './app.js' before the polyfill is ready.
+await import('./conditionally-load-polyfill.js');
+await import('./app.js');
+```
+
+### Fallback strategies
+
+Baseline status for Top-level await: Newly available. It's been Baseline since 2026-09-14.
+Supported by: Chrome 89 (Mar 2021), Edge 89 (Mar 2021), Firefox 89 (Jun 2021), and Safari 27 (Sep 2026).
+
+While basic top-level `await` has been supported across major browsers since 2021 (Chrome 89, Edge 89, Firefox 89, and Safari 15), it only reached full spec compliance in [Safari 27](https://webkit.org/blog/18227/fixing-top-level-await-in-safari/) (see [MDN browser compatibility](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/await#browser_compatibility)).
+
+* **Safari 15–26.6:** As long as you follow the single-entry-point pattern in the previous section so multiple sibling modules do not concurrently import the top-level `await` module, you can safely rely on top-level `await` without an additional fallback.
+* **Legacy browsers (pre-2021):** If your application must support browsers without any top-level `await` support, avoid top-level `await` and wrap your conditional `import()` orchestration in a standard `async` function or `.then()` promise chain.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-rendering-heavy-content.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-rendering-heavy-content.md
new file mode 100644
index 00000000..4a8c5489
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-rendering-heavy-content.md
@@ -0,0 +1,106 @@
+# Defer rendering heavy content
+
+Web pages with extensive content—such as infinite scrolls, complex dashboards, or dense articles can suffer from slow initial rendering and sluggish interactions. Modern web technologies allow you to defer the rendering workload for content that is not immediately visible, significantly boosting performance without breaking accessibility or user expectations.
+
+To optimize rendering, you can utilize the CSS `content-visibility` property and the HTML `hidden="until-found"` attribute. While both aid performance, they serve distinct use cases.
+
+## When to use which
+
+| Scenario / Example | Feature Applied | Performance Benefit |
+| :--- | :--- | :--- |
+| **1. Below the fold** (Delay initial load) | **`content-visibility: auto`** | Browser automatically offloads layout/paint workload until the container scrolls close to view, keeping standard page load speed frictionless. |
+| **2. Toggle State** (Fast view switching) | **`content-visibility: hidden`** | Skips layout calculations for hidden divs but preserves style containment state, allowing for instantaneous toggling without structural shifts (superior to `display: none`). |
+| **3. Searchable & Deferred** (Collapsible disclosures) | **`hidden="until-found"`** | For detailed instructions on combining rendering performance with find-in-page search accessibility, see `search-hidden-content` (via `npx -y modern-web-guidance@latest retrieve "search-hidden-content"`). |
+
+## How to implement `content-visibility: auto`
+
+### Choosing off-screen content
+
+**MANDATORY**: You MUST carefully identify which elements receive `content-visibility: auto`.
+- **DO** target large, self-contained layout blocks that are strictly **below the initial fold** (e.g., card items in an infinite feed, trailing comments, or bottom-heavy layout sections).
+- **DO NOT** apply this property to elements within the initial, above-the-fold viewport. Doing so forces the browser to evaluate visibility boundaries before rendering, which paradoxically delays critical page load performance.
+- **DO** target elements with deep or complex internal DOM structures to maximize rendering cost savings.
+
+### Implementation steps
+
+1. **MANDATORY**: Identify heavy sections that are confirmed to be off-screen on initial load.
+2. **MANDATORY**: Apply `content-visibility: auto` to each of these off-screen elements.
+3. **MANDATORY**: Provide an estimated layout structure size using `contain-intrinsic-size` on each element.
+
+### How to use `contain-intrinsic-size`
+
+**MANDATORY**: You MUST pair `content-visibility: auto` with `contain-intrinsic-size`. Failure to do so forces the browser to collapse the element to a 0px height when off-screen, causing severe layout shifting and scrollbar jumping as the user scrolls.
+
+The `contain-intrinsic-size` CSS shorthand property acts as a placeholder dimension. Using the `auto` keyword enables the browser to "remember" the exact size once the element is finally rendered, using that calculated size over the placeholder if the element goes off-screen again.
+
+### Example code
+
+```css
+/* DO ONLY apply this class to items OUTSIDE the initial layout viewport */
+.heavy-section-deferred {
+  /* MANDATORY: Skips rendering calculations when off-screen */
+  content-visibility: auto;
+  
+  /* Mandatory: Provide an estimated size to prevent layouts shifts.
+    - 'auto' is optional and enables the browser to remember the actual size
+      once rendered. It must be paired with a <length> value to be used for
+      the first render.
+    - 'none' tells the browser not to apply any intrinsic width to this element.
+      It can be used for either the height or the width value.
+    - '150px' is the estimated height of this element. This can be any valid
+      CSS <length> value.
+   */
+  contain-intrinsic-size: auto none auto 150px; 
+}
+```
+
+## How to implement `content-visibility: hidden`
+
+1. **Identify heavy sections:** Locate layout blocks that are initially hidden (e.g., extra rows in a large data table).
+2. **Apply CSS:** Add `content-visibility: hidden` to the element.
+3. **Reveal the element:** When the element should be revealed, change the `content-visibility` property to `visible` or `auto`.
+
+### Example code
+
+```css
+.cached-view {
+  /* Hides content but caches rendering state */
+  content-visibility: hidden;
+}
+
+.cached-view.is-active {
+  content-visibility: visible;
+}
+```
+
+Because `content-visibility: hidden` excludes the element and its children from the accessibility tree and find-in-page search, **DO NOT** use it if the content must remain discoverable while hidden. If you need hidden content to remain searchable via native Find-in-page, use `hidden="until-found"` as described in `search-hidden-content` (via `npx -y modern-web-guidance@latest retrieve "search-hidden-content"`).
+
+## Best Practices
+
+- **DO** use `contain-intrinsic-size` with `content-visibility: auto`. Failure to do so forces height recalculations on scroll, causing viewport layout jumping or visual glitches.
+- **DO NOT** apply `content-visibility: auto` to elements inside the initial fold viewport, as this delays critical page rendering.
+- **MANDATORY Accessibility Verification**: When applying `content-visibility: auto`, you MUST verify sequential keyboard reachability. In certain assistive technology configurations, off-screen nodes utilizing `content-visibility: auto` may be excluded from the accessibility tree or sequential navigation routes until focus is forcibly moved inside them. Test linear navigation across off-screen boundaries using keyboard alone.
+
+## Fallback strategies
+
+### `content-visibility` fallback
+
+Baseline status for content-visibility: Newly available. It's been Baseline since 2025-09-15.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 130 (Sep 2024), and Safari 26 (Sep 2025).
+
+When `content-visibility` is not supported it will be ignored by the browser. In most cases `content-visibility: auto` will not need a fallback, though without it performance gains will be lost. An unsupported browser will leave `content-visibility: hidden` elements completely visible. Use feature detection to implement a fallback.
+
+```css
+/* Default for everyone */
+.inactive {
+  display: none;
+}
+
+/* Modern Browsers only */
+@supports (content-visibility: hidden) {
+ .inactive {
+    display: block; /* Turn the layout box back on */
+    content-visibility: hidden;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-work-until-scroll-ends.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-work-until-scroll-ends.md
new file mode 100644
index 00000000..dcec82cf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/defer-work-until-scroll-ends.md
@@ -0,0 +1,78 @@
+# Defer Work Until Scroll Ends
+
+Scrolling on the web should be smooth and responsive. Executing heavy tasks—such as layout recalculations, analytics data beacons tracking, or dynamic DOM updates—during scrolling can saturate the main thread, resulting in dropped frames and layout thrashing.
+
+Historically, developers have relied on debouncing the `scroll` event using `setTimeout()` to guess when a scroll is finished. However, these debounced functions are notoriously unreliable. They may trigger while the user’s is still scrolling.
+
+The `scrollend` event offers a highly reliable, performance-driven solution. The browser fires a `scrollend` event exactly when a scroll has rested, all transitions are finished, and a touch gesture has been released.
+
+## How to Implement
+
+To implement a defer-work pattern:
+
+1. **Set Up a Scrollable Container**: Create a container with `overflow: auto` or `overflow: scroll`.
+2. **Listen for `scroll` events**: Only use this listener for basic dynamic metrics or informative layout styling. Do not execute heavy work here.
+3. **Listen for `scrollend` events**: Register a `scrollend` callback on the scroll container or the document itself.
+4. **Execute Expensive work in the callback**: This is where it's safe to fetch dynamic content or trigger comprehensive DOM layouts.
+
+## Example Code
+
+```css
+.scroll-container {
+  height: 300px;
+  overflow-y: auto;
+}
+```
+
+```javascript
+const scroller = document.querySelector('.scroll-container');
+
+// 1. Informative feedback during scroll
+scroller.addEventListener('scroll', () => {
+  // Avoid dynamic heavier data updates here
+  console.log('Scrolling dynamically... updates deferred');
+});
+
+// 2. Safe callback when scrolling rests
+scroller.addEventListener('scrollend', () => {
+  // Run layout recalculations or analytical beacons updates here
+  const currentVisibleSection = findMostVisibleSection(scroller);
+  fetchAdditionalData(currentVisibleSection);
+});
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `scrollend` instead of debounced `scroll` events when firing layout data beacons or fetching new content content layout dynamically. 
+- **DO** consider pairing this with `scrollSnapChange` or `scrollSnapChanging` snap interactions if you're building carousels or testimonial galleries slides.
+- **DO NOT** bundle layout-dependent dynamic updates inside dynamic visual scroll callbacks.
+- **DO** consider that visual viewport zooming and scrolling triggers the `scrollend` event correctly.
+
+## Fallback Strategy
+
+Baseline status for scrollend: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 109 (Jan 2023), and Safari 26.2 (Dec 2025).
+
+For unsupported browsers, fall back to a debounced `scroll` event with `setTimeout` to dispatch a custom `scrollend` event.
+
+```javascript
+function initializeDemo() {
+  const scroller = document.querySelector('#scroller');
+  scroller.addEventListener('scrollend', () => {
+    // Safe execution
+  });
+}
+
+if ('onscrollend' in window) {
+  initializeDemo();
+} else {
+  initializeDemo();
+  const scroller = document.querySelector('#scroller');
+  scroller.addEventListener('scroll', () => {
+    clearTimeout(window.scrollendtimer);
+    window.scrollendtimer = setTimeout(() => {
+      scroller.dispatchEvent(new CustomEvent('scrollend'));
+    }, 100);
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deliver-optimized-decorative-images.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deliver-optimized-decorative-images.md
new file mode 100644
index 00000000..d31dad97
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deliver-optimized-decorative-images.md
@@ -0,0 +1,51 @@
+# Deliver Optimized Decorative Images
+
+Delivering optimized decorative images via CSS improves perceived performance without sacrificing visual quality. By using the `image-set()` CSS function, you can provide the browser with multiple options for a single background or mask image. You can specify modern formats (like AVIF or WebP) alongside different resolutions (like `1x` and `2x`). The browser will dynamically select the smallest compatible image that provides the appropriate pixel density for the user's device.
+
+**CAUTION**: If the image is likely to be the Largest Contentful Paint (LCP) element (e.g., a large hero banner), be aware that images referenced in CSS via image-set() are not discoverable by the browser's preload scanner. This can significantly delay image loading and harm LCP. For LCP candidates, consider using a standard HTML `<img>` or `<picture>` tag instead or alternatively, preloading the image as well using `<link rel=preload>` option with a `media` attribute.
+
+### Implementation
+
+The `image-set()` function is used anywhere CSS expects an `<image>` value, most commonly in `background-image`, `content`, or `mask-image`. Note that while providing both the image format via `type()` and the resolution (like `1x` or `2x`) yields the best results, both of these arguments are optional. 
+
+```css
+.gallery-item {
+  /* Provide multiple resolutions and formats using image-set() */
+  /* MANDATORY: Always order your formats from most optimized (AVIF) to least optimized (JPEG/PNG). 
+     The browser will stop at the first supported format. */
+  background-image: image-set(
+    url("gallery.avif") type("image/avif") 1x,
+    url("gallery-2x.avif") type("image/avif") 2x,
+    url("gallery.webp") type("image/webp") 1x,
+    url("gallery-2x.webp") type("image/webp") 2x,
+    url("gallery.jpg") type("image/jpeg") 1x,
+    url("gallery-2x.jpg") type("image/jpeg") 2x
+  );
+  
+  /* Standard decorative properties */
+  background-size: cover;
+  background-position: center;
+}
+```
+
+### Fallback strategies
+
+Baseline status for image-set(): Widely available. It's been Baseline since 2023-09-18.
+Supported by: Chrome 113 (May 2023), Edge 113 (May 2023), Firefox 89 (Jun 2021), and Safari 17 (Sep 2023).
+
+For older browsers that do not support the `image-set()` function, you **MUST** provide a standard image declaration *before* the `image-set()` rule. This progressive enhancement strategy relies on CSS's cascading nature: unsupported rules are ignored.
+
+```css
+.gallery-item {
+  /* MANDATORY: Fallback for browsers that do not support image-set() */
+  background-image: url("gallery.jpg");
+  
+  /* Modern browsers will apply this and override the fallback */
+  background-image: image-set(
+    url("gallery.avif") type("image/avif") 1x,
+    url("gallery-2x.avif") type("image/avif") 2x,
+    url("gallery.jpg") type("image/jpeg") 1x,
+    url("gallery-2x.jpg") type("image/jpeg") 2x
+  );
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deprioritize-background-fetches.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deprioritize-background-fetches.md
new file mode 100644
index 00000000..f0dc0a7a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/deprioritize-background-fetches.md
@@ -0,0 +1,37 @@
+# Deprioritize background fetches
+
+When a page performs multiple simultaneous network requests, they often compete for the same bandwidth. Non-critical data such as analytics, logging, or background synchronization should be deprioritized so that user-initiated or critical data fetches can complete more quickly.
+
+## How to implement
+
+1. **Identify background requests**: Determine which `fetch()` calls are for non-essential data that doesn't impact the immediate user experience.
+2. **Apply fetch priority**: Add the `priority: 'low'` option to the `fetch()` initialization object.
+
+## Example code
+
+```javascript
+// Use high priority (default) for critical UI updates
+const criticalData = await fetch('/api/data');
+
+// Explicitly deprioritize background analytics
+fetch('/api/analytics', {
+  method: 'POST',
+  body: JSON.stringify(eventData),
+  // Lower the priority to prevent network contention
+  priority: 'low'
+});
+```
+
+## Best practices
+
+- **DO** use `priority: 'low'` for analytics, beacons, or telemetry data that isn't required for the current view.
+- **DO** use `priority: 'low'` for "prefetching" data that the user *might* need later, ensuring it doesn't slow down what they need *now*.
+- **DO NOT** use `priority: 'low'` for fetches that are critical to the user experience.
+- **DO NOT** use the deprecated `importance` key in the fetch options object. The correct key is `priority`.
+
+## Fallback strategy
+
+Baseline status for Fetch priority: Newly available. It's been Baseline since 2024-10-29.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 132 (Oct 2024), and Safari 17.2 (Dec 2023).
+
+The `priority` option in the Fetch API is a progressive enhancement. Browsers that do not support it will ignore the option and treat the request with default priority. No explicit feature detection or fallback logic is required for basic usage.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/detect-initial-visibility-state.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/detect-initial-visibility-state.md
new file mode 100644
index 00000000..30f82a55
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/detect-initial-visibility-state.md
@@ -0,0 +1,101 @@
+# Detect Initial Visibility State
+
+Determining if a page was initially loaded in the background (e.g., opened in a new background tab) is critical for accurate performance monitoring. Pages loaded in the background often have delayed rendering and longer metric times (like First Contentful Paint). Identifying these pages allows you to filter them out of performance analytics to avoid skewed data.
+
+The most accurate way to measure this is by using the `VisibilityStateEntry` API, which reliably records visibility changes on the browser's performance timeline, regardless of when your script actually executes.
+
+### Detecting initial visibility and background time
+
+MANDATORY: Use `performance.getEntriesByType('visibility-state')` to access the exact visibility history. Do not rely solely on checking `document.visibilityState` at execution time, as it is susceptible to race conditions.
+
+```javascript
+/**
+ * Accurately determines visibility state history using the Performance API.
+ */
+function getVisibilityInfo() {
+  // Retrieve VisibilityStateEntry members:
+  const entries = performance.getEntriesByType('visibility-state');
+  
+  if (entries.length > 0) {
+    const firstEntry = entries[0];
+    
+    // If the first performance entry for visibility is 'hidden',
+    // the page was loaded in the background.
+    const initiallyBackgrounded = firstEntry.name === 'hidden';
+    
+    // Find the precise, high-resolution timestamp of when the page 
+    // was first backgrounded.
+    let timeBackgrounded = null;
+    for (const entry of entries) {
+      if (entry.name === 'hidden') {
+        // entry.startTime is used because it provides the exact browser 
+        // timestamp of the visibility change, which is required for precision
+        timeBackgrounded = entry.startTime;
+        break;
+      }
+    }
+
+    return {
+      initiallyBackgrounded,
+      timeBackgrounded
+    };
+  }
+}
+```
+
+### Fallback strategies
+
+Browser support for Page visibility state performance entries: Limited availability.
+Supported by: Chrome 115 (Jul 2023) and Edge 115 (Jul 2023).
+Unsupported in: Firefox and Safari.
+
+For unsupported environments, you may fall back to checking the `document.visibilityState` property or listening for the `visibilitychange` event.
+
+**MANDATORY:** You must understand that this fallback approach is often **highly inaccurate for determining initial background state**. Because scripts can load and execute asynchronously, a page could be opened in a background tab and then foregrounded by the user *before* your script has finished downloading and executing. When your script finally runs, `document.visibilityState` will synchronously read as `'visible'`, and you will incorrectly assume the page was loaded in the foreground, completely missing its initial hidden state. Furthermore, the fallback timestamp lacks the internal precision of the Performance API. If precision is a high priority, do not use the fallback.
+
+```javascript
+/**
+ * Fallback implementation using document.visibilityState.
+ * This approach is prone to race conditions if the script loads asynchronously.
+ */
+function getFallbackVisibilityInfo() {
+  // Check the state exactly when this script executes.
+  // This will fail to detect an initial background state if the user 
+  // foregrounded the page before this script executed.
+  let initiallyBackgrounded = document.visibilityState === 'hidden';
+  
+  // If it's hidden now, we approximate that it was hidden from load (time 0).
+  let timeBackgrounded = initiallyBackgrounded ? 0 : null;
+
+  // Listen for future visibility changes to capture if it is backgrounded later.
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden' && timeBackgrounded === null) {
+      // performance.now() is used here as a fallback, but it only gives 
+      // us the time the event listener fired, not the precise internal 
+      // browser time the visibility actually changed.
+      timeBackgrounded = performance.now();
+    }
+  });
+
+  return {
+    get initiallyBackgrounded() { return initiallyBackgrounded; },
+    get timeBackgrounded() { return timeBackgrounded; }
+  };
+}
+
+// Modern implementation using VisibilityStateEntry API.
+function getVisibilityInfo() {
+  // Code omitted here would be the same modern
+  // implementation shown earlier in this guide
+  // ...
+}
+
+// DO: Detect if the VisibilityStateEntry API is available
+if ('VisibilityStateEntry' in window) {
+  // DO: If VisibilityStateEntry is available, use it first:
+  getVisibilityInfo();
+} else {
+  // DO: If VisibilityStateEntry is unavailable, fall back to `document.visibilityState`:
+  getFallbackVisibilityInfo();
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/efficient-background-processing.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/efficient-background-processing.md
new file mode 100644
index 00000000..f78873d5
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/efficient-background-processing.md
@@ -0,0 +1,117 @@
+# Efficient Background Processing
+
+Pause heavy background tasks when a component is not being rendered by the browser to conserve system resources and battery life.
+
+## Overview
+
+The `content-visibility: auto` property allows the browser to skip rendering calculations for elements that are far outside the viewport. When the browser decides to skip or resume rendering for an element, it fires the `contentvisibilityautostatechange` event on that element.
+
+By listening to this event, you can pause expensive operations like `<canvas>` animations, WebGL rendering, or high-frequency WebSocket data polling when they are not needed, and resume them just-in-time when the browser prepares to display the content.
+
+### `contentvisibilityautostatechange` vs. `IntersectionObserver`
+
+It is important to understand when to use which API:
+
+*   **Use `IntersectionObserver` for application logic** tied to the exact visual visibility of an element in the viewport (e.g., lazy-loading data, infinite scroll triggers).
+*   **Use `contentvisibilityautostatechange` for rendering-heavy work** (like complex canvas updates or heavy DOM mutations). This event ties directly to the browser's internal rendering lifecycle. The browser often starts rendering an element before it actually appears on screen (the pre-render margin). This event tells you when that happens, ensuring your content is ready to be seen.
+
+## Implementation
+
+### 1. Apply CSS Content Visibility
+
+Set `content-visibility: auto` on the heavy container and provide a placeholder size to prevent scrollbar jumping.
+
+```css
+.heavy-component {
+  /* Defer rendering work when off-screen */
+  content-visibility: auto;
+  
+  /* Mandatory: Provide a placeholder size to prevent layouts shifts.
+    - 'auto' is optional and enables the browser to remember the actual size
+      once rendered. It must be paired with a <length> value to be used for
+      the first render.
+    - 'none' tells the browser not to apply any intrinsic width to this element.
+      It can be used for either the height or the width value.
+    - '500px' is the estimated height of this element. This can be any valid
+      CSS <length> value. Replace it with the expected height of your
+      component.
+   */
+  contain-intrinsic-size: auto none auto 500px;
+}
+```
+
+### 2. Listen for State Changes
+
+Add an event listener for `contentvisibilityautostatechange` to pause or resume background tasks.
+
+> **Important:** The `contentvisibilityautostatechange` event does not bubble in some browser implementations. To handle this event reliably, you must either:
+> - Attach the event listener directly to the element that has `content-visibility: auto` applied.
+> - Use a capturing event listener (`{ capture: true }`) if you are delegating events to a parent container.
+
+```javascript
+const component = document.querySelector('.heavy-component');
+
+// Option 1: Direct listener (recommended)
+component.addEventListener('contentvisibilityautostatechange', (event) => {
+  if (event.skipped) {
+    // The browser skipped rendering this content.
+    // DO NOT perform heavy mutations or animation loops here.
+    stopSimulation();
+    pauseWebSocketPolling();
+  } else {
+    // The browser is about to render the content.
+    // Resume your work so it is ready when visible.
+    startSimulation();
+    resumeWebSocketPolling();
+  }
+});
+
+// Option 2: Capturing listener for event delegation
+document.addEventListener('contentvisibilityautostatechange', (event) => {
+  if (event.target.matches('.heavy-component')) {
+    if (event.skipped) {
+      stopSimulation();
+    } else {
+      startSimulation();
+    }
+  }
+}, { capture: true });
+```
+
+### Fallback strategies
+
+Baseline status for content-visibility: Newly available. It's been Baseline since 2025-09-15.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 130 (Sep 2024), and Safari 26 (Sep 2025).
+
+The `content-visibility` property and the associated `contentvisibilityautostatechange` event are progressive enhancements. In browsers that do not support them:
+*   The CSS property is ignored, and the content is rendered normally.
+*   The event never fires, so background tasks will continue to run as they normally would without optimization.
+
+If you must support pausing tasks on older browsers, you can fallback to using `IntersectionObserver` as a rough approximation. This helps save battery and CPU on older devices too.
+
+```javascript
+// Fallback using IntersectionObserver for older browsers
+const target = document.getElementById('target-container');
+
+// Check if content-visibility is supported
+const isSupported = 'contentVisibility' in document.documentElement.style;
+
+if (!isSupported) {
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        // The element is close to the screen. Start work!
+        startSimulation();
+      } else {
+        // The element is far away. Pause work!
+        stopSimulation();
+      }
+    });
+  }, {
+    // Use rootMargin to start rendering before it hits the screen
+    rootMargin: '200px'
+  });
+
+  observer.observe(target);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/faster-spa-view-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/faster-spa-view-transitions.md
new file mode 100644
index 00000000..e04cd285
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/faster-spa-view-transitions.md
@@ -0,0 +1,79 @@
+# Faster SPA View Transitions via State Caching
+
+Enable instant navigation between views in a Single-Page Application (SPA) by caching the rendered state of inactive views instead of destroying them.
+
+## Overview
+
+Traditionally, when a user navigates between tabs or views in an SPA, developers either destroy the old view or hide it using `display: none`. Both approaches require the browser to recreate or recalculate the full layout and paint when the user returns to that view.
+
+By using `content-visibility: hidden` on inactive views, the browser removes the element’s contents from the layout flow and stops painting it, but *retains* its cached rendering state in memory. When the user switches back, the view restores nearly instantly.
+
+### The CPU vs. RAM Trade-off
+
+While this approach offers massive performance benefits, it introduces a specific trade-off that you must manage carefully:
+
+*   **CPU Savings:** Massive. The browser completely skips layout and paint passes for hidden views.
+*   **RAM Cost:** High. The browser keeps all DOM nodes, event listeners, and state for the hidden view in memory.
+
+#### When This Trade-off Becomes Dangerous
+
+*   **DO** use this strategy for simple applications with a small, predictable number of views (e.g., a 3-to-5 tabbed interface).
+*   **DO NOT** unconditionally cache every view in highly dynamic applications that generate dozens of unique reports or use infinite dynamic routes. Doing so will eventually cause severe memory bloat and may crash the browser on low-end devices.
+*   **MANDATORY:** If your application is highly dynamic, you MUST implement an **eviction strategy** (like a Least Recently Used cache) to destroy old views when a memory threshold is reached.
+
+## Implementation
+
+### 1. Configure View Containers
+
+Set `content-visibility: hidden` on views that are not currently active.
+
+> **Note:** The `content-visibility: hidden` property hides an element's *contents*, but the element itself remains styled and visible. Its background, borders, padding, and margins will still be painted by the browser.
+
+```css
+.spa-view.inactive {
+  /* MANDATORY: Use hidden to cache the rendering state of inactive views */
+  content-visibility: hidden;
+  
+  /* Optional: Prevent hidden views from taking up physical space in layout flow */
+  position: absolute;
+}
+```
+
+### 2. Manage Focus
+
+When swapping views, ensure you manage keyboard focus correctly to preserve accessibility.
+
+```javascript
+function switchToView(viewId) {
+  // Hide all views
+  document.querySelectorAll('.spa-view').forEach(view => {
+    view.classList.add('inactive');
+    view.setAttribute('aria-hidden', 'true');
+  });
+  
+  // Show the target view
+  const activeView = document.getElementById(viewId);
+  activeView.classList.remove('inactive');
+  activeView.setAttribute('aria-hidden', 'false');
+  
+  // MANDATORY: Move focus to the new view to ensure a logical tab-order
+  activeView.focus();
+}
+```
+
+### Fallback strategies
+
+Baseline status for content-visibility: Newly available. It's been Baseline since 2025-09-15.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 130 (Sep 2024), and Safari 26 (Sep 2025).
+
+The `content-visibility` property degrades gracefully. In browsers that do not support it:
+*   The property is ignored.
+*   To prevent fallback browsers from rendering all views simultaneously, you should provide a fallback to `display: none` in your CSS:
+
+```css
+@supports not (content-visibility: hidden) {
+  .spa-view.inactive {
+    display: none;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/flicker-free-client-side-ab-testing.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/flicker-free-client-side-ab-testing.md
new file mode 100644
index 00000000..37233117
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/flicker-free-client-side-ab-testing.md
@@ -0,0 +1,168 @@
+# Flicker-Free Client-Side A/B Testing
+
+## The Problem
+
+Client-side A/B testing tools work by loading a script that modifies the DOM after the browser has already begun constructing the page. Without intervention, the user briefly sees the original content before it flickers or flashes to the experiment variant. Testing platforms have historically worked around this with "anti-flicker snippets" that hide the entire page with `opacity: 0` until the experiment script finishes or an arbitrary timeout (typically 4 seconds) elapses. This approach sacrifices progressive rendering, allows accidental clicks on invisible content, and introduces unnecessary paint cycles.
+
+## The Solution
+
+The `blocking=render` attribute allows a `<script>` or `<link>` element placed in the `<head>` to block rendering—but not parsing—until the resource has been fetched and executed. This gives experimentation scripts the same render-blocking behavior that stylesheets have by default, ensuring the browser never paints the page until the experiment variant has been applied. No opacity hacks, no arbitrary timeouts, and no flicker.
+
+### Implementation Strategy
+
+1. **MANDATORY:** Place the experimentation script in the document `<head>` and add `blocking="render"`.
+2. **MANDATORY:** Ensure the script either has `type="module"` (preferred for inline scripts) or `async` (preferred for external scripts with a `src` value).
+3. **DO** keep the experimentation script small and fast. Because rendering is blocked until the script executes, a large or slow script directly delays first paint.
+4. **DO NOT** use `blocking="render"` on scripts that do not need to run before first paint. It is intended only for scripts whose output must be visible in the initial render.
+5. **DO NOT** apply `blocking="render"` to scripts outside the `<head>`. Only scripts in the `<head>` can block rendering.
+
+## Implementation Guide
+
+### Basic Setup
+
+MANDATORY: Load the experimentation script with both `async` and `blocking="render"`. The `async` attribute ensures the script does not block HTML parsing (the browser continues building the DOM while fetching the script). The `blocking="render"` attribute ensures the browser does not paint anything until the script has executed.
+
+```html
+<head>
+  <!--
+    MANDATORY: Both `async` and `blocking="render"` are required.
+    - `async`: Prevents parser-blocking, so the DOM is built in parallel.
+    - `blocking="render"`: Holds rendering until the script executes,
+      ensuring experiment changes are applied before the user sees anything.
+  -->
+  <script
+    src="https://cdn.example.com/experiment-sdk.js"
+    async
+    blocking="render"
+  ></script>
+</head>
+```
+
+### Loading Experiment-Specific Styles
+
+If the experiment requires a variant stylesheet, use `blocking="render"` on the `<link>` element. Stylesheets in the `<head>` already block rendering by default, but dynamically injected stylesheets or those added via script do not. Use `blocking="render"` explicitly when the stylesheet is added dynamically or when you want to be explicit about the intent.
+
+```html
+<head>
+  <!--
+    DO: Use blocking="render" on experiment stylesheets that are
+    dynamically inserted or conditionally loaded by the experiment SDK.
+    This ensures variant styles are applied before first paint.
+  -->
+  <link
+    rel="stylesheet"
+    href="https://cdn.example.com/experiment-variant-b.css"
+    blocking="render"
+  >
+</head>
+```
+
+### Inline Experiment Script
+
+If the experiment logic is lightweight enough to inline, use an inline module script with `blocking="render"`. This is useful when the experiment logic fetches a configuration and applies DOM changes directly.
+
+```html
+<head>
+  <!--
+    DO: Use an inline module script when the experiment logic is small.
+    Module scripts are deferred by default (non-parser-blocking),
+    and blocking="render" ensures rendering waits for execution.
+  -->
+  <script type="module" blocking="render">
+    // Fetch the experiment configuration from your testing platform.
+    const config = await fetch('/api/experiment?id=homepage-cta')
+      .then(res => res.json());
+
+    // Apply the variant by setting a data attribute on <html>.
+    // CSS rules keyed to this attribute will style the variant.
+    document.documentElement.dataset.variant = config.variant;
+  </script>
+
+  <style>
+    /* Default styles (control group) */
+    .cta-button {
+      background-color: blue;
+    }
+
+    /* Variant B styles, activated by the data attribute */
+    [data-variant="b"] .cta-button {
+      background-color: green;
+    }
+  </style>
+</head>
+```
+
+## Best Practices
+
+- **MANDATORY:** The experimentation script MUST execute quickly. A slow script delays all rendering. Set a performance budget (e.g., under 100ms execution time) for the render-blocking script.
+- **DO** split heavy experiment logic from the render-blocking script. Load a small, render-blocking stub that applies the variant, then load heavier tracking or analytics scripts separately with `async` or `defer` (without `blocking="render"`).
+- **DO** use a data attribute on `<html>` or `<body>` to signal the active variant, and use CSS selectors keyed to that attribute for variant styling. This avoids direct DOM manipulation in the render-blocking script.
+- **DO NOT** use `blocking="render"` on analytics, tracking, or other non-visual scripts. Only scripts that must change what the user sees on first paint should block rendering.
+- **DO NOT** combine `blocking="render"` with legacy anti-flicker snippets. They solve the same problem; using both creates unnecessary delays.
+
+## Fallback Strategies
+
+Browser support for blocking="render": Limited availability.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+The `blocking` attribute is not supported in all browsers. In browsers that do not support it, the attribute is ignored and the script loads with its default behavior (`async` in the examples above), which may result in flicker. A fallback is required to prevent flicker in unsupported browsers.
+
+### Fallback: Anti-Flicker Snippet
+
+DO: Use a lightweight anti-flicker snippet as a fallback only when `blocking="render"` is not supported. Feature-detect support and skip the fallback in browsers that handle it natively.
+
+```html
+<head>
+  <!--
+    DO: Load the experiment script with blocking="render" for
+    browsers that support it. This is the preferred approach.
+  -->
+  <script
+    src="https://cdn.example.com/experiment-sdk.js"
+    async
+    blocking="render"
+  ></script>
+
+  <script>
+    // DO: Only apply the anti-flicker fallback in browsers
+    // that do not support blocking="render".
+    if (!Object.hasOwn(HTMLScriptElement.prototype, 'blocking')) {
+      // Hide the page until the experiment script runs.
+      document.documentElement.classList.add('ab-loading');
+
+      // DO: Set a timeout to reveal the page if the experiment
+      // script takes too long. This prevents an indefinitely
+      // blank page on slow connections. Adjust the timeout
+      // to match your experiment SDK's expected load time.
+      setTimeout(() => {
+        document.documentElement.classList.remove('ab-loading');
+      }, 4000);
+    }
+  </script>
+
+  <style>
+    /*
+      DO: Use opacity to hide content during experiment loading.
+      This is only applied when blocking="render" is unsupported.
+    */
+    .ab-loading {
+      opacity: 0 !important;
+    }
+  </style>
+</head>
+```
+
+```javascript
+// DO: In your experiment SDK's initialization callback,
+// remove the fallback class to reveal the page.
+function onExperimentReady() {
+  document.documentElement.classList.remove('ab-loading');
+}
+```
+
+## Other Considerations
+
+1. **Performance Impact**: `blocking="render"` trades first-paint speed for visual correctness. Monitor Largest Contentful Paint (LCP) and First Contentful Paint (FCP) to ensure the experimentation script is not adding excessive delay.
+2. **Third-Party Script Reliability**: If the experiment SDK is hosted on a third-party CDN, a CDN outage could block rendering entirely. The browser applies its own timeout heuristics (which may be longer than 4 seconds), but there is no developer-controlled timeout for `blocking="render"`. Ensure the third-party provider has strong uptime guarantees.
+3. **Server-Side Alternatives**: For performance-critical pages, consider server-side A/B testing (where the server renders the correct variant directly) instead of client-side testing. Server-side approaches eliminate flicker entirely without any render-blocking cost. Use client-side `blocking="render"` only when server-side testing is not feasible.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/full-session-analytics.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/full-session-analytics.md
new file mode 100644
index 00000000..584e3277
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/full-session-analytics.md
@@ -0,0 +1,135 @@
+# Reliably measure full-session analytics and telemetry
+
+To reliably track analytics, Core Web Vitals, and telemetry data that covers the entirety of a user's visit to a web page (not just until page load), use the `fetchLater()` API.
+
+The `fetchLater()` API is the most reliably way to send data to a server in cases where a response is not required and delivery timing is not urgent, which applies to data such as user analytics, telemetry, error tracking, and performance metrics like Core Web Vitals.
+
+Older technique like creating an `<img>` pixel in an `unload` event listener are notoriously unreliably (especially on mobile) and can negatively impact performance (by making pages ineligible for bfcache).
+
+## How to implement
+
+1. **Schedule the request:** As soon as relevant data is available, call `fetchLater()` with your data payload. This queues the data to be sent later.
+
+2. **Update the payload as needed:** If the user generates more data or the state changes, abort the previously scheduled request and call `fetchLater()` again with the fully updated snapshot.
+
+3. **Let the browser handle the rest:** When the user navigates away or closes the tab, the browser will reliably send the payload from your most recent `fetchLater()` call.
+
+## Example code
+
+This code measures the session duration of a user's visit to a page using `fetchLater()` to queue a new beacon every 10 seconds with the updated session duration.
+
+```javascript
+const ANALYTICS_ENDPOINT = '/path/to/analytics/endpoint';
+
+const sessionData = {
+  duration: 0,
+  id: crypto.randomUUID(),
+};
+
+let fetchLaterController = null;
+
+function queueBeacon() {
+  // Abort any pending beacons before creating a new one.
+  if (fetchLaterController) {
+    fetchLaterController.abort();
+  }
+  fetchLaterController = new AbortController();
+
+  // Update session duration to the current page time.
+  sessionData.duration = performance.now();
+
+  // Schedule a fetch for the data payload to be sent later.
+  // IMPORTANT: wrap the call in a try/catch to handle quota errors.
+  try {
+    fetchLater(ANALYTICS_ENDPOINT, {
+      method: 'POST',
+      headers: {'content-type': 'application/json'},
+      body: JSON.stringify(sessionData),
+      signal: fetchLaterController.signal,
+    });
+  } catch (error) {
+    // Handle errors as needed.
+  }
+}
+
+// Update the session data and queue a new beacon every 10 seconds.
+setInterval(queueBeacon, 10000);
+```
+
+## Best Practices
+
+- **DO** use `fetchLater()` to send data to a server in any situation where a response is not necessary, and it's not critical that the data is sent immediately.
+- **DO** use an `AbortController` to cancel the pending fetch in cases where the data may need to be updated before the user leaves the page
+- **DO** minimum the payload size to avoid exceeding the quota (currently roughly 64KB per origin).
+- **DO** wrap calls to `fetchLater()` in a `try/catch` to handle quota errors.
+- **DO** feature detect the presence of `fetchLater()` on `globalThis` and implement a fallback strategy for browsers that don't support the API.
+- **DO NOT** use a `ReadableStream` object for the request body, as that will error.
+
+## Browser support and fallback strategies
+
+Browser support for fetchLater: Limited availability.
+Supported by: Chrome 135 (Apr 2025) and Edge 135 (Apr 2025).
+Unsupported in: Firefox and Safari.
+
+A fallback strategy is required if `fetchLater()` doesn't meet your Baseline target. However, given the improved reliability and performance benefits of this API, `fetchLater()` should be used if the browser supports it.
+
+The recommended fallback strategy is to use the polyfill below, which internally handles unsupporting browsers using `fetch()` with `keepalive` or `navigator.sendBeacon()`. Your own code MUST call `fetchLater()` directly — never call `fetch()`, `sendBeacon()`, or other beacon APIs yourself.
+
+### `fetchLater()` polyfill
+
+Use the following minimal `fetchLater()` polyfill, which implements the API as closely as possible in unsupporting browsers.
+
+The only notable behavior difference with this polyfill is that it uses `visibilitychange` to detect when the user leaves, rather than relying on the browser's native unload handling. This is an internal implementation detail — your code does not need to listen for `visibilitychange` or any other page lifecycle events. Just call `fetchLater()` and the polyfill handles delivery.
+
+```js
+globalThis.fetchLater ??= function fetchLater(url, init = {}) {
+  let timeoutHandle;
+  let activated = false;
+
+  function sendNow() {
+    if (!(init.signal && init.signal.aborted)) {
+      // Use fetch keepalive if the browser supports it or if custom fetch
+      // parameters are specified (e.g. custom headers or methods).
+      // Otherwise fall back to `navigator.sendBeacon()`.
+      if (
+        'keepalive' in Request.prototype ||
+        init.method !== 'POST' ||
+        init.headers
+      ) {
+        fetch(url, Object.assign({}, init, {keepalive: true}));
+        activated = true;
+      } else {
+        activated = navigator.sendBeacon(url, init.body);
+      }
+    }
+    destroy();
+  }
+
+  function destroy() {
+    document.removeEventListener('visibilitychange', sendNow);
+    clearTimeout(timeoutHandle);
+  }
+
+  if (document.visibilityState === 'hidden') {
+    // If the beacon was created while the page is already hidden, send data
+    // ASAP but wait until the next microtask to allow all sync code to run.
+    queueMicrotask(sendNow);
+  } else {
+    document.addEventListener('visibilitychange', sendNow);
+
+    if (typeof init.activateAfter === 'number' && init.activateAfter >= 0) {
+      timeoutHandle = setTimeout(sendNow, init.activateAfter);
+    }
+  }
+
+  if (init.signal) {
+    init.signal.addEventListener('abort', destroy);
+  }
+
+  return {
+    get activated() {
+      return activated;
+    },
+  };
+};
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-heavy-scripts.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-heavy-scripts.md
new file mode 100644
index 00000000..ce45e1ee
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-heavy-scripts.md
@@ -0,0 +1,69 @@
+# Identify heavy-running JavaScript
+
+Heavy-running JavaScript can have a detrimental effect on both page load performance and interactivity. Modern web applications are more heavily reliant on JavaScript than ever before, from multiple sources. These include the application code itself (and the framework code it relies on), as well as third-party scripts that add functionality like chat widgets and video players. Behind-the-scenes analytics and marketing scripts are also common contributors that are all too easy to forget.
+
+Identifying root causes of an unresponsive web page can be tricky with certain expertise required to run web performance tracing or profiling and how to interpret the results. Additionally field data is often very different to lab data, which only replicates a small subset of real user scenarios. This can make it difficult to identify the root causes of poor performance, especially for interactions.
+
+The Long Animation Frames API is a lightweight API that can be used to identify heavy-running JavaScript in the field. A heavy-running script can be either a single long-running script, or a script that runs multiple times during the page lifecycle.
+
+## How to implement
+
+Long animation frames are monitored using the `PerformanceObserver` interface. It emits a `long-animation-frame` entry when an animation frame takes longer than 50ms to render. The entry contains information about the long animation frame, including the duration of the frame and the scripts that were executed during the frame.
+
+The `long-animation-frame` entry contains a `scripts` property which is an array of `PerformanceScript` objects. Each `PerformanceScript` object contains information about the script that was executed during the long animation frame, including the `sourceURL` and `duration` of the script.
+
+### Example of identifying the longest running scripts that contribute to long animation frames
+
+```javascript
+// Accumulate all script entries across the page lifecycle so no
+// data is lost between observer callbacks.
+const allScripts = [];
+
+const observer = new PerformanceObserver(list => {
+  // Collect all script entries across frames to find the biggest offenders.
+  allScripts.push(...list.getEntries().flatMap(entry => entry.scripts));
+
+  // Group by sourceURL so you can identify which scripts contribute
+  // the most total time, even if each individual invocation is short.
+  const scriptSource = [...new Set(allScripts.map(script => script.sourceURL))];
+  const scriptsBySource = scriptSource.map(sourceURL => ([sourceURL,
+      allScripts.filter(script => script.sourceURL === sourceURL)
+  ]));
+  const processedScripts = scriptsBySource.map(([sourceURL, scripts]) => ({
+    sourceURL,
+    count: scripts.length,
+    totalDuration: scripts.reduce((subtotal, script) => subtotal + script.duration, 0)
+  }));
+
+  // Only include scripts above a certain threshold to reduce noise.
+  const heavyScripts = processedScripts.filter(script => {
+    return script.totalDuration > 100;
+  });
+
+  // Sort by total duration so the worst offenders appear first,
+  // making it easier to prioritize optimization efforts.
+  heavyScripts.sort((a, b) => b.totalDuration - a.totalDuration);
+
+  // Log to the console for local debugging. In production, replace
+  // this with a call to send the data to your analytics service.
+  console.table(heavyScripts);
+});
+
+// Use buffered: true to capture any long frames that occurred before
+// this observer was registered.
+observer.observe({type: 'long-animation-frame', buffered: true});
+```
+
+## Best Practices
+
+- **DO** prefer the Long Animation Frames API over alternatives like the JS Self-Profiling API, which carries higher runtime overhead.
+- **DO** summarize the key information as the Long Animation Frames API contains a lot of detail.
+- **DO** send the required information to an analytics service in production.
+
+## Browser support and fallback strategies
+
+Browser support for Long animation frames performance entries: Limited availability.
+Supported by: Chrome 123 (Mar 2024) and Edge 123 (Mar 2024).
+Unsupported in: Firefox and Safari..
+
+The Long Animation Frames API is ignored by browsers that do not support it, so it can be safely used without fallbacks. In most cases the performance opportunities it identifies will apply to other browsers as well.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-inp-causes.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-inp-causes.md
new file mode 100644
index 00000000..e7f1170e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/identify-inp-causes.md
@@ -0,0 +1,105 @@
+# Identify causes of poor INP
+
+Poor responsiveness to interactions leads to a poor impression of a page being slow or even completely broken. Interaction to Next Paint (INP) is a metric based on the Event Timing API. It measures the worst interaction (minus some outliers) as a measure of the page's responsiveness.
+
+Identifying root causes of an unresponsive web page can be tricky especially as it depends on user interactions and environmental conditions such as device capabilities and network conditions. This makes it even more difficult to diagnose compared to a more repeatable and predictable scenario like page load. Lab data only replicates a small subset of real user scenarios so measuring the causes of slow INP in the field is essential.
+
+The Event Timing API allows for splitting the INP duration into three subparts: Input Delay (processing that is already happening when the interaction happens), Processing Duration (delays due as a direct result of the interaction), and Presentation Delay (delays that are due to rendering the next frame after the interaction). This helps identify if the issue is in other code, the interaction JavaScript code, or browser processing rendering updates respectively rather than jumping straight to the interaction code.
+
+It is possible to gather further insights into JavaScript, style recalculation, and layout work delaying an interaction. A full performance trace using the JS Self-Profiling API is a heavyweight solution that is liable to cause performance problems. The Long Animation Frames API is a lightweight API that can be used in the field to identify slow-running JavaScript and distinguish between style recalculation and layout costs during INP interactions:
+
+- **Script-level forced style and layout (`forcedStyleDuration` and `forcedLayoutDuration`):** Reports synchronous style recalculations (such as calling `getComputedStyle()` after DOM mutations) and forced layouts/reflows (such as reading `getBoundingClientRect()` or `offsetWidth` after mutations) inside a running script during **Input Delay** or **Processing Duration**.
+- **Frame-level rendering style and layout (`styleDuration` and `layoutDuration`):** Reports time spent recalculating styles versus updating layout during the frame's rendering update, helping explain high **Presentation Delay**.
+
+Distinguishing style recalculation from layout is critical because they have different root causes and fixes: high style duration points to expensive CSS selector matching or broad style invalidation (remediated by simplifying selectors or reducing rule scope), whereas high layout duration points to expensive geometry calculations or synchronous layout thrashing (remediated by batching DOM reads before writes, simplifying DOM structure, or using CSS containment).
+
+## How to implement
+
+Calculating INP from the raw Event Timing API is complicated and has several nuances. You are advised to use a RUM tool or library to gather this data.
+
+`web-vitals` is an open-source library from Google that calculates the Core Web Vitals including INP, and also includes subparts and long animation frame data for the INP interaction.
+
+## Get attributions for INP interactions using web-vitals library
+
+The `web-vitals` library is a tiny library used to measure Core Web Vitals and other performance metrics. The `onINP()` function can be used to identify the slowest interaction and includes information about the INP subparts, scripts that were executed during the interaction, and style and layout durations using the Long Animation Frames API.
+
+```javascript
+// Use the attribution build to get Long Animation Frame data
+// alongside the INP metric value.
+import { onINP } from 'web-vitals/attribution';
+
+onINP((metric) => {
+  const { attribution } = metric;
+  const longestScript = attribution.longestScript;
+
+  // Sum rendering-phase style and layout durations across all LoAF entries
+  // intersecting the INP interaction (primarily explains presentationDelay).
+  let renderStyleDuration = 0;
+  let renderLayoutDuration = 0;
+  for (const entry of attribution.longAnimationFrameEntries) {
+    renderStyleDuration += entry.styleDuration ?? 0;
+    renderLayoutDuration += entry.layoutDuration ?? 0;
+  }
+
+  // Beacon script, style, and layout attribution for the INP interaction,
+  // so you can identify the root cause in production.
+  navigator.sendBeacon(
+    '/analytics',
+    JSON.stringify({
+      name: 'INP',
+      value: metric.value,
+      // These fields give the INP subparts:
+      inputDelay: attribution.inputDelay,
+      presentationDelay: attribution.presentationDelay,
+      processingDuration: attribution.processingDuration,
+      interactionTarget: attribution.interactionTarget,
+      // These fields identify which script function was responsible
+      // for the longest processing during the INP interaction.
+      invokerType: longestScript?.entry?.invokerType,
+      sourceURL: longestScript?.entry?.sourceURL,
+      sourceFunctionName: longestScript?.entry?.sourceFunctionName,
+      sourceCharPosition: longestScript?.entry?.sourceCharPosition,
+      // subpart indicates which phase (input delay, processing, or
+      // presentation delay) the longest script overlapped with most.
+      subpart: longestScript?.subpart,
+      intersectingDuration: longestScript?.intersectingDuration,
+      // Synchronous style and layout work forced inside the longest script
+      // (with forcedStyleAndLayoutDuration as a combined fallback):
+      forcedStyleDuration: longestScript?.entry?.forcedStyleDuration,
+      forcedLayoutDuration: longestScript?.entry?.forcedLayoutDuration,
+      forcedStyleAndLayoutDuration: longestScript?.entry?.forcedStyleAndLayoutDuration,
+      // Rendering-phase style and layout work across the interaction's frames
+      // (with totalStyleAndLayoutDuration as a combined fallback):
+      renderStyleDuration,
+      renderLayoutDuration,
+      totalStyleAndLayoutDuration: attribution.totalStyleAndLayoutDuration
+    })
+  );
+});
+```
+
+## Best Practices
+
+- **DO** use INP subparts initially to identify whether the delay is already running JavaScript (input delay), the event handlers JavaScript for the interaction (processing duration), or the subsequent rendering (presentation delay).
+- **DO** attempt to identify the biggest blocking JavaScript as additional detail, particularly for input delay, and processing duration.
+- **DO** distinguish between style recalculation (`styleDuration`, `forcedStyleDuration`) and layout (`layoutDuration`, `forcedLayoutDuration`) when diagnosing high processing duration or presentation delay: high style times indicate expensive CSS selectors or broad invalidations, while high layout times indicate DOM geometry bottlenecks or synchronous layout thrashing.
+- **DO** prefer the Long Animation Frames API for providing this further detail over alternatives like the JS Self-Profiling API, which carries higher runtime overhead.
+- **DO** use the `web-vitals` library if no other RUM solution is in place. It can identify the INP interaction and includes information about the subparts and the scripts that were executed during the interaction (using the Long Animation Frames API).
+- **DO** beacon back the required information to an analytics service rather than just log it locally.
+
+## Browser support and fallback strategies
+
+Baseline status for Event timing performance entries: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 76 (Jul 2019), Edge 79 (Jan 2020), Firefox 89 (Jun 2021), and Safari 26.2 (Dec 2025).
+
+The Event Timing API is available in most modern browsers and is necessary to calculate INP and the INP subparts. For browsers that do not support this API INP cannot be measured.
+
+Browser support for Long animation frames performance entries: Limited availability.
+Supported by: Chrome 123 (Mar 2024) and Edge 123 (Mar 2024).
+Unsupported in: Firefox and Safari.
+
+The Long Animation Frames API provides optional, additional details. It can be safely used without fallbacks. In most cases the performance opportunities it identifies will apply to other browsers as well.
+
+If your Baseline target supports the Long Animation Frames API (`long-animation-frames`) but does not support separate style and layout duration properties (`styleDuration` and `layoutDuration` on `PerformanceLongAnimationFrameTiming`, or `forcedStyleDuration` and `forcedLayoutDuration` on `PerformanceScriptTiming`), fall back to the combined style-and-layout timings:
+- Use `script.forcedStyleAndLayoutDuration` on `PerformanceScriptTiming` for synchronous forced style and layout work inside scripts.
+- Use `metric.attribution.totalStyleAndLayoutDuration` in `web-vitals/attribution` (or compute `(entry.paintTime || entry.startTime + entry.duration) - entry.styleAndLayoutStart` on each `PerformanceLongAnimationFrameTiming` entry) for combined style and layout work.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/improve-next-page-load-performance.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/improve-next-page-load-performance.md
new file mode 100644
index 00000000..8544146c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/improve-next-page-load-performance.md
@@ -0,0 +1,121 @@
+# Improve next page load performance
+
+One of the most effective ways to improve page load performance for users navigating a site is to initiate loading the next page they're about to visit *before* they visit it. This can be done through a technique called speculative loading using the Speculation Rules API.
+
+## How it works
+
+Speculative loading works by using JSON-based speculation rules to tell the browser about links that can be prefetched or prerendered improving page load performance when user clicks on them.
+
+The rules can either be a hardcoded list of URLs a `urls` key (known as a list rule), or with a `where` key containing a set of href and CSS selectors used to find links on the page (known as a `document` rule).
+
+Rules can also include an optional `eagerness` property that specifies when the page should be prefetched or prerendered. The `eagerness` property can be set to `immediate`, `eager`, `moderate`, or `conservative`. `immediate` speculates as soon as possible, while the others wait for user signals such as hovering for a short period, for a longer period, or starting to click on the page respectively.
+
+Rules can be combined with different eagerness settings to prefetch eagerly and then prerender when the user interacts more.
+
+## When to use it
+
+Speculative loading is especially useful for static pages, where the content is not likely to change often, and where pages are cheaper to produce—especially if cached at the edge. It can also be used for dynamic pages, but it is important to be careful about the potential for stale content.
+
+Speculative loading is typically used for same-origin links, though more advanced options allow for some cross-origin speculation. This guide concentrates on the more-common same-origin use case.
+
+More eager speculative loading is a good choice for pages that are likely to be visited next, such as a headline article or the next page in a stepped process like a learning a course.
+
+Less eager speculative loading is a good choice when it is less obvious what the user will do next, when there are many links on the page, each equally likely to be visited. By waiting for more signals, such as hovering, or starting to click on the page, you can get a head-start on the next page and improve the user experience, even if it is not fully prefetched or prerendered.
+
+Similarly, prefetch is a more conservative choice than prerender, using less resources (on both the client and the server side) but providing less benefit to the user. It is a good choice for initial implementation, expanding to prerender later when the developer explicitly requests it.
+
+## How to use it
+
+Speculation rules have a JSON-based format and can be included in a `<script type="speculationrules">` tag. The rules can be included in the `<head>` or `<body>` of the document, or can be dynamically added using JavaScript.
+
+A `tag` can also be used, either at a global level or on a per-rule basis. When set, this tag will be included in the `Sec-Speculation-Tags` header, and allows you to identify server-side which speculations were made.
+
+### Example of a simple URL list rule for prefetching predefined URLs
+
+```html
+<script type="speculationrules">
+  {
+    "tag": "product-page-speculations",
+    "prefetch": [
+      {
+        "urls": ["/product/1", "/product/2", "/product/3"]
+      }
+    ]
+  }
+</script>
+```
+
+### Example of a simple document rule for prerendering all same-origin links on a page
+
+```html
+<script type="speculationrules">
+  {
+    "tag": "all-links-speculations",
+    "prerender": [{
+      "where": { "href_matches": "/*" }
+    }]
+  }
+</script>
+```
+
+### Example of a complex document rule for prerendering links with exclusions for interactive sites
+
+```html
+<script type="speculationrules">
+  {
+    "tag": "speculations-with-exclusions",
+    "prerender": [{
+      "where": {
+        "and": [
+          { "href_matches": "/*" },
+          { "not": {"href_matches": "/wp-admin"}},
+          { "not": {"href_matches": "/*\\?*(^|&)add-to-cart=*"}},
+          { "not": {"selector_matches": ".do-not-prerender"}},
+          { "not": {"selector_matches": "[rel~=nofollow]"}}
+        ]
+      }
+    }]
+  }
+</script>
+```
+
+### Example of a mixed rule set
+
+This example shows a rule set that prefetches all links eagerly, and then goes further than this to prerender those same links when it gets more signals with `moderate` eagerness.
+
+```html
+<script type="speculationrules">
+  {
+    "prefetch": [{
+      "tag": "prefetch-speculations",
+      "where": { "href_matches": "/*" },
+      "eagerness": "eager"
+    }],
+    "prerender": [{
+      "tag": "prerender-speculations",
+      "where": { "href_matches": "/*" },
+      "eagerness": "moderate"
+    }]
+  }
+</script>
+```
+
+## Best Practices
+
+- **DO** use speculation rules to prefetch and prerender pages that the user is likely to visit next.
+- **DO** use speculation rules for static sites, where the content is not likely to change often, and where pages are cheaper to produce—especially if cached at the edge.
+- **DO** take more care when using speculation rules for dynamic pages, where the content is more likely to change often, may become out of date, and where pages are more expensive to produce.
+- **DO** prefer document rules over list rules, as they are more flexible, allow the same rule to be shared across multiple pages, and can be used to prefetch and prerender pages that are not known in advance.
+- **DO** consider the trade-offs between prefetch and prerender, and choose the appropriate one for your use case. Prerender is more expensive than prefetch and can cause more unintended side effects in complex applications that display dynamic state, but provides a better user experience. Ask the developer for their preference if unsure.
+- **DO** consider the trade-offs between the different `eagerness` levels, and choose the appropriate one for your use case. More eager speculation provides a better user experience but uses more resources and can cause more unintended side effects in complex applications that display dynamic state. Ask the developer for their preference if unsure.
+- **DO NOT** overuse speculation rules, for example, to speculate every link on the page. Browsers have limits (2 speculations for non-eager speculations). `immediate` should only be used for a very small number of links.
+- **DO NOT** speculate URLs that likely trigger state changes, like `/logout` or `/add-to-cart`, and explicitly exclude them from your speculation rules if they are likely to be included in document rules.
+- **DO NOT** use speculation rules on Single Page Applications (SPAs). Speculation rules are designed for multi-page applications (MPAs) where the browser navigates to a new document on each navigation. In SPAs, the browser does not navigate to a new document on each navigation, so speculation rules will not work as expected.
+
+## Browser support and fallback strategies
+
+Browser support for Speculation rules: Limited availability.
+Supported by: Chrome 109 (Jan 2023) and Edge 109 (Jan 2023).
+Unsupported in: Firefox and Safari.
+
+However, speculative loading is a progressive enhancement. It is perfectly safe to use as an enhancement, and is highly recommended given the potential performance benefits. If a browser does not support speculation rules, it will simply ignore them.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interaction-paint-timing.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interaction-paint-timing.md
new file mode 100644
index 00000000..b0bfc4a8
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interaction-paint-timing.md
@@ -0,0 +1,200 @@
+# Measure interaction and soft-navigation paint timing
+
+Standard paint and responsiveness metrics leave a measurement gap after the initial page load:
+
+- **`LargestContentfulPaint` (`largest-contentful-paint`)** only measures the initial ("hard") document load and stops emitting entries as soon as the user first interacts with the page.
+- **`PerformanceEventTiming` and `event` / Interaction to Next Paint (INP)** measures input responsiveness up to the *very next frame* (such as a button active state or loading spinner), but does not track subsequent asynchronous paints—such as new content rendered after a `fetch()` resolves, or a client-side route transition completes.
+- Observing route changes in a Single Page App (SPA) can be difficult outside of framework code. Just monitoring URL updates can over report URL changes that are not linked to route changes (for example, anchor link changes, multiple "redirects" for a single route change).
+
+The `InteractionContentfulPaint` (`interaction-contentful-paint`) and `PerformanceSoftNavigation` (`soft-navigation`) performance entry types fill this gap. They propagate interaction causality across asynchronous tasks (`fetch`, `await`, `setTimeout`) to attribute new contentful paints and Single-Page Application (SPA) route transitions directly back to the user interaction that triggered them.
+
+## How to implement
+
+### 1. Observe contentful paints triggered by interactions
+
+Use a `PerformanceObserver` with `type: 'interaction-contentful-paint'` and `buffered: true` to observe progressively larger contentful paints attributable to any user interaction.
+
+Each `InteractionContentfulPaint` entry provides:
+- `interactionId`: The unique identifier of the initiating user interaction (matching `PerformanceEventTiming.interactionId` and `PerformanceSoftNavigation.interactionId`).
+- `startTime`: The timestamp when the initiating user interaction started, relative to the initial hard navigation time origin.
+- `paintTime` and `presentationTime`: When the rendering phase ended and when the painted pixels were drawn on screen.
+- `duration`: The elapsed time from interaction start to paint presentation (`presentationTime - startTime`).
+- `largestContentfulPaint`: A snapshot `LargestContentfulPaint` object containing details about the largest painted element for that interaction so far (`element`, `size`, `url`, `id`, `renderTime`, `loadTime`).
+
+```javascript
+/**
+ * Observes contentful paints caused by user interactions and invokes a callback
+ * whenever an interaction produces a larger contentful paint.
+ *
+ * @param {(entry: PerformanceEntry) => void} onInteractionPaint
+ */
+export function observeInteractionPaints(onInteractionPaint) {
+  // Feature-detect support before calling observe() so unsupported browsers
+  // do not throw or log console warnings.
+  if (
+    typeof PerformanceObserver === 'undefined' ||
+    !PerformanceObserver.supportedEntryTypes?.includes('interaction-contentful-paint')
+  ) {
+    return null;
+  }
+
+  const observer = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      // entry.duration is already calculated as (entry.presentationTime - entry.startTime),
+      // giving the total time from the user interaction to this contentful paint.
+      onInteractionPaint(entry);
+    }
+  });
+
+  // MANDATORY: Pass buffered: true to capture interaction paints that occurred
+  // before this observer was registered.
+  observer.observe({ type: 'interaction-contentful-paint', buffered: true });
+  return observer;
+}
+```
+
+### 2. Measure Largest Contentful Paint (LCP) for SPA soft navigations
+
+A soft navigation is emitted by the browser when a trusted user interaction causes both a visible URL change and a contentful paint. To calculate LCP for each soft navigation:
+
+1. Observe both `'soft-navigation'` and `'interaction-contentful-paint'` entries with `buffered: true`.
+2. **MANDATORY:** When a `'soft-navigation'` entry is received, seed its initial LCP candidate by calling `softNavEntry.getLargestInteractionContentfulPaint()`. If the application painted content *before* updating the URL (for example, rendering a view and then calling `history.pushState()`), those early `interaction-contentful-paint` entries were emitted before the `soft-navigation` entry and still carry the *previous* `navigationId`.
+3. **MANDATORY:** Correlate subsequent `'interaction-contentful-paint'` entries to the active soft navigation by matching `entry.interactionId === softNavEntry.interactionId`, **DO NOT** match by `entry.navigationId`. Using `interactionId` ensures you include paints that occurred before the URL update and exclude paints from later, unrelated interactions on the new route.
+
+```javascript
+/**
+ * Tracks FCP and LCP for each client-side soft navigation and reports finalized
+ * route metrics when the user navigates to a new route or hides the page.
+ *
+ * @param {(report: {
+ *   url: string,
+ *   navigationId: number,
+ *   interactionId: number,
+ *   fcpDuration: number,
+ *   lcpDuration: number | null,
+ *   lcpElement: Element | null,
+ *   lcpSize: number | null
+ * }) => void} onSoftNavReport
+ */
+export function trackSoftNavigationLCP(onSoftNavReport) {
+  const supported =
+    typeof PerformanceObserver !== 'undefined' &&
+    PerformanceObserver.supportedEntryTypes?.includes('soft-navigation') &&
+    PerformanceObserver.supportedEntryTypes?.includes('interaction-contentful-paint');
+
+  if (!supported) {
+    return null;
+  }
+
+  let activeSoftNav = null;
+  let activeLcpEntry = null;
+
+  function finalizeCurrentSoftNav() {
+    if (!activeSoftNav) return;
+
+    onSoftNavReport({
+      // activeSoftNav.name holds the destination URL of the soft navigation.
+      url: activeSoftNav.name,
+      navigationId: activeSoftNav.navigationId,
+      interactionId: activeSoftNav.interactionId,
+      // activeSoftNav.duration is (activeSoftNav.presentationTime - activeSoftNav.startTime),
+      // which represents First Contentful Paint (FCP) relative to interaction start.
+      fcpDuration: activeSoftNav.duration,
+      // activeLcpEntry.duration is (activeLcpEntry.presentationTime - activeSoftNav.startTime),
+      // representing the soft navigation's LCP duration relative to interaction start.
+      lcpDuration: activeLcpEntry ? activeLcpEntry.duration : null,
+      lcpElement: activeLcpEntry?.largestContentfulPaint?.element ?? null,
+      lcpSize: activeLcpEntry?.largestContentfulPaint?.size ?? null,
+    });
+
+    activeSoftNav = null;
+    activeLcpEntry = null;
+  }
+
+  const softNavObserver = new PerformanceObserver((list) => {
+    for (const softNavEntry of list.getEntries()) {
+      // Finalize the previous route's metrics before resetting state for the new route.
+      finalizeCurrentSoftNav();
+
+      activeSoftNav = softNavEntry;
+      // MANDATORY: Seed the LCP candidate with getLargestInteractionContentfulPaint()
+      // to capture any attributed contentful paints that occurred before the URL updated.
+      activeLcpEntry = softNavEntry.getLargestInteractionContentfulPaint();
+    }
+  });
+
+  const icpObserver = new PerformanceObserver((list) => {
+    for (const icpEntry of list.getEntries()) {
+      // MANDATORY: Match by interactionId (not navigationId) so only paints caused
+      // by the soft navigation's initiating interaction update the route's LCP.
+      if (activeSoftNav && icpEntry.interactionId === activeSoftNav.interactionId) {
+        activeLcpEntry = icpEntry;
+      }
+    }
+  });
+
+  softNavObserver.observe({ type: 'soft-navigation', buffered: true });
+  icpObserver.observe({ type: 'interaction-contentful-paint', buffered: true });
+
+  // Finalize the active route's LCP when the page is backgrounded or unloaded.
+  document.addEventListener('visibilitychange', () => {
+    if (document.visibilityState === 'hidden') {
+      finalizeCurrentSoftNav();
+    }
+  });
+
+  return { softNavObserver, icpObserver, finalizeCurrentSoftNav };
+}
+```
+
+### 3. Measure Core Web Vitals across soft navigations with `web-vitals`
+
+If your goal is to report standard Core Web Vitals (LCP, CLS, and INP) across both hard and soft navigations to an analytics endpoint, use the `web-vitals` library (v6.0.0+) with `{ reportSoftNavs: true }` rather than manually slicing every metric timeline.
+
+```javascript
+import { onLCP, onFCP, onCLS, onINP } from 'web-vitals';
+
+function sendToAnalytics(metric) {
+  // Example-only endpoint; replace with your real telemetry URL.
+  navigator.sendBeacon(
+    '/analytics',
+    JSON.stringify({
+      name: metric.name,
+      value: metric.value,
+      navigationType: metric.navigationType,
+      navigationURL: metric.navigationURL,
+    }),
+  );
+}
+
+// Pass { reportSoftNavs: true } to report metrics per soft navigation in addition
+// to the initial hard navigation.
+onLCP(sendToAnalytics, { reportSoftNavs: true });
+onFCP(sendToAnalytics, { reportSoftNavs: true });
+onCLS(sendToAnalytics, { reportSoftNavs: true });
+onINP(sendToAnalytics, { reportSoftNavs: true });
+```
+
+## Best practices
+
+- **DO** feature-detect `'interaction-contentful-paint'` and `'soft-navigation'` using `PerformanceObserver.supportedEntryTypes?.includes(...)` before calling `observer.observe()`.
+- **DO** pass `{ buffered: true }` when observing `'interaction-contentful-paint'` and `'soft-navigation'` so early entries are not missed if analytics code initializes asynchronously.
+- **DO** call `softNavEntry.getLargestInteractionContentfulPaint()` when handling a new `soft-navigation` entry so paints that occurred prior to the URL update are included in LCP.
+- **DO** match `interaction-contentful-paint` entries to a soft navigation using `interactionId`, not `navigationId`.
+- **DO** use `entry.duration` (or `entry.presentationTime - entry.startTime`) to measure interaction paint latency, rather than reporting `entry.presentationTime` directly. All `PerformanceEntry` timestamps are measured from the initial hard page load time origin, not from the soft navigation start.
+- **DO NOT** rely on `performance.getEntriesByType('soft-navigation')` to monitor long-lived single-page applications, as the browser's buffer is limited to the first 50 soft navigation entries.
+
+## Fallback strategies
+
+Browser support for Interaction contentful paint performance entries: Limited availability.
+Supported by: Chrome 151 (Jul 2026) and Edge 151 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+Browser support for Soft navigation performance entries: Limited availability.
+Supported by: Chrome 151 (Jul 2026) and Edge 151 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target includes browsers that do not support `InteractionContentfulPaint` or `PerformanceSoftNavigation`, treat these APIs as a progressive enhancement for Real User Monitoring (RUM):
+
+1. **Feature detection and graceful degradation:** Guard observer registration with `PerformanceObserver.supportedEntryTypes?.includes('interaction-contentful-paint')` and `PerformanceObserver.supportedEntryTypes?.includes('soft-navigation')`. In browsers lacking support, skip registering the observers so your application runs without throwing errors.
+2. **Keep standard hard-navigation observers active:** Continue observing standard `'largest-contentful-paint'`, `'event'`, and `'layout-shift'` entries across all browsers. Because `LargestContentfulPaint` is finalized on the first user interaction regardless of soft-navigation support, measuring soft navigations in supporting browsers does not alter or break initial hard-load LCP measurements.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interactions-in-complex-layouts.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interactions-in-complex-layouts.md
new file mode 100644
index 00000000..77173f46
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/interactions-in-complex-layouts.md
@@ -0,0 +1,78 @@
+# Optimizing Interactions in Complex Layouts
+
+Maintain high frame rates (60FPS) and eliminate interaction latency during drag-and-drop or heavy mutations in complex, multi-column layouts like Kanban boards or massive data grids.
+
+## Overview
+
+In complex layouts, performing a minor change to a single item—such as dragging a card or editing a cell—can trigger a chain reaction of style and layout calculations that forces the browser to reflow the entire page. This results in dropped frames and high Interaction to Next Paint (INP) latency.
+
+By applying `content-visibility: auto` to self-contained layout regions (like columns in a Kanban board), you can isolate rendering work.
+
+### Mechanism for On-Screen Elements
+
+It is important to understand how `content-visibility: auto` benefits elements that are **already visible on the screen**:
+
+*   For visible elements, the browser **does not** skip rendering.
+*   Instead, the performance benefit comes entirely from the **CSS containments** that the property automatically enforces (i.e., layout, style, and paint).
+*   This containment acts as a boundary. If a mutation occurs inside a container with containment applied, the browser knows that the changes cannot affect the geometry or styles of elements outside that container. The page reflow is isolated, preventing a global layout recalculation.
+
+## Implementation
+
+### 1. Identify Containment Regions
+
+Apply `content-visibility: auto` to large, self-contained containers that represent isolated layout units (e.g., grid columns, board lists).
+
+```css
+.board-column {
+  /* Apply containment boundaries */
+  content-visibility: auto;
+  
+  /* Mandatory: Provide a placeholder size to prevent layouts shifts.
+     For a vertical column, define a reasonable width and height. 
+     - 'auto' is optional and enables the browser to remember the actual size
+       once rendered. It must be paired with a <length> value to be used for
+       the first render.
+     - '300px' is the estimated width of this element. This can be any valid
+      CSS <length> value. Replace it with the expected width of your
+      component.
+     - '800px' is the estimated height of this element. This can be any valid
+      CSS <length> value. Replace it with the expected height of your
+      component.
+   */
+  contain-intrinsic-size: auto 300px auto 800px;
+}
+```
+
+### 2. Manage Interactions
+
+Ensure that interactions occurring inside the column benefit from the containment.
+
+```javascript
+// Example: Drag and drop item movement
+function moveItemToColumn(itemId, columnId) {
+  const item = document.getElementById(itemId);
+  const column = document.getElementById(columnId);
+  
+  // The browser will only reflow this specific column, 
+  // not the entire board layout!
+  column.appendChild(item);
+}
+```
+
+### Fallback strategies
+
+Baseline status for content-visibility: Newly available. It's been Baseline since 2025-09-15.
+Supported by: Chrome 108 (Nov 2022), Edge 108 (Dec 2022), Firefox 130 (Sep 2024), and Safari 26 (Sep 2025).
+
+The property degrades gracefully. In unsupported browsers:
+*   The property is ignored, and mutations will cause the standard global reflow.
+*   To achieve a similar isolation effect in older browsers, you can fall back to applying containment manually:
+
+```css
+@supports not (content-visibility: auto) {
+  .board-column {
+    /* Manual fallback for containment */
+    contain: layout style paint;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/lazy-load-video-and-audio.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/lazy-load-video-and-audio.md
new file mode 100644
index 00000000..110ffb38
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/lazy-load-video-and-audio.md
@@ -0,0 +1,192 @@
+# Lazy load video and audio
+
+Media elements (`<video>` and `<audio>`) and their associated resources (such as `<video poster>` images and preloaded metadata) consume significant network and storage bandwidth during initial page load. Even when `preload="metadata"` or `preload="none"` is set on a `<video>`, the browser eagerly fetches its `poster` image immediately, and `preload="metadata"` still initiates range requests for media headers across every player on the page.
+
+Adding `loading="lazy"` to offscreen `<video>` and `<audio>` elements instructs the browser to defer all media network requests—including `poster` image downloads, `preload` hints, and `autoplay` execution—until the element reaches a browser-calculated distance from the visual viewport.
+
+## How to implement
+
+1. **Add `loading="lazy"` to offscreen media**: Apply `loading="lazy"` to `<video>` and `<audio>` elements positioned below the fold. Omit the `loading` attribute on above-the-fold media so it defaults to `eager`.
+2. **Set explicit `width` and `height` on `<video>` elements**: Always specify integer `width` and `height` attributes (in CSS pixels) on `<video>`. Unloaded videos default to `300`×`150` dimensions; without explicit sizing, a lazy-loaded video may fail to intersect the visible viewport and never load, or cause disruptive layout shifts (CLS) when it loads.
+3. **Include the `controls` attribute on `<audio>` elements**: Always include `controls` on `<audio loading="lazy">`. Because `<audio>` elements have no intrinsic visual box without browser controls, an `<audio loading="lazy">` element without `controls` cannot visibly intersect the viewport and will never load or autoplay.
+4. **Coordinate `preload` and `poster` attributes**:
+   - On `<video loading="lazy">`, both the `poster` image fetch and the `preload` behavior (`none`, `metadata`, or `auto`) are deferred until the video approaches the viewport.
+   - Pair `loading="lazy"` with `preload="none"` when the user must explicitly press play after scrolling to the media, or `preload="metadata"` when duration and initial frame data should populate automatically once the player enters the viewport.
+5. **Handle lazy `autoplay` safely**: When `loading="lazy"` is combined with `autoplay` on a muted `<video>` (or an opt-in `<audio controls>`), playback and downloading wait until the element approaches the viewport. Always respect `@media (prefers-reduced-motion: reduce)` before autoplaying motion media.
+
+## Example code
+
+```html
+<!-- Above-the-fold hero video: DO NOT use loading="lazy".
+     Omit loading (defaults to "eager") so the poster and initial media load immediately. -->
+<video
+  controls
+  width="1280"
+  height="720"
+  poster="/images/hero-poster.jpg"
+  preload="metadata"
+>
+  <source src="/media/keynote.webm" type="video/webm">
+  <source src="/media/keynote.mp4" type="video/mp4">
+  <track src="/media/keynote-en.vtt" kind="captions" srclang="en" label="English">
+</video>
+
+<!-- Below-the-fold video player:
+     MANDATORY: Specify integer width and height attributes so the unloaded video
+     has a non-zero layout box to intersect the viewport and avoids layout shift.
+     Both the poster image and preload="metadata" are deferred until near the viewport. -->
+<video
+  controls
+  loading="lazy"
+  width="800"
+  height="450"
+  poster="/images/tutorial-poster.jpg"
+  preload="metadata"
+>
+  <source src="/media/tutorial.webm" type="video/webm">
+  <source src="/media/tutorial.mp4" type="video/mp4">
+  <track src="/media/tutorial-en.vtt" kind="captions" srclang="en" label="English">
+</video>
+
+<!-- Below-the-fold inline product loop:
+     With loading="lazy" and autoplay, downloading and playback wait until the
+     video approaches the viewport. Include muted and playsinline for autoplay. -->
+<video
+  controls
+  loading="lazy"
+  autoplay
+  loop
+  muted
+  playsinline
+  width="640"
+  height="360"
+  poster="/images/feature-loop-poster.jpg"
+>
+  <source src="/media/feature-loop.webm" type="video/webm">
+  <source src="/media/feature-loop.mp4" type="video/mp4">
+  <track src="/media/feature-loop-en.vtt" kind="captions" srclang="en" label="English">
+</video>
+
+<!-- Below-the-fold audio player:
+     MANDATORY: Include the controls attribute. Lazy-loaded <audio> without
+     controls is invisible, cannot intersect the viewport, and will never load. -->
+<figure>
+  <figcaption id="episode-title">Episode 42: Browser Architecture Deep Dive</figcaption>
+  <audio
+    controls
+    loading="lazy"
+    preload="metadata"
+    src="/media/episode-42.mp3"
+    aria-labelledby="episode-title"
+    aria-details="episode-transcript"
+  ></audio>
+  <details id="episode-transcript">
+    <summary>View transcript</summary>
+    <p>Transcript content for Episode 42...</p>
+  </details>
+</figure>
+```
+
+```javascript
+// Pause autoplaying videos when the user prefers reduced motion
+const reducedMotionQuery = window.matchMedia('(prefers-reduced-motion: reduce)');
+
+function syncReducedMotion(prefersReducedMotion) {
+  for (const video of document.querySelectorAll('video[autoplay]')) {
+    if (prefersReducedMotion) {
+      video.removeAttribute('autoplay');
+      video.pause();
+    }
+  }
+}
+
+syncReducedMotion(reducedMotionQuery.matches);
+reducedMotionQuery.addEventListener('change', (event) => {
+  syncReducedMotion(event.matches);
+});
+```
+
+## Best practices
+
+- **MANDATORY**: Always set explicit `width` and `height` attributes on `<video>` elements. Unloaded videos have a `300`×`150` intrinsic size and will never load if they do not intersect a visible part of the page.
+- **MANDATORY**: Always include the `controls` attribute on `<audio loading="lazy">` elements. Lazy-loaded `<audio>` elements without `controls` are not rendered visibly and will never load or autoplay.
+- **DO NOT** apply `loading="lazy"` to above-the-fold or Largest Contentful Paint (LCP) `<video>` elements, as it delays fetching both the `poster` image and video data.
+- **DO** omit the `loading` attribute when default eager loading is desired rather than explicitly writing `loading="eager"`.
+- **DO NOT** rely on the `window` `load` event to detect when lazy-loaded `<video>` or `<audio>` elements have loaded. The `load` event fires based only on eager-loaded media, even if a `loading="lazy"` media element is initially inside the visual viewport.
+- **DO** note that browsers only defer `loading="lazy"` media when JavaScript is enabled (an anti-tracking measure to prevent servers from inferring scroll position via media requests when scripting is disabled).
+
+## Fallback strategy
+
+Browser support for Lazy-loading media: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target does not support `loading="lazy"` on `<video>` and `<audio>`, choose between progressive enhancement and an `IntersectionObserver` fallback based on how strictly bandwidth must be conserved:
+
+### Progressive enhancement (recommended default)
+
+Browsers that do not recognize `loading="lazy"` on `<video>` and `<audio>` ignore the attribute and fall back to standard loading governed by the `preload` attribute. Pairing `loading="lazy"` with `preload="none"` or `preload="metadata"` ensures unsupported browsers still avoid downloading the full media file upfront, though `<video poster>` images and `preload="metadata"` headers will be fetched eagerly.
+
+### Custom code fallback (`IntersectionObserver`)
+
+When your Baseline target requires strictly deferring `<video poster>` downloads, `preload="metadata"` requests, or viewport-triggered playback in browsers without native support, feature-detect `Object.hasOwn(HTMLMediaElement.prototype, 'loading')`, then fall back to `IntersectionObserver`:
+
+```javascript
+// Feature-detect native media lazy loading on HTMLMediaElement.prototype
+const supportsLazyMedia = Object.hasOwn(HTMLMediaElement.prototype, 'loading');
+
+if (!supportsLazyMedia) {
+  const lazyMediaElements = document.querySelectorAll(
+    'video[loading="lazy"], audio[loading="lazy"][controls]',
+  );
+
+  // Example-only rootMargin value; adjust distance threshold for your layout
+  const mediaObserver = new IntersectionObserver(
+    (entries, observer) => {
+      for (const entry of entries) {
+        if (!entry.isIntersecting) continue;
+
+        const media = entry.target;
+
+        // Restore deferred poster and preload attributes when entering the viewport
+        if (media.dataset.poster) {
+          media.poster = media.dataset.poster;
+          delete media.dataset.poster;
+        }
+
+        if (media.dataset.preload) {
+          media.preload = media.dataset.preload;
+          delete media.dataset.preload;
+        }
+
+        if (media.dataset.src) {
+          media.src = media.dataset.src;
+          delete media.dataset.src;
+        }
+
+        for (const source of media.querySelectorAll('source[data-src]')) {
+          source.src = source.dataset.src;
+          delete source.dataset.src;
+        }
+
+        media.load();
+        observer.unobserve(media);
+      }
+    },
+    { rootMargin: '200px 0px' },
+  );
+
+  for (const media of lazyMediaElements) {
+    // Hold back network fetches in unsupported browsers until intersection
+    if (media.hasAttribute('poster')) {
+      media.dataset.poster = media.getAttribute('poster');
+      media.removeAttribute('poster');
+    }
+    if (media.hasAttribute('preload') && media.getAttribute('preload') !== 'none') {
+      media.dataset.preload = media.getAttribute('preload');
+    }
+    media.preload = 'none';
+    mediaObserver.observe(media);
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-image-priority.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-image-priority.md
new file mode 100644
index 00000000..c07bf3f6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-image-priority.md
@@ -0,0 +1,73 @@
+# Optimize image priority
+
+Browsers use heuristics to assign loading priorities to images, but these defaults may not always align with your page's Largest Contentful Paint (LCP).
+
+Using `fetchpriority` on an `<img>` element allows you to explicitly signal an image's importance to the browser, ensuring critical images load faster while non-essential ones don't compete for bandwidth.
+
+The `loading=lazy` attribute prevents images from being downloaded at all when sufficiently off-screen which can further help prioritize images.
+
+## How to implement
+
+1. **Identify the LCP image**: Determine which image is the most likely candidate for the Largest Contentful Paint (usually the hero image at the top of the page).
+2. **Elevate LCP priority**: Add `fetchpriority="high"` to the `<img>` element for the LCP candidate.
+3. **Deprioritize non-critical images**: For images that are part of a secondary UI or are only revealed after user interaction (like mega menus, modals, or off-screen carousel slides), add `fetchpriority="low"`.
+4. **Optimize lazy loading**: Never use `loading="lazy"` on the LCP image. For standard below-the-fold images, `loading="lazy"` is sufficient to defer the request until the user scrolls near them. Avoid adding `fetchpriority="low"` to these images, as you want them to load at normal priority once the user scrolls to them. Reserve `fetchpriority="low"` for images that are technically "above the fold" but not initially visible (e.g., hidden carousel slides or mega menus). For these hidden images, it is acceptable to use `loading="lazy"` as well; the browser will handle the request timing while respecting the low priority.
+5. **Prefer default priorities**: If an image should have normal loading priority, omit the `fetchpriority` attribute entirely rather than setting it to `auto`. This is a stylistic convention to keep your HTML cleaner while relying on the browser's native heuristics.
+
+## Example code
+
+```html
+<!-- Elevate priority for the LCP image -->
+<img src="/images/hero-lcp.jpg"
+     alt="Main Banner"
+     fetchpriority="high"
+     width="800" height="400">
+
+<!-- Deprioritize initially hidden images above the fold -->
+<!-- Additionally use `loading="lazy"` if there are likely to be many images-->
+ <div class="carousel">
+     <img src="/images/gallery-alt.jpg"
+          alt="Gallery Image 1"
+          width="400" height="300">
+     <img src="/images/gallery-alt.jpg"
+          alt="Gallery Image 2"
+          fetchpriority="low"
+          loading="lazy"
+          width="400" height="300">
+<div>
+
+<!-- Deprioritize images revealed only after user interaction -->
+<img src="/images/mega-menu-promo.jpg"
+     alt="Special Offer"
+     fetchpriority="low"
+     width="300" height="150">
+
+<!-- Use lazy loading ALONE for standard below-the-fold images -->
+<img src="/images/footer-logo.png"
+     alt="Footer Logo"
+     loading="lazy"
+     width="120" height="60">
+
+<!-- Omit fetchpriority for images with standard priority -->
+<img src="/images/standard-image.jpg"
+     alt="Standard Image"
+     width="400" height="300">
+```
+
+## Best practices
+
+- **MANDATORY**: Always apply `fetchpriority="high"` to the LCP image.
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical images to avoid network contention and diluting the priority boost.
+- **MANDATORY**: Use `fetchpriority="low"` for images that are technically "above the fold" but initially hidden (e.g., hidden carousel slides, mega menu images).
+- **MANDATORY**: **Do not** use `fetchpriority="low"` on standard below-the-fold images that are already using `loading="lazy"`. These images should load at normal priority once they enter the viewport.
+- **RECOMMENDED**: Avoid using `fetchpriority="auto"`. If you want the default priority, omit the attribute entirely to keep your HTML clean.
+- **DO NOT** combine `fetchpriority="high"` with `loading="lazy"`.
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority` and is not supported by any browser.
+- **DO NOT** use the deprecated `loading="auto"` value. It was initially supported by Chrome but has been removed and is not supported by any browser.
+
+## Fallback strategy
+
+Baseline status for Fetch priority: Newly available. It's been Baseline since 2024-10-29.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 132 (Oct 2024), and Safari 17.2 (Dec 2023).
+
+The `fetchpriority` attribute is a progressive enhancement for the `<img>` element. If a browser does not support it, the attribute is ignored, and the browser uses its default priority heuristics.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-preload-priority.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-preload-priority.md
new file mode 100644
index 00000000..cf317756
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-preload-priority.md
@@ -0,0 +1,41 @@
+# Optimize preload priority
+
+Preloading resources with `<link rel="preload">` signals to the browser that a resource will be needed soon. However, preloads inherit the default priority for the resource type and for images in particular this is low. Using `fetchpriority` allows you to refine this relative priority, in particular ensuring image preloads are preloaded with a high priority allowing them to start earlier and use get more bandwidth resources.
+
+## How to implement
+
+1. **Identify preload candidates**: Find resources that are not discovered early by the browser (e.g., video poster images or background images in CSS) but are essential for the page's appearance.
+2. **Elevate critical image preloads**: For the LCP image or other critical images that are not prioritized by default, use `<link rel="preload" fetchpriority="high">` to ensure they are prioritized above other preloads. Note that fonts are already high priority by default.
+3. **Deprioritize non-critical preloads**: For resources that aren't critical for the initial render (e.g., a background video or secondary fonts), use `<link rel="preload" fetchpriority="low">`.
+4. **Coordinate with resource types**: Note that different `as` types have different default priorities; use `fetchpriority` to override these defaults when necessary.
+
+## Example code
+
+```html
+<!-- Elevate priority for a video poster image that acts as the LCP candidate -->
+<link rel="preload" href="/images/video-poster.jpg" as="image" fetchpriority="high">
+
+<!-- Elevate priority for a critical LCP image that is hidden in CSS -->
+<link rel="preload" href="/images/hero-background.jpg" as="image" fetchpriority="high">
+
+<!-- Deprioritize a secondary font to avoid network contention -->
+<link rel="preload" href="/fonts/secondary-font.woff2" as="font" type="font/woff2" fetchpriority="low" crossorigin>
+```
+
+## Best Practices
+
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical image preloads to avoid network contention and diluting the priority boost.
+- **MANDATORY**: Use `fetchpriority="high"` on Largest Contentful Paint (LCP) images.
+- **DO**: Limit the total number of preloads on a page to at most 2 images and 2-3 essential fonts to prevent bandwidth contention.
+- **DO** use `fetchpriority="low"` for preloads that you want the browser to start early but not at the expense of critical resources (especially non-critical fonts).
+- **DO** specify the `as` attribute correctly to ensure the preload will be used.
+- **DO** prefer making critical resources (like LCP images) statically discoverable in HTML via `<img>` tags rather than relying on preloads for background images.
+- **DO** ensure that font preloads always have the `crossorigin` attribute (even if same-origin).
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority`.
+
+## Fallback strategy
+
+Baseline status for Fetch priority: Newly available. It's been Baseline since 2024-10-29.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 132 (Oct 2024), and Safari 17.2 (Dec 2023).
+
+The `fetchpriority` attribute on `<link rel="preload">` is a progressive enhancement. Browsers that do not support it will still preload the resource using their default priority for that resource type. To ensure compatibility, always provide correct `as` and `type` attributes.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-script-priority.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-script-priority.md
new file mode 100644
index 00000000..ed5cad7e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/optimize-script-priority.md
@@ -0,0 +1,38 @@
+# Optimize script priority
+
+Browsers assign default priorities to scripts based on where they appear in the document and whether they have attributes like `async` or `defer`. Using `fetchpriority` gives developers explicit control to ensure critical scripts load first, while non-essential scripts stay out of the way.
+
+## How to implement
+
+1. **Identify critical scripts**: Determine which scripts are essential for the page's core functionality or initial user interaction.
+2. **Elevate critical async scripts**: For critical scripts loaded with `async` or `defer`, add the `fetchpriority="high"` attribute to ensure they are prioritized during the discovery phase.
+3. **Deprioritize non-essential scripts**: For scripts that are not needed immediately (e.g., analytics, ads, or below-the-fold widgets), add `fetchpriority="low"` and ensure they have a `async`, `defer`, or `module` attribute to avoid blocking.
+4. **Sequence parser-blocking scripts**: Use `fetchpriority="low"` on parser-blocking scripts at the end of the body to prevent them from contending for bandwidth with more critical resources.
+
+## Example code
+
+```html
+<!-- Elevate the priority of the critical app logic -->
+<script src="/js/app.js" async fetchpriority="high"></script>
+
+<!-- Deprioritize non-essential tracking scripts -->
+<script src="/js/tracker.js" async fetchpriority="low"></script>
+
+<!-- Deprioritize late-body scripts to favor critical images or CSS -->
+<script src="/js/legacy-widgets.js" fetchpriority="low"></script>
+```
+
+## Best Practices
+
+- **MANDATORY**: Only use `fetchpriority="high"` on at most 1-2 critical scripts to avoid network contention and diluting the priority boost.
+- **DO** use `fetchpriority="high"` specifically for `async` scripts that are known to be critical for Interaction to Next Paint (INP).
+- **DO** deprioritize scripts that are not required for the initial user experience using `fetchpriority="low"`.
+- **DO NOT** use `fetchpriority` on every script tag; it should only be used to change the browser's default heuristic when it is known to be sub-optimal.
+- **DO NOT** use the deprecated `importance` attribute. It has been replaced by `fetchpriority`.
+
+## Fallback strategy
+
+Baseline status for Fetch priority: Newly available. It's been Baseline since 2024-10-29.
+Supported by: Chrome 103 (Jun 2022), Edge 103 (Jun 2022), Firefox 132 (Oct 2024), and Safari 17.2 (Dec 2023).
+
+The `fetchpriority` attribute is a progressive enhancement. Browsers that do not support it will ignore the attribute and use their internal scheduling logic without error. No explicit feature detection or fallback logic is required for basic usage.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/out-of-order-html-streaming.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/out-of-order-html-streaming.md
new file mode 100644
index 00000000..4d9ecc5c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/out-of-order-html-streaming.md
@@ -0,0 +1,144 @@
+# Out-of-Order (OOO) HTML Streaming
+
+Out-of-Order (OOO) HTML Streaming (also known as Declarative Partial Updates) is an alternative to the traditional "top-to-bottom" linear processing of HTML. It allows developers to define placeholders earlier in a document and "patch" them with content that arrives later in the same network stream, or via new imperative JavaScript streaming APIs.
+
+## Quick Overview
+
+The feature consists of two primary mechanisms:
+
+1.  **Declarative Patching (HTML-based)**: Uses new processing instructions (`<?marker>`, `<?start>`, `<?end>`) and `<template for>` to swap content in the DOM as it streams in from the server.
+2.  **Imperative setting and streaming (JS-based)**: A suite of new methods (e.g., `streamHTML()`, `setHTMLUnsafe()`) that allow setting of HTML or piping readable streams directly into DOM elements with native performance and optional script execution.
+
+## Best Practices
+
+*   **Prioritize Above-the-Fold Content**: Stream critical UI (header, hero, primary navigation, primary content) first. Use placeholders for "expensive" or lower priority components like comments, ads, or related content.
+*   **Implement Native Loading States**: Use the `<?start>` and `<?end>` markers to wrap fallback content. The browser automatically replaces everything between these markers when the corresponding `<template for>` arrives.
+*   **Minimize Cumulative Layout Shift (CLS)**: Always provide stable dimensions for placeholders. If the final content size is unknown, use skeleton screens or CSS `aspect-ratio` to reserve space and prevent jarring shifts.
+*   **Accessibility & Focus Management**: Be mindful that out-of-order updates can confuse screen reader users. Use `aria-live` regions for critical updates and ensure that focus isn't lost if a placeholder containing the active element is replaced.
+
+## Implementation Details
+
+### 1. Declarative HTML Markers
+The browser looks for specific processing instructions to identify where content should be patched.
+
+```html
+<!-- A simple insertion point -->
+<div id="sidebar">
+  <?marker name="dynamic-comments">
+</div>
+
+<!-- A replacement range with loading state -->
+<main>
+  <?start name="main-content">
+    <div class="skeleton">Loading content...</div>
+  <?end>
+</main>
+
+... (other content) ...
+
+<!-- Later in the same stream, provide the content -->
+<template for="dynamic-comments">
+  <div class="comments">...</div>
+</template>
+
+<template for="main-content">
+  <article>
+    <h1>The Real Content</h1>
+    <p>This replaces the skeleton div automatically.</p>
+  </article>
+</template>
+```
+
+Once a `<template>` replaces an insertion point, that insertion point no longer exists, and can not be reused. However, a `<template>` may contain insertion points that can be used later in the stream.
+
+```html
+ <?start name="replaced-content">
+  <div class="skeleton">
+<?end>
+<!-- Later in the same stream, provide initial content -->
+<template for="replaced-content">
+  <?start name="replaced-content">
+    <div>Quickly computed result</div>
+  <?end>
+</template>
+<!-- Later in the same stream, provide full content -->
+<template for="replaced-content">
+  <?start name="replaced-content">
+    <div>Full result</div>
+  <?end>
+</template>
+```
+
+### 2. Imperative JS Streaming
+
+The browser provides a suite of 24 methods (6 actions, each with 4 variations) to update the DOM either statically (from a string) or via a stream.
+
+#### API Reference Matrix
+
+| Action | Static (Safe) | Streaming (Safe) | Static (Unsafe) | Streaming (Unsafe) |
+| :--- | :--- | :--- | :--- | :--- |
+| **Set** | `setHTML()` | `streamHTML()` | `setHTMLUnsafe()` | `streamHTMLUnsafe()` |
+| **Replace** | `replaceWithHTML()` | `streamReplaceWithHTML()` | `replaceWithHTMLUnsafe()` | `streamReplaceWithHTMLUnsafe()` |
+| **Before** | `beforeHTML()` | `streamBeforeHTML()` | `beforeHTMLUnsafe()` | `streamBeforeHTMLUnsafe()` |
+| **Prepend** | `prependHTML()` | `streamPrependHTML()` | `prependHTMLUnsafe()` | `streamPrependHTMLUnsafe()` |
+| **Append** | `appendHTML()` | `streamAppendHTML()` | `appendHTMLUnsafe()` | `streamAppendHTMLUnsafe()` |
+| **After** | `afterHTML()` | `streamAfterHTML()` | `afterHTMLUnsafe()` | `streamAfterHTMLUnsafe()` |
+
+#### Key Concepts
+
+*   **Safe vs. Unsafe**: 
+    *   **Safe** methods (e.g., `setHTML()`) use a built-in sanitizer by default to strip potentially dangerous content like `<script>` tags. You can pass a custom `Sanitizer` object in the options to apply in addition to the default sanitizer.
+    *   **Unsafe** methods (e.g., `setHTMLUnsafe()`) do not sanitize by default, but you can still pass a custom `Sanitizer`. To allow scripts to execute in the new content, you must explicitly pass `{ runScripts: true }` in the options. **IMPORTANT**: Only use unsafe methods with trusted content where safe methods would not work.
+*   **Static vs. Streaming**:
+    *   **Static** methods take a string (or `TrustedHTML`) and apply it immediately.
+    *   **Streaming** methods return a `WritableStream`. This allows you to pipe content (e.g., from a `fetch` response) directly into the DOM, and the browser will render it incrementally as chunks arrive.
+
+#### Example: Streaming a Fetch Response
+
+You can pipe fetch responses directly into the DOM without manual chunk handling.
+
+```javascript
+const main = document.querySelector('main');
+const response = await fetch('/api/partial-update');
+
+// Pipe the stream directly into the element
+await response.body
+  .pipeThrough(new TextDecoderStream())
+  .pipeTo(main.streamHTMLUnsafe({ runScripts: true }));
+
+// Or use the `textStream()` convenience method which streams directly without needing the intermediate `TextDecoderStream()` step
+await response
+  .textStream()
+  .pipeTo(main.streamHTMLUnsafe({ runScripts: true }))
+```
+
+## Use Case Reference Matrix
+
+*   **Island Architecture**: Hydrate independent interactive components on top of static HTML without a full framework runtime.
+*   **Deferred "Expensive" Blocks**: Deliver the shell of a page immediately and stream database-heavy components as they become available.
+*   **Single Page Application (SPA) Updates**: Stream large UI transitions in SPAs using `streamHTML()` instead of waiting for a full JSON payload and manual DOM construction.
+
+## Anti-Patterns & Warnings (DO NOT DO THIS)
+
+*   **Do not use OOO streaming for everything.** Over-fragmenting a page can increase the complexity of the stream and potentially delay content if the browser spends too much time patching small nodes.
+*   **Do not ignore Trusted Types.** When using `*Unsafe` methods in environments with Trusted Types enforced, ensure you are passing a sanitized policy object if required.
+*   **Do not assume script execution order.** Scripts inside a `<template for>` will execute as soon as they are patched into the document. Do not rely on them executing in a specific sequence relative to other deferred templates.
+*   **Do not use without a polyfill strategy.** Ensure you have a fallback or use polyfills (`html-setters-polyfill` and `template-for-polyfill`) to support your required browsers until this feature becomes Baseline.
+
+## Fallback strategies
+
+Browser support for <template for>: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+HTML setter methods is not natively supported by any major browser yet.
+
+HTML streaming setters is not natively supported by any major browser yet.
+
+Browser support for HTML processing instructions: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+You can use polyfills like `template-for-polyfill` and `html-setters-polyfill` to emulate the API surface for non-supporting browsers.
+
+Browsers without `html-processing-instructions` support parse `<?marker>`, `<?start>`, and `<?end>` as comments. `template-for-polyfill` still recognizes these comments as markers, so keep the same processing instruction syntax for all browsers. Do not rewrite the markers as HTML comments or elements for non-supporting browsers.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/performance.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/performance.md
new file mode 100644
index 00000000..32c6eccb
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/performance.md
@@ -0,0 +1,384 @@
+# Performance
+
+## Critical Rendering Path (CRP) Optimization
+
+The Critical Rendering Path dictates how quickly the browser converts HTML, CSS, and JavaScript into painted pixels. 
+
+### DOs
+*   **DO inline critical CSS**: Extract styles necessary for above-the-fold content and inject them directly into the HTML `<head>`. Defer the rest of the stylesheet.
+*   **DO use `async` or `defer` for all non-critical scripts**: Prevent JavaScript from blocking the DOM parser. Use `defer` for scripts that depend on the DOM or each other, and `async` for independent scripts. `type="module"` is preferred for modern JavaScript and is deferred by default so no need to have an explicit `defer` attribute but you can use `async` on independent module scripts.
+*   **DO split CSS by media queries**: Use the `media` attribute on `<link>` tags so the browser downloads unused stylesheets (e.g., print styles or desktop styles on mobile) without blocking the render.
+*   **DO utilize resource hints**: Add `preconnect` or `dns-prefetch` for essential third-party domains (e.g., font foundries or API endpoints) to establish early TLS handshakes.
+
+### DON'Ts
+*   **DON'T use `@import` in CSS**: This creates sequential request chains that delay the CSS Object Model (CSSOM) construction.
+*   **DON'T place large, non-critical JavaScript in the `<head>`**: This halts DOM construction until the script is downloaded, parsed, and executed.
+*   **DON'T load invisible or unreachable CSS/JS**: Ensure build tools apply tree-shaking and CSS minification to drop unreachable code before deployment.
+
+### Code Examples
+
+**HTML: Deferring Non-Critical CSS & Scripts**
+```html
+<!-- Inline critical styles directly in head -->
+<style>
+  body { margin: 0; font-family: system-ui; }
+  .hero { min-height: 100vh; }
+</style>
+
+<!-- Defer non-critical CSS -->
+<link rel="preload" href="non-critical.css" as="style" onload="this.onload=null;this.rel='stylesheet'">
+<noscript><link rel="stylesheet" href="non-critical.css"></noscript>
+
+<!-- Load CSS conditionally based on viewport -->
+<link rel="stylesheet" href="mobile.css" media="(max-width: 768px)">
+
+<!-- Defer JavaScript execution -->
+<script defer src="app-bundle.js"></script>
+```
+
+### The Resource Hint Navigator
+
+| Hint | Tool Use Case | Example |
+| :--- | :--- | :--- |
+| `preconnect` | Resolve TLS/DNS for known third-party APIs | API endpoints, font services |
+| `dns-prefetch` | Lean fallback for non-critical third-party origins | Ad servers, analytics fallbacks |
+| `preload` | Same-origin asset needed *now* for rendering | Hero images, render-blocking fonts |
+| `prefetch` | Assets needed for next-page navigation | Next-page bundle, detail views |
+
+**Single-Sentence Mental Model**: "Preconnect for domains, Preload for viewport, Prefetch for futures."
+
+## Largest Contentful Paint (LCP) & Resource Fetching
+
+LCP measures the time required to render the largest visible text or image block within the viewport. Optimize LCP by prioritizing visible elements and prepolishing.
+
+### DOs
+*   **DO declare the LCP image in standard HTML**: Ensure LCP images are present in the raw HTML response so the preload scanner discovers it immediately. This can be be via an `<img>` element (preferred) or a `<link rel="preload" as="image">` (where the image resource is loaded due to JavaScript or CSS). Avoid relying on JavaScript or CSS to be the only source of the image resource.
+*   **DO use `fetchpriority="high"` on the LCP images**: Images are not downloaded initially while the browser prioritizes render-blocking resources like CSS and JavaScript and can perform layout to discover if the images are in the viewport or not. Use `fetchpriority="high"` to signal to the browser's heuristic engine to start downloading the LCP image earlier. This should be on the `<img>` element (`<img fetchpriority="high">`) and any preload (`<link rel="preload" as="image" fetchpriority="high">`).
+*   **DO use `fetchpriority="low"` to demote competing elements that are not in the initial viewport**: Lower the priority of large images or carousels that are *not* the primary LCP element and do *not* appear in the initial viewport, but may still be downloaded if near the viewport or hidden with CSS (for example `overflow:scroll` for carousels). Images with `fetchpriority="low"` will still be downloaded but start after higher-priority resources the browser has queued.
+*   **DO use `loading="lazy"` to avoid loading competing elements that are far out of the initial viewport**: Images, iframes, and video and audio media which are well outside of the viewport should be lazy-loaded to avoid fetching these at all. Images with `loading="lazy"` will not be downloaded at all when well outside the viewport but will download when in, or near, the viewport (depending on browser heuristics and connection settings),.
+
+### DON'Ts
+*   **DON'T lazy-load the LCP image**: Never apply `loading="lazy"` to above-the-fold images. This purposefully delays the fetch until layout calculation is complete, severely degrading LCP.
+*   **DON'T overuse `fetchpriority="high"`**: Prioritization is a zero-sum mechanism. Elevating too many resources creates network contention and negates the benefit.
+*   **DON'T implement complex JavaScript loaders for the hero section**: Client-side rendering of the LCP element introduces substantial request chains (HTML -> JS -> Execution -> Image Request).
+
+### Code Examples
+
+**HTML: LCP Image Optimization**
+```html
+<!-- Standard LCP Image -->
+<img 
+  src="/images/hero.webp" 
+  alt="Hero Product" 
+  fetchpriority="high" 
+  width="1200" 
+  height="600"
+>
+
+<!-- Preloading a CSS-based LCP background -->
+<link rel="preload" as="image" href="/images/bg-hero.webp" fetchpriority="high" type="image/webp">
+
+<!-- Demoting an above-the-fold non-LCP carousel image -->
+<img src="/images/carousel-2.webp" fetchpriority="low" loading="lazy" alt="Slide 2">
+```
+
+## Interaction to Next Paint (INP) & Main Thread Unblocking
+
+INP measures the latency of all interactive events across the page's lifecycle. Poor INP is caused by long-running JavaScript tasks blocking the main thread. 
+
+### DOs
+*   **DO break up long tasks**: Any JavaScript execution exceeding 50ms should be split. Yield to the main thread frequently so the browser can process pending user inputs.
+*   **DO use `scheduler.yield()` with a fallback**: Utilize the modern `scheduler.yield()` API to place task continuations at the *front* of the queue, falling back to `setTimeout` wrapped in a Promise for unsupported browsers.
+*   **DO debounce or throttle rapid event listeners**: Limit the execution frequency of handlers attached to `scroll`, `resize`, or rapid `input` events.
+*   **DO separate UI updates from heavy computations**: Update the UI synchronously to provide immediate visual feedback, then push background processing to a Web Worker or deferred task.
+
+### DON'Ts
+*   **DON'T rely solely on `setTimeout(..., 0)` for continuous yielding**: Standard `setTimeout` places continuations at the *back* of the task queue, potentially causing long delays if other tasks are pending. Use `scheduler.yield()` where available.
+*   **DON'T cause layout thrashing**: Avoid interleaving DOM reads (`offsetHeight`, `getBoundingClientRect`) and writes (`style.height`) within the same loop. Batch DOM reads, then batch DOM writes.
+*   **DON'T block the thread with recurring timers**: Avoid heavy polling with `setInterval` that starves the main thread.
+
+### Code Examples
+
+**JS: `scheduler.yield` Polyfill and Usage**
+```javascript
+// Polyfill for yielding to main thread
+async function yieldToMain() {
+  if ('scheduler' in window && 'yield' in scheduler) {
+    return await scheduler.yield();
+  }
+  return new Promise(resolve => setTimeout(resolve, 0));
+}
+
+// Processing a large array without blocking user input
+async function processLargeList(items) {
+  for (let i = 0; i < items.length; i++) {
+    processItem(items[i]);
+    
+    // Yield every 50 iterations to allow rendering/interaction
+    if (i % 50 === 0) {
+      await yieldToMain();
+    }
+  }
+}
+```
+
+### Main Thread Task Slicing Heuristic
+
+**The 50ms Rule for INP**:
+- **< 50ms**: Execute synchronously.
+- **50ms - 250ms**: Slice tasks and yield with `scheduler.yield()`.
+- **> 250ms**: Offload to a Web Worker.
+
+## Third-Party Script Management
+
+Third-party scripts (analytics, ads, chat widgets) are the primary source of main thread congestion.
+
+### DOs
+*   **DO avoid third-party scripts blocking main content**: Use `defer` with all third-party scripts unless critical to the page load and load them in the footer of the page, rather than the `<head>`.
+*   **DO self-host critical third-party dependencies**: Reduce DNS lookups and enforce custom `Cache-Control` logic by hosting third-party libraries on the origin domain.
+
+### Code Examples
+
+**HTML: Third-Party Script Execution**
+```html
+<!-- 1. Place third-party scripts near the end of the page with the defer attribute -->
+<script defer src="http://www.example.com/third-party.js"></script>
+```
+
+## CSS Rendering & Containment Optimization
+
+Rendering involves Layout, Style, Paint, and Compositing calculations. CSS Containment limits the scope of these calculations which is useful on large, complex pages where such calculations can cause performance problems.
+
+### DOs
+*   **DO use `content-visibility: auto` on off-screen sections on large, complex pages**: Instruct the browser to skip layout and paint calculations for entire subtrees until they approach the viewport.
+*   **DO pair `content-visibility` with `contain-intrinsic-size`**: Prevent layout shifts and scrollbar jumping by providing a placeholder height/width for unrendered containers.
+*   **DO derive `contain-intrinsic-size` from the content**: When setting `contain-intrinsic-size` use the `auto` keyword and a value that's derived from what is known about the contents (i.e. text size, spacing, size of graphics, character count). Preferably use units such as `rem`, `lh`, `cap`, or `ch` that match values used for the elements within the contents rather than `px`. If the content for items in a group is not consistently sized, then use an average size.
+*   **DO apply explicit CSS containment (`contain`)**: For isolated UI components (like modals or widgets), use `contain: layout style paint` to prevent internal changes from triggering page-wide reflows.
+
+### DON'Ts
+*   **DON'T apply `content-visibility: auto` on smaller, simpler pages**: The gains will be negligible and there are risks of side effects with content jumping.
+*   **DON'T apply `content-visibility: auto` to above-the-fold content**: The browser will still evaluate it, but forcing it through the containment engine unnecessarily adds slight overhead to visible elements.
+*   **DON'T overuse `will-change` globally**: Indiscriminately applying `will-change: transform` to multiple elements consumes excessive VRAM, causing GPU crashes or sluggish rendering.
+*   **DON'T forget accessibility when hiding elements**: `content-visibility: auto` keeps elements in the DOM for screen readers. If content should be truly hidden from assistive technology when off-screen, manage `aria-hidden` attributes manually.
+
+### Code Examples
+
+**CSS: Content Visibility and Containment**
+```css
+/* Optimize a long list of articles below the fold */
+.article-list-item {
+  content-visibility: auto;
+  contain-intrinsic-size: auto 600px; /* Provides a 600px placeholder */
+}
+
+.row {
+  --row-gap: .4rem;
+  --title-height: 1lh;
+  --description-height: 0.85lh;
+
+  display: grid;
+  row-gap: var(--row-gap);
+  content-visibility: auto;
+  /* The sum of the title height, row gap, and description height should be the size of the contents when skipped for rendering. */
+  contain-intrinsic-block-size: auto calc(var(--title-height) + var(--row-gap) + var(--description-height));
+}
+
+/* Scope a complex widget to prevent layout thrashing */
+.isolated-widget {
+  contain: layout style paint;
+}
+
+/* Hardware accelerate an animation only on hover */
+.interactive-button:hover {
+  will-change: transform;
+  transform: scale(1.05);
+}
+```
+
+## Modern Image & Media Optimization
+
+Images typically represent the largest payload on a given web page. Optimization requires format negotiation, responsive sizing, and layout stabilization.
+
+### DOs
+*   **DO serve modern formats (AVIF / WebP / JPEG XL)**: Use the `<picture>` element to offer AVIF or JPEG XL (best compression), falling back to WebP, and finally JPEG/PNG for legacy browsers.
+*   **DO apply explicit `width` and `height` attributes**: Setting native attributes allows the browser to compute the aspect ratio immediately, reserving space and eliminating CLS. Image dimensions may be set either as HTML attributes or CSS properties.
+*   **DO utilize `loading="lazy"` on all below-the-fold images**: Utilize native browser lazy loading to defer network requests for images outside the initial viewport.
+*   **DO implement responsive images with `srcset` and `sizes`**: Serve tailored resolutions based on screen density and viewport width to prevent mobile devices from downloading desktop-sized images.
+
+### DON'Ts
+*   **DON'T lazy load above-the-fold images**: This directly harms LCP. Visible images must use `loading="eager"` (the default).
+*   **DON'T delete necessary dimensions**: Failing to specify width/height on lazy loaded images causes layout shifts.
+*   **DON'T omit the `sizes` attribute when using `srcset`**: Without `sizes`, the browser assumes `100vw` and downloads the largest available image.
+
+### Code Examples
+
+**HTML: Comprehensive Responsive Image Component**
+```html
+<picture>
+  <!-- Modern Formats with Source Negotiation -->
+  <source type="image/avif" srcset="hero-400w.avif 400w, hero-800w.avif 800w" sizes="(max-width: 600px) 100vw, 50vw">
+  <source type="image/webp" srcset="hero-400w.webp 400w, hero-800w.webp 800w" sizes="(max-width: 600px) 100vw, 50vw">
+  
+  <!-- Fallback + Dimensions + Priority for Above-The-Fold -->
+  <img 
+    src="hero-800w.jpg" 
+    alt="Descriptive text" 
+    width="800" 
+    height="600"
+    fetchpriority="high"
+    loading="eager"
+  >
+</picture>
+
+<!-- Below-The-Fold Image -->
+<img 
+    src="footer-icon.png" 
+    alt="Footer Logo" 
+    width="100" 
+    height="100"
+    loading="lazy"
+>
+
+<!-- DO: Use native lazy loading for below the fold iframes -->
+<iframe src="https://example.com/map" width="800" height="600" loading="lazy" title="Example Map"></iframe>
+```
+
+## Service Workers & Caching Strategies
+
+Client-side caching via Service Workers allows applications to bypass the network entirely, serving resources from disk/memory.
+
+### DOs
+*   **DO use a `CacheFirst` strategy for static, versioned assets**: Immutable files (fonts, JS/CSS bundles with hash strings) should be served directly from the cache to guarantee instant loading.
+*   **DO use `StaleWhileRevalidate` for dynamic, non-critical resources**: For API calls where slight staleness is acceptable, serve immediately from cache while silently updating the cache in the background.
+*   **DO implement a `NetworkFirst` strategy for HTML documents**: Ensure the user always receives the latest application shell and manifest, falling back to cache only if offline.
+*   **DO restrict cache sizes and expiry**: Use expiration plugins to prevent the Service Worker from exhausting the device's storage quota.
+
+### DON'Ts
+*   **DON'T cache opaque responses blindly**: Responses from third-party domains lacking CORS headers are "opaque". Caching them heavily consumes quota and fails silently. Only cache them using `NetworkFirst` or `StaleWhileRevalidate`.
+*   **DON'T cache POST requests**: Service workers cannot cache non-GET requests natively. Implement background sync queues for offline submissions.
+*   **DON'T bypass versioning**: Failing to update asset hashes/versions will trap users in infinite cache loops.
+*   **DON'T use `Cache-Control: no-store` for non-sensitive resources**: This directive prevents the browser from storing the page in the **Back-Forward Cache (bfcache)**, leading to significantly slower perceived performance. Use it only for truly private data, and use `Cache-Control: no-cache` or `Cache-Control: max-age=0` for pages that simply need to serve up-to-date content.
+
+### Code Examples
+
+**JS: Service Worker Caching via Workbox**
+```javascript
+import { registerRoute } from 'workbox-routing';
+import { CacheFirst, StaleWhileRevalidate, NetworkFirst } from 'workbox-strategies';
+import { ExpirationPlugin } from 'workbox-expiration';
+import { CacheableResponsePlugin } from 'workbox-cacheable-response';
+
+// 1. HTML Documents: Network First
+registerRoute(
+  ({ request }) => request.mode === 'navigate',
+  new NetworkFirst({ cacheName: 'pages-cache' })
+);
+
+// 2. Static Assets (JS, CSS, Fonts): Cache First
+registerRoute(
+  ({ request }) => ['style', 'script', 'font'].includes(request.destination),
+  new CacheFirst({
+    cacheName: 'static-resources',
+    plugins: [
+      new CacheableResponsePlugin({ statuses: [0, 200] }),
+      new ExpirationPlugin({ maxEntries: 50, maxAgeSeconds: 30 * 24 * 60 * 60 })
+    ]
+  })
+);
+
+// 3. API Responses: Stale While Revalidate
+registerRoute(
+  ({ url }) => url.pathname.startsWith('/api/v1/content'),
+  new StaleWhileRevalidate({
+    cacheName: 'api-cache',
+    plugins: [
+      new CacheableResponsePlugin({ statuses: [0, 200] })
+    ]
+  })
+);
+```
+
+## Web Fonts Optimization
+
+Web fonts are a common source of render blocking. Optimizing them reduces the Flash of Invisible Text (FOIT) and speeds up initial rendering.
+
+### DOs
+*   **DO preload critical fonts**: Use `<link rel="preload" as="font" type="font/woff2" crossorigin>` for fonts seen above the fold. Do include the `crossorigin` attribute for all fonts (even same origin fonts).
+*   **DO subset fonts**: Trim font weights and glyph variations to include only the characters your application requires.
+
+### DON'Ts
+*   **DON'T preload all fonts**: Over-preloading leads to network contention that starves other critical assets.
+*   **DON'T use `fetchpriority="high"` on fonts**: Fonts are loaded with a high priority by default so there is no need to specify `fetchpriority="high"`.
+
+### Code Examples
+
+**CSS: Font Loading Face**
+```css
+@font-face {
+  font-family: 'Modern Sans';
+  src: url('/fonts/modern-sans.woff2') format('woff2');
+}
+```
+
+**HTML: Critical Font Preload**
+```html
+<!-- Always use crossorigin for fonts even if on the same origin -->
+<link rel="preload" href="/fonts/modern-sans.woff2" as="font" type="font/woff2" crossorigin>
+```
+
+## Video Performance & Metrics
+
+Video payloads are among the heaviest assets. Optimization focuses on reducing bandwidth stall and preserving Cumulative Layout Shift (CLS) stability.
+
+### DOs
+*   **DO specify explicit `width` and `height` attributes**: Setting native dimensions reserves layout space and prevents CLS.
+*   **DO provide a `poster` image fallback**: Display a lightweight image placeholder while the video buffers to improve perceived performance.
+*   **DO use `<link rel="preload" as="image" fetchpriority="high">` for poster images where the video is the LCP element**: This ensures the image is downloaded as quickly as possible.
+*   **DO use `preload="none"` for non-critical videos**: Delay bandwidth consumption for below-the-fold or non-autoplaying videos.
+*   **DO serve modern formats via source negotiation**: Offer WebM (better compression ratio) alongside standard MP4 formats.
+*   **DO use `loading="lazy"` for offscreen videos**: Lazy-loading videos allow `poster` and `preload` downloads to be deferred until the video is in or near the viewport.
+
+### DON'Ts
+*   **DON'T auto-play video files blindly**: Rely on user intent or use progressive enhancement streams.
+*   **DON'T auto-play large video files at all**: Rely on user intent before downloading large files.
+
+### Code Examples
+
+**HTML: Accessible and Dynamic Video Loader**
+```html
+<video 
+  controls 
+  width="1200" 
+  height="675"
+  poster="/images/video-poster.webp" 
+  preload="none"
+  loading="lazy"
+>
+  <source src="/videos/intro.webm" type="video/webm">
+  <source src="/videos/intro.mp4" type="video/mp4">
+  <!-- Include accessibility tracks -->
+  <track src="/video-caps.vtt" kind="captions" srclang="en" label="English">
+</video>
+```
+
+## JavaScript Code-Splitting
+
+Heavy monolithic bundles block main thread parse times on low-end devices. Splitting ensures we only download bytes required for the immediate viewport.
+
+### DOs
+*   **DO use dynamic imports**: Split routes or heavy UI libraries using standard `import()` specifications.
+*   **DO configure bundler asset chunking**: Use Vite or Webpack rollup directives to split third-party vendors from runtime application logic.
+
+### DON'Ts
+*   **DON'T ship a single, enormous `app.js` bundle**: It increases parse time and memory consumption for initial views.
+
+### Code Examples
+
+**JS: Route based Dynamic Splitting**
+```javascript
+// Dynamic import of heavy module only when button is clicked
+document.getElementById('heavy-btn').addEventListener('click', async () => {
+  const { heavyFunction } = await import('./heavy-module.js');
+  heavyFunction();
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/resolution-optimized-pseudo-elements.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/resolution-optimized-pseudo-elements.md
new file mode 100644
index 00000000..da5f76d5
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/resolution-optimized-pseudo-elements.md
@@ -0,0 +1,49 @@
+# Resolution Optimized Pseudo Elements
+
+Using resolution-optimized images in CSS pseudo-elements (like `::before` or `::after`) allows you to add decorative icons or structural graphics without cluttering your HTML with extra DOM nodes. By combining pseudo-elements with the `image-set()` CSS function, you can provide the browser with multiple formats (such as AVIF or WebP) and resolutions (like `1x` and `2x`). The browser will automatically choose the most optimal image for the user's device capabilities.
+
+### Implementation
+
+You can use the `image-set()` function directly within the `content` property of a pseudo-element, or within its `background-image` property (while setting `content: ""`). Note that while providing both the image format via `type()` and the resolution (like `1x` or `2x`) yields the best results, both of these arguments are optional.
+
+```css
+.icon-button::before {
+  /* Using image-set directly in the content property */
+  /* MANDATORY: Always order your formats from most optimized (AVIF) to least optimized (JPEG/PNG). 
+     The browser will stop at the first supported format. */
+  content: image-set(
+    url("icon.avif") type("image/avif") 1x,
+    url("icon-2x.avif") type("image/avif") 2x,
+    url("icon.webp") type("image/webp") 1x,
+    url("icon-2x.webp") type("image/webp") 2x,
+    url("icon.png") type("image/png") 1x,
+    url("icon-2x.png") type("image/png") 2x
+  );
+  
+  display: inline-block;
+  margin-right: 8px;
+  vertical-align: middle;
+}
+```
+
+### Fallback strategies
+
+Baseline status for image-set(): Widely available. It's been Baseline since 2023-09-18.
+Supported by: Chrome 113 (May 2023), Edge 113 (May 2023), Firefox 89 (Jun 2021), and Safari 17 (Sep 2023).
+
+For older browsers that do not support the `image-set()` function, you **MUST** provide a standard image declaration *before* the `image-set()` rule. This progressive enhancement strategy relies on CSS's cascading nature: unsupported rules are ignored.
+
+```css
+.icon-button::before {
+  /* MANDATORY: Fallback for browsers that do not support image-set() */
+  content: url("icon.png");
+  
+  /* Modern browsers will apply this and override the fallback */
+  content: image-set(
+    url("icon.avif") type("image/avif") 1x,
+    url("icon-2x.avif") type("image/avif") 2x,
+    url("icon.png") type("image/png") 1x,
+    url("icon-2x.png") type("image/png") 2x
+  );
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/schedule-tasks-by-priority.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/schedule-tasks-by-priority.md
new file mode 100644
index 00000000..c269d6b9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/performance/schedule-tasks-by-priority.md
@@ -0,0 +1,61 @@
+# Schedule Tasks By Priority
+
+When building complex web applications, tasks have different levels of urgency. Completing tasks for the current view is more important than sending analytics or prefetching assets. The Prioritized Task Scheduling API allows you to schedule work with specific priorities, ensuring the browser remains responsive to user input.
+
+### Scheduling tasks by priority
+
+Use `scheduler.postTask()` to schedule tasks with one of three priorities:
+- `user-blocking`: Tasks that block user interaction (e.g., input handling, critical rendering).
+- `user-visible`: Tasks visible to the user but not blocking (default).
+- `background`: Tasks that are not time-critical (e.g., analytics, prefetching).
+
+```javascript
+// Schedule a high-priority task that blocks user interaction
+scheduler.postTask(() => {
+  // DO: Handle critical updates that impact user interaction
+  handleCriticalUpdate();
+}, { priority: 'user-blocking' });
+
+// Schedule a default priority task
+scheduler.postTask(() => {
+  // DO: Render non-critical content that is visible to the user
+  renderSecondaryContent();
+}); // Defaults to 'user-visible'
+
+// Schedule a low-priority background task
+scheduler.postTask(() => {
+  // DO: Perform heavy background work that is not time-critical
+  sendAnalytics();
+}, { priority: 'background' });
+```
+
+### Fallback strategies
+
+Browser support for Scheduler API: Limited availability.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), and Firefox 142 (Aug 2025).
+Unsupported in: Safari.
+
+To support browsers that do not have the Prioritized Task Scheduling API, you must use a polyfill to maintain task prioritization.
+
+```javascript
+// Feature detect the scheduler API
+if (!('scheduler' in window && 'postTask' in window.scheduler)) {
+  // DO: Conditionally load the polyfill for browsers that need it
+  const script = document.createElement('script');
+  script.src = 'https://unpkg.com/scheduler-polyfill';
+  script.onload = () => {
+    // Polyfill is loaded and ready to use
+    runScheduledTasks();
+  };
+  document.head.appendChild(script);
+} else {
+  runScheduledTasks();
+}
+
+function runScheduledTasks() {
+  // Now safe to use scheduler.postTask in all browsers
+  scheduler.postTask(() => {
+    console.log('Task with priority support');
+  }, { priority: 'background' });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/privacy/privacy.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/privacy/privacy.md
new file mode 100644
index 00000000..c6fe3610
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/privacy/privacy.md
@@ -0,0 +1,247 @@
+# Web Privacy Guidelines for Developers
+
+Web application developers must treat privacy as a foundational architectural requirement, not just a legal compliance checkbox. As the web ecosystem shifts away from passive tracking toward explicit, user-consented interactions, building privacy-preserving applications is critical for user trust and security.
+
+This document provides high-level principles and detailed, actionable guidelines with code examples for web developers.
+
+## High-Level Overview
+
+These core themes should guide your approach to privacy in web development:
+
+1.  **Automation Asymmetry & Privacy Labor**: Do not offload the burden of protecting privacy to the user (privacy labor). Avoid overwhelming users with complex consent dialogs (automation asymmetry). Users have limited time and attention; offloading privacy choices to them is often ineffective and causes fatigue. Systems should be privacy-protective by default.
+2.  **Data Minimization**: "If you don't have the data, you can't lose it." Collect only the bare minimum required for the immediate task. Reducing data storage reduces the risk of breach and builds user trust.
+3.  **Purpose Limitation**: Data collected for one purpose must not be used for another without fresh consent. Repurposing data without explicit agreement violates the trust relationship with the user.
+4.  **Transparency by Default**: Be honest and clear about why data is collected, where it goes, and how long it is kept. Transparency builds trust and can be a unique selling point for your application.
+5.  **Trustworthy Agency**: Treat your application as an agent acting in the user's best interest. This means protecting them from intrusive behaviors, unnecessary data exposure, and acting as a loyal fiduciary to the user rather than serving third-party interests.
+
+## Detailed Guidelines
+
+### 1. Data Minimization and Purpose Limitation
+
+Reducing the amount of data collected and strictly limiting its use is the most effective way to protect user privacy.
+
+#### DOs:
+*   **DO** collect data at the lowest granularity necessary. If you only need to know if a user is in a certain age bracket (e.g., 18-34), ask for the bracket, not the exact date of birth.
+*   **DO** provide guest checkout options for e-commerce to avoid forced account creation, which reduces data collection and cart abandonment.
+*   **DO** delete data as soon as the purpose for its collection has been fulfilled.
+*   **DO** use techniques like "fuzzing" or adding noise to data (Differential Privacy) when gathering aggregate statistics.
+
+#### DON'Ts:
+*   **DON'T** collect data speculatively "just in case" it might be useful in the future.
+*   **DON'T** reuse data collected for one purpose (e.g., security verification) for another (e.g., marketing) without explicit user consent.
+
+#### Code Examples:
+
+**Fuzzing Data Collection (HTML/JS)**
+Instead of asking for exact age:
+```html
+<label for="age-bracket">Age Bracket:</label>
+<select id="age-bracket" name="age-bracket">
+  <option value="18-34">18-34</option>
+  <option value="35-49">35-49</option>
+  <option value="50+">50+</option>
+</select>
+```
+
+### 2. Transparency and Trust
+
+Build trust by being open about your data practices and providing easy ways for users to control their data.
+
+#### DOs:
+*   **DO** provide inline explanations for why data is requested. Place the explanation directly next to the input field.
+*   **DO** provide a clear reason and context *before* requesting powerful browser permissions (e.g., camera, location).
+*   **DO** consider using the **Page Embedded Permission Control (PEPC)** `<permission>` element, if supported, to make permission requests declarative, user-initiated, and act as data mediators.
+*   **DO** use the `Clear-Site-Data` header when a user logs out to ensure no lingering data remains in the browser.
+*   **DO** make it as easy to opt-out or delete an account as it was to sign up.
+
+#### DON'Ts:
+*   **DON'T** bury data collection explanations in long, complex privacy policies.
+*   **DON'T** use deceptive patterns (dark patterns) to trick users into giving consent.
+
+#### Code Examples:
+
+**Inline Transparency (HTML)**
+```html
+<div>
+  <label for="phone">Phone Number (Optional)</label>
+  <input id="phone" type="tel" name="phone">
+  <a href="#phone-help">Why do we ask for this?</a>
+  <aside id="phone-help">
+    We only use your phone number to send two-factor authentication codes for account security.
+  </aside>
+</div>
+```
+
+**Clear-Site-Data on Logout (HTTP Response)**
+```http
+HTTP/1.1 200 OK
+Clear-Site-Data: "*"
+```
+*Note: If clearing the cache, avoid sending this on the main navigation page to prevent blocking UI rendering on slow devices; trigger it via a subresource.*
+
+**Page Embedded Permission Control (HTML)**
+```html
+<!-- Declarative permission element with fallback -->
+<permission type="geolocation" onpromptdismiss="updateMap()">
+  <!-- Fallback for unsupported browsers -->
+  <button onclick="navigator.geolocation.getCurrentPosition(updateMap)">
+    Use my location
+  </button>
+</permission>
+```
+
+### 3. Security and Data Handling for Privacy
+ 
+Privacy relies on a foundation of secure coding. Vulnerabilities in the application or insecure storage directly lead to privacy violations.
+ 
+#### DOs:
+*   **DO** scrub Personally Identifiable Information (PII) from application logs. Use automated masking for emails, tokens, and IDs.
+*   **DO** use `HttpOnly` flags for cookies storing session identifiers to prevent other scripts from accessing them.
+*   **DO** implement rate limiting on sensitive endpoints (e.g., user search or profile views) to prevent bulk data scraping.
+*   **DO** use **CHIPS (Cookies Having Independent Partitioned State)** by appending the `Partitioned` attribute for 1:1 embeds that do not share state across top-level sites.
+ 
+#### DON'Ts:
+*   **DON'T** store sensitive tokens or PII in `localStorage`, as it is accessible by any embedded script.
+*   **DON'T** rely on unpartitioned `SameSite=None` cookies.
+ 
+#### Code Examples:
+ 
+**Secure Session Cookie (HTTP)**
+```http
+Set-Cookie: session_id=xyz123; Secure; HttpOnly; SameSite=Lax
+```
+
+**CHIPS Cookie (HTTP)**
+```http
+Set-Cookie: theme_pref=dark; SameSite=None; Secure; Path=/; Partitioned; HttpOnly
+```
+
+### 4. Third-Party Audits and Mitigations
+
+Third-party scripts and resources are a common source of privacy leaks. You are responsible for the third parties you bring into your application.
+
+#### DOs:
+*   **DO** conduct regular technical audits of network requests using DevTools or HAR files to identify what data third parties are collecting.
+*   **DO** use the **Façade Pattern** for heavy embeds (like YouTube or TikTok). Display a static thumbnail and load the interactive iframe only after the user clicks.
+*   **DO** use privacy-preserving options for embeds when available (e.g., `youtube-nocookie.com`).
+*   **DO** replace heavy social sharing SDKs with simple, static HTML links that do not track users.
+*   **DO** use the **Federated Credential Management API (FedCM)** to mediate "Sign-In" flows natively, preventing IdP tracking of Relying Parties prior to user consent.
+
+#### DON'Ts:
+*   **DON'T** assume a third party is privacy-safe just because it is popular.
+*   **DON'T** load third-party scripts on pages where sensitive data (like checkout or health info) is handled unless strictly necessary.
+
+#### Code Examples:
+
+**Privacy-Preserving Social Sharing (HTML)**
+```html
+<!-- No JS SDK required -->
+<a href="https://x.com/intent/tweet?text=Check%20this%20out&url=https%3A%2F%2Fexample.com" 
+   rel="noopener" target="_blank">
+   Share on X
+</a>
+```
+
+**Video Façade Pattern (HTML/JS)**
+```html
+<div id="video-container" data-video-id="abc123">
+  <img src="https://img.youtube.com/vi/abc123/maxresdefault.jpg" alt="Play Video" id="play-btn">
+</div>
+
+<script>
+document.getElementById('play-btn').addEventListener('click', function() {
+  const container = document.getElementById('video-container');
+  const videoId = container.dataset.videoId;
+  container.innerHTML = `<iframe src="https://www.youtube-nocookie.com/embed/${videoId}?autoplay=1" allowfullscreen></iframe>`;
+});
+</script>
+```
+
+**FedCM Sign-In (JavaScript)**
+```javascript
+try {
+  const credential = await navigator.credentials.get({
+    identity: {
+      providers: [{
+        configURL: "https://idp.example/fedcm.json",
+        clientId: "rp-client-id-123",
+        nonce: "a_secure_random_nonce_value"
+      }]
+    }
+  });
+  authenticateWithBackend(credential.token);
+} catch (error) {
+  // Handle FedCM login failure
+}
+```
+
+### 5. Privacy-Preserving Headers
+
+Use standard HTTP headers to instruct the browser to enforce privacy boundaries.
+
+#### DOs:
+*   **DO** use `Permissions-Policy` to disable powerful features (like camera, microphone, geolocation) by default, enabling them only where required.
+*   **DO** set a strict `Referrer-Policy` to prevent leaking sensitive URL parameters to third parties.
+
+#### Code Examples:
+
+**Strict Referrer Policy (HTTP)**
+```http
+Referrer-Policy: strict-origin-when-cross-origin
+```
+
+**Defensive Permissions Policy (HTTP)**
+Disables powerful features for all origins by default.
+```http
+Permissions-Policy: geolocation=(), camera=(), microphone=(), accelerometer=()
+```
+
+### 6. Fingerprinting and User-Agent Reduction
+
+Avoid techniques that attempt to uniquely identify users covertly based on their device configuration. Fingerprinting takes away user control because it relies on unchanging characteristics and happens invisibly, preventing users from opting out or clearing their identifier.
+
+#### DOs:
+*   **DO** use **Feature Detection** instead of User-Agent sniffing to determine if a browser supports a capability.
+*   **DO** use **User-Agent Client Hints** (UA-CH) if supported by the browser, when specific device targeting is required.
+
+#### DON'Ts:
+*   **DON'T** use canvas rendering, font lists, or audio/video device enumerations to build a device fingerprint.
+*   **DON'T** rely on the full granularity of the traditional `navigator.userAgent` string.
+
+#### Code Examples:
+
+**Feature Detection (JavaScript)**
+```javascript
+// GOOD: Check if the API exists
+if ('IntersectionObserver' in window) {
+  const observer = new IntersectionObserver(...);
+} else {
+  // Fallback
+}
+
+// BAD: Sniffing UA
+// if (navigator.userAgent.includes("Chrome/100")) ...
+```
+
+**User-Agent Client Hints (JavaScript)**
+```javascript
+if (navigator.userAgentData) {
+  navigator.userAgentData.getHighEntropyValues(["platformVersion", "architecture"])
+    .then(ua => {
+      console.log(ua.platformVersion);
+    });
+}
+```
+
+### 7. Data Rights and User Control
+
+Empower users to exercise their rights over their personal data.
+
+#### DOs:
+*   **DO** provide clear mechanisms for users to **access** all data you have collected about them.
+*   **DO** implement automated or easy manual flows for **data deletion** (erasure).
+*   **DO** allow users to correct inaccurate information associated with their identity.
+
+#### DON'Ts:
+*   **DON'T** make the deletion process difficult or require users to contact support if sign-up was automated.
+*   **DON'T** retaliate against users who exercise their data rights by denying access to non-dependent services.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/pwa/migrate-web-app-origin.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/pwa/migrate-web-app-origin.md
new file mode 100644
index 00000000..ca2b1d7a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/pwa/migrate-web-app-origin.md
@@ -0,0 +1,98 @@
+# Migrating the Origin of an Installed Web App
+
+Transferring an installed web app (PWA) to a new origin typically requires users to manually uninstall the old app and reinstall the new one. This process usually causes the loss of OS-level integration, such as taskbar shortcuts and notification permissions. Web App Origin Migration automates this transition by establishing a secure handover between the old and new origins.
+
+The migration is a two-step verification process: the new site claims the old site as its predecessor, and the old site authorizes the new site as its successor.
+
+### Important Constraints
+
+> [!WARNING]
+> **Data and Permissions are NOT migrated.**
+> This feature only migrates the **installation** (shortcuts, home screen icons). User data (LocalStorage, IndexedDB, Cookies) and browser permissions (Notifications, Geolocation) are tied to the origin and are NOT transferred. You must migrate data separately using cross-origin messaging or server-side synchronization.
+
+## Implementation steps
+
+### 1. Verification of "Same-Site" status
+
+MANDATORY: Both the new and old origins MUST be **"Same-Site"**. They must share the same **Registrable Domain (eTLD+1)**.
+
+*   **Allowed**: Migrating from `app.example.com` to `new.example.com` (both share `example.com`).
+*   **Allowed**: Migrating from `example.com/app1` to `example.com/app2`.
+*   **Prohibited**: Migrating from `example.com` to `example.org` (different registrable domains).
+
+### 2. Configure the new application
+
+The new application must declare its predecessor. The new app must have an `id`.
+
+In the **new** site's `manifest.json`, add the `migrate_from` field:
+
+```json
+{
+  "name": "My New App",
+  "id": "/demo.html",
+  "start_url": "/demo.html",
+  "migrate_from": [
+    {
+      "id": "https://old-app.example.com/"
+    }
+  ]
+}
+```
+
+### 3. Authorize the migration on the old origin
+
+The old origin must explicitly authorize the migration to prevent origin hijacking. Create a configuration file served from the `.well-known` directory.
+
+File location: `https://old-app.example.com/.well-known/web-app-origin-association`
+
+```json
+{
+  "https://new-app.example.com": {
+    "allow_migration": true
+  }
+}
+```
+
+### 4. Proactively signal the migration (Optional)
+
+To trigger the migration immediately for existing users without waiting for them to visit the new site, update the **old** site's manifest with a `migrate_to` hint.
+
+```json
+{
+  "migrate_to": [
+    {
+      "id": "https://new-app.example.com/",
+      "install_url": "https://new-app.example.com/demo.html"
+    }
+  ]
+}
+```
+
+### 5. Require users to migrate (Optional)
+
+By default, a migration is suggested to users. To make the transition mandatory, set the `behavior` to `force` in the **new** app's manifest.
+
+```json
+{
+  "migrate_from": [
+    {
+      "id": "https://old-app.example.com/",
+      "behavior": "force"
+    }
+  ]
+}
+```
+
+**Note**: `behavior: "force"` does not silently delete the old app. The browser will present the user with a dialog requiring them to either **Update** to the new version or **Remove** the app entirely.
+
+## Fallbacks & browser support
+
+Browser support for Web app origin migration: Limited availability.
+Supported by: Chrome 149 (Jun 2026) and Edge 149 (Jun 2026).
+Unsupported in: Firefox and Safari.
+
+### Manual reinstallation prompt
+
+For browsers that do not support automatic migration, the user will remain on the old installation. You should implement a UI element (e.g., a notification banner) on the old origin that directs the user to the new site.
+
+The user's settings will not be migrated, and the old app will not be automatically uninstalled.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/client-side-encryption.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/client-side-encryption.md
new file mode 100644
index 00000000..3d359ae3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/client-side-encryption.md
@@ -0,0 +1,302 @@
+# Encrypt data client-side with WebCrypto
+
+Use the Web Cryptography API (`crypto.subtle`) to establish shared secrets over untrusted networks using quantum-resistant Key Encapsulation Mechanisms (KEMs) or classical key agreement, and encrypt sensitive data in the browser with Authenticated Encryption with Associated Data (AEAD). For signing and verifying messages or artifacts without encrypting them, see `digital-signatures` (via `npx -y modern-web-guidance@latest retrieve "digital-signatures"`).
+
+An end-to-end envelope encryption flow splits into two phases:
+
+- **One-time recipient setup (Steps 1–2)**: The recipient generates a key pair, persists the `CryptoKeyPair` in IndexedDB for future sessions, and exports the public key (`'raw-public'`) to share with senders.
+- **Per-message encryption (Steps 3–4)**: For each payload, the sender imports the recipient's public key, calls `encapsulateKey()` to generate a fresh one-time shared key and ciphertext capsule, encrypts the payload with a fresh 12-byte IV, and sends `{ capsule, iv, ciphertext }` to the recipient.
+
+## 1. Choose a KEM algorithm and generate a recipient key pair
+
+Unlike Diffie-Hellman key agreement (`deriveKey()`), where both parties combine their keys, a Key Encapsulation Mechanism (KEM) uses the recipient's public key to generate both a random shared secret and a ciphertext capsule in a single `encapsulateKey()` call. The recipient recovers the same shared key from the ciphertext capsule using `decapsulateKey()`.
+
+Use **`'MLKEM768-X25519'`** by default: it combines post-quantum ML-KEM (standardized in NIST FIPS 203) with classical `'X25519'` so the shared secret remains secure as long as either algorithm holds. Choose standalone `'ML-KEM-768'` when a policy requires pure FIPS 203 output without a hybrid component, or `'ML-KEM-1024'` when a policy requires NIST Category 5 (CNSA 2.0) compliance.
+
+| Algorithm name | Security level & use case | Public key (`'raw-public'`) | Private seed (`'raw-seed'`) | Ciphertext size |
+|---|---|---|---|---|
+| **`'MLKEM768-X25519'`** | **Hybrid post-quantum (`'ML-KEM-768'`) + classical (`'X25519'`); recommended default** | 1216 bytes | 32 bytes | 1120 bytes |
+| `'ML-KEM-768'` | NIST Category 3 (~192-bit security); standalone post-quantum KEM | 1184 bytes | 64 bytes | 1088 bytes |
+| `'ML-KEM-1024'` | NIST Category 5 (~256-bit security); highest security margin | 1568 bytes | 64 bytes | 1568 bytes |
+
+- Pass `'MLKEM768-X25519'`, `'ML-KEM-768'`, or `'ML-KEM-1024'` as the algorithm name (aliases such as `'X-Wing'` or `'X25519MLKEM768'`, as well as `'ML-KEM-512'`, throw `NotSupportedError`).
+- Pass `extractable: false` and `['encapsulateKey', 'decapsulateKey']` (or `['encapsulateBits', 'decapsulateBits']`) when generating a KEM key pair. Non-extractable `CryptoKey` and `CryptoKeyPair` objects can be persisted across sessions directly in IndexedDB via structured cloning (`objectStore.put(recipientKeyPair, 'recipient-kem-key')`) without ever exporting the private key bytes:
+
+```javascript
+const recipientKeyPair = await crypto.subtle.generateKey(
+  'MLKEM768-X25519',
+  false,
+  ['encapsulateKey', 'decapsulateKey'],
+);
+```
+
+## 2. Export and import keys
+
+Modern WebCrypto algorithms (`'MLKEM768-X25519'`, `'ML-KEM-768'`, `'ML-KEM-1024'`, and `'ChaCha20-Poly1305'`) **reject the legacy `'raw'` format** in `importKey()` and `exportKey()` with a `NotSupportedError`. Always specify the explicit key format:
+
+- **`'raw-public'`**: Public key bytes (`1216`, `1184`, or `1568` bytes). Pass `['encapsulateKey']` (or `['encapsulateBits']`) when importing a KEM public key.
+- **`'raw-seed'`**: Private key seed bytes (`32` bytes for `'MLKEM768-X25519'`; `64` bytes for `'ML-KEM-768'` and `'ML-KEM-1024'`). Pass `['decapsulateKey']` (or `['decapsulateBits']`) when importing a KEM private key (passing `['encapsulateKey', 'decapsulateKey']` to `importKey()` or `getPublicKey()` throws `SyntaxError`). Both `'raw'` and `'raw-private'` throw `NotSupportedError` on KEM private keys. Note that `'MLKEM768-X25519'` only supports `'raw-public'`, `'raw-seed'`, and `'jwk'`—it does **not** support `'spki'` or `'pkcs8'`.
+- **`'raw-secret'`**: Symmetric secret key bytes (`'ChaCha20-Poly1305'`, and accepted on `'AES-GCM'` and `'HKDF'`).
+
+Export the recipient's public key with `'raw-public'` so the public key bytes can be serialized (for example, as Base64 via `new Uint8Array(recipientPublicKeyBytes).toBase64()` or hex) and shared with senders:
+
+```javascript
+// Export the recipient's public key bytes
+const recipientPublicKeyBytes = await crypto.subtle.exportKey(
+  'raw-public',
+  recipientKeyPair.publicKey,
+);
+
+// Import the recipient's public key on the sender (usage must be ['encapsulateKey'])
+const importedPublicKey = await crypto.subtle.importKey(
+  'raw-public',
+  recipientPublicKeyBytes,
+  'MLKEM768-X25519',
+  true,
+  ['encapsulateKey'],
+);
+```
+
+If you only hold a private `CryptoKey` (even with `extractable: false`) and need its corresponding public `CryptoKey`, call `crypto.subtle.getPublicKey()`:
+
+```javascript
+const publicKey = await crypto.subtle.getPublicKey(
+  recipientKeyPair.privateKey,
+  ['encapsulateKey'],
+);
+```
+
+## 3. Encapsulate and decapsulate a shared key
+
+`encapsulateKey()` and `decapsulateKey()` import the 32-byte (256-bit) KEM shared secret into a `CryptoKey` using the algorithm specified in `sharedKeyAlgorithm` (with `'raw-secret'` format). Pass `'ChaCha20-Poly1305'` or `'AES-GCM'` directly to produce an AEAD encryption key:
+
+```javascript
+// Sender encapsulates a 256-bit AEAD key and produces a ciphertext capsule
+const { sharedKey: senderKey, ciphertext: encapsulatedCiphertext } =
+  await crypto.subtle.encapsulateKey(
+    'MLKEM768-X25519',
+    importedPublicKey,
+    'ChaCha20-Poly1305', // Or 'AES-GCM'
+    false,
+    ['encrypt', 'decrypt'],
+  );
+
+// Recipient decapsulates the ciphertext capsule to recover the identical AEAD key
+const recipientKey = await crypto.subtle.decapsulateKey(
+  'MLKEM768-X25519',
+  recipientKeyPair.privateKey,
+  encapsulatedCiphertext,
+  'ChaCha20-Poly1305',
+  false,
+  ['encrypt', 'decrypt'],
+);
+```
+
+### Domain separation with `'HKDF'`
+
+To bind the shared key to a specific protocol context (`info` and `salt`) or derive multiple subkeys from a single encapsulation, pass `'HKDF'` as `sharedKeyAlgorithm` with `['deriveKey']` usage, then call `crypto.subtle.deriveKey()`:
+
+```javascript
+const { sharedKey: hkdfBaseKey, ciphertext } = await crypto.subtle.encapsulateKey(
+  'MLKEM768-X25519',
+  importedPublicKey,
+  'HKDF',
+  false,
+  ['deriveKey'],
+);
+
+const aeadKey = await crypto.subtle.deriveKey(
+  {
+    name: 'HKDF',
+    hash: 'SHA-256',
+    salt: new Uint8Array(32),
+    info: new TextEncoder().encode('envelope-v1'),
+  },
+  hkdfBaseKey,
+  { name: 'AES-GCM', length: 256 },
+  false,
+  ['encrypt', 'decrypt'],
+);
+```
+
+## 4. Encrypt and decrypt payloads (`'ChaCha20-Poly1305'` and `'AES-GCM'`)
+
+Encrypt payload data with an AEAD algorithm (`'ChaCha20-Poly1305'` or `'AES-GCM'`) using a fresh, cryptographically random **12-byte (96-bit) initialization vector (`iv`)** for every encryption operation. Never reuse an `(iv, key)` pair. Choose `'ChaCha20-Poly1305'` for consistent constant-time performance across devices without dedicated AES hardware acceleration, or `'AES-GCM'` when interoperating with existing WebCrypto or FIPS 140 deployments.
+
+- **`'ChaCha20-Poly1305'`**: Uses a fixed 256-bit (32-byte) key (`generateKey('ChaCha20-Poly1305', extractable, ['encrypt', 'decrypt'])` takes a string or `{ name: 'ChaCha20-Poly1305' }` with **no `length` property**). The `iv` must be exactly 12 bytes, and the 128-bit Poly1305 authentication tag is appended to the ciphertext.
+- **`'AES-GCM'`**: Pass `{ name: 'AES-GCM', length: 256 }` when calling `generateKey()` or `deriveKey()`, and a 12-byte `iv` when calling `encrypt()` and `decrypt()`.
+- **`additionalData` (AAD)**: Bind unencrypted metadata (such as a record ID, recipient ID, or protocol version) to the authentication tag via `additionalData` so tampering with either the ciphertext or the metadata causes `decrypt()` to reject with `OperationError`.
+
+```javascript
+/**
+ * Encrypts UTF-8 text with an AEAD CryptoKey ('ChaCha20-Poly1305' or 'AES-GCM').
+ * @param {CryptoKey} key
+ * @param {string} plaintext
+ * @param {Uint8Array} [additionalData]
+ */
+export async function encryptMessage(key, plaintext, additionalData = new Uint8Array(0)) {
+  // Always generate a fresh 12-byte (96-bit) IV per message
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const encoded = new TextEncoder().encode(plaintext);
+
+  const ciphertextBuffer = await crypto.subtle.encrypt(
+    {
+      name: key.algorithm.name,
+      iv,
+      additionalData,
+    },
+    key,
+    encoded,
+  );
+
+  return { iv, ciphertext: new Uint8Array(ciphertextBuffer) };
+}
+
+/**
+ * Decrypts and authenticates an AEAD payload. Throws OperationError if tampered.
+ * @param {CryptoKey} key
+ * @param {Uint8Array} iv
+ * @param {Uint8Array} ciphertext
+ * @param {Uint8Array} [additionalData]
+ */
+export async function decryptMessage(key, iv, ciphertext, additionalData = new Uint8Array(0)) {
+  const plaintextBuffer = await crypto.subtle.decrypt(
+    {
+      name: key.algorithm.name,
+      iv,
+      additionalData,
+    },
+    key,
+    ciphertext,
+  );
+
+  return new TextDecoder().decode(plaintextBuffer);
+}
+```
+
+## Fallback strategies
+
+Baseline status for Web Cryptography: Widely available. It's been Baseline since 2017-09-19.
+Supported by: Chrome 37 (Aug 2014), Edge 12 (Jul 2015), Firefox 34 (Dec 2014), and Safari 11 (Sep 2017).
+
+Baseline status for the api.SubtleCrypto.deriveBits.x25519 capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 130 (Sep 2024), and Safari 17 (Sep 2023).
+
+If your Baseline target does not yet support `SubtleCrypto.supports()`, `encapsulateKey()`, or `'ChaCha20-Poly1305'`, detect support using the **static** `SubtleCrypto.supports()` method and fall back to ephemeral-static Diffie-Hellman key agreement (`'X25519'` + `'HKDF'` + `'AES-GCM'`, or `'ECDH'` with `'P-256'` when targeting browsers prior to `'X25519'` support):
+
+- **Call `SubtleCrypto.supports()` on the `SubtleCrypto` constructor, not on `crypto.subtle`**: `globalThis.SubtleCrypto?.supports?.('encapsulateKey', 'MLKEM768-X25519', 'ChaCha20-Poly1305')` is a synchronous static method returning a boolean (`crypto.subtle.supports` is `undefined`). Note that `SubtleCrypto.supports()` validates operation-specific parameters: bare algorithm strings work for `'encapsulateKey'`, `'decapsulateKey'`, `'generateKey'`, `'importKey'`, `'exportKey'`, and `'getPublicKey'`, whereas probing `'encrypt'` or `'decrypt'` directly requires an `iv` (for example, `SubtleCrypto.supports('encrypt', { name: 'ChaCha20-Poly1305', iv: new Uint8Array(12) })`).
+- **Key format in the fallback (`'raw'`)**: While browsers that support Modern WebCrypto also accept `'raw-public'` on `'X25519'` and `'ECDH'`, use `'raw'` in fallback paths targeting older browsers.
+- **Classical fallback (`'X25519'` + `'HKDF'` + `'AES-GCM'`)**: When `SubtleCrypto.supports()` is unavailable or returns `false`, generate an ephemeral `'X25519'` key pair for the sender, export the ephemeral public key as the capsule bytes, derive 256 bits via `deriveBits({ name: 'X25519', public: peerPublicKey }, privateKey, 256)`, and pass those bits through `'HKDF'` (`'SHA-256'`) to derive a 256-bit `'AES-GCM'` key.
+
+```javascript
+const KEM_PUBLIC_KEY_ALGORITHMS = {
+  1184: 'ML-KEM-768',
+  1216: 'MLKEM768-X25519',
+  1568: 'ML-KEM-1024',
+};
+
+export function supportsPostQuantumEnvelope() {
+  return (
+    typeof globalThis.SubtleCrypto?.supports === 'function' &&
+    SubtleCrypto.supports('encapsulateKey', 'MLKEM768-X25519', 'ChaCha20-Poly1305')
+  );
+}
+
+export async function generateRecipientKeys() {
+  if (supportsPostQuantumEnvelope()) {
+    const keyPair = await crypto.subtle.generateKey(
+      'MLKEM768-X25519',
+      false,
+      ['encapsulateKey', 'decapsulateKey'],
+    );
+    const publicKeyBytes = new Uint8Array(
+      await crypto.subtle.exportKey('raw-public', keyPair.publicKey),
+    );
+    return { suite: 'MLKEM768-X25519+ChaCha20-Poly1305', keyPair, publicKeyBytes };
+  }
+
+  // Classical fallback: X25519 key agreement + HKDF + AES-GCM
+  const keyPair = await crypto.subtle.generateKey('X25519', false, ['deriveBits']);
+  const publicKeyBytes = new Uint8Array(
+    await crypto.subtle.exportKey('raw', keyPair.publicKey),
+  );
+  return { suite: 'X25519+HKDF+AES-GCM', keyPair, publicKeyBytes };
+}
+
+async function deriveFallbackAesKey(privateKey, peerPublicKey, infoBytes = new Uint8Array(0)) {
+  const sharedSecret = await crypto.subtle.deriveBits(
+    { name: 'X25519', public: peerPublicKey },
+    privateKey,
+    256,
+  );
+  const hkdfKey = await crypto.subtle.importKey('raw', sharedSecret, 'HKDF', false, ['deriveKey']);
+  return crypto.subtle.deriveKey(
+    {
+      name: 'HKDF',
+      hash: 'SHA-256',
+      salt: new Uint8Array(32),
+      info: infoBytes,
+    },
+    hkdfKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  );
+}
+
+export async function encapsulateEnvelopeKey(
+  recipientPublicKeyOrBytes,
+  infoBytes = new Uint8Array(0),
+) {
+  const pubKey =
+    recipientPublicKeyOrBytes instanceof CryptoKey
+      ? recipientPublicKeyOrBytes
+      : await (() => {
+          const bytes =
+            recipientPublicKeyOrBytes instanceof Uint8Array
+              ? recipientPublicKeyOrBytes
+              : new Uint8Array(recipientPublicKeyOrBytes);
+          const kemName = KEM_PUBLIC_KEY_ALGORITHMS[bytes.byteLength];
+          return kemName
+            ? crypto.subtle.importKey('raw-public', bytes, kemName, true, ['encapsulateKey'])
+            : crypto.subtle.importKey('raw', bytes, 'X25519', true, []);
+        })();
+
+  if (pubKey.algorithm.name !== 'X25519') {
+    const { sharedKey, ciphertext } = await crypto.subtle.encapsulateKey(
+      pubKey.algorithm.name,
+      pubKey,
+      'ChaCha20-Poly1305',
+      false,
+      ['encrypt', 'decrypt'],
+    );
+    return { sharedKey, capsuleBytes: new Uint8Array(ciphertext) };
+  }
+
+  // Classical fallback: generate ephemeral X25519 key pair and send ephemeral public key as capsule
+  const ephemeral = await crypto.subtle.generateKey('X25519', false, ['deriveBits']);
+  const capsuleBytes = new Uint8Array(await crypto.subtle.exportKey('raw', ephemeral.publicKey));
+  const sharedKey = await deriveFallbackAesKey(ephemeral.privateKey, pubKey, infoBytes);
+  return { sharedKey, capsuleBytes };
+}
+
+export async function decapsulateEnvelopeKey(
+  recipientPrivateKey,
+  capsuleBytes,
+  infoBytes = new Uint8Array(0),
+) {
+  if (recipientPrivateKey.algorithm.name !== 'X25519') {
+    return crypto.subtle.decapsulateKey(
+      recipientPrivateKey.algorithm.name,
+      recipientPrivateKey,
+      capsuleBytes,
+      'ChaCha20-Poly1305',
+      false,
+      ['encrypt', 'decrypt'],
+    );
+  }
+
+  const ephemeralPubKey = await crypto.subtle.importKey('raw', capsuleBytes, 'X25519', true, []);
+  return deriveFallbackAesKey(recipientPrivateKey, ephemeralPubKey, infoBytes);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/digital-signatures.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/digital-signatures.md
new file mode 100644
index 00000000..0aea909f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/digital-signatures.md
@@ -0,0 +1,235 @@
+# Sign and verify data with WebCrypto
+
+Use the Web Cryptography API (`crypto.subtle`) to sign and verify messages, tokens, or artifacts in the browser using quantum-resistant (ML-DSA) or classical (`'Ed25519'`, `'ECDSA'`) asymmetric keys. Digital signatures guarantee data integrity and signer authenticity without requiring shared secret keys. For establishing shared secrets and encrypting confidential payloads, see `client-side-encryption` (via `npx -y modern-web-guidance@latest retrieve "client-side-encryption"`).
+
+## 1. Choose an algorithm and generate a key pair
+
+ML-DSA (Module-Lattice-Based Digital Signature Algorithm, standardized in NIST FIPS 204) provides post-quantum lattice-based digital signatures resistant to attacks by both classical and quantum computers.
+
+Use **`'ML-DSA-65'`** by default for general-purpose signing. Choose `'ML-DSA-44'` when you need smaller public keys and signatures over bandwidth-constrained channels and 128-bit security is sufficient, or `'ML-DSA-87'` when a security policy requires NIST Category 5 (CNSA 2.0) compliance.
+
+| Algorithm name | Security level & use case | Public key (`'raw-public'`) | Signature size |
+|---|---|---|---|
+| `'ML-DSA-44'` | NIST Category 2 (~128-bit security); smallest keys and signatures | 1312 bytes | 2420 bytes |
+| **`'ML-DSA-65'`** | **NIST Category 3 (~192-bit security); recommended default** | 1952 bytes | 3309 bytes |
+| `'ML-DSA-87'` | NIST Category 5 (~256-bit security); highest security margin | 2592 bytes | 4627 bytes |
+
+- Pass `'ML-DSA-44'`, `'ML-DSA-65'`, or `'ML-DSA-87'` as the algorithm name (pre-standardization names such as `'Dilithium'` or `'CRYSTALS-Dilithium'` throw `NotSupportedError`).
+- Neither ML-DSA nor `'Ed25519'` takes a `hash` parameter.
+- Pass `['sign', 'verify']` when generating a key pair with `generateKey()`:
+
+```javascript
+const signerKeyPair = await crypto.subtle.generateKey(
+  'ML-DSA-65',
+  false,
+  ['sign', 'verify'],
+);
+```
+
+## 2. Export and import keys
+
+`'ML-DSA-44'`, `'ML-DSA-65'`, and `'ML-DSA-87'` **reject the legacy `'raw'` format** in `importKey()` and `exportKey()` with a `NotSupportedError`. Always export or import keys using an explicit format:
+
+- **`'raw-public'`**: Public key bytes (`1312`, `1952`, or `2592` bytes). Pass `['verify']` as the key usage when importing a public key.
+- **`'raw-seed'`**: 32-byte private key seed for all three ML-DSA algorithms. Both `'raw'` and `'raw-private'` throw `NotSupportedError` on ML-DSA—store or transmit private keys using `'raw-seed'`, `'pkcs8'` (54 bytes), or `'jwk'` (`kty: 'AKP'`). Pass `['sign']` as the key usage when importing a private key (passing `['sign', 'verify']` to `importKey()` throws `SyntaxError`).
+- **`'spki'`, `'pkcs8'`, and `'jwk'`**: Supported for all three ML-DSA algorithms.
+
+Always export the verification public key with `'raw-public'` so the public key bytes can be serialized or shared with verifiers:
+
+```javascript
+// Export the public key bytes on the signer
+const publicKeyBytes = await crypto.subtle.exportKey(
+  'raw-public',
+  signerKeyPair.publicKey,
+);
+
+// Import the public key bytes on the verifier (usage must be ['verify'] only)
+const verifierPublicKey = await crypto.subtle.importKey(
+  'raw-public',
+  publicKeyBytes,
+  'ML-DSA-65',
+  true,
+  ['verify'],
+);
+```
+
+If you only hold a private signing `CryptoKey` (even with `extractable: false`) and need its corresponding public `CryptoKey`, call `crypto.subtle.getPublicKey()` with `['verify']`:
+
+```javascript
+const publicKey = await crypto.subtle.getPublicKey(
+  signerKeyPair.privateKey,
+  ['verify'],
+);
+```
+
+## 3. Sign and verify payloads
+
+Call `crypto.subtle.sign()` with the private key to produce a signature, and `crypto.subtle.verify()` with the public key to check it:
+
+```javascript
+const payloadBytes = new TextEncoder().encode(
+  '{"artifact":"release-v2.4.0.tar.gz","sha256":"9f86d08..."}',
+);
+
+const signatureBuffer = await crypto.subtle.sign(
+  'ML-DSA-65',
+  signerKeyPair.privateKey,
+  payloadBytes,
+);
+
+const isValid = await crypto.subtle.verify(
+  'ML-DSA-65',
+  verifierPublicKey,
+  signatureBuffer,
+  payloadBytes,
+);
+```
+
+### Domain separation with `ContextParams`
+
+To prevent a signature created for one purpose from being replayed in another part of your application or protocol that shares the same key pair, bind the signature to a domain-separation `context`.
+
+Instead of a bare algorithm name string, pass a `ContextParams` dictionary (`{ name, context }`) to `sign()` and `verify()`, where `context` is a `BufferSource` (`Uint8Array` or `ArrayBuffer`):
+
+```javascript
+const contextBytes = new TextEncoder().encode('release-manifest-v1');
+
+const signatureBuffer = await crypto.subtle.sign(
+  {
+    name: 'ML-DSA-65',
+    context: contextBytes,
+  },
+  signerKeyPair.privateKey,
+  payloadBytes,
+);
+
+const isValid = await crypto.subtle.verify(
+  {
+    name: 'ML-DSA-65',
+    context: contextBytes,
+  },
+  verifierPublicKey,
+  signatureBuffer,
+  payloadBytes,
+);
+```
+
+- **255-byte limit**: `context` accepts `0` to `255` bytes (omitting `context` is equivalent to passing an empty `new Uint8Array(0)`). Passing more than `255` bytes rejects with `OperationError`.
+- **Exact match required**: `crypto.subtle.verify()` returns `true` only when the verifier passes the exact same `context` bytes used during `crypto.subtle.sign()`.
+
+## Fallback strategies
+
+Baseline status for Web Cryptography: Widely available. It's been Baseline since 2017-09-19.
+Supported by: Chrome 37 (Aug 2014), Edge 12 (Jul 2015), Firefox 34 (Dec 2014), and Safari 11 (Sep 2017).
+
+Baseline status for the api.SubtleCrypto.sign.ed25519 capability: Newly available. It's been Baseline since 2025-05-29.
+Supported by: Chrome 137 (May 2025), Edge 137 (May 2025), Firefox 129 (Aug 2024), and Safari 17 (Sep 2023).
+
+If your Baseline target does not yet support `SubtleCrypto.supports()` or ML-DSA, detect support using the **static** `SubtleCrypto.supports()` method and fall back to classical `'Ed25519'` (or `'ECDSA'` with `'P-256'` and `'SHA-256'` when targeting browsers prior to `'Ed25519'` support):
+
+- **Call `SubtleCrypto.supports()` on the `SubtleCrypto` constructor, not on `crypto.subtle`**: `globalThis.SubtleCrypto?.supports?.('sign', 'ML-DSA-65')` is a synchronous static method returning a boolean (`crypto.subtle.supports` is `undefined`). Probe `'sign'`, `'verify'`, `'generateKey'`, `'importKey'`, `'exportKey'`, or `'getPublicKey'` (or pass a `ContextParams` dictionary such as `SubtleCrypto.supports('sign', { name: 'ML-DSA-65', context })`).
+- **Key format in the fallback (`'raw'`)**: While browsers that support Modern WebCrypto also accept `'raw-public'` on `'Ed25519'` and `'ECDSA'`, use `'raw'` in fallback paths targeting older browsers.
+- **Domain separation in the fallback**: Classical WebCrypto algorithms (`'Ed25519'` and `'ECDSA'`) do not read a `context` property from the algorithm dictionary (WebIDL silently ignores unknown dictionary properties on `Algorithm` and `EcdsaParams`). Prepend a length-prefixed `context` header to the payload in your fallback path so domain separation behaves consistently across both suites.
+
+```javascript
+const ML_DSA_PUBLIC_KEY_ALGORITHMS = {
+  1312: 'ML-DSA-44',
+  1952: 'ML-DSA-65',
+  2592: 'ML-DSA-87',
+};
+
+export function supportsPostQuantumSignatures() {
+  return (
+    typeof globalThis.SubtleCrypto?.supports === 'function' &&
+    SubtleCrypto.supports('sign', 'ML-DSA-65')
+  );
+}
+
+export async function generateSigningKeyPair() {
+  if (supportsPostQuantumSignatures()) {
+    const keyPair = await crypto.subtle.generateKey('ML-DSA-65', false, ['sign', 'verify']);
+    const publicKeyBytes = new Uint8Array(
+      await crypto.subtle.exportKey('raw-public', keyPair.publicKey),
+    );
+    return {
+      suite: 'ML-DSA-65',
+      keyFormat: 'raw-public',
+      keyPair,
+      publicKeyBytes,
+    };
+  }
+
+  // Classical fallback: Ed25519
+  const keyPair = await crypto.subtle.generateKey('Ed25519', false, ['sign', 'verify']);
+  const publicKeyBytes = new Uint8Array(await crypto.subtle.exportKey('raw', keyPair.publicKey));
+  return {
+    suite: 'Ed25519',
+    keyFormat: 'raw',
+    keyPair,
+    publicKeyBytes,
+  };
+}
+
+function frameFallbackInput(payloadBytes, contextBytes) {
+  if (contextBytes.byteLength > 255) {
+    throw new DOMException('Context must not exceed 255 bytes', 'OperationError');
+  }
+  const framed = new Uint8Array(1 + contextBytes.byteLength + payloadBytes.byteLength);
+  framed[0] = contextBytes.byteLength;
+  framed.set(contextBytes, 1);
+  framed.set(payloadBytes, 1 + contextBytes.byteLength);
+  return framed;
+}
+
+export async function signPayload(
+  privateKey,
+  payloadBytes,
+  contextBytes = new Uint8Array(0),
+) {
+  if (privateKey.algorithm.name.startsWith('ML-DSA')) {
+    const sig = await crypto.subtle.sign(
+      { name: privateKey.algorithm.name, context: contextBytes },
+      privateKey,
+      payloadBytes,
+    );
+    return new Uint8Array(sig);
+  }
+
+  const framed = frameFallbackInput(payloadBytes, contextBytes);
+  const sig = await crypto.subtle.sign('Ed25519', privateKey, framed);
+  return new Uint8Array(sig);
+}
+
+export async function verifyPayload(
+  publicKeyOrBytes,
+  signatureBytes,
+  payloadBytes,
+  contextBytes = new Uint8Array(0),
+) {
+  const publicKey =
+    publicKeyOrBytes instanceof CryptoKey
+      ? publicKeyOrBytes
+      : await (() => {
+          const bytes =
+            publicKeyOrBytes instanceof Uint8Array
+              ? publicKeyOrBytes
+              : new Uint8Array(publicKeyOrBytes);
+          const mlDsaName = ML_DSA_PUBLIC_KEY_ALGORITHMS[bytes.byteLength];
+          return mlDsaName
+            ? crypto.subtle.importKey('raw-public', bytes, mlDsaName, true, ['verify'])
+            : crypto.subtle.importKey('raw', bytes, 'Ed25519', true, ['verify']);
+        })();
+
+  if (publicKey.algorithm.name.startsWith('ML-DSA')) {
+    return crypto.subtle.verify(
+      { name: publicKey.algorithm.name, context: contextBytes },
+      publicKey,
+      signatureBytes,
+      payloadBytes,
+    );
+  }
+
+  const framed = frameFallbackInput(payloadBytes, contextBytes);
+  return crypto.subtle.verify('Ed25519', publicKey, signatureBytes, framed);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/local-network-access.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/local-network-access.md
new file mode 100644
index 00000000..262a8374
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/local-network-access.md
@@ -0,0 +1,192 @@
+# Local Network Access
+
+When a web application served from a `public` origin (or an intranet `local` origin) connects to a user's private local network (such as a LAN printer, IoT hub, or router at `192.168.1.x` or `device.local`) or to a local companion service running on the user's machine (`127.0.0.1`, `[::1]`, or `localhost`), browsers gate the connection behind a **Local Network Access (LNA)** permission prompt.
+
+Local Network Access splits access into two granular permissions and `Permissions-Policy` tokens based on the IP address space lattice (`public` → `local` → `loopback`), enforcing checks **only** when a request crosses from a *less private* address space into a *more private* address space:
+- **`local-network`**: Required when connecting from a `public` origin to the `local` address space (RFC 1918 private IPv4 ranges `10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, link-local `169.254.0.0/16` / `fe80::/10`, IPv6 Unique Local Addresses `fc00::/7`, and `.local` mDNS hostnames).
+- **`loopback-network`**: Required when connecting from a `public` or `local` origin to the `loopback` address space (`127.0.0.0/8`, `::1/128`, or `localhost`).
+
+Because `localhost` (`127.0.0.1` and `[::1]`) is already in the most private (`loopback`) address space, serving your web app from `http://localhost` during local development will **not** trigger LNA checks by default. To test LNA prompts and permission states locally without deploying to a public server, either override your local dev server's IPv4 and IPv6 address space to `public` using the `--ip-address-space-overrides=127.0.0.1:8080=public,[::1]:8080=public` Chromium flag, or manually toggle **Local network** and **Loopback network** between `Ask`, `Allow`, and `Block` in browser **Site settings**.
+
+**MANDATORY:** Serve any web application that initiates local or loopback network requests from a **Secure Context (`https://`)**. Local Network Access permissions are denied automatically in insecure (`http://`) top-level contexts.
+
+**DO NOT** rely on deprecated Private Network Access (PNA) preflight headers (`Access-Control-Request-Private-Network: true` / `Access-Control-Allow-Private-Network: true`). Local Network Access enforces access via client-side user permission prompts (`local-network` and `loopback-network`) combined with standard CORS headers (`Access-Control-Allow-Origin`) when reading cross-origin responses. PNA preflights were never enforced as a blocking requirement and are not needed as a fallback. Existing servers or device firmware that already return `Access-Control-Allow-Private-Network: true` can keep doing so harmlessly, but do not add PNA handling to new code.
+
+## Implementation Steps
+
+### 1. Pre-Check Granular Permission State and Gate on User Gesture
+
+Never fire local network or loopback requests unconditionally on page load (`DOMContentLoaded`) when the permission state is `'prompt'`, and never initiate the first permission-triggering request from a **Service Worker** or **Shared Worker** (which lack an attached `Document` and will immediately fail if permission is not already `'granted'`).
+
+Instead, query `navigator.permissions.query()` for `'local-network'` or `'loopback-network'` first:
+- If `state === 'granted'`, connect automatically.
+- If `state === 'prompt'`, display clear UI explaining why the app needs access to the local device or companion app, and trigger the request from an explicit user gesture (such as a button click).
+- If `state === 'denied'`, render actionable remediation UI instructing the user how to re-enable Local Network or Loopback access in browser site settings.
+
+```javascript
+/**
+ * Queries the granular Local Network Access permission for the target space.
+ * @param {'local-network' | 'loopback-network'} permissionName
+ */
+export async function checkNetworkPermission(permissionName) {
+  const status = await navigator.permissions.query({ name: permissionName });
+
+  // Keep UI synchronized if the user changes permission in browser site settings
+  status.addEventListener('change', () => {
+    updatePermissionUI(permissionName, status.state);
+  });
+
+  updatePermissionUI(permissionName, status.state);
+  return status.state;
+}
+
+function updatePermissionUI(permissionName, state) {
+  const statusBadge = document.querySelector(`[data-permission-status="${permissionName}"]`);
+  const remediationBox = document.querySelector(`[data-remediation="${permissionName}"]`);
+  if (statusBadge) {
+    statusBadge.textContent = state;
+  }
+  if (remediationBox) {
+    // Show remediation instructions whenever permission is explicitly denied
+    remediationBox.hidden = state !== 'denied';
+  }
+}
+```
+
+### 2. Declare `targetAddressSpace` in `fetch()` and `Request`
+
+When an `https://` page requests an `http://` endpoint on the local network or loopback interface, specify `targetAddressSpace: 'local'` or `targetAddressSpace: 'loopback'` in the `fetch()` or `Request` options.
+
+Explicitly setting `targetAddressSpace` does two critical things:
+1. **Mixed Content Exemption**: Mixed Content checks run *before* DNS resolution. Declaring `targetAddressSpace: 'local'` (or `'loopback'`) informs the browser ahead of DNS resolution that an `http://` URL (including a custom DNS hostname that resolves to a local IP) targets a local/loopback endpoint and should be exempted from Mixed Content blocking once the user grants the permission.
+2. **Address Space Verification**: After DNS resolution, the browser verifies that the resolved IP address actually belongs to the declared `targetAddressSpace`. If a hostname with `targetAddressSpace: 'local'` unexpectedly resolves to a `public` IP address, the browser immediately aborts the request with a `TypeError` network error.
+
+```javascript
+/**
+ * Connects to a local network device (e.g., LAN printer or IoT hub) over HTTP.
+ * Example endpoint URL is illustrative; replace with your device's address.
+ */
+export async function fetchLocalDeviceStatus(deviceUrl = 'http://192.168.1.100:8080/api/status') {
+  const request = new Request(deviceUrl, {
+    method: 'GET',
+    mode: 'cors',
+    // MANDATORY: Declare 'local' when targeting RFC 1918 / .local LAN addresses
+    targetAddressSpace: 'local',
+  });
+
+  const response = await fetch(request);
+  if (!response.ok) {
+    throw new Error(`Device responded with HTTP ${response.status}`);
+  }
+  return response.json();
+}
+
+/**
+ * Connects to a local companion daemon running on the user's loopback interface.
+ * Example loopback port is illustrative; replace with your service's port.
+ */
+export async function fetchLoopbackDaemon(daemonUrl = 'http://127.0.0.1:45678/health') {
+  const request = new Request(daemonUrl, {
+    method: 'GET',
+    mode: 'cors',
+    // MANDATORY: Declare 'loopback' when targeting 127.0.0.1, [::1], or localhost
+    targetAddressSpace: 'loopback',
+  });
+
+  const response = await fetch(request);
+  if (!response.ok) {
+    throw new Error(`Companion app responded with HTTP ${response.status}`);
+  }
+  return response.json();
+}
+```
+
+### 3. Real-Time Connections with `WebSocket` and `WebTransport`
+
+Local Network Access restrictions also govern `WebSocket` and `WebTransport` connections:
+
+- **`WebSocket`**: The `WebSocket(url, protocols)` constructor only accepts a subprotocol string or array as its second argument—do **not** pass a `{ targetAddressSpace }` options object, which throws a `SyntaxError`. Instead, the browser inspects the `WebSocket` URL before DNS resolution: `ws://` connections initiated from an `https://` page are exempted from Mixed Content blocking when the URL host is syntactically recognizable as local or loopback—specifically a private or loopback IP literal (`ws://192.168.1.100:8080`, `ws://127.0.0.1:8080`, `ws://[::1]:8080`), `localhost` (`*.localhost`), or a `.local` mDNS hostname (`ws://device.local:8080`)—and gated behind the `local-network` or `loopback-network` permission prompt. If a local endpoint is addressed via a custom non-`.local` DNS hostname, connect over `wss://`.
+- **`WebTransport`**: Because `WebTransport` strictly requires `https://` (HTTP/3 over QUIC with TLS or `serverCertificateHashes` for local self-signed certificates), it never triggers Mixed Content blocks and does not accept a `targetAddressSpace` option. Instead, the browser automatically verifies the resolved IP address space and gates the `transport.ready` promise behind the `local-network` or `loopback-network` permission prompt.
+
+```javascript
+/**
+ * Opens a WebSocket connection to a local network device (IP literal, .local, or localhost).
+ */
+export function openLocalWebSocket(wsUrl = 'ws://192.168.1.100:8080/stream') {
+  // Pass only subprotocol string(s) as the second argument (never an options object).
+  // Browsers exempt ws:// from Mixed Content when the host is a local/loopback IP literal,
+  // .local, or localhost, and gate the connection on 'local-network' or 'loopback-network'.
+  const socket = new WebSocket(wsUrl, ['v1.telemetry']);
+  return socket;
+}
+
+/**
+ * Opens a WebTransport session to a local network endpoint using a pinned self-signed certificate hash.
+ */
+export async function openLocalWebTransport(wtUrl = 'https://192.168.1.100:4433/wt', certSha256Bytes) {
+  const transport = new WebTransport(wtUrl, {
+    serverCertificateHashes: [
+      {
+        algorithm: 'sha-256',
+        value: certSha256Bytes,
+      },
+    ],
+  });
+
+  // transport.ready resolves only after the user grants the 'local-network' permission
+  // and rejects with WebTransportError if the permission is denied.
+  await transport.ready;
+  return transport;
+}
+```
+
+### 4. Delegate Access to Cross-Origin Iframes via `Permissions-Policy`
+
+By default, `local-network` and `loopback-network` have a default allowlist of `'self'`, blocking cross-origin `<iframe>` embeds from making local or loopback requests. To allow an embedded cross-origin `<iframe>` (such as a hardware setup widget or an SSO frame that communicates with a local agent) to initiate local or loopback requests, explicitly delegate the granular permissions in the `allow` attribute and/or HTTP `Permissions-Policy` header:
+
+```html
+<!-- Delegate granular local-network and loopback-network permissions to the embedded iframe -->
+<iframe
+  src="https://setup.partner.example.com/device-bridge"
+  allow="local-network; loopback-network"
+  title="Local Device Bridge">
+</iframe>
+```
+
+Send the `Permissions-Policy` header on the **top-level (embedding) document's** response, not on the iframe's response:
+
+```http
+Permissions-Policy: local-network=(self "https://setup.partner.example.com"), loopback-network=(self "https://setup.partner.example.com")
+```
+
+## Fallback Strategies
+
+Browser support for Local network access: Limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target does not support Local Network Access permissions and `targetAddressSpace` options, implement **feature detection with progressive fallback**:
+
+1. **Permission Query Fallback**: Wrap `navigator.permissions.query({ name: permissionName })` in a `try / catch`. If the browser throws a `TypeError` because `'local-network'` or `'loopback-network'` is an unrecognized `PermissionName`, treat the state as `'prompt'` so the request still runs on an explicit user click (the connection attempt itself triggers the browser prompt where LNA is supported).
+2. **DO NOT** query the legacy combined permission name `{ name: 'local-network-access' }`. In older Chrome versions this query crashes the renderer process, and `try / catch` cannot prevent it. Newer Chrome versions treat `'local-network-access'` only as a legacy alias for the granular permissions.
+3. **Graceful Rejection Handling**: Always wrap `fetch()`, `WebSocket` error events, and `transport.ready` in error handlers that catch `TypeError` / connection failures and present clear remediation steps (checking that the local device is powered on, connected to the same network, and allowed in browser permissions).
+
+```javascript
+/**
+ * Cross-browser permission check for the granular LNA permissions.
+ * Never falls back to querying 'local-network-access', which crashes older Chrome versions.
+ * @param {'local-network' | 'loopback-network'} permissionName
+ */
+export async function queryLnaPermissionSafe(permissionName) {
+  if (!navigator.permissions?.query) {
+    return 'prompt';
+  }
+  try {
+    const status = await navigator.permissions.query({ name: permissionName });
+    return status.state;
+  } catch {
+    // Unrecognized permission name; proceed on user gesture
+    return 'prompt';
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-authentication.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-authentication.md
new file mode 100644
index 00000000..f198027d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-authentication.md
@@ -0,0 +1,205 @@
+# Passkey Authentication
+
+This guide details how to implement returning user authentication using discoverable credentials, both through explicit button triggers and seamless browser autofill suggestions (Conditional UI).
+
+## Server-Side
+
+### Options Generation
+
+Create an endpoint that generates WebAuthn request parameters using a vetted library per standards.
+
+1.  **Use the predefined RP ID**: Use the predefined proper RP ID as a constant string.
+2.  **Generate challenge**: Generate a high-entropy, cryptographically secure random buffer, store it securely in the user's session, and encode it as Base64URL.
+3.  **Discoverable Credentials mapping**: Specify an empty array `[]` for `allowCredentials`. This requests discoverable credentials, meaning the user does not need to enter their username first; the passkey provider will present available accounts.
+4.  **User Verification level**: Set `userVerification: "preferred"` (or `"required"` if explicitly mandated by corporate compliance policies).
+    - The requested `userVerification` constraint level MUST be persisted inside the server session record at the options endpoint, rather than passed back from the client via query strings. This allows the verification endpoint to enforce strict matching constraints safely without risk of client manipulation.
+
+```javascript
+// Options generation example (discoverable flow)
+const options = {
+  challenge: serverGeneratedBase64UrlChallenge, // High-entropy random challenge stored in session
+  rpId: "example.com",
+  allowCredentials: [], // Request discoverable passkeys
+  userVerification: "preferred",
+};
+
+// Persist expected UV level to user session
+req.session.expectedUserVerification = "preferred";
+```
+
+### Verification Endpoint
+
+Securely verify the assertion returned by the client to authenticate the user:
+
+1.  **Validate session challenge**: Enforce strict challenge matching between the client response and the expected challenge stored in the session.
+2.  **Enforce UV Preferences**:
+    - Allow UV-less authenticators (e.g., authenticator screen locks disabled) if the session's `expectedUserVerification` requested `"preferred"`, by passing `requireUserVerification: false` to your server-side verification library. If requested `"required"`, enforce biometrics/PIN entry strictly.
+3.  **Clean Server Error 404**: If the credential ID returned by the client is not found in the database, return an explicit HTTP `404` error so the client can trigger the Signal API.
+
+## Client-Side Logic
+
+### HTML Form Annotation
+
+Annotate your username and password inputs to natively leverage Conditional UI. Autocomplete tokens combine the webauthn spec parameters, and autofocus triggers the browser autofill popup immediately when the input is focused.
+
+```html
+<!-- Autocomplete tokens must contain webauthn space-separated -->
+<form id="signin-form">
+  <input
+    type="text"
+    name="username"
+    autocomplete="username webauthn"
+    autofocus
+    data-testid="username-field"
+  />
+  <input type="password" name="password" autocomplete="current-password" />
+  <button type="submit">Sign in</button>
+</form>
+```
+
+### Explicit Button Flow
+
+Trigger passkey authentication when a user clicks a "Sign in with passkey" button. Abort any ongoing form autofill (Conditional Get) calls before invoking the passkey prompt.
+
+### Conditional Mediation Flow (Form Autofill)
+
+Activate form autofill suggestions on page load to offer passkey authentication natively when users focus on sign-in fields:
+
+1.  **Feature detect**: Call `PublicKeyCredential.getClientCapabilities()` on page load and **skip signing in with passkey** if `conditionalGet` is not available.
+2.  **Decode options**: Decode fetched credential JSON object with `PublicKeyCredential.parseRequestOptionsFromJSON()`.
+3.  **Invoke Conditional Get**: Call `navigator.credentials.get()` with `mediation: "conditional"` and pass an `AbortController` signal. This registers autofill silently without rendering a passkey dialog.
+4.  **Try/Catch Exception Segregation**: Wrap `navigator.credentials.get` call in try/catch block:
+    - `NotAllowedError`: The user cancelled or timed out the passkey login prompt.
+    - `AbortError`: The authentication request was cancelled programmatically.
+5.  **Call Signal API**: Wrap server verification `fetch()` call in a try/catch block:
+    - Show an error message for the user to understand what went wrong.
+    - Call `signalUnknownCredential()` ONLY when the server explicitly responds with HTTP status `404` (Credential not found) and the user is unauthenticated.
+    - The `credentialId` parameter passed to `signalUnknownCredential()` MUST strictly be the Base64URL-encoded credential ID string (e.g., `encoded.id`), NOT the raw ArrayBuffer object `credential.rawId`.
+6.  **Encode the response**: Encode the credential `AuthenticatorAssertionResponse` with `.toJSON()` before sending it to the server for verification.
+
+```javascript
+// optionsFetch and loginVerifyFetch are app-defined HTTP methods
+import { optionsFetch, loginVerifyFetch } from "./api.js";
+
+let autofillAbortController = new AbortController();
+
+async function initializeConditionalAutofill() {
+  // Feature detect Conditional Get autofill support
+  const capabilities = await PublicKeyCredential.getClientCapabilities();
+  if (capabilities.conditionalGet === true) {
+    const loginOptionsJSON = await optionsFetch();
+    const publicKey =
+      PublicKeyCredential.parseRequestOptionsFromJSON(loginOptionsJSON);
+
+    try {
+      // Initiate Conditional UI form autofill suggestions
+      const credential = await navigator.credentials.get({
+        publicKey,
+        signal: autofillAbortController.signal,
+        mediation: "conditional",
+      });
+
+      // Segregated verification fetch
+      const encoded = credential.toJSON();
+      const response = await loginVerifyFetch(encoded);
+      if (!response.ok && response.status === 404) {
+        // Note: this code path runs pre-authentication, satisfying the unauth precondition
+        if (PublicKeyCredential.signalUnknownCredential) {
+          await PublicKeyCredential.signalUnknownCredential({
+            rpId, // RP ID must match the one defined on the server
+            credentialId: encoded.id,
+          });
+        }
+      }
+    } catch (err) {
+      // Silently swallow expected client WebAuthn exceptions
+      if (["NotAllowedError", "AbortError"].includes(err.name)) {
+        return;
+      }
+      console.error("Unexpected conditional get error:", err);
+    }
+  }
+}
+
+async function triggerButtonAuthentication() {
+  // Abort any pending Conditional Get call to prevent passkey prompt collisions
+  autofillAbortController.abort();
+  autofillAbortController = new AbortController(); // Reset controller for next triggers
+
+  const loginOptionsJSON = await optionsFetch();
+  const publicKey =
+    PublicKeyCredential.parseRequestOptionsFromJSON(loginOptionsJSON);
+
+  let credential;
+  try {
+    // Passkey explicit prompt trigger
+    credential = await navigator.credentials.get({
+      publicKey,
+      signal: autofillAbortController.signal,
+    });
+  } catch (err) {
+    if (err.name === "NotAllowedError") {
+      console.log("User cancelled passkey login.");
+    } else if (err.name === "AbortError") {
+      console.log("The authentication operation was aborted.");
+    }
+    // Re-arm Conditional autofill Suggestions after cancelled explicit button prompts
+    initializeConditionalAutofill();
+    return; // Safe exit
+  }
+
+  // Segregated verification try/catch (HTTP 404 trigger)
+  const encoded = credential.toJSON();
+  try {
+    const response = await loginVerifyFetch(encoded);
+    if (!response.ok && response.status === 404) {
+      // Note: this code path runs pre-authentication, satisfying the unauth precondition
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId, // RP ID must match the one defined on the server
+        credentialId: encoded.id, // Base64URL-encoded credential ID
+      });
+    }
+  } catch (serverErr) {
+    console.error("Verification request error:", serverErr);
+  }
+}
+
+// Trigger Conditional Get on load
+window.addEventListener("DOMContentLoaded", initializeConditionalAutofill);
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Signal API Synchronization Fallback
+
+Browser support for Web authentication signal methods: Limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive optimization used to keep password managers in sync with the server credential state.
+
+- **Fallback Experience**: Gated via `if (PublicKeyCredential.signalUnknownCredential)`. If unsupported, the background verification sync is bypassed gracefully without throwing browser exceptions.
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseRequestOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseRequestOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-conditional-create.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-conditional-create.md
new file mode 100644
index 00000000..4ed96d40
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-conditional-create.md
@@ -0,0 +1,134 @@
+# Passkey Conditional Create (Post-Login Promotion)
+
+This guide details how to automatically and silently register a passkey for a user immediately after a successful password-based sign-in, minimizing friction and boosting passkey adoption.
+
+## The Right Trigger Moment
+
+Automatic passkey creation (also known as Conditional Create or silent post-login promotion) MUST only be triggered **immediately after a successful, full sign-in that involved a password**. 
+* Do not attempt conditional creation for passwordless flows (e.g., magic links, SMS OTP, or identity federation).
+* If multi-factor authentication is required, you MUST wait until all factors have succeeded before initiating conditional creation.
+* Ensure a valid, authenticated user session is active before making requests to creation endpoints.
+
+## Implementation Steps
+
+### 1. Abort Prior Autofill Actions
+If the sign-in page utilizes form autofill (Conditional UI/Get), the active credential get call must be aborted to prevent browser conflicts.
+* Call `abortController.abort()` on the `AbortController` attached to the pending `navigator.credentials.get()` autofill request before calling `navigator.credentials.create()`.
+
+### 2. Feature Detection
+Determine whether Conditional Create is available by checking `conditionalCreate` with `PublicKeyCredential.getClientCapabilities()`.
+
+```javascript
+const capabilities = await PublicKeyCredential.getClientCapabilities();
+if (capabilities.conditionalCreate) {
+  // Conditional create is available
+}
+```
+
+### 3. Create a passkey with Conditional Create
+* Pass `mediation: 'conditional'` within the `navigator.credentials.create()` options. This signals the browser to handle the passkey creation flow silently in the background or contextually without throwing obtrusive modal dialogs.
+* Populate `excludeCredentials` with the user's existing passkey credential IDs to avoid registering duplicate keys.
+
+### 4. Silent Error Handling
+* Wrap the passkey creation prompt (`navigator.credentials.create`) in a try/catch block. You MUST catch and silently ignore typical user-facing exceptions (`InvalidStateError`, `NotAllowedError`, `AbortError`) without rendering any error UI to the user.
+
+### 5. Server-Side User Presence Verification
+* The server-side verification endpoint MUST relax the User Presence (UP) requirement (`requireUserPresence: false`) **ONLY** when verifying credentials produced by a conditional-create trigger. Strict presence verification must remain active for standard explicit creations.
+
+### 6. Handle Failed Server Verification gracefully
+* If `navigator.credentials.create()` succeeds but the server verification fetch returns a bad response (e.g., signature verification fails), invoke `PublicKeyCredential.signalUnknownCredential()` to prevent orphaned credentials from lingering in the passkey provider.
+
+## Code Example
+
+```javascript
+// optionsFetch and registerVerifyFetch are app-defined server endpoint requests
+import { optionsFetch, registerVerifyFetch } from './api.js';
+
+async function triggerConditionalCreate(loginAbortController) {
+  const capabilities = await PublicKeyCredential.getClientCapabilities();
+  if (capabilities.conditionalCreate !== true) {
+    return; // Platform does not support conditional creation
+  }
+
+  // 1. Abort any active autofill conditional-get controllers to clear the WebAuthn pipeline
+  loginAbortController.abort();
+
+  // 2. Fetch creation options signaling the backend that this is a conditional request
+  const creationOptionsJSON = await optionsFetch({ conditional: true });
+  const publicKey = PublicKeyCredential.parseCreationOptionsFromJSON(creationOptionsJSON);
+
+  let credential;
+  try {
+    // 3. Invoke silent credentials creation prompt
+    credential = await navigator.credentials.create({ 
+      publicKey,
+      mediation: 'conditional' // Silent background creation mediation
+    });
+  } catch (e) {
+    // 4. Silently swallow common WebAuthn browser exceptions
+    if (['InvalidStateError', 'NotAllowedError', 'AbortError'].includes(e.name)) {
+      return; 
+    }
+    console.error('Unexpected conditional create error:', e);
+    return;
+  }
+
+  // 5. Server verification step using dedicated Try/Catch block
+  let encodedResponse = credential.toJSON();
+  try {
+    const response = await registerVerifyFetch(encodedResponse);
+    if (!response.ok) {
+      // If the server verification fails, clean up using Signal API
+      if (PublicKeyCredential.signalUnknownCredential) {
+        await PublicKeyCredential.signalUnknownCredential({
+          rpId, // RP ID must match the one defined on the server
+          credentialId: encodedResponse.id
+        });
+      }
+    }
+  } catch (serverErr) {
+    console.error('Verification network failure:', serverErr);
+    if (PublicKeyCredential.signalUnknownCredential) {
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId, // RP ID must match the one defined on the server
+        credentialId: encodedResponse.id
+      });
+    }
+  }
+}
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Signal API Synchronization Fallback
+
+Browser support for Web authentication signal methods: Limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive optimization used to keep password managers in sync with the server credential state.
+*   **Fallback Experience**: Gated via `if (PublicKeyCredential.signalUnknownCredential)`. If unsupported, the background verification sync is bypassed gracefully without throwing browser exceptions.
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseCreationOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseCreationOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-management.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-management.md
new file mode 100644
index 00000000..f258c26f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-management.md
@@ -0,0 +1,235 @@
+# Passkey Management
+
+This guide details how to enable users to view, rename, and delete their registered passkeys while keeping saved credentials and user profile details synchronized between the server and the user's password managers using the Signal API.
+
+## Server-Side Operations
+
+Your backend database layer and endpoints MUST support common CRUD actions for registered credentials as well as updating user profile details. Decoupled from framework-specific libraries, the server exposes endpoints to:
+
+1.  **List all user credentials**: Fetch all `StoredPasskeyCredential` records matching the signed-in user's ID.
+2.  **Update credential names**: Accept a new custom nickname for a specific credential ID and persist the update on the server.
+3.  **Delete credentials**: Remove a specific credential ID from the database.
+4.  **Update user account details**: Accept updated `name` (username) and `displayName` values for the signed-in user's profile so the client can synchronize them with the passkey provider.
+
+```javascript
+// Node.js routing example for credential CRUD and user profile rename
+router.get('/api/credentials', checkUserAuthenticated, async (req, res) => {
+  const list = await db.findCredentialsByUserId(req.user.id);
+  return res.json(list);
+});
+
+router.put('/api/credential/:id', checkUserAuthenticated, async (req, res) => {
+  const { id } = req.params;
+  const { name } = req.body;
+  const cred = await db.findCredentialById(id);
+  if (!cred || cred.passkeyUserId !== req.user.id) {
+    return res.status(404).json({ error: 'Credential not found.' });
+  }
+  cred.name = name;
+  await db.saveCredential(cred);
+  return res.json(cred);
+});
+
+router.delete('/api/credential/:id', checkUserAuthenticated, async (req, res) => {
+  const { id } = req.params;
+  const cred = await db.findCredentialById(id);
+  if (!cred || cred.passkeyUserId !== req.user.id) {
+    return res.status(404).json({ error: 'Credential not found.' });
+  }
+  await db.deleteCredential(id);
+  return res.json({ success: true });
+});
+
+router.put('/api/user', checkUserAuthenticated, async (req, res) => {
+  const { name, displayName } = req.body;
+  const updatedUser = await db.updateUser(req.user.id, { name, displayName });
+  return res.json(updatedUser);
+});
+```
+
+## Client-Side Management UI
+
+Render a dedicated settings panel allowing users to easily audit and manage their registered authentication options and account profile details:
+
+1.  **Display saved list**: Fetch list from your endpoint and render individual credential rows. If the response is empty, render a helpful empty-state message (e.g., "No passkeys found").
+2.  **Map AAGUID Metadata**: For each passkey, lookup its `aaguid` property against your local registry to render its provider details. See [Determine the passkey provider from AAGUID](#aaguid) section for more details.
+3.  **Per-Item UI Requirements**: Every row inside the list container MUST render:
+    *   **Provider Icon**: AAGUID-derived image or data URI.
+    *   **Provider/Custom Name**: AAGUID-derived name or user-renamed string.
+    *   **Registration Date**: The database-persisted raw epoch timestamp `registeredAt` formatted to a human-readable date for client display.
+    *   **Last Used Date**: The database-persisted raw epoch timestamp `lastUsedAt` formatted to a human-readable date (if present) for client display.
+    *   **Rename Button**: Triggers a rename action to update the credential's custom nickname on the server (`PUT /api/credential/:id`). Note: Renaming an individual passkey's nickname is a server-side label change and does NOT invoke `signalCurrentUserDetails()`.
+    *   **Delete Button**: Triggers deletion of the credential (`DELETE /api/credential/:id`) and synchronizes the remaining credential IDs via `signalAllAcceptedCredentials()`.
+4.  **User Account Rename UI**:
+    *   Provide a control allowing the user to update their account username (`name`) or `displayName` (`PUT /api/user`), and immediately synchronize the updated user details with the password manager via `PublicKeyCredential.signalCurrentUserDetails()`.
+5.  **Conditional "Create Passkey" Button**:
+    *   Offer a prominent "Create passkey" registration trigger button on the management page. Before rendering this UI element, the page MUST feature-detect capabilities using `PublicKeyCredential.getClientCapabilities()` to verify platform authenticator is supported. If passkeys are unsupported, hide this button and gracefully encourage standard MFA enrollments instead.
+    *   Allow registering a security key by omitting `authenticatorSelection.authenticatorAttachment` on `navigator.credentials.create()` call.
+
+## Signal API Synchronization
+
+The Signal API lets the application communicate credential states to password managers, keeping the user's synced vaults and your backend database in lockstep.
+
+*   **Feature Detection & Parameter Encoding Rule**:
+    *   Always feature-detect Signal API methods before invoking them (`if (PublicKeyCredential.signalAllAcceptedCredentials)` and `if (PublicKeyCredential.signalCurrentUserDetails)`).
+    *   All `userId` and credential ID parameters passed to Signal API methods (`signalAllAcceptedCredentials`, `signalCurrentUserDetails`) MUST be **Base64URL-encoded strings**.
+*   **Initiating Page Load Sync**:
+    *   The application MUST invoke `signalAllAcceptedCredentials()` automatically when the management page loads (for example, inside a `DOMContentLoaded` event listener, module initialization, or framework component mount hook such as `useEffect`).
+*   **Management Updates Sync**:
+    *   The application MUST invoke `signalAllAcceptedCredentials()` immediately within your delete credential click handler post-fetch.
+    *   The application MUST invoke `signalCurrentUserDetails()` immediately within your user account rename (`name` or `displayName`) click handler post-fetch.
+
+```javascript
+// Client-side management synchronization ES module
+import { listFetch, renameCredentialFetch, updateUserFetch, deleteFetch } from './api.js';
+
+// Base64URL-encoded User ID string (illustration only)
+const base64UrlUserId = "M2YPl-KGnA8";
+
+async function syncAcceptedCredentials(currentCredentialsList) {
+  if (!window.PublicKeyCredential || !PublicKeyCredential.signalAllAcceptedCredentials) return;
+  try {
+    const credentialIds = currentCredentialsList.map(c => c.id); // Array of Base64URL credential ID strings
+    
+    await PublicKeyCredential.signalAllAcceptedCredentials({
+      rpId, // RP ID must match the one defined on the server
+      userId: base64UrlUserId, // User ID Base64URL-encoded string
+      allAcceptedCredentialIds: credentialIds
+    });
+  } catch (e) {
+    console.error('SignalAllAcceptedCredentials sync failure:', e);
+  }
+}
+
+async function loadManagementPanel() {
+  const response = await listFetch();
+  const list = await response.json();
+  
+  renderUI(list);
+  // Sync accepted credentials on initial load
+  await syncAcceptedCredentials(list);
+}
+
+async function performDelete(credentialId) {
+  const response = await deleteFetch(credentialId);
+  if (response.ok) {
+    const updatedResponse = await listFetch();
+    const updatedList = await updatedResponse.json();
+    
+    renderUI(updatedList);
+    // Sync remaining accepted credentials after deletion
+    await syncAcceptedCredentials(updatedList);
+  }
+}
+
+// Renaming a passkey's nickname updates the server record only
+async function performCredentialRename(credentialId, newCredentialName) {
+  const response = await renameCredentialFetch(credentialId, { name: newCredentialName });
+  if (response.ok) {
+    const updatedResponse = await listFetch();
+    renderUI(await updatedResponse.json());
+  }
+}
+
+// Renaming the user's account username or displayName triggers signalCurrentUserDetails
+async function performUserRename(rpId, userId, updatedName, updatedDisplayName) {
+  const response = await updateUserFetch({ name: updatedName, displayName: updatedDisplayName });
+  if (response.ok && window.PublicKeyCredential && PublicKeyCredential.signalCurrentUserDetails) {
+    try {
+      await PublicKeyCredential.signalCurrentUserDetails({
+        rpId, // RP ID must match the one defined on the server
+        userId, // Base64URL-encoded user ID
+        name: updatedName, // Updated username
+        displayName: updatedDisplayName // Updated display name
+      });
+    } catch (e) {
+      console.error('SignalCurrentUserDetails sync failure:', e);
+    }
+  }
+}
+
+window.addEventListener('DOMContentLoaded', loadManagementPanel);
+```
+
+## Determine the passkey provider from AAGUID {: #aaguid }
+
+An AAGUID (Authenticator Attestation Globally Unique Identifier) is a 128-bit identifier that represents the model of the authenticator, not a specific instance. It is included in the authenticator data during passkey registration and can be used to determine which passkey provider (e.g. Google Password Manager, iCloud Keychain, 1Password) created a credential.
+
+AAGUID should only be used to help users with passkey management. It can be modified unless cryptographically attested, which platform passkeys currently don't support.
+
+### 1. AAGUID Registry
+
+A community-maintained JSON mapping of AAGUIDs to provider names and icons is available at:
+
+```
+https://raw.githubusercontent.com/passkeydeveloper/passkey-authenticator-aaguids/refs/heads/main/combined_aaguid.json
+```
+
+Each entry has the following schema:
+
+```json
+{
+  "<aaguid-uuid>": {
+    "name": "Provider Name",
+    "icon_light": "data:image/png;base64,...",
+    "icon_dark": "data:image/png;base64,..."
+  }
+}
+```
+
+### 2. Using AAGUID After Registration
+
+After verifying a registration response, read the `aaguid` from the registration result and look it up against the registry to populate the credential's `name` and `providerIcon`:
+
+Before looking up the AAGUID in the registry, check if it equals `'00000000-0000-0000-0000-000000000000'`. If so, skip the registry lookup and set `name` to a fallback (e.g. device name from user-agent, or "Unknown passkey provider") and `providerIcon` to `undefined`. Only look up the registry for non-zeroed AAGUIDs.
+
+```javascript
+import aaguids from './aaguids.json' with { type: 'json' };
+
+const { aaguid } = registrationInfo;
+if (aaguid === '00000000-0000-0000-0000-000000000000') {
+  // use the device name as the passkey provider based on
+  // the information derived from the user agent string,
+  // or just say "Unknown passkey provider"
+} else {
+  const provider = aaguids[aaguid];
+  const credential = {
+    // ...other fields
+    aaguid,
+    name: provider?.name || 'Unknown passkey provider',
+    providerIcon: provider?.icon_light,
+  };
+}
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Signal API Synchronization Fallback
+
+Browser support for Web authentication signal methods: Limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+If the browser does not support `PublicKeyCredential.parseRequestOptionsFromJSON`, use the 'webauthn-polyfills': 
+  
+```html 
+<script type="module"> 
+  if (!PublicKeyCredential.parseRequestOptionsFromJSON) { 
+     await import('https://unpkg.com/webauthn-polyfills'); 
+   } 
+ </script> 
+ ``` 
+
+This will also add support for `PublicKeyCredential.prototype.toJSON`.
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-reauthentication.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-reauthentication.md
new file mode 100644
index 00000000..178931d3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-reauthentication.md
@@ -0,0 +1,128 @@
+# Passkey Reauthentication
+
+This delta-focused guide details how to implement step-up authentication or re-verification for a signed-in user before they perform sensitive account changes (e.g. passwords updates, financial transfers).
+
+## Delta Flow Architecture
+
+Unlike regular authentication, passkey reauthentication constrains passkey dialog prompts strictly to the logged-in user's pre-registered credentials to prevent account-mixing or passkey spoofing during active sessions.
+
+## Server-Side
+
+### Options Generation Delta
+
+Create an endpoint that populates the allowed credentials parameters specifically for the active, known user:
+
+**Constrain Credentials**: Populate the `allowCredentials` options array with specific `PublicKeyCredentialDescriptor` records mapping all registered credential IDs for the signed-in user. Leaving this empty or omitting it regresses to discoverable credentials, violating session safety.
+
+```javascript
+// Node.js step-up options generation example
+router.post("/api/reauth/options", enforceActiveSession, async (req, res) => {
+  const userPasskeys = await db.findCredentialsByUserId(req.user.id);
+
+  const options = {
+    challenge: serverGeneratedBase64UrlChallenge, // Random challenge stored in user session
+    rpId: "example.com",
+    // Enforce allowance strictly limited to the user's credentials list
+    allowCredentials: userPasskeys.map((cred) => ({
+      type: "public-key",
+      id: cred.id,
+      transports: cred.transports, // Speeds up resolution by indicating platform transports
+    })),
+  };
+  return res.json(options);
+});
+```
+
+### Verification Endpoint Delta
+
+Verify the assertion returned by the client:
+
+**Verify Account Ownership**: The verification endpoint MUST explicitly verify that the resulting authenticated credential ID returned by the client resolves to a stored credential record whose associated user ID strictly matches the active signed-in user (`storedCredential.passkeyUserId === req.user.id`). If a valid passkey of a _different_ user is returned, authentication MUST be rejected immediately.
+
+## Client-Side Flow Deltas
+
+Applications choose from two reauthentication interfaces depending on the transaction UI:
+
+### A. Button Flow (No Input Fields)
+
+Trigger reauthentication when a user presses a "Verify Identity" or "Proceed with Transaction" button.
+
+```html
+<button id="reauth-btn" data-testid="reauth-button">Confirm Transaction</button>
+```
+
+```javascript
+let reauthAbortController = new AbortController();
+
+async function triggerButtonReauth() {
+  // Abort any background suggestion flows to avoid passkey prompt collisions
+  reauthAbortController.abort();
+  reauthAbortController = new AbortController();
+
+  const optionsResponse = await fetch("/api/reauth/options", {
+    method: "POST",
+  });
+  const optionsJSON = await optionsResponse.json();
+  const publicKey =
+    PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);
+
+  try {
+    const credential = await navigator.credentials.get({
+      publicKey,
+      signal: reauthAbortController.signal,
+    });
+
+    if (credential) {
+      const encodedCredential = credential.toJSON();
+      const verifyResponse = await fetch("/api/reauth/verify", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(encodedCredential),
+      });
+
+      if (verifyResponse.ok) {
+        showTransactionSuccessUI();
+      } else if (verifyResponse.status === 404 && PublicKeyCredential.signalUnknownCredential) {
+        await PublicKeyCredential.signalUnknownCredential({
+          rpId, // RP ID must match the one defined on the server
+          credentialId: encodedCredential.id
+        });
+      }
+    }
+  } catch (err) {
+    if (err.name === "NotAllowedError") {
+      console.log("User cancelled reauthentication.");
+    }
+  }
+}
+
+document
+  .getElementById("reauth-btn")
+  .addEventListener("click", triggerButtonReauth);
+```
+
+## Fallback Strategies
+
+### Passkey feature detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.getClientCapabilities` is also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseRequestOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseRequestOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-registration.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-registration.md
new file mode 100644
index 00000000..e260d10f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkey-registration.md
@@ -0,0 +1,181 @@
+# Passkey Registration
+
+This guide details how to enable users to register a passkey for their account, providing a highly secure, phishing-resistant passwordless sign-in alternative.
+
+## Database Requirements
+
+To support passkey registrations, your database credential table must store the following fields:
+
+```typescript
+export interface StoredPasskeyCredential {
+  id: string; // Base64URL-encoded credential ID (unique lookup key)
+  passkeyUserId: string; // Associated application user ID
+  credentialPublicKey: string; // Base64URL-encoded public key used to verify assertion signatures
+  credentialType: "public-key";
+  credentialDeviceType: "singleDevice" | "multiDevice"; // Helps distinguish device-bound vs cloud-synced passkeys
+  credentialBackedUp: boolean; // Boolean backup state reported by the authenticator
+  aaguid: string; // Authenticator Attestation GUID
+  providerIcon?: string; // Provider icon derived from the AAGUID registry (dark or light theme URLs)
+  name: string; // Provider name derived from AAGUID registry
+  transports: string[]; // Array of transport names (e.g. 'internal', 'hybrid') necessary for exclusion options
+  lastUsedAt?: number; // Optional epoch timestamp of last sign-in
+  registeredAt: number; // Registration epoch timestamp
+  counter: number; // Authenticator sign-in signature counter used to prevent replay attacks
+}
+```
+
+## Server-Side
+
+### Options Generation
+
+Create an endpoint that generates WebAuthn creation parameters. Rely on a vetted library per category standards instead of hand-rolling cryptography.
+
+1.  **Use the predefined RP ID**: Use the predefined proper RP ID as a constant string.
+2.  **Create a secure Challenge**: Generate a high-entropy, cryptographically secure random buffer on the server, store it securely in the user's session, and encode it as Base64URL for options delivery.
+3.  **Avoid Duplicate Passkeys**: Map the user's existing pre-registered credential IDs to the `excludeCredentials` options array. This prevents the authenticator from registering duplicate credentials on the same passkey provider account.
+4.  **Enforce Discoverable Credentials**: Set `requireResidentKey: true` and `residentKey: "required"` in the `authenticatorSelection` options to request a discoverable credential, which is necessary for discoverable sign-ins.
+5.  **Configure User Verification**: Specify `userVerification: "preferred"` or `userVerification: "required"`. Many compliance use cases (e.g., finance, healthcare) require `'required'` to enforce user verification on creation.
+6.  **Determine Attachment Scope**:
+    - **Promotion Flow**: When proposing passkey creation right after standard password sign-ins or post-signup promotions, set `authenticatorAttachment: "platform"` to enforce platform authenticator and bypass external security key prompts.
+    - **Management Flow**: When called from a dedicated settings or security panel where external security keys are supported in addition to platform authenticator, omit the `authenticatorAttachment` property entirely.
+    - _Tip_: Accept a `promotion: boolean` request flag to conditionally handle both flows with a single endpoint.
+
+```javascript
+// Options generation example
+const options = {
+  challenge: serverGeneratedBase64UrlChallenge, // Cryptographically random challenge
+  rp: { id: "example.com", name: "Secure Application" },
+  user: {
+    id: userBase64UrlId, // Unique base64url string identifying the account
+    name: "user@example.com",
+    displayName: "Jane Doe",
+  },
+  pubKeyCredParams: [
+    {
+      type: "public-key",
+      alg: -7,
+    },
+    {
+      type: "public-key",
+      alg: -257,
+    },
+  ],
+  excludeCredentials: userExistingCredentials.map((cred) => ({
+    type: "public-key",
+    id: cred.id,
+    transports: cred.transports,
+  })),
+  authenticatorSelection: {
+    residentKey: "required",
+    requireResidentKey: true,
+    userVerification: "preferred",
+    ...(isPromotionFlow && { authenticatorAttachment: "platform" }),
+  },
+};
+```
+
+### Verification
+
+1.  **Challenge Verification**: Securely verify the challenge against the expected session bound challenge.
+2.  **Verify User Presence**:
+    - Ensure that the User Present (UP) flag returned in the parsed authenticator data is `true` to confirm physical user presence at the time of creation.
+3.  **Relaxing Verification for 'preferred'**:
+    - When the creation options specified `userVerification: "preferred"`, the server-side verification call MUST be configured with `requireUserVerification: false`. Otherwise, authenticators that register without user verification (e.g., screen locks disabled) will trigger spurious server verification failures.
+
+## Client-Side Logic
+
+1.  **Gate the UI on page load**:
+    - On page load, call `PublicKeyCredential.getClientCapabilities()` and **disable the "Create passkey" button** if `conditionalGet` or `passkeyPlatformAuthenticator` is not available.
+2.  **Invoke creation & Serialize**: Decode server options with `PublicKeyCredential.parseCreationOptionsFromJSON()` and pass the resulting configuration to `navigator.credentials.create()`.
+    - Call `credential.toJSON()` to encode the `AuthenticatorAttestationResponse` into a valid, JSON-serializable object before fetching the verification endpoint.
+3.  **Handle WebAuthn Exceptions**:
+    - `InvalidStateError`: A matching passkey already exists (matched by `excludeCredentials`).
+    - `NotAllowedError`: The user cancelled or timed out the authentication passkey dialog.
+    - `AbortError`: The operation has been aborted.
+    - `SecurityError`: Secure origins (HTTPS) or RP ID mismatch errors (configuration issues).
+4.  **Try/Catch Segregation for Signal API**:
+    - Wrap server verification `fetch()` call in a try/catch block. Call `signalUnknownCredential()` when the server verification fetch fails (any status `response.ok === false` or network throws).
+
+```javascript
+// optionsFetch and registerVerifyFetch are app-defined HTTP methods
+import { optionsFetch, registerVerifyFetch } from "./api.js";
+
+async function registerPasskey(isPromotion = false) {
+  // Verify passkey capability and conditional UI are available
+  const capabilities = await PublicKeyCredential.getClientCapabilities();
+  if (
+    !capabilities.passkeyPlatformAuthenticator ||
+    !capabilities.conditionalGet
+  ) {
+    // Hide "Create passkey" buttons and fall back to password flows instead
+    showStandardPasswordFallbackUI();
+    return;
+  }
+
+  const creationOptionsJSON = await optionsFetch({ promotion: isPromotion });
+  const publicKey =
+    PublicKeyCredential.parseCreationOptionsFromJSON(creationOptionsJSON);
+
+  let credential;
+  try {
+    // passkey prompt execution
+    credential = await navigator.credentials.create({ publicKey });
+  } catch (err) {
+    if (err.name === "InvalidStateError") {
+      console.log("A passkey already exists for this account.");
+      alert("A passkey already exists for this account.");
+    } else if (err.name === "SecurityError") {
+      console.error("Configuration RP ID or Secure Context error.");
+      alert("Configuration RP ID or Secure Context error.");
+    } else if (err.name === "NotAllowedError") {
+      console.log("User cancelled the passkey dialog.");
+    } else if (err.name === "AbortError") {
+      console.log("The creation operation has been aborted.");
+    }
+    return; // Safe API exit, do not signal unknown for standard WebAuthn cancels
+  }
+
+  // Server Verification phase (Segregated Try/Catch)
+  let encodedResponse = credential.toJSON();
+  try {
+    const response = await registerVerifyFetch(encodedResponse);
+    if (!response.ok) {
+      // Server verification failed to verify/authenticate the credential (orphaned)
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId, // RP ID must match the one defined on the server
+        credentialId: encodedResponse.id, // Base64URL-encoded credential ID
+      });
+    }
+  } catch (serverErr) {
+    console.error("Server verification network failure:", serverErr);
+    await publickeycredential.signalunknowncredential({
+      rpId, // RP ID must match the one defined on the server
+      credentialid: encodedresponse.id, // base64url-encoded credential id
+    });
+  }
+}
+```
+
+## Fallback Strategies
+
+### Signal API Synchronization Fallback
+
+Browser support for Web authentication signal methods: Limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive optimization used to keep password managers in sync with the server credential state.
+
+- **Fallback Experience**: If `PublicKeyCredential.signalUnknownCredential` is unsupported by the browser, the call MUST be bypassed safely via feature detection gating (`if (PublicKeyCredential.signalUnknownCredential)`), and the server-side verification simply logs the failure without triggering manager updates.
+
+### Easy JSON Serialization Fallback
+
+Baseline status for the api.PublicKeyCredential.parseCreationOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install 'webauthn-polyfills' and import it in the context.
+Consider as long as  `PublicKeyCredential` is supported, `PublicKeyCredential.parseCreationOptionsFromJSON` and `PublicKeyCredential.prototype.toJSON` are also supported. 
+
+```js 
+import 'webauthn-polyfills';
+``` 
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkeys.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkeys.md
new file mode 100644
index 00000000..be2df600
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/passkeys.md
@@ -0,0 +1,39 @@
+# Passkeys Orientation
+
+This guide provides high-density, action-oriented orientation for implementing secure, framework-agnostic passkey authentication and credential management in modern web applications.
+
+## 1. Core Prerequisites for Passkeys
+
+Passkeys rely on the Web Authentication API (WebAuthn), which imposes strict cross-cutting security constraints that must be satisfied before any implementation attempt:
+*   **Secure Contexts**: WebAuthn methods (`navigator.credentials.create` and `navigator.credentials.get`) are strictly gated behind Secure Contexts. Applications MUST run on `https://` in production, or `http://localhost` for local development.
+*   **Relying Party (RP) ID**: Every credential is tied to an RP ID (essentially the domain name of the application). The RP ID passed in the server-side options MUST match or be a valid suffix of the current origin's domain name (e.g., `example.com` is valid for `login.example.com`). Mismatches result in `SecurityError` exceptions on the client side.
+
+## 2. The AAGUID UX Caveat
+
+The Authenticator Attestation Globally Unique Identifier (AAGUID) is a 128-bit identifier returned in the registration attestation data that represents the model/provider of the authenticator (e.g., Google Password Manager, iCloud Keychain, 1Password).
+*   **UX Hinting Only**: Relying Parties MUST use the AAGUID exclusively for UX hints (such as rendering the passkey provider name and icon in a management list to help the user).
+*   **No Security Dependencies**: applications MUST NOT use AAGUID for cryptographic security or access decisions. Platform passkeys do not currently provide cryptographic attestation for their AAGUIDs, meaning it can be altered or simulated by user agents.
+
+## 3. Decoupled Library Recommendations
+
+For backend FIDO2/WebAuthn options generation and signature verification, developers MUST rely on vetted open source libraries per language instead of hand-rolling cryptography:
+*   **JavaScript/TypeScript**: SimpleWebAuthn (github.com/MasterKale/SimpleWebAuthn)
+*   **Python**: py_webauthn (github.com/duo-labs/py_webauthn)
+*   **Java**: Java WebAuthn Server (github.com/Yubico/java-webauthn-server), WebAuthn4J (github.com/webauthn4j/webauthn4j)
+*   **.NET**: .NET library for FIDO2 (github.com/abergs/fido2-net-lib)
+*   **Go**: WebAuthn Go Library (github.com/go-webauthn/webauthn)
+*   **Ruby**: WebAuthn Ruby (github.com/cedarcode/webauthn-ruby)
+*   **PHP**: WebAuthn Framework (github.com/web-auth/webauthn-framework)
+
+## 4. Use Case Reference Matrix
+
+Identify the matching use case below and retrieve its full implementation guide. Every use case has critical APIs (`PublicKeyCredential.parseCreationOptionsFromJSON`, `parseRequestOptionsFromJSON`, `signalAllAcceptedCredentials`, `signalCurrentUserDetails`, `signalUnknownCredential`, conditional mediation, AAGUID handling, etc.) that are documented only in the per-use-case guide. Do NOT skip this retrieval step, and do NOT substitute third-party library wrappers (such as SimpleWebAuthn's `startAuthentication`/`startRegistration`) on the client — call the native WebAuthn browser APIs directly. Library recommendations in Section 3 apply to the **server-side** (backend FIDO2 verification) only.
+
+Specific passkey and WebAuthn implementation details are mapped to the following guides:
+*   **Passkey Registration**: `passkey-registration` (via `npx -y modern-web-guidance@latest retrieve "passkey-registration"`) — Offering new passkey registration and promotions.
+*   **Passkey Conditional Create**: `passkey-conditional-create` (via `npx -y modern-web-guidance@latest retrieve "passkey-conditional-create"`) — Silently registering passkeys immediately after successful password login.
+*   **Passkey Authentication**: `passkey-authentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-authentication"`) — Discoverable-autofill and button sign-ins.
+*   **Quick Sign-Ins**: `quick-sign-ins` (via `npx -y modern-web-guidance@latest retrieve "quick-sign-ins"`) — Contextual in-place sign-ins with local passkeys and saved passwords before page navigation.
+*   **Passkey Management**: `passkey-management` (via `npx -y modern-web-guidance@latest retrieve "passkey-management"`) — Syncing lists, renames, and deletions with password managers.
+*   **Passkey Reauthentication**: `passkey-reauthentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-reauthentication"`) — Re-verifying returning signed-in users for sensitive steps.
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/quick-sign-ins.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/quick-sign-ins.md
new file mode 100644
index 00000000..a9ba4736
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/quick-sign-ins.md
@@ -0,0 +1,242 @@
+# Quick sign-ins with immediate UI mode
+
+Navigating an unauthenticated user to a dedicated sign-in page when they click a "Sign in" link, start checkout, save an item to favorites, or reach an article paywall causes context loss and increases user drop-off. Immediate UI mode (`uiMode: 'immediate'` in `navigator.credentials.get()`) enables contextual quick sign-ins by presenting a unified browser account chooser immediately when local passkeys (`publicKey`) or saved passwords (`password: true`) exist on the device.
+
+Unlike standard modal WebAuthn prompts—which always display browser UI and fall back to cross-device QR codes or external security keys—Immediate UI mode fails fast with a `NotAllowedError` if no eligible credentials are locally available on the device. This lets your application authenticate returning users in place with a single tap while seamlessly transitioning users without local credentials to your standard sign-in page, guest checkout, or inline login form.
+
+## Recommended UX patterns and anti-patterns
+
+Trigger Immediate UI mode inside a user-initiated event handler (requiring transient user activation) at moments of clear user intent **right before** navigating away from the current page. If immediate authentication succeeds, complete the user's intent immediately (whether by updating the current page in place or proceeding directly to their authenticated destination). If it fails with `NotAllowedError`, show a sign-in or registration flow with a path to complete the user's intent on completion.
+
+Potential use cases:
+
+- **Header sign-in link or button interception**: Intercept a click on a global "Sign in" link (`event.preventDefault()`) to authenticate returning users immediately, or continue navigating to the dedicated sign-in page on `NotAllowedError`.
+- **Dynamic sign-in before checkout**: Authenticate returning shoppers with a single tap when they click "Proceed to checkout" so they land directly on the shipping and payment step, or transition to the standard sign-in or guest checkout screen on fallback.
+- **Inline sign-in for micro-actions (Favorite, Like, Bookmark, Save)**: Authenticate in place when a signed-out user clicks a micro-action button and immediately complete the action (for example, toggling `aria-pressed="true"`), or open a fallback login modal or sign-in page with a return URL parameter.
+- **In-article soft paywalls**: Authenticate readers in place when they click "Continue reading with your account" on a paywall banner, or expand an inline sign-in or registration form on fallback.
+
+Anti-patterns to avoid:
+
+- **DO NOT use Immediate UI mode on a dedicated sign-in page**: Never attach `uiMode: 'immediate'` to the primary "Sign in" or "Sign in with a passkey" button on your final destination sign-in page. Users reach the dedicated sign-in page specifically when they have no local credentials on the current device, or when they intend to use a cross-device passkey (scanning a QR code with a phone) or an external hardware security key. Because `uiMode: 'immediate'` suppresses cross-device QR code and security key options and immediately throws `NotAllowedError` when no local credentials exist, using it on a dedicated sign-in page traps the user in a dead end where clicking the button does nothing. On a dedicated sign-in page, use Conditional UI (`mediation: 'conditional'` with `autocomplete="username webauthn"`) on form inputs paired with a standard modal `navigator.credentials.get({ publicKey })` button (see `passkey-authentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-authentication"`)).
+- **DO NOT use Immediate UI mode for step-up reauthentication**: Never use `uiMode: 'immediate'` to reauthenticate an already signed-in user before sensitive operations (such as changing a password, updating a shipping address, editing saved payment methods, or adding a new passkey). Reauthentication must restrict the prompt to the signed-in user's credentials via a non-empty `allowCredentials` list, which Immediate UI mode rejects with `NotAllowedError`, and omitting `allowCredentials` would let the user inadvertently select a different account than the one currently signed in. For step-up reauthentication, follow `passkey-reauthentication` (via `npx -y modern-web-guidance@latest retrieve "passkey-reauthentication"`).
+
+## Privacy and security constraints
+
+Browsers enforce strict privacy and security rules when `uiMode: 'immediate'` is requested:
+
+- **Transient user activation is required**: You MUST call `navigator.credentials.get({ uiMode: 'immediate' })` inside a user-initiated event handler (such as a `click` listener on a `<button>` or `<a>` element) to prevent silent credential probing. Never invoke it automatically on page load (`DOMContentLoaded`). Calling the API does not consume the transient activation.
+- **Do not pass a non-empty `allowCredentials` list**: Do **NOT** populate `publicKey.allowCredentials` when `uiMode: 'immediate'` is specified. Browsers immediately reject any Immediate UI mode request with a non-empty `allowCredentials` list by throwing `NotAllowedError` so relying parties cannot probe for specific credential IDs to infer prior visits or track users across sessions.
+- **Do not pass an `AbortSignal` (`signal`)**: Do **NOT** set the `signal` property on `navigator.credentials.get()` when `uiMode: 'immediate'` is specified, as browsers disallow programmatic dismissal of the immediate login dialog. If your page also runs a background Conditional UI (`mediation: 'conditional'`) request, call `abort()` on that Conditional UI `AbortController` before invoking Immediate UI mode, and omit `signal` from the immediate request itself.
+- **Incognito and private browsing sessions**: Requests made in Incognito or private browsing windows always reject with `NotAllowedError` so private sessions remain indistinguishable from sessions without local credentials.
+
+## Server-side setup
+
+### Options generation endpoint
+
+Expose an endpoint that generates discoverable WebAuthn request options for unauthenticated visitors:
+
+1. **Generate a session-bound challenge**: Create a cryptographically random challenge buffer, store it in the server session, and encode it as Base64URL.
+2. **Persist user verification preference**: Set `userVerification: 'preferred'` and store `expectedUserVerification: 'preferred'` in the session.
+3. **Omit `allowCredentials`**: Do not include a non-empty `allowCredentials` list in the options for Immediate UI mode, as browsers reject non-empty allowlists with `NotAllowedError`.
+
+```javascript
+// Server-side options generation example (/api/login/options)
+router.post('/api/login/options', (req, res) => {
+  const options = {
+    challenge: serverGeneratedBase64UrlChallenge, // High-entropy random challenge stored in session
+    rpId: 'example.com',
+    userVerification: 'preferred',
+  };
+
+  req.session.challenge = options.challenge;
+  req.session.expectedUserVerification = 'preferred';
+  return res.json(options);
+});
+```
+
+### Dual credential verification endpoints
+
+Because `navigator.credentials.get({ password: true, publicKey, uiMode: 'immediate' })` can resolve with either a passkey (`PublicKeyCredential`) or a saved password (`PasswordCredential`), provide verification handlers for both credential types:
+
+1. **WebAuthn assertion verification (`/api/login/verify`)**: Verify the assertion against the session challenge and stored public key. If the credential ID is not found in the database, return HTTP status `404` so the client can notify the password manager via `PublicKeyCredential.signalUnknownCredential()`.
+2. **Password verification (`/api/login/password`)**: Verify the `username` (`cred.id`) and `password` (`cred.password`) against the user database and establish an authenticated session.
+
+## Client-side implementation
+
+### Unified credential request
+
+1. **Request both passkeys and passwords**: Decode the server options using `PublicKeyCredential.parseRequestOptionsFromJSON()` and call `navigator.credentials.get()` inside a user-initiated click handler with `password: true`, `publicKey`, and `uiMode: 'immediate'` (without passing `signal`).
+2. **Branch verification by `cred.type`**:
+    - If `cred.type === 'public-key'`, serialize the assertion with `cred.toJSON()` and POST it to your WebAuthn verification endpoint. When the server responds with HTTP `404`, call `PublicKeyCredential.signalUnknownCredential({ rpId: publicKey.rpId, credentialId: encoded.id })`.
+    - If `cred.type === 'password'`, POST `{ username: cred.id, password: cred.password }` to your password verification endpoint.
+3. **Handle `NotAllowedError` when no local credentials exist**: Catch `NotAllowedError` (thrown immediately when no local passkeys or saved passwords exist on the device, or when the user dismisses the chooser) and transition to your standard sign-in flow (such as opening an inline sign-in dialog or navigating to `/signin` with a return URL).
+
+```javascript
+let isAuthenticating = false;
+
+async function authenticateWithImmediateUi() {
+  const optionsResponse = await fetch('/api/login/options', { method: 'POST' });
+  if (!optionsResponse.ok) {
+    throw new Error('Failed to fetch authentication options');
+  }
+  const optionsJSON = await optionsResponse.json();
+  const publicKey = PublicKeyCredential.parseRequestOptionsFromJSON(optionsJSON);
+
+  // MANDATORY: Request both password and publicKey with uiMode: 'immediate' and NO signal parameter
+  const cred = await navigator.credentials.get({
+    password: true,
+    publicKey,
+    uiMode: 'immediate',
+  });
+
+  if (!cred) {
+    throw new DOMException('No credential returned', 'NotAllowedError');
+  }
+
+  if (cred.type === 'public-key') {
+    const encoded = cred.toJSON();
+    const verifyResponse = await fetch('/api/login/verify', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify(encoded),
+    });
+
+    if (verifyResponse.status === 404) {
+      await PublicKeyCredential.signalUnknownCredential({
+        rpId: publicKey.rpId || window.location.hostname,
+        credentialId: encoded.id, // Base64URL-encoded credential ID string
+      });
+      throw new Error('Passkey credential is no longer recognized by the server');
+    }
+
+    if (!verifyResponse.ok) {
+      throw new Error('Passkey verification failed');
+    }
+    return await verifyResponse.json();
+  }
+
+  if (cred.type === 'password') {
+    const verifyResponse = await fetch('/api/login/password', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({
+        username: cred.id,
+        password: cred.password,
+      }),
+    });
+
+    if (!verifyResponse.ok) {
+      throw new Error('Password verification failed');
+    }
+    return await verifyResponse.json();
+  }
+
+  throw new Error(`Unsupported credential type: ${cred.type}`);
+}
+
+// Example: Intercepting an inline micro-action (Favorite button) or Header Sign-in click
+const favoriteButton = document.getElementById('favorite-btn');
+
+favoriteButton.addEventListener('click', async (event) => {
+  event.preventDefault();
+  if (isAuthenticating) return;
+
+  // If already signed in, toggle the micro-action state immediately
+  if (document.body.dataset.signedIn === 'true') {
+    const nextPressed = favoriteButton.getAttribute('aria-pressed') !== 'true';
+    favoriteButton.setAttribute('aria-pressed', String(nextPressed));
+    return;
+  }
+
+  isAuthenticating = true;
+  try {
+    const user = await authenticateWithImmediateUi();
+    // Complete the user's intended action immediately
+    document.body.dataset.signedIn = 'true';
+    favoriteButton.setAttribute('aria-pressed', 'true');
+    updateHeaderUserState(user);
+  } catch (err) {
+    if (err.name === 'NotAllowedError') {
+      // No local credentials available or user dismissed dialog:
+      // transition smoothly to fallback sign-in UI or redirect with return URL
+      showFallbackSignInUi({ returnAction: 'favorite' });
+      return;
+    }
+    console.error('Authentication error:', err);
+  } finally {
+    isAuthenticating = false;
+  }
+});
+```
+
+## Fallback strategies
+
+### Immediate UI mode fallback
+
+- **Progressive enhancement experience**: Treat `uiMode: 'immediate'` as a progressive enhancement. Do not infer support from a browser's name or version; the only reliable support signal is the `capabilities.immediateGet` runtime check via `PublicKeyCredential.getClientCapabilities()`. **MANDATORY**: Always check `capabilities.immediateGet` before calling `navigator.credentials.get({ uiMode: 'immediate' })`—browsers that do not recognize `uiMode: 'immediate'` ignore the unknown dictionary key and open a blocking modal passkey and QR code dialog. When `capabilities.immediateGet` is falsy, or when `navigator.credentials.get()` rejects with `NotAllowedError`, fall back to your application's standard sign-in experience (such as opening an inline sign-in modal or navigating to the dedicated sign-in page with a return URL parameter), so users in unsupported browsers see your existing sign-in flow unchanged:
+
+```javascript
+async function isImmediateUiSupported() {
+  if (!window.PublicKeyCredential || !PublicKeyCredential.getClientCapabilities) {
+    return false;
+  }
+  try {
+    const capabilities = await PublicKeyCredential.getClientCapabilities();
+    return Boolean(capabilities?.immediateGet);
+  } catch {
+    return false;
+  }
+}
+
+async function authenticateWithImmediateUi() {
+  // MANDATORY: Check immediateGet support so unsupported browsers do not open a modal QR dialog
+  const supported = await isImmediateUiSupported();
+  if (!supported) {
+    // Throw NotAllowedError so the caller's single catch path treats "unsupported" like "no local credentials"
+    throw new DOMException('Immediate UI mode is not supported', 'NotAllowedError');
+  }
+  // Proceed with fetching options and calling navigator.credentials.get({ password: true, publicKey, uiMode: 'immediate' })
+}
+```
+
+### Client capabilities detection fallback
+
+Baseline status for the api.PublicKeyCredential.getClientCapabilities_static capability: Newly available. It's been Baseline since 2025-02-06.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), Firefox 135 (Feb 2025), and Safari 17.4 (Mar 2024).
+
+Always install `'webauthn-polyfills'` and import it in your client module so `PublicKeyCredential.getClientCapabilities()` is available whenever `PublicKeyCredential` is supported:
+
+```javascript
+import 'webauthn-polyfills';
+```
+
+### Password credentials fallback
+
+Browser support for Password credentials: Limited availability.
+Supported by: Chrome 60 (Jul 2017) and Edge 79 (Jan 2020).
+Unsupported in: Firefox and Safari.
+
+Passing `password: true` alongside `publicKey` in `navigator.credentials.get()` allows supporting browsers to include saved passwords from the browser's password manager in the unified immediate account chooser.
+
+- **Fallback experience**: Browsers that do not support `PasswordCredential` ignore the `password: true` option or fall back via the `capabilities.immediateGet` feature check to the standard sign-in form, where `<input autocomplete="username webauthn">` and `<input type="password" autocomplete="current-password">` provide native password autofill.
+
+### Easy JSON serialization fallback
+
+Baseline status for the api.PublicKeyCredential.parseRequestOptionsFromJSON_static capability: Newly available. It's been Baseline since 2025-03-31.
+Supported by: Chrome 129 (Sep 2024), Edge 129 (Sep 2024), Firefox 119 (Oct 2023), and Safari 18.4 (Mar 2025).
+
+Always install `'webauthn-polyfills'` and import it in the client bundle so `PublicKeyCredential.parseRequestOptionsFromJSON()` and `PublicKeyCredential.prototype.toJSON()` work consistently across browsers supporting `PublicKeyCredential`:
+
+```javascript
+import 'webauthn-polyfills';
+```
+
+### Signal API synchronization fallback
+
+Browser support for Web authentication signal methods: Limited availability.
+Supported by: Chrome 132 (Jan 2025), Edge 132 (Jan 2025), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The WebAuthn Signal API (`webauthn-signals`) is a progressive enhancement that removes stale passkeys from the user's password manager when the server responds with HTTP `404`.
+
+- **Fallback experience**: Gate calls behind `if (PublicKeyCredential.signalUnknownCredential)`. When unsupported, skip the signal call gracefully and display a clear message guiding the user to sign in with an alternative method.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/restrict-outbound-connections.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/restrict-outbound-connections.md
new file mode 100644
index 00000000..b33393ee
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/restrict-outbound-connections.md
@@ -0,0 +1,169 @@
+# Restrict outbound network connections with Connection Allowlists
+
+The `Connection-Allowlist` HTTP response header restricts a document or worker to communicating only with an explicit list of network endpoints. Unlike Content Security Policy (CSP)—which requires maintaining separate per-resource directives (`connect-src`, `img-src`, `script-src`, `font-src`, `form-action`) and does not govern speculative or non-Fetch network channels such as `<link rel="dns-prefetch">`, `<link rel="preconnect">`, or WebRTC—`Connection-Allowlist` enforces a single, network-layer allowlist across **all** outbound connections initiated by the context (`fetch()`, `XMLHttpRequest`, subresources, `navigator.sendBeacon()`, `<a ping>`, top-level and frame navigations, resource hints, Speculation Rules, `WebSocket`, `WebTransport`, and WebRTC).
+
+## How to implement
+
+1. **Serialize the allowlist as an RFC 9651 Inner List `(...)`**: Format `Connection-Allowlist` (or `Connection-Allowlist-Report-Only`) as a single parenthesized list of space-separated items. Include the unquoted token `response-origin` to permit the document or worker's own origin, followed by double-quoted `URLPattern` strings for every legitimate external endpoint the context connects or navigates to (APIs, image/font CDNs, and outbound `<a href>`, `<form action>`, OAuth, or payment redirect targets). When building patterns dynamically from configuration or `URL` objects, normalize `ws:`/`wss:` to `http:`/`https:` and strip bare trailing slashes on origin-only URLs (because `new URL('https://api.example.com').href` appends `/`, which restricts `URLPattern` matching to the root path `/` only).
+2. **Scope middleware by `Sec-Fetch-Dest` and cover workers**: Browsers only honor `Connection-Allowlist` on document/navigation responses and worker script responses (`Sec-Fetch-Dest` values `document`, `iframe`, `worker`, `sharedworker`, and `serviceworker`). When varying headers by `Sec-Fetch-Dest`, include `Vary: Sec-Fetch-Dest` so shared caches do not serve headerless responses. Serve a matching allowlist on Dedicated and Shared Worker scripts so compromised page scripts cannot exfiltrate data via `worker.postMessage()`. Because a Service Worker performs its own network fetches on cache misses and navigation preloads, configure its `Connection-Allowlist` as a **superset** of the allowlists of all documents it controls.
+3. **Configure violation reporting and staged or dual rollout**: Define a `Reporting-Endpoints` header and append an unquoted `; report-to=<endpoint-name>` parameter after the closing `)`. You can send `Connection-Allowlist-Report-Only` alone during initial rollout, or send **both** `Connection-Allowlist` (enforcing a baseline allowlist) and `Connection-Allowlist-Report-Only` (auditing a stricter candidate allowlist) on the same response. Violation reports are delivered with `"type": "connection-allowlist"` and body `{ url, connection, allowlist, disposition }` (where `connection` is the blocked destination URL or `"webrtc"`, and `disposition` is `"enforce"` or `"report"`).
+4. **Account for default redirect and WebRTC blocking, and handle client errors**: By default, `Connection-Allowlist` blocks all `3xx` HTTP redirects (`redirects=block`, even when redirecting between allowlisted or same-origin URLs) and all `RTCPeerConnection` traffic (`webrtc=block`). Append `; redirects=allow` only when trusted endpoints require server-side redirects (the initial request must still match the allowlist), or `; webrtc=allow` when WebRTC is required. On the client, wrap outbound `fetch()` calls in `try...catch` and handle `WebSocket` `error` events so requests rejected with `TypeError` (`net::ERR_NETWORK_ACCESS_REVOKED`) return a handled error state and update UI status instead of causing unhandled rejections.
+
+## Example code
+
+```http
+Vary: Sec-Fetch-Dest
+Reporting-Endpoints: conn-reports="https://app.example.com/api/security-reports"
+Connection-Allowlist: (response-origin "https://api.example.com" "https://realtime.example.com" "https://*.cdn.example.com/*"); report-to=conn-reports
+Connection-Allowlist-Report-Only: (response-origin "https://api.example.com/v2/*"); report-to=conn-reports
+```
+
+```javascript
+const ALLOWLIST_DESTS = new Set(['document', 'iframe', 'worker', 'sharedworker', 'serviceworker']);
+
+// Normalize a config URL or URLPattern string for Connection-Allowlist:
+// - Rewrites ws:// and wss:// to http:// and https:// (WebSocket matching rule).
+// - Strips a bare trailing slash on origin-only URLs (e.g. from new URL(...).href)
+//   so all subpaths on the origin are permitted instead of only "/".
+export function normalizeAllowlistPattern(rawPattern) {
+  const trimmed = String(rawPattern).trim().replace(/^ws(s?):\/\//i, 'http$1://');
+  if (!/^https?:\/\//i.test(trimmed)) {
+    throw new Error(`Pattern must include an http:// or https:// scheme: ${rawPattern}`);
+  }
+  if (/[\s,]/.test(trimmed)) {
+    throw new Error(`Pattern must be a single URLPattern without spaces or commas: ${rawPattern}`);
+  }
+  if (/[()]/.test(trimmed)) {
+    throw new Error(`Custom regex groups are rejected by Connection-Allowlist: ${rawPattern}`);
+  }
+  return trimmed.replace(/^(https?:\/\/[^/?#]+)\/$/i, '$1');
+}
+
+// Build an RFC 9651 Inner List value for Connection-Allowlist or Connection-Allowlist-Report-Only.
+export function buildConnectionAllowlistHeader({
+  allowSelf = true,
+  patterns = [],
+  reportTo,
+  redirects = 'block',
+  webrtc = 'block',
+} = {}) {
+  const items = allowSelf ? ['response-origin'] : [];
+  for (const pattern of patterns) {
+    const raw = String(pattern).trim();
+    if (raw === 'response-origin') {
+      if (!items.includes('response-origin')) items.push('response-origin');
+      continue;
+    }
+    const normalized = normalizeAllowlistPattern(raw);
+    items.push(`"${normalized.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`);
+  }
+  let header = `(${items.join(' ')})`;
+  if (redirects === 'allow') header += '; redirects=allow';
+  if (webrtc === 'allow') header += '; webrtc=allow';
+  if (reportTo) {
+    const endpointToken = String(reportTo).trim().replace(/^"+|"+$/g, '');
+    header += `; report-to=${endpointToken}`;
+  }
+  return header;
+}
+
+// Server or middleware helper applying Connection-Allowlist and Reporting-Endpoints
+// on document and worker responses.
+export function setConnectionAllowlistHeaders(res, options = {}) {
+  const {
+    secFetchDest = 'document',
+    patterns = ['https://api.example.com', 'https://realtime.example.com', 'https://*.cdn.example.com/*'],
+    reportOnlyPatterns,
+    reportEndpointName = 'conn-reports',
+    reportEndpointUrl = 'https://app.example.com/api/security-reports',
+    redirects = 'block',
+    webrtc = 'block',
+    reportOnly = false,
+  } = options;
+
+  const setHeader = (name, value) =>
+    typeof res.setHeader === 'function' ? res.setHeader(name, value) : res.headers.set(name, value);
+
+  if (typeof res.appendHeader === 'function') {
+    res.appendHeader('Vary', 'Sec-Fetch-Dest');
+  } else if (typeof res.headers?.append === 'function') {
+    res.headers.append('Vary', 'Sec-Fetch-Dest');
+  } else {
+    setHeader('Vary', 'Sec-Fetch-Dest');
+  }
+  if (secFetchDest && !ALLOWLIST_DESTS.has(String(secFetchDest).toLowerCase())) return;
+
+  setHeader('Reporting-Endpoints', `${reportEndpointName}="${reportEndpointUrl}"`);
+  setHeader(
+    reportOnly ? 'Connection-Allowlist-Report-Only' : 'Connection-Allowlist',
+    buildConnectionAllowlistHeader({ allowSelf: true, patterns, reportTo: reportEndpointName, redirects, webrtc }),
+  );
+
+  if (!reportOnly && Array.isArray(reportOnlyPatterns)) {
+    setHeader(
+      'Connection-Allowlist-Report-Only',
+      buildConnectionAllowlistHeader({
+        allowSelf: true,
+        patterns: reportOnlyPatterns,
+        reportTo: reportEndpointName,
+        redirects,
+        webrtc,
+      }),
+    );
+  }
+}
+
+// Client-side helper that catches blocked outbound requests gracefully without unhandled rejections.
+export async function fetchWithPolicyHandling(url, { statusElement, ...fetchOptions } = {}) {
+  try {
+    const response = await fetch(url, fetchOptions);
+    if (!response.ok) throw new Error(`HTTP ${response.status}`);
+    const body = await response.text();
+    if (statusElement) {
+      statusElement.textContent = `Allowed: Loaded ${url} (${body.length} bytes).`;
+    }
+    return { ok: true, body, error: null };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (statusElement) {
+      statusElement.textContent = `Blocked: Request to ${url} was rejected by the outbound connection policy (${message}).`;
+    }
+    return { ok: false, body: null, error };
+  }
+}
+```
+
+## Best practices
+
+- **DO** format `Connection-Allowlist` as a single RFC 9651 Inner List `(...)` of space-separated items. If a non-empty `Connection-Allowlist` header fails top-level Structured Field parsing (for example, omitting `(...)` or using single quotes `'...'`), the browser fails closed with an empty allowlist and blocks **all** outbound network connections. Use `Connection-Allowlist: ()` when you intentionally want to revoke all network access after load (local schemes `data:`, `blob:`, `about:`, and `filesystem:` remain permitted).
+- **DO** omit the trailing slash on origin-wide URL patterns (`"https://api.example.com"`) or use an explicit wildcard (`"https://api.example.com/*"`) so subpaths like `/v1/users` are permitted. Strip trailing slashes added by `new URL(origin).href` before serializing patterns.
+- **DO** allowlist `WebSocket` (`ws://` and `wss://`) endpoints using `"http://..."` and `"https://..."` patterns in `Connection-Allowlist`, because the browser normalizes WebSocket schemes to HTTP/HTTPS before matching.
+- **DO** include expected external navigation targets (`<a href>`, `<form action>`, OAuth/SSO providers, payment checkouts) in a restricted document's allowlist, and remember that the default `redirects=block` blocks even same-origin `3xx` redirects unless `; redirects=allow` is specified.
+- **DO NOT** wrap `response-origin` or inner-list parameter values (`; report-to=conn-reports`, `; redirects=allow`, `; webrtc=allow`) in quotes, or separate items inside `(...)` with commas.
+- **DO NOT** use custom regular expression groups such as `(\d+)` or relative paths such as `"/api/*"` inside URL patterns; the browser's network-service parser rejects regex groups and patterns without a scheme and hostname.
+- **DO NOT** rely on the experimental `<iframe connectionAllowlist="...">` attribute or `Allow-Connection-Allowlist-From` embedded enforcement header in production yet, as embedded enforcement is not enabled by default in shipping browsers.
+
+## Fallback strategy
+
+Browser support for Connection allowlists: Limited availability.
+Supported by: Chrome 152 (Aug 2026) and Edge 152 (Aug 2026).
+Unsupported in: Firefox and Safari.
+
+Because `Connection-Allowlist` is enforced at the browser network layer via an HTTP response header, it cannot be polyfilled in client-side JavaScript. If your Baseline target includes browsers that do not yet support `Connection-Allowlist`, **pair `Connection-Allowlist` with a `Content-Security-Policy` (CSP) header** (and a `<meta http-equiv="Content-Security-Policy">` element for document-level fetch and subresource restrictions when HTTP response headers cannot be configured):
+
+- **Additive defense-in-depth**: Supporting browsers enforce both policies simultaneously—`Connection-Allowlist` blocks non-CSP exfiltration channels (`dns-prefetch`, `preconnect`, WebRTC, and redirects), while CSP restricts `fetch()`, subresources, and `<form action>` navigations in browsers without `Connection-Allowlist`.
+- **Cover `form-action` and `worker-src` explicitly**: In CSP, `default-src` does **not** fall back for `<form action>` submissions; always include `form-action` explicitly. Include `worker-src 'self'` (excluding `blob:`) so restricted pages cannot spawn `blob:` SharedWorkers to bypass document-level restrictions.
+- **Map allowed origins to per-resource CSP directives**: Unlike `Connection-Allowlist` (which uses a single endpoint list and does not govern inline markup), `default-src 'self'` in CSP restricts each resource type (`connect-src`, `img-src`, `style-src`, `font-src`, `script-src`) and blocks inline `<style>` and `<script>` blocks unless authorized via hashes or nonces.
+- **Include `wss://` in CSP `connect-src`**: While `Connection-Allowlist` matches `wss://` connections against `"https://..."` patterns, CSP `connect-src` in cross-browser environments should explicitly list `wss://` origins when WebSockets are used.
+
+```http
+Content-Security-Policy: default-src 'self'; connect-src 'self' https://api.example.com https://realtime.example.com wss://realtime.example.com; img-src 'self' https://*.cdn.example.com data: blob:; form-action 'self'; worker-src 'self'; object-src 'none'; base-uri 'self'; report-to conn-reports
+```
+
+```html
+<!-- Document-level fallback when HTTP response headers cannot be set on static hosting -->
+<meta
+  http-equiv="Content-Security-Policy"
+  content="default-src 'self'; connect-src 'self' https://api.example.com https://realtime.example.com wss://realtime.example.com; img-src 'self' https://*.cdn.example.com data: blob:; form-action 'self'; worker-src 'self'; object-src 'none'; base-uri 'self'"
+/>
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/sanitize-untrusted-html.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/sanitize-untrusted-html.md
new file mode 100644
index 00000000..a1a051bb
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/sanitize-untrusted-html.md
@@ -0,0 +1,105 @@
+# Sanitizing Untrusted HTML
+
+Safely displaying user-generated HTML is a common security challenge. The native **Sanitizer API** provides a built-in, browser-optimized way to strip dangerous content (like `<script>` tags or `on*` attributes) before it reaches the DOM.
+
+Client-side sanitization protects the page that renders the content. If the same user-generated content is also rendered elsewhere (other clients, server-rendered pages, or emails), sanitize it on the server as well as defence in depth, and make sure the server and client sanitization rules do not conflict.
+
+## 1. Safely Inserting HTML with `setHTML()`
+
+The primary way to use the Sanitizer API is through the `setHTML()` method on any `Element`. This method handles parsing, sanitization and insertion in a single step, ensuring that content is sanitized specifically for the context in which it will be inserted.
+
+```javascript
+const untrustedHTML = `
+  <p>Hello!</p>
+  <script>alert('XSS')</script>
+  <img src="x" onerror="alert('XSS')">
+  <div onclick="doBadThing()">Click me</div>
+`;
+
+const container = document.getElementById('output');
+
+// Sanitize and insert in one call
+// The default sanitizer removes scripts and event handlers, plus other
+// elements and attributes outside its built-in allowlist (such as style)
+container.setHTML(untrustedHTML);
+```
+
+## 2. Using Custom Sanitizer Configurations
+
+You can customize the sanitization rules by creating a `Sanitizer` instance. This allows you to define exactly which elements and attributes are permitted for your specific use case.
+
+When using `Element.setHTML()` and `Document.parseHTML()`, the default `Sanitizer` settings remove all XSS-unsafe elements and attributes. You cannot make a more permissive `Sanitizer` that allows those elements, but you can further restrict what is allowed.
+
+```javascript
+// Define a restrictive configuration that only allows the specified elements and attributes.
+const config = {
+  elements: ["p", "b", "i", "strong", "em"],
+  attributes: ["class"],
+  replaceWithChildrenElements: ['div']
+};
+
+const mySanitizer = new Sanitizer(config);
+
+// Apply custom sanitization
+container.setHTML(untrustedHTML, { sanitizer: mySanitizer });
+```
+
+Elements that are not in `elements` are removed **together with their content**. List wrapper elements whose text you want to keep (such as `div` above) in `replaceWithChildrenElements`, which removes the element but keeps its children.
+
+If you need a more permissive `Sanitizer` that allows some XSS-unsafe elements or attributes, you can use a custom Sanitizer with `Element.setHTMLUnsafe()` and `Document.parseHTMLUnsafe()`.
+
+## 3. Parsing User Input with `Document.parseHTML()`
+
+If you need to parse untrusted HTML without immediately inserting it into the live DOM, use `Document.parseHTML()`. This method returns a `Document` that has been sanitized according to default or custom rules, so you can inspect or transform the sanitized nodes (for example, to build a preview or extract text) before inserting them.
+
+Move the resulting nodes into the page rather than serializing them to a string and re-parsing it with `innerHTML`, which can reintroduce mutation XSS (mXSS).
+
+```javascript
+const rawHTML = '<p>Hello <script>console.log("bad")</script></p>';
+
+const doc = Document.parseHTML(rawHTML);
+// doc.body now contains the sanitized nodes: <p>Hello </p>
+preview.replaceChildren(...doc.body.childNodes);
+```
+
+## Fallbacks & browser support for Sanitizer API
+
+Browser support for Sanitizer API: Limited availability.
+Supported by: Chrome 146 (Mar 2026), Edge 146 (Mar 2026), and Firefox 148 (Feb 2026).
+Unsupported in: Safari.
+
+If the native Sanitizer API is not available in your target browsers, load a library like **DOMPurify** only when native support is missing, to avoid shipping it to browsers that don't need it. Use `in` checks for feature detection so the check itself works in older browsers.
+
+```javascript
+let domPurifyPromise;
+
+function loadDOMPurify() {
+  // Code-split with your bundler so DOMPurify is only downloaded when needed
+  domPurifyPromise ??= import('dompurify').then((mod) => mod.default ?? mod);
+  return domPurifyPromise;
+}
+
+export async function safeSetHTML(el, html) {
+  const elements = ['p', 'b', 'i', 'strong', 'em'];
+  const attributes = ['class'];
+
+  if ('setHTML' in Element.prototype) {
+    // setHTML() accepts a plain configuration object as the sanitizer
+    el.setHTML(html, { sanitizer: { elements, attributes } });
+  } else {
+    const DOMPurify = await loadDOMPurify();
+    el.innerHTML = DOMPurify.sanitize(html, {
+      ALLOWED_TAGS: [...elements, '#text'],
+      ALLOWED_ATTR: attributes,
+      // Match the native Sanitizer: strip aria-*/data-* and disallowed element content
+      ALLOW_ARIA_ATTR: false,
+      ALLOW_DATA_ATTR: false,
+      KEEP_CONTENT: false
+    });
+  }
+}
+```
+
+By default, DOMPurify keeps `aria-*` and `data-*` attributes (even when `ALLOWED_ATTR` is specified) as well as the text content of elements it removes, while the native Sanitizer strips `aria-*` and `data-*` attributes and removes disallowed elements together with their content. Setting `ALLOW_ARIA_ATTR: false`, `ALLOW_DATA_ATTR: false`, `KEEP_CONTENT: false`, and allowing `#text` makes DOMPurify match the native behavior. DOMPurify has no built-in option equivalent to `replaceWithChildrenElements`, so avoid that option in configurations that need a matching fallback.
+
+If the page enforces Trusted Types (`require-trusted-types-for 'script'`), assigning a string to `innerHTML` throws. `setHTML()` does not need a Trusted Types policy, but the fallback does: pass `RETURN_TRUSTED_TYPE: true` to `DOMPurify.sanitize()` and allow its `dompurify` policy name in your `trusted-types` CSP directive.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/secure-external-subresources.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/secure-external-subresources.md
new file mode 100644
index 00000000..464250a9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/secure-external-subresources.md
@@ -0,0 +1,202 @@
+# Secure external subresources with Subresource Integrity, CORS, and Referrer Policy
+
+When loading scripts, stylesheets, fonts, or images from third-party CDNs or external origins, verify their cryptographic integrity with Subresource Integrity (`integrity` in HTML and `integrity()` in CSS `url()`), configure cross-origin credential handling (`crossorigin` and `cross-origin()`), and restrict outgoing `Referer` headers (`referrerpolicy` and `referrer-policy()`). For document-level Content Security Policy and outbound connection allowlists, see `security` (via `npx -y modern-web-guidance@latest retrieve "security"`) and `restrict-outbound-connections` (via `npx -y modern-web-guidance@latest retrieve "restrict-outbound-connections"`).
+
+## 1. Generate cryptographic integrity digests for immutable assets
+
+Subresource Integrity (SRI) ensures the browser only executes or renders an external asset if its bytes match the cryptographic hash declared by your application.
+
+- **Compute digests at build or release time, never from live untrusted responses**: Generate integrity hashes during your build or release step from known-good local asset bytes (or copy the official digest published by the package author) and hardcode them into your HTML, CSS, or JavaScript. Never fetch a third-party URL in the browser at runtime to compute its own `integrity` hash, which trusts whatever bytes the remote server returns and defeats SRI.
+- **Use `sha384-` by default**: Format integrity metadata as `<algorithm>-<base64-digest>` using `sha384-` (recommended default), `sha512-`, or `sha256-`.
+- **Pin external subresources to immutable, versioned URLs**: Always reference third-party assets using immutable, version-pinned or content-addressed URLs (such as `https://cdn.example.com/ui@2.4.0/app.min.js`) rather than mutable floating URLs (`latest/app.min.js`), which expose your site to silent supply-chain changes and break SRI as soon as the remote file updates. If you must load a mutable third-party script that updates in place (such as a vendor analytics tag), omit `integrity` on that URL and restrict it with Content Security Policy (`strict-dynamic` / nonces) or iframe sandboxing instead.
+- **Space-separate multiple digests when an endpoint may serve multiple valid payloads**: All browsers that support SRI implement `sha256-`, `sha384-`, and `sha512-`. If a URL may legitimately return one of several known-good payloads (such as during an A/B test, staged CDN rollout, or content-negotiated build), list multiple digests of the same algorithm separated by whitespace (for example, `integrity="sha384-variantA... sha384-variantB..."`). The browser accepts the response if it matches *any* listed digest of the strongest algorithm present.
+- **Serve cross-origin subresources with CORS headers**: Browsers can only verify the integrity of a cross-origin response when it is CORS-readable (`Access-Control-Allow-Origin: *` for anonymous requests, or the exact requesting origin with `Access-Control-Allow-Credentials: true` for credentialed requests).
+
+```bash
+# Generate a sha384- SRI hash at build time from a known-good local file
+printf "sha384-%s\n" "$(openssl dgst -sha384 -binary app.min.js | openssl base64 -A)"
+```
+
+```javascript
+// Build-time / tooling helper (Node.js 19+, Deno, Bun) to compute an SRI string from known-good local bytes
+export async function computeIntegrityMetadata(bytes) {
+  const rawBytes =
+    typeof bytes === 'string' ? new TextEncoder().encode(bytes) : bytes;
+  const digestBuffer = await crypto.subtle.digest('SHA-384', rawBytes);
+  const binary = Array.from(new Uint8Array(digestBuffer), (b) =>
+    String.fromCharCode(b),
+  ).join('');
+  return `sha384-${btoa(binary)}`;
+}
+```
+
+## 2. Secure HTML scripts, stylesheets, and preloads
+
+Set a document-level `Referrer-Policy: strict-origin-when-cross-origin` HTTP response header (or include `<meta name="referrer" content="strict-origin-when-cross-origin">` in `<head>`) as a baseline default so any subresource or CSS `url()` that omits a per-request referrer modifier still strips sensitive path and query parameters on cross-origin requests.
+
+Then, on external `<script>`, `<link rel="stylesheet">`, `<link rel="preload">`, and `<link rel="modulepreload">` elements, always set `integrity`, `crossorigin`, and `referrerpolicy` together:
+
+- **`integrity="sha384-..."`**: Blocks execution or application of the resource if the response bytes do not match the expected digest (for a blocked `<link rel="stylesheet">`, `linkElement.sheet` remains `null` and an `error` event fires).
+- **`crossorigin="anonymous"`** (recommended default for public CDN assets) or **`crossorigin="use-credentials"`**: Required whenever `integrity` is set on a cross-origin resource. Omitting `crossorigin` causes the browser to fetch the resource in `no-cors` mode (producing an opaque response that cannot be hash-verified) and block the resource.
+- **`referrerpolicy="no-referrer"`** (recommended default for third-party CDNs) or **`referrerpolicy="strict-origin-when-cross-origin"`**: Overrides the document referrer policy to prevent leaking any origin or path information in the `Referer` request header to the third-party host.
+
+```html
+<!-- Document-level baseline referrer policy in <head> (or via Referrer-Policy HTTP header) -->
+<meta name="referrer" content="strict-origin-when-cross-origin" />
+
+<!-- External stylesheet with SRI, anonymous CORS, and no referrer -->
+<link
+  rel="stylesheet"
+  href="https://cdn.example.com/ui@2.4.0/styles.css"
+  integrity="sha384-bs0EksOYBbU/g0IAHMXbSyH1Mgw83GKn+EZlSI+VE+zVchXmSbLwhVLrPzsOWnc5"
+  crossorigin="anonymous"
+  referrerpolicy="no-referrer"
+/>
+
+<!-- External script with SRI, anonymous CORS, and no referrer -->
+<script
+  src="https://cdn.example.com/ui@2.4.0/bundle.min.js"
+  integrity="sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC"
+  crossorigin="anonymous"
+  referrerpolicy="no-referrer"
+></script>
+```
+
+When fetching external subresources programmatically with `fetch()`, pass the matching `integrity`, `mode`, `credentials`, and `referrerPolicy` options (a digest mismatch rejects the promise with `TypeError`):
+
+```javascript
+const response = await fetch('https://cdn.example.com/ui@2.4.0/manifest.json', {
+  integrity: 'sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC',
+  mode: 'cors',
+  credentials: 'omit',
+  referrerPolicy: 'no-referrer',
+});
+```
+
+## 3. Secure CSS images, fonts, and imported stylesheets with `url()` modifiers
+
+CSS `url()` request modifiers (`cross-origin()`, `referrer-policy()`, and `integrity()`) control the fetch mode, referrer header, and Subresource Integrity verification of CSS-loaded resources—including `background-image`, `content`, `mask-image`, `border-image-source`, `filter`, `@font-face` `src`, and `@import` rules—directly from CSS:
+
+| Modifier function | Argument syntax & allowed values | Purpose |
+|---|---|---|
+| `cross-origin(<ident>)` | **Unquoted keyword**: `anonymous` (recommended default) or `use-credentials` | Fetches the CSS resource using CORS and controls whether credentials are sent. Always include alongside `integrity()` on cross-origin CSS resources. |
+| `referrer-policy(<ident>)` | **Unquoted keyword**: `no-referrer` (recommended default for third-party assets), `strict-origin-when-cross-origin`, `origin`, `same-origin`, `strict-origin`, `origin-when-cross-origin`, `no-referrer-when-downgrade`, or `unsafe-url` | Overrides the document referrer policy for this specific CSS request. |
+| `integrity("<string>")` | **Quoted string**: `"sha384-<base64>"` (or space-separated digests `"sha384-... sha384-..."`) | Verifies the fetched CSS resource against the expected cryptographic digest before rendering or applying it. |
+
+Follow these CSS syntax and security rules when authoring `url()` modifiers:
+
+- **Quote the URL string inside `url("...")`**: Request modifiers are only valid when the URL inside `url(...)` is a quoted `<string>` (unquoted URLs cannot use modifiers).
+- **Specify each modifier type at most once per `url()`**: You can combine `cross-origin()`, `referrer-policy()`, and `integrity()` in any order inside `url("..." ...)`, but repeating the same modifier type twice (such as two `integrity()` modifiers) is invalid. To supply multiple hashes, space-separate them inside a single `integrity("sha384-... sha384-...")` string.
+- **Always pair cross-origin `integrity()` with `cross-origin(anonymous)`**: While `@font-face` `src` and `mask-image` already fetch in anonymous `cors` mode by default, `background-image`, `content`, `border-image-source`, and `@import` default to `no-cors` mode (producing an opaque response that cannot be hash-verified) and external SVG `filter` defaults to `same-origin` mode (blocking cross-origin URLs outright). Including `cross-origin(anonymous)` (or `cross-origin(use-credentials)`) ensures consistent CORS verification across every CSS property.
+- **Place modifiers inside `url("...")` in `@import` and `@font-face` rules**: Keep `cross-origin()`, `referrer-policy()`, and `integrity()` inside `url("..." ...)`, while keeping font descriptors like `format("woff2")` and `tech(...)` outside `url(...)`.
+
+```css
+@import url(
+  "https://cdn.example.com/theme@1.2.0/tokens.css"
+  cross-origin(anonymous)
+  referrer-policy(no-referrer)
+  integrity("sha384-bs0EksOYBbU/g0IAHMXbSyH1Mgw83GKn+EZlSI+VE+zVchXmSbLwhVLrPzsOWnc5")
+);
+
+@font-face {
+  font-family: "BrandSans";
+  src: url(
+    "https://cdn.example.com/fonts@1.0.0/brand-sans.woff2"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+    integrity("sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC")
+  ) format("woff2");
+  font-display: swap;
+}
+
+.verified-graphic {
+  background-image: url(
+    "https://cdn.example.com/media@1.0.0/badge.svg"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+    integrity("sha384-Iw/0p59dP96nGTzHvf2XIfqcBwBW7RM6JfOij8uZxyg5azfNaOOUW8SQy6H/hU91")
+  );
+}
+```
+
+## Fallback strategies
+
+Browser support for cross-origin() for url(): Limited availability.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), and Safari 26.2 (Dec 2025).
+Unsupported in: Firefox.
+
+Browser support for referrer-policy() for url(): Limited availability.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), and Safari 26.2 (Dec 2025).
+Unsupported in: Firefox.
+
+Browser support for integrity() for url(): Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target does not yet support CSS `url()` request modifiers (`cross-origin()`, `referrer-policy()`, or `integrity()`), combine document-level policies with cascading CSS declarations so subresources remain functional and protected:
+
+1. **Prefer HTML `<link rel="stylesheet">` over CSS `@import` when cross-browser SRI is required**: Because `subresource-integrity` and `referrer-policy` on `<link rel="stylesheet">` are widely available across all browsers, load external stylesheets with `<link rel="stylesheet" href="..." integrity="sha384-..." crossorigin="anonymous" referrerpolicy="no-referrer">` instead of `@import` whenever integrity verification must be enforced in every browser.
+2. **Rely on the document-level `Referrer-Policy` header or `<meta name="referrer">` from Step 2**: In browsers that do not support `referrer-policy()` inside CSS `url()`, the document-level `Referrer-Policy: strict-origin-when-cross-origin` header or `<meta name="referrer" content="strict-origin-when-cross-origin">` element automatically strips sensitive path and query parameters on cross-origin CSS requests.
+3. **Cascade separate CSS declarations for progressive enhancement**: Browsers that do not recognize a modifier inside `url("..." ...)` discard the entire declaration at CSS parse time. Declare a plain `url("...")` first, followed by a `cross-origin()` and `referrer-policy()` declaration (for browsers that support those two modifiers but not `integrity()`), followed by the full declaration including `integrity("sha384-...")`:
+   - **Never put an unverified `url()` inside the same comma-separated `@font-face` `src` list**: Writing `src: url("font.woff2" cross-origin(anonymous) integrity("sha384-...")), url("font.woff2");` in a single `src` descriptor bypasses Subresource Integrity at runtime—if a CDN serves a tampered font that fails the `integrity()` check, the browser treats it as a load failure and automatically falls back to the second comma-separated `url("font.woff2")`. Using **separate** `src:` declarations ensures supporting browsers overwrite the unverified declaration at CSS parse time and block tampered fonts at runtime.
+
+```css
+@font-face {
+  font-family: "BrandSans";
+  /* 1. Parse-time fallback for browsers without url() modifier support */
+  src: url("https://cdn.example.com/fonts@1.0.0/brand-sans.woff2") format("woff2");
+  /* 2. Parse-time fallback for browsers supporting cross-origin() and referrer-policy() */
+  src: url(
+    "https://cdn.example.com/fonts@1.0.0/brand-sans.woff2"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+  ) format("woff2");
+  /* 3. Full protection in browsers supporting cross-origin(), referrer-policy(), and integrity() */
+  src: url(
+    "https://cdn.example.com/fonts@1.0.0/brand-sans.woff2"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+    integrity("sha384-oqVuAfXRKap7fdgcCY5uykM6+R9GqQ8K/uxy9rx7HNQlGYl1kPzQho1wx4JwY8wC")
+  ) format("woff2");
+  font-display: swap;
+}
+
+.verified-graphic {
+  background-image: url("https://cdn.example.com/media@1.0.0/badge.svg");
+  background-image: url(
+    "https://cdn.example.com/media@1.0.0/badge.svg"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+  );
+  background-image: url(
+    "https://cdn.example.com/media@1.0.0/badge.svg"
+    cross-origin(anonymous)
+    referrer-policy(no-referrer)
+    integrity("sha384-Iw/0p59dP96nGTzHvf2XIfqcBwBW7RM6JfOij8uZxyg5azfNaOOUW8SQy6H/hU91")
+  );
+}
+```
+
+4. **Feature-detect CSS `url()` modifier support in JavaScript with `CSS.supports()`**:
+
+```javascript
+export function getCssUrlModifierSupport() {
+  const supportsCrossOriginAndReferrer =
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports(
+      'background-image',
+      'url("https://example.com/a.svg" cross-origin(anonymous) referrer-policy(no-referrer))',
+    );
+
+  const supportsUrlIntegrity =
+    typeof CSS !== 'undefined' &&
+    typeof CSS.supports === 'function' &&
+    CSS.supports(
+      'background-image',
+      'url("https://example.com/a.svg" cross-origin(anonymous) referrer-policy(no-referrer) integrity("sha384-Iw/0p59dP96nGTzHvf2XIfqcBwBW7RM6JfOij8uZxyg5azfNaOOUW8SQy6H/hU91"))',
+    );
+
+  return { supportsCrossOriginAndReferrer, supportsUrlIntegrity };
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/security.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/security.md
new file mode 100644
index 00000000..4b6f839b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/security.md
@@ -0,0 +1,380 @@
+# Web Security
+
+Guidelines for implementing preventative security measures on the web safely and incrementally.
+
+**NOTE**: This skill covers standard web platform defenses, focusing mostly on the browser. Applications still require comprehensive server-side security, authorization models, and input validation.
+
+## Table of Contents
+
+- When to apply this skill
+- Phase 1: Quick Wins & Obvious Anti-Patterns
+  - 1.1 Secure Contexts
+  - 1.2 Avoid Dangerous DOM Sinks
+  - 1.3 Secure Cookies
+  - 1.4 Clickjacking Protection (Frame-Ancestors & X-Frame-Options)
+  - 1.5 Secure Window Messaging (postMessage)
+- Phase 2: Discovery & Data Collection (Prerequisites)
+  - 2.1 Inspect the Application
+  - 2.2 Deploy Report-Only Policies
+  - 2.3 Data Hygiene for Reports
+  - 2.4 Automated Discovery via Browser APIs and DevTools
+- Phase 3: Interpreting Results & Enforcement
+  - Core enforcement
+    - 3.1 Analyzing CSP Reports
+    - 3.2 Enforcing Content Security Policy (CSP)
+    - 3.3 Trusted Types Enforcement
+    - 3.4 Cross-Origin Opener Policy (COOP)
+    - 3.5 Cross-Origin Resource Policy (CORP)
+    - 3.6 Cross-Origin Isolation
+    - 3.7 Fetch Metadata (Resource Isolation)
+  - Companion policies (deploy in parallel)
+    - HTTP Strict Transport Security (HSTS)
+    - X-Content-Type-Options
+    - Referrer Policy
+    - Permissions Policy
+    - Subresource Integrity (SRI)
+    - Cross-Origin Resource Sharing (CORS)
+    - Clear-Site-Data (Logout)
+
+## When to apply this skill
+
+The right starting point depends on the application and whether you can update the codebase directly:
+
+- **Auditing and hardening a codebase directly**: Apply Phase 1 code hygiene, wire up Phase 2 reporting (`Reporting-Endpoints` and `report-to`), and enforce Phase 3 headers (`Content-Security-Policy` with nonces/hashes, `'strict-dynamic'`, `'report-sample'`, `object-src 'none'`, `base-uri 'none'`, `frame-ancestors 'self'`, and `require-trusted-types-for 'script'`, plus COOP, CORP, Fetch Metadata, HSTS, `X-Content-Type-Options`, `Referrer-Policy`, and `Permissions-Policy`) directly by updating `<script>` tags, cookies, and server middleware in the same pass.
+- **Staged rollout on a large production site with unknown third-party dependencies**: Start with Phase 1 quick wins and deploy Phase 2 report-only headers alongside enforced companion policies while collecting violation telemetry, then promote the report-only policies to Phase 3 enforcement.
+- **Greenfield app or SaaS template / framework defaults**: Ship Phase 1 hygiene and Phase 3 enforced policies by default, with Phase 2 reporting configured so regressions are captured immediately.
+
+**Focusing on Leverage**: While Phase 1 and 2 establish baseline hygiene and violation visibility, Phase 3 core enforcement represents the highest-leverage security work. Specifically, Injection/XSS mitigation through enforced CSP (§3.2) and Trusted Types (§3.3) addresses the largest practical threat, while companion policies and isolation defenses provide important defense-in-depth.
+
+## Phase 1: Quick Wins & Obvious Anti-Patterns
+
+Before attempting to deploy global security policies, focus on code-level hygiene and immediate fixes that do not risk breaking the application.
+
+### 1.1 Secure Contexts
+- **DO**: Deliver resources over HTTPS to protect against both passive and active network attackers.
+- **DO**: Serve a header like `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload` to force HTTPS whenever possible.
+- **TIP**: In production rollout, start with a short `max-age` (e.g., 300 seconds) and incrementally increase to 1 year. A misconfigured HSTS with a long max-age can render the site permanently inaccessible until the cache expires in every browser that saw it.
+
+### 1.2 Avoid Dangerous DOM Sinks
+- **DO**: Prefer `textContent` or `innerText` over `innerHTML` when setting text content.
+- **DO**: Use `setHTML()` (part of the Sanitizer API; see `sanitize-untrusted-html` (via `npx -y modern-web-guidance@latest retrieve "sanitize-untrusted-html"`)) when available to safely insert untrusted HTML without going through `innerHTML`.
+- **DO NOT**: Use `innerHTML` or `setHTMLUnsafe` with untrusted or unsanitized input.
+- **DO**: Use DOMParser or create elements programmatically (`document.createElement`) instead of concatenating HTML strings.
+
+**Dangerous sinks to grep for**: `innerHTML`, `outerHTML`, `document.write`, `eval`, `setTimeout` with a string argument, `script.src`.
+
+**Code Pattern:**
+```javascript
+// Unsafe
+element.innerHTML = `Hello, ${untrustedName}!`;
+
+// Safe
+element.textContent = `Hello, ${untrustedName}!`;
+```
+
+Trusted Types can enforce this pattern at runtime by blocking string assignments to dangerous sinks. Deploying it is a CSP enforcement step with real breakage risk — see §3.3.
+
+### 1.3 Secure Cookies
+Ensure session and application cookies are configured securely by default, whether set via `Set-Cookie` headers or framework session configuration (such as Astro or Express session middleware).
+- **DO**: Name first-party session cookies with the `__Host-` prefix (`name: '__Host-session'`) when used by a single domain. This requires `Secure` (`secure: true`), `Path=/` (`path: '/'`), and omitting the `Domain` attribute, protecting against same-site and network attackers.
+- **DO**: Prefer naming cookies with the `__Secure-` prefix when `__Host-` isn't appropriate. This requires the `Secure` attribute, and protects against network attackers.
+- **DO**: Set `HttpOnly` (`httpOnly: true`) on session and authentication cookies unless the cookie must be read by client-side script, and explicitly set `SameSite=Lax` (`sameSite: 'lax'`) for standard first-party cookies.
+- **DO**: If your application will be embedded as an iframe in third-party contexts, use `SameSite=None; Secure; Partitioned`.
+- **DO NOT**: Rely on unpartitioned `SameSite=None` — these are being systematically blocked for tracking prevention.
+
+```http
+Set-Cookie: __Host-session_id=value; SameSite=Lax; HttpOnly; Secure; Path=/
+Set-Cookie: third_party_var=value; SameSite=None; Secure; Partitioned
+```
+
+### 1.4 Clickjacking Protection (Frame-Ancestors & X-Frame-Options)
+Clickjacking protection is easy to deploy, carries extremely low risk of breaking legitimate functionality, and provides immediate defense against malicious UI redressing.
+- **DO**: Set the `X-Frame-Options: SAMEORIGIN` header to prevent other sites from embedding your pages in an iframe (or use `DENY` if you should never be embedded).
+- **DO**: For fine-grained control, use `frame-ancestors 'self'` (or specified trusted domains) in your CSP header.
+
+```http
+X-Frame-Options: SAMEORIGIN
+Content-Security-Policy: frame-ancestors 'self' https://trusted-partner.com;
+```
+
+### 1.5 Secure Window Messaging (postMessage)
+If your application communicates with other origins using `window.postMessage`, you must strictly validate the sender and receiver.
+- **DO**: Always validate the `event.origin` of incoming messages on the receiver side using strict equality against a list of trusted origins (or use the `Origin` API when comparing against URLs/elements, checking schemeful same-site relationships, or distinguishing opaque sandboxed iframe origins; see `validate-origins` (via `npx -y modern-web-guidance@latest retrieve "validate-origins"`)). Do **not** trust wildcards (`*`), substring checks, or unverified payloads.
+- **DO**: Always specify a target origin (rather than the wildcard `*`) when calling `postMessage` to send sensitive data, ensuring only the intended origin can receive it.
+- **DO**: Validate and sanitize the properties of incoming message payloads before performing operations or writing them to DOM sinks. Manual JSON serialization is unnecessary as `postMessage` handles object cloning internally.
+
+```javascript
+// Receiver (Safe - traditional string check)
+window.addEventListener('message', (event) => {
+  if (event.origin !== 'https://trusted-origin.com') return;
+  const data = event.data;
+  if (data && data.action === 'update') {
+    // Process data safely
+  }
+});
+
+// Sender (Safe)
+targetWindow.postMessage({ action: 'update' }, 'https://trusted-origin.com');
+```
+
+## Phase 2: Discovery & Data Collection (Prerequisites)
+
+Do not blindly apply strict policies to an existing application. You must first understand the application's constraints by collecting data.
+
+### 2.1 Inspect the Application
+Before turning anything on, gather facts:
+- **Grep for existing security headers** in server config, middleware, CDN/edge config, and meta tags: `Content-Security-Policy`, `Strict-Transport-Security`, `X-Frame-Options`, `X-Content-Type-Options`, `Permissions-Policy`, `Cross-Origin-*`, `Access-Control-*`, `Timing-Allow-Origin`, `Reporting-Endpoints`.
+- **Enumerate inline scripts and styles** in server-rendered templates and static HTML — these will need nonces, hashes, or refactoring.
+- **List third-party script origins** loaded by the app (analytics, ads, tag managers, CDNs). These dictate what `script-src` must allow or whether `'strict-dynamic'` is viable.
+- **Identify popup-dependent flows**: OAuth, payment gateways, SSO. These constrain COOP choices.
+- **Identify cross-origin embeds and embedders**: iframes the app loads, and sites that embed the app. These constrain COEP/CORP/`frame-ancestors`.
+- **Enumerate required browser features**: List any features (camera, geolocation, microphone, fullscreen) used by the app or embedded third-party widgets to inform `Permissions-Policy`.
+- **Identify dynamic dependencies**: Check if third-party scripts are versioned or if they receive silent updates, determining if `SRI` can be used.
+- **Map cross-site integrations**: List all incoming Webhooks, cross-site APIs, or SSO redirect endpoints so `Fetch Metadata` resource isolation policies don't break them.
+
+### 2.2 Deploy Report-Only Policies
+Use "Report-Only" headers to identify potential breakages before they happen.
+- **DO**: Use report-only headers to dry-run policies without enforcement. Standard report-only headers include:
+  - `Content-Security-Policy-Report-Only` for CSP rules.
+  - `Cross-Origin-Opener-Policy-Report-Only` for COOP isolation.
+  - `Cross-Origin-Embedder-Policy-Report-Only` for COEP isolation.
+  - `Document-Policy-Report-Only` for document features.
+- **DO**: Define a `Reporting-Endpoints` header so violations have somewhere to go, and reference its name from `report-to`. Recommend setting an endpoint named `default`, which will automatically capture deprecation and crash reports.
+- **DO**: Run report-only for long enough to cover real traffic patterns (typically days to weeks), not just synthetic testing.
+
+**Example headers:**
+```http
+Reporting-Endpoints: default="https://reports.example/default", main-endpoint="https://reports.example/main"
+Content-Security-Policy-Report-Only: script-src 'nonce-{RANDOM}' 'strict-dynamic' 'report-sample'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'; require-trusted-types-for 'script'; report-to main-endpoint;
+```
+
+The `'strict-dynamic'`, `https:`, and `'unsafe-inline'` tokens together form a backwards-compatibility ladder: modern browsers honor `'strict-dynamic'` (nonce-propagating) and ignore the others; older browsers fall back to `https:`; very old browsers fall back to `'unsafe-inline'`. The fallbacks are harmless on any browser that supports a stricter token.
+
+**Managing report false-positives**: Reporting endpoints receive a significant volume of false-positive violation reports caused by client-side middleware, aggressive browser extensions, ancient browsers, web crawlers, or antivirus scanners. When analyzing report-only logs, focus on high-frequency patterns from modern user-agents and filter out noise before making deployment decisions. Specifically:
+- **Filter out noise**: Ignore reports sent by old browsers with known bugs triggering spurious violations, reports for markup known to be injected by popular browser extensions or client-side middleware (like identical reports seen across many distinct applications), and reports that do not contain enough information to debug.
+- **Ignore low-volume reports**: If a policy is deployed, a low violation volume often indicates a false positive that can be safely ignored.
+- **Leverage `'report-sample'`**: Always include `'report-sample'` in your `script-src` directives. This instructs the browser to include the first 40 characters of the violating script or inline code snippet in the violation report, which makes debugging much easier.
+
+### 2.3 Data Hygiene for Reports
+- **DO NOT**: Include sensitive data (PII, authentication tokens, session identifiers, query strings with secrets) in logs or violation reports. Mask or omit them at the edge before they reach the reporting endpoint.
+
+### 2.4 Automated Discovery via Browser APIs and DevTools
+- **Reporting API**: Use `Reporting-Endpoints` in combination with report-only headers (e.g., `Content-Security-Policy-Report-Only`, `Document-Policy-Report-Only`) to have the browser automatically post violations to your server.
+- **Browser DevTools**: Use the **Issues Tab** in modern browsers (e.g., Chrome DevTools). It automatically surfaces blocked resources, mixed content, third-party cookie deprecation warnings, and feature policy violations without you having to crawl the codebase manually.
+
+## Phase 3: Interpreting Results & Enforcement
+
+After inspecting the application (or collecting report-only data), enforce your security policies. Phase 3 has two tracks that are enforced together:
+
+- **Core enforcement** — high-leverage XSS and isolation defenses (`Content-Security-Policy`, Trusted Types, COOP, CORP, and Fetch Metadata).
+- **Companion policies (deploy in parallel)** — low-risk headers (`Strict-Transport-Security`, `X-Content-Type-Options`, `Referrer-Policy`, `Permissions-Policy`, `Clear-Site-Data`) that should always be enabled alongside core enforcement.
+
+### Core enforcement
+
+#### 3.1 Analyzing CSP Reports
+
+When reviewing CSP violation reports, first separate the noise (per §2.2) from legitimate application issues. For violations that appear to be caused by an incompatibility in your application (usually those where the "Sample" or "Blocked URI" seem like legitimate scripts or assets that might be present in your markup):
+- **Code Search**: Search your codebase for the offending script source, URL, or hash to see if it is present in your code, dynamic server templates, or static HTML files.
+- **Console Auditing**: Open the page that triggered the violation (the "Document URI" in the report) using the same browser, and check the developer tools/console for CSP violations while exercising as much application functionality as possible (some violations only trigger on specific user interactions).
+
+Once filtered and triaged, analyze the reports against the following common scenarios:
+
+- **Scenario**: Many violations for inline scripts.
+  - **Condition**: The app uses a framework that relies on inline scripts.
+  - **Decision**: Implement Nonces (server-rendered) or Hashes (static) before enforcing.
+- **Scenario**: Violations for third-party analytics scripts.
+  - **Condition**: The scripts are required.
+  - **Decision**: Use `'strict-dynamic'` with a per-request nonce so the analytics loader can attach its dependencies. Do **not** add the analytics origin to a URL allowlist — domain allowlists are bypassable via open redirects, JSONP, and dependency injection on the listed origin.
+- **Scenario**: Trusted Types violations on specific sinks.
+  - **Condition**: Legacy code paths still write strings to `innerHTML` etc.
+  - **Decision**: Refactor those sinks (per §1.2) or route them through a Trusted Types policy (§3.3) before enforcing.
+
+#### 3.2 Enforcing Content Security Policy (CSP)
+When enforcing `Content-Security-Policy`, always keep `Reporting-Endpoints` and `report-to` wired up on the enforced header so any regressions remain visible.
+
+**Mandatory directives to set:**
+- `script-src 'nonce-{RANDOM}' 'strict-dynamic' 'report-sample'` (or SHA-256/384/512 script hashes for static HTML) — the core directive of any CSP and the primary mechanism to prevent XSS.
+- `object-src 'none'` — blocks plugin-based code execution (`<object>`, `<embed>`).
+- `base-uri 'none'` — blocks `<base>` tag hijacking of relative URLs.
+- `frame-ancestors 'self'` — prevents clickjacking alongside `X-Frame-Options: SAMEORIGIN` (§1.4).
+- `require-trusted-types-for 'script'` — enforces Trusted Types runtime checks on DOM XSS sinks (§3.3).
+- `report-to <endpoint>` — sends violation reports to the endpoint defined in `Reporting-Endpoints`.
+- *Optional*: `form-action 'self'` prevents form submissions to attacker-controlled origins.
+
+**Enforced Header Example (CSP with reporting):**
+```http
+Reporting-Endpoints: main-endpoint="https://reports.example/main"
+Content-Security-Policy: script-src 'nonce-{RANDOM}' 'strict-dynamic' 'report-sample'; object-src 'none'; base-uri 'none'; frame-ancestors 'self'; require-trusted-types-for 'script'; report-to main-endpoint;
+```
+
+HTML for nonce-based CSP:
+```html
+<script nonce="{RANDOM}" src="https://example.com/script.js"></script>
+```
+
+**Server / Middleware Per-Request Nonce Generation:**
+In server-rendered or SSR middleware (such as Node.js, Express, or Astro middleware), generate a fresh cryptographic nonce on every request, attach it to `Content-Security-Policy`, and pass the nonce into your template/SSR rendering context so only trusted template `<script>` tags receive it:
+
+```javascript
+const bytes = new Uint8Array(16);
+crypto.getRandomValues(bytes);
+const nonce = btoa(String.fromCharCode(...bytes));
+
+const csp = [
+  `script-src 'nonce-${nonce}' 'strict-dynamic' 'report-sample'`,
+  "object-src 'none'",
+  "base-uri 'none'",
+  "frame-ancestors 'self'",
+  "require-trusted-types-for 'script'",
+  'report-to main-endpoint',
+].join('; ');
+
+headers.set('Reporting-Endpoints', 'main-endpoint="https://reports.example/main"');
+headers.set('Content-Security-Policy', csp);
+
+// Pass the per-request nonce into your template/SSR rendering context (or replace an
+// explicit placeholder token in a static template before interpolating any user data):
+res.locals.nonce = nonce; // e.g., <script nonce="<%= nonce %>" src="/app.js"></script>
+```
+
+For static/cached HTML (SPAs) where a per-response nonce is not possible, use hash-based CSP: compute the `sha256-` hash of each script and list the hashes in `script-src` alongside `'strict-dynamic' 'report-sample'`.
+
+**Avoid**:
+- Broad scheme or domain allowlists (such as `https:` alone or `script-src https://cdn.example.com` without `'strict-dynamic'`) as the primary `script-src` protection — they are easily bypassed by open redirects, JSONP endpoints, and dependency injection on the allowed origin.
+- Rewriting already-rendered HTML with a regular expression (such as `html.replace(/<script\b.../gi, ...)`) to stamp CSP nonces onto every `<script>` tag — post-processing rendered HTML cannot distinguish developer-authored `<script>` tags from untrusted `<script>` tags introduced via reflected or stored HTML injection, authorizing attacker-injected scripts under `script-src 'nonce-...'`.
+
+#### 3.3 Trusted Types Enforcement
+Trusted Types enforces source-level guidance at runtime by blocking raw string assignments to dangerous DOM XSS sinks (`innerHTML`, `outerHTML`, `document.write`, `script.src`, `script.textContent`) unless they pass through a named policy.
+
+- **DO**: Enforce Trusted Types in your `Content-Security-Policy` header by including the `require-trusted-types-for 'script'` directive.
+- **DO**: Sanitize any HTML sink assignments through a named `trustedTypes.createPolicy(...)` instance rather than assigning raw strings (or prefer `element.setHTML()` directly, which sanitizes HTML without needing a Trusted Types policy).
+- **DO NOT**: Create a pass-through policy (such as `createHTML: (s) => s`) that returns unsanitized input unchanged, as this neutralizes Trusted Types protection.
+- **DO**: Consult the dedicated `trusted-types` (via `npx -y modern-web-guidance@latest retrieve "trusted-types"`) guide for full implementation details, including `trusted-types` policy allowlisting and rollout strategies.
+
+```javascript
+const htmlPolicy = window.trustedTypes?.createPolicy('app-html', {
+  createHTML(input) {
+    return String(input)
+      .replace(/&/g, '&amp;')
+      .replace(/</g, '&lt;')
+      .replace(/>/g, '&gt;')
+      .replace(/"/g, '&quot;')
+      .replace(/'/g, '&#39;');
+  },
+});
+```
+
+#### 3.4 Cross-Origin Opener Policy (COOP)
+
+Lowest-risk of the three. Deploy if the app is **not** an OAuth provider, payment processor, or otherwise expected to be reached from an opener.
+
+- **DO**: Use `Cross-Origin-Opener-Policy: same-origin-allow-popups` — prevents a malicious opener from mounting XS-leaks attacks while still allowing OAuth and payment flows that *the app itself* initiates.
+- **DO NOT**: Jump straight to `same-origin` unless you have explicitly verified that no integrations rely on cross-origin `window.opener` access.
+
+#### 3.5 Cross-Origin Resource Policy (CORP)
+
+Set CORP explicitly on each response based on whether it should be embeddable in other contexts. Two core benefits: it protects resources from malicious cross-origin reads, and ensures compatibility when pages request stronger client-side isolation.
+
+- **DO**: Default to `Cross-Origin-Resource-Policy: same-origin` for app-internal resources (authenticated data, user session JSON, restricted internal scripts).
+- **DO**: Use `same-site` for endpoints utilized across subdomains of the same eTLD+1.
+- **DO**: Provide `cross-origin` exclusively for resources created for generic embedding or widely cached delivery (e.g., static shared assets or public CDNs).
+
+#### 3.6 Cross-Origin Isolation
+
+Highest deployment breakage risk. You only need to deploy this infrastructure if the application requires features relying on `SharedArrayBuffer` (e.g., WebAssembly multi-threading or shared memory architectures). If not required, skip this policy group.
+
+- **Preferred path (Chromium environments)**: Enable `Document-Isolation-Policy: isolate-and-credentialless`. This provides client-side isolation comparable to COEP while instructing the browser to strip cookies and authentication credentials from non-CORS cross-origin resource fetches rather than blocking them outright. Note that this is supported primarily in Chrome (142+) and other vendors have not yet shown interest, so evaluate carefully based on your target audience. Apps that need to *block* cross-origin resources lacking explicit CORP opt-in (rather than load them with credentials stripped) can adopt `isolate-and-require-corp` instead. This is stricter and harder to deploy — it requires the same subresource audit as the cross-browser path below.
+- **Cross-browser path (Complex enforcement)**: Require `Cross-Origin-Opener-Policy: same-origin` coupled with `Cross-Origin-Embedder-Policy: require-corp`. Every embedded subresource (images, styles, external media) MUST serve an explicit `Cross-Origin-Resource-Policy` header or the browser will prevent it from loading.
+
+```http
+Cross-Origin-Opener-Policy: same-origin
+Cross-Origin-Embedder-Policy: require-corp
+Cross-Origin-Resource-Policy: same-origin
+```
+
+#### 3.7 Fetch Metadata (Resource Isolation)
+Server-side enforcement that uses `Sec-Fetch-*` request headers to reject suspicious cross-site requests. Requires the cross-site integration mapping from §2.1 before enforcing.
+
+- **DO**: Implement a server-side resource isolation policy that checks `Sec-Fetch-*` headers and rejects `cross-site` requests for non-navigational endpoints.
+- **DO**: Reject disallowed requests *before* authentication or authorization checks, so the response does not leak timing information about whether a resource or session exists.
+- **DO**: Include `Vary: Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site` to prevent intermediate caches (CDNs) from serving cached responses to attackers.
+- **CAUTION**: `same-site` trusts every subdomain under your eTLD+1. If any subdomain hosts user-generated content, a legacy app, or otherwise untrusted code, drop `same-site` from the allowlist and accept only `same-origin` and `none`.
+- **CAUTION**: Misconfiguring these checks will block legitimate API requests coming from cross-site integrations, SSO handlers, or Webhooks. Ensure you log and test your `Sec-Fetch-*` constraints beforehand.
+
+```javascript
+app.use((req, res, next) => {
+  res.setHeader('Vary', 'Sec-Fetch-Dest, Sec-Fetch-Mode, Sec-Fetch-Site');
+
+  const site = req.get('Sec-Fetch-Site');
+  const mode = req.get('Sec-Fetch-Mode');
+  const dest = req.get('Sec-Fetch-Dest');
+
+  if (!site) return next(); // Fallback for legacy browsers
+
+  if (['same-origin', 'same-site', 'none'].includes(site)) return next();
+
+  // Allow standard navigate GET requests (link clicks)
+  if (site === 'cross-site' && mode === 'navigate' && req.method === 'GET' && !['object', 'embed'].includes(dest)) {
+    return next();
+  }
+
+  res.status(403).send('Forbidden');
+});
+```
+
+### Companion policies (deploy in parallel)
+
+These carry significantly lower breakage risk than the core enforcement track. They can be deployed alongside — or before — the CSP and isolation rollouts.
+
+#### HTTP Strict Transport Security (HSTS)
+- **DO**: `Strict-Transport-Security: max-age=31536000; includeSubDomains; preload` to force HTTPS.
+- **TIP**: In production rollout, start with a short `max-age` (e.g., 300 seconds) and incrementally increase to 1 year. A misconfigured HSTS with a long max-age can render the site permanently inaccessible until the cache expires in every browser that saw it.
+
+#### X-Content-Type-Options
+- **DO**: Set `X-Content-Type-Options: nosniff` to block MIME-type sniffing.
+- **DO**: Ensure the server serves correct `Content-Type` headers for all resources (`application/javascript` for scripts, `application/json` for APIs, `text/html` for documents, etc.) so the browser can strictly enforce the `nosniff` constraint.
+
+#### Referrer Policy
+- **DO**: Use `Referrer-Policy: strict-origin-when-cross-origin` as a safe default.
+
+#### Permissions Policy
+- **DO**: Disable unused browser features (camera, geolocation, microphone) for the page and iframes using Structured Fields syntax.
+- **DO**: Disable `focus-without-user-activation` for third-party iframes to prevent focus stealing.
+- **DO**: When delegating features to an iframe, use the `allow` attribute in HTML *in addition* to the header.
+- **CAUTION**: Unintentionally blocking a delegated feature will cause silent failures in third-party widgets (like embedded video players or payment gateways). Audit third-party dependencies before blocking.
+
+```http
+Permissions-Policy: camera=(), geolocation=(), microphone=(), focus-without-user-activation=()
+```
+
+```html
+<iframe src="https://trusted-video.com/player" allow="fullscreen; camera; focus-without-user-activation 'none'"></iframe>
+```
+
+#### Subresource Integrity (SRI)
+- **DO**: Use the `integrity` attribute with a cryptographic hash (preferring `sha384`, `sha512`, or `sha256`) when loading third-party scripts and stylesheets, combined with `crossorigin="anonymous"` (see `secure-external-subresources` (via `npx -y modern-web-guidance@latest retrieve "secure-external-subresources"`) for securing HTML and CSS subresources with SRI, CORS, and Referrer Policy).
+- **DO**: Ensure the server/CDN sends an appropriate `Access-Control-Allow-Origin` header so the browser can compute the hash.
+- **DO NOT**: Use SRI for dynamic or unversioned assets — silent updates will cause script execution to fail. SRI is strictly for immutable, versioned assets.
+
+```html
+<script src="https://cdn.example.com/lib@1.0.0.js" integrity="sha384-oqVu...Y8wC" crossorigin="anonymous"></script>
+```
+
+#### Cross-Origin Resource Sharing (CORS)
+CORS is a permission grant, not a defense — it tells the browser which cross-origin reads to allow. The risk is misconfiguring it as too permissive.
+
+- **DO**: Validate the `Origin` header on the server and set `Access-Control-Allow-Origin` dynamically to specific origins (rather than wildcard `*`).
+- **DO NOT**: Use wildcard `*` for `Access-Control-Allow-Origin` if `Access-Control-Allow-Credentials: true` is required — the browser will reject the response.
+- **DO**: Handle preflight (`OPTIONS`) requests by returning appropriate headers before processing data.
+
+```http
+Access-Control-Allow-Origin: https://trusted-app.com
+Access-Control-Allow-Credentials: true
+```
+
+#### Clear-Site-Data (Logout)
+- **DO**: Use `Clear-Site-Data` on logout endpoints to ensure complete session termination.
+
+```http
+Clear-Site-Data: "cookies", "storage", "cache"
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/trusted-types.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/trusted-types.md
new file mode 100644
index 00000000..41e6364d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/trusted-types.md
@@ -0,0 +1,140 @@
+# Prevent DOM-based XSS attacks with Trusted Types
+
+Trusted Types is a security feature that helps prevent DOM-based Cross-Site Scripting (DOM XSS) by requiring that data being passed into "dangerous" browser APIs (known as sinks) is first converted into a specific type, such as `TrustedHTML`.
+
+By default, many DOM APIs (like `innerHTML` or `document.write`) accept raw strings. If a string contains malicious script from an untrusted source, it can be executed. Trusted Types changes this behavior: once enabled via CSP, these sinks will only accept `TrustedHTML` objects created by authorized policies.
+
+## Key Implementation Details
+
+To use Trusted Types, follow four main steps:
+
+1. Define a security policy that specifies how to sanitize or transform strings.
+2. Use that policy to create Trusted Type objects from raw strings.
+3. Use the Trusted Type objects when writing to DOM sinks.
+4. Enforce Trusted Types using a Content Security Policy (CSP).
+
+### 1. Creating a Policy
+
+A policy is a set of rules for sanitizing content. You create it using `trustedTypes.createPolicy()`, typically delegating to a sanitizer library such as DOMPurify or your application's HTML escaping rules:
+
+```javascript
+import DOMPurify from 'dompurify';
+
+const myPolicy = trustedTypes.createPolicy('sanitize-html', {
+  createHTML: (input) =>
+    // Return a sanitized string; createPolicy() wraps it in a TrustedHTML object.
+    // Example using DOMPurify:
+    DOMPurify.sanitize(input, { RETURN_TRUSTED_TYPE: false }),
+});
+
+// Example using HTML escaping (for environments without third-party sanitizers):
+const escapePolicy = trustedTypes.createPolicy('escape-html', {
+  createHTML: (input) =>
+    String(input)
+      .replaceAll('&', '&amp;')
+      .replaceAll('<', '&lt;')
+      .replaceAll('>', '&gt;')
+      .replaceAll('"', '&quot;')
+      .replaceAll("'", '&#39;'),
+});
+```
+
+> **Warning:** Character-level HTML escaping (`escapePolicy`) converts all markup into plain text and is **not** a context-aware HTML sanitizer. If you only need plain text, prefer `element.textContent` (which is not a Trusted Types sink). Never interpolate `escapePolicy.createHTML()` output into another HTML template string—such as an unquoted attribute (`<img src=${escaped}>`) or a URL attribute (`<a href="${escaped}">`, where `javascript:` URLs are not neutralized by entity escaping). Use a full HTML sanitizer (`DOMPurify` or `element.setHTML()`, covered in `sanitize-untrusted-html` (via `npx -y modern-web-guidance@latest retrieve "sanitize-untrusted-html"`)) whenever accepting HTML markup or attributes.
+
+### 2. Using the Policy
+
+Instead of passing a string directly to a sink, you call the policy's creation method.
+
+```javascript
+const untrustedInput = '<p>Hello, <strong>world</strong>!</p><img src="x" onerror="alert(1)">';
+
+// In an enforced environment, this would throw a TypeError:
+// element.innerHTML = untrustedInput;
+
+// This returns a TrustedHTML object with unsafe elements and attributes removed:
+const cleanHTML = myPolicy.createHTML(untrustedInput);
+// Result: "<p>Hello, <strong>world</strong>!</p><img src=\"x\">"
+```
+
+### 3. Transitioning sinks to use Trusted Types
+
+Update each instance where you write to a sink to first convert it to a Trusted Type object. To help locate where code needs to be updated, you can define a temporary `default` policy that logs when a sink is written to with a string rather than a TrustedType.
+
+```javascript
+trustedTypes.createPolicy("default", {
+  createHTML(value) {
+    console.warn("String passed instead of Trusted Type.");
+    return DOMPurify.sanitize(value, { RETURN_TRUSTED_TYPE: false });
+  },
+});
+```
+
+Common sinks that support Trusted Types include:
+- **HTML:** `element.innerHTML`, `element.outerHTML`, `document.write()`, `element.setHTMLUnsafe()`, `Document.parseHTMLUnsafe()`
+- **Script:** `<script>` text content, `eval()`
+- **ScriptURL:** `<script src>`, `Worker()`, `SharedWorker()`
+
+```javascript
+// Assign the TrustedHTML object.
+element.innerHTML = cleanHTML;
+```
+
+Note that the "safe" HTML sanitization methods (`element.setHTML()` and `Document.parseHTML()`, covered in `sanitize-untrusted-html` (via `npx -y modern-web-guidance@latest retrieve "sanitize-untrusted-html"`)), do not require a Trusted Types policy, as they always sanitize potential XSS attacks natively.
+
+### 4. Enforcing Trusted Types with CSP
+
+Trusted Types should be rolled out incrementally to avoid breaking your application. While full enforcement provides the strongest protection, it carries a risk of site breakage if every sink write hasn't been migrated.
+
+#### Prerequisites
+
+- **Framework cooperation**: If your application's framework (or any third-party library that writes to DOM sinks) does not produce `TrustedHTML` or `TrustedScript` values, you cannot enforce Trusted Types without breaking that code. Audit framework support before starting the rollout.
+- **Sink refactoring**: Ensure you have identified and refactored dangerous sinks to use your Trusted Types policies.
+
+#### Rollout Strategy
+
+1.  **Report-Only**: First, roll out using the `Content-Security-Policy-Report-Only` header. This will log violations to your reporting endpoint without actually blocking the writes.
+    ```http
+    Content-Security-Policy-Report-Only: require-trusted-types-for 'script';
+    ```
+2.  **Enforcement**: Once you have integrated your policies and violation reports drop to zero, move to full enforcement.
+
+    ```http
+    Content-Security-Policy: require-trusted-types-for 'script';
+    ```
+
+You can also restrict which policies are allowed to be created (list your policy names such as `sanitize-html` or `escape-html`, include `dompurify` if your policy delegates to `DOMPurify.sanitize()`—which internally creates a `dompurify` policy—and include `default` if you register a default policy during migration):
+
+```http
+Content-Security-Policy: require-trusted-types-for 'script'; trusted-types sanitize-html escape-html dompurify;
+```
+
+With this CSP in place, any writes to a sink that don't use Trusted Types will throw an error. In addition, attempting to create a Trusted Type policy with a name not listed in `trusted-types` will throw an error.
+
+You can also set this CSP as a `<meta>` tag in your document's `<head>`, although this is potentially less secure.
+
+```html
+<!-- First child of `<head>`, as earlier tags will not enforce this CSP. -->
+<meta
+  http-equiv="Content-Security-Policy"
+  content="require-trusted-types-for 'script'; trusted-types sanitize-html escape-html dompurify;"
+/>
+```
+
+## Fallback strategies
+
+Baseline status for Trusted types: Newly available. It's been Baseline since 2026-02-24.
+Supported by: Chrome 83 (May 2020), Edge 83 (May 2020), Firefox 148 (Feb 2026), and Safari 26 (Sep 2025).
+
+For browsers that do not yet support Trusted Types, you can use a minimal "tinyfill" to ensure your code doesn't break while still providing sanitization.
+
+```javascript
+if (!window.trustedTypes) {
+  window.trustedTypes = {
+    createPolicy: (name, rules) => rules,
+  };
+}
+```
+
+This allows you to write your code using the Trusted Types pattern today. Supporting browsers will enforce the types, while older browsers will still execute your sanitization logic via the mock policy.
+
+If a browser doesn't support Trusted Types, it will simply treat the `TrustedHTML` objects as strings (if using the tinyfill) or won't have the enforcement check at the sink level.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/validate-origins.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/validate-origins.md
new file mode 100644
index 00000000..c3bafd1c
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/validate-origins.md
@@ -0,0 +1,197 @@
+# Compare and validate web origins and sites
+
+While comparing `event.origin` against a fixed, port-normalized string literal (such as `event.origin === 'https://app.example.com'`) works for simple allowlists, manual string comparisons and regular expressions break down when validating arbitrary URLs, DOM link elements, cross-subdomain redirects, or sandboxed messages:
+
+- **Prefix and substring spoofing:** Checking `url.startsWith('https://app.example.com')` is bypassed by `'https://app.example.com.attacker.example'`.
+- **Unnormalized URLs:** Full URLs with paths, query strings, or explicit default ports (`'https://app.example.com:443/path'`) do not match `'https://app.example.com'` under string equality without first parsing and normalizing.
+- **Public Suffix List mistakes:** Splitting hostnames on `.` to check same-site relationships fails on multi-label public suffixes (such as `.co.uk` or shared hosting domains like `.github.io`) and ignores scheme mismatches (`http:` vs. `https:`).
+- **Opaque `"null"` origin collisions:** Sandboxed iframes (`<iframe sandbox="allow-scripts">`) and `data:` URLs serialize `event.origin` to the literal string `"null"`. Comparing two serialized runtime origins with `originA === originB` falsely equates two unrelated opaque contexts (`"null" === "null"`).
+
+The **`Origin` API** (`Origin.from()`, `isSameOrigin()`, `isSameSite()`, and `opaque`) provides structured, spec-compliant origin and schemeful same-site comparisons backed by the browser's URL parser and Public Suffix List.
+
+## Choosing the right comparison for your scenario
+
+- **Use `isSameOrigin()` for strict privilege boundaries:** Require an exact `(scheme, host, port)` match when handling cross-window `postMessage` commands (such as an embedded checkout or auth popup) or deciding whether to attach credentials. Even a different subdomain (`https://blog.example.com` vs. `https://app.example.com`) is a different origin and must be rejected so a vulnerability on one subdomain cannot control another.
+- **Use `isSameSite()` for cross-subdomain navigation and link classification:** Allow any subdomain or port sharing the same scheme and registrable domain when validating post-login redirect URLs (`?returnTo=https://billing.example.co.uk/orders`) or classifying links as internal vs. external. `isSameSite()` rejects both `http:` scheme downgrades and sibling tenants on shared public suffixes (`.co.uk`, `.github.io`).
+- **Use `origin.opaque` and `Origin.from(event)` for opaque or sandboxed contexts:** Reject `data:` URLs for redirects (`origin.opaque === true`), or pin the opaque `Origin` extracted via `Origin.from(event)` when communicating with a specific `<iframe sandbox="allow-scripts">` widget whose serialized `event.origin` is `"null"`.
+
+## 1. Verify Exact Origins for Privileged Actions (`Origin.from()` and `isSameOrigin()`)
+
+Use `Origin.from()` to extract an `Origin` object and compare it against a trusted `Origin` using `isSameOrigin()`:
+
+- **Both sides must be `Origin` instances:** `isSameOrigin(other)` and `isSameSite(other)` only accept an `Origin` object—passing a raw string throws a `TypeError`.
+- **Supported `Origin.from()` inputs:**
+  - Serialized URL strings (for example, `'https://app.example.com:443/path'`). Note that any invalid URL string—for instance `'example'`, or the `'null'` string serialized by `event.origin` for opaque origins—causes `Origin.from()` to throw a `TypeError`.
+  - Platform objects that define origin-extraction steps in the HTML specification: `Origin`, `URL`, `HTMLAnchorElement` (`<a>`), `HTMLAreaElement` (`<area>`), same-origin `Window` or `WorkerGlobalScope` (`Origin.from(self)`), and browser-dispatched `MessageEvent` instances (`Origin.from(event)`).
+  - Objects such as `Location`, `WorkerLocation`, `Document`, `Request`, and `Response` do **not** define origin-extraction steps and throw a `TypeError` if passed directly to `Origin.from()`—pass `self` (for the current context) or `request.url` / `response.url` instead.
+- **Handle both browser-dispatched and synthetic `MessageEvent` instances:** Real browser `postMessage` events carry an internal origin extracted by `Origin.from(event)`, whereas synthetic `new MessageEvent('message', { origin })` events created in unit tests only populate the `event.origin` string and throw on `Origin.from(event)`. Falling back to `Origin.from(event.origin)` inside a `try...catch` handles both cleanly while still rejecting invalid or `"null"` strings.
+
+```javascript
+// Replace with your application's trusted origin(s)
+const TRUSTED_ORIGIN = Origin.from('https://app.example.com');
+
+function extractOrigin(candidate) {
+  try {
+    return Origin.from(candidate);
+  } catch (err) {
+    // Synthetic new MessageEvent('message', { origin }) objects in tests lack an
+    // internal browser origin; fall back to parsing candidate.origin if it is a URL.
+    if (typeof MessageEvent !== 'undefined' && candidate instanceof MessageEvent) {
+      return Origin.from(candidate.origin);
+    }
+    throw err;
+  }
+}
+
+export function isTrustedSameOrigin(candidate) {
+  try {
+    return extractOrigin(candidate).isSameOrigin(TRUSTED_ORIGIN);
+  } catch {
+    // Rejects invalid URLs, "null" strings, or unsupported objects
+    return false;
+  }
+}
+
+window.addEventListener('message', (event) => {
+  if (!isTrustedSameOrigin(event)) return;
+
+  // Safe to process privileged commands from the verified origin
+});
+```
+
+## 2. Validate Cross-Subdomain Redirects and Links (`isSameSite()`)
+
+When validating redirect targets (such as `?returnTo=` parameters) or internal links across subdomains of the same registrable domain (for example, `https://app.example.co.uk` and `https://billing.example.co.uk:8443`), use `isSameSite()`:
+
+- `isSameSite()` performs a **schemeful same-site** comparison: `https://sub.example.com` and `http://sub.example.com` are **not** same-site because their schemes differ.
+- `isSameSite()` uses the browser's built-in **Public Suffix List**, so distinct tenants on shared public suffixes (such as `https://tenant-a.github.io` and `https://tenant-b.github.io`, or `https://a.co.uk` and `https://b.co.uk`) evaluate to `false`.
+
+```javascript
+// Replace with your application's primary origin
+const APP_ORIGIN = Origin.from('https://app.example.co.uk');
+
+export function isAllowedSameSiteUrl(candidateUrlOrElement) {
+  try {
+    return extractOrigin(candidateUrlOrElement).isSameSite(APP_ORIGIN);
+  } catch {
+    return false;
+  }
+}
+
+// true: same scheme (https) and same registrable domain (example.co.uk)
+isAllowedSameSiteUrl('https://billing.example.co.uk:8443/checkout');
+
+// false: scheme downgrade (http vs. https) is rejected by schemeful same-site
+isAllowedSameSiteUrl('http://billing.example.co.uk/checkout');
+```
+
+## 3. Distinguish and Pin Opaque Origins (`origin.opaque` and `Origin.from(event)`)
+
+Sandboxed iframes (`<iframe sandbox="allow-scripts">`), `data:` URLs, and `new Origin()` produce **opaque origins** (`origin.opaque === true`). While their string serialization is always `"null"`, `Origin.from(event)` extracts the sender's actual underlying opaque origin from a browser-dispatched `MessageEvent`:
+
+- Two messages sent from the **same** sandboxed iframe yield `Origin` objects that are `isSameOrigin()` with each other (`true`).
+- Messages sent from **different** sandboxed iframes—or separate `Origin.from('data:...')` / `new Origin()` calls—yield distinct opaque origins that evaluate `isSameOrigin()` to `false`, preventing `"null" === "null"` spoofing across unrelated opaque contexts.
+- `new Origin()` creates a fresh, unique opaque origin that matches nothing except itself, which is useful as a default deny-all sentinel before an expected peer origin is pinned once on initialization.
+
+```javascript
+// Initialize with a unique opaque sentinel that matches no other origin
+let pinnedSandboxOrigin = new Origin();
+let isSandboxPinned = false;
+
+export function handleSandboxedWidgetMessage(event, expectedWidgetWindow) {
+  try {
+    const senderOrigin = Origin.from(event);
+
+    // Pin the opaque origin only once on initialization from the expected sandboxed iframe
+    if (!isSandboxPinned && event.source === expectedWidgetWindow && event.data?.type === 'init') {
+      pinnedSandboxOrigin = senderOrigin;
+      isSandboxPinned = true;
+    }
+
+    // Subsequent messages from the SAME sandboxed iframe match pinnedSandboxOrigin;
+    // messages from any other sandboxed iframe (also event.origin === "null") return false.
+    return senderOrigin.isSameOrigin(pinnedSandboxOrigin);
+  } catch {
+    return false;
+  }
+}
+```
+
+## Best practices
+
+- **DO** convert both sides of a comparison to `Origin` instances via `Origin.from()` before calling `isSameOrigin(other)` or `isSameSite(other)`.
+- **DO** pass a browser-dispatched `MessageEvent` directly to `Origin.from(event)` when you need to preserve opaque origin identity, and use `Origin.from(self)` (rather than `Location` or `Document`, which throw `TypeError`) to obtain the current execution context's `Origin`.
+- **DO** wrap `Origin.from()` calls on untrusted or runtime inputs in a `try...catch` block so invalid URLs, `"null"` strings, or unsupported objects safely return `false` instead of throwing an uncaught `TypeError`.
+- **DO NOT** compare two runtime `event.origin` or `url.origin` strings directly without first rejecting `"null"` (`origin !== 'null'`), as two unrelated opaque origins both serialize to `"null"`.
+- **DO NOT** validate origins or sites with `startsWith()`, `includes()`, `endsWith()`, or naive `.split('.')` hostname slicing.
+
+## Fallback strategy
+
+Browser support for Origin: Limited availability.
+Supported by: Chrome 145 (Feb 2026), Edge 145 (Feb 2026), and Safari 26.5 (May 2026).
+Unsupported in: Firefox.
+
+If your Baseline target includes browsers that do not yet support the `Origin` interface, feature-detect `'Origin' in globalThis` and fall back to parsing URLs with `new URL()`:
+
+- **Same-origin fallback (tuple origins):** Extract the URL string (using `event.origin` for `MessageEvent` objects or `candidate.href` for link elements), parse both the candidate and trusted URLs with `new URL()`, reject `"null"` opaque origins (`candidateUrl.origin !== 'null'`), and compare `candidateUrl.origin === trustedUrl.origin`. Because an opaque origin is never same-origin with a tuple origin like `'https://app.example.com'`, immediately rejecting `'null'` matches `Origin.isSameOrigin()`.
+- **Same-site fallback (caveat):** The `URL` interface does not expose the browser's Public Suffix List. In browsers without `Origin`, only perform suffix matching against an explicit, known private registrable domain that you control (verifying both `protocol` and an exact or dot-prefixed `hostname` match), or use a maintained Public Suffix List library.
+- **Opaque / sandboxed iframe fallback:** Browsers without `Origin` do not expose distinct opaque origin identities on `MessageEvent` (`event.origin` is always `"null"`). If you intentionally accept messages from a known sandboxed `<iframe sandbox="allow-scripts">`, verify `event.source === expectedWidgetWindow` (or communicate over a dedicated `MessageChannel` `MessagePort` transferred to the iframe on initialization) rather than comparing `event.origin`.
+
+```javascript
+// Replace with your trusted reference URL and known registrable domain
+const TRUSTED_URL = 'https://app.example.com';
+const TRUSTED_SITE_DOMAIN = 'example.com';
+
+function extractUrlString(candidate) {
+  if (typeof candidate === 'string') return candidate;
+  if (typeof MessageEvent !== 'undefined' && candidate instanceof MessageEvent) {
+    return candidate.origin;
+  }
+  if (candidate === globalThis) {
+    return globalThis.location?.href ?? '';
+  }
+  return candidate?.href ?? '';
+}
+
+function extractOrigin(candidate) {
+  try {
+    return Origin.from(candidate);
+  } catch (err) {
+    if (typeof MessageEvent !== 'undefined' && candidate instanceof MessageEvent) {
+      return Origin.from(candidate.origin);
+    }
+    throw err;
+  }
+}
+
+export function checkSameOriginWithFallback(candidate) {
+  try {
+    if ('Origin' in globalThis) {
+      return extractOrigin(candidate).isSameOrigin(Origin.from(TRUSTED_URL));
+    }
+    const candidateUrl = new URL(extractUrlString(candidate));
+    const trustedUrl = new URL(TRUSTED_URL);
+    return candidateUrl.origin !== 'null' && candidateUrl.origin === trustedUrl.origin;
+  } catch {
+    return false;
+  }
+}
+
+export function checkSameSiteWithFallback(candidate) {
+  try {
+    if ('Origin' in globalThis) {
+      return extractOrigin(candidate).isSameSite(Origin.from(TRUSTED_URL));
+    }
+    const candidateUrl = new URL(extractUrlString(candidate));
+    const trustedUrl = new URL(TRUSTED_URL);
+    return (
+      candidateUrl.origin !== 'null' &&
+      candidateUrl.protocol === trustedUrl.protocol &&
+      (candidateUrl.hostname === TRUSTED_SITE_DOMAIN ||
+        candidateUrl.hostname.endsWith(`.${TRUSTED_SITE_DOMAIN}`))
+    );
+  } catch {
+    return false;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/verify-email-ownership.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/verify-email-ownership.md
new file mode 100644
index 00000000..50b1542b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/security/verify-email-ownership.md
@@ -0,0 +1,235 @@
+# Verify email address ownership
+
+When collecting an email address during sign-up, sign-in, checkout, or account recovery, verifying ownership traditionally requires sending an out-of-band one-time passcode (OTP) or magic link. This forces users to leave your page, wait for email delivery, and copy codes—introducing friction, drop-off, and phishing risk, while also revealing to the email provider which relying party (RP) the user is visiting.
+
+The **Email Verification API** (client-side HTML extension) and **Email Verification Protocol (EVP)** (backend cryptographic protocol) enable a relying party to verify that a user controls an email address without sending a verification email. The browser intermediates between the relying party and the user's email provider (the issuer):
+
+1. The relying party includes a hidden `<input>` with `autocomplete="email-verification-token"` and a single-use cryptographic `nonce` in the same `<form>` as the email input.
+2. When the user selects or enters an email address, the browser looks up the domain's `_email-verification.<domain>` DNS `TXT` record, verifies the user has an active session with the authoritative issuer, and requests an **Email Verification Token (EVT)** without disclosing the relying party's identity to the issuer.
+3. The browser binds the EVT to the relying party's origin and session `nonce` in a **Key Binding JWT (KB-JWT)** signed with an ephemeral browser key pair (`EVT + KB-JWT`), populates the hidden input, and submits the form.
+4. The relying party's backend verifies the cryptographic chain and, if valid, skips the email OTP or magic link step.
+
+## 1. Enable the Origin Trial and Render the Verification Form
+
+To participate as a verifying site (relying party):
+
+1. **Provide the Origin Trial token** on the page hosting the form using either the `Origin-Trial` HTTP response header or a `<meta http-equiv="origin-trial">` element.
+   - **Third-party origin trials:** Embedded identity SDKs can inject a third-party trial token, provided the Origin Trial registrant origin matches the issuer domain (same-site with the issuer, such as `https://issuer.example`).
+2. **Generate a cryptographically random nonce per form render** with at least 128 bits of entropy (for example, `randomBytes(32).toString('base64url')` from `node:crypto`), store it in **server-side session state** keyed by an `HttpOnly`, `Secure`, `SameSite=Lax` session ID cookie (never store the expected `nonce` value directly inside a client cookie where an attacker could replay both the cookie and token), and render it into the hidden token input's `nonce` attribute. Serve the page with `Cache-Control: no-store` so back/forward navigation does not reuse an already-consumed nonce.
+3. **Add the hidden token input** (`autocomplete="email-verification-token"`) inside the same `<form>` as the email input (`autocomplete="email"`).
+
+```html
+<!-- Serve with:
+     Origin-Trial: <YOUR_ORIGIN_TRIAL_TOKEN>
+     Cache-Control: no-store -->
+<form method="POST" action="/api/verify-email">
+  <label for="email">Email address:</label>
+  <input
+    type="email"
+    id="email"
+    name="email"
+    autocomplete="email"
+    required
+  />
+
+  <!-- MANDATORY: Must be in the same <form> as the email input.
+       The nonce value must be freshly generated on the server per form render. -->
+  <input
+    type="hidden"
+    name="token"
+    nonce="SERVER_GENERATED_PER_FORM_NONCE"
+    autocomplete="email-verification-token"
+  />
+
+  <button type="submit">Continue</button>
+</form>
+```
+
+## 2. Verify the Submitted Token on the Server
+
+When the form is submitted, treat the `token` field as untrusted input. Atomically read and delete the expected `nonce` from your server-side session store on receipt. If the `token` field is empty (for example, in browsers that do not support EVP or when the user is signed out of their email provider) or if verification fails, fall back immediately to your standard email OTP or magic link flow:
+
+```javascript
+// Replace with your public relying-party origin
+const RP_ORIGIN = 'https://rp.example.com';
+
+export async function handleSignupSubmission(request) {
+  const formData = await request.formData();
+  const submittedEmail = String(formData.get('email') || '').trim();
+  const rawToken = String(formData.get('token') || '').trim();
+  // Atomically read and delete the single-use nonce from server-side session state
+  const expectedNonce = await consumeSessionNonce(request);
+
+  if (rawToken && expectedNonce) {
+    try {
+      await verifyEmailVerificationToken({
+        rawToken,
+        submittedEmail,
+        expectedNonce,
+        expectedAudience: RP_ORIGIN,
+      });
+      // Fast path: email ownership is cryptographically verified; skip OTP email.
+      return completeAccountCreation(submittedEmail);
+    } catch (err) {
+      // Log token verification failures before falling back to standard email verification.
+      console.error('Email verification token check failed:', err);
+    }
+  }
+
+  // Fallback path: send standard OTP code or magic link email to submittedEmail.
+  return sendTraditionalVerificationEmail(submittedEmail);
+}
+```
+
+Always use established SD-JWT and JOSE/JWT libraries for your backend platform (such as `@sd-jwt/core` and `jose` in Node.js, `sd-jwt-python` / `jwcrypto` in Python, or `sd-jwt-java` / Nimbus JOSE+JWT on the JVM) to implement `verifyEmailVerificationToken` rather than hand-rolling custom JWT or SD-JWT parsing code.
+
+### Step 1: Parse the SD-JWT claims and validate the email address
+
+After consuming the single-use `expectedNonce` from server-side session storage, decode the SD-JWT presentation (`EVT + KB-JWT`) and verify that:
+- Both the issuer JWT (`jwt`) and Key Binding JWT (`kbJwt`) are present, along with the issuer claim (`iss`).
+- `evtPayload.email_verified === true`.
+- `evtPayload.email` matches the submitted form email using a **case-insensitive comparison** (`toLowerCase()`).
+
+```javascript
+import { createHash } from 'node:crypto';
+import { decodeSdJwtSync } from '@sd-jwt/core';
+
+const hasher = (data, alg) =>
+  createHash(alg === 'sha-256' ? 'sha256' : alg).update(data).digest();
+
+const decoded = decodeSdJwtSync(rawToken, hasher);
+const evtPayload = decoded.jwt.payload;
+const iss = evtPayload.iss;
+
+if (!expectedNonce || !decoded.kbJwt || !iss || evtPayload.email_verified !== true) {
+  throw new Error('Missing nonce, KB-JWT, issuer, or email_verified !== true.');
+}
+// MANDATORY: Compare email addresses case-insensitively
+if (evtPayload.email?.toLowerCase() !== submittedEmail.toLowerCase()) {
+  throw new Error('Submitted email does not match the EVT email claim.');
+}
+```
+
+### Step 2: Validate DNS TXT delegation and load the issuer JWKS
+
+Before making any network request to `iss`, verify that the submitted email's domain delegates authority to that exact issuer via a `_email-verification.<domain>` DNS `TXT` record (`iss=<issuer-host>` -> `https://<issuer-host>` with no port, path, or trailing slash). Once DNS delegation matches `iss` byte-for-byte, fetch `${iss}/.well-known/email-verification` over HTTPS, confirm that `metadata.issuer === iss`, and load the issuer's JSON Web Key Set (JWKS).
+
+> **Note on `kid` handling:** Some major email providers (such as Gmail) omit `kid` from the EVT header. When `kid` is absent and the JWKS contains multiple keys, `jose` throws `ERR_JWKS_MULTIPLE_MATCHING_KEYS` (an `AsyncIterable` of matching `CryptoKey`s)—iterate `for await (const publicKey of err)` to trial-verify each key, as shown in Step 3.
+
+```javascript
+import dns from 'node:dns/promises';
+import { createRemoteJWKSet } from 'jose';
+
+const domain = submittedEmail.split('@')[1];
+const txtRecords = (await dns.resolveTxt(`_email-verification.${domain}`)).map((r) => r.join(''));
+if (!txtRecords.some((txt) => txt.startsWith('iss=') && `https://${txt.slice(4).trim()}` === iss)) {
+  throw new Error(`Issuer "${iss}" is not delegated via DNS for "${domain}".`);
+}
+
+const discoveryUrl = new URL('/.well-known/email-verification', iss);
+if (discoveryUrl.protocol !== 'https:') throw new Error('Issuer must use HTTPS.');
+const metadata = await (await fetch(discoveryUrl)).json();
+if (metadata.issuer !== iss || !metadata.jwks_uri?.startsWith('https://')) {
+  throw new Error('Invalid issuer metadata or non-HTTPS jwks_uri.');
+}
+const issuerJwks = createRemoteJWKSet(new URL(metadata.jwks_uri));
+```
+
+### Step 3: Verify the EVT signature and Key Binding JWT (`KB-JWT`)
+
+Finally, verify both signatures and the cryptographic binding between the two tokens using the explicit asymmetric algorithm allowlist (`['Ed25519', 'EdDSA', 'ES256']`):
+1. **EVT signature (`verifier`):** Verify against `issuerJwks` (catching `ERR_JWKS_MULTIPLE_MATCHING_KEYS` to iterate candidate keys when `kid` is omitted), enforcing `iss` and a tight freshness window (`maxTokenAge: '5m'`, `clockTolerance: '1m'`).
+2. **Holder binding (`kbVerifier` and `sdJwt.verify` options):** Extract the browser's ephemeral public key from `evtPayload.cnf.jwk`, confirm both `cnf.jwk.alg` and `decoded.kbJwt.header.alg` are in `ALLOWED_ALGS` and match (treating `'Ed25519'` and `'EdDSA'` as equivalent while Origin Trial implementations transition to RFC 9864 `'Ed25519'`), and verify the `KB-JWT` signature with `typ: 'kb+jwt'`. Pass `keyBindingNonce: expectedNonce`, `expectedKeyBindingAudience: expectedAudience`, and `keyBindingMaxAgeSeconds: 300` to `sdJwt.verify()`—`@sd-jwt/core` only invokes `kbVerifier` and validates `nonce`, `aud`, `iat`, and `sd_hash` when `keyBindingNonce` is supplied.
+
+```javascript
+import { SDJwtInstance } from '@sd-jwt/core';
+import { importJWK, jwtVerify } from 'jose';
+
+// IETF draft-hardt-email-verification-02 (§3.3, §5.1.1) specifies RFC 9864 'Ed25519' and 'ES256'.
+// TODO: Remove 'EdDSA' once live issuers (e.g. Gmail) and Chrome Origin Trial builds finish
+// transitioning from 'EdDSA' (with crv: 'Ed25519') to 'Ed25519'.
+const ALLOWED_ALGS = ['Ed25519', 'EdDSA', 'ES256'];
+const normalizeAlg = (alg) => (alg === 'Ed25519' ? 'EdDSA' : alg);
+const evtOptions = {
+  typ: 'ev+sd-jwt',
+  issuer: iss,
+  algorithms: ALLOWED_ALGS,
+  maxTokenAge: '5m',
+  clockTolerance: '1m',
+};
+
+const sdJwt = new SDJwtInstance({
+  hasher,
+  verifier: async (data, sig) => {
+    const compactEvt = `${data}.${sig}`;
+    try {
+      await jwtVerify(compactEvt, issuerJwks, evtOptions);
+    } catch (err) {
+      // When `kid` is omitted (e.g. Gmail) and multiple keys match in the JWKS,
+      // jose throws JWKSMultipleMatchingKeys, which yields each matching CryptoKey.
+      if (err?.code !== 'ERR_JWKS_MULTIPLE_MATCHING_KEYS') throw err;
+      let matched = false;
+      for await (const publicKey of err) {
+        try {
+          await jwtVerify(compactEvt, publicKey, evtOptions);
+          matched = true;
+          break;
+        } catch {}
+      }
+      if (!matched) throw err;
+    }
+    return true;
+  },
+  kbVerifier: async (data, sig) => {
+    const holderJwk = evtPayload.cnf?.jwk;
+    const holderAlg = holderJwk?.alg;
+    const kbAlg = decoded.kbJwt.header.alg;
+    if (
+      !holderAlg ||
+      !kbAlg ||
+      !ALLOWED_ALGS.includes(holderAlg) ||
+      !ALLOWED_ALGS.includes(kbAlg) ||
+      normalizeAlg(kbAlg) !== normalizeAlg(holderAlg)
+    ) {
+      throw new Error('Missing, disallowed, or mismatched KB-JWT algorithm.');
+    }
+    const holderKey = await importJWK(holderJwk, kbAlg);
+    await jwtVerify(`${data}.${sig}`, holderKey, {
+      typ: 'kb+jwt',
+      audience: expectedAudience,
+      algorithms: [kbAlg],
+      maxTokenAge: '5m',
+      clockTolerance: '1m',
+    });
+    return true;
+  },
+});
+
+const verified = await sdJwt.verify(rawToken, {
+  requiredClaimKeys: ['email', 'email_verified'],
+  keyBindingNonce: expectedNonce,
+  expectedKeyBindingAudience: expectedAudience,
+  keyBindingMaxAgeSeconds: 300,
+  skewSeconds: 60,
+});
+```
+
+## Best practices
+
+- **DO** perform all token verification strictly on the server. **DO NOT** validate tokens in client-side JavaScript or trust any client-side verification state—client-side checks can be trivially bypassed or forged and provide zero trust guarantee to the relying party.
+- **DO** use established SD-JWT and JOSE/JWT libraries for your backend platform (for example, `@sd-jwt/core` and `jose` in Node.js) to parse and validate the `EVT~KB-JWT` presentation, and pass `keyBindingNonce` to `sdJwt.verify()` so Key Binding verification cannot be bypassed. **DO NOT** hand-roll custom JWT, SD-JWT, or `sd_hash` parsing and signature verification routines.
+- **DO** generate a fresh cryptographic `nonce` (at least 128 bits, such as `randomBytes(32).toString('base64url')`) on the server for each form render, store it in **server-side session state** (not directly in a client cookie), and serve the form page with `Cache-Control: no-store`.
+- **DO** atomically read and delete the expected `nonce` from server-side session storage immediately when the `POST` request arrives so an intercepted token cannot be replayed.
+- **DO** perform a **case-insensitive comparison** between `evtPayload.email` and the submitted form email address (`email.toLowerCase()`), while preserving the submitted email string.
+- **DO** trial-verify all keys in the issuer's JWKS when `kid` is absent from the EVT header (providers such as Gmail omit `kid`).
+- **DO** verify DNS delegation (`_email-verification.<domain>`) before trusting any `iss` claim in an EVT, and confirm `metadata.issuer === iss` in the `.well-known/email-verification` response.
+- **DO NOT** treat email ownership verification as proof of inbox deliverability. EVP proves that the user controls the email account with the authoritative provider; still send transactional welcome emails and handle bounces normally.
+- **DO NOT** block account creation or sign-in when `token` is empty or when verification fails—always degrade gracefully to your standard email OTP or magic link flow.
+
+## Fallback strategy
+
+Email Verification (`autocomplete="email-verification-token"`) is designed as a **progressive enhancement** over traditional out-of-band email verification (OTP codes or magic links):
+
+- **Unsupported browsers:** Browsers that do not support `autocomplete="email-verification-token"` ignore the hidden input and submit the form with an empty `token` value.
+- **Unauthenticated or non-participating email domains:** When a user enters an email address whose domain does not publish an `_email-verification` DNS `TXT` record, or when the user does not have an active session with their email provider in the browser, the browser submits the form with an empty `token`.
+- **Expired or invalid tokens:** If the `nonce` has expired, was already consumed, or fails any step of `verifyEmailVerificationToken` in `handleSignupSubmission`, the server catches the error and sends a traditional OTP or magic link email without interrupting the user's sign-up or sign-in flow.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/carousel-slide-effects.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/carousel-slide-effects.md
new file mode 100644
index 00000000..e0db76da
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/carousel-slide-effects.md
@@ -0,0 +1,187 @@
+# Build Carousel Slide Effects
+
+Carousel slide effects are a great way to add visual interest to a carousel. As the user scrolls through the slides, each slide can animate as it enters, centers, and exits the scrollport. For example, the slides can fade in and out, rotate, or scale in size. This creates a dynamic and engaging user experience. Unlike simple entry/exit animations, this effect uses a single, continuous animation to control the slide's appearance across the entire scrollport.
+
+## How to implement
+
+Here’s how to create carousel slide effects:
+
+1.  **Create a scroller:** This element will act as the container for your carousel slides. In this example it uses `overflow-x: scroll` to allow horizontal scrolling.
+
+    ```html
+    <ul class="scroller">
+      <li class="entry">1</li>
+      <li class="entry">2</li>
+      <li class="entry">3</li>
+      …
+    </ul>
+    ```
+
+    ```css
+    .scroller {
+      overflow-x: scroll;
+    }
+    ```
+
+2.  **Define the animation:** Create a CSS animation that defines the different states of your slides as they traverse the scrollport. You can define keyframes for any part of the animation. For example, you can define a state for when the slides are in the center of the scrollport by including a `50%` keyframe. In this example, the `scale` property makes the slides grow as they approach the center and shrink as they move away.
+
+    ```css
+    @keyframes animate {
+      0% {
+        scale: 0.5;
+      }
+      50% {
+        scale: 1;
+      }
+      100% {
+        scale: 0.5;
+      }
+    }
+    ```
+
+3.  **Apply the animation and `view-timeline`:** Attach the animation to the carousel slides and link it to a `view-timeline` that tracks the element as it scrolls through the container.
+
+    ```css
+    .scroller > * {
+      animation: animate auto linear both;
+      animation-timeline: view(inline);
+    }
+    ```
+
+    By default, `view()` tracks the element on the `block` axis. If you need to track it on the `inline` axis, you can use `view(inline)`.
+
+## Example code
+
+This code animates the carousel items of a horizontal scroller on scroll using an **anonymous view-timeline**:
+
+```css
+@keyframes animate {
+  0% {
+    scale: 0.5;
+  }
+
+  50% {
+    scale: 1;
+  }
+
+  100% {
+    scale: 0.5;
+  }
+}
+
+.scroller > * {
+  /* Applies the animation using an `auto` duration */
+  animation: animate auto linear both;
+  /* Sets the animation timeline to use an anonymous view progress timeline, tracking the element's progress through the scroller on the inline axis */
+  animation-timeline: view(inline);
+}
+```
+
+This code animates the carousel items of a horizontal scroller on scroll using a **named view-timeline**:
+
+```css
+@keyframes animate {
+  0% {
+    scale: 0.5;
+  }
+
+  50% {
+    scale: 1;
+  }
+
+  100% {
+    scale: 0.5;
+  }
+}
+
+/* This creates a named view-timeline on each carousel item. The timeline is used to drive the animation that is applied on the same element. */
+.scroller > * {
+  /* Applies the animation using an `auto` duration */
+  animation: animate auto linear both;
+  /* Defines a named view progress timeline, tracking the element's progress through the scroller on the inline axis */
+  view-timeline: --item inline;
+  /* Sets the animation timeline to use the named view progress timeline defined above */
+  animation-timeline: --item;
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: view()) and (animation-range: entry))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: entry)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` and `animation-range` *after* it to prevent the shorthand from resetting the timeline.
+
+Prefer a named `view-timeline` when multiple DOM elements need to animate based on the same timeline, or when you need to animate children of the element that has the `view-timeline` defined on it. If the element that you animate is also the element that defines the `view-timeline`, you can use an anonymous view-timeline using `view()`.
+
+When using the `view()` function to create a scroll-driven animation:
+
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `view(block)` or `view(inline)`.
+
+When using the `view-timeline` property to create a scroll-driven animation:
+
+- **DO** use a CSS `<dashed-ident>` for the name (e.g. `view-timeline: --my-custom-name`)
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `view-timeline-axis`.
+- **DO** make sure the scope of the lookup works: When the element that is declaring the `view-timeline` is not a flat tree ancestor of the animated element, hoist up the visibility of the `view-timeline`’s name by using `timeline-scope` on a shared ancestor.
+
+## Browser support and fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.. Therefore, a fallback strategy is typically required.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses the Web Animations API (`Element.animate()`) to create a paused animation for each item in the carousel. It then listens to the `scroll` event on the scroller and updates the `currentTime` of each animation based on the item's scroll progress within the scroller.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: view()) and (animation-range: entry)')) {
+  const scroller = document.querySelector('.scroller');
+  const entries = document.querySelectorAll('.entry');
+
+  // Create a map to store animations
+  const animations = new Map();
+
+  entries.forEach(entry => {
+    const animation = entry.animate(
+      {
+        scale: ['0.5', '1', '0.5']
+      },
+      {
+        duration: 1, // We'll control the time ourselves
+        fill: 'both'
+      }
+    );
+    animation.pause();
+    animations.set(entry, animation);
+  });
+
+  // Update animations on scroll
+  const tick = () => {
+    const scrollerRect = scroller.getBoundingClientRect();
+
+    entries.forEach(entry => {
+      const animation = animations.get(entry);
+      if (!animation) return;
+
+      const entryRect = entry.getBoundingClientRect();
+      const progress = (entryRect.left + entryRect.width / 2 - scrollerRect.left) / scrollerRect.width;
+
+      animation.currentTime = progress;
+    });
+  };
+    
+  scroller.addEventListener('scroll', tick);
+  tick();
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/component-specific-light-dark-theme.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/component-specific-light-dark-theme.md
new file mode 100644
index 00000000..c5478494
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/component-specific-light-dark-theme.md
@@ -0,0 +1,179 @@
+# Component-specific light/dark themes
+
+While more commonly set on the root, the `color-scheme` property can be set on individual elements to force them into a different color scheme from the rest of the page.
+This can be useful for components that must always be viewed in a specific color scheme (e.g. always in dark or light mode).
+
+Example use cases include:
+- Elements that are often in dark mode even on light mode pages for aesthetic reasons, e.g. code blocks, media players, photo galleries
+- Areas that contain media designed for a light background (e.g. images, videos, illustrations, print previews) can be set to light mode even if the rest of the page is in dark mode.
+- Elements whose color-scheme is controlled by a user-level setting, such as component previews
+- Embeds that don't support both light and dark modes
+- Design tools, maps, visualizations, games etc.
+
+## When to change colors vs. when to force `color-scheme`?
+
+Not every element that uses lighter text on darker background in light mode or darker text on lighter background in dark mode needs a different `color-scheme`.
+For example, a primary button may be rendered as blue with white text in light mode, but that does not warrant a `color-scheme: dark`.
+
+As a rule of thumb, typically elements using a different `color-scheme` are complex surfaces establishing their own visual context, rather than simple shallow containers.
+
+When considering using a different `color-scheme` on an element, ask yourself:
+
+- Should built-in browser UI that is not otherwise customized (e.g. form controls, scrollbars, etc) use that color-scheme or adapt to the page's color-scheme? -> if the former, don't use `color-scheme`.
+- Should any `light-dark()` colors resolve like they do for the rest of the page or based on the override? -> if the former, don't use `color-scheme`.
+- Should descendants be in that `color-scheme`? If not, don't use `color-scheme`.
+
+## Basic implementation
+
+Component-specific overrides are typically (though not strictly necessarily) used on pages that also support multiple color schemes via a global `color-scheme`.
+For implementing page-wide dark mode well, see `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`).
+
+Once a page-wide `color-scheme` is in place, and you are using color tokens sensitive to it (e.g. via `light-dark()`), you can simply set `color-scheme` on specific components to override the color mode for that subtree:
+
+```css
+pre, code, .dark {
+  color-scheme: dark;
+}
+```
+
+Note that some browsers automatically adapt components to a different color scheme anyway.
+To force the specified color scheme in all cases, use `only`, i.e. `color-scheme: only dark;` instead of `color-scheme: dark;`.
+
+### Adapting non-color values
+
+`light-dark()` currently only works for colors.
+
+## Best practices
+
+- **MANDATORY**: Do not set `color-scheme` on elements without a background, as that risks mixing background and text color pairs from different color-schemes, resulting in unreadable text.
+- **OPTIONAL**: While it is easier to reuse the same color pairs as the page-wide dark mode, we _can_ define different color pairs for these components. For example, we may want a dark mode component used in a light mode page to be a little less dark than when the same dark mode component is used in a page that is overall in dark mode.
+
+## Known issues to be aware of
+
+### Important gotcha: Inheritance of `light-dark()` colors
+
+**`light-dark()` resolves at computed value time.**
+This means that any inherited `<color>` properties set to a `light-dark()` color will only pass down one of the two colors to their descendants, not the `light-dark()` expression itself.
+
+This includes:
+- Built-in color properties that inherit, such as `color`, `accent-color`, `fill`, `stroke`, `text-shadow`, `caret-color`
+- Any registered inheritable custom properties with `syntax: <color>` and `inherits: true`
+- Any other `<color>` property set to `inherit`
+
+This means you should:
+- **NOT** register custom properties meant to hold *design tokens* (e.g. `--surface-color`) as `<color>`. Tokens need to keep their `light-dark()` expression live so descendants can re-resolve them under a different `color-scheme`.
+- When setting `color-scheme` on an element, re-specify any inherited `<color>` properties that may have been set to `light-dark()` values (directly or via design tokens), even if that's to the same design token.
+- **NOT** use `inherit` on `<color>` properties on elements with a `color-scheme` override (fine to use on their descendants).
+- **DO** use registered `<color>` properties for the *opposite* use case: when you deliberately want to snapshot the ancestor's resolved color and prevent it from re-resolving under the descendant's `color-scheme`. For example, capturing the page background to use elsewhere.
+- If you need to animate a color, use a separate `@property`-registered `<color>` property on the element being animated (registration is required for color interpolation) — this is not a design token, but a per-element animation target, so it does not conflict with the rule above.
+
+Example:
+
+```css
+:root {
+	--accent-color: light-dark(blue, skyblue);
+	--surface-color: light-dark(white, #222);
+	--text-color: light-dark(#111, white);
+
+	color-scheme: light dark;
+	accent-color: var(--accent-color);
+	color: var(--text-color);
+}
+
+body {
+	/* --surface-color dynamically switches despite being inherited because --surface-color is not registered */
+	background: var(--surface-color);
+}
+
+pre, code {
+	color-scheme: dark;
+	background: var(--surface-color);
+
+	/* Without this, accent-color would be blue, not skyblue! */
+	accent-color: var(--accent-color);
+
+	/* Without this, text-color would be #111, not white! */
+	color: var(--text-color);
+}
+```
+
+### Issues to be aware of when using color-scheme
+
+- Chrome and Firefox respect `color-scheme` for iframes: they render embedded pages in the correct color scheme and adjust the embedded page's `prefers-color-scheme` media query to reflect the embedding context's `color-scheme`. Safari does not, and resolves `prefers-color-scheme` to the system setting even inside iframes.
+  - **If you control both parent and iframe:** pass the parent's color scheme to the iframe explicitly — via a URL parameter (`?theme=dark`) at iframe construction time, or via `postMessage()` (which also lets you react to runtime changes). In the iframe, set a class on `<html>` (and/or `color-scheme` on `:root`) from that signal instead of relying on `prefers-color-scheme`.
+  - **If you only control the embedded page:** there is no reliable way to detect the embedding context's `color-scheme` from inside the iframe in Safari. Expose an explicit theme parameter on your embed API (e.g. a query string or `postMessage` protocol) and document it for embedders.
+
+## Fallback strategies
+
+### Fallbacks & browser support for color-scheme
+
+Baseline status for color-scheme: Widely available. It's been Baseline since 2022-02-03.
+Supported by: Chrome 98 (Feb 2022), Edge 98 (Feb 2022), Firefox 96 (Jan 2022), and Safari 13 (Sep 2019).
+
+The `color-scheme` property is **progressive enhancement**.
+Browsers that do not support it will ignore this property and use their default light-mode UI.
+
+To adapt to the user's preferences in older browsers, use `prefers-color-scheme` media queries to provide different colors when dark mode is preferred.
+
+- DO use the media query to switch custom properties on `:root` or `html`
+- Avoid using the media query on individual components unless the component requires a very specific type of dark mode customization beyond colors.
+
+```css
+:root {
+  /* Define brand colors for each mode */
+  --color-brand-light: #0056b3;
+  --color-brand-dark: #00e5ff;
+  --color-brand: var(--color-brand-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --color-brand: var(--color-brand-dark);
+  }
+
+  /* Ignored in older browsers */
+  color-scheme: light dark;
+}
+
+button.primary {
+	background-color: var(--color-brand);
+}
+```
+
+### Fallbacks & browser support for light-dark()
+
+Baseline status for light-dark(): Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 123 (Mar 2024), Edge 123 (Mar 2024), Firefox 120 (Nov 2023), and Safari 17.5 (May 2024).
+
+For browsers that support `color-scheme` but not yet `light-dark()`, light and dark versions of colors should first be defined as custom properties, and the `prefers-color-scheme` media query should be used to set colors for the respective mode like in the example below:
+
+```css
+:root {
+  /* Define browser UI accent color for each mode */
+  --brand-accent-light: #0056b3;
+  --brand-accent-dark: #00e5ff;
+  --accent-color: var(--brand-accent-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --accent-color: var(--brand-accent-dark);
+  }
+
+  /* OPTIONAL: use light-dark() for more control of built-in UI colors */
+  @supports (color: light-dark(white, black)) {
+    --accent-color: light-dark(var(--brand-accent-light), var(--brand-accent-dark));
+  }
+
+  /* MANDATORY: Automatically adapt native UI to user system preferences */
+  color-scheme: light dark;
+
+  /* Example inherited color property */
+  accent-color: var(--accent-color);
+}
+
+pre, code {
+  color-scheme: dark;
+
+  /* **Mandatory**: any inherited color properties must be set again, even if to the same design tokens */
+  accent-color: var(--accent-color);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/icons.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/icons.md
new file mode 100644
index 00000000..5b00fba2
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/icons.md
@@ -0,0 +1,290 @@
+# Using and managing icons
+
+
+## Choosing an Icon Technique
+
+Icon storage and rendering are separate choices. For example, an SVG sprite can supply an icon to the CSS icon system or be referenced with `<use>`.
+
+* **CSS icon system:** Use when CSS should choose when and which icon to show. Use a mask for a single-color icon or a background image for a full-color icon.
+* **SVG with `<use>`:** Use to reuse a symbol when its built-in styling options are enough. CSS can't arbitrarily style or animate the referenced SVG's contents, but inherited properties and custom properties can be passed in when the symbol is designed to use them. For example, a path can use `fill="var(--icon-accent, currentColor)"` to let CSS color that part of the icon.
+* **Inline SVG:** Use when you need arbitrary styling or animation of the SVG's contents.
+* **`<img>` with CSS filters:** Avoid this for recoloring icons. Filters can't reliably apply an arbitrary CSS color value to the image, so recoloring is cumbersome and inflexible.
+
+To decide, ask two questions. Does CSS need to pick or swap the icon (component defaults, state changes, theming)? If yes, use the CSS icon system. Do you need to reach inside the icon beyond color? If yes and you control the icon source, design the symbol with custom properties and use `<use>`; if you do not control the source, inline the SVG. Third-party icon sets rarely expose custom properties, so `<use>` against them gives you color and little else.
+
+### Embedded or remote icons
+
+Both the CSS icon system and `<use>` can take icons from a data URI, an individual file, or a sprite. Embedding (data URIs or inline SVG) avoids a request and renders with the first paint, but bloats CSS or HTML and cannot be cached separately, so it suits a small set of icons that appear on every page. Individual files are cached independently and loaded on demand, at the cost of one request each. A sprite is one cacheable request for the whole set, but downloads every icon whether used or not, and `<use>` can only reference a sprite from the same origin. Prefer embedding for a handful of core icons and a sprite or individual files for larger sets.
+
+If a page renders thousands of icons at once, benchmark the actual page and assets. In a stress test, inline SVG had a small performance advantage at that scale, but results depend on the browser and implementation. [Cloud Four's SVG icon stress test](https://cloudfour.com/thinks/svg-icon-stress-test/)
+
+## Primary Approach: CSS-Driven Icon Engine
+
+Icons are design tokens: each icon is a custom property holding an image, and any element can display one by setting `--icon-start` or `--icon-end`. The engine combines three CSS capabilities:
+
+* **Registered custom properties (`@property`)** keep `--icon-start` and `--icon-end` from inheriting, so an icon set on a component does not cascade into its children.
+* **Container style queries (`@container style(...)`)** detect when an element has an icon assigned and render it, with no class or markup changes.
+* **CSS masks and `currentColor`** render the icon in a pseudo-element that follows the element's text color. Size, color, spacing and vertical offset are read from inheritable `--icon-style-*` properties with sensible fallbacks, so a whole subtree can be restyled from an ancestor. The `--icon-style-` prefix keeps these settings from colliding with the icon tokens themselves, which also live under `--icon-*`.
+
+### Defining icon design tokens
+
+Define SVG icons and any `--icon-style-*` overrides as reusable custom properties using inline SVG data URIs or root-relative URLs (e.g., `url("/icons/trash.svg")`). When an icon is loaded from an external SVG file, use a root-relative URL or an embedded data URI. A relative URL used through a custom property can resolve relative to the stylesheet where the icon is used, rather than the stylesheet where the custom property is defined. If those stylesheets are in different directories, the URL may resolve to the wrong file.
+
+To keep a URL relative to the stylesheet that defines the icon token, a registered property is meant to help: the computed value of a registered `<url>` or `<image>` is resolved against the stylesheet that declared it. DO NOT rely on registering the token as `<image>` with the URL in `initial-value`. Chrome and Safari resolve `initial-value` URLs against the document, so it only works in Firefox. Chrome also resolves values declared on `:root` against the document unless the syntax starts with `<url>`.
+
+When relative URLs are unavoidable, such as stylesheets in different directories, register the token with a syntax that starts with `<url>` and declare the actual URL on `:root`. This resolves against the declaring stylesheet in every browser:
+
+```css
+@property --icon-caret {
+  /* The syntax must start with <url>. A syntax that starts with <image> resolves against the document in Chrome. */
+  syntax: "<url> | <image> | none";
+  inherits: true;
+  initial-value: none;
+}
+
+:root {
+  /* Declared here, the URL resolves against this stylesheet */
+  --icon-caret: url("icons/caret.svg");
+}
+```
+
+Each icon now lives in two places, and there is much more boilerplate, so this is only worth it when a project has stylesheets in different directories and a manageable number of icons. Past a dozen or so icons, register the `--icon-*` tokens (excluding `--icon-style-*`) from a script with `CSS.registerProperty`, using the same syntax, instead of writing each `@property` by hand. Registered properties are global and do not work in shadow roots, so this may not fit every project. If root-relative URLs or data URIs are an option, they are simpler and work everywhere.
+
+```css
+:root {
+  /* Optional: override the built-in fallbacks (1em, currentColor, 0.3em, -0.02em) */
+  --icon-style-size: 1em;
+  --icon-style-spacing: 0.4em;
+  --icon-trash: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='currentColor' stroke-width='2'%3E%3Cpath d='M3 6h18M8 6V4a2 2 0 0 1 2-2h4a2 2 0 0 1 2 2v2m3 0-1 14a2 2 0 0 1-2 2H7a2 2 0 0 1-2-2L4 6h16Z'/%3E%3C/svg%3E");
+  --icon-favorite: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='currentColor'%3E%3Cpath d='M12 2l3.09 6.26L22 9.27l-5 4.87 1.18 6.88L12 17.77l-6.18 3.25L7 14.14 2 9.27l6.91-1.01L12 2z'/%3E%3C/svg%3E");
+}
+```
+
+### Rendering icons from tokens
+
+An element displays an icon by setting `--icon-start` (leading) or `--icon-end` (trailing) to one of the tokens above. Two pieces of CSS turn that assignment into a rendered icon.
+
+First, register `--icon-start` and `--icon-end` with `@property`. The `"*"` syntax accepts any value, and `inherits: false` is the important part: without it, an icon set on a button would inherit into every descendant, and each of them would render the icon too.
+
+```css
+@property --icon-start {
+  syntax: "*";
+  inherits: false;
+}
+
+@property --icon-end {
+  syntax: "*";
+  inherits: false;
+}
+```
+
+Second, a container style query detects when the property is set on an element and renders the icon in a pseudo-element. Because the pseudo-element does not inherit `--icon-start` (it was registered as non-inheriting), the first declaration forwards the value explicitly with `inherit`. The remaining declarations handle sizing, masking, alignment and spacing. Because the fill defaults to `currentColor`, the icon adopts the element's text color and follows its transitions.
+
+```css
+/* Style query for elements configuring a start icon */
+@container style(--icon-start) {
+  ::before {
+    --icon-start: inherit; /* Forward the value inside the query block */
+    content: "" / var(--icon-style-alt, "");
+    display: inline-block;
+    width: var(--icon-style-size, 1em);
+    height: var(--icon-style-size, 1em);
+    background-color: var(--icon-style-color, currentColor);
+    mask: var(--icon-start) no-repeat center / contain;
+    /* Center on the cap height, nudged slightly up for optical balance */
+    vertical-align: calc(0.5cap - var(--icon-style-size, 1em) / 2 + var(--icon-style-voffset, -0.02em));
+    flex: none;
+    pointer-events: none;
+    forced-color-adjust: none;
+  }
+
+  /* Automatically add spacing ONLY if the element has other text or sibling content */
+  :where(:not(.icon, :empty))::before {
+    margin-inline-end: var(--icon-style-spacing, 0.3em);
+  }
+}
+```
+
+Each declaration earns its place:
+
+* **`vertical-align`**: `middle` aligns to half the x-height, which sits visibly low for most icon sets. Centering on `0.5cap` keeps the icon's center fixed as `--icon-style-size` grows, and the small negative `--icon-style-voffset` compensates for the eye weighting the space above an icon more than the space below.
+* **`flex: none`**: An empty pseudo-element has a zero minimum size, so inside a flex button it is the first thing to shrink when the label is long, potentially to nothing. Icon size is a design decision, not something layout pressure should negotiate.
+* **`pointer-events: none`**: Keeps the icon from trapping clicks or becoming the `event.target`.
+* **`forced-color-adjust: none`**: In forced-colors mode the browser otherwise replaces `background-color`, making a masked icon disappear. The mask fill is preserved, and `currentColor` still follows the forced text color.
+* **`content: "" / var(--icon-style-alt, "")`**: Alternative text for generated content lets an icon-only control take its accessible name from the icon via `--icon-style-alt` (see Icon-Only Controls below). The default empty alt keeps decorative icons hidden from assistive technology.
+
+For a trailing icon, follow the same pattern with `--icon-end` and `::after` instead of `--icon-start` and `::before`. Use `mask: var(--icon-end)` and apply spacing with `margin-inline-start` instead of `margin-inline-end`.
+
+### Standalone and icon-only elements
+
+For standalone icons or icon-only buttons, apply `.icon` directly to the empty element (the button itself for an icon-only control) and set its icon with `--icon`. Here, `--icon` is the higher-level property; the `.icon:empty` rule maps it to `--icon-start` for a leading icon:
+
+```css
+.icon:empty {
+  --icon-start: var(--icon);
+}
+```
+
+## Usage Examples
+
+### Component defaults in the stylesheet
+
+The main benefit of icons as custom properties is that they participate in the cascade. Set an icon on a selector and every matching element gets it, with no markup changes:
+
+```css
+.button-delete {
+  --icon-start: var(--icon-trash);
+}
+
+a[href^="http"]:not([href*="example.com"]) {
+  --icon-end: var(--icon-external);
+}
+```
+
+```html
+<button class="button-delete">Delete item</button>
+```
+
+### Changing icons with state
+
+Because the icon is just a property, a state change is an ordinary CSS override. There is no second element to show or hide and no class to toggle:
+
+```css
+.button-expand {
+  --icon-start: var(--icon-caret-right);
+}
+
+.button-expand[aria-expanded="true"] {
+  --icon-start: var(--icon-caret-down);
+}
+```
+
+The same applies to presentation: set `--icon-style-size`, `--icon-style-color` or `--icon-style-spacing` on a container such as a toolbar and every icon inside it updates.
+
+### One-off icons with inline styles
+
+An element that no component rule covers can set the same property inline, for example `<button style="--icon-start: var(--icon-trash)">`. Treat this as the escape hatch rather than the default: once the same icon appears on the same kind of element more than once, move it into a stylesheet rule.
+
+### Icon-Only Controls
+
+Icon-only buttons use the `.icon` class and `--icon` described above. Give the button an accessible name with `aria-label`, or let the icon supply one through `--icon-style-alt`; without either, the CSS-generated icon is decorative. For standalone informative icons, expose the `.icon` element with `role="img"` and `aria-label`:
+
+```css
+.button-close {
+  --icon: var(--icon-close);
+  --icon-style-alt: "Close";
+}
+```
+
+```html
+<!-- Icon-only interactive control, icon and name from the stylesheet -->
+<button class="icon button-close"></button>
+
+<!-- Icon-only interactive control, named via aria-label -->
+<button class="icon" style="--icon: var(--icon-trash);" aria-label="Delete item"></button>
+
+<!-- Standalone informative icon -->
+<span class="icon" style="--icon: var(--icon-favorite);" role="img" aria-label="Favorite"></span>
+```
+
+## Working with SVG directly
+
+When the CSS icon system is not the right fit, use inline SVG and `<use>` together rather than as alternatives. Inline the SVG the first time an icon appears on a page and reference it with `<use href="#id">` for every repeat; the local reference costs no request and has no cross-origin restriction. Reserve an external sprite (`<use href="/icons.svg#id">`) for icons shared across many pages.
+
+With `<use>`, the referenced content is cloned into a shadow tree, so page CSS cannot select its elements. What does reach it is inheritance: `color`, `currentColor`, and any custom property. Beyond SVG presentation attributes, modern CSS can change many geometry attributes as well, so an icon you control can expose exactly the hooks you need, for example `stroke-width="var(--icon-stroke, 2)"` or even `d: var(--icon-path, path(…))` on a particular path.
+
+Browser support for the css.properties.d capability: Limited availability.
+Supported by: Chrome 52 (Jul 2016), Edge 79 (Jan 2020), and Firefox 97 (Feb 2022).
+Unsupported in: Safari.
+
+CSS `d` is not supported in Safari, so use this customization only when that support gap is acceptable. If you do not control the icon, inline it.
+
+`<use>` gotchas worth knowing:
+
+* The `viewBox` must be on the `<symbol>` or referenced `<svg>`; the outer `<svg>` wrapping `<use>` does not pick it up from the reference, so set `width` and `height` on the wrapper and keep the `viewBox` with the symbol.
+* Styles do not cross the boundary in either direction: `<style>` inside an external sprite does not apply to the page, and page stylesheets do not apply inside the referenced tree. Only inherited properties and custom properties pass through.
+* External references are same-origin only; cross-origin sprites fail silently.
+* Sprites inlined into the document share the page's `id` namespace, so namespace symbol ids to avoid collisions.
+
+Mark decorative SVGs with `aria-hidden="true"` and give the containing control its own accessible name, as with the CSS icon system.
+
+## Fallback Strategies
+
+### Registered Custom Properties
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+Without `@property`, `--icon-start` and `--icon-end` behave as ordinary inheriting custom properties, so an icon set on an element would also render on its descendants. Prevent this by resetting the properties on children inside the style query (`@container style(--icon-start) { * { --icon-start: initial; } }`), the same approach the Safari workaround below uses.
+
+### Container Style Queries
+
+Baseline status for Container style queries: Newly available. It's been Baseline since 2026-05-19.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 151 (May 2026), and Safari 18 (Sep 2024).
+
+To support browsers without Container Style Queries, use classes or component selectors as fallback hooks. Keep icon selection in custom properties; inline-style selectors alone miss icons assigned through CSS rules.
+
+```css
+:where(.icon-start, .icon:empty)::before {
+  content: image-set(linear-gradient(transparent 0 100%), var(--icon-start)) / var(--icon-style-alt, "");
+  /* icon styles */
+}
+
+:where(.icon-start)::before {
+  --icon-start: inherit;
+}
+
+:where(.icon:empty)::before {
+  --icon-start: var(--icon);
+}
+
+:where(.icon-start:not(.icon, :empty))::before {
+  margin-inline-end: var(--icon-style-spacing, 0.3em);
+}
+```
+
+For trailing icons, use the same class-hook fallback with `.icon-end`, `--icon-end`, and `::after` instead of `.icon-start`, `--icon-start`, and `::before`. Apply spacing to non-empty content with `margin-inline-start` instead of `margin-inline-end`.
+
+This `image-set()` pattern makes `content` invalid when the custom property is unset, so it falls back to `none` and the pseudo-element disappears without adding or removing a class. It does not remove the pseudo-element's other styles or prevent conflicts with other `::before` or `::after` rules, so use these hooks only where those pseudo-elements are available for icons.
+
+### Safari Browser Workarounds
+
+Safari has two rendering bugs affecting icons: WebKit [#301609](https://bugs.webkit.org/show_bug.cgi?id=301609) can prevent them from appearing until user interaction, and [#320220](https://bugs.webkit.org/show_bug.cgi?id=320220) also affects their rendering. The workaround below addresses both:
+
+```css
+@keyframes webkit-301609 {}
+
+@supports ((-webkit-nbsp-mode: normal) or (-webkit-touch-callout: none) or (font: -apple-system-body)) and (content-visibility: auto) {
+  @layer webkit-301609-fix {
+    ::before, ::after {
+      animation: webkit-301609 0s;
+    }
+  }
+}
+```
+
+The `@supports` query targets Safari only, and `@layer` reduces animation conflicts.
+
+WebKit bug #325900 can prevent a direct override of `--icon-start` from taking effect in some cases, such as changing the icon on hover. This affects the workaround for non-inheriting registered properties. For Safari, register `--icon-start` as inheriting and reset it on descendants inside the style query:
+
+```css
+@supports ((-webkit-nbsp-mode: normal) or
+           (-webkit-touch-callout: none) or
+           (font: -apple-system-body)) and (content-visibility: auto) {
+  /* Override previous declaration */
+  @property --icon-start {
+    syntax: "*";
+    inherits: true;
+  }
+
+  @layer webkit-325900-fix {
+    @container style(--icon-start) {
+      * {
+        --icon-start: initial;
+      }
+    }
+  }
+}
+```
+
+The reset prevents the icon value from propagating to descendants. Keeping it in a layer lets unlayered icon declarations take precedence over the reset.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/position-aware-tooltips.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/position-aware-tooltips.md
new file mode 100644
index 00000000..0bcf055f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/position-aware-tooltips.md
@@ -0,0 +1,158 @@
+# Position Aware Tooltips
+
+When building tooltips or popovers with CSS Anchor Positioning, the browser can automatically "flip" the element to a fallback position if it would otherwise overflow the viewport. When this happens, you may want to adjust the style of the positioned content, for instance to reposition an arrow that points from the positioned content to the anchor.
+
+**Anchored Container Queries** solve this by allowing you to query the active positioning state of an element and apply styles accordingly. For general anchored dropdown and flyout positioning with viewport collision flipping (without directional arrow restyling), see `viewport-aware-dropdowns` (via `npx -y modern-web-guidance@latest retrieve "viewport-aware-dropdowns"`).
+
+## The problem
+
+Imagine a tooltip that appears above its anchor by default. It has a "down" arrow at the bottom. If the user scrolls and the tooltip flips to appear *below* the anchor, the arrow is now pointing the wrong way and is on the wrong side of the tooltip.
+
+## The solution: Anchored Container Queries
+
+By setting `container-type: anchored` on your positioned element, you turn it into a query container that knows about its own anchor-positioned state. You can then use the `@container anchored()` query to update its descendants or pseudo-elements.
+
+### 1. Create the tooltip and trigger
+
+Use the Popover API to create a tooltip. Invoking the popover via `popovertarget` automatically establishes an **implicit anchor connection** with the trigger button, so no explicit `anchor-name` or `position-anchor` is required.
+
+```html
+<button popovertarget="tooltip" id="anchor" aria-describedby="tooltip">anchor</button>
+<div id="tooltip" popover role="tooltip"></div>
+```
+
+Reset the popover inset and margin styles for use with anchor positioning, but only if anchor positioning is supported.
+
+```css
+@supports (anchor-name: --my-anchor) {
+  [popover] {
+    inset: auto;
+    margin: unset;
+  }
+}
+```
+
+### 2. Set up the container
+
+Apply `container-type: anchored` to the element being positioned. This element must also have `position-try-fallbacks` defined to enable the flipping behavior.
+
+```css
+#tooltip {
+  position: fixed;
+  position-area: block-start;
+  position-try-fallbacks: flip-block;
+
+  /* Enable anchored container queries */
+  container-type: anchored;
+}
+```
+
+### 3. Style based on the fallback
+
+Use `@container anchored(fallback: <value>)` to apply styles when a specific fallback is active.
+
+Like all container queries, `@container` can only style **descendants** of the container. A common strategy to create the arrows is with the `::before` and `::after` pseudo-elements, which are treated as descendants and can be styled directly. However, to style the tooltip itself (as seen in step 4), we will add a child element to the tooltip, and create the arrow in its `::before` pseudo-element.
+
+```html
+<div id="tooltip" popover role="tooltip">
+  <div class="tooltip-content">Tooltip</div>
+</div>
+```
+
+```css
+.tooltip-content::before {
+  /* Default "down" arrow for the 'top' position */
+  content: "▼";
+  position: absolute;
+  inset-block-end: 0;
+  inset-inline-start: 1rem;
+}
+
+/* Update to an "up" arrow when the 'flip-block' fallback (bottom) is active */
+@container anchored(fallback: flip-block) {
+  .tooltip-content::before {
+    content: "▲";
+    inset-block-start: 0;
+    inset-block-end: auto;
+  }
+}
+```
+
+## 4. Styling the container itself
+
+If you need to change properties on the container itself (like `margin` or `background-color`) when it flips, you should use an **inner wrapper element**.
+
+1. Apply `container-type: anchored` to the outer positioned element.
+2. Target the inner element inside the `@container` block.
+
+
+```css
+@container anchored(fallback: flip-block) {
+  .tooltip-content {
+    border-radius: 0 0 .5rem .5rem;
+    margin-block-start: 0.25rem;
+  }
+}
+```
+
+## Best practices
+
+- **Prefer logical fallbacks**: Use keywords like `flip-block` and `flip-inline` in `position-try-fallbacks` for simpler queries that handle RTL and different writing modes automatically.
+- **Use pseudo-elements for arrows**: Tooltip arrows are purely decorative and are perfect candidates for `::before` or `::after`, which can be styled via anchored container queries without extra DOM.
+
+
+## Fallback strategies
+
+Browser support for Anchor position container queries: Limited availability.
+Supported by: Chrome 143 (Dec 2025) and Edge 143 (Dec 2025).
+Unsupported in: Firefox and Safari.
+
+Positioning the arrow based on the applied fallback is a progressive enhancement, and there is not another way of reacting to the fallback position. To hide the arrow in browsers that don't support anchor position container queries, test for CSS support with `@supports (container-type: anchored)`.
+
+```css
+@supports (container-type: anchored) {
+  .tooltip-content::before {
+    content: "▼";
+  }
+}
+```
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+Browsers without support for the Popover API also do not support anchor positioning, so the tooltip will appear in the center of the screen.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/pull-to-reveal.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/pull-to-reveal.md
new file mode 100644
index 00000000..da150218
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/pull-to-reveal.md
@@ -0,0 +1,83 @@
+# Pull to Reveal
+
+"Pull to reveal" is a UI pattern where content (such as a search bar or refresh control) is hidden above the top of a scrollable area on initial load, and the user can pull down (scroll up) to reveal it. This pattern is commonly used in mobile apps and web apps for search bars, filters, and other secondary controls that should be accessible but not immediately visible.
+
+The CSS property `scroll-initial-target` offers a declarative, CSS-only way to implement this pattern. By setting `scroll-initial-target: nearest` on the main content element, the scroll container will render with the hidden content scrolled out of view. Previously, developers relied on JavaScript (`Element.scrollIntoView()`) or URL fragment identifiers (`#content-id`) to achieve this, both of which have limitations and are tricky to implement.
+
+## How to Implement
+
+To implement a pull-to-reveal pattern:
+
+1. **Ensure a scroll container:** The target element must be inside a scroll container (an element with overflow that allows scrolling, such as `overflow: auto`). This can be any ancestor element, including the root `<html>` element.
+2. **Define the hidden element:** Place the content you want to hide (e.g., a search bar) as the first descendant inside the scroll container. This element will be scrolled out of view on initial load.
+3. **Define the main content:** Place the main content element immediately after the hidden element. This is the element the user should see first.
+4. **Target the main content:** Apply `scroll-initial-target: nearest` to the main content element so the scroll container renders with it scrolled into view, hiding the element above it.
+5. **Add scroll snapping:** To ensure the hidden element is always either fully visible or fully hidden (and doesn't rest in a partially-scrolled state), add `scroll-snap-type: y mandatory` to the scroll container and `scroll-snap-align: start` to both the hidden element and the main content element.
+
+## Example Code: Pull to Reveal Search
+
+```css
+/**
+ * ANCESTOR: Define the scroll container.
+ * Scroll snapping ensures the search bar is always
+ * either fully visible or fully hidden.
+ */
+.scroll-container {
+  height: 100vh;
+  overflow-y: auto;
+  scroll-snap-type: y mandatory;
+}
+
+/**
+ * HIDDEN ELEMENT: The search bar hidden above the fold on load.
+ * It has scroll-snap-align so it snaps into place when pulled down.
+ */
+.search-bar {
+  height: 60px;
+  scroll-snap-align: start;
+}
+
+/**
+ * MAIN CONTENT + TARGET: The element the user sees first.
+ * scroll-snap-align makes it a valid snap point.
+ * scroll-initial-target tells the browser to scroll here on
+ * initial render, hiding the search bar above it.
+ */
+.main-content {
+  scroll-snap-align: start;
+  scroll-initial-target: nearest;
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `scroll-initial-target: nearest` when you want to draw the user's attention to a specific part of a scrollable area upon load and intentionally hide peripheral UI units like a search bar at the very top.
+- **DO NOT** confuse this with accessibility focus. This property only moves the **visual** viewport; it does not move the keyboard focus. You must manually manage `element.focus()` if the target is intended to be the starting point for keyboard users.
+- **DO NOT** use this if you need a smooth "scrolling" animation on load; this property is discrete and sets the position instantly during the layout phase.
+- **DO NOT** set `scroll-initial-target` on multiple elements within the same scrollable container. If multiple elements specify `scroll-initial-target: nearest`, the browser selects the one that appears first in the DOM tree order.
+- **DO** account for the **Precedence Hierarchy**: A URL fragment (e.g., `example.com/#top`) and the container-level `scroll-start` property both take precedence over `scroll-initial-target`.
+
+## Fallback Strategy
+
+Browser support for scroll-initial-target: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not yet support the API, use a JavaScript fallback. Note that for pulling content to reveal, you want the main content to be bound to the `start` (top) of the container.
+
+```javascript
+/**
+ * Progressive Enhancement Fallback
+ */
+document.addEventListener("DOMContentLoaded", () => {
+  // Check for native CSS support
+  if (!CSS.supports("scroll-initial-target", "nearest")) {
+    const targetContent = document.querySelector('.main-content.target');
+    if (targetContent) {
+      // Use behavior: "instant" to mimic the native CSS behavior
+      // 'block: start' should match your CSS 'scroll-snap-align' (or expected top position)
+      targetContent.scrollIntoView({ behavior: 'instant', block: 'start' });
+    }
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/responsive-table.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/responsive-table.md
new file mode 100644
index 00000000..33929654
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/responsive-table.md
@@ -0,0 +1,121 @@
+# Responsive tables
+
+Large data tables often become unreadable on small screens as columns overflow or shrink beyond legibility. This guide demonstrates how to use **sticky positioning** to keep headers visible during scrolling and how to transform the table into a mobile-friendly "stacked" layout when space is limited.
+
+## Recommended Approach
+
+The core of a responsive table is maintaining the relationship between data cells and their headers.
+
+1.  **Semantic Foundation**: Use standard `<table>` elements with `<thead>`, `<tbody>`, and `<th>` elements.
+2.  **Sticky Context**: Apply `position: sticky` to both column headers and row headers. This ensures that no matter how far a user scrolls in any direction, they never lose the context of what the data represents.
+3.  **Adaptive Transformations**: Use `@container` queries instead of `@media` queries. This allows the table to adapt based on its own width (e.g., when placed in a sidebar or a narrow dashboard widget) rather than the entire viewport.
+4.  **Label Injection**: In the stacked layout, the `<thead>` is hidden, and accessible headers are injected into each cell using `::before` pseudo-elements and CSS variables.
+
+## Implementation Steps
+
+### 1. Markup and Layout
+
+Structure your table with standard semantic headers. Use a `.table-wrapper` to handle overflow and provide a container for queries. Add a `tabindex="0"` attribute to the container, to ensure that people using only a keyboard can consistently scroll the table.
+
+Give the wrapper a `role="region"` attribute to communicate its purpose. Provide it with an accessible name using `aria-labelledby` (referencing the `id` attribute of an existing element that captions/names the table) or an `aria-label` attribute.
+
+```html
+<div tabindex="0" role="region" aria-labelledby="employee-table-caption" class="table-wrapper">
+  <table>
+    <caption id="employee-table-caption">Current employee directory</caption>
+    <thead>
+      <tr>
+        <th>Employee</th>
+        <th>Role</th>
+        <th>Status</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <!-- Row header remains sticky horizontally on desktop, 
+             and becomes a sticky card header on mobile -->
+        <th>Alex Rivera</th>
+        <td>Engineer</td>
+        <td>Active</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+```
+
+### 2. Configure Sticky Headers
+Enable scrolling and make headers sticky. Use logical properties and explicit z-index values to manage the stacking order.
+
+```css
+.table-wrapper {
+  overflow: auto;
+  max-inline-size: 100%;
+  max-block-size: min(500px, 80vh);
+  container-type: inline-size;
+}
+
+table {
+  border-collapse: separate;
+  border-spacing: 0;
+}
+
+/* Sticky column headers (desktop) */
+thead {
+  position: sticky;
+  inset-block-start: 0;
+  z-index: 1; /* Above sticky row headers */
+}
+
+/* Sticky row headers (desktop) */
+tbody th {
+  position: sticky;
+  inset-inline-start: 0;
+  background: white; /* Required to cover background during scroll */
+}
+```
+
+### 3. Responsive Stacked Layout
+When space is limited, hide the original header row and transform the table into cards. Inject labels using pseudo-elements. Only provide alternative text for non-text content, otherwise this may result in both the text content and accessible name being announced by screen readers.
+
+```css
+@container (width < 600px) {
+  table, thead, tbody, tr, th, td {
+    display: block;
+  }
+
+  thead {
+    /* MANDATORY: Hide column header from layout and screen readers. */
+    display: none
+  }
+
+  tr {
+    margin-block-end: 1.5rem;
+    border: 1px solid #ccc;
+  }
+
+  /* Sticky row headers at the top of each block/card */
+  tbody th {
+    position: sticky;
+    inset-block-start: 0;
+    z-index: 2;
+    background: #eee;
+  }
+
+  /* Define column labels as CSS variables (often set via JS) */
+  table {
+    --label-1: "Employee";
+    --label-2: "Role";
+    --label-3: "Status";
+  }
+
+  /* Inject labels */
+  td:nth-child(2)::before {
+    /* MANDATORY: If using non-text content, provide the accessible name (after the /) which ensures screen readers hear the text alternative. */
+    content: var(--label-2) ": ";
+  }
+  /* MANDATORY: Map the label for each column */
+  td:nth-child(3)::before {
+    content: var(--label-3) ": ";
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-position-aware-elements.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-position-aware-elements.md
new file mode 100644
index 00000000..44b9dbb9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-position-aware-elements.md
@@ -0,0 +1,130 @@
+# Scroll Position Aware Elements
+
+## Overview
+
+Improve the user experience of floating buttons, like a "Back to Top" link, by showing them only when they are useful. This guide shows how to build these elements using CSS `container-scroll-state-queries`, which allows styling elements based on the scroll position of their container without relying on JavaScript scroll listeners or observers.
+
+## Implementation
+
+### 1. Establish the Scroll Container
+
+The scroll container must be declared as a scroll-state query container.
+
+```css
+.scroller {
+  overflow-y: auto;
+  /* Establish this element as a scroll-state query container */
+  container-type: scroll-state;
+}
+```
+
+### 2. Style the Floating Element
+
+Place the element inside the container and style it. By default, it should be hidden.
+
+```css
+.back-to-top {
+  position: sticky;
+  bottom: 20px;
+  visibility: hidden;
+  opacity: 0;
+  translate: 0 20px;
+  transition:
+    visibility 0.3s,
+    opacity 0.3s ease,
+    translate 0.3s ease;
+}
+```
+
+> **Important:** Sticky or floating elements hover above the scrollable content. Ensure that the main content has sufficient bottom padding or margin so that the last few elements are not permanently covered by the button when the user scrolls completely to the bottom.
+
+### 3. Respond to the Scroll State
+
+Use the `@container` rule with the `scroll-state` function. To check if the user has scrolled down, check if the container is scrollable to the top.
+
+```css
+/* When the container can be scrolled toward the top, it means the user has scrolled down */
+@container scroll-state(scrollable: top) {
+  .back-to-top {
+    visibility: visible;
+    opacity: 1;
+    translate: 0 0;
+  }
+}
+```
+
+## Fallback strategies
+
+Browser support for Container scroll-state queries: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+### Basic Fallback
+If `container-scroll-state-queries` is not supported, the floating element will remain invisible because of the default `visibility: hidden`. To ensure functionality, you can choose to make the element always visible in unsupported browsers.
+
+```css
+/* Fallback for browsers that do not support the feature */
+.back-to-top {
+  visibility: visible; /* Always visible */
+  opacity: 1;
+}
+
+/* Override for supported browsers to handle dynamic visibility */
+@supports (container-type: scroll-state) {
+  .back-to-top {
+    visibility: hidden;
+    opacity: 0;
+  }
+  
+  @container scroll-state(scrollable: top) {
+    .back-to-top {
+      visibility: visible;
+      opacity: 1;
+      translate: 0 0;
+    }
+  }
+}
+```
+
+### Advanced Fallback (Intersection Observer)
+If dynamic visibility is required, use an `IntersectionObserver` to toggle a class when a sentinel element at the top of the scroller goes out of view.
+
+```html
+<!-- Sentinel element placed at the top of the scroller -->
+<div class="scroll-sentinel"></div>
+```
+
+```css
+/* Marker styling to ensure it does not affect layout */
+.scroll-sentinel {
+  height: 0;
+  width: 0;
+  visibility: hidden;
+}
+
+.scrolled .back-to-top {
+  visibility: visible;
+  opacity: 1;
+  translate: 0 0;
+}
+```
+
+```javascript
+if (!CSS.supports('container-type', 'scroll-state')) {
+  const sentinel = document.querySelector('.scroll-sentinel');
+  const scroller = document.querySelector('.scroller');
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      // If the sentinel is NOT intersecting, it means the user has scrolled down
+      if (!entry.isIntersecting) {
+        scroller.classList.add('scrolled');
+      } else {
+        scroller.classList.remove('scrolled');
+      }
+    });
+  }, { root: scroller });
+
+  observer.observe(sentinel);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-progress-indicator.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-progress-indicator.md
new file mode 100644
index 00000000..f88a0a59
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scroll-progress-indicator.md
@@ -0,0 +1,133 @@
+# Build a Scroll Progress Indicator
+
+A scroll progress indicator is a common user interface pattern that visually communicates the user's progress through a scrollable document or container. As the user scrolls, a visual element updates to reflect their position, providing a clear and intuitive sense of how much content has been viewed and how much remains.
+
+## How to implement
+
+To create a scroll progress indicator, you need two things:
+
+1.  An element to act as the progress bar. This element is typically `position: fixed` or `position: absolute` so that it stays in view while the user scrolls.
+2.  An animation that is linked to the scroll position.
+
+Here’s how you can achieve this:
+
+-   First, create an HTML element that will serve as your progress bar. This element can be styled to your liking.
+-   Next, in your CSS, define a `@keyframes` animation that scales the progress bar. A common approach is to scale the element from `scaleX(0)` to `scaleX(1)`.
+-   Finally, apply this animation to your progress bar element and set its `animation-timeline` to a scroll-timeline. This tells the browser to drive the animation's progress based on the scroll position of the nearest ancestor scroller.
+
+## Example code
+
+This code grows the `#progress` element on scroll using an anonymous scroll-timeline, created by the `scroll()` function.
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @supports ((animation-timeline: scroll())) {
+    @keyframes grow-progress {
+      from { transform: scaleX(0); }
+      to { transform: scaleX(1); }
+    }
+
+    #progress {
+      position: fixed;
+      left: 0; top: 0;
+      width: 100%; height: 1em;
+      background: red;
+
+      transform-origin: 0 50%;
+      animation: grow-progress auto linear;
+      animation-timeline: scroll();
+    }
+  }
+}
+```
+
+Because of its location in the DOM, the `scroll()` function will track its nearest ancestor scroller in the `block` direction, which here is the root scroller.
+
+```html
+<body>
+  <!-- MANDATORY: Purely decorative visual scroll progress bars MUST set aria-hidden="true" to remove the empty element from the assistive technology reading tree -->
+  <div id="progress" aria-hidden="true"></div>
+</body>
+```
+
+This code grows the `#progress` element on scroll using a named scroll-timeline, created by the `scroll-timeline` property.
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @supports ((animation-timeline: scroll())) {
+    @keyframes grow-progress {
+      from { transform: scaleX(0); }
+      to { transform: scaleX(1); }
+    }
+
+    :root {
+      scroll-timeline: --tl block;
+    }
+
+    #progress {
+      position: fixed;
+      left: 0; top: 0;
+      width: 100%; height: 1em;
+      background: red;
+
+      transform-origin: 0 50%;
+      animation: grow-progress auto linear;
+      animation-timeline: --tl;
+    }
+  }
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports (animation-timeline: scroll())` to check for support and provide a fallback for browsers that don't support it.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** remove purely decorative elements from assistive technology reading flows: Apply `aria-hidden="true"` to purely visual scroll indicators to ensure screen readers do not encounter empty, unnamed nodes.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` *after* it to prevent the shorthand from resetting the timeline.
+
+When using the `scroll()` function to create a scroll-driven animation:
+
+- **OPTIONAL** be explicit about the scroller: When not targeting the nearest ancestor scroller, be explicit about which scroller you want to use with `scroll(root)` or `scroll(self)`.
+  - When `root`, `nearest`, or `self` are not sufficient, use a named scroll-timeline.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `scroll(block)` or `scroll(inline)`.
+
+When using the `scroll-timeline` property to create a scroll-driven animation:
+
+- **DO** use a CSS `<dashed-ident>` for the name.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `scroll-timeline-axis`.
+- **DO** make sure the scope of the lookup works: When the element that is declaring the `scroll-timeline` is not a flat tree ancestor of the animated element, hoist up the visibility of the `scroll-timeline`’s name by using `timeline-scope` on a shared ancestor.
+
+## Fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses a scroll listener to track the scroll position of the root element and updates the `transform` property of the progress bar accordingly.
+
+```html
+<script>
+  if (!CSS.supports('animation-timeline', 'scroll()')) {
+    const progress = document.querySelector('#progress');
+
+    window.addEventListener('scroll', () => {
+      const scrollable = document.documentElement.scrollHeight - window.innerHeight;
+      const scrolled = window.scrollY;
+      const progressPercentage = (scrolled / scrollable);
+
+      progress.style.transform = `scaleX(${progressPercentage})`;
+    });
+  }
+</script>
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scrollability-affordance-hints.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scrollability-affordance-hints.md
new file mode 100644
index 00000000..e125c736
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/scrollability-affordance-hints.md
@@ -0,0 +1,126 @@
+# Scrollability Affordance Hints
+
+## Overview
+
+Visual hints, like shadows or gradients, help users understand that they can scroll to see more content. This guide shows how to build these hints using CSS `container-scroll-state-queries`, which allows styling elements based on the scrollable state of their container without relying on JavaScript scroll listeners or observers.
+
+## Implementation
+
+### 1. Establish the Scroll Container
+
+The scroll container must be declared as a scroll-state query container.
+
+```css
+.scroller {
+  overflow-y: auto;
+  /* Establish this element as a scroll-state query container */
+  container-type: scroll-state;
+  position: relative;
+}
+```
+
+### 2. Style the Indicators
+
+Place the indicator elements (like shadows, gradients, or arrows) inside the container and style them. By default, they should not be visible. When they are shown, they should not be interactive, by setting `pointer-events: none`.
+
+```css
+.indicator-top, .indicator-bottom {
+  position: sticky;
+  left: 0;
+  right: 0;
+  height: 20px;
+  opacity: 0;
+  transition: opacity 0.2s;
+  pointer-events: none; /* Let clicks pass through */
+}
+
+.indicator-top {
+  top: 0;
+  background: linear-gradient(to bottom, rgba(0,0,0,0.2), transparent); /* Example: Shadow */
+}
+
+.indicator-bottom {
+  bottom: 0;
+  background: linear-gradient(to top, rgba(0,0,0,0.2), transparent); /* Example: Shadow */
+}
+```
+
+### 3. Query the Scroll State
+
+Use the `@container` rule with the `scroll-state` function. Check if the container is scrollable up or down to show the respective indicator.
+
+```css
+/* Show top indicator when the user can scroll up */
+@container scroll-state(scrollable: top) {
+  .indicator-top {
+    opacity: 1;
+  }
+}
+
+/* Show bottom indicator when the user can scroll down */
+@container scroll-state(scrollable: bottom) {
+  .indicator-bottom {
+    opacity: 1;
+  }
+}
+```
+
+## Fallback strategies
+
+Browser support for Container scroll-state queries: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+### Basic Fallback
+If the feature is not supported, the indicators will remain invisible. Since these are hints and not critical for functionality, it is acceptable to omit them in unsupported browsers.
+
+### Advanced Fallback (Intersection Observer)
+If the hints are required, use an `IntersectionObserver` to toggle classes when sentinel elements at the top and bottom of the scroller move in and out of the scrollport.
+
+```html
+<!-- Sentinel elements placed at the ends of the scroller -->
+<div class="sentinel-top"></div>
+<!-- Content goes here -->
+<div class="sentinel-bottom"></div>
+```
+
+```css
+/* Marker styling to ensure it does not affect layout */
+.sentinel-top, .sentinel-bottom {
+  height: 0;
+  width: 0;
+  visibility: hidden;
+}
+
+.scroller.scrolled-down .indicator-top {
+  opacity: 1;
+}
+
+.scroller.can-scroll-down .indicator-bottom {
+  opacity: 1;
+}
+```
+
+```javascript
+if (!CSS.supports('container-type', 'scroll-state')) {
+  const topSentinel = document.querySelector('.sentinel-top');
+  const bottomSentinel = document.querySelector('.sentinel-bottom');
+  const scroller = document.querySelector('.scroller');
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.target === topSentinel) {
+        // If top sentinel is not intersecting, we have scrolled down
+        scroller.classList.toggle('scrolled-down', !entry.isIntersecting);
+      }
+      if (entry.target === bottomSentinel) {
+        // If bottom sentinel is intersecting, we reached the bottom
+        scroller.classList.toggle('can-scroll-down', !entry.isIntersecting);
+      }
+    });
+  }, { root: scroller });
+
+  observer.observe(topSentinel);
+  observer.observe(bottomSentinel);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/shrinking-header-on-scroll.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/shrinking-header-on-scroll.md
new file mode 100644
index 00000000..b9754945
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/shrinking-header-on-scroll.md
@@ -0,0 +1,126 @@
+# Shrinking header on scroll
+
+A shrinking header on scroll is a common UI pattern where a fixed header element at the top of the page smoothly transitions to a smaller size as the user scrolls down. This effect is often used to maximize screen real estate for the main content while keeping essential navigation or branding elements accessible. With CSS scroll-driven animations, this effect can be achieved in a declarative and performant way, by linking an animation to the scroll position of the document.
+
+## How to implement
+
+Here’s how to create a shrinking header on scroll:
+
+1.  **Create a fixed header:** Start with a header element that is fixed to the top of the page and has a predefined height.
+
+    ```html
+    <header>HEADER</header>
+    ```
+
+    ```css
+    header {
+      position: fixed;
+      height: 200px;
+      top: 0;
+      left: 0;
+      right: 0;
+    }
+    ```
+
+2.  **Define the shrink animation:** Create a CSS animation that changes the height of the header.
+
+    ```css
+    @keyframes shrink {
+      to {
+        height: 50px;
+      }
+    }
+    ```
+
+3.  **Apply the animation and scroll timeline:** Attach the animation to the header and use the `scroll()` function to link it to the document’s scroll position.
+
+    ```css
+    header {
+      animation: shrink auto linear both;
+      animation-timeline: scroll(block root);
+    }
+    ```
+
+4.  **Set the `animation-range`:** Use the `animation-range` property to specify the scroll distance over which the animation should occur. For example, to shrink the header over the first 150 pixels of scrolling, you would use `animation-range: 0px 150px;`.
+
+    ```css
+    header {
+      animation-range: 0px 150px;
+    }
+    ```
+
+**Tip:** To prevent the content following the header from being obscured by it, add a `padding-top` to the `body` (or the main content container) that is equal to the initial height of the header.
+
+**Tip:** To make sure the contents of the page scroll in sync with the shrinking header, set the `animation-range-end` to the difference between the start and end sizes. This ensures the animation completes precisely when the header reaches its final size. In this demo the header shrinks from `200px` to `50px`, so the `animation-range-end` is set to `150px`.
+
+## Example code
+
+```css
+@keyframes shrink {
+  to {
+    height: 50px;
+  }
+}
+
+header {
+  animation: shrink auto linear both;
+  animation-timeline: scroll(block root);
+  animation-range: 0px 150px;
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: 0% 100%)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` and `animation-range` *after* it to prevent the shorthand from resetting the timeline.
+
+When using the `scroll()` function to create a scroll-driven animation:
+
+- **OPTIONAL** be explicit about the scroller: When not targeting the nearest ancestor scroller, be explicit about which scroller you want to use with `scroll(root)` or `scroll(self)`.
+  - When `root`, `nearest`, or `self` are not sufficient, use a named scroll-timeline.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `scroll(block)` or `scroll(inline)`.
+
+As for this use case specifically:
+
+- The element that you animate **MUST** not be `position: static` or `position: relative` when using percentages in the `animation-range`.
+  - This is because those elements are considered “in-flow”. Shrinking those elements as you scroll, would shrink the total scroll distance, thereby affecting the computed value of — for example — `10%` into the scroll.
+
+## Browser support and fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.. Therefore, a fallback strategy is typically required.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses a scroll listener to track the scroll position of the document over a distance of `150px` and updates the header's height accordingly.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: scroll()) and (animation-range: 0% 100%)')) {
+  const header = document.querySelector('header');
+
+  const initialHeight = 200;
+  const finalHeight = 50;
+  const scrollDistance = 150;
+
+  window.addEventListener('scroll', () => {
+    const scrollY = window.scrollY;
+    const scrollPercent = Math.min(1, scrollY / scrollDistance);
+    const newHeight = initialHeight - (initialHeight - finalHeight) * scrollPercent;
+
+    header.style.height = `${newHeight}px`;
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/state-aware-sticky-headers.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/state-aware-sticky-headers.md
new file mode 100644
index 00000000..438381ee
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/state-aware-sticky-headers.md
@@ -0,0 +1,139 @@
+# State-Aware Sticky Headers
+
+Sticky headers are a common UI pattern, but they often need to change their appearance when they become "stuck" to maintain readability or save space. Traditional solutions required JavaScript scroll listeners, which can cause performance issues. Modern CSS allows you to handle this natively using **Scroll State Queries**.
+
+## Implementation Steps
+
+### 1. Create the Sticky Container
+You need a container that will act as the sticky element and the container for the scroll state query.
+
+```html
+<!-- Wrap in a section to define the containment area for the sticky element -->
+<div class="section">
+  <div class="sticky-container">
+    <div class="sticky-header">
+      Section Header
+    </div>
+  </div>
+  <div class="content">
+    <!-- Content goes here -->
+  </div>
+</div>
+```
+
+### 2. Apply CSS for Sticky Behavior and Container Type
+Set `container-type: scroll-state` on the `position: sticky` element, not on its scrollable ancestor. Always specify a `container-name`, since these queries may be nested and unnamed containers will collide. You can also combine it with size queries, e.g., `container-type: scroll-state inline-size`.
+
+```css
+.sticky-container {
+  position: sticky;
+  top: 0;
+  /* MANDATORY: Always specify a container name to avoid collisions if CQs are nested */
+  container-type: scroll-state;
+  container-name: section-header;
+  z-index: 10;
+}
+
+.sticky-header {
+  /* Base styles for the header */
+  background: #f0f0f0;
+  padding: 20px;
+  transition: background-color 0.3s, box-shadow 0.3s;
+}
+```
+
+**Important:** The scroll state is queried by **descendants** of the scroll-state container. The styles in the `@container` query will not apply to the `.sticky-container` itself, but to its children (like `.sticky-header`). You cannot style the container element itself with its own scroll-state query.
+
+
+### 3. Target the Stuck State
+Use the `@container scroll-state(...)` query to apply styles when the header is stuck.
+
+```css
+/* Apply styles when the named container is stuck at the top */
+@container section-header scroll-state(stuck: top) {
+  .sticky-header {
+    background: #0056b3;
+    color: white;
+    box-shadow: 0 4px 6px rgb(0 0 0 / 0.15);
+  }
+}
+```
+
+**Tip:** You can also use logical properties like `stuck: inset-block-start` or `stuck: inset-inline-start` to better support internationalization (i18n) and right-to-left (RTL) layouts by querying flow-relative edges rather than physical ones.
+
+### Notes on Dimension Changes
+
+Without scroll anchoring disabled, changing layout-affecting properties (height, padding, font-size) when stuck can cause visual flickering. Scroll anchoring on the in-flow content below the sticky element adjusts the scroll offset to compensate for the layout change, which pushes the element back out of its stuck position and triggers an oscillation.
+
+Disable scroll anchoring on the parent of the sticky element to avoid this:
+
+```css
+.section {
+  overflow-anchor: none;
+}
+```
+
+Apply `overflow-anchor: none` to the direct parent of the `position: sticky` element, not to `:root` or `body`, which would disable scroll anchoring for the entire page. With this in place, you can freely change any property in the stuck state, including box-model properties and transforms.
+
+DO NOT: Rely on `overflow-anchor: none` for elements stuck to the **bottom**. Scroll anchoring only compensates for layout shifts above the current scroll position, so it has no effect on bottom-stuck elements. Avoid changing box-model properties in the stuck state for bottom-stuck headers.
+
+### Fallback strategies
+Browser support for Container scroll-state queries: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+Scroll state queries are a progressive enhancement. In browsers that do not support `container-type: scroll-state`, the header will still stick to the top (due to `position: sticky`), but it will not visually transform. For most use cases, this is the recommended approach.
+
+If stickiness is not essential, but `position: sticky` without different styling would be a worse experience than no stickiness at all, you can wrap the `position: sticky` and related declaration in an `@supports` query as well:
+
+```css
+.sticky-container {
+  @supports (container-type: scroll-state) {
+	  position: sticky;
+	  top: 0;
+	  container-type: scroll-state;
+	  container-name: section-header;
+	  z-index: 10;
+	}
+}
+```
+**Tip:** If your "stuck" styling requires a different background color for readability, consider setting your layout up so that the default styling works everywhere (Progressive Enhancement). If you must use a fallback, you can gate the `position: sticky` behaviour itself inside an `@supports (container-type: scroll-state)` query.
+
+If the visual transformation is absolutely critical to the design (e.g., the stuck state introduces a background or compaction without which the content is unreadable), you can implement a robust JavaScript fallback using `IntersectionObserver`. You must duplicate your CSS styles under an `.is-stuck` class. The following generic polyfill checks `getComputedStyle` to traverse up and find the correct scroll container (defaulting to the viewport), matching the behavior of `@container scroll-state(stuck: top)`:
+
+```javascript
+function getScrollParent(node) {
+  if (node == null || node === document.body || node === document.documentElement) {
+    return null; // default to viewport
+  }
+  if (node.scrollHeight > node.clientHeight || node.scrollWidth > node.clientWidth) {
+    const overflow = getComputedStyle(node).overflow;
+    if (overflow !== 'visible' && overflow !== 'clip') {
+      return node;
+    }
+  }
+  return getScrollParent(node.parentNode);
+}
+
+document.querySelectorAll('.sticky-container').forEach(container => {
+  const root = getScrollParent(container);
+  
+  const topOffset = parseFloat(getComputedStyle(container).top) || 0;
+  
+  const observer = new IntersectionObserver(
+    ([e]) => {
+      // Toggle the fallback class on the sticky header container
+      e.target.classList.toggle('is-stuck', e.intersectionRatio < 1);
+    },
+    { 
+      root: root,
+      threshold: [1],
+      rootMargin: `-${topOffset + 1}px 0px 0px 0px` 
+    }
+  );
+  
+  observer.observe(container);
+});
+```
+
+*Note: This generic IntersectionObserver pattern can also be used as a polyfill for the `scroll-state(scrollable)` query.*
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/viewport-aware-dropdowns.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/viewport-aware-dropdowns.md
new file mode 100644
index 00000000..e1935247
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-atoms/viewport-aware-dropdowns.md
@@ -0,0 +1,134 @@
+# Viewport-Aware Dropdowns
+
+A revealed action panel or popover button group is a useful pattern for users to access additional functionality while taking up minimal space. This overlay pattern comes with layout complexity, as the panel must remain tethered to a trigger element while adapting to viewport constraints. Traditionally, this required complex JavaScript libraries (like Popper.js or Floating UI) to calculate positions and handle collisions.
+
+CSS Anchor Positioning provides a declarative, performance-optimized way to handle these relationships entirely in CSS, allowing browsers to manage the positioning and overflow logic natively.
+
+> [!NOTE]
+> This guide demonstrates anchor-positioning and popover mechanics — it does not prescribe a specific accessible UI pattern. The trigger and panel below are shown as a plain **button-revealing-a-button-group**. If you need a true ARIA menu (`role="menu"` with arrow-key navigation), a combobox, a disclosure widget, or any other named pattern, layer that pattern's full semantics and keyboard contract on top of the positioning techniques shown here.
+
+### 1. Define the Button and Panel Relationship
+
+The first step is to create a trigger button that opens the overlay container using the Popover API.
+
+**MANDATORY Accessibility Distinction:** This pattern explicitly models a **button group revealed inside a popover** rather than a true ARIA menu. Do not apply `role="menu"` or `role="menuitem"` unless you fully implement the corresponding keyboard navigation contract (such as handling spatial arrow-key navigation between items). For the same reason, do not add `aria-haspopup` to the trigger — its value (`menu`, `listbox`, `tree`, `grid`, or the legacy `true`) is a promise that the target exposes a matching role, which this pattern does not.
+
+```html
+<button popovertarget="action-panel">
+  Open Actions
+</button>
+<!-- Use the Popover API (`popover="auto"`) for the overlay to ensure it is placed in the top layer and handled accessibly by the browser. -->
+<div id="action-panel" popover="auto" class="panel">
+  <button class="action-item" type="button">Edit</button>
+</div>
+```
+
+This creates an *implicit* anchor association between the button and the panel, so that the panel can be positioned relative to the button natively without needing `anchor-name` on the button or `position-anchor` on the panel.
+
+### 2. Positioning with `position-area`
+
+Instead of manual `top`/`left` offsets, use `position-area` to place the target on a 3x3 grid relative to the anchor.
+
+```css
+.panel {
+  /* 
+     Position the panel below the anchor (block-end), 
+     aligned to the start of the anchor and spanning to its end (span-inline-end).
+  */
+  position-area: block-end span-inline-end;
+  
+  /* Reset insets to allow the grid to take control */
+  inset: auto;
+}
+```
+
+Prefer logical keywords (`span-inline-end`, `block-start`) over physical ones (`left`, `top`) to support RTL and different writing modes automatically.
+
+**MANDATORY**: Do not mix physical and logical keywords in `position-area`.
+
+### 3. Implement Edge-Resilience (Fallbacks)
+
+To prevent the panel from being cut off at the edge of the screen, define "try tactics" that the browser should attempt if the default position overflows.
+
+```css
+.panel {
+  /* 
+     If the panel overflows the bottom, flip it to the top (flip-block).
+     If it overflows the inline edges, flip it horizontally (flip-inline).
+     If it overflows both (e.g., in a corner), flip on both axes (flip-block flip-inline).
+  */
+  position-try-fallbacks: flip-block, flip-inline, flip-block flip-inline;
+}
+```
+
+If your dropdown or flyout includes a directional arrow or border that needs to change style depending on which fallback position was chosen, see `position-aware-tooltips` (via `npx -y modern-web-guidance@latest retrieve "position-aware-tooltips"`). For declarative invocation of dialogs and popovers without JavaScript, see `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`).
+
+## Fallback strategies
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+To support browsers without anchor positioning, you must set a reasonable position. By default popovers are centered in the middle of the screen, which may work for your use case.
+
+For some use cases, you may be able to use the `@oddbird/css-anchor-positioning` polyfill, which adds support for some anchor positioning use cases. It does not support implicit anchors, so you MUST add anchor names to the trigger. Additionally, `position-area` is not supported on popovers by the polyfill, so you MUST use `anchor()` on the desired insets. 
+
+```html
+<!-- MANDATORY: Conditionally install the anchor positioning polyfill -->
+<script type="module">
+  if (!("anchorName" in document.documentElement.style)) {
+    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+```css
+.panel {
+  /* Mandatory: use explicit anchor name */
+  position-anchor: --kebab-anchor;
+  /* Mandatory: use insets rather than position-area for positioning */
+  bottom: auto;
+  right: auto;
+  top: anchor(bottom);
+  left: anchor(left);
+  margin: 0;
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/2d-panning.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/2d-panning.md
new file mode 100644
index 00000000..796ef734
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/2d-panning.md
@@ -0,0 +1,151 @@
+# Two-Dimensional Panning
+
+When a user scrolls a two-dimensional scroll container, browsers typically apply a scroll axis-locking heuristic (also known as "railing"). If a gesture begins with significantly more movement along one axis than the perpendicular axis, the browser locks the scroll to that single horizontal or vertical axis and ignores perpendicular deltas—often for the remainder of the gesture.
+
+While axis-locking prevents accidental sideways drift in one-dimensional reading flows, it creates friction on two-dimensional panning surfaces such as interactive maps, zoomed images, infinite canvases, node graphs, and large data grids. Because the lock persists across the gesture, it affects any panning that involves two directions—whether both axes are panned simultaneously (diagonal panning) or one after the other within a single gesture (such as curved, circular, or L-shaped paths). The CSS `scroll-axis-lock` property disables this heuristic directly on a native scroll container, allowing unrestricted two-dimensional panning while preserving compositor-thread scrolling, momentum physics, native scrollbars, and keyboard navigation.
+
+## Implementation
+
+### 1. Disable axis-locking and contain overscroll on the two-dimensional scroll container
+
+Apply `scroll-axis-lock: none` directly to the element that establishes the two-dimensional scroll container (`overflow: auto` or `overflow: scroll`). While a 2D scroll container can already update scroll deltas along both axes under the default `auto` value, `auto` allows the browser's railing heuristic to kick in when a gesture starts predominantly along one axis. Setting `scroll-axis-lock: none` prevents that railing from engaging across touchscreens, trackpads, and mouse wheels.
+
+Pair `scroll-axis-lock: none` with `overscroll-behavior: none` (or `overscroll-behavior: contain`) on the scroll container so that reaching an edge does not chain scrolling to the parent page or trigger accidental browser overscroll navigations (such as horizontal back/forward swipe navigation or pull-to-refresh).
+
+### 2. Preserve keyboard focusability and accessibility
+
+Because a 2D panning surface often lacks focusable child controls (for example, a map or zoomed image), ensure keyboard users can focus the container and pan it with the Arrow keys by adding `tabindex="0"`, an appropriate `role` and accessible label, and a visible `:focus-visible` indicator.
+
+## Example Code
+
+```html
+<!-- Make the 2D scroll container keyboard-focusable and labeled so keyboard
+     users can focus the viewport and pan in all directions with Arrow keys. -->
+<div class="pan-viewport" tabindex="0" role="region" aria-label="Interactive canvas">
+  <div class="pan-surface">
+    <!-- 2D overflowing content (map tiles, zoomed image, canvas nodes, or grid) -->
+  </div>
+</div>
+```
+
+```css
+.pan-viewport {
+  /* Example viewport dimensions; adjust to fit your layout. */
+  inline-size: 100%;
+  block-size: 500px;
+
+  /* MANDATORY: Establish a scroll container that can overflow on both axes. */
+  overflow: auto;
+
+  /* MANDATORY: Prevent browser scroll axis-locking ("railing") from kicking in
+     so 2D gestures never get locked to a single axis. */
+  scroll-axis-lock: none;
+
+  /* Contain scrolling and prevent accidental swipe navigations at edges
+     (use `none` or `contain`). */
+  overscroll-behavior: none;
+}
+
+/* Provide a clear focus indicator when keyboard users focus the viewport. */
+.pan-viewport:focus-visible {
+  outline: 3px solid #005fcc;
+  outline-offset: 2px;
+}
+
+.pan-surface {
+  /* Example surface dimensions larger than .pan-viewport in both axes. */
+  inline-size: 3000px;
+  block-size: 3000px;
+}
+```
+
+## Best Practices & Constraints
+
+- **Apply it to the scroll container itself, not an ancestor wrapper**: `scroll-axis-lock` is not inherited, so setting it on a wrapper has no effect on descendant scroll containers.
+- **Contain overscroll and prevent accidental navigations**: Add `overscroll-behavior: none` or `overscroll-behavior: contain` to the 2D scroll container so panning into a boundary does not chain to the parent page or trigger browser back/forward swipe navigation and pull-to-refresh gestures.
+- **Nested one-dimensional panels keep railing automatically**: Because `scroll-axis-lock` does not inherit, a sidebar or inspector panel nested inside `.pan-viewport` retains the default `scroll-axis-lock: auto` behavior.
+- **Keep `auto` on standard vertical feeds, articles, and one-dimensional lists**: Axis-locking prevents unintentional perpendicular drift in unidirectional content.
+- **Do not set `touch-action: none` unconditionally**: `touch-action` controls whether the browser handles touch gestures at all (and has no effect on trackpad or wheel input), so setting it disables native compositor touch scrolling. Only apply it inside `@supports not (scroll-axis-lock: none)` when implementing the JavaScript pointer fallback.
+- **Pan with `scrollLeft` / `scrollTop`, never CSS `transform`**: Translating the surface with `transform` stops the element from functioning as a scroll container—breaking native scrollbars, boundary clamping, keyboard Arrow-key scrolling, `scroll` events, `IntersectionObserver`, and scroll-driven animations.
+
+## Fallback strategies
+
+Browser support for scroll-axis-lock: Limited availability.
+Supported by: Chrome 153 (Sep 2026).
+Unsupported in: Edge, Firefox, and Safari.
+
+Choose between **progressive enhancement** and a **JavaScript fallback** based on your application's requirements:
+
+### Option 1: Progressive Enhancement (No JavaScript)
+
+Use progressive enhancement when preserving native compositor-thread touch scrolling, inertial fling momentum, and pinch-to-zoom is more important than eliminating axis-locking in unsupported browsers:
+
+- **Supporting browsers**: The browser prevents its axis-locking ("railing") heuristic from kicking in on the 2D scroll container during scroll gestures.
+- **Unsupported browsers**: Browsers that do not recognize `scroll-axis-lock: none` safely ignore the declaration and keep their default `auto` 2D scrolling behavior—scrolling across both axes natively, while still railing gestures that begin predominantly along a single axis.
+
+### Option 2: JavaScript Fallback (`wheel` + `pointermove` with `scrollLeft`/`scrollTop`)
+
+If unrestricted two-dimensional panning across all browsers is required, use `@supports not (scroll-axis-lock: none)` and `CSS.supports('scroll-axis-lock', 'none')` to conditionally intercept `wheel` and pointer drag gestures.
+
+Because `wheel` (`e.deltaX`, `e.deltaY`) and `pointermove` (`e.clientX`, `e.clientY`) expose raw, unlocked 2D deltas before the browser's scrolling engine applies axis-locking, you can apply those deltas directly to `scrollLeft` and `scrollTop`:
+
+- **Why `scrollLeft`/`scrollTop` instead of CSS `transform`**: Updating `scrollLeft` and `scrollTop` keeps the element as a true scroll container. The browser automatically clamps scroll positions to `[0, scrollWidth - clientWidth]` and `[0, scrollHeight - clientHeight]`, native scrollbars stay synchronized, keyboard Arrow-key scrolling continues to work, and `scroll` events and `IntersectionObserver` fire normally.
+- **Trade-offs**: Intercepting `wheel` with `{ passive: false }` moves scrolling onto the main thread, and setting `touch-action: none` on touchscreens disables native inertial fling momentum after `pointerup` (as well as native pinch-to-zoom).
+
+```css
+/* Only disable native touch scrolling when scroll-axis-lock is unsupported
+   and the JavaScript pointer fallback below is active. */
+@supports not (scroll-axis-lock: none) {
+  .pan-viewport {
+    touch-action: none;
+  }
+}
+```
+
+```javascript
+// Only attach the main-thread gesture fallback when native support is missing
+if (!CSS.supports('scroll-axis-lock', 'none')) {
+  const viewport = document.querySelector('.pan-viewport');
+  let lastPointer = null;
+
+  // 1. Trackpad and mouse wheel fallback
+  viewport.addEventListener(
+    'wheel',
+    (e) => {
+      e.preventDefault();
+      viewport.scrollLeft += e.deltaX;
+      viewport.scrollTop += e.deltaY;
+    },
+    { passive: false },
+  );
+
+  // 2. Touch and pointer drag fallback
+  viewport.addEventListener('pointerdown', (e) => {
+    // Ignore non-primary buttons and clicks on native scrollbars
+    const rect = viewport.getBoundingClientRect();
+    if (
+      !e.isPrimary ||
+      e.button !== 0 ||
+      e.clientX - rect.left - viewport.clientLeft >= viewport.clientWidth ||
+      e.clientY - rect.top - viewport.clientTop >= viewport.clientHeight
+    ) {
+      return;
+    }
+    lastPointer = { x: e.clientX, y: e.clientY };
+    viewport.setPointerCapture(e.pointerId);
+  });
+
+  viewport.addEventListener('pointermove', (e) => {
+    if (!lastPointer) return;
+    viewport.scrollLeft -= e.clientX - lastPointer.x;
+    viewport.scrollTop -= e.clientY - lastPointer.y;
+    lastPointer = { x: e.clientX, y: e.clientY };
+  });
+
+  const endPointerPan = () => {
+    lastPointer = null;
+  };
+  viewport.addEventListener('pointerup', endPointerPan);
+  viewport.addEventListener('pointercancel', endPointerPan);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/anchor-positioning-tab-underline.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/anchor-positioning-tab-underline.md
new file mode 100644
index 00000000..31ef4b15
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/anchor-positioning-tab-underline.md
@@ -0,0 +1,99 @@
+# Anchor Positioning Tab Underline
+
+In a tab menu, you should provide visual hints to users about what page they are on. One option is by underlining the tab. With anchor positioning, you can create a smooth animation between the positions of the underline. This does not work when changing the active tab loads a new web page.
+
+You can also use this effect to add an animated dot to indicate the active tab in a vertical tab bar.
+
+Create the underline using a `::before` pseudo-element on the `<ul>` that contains the `<li>` elements. **Using a pseudo-element is the preferred approach as it keeps the DOM clean and avoids adding extra elements for purely decorative effects.**
+
+```css
+ul::before {
+  /* Use a pseudo-element on the container to represent the animated indicator */
+  content: '';
+}
+```
+
+Make the active list item an anchor by adding the `anchor-name` property, which has a value that starts with `--`.
+
+```css
+li.active {
+  /* Make a unique anchor-name for the active element. */
+  anchor-name: --active;
+}
+```
+
+Tether the underline to the active item anchor with a `position-anchor` that matches the `anchor-name` on the anchor, and making it `position: absolute`.
+
+```css
+ul::before {
+  /* Tether the underline to the active element. */
+  position: absolute;
+  position-anchor: --active;
+}
+```
+
+Position the underline relative to the anchor using the inset properties and `anchor()` functions.
+
+```css
+ul::before {
+  /* DO NOT use position-area, which can not be transitioned. */
+  /* Use calc() to offset the top slightly */
+  inset-block-start: calc(anchor(bottom) + .1lh);
+  inset-inline-start: anchor(left);
+  inset-inline-end: anchor(right);
+}
+```
+
+Add a height and other visual styles.
+
+```css
+ul::before {
+  /* Apply your project's styles for the indicator */
+  block-size: .25lh;
+  background: red;
+}
+```
+
+Finally, add a transition on the `inset` properties.
+
+```css
+ul::before {
+  @media (prefers-reduced-motion: no-preference) {
+    /* MANDATORY: The transition must be wrapped in a prefers-reduced-motion media query to respect user preferences. */
+    transition: inset .2s;
+  }
+}
+```
+
+This is only a visual indicator, and must not be a replacement for setting the appropriate `aria-current="page"` or `aria-selected` aria values.
+
+```html
+<!-- MANDATORY: Provide explicit assistive technology state alongside the visual tab underline -->
+<nav aria-label="Primary">
+  <ul>
+    <li class="active">
+      <a href="/home" aria-current="page">Home</a>
+    </li>
+    <li>
+      <a href="/about">About</a>
+    </li>
+  </ul>
+</nav>
+```
+
+## Fallback strategies
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+If anchor positioning is not supported in the browser, use a `border-bottom` to add an underline. It will not be animated.
+
+```css
+ul li.active {
+  @supports not (position-anchor: auto) {
+    /* Choose a color appropriate to the app theme. */
+    border-bottom: .25lh var(--primary) solid;
+  }
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-element-entry-exit.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-element-entry-exit.md
new file mode 100644
index 00000000..21fc98d1
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-element-entry-exit.md
@@ -0,0 +1,192 @@
+# Animate Element Entry and Exit
+
+In the past, CSS transitions could not animate elements when they were first added to the DOM or when their `display` property changed from `none`. The `@starting-style` at-rule and `transition-behavior: allow-discrete` provide a declarative way to create smooth entry and exit animations.
+
+## Implementation
+
+### 1. Animating `display: none` Toggles
+
+To animate an element when toggling its visibility via an attribute (e.g., `hidden` with `display: none`):
+
+1. **Define the visible state**: Set the final property values (e.g., `opacity: 1`) on the base class.
+2. **Define the entry starting state**: Use `@starting-style` to specify the values to transition *from* when the element becomes visible.
+3. **Enable discrete transitions**: Include `display` in the `transition` property and use `transition-behavior: allow-discrete`.
+4. **Define the exit state**: Set the target values in the `hidden` attribute.
+
+```css
+.card {
+  display: block;
+  opacity: 1;
+  translate: 0;
+  /* MANDATORY: Use transition-behavior: allow-discrete for display transition */
+  transition:
+    display 0.4s,
+    opacity 0.4s ease-out,
+    translate 0.4s ease-out;
+  transition-behavior: allow-discrete;
+}
+
+/* Entry animation: transition FROM these values when first rendered */
+@starting-style {
+  .card {
+    opacity: 0;
+    translate: 0 -20px;
+  }
+}
+
+/* Exit animation: transition TO these values when hidden */
+.card[hidden] {
+  display: none;
+  opacity: 0;
+  translate: 0 -20px;
+}
+
+/* Respect user preference for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    /* Disable movement and shorten duration for a simple fade */
+    translate: none;
+    transition-duration: 0.1s;
+  }
+
+  @starting-style {
+    .card {
+      translate: none;
+    }
+  }
+
+  .card[hidden] {
+    translate: none;
+  }
+}
+```
+
+### 2. Animating DOM Insertion and Removal
+
+For elements added via `appendChild()` or removed via `remove()`:
+
+- **Entry**: Use `@starting-style` as shown above. The browser will automatically detect the style change from "nothing" to the element's initial styles and trigger the transition from the `@starting-style` values.
+- **Removal**: Since `element.remove()` is instantaneous and doesn't trigger a CSS transition on its own, you must trigger the exit transition first and wait for it to finish before removing the node from the DOM.
+
+```javascript
+// 1. Trigger exit transition
+element.hidden = true;
+
+// 2. Wait for all active transitions/animations to finish,
+//    with a failsafe timeout in case an animation never ends (e.g. for looping animations)
+const animations = element.getAnimations();
+if (animations.length > 0) {
+  await Promise.race([
+    // Promise.allSettled ensures we wait even if some animations fail
+    Promise.allSettled(animations.map(a => a.finished)),
+    new Promise(r => setTimeout(r, 2000))
+  ]);
+}
+
+// 3. Finally remove the node from the DOM
+element.remove();
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Use `transition-behavior: allow-discrete` when transitioning `display`. Without it, the element will instantly disappear during exit.
+- **DO NOT** use `allow-discrete` in the `transition` shorthand — it will make older browsers ignore the entire `transition` declaration. Except in use cases where that is desirable, use a separate `transition-behavior: allow-discrete` declaration.
+- **MANDATORY**: Use `@starting-style` for entry animations. Browsers skip transitions on an element's first style update (initial render or `display: none` change) unless this is provided.
+- **DO**: Include `overlay` in the `transition` list if animating top-layer elements like `<dialog>` or `popover` to ensure they stay in the top layer during the exit animation.
+- **DO**: Respect user preferences for reduced motion using the `prefers-reduced-motion` media query.
+- **DO NOT**: Rely on `@starting-style` for exit animations; it only defines the *starting* point for an entry transition. Exit animations are defined by the transition to the hidden state.
+
+## Fallback strategies
+
+Baseline status for @starting-style: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.5 (May 2024).
+
+### Fallbacks & browser support for transition-behavior
+
+Baseline status for transition-behavior: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.4 (Mar 2024).
+
+Browser support for the css.properties.transition-behavior.transitionable_display capability: Limited availability.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), and Safari 18 (Sep 2024).
+Unsupported in: Firefox.
+
+Firefox 129+ parses `transition-behavior: allow-discrete` (`CSS.supports('transition-behavior', 'allow-discrete')` returns `true`) without actually transitioning the `display` property (Firefox bug 1882408), causing elements to disappear immediately on exit.
+
+To reliably detect discrete `display` transition support, probe whether a temporary element's computed `display` remains visible when transitioned to `none` rather than relying solely on `CSS.supports('transition-behavior', 'allow-discrete')`:
+
+```javascript
+let supportsDisplayTransition;
+function canTransitionDisplay() {
+  if (supportsDisplayTransition !== undefined) return supportsDisplayTransition;
+  if (!window.CSS?.supports?.('transition-behavior', 'allow-discrete') || !document.body) {
+    return false;
+  }
+  const probe = document.createElement('div');
+  // The shorthand is intentional here: browsers that don't parse allow-discrete
+  // drop the whole declaration, so display: none applies instantly and the probe
+  // correctly returns false. !important guards against global reduced-motion
+  // resets like `* { transition: none !important }`.
+  probe.style.cssText = 'transition: display 1s allow-discrete !important; display: block;';
+  document.body.appendChild(probe);
+  getComputedStyle(probe).display;
+  probe.style.display = 'none';
+  supportsDisplayTransition = getComputedStyle(probe).display === 'block';
+  probe.remove();
+  return supportsDisplayTransition;
+}
+```
+
+### Exit fallback when discrete `display` transitions are unsupported
+
+Entry animations using `@starting-style` work across all modern browsers without JavaScript. When discrete `display` transitions are unsupported (`!canTransitionDisplay()`), setting `hidden` applies `display: none` immediately and skips the exit animation (both when hiding and before `element.remove()`). Separate the visual exit state (`[data-closing]`) from `display: none` (`[hidden]`) so `opacity` and `translate` finish animating before hiding or removing the element. Replace the `.card[hidden]` rules from step 1 (including the `prefers-reduced-motion` override) with:
+
+```css
+.card:where([hidden], [data-closing]) {
+  opacity: 0;
+  translate: 0 -20px;
+}
+
+.card[hidden] {
+  display: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .card:where([hidden], [data-closing]) {
+    translate: none;
+  }
+}
+```
+
+```javascript
+async function hideElement(el) {
+  if (canTransitionDisplay()) {
+    el.hidden = true;
+  } else {
+    el.setAttribute('data-closing', '');
+  }
+
+  const animations = el.getAnimations();
+  if (animations.length > 0) {
+    await Promise.race([
+      Promise.allSettled(animations.map((a) => a.finished)),
+      new Promise((r) => setTimeout(r, 2000)),
+    ]);
+  }
+
+  // Skipped if showElement() cancelled the close mid-animation.
+  if (el.hasAttribute('data-closing')) {
+    el.removeAttribute('data-closing');
+    el.hidden = true;
+  }
+}
+
+function showElement(el) {
+  el.removeAttribute('data-closing');
+  el.hidden = false;
+}
+
+async function removeElement(el) {
+  await hideElement(el);
+  el.remove();
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-to-from-top-layer.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-to-from-top-layer.md
new file mode 100644
index 00000000..23b9859f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/animate-to-from-top-layer.md
@@ -0,0 +1,240 @@
+# Animate Elements To and From Top Layer
+
+Elements that render in the "top layer" (like `<dialog>`, elements with the `popover` attribute, or tooltips) have historically been difficult to animate because they toggle between `display: none` and a visible state. Modern CSS provides `@starting-style`, `transition-behavior: allow-discrete`, and the `overlay` property to enable smooth entry and exit transitions for these elements. Note that native CSS nesting is used in the examples below.
+
+## Implementation
+
+### 1. Enable Discrete Transitions
+
+To animate the `display` property, you must set `transition-behavior: allow-discrete`. This allows the element to remain visible during its exit transition. If using transition shorthands, be sure to place the `transition-behavior: allow-discrete` afterwards to prevent the shorthand from negating it.
+
+### 2. The `overlay` Property
+
+When an element moves in or out of the top layer, it must transition the `overlay` property. This ensures the element stays in the top layer for the duration of the animation, preventing it from being clipped by other elements or the viewport prematurely.
+
+### 3. Entry Animations with `@starting-style`
+
+Use the `@starting-style` at-rule to define the styles an element should transition *from* when it is first rendered or its `display` changes from `none`.
+
+### 4. Animating the Backdrop
+
+The `::backdrop` pseudo-element can be animated similarly by applying transitions to its own properties.
+
+## Example
+
+```css
+/* 1. Define the visible (open) state */
+dialog[open],
+[popover]:popover-open {
+  opacity: 1;
+  transform: scale(1);
+
+  /* 2. Define the starting state for entry (must come after open state) */
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+}
+
+/* 3. Define the base (closed/exit) state and transitions */
+dialog,
+[popover] {
+  opacity: 0;
+  transform: scale(0.9);
+
+  /* MANDATORY: transition display and overlay for top-layer elements */
+  transition-property: opacity, transform, display, overlay;
+  transition-duration: 0.3s;
+  transition-timing-function: ease-out;
+  /* Applies to discrete properties like display and overlay */
+  transition-behavior: allow-discrete; /* Note: be sure to write this after the shorthand */
+}
+
+/* 4. Animate the backdrop */
+dialog::backdrop,
+[popover]::backdrop {
+  background-color: rgba(0, 0, 0, 0);
+  transition-property: background-color, display, overlay;
+  transition-duration: 0.3s;
+  transition-timing-function: ease-out;
+  transition-behavior: allow-discrete;
+}
+
+dialog[open]::backdrop,
+[popover]:popover-open::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+
+  @starting-style {
+    background-color: rgba(0, 0, 0, 0);
+  }
+}
+
+/* 5. Respect user preference for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  dialog,
+  [popover] {
+    /* Disable movement and shorten duration for a simple fade */
+    transform: none;
+    transition-duration: 0.1s;
+  }
+
+  @starting-style {
+    dialog[open],
+    [popover]:popover-open {
+      transform: none;
+    }
+  }
+}
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Include `overlay` in your `transition` list for any element moving into or out of the top layer.
+- **MANDATORY**: Use `allow-discrete` for the `display` property transition.
+- **MANDATORY**: Respect user preferences for reduced motion using `prefers-reduced-motion` by simplifying transitions (e.g., removing transforms and shortening duration).
+- **DO**: Place the `@starting-style` block inside or after the "open" state selector to ensure proper cascading.
+- **DO NOT**: Use `@starting-style` for exit animations; exit animations are defined by the transition to the base (closed) state.
+
+## Fallback strategies
+
+Baseline status for @starting-style: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.5 (May 2024).
+
+Browser support for overlay: Limited availability.
+Supported by: Chrome 117 (Sep 2023) and Edge 117 (Sep 2023).
+Unsupported in: Firefox and Safari.
+
+### Fallbacks & browser support for transition-behavior
+
+Baseline status for transition-behavior: Newly available. It's been Baseline since 2024-08-06.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), Firefox 129 (Aug 2024), and Safari 17.4 (Mar 2024).
+
+Browser support for the css.properties.transition-behavior.transitionable_display capability: Limited availability.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), and Safari 18 (Sep 2024).
+Unsupported in: Firefox.
+
+Firefox 129+ parses `transition-behavior: allow-discrete` (`CSS.supports('transition-behavior', 'allow-discrete')` returns `true`) without actually transitioning the `display` property (Firefox bug 1882408), causing elements to disappear immediately on exit.
+
+To reliably detect discrete `display` transition support, probe whether a temporary element's computed `display` remains visible when transitioned to `none` rather than relying solely on `CSS.supports('transition-behavior', 'allow-discrete')`:
+
+```javascript
+let supportsDisplayTransition;
+function canTransitionDisplay() {
+  if (supportsDisplayTransition !== undefined) return supportsDisplayTransition;
+  if (!window.CSS?.supports?.('transition-behavior', 'allow-discrete') || !document.body) {
+    return false;
+  }
+  const probe = document.createElement('div');
+  // The shorthand is intentional here: browsers that don't parse allow-discrete
+  // drop the whole declaration, so display: none applies instantly and the probe
+  // correctly returns false. !important guards against global reduced-motion
+  // resets like `* { transition: none !important }`.
+  probe.style.cssText = 'transition: display 1s allow-discrete !important; display: block;';
+  document.body.appendChild(probe);
+  getComputedStyle(probe).display;
+  probe.style.display = 'none';
+  supportsDisplayTransition = getComputedStyle(probe).display === 'block';
+  probe.remove();
+  return supportsDisplayTransition;
+}
+```
+
+### Top-layer exit fallback
+
+Entry animations work in pure CSS across all browsers that support `@starting-style`—no `.is-opening` class is needed because entry transitions do not depend on `overlay` or discrete `display` transitions.
+
+Exit animations require both `overlay` and discrete `display` transition support. When either is unsupported (such as in Firefox and Safari), wrap the open-state selectors in `:is()` and append `:where(:not([data-closing]))` (nesting `&::backdrop` and `@starting-style`) so setting `data-closing` triggers the exit transition while the element remains in the top layer, then wait for `getAnimations()` to settle before calling `.close()` or `.hidePopover()`:
+
+```css
+:is(dialog[open], [popover]:popover-open):where(:not([data-closing])) {
+  opacity: 1;
+  transform: scale(1);
+
+  @starting-style {
+    opacity: 0;
+    transform: scale(0.9);
+  }
+
+  &::backdrop {
+    background-color: rgb(0 0 0 / 0.5);
+
+    @starting-style {
+      background-color: transparent;
+    }
+  }
+}
+```
+
+```javascript
+// Evaluate lazily: canTransitionDisplay() needs document.body, so a top-level
+// const would be permanently false if this script runs in <head>.
+function supportsTopLayerExit() {
+  return window.CSS?.supports?.('overlay', 'auto') && canTransitionDisplay();
+}
+
+async function closeTopLayer(element) {
+  if (!supportsTopLayerExit()) {
+    element.setAttribute('data-closing', '');
+    const animations = element.getAnimations({ subtree: true });
+    if (animations.length > 0) {
+      await Promise.race([
+        Promise.allSettled(animations.map((a) => a.finished)),
+        new Promise((r) => setTimeout(r, 2000)),
+      ]);
+    }
+    if (!element.hasAttribute('data-closing')) return;
+    element.removeAttribute('data-closing');
+  }
+
+  element.close();
+  // Or for popover:
+  // element.hidePopover();
+}
+
+// Route native close requests (Esc, closedby light dismiss) through the same
+// helper so they animate too, instead of closing instantly.
+dialog.addEventListener('cancel', (event) => {
+  event.preventDefault();
+  closeTopLayer(dialog);
+});
+```
+
+Popover light dismiss and `popovertarget` toggles cannot be intercepted (`beforetoggle` is only cancelable when opening), so in browsers that need the fallback those exits are instant. Provide an explicit close control that calls `closeTopLayer()` if the exit animation matters.
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/carousel-snap-highlights.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/carousel-snap-highlights.md
new file mode 100644
index 00000000..e7c422d3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/carousel-snap-highlights.md
@@ -0,0 +1,138 @@
+# Carousel Snap Highlights
+
+Scroll-state container queries allow you to style elements based on their current scroll state, such as whether an element is "stuck" (via sticky positioning) or "snapped" (via scroll snapping). This enables carousel or gallery experiences where the active item can be visually distinguished without relying on JavaScript intersection observers or scroll event listeners.
+
+### Core implementation
+
+To highlight snapped items, you must establish a scroll-snap container, define the snap targets as scroll-state containers, and then query that state to style descendants.
+
+#### 1. Establish the scroll snap container
+The parent container must have `scroll-snap-type` enabled.
+
+```html
+<div class="carousel">
+  <div class="carousel-item">
+    <div class="card">Product 1 content</div>
+  </div>
+  <div class="carousel-item">
+    <div class="card">Product 2 content</div>
+  </div>
+</div>
+```
+
+```css
+.carousel {
+  display: flex;
+  overflow-x: auto;
+  /* MANDATORY: Enable scroll snapping on the container */
+  scroll-snap-type: x mandatory;
+}
+```
+
+#### 2. Define snap targets as scroll-state containers
+Each item in the carousel that should be tracked for snapping must be declared as a `scroll-state` container.
+
+```css
+.carousel-item {
+  /* Define where the item snaps within the container */
+  scroll-snap-align: center;
+  
+  /* MANDATORY: Establish this element as a scroll-state query container */
+  container-type: scroll-state;
+}
+```
+
+#### 3. Query the `snapped` state
+
+Because container queries style **descendants**, you must apply the highlight styles to an element *inside* the snap target.  Because the scroll container is set to overflow on the x axis, use the `scroll-state(snapped: x)` query.
+
+**MANDATORY**: Wrap the styles in ` @media (prefers-reduced-motion: no-preference)` to only show the effect to users who have not requested reduced motion. Depending on your use case, you may retain portions of the effect, but in this case, the cards flash from white to blue in a way that may cause problems for some users, so we disable it completely.
+
+```css
+/* Specify transition outside of queries so that it is applied regardless of state.  */
+.card {
+  transition:
+    scale 0.4s cubic-bezier(0.25, 0.8, 0.25, 1),
+    background-color 0.4s,
+    color 0.4s,
+    box-shadow 0.4s;
+}
+/* 
+Only show the effect for users not requesting reduced motion. Disable completely, including the color change, as it causes a flash that may be problematic.
+*/
+@media (prefers-reduced-motion: no-preference) {
+  /* Style the content when its parent .carousel-item is snapped on the x axis */
+  @container scroll-state(snapped: x) {
+    .card {
+      background: #007bff;
+      color: white;
+      scale: 1.15;
+      box-shadow: 0 10px 25px rgba(0, 123, 255, 0.3);
+    }
+  }
+}
+
+/* MANDATORY Copy-Paste Safety: Disable highlight scaling/flashing for motion sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none !important;
+    scale: 1 !important;
+  }
+}
+```
+
+The `snapped` descriptor can query specific axes: `x`, `y`, `inline`, `block`, or `both`.
+
+
+### Accessibility
+
+**AVOID**: using `scroll-state` with interactive elements.
+
+Visual highlights for snapped items can improve the UX, but the snapped item is not exposed to the accessibility tree. The visual theme applied to a snapped item should not convey that the element is active or focused, and a keyboard focus ring should be highly visible and distinct from the `snapped` highlight. If the snapped item is interactive, you must use other standard accessibility practices to make it accessible.  
+
+Snapping occurs due to scrolling, which does not move keyboard focus. However, keyboard focus may cause the scroll container to move, causing a change in the snapped item, which may or may not be the focused item. This will likely be a source of confusion for users and is discouraged.
+
+> [!NOTE]
+> Detailed accessibility requirements for carousels (such as ARIA roles, slide attributes, and complex keyboard patterns) have been intentionally omitted from this guide. Carousel accessibility is highly nuanced and context-dependent; refer to established accessibility standards and perform thorough user testing for production environments.
+
+
+## Fallback strategies
+
+Browser support for Container scroll-state queries: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not support scroll-state queries, you should provide a functional base experience where all items are legible, even without the "active" highlight.
+
+#### Feature detection
+You can use `@supports` to provide enhancements only to supported browsers:
+
+```css
+@supports (container-type: scroll-state) {
+  /* Enhancement styles here */
+}
+```
+
+#### JavaScript fallback
+
+If the highlight is critical for the user experience, use `IntersectionObserver` to determine the snapped item. Adjust the observed area to a thin slice in the center of the carousel by providing a `rootMargin` with a negative inline value. For example, to consider an element to be intersecting if it is in the center 2% of the carousel, set the `rootMargin` to `"0px -49%"`.  
+
+```javascript
+// Optional: detect support and apply a JS-based fallback
+if (!CSS.supports('container-type', 'scroll-state')) {
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      // Toggle a class based on intersection
+      entry.target.classList.toggle('is-snapped', entry.isIntersecting);
+    });
+  }, {
+    root: document.querySelector(".carousel"),
+    // Carousel item intersects if any part of the carousel item is in the middle 2% of the carousel.
+    rootMargin: "0px -49%"
+  });
+
+  document.querySelectorAll('.carousel-item').forEach(item => {
+    observer.observe(item);
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/consistent-cross-document-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/consistent-cross-document-transitions.md
new file mode 100644
index 00000000..3998f7e2
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/consistent-cross-document-transitions.md
@@ -0,0 +1,259 @@
+# Consistent Cross-Document Transitions
+
+## The Problem
+
+Cross-document view transitions animate elements between two pages during a same-origin navigation. The browser captures a snapshot of the old page, navigates, then animates from the snapshot to the new page. If the new page has not finished loading critical resources — stylesheets, layout scripts, or key DOM elements — the transition animates to an incomplete or unstyled state. This causes visual glitches such as elements morphing to wrong positions, content reflowing mid-animation, or fallback fonts flashing to web fonts after the transition completes.
+
+## The Solution
+
+Use `blocking="render"` on critical `<link>` and `<script>` elements in the new page's `<head>`, and use `<link rel="expect">` to block rendering until specific DOM elements have been parsed. This ensures the browser does not begin the view transition animation until the new page's visual state is stable. The browser continues parsing the HTML in the background — only painting is deferred.
+
+### Implementation Strategy
+
+1. **MANDATORY:** Opt in to cross-document view transitions with the `@view-transition` CSS at-rule on both pages.
+2. **MANDATORY:** Ensure critical stylesheets are in the `<head>`. Stylesheets in the `<head>` are render-blocking by default. Dynamically injected stylesheets require explicit `blocking="render"`.
+3. **DO** use `blocking="render"` on `<script>` elements that must execute before the transition animates (e.g., scripts that apply a theme or affect the layout).
+4. **DO** use `<link rel="expect" href="#element-id" blocking="render">` to block rendering until above-the-fold content has been parsed. This applies to all transition types: full-page cross-fades (to avoid animating to a blank page), morph animations (to ensure named elements exist in the DOM), and script-dependent layouts (to ensure styled content is parsed).
+5. **DO NOT** block rendering on non-critical content. Only block on resources and elements that affect the initial viewport. Blocking on too much content delays the transition and degrades perceived performance.
+
+## Implementation Guide
+
+### Step 1: Opt in to Cross-Document View Transitions
+
+MANDATORY: Both the source and destination pages must include the `@view-transition` at-rule. Without this, no cross-document transition occurs.
+
+```css
+/*
+  MANDATORY: Include this rule in every page that participates
+  in cross-document view transitions.
+  `navigation: auto` enables transitions for standard navigations
+  (link clicks, form submissions, back/forward).
+*/
+@view-transition {
+  navigation: auto;
+}
+
+/* MANDATORY Copy-Paste Safety: Disable cross-document view transitions for users requesting reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  @view-transition {
+    navigation: none;
+  }
+}
+```
+
+### Step 2: Block Rendering Until Critical Scripts Execute
+
+If a non-blocking script in the `<head>` must run before the transition animates (e.g., to apply a theme class or affect the layout), mark it with `blocking="render"`. Without this, `async`, `defer`, or `type="module"` scripts may execute after the transition has already started.
+
+```html
+<head>
+  <!--
+    DO: Mark layout-critical scripts with blocking="render".
+  -->
+  <script type=module blocking="render">
+    // Example: apply a stored theme before the page renders,
+    // so the transition snapshot reflects the correct theme.
+    document.documentElement.dataset.theme =
+      localStorage.getItem('theme') || 'light';
+  </script>
+</head>
+```
+
+### Step 3: Block Rendering Until Key DOM Elements Are Parsed
+
+Stylesheets and `blocking="render"` scripts in the `<head>` only guarantee that the `<head>` has been fully processed. They do **not** wait for any `<body>` content to be parsed. Without additional blocking, the browser may take the new-page snapshot before above-the-fold elements exist in the DOM — resulting in a transition that animates to a blank or partially rendered page.
+
+`<link rel="expect">` solves this by blocking rendering until a specific element (identified by its `id`) has been parsed. The `href` value must be a fragment identifier (e.g., `#hero`) matching the target element's `id` attribute. Once that element's closing tag is parsed, the render block is released. Note that `<link rel="expect">` only guarantees that the target DOM element exists in the document — it does **not** wait for external subresources (such as `<img>` pixels) to download or decode.
+
+**DO** use `<link rel="expect">` in all of the following scenarios:
+
+#### Use Case 1: Full-Page Cross-Fade
+
+Even when no individual elements have a `view-transition-name`, the default `root` transition cross-fades the entire page. If the new page's snapshot is taken before above-the-fold content is parsed, the cross-fade animates from the old page to a blank or incomplete page. Block rendering on an element that marks the end of the visible above-the-fold content.
+
+```html
+<head>
+  <link rel="stylesheet" href="/css/styles.css">
+
+  <!--
+    DO: Block rendering until the main content area is parsed,
+    even for a simple cross-fade. Without this, the browser may
+    snapshot the page before visible content exists in the DOM,
+    causing the cross-fade to reveal a blank or partial page.
+  -->
+  <link rel="expect" href="#main-content" blocking="render">
+</head>
+<body>
+  <header>...</header>
+  <main id="main-content">
+    <h1>Page Title</h1>
+    <p>Above-the-fold content the user should see immediately.</p>
+  </main>
+  <!-- Content below the fold does NOT need to be blocked on -->
+  <section>...</section>
+</body>
+```
+
+#### Use Case 2: Morph Animations Between Specific Elements
+
+When elements on both pages share a `view-transition-name`, the browser morphs them smoothly across the navigation. If the target element has not been parsed when the transition starts, the browser cannot find it — the morph degrades to separate exit and entry animations. Block rendering until the element with the `view-transition-name` has been parsed.
+
+Because `<link rel="expect">` only pauses rendering until the target DOM element is parsed and does not wait for image data to download or decode, an uncached `<img>` may be captured as an empty rectangle in the new-page snapshot. To prevent blank snapshots or layout shifts during image morphs, preload or pre-decode critical transition images (for example, with `<link rel="preload" as="image">` or by prerendering the destination page) and provide explicit sizing fallbacks (`width` and `height` attributes or CSS `aspect-ratio`, plus a placeholder background color).
+
+```html
+<head>
+  <link rel="stylesheet" href="/css/styles.css">
+
+  <!--
+    DO: Preload critical transition images so their pixels are
+    available to decode before the new-page snapshot is captured.
+    <link rel="expect"> only waits for the DOM element to be parsed,
+    NOT for image pixels to download or decode.
+  -->
+  <link rel="preload" as="image" href="/img/product.webp" fetchpriority="high">
+
+  <!--
+    DO: Block rendering until the element participating in the
+    morph animation has been parsed. Without this, the browser
+    may start the transition before #hero exists, causing the
+    morph to degrade to a fade-out/fade-in.
+  -->
+  <link rel="expect" href="#hero" blocking="render">
+
+  <!--
+    When multiple blocking="render" resources are present,
+    rendering is blocked until ALL of them are satisfied.
+    Here, the browser waits for both the script to execute
+    AND the #hero element to be parsed — whichever comes last.
+  -->
+  <script async blocking="render" src="/js/transition-setup.js"></script>
+</head>
+<body>
+  <header>...</header>
+  <section id="hero">
+    <h1 style="view-transition-name: page-title">Product Name</h1>
+    <!--
+      DO: Provide explicit dimensions (width/height or aspect-ratio)
+      as a sizing fallback so the snapshot captures the correct layout
+      box even if image decoding is still in progress.
+    -->
+    <img
+      style="view-transition-name: hero-image"
+      src="/img/product.webp"
+      width="800"
+      height="600"
+      alt="Product"
+    >
+  </section>
+</body>
+```
+
+### Step 4: Use Media Queries for Responsive Render Blocking
+
+Different viewport sizes may show different amounts of content above the fold. Use the `media` attribute on `<link rel="expect">` to block rendering only for the content visible at a given viewport width.
+
+```html
+<head>
+  <!--
+    DO: Use media queries to conditionally block rendering.
+    On wide screens, both the hero and the sidebar are visible,
+    so block until both are parsed. On narrow screens, only the
+    hero is visible initially.
+  -->
+  <link
+    rel="expect"
+    href="#hero"
+    blocking="render"
+    media="screen and (width <= 768px)"
+  >
+  <link
+    rel="expect"
+    href="#sidebar"
+    blocking="render"
+    media="screen and (width > 768px)"
+  >
+</head>
+```
+
+### Step 5: Use pagereveal for Context-Dependent Transitions (Optional)
+
+The `pagereveal` event is **not required** for the core render-blocking strategy. It is only needed when `view-transition-name` values must be assigned dynamically based on where the user navigated from — for example, morphing a specific list item to a detail page heading.
+
+If `view-transition-name` values are assigned statically in CSS, or if you are only using the default full-page cross-fade, skip this step entirely.
+
+```html
+<head>
+  <!--
+    MANDATORY: The pagereveal listener must be registered before
+    the page renders. Inline small setup scripts with blocking="render"
+    to avoid an extra network round-trip on cold loads, or use an
+    external async script with blocking="render" so the listener is
+    registered early without blocking HTML parsing.
+    If the listener is registered too late (e.g., in a deferred
+    script), the event may have already fired.
+  -->
+  <script async blocking="render" src="/js/transition-setup.js"></script>
+</head>
+```
+
+```javascript
+// transition-setup.js
+window.addEventListener('pagereveal', async (event) => {
+  if (!event.viewTransition) return;
+
+  const from = navigation.activation?.from;
+  if (!from) return;
+
+  const fromUrl = new URL(from.url);
+
+  // DO: Assign view-transition-name based on navigation context.
+  // This enables a morph animation from the product card on the
+  // list page to the heading on the detail page.
+  if (fromUrl.pathname === '/products/') {
+    const heading = document.querySelector('main h1');
+    if (!heading) return;
+
+    heading.style.viewTransitionName = 'product-title';
+
+    try {
+      await event.viewTransition.ready;
+    } catch (error) {
+      // Skipped view transitions reject `ready` with InvalidStateError.
+      if (error.name !== 'InvalidStateError') {
+        throw error;
+      }
+    } finally {
+      // MANDATORY: Remove the temporary name after the transition
+      // finishes. Stale names interfere with subsequent navigations
+      // and prevent the page from entering the bfcache.
+      await event.viewTransition.finished;
+      heading.style.viewTransitionName = '';
+    }
+  }
+});
+```
+
+## Best Practices
+
+- **DO** assign `view-transition-name` via CSS whenever possible. Reserve JavaScript assignment (via `pagereveal`) for cases where the name depends on navigation context.
+- **DO** keep render-blocking scripts small and fast. The browser has a built-in timeout (around 4 seconds), after which the transition is skipped entirely (rejecting `viewTransition.ready` with an `InvalidStateError` if a transition was initiated).
+- **DO NOT** use `<link rel="expect">` to block on elements deep in the page that are not visible in the initial viewport. This delays the transition without visual benefit.
+- **DO NOT** mark analytics, ad-network, tag-manager or other third-party loaders with `blocking="render"`, even if they inject content into the initial viewport. Their network latency counts toward the transition timeout and their output is not part of the page's stable state.
+- **DO NOT** assign the same `view-transition-name` to multiple elements on the same page. Duplicate names cause the entire transition to be skipped.
+- **Assistive Technology Timing Impact**: Using `blocking="render"` delays visual updates and initial paint. While this prevents visual glitches for sighted users, it can cause processing latency or deferred initialization for screen readers and other assistive technologies that depend on rendered accessibility trees. Weigh the visual continuity benefits against the initial read latency for non-visual users, and ensure render-blocking scripts are minimal and extremely optimized.
+
+## Fallback Strategies
+
+Browser support for Cross-document view transitions: Limited availability.
+Supported by: Chrome 126 (Jun 2024), Edge 126 (Jun 2024), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+Cross-document view transitions are an excellent candidate for progressive enhancement. In browsers that do not support them, the `@view-transition` rule is ignored and standard same-origin navigations occurs exactly as they would without the feature. Supporting browsers get smooth transitions; all others get standard navigation. Limited browser support is not a reason to avoid adoption.
+
+All browsers that support cross-document view transitions also support `blocking="render"` and `<link rel="expect">`, so no separate fallback is needed for the render-blocking features described in this guide.
+
+## Other Considerations
+
+1. **Performance Impact**: Every render-blocking resource delays the view transition animation start. Minimize the number of render-blocking scripts and use `<link rel="expect">` only for elements that are above the fold. Prerender destination pages using the Speculation Rules API to eliminate loading delays entirely.
+2. **Timeout Behavior**: If the combined render-blocking time exceeds approximately 4 seconds, the browser skips the transition (and any active `viewTransition.ready` promise rejects with an `InvalidStateError`). Ensure critical resources load well within this window.
+3. **bfcache Compatibility**: Temporary `view-transition-name` assignments that are not cleaned up after the transition can prevent the page from entering the bfcache. Always remove dynamically assigned names in the `finished` callback.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/cross-document-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/cross-document-transitions.md
new file mode 100644
index 00000000..fe30d7c8
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/cross-document-transitions.md
@@ -0,0 +1,129 @@
+# Cross-Document Transitions
+
+Cross-document view transitions allow you to create smooth, app-like transitions between different pages of a Multi-Page Application (MPA). By default, the browser performs a cross-fade, but you can customize this to match your site's aesthetic.
+
+### Implementation Steps
+
+#### 1. Opt-in to Cross-Document View Transitions
+
+Both the source and destination pages must opt-in to view transitions for the browser to trigger them on navigation.
+
+```css
+/* Respect user's preference for reduced motion */
+@media (prefers-reduced-motion: no-preference) {
+  /* Add to a global stylesheet shared by both pages */
+  @view-transition {
+    /* Enables transitions for same-origin navigations */
+    navigation: auto;
+  }
+}
+```
+
+#### 2. Customize Transition Animations (Optional)
+
+You can target the old and new states of the transition using pseudo-elements to create effects like slides or reveals.
+
+```css
+/* Customizing the outgoing page animation */
+::view-transition-old(root) {
+  /* Move the old page out to the left */
+  animation: 0.4s ease-in both slide-out;
+}
+
+/* Customizing the incoming page animation */
+::view-transition-new(root) {
+  /* Move the new page in from the right */
+  animation: 0.4s ease-out both slide-in;
+}
+
+@keyframes slide-out {
+  to { transform: translateX(-20%); opacity: 0; }
+}
+
+@keyframes slide-in {
+  from { transform: translateX(100%); }
+}
+```
+
+#### 3. Create Directional Transitions (Optional)
+
+You may want different transition effects depending on the pages you are navigating between. For instance, when navigating from a home page to a contact page, you may want the effect of new content coming from the right. When navigating back to the home page, it wouldn't make sense to have the same effect. 
+
+If the page you are navigating to will always have the same transition type, regardless of how you get to the page, you can specify it with `types` in the `@view-transition` rule.
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @view-transition {
+    navigation: auto;
+    /* Specify the types of view transitions that will always be used on this page. */
+    types: previous;
+  }
+}
+```
+
+You can also conditionally specify transition types inside of an event listener for `pagereveal`.
+
+```js
+window.addEventListener("pagereveal", async (e) => {
+  if (e.viewTransition && window.navigation?.activation) {
+    // Use application-specific logic to compute a transition type
+     const transitionType = yourTransitionTypeLogic(navigation.activation.from, navigation.activation.entry);
+    e.viewTransition.types.add(transitionType);
+  }
+});
+```
+
+Then, use the `:active-view-transition-type()` pseudo selector to apply the different animations for each type.
+
+```css
+:active-view-transition-type(next) {
+  &::view-transition-old(root) {
+    animation-name: slide-out-next;
+  }
+
+  &::view-transition-new(root) {
+    animation-name: slide-in-next;
+  }
+}
+:active-view-transition-type(previous) {
+  &::view-transition-old(root) {
+    animation-name: slide-out-previous;
+  }
+
+  &::view-transition-new(root) {
+    animation-name: slide-in-previous;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for View transitions: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 144 (Oct 2025), and Safari 18 (Sep 2024).
+
+Browser support for Cross-document view transitions: Limited availability.
+Supported by: Chrome 126 (Jun 2024), Edge 126 (Jun 2024), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+If a browser does not support view transitions, or cross-document view transitions, it will perform a standard instant page navigation. Cross-document view transitions are a progressive enhancement; the core functionality of the site remains unaffected.
+
+To check for support in JavaScript:
+
+```javascript
+if ('onpagereveal' in window) {
+  // Browser supports cross-document view transitions
+}
+```
+
+Baseline status for Navigation API: Newly available. It's been Baseline since 2026-01-13.
+Supported by: Chrome 102 (May 2022), Edge 102 (May 2022), Firefox 147 (Jan 2026), and Safari 26.2 (Dec 2025).
+
+If a browser does not support the Navigation API, you will not be able to use it to determine a transition type. Use an alternate method for determining the transition type, or provide a fallback transition type. Otherwise, the browser will perform a standard instant page navigation.
+
+To check for support in JavaScript:
+
+```javascript
+if (window.navigation?.activation) {
+  // Browser supports the Navigation API
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/custom-button-actions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/custom-button-actions.md
new file mode 100644
index 00000000..f9c7b5ef
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/custom-button-actions.md
@@ -0,0 +1,180 @@
+# Custom Button Actions
+The Invoker Commands API allows buttons to trigger actions on target elements declaratively using HTML attributes. 
+This approach reduces the need for manual event listeners and decouples the UI from implementation details.
+For custom, application-specific actions, you can define your own command names. Custom commands must be prefixed with a double dash (`--`) to avoid collisions with future built-in browser commands.
+
+## Implementation steps
+
+1.  **Define the target element**: Identify the element that will respond to the action. If it doesn’t have a unique `id`, add one.
+2.  **Configure the invoker button**: Use the `commandfor` attribute to point to the target's `id`, and the `command` attribute to specify the custom command name (prefixed with `--`).
+3.  **Handle the command event**: Attach a `command` event listener directly on the target element. The event object contains a `command` property and a `target` property (referring to the element identified by `commandfor`).
+4.  **Handle aria states**: Custom commands do not have inherent semantics, and you must handle states like `aria-pressed` or `aria-expanded`.
+
+## Example: Custom Animation Controls
+
+```html
+<!-- The target element that will respond to custom commands -->
+<div id="action-target" class="target">
+  Action Target
+</div>
+
+<!-- Buttons declaratively linked to the target element -->
+<!-- Each button sends a unique custom command starting with '--' -->
+<button commandfor="action-target" command="--spin">
+  Spin
+</button>
+
+<button commandfor="action-target" command="--grow">
+  Grow
+</button>
+
+<button commandfor="action-target" command="--reset">
+  Reset All
+</button>
+
+<script>
+  // 1. **Optional:** Define a registry of requested actions for cleaner logic
+const commandRegistry = {
+  '--spin': (target, source) => {
+    const isSpun = target.classList.toggle('is-spun');
+    // Set ARIA states, as custom commands have no inherent semantics.
+    source?.setAttribute('aria-pressed', isSpun);
+  },
+  '--grow': (target, source) => {
+    const isGrown = target.classList.toggle('is-grown');
+    source?.setAttribute('aria-pressed', isGrown);
+  },
+  '--reset': (target) => {
+    target.classList.remove('is-spun', 'is-grown');
+    // Reset all associated buttons' ARIA states
+    document.querySelectorAll(`button[commandfor="${target.id}"]`).forEach(btn => {
+      btn.setAttribute('aria-pressed', 'false');
+    });
+  },
+};
+
+  // 2. **Mandatory:** Listen for the 'command' event directly on the target element
+  // (This is necessary because the native 'command' event does not bubble)
+  document.getElementById('action-target').addEventListener('command', (event) => {
+    const command = event.command;
+    const target = event.target;
+    const source = event.source; // event.source refers to the triggering button
+    const action = commandRegistry[command];
+
+    if (action) {
+      action(target, source);
+    }
+  });
+</script>
+```
+
+## Key constraints
+
+*   **Prefix custom commands**: MANDATORY: All custom command names must start with `--` (e.g., `command="--my-action"`).
+*   **Targeting**: The `commandfor` attribute must match the `id` of an element in the same document tree.
+*   **No bubbling**: The `command` event does not bubble. If there multiple possible targets, add `{ capture: true }` to the event handler and listen on an ancestor.
+*   **Shadow roots**: If the target may be in a shadow root, use `event.composedPath()[0]` instead of `event.target`.
+*   **Accessibility**: Custom commands have no inherent semantics, and you must explicitly apply any states.
+
+## Accessibility considerations
+
+* If the button displays additional content, use the `aria-expanded` attribute, set to `aria-expanded="false"` by default and `aria-expanded="true"` when the accompanying content is displayed
+* If the button facilitates an interaction itself (examples include toggle buttons which can play and pause, volume buttons which can mute and unmute), use the `aria-pressed` attribute, set to `aria-pressed="false"` when inactive, and `aria-pressed="true"` when active
+* If the button opens an element with a role of either `menu`, `listbox`, `tree`, `grid`, or `dialog`, then the control must have an `aria-haspopup` attribute, with a value set to the role of the element that it opens
+* If the button becomes disabled on activation, instead of using `disabled`, use `aria-disabled="true"` so that there is no loss of focus
+
+## Fallback strategies
+
+Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).
+
+If the Invoker Commands API is not supported, the `command` event will not fire. For full support across all modern browsers, it is recommended to use the invokers-polyfill from https://github.com/keithamus/invokers-polyfill via `npm install` or CDN.
+
+This polyfill fully supports custom actions (starting with `--`) and dispatches the `command` event exactly like the native API.
+
+### Dynamic Import (Performance Optimization)
+
+For the best performance, you should only load the polyfill if the browser doesn't support the API natively. This saves bandwidth and reduces script execution time for users on modern browsers.
+
+**NOTE:** This polyfill does not manage ARIA states (like `aria-pressed` or `aria-expanded`) for custom commands. You must manually synchronize these states in your event listener to ensure your site is accessible.
+
+```javascript
+// 1. Conditionally load the polyfill
+const hasNativeSupport = 'commandForElement' in HTMLButtonElement.prototype;
+
+if (!hasNativeSupport) {
+  // Wrap in an async IIFE to avoid top-level await issues in older browsers
+  (async () => {
+    try {
+      await import('https://esm.run/invokers-polyfill');
+    } catch (err) {
+      console.error('Error loading fallback:', err);
+    }
+  })();
+}
+
+// 2. Manually manage ARIA states in your listener
+document.getElementById('action-target').addEventListener('command', (event) => {
+  const command = event.command;
+  const target = event.target;
+  const source = event.source; // The button that triggered the command
+
+  if (command === '--spin') {
+    const isSpun = target.classList.toggle('is-spun');
+    
+    // Polyfill tip: Manually update ARIA to match the new state
+    source?.setAttribute('aria-pressed', isSpun);
+  }
+});
+```
+
+### Manual fallback (Traditional pattern)
+
+If you prefer not to use a polyfill, you can use a combination of **event delegation** to dispatch events and a **command registry** to handle the actions. This is a common architectural pattern in traditional JavaScript development that remains highly efficient and scalable.
+
+```javascript
+// 1. **Optional:** Define a registry of requested actions for cleaner logic
+const commandRegistry = {
+  '--spin': (target) => target.classList.toggle('is-spun'),
+  '--grow': (target) => target.classList.toggle('is-grown'),
+  '--reset': (target) => target.classList.remove('is-spun', 'is-grown'),
+};
+
+// 2. If CommandEvent doesn't exist, we assume no native support and provide the fallback
+if (!globalThis.CommandEvent) {
+  globalThis.CommandEvent = class CommandEvent extends Event {
+    constructor(type, { source, command, ...options } = {}) {
+      super(type, options);
+      this.source = source;
+      this.command = command;
+    }
+  }
+}
+
+// 3. The fallback: Dispatch events manually if native support is missing
+  document.addEventListener('click', (event) => {
+    const button = event.composedPath().find((el) => el.matches?.("button[commandfor]"));
+    if (!button) return;
+
+    const target = document.getElementById(button.getAttribute('commandfor'));
+    const command = button.getAttribute('command');
+
+    if (target && command) {
+      target.dispatchEvent(new CommandEvent('command', { 
+        command, 
+        source: button,
+      }));
+    }
+  });
+
+// 4. **Mandatory:** Register the unified listener directly on the target element
+document.getElementById('action-target').addEventListener('command', (event) => {
+  const command = event.command;
+  const target = event.target;
+  const action = commandRegistry[command];
+
+  if (action) {
+    action(target);
+  }
+ });
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/declarative-dialog-popover-control.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/declarative-dialog-popover-control.md
new file mode 100644
index 00000000..0218fc0a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/declarative-dialog-popover-control.md
@@ -0,0 +1,232 @@
+# Declarative Dialog and Popover Control
+
+Use the Invoker Commands API to toggle the visibility of `<dialog>` and `[popover]` elements directly from HTML buttons, eliminating the need for custom JavaScript event listeners.
+
+By applying the `commandfor` (target ID) and `command` (action) attributes to a `<button>`, the browser automatically handles open/close state changes, focus management, and accessibility bindings (such as `aria-expanded`). This declarative approach is recommended because it removes brittle boilerplate code, ensures interactions are functional immediately upon HTML parsing, and guarantees a robust, natively accessible user experience.
+
+## Implementing Declarative Popovers
+
+Popovers can be toggled open and closed using a single button.
+
+```html
+<!-- MANDATORY: The commandfor attribute links the invoker to the ID of the target element so the browser knows what to control. -->
+<!-- MANDATORY: The command attribute specifies the action to perform. Use 'toggle-popover' to handle both open and close states automatically. -->
+<button commandfor="my-popover" command="toggle-popover">
+  Toggle Popover
+</button>
+
+<!-- MANDATORY: The target element must have the popover attribute to be controlled as a popover. -->
+<div id="my-popover" popover>
+  <p>Popover content goes here.</p>
+</div>
+```
+
+If you need to control opening and closing with separate buttons, you can use the `show-popover` and `hide-popover` commands.
+
+```html
+<!-- MANDATORY: Use 'show-popover' to explicitly open the popover. It will not close the popover if clicked again. -->
+<button commandfor="my-explicit-popover" command="show-popover">
+  Show Popover
+</button>
+
+<div id="my-explicit-popover" popover="manual">
+  <p>This popover is explicitly opened and closed by separate buttons.</p>
+
+  <!-- MANDATORY: Use 'hide-popover' to explicitly close the targeted popover. -->
+  <button commandfor="my-explicit-popover" command="hide-popover">
+    Hide Popover
+  </button>
+</div>
+```
+
+## Implementing Declarative Modal Dialogs
+
+Unlike popovers, modal dialogs typically use separate buttons for opening and closing. Use the `show-modal` command specifically when you need to open a dialog as a modal.
+
+```html
+<!-- MANDATORY: Use command="show-modal" to trigger the dialog as a modal, trapping focus and preventing interaction with the rest of the page. -->
+<!-- MANDATORY: The commandfor attribute connects this button to the dialog ID. -->
+<button commandfor="confirm-dialog" command="show-modal">
+  Open Confirmation
+</button>
+
+<dialog id="confirm-dialog">
+  <p>Are you sure you want to proceed?</p>
+
+  <!-- MANDATORY: Use command="close" to dismiss the dialog safely. -->
+  <button commandfor="confirm-dialog" command="close">
+    Cancel
+  </button>
+</dialog>
+```
+
+## Fallback strategies
+
+Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).
+
+Because Invoker Commands and Popovers are not yet universally supported, you MUST use polyfills as fallbacks for older browsers.
+
+### Polyfilling Invoker Commands
+
+MANDATORY: Feature detect support by checking for the `commandForElement` property on the `HTMLButtonElement` prototype. Do NOT check the window or document object. You MUST dynamically import the polyfill only when the native feature is missing. DO NOT unconditionally load the polyfill.
+Mandatory: Listen for the 'command' event directly on the target element because the native 'command' event does not bubble.
+
+**Option 1: Using a bundler**
+Install the polyfill via npm (`npm install invokers-polyfill`). This approach is for projects using a bundler (like Vite or Webpack) or import maps. For all other setups, use the CDN option below.
+
+```javascript
+// MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
+// Conditionally load the invokers-polyfill only in browsers lacking native support.
+if (!('commandForElement' in HTMLButtonElement.prototype)) {
+  import('invokers-polyfill');
+}
+```
+
+**Option 2: Using a CDN**
+For projects without a bundler, dynamically import the polyfill directly from a CDN inside a `<script type="module">`.
+
+```html
+<script type="module">
+  // MANDATORY: Feature detect 'commandForElement' on HTMLButtonElement.prototype.
+  // Conditionally load the invokers-polyfill from a CDN only in browsers lacking native support.
+  if (!('commandForElement' in HTMLButtonElement.prototype)) {
+    import('https://esm.run/invokers-polyfill');
+  }
+</script>
+```
+
+**Invokers Polyfill Limitations**
+MANDATORY: This polyfill does not handle the ARIA states (e.g., `aria-expanded`) of the command button the way native browsers do. You are strongly encouraged to handle these states yourself to ensure your site is fully accessible.
+
+Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).
+
+If the Invoker Commands API is not supported, the `command` event will not fire. For full support across all modern browsers, it is recommended to use the invokers-polyfill from https://github.com/keithamus/invokers-polyfill via `npm install` or CDN.
+
+This polyfill fully supports custom actions (starting with `--`) and dispatches the `command` event exactly like the native API.
+
+### Dynamic Import (Performance Optimization)
+
+For the best performance, you should only load the polyfill if the browser doesn't support the API natively. This saves bandwidth and reduces script execution time for users on modern browsers.
+
+**NOTE:** This polyfill does not manage ARIA states (like `aria-pressed` or `aria-expanded`) for custom commands. You must manually synchronize these states in your event listener to ensure your site is accessible.
+
+```javascript
+// 1. Conditionally load the polyfill
+const hasNativeSupport = 'commandForElement' in HTMLButtonElement.prototype;
+
+if (!hasNativeSupport) {
+  // Wrap in an async IIFE to avoid top-level await issues in older browsers
+  (async () => {
+    try {
+      await import('https://esm.run/invokers-polyfill');
+    } catch (err) {
+      console.error('Error loading fallback:', err);
+    }
+  })();
+}
+
+// 2. Manually manage ARIA states in your listener
+document.getElementById('action-target').addEventListener('command', (event) => {
+  const command = event.command;
+  const target = event.target;
+  const source = event.source; // The button that triggered the command
+
+  if (command === '--spin') {
+    const isSpun = target.classList.toggle('is-spun');
+    
+    // Polyfill tip: Manually update ARIA to match the new state
+    source?.setAttribute('aria-pressed', isSpun);
+  }
+});
+```
+
+### Manual fallback (Traditional pattern)
+
+If you prefer not to use a polyfill, you can use a combination of **event delegation** to dispatch events and a **command registry** to handle the actions. This is a common architectural pattern in traditional JavaScript development that remains highly efficient and scalable.
+
+```javascript
+// 1. **Optional:** Define a registry of requested actions for cleaner logic
+const commandRegistry = {
+  '--spin': (target) => target.classList.toggle('is-spun'),
+  '--grow': (target) => target.classList.toggle('is-grown'),
+  '--reset': (target) => target.classList.remove('is-spun', 'is-grown'),
+};
+
+// 2. If CommandEvent doesn't exist, we assume no native support and provide the fallback
+if (!globalThis.CommandEvent) {
+  globalThis.CommandEvent = class CommandEvent extends Event {
+    constructor(type, { source, command, ...options } = {}) {
+      super(type, options);
+      this.source = source;
+      this.command = command;
+    }
+  }
+}
+
+// 3. The fallback: Dispatch events manually if native support is missing
+  document.addEventListener('click', (event) => {
+    const button = event.composedPath().find((el) => el.matches?.("button[commandfor]"));
+    if (!button) return;
+
+    const target = document.getElementById(button.getAttribute('commandfor'));
+    const command = button.getAttribute('command');
+
+    if (target && command) {
+      target.dispatchEvent(new CommandEvent('command', { 
+        command, 
+        source: button,
+      }));
+    }
+  });
+
+// 4. **Mandatory:** Register the unified listener directly on the target element
+document.getElementById('action-target').addEventListener('command', (event) => {
+  const command = event.command;
+  const target = event.target;
+  const action = commandRegistry[command];
+
+  if (action) {
+    action(target);
+  }
+ });
+```
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/directional-navigation-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/directional-navigation-transitions.md
new file mode 100644
index 00000000..180255c9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/directional-navigation-transitions.md
@@ -0,0 +1,128 @@
+# Directional Navigation Transitions
+
+Single Page Applications (SPAs) provide the appearance of navigation by replacing the content of the page without navigating to a new page. By default, the content is simply replaced, without any transitions. Directional transitions can visually reinforce a spatial relationship between views. 
+
+By sliding new content in from the direction the user is moving you create a mental map of the application structure. For instance, a product site may show a transition to the right for "forward," and to the left for "back", or a slideshow may transition up and down to show next and previous slides.
+
+### Implementation Steps
+
+1. **Detect Navigation Direction**: Determine if the user is moving "forward" or "backward" in the application flow. How you detect the direction depends on your use case.
+2. **Trigger Transition with Types**: Pass the direction in a `types` array to `document.startViewTransition()` to categorize the transition.
+3. **Define Directional Animations with CSS**: Use the `:active-view-transition-type()` pseudo-class to apply specific animations based on the navigation type.
+
+### Defining Keyframes
+
+Define sliding animations to and from each direction. For best performance, animate position changes using the `transform` property or the individual transform properties, `scale`, `rotate`, and `translate`. `opacity` is generally performant as well, but avoid animating other CSS properties without first verifying that they don't trigger layout or painting.
+
+```css
+/* Slide an element out to the left */
+@keyframes slide-to-left {
+  /* Mandatory: animate `transform` instead of inset properties for better performance. */
+  to { transform: translateX(-100%); }
+}
+
+/* Slide an element in from the right */
+@keyframes slide-from-right {
+  from { transform: translateX(100%); }
+}
+
+/* Slide an element out to the right */
+@keyframes slide-to-right {
+  to { transform: translateX(100%); }
+}
+
+/* Slide an element in from the left */
+@keyframes slide-from-left {
+  from { transform: translateX(-100%); }
+}
+```
+
+### Set up shared animation settings
+
+Use the `::view-transition-group(root)` selector to apply animation settings that are shared across all transitions.
+
+```css
+::view-transition-group(root){
+  animation: 0.4s ease-in-out both;
+}
+```
+
+### Applying Directional Animations
+
+Use the `active-view-transition-type` pseudo-class to target the transition views specifically when the "forward" or "backward" type is active.
+
+```css
+/* MANDATORY: Apply forward animations when the 'forward' type is active */
+html:active-view-transition-type(forward)::view-transition-old(root) {
+  animation-name: slide-to-left;
+}
+html:active-view-transition-type(forward)::view-transition-new(root) {
+  animation-name: slide-from-right;
+}
+
+/* MANDATORY: Apply backward animations when the 'backward' type is active */
+html:active-view-transition-type(backward)::view-transition-old(root) {
+  animation-name: slide-to-right;
+}
+html:active-view-transition-type(backward)::view-transition-new(root) {
+  animation-name: slide-from-left;
+}
+```
+
+### Triggering the Transition
+
+When navigating, pass the appropriate type to the `startViewTransition` method.
+
+```javascript
+const transitionType = yourTransitionTypeLogic();
+const updateDOM = yourUpdateDOMLogic();
+
+document.startViewTransition({
+  update: updateDOM,
+  types: [transitionType] // Matches the CSS :active-view-transition-type() selectors
+});
+```
+
+
+### Accessibility
+
+Always respect user preferences for reduced motion by disabling or simplifying animations.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(root) {
+    animation: none !important;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for View transitions: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 144 (Oct 2025), and Safari 18 (Sep 2024).
+
+Baseline status for Active view transition: Newly available. It's been Baseline since 2026-01-13.
+Supported by: Chrome 125 (May 2024), Edge 125 (May 2024), Firefox 147 (Jan 2026), and Safari 18.2 (Dec 2024).
+
+The View Transitions API is a progressive enhancement. In unsupported browsers, `document.startViewTransition` will be `undefined`. You must wrap your navigation logic in a feature detection check to ensure the DOM update still occurs immediately without animation, as shown in this helper function.
+
+```javascript
+/**
+ * Navigates to a new view with a directional transition.
+ * @param {Function} updateDOM - Callback to update the DOM state.
+ * @param {string} direction - Either 'forward' or 'backward'.
+ */
+function navigate(updateDOM, direction) {
+  // Feature detect for browsers that do not support View Transitions
+  if (!document.startViewTransition) {
+    updateDOM();
+    return;
+  }
+
+  // Start transition with the specific navigation type
+  document.startViewTransition({
+    update: updateDOM,
+    types: [direction] // Matches the CSS :active-view-transition-type() selectors
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/drag.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/drag.md
new file mode 100644
index 00000000..dc58c6df
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/drag.md
@@ -0,0 +1,84 @@
+# Build a Draggable Element
+
+Add dragging to an existing floating element such as a panel, palette, toolbar, inspector, or dialog. Dragging does not determine how the element is displayed, dismissed, stacked, or focused.
+
+## Use a dedicated handle
+
+Start dragging from a dedicated handle when the element contains selectable text, buttons, inputs, or links. This keeps its normal contents usable. Make the handle focusable for keyboard movement and give it an accessible name that mentions the arrow-key interaction.
+
+Do not apply `role="application"` to the handle. It unnecessarily changes assistive-technology interaction.
+
+Apply `cursor: grab`/`grabbing`, `touch-action: none`, and both `user-select: none` and `-webkit-user-select: none` to the handle—not the entire draggable element—so text outside it remains selectable and touch gestures retain their usual behavior:
+
+```css
+.drag-handle {
+  cursor: grab;
+  touch-action: none;
+  -webkit-user-select: none;
+  user-select: none;
+}
+
+.drag-handle.dragging {
+  cursor: grabbing;
+}
+```
+
+## Preserve pointer position and reachability
+
+Use a viewport-relative positioning model such as `position: fixed` when clamping movement to the viewport.
+
+- Start a drag only for the primary pointer button (`event.button === 0`).
+- Record the pointer offset on `pointerdown` and use it on every move so the element does not jump when grabbed away from its corner.
+- Keep the drag active after the pointer leaves the handle. Default to `setPointerCapture()` and clear the dragging state on `lostpointercapture`. If the handle may be removed or re-rendered mid-drag, use document-level `pointermove`, `pointerup`, and `pointercancel` listeners instead, since capture is lost in that case.
+- Optionally, wait for roughly 4px of movement before entering the dragging state, so a click on the handle does not trigger drag styling.
+
+With pointer capture, the movement listeners can remain on the handle:
+
+```js
+handle.addEventListener('pointerdown', (event) => {
+  if (event.button !== 0 || event.target.closest('button, input, select, textarea, a')) return;
+
+  const rect = draggable.getBoundingClientRect();
+  offsetX = event.clientX - rect.left;
+  offsetY = event.clientY - rect.top;
+  handle.setPointerCapture(event.pointerId);
+});
+
+handle.addEventListener('pointermove', (event) => {
+  if (!handle.hasPointerCapture(event.pointerId)) return;
+  handle.classList.add('dragging');
+  moveTo(event.clientX - offsetX, event.clientY - offsetY);
+});
+
+handle.addEventListener('lostpointercapture', () => {
+  handle.classList.remove('dragging');
+});
+
+function moveTo(left, top) {
+  const maxLeft = Math.max(0, window.innerWidth - draggable.offsetWidth);
+  const maxTop = Math.max(0, window.innerHeight - draggable.offsetHeight);
+
+  draggable.style.left = `${Math.max(0, Math.min(left, maxLeft))}px`;
+  draggable.style.top = `${Math.max(0, Math.min(top, maxTop))}px`;
+}
+```
+
+Clamp every pointer and keyboard position through the same helper so the element stays reachable. Re-clamp its current position after viewport or element-size changes. For layout-heavy elements, consider translating during the drag to avoid per-frame layout, then commit the final position to `left` and `top` on release.
+
+## Provide keyboard movement
+
+When the handle has focus, move the element with the arrow keys and call `preventDefault()` for those keys. Use the same clamped positioning helper as pointer movement. A 15px increment is a reasonable starting point; adapt it to the component's size and precision needs.
+
+## Dialog-specific note
+
+A `<dialog>` or `[popover]` can use this mechanism with its header as the handle. Set `margin: 0` before assigning `left` and `top`, because the browser's default margins interfere with manual positioning. For dialog and popover opening, closing, focus, and dismissal behavior, see `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`) and `platform-controls-dismiss-dialog` (via `npx -y modern-web-guidance@latest retrieve "platform-controls-dismiss-dialog"`).
+
+## Fallback strategies
+
+When dragging only repositions a component, treat it as progressive enhancement: without JavaScript, keep the element, its content, and its controls visible, readable, and functional in a sensible default position. Do not expose a non-functional drag handle: if the handle is a standalone grip control, hide it by default and reveal it when JavaScript initializes; if a header doubles as the handle, attach its drag affordances when JavaScript initializes.
+
+Browser support for user-select: Limited availability.
+Supported by: Chrome 54 (Oct 2016), Edge 79 (Jan 2020), and Firefox 69 (Sep 2019).
+Unsupported in: Safari.
+
+Include `-webkit-user-select: none` before `user-select: none` so text selection stays suppressed during dragging in Safari.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/dynamic-sibling-animations.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/dynamic-sibling-animations.md
new file mode 100644
index 00000000..3a347592
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/dynamic-sibling-animations.md
@@ -0,0 +1,53 @@
+# Creating a stagger animation
+
+Stagger animations provide an interesting effect where multiple ordered elements animate sequentially with a slight delay between each, rather than all animating at once. This technique is often used in lists, galleries, or navigation menus to guide the user's eye and add a polished, rhythmic feel to interactions.
+
+## Stagger animations with `sibling-index()`
+
+Use the `sibling-index()` property on the `animation-delay` property so that the animation on each element is offset by a number proportionate to their position in their parent. The `sibling-index()` function returns an integer, so it must be multiplied by a time unit to convert it to a time.
+
+```css
+#stagger-list > .item {
+  --stagger-time: 0.1s;
+  /* Define the animation first */
+  animation: fade-in 0.4s;
+  /* Set the `animation-delay` to a time multiplied by the `sibling-index()` */
+  animation-delay: calc(sibling-index() * var(--stagger-time))
+}
+```
+
+**MANDATORY:** Respect user preferences by disabling the animation for users who prefer reduced motion. 
+
+```css
+@media (prefers-reduced-motion: reduce){
+  /* Disable animation for users who prefer reduced motion. */
+  #stagger-list > .item {
+    animation: none;
+  }
+}
+```
+
+## Fallback strategies
+
+Baseline status for sibling-count() and sibling-index(): Newly available. It's been Baseline since 2026-08-18.
+Supported by: Chrome 138 (Jun 2025), Edge 138 (Jun 2025), Firefox 154 (Aug 2026), and Safari 26.2 (Dec 2025).
+
+Test for support for `sibling-index()` using CSS with `@supports (animation-delay: calc(sibling-index() * 0.1s)){}` or JavaScript with `!CSS.supports('animation-delay: calc(sibling-index() * 0.1s)')`.
+
+To support stagger animations in older browsers, use JavaScript to add a `--sibling-index` custom property to each sibling element. MANDATORY: wrap this in a `CSS.supports('animation-delay: calc(sibling-index() * 0.1s)')` test to avoid running unneeded JavaScript.
+
+```js
+if(!CSS.supports('animation-delay: calc(sibling-index() * 0.1s)')){
+  const staggerList = document.getElementById('stagger-list');
+  [...staggerList.children].forEach((el, index)=>el.style.setProperty('--sibling-index', index + 1));
+}
+```
+
+Add an `animation-delay` declaration that uses the `--sibling-index` custom property. It must be before the `animation-delay` declaration that uses the `sibling-index()` function. This does not need to be wrapped in `@supports` - older browsers will not parse the second declaration and will use the first declaration.
+
+```css
+#stagger-list > .item {
+  animation-delay: calc(var(--sibling-index) * var(--stagger-time));
+  animation-delay: calc(sibling-index() * var(--stagger-time));
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/group-element-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/group-element-transitions.md
new file mode 100644
index 00000000..1ea3b263
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/group-element-transitions.md
@@ -0,0 +1,126 @@
+# Group Element Transitions
+
+As items are added or removed from a list, or rearranged, transitions can help users maintain context. View transitions provide a way to transition between two states of an element by giving the element a unique `view-transition-name`. When multiple elements on a page share the same transition behavior, `view-transition-class` allows you to define that logic once in CSS rather than repeating it for every unique `view-transition-name`. This keeps your stylesheets maintainable while ensuring consistent animations across a group of elements.
+
+### Implementation steps
+
+1. **Assign unique names and a shared class**
+
+Each element that needs to be tracked individually during a transition must have a unique `view-transition-name`.
+
+```html
+<!-- Mandatory: Each element must have a unique view-transition-name -->
+<li style="view-transition-name: item-1" class="item">Item 1</li>
+<li style="view-transition-name: item-2" class="item">Item 2</li>
+```
+
+To apply shared styles, also assign a `view-transition-class`.
+
+```css
+.item {
+  view-transition-class: list-item;
+}
+```
+
+2. **Define the shared transition logic**
+   
+Use the `::view-transition-group()` pseudo-element with the class selector to apply styles to all members of that group.
+
+```css
+/* Targets any view transition group that has the 'list-item' class */
+::view-transition-group(.list-item) {
+  animation-duration: 0.5s;
+  animation-timing-function: ease-in-out;
+}
+
+/* Handle accessibility by respecting motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  /* Disable all group transitions, including the default `root` group. */
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+3. **Optional: Define entry and exit animations**
+
+Use the `:only-child` selector to add specific transitions to the elements that are added or removed. `::view-transition-new()` and `::view-transition-old()` pseudo-elements are children of a `::view-transition-image-pair()` pseudo-element, so we can determine it is an added or removed element if it is the only child.
+
+```css
+/* A `::view-transition-new()` element is the only child if it wasn't present before the view transition, so it is an added element. */
+::view-transition-new(.list-item):only-child {
+  animation-name: slide-in;
+  /* Specify an animation duration if you want something different than the UA default of 0.5s */
+  animation-duration: 1s;
+}
+/* A `::view-transition-old()` element is the only child if it isn't present after the view transition, so it is a removed element. */
+::view-transition-old(.list-item):only-child {
+  animation-name: slide-out;
+  /* Specify an animation duration if you want something different than the UA default of 0.5s */
+  animation-duration: 1s;
+}
+
+@keyframes slide-in {
+  from {
+    translate: -100vw 0;
+  }
+}
+@keyframes slide-out {
+  to {
+    translate: -100vw 0;
+  }
+}
+```
+
+4. **Trigger the transition**
+
+Wrap the DOM update in `document.startViewTransition()`. The browser will capture the old state, perform the update, and then animate to the new state.
+
+```javascript
+function updateList(newData) {
+  document.startViewTransition(() => {
+    // All DOM changes inside this callback will be transitioned
+    render(newData);
+  });
+}
+```
+
+5. **Maintain interactivity of non-transitioned elements**
+
+View transitions work by overlaying snapshots of the DOM elements, and then transitioning the snapshots. This means that during the transition, elements are not interactive. If there are interactive elements that are not transitioned, you can make them interactive by disabling touch events on the view transitions.
+
+```css
+::view-transition {
+  /* Non-transitioned elements below the view transitions remain interactive */
+  pointer-events: none;
+}
+```
+
+In addition, by default, the `:root` element has a view transition named `root`, which enables default full-page transitions. If there are no changes to the root element, this will be a transition between two identical snapshots, which are not interactive. Because we are only transitioning specific elements, and not the entire screen, we can disable the `root` transition. 
+
+```css
+:root {
+  /* Disable the root transition because we are only transitioning specific elements. */
+  view-transition-name: none;
+}
+```
+
+### Fallback strategies
+
+Baseline status for view-transition-class: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 125 (May 2024), Edge 125 (May 2024), Firefox 144 (Oct 2025), and Safari 18.2 (Dec 2024).
+
+View Transitions are a progressive enhancement. If the browser does not support `document.startViewTransition`, the DOM update should still occur immediately, providing a functional but non-animated experience.
+
+```javascript
+if (document.startViewTransition) {
+  document.startViewTransition(() => updateDOM());
+} else {
+  // Fallback: Perform the update without animation
+  updateDOM();
+}
+```
+
+For CSS, browsers that do not recognize `view-transition-class` or the `::view-transition-group()` class selector will simply ignore those rules, and no animation will be applied.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/highlight-text-ranges.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/highlight-text-ranges.md
new file mode 100644
index 00000000..87e875a9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/highlight-text-ranges.md
@@ -0,0 +1,130 @@
+# Highlight Text Ranges
+
+The CSS Custom Highlight API lets you style arbitrary text ranges on a page without modifying the DOM structure. This enables search-result highlighting, syntax coloring, collaborative editing cursors, or spelling and grammar error markers without wrapping text in extra elements or relying on `innerHTML` manipulation.
+
+### Core implementation
+
+To highlight text ranges, you must collect the target text nodes, create `Range` and `Highlight` objects, register them in the `HighlightRegistry`, and then style them with the `::highlight()` pseudo-element.
+
+#### 1. Collect text nodes and create ranges
+Use a `TreeWalker` to collect all text nodes in the target element, then create `Range` objects pointing at the character offsets you want to highlight.
+
+```javascript
+const article = document.querySelector("article");
+
+// MANDATORY: Use TreeWalker to collect text nodes — do not manipulate innerHTML.
+const treeWalker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
+const allTextNodes = [];
+let currentNode = treeWalker.nextNode();
+while (currentNode) {
+  allTextNodes.push(currentNode);
+  currentNode = treeWalker.nextNode();
+}
+
+// MANDATORY: Set range start/end on text nodes, not element nodes.
+const range = new Range();
+range.setStart(textNode, matchStartIndex);
+range.setEnd(textNode, matchEndIndex);
+```
+
+Cache the text-node list and only rebuild it when the DOM content actually changes, since walking the tree is expensive.
+
+#### 2. Create a Highlight from the ranges
+Group one or more `Range` objects into a `Highlight`. Multiple ranges that share the same style belong in a single highlight.
+
+```javascript
+const searchHighlight = new Highlight(...matchingRanges);
+```
+
+#### 3. Register the highlight in the registry
+Register each `Highlight` under a custom name using `CSS.highlights`, which is a `Map`-like `HighlightRegistry`.
+
+```javascript
+// MANDATORY: Clear previous highlights before registering new ones
+// to avoid stale ranges persisting on the page.
+CSS.highlights.clear();
+
+CSS.highlights.set("search-results", searchHighlight);
+```
+
+When multiple highlights overlap, use the `priority` property to control stacking order. Higher priority highlights paint on top.
+
+```javascript
+const primary = new Highlight(...primaryRanges);
+primary.priority = 1;
+
+const secondary = new Highlight(...secondaryRanges);
+secondary.priority = 0; // painted first (behind primary)
+
+CSS.highlights.set("primary", primary);
+CSS.highlights.set("secondary", secondary);
+```
+
+#### 4. Style with `::highlight()`
+Use the `::highlight()` pseudo-element in CSS to style each registered highlight by name.
+
+```css
+::highlight(search-results) {
+  background-color: #ffdd00;
+  color: black;
+}
+```
+
+Only a limited set of CSS properties work inside `::highlight()`: `color`, `background-color`, `text-decoration` and its longhands, `text-shadow`, `-webkit-text-stroke-color`, `-webkit-text-fill-color`, and `-webkit-text-stroke-width`. Properties like `background-image`, `font-size`, or `padding` are ignored.
+
+### Accessibility
+
+**AVOID**: using custom highlights as a replacement for semantic HTML.
+
+Custom highlights are purely presentational and are not exposed to the accessibility tree. If the highlighted text is semantically relevant to the document (e.g., a user-selected passage), use `<mark>` instead. Reserve custom highlights for transient, visual-only effects like search results or syntax coloring.
+
+Highlights should not rely solely on color to convey meaning. If a highlight indicates an error, pair it with another visual indicator such as `text-decoration: wavy underline` or an adjacent text label. Ensure sufficient contrast between the highlight background and text color to meet WCAG 2.1 requirements (at least 4.5:1 for normal text).
+
+### Fallback strategies
+
+Baseline status for Custom highlights: Newly available. It's been Baseline since 2026-03-24.
+Supported by: Chrome 105 (Sep 2022), Edge 105 (Sep 2022), Firefox 149 (Mar 2026), and Safari 17.2 (Dec 2023).
+
+For browsers that do not support the CSS Custom Highlight API, you should provide a functional base experience where text is still legible, even without the visual highlight.
+
+You can detect support before using the API:
+
+```javascript
+if (CSS.highlights) {
+  // CSS Custom Highlight API is supported.
+} else {
+  // Fallback: wrap matches in <mark> elements.
+}
+```
+
+If the highlight is critical for the user experience, fall back to wrapping matched text in `<mark>` elements. This modifies the DOM, so take care to preserve event listeners and avoid breaking the document structure.
+
+```javascript
+if (!CSS.highlights) {
+  // Walk text nodes and wrap matches in <mark>, preserving structure.
+  const walker = document.createTreeWalker(article, NodeFilter.SHOW_TEXT);
+  const nodes = [];
+  for (let n = walker.nextNode(); n; n = walker.nextNode()) nodes.push(n);
+
+  const term = searchTerm.toLowerCase();
+  for (const textNode of nodes) {
+    const text = textNode.textContent;
+    let pos = text.toLowerCase().indexOf(term);
+    if (pos === -1) continue;
+
+    const frag = document.createDocumentFragment();
+    let last = 0;
+    while (pos !== -1) {
+      frag.append(text.slice(last, pos));
+      const mark = document.createElement("mark");
+      // textContent assignment avoids HTML injection.
+      mark.textContent = text.slice(pos, pos + term.length);
+      frag.append(mark);
+      last = pos + term.length;
+      pos = text.toLowerCase().indexOf(term, last);
+    }
+    frag.append(text.slice(last));
+    textNode.replaceWith(frag);
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interactive-content-reveal.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interactive-content-reveal.md
new file mode 100644
index 00000000..843cbae1
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interactive-content-reveal.md
@@ -0,0 +1,120 @@
+# Interactive Content Reveal
+
+Add performant, interactive reveal effects to your site with CSS masks and registered custom properties. By using a radial gradient as a mask and registering its stop values, we can smoothly transition the entry and exit, while following a user's pointer with minimal JavaScript. 
+
+## Implementation
+
+### 1. Register Custom Properties
+To enable smooth interpolation of gradient stop values, you must register the variables using `@property`. This informs the browser's engine about the data type, allowing it to transition between values during updates.
+
+```css
+/* Register the spotlight inner and outer sizes to enable interpolation */
+ @property --inner-size{
+  syntax: "<length-percentage>";
+  inherits: true;
+  initial-value: 0px;
+}
+@property --outer-size{
+  syntax: "<length-percentage>";
+  inherits: true;
+  initial-value: 0px;
+}
+```
+
+The custom properties tracking the pointer position do not need to be transitioned, so it is not required to register them.
+
+### 2. Define the Masking Layer
+Apply the `mask-image` to the element you want to reveal. Use a `radial-gradient` that references the registered properties.
+
+```css
+.reveal-layer {
+  /* Only transition the size properties, NOT the position variables */
+  transition: --inner-size 0.2s ease-in-out, --outer-size 0.2s ease-in-out;  
+
+  /* The spotlight is defined by the transparent center of the mask */
+  mask-image: radial-gradient(
+    circle at var(--mouse-x) var(--mouse-y),
+    black var(--inner-size, 0%),
+    transparent var(--outer-size, 0%)
+  );
+
+  /* Ensure the mask doesn't repeat if the element is large */
+  mask-repeat: no-repeat;
+
+  /* Make the mask layer non-interactive */
+  pointer-events: none;
+}
+
+/* Update the gradients stops on interaction */
+.reveal-layer:hover {
+  --inner-size: 100px;
+  --outer-size: 120px;
+}  
+```
+
+### 3. Update Coordinates with JavaScript
+Track the pointer position and update the CSS variables. Because the properties are registered and have a `transition` defined, the spotlight will move smoothly even if the pointer events are infrequent.
+
+```javascript
+const container = document.querySelector('.container');
+// Store the container's bounding rect
+let rect = container.getBoundingClientRect();
+// Update the rect when the container is resized
+const resizeObserver = new ResizeObserver(()=>{
+  rect = container.getBoundingClientRect();
+})
+resizeObserver.observe(container);
+
+container.addEventListener('pointermove', (e) => {
+  // Calculate position as a percentage of the container.
+  const x = ((e.clientX - rect.left) / rect.width) * 100;
+  const y = ((e.clientY - rect.top) / rect.height) * 100;
+
+  // Update the registered properties
+  container.style.setProperty('--mouse-x', `${x}%`);
+  container.style.setProperty('--mouse-y', `${y}%`);
+});
+```
+
+### 4. Accessibility and Interaction
+**MANDATORY Accessibility Guarantee:** This pattern relies on pointer interactions to reveal a visual spotlight. You MUST guarantee that all underlying content remains fully visible, legible, and independently keyboard-reachable by default in the underlying layout, using the spotlight layer purely as a non-essential visual enhancement for pointer users. Never use this effect to obscure or gate essential content from keyboard-only or assistive technology users.
+
+* **Pointer Events:** Set `pointer-events: none` on the mask overlay layer to allow standard click and touch interactions to pass through to controls underneath.
+* **Reduced Motion Override:** Disable smooth transition interpolation for users requesting reduced motion.
+
+```css
+/* MANDATORY Copy-Paste Safety: Disable transition scaling for motion-sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  .reveal-layer {
+    transition: none !important;
+  }
+}
+```
+
+## Fallback strategies
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+### Non-registered Property Fallback
+Browsers that support `mask-image` but not `@property` will still show the spotlight, but the movement will jump between on and off states because they cannot interpolate values inside a `radial-gradient`. Provide fallback values when using `var()`.
+
+```css
+.reveal-layer {
+  mask-image: radial-gradient(
+    circle at var(--mouse-x) var(--mouse-y),
+    /* Use fallback values when using the `var()` function for browsers that don't get an initial value from the @property registration. */
+    black var(--inner-size, 0%),
+    transparent var(--outer-size, 0%)
+  );
+}
+```
+
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+### Basic Mask Support
+
+For browsers that do not support CSS masking at all:
+1. **Prefixed property:** Use the `-webkit-mask-image` prefixed property for broader browser support.
+2. **Progressive Enhancement:** Design the base state of the UI to be fully functional and legible without the reveal effect. This is useful when the effect is only adds visual flair, and not a requirement for reading content.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-action-previews.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-action-previews.md
new file mode 100644
index 00000000..6fd4bff8
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-action-previews.md
@@ -0,0 +1,93 @@
+# Interest Triggered Action Previews
+
+It can be beneficial to provide users a preview of their actions before they commit to them. Interest invokers are an experimental web platform feature that provides a declarative-based way of creating interest relationships between an interest source (i.e. a button or a link) and an interest target. Once the declarative relationship has been established there are a number of methods a developer can respond to based on interest and loss of interest using both CSS and JavaScript. For this use case, we can leverage the `interest` and `loseinterest` events to preview various effects for an interest target.
+
+## How to implement
+
+An interest relationship is created by setting the `interestfor` attribute on a button or link (i.e. the interest source). The attribute takes an ID reference to another element (i.e. the interest target). Interest invokers or sources can only have a single interest target, but an interest target can have multiple interest invokers.
+
+```html
+<!-- MANDATORY: interest relationships must be established with the `interestfor` attribute on a button or a link -->
+<button interestfor="interestingElement" data-effect="A">Some effect</button>
+<button interestfor="interestingElement" data-effect="B">Some other effect</button>
+<div id="interestingElement">Something interesting</div>
+```
+
+For the sake of this use case, we can leverage the `interest` and `loseinterest` events to preview various effects for an interest target. Both of these events are `InterestEvent`s which has a `source` property which is the source of the interest (i.e. the element with the `interestfor` attribute).
+
+```javascript
+interestingElement.addEventListener("interest", event => {
+  // Apply the preview based on `event.source`
+  event.target.dataset.preview = event.source.dataset.effect;
+});
+
+interestingElement.addEventListener("loseinterest", event => {
+  // Unapply the preview
+  delete event.target.dataset.preview;
+});
+```
+
+> [!NOTE]
+> **Don't announce interest-driven previews via a live region.** Interest can be triggered just by moving the pointer across the page or tabbing through nearby buttons, so apply/unapply announcements quickly become noise that can drown out content the user actually cares about. The preview itself is the affordance; users who can perceive it benefit directly, and those who can't will not benefit from a verbal echo of "Previewing effect: A". If you decide you genuinely need an announcement for a specific case, make sure to test it carefully with users.
+
+Active interest sources and targets can be selected with CSS using the `:interest-source` and `:interest-target` pseudo-selectors respectively.
+
+```css
+/* Styles to apply when the effect is being previewed */
+:interest-source {}
+:interest-target {}
+```
+
+The start and end delay for an interest invoker (i.e. the element with the `interestfor` attribute) can be set with the `interest-delay-start` and `interest-delay-end` CSS properties or the shorthand `interest-delay` property.
+
+```css
+[interestfor] {
+  interest-delay-start: 0.2s;
+  interest-delay-end: 0.1s;
+}
+```
+
+### Fallback strategies
+
+### Fallbacks & browser support for Interest invokers
+
+Browser support for Interest invokers: Limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+Interest invokers must be conditionally polyfilled using the `interestfor` polyfill package from NPM. Prefer bundling the polyfill over using the CDN.
+
+**MANDATORY:** Feature detect by checking for the `interestForElement` property on `HTMLButtonElement.prototype`, and load the polyfill **only** when native support is missing.
+
+```html
+<script type="module">
+  if (!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")) {
+    // CDN link only used for example, prefer bundling.
+    await import("https://unpkg.com/interestfor@latest");
+  }
+</script>
+```
+
+### CSS Polyfill Caveats
+
+When using the polyfill, the CSS API changes slightly to account for the lack of native pseudo-class and property support:
+
+- **Pseudo-classes:** The polyfill cannot define real `:interest-source` and `:interest-target` pseudo-classes, so it applies `.interest-source` and `.interest-target` classes instead. **MANDATORY:** Combine them with `:is()` to support both native and polyfilled states.
+
+```css
+/* Styles to apply when the effect is being previewed */
+:is(:interest-source, .interest-source) { /* ... */ }
+:is(:interest-target, .interest-target) { /* ... */ }
+```
+
+- **CSS Properties:** For `interest-delay`, `interest-delay-start`, and `interest-delay-end`, the polyfill requires using CSS variables as it cannot read the custom properties directly in all browsers.
+
+```css
+/* Adjust the start and end delay for interest invokers */
+[interestfor] {
+  --interest-delay-start: 0.2s;
+  interest-delay-start: var(--interest-delay-start);
+  --interest-delay-end: 0.1s;
+  interest-delay-end: var(--interest-delay-end);
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-tooltips.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-tooltips.md
new file mode 100644
index 00000000..fe2f6606
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/interest-triggered-tooltips.md
@@ -0,0 +1,179 @@
+# Show a tooltip when hovering
+
+Users expect to see additional related information without completely changing their context. Showing a tooltip when a user is interested in more information can be useful to provide definitions for a term, clarifying the action an icon-only button will take, or provide additional form field guidance.
+
+## Creating the tooltip
+
+You can create a popover with the required behavior by adding the `popover="hint"` attribute to a `<div>` or other semantically appropriate element. When the user opens the tooltip, this hides other `popover="hint"` tooltips, but doesn't hide `auto` or `manual` tooltips. It also handles dismissing nested tooltips.
+
+It also provides light dismiss behavior, so when a user clicks or otherwise focuses outside of the popover, the popover is dismissed.
+
+The tooltip element must have an `id` attribute with a unique value:
+
+```html
+<!-- MANDATORY: The tooltip container `<div>` must have a `popover` attribute.
+     the value of `"hint"` ensures it can be "light dismissed". -->
+<div popover="hint" id="tooltip">Tooltip content</div>
+```
+
+A user expresses interest in the additional information by hovering or focusing on an `<a>` or `<button>` element. The element must have an `interestfor` attribute that matches the `id` attribute of the tooltip.
+
+```html
+<!-- The `interestfor` attribute can be applied to a `<button>` element: -->
+<button interestfor="tooltip">Tooltip trigger</button>
+
+<!-- The `interestfor` attribute can also be applied to an `<a>` element: -->
+<a interestfor="tooltip" href="">Tooltip trigger</a>
+```
+
+The trigger must have a visual indicator to indicate that there is additional information available by interacting with the trigger.
+
+### Accessibility built in to `interestfor`
+
+When you use `interestfor`, the browser handles the assistive-technology wiring for you:
+
+- **Implicit semantics:** A target with `popover="hint"` gains an implicit minimum role of `tooltip`. **DO NOT** set `role="tooltip"` yourself.
+- **Implicit association:** The browser implicitly associates the source element with the target via `aria-describedby` when the target is plaintext, or via `aria-details` when the target contains interactive content. **DO NOT** add `aria-describedby` or `aria-details` to the trigger.
+- **Interactive content:** Because the association switches to `aria-details` when needed, the target IS allowed to contain interactive content (e.g. a link inside an "interest card").
+
+### Accessibility Constraints (WCAG 1.4.13)
+
+Even with `interestfor` handling the semantics above, your implementation MUST still satisfy WCAG 1.4.13 (Content on Hover or Focus):
+- **Dismissible:** Users must be able to dismiss the tooltip without moving pointer hover or keyboard focus (e.g., by pressing the `Escape` key). The native `popover` attribute manages this binding automatically.
+- **Hoverable:** The pointer must be able to move over the tooltip content itself without the tooltip disappearing. This allows users with magnification tools to read the tooltip text safely.
+- **Persistent:** The tooltip must remain visible until the hover or focus trigger is removed, the user explicitly dismisses it, or its content is no longer valid.
+
+### Positioning the tooltip
+
+The tooltip is positioned using **CSS Anchor Positioning**. When the tooltip is opened using `interestfor`, the trigger element automatically becomes an **implicit anchor** for the popover.
+
+In modern browsers supporting native anchor positioning, you do **not** need to define an `anchor-name` on the trigger or a `position-anchor` on the tooltip. You can position the tooltip directly relative to its implicit anchor using `position-area` and handle collision flipping with `position-try-fallbacks`:
+
+```css
+[popover] {
+  /* Implicit anchor from interestfor: no anchor-name or position-anchor needed */
+  position-area: top;
+  position-try-fallbacks: flip-block;
+  margin: unset;
+}
+```
+
+### Fallback strategies
+
+### Fallbacks & browser support for Interest invokers
+
+Browser support for Interest invokers: Limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+Interest invokers must be conditionally polyfilled using the `interestfor` polyfill package from NPM. Prefer bundling the polyfill over using the CDN.
+
+**MANDATORY:** Feature detect by checking for the `interestForElement` property on `HTMLButtonElement.prototype`, and load the polyfill **only** when native support is missing.
+
+```html
+<script type="module">
+  if (!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")) {
+    // CDN link only used for example, prefer bundling.
+    await import("https://unpkg.com/interestfor@latest");
+  }
+</script>
+```
+
+### CSS Polyfill Caveats
+
+When using the polyfill, the CSS API changes slightly to account for the lack of native pseudo-class and property support:
+
+- **Pseudo-classes:** The polyfill cannot define real `:interest-source` and `:interest-target` pseudo-classes, so it applies `.interest-source` and `.interest-target` classes instead. **MANDATORY:** Combine them with `:is()` to support both native and polyfilled states.
+
+```css
+/* Styles to apply when the effect is being previewed */
+:is(:interest-source, .interest-source) { /* ... */ }
+:is(:interest-target, .interest-target) { /* ... */ }
+```
+
+- **CSS Properties:** For `interest-delay`, `interest-delay-start`, and `interest-delay-end`, the polyfill requires using CSS variables as it cannot read the custom properties directly in all browsers.
+
+```css
+/* Adjust the start and end delay for interest invokers */
+[interestfor] {
+  --interest-delay-start: 0.2s;
+  interest-delay-start: var(--interest-delay-start);
+  --interest-delay-end: 0.1s;
+  interest-delay-end: var(--interest-delay-end);
+}
+```
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+Browser support for popover="hint": Limited availability.
+Supported by: Chrome 151 (Jul 2026), Edge 151 (Jul 2026), and Firefox 153 (Jul 2026).
+Unsupported in: Safari.
+
+The `popover-polyfill` does not polyfill the hint behavior in browsers that support `popover` but not `popover="hint"`. For those browsers, a tooltip opened via focus may stay open when a second tooltip opened via hover.
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+To support browsers without anchor positioning, you can use the `@oddbird/css-anchor-positioning` polyfill. Alternatively, you can use `@supports` to specify a fallback position.
+
+When using the `@oddbird/css-anchor-positioning` polyfill for legacy browser support, be aware that the polyfill does not support implicit anchors or `position-area` on popovers. Explicitly set an `anchor-name` on the trigger, set `position-anchor` on the popover, and position using `anchor()` inset functions instead of `position-area`: 
+
+```html
+<!-- MANDATORY: Conditionally install the anchor positioning polyfill -->
+<script type="module">
+  if (!("anchorName" in document.documentElement.style)) {
+    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+```css
+button[interestfor="tooltip-attrs"] {
+  /* MANDATORY: Each trigger and popover pair must have a unique anchor name, referenced by `anchor-name` on the trigger and `position-anchor` on the popover. */
+  anchor-name: --tooltip-attrs;
+}
+#tooltip-attrs {
+  position-anchor: --tooltip-attrs;
+  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions, and not `position-area. */
+  top: anchor(bottom);
+  left: anchor(right);
+  margin: unset;
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/light-dismiss-a-dialog.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/light-dismiss-a-dialog.md
new file mode 100644
index 00000000..a44821ed
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/light-dismiss-a-dialog.md
@@ -0,0 +1,86 @@
+# Light-Dismiss a Dialog
+
+Modern modal dialogs often support "light-dismiss," allowing users to close a dialog by clicking or tapping the backdrop (the area outside the dialog). The `closedby` attribute provides a declarative way to enable this behavior without custom JavaScript.
+
+## Implementation
+
+To enable light-dismiss:
+
+1. Add `closedby="any"` to the `<dialog>` element.
+2. Open the dialog using `dialog.showModal()`.
+
+### Attribute Values
+
+- `any`: Enables light-dismiss (clicking the backdrop), "close requests" (the `Esc` key), and developer mechanisms (e.g., `dialog.close()`).
+- `closerequest`: Enables "close requests" and developer mechanisms only. This is the default for modal dialogs.
+- `none`: Only developer mechanisms can close the dialog.
+
+### Styling the Backdrop
+When a dialog is opened as a modal using `showModal()`, the browser generates a `::backdrop` pseudo-element. This backdrop covers the entire viewport and sits directly behind the dialog.
+
+```css
+/* Style the backdrop to indicate the dialog is modal */
+dialog::backdrop {
+  background-color: rgba(0, 0, 0, 0.5);
+  backdrop-filter: blur(2px); /* Optional: add blur for modern browsers */
+}
+```
+
+## Example
+
+```html
+<!-- MANDATORY: Use closedby="any" to enable light-dismiss behavior -->
+<dialog id="myDialog" closedby="any" aria-labelledby="dialogTitle">
+  <form method="dialog">
+    <h2 id="dialogTitle">Feedback</h2>
+    <p>Click outside this box or press Esc to dismiss.</p>
+    <button type="submit">Close</button>
+  </form>
+</dialog>
+
+<button onclick="document.getElementById('myDialog').showModal()">Open Dialog</button>
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Use `closedby="any"` to enable light-dismiss declaratively.
+- **MANDATORY**: Always open modal dialogs with `showModal()`. This ensures the dialog is in the top layer, focus is trapped, and the `Esc` key is handled.
+- **DO**: Use `aria-labelledby` or `aria-label` to provide an accessible name for the dialog.
+- **DO NOT**: Use `closedby` for non-modal dialogs (opened with `show()`), as they do not have a backdrop and won't trigger light-dismiss.
+- **DO NOT**: Use the `click` event for critical logic that should happen *before* closing; instead, listen for the `close` or `cancel` events.
+
+## Fallback strategies
+
+Browser support for <dialog closedby>: Limited availability.
+Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
+Unsupported in: Safari.
+
+**MANDATORY**: For browsers that do not yet support `closedby`, you **must** implement a fallback for light-dismiss by checking if a click occurred outside the dialog content's boundaries using the following script:
+
+```javascript
+const dialog = document.querySelector('dialog');
+
+// Fallback for browsers without closedby support
+if (!('closedBy' in HTMLDialogElement.prototype)) {
+  dialog.addEventListener('click', (event) => {
+    // 1. When clicking the backdrop, the event target is the dialog element itself.
+    // Ignore clicks where the target is a child element inside the dialog.
+    if (event.target !== dialog) return;
+
+    // 2. Check if the click coordinates fall within the dialog's content box.
+    // This distinguishes between a click on the backdrop vs a click on the dialog's background/padding.
+    const rect = dialog.getBoundingClientRect();
+    const isDialogContent = (
+      rect.top <= event.clientY &&
+      event.clientY <= rect.top + rect.height &&
+      rect.left <= event.clientX &&
+      event.clientX <= rect.left + rect.width
+    );
+
+    if (isDialogContent) return;
+
+    // 3. Since the click was outside the content area (on the backdrop), manually close the dialog.
+    dialog.close();
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/motion.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/motion.md
new file mode 100644
index 00000000..b6172631
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/motion.md
@@ -0,0 +1,102 @@
+# Motion
+
+- Use `clip-path` and `mask-image` for custom geometric reveals and smooth fade-outs.
+- Use **Scroll-Driven Animations** (`animation-timeline: scroll()`) for non-essential scroll-bound effects instead of JS listeners.
+- Use **View Transitions** to animate between complex layout states seamlessly.
+
+### Performance
+
+- Prefer to animate `opacity` and `transform` (including individual transform properties, e.g. `translate` instead of `left/right/top/bottom`) to ensure animations stay on the compositor thread.
+- Use `transition-behavior: allow-discrete`, `@starting-style`, and (for top-layer elements like `<dialog>` or `[popover]`) `overlay` to animate discrete entry and exit states natively; see `animate-element-entry-exit` (via `npx -y modern-web-guidance@latest retrieve "animate-element-entry-exit"`) and `animate-to-from-top-layer` (via `npx -y modern-web-guidance@latest retrieve "animate-to-from-top-layer"`).
+
+```css
+.popover-reveal {
+  /* Transition discrete display and top-layer overlay alongside opacity */
+  transition:
+    opacity ease-out,
+    display,
+    overlay;
+  transition-duration: 0.2s;
+  transition-behavior: allow-discrete;
+}
+```
+
+### Accessibility
+
+Use `prefers-reduced-motion` media queries to turn off heavy motion for users who prefer it.
+- **Provide Pause mechanism**: Allow users to stop auto-running carousels, banners, or other persistent animations.
+- **Default to static views**: Consider defaulting to static states and allowing users to opt-in to motion.
+- **Don't exceed flash limits (three per second)**: Never include rapid light-to-dark flashing. Such effects can cause seizures.
+
+**DO NOT** globally apply `animation-duration: 0.01ms;` as it can cause certain animations to become _more_ jarring.
+Instead, handle motion preferences on a case-by-case basis using one of two approaches, nesting the `@media` query inside the rule so both versions are kept together:
+
+- **Start with animations enabled by default, and tone them down using `@media (prefers-reduced-motion: reduce)`**:
+
+```css
+/* Good: Dampen spin states or slow down animations for reduced motion */
+.spinner {
+  animation: spin 1s linear infinite;
+  @media (prefers-reduced-motion: reduce) {
+    animation: none;
+    opacity: 0.5;
+  }
+}
+
+progress:not([value]) {
+  animation: slide 1s infinite linear;
+  @media (prefers-reduced-motion: reduce) {
+    animation-duration: 20s;
+  }
+}
+```
+
+- **Start with no animations by default, and enable them using `@media (prefers-reduced-motion: no-preference)`**:
+
+```css
+/* Good: Default to static or gentle states and opt-in to full motion */
+.spinner {
+  opacity: 0.5;
+  @media (prefers-reduced-motion: no-preference) {
+    opacity: 1;
+    animation: spin 1s linear infinite;
+  }
+}
+
+progress:not([value]) {
+  animation: slide 20s infinite linear;
+  @media (prefers-reduced-motion: no-preference) {
+    animation-duration: 1s;
+  }
+}
+```
+
+### Working with animation and transition events in JavaScript
+
+On both the `AnimationEvent` (`animationstart`, `animationiteration`, `animationend`, `animationcancel`) and `TransitionEvent` (`transitionrun`, `transitionstart`, `transitionend`, `transitioncancel`) interfaces, `event.target` gives you the originating DOM element. To access the specific `Animation` object (`Animation`, `CSSAnimation`, or `CSSTransition`) that triggered the event, use the readonly `event.animation` property.
+
+When `event.animation` is not available, you can usually find the `Animation` instance by calling `event.target.getAnimations()` and filtering by `event.animationName` (or `event.propertyName` for transitions). However, using `event.animation` directly is preferred, in order to avoid several scenarios where this fallback that filters `event.target.getAnimations()` does not work as expected:
+
+- Web Animations API (`element.animate()`) animations do not have an `animationName`, so they cannot be matched by name when filtering `event.target.getAnimations()`.
+- Filtering by `animationName` for `AnimationEvent`s is ambiguous when multiple animations with the same name are attached to the same element.
+  - Note that filtering on `transitionProperty` for `TransitionEvent`s works as there is only one event per transition property. 
+- `event.target` always points to the originating DOM element, so it does not distinguish between animations running on the element itself versus one of its pseudo-elements — whereas `event.animation.effect.pseudoElement` exposes the target pseudo-element directly.
+
+```js
+// Works in most basic CSS animation cases, but fails for WAAPI animations,
+// duplicate animation names on the same element, or pseudo-elements.
+document.addEventListener('animationstart', (event) => {
+  const animation = event.target
+    .getAnimations()
+    .find((anim) => anim.animationName === event.animationName);
+  console.log(animation);
+});
+
+// PREFERRED: Directly access the exact Animation object via event.animation
+document.addEventListener('animationstart', (event) => {
+  const animation = event.animation;
+  console.log(animation);
+});
+```
+
+You can feature-detect support using `'animation' in AnimationEvent.prototype` (or `'animation' in TransitionEvent.prototype`).
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/move-dom-element-without-losing-state.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/move-dom-element-without-losing-state.md
new file mode 100644
index 00000000..f3739fe0
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/move-dom-element-without-losing-state.md
@@ -0,0 +1,59 @@
+# Move DOM Element Without Losing State
+
+When reparenting DOM elements using traditional methods like `appendChild()` or `insertBefore()`, the browser implicitly removes the element from the DOM and then inserts it into its new location. This "remove and insert" operation resets many internal states, causing `<iframe>` elements to reload, CSS animations to restart, and input fields to lose focus.
+
+To move an element while preserving its state, use the `moveBefore()` API. This method performs an atomic move, completely bypassing the removal and insertion steps.
+
+### Moving an element with state
+
+Use `moveBefore()` exactly as you would use `insertBefore()`. It requires two arguments: the node to move, and a reference node to insert before (or `null` to append to the end of the new parent).
+
+```javascript
+const newParent = document.getElementById('new-parent');
+const elementWithState = document.getElementById('iframe-or-focused-input');
+
+// MANDATORY: Use moveBefore to preserve state. 
+// Passing null as the second argument appends the element to the end of newParent.
+newParent.moveBefore(elementWithState, null);
+```
+
+### Moving custom elements (Web Components)
+
+If you are moving custom elements using `moveBefore()`, their `connectedCallback` and `disconnectedCallback` lifecycle methods will **not** be fired.
+
+If your custom element needs to perform specific logic when moved, implement the `connectedMoveCallback()` method inside the custom element definition.
+
+```javascript
+class MyCustomElement extends HTMLElement {
+  connectedCallback() {
+    // Runs on initial insertion.
+  }
+  
+  connectedMoveCallback() {
+    // Runs when the element is moved via moveBefore().
+    // Use this to update state that depends on the new DOM location.
+  }
+}
+```
+
+### Fallback strategies
+
+Browser support for moveBefore(): Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 144 (Oct 2025).
+Unsupported in: Safari.
+
+Since `moveBefore()` is a progressive enhancement, you MUST use feature detection before calling it, falling back to traditional `insertBefore()` or `appendChild()` operations for older browsers. 
+
+```javascript
+const targetParent = document.getElementById('target-container');
+const nodeToMove = document.getElementById('moving-element');
+
+// Check if moveBefore is supported on the Element prototype
+if ('moveBefore' in Element.prototype) {
+  targetParent.moveBefore(nodeToMove, null);
+} else {
+  // Fallback: traditional move. 
+  // Note: This WILL reset <iframe>, animation, and focus state in unsupported browsers.
+  targetParent.insertBefore(nodeToMove, null);
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/parallax-scroll-effects.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/parallax-scroll-effects.md
new file mode 100644
index 00000000..3ec8e01d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/parallax-scroll-effects.md
@@ -0,0 +1,230 @@
+# Build a Parallax Effect on Scroll
+
+A parallax effect on scroll is a visual technique where different layers of content move at varying speeds as the user scrolls down a page. This creates an illusion of depth, with foreground elements appearing to move faster than the background elements, resulting in an engaging and immersive browsing experience. This effect is best achieved using CSS Scroll-Driven Animations, which allow you to link animations to the scroll position of a container.
+
+## How to implement
+
+Here’s how to create a basic parallax effect:
+
+1.  **Create a wrapper element:** This element simply groups all the layers of the parallax effect together. It is not the scrollable element, so its overflow should be clipped. Also give it a `height` that matches the height of one of the layers of the parallax effect.
+
+    ```html
+    <div class="wrapper">
+      …
+    </div>
+    ```
+
+    ```css
+    .wrapper {
+      overflow: clip;
+      height: 100vh; /* Height of one of the layers of the parallax */
+    }
+    ```
+
+2.  **Declare the layers:** Inside the wrapper, add the individual layers that will move at different speeds.
+
+    ```html
+    <div class="wrapper">
+      <div class="layer">LAYER 0</div>
+      <div class="layer">LAYER 1</div>
+      <div class="layer">LAYER 2</div>
+      …
+    </div>
+    ```
+
+3.  **Add a translate animation:** Define a CSS animation that changes the `transform` property of the layers. For a parallax effect, you'll typically use `translateY` to move the layers vertically.
+
+    ```css
+    @keyframes parallax {
+      from {
+        transform: translateY(700px);
+      }
+    }
+    ```
+
+4.  **Set up the `view-timeline`:** To link the animation to the scroll position, create a `view-timeline` on the wrapper element and then apply it to the layers.
+
+    ```css
+    .wrapper {
+      view-timeline: --wrapper;
+    }
+
+    .layer {
+      animation: parallax linear both;
+      animation-timeline: --wrapper;
+    }
+    ```
+
+5.  **Stagger the animations:** To make the layers move at different speeds, you can use one of two main approaches: **staggering in the keyframes**, or **staggering the `animation-range`**. 
+
+    Both of these approaches can use hardcoded values, or can use the `sibling-index()`/`sibling-count()` implementation. The hardcoded values are easiest and also useful when having only a limited amount of layers. The `sibling-index()`/`sibling-count()` implementation is handy when you have many layers.
+
+    *   **Staggering in the keyframes:**
+
+        Using **hardcoded values**, you can define a custom property for each layer to manually control its parallax offset.
+
+        ```css
+        .layer:nth-child(1) { --offset: 100px; }
+        .layer:nth-child(2) { --offset: 200px; }
+        .layer:nth-child(3) { --offset: 300px; }
+
+        @keyframes parallax {
+          from {
+            transform: translateY(var(--offset));
+          }
+        }
+        ```
+
+        Using **`sibling-index()`**, let the `sibling-index()` function return the index of a child element amongst its siblings to automatically calculate the staggered effect.
+
+        ```css
+        @keyframes parallax {
+          from {
+            transform: translateY(calc(100px * sibling-index()));
+          }
+        }
+        ```
+
+    *   **Staggering the `animation-range`:**
+
+        Using **hardcoded values**, you can explicitly define the boundaries of the `animation-range` on each layer individually.
+
+        ```css
+        .layer:nth-child(1) { animation-range: entry 25% exit 50%; }
+        .layer:nth-child(2) { animation-range: entry 25% exit 75%; }
+        .layer:nth-child(3) { animation-range: entry 25% exit 100%; }
+        ```
+
+        Using **`sibling-index()` and `sibling-count()`**, you can calculate the range mathematically based on the total number of layers (`sibling-count()`).
+
+        ```css
+        .layer {
+          animation-range: entry 25% exit calc(100% / sibling-count() * sibling-index());
+        }
+        ```
+
+## Example code
+
+```css
+@keyframes parallax {
+  from {
+    transform: translateY(calc(100px * sibling-index()));
+  }
+}
+
+.wrapper {
+  view-timeline: --wrapper;
+}
+
+.layer {
+  animation: parallax linear both;
+  animation-timeline: --wrapper;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .layer {
+    animation: none;
+  }
+}
+```
+
+Alternatively, you can use the `animation-range` property to achieve a similar effect:
+
+```css
+@keyframes parallax {
+  from {
+    transform: translateY(700px);
+  }
+}
+
+.wrapper {
+  view-timeline: --wrapper;
+}
+
+.layer {
+  animation: parallax linear both;
+  animation-timeline: --wrapper;
+  animation-range: entry 25% exit calc(100% / sibling-count() * sibling-index());
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .layer {
+    animation: none;
+  }
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: view()) and (animation-range: entry))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: entry)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` and `animation-range` *after* it to prevent the shorthand from resetting the timeline.
+
+As for setting the `animation-range`:
+
+- **DO** give all layers the same start offset, e.g. `entry 25%`
+- **DO** give all layers a different end offset that uses `sibling-count()` and `sibling-index()` to distribute the offsets, e.g. `exit calc(100% / sibling-count() * sibling-index())`.
+
+
+## Browser support and fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.. Therefore, a fallback strategy is typically required.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses an `IntersectionObserver` to track the visibility of the `.wrapper` element and updates the `transform` property of the layers based on the scroll position.
+
+```js
+// Fallback for browsers that don't support scroll-driven animations
+if (!CSS.supports('(animation-timeline: view()) and (animation-range: entry)')) {
+  const wrapper = document.querySelector('.wrapper');
+  const layers = document.querySelectorAll('.layer');
+
+  const observer = new IntersectionObserver((entries) => {
+    entries.forEach(entry => {
+      if (entry.isIntersecting) {
+        window.addEventListener('scroll', onScroll);
+      } else {
+        window.removeEventListener('scroll', onScroll);
+      }
+    });
+  }, { threshold: 0 });
+
+  observer.observe(wrapper);
+
+  function onScroll() {
+    const scrollY = window.scrollY;
+    const wrapperRect = wrapper.getBoundingClientRect();
+    const wrapperTop = wrapperRect.top + scrollY;
+    const wrapperHeight = wrapperRect.height;
+    const windowHeight = window.innerHeight;
+
+    if (scrollY >= wrapperTop - windowHeight && scrollY <= wrapperTop + wrapperHeight) {
+      const scrollPercent = (scrollY - (wrapperTop - windowHeight)) / (wrapperHeight + windowHeight);
+      
+      layers.forEach((layer, index) => {
+        // This matches the effect as defined in the CSS example above.
+        // Customize this further if needed.
+        const initialTranslateY = 100 * index;
+        const translateY = initialTranslateY * (1 - scrollPercent);
+        layer.style.transform = `translateY(${translateY}px)`;
+      });
+    }
+  }
+
+  // Trigger onScroll once to set initial positions
+  onScroll();
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/persistent-top-layer-ui.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/persistent-top-layer-ui.md
new file mode 100644
index 00000000..cc695f02
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/persistent-top-layer-ui.md
@@ -0,0 +1,50 @@
+# Persistent Top Layer UI
+
+When moving an open `<dialog>`, `popover`, or fullscreen element in the DOM using traditional methods like `appendChild()` or `insertBefore()`, the browser implicitly removes the element from the DOM and re-inserts it. This removal resets the state, causing open modals, popovers, and fullscreen elements to close abruptly.
+
+To reparent top-layer elements without interrupting the user experience or closing them, use the atomic `moveBefore()` API instead.
+
+### Reparenting open top-layer elements
+
+`moveBefore()` takes two arguments: the node to move, and a reference node to insert before (or `null` to append to the end of the new parent).
+
+```javascript
+const newParent = document.getElementById('new-container');
+const dialogElement = document.getElementById('my-dialog');
+
+// MANDATORY: Use moveBefore to ensure the <dialog> or popover stays open.
+// Passing null appends it to the end of newParent.
+newParent.moveBefore(dialogElement, null);
+```
+
+### Fallback strategies
+
+Browser support for moveBefore(): Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 144 (Oct 2025).
+Unsupported in: Safari.
+
+Since `moveBefore()` is a progressive enhancement, you MUST use feature detection before calling it. For older browsers, you will have to fallback to traditional reparenting.
+
+**MANDATORY**: For `<dialog>` elements in unsupported browsers, the traditional move will close the dialog. If you need it to remain open, you must manually re-open it after the move.
+
+```javascript
+const targetParent = document.getElementById('target-container');
+const popoverOrDialog = document.getElementById('my-top-layer-element');
+
+// Check if moveBefore is supported
+if ('moveBefore' in Element.prototype) {
+  targetParent.moveBefore(popoverOrDialog, null);
+} else {
+  // Fallback: traditional move.
+  // Note: This WILL close <dialog>, popover, and fullscreen elements.
+  const wasOpen = popoverOrDialog.hasAttribute('open') || popoverOrDialog.matches(':popover-open');
+  targetParent.insertBefore(popoverOrDialog, null);
+  
+  // Manually restore state if possible
+  if (wasOpen && typeof popoverOrDialog.showModal === 'function') {
+    popoverOrDialog.showModal();
+  } else if (wasOpen && typeof popoverOrDialog.showPopover === 'function') {
+    popoverOrDialog.showPopover();
+  }
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/physics-based-easing.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/physics-based-easing.md
new file mode 100644
index 00000000..e7276daa
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/physics-based-easing.md
@@ -0,0 +1,120 @@
+# Physics Based Easing
+
+Traditional CSS easing functions like `ease-in` or `cubic-bezier()` are limited to simple curves, making it impossible to create complex physics-based effects like bounces or springs. The `linear()` timing function solves this by allowing you to provide a series of stops that can approximate complex curves. Transitions and animations are interpolated based on straight lines between the stops, but within enough stops, it can appear smooth.
+
+### Implementation Steps
+
+1.  **Generate the curve stops:**
+    Manually plotting dozens of points for a spring or bounce is impractical. Use a timing function from an external library, or use a  tool to convert an existing JavaScript easing function or an SVG path into the `linear()` syntax. Optional: store these timing functions as CSS custom properties for reuse throughout your site.
+2.  **Define the timing function:**
+    Apply the generated stops to the `transition-timing-function` or `animation-timing-function` property, or through the `transition` or `animation` shorthands.
+3.  **Adjust the duration:**
+    Unlike JavaScript physics engines where duration is derived from physical properties (mass, stiffness), CSS still requires a fixed `duration`. You may need to adjust the duration to get the intended effect.
+
+### Example: Spring Easing
+
+This example shows how to use a custom `linear()` function to create a spring effect that overshoots the target value before settling.
+
+```css
+.spring {
+  /* Define the physics-based easing as a reusable variable */
+  --spring-easing: linear(0, 0.016 0.5%, 0.06 1%, 0.226 2%, 1.116 5.4%, 1.375 6.6%, 1.527 7.7%, 1.565 8.2%, 1.585 8.8%, 1.581 9.3%, 1.559 9.8%, 1.458 10.9%, 0.937 14.3%, 0.784 15.5%, 0.693 16.6%, 0.67 17.1%, 0.657 17.7%, 0.671 18.7%, 0.729 19.8%, 1.042 23.3%, 1.13 24.5%, 1.182 25.6%, 1.201 26.7%, 1.192 27.7%, 1.156 28.8%, 0.977 32.2%, 0.925 33.4%, 0.894 34.5%, 0.882 35.6%, 0.887 36.6%, 0.907 37.7%, 1.045 42.4%, 1.069 44.5%, 1.059 46.3%, 0.979 50.9%, 0.96 53.4%, 0.966 55.3%, 1.013 59.9%, 1.024 62.3%, 0.986 71.2%, 1.008 79.9%, 0.995 88.9%, 1);
+
+
+  /* Apply the easing with a duration that fits the spring's complexity */
+  /* MANDATORY: Always include a duration; linear() does not calculate it automatically */
+  transition: scale 0.8s var(--spring-easing);
+}
+
+.spring:hover {
+  scale: 1.2;
+}
+```
+### Example: Bounce Easing
+
+This example shows how to use a custom `linear()` function to create a bounce effect.
+
+```css
+.bounce {
+  /* Define the physics-based easing as a reusable variable */
+  --bounce-easing: linear(0, 0.214 14.7%, 0.386 23.7%, 0.598 31.9%, 0.999 44.7%, 0.807 52.6%, 0.762 56%, 0.747 59.4%, 0.758 62.4%, 0.793 65.6%, 0.999 77.4%, 0.961 81.2%, 0.949 84.8%, 0.956 88%, 0.993 95.5%, 1);
+
+
+  /* Apply the easing with a duration that fits the bounce's complexity */
+  /* MANDATORY: Always include a duration; linear() does not calculate it automatically */
+  transition: scale 0.4s var(--bounce-easing);
+}
+
+.bounce:hover {
+  scale: 1.2;
+}
+```
+
+### Key Considerations
+
+*   **Performance:** For the smoothest physics-based animations, apply `linear()` to properties that run on a separate thread, such as `transform` and `opacity`.
+*   **Precision vs. Payload:** While more stops result in a smoother curve, they also increase the size of your CSS. Most generators allow you to "simplify" the curve to find the optimal balance between smoothness and code size.
+*   **Avoid Opacity for Bounces:** Applying bounce easings to `opacity` can cause visually jarring flickering if the value overshoots below 0 or above 1.
+*   **Accessibility:** Complex physics-based animations can be distracting or cause motion sensitivity for some users. Always respect user preferences by reducing or disabling these animations.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .element {
+    transition: none;
+  }
+}
+```
+
+### Fallback strategies
+
+Baseline status for linear() easing: Widely available. It's been Baseline since 2023-12-11.
+Supported by: Chrome 113 (May 2023), Edge 113 (May 2023), Firefox 112 (Apr 2023), and Safari 17.2 (Dec 2023).
+
+#### CSS Fallback
+For browsers that do not support `linear()`, provide a standard easing function as a fallback. The browser will ignore the `linear()` value if it doesn't recognize it, falling back to the previous valid declaration.
+
+```css
+.element {
+  /* Fallback for older browsers (standard smooth exit) */
+  transition: transform 0.8s ease-out;
+  
+  /* Modern browsers will override with the physics-based easing */
+  transition-timing-function: linear(0, 1.1, 0.95, 1.02, 1);
+}
+```
+
+#### JavaScript Library Fallback (Motion/GSAP)
+
+Optional: If a high-fidelity physics animation is critical even in older browsers, use a JavaScript library like **Motion** (motion.dev) or **GSAP** (greensock.com) to handle the animation when `linear()` is unsupported.
+
+1.  **Detect support:** Use `CSS.supports()` to check if the browser handles the `linear()` function.
+2.  **Conditionally load/apply:** If unsupported, use the library's spring or bounce implementation.
+
+```javascript
+/* Detect if the browser supports the linear() function */
+const supportsLinearEasing = window.CSS && CSS.supports('animation-timing-function', 'linear(0, 1)');
+
+if (!supportsLinearEasing) {
+  /* 
+     Example using Motion (motion.dev) for a spring fallback.
+     This should only be initialized if native CSS support is missing.
+  */
+  import("https://cdn.jsdelivr.net/npm/motion@latest/dist/motion.js").then(({ animate, spring }) => {
+    animate(".element", { transform: "scale(1.2)" }, {
+      easing: spring({ stiffness: 100, damping: 10 })
+    });
+  });
+}
+```
+
+You can also use `@supports` in CSS for more explicit feature detection:
+
+```css
+@supports not (animation-timing-function: linear(0, 1)) {
+  .element {
+    /* Alternative experience for unsupported browsers */
+    transition-duration: 0.4s;
+    transition-timing-function: cubic-bezier(0.34, 1.56, 0.64, 1);
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/platform-controls-dismiss-dialog.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/platform-controls-dismiss-dialog.md
new file mode 100644
index 00000000..2b3bc6aa
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/platform-controls-dismiss-dialog.md
@@ -0,0 +1,40 @@
+# Platform Controls Dismiss Dialog
+
+When a modal dialog is open, users expect to use familiar controls to dismiss them: pressing the <kbd>Esc</kbd> key on a keyboard, using the back button or gesture on mobile platforms, or a dismiss gesture with assistive technologies.
+
+When the `<dialog>` element was first introduced, it could be dismissed with the <kbd>Esc</kbd> key, but not other platform controls such as a back button/gesture on mobile. With the addition of the `closedby` attribute for `<dialog>` elements, the extended behavior of responding to more platform-specific controls for close requests has been applied for `<dialog>` elements that are opened in a modal state (i.e. when opened imperatively with the `<dialog>` element’s `showModal()` method in JavaScript or declaratively with the `show-modal` invoker command). So, there is no specific change developers need to make if they are already using the `<dialog>` element.
+
+```html
+<!-- MANDATORY: must be opened with either `showModal()` with JavaScript or the `show-modal` command using declarative command invokers in order respond to close requests including platform-specific controls. -->
+<dialog aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests.</p>
+</dialog>
+```
+
+When opened in a modal state, a dialog without the `closedby` attribute responds to close requests the same as explicitly setting the `closedby` attribute to `closerequest`.
+
+```html
+<!-- This is unnecessary as it is the default behavior for modal dialogs -->
+<dialog closedby="closerequest" aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests.</p>
+</dialog>
+```
+
+If you also want “light dismiss” behavior, then you must set `closedby` to `any`:
+
+```html
+<dialog closedby="any" aria-labelledby="example">
+  <h1 id="example">Example</h1>
+  <p>Modal that can be dismissed with close requests and light dismiss.</p>
+</dialog>
+```
+
+## Fallback strategies
+
+Browser support for <dialog closedby>: Limited availability.
+Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
+Unsupported in: Safari.
+
+`<dialog>` elements opened in a modal state can already be dismissed with <kbd>Esc</kbd>, so there is no fallback necessary. There is no good way to implement close requests from mobile back button/gestures, so it is simpler to embrace this feature as a progressive enhancement, especially given that there are other inclusive means to dismiss the modal dialog. Similarly, light dismiss behavior for a `<dialog>` element using `closedby="any"` can be considered a progressive enhancement.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/prevent-page-scroll-under-modal-dialog.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/prevent-page-scroll-under-modal-dialog.md
new file mode 100644
index 00000000..93bcfbdc
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/prevent-page-scroll-under-modal-dialog.md
@@ -0,0 +1,59 @@
+# Prevent the Page Underneath a Modal Dialog from Scrolling
+
+When a `<dialog>` element is opened as a modal using `showModal()`, the browser promotes it to the top layer and marks the rest of the document inert. While that blocks pointer clicks and keyboard focus on the underlying page, it does not prevent scrolling:
+
+1. Scrolling while the pointer or touch gesture is over the `::backdrop` scrolls the page underneath.
+2. Scrolling inside the `<dialog>` chains to the underlying page once the dialog reaches its scroll boundary—or immediately if the dialog's content does not overflow.
+
+Per the CSS Overscroll Behavior specification, `overscroll-behavior` applies to **all scroll container elements**, including non-scrollable scroll containers (elements with `overflow: hidden`, or `overflow: auto` whose content does not currently overflow). By combining `overscroll-behavior: contain` on the `<dialog>` with `overflow: hidden` and `overscroll-behavior: contain` on `dialog::backdrop`, you can prevent the underlying page from scrolling using pure CSS.
+
+## Implementation
+
+### 1. Contain scroll chaining on the `<dialog>`
+
+The user-agent stylesheet sets `overflow: auto` on `<dialog>`, making it a scroll container by default. Apply `overscroll-behavior: contain` (or `none`) to `dialog:modal` (or `dialog`).
+
+### 2. Turn `::backdrop` into a scroll container and contain its scroll
+
+By default, `dialog::backdrop` has `overflow: visible`, which means it is **not** a scroll container and ignores `overscroll-behavior`. You must set `overflow: hidden` on `dialog::backdrop` to make it a non-scrollable scroll container, and pair it with `overscroll-behavior: contain` so scroll gestures performed over the backdrop are trapped and do not reach the document underneath.
+
+## Example Code
+
+```css
+dialog:modal {
+  /* MANDATORY: Prevent scroll gestures inside the modal (even when its content
+     does not overflow) from chaining to the underlying page. */
+  overscroll-behavior: contain;
+}
+
+dialog::backdrop {
+  /* MANDATORY: ::backdrop defaults to overflow: visible (not a scroll container).
+     Set overflow: hidden so it becomes a non-scrollable scroll container that
+     honors overscroll-behavior. */
+  overflow: hidden;
+  overscroll-behavior: contain;
+}
+```
+
+## Best Practices & Constraints
+
+- **MANDATORY**: Set `overscroll-behavior: contain` on the `<dialog>` element itself (using the `dialog:modal` selector) and the `dialog::backdrop`. Without this declaration, scroll gestures over the backdrop or inside the dialog will still chain to the page.
+- **MANDATORY**: Set `overflow: hidden` (or `overflow: auto`) on `dialog::backdrop` so that it becomes a scroll container. Without this declaration `::backdrop` defaults to `overflow: visible` and `overscroll-behavior` will have no effect.
+- **DO NOT** use `overflow: clip` or `overflow: visible` on `dialog::backdrop` or `dialog`. Neither value establishes a scroll container, so `overscroll-behavior` will not apply.
+- **DO NOT** apply `overflow: hidden` or `position: fixed` to `<html>` or `<body>` to lock background scrolling when a dialog opens. Mutating root overflow removes the page scrollbar (causing horizontal layout shift), can reset or jump the page scroll position, and can break `position: sticky` elements on the underlying page.
+
+## Fallback Strategies
+
+Browser support for overscroll-behavior: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 150 (Apr 2026).
+Unsupported in: Safari.
+
+While the `overscroll-behavior` CSS property is supported across all major browsers for scroll containers that have overflowing content, respecting `overscroll-behavior` on **non-scrollable** scroll containers is a newer specification that cannot be feature detected.
+
+**DO NOT** attempt to feature-detect non-scrollable container support with `@supports (overscroll-behavior: contain)` or `CSS.supports('overscroll-behavior', 'contain')`. All modern browsers support the `overscroll-behavior: contain` property syntax and return `true`, even if they only enforce it when content overflows.
+
+Instead, treat scroll containment on non-scrollable scroll containers as a **progressive enhancement**:
+
+- In browsers that support `overscroll-behavior` on non-scrollable scroll containers, background page scrolling is completely prevented both over `dialog::backdrop` and inside the `<dialog>` (whether or not its content overflows).
+- In browsers that do not yet support `overscroll-behavior` on non-scrollable scroll containers, `overscroll-behavior: contain` on `dialog` still prevents scroll chaining whenever the dialog's own content overflows and is scrollable. Meanwhile, `showModal()` still traps keyboard focus and marks the background document `inert`.
+- Relying on progressive enhancement is recommended over legacy workarounds that apply `overflow: hidden` or `position: fixed` to `<html>` or `<body>`, because it does not remove the root scrollbar, cause horizontal layout shifts, jump the page scroll position, or break `position: sticky` elements on the underlying page.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/same-document-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/same-document-transitions.md
new file mode 100644
index 00000000..07308918
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/same-document-transitions.md
@@ -0,0 +1,177 @@
+# Same Document Transitions
+
+## The Problem
+
+Web sites often provide multiple views of an object, for instance a list of products, and then a detail page for each product. Navigating between the two views often feels disconnected. When a user clicks a product thumbnail to view its details, the thumbnail disappears and a new, larger image appears instantly elsewhere on the screen. This lack of continuity makes it harder for users to track relationships between elements.
+
+## The Solution
+
+The **View Transitions API** allows you to specify element pairs that exist in different states before and after a transition. When triggering a transition with `document.startViewTransition()` in a Single Page Navigation (SPA), the browser identifies these shared elements by their shared unique `view-transition-name`. It then automatically calculates the difference in their position, size, and styling, and animates them smoothly from the old state to the new state. This transition occurs in the top layer, above even elements with high `z-index` values.
+
+## Implementation Guide
+
+### Step 1: Wrap State Changes in `startViewTransition`
+
+For Single-Page Applications (SPAs) or simple state changes, wrap the logic that updates the DOM in `document.startViewTransition`. The browser captures a snapshot of the current state, runs the update, and then captures the new state. 
+
+```javascript
+function navigate(view) {
+  // MANDATORY: Wrap the update in startViewTransition
+  document.startViewTransition(() => updateDOM(view));
+}
+```
+
+### Step 2: Assign Shared Transition Names
+
+Use the `view-transition-name` CSS property to tell the browser which elements should be morphed. The name can be anything (except `none`). **MANDATORY**: there must be no more than 1 element before and after with a given `view-transition-name`. If there are 2 or more elements with a given `view-transition-name`, the DOM will be updated to the new state immediately, without a transition.
+
+You can use multiple `view-transition-name`s to morph multiple pairs of elements. For example, you may want to transition both the product image and title with separate transitions.
+
+Because there are multiple items on the list view, you can not give the all of them the same `view-transition-name`. This can be solved in two ways in a SPA.
+
+1. **Dynamic detail page:** Assign each item on the list page a unique `view-transition-name`, and then dynamically apply that name to the matching element on the detail page when the list item is selected, as shown here.
+
+```css
+/* In the list view, give each */
+#product-1 { view-transition-name: p1 }
+#product-2 { view-transition-name: p2 }
+#product-3 { view-transition-name: p3 }
+```
+
+```js
+function updateDOM(clickedTransitionName){
+  const hero = document.getElementById("hero");
+  hero.style.viewTransitionName = clickedTransitionName;
+}
+```
+
+2. **Dynamic list item:** Assign the element on the detail page a `view-transition-name`, and apply that name to the item on the list page when it is selected. Remove the `view-transition-name` from the item on the list page when returning to the list page.
+
+The `#hero` element on the detail page and the selected `.thumbnail` element on the list page share a `view-transition-name`. 
+
+```css
+#hero{
+  view-transition-name: hero;
+}
+.thumbnail.selected {
+  view-transition-name: hero;
+}
+```
+
+When a thumbnail is clicked, we need to prepare the list view by assigning the `view-transition-name` using the `.selected` class selector, and making any changes to the DOM before starting the transition.
+
+Then, you can call `document.startViewTransition()`, and apply the changes to transition the page from the detail to list view.
+
+After navigating back to the list view, you must clean up the view transition classes to prevent the next navigation from erroring. You can perform this cleanup after the transition's `finished` promise resolves.
+
+```javascript
+// Function called when a thumbnail is clicked
+function goFromListToDetail(e){
+  e.currentTarget.classList.add("selected");
+  const hero = document.getElementById("hero");
+  const bgColor = getComputedStyle(e.currentTarget).backgroundColor;
+  hero.style.background = bgColor;
+
+  // Trigger the transition, checking for support
+  if (!document.startViewTransition) {
+    document.body.classList.add("detail");
+    // MANDATORY Accessibility Routing: Route focus to the newly revealed heading to announce context and preserve logical tab flow
+    document.getElementById("detail-heading")?.focus();
+    return; // MANDATORY: End function execution if view transitions are not supported.  
+  }
+  const transition = document.startViewTransition(() => {
+    document.body.classList.add("detail");
+  });
+  // MANDATORY Accessibility Routing: Route focus after the view transition resolves
+  transition.finished.finally(() => {
+    document.getElementById("detail-heading")?.focus();
+  });
+}
+
+// Function called when navigating from detail back to list view
+function goFromDetailToList() {
+  if (!document.startViewTransition) {
+    document.body.classList.remove("detail");
+    document.getElementById("list-heading")?.focus();
+    return;
+  }
+  const transition = document.startViewTransition(() => {
+    document.body.classList.remove("detail");
+  });
+  // Clean up the list view and route focus
+  transition.finished.finally(() => {
+    // Route focus back to list view
+    document.getElementById("list-heading")?.focus();
+    // Remove selected classList to remove view-transition-names
+    document.querySelectorAll(".selected").forEach(
+      (element) => {
+        element.classList.remove("selected");
+      },
+    );
+  });
+}
+```
+
+The method you choose will depend on the use case. The dynamic list item requires less repeated CSS, but more manual JavaScript cleanup.
+
+
+### Step 3: Fix Aspect Ratio "Stretching"
+
+By default, the browser cross-fades the old and new snapshots within a group that stretches to fit both. If you are transitioning text, set the width of the text element to `fit-content` on both the old and new views, so that the transitioned element's aspect ratio is stable.
+
+```css
+#list-page .title {
+  width: fit-content;
+}
+
+#detail-page #title {
+  width: fit-content;
+}
+```
+
+If you are transitioning elements that change aspect ratio, you may need to set the height of the old and new pseudo-elements to 100% of the `::view-transition-pair()` pseudo-element.
+
+```css
+::view-transition-old(hero),
+::view-transition-new(hero){
+  height: 100%;
+}
+```
+
+The pseudo-elements are snapshots of the live elements, so you can also use `object-fit` and `object-position` declarations for more control of the transitioning effect.
+
+## Best Practices
+
+-   **DO NOT** specify too many transitions. Only use shared elements for primary content that the user is actively tracking (e.g., hero images, headings).
+-   **DO** remove temporary `view-transition-name` values after the transition finishes to avoid side effects on future transitions.
+-   **DO NOT** transition elements with active animations. View transitions operate on snapshots, so any animations will appear to be paused during the view transition.
+-   **DO** respect user preferences for reduced motion using the `prefers-reduced-motion` media query.
+-   **MANDATORY Accessibility Routing**: View transitions morph page layouts dynamically but do not manage programmatic focus. If focus remains on an element that is hidden or removed during the transition, focus is abandoned, leaving keyboard and assistive technology users without context. Shift focus programmatically to an updated page heading or view container (using `tabindex="-1"`) immediately after the DOM updates or when the view transition's `finished` promise resolves.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+## Fallback Strategies
+
+Baseline status for View transitions: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 144 (Oct 2025), and Safari 18 (Sep 2024).
+
+The View Transitions API is designed for progressive enhancement. Browsers that do not support it will simply execute the DOM update immediately without animation.
+
+```javascript
+function navigate(){
+  if (!document.startViewTransition) {
+    // Fallback: Just update the DOM
+    updateDOM();
+  } else {
+    document.startViewTransition(() => updateDOM());
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scoped-component-transitions.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scoped-component-transitions.md
new file mode 100644
index 00000000..5b33125f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scoped-component-transitions.md
@@ -0,0 +1,229 @@
+# Scoped Component Transitions
+
+Starting a view transition with `document.startViewTransition()` attaches the `::view-transition` overlay to the `:root` element, which blocks pointer events on the rest of the page, prevents concurrent transitions, and obscures `position: fixed` headers or open `[popover]` elements (even when nested view transition groups are used to prevent overflow bleeding).
+
+Calling `element.startViewTransition()` on a component root addresses this by scoping the transition to that DOM subtree: the `::view-transition` pseudo-element tree is injected directly onto the element, preserving external stacking contexts and page interactivity while allowing multiple components to transition concurrently.
+
+## Implementation
+
+### 1. Trigger a Scoped Transition
+
+Call `element.startViewTransition()` on the component's root container element instead of `document.startViewTransition()`. The element you call `startViewTransition()` on becomes the transition's scope (the scope element): only elements within its subtree are captured, only rendering of the scope halts during the update callback, and the resulting `::view-transition` overlay matches the scope element's size, shape, and stacking context.
+
+### 2. Name Participating Elements
+
+Assign a `view-transition-name` to child elements inside the scope that should animate. You can use `view-transition-name: match-element` on dynamic list items to automatically derive each element's transition name from its DOM node identity, or assign explicit names (which only need to be unique within that scope).
+
+Names are isolated within each scope, preventing collisions across components in different parts of the DOM. However, `view-transition-name`s can collide with names in nested scoped view transitions. To prevent this, add `view-transition-scope: all` to the child scope element.
+
+### 3. Self-Participation and Overflow Clipping
+
+The scope element automatically participates in its own view transition because the user-agent stylesheet applies `view-transition-name: root` and `view-transition-group: contain` to it. This way, when the scope’s geometry is affected by the change you make in the DOM, it smoothly animates its own geometry alongside its children, as part of the View Transition.
+
+When the scope clips its overflow (`overflow: hidden`, `scroll`, or `clip`), `::view-transition-group-children(root)` automatically applies `overflow: clip`, preventing transitioning children from bleeding outside the component bounds.
+
+> **Note:** Automatic overflow clipping only applies to the scope element itself (`root`). If a captured element inside the scope clips its own overflow and contains other nested captured elements (for example, a scrollable or clipped `<ul>` inside a `.card`), use Nested View Transition Groups so those nested elements stay clipped to their outer captured container:
+>
+> ```css
+> .card ul {
+>   height: 200px;
+>   overflow-y: auto;
+>   view-transition-name: match-element;
+>   view-transition-group: contain;
+>   view-transition-class: list;
+> }
+>
+> ::view-transition-group-children(.list) {
+>   overflow: clip;
+> }
+> ```
+
+### 4. Concurrent and Nested Transitions
+
+Separate component subtrees can run `element.startViewTransition()` concurrently without skipping each other. Active scopes automatically receive `view-transition-scope: all` in the UA stylesheet so internal `view-transition-name` values do not leak into outer transitions. Apply `view-transition-scope: all` in CSS on repeated component containers to prevent outer transitions from capturing internal names even when the component is idle.
+
+If an outer transition needs to move a component while its inner transition is active, assign a `view-transition-name` to an element wrapping the inner scope. The outer transition then captures and animates only the wrapper instead of the inner scope element, allowing the inner transition to run to completion.
+
+## Example
+
+No CSS is needed on the scope element itself (`.card` or `.card ul`) to establish the scope—the scope is determined by calling `startViewTransition()` on the element instead of `document` (if the component will be nested inside an outer view transition, see [Running an outer transition](#running-an-outer-transition) for `view-transition-scope: all`).
+
+```css
+/* 1. Name participating child items */
+.card ul li {
+  view-transition-name: match-element;
+}
+
+/* 2. OPTIONAL: Customize transition timing (300ms is an example duration) */
+::view-transition-group(*) {
+  animation-duration: 300ms;
+  animation-timing-function: ease-in-out;
+}
+
+/* 3. MANDATORY: Respect user preference for reduced motion */
+@media (prefers-reduced-motion: reduce) {
+  ::view-transition-group(*),
+  ::view-transition-old(*),
+  ::view-transition-new(*) {
+    animation: none !important;
+  }
+}
+```
+
+```javascript
+// 1. Trigger a transition scoped to a single component subtree
+function runScopedTransition(scopeEl, updateDOM) {
+  // MANDATORY: Call startViewTransition on the component element, not document
+  const transition = scopeEl.startViewTransition(() => {
+    updateDOM();
+  });
+
+  // Re-triggering startViewTransition() on the same element skips the active transition
+  // and rejects `ready`. Catch the rejection to avoid unhandled promise rejection errors.
+  transition.ready.catch(() => {});
+}
+
+// 2. Reorder items by moving existing DOM nodes (required for `match-element`)
+// Scope to `listEl` since only the list order changes, keeping controls outside `listEl` interactive
+function reorderItems(listEl, orderedIds) {
+  const existing = new Map(
+    Array.from(listEl.children, (li) => [li.dataset.id, li]),
+  );
+
+  runScopedTransition(listEl, () => {
+    for (const id of orderedIds) {
+      const li = existing.get(id);
+      if (li) listEl.appendChild(li);
+    }
+  });
+}
+
+// 3. Remove an item while preserving exit animation and keyboard focus
+// Scope to the outer `cardEl` so the card itself also transitions its height change
+function removeItem(cardEl, itemEl) {
+  const hadFocus = itemEl.contains(document.activeElement);
+  const nextFocusTarget =
+    itemEl.nextElementSibling?.querySelector('button') ??
+    itemEl.previousElementSibling?.querySelector('button') ??
+    cardEl.querySelector('button');
+
+  runScopedTransition(cardEl, () => {
+    itemEl.remove();
+    if (hadFocus) {
+      nextFocusTarget?.focus();
+    }
+  });
+}
+```
+
+## Running an outer transition
+
+When starting a view transition outside of the intended scope (e.g. from a parent component, or from the document for a page-level transition), the outer transition will capture and animate the scope element and everything inside it.
+
+To prevent this from happening, wrap the scope element in a separate wrapper element with its own `view-transition-name`, and apply `view-transition-scope: all` to the inner scope element. This allows the wrapper itself to be captured and animated by the outer transition while preventing the inner scope's contents from being captured.
+
+```html
+<div class="page" id="page">
+  <div class="card-wrapper">
+    <section class="card" id="left">
+      <h2>Card A</h2>
+      <ul id="left-list">
+        <li>…</li>
+      </ul>
+    </section>
+  </div>
+  <div class="card-wrapper">
+    <section class="card" id="right">
+      <h2>Card B</h2>
+      <ul id="right-list">
+        <li>…</li>
+      </ul>
+    </section>
+  </div>
+</div>
+```
+
+```javascript
+document.querySelector('#page').startViewTransition(() => {
+  // do your DOM updates here...
+});
+```
+
+```css
+/* Apply a view-transition-name on the wrapper */
+.card-wrapper {
+  view-transition-name: match-element;
+}
+
+/* Prevent the contents of the card being captured by an outer transition */
+.card {
+  view-transition-scope: all;
+}
+
+.card ul li {
+  view-transition-name: match-element;
+}
+```
+
+Alternatively, you can allow the outer transition to capture the children. In order to retain clipping effects, resort to using Nested View Transition Groups to clip the captured children at the boundaries of their wrapper. In that case, though, you need to manually apply the `clip` onto the resulting `::view-transition-group-children()` pseudo.
+
+```css
+.card-wrapper {
+  overflow: clip;
+  view-transition-name: match-element; /* Capture me as part of the outer VT */
+  view-transition-group: contain; /* Nest children that also have a view-transition-name */
+  view-transition-class: card; /* For targeting purposes */
+}
+
+/* Manually copy back the clip onto the ::view-transition-group-children pseudo */
+::view-transition-group-children(.card) {
+  overflow: clip;
+}
+
+.card ul li {
+  view-transition-name: match-element;
+}
+```
+
+## Constraints & Accessibility
+
+- **MANDATORY**: Call `startViewTransition()` on the component root element rather than `document` so external `position: fixed` elements and `[popover]` overlays remain layered on top and the rest of the page stays interactive.
+- **MANDATORY**: Preserve and move existing DOM nodes (rather than recreating them with `innerHTML`) when using `view-transition-name: match-element`, as `match-element` tracks DOM node identity.
+- **MANDATORY**: Respect user preferences for reduced motion using `@media (prefers-reduced-motion: reduce)` by setting `animation: none !important` on `::view-transition-group(*)`, `::view-transition-old(*)`, and `::view-transition-new(*)`.
+- **MANDATORY**: Preserve keyboard focus when removing a focused element during a transition by shifting focus to an adjacent item or control inside the update callback.
+- **DO**: Use Nested View Transition Groups (`view-transition-group: contain` and `overflow: clip` on `::view-transition-group-children()`) when a captured element inside the scope clips its own overflow and contains nested captured elements.
+- **DO**: Attach `transition.ready.catch(() => {})` when rapid interactions can re-trigger `element.startViewTransition()` on the same scope element.
+- **DO**: Wrap an inner scope element in a separate named wrapper element if an outer transition needs to animate the component's position while an inner transition is running.
+- **DO NOT**: Set `view-transition-name: none` on a scope element that clips its overflow (`overflow: hidden`, `scroll`, or `clip`) or changes its own geometry, as opting out of self-participation disables automatic overflow clipping.
+
+## Fallback strategies
+
+Browser support for Element-scoped view transitions: Limited availability.
+Supported by: Chrome 147 (Apr 2026) and Edge 147 (Apr 2026).
+Unsupported in: Firefox and Safari.
+
+Baseline status for View transitions: Newly available. It's been Baseline since 2025-10-14.
+Supported by: Chrome 111 (Mar 2023), Edge 111 (Mar 2023), Firefox 144 (Oct 2025), and Safari 18 (Sep 2024).
+
+If your Baseline target does not support element-scoped view transitions, degrade gracefully by running the DOM update callback immediately without animation. While you could fall back to `document.startViewTransition()` this is not recommended for isolated component updates, as a document-scoped transition blocks concurrent component transitions and obscures `position: fixed` and `[popover]` elements in the top layer.
+
+```javascript
+// Feature detect specifically on Element.prototype (not document.startViewTransition)
+const supportsScopedTransition = 'startViewTransition' in Element.prototype;
+
+function runWithTransition(scopeEl, updateDOM) {
+  if (!supportsScopedTransition) {
+    // Fallback: apply the DOM update immediately without animation
+    updateDOM();
+    return;
+  }
+
+  const transition = scopeEl.startViewTransition(() => {
+    updateDOM();
+  });
+
+  transition.ready.catch(() => {});
+}
+```
+
+If you really need to have a fallback using `document.startViewTransition()`, you’ll need to make sure that clipping effects of containers are preserved, as detailed in the [Running an outer transition](#running-an-outer-transition) section. Note that this fallback approach breaks the ability to run multiple view transitions concurrently and will obscure `position: fixed` and `[popover]` elements in the top layer.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-completion-effects.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-completion-effects.md
new file mode 100644
index 00000000..3c1ff744
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-completion-effects.md
@@ -0,0 +1,97 @@
+# Triggering Effects After Programmatic Scrolling Completes
+
+When programmatically scrolling to a section or element (especially with `behavior: 'smooth'`), triggering a follow-up action immediately—such as flashing a highlight state, starting an entry animation, or moving focus—causes the effect to run while the target is still off-screen or mid-scroll.
+
+Previously, developers had to guess the scroll duration with `setTimeout()` (which fires too early on long scrolls and too late on short ones) or manually wrap a `scrollend` event listener in a `Promise` with a fallback timer (because `scrollend` does not fire when the target is already in view and no scrolling occurs).
+
+The programmatic scroll methods on `Element` (`scrollIntoView()`, `scroll()`, `scrollTo()`, `scrollBy()`) and `Window` (`scroll()`, `scrollTo()`, `scrollBy()`) return a `Promise` that resolves when the scroll operation completes. If the target is already at the requested scroll position and no scrolling is needed, the returned `Promise` resolves immediately without hanging.
+
+## Implementation
+
+1. **Mark the handler as `async`**: Use an `async` function for the event listener or navigation handler that triggers the scroll.
+2. **Await the scroll method directly**: Call `await element.scrollIntoView({ behavior: 'smooth', ... })` (or `await element.scrollTo(...)`, `await window.scrollTo(...)`, etc.). Execution pauses until the browser finishes the scroll animation and the scroll position settles.
+3. **Apply the post-scroll effect**: Toggle the highlight class, start the animation, or move focus after the `await` expression completes.
+
+## Interrupted Scrolls & Focus Management
+
+- **Handling rapid / interrupted scrolls**: If a new scroll starts on the same scroll container before an ongoing smooth scroll finishes, the browser aborts the ongoing smooth scroll and **resolves** (does not reject) all pending scroll promises on that container. If you need to suppress the post-scroll effect for superseded scrolls when a user clicks rapidly, track an incrementing operation ID and return early after `await` if a newer scroll was started:
+
+```javascript
+let currentScrollId = 0;
+const sections = document.querySelectorAll('section');
+
+async function scrollToAndHighlight(targetElement) {
+  const scrollId = ++currentScrollId;
+  sections.forEach((sec) => sec.classList.remove('highlight'));
+
+  await targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+
+  // Abort follow-up effect if another scroll was triggered while awaiting
+  if (scrollId !== currentScrollId) return;
+
+  targetElement.classList.add('highlight');
+}
+```
+
+- **Focusing the target after scrolling**: When moving keyboard focus to the target element (or a heading inside it with `tabindex="-1"`) after `await targetElement.scrollIntoView(...)`, pass `{ preventScroll: true }` to `focus()` so the focus call does not initiate a second, competing scroll:
+
+```javascript
+await targetElement.scrollIntoView({ behavior: 'smooth', block: 'center' });
+targetHeading.focus({ preventScroll: true });
+```
+
+## Constraints & Best Practices
+
+- **MANDATORY**: Await the `Promise` returned directly by `scrollIntoView()`, `scroll()`, `scrollTo()`, or `scrollBy()` rather than guessing scroll durations with `setTimeout()`.
+- **DO NOT** wrap `scrollend` in a manual `new Promise()` as your primary implementation—`scrollend` does not fire when the target is already in view and no scroll distance is traveled, whereas scroll method promises resolve automatically in that case.
+- **DO**: Pass `{ preventScroll: true }` when calling `.focus()` after awaiting a scroll method so the browser does not jump or scroll a second time.
+- **DO**: Guard post-scroll effects with a request token if rapid user interactions can trigger overlapping smooth scrolls on the same container, since interrupting a smooth scroll resolves (rather than rejects) the previous promise.
+- **Known Chrome bug with the root scroller**: Chrome has a bug where the `Promise` returned by `scrollIntoView()` resolves too early when it is the document's root scroller that is scrolling. Awaiting a `scrollIntoView()` on a nested scroll container works as expected. Do not wrap your content in a scroll container, such as `div` with `overflow-y: auto`, as a workaround for this bug.
+
+## Fallback strategies
+
+Browser support for Scroll method promises: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+In browsers that do not support scroll method promises, `scrollIntoView()`, `scroll()`, `scrollTo()`, and `scrollBy()` return `undefined` instead of a `Promise`.
+
+- **Progressive enhancement (default `await` behavior)**: Because `await undefined` is valid JavaScript that resolves immediately on the next microtask, writing `await element.scrollIntoView({ behavior: 'smooth' })` will not throw an error in unsupported browsers. Instead, it degrades gracefully by running the post-scroll code as soon as the scroll begins. For non-critical visual flourishes like a temporary highlight, this is often sufficient.
+- **Faithful fallback (`scrollend` + timeout)**: If your Baseline target does not support `scroll-promises` and the post-scroll action must wait until scrolling finishes in older browsers, check whether the return value is a `Promise` (`result instanceof Promise`). When it is `undefined`, wait for the `scrollend` event on the scroll container with a short fallback timeout in case the element is already in view and no scrolling occurs:
+
+```javascript
+function scrollIntoViewAsync(element, options, scroller = window) {
+  const result = element.scrollIntoView(options);
+
+  // Feature detect: in supporting browsers, scrollIntoView() returns a Promise
+  if (result instanceof Promise) {
+    return result;
+  }
+
+  // Fallback for browsers where scrollIntoView() returns undefined
+  return new Promise((resolve) => {
+    let timeoutId;
+
+    const finish = () => {
+      clearTimeout(timeoutId);
+      scroller.removeEventListener('scrollend', finish);
+      scroller.removeEventListener('scroll', onScroll);
+      resolve();
+    };
+
+    const onScroll = () => {
+      // Restart the idle timer on every scroll event. If scrollend never fires
+      // (browsers without scrollend support), this resolves once scrolling goes idle.
+      clearTimeout(timeoutId);
+      timeoutId = setTimeout(finish, 100);
+    };
+
+    scroller.addEventListener('scrollend', finish, { once: true });
+    scroller.addEventListener('scroll', onScroll, { passive: true });
+
+    // If no scroll event fires within the idle window (e.g., already in view), resolve.
+    // 100ms is an example value; it only needs to exceed the gap between scroll events.
+    timeoutId = setTimeout(finish, 100);
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-entry-exit-effects.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-entry-exit-effects.md
new file mode 100644
index 00000000..67b74d30
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-entry-exit-effects.md
@@ -0,0 +1,173 @@
+# Add entry and exit effects to elements as they enter or exit the scrollport
+
+Entry and exit effects are animations that are triggered when an element enters or leaves the viewport. This can be used to create engaging and dynamic user experiences. For example, you can use an entry effect to fade in an element as it scrolls into view, or an exit effect to scale it down as it scrolls out of view.
+
+## How to implement
+
+To add entry and exit effects to an element, you need to combine a few CSS properties. Here’s a step-by-step guide:
+
+1.  **Create separate `@keyframes` for the entry and exit animations.** The entry animation will be applied as the element enters the viewport, and the exit animation will be applied as it leaves.
+
+    ```css
+    @keyframes slide-in {
+      from { transform: translateX(-100%); }
+    }
+    @keyframes slide-out {
+      to { transform: translateX(100%); }
+    }
+    ```
+
+2.  **Attach the entry and exit keyframes to the element.** You can do this by defining multiple animations in the `animation` property.
+
+    -   Give the entry animation an `animation-fill-mode` of `backwards` so that it applies its initial state before the animation starts.
+    -   Give the exit animation an `animation-fill-mode` of `forwards` so that it maintains its final state after the animation is complete.
+
+    ```css
+    .animated-element {
+      animation:
+        slide-in 1s linear backwards,
+        slide-out 1s linear forwards;
+    }
+    ```
+
+3.  **Create a View Timeline and link it to the animations.** A View Timeline is a type of timeline that is linked to the visibility of an element in the viewport. You can create one using the `view()` function and then apply it to your animations using the `animation-timeline` property.
+
+    ```css
+    .animated-element {
+      animation-timeline: view();
+    }
+    ```
+
+    By default, `view()` tracks the element on the `block` axis. If you need to track it on the `inline` axis, you can use `view(inline)`.
+
+4.  **Limit the animations to the `entry` and `exit` ranges.** The `animation-range` property allows you to specify which part of the timeline an animation should run on.
+
+    -   The `entry` range covers the time from when the element first enters the viewport until it is fully visible.
+    -   The `exit` range covers the time from when the element starts to leave the viewport until it is completely hidden.
+
+    ```css
+    .animated-element {
+      animation-range: entry, exit;
+    }
+    ```
+
+## Example code
+
+This code animates the direct children of the scroller on scroll using an **anonymous view-timeline**:
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @supports ((animation-timeline: view()) and (animation-range: entry)) {
+    @keyframes grow {
+      from {
+        scale: 0.5;
+      }
+    }
+    @keyframes shrink {
+      to {
+        scale: 0.5;
+      }
+    }
+
+    .scroller > * {
+      animation:
+        grow auto linear backwards,
+        shrink auto linear forwards;
+      animation-timeline: view(inline);
+      animation-range: entry, exit;
+    }
+  }
+}
+```
+
+As the elements enter the scrollport the `grow` animation is played, and as they leave the scrollport the `shrink` animation is played.
+
+The following code has the same visual outcome, but animates the direct children of the scroller on scroll using an **named view-timeline**:
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  @supports ((animation-timeline: view()) and (animation-range: entry)) {
+    @keyframes grow {
+      from {
+        scale: 0.5;
+      }
+    }
+    @keyframes shrink {
+      to {
+        scale: 0.5;
+      }
+    }
+
+    .scroller > * {
+      view-timeline: --tl inline;
+      animation:
+        grow auto linear backwards,
+        shrink auto linear forwards;
+      animation-timeline: --tl;
+      animation-range: entry, exit;
+    }
+  }
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: view()) and (animation-range: entry))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: entry)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` *after* it to prevent the shorthand from resetting the timeline.
+
+When using the `view()` function to create a scroll-driven animation:
+
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `view(block)` or `view(inline)`.
+- When the animation is not applied to the tracked subject itself, use a named view timeline.
+
+When using the `view-timeline` property to create a scroll-driven animation:
+
+- **DO** use a CSS `<dashed-ident>` for the name.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `view-timeline-axis`.
+- **DO** make sure the scope of the lookup works: When the element that is declaring the `view-timeline` is not a flat tree ancestor of the animated element, hoist up the visibility of the `view-timeline`’s name by using `timeline-scope` on a shared ancestor.
+
+Prefer a named `view-timeline` when multiple elements or children of the tracked subject need to animate.
+
+## Browser support and fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.. Therefore, a fallback strategy is typically required.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses an `IntersectionObserver` to track the visibility of the `.wrapper` element and updates the `transform` property of the layers based on the scroll position.
+
+```html
+<script>
+  if (!CSS.supports('(animation-timeline: view()) and (animation-range: entry)')) {
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          // This matches the effect as defined in the CSS example above.
+          // Customize this further if needed.
+          entry.target.style.scale = 0.5 + entry.intersectionRatio * 0.5;
+        }
+      },
+      {
+        threshold: Array.from({ length: 101 }, (_, i) => i / 100),
+      }
+    );
+
+    document.querySelectorAll('.scroller > *').forEach((el) => {
+      observer.observe(el);
+    });
+  }
+</script>
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-realtime-feedback.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-realtime-feedback.md
new file mode 100644
index 00000000..f5ee4032
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-realtime-feedback.md
@@ -0,0 +1,156 @@
+# Scroll Snap Real-Time Feedback
+
+## Overview
+Users expect immediate visual feedback when interacting with UI elements like carousels or galleries. Traditional scroll snap only provides feedback *after* the scroll gesture completes and the element settles. By using Scroll Snap Events, specifically `scrollsnapchanging`, you can provide real-time feedback during the scroll gesture, highlighting the pending snap target before the user releases their touch or mouse.
+
+## Implementation
+
+### 1. Listen for `scrollsnapchanging`
+Attach an event listener for `scrollsnapchanging` to the scroll container. This event fires when the browser determines a new snap target is likely to be selected.
+
+```javascript
+const container = document.querySelector('#gallery');
+const thumbnails = document.querySelectorAll('.thumbnail');
+const items = document.querySelectorAll('.gallery-item');
+
+container.addEventListener('scrollsnapchanging', (event) => {
+  // Highlight pending snap target during scroll for real-time feedback.
+  const pendingTarget = event.snapTargetInline;
+  const index = [...items].indexOf(pendingTarget);
+
+  if (index === -1 || !thumbnails[index]) return;
+
+  // Use lightweight class toggle to avoid layout thrashing during rapid events.
+  // Note: aria-current is NOT toggled here. It tracks the settled "current"
+  // item, which is updated in the scrollsnapchange handler below.
+  thumbnails.forEach((thumb) => thumb.classList.remove('pending'));
+  thumbnails[index].classList.add('pending');
+});
+```
+
+This example uses `snapTargetInline` because the gallery scrolls horizontally. If your scroll container scrolls vertically, use `snapTargetBlock` instead.
+
+### 2. Listen for `scrollsnapchange`
+To finalize the state when the scroll gesture completes and the element actually snaps, listen for the `scrollsnapchange` event. This is required to establish the final active state.
+
+```javascript
+container.addEventListener('scrollsnapchange', (event) => {
+  // Promote pending state to active on scroll completion.
+  const snappedTarget = event.snapTargetInline;
+  const index = [...items].indexOf(snappedTarget);
+
+  if (index === -1 || !thumbnails[index]) return;
+
+  // Establish final active state and clean up pending.
+  thumbnails.forEach((thumb) => {
+    thumb.classList.remove('pending', 'active');
+    thumb.removeAttribute('aria-current');
+  });
+  thumbnails[index].classList.add('active');
+  thumbnails[index].setAttribute('aria-current', 'true');
+});
+```
+
+### 3. Sync initial state
+When the page loads, the scroll position might be restored by the browser (e.g., via history traversal or an anchor link). Neither `scrollsnapchange` nor `scroll` events will fire automatically. Run a one-off geometric check to sync the UI with the initial scroll position.
+
+```javascript
+// Note: For item.offsetLeft to be relative to the container, 
+// the container MUST be the offsetParent (e.g., `position: relative`).
+const findClosestItemIndex = () => {
+  // Center-distance assumes scroll-snap-align: center on items.
+  // For start-aligned snap, compare scrollLeft to item.offsetLeft directly.
+  const containerCenter = container.scrollLeft + container.clientWidth / 2;
+  let closestIndex = 0;
+  let minDistance = Infinity;
+
+  items.forEach((item, index) => {
+    const itemCenter = item.offsetLeft + item.offsetWidth / 2;
+    const distance = Math.abs(containerCenter - itemCenter);
+    if (distance < minDistance) {
+      minDistance = distance;
+      closestIndex = index;
+    }
+  });
+  return closestIndex;
+};
+
+const initActiveItem = () => {
+  const closestIndex = findClosestItemIndex();
+  if (!thumbnails[closestIndex]) return;
+
+  thumbnails.forEach((thumb) => {
+    thumb.classList.remove('pending', 'active');
+    thumb.removeAttribute('aria-current');
+  });
+  thumbnails[closestIndex].classList.add('active');
+  thumbnails[closestIndex].setAttribute('aria-current', 'true');
+};
+
+if (document.readyState === 'complete') {
+  initActiveItem();
+} else {
+  window.addEventListener('load', initActiveItem, { once: true });
+}
+```
+
+### Fallback strategies
+Browser support for Scroll snap events: Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+Baseline status for Scroll snap: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 69 (Sep 2018), Edge 79 (Jan 2020), Firefox 68 (Jul 2019), and Safari 11 (Sep 2017).
+
+For browsers that do not support `scrollsnapchanging`, the UI will not provide eager feedback during the scroll gesture by default, and the linked UI will desynchronize from the content.
+
+**MANDATORY:** Provide a fallback for browsers without support, or the linked UI will desynchronize from the content.
+
+**DO** simulate the real-time nature of `scrollsnapchanging` with a `scroll` event listener coupled with `requestAnimationFrame` and geometric distance calculations to determine the closest snap target while the user is actively scrolling.
+
+```javascript
+if ('onscrollsnapchanging' in Element.prototype) {
+  // Use native scroll snap events
+} else {
+  // Fallback: use scroll + requestAnimationFrame for eager feedback
+  // (assumes the same container, thumbnails, items defined in step 1)
+  let scrollTimeout;
+  let rafId = null;
+
+  const promotePendingToActive = () => {
+    const closestIndex = findClosestItemIndex();
+    if (!thumbnails[closestIndex]) return;
+    thumbnails.forEach((thumb) => {
+      thumb.classList.remove('pending', 'active');
+      thumb.removeAttribute('aria-current');
+    });
+    thumbnails[closestIndex].classList.add('active');
+    thumbnails[closestIndex].setAttribute('aria-current', 'true');
+  };
+
+  container.addEventListener('scroll', () => {
+    if (rafId) return;
+    rafId = requestAnimationFrame(() => {
+      rafId = null;
+      const closestIndex = findClosestItemIndex();
+      if (!thumbnails[closestIndex]) return;
+
+      // DO NOT forget to clean up stale pending classes
+      thumbnails.forEach((thumb) => thumb.classList.remove('pending'));
+      thumbnails[closestIndex].classList.add('pending');
+    });
+
+    // Debounce fallback for browsers that don't support scrollend
+    clearTimeout(scrollTimeout);
+    scrollTimeout = setTimeout(promotePendingToActive, 100);
+  }, { passive: true });
+
+  // Fallback: use Baseline `scrollend` event to promote pending to active cleanly where supported
+  container.addEventListener('scrollend', () => {
+    clearTimeout(scrollTimeout);
+    promotePendingToActive();
+  });
+}
+```
+
+The geometric `scroll` + `requestAnimationFrame` fallback closely emulates the behavior of native snap prediction, including handling programmatic scrolling correctly. Because functions like `scrollIntoView` naturally fire `scroll` events during their execution, the UI will stay smoothly synchronized throughout the scroll animation without requiring additional custom logic.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-state-sync.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-state-sync.md
new file mode 100644
index 00000000..e9dd92b9
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-snap-state-sync.md
@@ -0,0 +1,95 @@
+# Scroll Snap State Sync
+
+Synchronizing UI state with a scrollable container's snap position traditionally required complex scroll event listeners, manual calculations of scroll offsets, and intersection observers. The `scrollsnapchange` event provides a native, efficient way to detect when a scroller has settled on a new snap target, making it useful for synchronizing sidebars or highlighting the active section in a table of contents.
+
+## Implementation
+
+### 1. Configure Scroll Snap in CSS
+The container must have `scroll-snap-type` defined, and have children with `scroll-snap-align` for the browser to track snap targets. In a long article with a table of contents, you can use this to snap section headers to the top of the viewport.
+
+```css
+main {
+    /* Enable scroll snapping on the container */  
+  scroll-snap-type: y proximity;
+  overflow-y: auto;
+}
+
+h2 {
+  /* Define how headers align when snapped */
+  scroll-snap-align: start;
+}
+```
+
+### 2. Listen for Snap Changes
+Use the `scrollsnapchange` event on the scroll container to react when the user finishes scrolling and the browser snaps to a new element. In our TOC demo, we use this to highlight the active link in the sidebar.
+
+```html
+<!-- MANDATORY: Wrap table of contents links inside a proper navigation landmark -->
+<nav aria-label="Table of contents">
+  <ul>
+    <li><a href="#section-1" aria-current="location">Section 1</a></li>
+    <li><a href="#section-2">Section 2</a></li>
+  </ul>
+</nav>
+```
+
+```javascript
+const main = document.getElementById('main');
+const links = document.querySelectorAll('nav a');
+
+// The event fires when the scroller settles on a new snap target
+main.addEventListener('scrollsnapchange', (event) => {
+  // Use snapTargetBlock for vertical or snapTargetInline for horizontal
+  const snappedHeader = event.snapTargetBlock;
+  
+  if (snappedHeader) {
+    setSelectedParagraph(snappedHeader.id);
+  }
+});
+```
+
+
+## Accessibility
+
+Caution: While Scroll Snap Events make it possible to visually synchronize other content to the state of the scroller, it does not automatically expose that information programmatically. Relationships between elements, active states, and live content must be reflected in the Accessibility Tree.
+
+For a table of contents, ensure the sidebar links use `aria-current="true"` or `aria-current="location"` when they are active.
+
+In addition, be careful when using the `mandatory` value for `scroll-snap-type`, as it can cause content in-between snap-points to become inaccessible when longer than the screen.
+
+
+## Fallback strategies
+
+Browser support for Scroll snap events: Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+If `scrollsnapchange` is not supported, use `IntersectionObserver` to detect which element is currently at the top of the scroller. Note this is different behavior than `scrollsnapchange`, as this will trigger while the scroll happens, rather than only when the scroll has settled.
+
+```javascript
+// Feature detect support for scroll snap events
+if (!('onscrollsnapchange' in HTMLElement.prototype)) {
+  const observer = new IntersectionObserver(
+    () => {
+      // Each time the set of intersecting headers changes, find the top
+      // header that is visible.
+      const topEntry = [...headers].reduce((currentTop, header) => {
+        // Use the bottom to handle scrolling up, when the top is still offscreen
+        const {bottom} = header.getBoundingClientRect();
+        // Don't match if the header's bottom is above the scrollport
+        if (bottom < 0) return;
+        if (!currentTop) return header;
+        return bottom <
+          currentTop.getBoundingClientRect().bottom
+          ? header
+          : currentTop;
+      }, undefined);
+      if (topEntry) setSelectedParagraph(topEntry.id);
+    },
+    { root: main, threshold: 0.9 // Adjust based on your use case },
+  );
+
+  // Observe all snap targets (e.g., section headers)
+  document.querySelectorAll('h2').forEach(header => observer.observe(header));
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-target-on-load.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-target-on-load.md
new file mode 100644
index 00000000..6a43e23d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scroll-target-on-load.md
@@ -0,0 +1,56 @@
+# Set a scroll target for the initial render
+
+The CSS property `scroll-initial-target` offers a declarative, CSS-only way to bring a specific descendant element into the visible area of its scroll container as soon as that container is rendered. Previously, developers relied on JavaScript (`Element.scrollIntoView()`) or URL fragment identifiers (`#item-id`), both of which have limitations and are tricky to implement.
+
+## How to Implement
+
+To implement this successfully:
+
+1. **Ensure a scroll container:** The target element must be inside a scroll container (an element with overflow that allows scrolling, such as `overflow: auto`). This can be any ancestor element, including the root `<html>` element.
+2. **Target the Item:** Apply `scroll-initial-target: nearest` to the specific descendant element you want to bring into view.
+
+## Example Code: Vertical Media Feed
+
+In this example, a feed starts scrolled to a specific "featured" item rather than the very top of the list.
+
+```css
+/** 
+ * TARGET: The item that should be visible on initial load.
+ */
+.item.target {
+  scroll-initial-target: nearest;
+}
+```
+
+## Strategic Implementation & Best Practices
+
+- **DO** use `scroll-initial-target` for "middle-start" experiences, such as a calendar starting on the current day or a gallery starting on a specific image.
+- **DO NOT** confuse this with accessibility focus. This property only moves the **visual** viewport; it does not move the keyboard focus. You must manually manage `element.focus()` if the target is intended to be the starting point for keyboard users.
+- **DO NOT** use this if you need a smooth "scrolling" animation on load; this property is discrete and sets the position instantly during the layout phase.
+- **DO NOT** set `scroll-initial-target` on multiple elements within the same scrollable container. If multiple elements specify `scroll-initial-target: nearest`, the browser selects the one that appears first in the DOM tree order.
+- **DO** provide dimensions for media. Since the scroll position is calculated during initial layout, ensure images or videos have `aspect-ratio` or fixed `height`/`width` to prevent the target from shifting after the media loads.
+- **DO** account for the **Precedence Hierarchy**: A URL fragment (e.g., `example.com/#top`) and the container-level `scroll-start` property both take precedence over `scroll-initial-target`.
+
+## Fallback Strategy
+
+Browser support for scroll-initial-target: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not yet support the API, use a JavaScript fallback. Use the `DOMContentLoaded` event to ensure the browser scrolls the element into view as soon as the HTML parsing completes, providing a faster experience than waiting for all images and resources to load. Alternatively, placing the script at the end of the `<body>` element is also acceptable and avoids the need for an event listener.
+
+```javascript
+/**
+ * Progressive Enhancement Fallback
+ */
+document.addEventListener("DOMContentLoaded", () => {
+  // Check for native CSS support
+  if (!CSS.supports("scroll-initial-target", "nearest")) {
+    const feedTarget = document.querySelector(".item.target");
+    if (feedTarget) {
+      // 'block: center' ensures the featured media is centered in view
+      feedTarget.scrollIntoView({ behavior: "instant", block: "center" });
+    }
+  }
+});
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scrollytelling.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scrollytelling.md
new file mode 100644
index 00000000..9c4f9092
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/scrollytelling.md
@@ -0,0 +1,181 @@
+# Scrollytelling
+
+Scrollytelling is a popular technique used to create engaging and immersive web experiences. It involves animating elements on a page as the user scrolls, effectively telling a story or guiding the user through a narrative. With CSS Scroll-Driven Animations, you can create these effects directly in CSS, without needing to rely on JavaScript. The animations are controlled by the scroll position, not a time-based clock, which ensures they are always in sync with the user's scroll.
+
+## How to implement
+
+To create a scrollytelling experience, you need two sets of elements: one to track the scroll position and another to be animated.
+
+First, define a named `view-timeline` on the elements you want to track. These will act as the drivers for your animations.
+
+```css
+#tracked {
+  section:nth-child(1){ view-timeline: --tl-1 block; }
+  section:nth-child(2){ view-timeline: --tl-2 block; }
+  section:nth-child(3){ view-timeline: --tl-3 block; }
+  section:nth-child(4){ view-timeline: --tl-4 block; }
+  section:nth-child(5){ view-timeline: --tl-5 block; }
+}
+```
+
+Next, apply animations to the elements you want to animate and link them to the timelines you just created using the `animation-timeline` property.
+
+```css
+#animated {
+  section {
+    animation: animate-in auto linear both, animate-out auto linear forwards;
+    animation-range: entry 25% cover 50%, exit 50% exit 75%;
+  }
+
+  section:nth-child(1){ animation-timeline: --tl-1; }
+  section:nth-child(2){ animation-timeline: --tl-2; }
+  section:nth-child(3){ animation-timeline: --tl-3; }
+  section:nth-child(4){ animation-timeline: --tl-4; }
+  section:nth-child(5){ animation-timeline: --tl-5; }
+}
+```
+
+For the `animation-timeline` to be able to reference the named timelines, they need to be in the same scope. You can use the `timeline-scope` property on a common ancestor to make the timelines available to all the elements that need them. The `:root` element is often a good choice for this.
+
+```css
+html {
+  timeline-scope: --tl-1, --tl-2, --tl-3, --tl-4, --tl-5;
+}
+```
+
+Finally, you can use the `animation-range` property to specify the exact range of the timeline during which the animation should run. This gives you fine-grained control over when the animations are triggered and how they progress.
+
+```css
+#animated section {
+  animation-range: entry 25% cover 50%, exit 50% exit 75%;
+}
+```
+
+## Example code
+
+```css
+html {
+  timeline-scope: --tl-1, --tl-2, --tl-3, --tl-4, --tl-5;
+}
+
+#tracked {
+  section:nth-child(1){ view-timeline: --tl-1 block; }
+  section:nth-child(2){ view-timeline: --tl-2 block; }
+  section:nth-child(3){ view-timeline: --tl-3 block; }
+  section:nth-child(4){ view-timeline: --tl-4 block; }
+  section:nth-child(5){ view-timeline: --tl-5 block; }
+}
+
+@keyframes animate-in {
+  from { scale: 0.5; opacity: 0; transform: rotateY(-180deg); }
+  to { transform: rotateY(0deg); }
+}
+@keyframes animate-out {
+  to { translate: 100% 0; opacity: 0; }
+}
+
+#animated {
+  section {
+    animation: animate-in auto linear both, animate-out auto linear forwards;
+    animation-range: entry 25% cover 50%, exit 50% exit 75%;
+    backface-visibility: hidden;
+  }
+
+  section:nth-child(1){ animation-timeline: --tl-1; }
+  section:nth-child(2){ animation-timeline: --tl-2; }
+  section:nth-child(3){ animation-timeline: --tl-3; }
+  section:nth-child(4){ animation-timeline: --tl-4; }
+  section:nth-child(5){ animation-timeline: --tl-5; }
+}
+
+/* MANDATORY Copy-Paste Safety: Disable continuous storytelling motion for sensitive users */
+@media (prefers-reduced-motion: reduce) {
+  #animated section {
+    animation: none !important;
+    opacity: 1 !important;
+    transform: none !important;
+  }
+}
+```
+
+## Best Practices
+
+When using scroll-driven animations, it's important to follow a few best practices to ensure a smooth and accessible experience:
+
+- **DO** include feature detection: Not all browsers support scroll-driven animations. Use `@supports ((animation-timeline: scroll()) and (animation-range: 0% 100%))` to check for support and provide a fallback for browsers that don't support it.
+  - The `(animation-range: 0% 100%)` check **MUST** be included here, to filter out browsers with only partial support.
+  - **DO NOT** use the `scroll-timeline-polyfill` package for the fallback strategy as it is not feature complete and has a lot of known issues.
+  - If the animation is only considered to be decorative, opt for Progressive Enhancement and **DO NOT** provide a fallback.
+- **DO** respect user preferences: Some users prefer to have less motion on the web. Use the `prefers-reduced-motion` media query to disable or reduce your animations for these users.
+- **DO** try to animate only performant CSS properties: For the smoothest animations, stick to animating properties that can be handled by the browser's compositor thread, such as `transform` and `opacity`. Animating other properties like `width` or `height` can lead to performance issues.
+- **DO** use the correct declaration order: When using the `animation` shorthand property, declare `animation-timeline` and `animation-range` *after* it to prevent the shorthand from resetting the timeline.
+
+When using the `view-timeline` property to create a scroll-driven animation:
+
+- **DO** use a CSS `<dashed-ident>` for the name.
+- **OPTIONAL** be explicit about the axis to track: When not targeting the default `block` axis (such as in a horizontal scroller), be explicit about which axis to track with `view-timeline-axis`.
+- **DO** make sure the scope of the lookup works: When the element that is declaring the `view-timeline` is not a flat tree ancestor of the animated element, hoist up the visibility of the `view-timeline`’s name by using `timeline-scope` on a shared ancestor.
+
+## Fallback strategies
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+For browsers that do not support scroll-driven animations, you can use a fallback to recreate the visual effects. The fallbacks are typically built with either a scroll listener (for ScrollTimeline effects) or the IntersectionObserver API (for ViewTimeline effects).
+
+In browsers with built-in support for scroll-driven animations, ALWAYS use the native CSS implementation as those are more performant.
+
+Note that not every effect can be recreated using the fallbacks approach.
+
+For this use-case specifically, the following script applies the fallback for browsers that do not support scroll-driven animations. It uses an `IntersectionObserver` to track the visibility of each `#tracked section` element and updates the `transform` property of the corresponding `#animated section` accordingly.
+
+```js
+const animatedSections = document.querySelectorAll('#animated section');
+
+const observer = new IntersectionObserver((entries) => {
+  entries.forEach(entry => {
+    const sectionIndex = Array.from(document.querySelectorAll('#tracked section')).indexOf(entry.target);
+    if (sectionIndex !== -1) {
+      const animatedSection = animatedSections[sectionIndex];
+      const ratio = entry.intersectionRatio;
+
+      // Animate-in
+      animatedSection.style.opacity = ratio;
+      animatedSection.style.transform = `scale(${0.5 + ratio * 0.5}) rotateY(${-180 + ratio * 180}deg)`;
+
+      // Animate-out
+      if (ratio < 0.5) {
+        animatedSection.style.translate = `${(0.5 - ratio) * 2 * 100}% 0`;
+      } else {
+        animatedSection.style.translate = '0 0';
+      }
+    }
+  });
+}, { threshold: Array.from({length: 101}, (_, i) => i / 100) });
+
+document.querySelectorAll('#tracked section').forEach(section => {
+  observer.observe(section);
+});
+```
+
+And the accompanying CSS:
+
+```css
+#animated section {
+  opacity: 0;
+  transform: scale(0.5)  rotateY(-180deg);
+  backface-visibility: hidden;
+}
+
+/* MANDATORY Copy-Paste Safety: Ensure content remains fully visible and legible for assistive technologies or users with motion sensitivities */
+@media (prefers-reduced-motion: reduce) {
+  #animated section {
+    opacity: 1 !important;
+    transform: none !important;
+    translate: 0 0 !important;
+  }
+}
+```
+
+This fallback provides a more accurate, scroll-driven animation for browsers that do not support the native CSS feature, ensuring a more consistent experience for all users. By using a series of thresholds for the `IntersectionObserver`, we can track the scroll position with more precision and create a smoother animation.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/search-hidden-content.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/search-hidden-content.md
new file mode 100644
index 00000000..984e66f6
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/search-hidden-content.md
@@ -0,0 +1,141 @@
+# Search hidden content
+
+Web interfaces often hide content from view to improve the user experience, save screen space, or increase page performance. Traditional methods like `display: none` or `visibility: hidden` work to hide content visually, but they also make that content completely inaccessible to screen readers and browser features like "Find in page".
+
+To hide content visually but still allow it to be searchable by users and enable it to be deep linked to via URL fragments and "Scroll to Text Fragment" links, you can use either the HTML `<details>` element or the `hidden="until-found"` attribute. The `<details>` element is generally recommended as it's simpler to implement and maintain, but there are some more complex cases where `<details>` is not sufficient and `hidden="until-found"` is required.
+
+For example:
+
+- If you want full control over the styling of the show/hide mechanism.
+- If the UI controls to show/hide the content are in another part of the DOM.
+- If you don't want to support hiding the content after it's shown.
+
+## How to implement
+
+The `<details>` element has searchable and accessible text by default, and no special implementation is required. Prefer using `<details>` over `hidden="until-found"` if possible.
+
+If you need to use `hidden="until-found"` instead, follow these instructions:
+
+1. **Apply the attribute:** Add the `hidden="until-found"` HTML attribute directly to the elements containing the content that should be hidden from view.
+2. **Synchronize UI state:** If the interface has related states that depend on the content's visibility (e.g., updating ARIA attributes, toggling open/close CSS classes, or rotating accordion icons):
+   - You **MUST** add an event listener for the `beforematch` event.
+   - Register the `beforematch` event listener directly on the element carrying the `hidden="until-found"` attribute. Since the event bubbles, you may alternatively use event delegation by registering a single listener on a parent element (such as a tab container) to manage multiple hidden sections at once.
+   - Inside the event listener, execute the logic to synchronize related UI elements (such as closing other open tabs or changing the state of a toggle button).
+
+## Example code
+
+**Goal:** Render a hidden container where the content remains invisible to the user until they search for a word within that section.
+
+### Using `<details>` element
+
+```html
+<details>
+  <summary>Click to expand</summary>
+  <p>This content is visually hidden.</p>
+</details>
+```
+
+#### Mutually exclusive disclosures
+
+When handling mutually exclusive content regions, like an exclusive accordion, use the native HTML `<details>` element with a shared `name` attribute.
+
+```html
+<div class="accordion-group">
+  <!-- The name attribute creates an exclusive disclosure group -->
+  <details class="disclosure" name="my-accordion">
+    <summary>Section 1</summary>
+    <p>Section 1 content</p>
+  </details>
+
+  <details class="disclosure" name="my-accordion" open>
+    <summary>Section 2</summary>
+    <p>Section 2 content</p>
+  </details>
+
+  <details class="disclosure" name="my-accordion">
+    <summary>Section 3</summary>
+    <p>Section 3 content</p>
+  </details>
+</div>
+```
+
+### Using `hidden="until-found"` attribute
+
+```html
+<!-- The browser automatically removes hidden="until-found" upon a search match -->
+<div class="hidden-container" hidden="until-found">
+  <p>This content is visually hidden.</p>
+</div>
+```
+
+#### Custom mutually exclusive disclosures
+
+When handling custom mutually exclusive regions controlled by external buttons, ensure only the matched panel remains visible. In the `beforematch` event handler, you MUST synchronize related ARIA states such as setting `aria-expanded="true"` on the controlling button.
+
+```html
+<div class="custom-accordion">
+  <div class="controls">
+    <button aria-expanded="true" aria-controls="panel-1" id="btn-1">Section 1</button>
+    <button aria-expanded="false" aria-controls="panel-2" id="btn-2">Section 2</button>
+  </div>
+
+  <div id="panel-1" class="panel">
+    <p>Section 1 content (visible)</p>
+  </div>
+
+  <div id="panel-2" class="panel" hidden="until-found">
+    <p>Section 2 content (hidden)</p>
+  </div>
+</div>
+```
+
+```javascript
+const accordion = document.querySelector('.custom-accordion');
+
+accordion.addEventListener('beforematch', (e) => {
+  // Hide all panels and synchronize button states before the browser reveals the matched panel
+  accordion.querySelectorAll('.panel').forEach((panel) => {
+    if (panel !== e.target) {
+      panel.hidden = 'until-found';
+    }
+  });
+  accordion.querySelectorAll('button').forEach((btn) => {
+    const controls = btn.getAttribute('aria-controls');
+    btn.setAttribute('aria-expanded', controls === e.target.id ? 'true' : 'false');
+  });
+});
+```
+
+## Best practices for `hidden="until-found"`
+
+- **DO** apply borders, padding, and backgrounds to nested child wrappers rather than directly to the element with the `hidden="until-found"` attribute. This prevents unintended layout shifts or visual remnants while the element is hidden.
+- **DO NOT** apply `display: none`, `visibility: hidden`, or any associated `display` or `visibility` CSS properties directly to elements with the `hidden="until-found"` attribute. This breaks the native functionality and permanently hides the content from the search index.
+- **DO NOT** use `hidden="until-found"` for sensitive information, internal data tokens, or irrelevant data that should not be exposed via search.
+- **DO NOT** use `hidden="until-found"` as a replacement for "screen reader only" (.sr-only) text.
+
+## Browser support and fallback strategies
+
+Baseline status for <details>: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 12 (Jun 2011), Edge 79 (Jan 2020), Firefox 49 (Sep 2016), and Safari 6 (Jul 2012).
+
+Browser support for hidden="until-found": Limited availability.
+Supported by: Chrome 102 (May 2022), Edge 102 (May 2022), and Firefox 148 (Feb 2026).
+Unsupported in: Safari.
+
+**DO NOT** avoid `hidden="until-found"` because of missing browser support, as its accessibility benefits far outweigh the cost of implementing a fallback.
+
+#### `hidden="until-found"` fallback
+
+For standard UI elements like accordions or "Read more" sections, use JavaScript to feature-detect and show all content if the feature is unsupported.
+
+```javascript
+if (!('onbeforematch' in HTMLElement.prototype)) {
+  // Expand all hidden content for unsupported browsers
+  document.querySelectorAll('[hidden="until-found"]').forEach((el) => {
+    el.removeAttribute('hidden');
+    // MANDATORY: also update any aria references to this element.
+  });
+}
+```
+
+For mutually exclusive UI paradigms (like custom exclusive panels where content shares the same visual region), the fallback should extract and display all content linearly below the main interactive area, using URL anchor fragments to allow users to navigate directly to the respective sections.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/spatial-navigation.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/spatial-navigation.md
new file mode 100644
index 00000000..9bab3dda
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/spatial-navigation.md
@@ -0,0 +1,56 @@
+# Spatial Navigation (Directional Keypad Focus)
+
+Directional focus navigation (using arrow keys or D-Pads) enables keyboard-only and alternative-input users to navigate interactive items based on their visual 2D layout. It is highly beneficial for spatial user interfaces (such as media rails, dashboard panels, or nested catalogs), but it must be implemented carefully to avoid breaking native browser behaviors like viewport scrolling.
+
+This guide covers building performant, accessible 2D directional navigation inside composite widgets.
+
+---
+
+### Core Architectural Principles
+
+When implementing custom arrow-key spatial focus, adhere to these foundational rules:
+
+1. **Limit to composite widgets**: Do not override arrow keys on normal document text flow or simple vertical list layouts where default sequential Tab navigation is expected. See `accessibility` (via `npx -y modern-web-guidance@latest retrieve "accessibility"`) for general document flow guidance.
+2. **Preserve native boundary scrolling**: If there is no focusable element in the pressed direction, **do not prevent default browser behavior**. Let the event bubble so the browser can scroll the viewport natively. Overriding arrow keys unconditionally breaks accessibility (WCAG 1.4.10).
+3. **Ensure focus visibility and alignment**: When focus changes, ensure the newly focused element is scrolled into view (e.g., using `scrollIntoView({ block: 'nearest', inline: 'nearest' })`) so that it remains fully visible.
+4. **Coordinate with the layout system**: Determine focus candidate positions from live bounding geometries (`getBoundingClientRect()`) while handling each keypress. Avoid assuming that DOM order or a fixed grid structure represents the visual layout. See `css-layout` (via `npx -y modern-web-guidance@latest retrieve "css-layout"`) for modern layout recommendations.
+
+---
+
+### Accessible Focus Management
+
+The spatial container must expose a single tab stop to sequential Page Tab navigation. Inside the widget, manage keyboard focus using the **Roving Tabindex Pattern**:
+* The active item has `tabindex="0"`.
+* All inactive items have `tabindex="-1"`.
+* When navigating, programmatically move focus by shifting the `tabindex="0"` attribute and calling `focus()`.
+
+---
+
+### Visual Candidate Selection
+
+In asymmetrical, wrapped, or grid layouts, index-based mapping fails. Instead, derive candidates from the live visual geometry for the current keypress:
+
+* **Candidates**: Use the focusable descendants of the widget container that pass `checkVisibility()`. Hidden elements can have a zero-sized rect at `(0, 0)` and must not become accidental `up` or `left` targets.
+* **Geometry**: Read `getBoundingClientRect()` for the focused element and every candidate while handling the keypress. Do not cache these rects globally: layout can change for many reasons, and a small number of geometry reads is cheap when handling a user-paced key event.
+* **Direction filter**: A candidate is in the pressed direction only when its near edge is at or beyond the current element’s far edge on that axis, allowing a small tolerance for sub-pixel rounding. For example, a candidate for `right` must have `candidate.left >= current.right - tolerance`. Do not compare centres to determine whether a candidate is in the direction.
+* **Aligned candidates first**: Among candidates that pass the direction filter, prefer candidates whose extent on the perpendicular axis overlaps the current element’s extent. Choose the smallest gap on the navigation axis, breaking ties with the smallest perpendicular centre offset. This keeps navigation in the adjacent visual row or column even when an item is unusually wide.
+* **Fallback scoring**: If no candidate overlaps on the perpendicular axis, score the remaining candidates as `gap + w * perpendicularCentreOffset` and choose the minimum. Use a weight `w >= 2` as a starting point, then tune it for the layout; a larger weight favours candidates that are more closely aligned.
+* **No candidate**: Return nothing. The event handler must not call `preventDefault()`, allowing the browser to scroll natively.
+
+The exact implementation can vary, but keep the direction test edge-based and apply the overlap preference before the weighted fallback. This is the crux of the algorithm; avoid presenting a cache or a fixed weight as universally correct.
+
+---
+
+### Keypress Integration & Scroll Cooperation
+
+Your event router must prevent standard viewport scrolling **only** when a valid spatial focus transition occurs:
+
+* Do not intercept the event when a modifier key is held, when `e.defaultPrevented` is already true, or when the innermost event target consumes arrow keys itself. Use `e.composedPath()[0]` rather than only `e.target`, because `e.target` can be retargeted to a shadow host. A practical editable/control check is `target.matches(':read-write, select, input[type="range"], [role="slider"]')`; closed shadow roots cannot be inspected.
+* Scope the listener to the widget container, so multiple spatial widgets can coexist on a page.
+* Act only when the focused element is itself a candidate. If items contain their own focusable controls, either make those controls candidates too or leave them alone; do not resolve a parent with `closest()`.
+* When a candidate is found, call `preventDefault()`, update the roving `tabindex`, call `focus()`, and use `scrollIntoView({ block: 'nearest', inline: 'nearest' })`.
+* When no candidate is found, return without calling `preventDefault()` so native scrolling continues.
+
+---
+
+Avoid adding single-character shortcuts such as `h`/`j`/`k`/`l` or `W`/`A`/`S`/`D` for spatial navigation. Arrow keys are not character keys, and preserving native scrolling when no candidate exists avoids unnecessarily blocking viewport movement.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-remove.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-remove.md
new file mode 100644
index 00000000..bfab2040
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-remove.md
@@ -0,0 +1,544 @@
+# Swipe to remove
+
+Swipe-to-remove patterns are common in mobile applications but can be challenging to implement cleanly on the web. By using CSS Scroll Snap, you can create a smooth, native-feeling swipe interaction that hooks directly into the browser's scrolling engine. This ensures high performance and physics-based momentum without needing a complex JavaScript gesture library.
+
+The same pattern works for any single-action swipe (remove, archive, mark as read, snooze). The action visuals change; the mechanics do not.
+
+> If you instead want a horizontal swipe to snap open a set of action buttons or a side menu **without** automatically committing an action during the swipe, see `swipe-to-reveal` (via `npx -y modern-web-guidance@latest retrieve "swipe-to-reveal"`).
+
+## How to implement
+
+The component has two layers: a **list** (the `<ul>`) and the **items** inside it. Each item is structured as an outer `<li>`, an inner scroll **track** (the scroll container with the snap points), and a **content** element (the visible row). The action's revealed UI (trash icon, archive label, etc.) lives on either side of the content. The list owns shared wiring (lazy item setup, picking up newly added items); each item owns its own swipe detection.
+
+### Step 1: Mark up the list with track and content
+
+```html
+<ul class="SwipeableList">
+  <li id="list-item-1" class="SwipeableList-item">
+    <div class="SwipeableList-track">
+      <div class="SwipeableList-content">Item One</div>
+    </div>
+  </li>
+  <li id="list-item-2" class="SwipeableList-item">
+    <div class="SwipeableList-track">
+      <div class="SwipeableList-content">Item Two</div>
+    </div>
+  </li>
+  <!-- ...more items... -->
+</ul>
+```
+
+### Step 2: Configure the track as a horizontal snap container with three snap points
+
+The track has three full-width columns: a left spacer (`::before`), the content, and a right spacer (`::after`). Snapping to a spacer means the content is fully off-screen, which is the rest position after a committed swipe.
+
+The track configuration is gated behind an `.is-initialized` class on the list item. Before JS upgrades the row, the item just renders as plain content with no horizontal scroller. The class is added in Step 4 once the JavaScript that detects swipes has been wired up. This ensures the user cannot swipe before the functionality is ready.
+
+```css
+.SwipeableList {
+  list-style: none;
+}
+
+.SwipeableList-item {
+  /* Establishes a containing block for the absolutely positioned action
+     icons (Step 3) and clips overflow during the row's removal
+     animation (Step 4). */
+  contain: content;
+}
+
+/* The track only becomes a scroll snap container after JS upgrades
+   the row by adding `.is-initialized` (see Step 4). */
+.SwipeableList-item.is-initialized .SwipeableList-track {
+  /* Three full-width columns: left spacer | content | right spacer.
+     Width is 100% of the track, so each column fills the viewport row. */
+  display: grid;
+  grid-template-columns: 100% 100% 100%;
+
+  /* Horizontal scroll only; vertical overflow is clipped so the
+     reveal stays inside the row. */
+  overflow: scroll clip;
+
+  /* Prevent the swipe from chaining into the page scroll or browser
+     back-gesture on iOS/Android. */
+  overscroll-behavior-x: none;
+
+  /* Hide the scrollbar; the gesture is the affordance. */
+  scrollbar-width: none;
+
+  /* `mandatory` ensures the track always rests on a snap point
+     (spacer or content), never partially scrolled. */
+  scroll-snap-type: x mandatory;
+}
+
+/* Spacers act as the left and right snap targets, AND carry the action's
+   reveal color. As the user swipes, the colored spacer slides into view,
+   which is what the user sees behind the content. */
+.SwipeableList-item.is-initialized .SwipeableList-track::before,
+.SwipeableList-item.is-initialized .SwipeableList-track::after {
+  content: '';
+
+  /* `scroll-snap-align` is required to make this a valid snap target,
+     but the specific value (`start`/`center`/`end`) doesn't matter here
+     because each snap point spans the full width of the scroll
+     container, so all alignments resolve to the same resting position. */
+  scroll-snap-align: start;
+
+  /* `hsl(0 65% 50%)` is an example value; pick whatever fits your
+     design (red here signals "delete"; use a different color for
+     archive, mark-as-read, etc.). */
+  background-color: hsl(0 65% 50%);
+}
+
+.SwipeableList-content {
+  /* The content sits above the action icons (Step 3), so it covers
+     them until the user swipes. */
+  position: relative;
+  z-index: 2;
+
+  /* Required to make the content a valid snap target (its resting
+     position). As with the spacers above, the specific value doesn't
+     matter because the snap points are full-width. */
+  scroll-snap-align: start;
+
+  /* The content must paint over the revealed spacer color. */
+  background: Canvas;
+
+  /* Row separator (example value; customize to taste). */
+  border-bottom: 1px solid #eee;
+}
+
+/* Gate `scroll-initial-target` behind `.is-initialized` so it only
+   applies once the track is actually a scroll container. Setting it on
+   the content before then would let the property walk up to the nearest
+   scrollable ancestor (typically the document) and shift the page's
+   initial scroll position to bring this row's content into view. With
+   the gate, the rule is only live when the row's own track can satisfy
+   it, so the initial scroll happens inside the track as intended. */
+.SwipeableList-item.is-initialized .SwipeableList-content {
+  scroll-initial-target: nearest;
+}
+
+/* The track is the focusable scroll container, but its overflow is clipped
+   so a default focus ring on the track itself would be invisible. Project
+   the focus affordance onto the content element (which paints above the
+   track) using `:focus-visible` on the track. */
+.SwipeableList-track:focus-visible .SwipeableList-content {
+  outline: auto;
+  outline-offset: -2px;
+}
+```
+
+### Step 3: Add the action icons to the list item
+
+The action color lives on the spacers (Step 2). The action **icon** lives on the list item itself, anchored to the row's left and right edges.
+
+> **Note:** Throughout this guide, "left" refers to the *left side of the row* (which is revealed by swiping right), and "right" refers to the *right side of the row* (revealed by swiping left).
+
+The placement, sizing, and motion below are a **starting suggestion**, not a requirement. Adjust the icon size, edge insets, threshold-pop scale, transition duration, and even the choice of pseudo-elements vs. real DOM nodes to match your design. The only mechanical requirement is that the icon sits behind the content (so the content can cover it pre-swipe) and inside the list item (so it doesn't scroll with the spacer). Everything else is taste.
+
+```css
+/* Action icons painted on the list item. They're absolutely positioned
+   inside the row (which is a containing block thanks to `contain: content`
+   on `.SwipeableList-item` from Step 2) and sit at z-index 1, so the
+   content element (z-index 2) covers them until the user swipes far
+   enough. */
+.SwipeableList-item.is-initialized::before,
+.SwipeableList-item.is-initialized::after {
+  /* Inline an SVG as the action icon. Replace this with whatever icon
+     fits the action (archive, checkmark, clock, etc.). The `fill='white'`
+     is baked into the SVG so it contrasts with the red spacer background;
+     adjust if your background color is light. */
+  --action-icon: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='white'><path d='M9 3v1H4v2h1v13a2 2 0 0 0 2 2h10a2 2 0 0 0 2-2V6h1V4h-5V3H9zm0 5h2v9H9V8zm4 0h2v9h-2V8z'/></svg>");
+
+  content: '';
+  position: absolute;
+  z-index: 1;
+
+  /* The size (`width`) and insets (`left`/`right` below) are example
+     values, tune them to match your row height and visual weight.
+     The icon fills its box via `background-size: contain`, so changing
+     `width` resizes it. */
+  width: 1.5em; /* example value, adjust to taste */
+  aspect-ratio: 1;
+  top: 50%;
+  translate: 0 -50%;
+
+  /* Smooth transitions for the icon's visual states: the activate-point
+     pop (`scale`, see `.is-activating` below) and the removal fade
+     (`scale` + `opacity`, see `.is-removing` below). 0.2s is an example
+     duration. */
+  transition: scale 0.2s ease, opacity 0.2s ease;
+
+  background: var(--action-icon) center / contain no-repeat;
+}
+/* Inset from the row edge (example values; adjust to match your layout). */
+.SwipeableList-item.is-initialized::before { left: 1.5em; }
+.SwipeableList-item.is-initialized::after  { right: 1.5em; }
+
+/* Activating pop: scale the icon up when the user is past the visual
+   activate point, so the row's affordance feels reactive. Toggled by JS
+   in Step 4. */
+.SwipeableList-item.is-activating::before,
+.SwipeableList-item.is-activating::after {
+  scale: 1.333;
+}
+
+/* Removal affordance: fade and shrink the icons as the row collapses.
+   Driven by the `is-removing` class added in Step 4 at commit time;
+   the existing `transition` on the icons animates the change. */
+.SwipeableList-item.is-removing::before,
+.SwipeableList-item.is-removing::after {
+  scale: 0.5;
+  opacity: 0;
+}
+
+/* Only show the icon on the *leading* side of the swipe; hide the
+   trailing-side one. `data-swipe-direction` is set by JS in Step 4. */
+.SwipeableList-item.is-activating[data-swipe-direction="left"]::after,
+.SwipeableList-item.is-activating[data-swipe-direction="right"]::before {
+  visibility: hidden;
+}
+```
+
+### Step 4: Detect the commit gesture with `IntersectionObserver`
+
+Use `IntersectionObserver` rooted at the track, observing the content. As the user swipes, the content's intersection ratio with the track drops; we use **two thresholds**:
+
+- `activateThreshold`: a high ratio (e.g., 0.8). When the visible portion of the content drops below this, the user is past the visual activate point. Toggle the icon-pop affordance.
+- `commitThreshold`: a low ratio (e.g., 0.2). When the visible portion drops below this, the user has committed. Start the remove animation **immediately**, without waiting for the snap gesture to fully settle. The collapsing row blends into the user's continuing swipe momentum, which feels more responsive than waiting for the snap to land before reacting.
+
+Two more concerns are handled here:
+
+- **Lazy per-item setup**: a single outer `IntersectionObserver` rooted at the viewport drives setup and the start/stop of the inner swipe observers. Items only get wired up the first time they scroll into view, and items that scroll off-screen have their swipe observer paused. This keeps the active observer count bounded and avoids reading layout-dependent values (like `clientWidth`) before the item has been rendered.
+- **Dynamic items**: real lists grow over time (initial render, infinite scroll, server push). A `MutationObserver` on the `<ul>` registers any newly added items with the outer observer.
+
+```js
+// Per-item handles. Populated when an item is first lazily wired up; read by
+// the outer viewport observer to start/stop the inner observer as items enter
+// and leave the viewport.
+const swipeObservers = new WeakMap();
+
+// Outer observer: drives the entire swipe lifecycle off viewport visibility.
+// On first entry, lazily wires the item up (`setupItem` reads layout-dependent
+// values like `clientWidth`, which return 0 until the item is rendered). After
+// setup, starts the inner observer. On exit, stops the inner observer so
+// offscreen items don't track scroll positions.
+const viewportObserver = new IntersectionObserver((entries) => {
+  for (const entry of entries) {
+    const item = entry.target;
+    if (entry.isIntersecting) {
+      const handle = swipeObservers.get(item) ?? setupItem(item);
+      handle.observer.observe(handle.content);
+    } else {
+      const handle = swipeObservers.get(item);
+      if (handle) handle.observer.unobserve(handle.content);
+    }
+  }
+});
+
+function setupItem(item) {
+  const track = item.querySelector('.SwipeableList-track');
+  const content = track.querySelector('.SwipeableList-content');
+
+  // Upgrade the row into "swipeable" mode. This is the gate for all the CSS
+  // from Steps 2 and 3 (the track becomes a snap container, the action icons
+  // appear). Done *before* the inner observer is attached so the snap
+  // container exists by the time intersection callbacks can fire.
+  item.classList.add('is-initialized');
+
+  // Tunable thresholds. `activateThreshold` is the visual feedback point
+  // (icon pops). `commitThreshold` is the point of no return: once the
+  // content is past this point of being off-screen, we commit even if the
+  // user releases mid-gesture and the track snaps back. A low value (~0.2)
+  // commits before the snap settles, so the remove animation can start
+  // during the swipe.
+  const activateThreshold = 0.8;
+  const commitThreshold = 0.2;
+
+  // One inner observer per item, rooted at the track. Vertical scrolling of
+  // the outer list moves root and target together, so the callback only fires
+  // for the horizontal swipe.
+  const observer = new IntersectionObserver((entries, observer) => {
+    const entry = entries.at(-1);
+    const ratio = entry.intersectionRatio;
+
+    // Direction the user is swiping toward. A positive offset from the
+    // track's left edge means the content has been pulled right (left
+    // spacer revealed), so the leading icon is on the left.
+    const direction = (entry.boundingClientRect.x - entry.rootBounds.x) > 0
+      ? 'left'
+      : 'right';
+
+    if (ratio < commitThreshold) {
+      // The IO entry's boundingClientRect is the last reliable measurement
+      // before the animation starts; reuse it for both the pre-collapse
+      // height and the slide-off translate distance.
+      removeItem(item, content, direction, entry);
+      viewportObserver.unobserve(item);
+      observer.disconnect();
+      return;
+    }
+
+    // Scale up the leading icon while the content is past the activate
+    // point; restore it at rest.
+    item.classList.toggle('is-activating', ratio < activateThreshold);
+
+    // Hold the previous direction at rest so the icon's exit animation
+    // finishes on the side the user was swiping toward.
+    if (entry.boundingClientRect.x !== entry.rootBounds.x) {
+      item.dataset.swipeDirection = direction;
+    }
+  }, {
+    root: track,
+    threshold: [commitThreshold, activateThreshold],
+  });
+
+  // Return the handle without starting observation; the outer viewport observer
+  // calls `observer.observe(content)` once the item is in view.
+  const handle = {observer, content};
+  swipeObservers.set(item, handle);
+  return handle;
+}
+
+async function removeItem(item, content, direction, entry) {
+  const opts = { duration: 300, easing: 'ease', fill: 'forwards' };
+
+  const rect = entry.boundingClientRect;
+  // Content's pixel offset from the track's left edge.
+  const x = rect.x - entry.rootBounds.x;
+  // Pixel distance the content needs to travel to be fully out of view.
+  const translate = direction === 'left'
+    ? rect.width - x
+    : -(x + rect.width);
+
+  // Use a combination of CSS transitions (for declarative styles) and
+  // WAAPI animations (for computed values) to remove the element,
+  // then await the completion of all of them.
+  // Note: the content translate animation is important because the
+  // height-collapse animation can otherwise finish before the browser's
+  // smooth scroll-snap has scrolled the content fully off-screen.
+  item.classList.add('is-removing');
+  item.animate([{ height: `${rect.height}px` }, { height: '0px' }], opts);
+  content.animate([{ translate: `${translate}px` }], opts);
+  await Promise.allSettled(
+    item.getAnimations({ subtree: true }).map((a) => a.finished),
+  );
+
+  // Safari has a scroll-latching bug: removing the node while the swipe
+  // gesture's momentum is still resolving causes the next item (which
+  // slides up into this one's place) to inherit the scroll and
+  // immediately scroll itself off-screen. Detect Safari via
+  // `GestureEvent` (a Safari-only API) and defer the actual DOM removal
+  // until the gesture has fully settled. The 5s delay is conservative;
+  // anything longer than the momentum tail is fine. Mark the row inert
+  // so it can't be interacted with during the delay.
+  if (globalThis.GestureEvent) {
+    item.inert = true;
+    setTimeout(() => item.remove(), 5000);
+  } else {
+    item.remove();
+  }
+}
+
+function setupList(list) {
+  // Observe items already in the list.
+  for (const item of list.children) {
+    if (item.matches('.SwipeableList-item')) {
+      viewportObserver.observe(item);
+    }
+  }
+
+  // Pick up items added later (initial render after data loads, infinite
+  // scroll, server push). Removals don't need MutationObserver handling —
+  // the commit branch above already unobserves the item before removing it
+  // from the DOM.
+  new MutationObserver((mutations) => {
+    for (const mutation of mutations) {
+      for (const node of mutation.addedNodes) {
+        if (node.nodeType === Node.ELEMENT_NODE &&
+            node.matches('.SwipeableList-item')) {
+          viewportObserver.observe(node);
+        }
+      }
+    }
+  }).observe(list, { childList: true });
+}
+
+document.querySelectorAll('.SwipeableList').forEach(setupList);
+```
+
+### Step 5: Use the action and label that fits your use case
+
+For variants other than removal, only the visuals and the body of the commit handler change:
+
+- **Archive**: green/blue background, archive icon, move the item to an archive list rather than removing it.
+- **Mark as read**: subdued background, checkmark icon, update item state and re-render (or just remove a `.unread` class).
+- **Snooze**: blue background, clock icon, hide until a chosen time.
+
+The scroll/snap/observation mechanics are unchanged.
+
+#### Different actions per swipe direction
+
+A single row can also expose **two different actions**: one for a left swipe and one for a right swipe (e.g., "archive" on right, "delete" on left), the way many native mail apps do it. The scroll, snap, and commit-detection mechanics don't change at all — the only thing that changes is what happens at commit time.
+
+In Step 4, the commit branch always calls `removeItem(...)`. To support two actions, pick the handler based on `direction`:
+
+```js
+if (ratio < commitThreshold) {
+  const handler = direction === 'left' ? archiveItem : removeItem;
+  handler(item, content, direction, entry);
+  viewportObserver.unobserve(item);
+  observer.disconnect();
+  return;
+}
+```
+
+A note on naming: `removeItem` is named for the destructive case, but the function it runs (collapse the row's height, slide the content off-screen, then drop the node) is really a generic "this row is done, animate it away" routine. It works just as well for archive, mark-as-read, or snooze — the row goes away from *this* list either way. If your handlers don't actually remove anything (e.g., both move the item elsewhere), rename it to something neutral like `dismissItem` so the code reads correctly.
+
+To make the two actions visually distinct, hoist a color and icon for each direction onto the list item, then paint the track with a split gradient and the two pseudo-element icons from the same variables.
+
+```css
+.SwipeableList-item {
+  /* Action color + icon per swipe direction. `--left-*` is revealed
+     when the user swipes RIGHT (e.g., archive); `--right-*` is revealed
+     when the user swipes LEFT (e.g., delete). */
+  --left-action-color: hsl(140 50% 40%);
+  --left-action-icon: url("…archive svg…");
+  --right-action-color: hsl(0 65% 50%);
+  --right-action-icon: url("…trash svg…");
+}
+
+.SwipeableList-item.is-initialized .SwipeableList-track {
+  /* Split reveal: left half of the scrollable area gets the left-action
+     color, right half gets the right-action color. `background-attachment:
+     local` makes the gradient's positioning area the scrollable area
+     (3x the visible width), so the default size fills it and the 50% hard
+     stop lines up exactly with the midpoint of the resting content column.
+     The track's color also stays continuous behind the content as it
+     translates off, so the leading-direction color shows the whole way. */
+  background-image: linear-gradient(
+    to right,
+    var(--left-action-color) 50%,
+    var(--right-action-color) 50%
+  );
+  background-attachment: local;
+}
+
+/* Per-side icons read from the same variables. */
+.SwipeableList-item.is-initialized::before { background-image: var(--left-action-icon); }
+.SwipeableList-item.is-initialized::after  { background-image: var(--right-action-icon); }
+```
+
+With this setup, the spacers no longer need their own background-color (the track's gradient handles the reveal), so you can drop the `background-color` rule on `.SwipeableList-track::before, ::after` from Step 2 if you're using this dual-action variant.
+
+## Best practices and pitfalls
+
+- **DO** use `mandatory` snap, not `proximity`. With `proximity`, the row can rest partially scrolled, leaving the action background half-visible.
+- **DO** set `overscroll-behavior-x: none` on the track. Without it, an over-swipe can trigger the browser's back-navigation gesture on iOS/Android.
+- **DO** commit at a threshold *before* the snap settles (e.g., `commitThreshold ≈ 0.2`) rather than waiting for the content to be fully off-screen. This lets the remove animation start during the gesture, which feels significantly more responsive than waiting for the snap to land.
+- **DO** drive per-item setup from an outer viewport `IntersectionObserver` rather than wiring every item up at page load. This avoids reading layout-dependent values (`clientWidth`, etc.) before items have been rendered, and keeps the active observer count proportional to what the user can actually see.
+- **DO** use a `MutationObserver` on the list when items are added dynamically (initial render after data loads, infinite scroll, server push). Without it, items appended after page load won't get wired up.
+- **DO NOT** rely on `pointerdown`/`pointermove`/`pointerup` to drive a manual transform. You'll lose momentum, snap-back, keyboard accessibility, and reduced-motion handling that the browser gives you for free.
+- **DO** confirm destructive actions when appropriate. For "remove", consider showing an undo toast after the swipe completes; the gesture is fast and easy to trigger by accident.
+- **DO** ensure the scroll track is focusable, keyboard accessible, and that there is a visual focus affordance.
+- **DO** provide accessible alternatives for any relevant actions triggered by the swipe (e.g., a visible button, context menu, or edit mode).
+
+## Fallback strategies
+
+Baseline status for Scroll snap: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 69 (Sep 2018), Edge 79 (Jan 2020), Firefox 68 (Jul 2019), and Safari 11 (Sep 2017).
+
+Baseline status for Intersection observer: Widely available. It's been Baseline since 2019-03-25.
+Supported by: Chrome 58 (Apr 2017), Edge 16 (Oct 2017), Firefox 55 (Aug 2017), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for MutationObserver: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 26 (Mar 2013), Edge 12 (Jul 2015), Firefox 14 (Jul 2012), and Safari 7 (Oct 2013).
+
+Baseline status for Resize observer: Widely available. It's been Baseline since 2020-07-28.
+Supported by: Chrome 64 (Jan 2018), Edge 79 (Jan 2020), Firefox 69 (Sep 2019), Safari 13.1 (Mar 2020), and Safari iOS 13.4 (Mar 2020).
+
+Baseline status for Web animations: Widely available. It's been Baseline since 2020-09-16.
+Supported by: Chrome 84 (Jul 2020), Edge 84 (Jul 2020), Firefox 75 (Apr 2020), and Safari 14 (Sep 2020).
+
+All newer features that are used are either not core to the experience or have robust fallbacks that can be reliably used now.
+
+### Fallback for `overscroll-behavior`
+
+Browser support for overscroll-behavior: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 150 (Apr 2026).
+Unsupported in: Safari.
+
+No fallback is needed for this use case. Although `overscroll-behavior` has an interop issue that manifests on containers without scrollable overflow, the track here is always horizontally scrollable (three full-width columns inside a 100%-width container), so the property behaves consistently across browsers and the swipe gesture is reliably contained.
+
+### Fallback for `scrollbar-width`
+
+Baseline status for scrollbar-width: Newly available. It's been Baseline since 2024-12-11.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 18.2 (Dec 2024).
+
+Hidden scrollbars are a visual enhancement, not the mechanism that makes swipe-to-remove work. If your Baseline target does not include `scrollbar-width`, the row still scrolls, snaps, detects commit, and removes correctly; the unsupported experience may simply show a horizontal scrollbar. If your product requires hidden scrollbars in older WebKit-derived browsers, you can add a narrowly scoped `::-webkit-scrollbar { display: none; }` rule for the swipe track.
+
+### Fallback for `scroll-initial-target`
+
+Browser support for scroll-initial-target: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target does not include `scroll-initial-target`, scroll the track to the content programmatically inside `setupItem`. Detect with `CSS.supports`:
+
+```js
+// Hoist the feature detect so the conditional `ResizeObserver` below can be
+// skipped entirely when the property is supported.
+const needsScrollWorkaround = !CSS.supports('scroll-initial-target', 'nearest');
+
+function setupItem(item) {
+  // ...existing setup from Step 4...
+
+  if (needsScrollWorkaround) {
+    track.scrollLeft = track.clientWidth;
+  }
+
+  // ...attach the inner IntersectionObserver, etc.
+}
+```
+
+**Call ordering matters.** The programmatic scroll MUST run:
+
+1. **AFTER** `.is-initialized` is added to the list item (the class is what turns the track into a scroll container; setting `scrollLeft` on a non-scrollable element is a no-op).
+2. **BEFORE** the inner `IntersectionObserver` from Step 4 is attached. Otherwise the initial programmatic scroll past the left spacer will be observed as a "swipe" and immediately fire the commit handler.
+
+Driving setup from the outer viewport observer (Step 4) is what makes this reliable: `setupItem` runs after the item is rendered, so `track.clientWidth` returns a real value rather than `0`.
+
+Some browsers (notably Safari) also reset the snap-container scroll position whenever the track resizes (URL-bar show/hide, viewport resize, container queries, etc.). Use a `ResizeObserver` on each track to re-apply the scroll. Gate it behind the same `CSS.supports` check — when `scroll-initial-target` is supported, the browser handles resize-time scroll restoration itself.
+
+```js
+const trackResizeObserver = needsScrollWorkaround
+  ? new ResizeObserver((entries) => {
+      for (const entry of entries) {
+        entry.target.scrollLeft = entry.target.clientWidth;
+      }
+    })
+  : null;
+
+function setupItem(item) {
+  // ...existing setup...
+
+  if (needsScrollWorkaround) {
+    track.scrollLeft = track.clientWidth;
+    trackResizeObserver.observe(track);
+  }
+
+  // ...attach the inner IntersectionObserver, etc.
+}
+```
+
+Unobserve the track before the row's height animation runs in `removeItem`, otherwise the height change re-triggers the resize callback during removal. Add this alongside the existing `viewportObserver.unobserve(item)` in the commit branch:
+
+```js
+if (ratio < commitThreshold) {
+  removeItem(item, content, direction, entry);
+  viewportObserver.unobserve(item);
+  if (needsScrollWorkaround) trackResizeObserver.unobserve(track);
+  observer.disconnect();
+  return;
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-reveal.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-reveal.md
new file mode 100644
index 00000000..13a72048
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-behaviors/swipe-to-reveal.md
@@ -0,0 +1,164 @@
+# Swipe to reveal
+
+Swipe-to-reveal patterns let users slide a foreground row or content pane horizontally to expose hidden UI—such as contextual action buttons (*Pin*, *Mute*, *Archive*, *Delete*) or a secondary side menu—**without automatically activating any action**. Instead of committing an action during the swipe, the container snaps open to reveal interactive controls that the user can inspect and activate, or swipe back to close.
+
+> For a full-width swipe gesture that immediately commits and dismisses an item past a threshold, see `swipe-to-remove` (via `npx -y modern-web-guidance@latest retrieve "swipe-to-remove"`). For revealing a hidden header at the top of a vertical scroll container, see `pull-to-reveal` (via `npx -y modern-web-guidance@latest retrieve "pull-to-reveal"`).
+
+## How to implement
+
+Whether you are revealing action buttons on a list item or a side menu next to a scrollable pane, the mechanics are identical: wrap the foreground content and the hidden panel inside an outer horizontal scroll container configured with **CSS Scroll Snap** (`scroll-snap-type: x mandatory`) and **`overscroll-behavior: chain`**. The browser's native scrolling engine handles momentum, snapping, keyboard focus scrolling, and scroll chaining without JavaScript gesture listeners.
+
+### Step 1: Mark up the swipe wrapper, content, and revealed panel
+
+Place the foreground content first and the revealed controls (action buttons or a side menu) second inside the `.SwipeReveal` scroll container. Because the content is first in DOM order, the scroll container naturally starts at scroll offset `0` with the panel hidden off-screen to the right.
+
+```html
+<!-- Example A: List item with revealable action buttons -->
+<div class="SwipeReveal">
+  <div class="SwipeReveal-content">
+    <strong>Design review notes</strong>
+    <p>Updated component specs for the Q3 release.</p>
+  </div>
+  <div class="SwipeReveal-panel" role="group" aria-label="Item actions">
+    <button type="button">Pin</button>
+    <button type="button">Archive</button>
+    <button type="button">Delete</button>
+  </div>
+</div>
+
+<!-- Example B: Scrollable content pane with a revealable side menu -->
+<div class="SwipeReveal" role="region" aria-label="Document preview with swipeable side menu">
+  <div class="SwipeReveal-content is-scrollable" tabindex="0">
+    <h2>Article Preview</h2>
+    <p>Scroll vertically through this pane, or swipe left to reveal the side menu...</p>
+  </div>
+  <nav class="SwipeReveal-panel" aria-label="Contextual menu">
+    <a href="#share">Share</a>
+    <a href="#bookmark">Bookmark</a>
+    <a href="#export">Export PDF</a>
+  </nav>
+</div>
+```
+
+### Step 2: Configure the horizontal snap container and `overscroll-behavior: chain`
+
+When you wrap an element in an outer scroll container solely to create a swipe-to-reveal effect, that outer wrapper becomes an intermediate scroller inside the document (or another parent scroll container).
+
+The four keywords of `overscroll-behavior` independently control whether excess scroll propagates to an ancestor scroll container (**scroll chaining**) and whether the container displays local overscroll affordances such as elastic rubber-band stretching or edge glow (**local boundary effect**):
+
+| Value | Scroll Chaining (Propagates to Ancestor) | Local Boundary Effect (Rubber-band / Glow) | Role in Swipe-to-Reveal |
+| :--- | :--- | :--- | :--- |
+| `auto` | Yes | Yes | Default behavior; keep this on inner content scrollers where normal bounce feedback is desired, but avoid on the outer swipe wrapper where it causes the menu to bounce |
+| `chain` | **Yes** | **No** | **Use on the outer `.SwipeReveal` scroller so excess scroll chains into the parent scroller (such as the document) without the menu or action strip bouncing** |
+| `contain` | No | Yes | Traps scroll inside the container while still bouncing locally |
+| `none` | No | No | Blocks both local bounce and scroll chaining to ancestors |
+
+Make `.SwipeReveal` a two-column grid (`grid-template-columns: 100% max-content`) where `.SwipeReveal-content` snaps to `start` and `.SwipeReveal-panel` snaps to `end`:
+
+```css
+.SwipeReveal {
+  /* Column 1: full-width content. Column 2: auto-sized actions or side menu. */
+  display: grid;
+  grid-template-columns: 100% max-content;
+  overflow-x: auto;
+  scroll-snap-type: x mandatory;
+  scrollbar-width: none;
+
+  /* Prevent the swipe wrapper and revealed panel from bouncing locally while
+     still chaining excess scroll into the parent scroller (the document). */
+  overscroll-behavior: chain;
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .SwipeReveal {
+    scroll-behavior: smooth;
+  }
+}
+
+.SwipeReveal-content {
+  scroll-snap-align: start;
+  scroll-initial-target: nearest;
+  background: Canvas;
+}
+
+.SwipeReveal-content:focus-visible {
+  outline: auto;
+  outline-offset: -2px;
+}
+
+.SwipeReveal-content.is-scrollable {
+  block-size: 20rem;
+  overflow: auto;
+  /* Keeps default `overscroll-behavior: auto` so the content pane retains
+     its normal bounce effect while chaining horizontal swipes to `.SwipeReveal`. */
+}
+
+.SwipeReveal-panel {
+  /* Snapping a trailing panel to `end` (or a leading panel to `start`) brings
+     all controls fully into view while keeping the adjacent edge of the content visible. */
+  scroll-snap-align: end;
+  display: flex;
+
+  &:first-child {
+    scroll-snap-align: start;
+  }
+}
+```
+
+> If you also want to reveal controls on the left (`inline-start`) side using three columns (`grid-template-columns: max-content 100% max-content`) or two columns (`max-content 100%`), place the leading `.SwipeReveal-panel` before `.SwipeReveal-content`. Because `.SwipeReveal-content` has `scroll-initial-target: nearest`, the scroll container initially rests on the content column rather than the leading panel.
+
+### Step 3: Snap focusable content panes back into view on keyboard focus
+
+Because the buttons or links inside `.SwipeReveal-panel` are off-screen at rest, tabbing into them with a keyboard automatically scrolls `.SwipeReveal` to reveal the focused control. However, because `.SwipeReveal-content` spans `100%` of the outer container's width, most of it remains inside the scrollport even while the side panel is open—so pressing `Shift+Tab` to move focus back onto `.SwipeReveal-content` (or onto a focusable element inside it) will not automatically scroll the track back to `0`.
+
+Listen for `focusin` on `.SwipeReveal-content` and check `event.target.matches(':focus-visible')` so keyboard focus on the pane or any descendant snaps `.SwipeReveal-content` back to the start without interfering with pointer clicks or touch drags:
+
+```js
+for (const content of document.querySelectorAll('.SwipeReveal-content')) {
+  content.addEventListener('focusin', (event) => {
+    if (event.target.matches(':focus-visible')) {
+      content.scrollIntoView({
+        block: 'nearest',
+        inline: 'start',
+      });
+    }
+  });
+}
+```
+
+## Best practices and pitfalls
+
+- **DO** use `scroll-snap-type: x mandatory` rather than `proximity`. With `proximity`, a light swipe can leave the action buttons or side menu partially exposed at rest.
+- **DO** set `overscroll-behavior: chain` on the outer horizontal swipe-to-reveal scroller (`.SwipeReveal`) so scroll can chain into the parent scroller without the revealed menu or action strip bouncing.
+- **DO** leave `overscroll-behavior: auto` (the default) on inner scrollable content panes (`.SwipeReveal-content.is-scrollable`) where you want normal bounce feedback to happen while still chaining horizontal swipes to the outer swipe scroller.
+- **DO** implement revealed actions and side-menu items as real focusable DOM controls (`<button>`, `<a>`). When `.SwipeReveal-content` is focusable or contains focusable controls, pair a `focusin` listener with `event.target.matches(':focus-visible')` to call `scrollIntoView({ block: 'nearest', inline: 'start' })` so tabbing back into the content pane closes the side panel without affecting pointer interactions.
+- **DO NOT** intercept `wheel`, `touchmove`, or `pointermove` events in JavaScript to manually translate the content or emulate scroll chaining. Main-thread gesture interception blocks compositor-driven scrolling, breaks native scroll momentum, and degrades responsiveness.
+
+## Fallback
+
+Browser support for scroll-initial-target: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+When a `.SwipeReveal` container places a `.SwipeReveal-panel` on the left (`inline-start`) side before `.SwipeReveal-content`, browsers that do not support `scroll-initial-target: nearest` will initially render at scroll offset `0` with the leading panel exposed.
+
+If your Baseline target does not support `scroll-initial-target`, detect support with `CSS.supports('scroll-initial-target', 'nearest')` and call `scrollTo()` with `behavior: 'instant'` on `load` so containers with a leading panel jump straight to `.SwipeReveal-content` without scrolling the page:
+
+
+## Progressive enhancement
+
+Browser support for overscroll-behavior: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 150 (Apr 2026).
+Unsupported in: Safari.
+
+Baseline status for Scroll snap: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 69 (Sep 2018), Edge 79 (Jan 2020), Firefox 68 (Jul 2019), and Safari 11 (Sep 2017).
+
+Baseline status for scrollbar-width: Newly available. It's been Baseline since 2024-12-11.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 18.2 (Dec 2024).
+
+Treat `overscroll-behavior: chain` and `scrollbar-width: none` as progressive enhancements without JavaScript fallbacks:
+
+- **Automatic CSS cascade fallback**: The initial value of `overscroll-behavior` is `auto`. Browsers that do not yet recognize the `chain` keyword ignore `overscroll-behavior: chain` at parse time and retain `auto`. Because `auto` already allows scroll chaining to ancestor scroll containers, both the swipe-to-reveal gesture and scroll chaining to the parent work across all browsers out of the box; supporting browsers simply suppress the unwanted rubber-band bounce on the outer swipe wrapper.
+- **Overriding `contain` or `none`**: If a base stylesheet or utility class sets `overscroll-behavior: contain` or `none`, declare `overscroll-behavior: auto` immediately before `overscroll-behavior: chain` so browsers that do not yet support `chain` still chain scrolling to the parent rather than trapping it.
+- **Scrollbar hiding (`scrollbar-width: none`)**: Hiding the horizontal scrollbar track is purely cosmetic; if an older engine ignores `scrollbar-width: none`, the swipe-to-reveal container remains fully functional with a standard scrollbar.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/card.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/card.md
new file mode 100644
index 00000000..81fb9732
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/card.md
@@ -0,0 +1,132 @@
+# Build a Card
+
+## Overview
+
+A card groups one related piece of content or one choice. It is a visual pattern, not a fixed semantic or interaction model, so preserve the content's meaning and use the native interaction that matches its purpose.
+
+## Guidelines
+
+Choose semantics for the content and its interaction separately:
+
+- use `<article>` as the card root, whether or not it links to a destination;
+- use a native link for navigation. When the whole card is one destination, a single link may wrap the `<article>` only if the card contains no other interactive elements (`a`, `button`, `input`, `select`, `textarea`);
+- keep links and buttons for independent actions as separate native controls;
+- use a radio button or checkbox with an associated `<label>`, or an `option` in a native `<select>`, when the card is a choice.
+
+Keep media, title, supporting content, and actions in meaningful source order; don't use CSS `order` to contradict it (see `css-layout` (via `npx -y modern-web-guidance@latest retrieve "css-layout"`)).
+
+## Implementation
+
+Keep the markup minimal and let CSS selectors recognize each region, so simple cards stay simple and richer cards stay possible. A card has up to four regions, in this source order, and any of them can be omitted. Regions are direct children of the card, not grouped in wrapper elements such as `.card__body`, which prevents placing and styling regions by selector. A region with a single element is that element itself, not wrapped: a lone paragraph is the `<p>`. Use a wrapper only when a region holds multiple elements.
+
+- **Media**: an `<img>`, `<picture>`, `<video>`, or `<svg>` as the first child. Add a `.media` class only to arbitrary hero content that is not one of those elements, and never wrap a plain `<img>` in a `.media` element.
+- **Header**: a heading on its own. Use `<hgroup>` only when the heading has a subtitle or tagline, and `<header>` when the region carries more than a title, such as a byline or badge. When the card has a primary destination, the link goes inside the heading.
+- **Content**: a single `<p>`, `<ul>`, or `<dl>` stands on its own. When the content is several elements, such as multiple paragraphs or a paragraph plus a list, group them in one `<div>` so the region is a single grid item.
+- **Footer**: a `<footer>` holding independent actions as native links and buttons. A "read more" link may share the heading link's URL, but give it a descriptive accessible name that starts with the visible text, using visually hidden text (for example, `Read more<span> about poached eggs</span>`), because identical "read more" links are ambiguous in a screen reader's link list. Don't add other footer links that repeat the heading's URL.
+
+The simplest card is an `<article>` containing a heading and a paragraph. Choose the link and action pattern that matches the card's behavior; see [Interaction models](#interaction-models).
+
+For card images or video that should fill a fixed-ratio area, set `aspect-ratio` and `object-fit: cover` on the `<img>` or `<video>` itself, so it fills the area without distortion (cropping may occur). Use a `.media` container's `aspect-ratio` only for other hero content. Otherwise, preserve the media's intrinsic ratio. Give informative images an appropriate text alternative; use `alt=""` for decorative images.
+
+### Adapt to available space
+
+Base the layout on the card's available space, not the viewport. To adapt the card's descendants (media, text, actions), make the card the size container (`container-type: inline-size`) and write `@container` rules against its children. Avoid sizing from the grid or list parent: the card's actual width can depend on column count, gaps and so on, making parent-based breakpoints are noisy.
+
+In a narrow container, stack the regions in source order. In a wide container, place the media in a side column beside the other regions, but only for cards that have media: scope those rules with `:has()` on the media child (for example `.card:has(> img)`) so the column definitions and `grid-column` placements never apply to a card without media. A card without media stays single-column at every width, and must not reserve an empty media column.
+
+### Align cards in a grid
+
+When cards in a row should share the heights of their regions, use `subgrid`: make each card span four shared row tracks (media, header, content, footer) and place regions by element selector, treating everything that is not media, a heading, or a `<footer>` as content. A card that omits a region leaves its track empty, so the remaining regions still line up with neighboring cards. Each track holds one grid item, so wrap the content region in a `<div>` only when it has more than one element and cards share tracks. Cards that are not aligned with siblings need neither wrapper nor subgrid.
+
+## Interaction models
+
+### Content cards
+
+Use an `<article>` as the card root. Keep links and buttons as separate native controls.
+
+### Single-destination cards
+
+When the whole card is one destination and has no independent actions, use one native link. The link can wrap the `<article>`. Do not nest other links, buttons, or form controls inside the link, and keep any "read more" text a plain `<p>` or `<span>`. Because the link's accessible name is all of the card's text, keep the content short; if the card has a lot of text or other actions, use the stretched-link pattern below so only the heading is the link:
+
+```html
+<a href="/recipes/poached-eggs">
+  <article class="card">
+    <h3>Poached eggs</h3>
+    <p>Two poached eggs served on toasted sourdough.</p>
+  </article>
+</a>
+```
+
+### Clickable cards with independent actions
+
+If clicking the card triggers an action rather than navigating, use a `<button>` instead of a link.
+
+When a content card links to a primary destination, also contains other interactive elements, and needs to be clickable as a whole:
+- Use a single opt-in, on the primary link itself: put `.card-link` on exactly one link per card (the heading link). Footer and other links never get it, or each would stretch its own overlay and the last one would capture the whole card.
+- Link its title and stretch the pointer hit area across the card with `::after`
+
+```css
+.card:has(a.card-link) {
+	position: relative;
+}
+
+.card a.card-link::after {
+	content: "";
+	position: absolute;
+	inset: 0;
+}
+```
+
+- Elevate interactive elements with `position: relative; z-index: 1` so they remain operable. Target types of elements (e.g. `a, button`) rather than requiring opt-in via classes. 
+- Do NOT apply `z-index` to entire containers as that would make them capture pointer events that don't produce any action.
+
+```css
+.card:has(a.card-link) {
+	/* Keep other interactive elements above the overlay */
+	a:not(.card-link), button, input, x-button {
+	    position: relative;
+	    z-index: 1;
+	}
+}
+```
+
+- Style the card itself on hover/focus, rather than the stretched link:
+
+```css
+.card {
+	a.card-link {
+		&:focus-visible {
+			outline: none; /* Draw it on the card instead */
+		}
+	}
+	
+	&:has(a.card-link:focus-visible) {
+		/* Focus ring */
+	}
+
+	&:has(a.card-link:hover) {
+		/* Hover styles */
+	}
+}
+
+```
+
+### Choice cards
+
+For cards that represent predefined choices, use `<label class="card">` with a checkbox or radio as a direct child.
+
+Style the selected card with `:has(:checked)`. Never change layout-affecting properties such as `border-width`, `padding`, or `font-weight` on selection, because the card and its neighbors jump; draw the emphasis with `outline`, `box-shadow`, or a transparent border that only changes color:
+
+```css
+.card {
+  border: 2px solid transparent;
+
+  &:has(> :checked) {
+    border-color: var(--accent);
+  }
+}
+```
+
+The visible checkbox or radio is itself a non-color indicator of selection, so the color change alone is sufficient. If the control is visually hidden (keep it focusable and in the accessibility tree, never `display: none`), add a non-color indicator that does not affect layout, such as a check icon or a thicker `outline`.
+
+When choices belong in a dropdown picker whose options are laid out as cards, use a native `<select>` with `appearance: base-select` and style `::picker(select)` and `<option>` elements rather than replacing the select with `<div>` cards; see `custom-select-picker-layouts` (via `npx -y modern-web-guidance@latest retrieve "custom-select-picker-layouts"`) for more details and fallbacks.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/checkbox.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/checkbox.md
new file mode 100644
index 00000000..53e8ab2a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/checkbox.md
@@ -0,0 +1,142 @@
+# Styling Checkboxes
+
+Use semantic, accessible HTML with each checkbox associated with its label, either by nesting the `<input>` inside the `<label>` or by matching the label’s `for` attribute to the input’s `id`.
+
+Modern CSS provides two approaches to styling checkboxes: customize the native appearance with `accent-color`, or override the default presentation with `appearance: none` on the `<input type="checkbox">` element.
+
+## Native customization with `accent-color`
+
+For simple, brand-consistent styling that retains native rendering, keyboard behavior, validation, and operating-system focus indicators, use `accent-color`.
+
+```css
+.checkbox-native {
+  accent-color: #1a73e8;
+
+  /* Sizing is controlled via relative units */
+  inline-size: 1.25em;
+  aspect-ratio: 1;
+  margin: 0;
+  cursor: pointer;
+}
+```
+
+## Fully custom styling with `appearance: none`
+
+Use `appearance: none` when the design requires control over the checkbox’s
+shape, size, states, or indicators. This removes the native visual styling while
+leaving the `<input>` as the interactive target.
+
+Set explicit relative sizes for `--checkbox-size` and `--checkbox-icon-size` because `appearance: none` removes the browser’s default dimensions. Keep the icon smaller than the checkbox to provide space for its border and visual padding.
+
+```css
+/* Reusable SVG assets */
+:root {
+  --icon-check: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='3.5' stroke-linecap='round' stroke-linejoin='round'><polyline points='20 6 9 17 4 12'></polyline></svg>");
+  --icon-dash: url("data:image/svg+xml;utf8,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='black' stroke-width='4.5' stroke-linecap='round' stroke-linejoin='round'><line x1='5' y1='12' x2='19' y2='12'></line></svg>");
+}
+
+/* Custom checkbox */
+.checkbox-custom {
+  --checkbox-size: 1.25em;
+  --checkbox-icon-size: 0.7em;
+
+  appearance: none;
+  display: inline-grid;
+  place-content: center;
+  inline-size: var(--checkbox-size);
+  aspect-ratio: 1;
+  margin: 0;
+  border: 2px solid currentColor;
+  cursor: pointer;
+
+  &::before {
+    content: "";
+    inline-size: var(--checkbox-icon-size);
+    aspect-ratio: 1;
+    background-color: currentColor;
+    mask: var(--checkbox-icon) no-repeat center / contain;
+    scale: 0;
+
+    @media (prefers-reduced-motion: no-preference) {
+      transition: scale 150ms ease;
+    }
+
+    @media (forced-colors: active) {
+      background-color: CanvasText;
+    }
+  }
+
+  &:checked {
+    --checkbox-icon: var(--icon-check);
+  }
+
+  &:indeterminate {
+    --checkbox-icon: var(--icon-dash);
+  }
+
+  &:is(:checked, :indeterminate)::before {
+    scale: 1;
+  }
+
+  &:focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    cursor: not-allowed;
+    opacity: 0.5;
+  }
+}
+```
+
+
+## The indeterminate state
+
+The indeterminate state cannot be set via an HTML attribute; set the `indeterminate` DOM property in JavaScript (`checkbox.indeterminate = true`) and ensure the `:indeterminate` pseudo-class is visually distinct from both `:checked` and unchecked states:
+
+* **Native (`accent-color`):** Automatically styled by the browser using the element's `accent-color` (no extra `:indeterminate` CSS rule needed).
+* **Custom (`appearance: none`):** Swap `--checkbox-icon` to `var(--icon-dash)` on `.checkbox-custom:indeterminate` as shown above.
+
+```js
+const selectAll = document.querySelector("#select-all");
+selectAll.indeterminate = true;
+```
+
+## Accessibility and interaction
+
+- **DO** use `:focus-visible` rather than `:focus` to style focus indicators on custom checkboxes so a distinct outline appears for keyboard navigation without showing on pointer clicks.
+- **DO NOT** use `outline: none` or hide focus indicators on checkboxes.
+- **DO** ensure the checkbox or its wrapping `<label>` provides an interactive hit target of at least `44px x 44px` while keeping the visual checkbox box sized in relative units:
+  ```css
+  label {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.65rem;
+    min-block-size: 44px;
+    cursor: pointer;
+  }
+  ```
+- **DO** provide a `:disabled` style variant that lowers opacity and sets `cursor: not-allowed` to convey inactive states clearly.
+
+### Issues to be aware of when using accent-color
+
+Browser rendering of `accent-color` varies.
+For indicators generally painted over an accent color background, such as checkbox marks and radio-button dots, browsers may apply different treatments:
+- **Chromium** and **Firefox** generally select a contrasting indicator color.
+- **Safari** may instead preserve a white indicator in light mode or a black indicator in dark mode, while modifying the accent color behind it. This adjustment does not always provide sufficient contrast for every supplied color, so test important combinations in Safari, including both light and dark color schemes. Do not assume that Safari will automatically choose whichever indicator color provides the best contrast.
+
+## Fallback strategies
+
+### Fallbacks & browser support for accent-color
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+The `accent-color` property is progressive enhancement.
+Browsers that do not support this property will ignore it and use their default UI colors.
+
+### CSS Masks
+
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dark-mode-toggle.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dark-mode-toggle.md
new file mode 100644
index 00000000..cec6288b
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dark-mode-toggle.md
@@ -0,0 +1,138 @@
+# Dark mode toggles
+
+A dark mode toggle lets users override the system color scheme for one site.
+The override is applied by updating `<meta name="color-scheme">`: `light dark` means "follow the system preference", `light` or `dark` pin an explicit scheme.
+Colors (`light-dark()`), system colors, and native UI all key off the CSS `color-scheme` property, so the toggle works by keeping that property in sync with the `<meta>` (see [Reflect the override in CSS](#reflect-the-override-in-css)).
+
+## Persistent toggle, settings control, or no toggle at all?
+
+Most sites do not need a persistent color scheme toggle in the site UI (header, nav, footer, etc.).
+Follow the system preference by default and, if a manual override is needed at all, put the control in a separate settings surface: a settings page, panel, or overlay.
+
+Pinning a scheme against the OS is a legitimate but rare intent, and rare intents belong behind progressive disclosure, not in a control that is visible at all times.
+
+Persistent toggles are mostly found on developer-facing or developer-adjacent (e.g. for designers) sites, where switching schemes is a far more frequent task than it is for the average web user.
+Do NOT add one just because it is a common pattern on developer sites: the developer's interest in this control is not representative of typical users.
+
+## Implementation
+
+First, follow all steps in `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`) to support both schemes, defaulting to the system preference.
+
+### Data model
+
+The data model for the dark mode toggle typically includes three states:
+1. System (no stored value): The UI follows the system color scheme. Ideally this should be the default.
+2. Light (stored as `"light"`): The UI uses the light theme regardless of the system color scheme.
+3. Dark (stored as `"dark"`): The UI uses the dark theme regardless of the system color scheme.
+
+This state is usually stored in `localStorage` and reflected in a `<meta name="color-scheme">` element in the document head.
+
+### Reflect the override in CSS
+
+The `<meta>` is only a *presentational hint*: any `color-scheme` declaration in author CSS overrides it.
+Since `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`) sets `color-scheme: light dark` on `:root`, updating the `<meta>` alone is a **no-op** — CSS wins.
+Map the `<meta>` back to the property so the cascade follows it:
+
+```css
+:root {
+  color-scheme: light dark;
+
+  &:has(> head > meta[name="color-scheme"][content="dark"]) {
+    color-scheme: dark;
+  }
+  &:has(> head > meta[name="color-scheme"][content="light"]) {
+    color-scheme: light;
+  }
+}
+```
+
+**DO NOT** hardcode `color-scheme: light` or `color-scheme: dark` as the root default; the base declaration MUST stay `light dark`.
+CSS MUST NOT depend on JS: if JS never runs, the `<meta>` stays `light dark` and the site follows the system preference — nothing breaks.
+
+### Persistence and FOUC prevention
+
+Persist the override in `localStorage`; remove the entry when returning to the system default.
+
+To avoid a flash of the wrong scheme, apply the stored value in an inline script (NOT `type=module`, NOT `defer`) placed immediately after the `<meta>` element:
+
+```html
+<meta name="color-scheme" content="light dark">
+<script>
+document.querySelector('meta[name="color-scheme"]').content = localStorage.getItem("color-scheme") ?? "light dark";
+</script>
+```
+
+- This inline script exists **only** for FOUC prevention. Keep it as small as possible; additional JS for handling color scheme toggling can load later.
+- In rare cases `localStorage` access can throw (e.g. site data blocked), but since this script does nothing else, the only side effect would be a console error. Wrap in `try .. catch` if this matters. Ensure the theme is still applied to the page, even if it cannot be persisted.
+- The override can change from another tab: handle `window`'s `storage` event to stay in sync.
+- **DO NOT** use `matchMedia()` to remove the stored value when the system preference changes to match it.
+Many users' OS switches schemes automatically based on time of day; removing the stored value whenever the two happen to coincide would make it impossible to pin a scheme at all.
+
+### Branching for HTML and non-color values
+
+Colors need no extra work: once the `<meta>` is mapped to `color-scheme` (above), `light-dark()` follows the override.
+This section is about adapting other values (e.g. `font-weight`, media sources, etc.).
+
+When the page simply follows the system preference, `(prefers-color-scheme: dark)` can be used for branching, including in `<picture>` or `<video>` sources.
+Overriding the color scheme adds an additional complication: the system preference is no longer the source of truth, and for APIs that only accept media queries there is no direct alternative.
+
+Do NOT rely exclusively on JS-applied classes like `.dark` for branching, as they will be incorrect if JS doesn't load and the OS default is dark.
+
+You can combine the media query with a `:root:has(> head > meta[name="color-scheme"][content="dark"])` (or `light`) selector to branch.
+See `selector-atrule-combinations` (via `npx -y modern-web-guidance@latest retrieve "selector-atrule-combinations"`) for details on how to implement this elegantly.
+
+The control's own options are non-color branches too: include both states in the markup (icon plus visually hidden action text, e.g. "Switch to dark theme") and hide the inactive one via these selectors.
+`display: none` also removes the redundant option from the AT so the control needs no JS to stay current when the system preference changes.
+
+For in-HTML media, the only way right now is to include both versions as separate elements and toggle visibility appropriately.
+Hiding `<source>` elements with `display: none` does not work.
+
+## User Interface
+
+### Two or three states?
+
+In all cases, the UI MUST support reverting or setting the color scheme to system.
+
+Prefer displaying two states in space-constrained toggles, such as persistent toggles in the site chrome (header, nav, footer, etc.) where space is limited and tweaking settings is usually orthogonal to the user goal.
+
+A color scheme control in a separate settings surface (page, panel, or overlay) is a different scenario and MAY expose all three states explicitly ("Light", "Dark", "System"): there, the user is already making deliberate decisions about future behavior, and there is room to explain the options.
+
+Three explicit states are also warranted if the site implements context-aware schemes (e.g. a dimmer light mode when the OS is dark), since "Light" and "System (currently light)" then genuinely differ.
+
+### Two-state toggles
+
+When such a control is used, it tends to be a temporary comfort adjustment ("it's too bright right now"), rather than ensuring the current state is preserved long-term.
+Therefore, for two-state toggles, it is sufficient to display two out of three settings: system (so that the setting can be reverted) and the current opposite of system, stored as its current literal value.
+
+The only two states should be:
+
+1. **System default** — no stored value, `<meta>` content `light dark`. Displayed as its current resolved value (e.g. a sun icon when light).
+2. **Override** — stored literally as `light` or `dark`.
+
+Essentially, it is a tri-state control (`light dark`, `light`, `dark`) where the explicit state matching the current system preference is unreachable.
+
+When the user toggles:
+
+1. Target scheme = the opposite of the currently *rendered* scheme (stored value if any, else system preference). The user intent is "select the opposite of what I see right now", NOT "select the inverse of the system default".
+2. If the target differs from the current system preference, store it literally.
+3. If the target matches the current system preference, the user is undoing their adjustment: remove the stored value. DO NOT store it — that would invisibly pin the scheme against future system changes.
+4. Set the `<meta>` content to the stored value, or `light dark` if none.
+
+IMPORTANT: Divergence must be checked only at storage time, never retroactively: a stored value that the system preference later changes to match MUST be kept.
+Many users' OS switches schemes automatically based on time of day; removing the stored value whenever the two happen to coincide would make it impossible to pin a scheme at all.
+
+Example scenario, starting with the OS set to light:
+
+1. The user toggles. Dark differs from the system preference, so `dark` is stored; the site turns dark.
+2. The OS setting changes to dark. The site stays dark (the stored value now matches the system preference, but is kept).
+3. The OS setting changes back to light. The site stays dark.
+4. The user toggles. The target (light) matches the system preference, so the stored value is removed and the site follows the system again.
+
+### Three-state toggles
+
+When there is more space and users are already in the mindset of setting long-term preferences, a tri-state control can provide more clarity.
+In this case, the data model cleanly maps to the three UI options: system, light, and dark.
+
+To reduce cognitive load, the "system" option should also display what the current system setting is, for example via:
+- Icon, e.g. a sun icon at the bottom right of the system icon
+- Text, e.g. "System (Currently light)"
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dialog.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dialog.md
new file mode 100644
index 00000000..fbd3c21e
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/dialog.md
@@ -0,0 +1,226 @@
+# Dialog
+
+## Overview
+
+Use the native `<dialog>` element for modal and non-modal dialogs. It provides the accessibility semantics, focus handling, top-layer rendering and `Esc` handling that custom overlays have to rebuild by hand.
+
+## Choose the overlay type
+
+Pick the first rule that matches. If unsure, use Rule 1.
+
+### Rule 1: The overlay interrupts the user and blocks the page (default)
+
+Use for confirmations, forms, sign-in, destructive actions, and any "modal", "dialog", "lightbox" or "popup" request that does not say otherwise.
+
+Use `<dialog>` opened as a modal, declaratively with `command="show-modal"` (see `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`)) or from script with `showModal()`.
+
+```html
+<button type="button" command="show-modal" commandfor="confirm">Delete</button>
+
+<!-- MANDATORY: no role="dialog" or aria-modal; the native modal already provides them -->
+<dialog id="confirm" aria-labelledby="confirm-title">
+  <h2 id="confirm-title">Delete this item?</h2>
+  <form method="dialog">
+    <button value="cancel" autofocus>Cancel</button>
+    <button value="delete">Delete</button>
+  </form>
+</dialog>
+```
+
+The browser provides: inert page, focus containment, top layer, `::backdrop`, `Esc` and back-gesture dismissal, and focus return to the invoker.
+
+- **DON'T** add `role="dialog"`, `aria-modal`, a focus trap, `inert` toggling or an `Esc` handler.
+- **DON'T** open it with `show()` or the `open` attribute.
+- **DO** stop the page scrolling behind it with the CSS below. See `prevent-page-scroll-under-modal-dialog` (via `npx -y modern-web-guidance@latest retrieve "prevent-page-scroll-under-modal-dialog"`) for the details.
+- **DON'T** lock scrolling with `overflow: hidden` or `position: fixed` on `html` or `body`.
+
+```css
+/* MANDATORY (both rules): without them, scrolling over the backdrop or inside the dialog scrolls the page behind it */
+dialog:modal {
+  overscroll-behavior: contain; /* stops scroll gestures in the dialog chaining to the page */
+}
+dialog::backdrop {
+  overflow: hidden; /* ::backdrop is not a scroll container by default, so it would ignore overscroll-behavior */
+  overscroll-behavior: contain;
+}
+```
+
+Not for menus or tooltips: see Rule 3.
+
+### Rule 2: The user keeps working in the page while the panel is open
+
+Use for find bars, inspectors, palettes and compose panes that are still dialogs semantically.
+
+Use `<dialog popover>` for a top-layer panel with popover dismissal (`auto` light-dismisses, `manual` does not). Use `dialog.show()` only when the panel must not be in the top layer.
+
+```html
+<button type="button" popovertarget="find">Find</button>
+<dialog id="find" popover="manual" aria-labelledby="find-title">
+  <h2 id="find-title">Find</h2>
+  <input type="search" aria-label="Search">
+  <button type="button" popovertarget="find" popovertargetaction="hide">Close</button>
+</dialog>
+```
+
+The page stays interactive and is not made inert.
+
+- **DO** include a visible close button.
+- **DON'T** use `showModal()`, which blocks the page.
+
+Not for blocking confirmations: see Rule 1.
+
+### Rule 3: The overlay is not a dialog
+
+Use for menus, dropdowns, tooltips, hovercards and toasts.
+
+Use a semantic element with the `popover` attribute, not `<dialog>`.
+
+```html
+<button type="button" popovertarget="menu">Actions</button>
+<ul id="menu" popover>
+  <li><a href="/rename">Rename</a></li>
+</ul>
+```
+
+## Choose how it can be dismissed
+
+The default depends on how the dialog is opened. If `closedby` is absent or invalid, `showModal()` behaves as `closerequest` and any other way of opening behaves as `none`.
+
+- **Esc and back gesture only (modal default):** set nothing, or `closedby="closerequest"`.
+- **Also click outside to close:** use `closedby="any"`.
+- **Only the developer closes it (for example a form with unsaved changes):** use `closedby="none"` and add a confirmation path. See Closing below.
+
+## Guidelines
+
+### Accessible name and initial focus
+
+- **DO** name every dialog with `aria-labelledby` pointing at its heading, or `aria-label` when there is no visible title.
+- **DO** put `autofocus` on the primary control or first field.
+- **DO** put `autofocus` on the safe action (such as Cancel or Keep) in a destructive confirmation.
+- **DON'T** write code to return focus on close. The browser returns it to the invoker.
+
+### Opening
+
+- **DO** open declaratively with `command="show-modal"` and `commandfor` on a `<button>`. See `declarative-dialog-popover-control` (via `npx -y modern-web-guidance@latest retrieve "declarative-dialog-popover-control"`).
+- **DO** use `dialog.showModal()` when opening from script.
+
+### Closing
+
+- **DO** close with `<form method="dialog">` buttons or `command="close"`.
+- **DO** choose `closedby` deliberately: `any` (light dismiss and `Esc`), `closerequest` (`Esc` only, the modal default) or `none` (developer-controlled close only).
+- **DO** use `command="request-close"` or `requestClose()` for Cancel buttons that must honor unsaved-changes logic. They fire `cancel` first and ignore `closedby`.
+- **DO** treat `closedby` as progressive enhancement. `Esc` and the mobile back gesture already close modals without it.
+
+### Hooking into close
+
+- **DO** read `dialog.returnValue` in a `close` listener to learn which button was used, then reset it with `dialog.returnValue = ''`. `Esc` and other close requests set no value, and browsers differ on whether they clear the previous one, so without the reset a stale value can leak. Treat `''` as "dismissed without choosing".
+- **DO** use `cancel` to intercept `Esc` and `request-close`, but do not rely on `preventDefault()` for repeated `Esc` presses without user activation.
+- **DO** use `closedby="none"` with an explicit confirmation step for dirty forms.
+- **DO** tell the user why the dialog stayed open when `cancel` is prevented: show a visible message and reference it with `aria-describedby` from the control that receives focus (such as Discard), so a screen reader reads it when focus moves. Without it, focus moving to a new button announces only that button's name.
+- **DON'T** let the confirmation move controls under the pointer. Reserve the message's space (hide it with `visibility`, not `display` or `hidden`) and add the destructive button where existing buttons do not move (for example first in a right-aligned row), so a second click at the same spot cannot discard the user's changes.
+
+### Non-modal dialogs
+
+- **DO** use `<dialog popover>` (`auto` or `manual`) for a top-layer panel, and `dialog.show()` when you do not want the top layer.
+- **DO** include a visible close button in every non-modal dialog.
+
+### Backdrop and styling
+
+- **DO** style `::backdrop` and use `dialog:modal` to target modal-only styles.
+- **DO** leave animation to `animate-to-from-top-layer` (via `npx -y modern-web-guidance@latest retrieve "animate-to-from-top-layer"`), dragging to `drag` (via `npx -y modern-web-guidance@latest retrieve "drag"`), and reparenting to `persistent-top-layer-ui` (via `npx -y modern-web-guidance@latest retrieve "persistent-top-layer-ui"`).
+- **DON'T** set `display` on `dialog` unconditionally. It overrides the closed state. Scope it with `dialog[open]`.
+
+### Accessibility
+
+- **DON'T** add `role="dialog"`, `aria-modal`, a manual focus trap or `inert` toggling to a native modal.
+- **DO** use a native `<button>` with an accessible name for close controls.
+- **DO** use one consistent heading level for dialog titles.
+
+## Fallback strategies
+
+### `closedby` (`dialog-closedby`)
+
+Browser support for <dialog closedby>: Limited availability.
+Supported by: Chrome 134 (Mar 2025), Edge 134 (Mar 2025), and Firefox 141 (Jul 2025).
+Unsupported in: Safari.
+
+Without `closedby`, a modal still closes with `Esc` and the back gesture; only click-outside is lost, so this is graceful degradation. `closedby="none"` is ignored the same way: `Esc` fires `cancel` and then closes the dialog. Keep the unsaved-changes guard in a `cancel` handler, not in `closedby="none"` alone, so it also protects where `closedby` is missing. If your Baseline target requires light dismiss, add this where `closedby` is missing:
+
+```js
+if (!('closedBy' in HTMLDialogElement.prototype)) {
+  // Test the pointer position, not event.target: the <dialog> is also the target for its own
+  // padding and the gaps between its children, so a target check would close on those clicks
+  const outside = (e, dialog) => {
+    const r = dialog.getBoundingClientRect();
+    return e.clientX < r.left || e.clientX > r.right || e.clientY < r.top || e.clientY > r.bottom;
+  };
+  for (const dialog of document.querySelectorAll('dialog[closedby="any"]')) {
+    let pressedOutside = false;
+    dialog.addEventListener('pointerdown', (e) => { pressedOutside = outside(e, dialog); });
+    // Require the press and the release outside, so a text-selection drag that ends on the backdrop does not dismiss
+    dialog.addEventListener('pointerup', (e) => { if (pressedOutside && outside(e, dialog)) dialog.close(); });
+  }
+}
+```
+
+### `overscroll-behavior`
+
+Browser support for overscroll-behavior: Limited availability.
+Supported by: Chrome 144 (Jan 2026), Edge 144 (Jan 2026), and Firefox 150 (Apr 2026).
+Unsupported in: Safari.
+
+Treat scroll containment as progressive enhancement. Do not feature-detect it: `@supports` reports the property as supported even where non-scrollable containers ignore it. Where it is not enforced, the dialog still contains scroll whenever its own content overflows, and `showModal()` still makes the page inert. Do not fall back to `overflow: hidden` or `position: fixed` on `html` or `body`, which removes the root scrollbar and shifts the layout.
+
+### Invoker Commands (`command` / `commandfor`)
+
+Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).
+
+If your Baseline target does not include Invoker Commands, keep the same markup and conditionally load the polyfill (the same experience, as progressive enhancement). Detect on the interface and never load it unconditionally:
+
+```js
+// MANDATORY: feature detect on HTMLButtonElement.prototype and load only when native support is missing
+if (!('commandForElement' in HTMLButtonElement.prototype)) {
+  import('invokers-polyfill'); // npm install invokers-polyfill
+}
+```
+
+Only Rules 2 and 3 use Popover.
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/hovercard.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/hovercard.md
new file mode 100644
index 00000000..47f08b1d
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/hovercard.md
@@ -0,0 +1,279 @@
+# Build an interactive hovercard
+
+Hovercards provide an interactive preview of content when a user expresses interest in a link (via hover or focus). This is shown to users before they navigate, and either provides the user with the content they need or helps verify that the link will contain the content they are looking for.
+
+If you need plain-text, non-interactive tooltips rather than structured link previews, see `interest-triggered-tooltips` (via `npx -y modern-web-guidance@latest retrieve "interest-triggered-tooltips"`).
+
+## 1. Triggering the hovercard
+
+Use the **Interest Invokers** API to trigger the hovercard. This ensures the card appears on both hover and focus, and handles accessibility wiring automatically.
+
+- Add the `popover="hint"` attribute to your card container. Use `hint` to avoid closing unrelated popover menus that may be open.
+- Add the `interestfor` attribute to the trigger link, pointing to the card's `id`.
+
+```html
+<a href="/article" interestfor="article-preview">Article title</a>
+
+<!-- The `id` must match the `interestfor` value on the trigger. -->
+<div id="article-preview" popover="hint" class="hovercard">
+  <h2>The buzz on hummingbirds</h2>
+  <p class="byline">By Delphi Aguilar</p>
+  <div>
+    <img src="bird.jpg" alt="A vibrant hummingbird">
+    <p>Brief summary of the article...</p>
+  </div>
+</div>
+```
+
+You do not need to include an additional link to the content inside of the hovercard, as it is redundant to the triggering link. 
+
+### Accessibility built in to `interestfor`
+
+When you use `interestfor`, the browser handles the assistive-technology wiring for you:
+
+- **Implicit semantics:** A target with `popover="hint"` gains an implicit minimum role of `tooltip`. **DO NOT** set `role="tooltip"` yourself.
+- **Implicit association:** The browser implicitly associates the source element with the target via `aria-describedby` when the target is plaintext, or via `aria-details` when the target contains interactive content. **DO NOT** add `aria-describedby` or `aria-details` to the trigger.
+- **Interactive content:** Because the association switches to `aria-details` when needed, the target IS allowed to contain interactive content (e.g. a link inside an "interest card").
+
+## 2. Positioning with Anchor Positioning
+
+Position the hovercard relative to its trigger using **CSS Anchor Positioning**. When using `interestfor`, the trigger becomes an implicit anchor for the popover.
+
+```css
+[popover].hovercard {
+  /* Position the card below the trigger, aligned with its inline-start edge
+     and spanning toward the inline-end, flipping if it overflows the viewport. */
+  position-area: block-end span-inline-end;
+  position-try-fallbacks: flip-block, flip-inline;
+}
+```
+
+## 3. Animating entry and exit
+
+By default, interest is shown and lost for keyboard and mouse users with a delay of half a second. This prevents the targeted popover from opening while tabbing through a page or moving your mouse around, and from closing while moving your mouse from the trigger to the popover. To adjust the timing, use the `interest-delay` CSS property.
+
+```css
+[interestfor]{
+  /* Shorthand for interest-delay-start and interest-delay-end */
+  interest-delay: 0.2s 0.1s;
+}
+```
+
+If users are likely to move through multiple triggers in quick succession, set the initial delay to `0s` if an interest-triggered popover is already open.
+
+```css
+:root:has(:interest-source) [interestfor] {
+  interest-delay-start: 0s;
+}
+```
+
+Use `@starting-style` to define the entry animation and `transition-behavior: allow-discrete` (along with `display` and `overlay`) to animate the exit from the top layer, gating the transitions behind `@media (prefers-reduced-motion: no-preference)`.
+
+```css
+[popover].hovercard {
+  opacity: 0;
+  transform-origin: top;
+}
+
+[popover].hovercard:popover-open {
+  opacity: 1;
+  transform: translateY(0) scale(1);
+}
+
+@starting-style {
+  [popover].hovercard:popover-open {
+    opacity: 0;
+    transform: translateY(-10px) scale(0.95);
+  }
+}
+
+/* MANDATORY: Respect user preference for reduced motion by selectively applying transitions. */
+@media (prefers-reduced-motion: no-preference) {
+  [popover].hovercard {
+    transition:
+      opacity,
+      transform,
+      display,
+      overlay;
+    transition-duration: 0.4s;
+    transition-behavior: allow-discrete;
+  }
+}
+```
+
+## 4. OPTIONAL: Seamlessly morphing to the next page
+
+You can optionally use **Cross-Document View Transitions** to create a seamless "morph" animation between the hovercard and the destination page. See `consistent-cross-document-transitions` (via `npx -y modern-web-guidance@latest retrieve "consistent-cross-document-transitions"`) for guidance on implementation.
+
+By assigning matching `view-transition-name` values to elements in the hovercard and their counterparts on the next page, the browser will animate them across the navigation. You can name multiple elements (e.g. titles, images, bylines) to create a complex, multi-element morphing effect. Assign the `view-transition-name` to elements on the open popover using `:popover-open`, to avoid creating duplicate `view-transition-name`s or requiring link-specific `view-transition-name`s.
+
+```css
+/* Opt-in to cross-document transitions on both pages */
+@view-transition {
+  navigation: auto;
+}
+
+/* Don't show transitions when loading this page */
+::view-transition-group(*) {
+  animation-duration: 0s;
+}
+
+/* Assign names ONLY when the popover is open to ensure only the correct elements are selected. */
+[popover]:popover-open {
+  view-transition-name: --hovercard;
+  view-transition-class: morph;
+
+  h2 {
+    view-transition-name: --title;
+    view-transition-class: morph;
+  }
+
+  img {
+    view-transition-name: --image;
+    view-transition-class: morph;
+  }
+}
+```
+
+**MANDATORY:** To ensure the transition is stable and doesn't flicker, the destination page should use `blocking="render"` and `<link rel="expect">` to wait for critical content to be parsed before rendering the first frame.
+
+```html
+<!-- On the destination page: -->
+<head>
+  <!-- Block rendering until the hero image and title are parsed,
+       ensuring the view transition snapshot is taken at the right time. -->
+  <link rel="expect" href="#main-content" blocking="render">
+</head>
+<body>
+  <main id="main-content">
+    <h1>The buzz on hummingbirds</h1>
+    <img src="bird.jpg">
+  </main>
+</body>
+```
+
+```css
+/* On the destination page: */
+main {
+  view-transition-name: --hovercard;
+  view-transition-class: morph;
+}
+h1 {
+  view-transition-name: --title;
+  view-transition-class: morph;
+}
+img {
+  view-transition-name: --image;
+  view-transition-class: morph;
+}
+
+/* By default no transition */
+::view-transition-group(*) {
+  animation-duration: 0s;
+}
+/* Short transition for morphing elements */
+::view-transition-group(.morph) {
+  animation-duration: 0.4s;
+}
+/* Disable transition if no `old` view */
+::view-transition-new(.morph):only-child {
+  animation-duration: 0s;
+}
+```
+
+## Fallback strategies
+
+Because the trigger is a standard `<a href="...">` link, browsers without support can still navigate on click if you choose to treat the hovercard as a progressive enhancement. When cross-browser hovercard support is required, conditionally load polyfills as needed.
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+Browser support for popover="hint": Limited availability.
+Supported by: Chrome 151 (Jul 2026), Edge 151 (Jul 2026), and Firefox 153 (Jul 2026).
+Unsupported in: Safari.
+
+### Fallbacks & browser support for Interest invokers
+
+Browser support for Interest invokers: Limited availability.
+Supported by: Chrome 142 (Oct 2025) and Edge 142 (Oct 2025).
+Unsupported in: Firefox and Safari.
+
+Interest invokers must be conditionally polyfilled using the `interestfor` polyfill package from NPM. Prefer bundling the polyfill over using the CDN.
+
+**MANDATORY:** Feature detect by checking for the `interestForElement` property on `HTMLButtonElement.prototype`, and load the polyfill **only** when native support is missing.
+
+```html
+<script type="module">
+  if (!HTMLButtonElement.prototype.hasOwnProperty("interestForElement")) {
+    // CDN link only used for example, prefer bundling.
+    await import("https://unpkg.com/interestfor@latest");
+  }
+</script>
+```
+
+### CSS Polyfill Caveats
+
+When using the polyfill, the CSS API changes slightly to account for the lack of native pseudo-class and property support:
+
+- **Pseudo-classes:** The polyfill cannot define real `:interest-source` and `:interest-target` pseudo-classes, so it applies `.interest-source` and `.interest-target` classes instead. **MANDATORY:** Combine them with `:is()` to support both native and polyfilled states.
+
+```css
+/* Styles to apply when the effect is being previewed */
+:is(:interest-source, .interest-source) { /* ... */ }
+:is(:interest-target, .interest-target) { /* ... */ }
+```
+
+- **CSS Properties:** For `interest-delay`, `interest-delay-start`, and `interest-delay-end`, the polyfill requires using CSS variables as it cannot read the custom properties directly in all browsers.
+
+```css
+/* Adjust the start and end delay for interest invokers */
+[interestfor] {
+  --interest-delay-start: 0.2s;
+  interest-delay-start: var(--interest-delay-start);
+  --interest-delay-end: 0.1s;
+  interest-delay-end: var(--interest-delay-end);
+}
+```
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+Browser support for Cross-document view transitions: Limited availability.
+Supported by: Chrome 126 (Jun 2024), Edge 126 (Jun 2024), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/menu.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/menu.md
new file mode 100644
index 00000000..94809f58
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/menu.md
@@ -0,0 +1,410 @@
+<!-- Baseline best practices to be referenced by any guide that involves a popup menu (dropdown menus, context menus, overflow menus, etc)
+
+Include:
+- fixed-size icon slot (no subgrid)
+- proper keyboard nav
+- safe triangles for submenus
+- converting to drawer on small screens?
+-->
+
+# Build a dropdown menu
+
+This guide covers any popup menu: dropdown, context, overflow, and the menu bars that open them. The worked example is an application command menu, where items change the interface (create, save, preferences).
+
+### Commands, links, and what makes a menu
+
+Two independent choices. Everything else here applies to both.
+
+* **Element, per item.** A command is a `<button type="button">`; a destination is an `<a href>` that still opens in a new tab, copies as a URL, and works without script. A dropdown may mix them freely: two links and six commands, or one command and six links, changes nothing below.
+* **Interaction model, per dropdown.** Arrow keys, `Home`/`End`, and `Esc` make it a menu: add the focusgroup, let it infer `menuitem` on every item whether button or link, and make it look like one (a continuous bar or a trigger with a dropdown indicator; see "Menubar or separate menu buttons" below). A short list of links users `Tab` through is navigation: no focusgroup, no `role="menu"`, `role="menuitem"`, or `aria-haspopup="menu"`; keep the popover, `Esc`, and focus restoration, and see the navbar guide.
+
+Content never decides the roles. A "Products" dropdown of links can be a menu; an "Account" dropdown of commands cannot be navigation.
+
+Use the menu pattern only for a composite widget with one tab stop and arrow-key navigation. Use a `<div focusgroup="menu nomemory">`, not the HTML `<menu>` element. Do not add `role="menu"` or `role="menuitem"` in the shared markup: native focusgroup infers those roles, and explicit roles block that inference. Add them only in the unsupported-browser fallback below. `nomemory` makes reopening start at the first item. Focusgroup moves focus; script handles preview, activation, and focus restoration.
+
+## Open and position the menu
+
+Make each trigger a command invoker with `commandfor` and `command="toggle-popover"`. The browser opens and closes the popover on click, Enter, and Space, and keeps the trigger inside its popover's light-dismiss group, so clicking an open trigger closes it. Do not use `popovertarget` or `popovertargetaction`; this pattern uses `commandfor` instead.
+
+Place each popover immediately after its trigger. Browsers add an implicit `aria-details` relationship only when the popover is not the next sibling, so this placement avoids it without extra attributes.
+
+```html
+<!-- Command invoker: the browser toggles the popover on click, Enter, and Space -->
+<button id="file-trigger" class="trigger" type="button" aria-haspopup="menu" aria-expanded="false"
+  commandfor="file-menu" command="toggle-popover">
+  File
+</button>
+<!-- Immediately after its trigger, so browsers add no implicit aria-details -->
+<div id="file-menu" popover="auto">
+  <!-- Nested, not on the popover: Chromium otherwise drops focusgroup keyboard behavior -->
+  <div focusgroup="menu nomemory" aria-labelledby="file-trigger">
+    <button type="button">New file</button>
+    <button type="button">Save</button>
+    <button id="export-trigger" type="button" aria-haspopup="menu" aria-expanded="false"
+      commandfor="export-menu" command="toggle-popover">
+      Export <span aria-hidden="true">›</span>
+    </button>
+    <!-- Submenu: popover="auto" directly after its trigger, inside the parent focusgroup -->
+    <div id="export-menu" popover="auto">
+      <div focusgroup="menu nomemory" aria-labelledby="export-trigger">
+        <button type="button">PDF</button>
+        <button type="button">Plain Text</button>
+      </div>
+    </div>
+  </div>
+</div>
+```
+
+Name each menu with `aria-labelledby` pointing at its trigger. Keep decorative submenu indicators in CSS, or add `aria-hidden="true"`. Give triggers with `aria-expanded="true"` a visible active style so users can tell which menu is open or previewed.
+
+### Menubar or separate menu buttons
+
+Pick one form for the top-level triggers. Role, keyboard model, and styling must match: visually separate buttons signal one `Tab` stop each.
+
+* **Menubar.** `role="menubar"` on the container (never on a popover), styled as one continuous bar with no gaps between triggers. One `Tab` stop; `ArrowLeft`/`ArrowRight` move between triggers; hover switches open menus. Use for an application command bar.
+* **Separate menu buttons.** Each trigger is its own `Tab` stop and looks like a standalone button. No `role="menubar"`, no arrow keys between triggers, no preview on focus, no hover switching. Wrap in `<nav>` if they navigate, otherwise no role. Use for toolbars and page headers.
+
+The rest of this guide describes the menubar form. For separate buttons, keep everything inside each menu and drop the menubar-level behavior.
+
+### Position the menu with CSS Anchor Positioning
+
+Use CSS anchor positioning, not JavaScript coordinates. Both `command="toggle-popover"` and `showPopover({ source: trigger })` set an implicit anchor, so do not add per-menu `anchor-name` or `position-anchor` rules. Menu behavior must not depend on anchor positioning.
+
+```css
+/* Top-level menus sit below their trigger. The implicit anchor comes from the invoker or source. */
+[popover] {
+  position-area: block-end span-inline-end;
+  inset: auto;
+}
+
+/* A popover nested in another popover is a submenu: beside its parent item, flipping when it would overflow. */
+[popover] [popover] {
+  position-area: inline-end span-block-end;
+  position-try-fallbacks: flip-inline, flip-block, --below;
+}
+
+/* Last resort for narrow viewports: directly below the trigger, indented, so the submenu never
+   covers its trigger. */
+@position-try --below {
+  position-area: block-end span-inline-end;
+  margin-inline-start: 1rem;
+  /* Fit the area: the submenu's minimum width must not stop this fallback from fitting. */
+  min-inline-size: 0;
+  max-inline-size: calc(100% - 1rem);
+}
+```
+
+Keep `--below` last so it applies only when neither side fits. It opens directly under the trigger, so on a narrow screen it covers the sibling items beneath the trigger; that is the accepted trade-off for staying next to the trigger. Also let the submenu shrink to the area (`min-inline-size: 0`, `max-inline-size` minus the indent). A fallback that does not fit is skipped, and if none fit the browser keeps the base placement, so a submenu that is a few pixels too wide silently covers its trigger.
+
+For how the flip fallbacks work on a plain popover, see `viewport-aware-dropdowns` (via `npx -y modern-web-guidance@latest retrieve "viewport-aware-dropdowns"`). That guide positions a button group, not a menu; for menus, the submenu placement and `--below` fallback above take precedence.
+
+### Animate open and close
+
+Optional. Under 150 ms, `opacity` and a small `translate` only, same for submenus, inside `@media (prefers-reduced-motion: no-preference)`. Focus moves on `toggle`, so the transition never delays keyboard users.
+
+```css
+@media (prefers-reduced-motion: no-preference) {
+  /* Closing: this rule is in effect once :popover-open is removed. */
+  [popover] {
+    opacity: 0;
+    translate: 0 -.25rem;
+    transition: opacity .15s, translate .15s, display .15s allow-discrete, overlay .15s allow-discrete;
+  }
+  /* Opening: faster. */
+  [popover]:popover-open {
+    opacity: 1;
+    translate: 0 0;
+    transition-duration: .1s;
+    @starting-style { opacity: 0; translate: 0 -.25rem; }
+  }
+  /* Switching between open menubar menus is instant, as in native menubars. */
+  [role="menubar"]:has(> [popover]:popover-open) > [popover] {
+    transition: none;
+  }
+}
+```
+
+`@starting-style` is not a repeat of `[popover]`: a closed popover is `display: none`, and transitions do not run from an unrendered state, so it supplies the before-values for the open. Without it the open snaps and only the close animates. `display` and `overlay` with `allow-discrete` keep the popover rendered and in the top layer until the close transition ends.
+
+## Keyboard and focus
+
+Do not add a second roving-tabindex system inside a focusgroup. Script covers only what the invokers and focusgroup do not:
+
+* **One tab stop for the menubar.** `Tab` enters at the first top-level trigger. `ArrowLeft` and `ArrowRight` move between top-level triggers and wrap at either end. `Home` and `End` on a trigger enter its menu at the first or last item.
+  * **Note: which trigger `Tab` returns to.** The APG allows either the first trigger or the last one used. The guide specifies the first, but the demo moves the tab stop with `ArrowLeft` and `ArrowRight`, so after keyboard navigation `Shift`+`Tab` returns to the last trigger reached. Pointer use does not move it, so the same sequence can land on a different trigger. Either behavior is acceptable; pick one and keep it consistent.
+* **Preview.** Focusing a top-level trigger shows its menu and sets `aria-expanded="true"`. Focus stays on the trigger, and no item is focused. Blurring the trigger closes a preview-only menu.
+* **Enter and Space on a preview.** They close the preview and keep focus on the trigger. The native `toggle-popover` action handles this, so the script must not intercept these keys.
+* **ArrowDown on a preview.** Converts it to an open menu and focuses the first item.
+* **Pointer click on an open or previewed trigger.** Closes it natively; it does not enter the menu.
+  * **Known difference on submenu triggers.** A pointer click on a submenu trigger also toggles natively, so it can close a submenu that hover already previewed, or open one that has not appeared yet. Native menus only open it and never close it. This is harmless, so the guide accepts it.
+* **Pointer click on a closed trigger.** Opens it natively. Focus stays on the trigger; no item is focused. Only keyboard opens enter the menu.
+* **Pointer over an item.** Focuses it without a ring, so hover and focus are one item.
+* **Pointer over another top-level trigger while a menu is open.** Closes it and previews the hovered one, focusing its trigger without a ring. Nothing open: hover does nothing.
+* **Pointer over a submenu trigger.** Previews its submenu after a short delay (pointer focus runs the same preview-on-focus). A sibling item closes it.
+* **Within a menu.** `ArrowUp` and `ArrowDown` move between enabled items. `Home` and `End` move to the first and last enabled item, which the script handles.
+* **ArrowLeft or ArrowRight in an open top-level menu.** Closes it and previews the adjacent menu with focus on its trigger, wrapping at either end. `ArrowDown` then enters it. Left and Right never land inside a menu.
+* **ArrowRight on a submenu trigger.** Opens the submenu and focuses its first item.
+* **ArrowRight on a submenu item without a child submenu.** Closes the hierarchy and previews the next top-level menu while focus stays on its trigger. `ArrowDown` then enters it.
+* **ArrowLeft or Escape in a submenu.** Closes only that submenu and restores focus to its trigger. The parent menu stays open.
+* **Enter or Space on a command.** Activates it and closes all open menus.
+* **Tab.** Leaves the menu system. Do not trap focus or step through every command. Closing must not leave focus inside hidden content.
+
+The `command` event fires before `toggle-popover` opens the menu, so focus cannot move into the menu there. Move focus in the `toggle` event instead. HTML restores focus only for the first `popover="auto"` in a stack, so nested levels must restore focus to their trigger explicitly.
+
+## Implementing the interaction
+
+Implement the behaviors above for your own markup. Arrow, `Home`/`End`, wrap-around and `Tab`-to-exit handling is ordinary `keydown` code. A few parts are easy to get wrong, grouped below by input type.
+
+### Keyboard and focus handling
+
+1. **One open path.** Opening by keyboard calls `trigger.click()`, so the invoker's `toggle-popover` is the only way a menu opens. Mark the menu so the `toggle` handler enters it, keyboard opens only. On a pointer open, `toggle` focuses the trigger without a ring instead, because `pointerdown` prevented focus and arrow keys must still work.
+2. **Preview on focus.** Focusing a trigger calls `showPopover({ source: trigger })` so the menu anchors to it. Ignore focus returning from inside the trigger's own menu, or from another window (flag on window `blur`, cleared a tick after window `focus`, or app-switching reopens the last menu). Hide a previewed menu on `blur` unless focus moved into it.
+3. **Move focus in `toggle`, not `command`.** `command` fires before the menu opens.
+4. **Restore focus to the trigger yourself.** Focus the trigger before `hidePopover()`. After a pointer activation, restore focus without a ring (`focus({ focusVisible: false })`), or the trigger shows the keyboard focus outline after a mouse click; keyboard activations keep the ring. A click with `event.detail === 0` came from the keyboard.
+5. **Close one level at a time.** Call `stopPropagation()` on `Escape` and `ArrowLeft` in a submenu, or the parent's listener closes it too.
+
+### Pointer handling
+
+1. **Pointer click toggles.** Call `preventDefault()` on `pointerdown` so the click doesn't move focus and start a preview mid-click. Remember which trigger was pressed. Clicking a closed or previewed trigger opens or closes it natively and never enters the menu; only keyboard opens enter it. Do not intercept the click.
+2. **Hover follows focus.** Style `:hover` and `:focus-visible` separately. On `pointermove` over an item, call `focus({ focusVisible: false })`; browsers that ignore the option paint no ring for pointer focus anyway.
+3. **Hover switches open menus.** On `pointerenter` of a top-level trigger while another top-level menu is open: hide it, focus the hovered trigger without a ring, and preview on focus (see above) previews it. Nothing open: do nothing.
+4. **Safe triangle.** A fixed CSS bridge is too narrow: it only works when the pointer starts near the parent's edge. Let CSS draw the bridge and use script only to report the pointer:
+   * Run this only when `matchMedia('(hover: hover)').matches`; it is irrelevant to touch and keyboard.
+   * Start when the pointer leaves a submenu trigger whose submenu is open. Skip a `--below` submenu, which has no side edge.
+   * Set `--bridge-x` and `--bridge-y` (the pointer, in px relative to the submenu), `--bridge-edge` (the submenu's near-edge x: `0` when the pointer is to its left, its width when it flipped) and `--bridge-height` on the submenu, and `data-bridge` to switch the bridge on.
+   * Stop after about 300 ms, when the pointer reaches an item in the submenu, or when the submenu closes. Remove the listener and the attribute. Nothing runs after that.
+   * CSS gives the submenu a `::before` clipped to a triangle from the pointer to the near-edge corners. It sits over the sibling items on the pointer's path, so they never receive the hover that would close the submenu. `clip-path` also limits hit testing, so the rest of the parent menu stays interactive.
+   * The submenu needs `overflow: visible` (a popover clips by default), and the pseudo-element extends past it, so offset the shape's points by that extent.
+   * Follow-up: a curved path (`shape()` curve commands) follows real pointer arcs better than a straight triangle.
+
+```css
+[popover] [popover] {
+  overflow: visible;
+
+  &[data-bridge]::before {
+    content: "";
+    position: absolute;
+    inset: -100vh -100vw; /* Room for the triangle, which can extend far outside the submenu. */
+    clip-path: shape(
+      from calc(100vw + var(--bridge-x)) calc(100vh + var(--bridge-y)),
+      line to calc(100vw + var(--bridge-edge)) 100vh,
+      line to calc(100vw + var(--bridge-edge)) calc(100vh + var(--bridge-height)),
+      close
+    );
+  }
+}
+```
+
+```js
+const canHover = matchMedia('(hover: hover)');
+
+// Call on pointerleave of a submenu trigger, with that trigger's submenu.
+function startBridge(submenu, event) {
+  if (!canHover.matches || !submenu.matches(':popover-open')) return;
+  const rect = submenu.getBoundingClientRect();
+  if (event.clientX >= rect.left && event.clientX <= rect.right) return; // --below: no side edge.
+  const style = submenu.style;
+  style.setProperty('--bridge-edge', `${event.clientX < rect.left ? 0 : rect.width}px`);
+  style.setProperty('--bridge-height', `${rect.height}px`);
+  const update = ({ clientX, clientY, target }) => {
+    if (target !== submenu && submenu.contains(target)) return stop(); // Reached an item.
+    style.setProperty('--bridge-x', `${clientX - rect.left}px`);
+    style.setProperty('--bridge-y', `${clientY - rect.top}px`);
+  };
+  const timer = setTimeout(() => stop(), 300);
+  const stop = () => {
+    clearTimeout(timer);
+    document.removeEventListener('pointermove', update);
+    submenu.removeEventListener('toggle', stop);
+    submenu.removeAttribute('data-bridge');
+  };
+  update(event);
+  submenu.dataset.bridge = '';
+  document.addEventListener('pointermove', update);
+  submenu.addEventListener('toggle', stop, { once: true });
+}
+```
+
+Hover follows focus (item 2) stays a plain `pointermove` handler: it needs no triangle logic.
+
+Also:
+
+* **Outside focus.** Close every open menu when focus lands outside the menu system (a `document` `focusin` listener).
+* **Command activation.** Announce it, then hide the root menu and restore focus to its trigger, without a ring if the activation came from a pointer. For checkable items (`menuitemcheckbox`, `menuitemradio`), wait about 300 ms before closing so the changed check mark is visible. Style a closed trigger as active only on `:focus-visible`; otherwise the restored (ringless) focus leaves it highlighted after a pointer selection.
+* **`aria-expanded`.** Set it only in the `toggle` listener. It covers preview and open states, and the trigger's `aria-expanded` stays `"true"` while its menu is previewed or open.
+* **Helpers.** The fallbacks below assume helpers you define for your markup: `triggers` (all `[commandfor]` buttons), `menuFor(trigger)`, `isOpen(menu)`, `closeAndRestore(menu, { fromPointer })` (focus the trigger, without a ring when `fromPointer`, then `menu.hidePopover()`), `enterOnOpen` (a `WeakSet` of menus to enter once open) and `pointerTrigger` (the trigger last pressed by a pointer).
+
+### Submenus
+
+* Use `popover="auto"` for submenus, placed after the submenu trigger inside the parent's `focusgroup`. Never `popover="manual"`.
+* Nesting lets the browser keep the parent open, close sibling submenus, close child submenus when the root menu closes, and handle outside-click light dismiss.
+* The submenu trigger keeps `aria-haspopup="menu"` and `aria-expanded`; the `toggle` listener keeps `aria-expanded` in sync.
+* The keyboard script handles nested `Escape` and `ArrowLeft` as described above.
+* A submenu trigger never also runs a command: one control cannot both activate and open, and `Enter` cannot mean both. Put the default action as the first submenu item, or add a separate command item beside the trigger. If a combined control is forced, document it as an accessibility tradeoff.
+
+### Separators and checkable items
+
+* Separate item groups with `<hr>` inside the focusgroup: a native `separator`, not focusable, skipped by focusgroup and the fallback. Never a styled `<div>`.
+* A boolean option is a `<button type="button">` with `aria-checked` and an explicit `role="menuitemcheckbox"`. Focusgroup does not infer these roles, so this is the one place shared markup sets an item role.
+* One of a set is a `<button type="button">` with `role="menuitemradio"` and `aria-checked`, inside a `role="group"` with an `aria-label`, in the same focusgroup.
+* Script toggles `aria-checked`.
+* `Enter` on a checkbox toggles and closes the menu; `Space` toggles and stays open (APG). Radios close on either key.
+* Render the check mark from `[aria-checked="true"]::before`, not a separate icon element (see the CSS below).
+
+### Not covered here
+
+* **Activation feedback.** Native menus flash the chosen item before closing. If wanted, show a ~100 ms visual confirm before `hidePopover()`; do not delay focus restoration or the announcement.
+* **Typeahead.** Focusgroup has none. If needed, on printable `keydown` match the current level's enabled item labels and focus the next match after the current item, wrapping. Do not intercept `Space`.
+
+## Verify before finishing
+
+An instruction cannot guarantee behavior, so test the result. Open the page and check each of these with the real keyboard and mouse; fix and re-test any that fail:
+
+* **Keyboard.** `Tab` lands on the first trigger once; `ArrowDown` enters; `Escape` closes one level and returns focus to its trigger; `Tab` closes every menu.
+* **Pointer open.** Clicking a trigger opens its menu with focus on the trigger and no ring; clicking again closes it.
+* **Pointer command.** Clicking a command closes every menu and shows no focus ring on the trigger.
+* **Submenu.** Moving diagonally from the middle of a submenu trigger to a submenu item keeps it open; moving to an unrelated sibling closes it.
+* **Narrow screen.** At 375 px no submenu covers its own trigger.
+* **Check marks.** Checked items show a check mark.
+* **No leftovers.** No console errors, and no `popovertarget`, `popovertargetaction` or `aria-details` on triggers.
+
+## Align menu item content
+
+When a row has an icon, label, and shortcut or submenu indicator, reserve a fixed-size leading slot for the icon or check mark and push the trailing content to the inline end. Icons are a known size, so a fixed slot keeps labels aligned whether or not an item has an icon. Do not use `subgrid` for rows: any extra inline child (a badge, for example) becomes its own grid item and breaks the layout. Hide shortcut text from assistive technology when it only repeats a key that already operates the item.
+
+```css
+[focusgroup~="menu"] {
+  --menu-icon-size: 1.25rem;
+}
+
+/* Target items only. A closed submenu popover inside the focusgroup must keep display: none. */
+[focusgroup~="menu"] > button,
+[focusgroup~="menu"] > [role="group"] > button {
+  display: flex;
+  align-items: center;
+  gap: .5rem;
+}
+
+/* The leading slot holds the icon or check mark. */
+[focusgroup~="menu"] button::before {
+  content: "";
+  flex: none;
+  inline-size: var(--menu-icon-size);
+}
+
+/* Check mark for checked items. This selector must be at least as specific as the base
+   ::before rule above, or the empty content wins and the check mark never shows. */
+[focusgroup~="menu"] button[aria-checked="true"]::before {
+  content: "✓";
+}
+
+/* Shortcut or submenu indicator at the inline end. */
+[focusgroup~="menu"] .hint {
+  margin-inline-start: auto;
+}
+```
+
+Put a trailing indicator or shortcut in a `<span class="hint" aria-hidden="true">` inside the button; the submenu trigger already announces its popup.
+
+## Progressive enhancement and fallbacks
+
+### Fallbacks & browser support for focusgroup
+
+focusgroup is not natively supported by any major browser yet.
+
+Keep `focusgroup="menu nomemory"` in the markup. If `'focusGroup' in HTMLElement.prototype` is false, install Up, Down, Home, and End, set `role="menu"` on each menu container, and `role="menuitem"` on buttons with no role; leave checkable items, `<hr>`, and `role="group"` alone. Never install it when native focusgroup is present. Left, Right, preview, open, and close are author script either way.
+
+```js
+if (!('focusGroup' in HTMLElement.prototype)) {
+  document.querySelectorAll('[focusgroup~="menu"]').forEach(group => {
+    group.setAttribute('role', 'menu');
+    group.querySelectorAll('button:not([role])').forEach(item => {
+      item.setAttribute('role', 'menuitem');
+    });
+    group.addEventListener('keydown', event => {
+      if (!['ArrowDown', 'ArrowUp', 'Home', 'End'].includes(event.key)) return;
+      // Own items only: a nested submenu has its own focusgroup, a role="group" wrapper does not.
+      const items = [...group.querySelectorAll('button')]
+        .filter(item => item.closest('[focusgroup]') === group)
+        .filter(item => !item.disabled && item.getAttribute('aria-disabled') !== 'true');
+      const current = items.indexOf(document.activeElement);
+      if (current < 0) return;
+      const next = event.key === 'Home' ? 0 : event.key === 'End' ? items.length - 1 :
+        (current + (event.key === 'ArrowUp' ? -1 : 1) + items.length) % items.length;
+      event.preventDefault();
+      event.stopImmediatePropagation();
+      items[next].focus({ preventScroll: true });
+    }, true);
+  });
+}
+```
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+### Fallbacks & browser support for Anchor positioning
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+Without CSS Anchor Positioning, a popover falls back to the UA's centered viewport placement. Never ship that for a menu: it detaches the menu from its trigger, and a centered submenu covers its parent. Gate the anchored rules behind `@supports (position-area: block-end)` and position the menu from script when it fails:
+
+* Place the menu below its trigger (top level) or beside it (submenu), flipping to the other side and clamping to the viewport when it would overflow.
+* Run it in the `toggle` handler when the menu opens, and apply the result as `left` and `top` on the menu. Use `position: fixed` with `inset: auto` and `margin: 0` so the coordinates are viewport-relative.
+* Keep these overrides inside `@supports not (position-area: block-end)`, so browsers with anchor positioning are unaffected.
+
+Baseline status for the api.HTMLElement.showPopover.options_source_parameter.implicit_anchor_reference capability: Newly available. It's been Baseline since 2026-01-13.
+Supported by: Chrome 137 (May 2025), Edge 137 (May 2025), Firefox 147 (Jan 2026), and Safari 26 (Sep 2025).
+
+If targeting earlier implementations where `showPopover({ source })` does not establish an implicit anchor (no `source` on `ToggleEvent.prototype`), give each trigger a unique `anchor-name` and each menu a matching `position-anchor` from script, instead of writing per-menu CSS rules.
+
+For browsers without anchor positioning at all, see `viewport-aware-dropdowns` (via `npx -y modern-web-guidance@latest retrieve "viewport-aware-dropdowns"`) for the polyfill route.
+
+### Fallbacks & browser support for Invoker commands
+
+Baseline status for Invoker commands: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 144 (Oct 2025), and Safari 26.2 (Dec 2025).
+
+Without invokers, `command="toggle-popover"` does nothing, so script must toggle the menu.
+
+* Feature-detect the interface, not an instance: `'commandForElement' in HTMLButtonElement.prototype`.
+* On each trigger `click`, call `preventDefault()` so a browser with invokers cannot toggle twice.
+* If the menu is open, close it with `closeAndRestore(menu)`. Otherwise call `menu.showPopover({ source: trigger })`.
+* Mark the menu in `enterOnOpen` unless the click came from the pressed trigger (`pointerTrigger`), so only keyboard opens enter the menu.
+* `Enter` and `Space` still work because they generate a click on buttons.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/navigation-drawer.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/navigation-drawer.md
new file mode 100644
index 00000000..6b17dc03
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/navigation-drawer.md
@@ -0,0 +1,365 @@
+# Navigation Drawer
+
+## Overview
+
+A navigation drawer is a panel that slides in from the edge of the viewport over the page content, dimming everything behind it. It is opened from a trigger button and dismissed by swiping the panel off-screen, tapping the dimmed backdrop, or pressing Escape.
+
+This guide implements the drawer as:
+
+- A `popover="manual"` element promoted to the top layer so the panel and its `::backdrop` overlay every other element on the page, regardless of stacking context.
+- A horizontally scrolling container with two CSS scroll-snap stops — one for "open", one for "closed" — so the swipe gesture is handled natively by the browser. This delivers momentum, velocity, and interruption tracking for free, with no JavaScript pointer-event code.
+- A scroll-driven animation that ties the backdrop's opacity to the scroll position, so the dim fades in and out smoothly as the user drags the panel.
+- An `IntersectionObserver` on the panel that detects when it has fully entered or fully left the viewport, and uses those moments to update focus, `aria-expanded`, and `inert`.
+
+This approach is preferred over JavaScript-driven `transform` animations because the scroll mechanism gives the user direct control of the panel's position (their finger drives it, not a tween) and it much more closely matches the interaction patterns that users are accustomed to in native mobile apps.
+
+## Implementation
+
+### 1. Markup
+
+The drawer is a single popover containing a horizontal scroller, which contains the visible "sheet". The trigger button lives in the page content.
+
+```html
+<!-- popover="manual" is REQUIRED. Do not use popover="auto" or "hint". -->
+<div class="Drawer" id="drawer" popover="manual">
+  <div class="Drawer-scroller">
+    <nav class="Drawer-sheet" tabindex="-1">
+      <!-- tabindex="-1" makes the sheet programmatically focusable so we
+           can move focus into it when the drawer opens, without adding it
+           to the natural tab order. -->
+      <ul>
+        <li><a href="/page-1">Page 1</a></li>
+        <li><a href="/page-2">Page 2</a></li>
+        <!-- ... -->
+      </ul>
+    </nav>
+  </div>
+</div>
+
+<main>
+  <header>
+    <!-- aria-controls links the trigger to the drawer; aria-expanded
+         reflects the current state for assistive tech. -->
+    <button id="drawer-open"
+            aria-label="Menu"
+            aria-expanded="false"
+            aria-controls="drawer">
+      <!-- MANDATORY: Inline decorative SVGs MUST define aria-hidden="true" -->
+      <svg aria-hidden="true" viewBox="0 0 24 24">...</svg>
+    </button>
+  </header>
+  <!-- Page content. -->
+</main>
+```
+
+### 2. Styles
+
+#### Reset the popover and fill the viewport
+
+The popover must cover the whole viewport so its `::backdrop` dims the entire page and the swipe surface extends edge-to-edge. The default user-agent popover styles (centered, auto-sized, bordered) get in the way and must be reset.
+
+```css
+.Drawer {
+  /* min() caps the sheet width on large screens but on a phone leaves
+     a 20% peek of page content visible, which is the affordance that
+     tells the user they can tap outside to dismiss. */
+  --drawer-width: min(20em, 80dvw);
+
+  /* Custom property driven by the scroll-driven animation below.
+     0 = drawer fully closed (transparent backdrop).
+     1 = drawer fully open (visible backdrop). */
+  --drawer-backdrop: 0;
+
+  /* Reset UA popover style that would constrain the element. */
+  width: auto;
+  height: auto;
+  background: transparent;
+  border: 0;
+  overflow: visible;
+}
+
+/* Style the popover's ::backdrop to achieve the overlay effect and
+   provide visual affordances indicating that the rest of the page is inert */
+.Drawer::backdrop {
+  background: #000;
+  /* Use calc() to limit the opacity range so the content beneath is visible */
+  opacity: calc(var(--drawer-backdrop) / 2);
+}
+```
+
+#### Build the swipe surface with scroll snap
+
+The scroller is a horizontal grid wider than the viewport: column 1 holds the sheet (width `--drawer-width`), column 2 is an empty pseudo-element spacer the width of the viewport. Snapping between the two columns is what opens and closes the drawer.
+
+```css
+.Drawer-scroller {
+  position: relative;
+  display: grid;
+  /* Sheet on the left, full-viewport spacer on the right. The user
+     scrolls between the two snap stops to open and close. */
+  grid-template-columns: var(--drawer-width) 100%;
+
+  overflow-x: scroll;
+  /* Stop the swipe from chaining into the page's vertical scroll
+     when the user reaches either snap edge. */
+  overscroll-behavior: none;
+  scrollbar-width: none;
+  /* `mandatory` guarantees the drawer always settles fully open or
+     fully closed — never half-open after a partial swipe. */
+  scroll-snap-type: x mandatory;
+}
+
+/* Enable smooth scrolling natively, but only if the user has not
+   requested reduced motion. */
+@media (prefers-reduced-motion: no-preference) {
+  .Drawer-scroller {
+    scroll-behavior: smooth;
+  }
+}
+
+/* The empty spacer that creates the "closed" snap stop. */
+.Drawer-scroller::after {
+  content: '';
+  scroll-snap-align: end;
+  /* Open the popover already scrolled to this stop (drawer off-screen),
+     so the JS only needs to scroll to the open position to
+     animate it in. */
+  scroll-initial-target: nearest;
+}
+
+.Drawer-sheet {
+  display: grid;
+  grid-template-rows: auto 1fr;
+  /* Use `svh` (small viewport height) — not `vh` or `dvh` — so the
+     sheet height does not jump when the iOS Safari address bar
+     resizes mid-swipe. */
+  height: 100svh;
+
+  background: #333;
+  color: #fff;
+  overflow-y: auto;
+  scroll-snap-align: start;
+  scrollbar-width: none;
+}
+```
+
+#### Tie the backdrop opacity to the scroll position
+
+A scroll-driven animation maps `--drawer-backdrop` from 1 (open) to 0 (closed) across the scroller's range, so the backdrop fades in and out perfectly synced with the drag.
+
+```css
+/* MANDATORY: Wrap this entire block in @supports. Browsers that don't
+   support animation-timeline still parse the @keyframes and would
+   apply the animation's `0%` value (--drawer-backdrop: 1) at all
+   times, leaving the backdrop permanently opaque. The @supports gate
+   ensures the animation is only registered where it actually works. */
+@supports (animation-timeline: scroll()) {
+  .Drawer {
+    /* timeline-scope lets .Drawer reference a scroll-timeline that
+       is defined on its descendant (the scroller). Without this, the
+       timeline name is not visible to the .Drawer element. */
+    timeline-scope: --drawer-fade;
+    animation: fade-drawer-backdrop linear both;
+    animation-timeline: --drawer-fade;
+  }
+
+  .Drawer-scroller {
+    /* The horizontal scroll position of this element drives the
+       timeline named `--drawer-fade`. */
+    scroll-timeline: --drawer-fade x;
+  }
+
+  /* @property is REQUIRED. Without registering --drawer-backdrop with
+     a `<number>` syntax, the browser treats it as a string and cannot
+     interpolate it — the backdrop would jump from 0 to 1 with no
+     fade. */
+  @property --drawer-backdrop {
+    syntax: '<number>';
+    inherits: true;
+    initial-value: 0;
+  }
+
+  @keyframes fade-drawer-backdrop {
+    /* Scroll position 0 = drawer fully open = backdrop visible. */
+    0% { --drawer-backdrop: 1 }
+    /* Scroll position 100% = drawer fully closed = backdrop hidden. */
+    100% { --drawer-backdrop: 0 }
+  }
+}
+```
+
+### 3. Open and close the drawer
+
+Opening is two steps: promote the popover to the top layer, then scroll the sheet into view. Closing is one step: scroll back to the spacer; an observer (step 4) hides the popover once the sheet is fully off-screen.
+
+```js
+const drawer = document.getElementById('drawer');
+const openBtn = document.getElementById('drawer-open');
+const scroller = drawer.querySelector('.Drawer-scroller');
+const sheet = drawer.querySelector('.Drawer-sheet');
+
+function openDrawer() {
+  // Show the popover first so the element is in the top layer before
+  // we trigger any scrolling. `scroll-initial-target` (set on the
+  // ::after spacer) places the initial scroll position at the closed
+  // stop, so the drawer enters the top layer already off-screen.
+  drawer.showPopover();
+
+  // Scroll the sheet into view. The `behavior: 'auto'` option defers
+  // to the CSS `scroll-behavior` property, which will be smooth unless
+  // the user prefers reduced motion. Snap takes over at the end and
+  // locks the drawer fully open.
+  scroller.scrollTo({left: 0, behavior: 'auto'});
+}
+
+function closeDrawer() {
+  // Scroll back to the spacer. Do NOT call hidePopover() here —
+  // doing so would remove the element from the top layer mid-animation
+  // and the close animation would not be visible. The
+  // IntersectionObserver in step 4 hides the popover once the sheet
+  // has actually left the viewport.
+  scroller.scrollTo({left: scroller.offsetWidth, behavior: 'auto'});
+}
+```
+
+### 4. Detect open and closed state
+
+Use an `IntersectionObserver` on the sheet — not the scroll position — as the source of truth for the drawer's state. The observer fires regardless of how the sheet moved (user swipe, programmatic scroll, snap settle), so all dismissal paths converge in the same callback.
+
+```js
+function onDrawerOpened() {
+  // Mark the rest of the page inert so keyboard and screen-reader
+  // users cannot tab into content hidden behind the drawer.
+  document.querySelector('main').inert = true;
+  openBtn.setAttribute('aria-expanded', 'true');
+  // Move focus into the drawer for keyboard users.
+  sheet.focus();
+}
+
+function onDrawerClosed() {
+  // Hide the popover only after the close animation completes,
+  // so the slide-out is visible to the user.
+  drawer.hidePopover();
+  document.querySelector('main').inert = false;
+  openBtn.setAttribute('aria-expanded', 'false');
+}
+
+// Treat "any pixel of the sheet visible inside the popover root" as
+// "open enough to count as not closed". This threshold is intentionally
+// tiny so the closed callback only fires once the sheet is truly gone.
+const visibleThreshold = 1 / window.innerWidth;
+
+const observer = new IntersectionObserver(
+  (entries) => {
+    // During programmatic scrolling the observer can deliver multiple
+    // entries in one batch. Only the most recent describes the
+    // current state; earlier entries are intermediate positions.
+    const entry = entries.at(-1);
+    if (entry.intersectionRatio < visibleThreshold) onDrawerClosed();
+    if (entry.intersectionRatio === 1) onDrawerOpened();
+  },
+  // root: drawer makes the popover element the intersection root,
+  // so the ratio reflects the sheet's visibility within the popover
+  // (i.e. how much of it has been swiped on-screen).
+  {root: drawer, threshold: [visibleThreshold, 1]},
+);
+observer.observe(sheet);
+```
+
+### 5. Wire up the trigger and dismissal handlers
+
+```js
+// Open trigger.
+openBtn.addEventListener('click', openDrawer);
+
+// Light-dismiss: a tap on the dimmed area (anywhere inside the
+// popover but outside the sheet) closes the drawer. We implement
+// this manually because popover="manual" disables the browser's
+// built-in light-dismiss (which would also fire mid-swipe — see step 1).
+drawer.addEventListener('click', (event) => {
+  if (!sheet.contains(event.target)) closeDrawer();
+});
+
+// Escape key. Listen on document because focus may be inside the
+// drawer when the user presses Escape.
+document.addEventListener('keydown', (event) => {
+  if (event.key === 'Escape') closeDrawer();
+});
+```
+
+### Fallback strategies
+
+Baseline status for Scroll snap: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 69 (Sep 2018), Edge 79 (Jan 2020), Firefox 68 (Jul 2019), and Safari 11 (Sep 2017).
+
+Baseline status for Intersection observer: Widely available. It's been Baseline since 2019-03-25.
+Supported by: Chrome 58 (Apr 2017), Edge 16 (Oct 2017), Firefox 55 (Aug 2017), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for inert: Widely available. It's been Baseline since 2023-04-11.
+Supported by: Chrome 102 (May 2022), Edge 102 (May 2022), Firefox 112 (Apr 2023), and Safari 15.5 (May 2022).
+
+The popover API, the scroll-driven animation that fades the backdrop, and `scroll-initial-target` are progressive enhancements with simple fallbacks that can be easily implemented if wide browser support is required.
+
+#### Backdrop fade fallback (no `animation-timeline` support):
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+Detect with `CSS.supports('animation-timeline: scroll()')` and write `--drawer-backdrop` from a `scroll` event listener if not supported. The CSS `@supports` block in step 2 ensures the keyframes never apply in unsupported browsers, so the JavaScript value is the only writer.
+
+```js
+if (!CSS.supports('animation-timeline: scroll()')) {
+  scroller.addEventListener('scroll', () => {
+    // Same mapping as the @keyframes: 0 scroll = 1 (open),
+    // sheet-width scroll = 0 (closed).
+    const ratio = 1 - scroller.scrollLeft / sheet.offsetWidth;
+    drawer.style.setProperty('--drawer-backdrop', ratio);
+  });
+}
+```
+
+#### Initial scroll position fallback (no `scroll-initial-target` support):
+
+Browser support for scroll-initial-target: Limited availability.
+Supported by: Chrome 133 (Feb 2025) and Edge 133 (Feb 2025).
+Unsupported in: Firefox and Safari.
+
+Detect with `CSS.supports('scroll-initial-target', 'nearest')` and inside `openDrawer()`, jump-scroll the scroller to the closed position immediately after `showPopover()`. Without this, the drawer would appear instantly in the open position with no slide-in animation.
+
+```js
+async function openDrawer() {
+  drawer.showPopover();
+
+  if (!CSS.supports('scroll-initial-target', 'nearest')) {
+    // Jump-scroll to the closed stop so the scroll below
+    // animates the drawer in from off-screen.
+    scroller.scrollTo({left: scroller.offsetWidth, behavior: 'instant'});
+    // Wait two animation frames for the jump-scroll to commit.
+    // A single rAF is not enough — the second `scrollTo` would
+    // cancel the first before the browser has a chance to apply it.
+    await new Promise((r) =>
+      requestAnimationFrame(() => requestAnimationFrame(r))
+    );
+  }
+
+  scroller.scrollTo({left: 0, behavior: 'auto'});
+}
+```
+
+#### `@property` fallback (no registered custom properties):
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+`@property` is only needed because the scroll-driven animation interpolates `--drawer-backdrop` between keyframes — without registration, the property would be treated as a string and would jump between 0 and 1 with no fade. If the scroll-driven animation fallback above is in place, that JavaScript writes a fresh numeric string to `--drawer-backdrop` on every scroll frame and never interpolates, so no separate `@property` fallback is needed since all browsers that support scroll-driven animations also support `@property`.
+
+
+#### Popover API fallback (no `popover` attribute support):
+
+Baseline status for the api.HTMLElement.showPopover capability: Newly available. It's been Baseline since 2024-04-16.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 125 (Apr 2024), and Safari 17 (Sep 2023).
+
+Because this component uses `popover="manual"` and implements dismissal entirely from JavaScript, it does not depend on the popover API's defining behaviors — light-dismiss, the `popovertarget` attribute, top-layer-managed Escape handling, or focus management. The only popover features it actually uses are top-layer promotion (via `showPopover()`) and the `::backdrop` pseudo-element.
+
+If wider browser support is needed, do not branch on feature detection — simply do not use popover at all. Drop the `popover="manual"` attribute, replace top-layer promotion with `position: fixed` and a high `z-index`, replace `::backdrop` with a sibling element styled identically (using the same `--drawer-backdrop` custom property), and toggle visibility from a class instead of `showPopover()`/`hidePopover()`. The rest of the component (scroll snap, the scroll-driven backdrop animation, the `IntersectionObserver`, and the dismissal handlers) is unchanged.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-app-tours.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-app-tours.md
new file mode 100644
index 00000000..74165230
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-app-tours.md
@@ -0,0 +1,137 @@
+# Creating Persistent App Tours
+
+Onboarding tours require overlays that persist while users interact with the highlighted features. Unlike auto popovers, manual popovers do not close when the user clicks elsewhere on the page. Combining `popover="manual"` with CSS Anchor Positioning allows you to create non-modal, tethered tour steps.
+
+### Recommended Implementation
+
+#### HTML
+```html
+<div id="feature-target">Highlight this feature</div>
+
+<!-- MANDATORY: Enforce overlay dialog semantics and accessible name bindings -->
+<div id="tour-step" popover="manual" role="dialog" aria-labelledby="tour-title">
+  <!-- Assume an <h1> precedes this element in the full document outline -->
+  <h2 id="tour-title">Step 1</h2>
+  <p>Learn how to use this feature.</p>
+  <button popovertarget="tour-step" popovertargetaction="hide">Got it</button>
+</div>
+```
+
+#### CSS
+```css
+#feature-target {
+  anchor-name: --feature-target;
+}
+
+#tour-step {
+  popover: manual;
+  position-anchor: --feature-target;
+  position-area: right center;
+  inset: auto;
+  margin: 1rem;
+  padding: 1rem;
+  border: 1px solid blue;
+  border-radius: 0.5rem;
+  background: aliceblue;
+}
+```
+
+#### JavaScript
+```javascript
+const tourStep = document.getElementById('tour-step');
+tourStep.showPopover();
+// MANDATORY: Programmatically route focus into the non-modal popover so keyboard/assistive technology users immediately perceive the new context
+tourStep.querySelector('button').focus();
+```
+
+### Implementation Guidelines
+
+* **MANDATORY:** Use `popover="manual"` to prevent the tour step from closing accidentally during user interaction.
+* **MANDATORY:** Mark the container with `role="dialog"` and link its heading via `aria-labelledby`.
+* **MANDATORY:** Shift programmatic focus inside the popover immediately after opening to prevent focus abandonment.
+* **DO** use CSS Anchor Positioning to tether the tour step to the specific feature being explained.
+* **DO** provide an explicit "Close" or "Next" button within the popover that uses `popovertargetaction="hide"`.
+
+### Fallback strategies
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+#### anchor-positioning
+
+Browser support for Anchor positioning: Limited availability.
+Supported by: Safari 27 (Sep 2026).
+Unsupported in: Chrome, Edge, and Firefox.
+
+To support browsers without anchor positioning, you can choose between using a polyfill or a pure CSS fallback.
+
+##### Option 1: Polyfill Fallback
+The `@oddbird/css-anchor-positioning` polyfill can be used to emulate anchor positioning. It does not support implicit anchors, so you MUST add explicit anchor names to the trigger. Additionally, `position-area` is not supported on popovers by the polyfill, so you MUST use `anchor()` on the desired insets instead of `position-area`.
+
+```html
+<script type="module">
+  if (!CSS.supports('anchor-name: --foo')) {
+    await import("https://unpkg.com/@oddbird/css-anchor-positioning");
+  }
+</script>
+```
+
+```css
+#tour-step {
+  /* If using the anchor positioning polyfill with a popover, DO use `anchor()` functions instead of `position-area`. */
+  left: anchor(right);
+  top: anchor(top);
+}
+```
+
+##### Option 2: Non-Polyfill CSS Fallback
+If you prefer not to use a polyfill, you can default the tooltip to a fixed position at the bottom of the viewport using `@supports not`.
+
+```css
+@supports not (anchor-name: --foo) {
+  #tour-step {
+    position: fixed;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    width: 100%;
+    margin: 0;
+    border-radius: 0;
+  }
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-toast-notifications.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-toast-notifications.md
new file mode 100644
index 00000000..b1885176
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/persistent-toast-notifications.md
@@ -0,0 +1,64 @@
+# Creating Toast Notifications
+
+Toast notifications are transient status messages. Unlike menus, they should not close when a user interacts with other parts of the page. The popover="manual" state is ideal because it lacks "light-dismiss" behavior and allows multiple notifications to coexist.
+
+### Implementation Guidelines
+
+* **MANDATORY:** Use popover="manual" so the notification stays visible until explicitly closed or timed out by a script.
+* **DO** use a container to manage the stacking of multiple toasts. Since popovers in the Top Layer ignore parent z-index, you must position them individually or within a common layout group.
+* **DO** use sibling-index() to add margin between toast notifications so that items lower in the stack are visible.
+* **DO** provide an explicit "Close" button within the toast using popovertargetaction="hide".
+* **DO** use JavaScript for auto-dismissal timers (e.g., calling hidePopover() after 3000ms).
+* **DO** utilize transition-behavior: allow-discrete to animate the entry and exit from the Top Layer.
+
+### Fallback Strategies
+
+### Fallbacks & browser support for Popover
+
+Baseline status for Popover: Newly available. It's been Baseline since 2025-01-27.
+Supported by: Chrome 116 (Aug 2023), Edge 116 (Aug 2023), Firefox 125 (Apr 2024), Safari 17 (Sep 2023), and Safari iOS 18.3 (Jan 2025).
+
+The Popover API is mostly **progressive enhancement**, but its defining behaviors — top-layer promotion, light-dismiss, and `popovertarget` invocation — have no CSS-only equivalent. Older browsers need a polyfill, or a manual fallback if you would rather not ship one.
+
+**Polyfill:** To support the `popover` attribute in older browsers, conditionally load [`@oddbird/popover-polyfill`](https://github.com/oddbird/popover-polyfill). **MANDATORY:** Feature detect by checking for the `popover` property on `HTMLElement.prototype`, and load the polyfill **only** when native support is missing — do NOT load it unconditionally.
+
+With a bundler or import map:
+
+```js
+// MANDATORY: Feature detect 'popover' on HTMLElement.prototype.
+if (!("popover" in HTMLElement.prototype)) {
+  import("@oddbird/popover-polyfill");
+}
+```
+
+Without a bundler, import from a CDN inside a `<script type="module">`:
+
+```html
+<script type="module">
+  if (!("popover" in HTMLElement.prototype)) {
+    import("https://unpkg.com/@oddbird/popover-polyfill@latest/dist/popover.min.js");
+  }
+</script>
+```
+
+**Styling caveat:** The polyfill cannot define the real `:popover-open` pseudo-class, so it applies a `.\:popover-open` class instead. **MANDATORY:** Combine the two with `:is()` or `:where()`, otherwise browsers that lack `:popover-open` discard the entire rule:
+
+```css
+[popover]:is(:popover-open, .\:popover-open) {
+  display: block;
+}
+```
+
+Alternatively, for a legacy fallback without a polyfill, use `position: fixed` and manually calculate coordinates via `getBoundingClientRect()` or rely on default positioning with `inset: auto` if that's acceptable for the use case.
+
+#### sibling-index()
+
+* **Guidance:** If sibling-index() is not supported, use the `+` operator to add margin manually. I.e. `popover + popover { margin-top: 1rem }`
+
+#### anchor-positioning
+
+* **Guidance:** Use the [CSS Anchor Positioning Polyfill](https://github.com/oddbird/css-anchor-positioning). For a non-polyfill fallback, default the tooltip to a fixed position at the bottom of the viewport using `@supports not (anchor-name: --foo)`.
+
+#### transition-behavior
+
+* **Guidance:** If transition-behavior is not supported, use JavaScript to add animation via classes as the toast element transitions in and out.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress-ring.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress-ring.md
new file mode 100644
index 00000000..c4d42d88
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress-ring.md
@@ -0,0 +1,181 @@
+# Progress ring
+
+A progress ring (or circular progress bar) provides visual feedback on the status of a task. Unlike a linear progress bar, its circular shape is ideal for dashboards, card components, or anywhere space is constrained.
+
+This guide implements a progress ring by:
+
+- Using the native `<progress>` element as the semantic foundation to ensure the component is accessible to screen readers and keyboard users out-of-the-box.
+- Styling the component with `conic-gradient()` and `mask-image`, allowing for a fully responsive and themeable ring without the complexity of SVG path manipulation.
+- Leveraging CSS Custom Properties and `@property` to enable smooth, GPU-accelerated transitions of the progress fill.
+
+This approach is preferred over SVG-only solutions because it uses the semantic `<progress>` element rather than ARIA, and more easily integrates with existing layout, design systems and typography.
+
+See the `spinner` (via `npx -y modern-web-guidance@latest retrieve "spinner"`) for handling indeterminate loading states.
+
+## Implementation
+
+### 1. Markup
+
+Use a wrapper to hold both the visual ring and the optional center content. The `<progress>` element remains the semantic source of truth. Use a utility class to visually hide the native progress bar while keeping it accessible.
+
+```html
+<div class="ring-wrapper">
+  <progress value="75" max="100" aria-label="Task progress" class="progress-ring"></progress>
+  <!-- Optional: Content to display in the center -->
+  <div class="ring-content">
+    75%
+  </div>
+</div>
+```
+
+### 2. Styles
+
+#### Hiding Native UI
+To style the `<progress>` element as a progress ring, first hide the default browser styling for progress bars.
+
+```css
+/* Hide native bars */
+progress.loading-spinner:indeterminate::-webkit-progress-bar {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::-webkit-progress-value {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::-moz-progress-bar {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::slider-fill {
+  display: none;
+  background: none;
+}
+```
+
+#### Container and Ring
+
+The wrapper provides the positioning context. The `<progress>` element handles the visual gradient.
+
+```css
+.progress-ring-wrapper {
+  position: relative;
+  display: grid;
+  place-items: center;
+}
+
+progress.progress-ring {
+  --size: 150px;
+  --thickness: 16px;
+  --track-color: #f1f5f9;
+  --fill-color: #3b82f6;
+  --value: attr(value type(<number>));
+  width: var(--size);
+  height: var(--size);
+
+  transition: --value 0.4s cubic-bezier(0.4, 0, 0.2, 1);
+  border-radius: 50%;
+
+  background: conic-gradient(
+    var(--fill-color) calc(var(--value) * 1%),
+    var(--track-color) 0
+  );
+
+  /* MANDATORY: Clip the background to the border-area. */
+  background-clip: border-area;
+  border: var(--thickness) solid transparent;
+  background-origin: border-box;
+}
+
+.progress-ring-content {
+  /* Positioned in the center of the wrapper */
+  position: absolute;
+}
+```
+
+You can also use a `radial-gradient` to make rounded end caps.
+
+#### Enable smooth transitions with `@property`
+
+To animate the progress ring smoothly when the value changes, register `--value` as a numeric custom property. 
+
+Users with motion sensitivities may find the transition between values disorienting. Respect the `prefers-reduced-motion` media query by having a 0 second (immediate) duration by default, and setting a longer time for users with no preference.
+
+
+```css
+@property --value {
+  syntax: '<number>';
+  inherits: true;
+  initial-value: 0;
+}
+
+progress.progress-ring {
+  transition: --value 0s ease-in-out;
+  @media (prefers-reduced-motion: no-preference) {
+    transition-duration: 0.4s;
+  }
+}
+
+```
+
+### 3. Progress Updates
+
+Update the `value` attribute on the `<progress>` element and the text content of `.progress-ring-content` (if displaying a percentage) whenever the value changes.
+
+### 4. Optional Success State
+
+You can use the CSS attribute selector to automatically update the ring's appearance (e.g., changing the color to green) when the task reaches completion.
+
+```css
+/* Change the fill color to green when the progress reaches 100% */
+progress.progress-ring[value="100"] {
+  --fill-color: #10b981;
+}
+```
+
+## Fallback strategies
+
+Do not add a fallback value inside the `<progress>` element. It is not used by assistive technology and ignored by all modern browsers.
+
+#### Animation fallback
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+If `@property` is not supported, the ring will jump to the new value instantly instead of transitioning smoothly. In most cases this is fine, and does not break any functionality.
+
+If the transition is absolutely necessary, you can check for `@property` support and use a `requestAnimationFrame()` loop to interpolate `--value` in older browsers.
+
+Browser support for background-clip: border-area: Limited availability.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+For browsers that don't yet support `background-clip: border-area`, fall back to a `mask-image` to hollow out the center of the `<progress>` element.
+
+```css
+@supports not (background-clip: border-area) {
+  mask-image: radial-gradient(
+    transparent calc(50% - var(--thickness)),
+    black calc(50% - var(--thickness) + 0.5px)
+  );
+  border: 0;
+}
+```
+
+Browser support for attr(): Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Firefox 155 (Sep 2026).
+Unsupported in: Safari.
+
+For browsers that don't support the `attr()` CSS function for any property, use a `MutationObserver` to automatically sync the `value` attribute to the `--value` custom property.
+
+```js
+if (!CSS.supports("width: attr(value type(<number>))")) {
+  const observer = new MutationObserver(() => {
+    progress.style.setProperty("--value", progress.getAttribute("value"));
+  });
+  observer.observe(progress, {
+    attributes: true,
+    attributeFilter: ["value"],
+  });
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress.md
new file mode 100644
index 00000000..b71747ba
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/progress.md
@@ -0,0 +1,181 @@
+# Build a Styled Progress Bar
+
+The `<progress>` element is the semantic way to represent the completion progress of a task, like downloading or uploading information or completing part of a multi-step process. Using the native element helps with accessibility, as screen readers have an implicit `role="progressbar"` and can announce values.
+
+This guide implements a fully styled horizontal progress bar with style customizations.
+
+## Progress bar or progress ring?
+
+- If space is constrained or a square aspect ratio is preferable, consider using a circular progress bar (progress ring): `progress-ring` (via `npx -y modern-web-guidance@latest retrieve "progress-ring"`)
+- Prefer spinners for most indeterminate progress scenarios (`spinner` (via `npx -y modern-web-guidance@latest retrieve "spinner"`)). Use indeterminate progress bars when the indeterminate state is temporary and will soon be replaced by a determinate progress bar (e.g. waiting for metadata around an upload before a progress % can be shown)
+
+## Markup
+
+1.  **Use a native `<progress>` element**: It provides built-in accessibility and platform-consistent behavior.
+2. Use `max` if a scale different from the default 0-1 scale is needed.
+3. For a specific progress value, set a `value` attribute. Omit `value` for an indeterminate state (e.g. before more concrete feedback starts).
+4. Use `<label for="...">`, `aria-labelledby`, or `aria-label` to associate the progress element with a label.
+
+## What type of customization is needed?
+
+For limited styling, these properties are sufficient:
+- `accent-color` to change the color of the progress bar
+- `width` / `inline-size` to change the width of the progress bar
+- `height`/`block-size` applies inconsistently — test first
+- `writing-mode: vertical-lr` for vertical bars.
+- Effects that apply after painting: `opacity`, `filter`, `clip-path`, masks, transforms, `box-shadow`, etc.
+
+If limited styling suffices, skip the next section.
+
+WARNING: Certain properties (e.g. `border-radius`, `background`, `border`) will silently disable the default progress bar styling. If you need styling beyond the properties above, you must implement fully custom styling as described in the next section. Do NOT apply more extensive styling "just in case it works".
+
+## Fully custom styling
+
+### 1. Basic setup
+
+- MANDATORY: Use `appearance: none` to enable custom styling.
+- Reset UA borders with `border: 0 solid`
+- To clip the active bar to the element’s border-radius, use `overflow: clip` OR apply the same `border-radius` to the bar. Do NOT use `border-radius: inherit` on the bar, which depends on the specific structure of elements in the shadow DOM.
+
+```css
+progress {
+  /* Reset default browser styles */
+  appearance: none;
+  border: 0 solid;
+  /* Clip bar to element’s border-radius  */
+  overflow: clip;
+}
+```
+
+### 2. Styling
+
+- Style the track on the `progress` element itself.
+- Use the appropriate browser-targeted pseudo-element to target the progress bar itself: `::-webkit-progress-value` for WebKit/Blink and `::-moz-progress-bar` for Firefox.
+- MANDATORY: Do NOT group `-webkit-` and `-moz-` pseudo-elements in the same rule. The rule will be deemed invalid and will be ignored. `:is()` and `:where()` do not help here, as they don't support pseudo-elements.
+- Each browser-targeted pseudo-element should appear exactly once. State-specific customizations (such as the indeterminate segment size and animation) should be routed through custom properties set on the `progress` element itself.
+- Optional: Transition `inline-size` on the fill so determinate value changes animate instead of jumping. Firefox sizes the fill in layout and ignores it, which is harmless.
+
+```css
+progress {
+  --progress-bar-radius: 1e5px;
+  border-radius: var(--progress-bar-radius);
+  /* Apply color for custom progress track (background) */
+  background: var(--progress-bar-track, var(--color-neutral-90));
+  /* Subtle depth on the empty part of the track */
+  box-shadow: inset 0 1px 2px rgb(0 0 0 / 0.1);
+}
+
+/* Let <progress> styling show through */
+progress::-webkit-progress-bar {
+  background: transparent;
+}
+
+/* Webkit, Chrome */
+progress::-webkit-progress-value {
+  background: var(--progress-bar-fill, var(--accent-color));
+  border-radius: var(--progress-bar-radius);
+  transition: inline-size 0.3s;
+}
+
+/* Firefox */
+progress::-moz-progress-bar {
+  background: var(--progress-bar-fill, var(--accent-color));
+  border-radius: var(--progress-bar-radius);
+  transition: inline-size 0.3s;
+}
+```
+
+### 3. Indeterminate state styling
+
+**Add a custom animation for the indeterminate state:** Turn the fill pseudo-element into a short segment and slide it along the track.
+- Style the fill itself; do NOT recreate it as a background on `progress`.
+- The indeterminate fill exists only through its animation: the keyframes set its length with a real `inline-size` (this beats Chromium's UA inline `inline-size`) and moves it with `translate`. Do NOT use `scale` for the length; it distorts any pattern painted on the fill.
+- `translate` percentages resolve against the fill's own width, so express positions in track units instead: make `progress` an inline-size container and use `cqi` in the keyframes. Include `margin-right: auto` in `from, to` so Chromium lays the fill out at the physical left in RTL too.
+- Use transforms, not margins, to move the fill.
+  - Transforms keep the animation in the compositor (unless `inline-size` is also being animated)
+  - Margins break in RTL, for two separate reasons:
+    - Firefox positions the indeterminate fill using only its physical left margin, so `margin-inline-start` has no effect in RTL and the fill never moves.
+    - In Chromium and WebKit, which lay the fill out as a normal block, once a margin pushes the fill past the end of the track the margins add up to more than the track. Standard CSS resolves that by ignoring `margin-left` in RTL, so the segment jumps to the edge instead of sliding off it.
+  - `translate` is applied after layout, so neither problem applies.
+- To mirror the motion in RTL (as Chrome's native bar does), reverse the animation under `:dir(rtl)`:
+
+```css
+progress:dir(rtl) {
+  --progress-bar-indeterminate-animation: progress-bar-indeterminate var(--progress-bar-indeterminate-animation-duration) infinite linear reverse;
+}
+```
+
+- Define the public `--progress-bar-indeterminate-*` properties on `progress` (their name already scopes them to the state) so consumers can override them without knowing about `:indeterminate`.
+- To vary the segment length (e.g. the leading edge races ahead and the trailing edge catches up), set `--progress-bar-indeterminate-animation` to two concurrent animations: one whose keyframes animate `translate` in `cqi` (position) and one whose keyframes animate `inline-size` (length), so each gets its own keyframes and easing. Do NOT try to shape both edges in a single keyframe list; per-keyframe `animation-timing-function` applies to every property in that keyframe.
+- `--progress-bar-animation` applies in both states and can be used for effects such as a determinate shimmer. `revert-rule` is used to only override when it is set, to maximize composability.
+- Never disable the indeterminate animation (`animation: none` leaves a zero-width fill in Chromium). For reduced motion, slow it down instead.
+
+```css
+progress {
+  /* Lets the fill position itself in track units (cqi) */
+  container-type: inline-size;
+  /* Segment length relative to the track */
+  --progress-bar-indeterminate-size: 30%;
+  --progress-bar-indeterminate-animation-duration: 1.5s;
+
+  /* Respect prefers-reduced-motion */
+  @media (prefers-reduced-motion: reduce) {
+    --progress-bar-indeterminate-animation-duration: 10s;
+  }
+}
+
+progress:indeterminate {
+  --progress-bar-animation: var(
+      --progress-bar-indeterminate-animation,
+      progress-bar-indeterminate var(--progress-bar-indeterminate-animation-duration) infinite linear
+    );
+}
+
+/* Add to the existing pseudo-element rules */
+progress::-webkit-progress-value {
+  animation: var(--progress-bar-animation, revert-rule);
+}
+
+progress::-moz-progress-bar {
+  animation: var(--progress-bar-animation, revert-rule);
+}
+
+/* Physical: left to right regardless of direction (reverse under :dir(rtl) to mirror). */
+@keyframes progress-bar-indeterminate {
+  from, to {
+    inline-size: var(--progress-bar-indeterminate-size);
+    /* Pin to the physical left; Chromium would otherwise lay the fill out at the inline start */
+    margin-right: auto;
+  }
+  from { translate: -100%; } /* Own width: fully outside the left edge */
+  to { translate: 100cqi; }  /* Track width: fully outside the right edge */
+}
+```
+
+### Additional Accessibility Considerations
+
+In addition to the guidelines mentioned above:
+* **Announce completion without stealing focus**: Do not set `tabindex` or call `.focus()` on `<progress>`, as it is non-interactive and moving focus to it disrupts keyboard users. To announce when a background task finishes, update a polite status element (`role="status"` or `aria-live="polite"`).
+* **Do not add fallback text inside `<progress>`**: Text inside `<progress>` is ignored by modern browsers and is not used by assistive technologies.
+* Avoid `aria-busy` + `aria-describedby` on an unlabeled generic `<div>`. `aria-busy` has inconsistent screen reader support, and `aria-describedby` on an unnamed `<div>` without a role is ignored by assistive technologies. If a region's content is not ready while loading, hide it with `hidden` or `aria-hidden="true"`.
+* **DO** ensure proper contrast between the progress bar and track when adding custom styles.
+* **Consider alternatives to represent indeterminate state**: Indeterminate progress bar animations displayed in parallel to other content can be considered distracting for some users.
+
+## Fallback strategies
+
+### Fallbacks & browser support for accent-color
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+The `accent-color` property is progressive enhancement.
+Browsers that do not support this property will ignore it and use their default UI colors.
+
+If `accent-color` is not supported and styling the progress bar is required, use the customized styling method to apply preferred styling to the progress bar.
+
+### Fallbacks & browser support for `revert-rule`
+
+Baseline status for revert-rule: Newly available. It's been Baseline since 2026-09-14.
+Supported by: Chrome 148 (May 2026), Edge 148 (May 2026), Firefox 150 (Apr 2026), and Safari 27 (Sep 2026).
+
+If `revert-rule` is not supported, `animation: var(--progress-bar-animation, revert-rule)` falls back to `animation-name: revert-rule` with a `0s` duration when `--progress-bar-animation` is unset, which is a harmless no-op when no `@keyframes revert-rule` exists.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/scrollspy.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/scrollspy.md
new file mode 100644
index 00000000..6924a2cb
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/scrollspy.md
@@ -0,0 +1,127 @@
+# Build a Scrollspy Navigation
+
+A scrollspy navigation is a common UI pattern that automatically highlights the navigation link corresponding to the section of the page currently in the viewport. This provides users with a clear sense of where they are in a long document as they scroll.
+
+This pattern is common in two scenarios:
+- **Single-page websites**: Where the primary site navigation links to different sections of a single page rather than separate URLs.
+- **Long-form content**: Where a table of contents or sidebar navigation tracks the user's progress through an article, guide, or documentation.
+
+## How to implement
+
+Traditionally, the scrollspy pattern required JavaScript and the `IntersectionObserver` API. Modern CSS provides a native way to achieve this using the `scroll-target-group` property and the `:target-current` pseudo-class.
+
+1.  **Ensure Navigation Links use Fragment Identifiers**: Your navigation must consist of anchor links (`<a>`) that point to sections on the same page using fragment identifiers (e.g., `<a href="#section-1">`) that match the `id` of your content sections.
+2.  **Enable Scroll Target Grouping**: Apply the `scroll-target-group: auto` property to the container of your navigation links. This tells the browser to treat these links as markers that track their respective targets.
+3.  **Style the Active Link**: Use the `:target-current` pseudo-class on your navigation links to apply styles when their target section is visible in the scroll container.
+4.  **Semantic State**: Use a script to update `aria-current="true"` on the active link when scrolling stops to ensure the state is correctly communicated to assistive technologies.
+
+## Example code
+
+This example highlights the active link in a fixed navigation menu as the user scrolls through sections.
+
+```css
+
+/* MANDATORY: The container of markers must have scroll-target-group: auto */
+nav {
+  /* Enables automatic tracking of fragment links */
+  scroll-target-group: auto;
+}
+/* MANDATORY: Use :target-current to style the link whose target is in view. */
+nav a:target-current {
+  color: var(--accent, #007bff);
+  border-bottom-color: var(--accent, #007bff);
+}
+```
+
+```html
+<nav>
+  <a href="#intro">Introduction</a>
+  <a href="#features">Features</a>
+  <a href="#pricing">Pricing</a>
+</nav>
+
+<main>
+  <!-- MANDATORY: Each section must have a unique ID matching a link fragment in the <nav>. -->
+  <section id="intro">
+    <h2>Introduction</h2>
+    <!-- content -->
+  </section>
+  <section id="features">
+    <h2>Features</h2>
+    <!-- content -->
+  </section>
+  <section id="pricing">
+    <h2>Pricing</h2>
+    <!-- content -->
+  </section>
+</main>
+
+<script type="module">
+  if (CSS.supports('scroll-target-group: auto')) {
+    const syncAriaCurrent = () => {
+      const currentLink = document.querySelector('nav a:target-current');
+      document.querySelectorAll('nav a').forEach(link => {
+        link.setAttribute('aria-current', link === currentLink ? 'true' : 'false');
+      });
+    };
+    // Update the aria on initial page load. Ensure the DOM content is loaded, either by using `<script type="module">` or an event listener for `DOMContentLoaded`.
+    syncAriaCurrent();
+    // Update the aria after scroll ends
+    document.addEventListener('scrollend', syncAriaCurrent);
+  }
+</script>
+```
+
+## Best Practices
+
+- **DO** use `scroll-target-group: auto` on a dedicated container for navigation links: This ensures the browser knows which links should be tracked.
+- **DO** ensure targets have unique `id` attributes matching the links' `href` attributes.
+- **DO** provide enough vertical space for sections: `scroll-target-group` most clearly identifies the visible target when sections are large enough that only one or two are visible at a time.
+- **MANDATORY**: For accessibility, the visual state must be mirrored with `aria-current`. While `:target-current` handles the visual aspect, this is not exposed to screen readers.
+- **AVOID** relying solely on color for the active state: Include other visual cues like font weight, an underline, or an indicator dot, or ensure there is sufficient contrast between the colors to ensure the difference is accessible to users with color vision deficiencies.
+
+## Fallback strategies
+
+Browser support for scroll-target-group: Limited availability.
+Supported by: Chrome 140 (Sep 2025) and Edge 140 (Sep 2025).
+Unsupported in: Firefox and Safari.
+
+For browsers that do not support `scroll-target-group`, you should use a fallback based on the `IntersectionObserver` API.
+
+```html
+<script>
+  // Feature detection for scroll-target-group
+  const supportsScrollTargetGroup = CSS.supports('scroll-target-group: auto');
+
+  if (!supportsScrollTargetGroup) {
+    const navLinks = document.querySelectorAll('nav a');
+    const sections = document.querySelectorAll('main section');
+
+    const observer = new IntersectionObserver((entries) => {
+      entries.forEach(entry => {
+        if (entry.isIntersecting) {
+          const id = entry.target.getAttribute('id');
+          navLinks.forEach(link => {
+            const isActive = link.getAttribute('href') === `#${id}`;
+            // Use the escaped colon class for consistent styling
+            link.classList.toggle('\:target-current', isActive);
+            link.setAttribute('aria-current', isActive);
+          });
+        }
+      });
+    }, { rootMargin: '-50% 0px -50% 0px', threshold: 0 });
+
+    sections.forEach(section => observer.observe(section));
+  }
+</script>
+
+<style>
+  /* Fallback style if :target-current is not supported.
+     Use :is() to combine the native pseudo-class with a fallback class for older browsers. DO NOT use `nav a:target-current, nav a.\:target-current, as the unrecognized pseudoselector invalidates the entire rule in older browsers. */
+  nav a:is(:target-current, .\:target-current) {
+    color: var(--accent, #007bff);
+    border-bottom-color: var(--accent, #007bff);
+    font-weight: bold;
+  }
+</style>
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/spinner.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/spinner.md
new file mode 100644
index 00000000..28c582bf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/spinner.md
@@ -0,0 +1,169 @@
+# Loading spinner
+
+A loading spinner (or activity indicator) informs users that a process is underway when the exact duration is unknown. Unlike a progress ring, a spinner is "indeterminate" and typically uses animation to signal activity.
+
+This guide implements a spinner by:
+
+- Using the native `<progress>` element as the semantic foundation. By omitting the `value` attribute, the browser treats it as an indeterminate progress bar, ensuring correct announcement by assistive technologies.
+- Styling the component with `conic-gradient()` to create a visual "trail" and `background-clip: border-area` to hollow out the center into a ring.
+- Animating the spinner efficiently using CSS transforms and respecting `prefers-reduced-motion` to ensure a comfortable experience for all users.
+
+See `progress-ring` (via `npx -y modern-web-guidance@latest retrieve "progress-ring"`) for handling determinate tasks with a known duration.
+
+
+## Implementation
+
+### 1. Markup
+
+Use the native `<progress>` element as both the semantic source of truth and the visual component. Without a `value` attribute, it is implicitly indeterminate.
+
+```html
+<progress aria-label="Loading" class="loading-spinner"></progress>
+```
+
+### 2. Styles
+
+#### Hiding Native UI
+To style the `<progress>` element as a spinner, first hide the default browser styling for indeterminate progress bars.
+
+```css
+/* Hide native bars */
+progress.loading-spinner:indeterminate::-webkit-progress-bar {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::-webkit-progress-value {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::-moz-progress-bar {
+  display: none;
+  background: none;
+}
+progress.loading-spinner:indeterminate::slider-fill {
+  display: none;
+  background: none;
+}
+```
+
+#### Spinner Ring and Trail
+The spinner uses a `conic-gradient` to create a visual trail.
+
+```css
+@property --arc-start {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+@property --arc-end {
+  syntax: "<angle>";
+  inherits: false;
+  initial-value: 0deg;
+}
+/* Use a custom property to conditionally include the dash animation */
+@property --progress-dash-animation {
+  syntax: "*";
+  inherits: false;
+  initial-value: , progress-dash 3s ease-in-out infinite;
+}
+
+progress.loading-spinner:indeterminate {
+  --_from: calc(90deg + var(--arc-start, 0deg));
+  --_to: calc(90deg + var(--arc-end, 158deg));
+  --size: 40px;
+  --thickness: 2px;
+  --spinner-color: #3b82f6;
+  --track-color: #e2e5e7;
+  --spinner-duration: 1.5s;
+  --_used-spinner-duration: var(--spinner-duration);
+  --spinner-timing: linear;
+
+  position: relative;
+  width: var(--size);
+  height: var(--size);
+  border-radius: 50%;
+  appearance: none;
+
+  /* Create the fading trail with dynamic angles */
+  background: conic-gradient(
+      from var(--_from),
+      var(--spinner-color) calc(var(--_to) - var(--_from)),
+      transparent 0
+    )
+    var(--track-color);
+
+  @supports (background-clip: border-area) {
+    background-clip: border-area;
+    border: var(--thickness) solid transparent;
+    background-origin: border-box;
+  }
+
+  /* ... fallback for background-clip: border-area ... */
+
+  /* The dash animation is only included if @property is supported */
+  animation:
+    progress-spin var(--_used-spinner-duration) linear infinite
+    var(--progress-dash-animation, );
+}
+
+@keyframes progress-spin {
+  to {
+    rotate: 1turn;
+  }
+}
+
+@keyframes progress-dash {
+  from {
+    --arc-start: 0deg;
+    --arc-end: 3deg;
+  }
+  50% {
+    --arc-start: 100deg;
+    --arc-end: 358deg;
+  }
+  to {
+    --arc-start: 360deg;
+    --arc-end: 363deg;
+  }
+}
+```
+
+#### Respecting Motion Preferences
+
+Users with motion sensitivities may find fast-spinning elements disorienting. Always respect the `prefers-reduced-motion` media query. Set the internal `--_used-spinner-duration` property to override the user's `--spinner-duration` value.
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  .loading-spinner {
+    /* Slow down the animation significantly rather than stopping it entirely,
+       so the user still knows that the process is active. */
+    --_used-spinner-duration: 6s;
+  }
+}
+```
+
+## Fallback strategies
+
+Baseline status for Registered custom properties: Newly available. It's been Baseline since 2024-07-09.
+Supported by: Chrome 85 (Aug 2020), Edge 85 (Aug 2020), Firefox 128 (Jul 2024), and Safari 16.4 (Mar 2023).
+
+If `@property` is supported, the dash animation is automatically included via the `--progress-dash-animation` property's `initial-value`. In browsers without `@property` support, the property registration is ignored, and the animation falls back to a simple rotation. No JavaScript is required for this fallback.
+
+Browser support for background-clip: border-area: Limited availability.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+For browsers that don't yet support `background-clip: border-area`, fall back to a `mask-image` to hollow out the center.
+
+```css
+/* Fallback: use mask-image to create the ring */
+@supports not (background-clip: border-area) {
+  --clip-boundary: calc(100% - var(--thickness));
+  mask-image: radial-gradient(
+    farthest-side,
+    transparent var(--clip-boundary),
+    black var(--clip-boundary)
+  );
+  border: 0;
+}
+```
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/stack-drill-down.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/stack-drill-down.md
new file mode 100644
index 00000000..985208c1
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/ui-components/stack-drill-down.md
@@ -0,0 +1,689 @@
+# Stack Drill Down
+
+## Overview
+
+A stack drill-down is a hierarchical navigation pattern, common in mobile apps, where activating a link pushes a new full-screen view on top of the previous one. The view's content is application-defined — a settings sub-page, a thread inside a feed, a folder inside a file browser, a detail page inside a gallery, etc. The user returns by swiping the current view off-screen to the right or by tapping a back button. Browser history stays in sync so the OS-level Back gesture, deep links, and forward/back navigation all work coherently.
+
+This guide implements the stack as:
+
+- A horizontal CSS scroll-snap container where each view is exactly one snap stop. Drilling down appends a new view and smooth-scrolls to it; the swipe-back gesture is handled natively by the browser, giving momentum, velocity, and interruption tracking for free with no pointer-event JavaScript.
+- A `scrollsnapchange` event listener on the stack that fires when the snap target changes. This is used as the single source of truth for "the active view changed" — so swipe, click, programmatic scroll, and `popstate` paths all converge in one callback that updates `inert`, restores focus, prunes views the user swiped past, and reconciles browser history.
+- A `pushState` / `popstate` integration so every drill-down adds a history entry, the OS-level Back gesture works, and deep links open directly into the right view.
+- An (optional) scroll-driven `view()` animation on each view that produces a parallax + dim + shadow effect tied directly to the swipe gesture, so the visible motion is driven by the user's finger, not a tween.
+
+This approach is preferred over JavaScript-driven `transform` animations because the snap mechanism gives the user direct gestural control of the panel's position (their finger drives it, not a tween) and matches the interaction patterns users expect from native mobile apps.
+
+## Implementation
+
+### 1. Markup
+
+The static HTML is just an empty stack container; views are built in JavaScript and appended as the user navigates.
+
+```html
+<div class="Stack">
+  <!-- Intentionally empty. The initial view is appended by JavaScript
+       at init time (step 8). -->
+</div>
+```
+
+Each view is a `.Stack-view` direct child of `.Stack` (the snap target) with a `.Stack-viewContent` wrapper inside it (where view content lives, and where the parallax transform applies — see step 2). At any moment the stack has one view per active history entry, left-to-right in drill-down order. After the user has drilled in two levels from the root the rendered DOM looks like this:
+
+```html
+<div class="Stack">
+  <!-- Root view. Has whatever content makes sense as the entry point
+       of this section of the app. No back button — there is nothing
+       behind the root in the stack. -->
+  <div class="Stack-view" inert>
+    <div class="Stack-viewContent">
+      <!-- Root content; includes <a href> links that drill in. -->
+    </div>
+  </div>
+
+  <!-- First-level drill-down view. The user got here by activating a
+       link in the root view. -->
+  <div class="Stack-view" inert>
+    <div class="Stack-viewContent">
+      <header>
+        <!-- DO include a back button. The swipe gesture only works on
+             touch — keyboard and pointer users need an explicit control. -->
+        <button class="back" aria-label="Back"></button>
+        <!-- Title / breadcrumb / etc. -->
+      </header>
+      <main>
+        <!-- View content; may include further drill-down <a href> links. -->
+      </main>
+    </div>
+  </div>
+
+  <!-- Second-level drill-down view. Currently visible — no `inert`
+       attribute. Same shape as the first-level view. -->
+  <div class="Stack-view">
+    <div class="Stack-viewContent">
+      <header>
+        <button class="back" aria-label="Back"></button>
+        <!-- ... -->
+      </header>
+      <main><!-- ... --></main>
+    </div>
+  </div>
+</div>
+```
+
+Notes:
+
+- All views except the currently-visible one carry the `inert` attribute. This is applied/removed automatically by the `scrollsnapchange` handler in step 7 — do not set it from your view builders.
+- Views the user swipes back past are removed from the DOM (also by step 7) so the stack never grows beyond `currentDepth + 1` children. They are rebuilt on demand from their cached URL paths if forward navigation returns to them.
+
+### 2. Styles
+
+#### The stack scroller
+
+The stack is a horizontal grid where each child view is exactly the width of the container, with CSS scroll-snap enforcing one-view-per-snap. This is what gives the swipe-back gesture its native feel.
+
+```css
+.Stack {
+  /* Use dvh so the height tracks the dynamic viewport on mobile, where
+     the address bar can show/hide. svh would clip during the address bar
+     animation; vh leaks under it. */
+  height: 100dvh;
+
+  /* Lay views out left-to-right, each one full-width, so horizontal
+     scrolling moves between them one at a time. */
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 100%;
+  grid-template-rows: 100%;
+  overflow-x: auto;
+
+  /* `mandatory` guarantees the stack always settles fully on a view —
+     never half-way between two. */
+  scroll-snap-type: x mandatory;
+  /* Prevent the swipe-back gesture from chaining into the browser's
+     own history-back gesture (iOS, some Android) or the page's vertical
+     scroll. The user is navigating the stack, not the page. */
+  overscroll-behavior-x: none;
+}
+
+/* Hide the visual scrollbar — the snap and the parallax are the
+   affordances; a horizontal scrollbar would look out of place. */
+.Stack::-webkit-scrollbar {
+  display: none;
+}
+
+/* MANDATORY: Opt into smooth programmatic scrolling via CSS, gated on
+   prefers-reduced-motion. JS code calls scrollTo/scrollBy with
+   behavior: 'auto' which defers to this rule, so the OS-level reduced-
+   motion preference automatically downgrades to instant scrolling
+   without any per-call JS branching. */
+@media (prefers-reduced-motion: no-preference) {
+  .Stack {
+    scroll-behavior: smooth;
+  }
+}
+
+.Stack-view {
+  scroll-snap-align: start;
+  /* `always` prevents the user from blowing through more than one view
+     per gesture, so depth changes always happen one step at a time. */
+  scroll-snap-stop: always;
+}
+
+/* MANDATORY: A separate inner element is required for the parallax
+   transform below. Applying transforms directly to the snap target
+   (.Stack-view) would feed back into the scroll container's snap
+   geometry and the scroller would jump mid-gesture. */
+.Stack-viewContent {
+  width: 100%;
+  height: 100%;
+  background-color: #fff;
+  /* Each view scrolls its own content vertically, independent of the
+     stack's horizontal scroll. */
+  overflow-y: auto;
+}
+```
+
+#### The "stack" effect (parallax / dim / shadow)
+
+A scroll-driven `view(inline)` animation tracks each view's progress through the stack scroller and applies a parallax + dim to the exiting view, plus a shadow on incoming drill-down views so they read as "cards" stacking over the previous view.
+
+```css
+/* MANDATORY: Wrap the animation block in @supports. Browsers without
+   scroll-driven animations still parse the @keyframes and would
+   apply the `to` state as a static style, leaving every view
+   permanently transformed. The @supports gate confines the animation
+   to browsers where it actually animates. */
+@supports (animation-timeline: view()) {
+  .Stack-viewContent {
+    /* view(inline) tracks this element's progress through its nearest
+       scrollable ancestor on the inline (x) axis. */
+    animation: parallax linear both;
+    animation-timeline: view(inline);
+    /* Only animate the EXIT phase — when this view is being covered
+       by a deeper one. During its own entry the view stays at rest,
+       so the fresh content is fully bright and in position throughout. */
+    animation-range: exit 0% exit 100%;
+  }
+
+  /* Drill-down views (everything except the root) also get a shadow on
+     their left edge during the transition so they feel like cards
+     stacking over the previous view. */
+  .Stack-view:not(:first-child) .Stack-viewContent {
+    animation: parallax linear both, shadow-fade linear both;
+    animation-timeline: view(inline), view(inline);
+    /* parallax: only exit (the view sliding back as a deeper one comes in).
+       shadow-fade: entry through exit (visible the whole time the view is
+       transitioning, not when it's at rest). */
+    animation-range: exit 0% exit 100%, entry 0% exit 100%;
+  }
+
+  @keyframes parallax {
+    /* translateX(75%) and brightness(0.8) are examples — adjust to taste. */
+    to {
+      transform: translateX(75%);
+      filter: brightness(0.8);
+    }
+  }
+
+  @keyframes shadow-fade {
+    /* Shadow ramps in during entry, holds across the middle of the
+       gesture, and ramps out during exit — so it's only visible while
+       the view is mid-transition, not when at rest. */
+    0%, 100% { box-shadow: 0 0 1.5rem #0000; }
+    25%, 75% { box-shadow: 0 0 1.5rem #0004; }
+  }
+}
+```
+
+NOTE: This effect is popular in modern native stack applications and is a good starting point, but the exact visual effects can be customized to fit existing transition styles as needed.
+
+### 3. Module state
+
+The stack tracks four pieces of state in module scope:
+
+```js
+const stack = document.querySelector('.Stack');
+
+// Reference to the root view DOM element. The Stack starts empty, so
+// this is null until the root view is created — either at init (step 8,
+// when the URL is '/') or later by synthesizeRootEntry() (when the user
+// landed on a deep link and then navigates back). Held as a mutable
+// reference because other code (the scrollsnapchange handler, init, etc.)
+// uses identity comparisons against it.
+let rootView = null;
+
+// Tracks which element to restore focus to when the user swipes back
+// into a previous view. Keyed by the view element itself so entries
+// are garbage-collected automatically when the view is pruned.
+const returnFocus = new WeakMap();
+
+// Maps history depth -> {urlPath, view}. We MUST maintain this map
+// ourselves because the History API does not expose state for entries
+// other than the current one — so when a view is pruned on swipe-back,
+// we still need to remember which URL it represented in case the user
+// later forward-navigates back into it.
+const entriesByDepth = new Map();
+
+// Tracked manually because history.state on a popstate event tells us
+// the destination depth but not where we came from. We need both to
+// compute the direction (back vs forward) and the distance.
+let currentDepth = 0;
+```
+
+Plus three application-specific helpers — the only places where your app's routing and view rendering plug in:
+
+```js
+// Resolve a URL path to the data your app needs to render the
+// corresponding drill-down view, or return null for paths this section
+// of the app does not handle (the root path '/', external links,
+// unknown routes). resolveUrl() is for drill-down routes only — the
+// root view is rendered separately by createRootView() below.
+function resolveUrl(urlPath) {
+  // Replace with your routing logic. For example, match `/view/:id`
+  // and look the id up in your app state.
+}
+
+// Build the root (home) view of the stack. Application-specific content;
+// preserve the .Stack-view / .Stack-viewContent wrapper structure (the
+// inner element is required for the parallax — see step 2) and DO NOT
+// render a back button — the root view has nothing behind it in the
+// stack.
+function createRootView() {
+  const view = document.createElement('div');
+  view.className = 'Stack-view';
+  view.innerHTML = `
+    <div class="Stack-viewContent">
+      <!-- Root content. Include <a href> elements pointing at URL paths
+           that resolveUrl() accepts, to enable drill-down from here. -->
+    </div>
+  `;
+  return view;
+}
+
+// Build a drill-down view DOM element from the resolved route data.
+// Customize the inner content freely, but DO preserve the .Stack-view
+// / .Stack-viewContent wrapper structure and DO include a back button
+// (the swipe gesture only works on touch).
+function createDrillDownView(routeData) {
+  const view = document.createElement('div');
+  view.className = 'Stack-view';
+  view.innerHTML = `
+    <div class="Stack-viewContent">
+      <header>
+        <button class="back" aria-label="Back"></button>
+        <!-- Title, breadcrumb, or other view chrome derived from
+             routeData. -->
+      </header>
+      <main>
+        <!-- View body, also from routeData. Include further <a href>
+             elements pointing at URL paths that resolveUrl() also
+             accepts, to enable additional drill-downs from this view. -->
+      </main>
+    </div>
+  `;
+  return view;
+}
+
+function getCurrentUrlPath() {
+  return location.pathname;
+}
+```
+
+### 4. Drill down
+
+A drill-down does four things in this order: push a history entry, build the new view, append it, smooth-scroll to it. The `scrollsnapchange` handler (step 7) picks up from there once the snap settles.
+
+```js
+function drillDown(urlPath) {
+  const routeData = resolveUrl(urlPath);
+  if (!routeData) return;
+
+  const newDepth = currentDepth + 1;
+  // Push BEFORE creating the view so the URL is correct if anything
+  // observing history (analytics, etc.) reads it during view creation.
+  history.pushState({depth: newDepth}, '', urlPath);
+
+  // pushState truncates forward entries in real browser history;
+  // mirror that truncation in our depth map so we don't hold references
+  // to views the user can no longer reach.
+  for (const d of entriesByDepth.keys()) {
+    if (d >= newDepth) entriesByDepth.delete(d);
+  }
+  currentDepth = newDepth;
+
+  const newView = createDrillDownView(routeData);
+  stack.appendChild(newView);
+  entriesByDepth.set(newDepth, {urlPath, view: newView});
+
+  // Scroll one viewport-width to the right. behavior: 'auto' defers to
+  // the CSS `scroll-behavior` set in step 2, which is smooth unless
+  // prefers-reduced-motion is set. The snap container locks onto the
+  // new view; the scrollsnapchange listener (step 7) fires when the
+  // snap settles.
+  stack.scrollBy({left: stack.clientWidth, behavior: 'auto'});
+}
+```
+
+### 5. Click and back-button handling
+
+Intercept link clicks inside the stack and convert them to drill-downs. Preserve modifier-key behavior so cmd/middle-click still opens the link in a new tab.
+
+```js
+stack.addEventListener('click', (e) => {
+  // Back button: defer to goBack() (defined below), which handles both
+  // the normal in-app case and the deep-link case.
+  if (e.target.closest('.back')) {
+    goBack();
+    return;
+  }
+
+  // Drill-down link.
+  const link = e.target.closest('a');
+  if (!link || !stack.contains(link)) return;
+  // Let the browser handle modified clicks so users can open links
+  // in new tabs / windows. e.button !== 0 filters out middle-clicks.
+  if (e.metaKey || e.ctrlKey || e.shiftKey || e.button !== 0) return;
+
+  const urlPath = new URL(link.href).pathname;
+  const parentView = link.closest('.Stack-view');
+  // If the URL isn't handled by this section of the app (resolveUrl
+  // returns null), fall through so the browser navigates normally.
+  if (!resolveUrl(urlPath) || !parentView) return;
+
+  e.preventDefault();
+  // Record which link the user activated so focus can be restored to
+  // it when they swipe (or click) back into this view.
+  returnFocus.set(parentView, link);
+  drillDown(urlPath);
+});
+
+// Going back is usually just history.back(), but there's an important
+// edge case: when the user lands directly on a deep-linked URL, there
+// is no in-app history entry behind it. Calling history.back() in that
+// situation would take them out of the app entirely. MANDATORY: detect
+// this case and synthesize a root entry instead, so an in-app Back from
+// a deep link lands on the root view and the platform Back from there
+// returns the user to where they came from.
+function goBack() {
+  const atDeepLinkRoot = currentDepth === 0
+    && entriesByDepth.get(0)?.view !== rootView;
+  if (atDeepLinkRoot) {
+    synthesizeRootEntry();
+  } else {
+    // history.back() fires popstate, which routes through
+    // updateFromHistoryState (step 6) and scrolls the stack — the
+    // same path a swipe-back converges on.
+    history.back();
+  }
+}
+
+function synthesizeRootEntry() {
+  // Push a new history entry pointing at the root URL. This becomes the
+  // entry the user "came from"; the original deep-linked entry is now
+  // behind us, so platform Back from the root view will return there.
+  const newDepth = currentDepth + 1;
+  history.pushState({depth: newDepth}, '', '/');
+
+  // Create the root view if it doesn't exist yet (we landed on a deep
+  // link and never needed it before now), and insert it at the LEFT end
+  // of the stack. Adjust scrollLeft by one viewport width so the user's
+  // view doesn't visually jump — they should still be looking at the
+  // deep-linked view until the scroll animation below runs.
+  if (!rootView) {
+    rootView = createRootView();
+    stack.prepend(rootView);
+    stack.scrollLeft += stack.clientWidth;
+  }
+  entriesByDepth.set(newDepth, {urlPath: '/', view: rootView});
+
+  // Now scroll to the new entry (the root view). updateFromHistoryState
+  // smooth-scrolls one step left, the parallax plays, and
+  // scrollsnapchange fires when the root view settles.
+  updateFromHistoryState(history.state);
+}
+```
+
+### 6. Sync from history (popstate)
+
+`popstate` fires when the user uses the browser/OS back or forward button, or when JavaScript calls `history.back()` / `.go()`. This handler is the only path that scrolls the stack in response to a history change.
+
+```js
+window.addEventListener('popstate', (event) => {
+  updateFromHistoryState(event.state);
+});
+
+function updateFromHistoryState(state, behaviorOverride) {
+  const newDepth = state?.depth ?? 0;
+  const urlPath = getCurrentUrlPath();
+
+  // Ensure entriesByDepth has an entry for the destination depth.
+  // If the URL changed (e.g. forward-nav into a previously-pruned
+  // view), clear the cached view reference so the loop below rebuilds.
+  const entry = entriesByDepth.get(newDepth) ?? {view: null};
+  if (entry.urlPath !== urlPath) {
+    entry.urlPath = urlPath;
+    entry.view = urlPath === '/' ? rootView : null;
+  }
+  entriesByDepth.set(newDepth, entry);
+
+  // Rebuild any views between root and the destination that were
+  // pruned earlier (when the user swiped back past them). Without
+  // this, forward-navigating to a previously-pruned view would have
+  // no element to scroll to.
+  for (let d = 0; d <= newDepth; d++) {
+    const e = entriesByDepth.get(d);
+    if (!e || e.view) continue;
+    const routeData = resolveUrl(e.urlPath);
+    if (!routeData) continue;
+    const rebuilt = createDrillDownView(routeData);
+    stack.appendChild(rebuilt);
+    e.view = rebuilt;
+  }
+
+  currentDepth = newDepth;
+
+  const targetView = entriesByDepth.get(newDepth)?.view;
+  if (!targetView) return;
+
+  // Compare destination index against current scroll position so we
+  // can bail if they're already aligned. This is reached when the
+  // scrollsnapchange handler below calls history.go() to sync history
+  // after a swipe-back that already completed visually — there's
+  // nothing more to scroll.
+  const toIdx = [...stack.children].indexOf(targetView);
+  const fromIdx = Math.round(stack.scrollLeft / stack.clientWidth);
+  if (fromIdx === toIdx) return;
+
+  // Pick a scroll behavior:
+  //   - multi-step jumps (e.g. history.go(-3)): 'instant' to skip
+  //     intermediate snap points — otherwise smooth-scrolling would
+  //     fire scrollsnapchange for each one and do N rounds of
+  //     state-transition work for no reason.
+  //   - rightward (forward) single-step: 'instant'. Browser-forward is
+  //     rare on the web and is often spurious (e.g. iOS Safari treats
+  //     edge swipes as forward navigation, even with overscroll-behavior
+  //     set). An instant swap reads as "snap" rather than a misleading
+  //     drilldown animation the user didn't ask for. The user-initiated
+  //     drill-down path (drillDown, step 4) is unaffected — it calls
+  //     scrollBy directly and never reaches this code.
+  //   - leftward (back) single-step: 'auto' so the CSS `scroll-behavior`
+  //     (smooth unless prefers-reduced-motion is set — see step 2)
+  //     applies. Back is the common, expected case and benefits from
+  //     the animation.
+  // NOTE: "forward" here means spatial direction (toIdx > fromIdx),
+  // NOT depth direction. synthesizeRootEntry (step 5) pushes a new
+  // depth but scrolls LEFT to the root view, which correctly reads as
+  // back-style (smooth).
+  const forward = toIdx > fromIdx;
+  const multiStep = Math.abs(toIdx - fromIdx) > 1;
+  const behavior = behaviorOverride ?? (forward || multiStep ? 'instant' : 'auto');
+  stack.scrollTo({left: toIdx * stack.clientWidth, behavior});
+}
+```
+
+### 7. `scrollsnapchange`: the single source of truth
+
+After every snap commit — whether triggered by a swipe, a click, or a programmatic scroll — the browser fires a `scrollsnapchange` event on the scroll container, with the newly snapped element exposed as `event.snapTargetInline` (for horizontal snapping). Putting all state transitions inside this one handler is what keeps the swipe path, the click path, and the `popstate` path coherent.
+
+The handler is extracted into a standalone `onActiveViewChanged` function so the fallback (see "Fallback strategies" below) can reuse it without duplicating the logic.
+
+```js
+function onActiveViewChanged(currentView) {
+  // Walk the stack in DOM order to update each view's role:
+  //  - Views at or before currentView stay in the DOM but get
+  //    `inert` (except currentView) so focus, pointer events, and
+  //    AT navigation cannot leak into views hidden behind the
+  //    parallax.
+  //  - Views after currentView are unreachable (the user swiped
+  //    back past them) so we drop them from the DOM to free memory.
+  //    Their urlPath stays in entriesByDepth so a later forward
+  //    navigation can rebuild the view from scratch.
+  let seenCurrent = false;
+  for (const view of [...stack.children]) {
+    if (seenCurrent) {
+      for (const e of entriesByDepth.values()) {
+        if (e.view === view) e.view = null;
+      }
+      view.remove();
+    } else {
+      // MANDATORY: inert non-current views. Without this, tabbing
+      // and screen-reader navigation can reach content hidden behind
+      // the parallax — a severe accessibility failure that's
+      // invisible to sighted users.
+      view.toggleAttribute('inert', view !== currentView);
+      if (view === currentView) seenCurrent = true;
+    }
+  }
+
+  // If the visible view's depth doesn't match `currentDepth`, the
+  // user got here by swiping (not clicking) — sync history so the
+  // browser back/forward buttons stay coherent with what's on screen.
+  let currentViewDepth;
+  for (const [d, e] of entriesByDepth) {
+    if (e.view === currentView) currentViewDepth = d;
+  }
+  if (currentViewDepth !== undefined && currentViewDepth !== currentDepth) {
+    // history.go fires popstate, which re-enters updateFromHistoryState.
+    // That call's fromIdx === toIdx check bails out without scrolling.
+    history.go(currentViewDepth - currentDepth);
+  }
+
+  // Restore focus on the now-active view:
+  //  - If we recorded which link the user activated to drill out
+  //    of this view, return focus there so a swipe-back lands them
+  //    exactly where they left off.
+  //  - Otherwise (a freshly-pushed drill-down view), move focus to
+  //    the back button so keyboard users have an obvious next action.
+  //  - preventScroll is REQUIRED: without it, .focus() scrolls the
+  //    snap container to bring the focused element into view, which
+  //    fights the snap and can land the user mid-snap.
+  const stored = returnFocus.get(currentView);
+  if (stored) {
+    stored.focus({preventScroll: true});
+    returnFocus.delete(currentView);
+  } else if (currentView !== rootView) {
+    currentView.querySelector('.back')?.focus({preventScroll: true});
+  }
+}
+
+stack.addEventListener('scrollsnapchange', (event) => {
+  // snapTargetInline is the element that was just snapped to on the
+  // inline (horizontal) axis. For this stack — where each view is one
+  // horizontal snap stop — that's the new active view.
+  onActiveViewChanged(event.snapTargetInline);
+});
+```
+
+### 8. Initialization (including deep links)
+
+When the page loads, the URL may already point at a deep view (a shared link, a bookmark, a refresh on a deep page). Build whichever initial view matches the URL — root or deep-linked, but never both — append it to the empty stack, seed the depth-0 history entry, and run an initial scroll pass with `behavior: 'instant'` so the parallax doesn't animate on first paint.
+
+```js
+const initialUrlPath = getCurrentUrlPath();
+const initialRouteData = resolveUrl(initialUrlPath);
+
+// Build the initial view: a drill-down view if the URL maps to one,
+// otherwise the root view. Whichever it is, that's the only view in
+// the stack right now — the other will be created lazily by
+// synthesizeRootEntry (step 5) or drillDown (step 4) if the user
+// navigates to it.
+let initialView;
+if (initialRouteData) {
+  initialView = createDrillDownView(initialRouteData);
+} else {
+  rootView = createRootView();
+  initialView = rootView;
+}
+stack.appendChild(initialView);
+
+entriesByDepth.set(0, {urlPath: initialUrlPath, view: initialView});
+// replaceState attaches a `depth` to the entry the user landed on, so
+// any subsequent pushState / popstate has a base depth to count from.
+history.replaceState({depth: 0}, '');
+
+updateFromHistoryState(history.state, 'instant');
+```
+
+### Best practices
+
+- **DO** use the `scrollsnapchange` event (with an `IntersectionObserver` fallback — see "Fallback strategies") as the source of truth for "the active view changed", not scroll-event coordinates. Snap commit is the only event that fires consistently across swipe, click, programmatic scroll, and `popstate` paths.
+- **DO** apply transforms to a child of the snap target, never to the snap target itself. A transform on the snap target feeds back into the scroll container's snap geometry and the scroller will glitch mid-gesture.
+- **DO** apply `inert` to every view except the currently visible one. Without this, focus and screen-reader navigation leak into views hidden behind the parallax — invisible to sighted users but a severe accessibility failure.
+- **DO** push a history entry on every drill-down and handle `popstate` so the OS-level Back gesture and the browser back/forward buttons work. This is what makes the pattern feel like a native app.
+- **DO** reconcile history from the active-view-changed handler when a swipe-back lands on a view whose depth doesn't match `currentDepth`. Without this, a subsequent OS Back returns the user somewhere unexpected because the browser's history cursor is out of sync with what's on screen.
+- **DO** prune views the user swiped past from the DOM. A long drill-down session can otherwise accumulate dozens of detached subtrees. The cached URL path in `entriesByDepth` is enough to rebuild any view if forward navigation returns to it.
+- **DO** call `.focus({preventScroll: true})` when restoring focus inside the stack. The default `preventScroll: false` makes the browser scroll the focus target into view, which fights the snap container and can land the user mid-snap.
+- **DO** preserve cmd/ctrl/middle-click on internal links so URLs remain shareable and openable in a new tab.
+- **DO** use `behavior: 'instant'` for multi-step history jumps AND for spatial-forward popstate transitions (`toIdx > fromIdx`). Multi-step jumps would otherwise fire `scrollsnapchange` at every intermediate snap and do N rounds of inert/focus/history work. Forward popstates are often spurious — iOS Safari treats edge swipes as browser forward even with `overscroll-behavior-x: none` set, and an instant swap is much less misleading than animating a "drilldown" the user didn't initiate. The user-initiated drill-down path (`drillDown`) is unaffected because it scrolls directly, not via `popstate`.
+- **DO** respect `prefers-reduced-motion`: declare `scroll-behavior: smooth` only inside `@media (prefers-reduced-motion: no-preference)` and call `scrollTo` / `scrollBy` with `behavior: 'auto'` (not `'smooth'`) so the OS-level preference takes effect without per-call JS branching. Hard-coding `behavior: 'smooth'` bypasses the user's setting.
+- **DO** render real `<a href>` elements as drill-down triggers, not `<button onclick>` or `<div>`. Real anchors get URL preview on hover, shareability, middle-click, screen-reader role, and SEO for free.
+- **DO** include an explicit back button in every drill-down view. The swipe gesture only works on touch — keyboard, pointer, and desktop users need a visible affordance.
+- **DO NOT** call `history.pushState` from the `popstate` handler — that pushes *new* entries while the user is trying to go back and breaks the browser back button.
+- **DO NOT** drive the parallax with a `scroll` event listener when scroll-driven animations are available. The CSS path runs on the compositor; a JS scroll listener runs on the main thread and will visibly drop frames during the gesture.
+- **DO NOT** mutate views you removed from the DOM after a swipe-back. Treat `entriesByDepth` as the canonical record: a pruned entry has `view: null` and is rebuilt on demand in `updateFromHistoryState`.
+
+### Fallback strategies
+
+Baseline status for Scroll snap: Widely available. It's been Baseline since 2020-01-15.
+Supported by: Chrome 69 (Sep 2018), Edge 79 (Jan 2020), Firefox 68 (Jul 2019), and Safari 11 (Sep 2017).
+
+Baseline status for Intersection observer: Widely available. It's been Baseline since 2019-03-25.
+Supported by: Chrome 58 (Apr 2017), Edge 16 (Oct 2017), Firefox 55 (Aug 2017), Safari 12.1 (Mar 2019), and Safari iOS 12.2 (Mar 2019).
+
+Baseline status for inert: Widely available. It's been Baseline since 2023-04-11.
+Supported by: Chrome 102 (May 2022), Edge 102 (May 2022), Firefox 112 (Apr 2023), and Safari 15.5 (May 2022).
+
+The features that may require fallbacks are scroll-snap-events and scroll-driven-animations, both of which have robust fallback or progressive enhancement stories, and are safe to use for this use case:
+
+#### Scroll snap events
+
+Browser support for Scroll snap events: Limited availability.
+Supported by: Chrome 129 (Sep 2024) and Edge 129 (Sep 2024).
+Unsupported in: Firefox and Safari.
+
+The `scrollsnapchange` event is the cleanest way to detect "the active view changed" — one listener on the stack, fired exactly once per snap commit. In browsers without it, the same effect can be polyfilled with an `IntersectionObserver` watching each view for full visibility inside the stack. The fallback dispatches into the same `onActiveViewChanged` function the primary path uses, so all the state-transition logic stays in one place.
+
+```js
+// MANDATORY when supporting browsers that haven't shipped scroll-snap-events
+// yet. Check `HTMLElement.prototype` (not `window` or `document`) — the
+// event handler IDL attribute is added to the prototype when the feature
+// is supported, regardless of whether any element has the handler set.
+if (!('onscrollsnapchange' in HTMLElement.prototype)) {
+  const viewObserver = new IntersectionObserver((entries) => {
+    for (const entry of entries) {
+      // threshold:1 only fires for fully-visible entries, but the
+      // observer also emits a "leaving" entry per view that drops below
+      // ratio 1. Filter to the entering side, which is the snap-commit
+      // moment we're trying to detect.
+      if (entry.intersectionRatio === 1) {
+        onActiveViewChanged(entry.target);
+      }
+    }
+  }, {root: stack, threshold: 1});
+
+  // Auto-observe every .Stack-view as it's added to the stack, and stop
+  // observing as it's removed. Using a MutationObserver lets the primary
+  // code (drillDown, updateFromHistoryState, synthesizeRootEntry, init)
+  // stay free of fallback wiring.
+  new MutationObserver((mutations) => {
+    for (const m of mutations) {
+      for (const node of m.addedNodes) {
+        if (node.classList?.contains('Stack-view')) viewObserver.observe(node);
+      }
+      for (const node of m.removedNodes) {
+        if (node.classList?.contains('Stack-view')) viewObserver.unobserve(node);
+      }
+    }
+  }).observe(stack, {childList: true});
+
+  // Catch up to any views already in the stack at the time this code
+  // runs (typically the initial view appended in step 8).
+  for (const view of stack.children) viewObserver.observe(view);
+}
+```
+
+#### Scroll-driven animations
+
+Browser support for Scroll-driven animations: Limited availability.
+Supported by: Chrome 115 (Jul 2023), Edge 115 (Jul 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+The scroll-driven parallax / dim / shadow effect is a progressive enhancement on top of the navigation core. The CSS `@supports (animation-timeline: view())` gate (shown in step 2) confines the animation to supporting browsers; everywhere else the views simply cut between snap stops with no transition. The component is fully functional without the parallax — snap, history sync, focus management, and `inert` all still work.
+
+If a parallax fallback is required for older baseline targets, attach a `scroll` listener to the stack and write a CSS custom property describing each view's progress through the scrollport, then drive `transform` and `filter` from that property:
+
+```js
+if (!CSS.supports('animation-timeline: view()')) {
+  stack.addEventListener('scroll', () => {
+    const viewWidth = stack.clientWidth;
+    for (const view of stack.children) {
+      // Progress: 0 when this view is centered, 1 when it has fully
+      // exited to the left. Matches the @keyframes mapping above.
+      const offsetLeft = view.offsetLeft - stack.scrollLeft;
+      const progress = Math.min(1, Math.max(0, -offsetLeft / viewWidth));
+      const content = view.querySelector('.Stack-viewContent');
+      content.style.transform = `translateX(${progress * 75}%)`;
+      content.style.filter = `brightness(${1 - progress * 0.2})`;
+    }
+  });
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/adapt-scrollbar-to-contrast-preferences.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/adapt-scrollbar-to-contrast-preferences.md
new file mode 100644
index 00000000..aec02957
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/adapt-scrollbar-to-contrast-preferences.md
@@ -0,0 +1,74 @@
+# Adapt scrollbar to high-contrast preferences
+
+Users who enable high-contrast modes in their operating system or browser expect UI elements (like scrollbars) to be extremely legible, often relying on stark foreground-background separation rather than subtle grays or theme colors.
+
+This guide provides optional instructions on how to use the `@media (prefers-contrast: more)` CSS media feature to enforce high-contrast scrollbar styling.
+
+## Enhance Legibility
+
+When customizing scrollbars with `scrollbar-color` or custom variables, you can provide an explicit override for high-contrast modes. This is especially helpful if your primary application theme uses low-contrast scrollbars for aesthetic reasons.
+
+OPTIONAL: Use a `@media (prefers-contrast: more)` block to define dark, distinct colors for the thumb and track.
+
+```css
+/* Define default standard colors as variables */
+.scroller {
+  --scrollbar-thumb: #bbb;
+  --scrollbar-track: #f1f1f1;
+
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+  scrollbar-width: thin;
+  scrollbar-gutter: stable;
+}
+
+/* OPTIONAL: Provide clear, high-contrast overrides */
+@media (prefers-contrast: more) {
+  .scroller {
+    /* Use extremely distinct colors like solid black against white */
+    --scrollbar-thumb: #000000;
+    --scrollbar-track: #ffffff;
+  }
+}
+```
+
+### Issues to be aware of when using scrollbar-color
+
+- Do NOT animate or transition `scrollbar-color`. A [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=311752) causes the scrollbar to flicker every time `scrollbar-color` changes.
+- On macOS, `scrollbar-color` (standard) and `::-webkit-scrollbar` (legacy) properties are ignored by default because macOS uses native "overlay" scrollbars. You MUST pair custom colors with `scrollbar-width` (e.g., `thin` or `auto`) to force macOS to render them.
+- Even with `scrollbar-width` applied, macOS overlay scrollbars render the track (gutter) as transparent by default. If the design requires a visible track background color on MacOS, you MUST apply `scrollbar-gutter: stable;` to the scrollable container, but note that it only appears after the user hovers over the scrollbar.
+- Even with `scrollbar-gutter: stable` the track may be transparent on MacOS. The thumb should not depend on the track color to be visible.
+
+## Fallbacks & Browser Support
+
+### Fallbacks & browser support for scrollbar-color
+
+Baseline status for scrollbar-color: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 26.2 (Dec 2025).
+
+This feature is progressive enhancement and does not always require fallbacks.
+
+If the styling is important and the user's Baseline target is "Baseline Widely Available" or earlier, you SHOULD include the non-standard `::-webkit-scrollbar` pseudo-elements as fallbacks.
+
+Wrap legacy fallbacks in an `@supports not (scrollbar-color: auto)` block to prevent conflicts between standard properties and legacy WebKit selectors in browsers that support both natively.
+
+If you are using custom properties to define colors, these will cascade to the legacy WebKit selectors automatically. You do NOT need to duplicate them.
+
+```css
+/* Legacy fallback for WebKit/Blink browsers */
+@supports not (scrollbar-color: auto) {
+  .scroller::-webkit-scrollbar {
+    /* Must define base size in WebKit for custom colors to be visual */
+    width: 12px;
+    height: 12px;
+  }
+
+  .scroller::-webkit-scrollbar-thumb {
+    background: var(--scrollbar-thumb);
+  }
+
+  .scroller::-webkit-scrollbar-track {
+    background: var(--scrollbar-track);
+  }
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/apply-webgl-shaders.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/apply-webgl-shaders.md
new file mode 100644
index 00000000..accc2357
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/apply-webgl-shaders.md
@@ -0,0 +1,278 @@
+# Apply WebGL shaders to HTML content
+
+WebGL shaders provide powerful GPU-accelerated visual effects, enabling advanced capabilities like dynamic ripple distortions, lighting models, color grading, and custom vertex transformations. The HTML-in-Canvas API allows developers to apply WebGL textures to HTML content. This enables applying high-performance fragment and vertex shaders natively to fully interactive UI components, such as buttons, input fields, and rich text, while retaining native accessibility, text selection, and DOM event handling.
+
+## How to implement
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```js
+if ('content' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+> [!NOTE]
+> HTML-in-Canvas is supported from Chrome 157.
+
+2. Add the `content="drawable"` attribute to the `<canvas>` HTML element.
+3. Place your HTML content inside the `<canvas>` element, and add the `drawable` attribute to every element that you draw. An element with `drawable` captures its subtree, except nested descendants that are also `drawable`.
+
+```html
+<canvas id="canvas" content="drawable">
+  <div id="html-content" drawable></div>
+</canvas>
+```
+
+4. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+5. Pre-allocate the texture backing first using the `texImage2D` method. The snippets in this guide use a WebGL 2 context (`canvas.getContext("webgl2")`).
+
+Allocate texture storage first by calling `texImage2D()` with `null` instead of pixel data, which reserves GPU memory of the given size and format without uploading any pixels. Follow these rules:
+  - Size the texture from `canvas.captureElementImage(element)`. Its `width` and `height` are in canvas grid (backing store) pixels, so round them up with `Math.ceil()`. `captureElementImage()` throws if the element has no paint record yet: call `requestPaint()`, and retry on the next `paint` event.
+  - Allocate level 0 only on the first upload, or when the size changes, because reallocating clears the texture. Use mutable storage: immutable `texStorage2D()` storage can't be resized when the element changes size.
+
+```js
+// Returns the element's size in canvas grid pixels, or null if the element
+// has no paint record yet.
+function getElementImageSize(canvas, element) {
+  let elementImage;
+  try {
+    elementImage = canvas.captureElementImage(element);
+  } catch (err) {
+    canvas.requestPaint(); // No paint record yet: retry on the next paint event.
+    return null;
+  }
+  const width = Math.ceil(elementImage.width);
+  const height = Math.ceil(elementImage.height);
+  elementImage.close();
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+
+// Binds the texture, and allocates its storage on the first upload, and when
+// the element size changes. `state` stores the allocated size.
+function allocateElementTexture(gl, texture, state, width, height) {
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  if (state.width === width && state.height === height) return;
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,                // Mipmap level
+    gl.RGBA8,         // Internal format: 8 bits per RGBA channel
+    width,            // Size in canvas grid pixels
+    height,
+    0,                // Border: must be 0
+    gl.RGBA,          // Format and type that match RGBA8
+    gl.UNSIGNED_BYTE,
+    null              // null reserves GPU memory without uploading pixels
+  );
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  state.width = width;
+  state.height = height;
+}
+
+const texture = gl.createTexture();
+const textureState = { width: 0, height: 0 };
+```
+
+6. Render the HTML content to the texture inside a `canvas.onpaint` event handler using the `texElementSubImage2D` method. Follow these rules:
+  - An element can only be uploaded after the canvas has painted it. Upload from the `paint` event, and call `canvas.requestPaint()` to request one.
+  - Pass `{ width, height }` in the config. It makes the copy fill the allocated texture regardless of how the canvas is scaled.
+  - Reallocate the texture if the size changed, as shown in step 5.
+
+```js
+// Uploads the element into the texture. Returns false if the element has no
+// paint record yet. In that case, it's uploaded on the next paint event.
+function uploadElementWebGL(gl, canvas, texture, element, state) {
+  const size = getElementImageSize(canvas, element);
+  if (!size) return false;
+  const { width, height } = size;
+
+  // Bind the texture, and reallocate it if the size changed (step 5).
+  allocateElementTexture(gl, texture, state, width, height);
+  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
+  return true;
+}
+
+canvas.onpaint = () => {
+  try {
+    uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+  } catch (err) {
+    console.error('texElementSubImage2D copy failed:', err);
+  }
+};
+```
+
+  When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. `event.changedElements` lists the elements whose rendering changed. Make sure you only re-upload the texture if there has been an update to the descendant HTML elements:
+
+  ```js
+  function render() {
+    // Request to update the canvas
+    canvas.requestPaint();
+    requestAnimationFrame(render);
+  }
+  requestAnimationFrame(render);
+
+  canvas.onpaint = (event) => {
+    if (event.changedElements && event.changedElements.length > 0) {
+      // Update the texture with uploadElementWebGL()
+    }
+    // Render the scene, and sync the element geometry as shown in step 7
+  };
+  ```
+
+7. Sync the element geometry.
+
+Compute a `DOMMatrix` that maps the element's border box, in CSS pixels, to the canvas, in CSS pixels. The browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+  - Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from -0.5 to 0.5. If you don't normalize, your 200px button will look 200 times larger. This step also flips the Y-axis, because in CSS, down is positive, but in WebGL, up is positive.
+  - Convert the WebGL MVP Matrix to a DOM Matrix.
+  - Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the CSS pixel dimensions of your `<canvas>` element on the screen, and flips the Y-axis back.
+  - Calculate the final transform. Multiply the matrices in order: Viewport * MVP * Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element should sit to align with the 3D drawing. The browser performs the perspective divide.
+
+  ```js
+  // Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a
+  // quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix.
+  function computeCanvasTransform(canvas, element, mvp) {
+    const width = element.offsetWidth;
+    const height = element.offsetHeight;
+
+    // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space)
+    const toGLModel = new DOMMatrix()
+      // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+      .scale(1 / width, -1 / height, 1 / height)
+      // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+      .translate(-width / 2, -height / 2);
+
+    // 2. Convert WebGL MVP Matrix to DOM Matrix
+    const mvpDOM = new DOMMatrix(Array.from(mvp));
+
+    // 3. Map to the canvas viewport, in CSS pixels
+    const clipToCanvasViewport = new DOMMatrix()
+      // Move center (0,0) to center of canvas
+      .translate(canvas.clientWidth / 2, canvas.clientHeight / 2)
+      // Scale normalized clip (-1..1) to viewport size, and flip Y back
+      .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2);
+
+    // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+    return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel);
+  }
+  ```
+
+Then pass the transform to `canvas.updateElementGeometry()` as `canvasTransform`. This moves the HTML element to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element. The browser also uses the transform for the element's accessibility bounds, for example, for screen reader focus rings:
+
+  ```js
+  canvas.updateElementGeometry(targetHTMLElement, {
+    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
+  });
+  ```
+
+Use these options to control hit testing:
+  - Each `updateElementGeometry()` call moves the element to the top of the hit-testing order. Pass `{ preserveHitTestOrder: true }` to keep its position.
+  - Call `canvas.clearElementGeometry(element)` to remove an element from hit testing, for example, when you hide it.
+  - Pass `{ canvasClip }`, a `DOMRectInit` in the coordinate space of `canvasTransform`, to limit the hit-testable area, for example, when only part of the element is drawn.
+
+## Example code
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
+  <div id="ui-element" drawable>
+    <p>WebGL UI Element</p>
+    <button>Action</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const gl = canvas.getContext("webgl2");
+  const uiElement = document.getElementById("ui-element");
+
+  // getElementImageSize() and allocateElementTexture() are defined in step 5.
+  // uploadElementWebGL() is defined in step 6.
+  // computeCanvasTransform() is defined in step 7.
+
+  // Setup WebGL texture...
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  const textureState = { width: 0, height: 0 };
+
+  canvas.onpaint = () => {
+    // 1. Update texture with HTML content
+    try {
+      uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+    } catch (err) {
+      console.error('texElementSubImage2D copy failed:', err);
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position, hit testing, and accessibility bounds with 3D scene
+    canvas.updateElementGeometry(uiElement, {
+      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
+    });
+  };
+</script>
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: Always add the `content="drawable"` attribute to the `<canvas>` element.
+- **MANDATORY**: ALWAYS add the `drawable` attribute to the direct children of the canvas.
+- **MANDATORY**: Add the `drawable` attribute to every element that you want to be able to draw independently from its parent elements.
+- **MANDATORY**: Use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Pre-allocate the texture buffer with `texImage2D()` once (when it's initialized or when the element size changes). Reallocate the texture only when the size changes, and set `TEXTURE_MIN_FILTER` to `LINEAR`.
+- **MANDATORY**: Use the `texElementSubImage2D` method to render the HTML content to a texture that you pre-allocate with `texImage2D()`, sized from `captureElementImage()`.
+- **MANDATORY**: Sync the geometry of the HTML element with the rendered content by calling `canvas.updateElementGeometry(element, { canvasTransform })`.
+- **MANDATORY**: Use `ResizeObserver` to observe the screen size and update the canvas size to match device pixels.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+### Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required.
+
+However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+The fallback strategy depends on the use case. For example, for an interactive HTML content in canvas, if HTML-in-Canvas is not supported, place the HTML content on top of the canvas using CSS.
+
+### HTML-in-Canvas polyfill
+
+Use the following polyfill script to mimic the HTML-in-Canvas API in browsers that do not support it.
+
+1. Install or embed the library:
+
+```
+# Install
+npm install three-html-render
+```
+
+```
+# Embed
+<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
+```
+
+2. Run the `installHtmlInCanvasPolyfill()` method to translate HTML-in-Canvas.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/browser-ui-theming.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/browser-ui-theming.md
new file mode 100644
index 00000000..50f78756
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/browser-ui-theming.md
@@ -0,0 +1,39 @@
+# Theming browser-generated UI
+
+Most browser-generated UI can be customized to some extent using CSS.
+Even if it requires modern features, it degrades gracefully in older browsers, and thus often does not require a polyfill or fallback.
+
+Before re-creating browser UI (form controls, scrollbars, selections, error messages, etc), first verify that:
+1. the browser UI cannot be customized enough for your needs, even with modern CSS,
+2. the desired customization is sufficiently critical to justify the tradeoffs of re-creating built-in UI — most notably losing accessible semantics, keyboard handling, IME, and AT integration that the native UI provides for free.
+
+Example customizations that are possible:
+- Use `::selection` to customize highlighted text colors.
+- **DON'T** apply `user-select: none` to content text — breaks copy-paste, translation tools, and AT "read from here" gestures. Limit it to chrome (drag handles, toolbars, redundant button labels).
+- Use `accent-color` to apply the page's accent color to any browser-generated UI.
+- Use `color-scheme` to have browser UI adapt to light/dark mode.
+- Use `scrollbar-color` to customize scrollbar colors and `scrollbar-width` to control scrollbar thickness — keep the thumb visibly distinct from the track (≥3:1), and don't set `scrollbar-width: none` on scrollable regions (use it only when scrolling is fully replaced by another affordance).
+- Use `:user-invalid` / `:user-valid` for validity styling, **not** `:invalid` / `:valid` — they only match after the user has interacted with the field, avoiding the hostile default of flagging required-empty fields as errors on page load. Exclude range sliders when targeting `input` broadly (e.g., `input:not(input[type="range"]):user-valid`) so adjusting a slider does not apply field validity borders or backgrounds to it.
+- Buttons and text fields (including `<textarea>`) can generally be styled as normal elements.
+- Use `font-size` to scale and other textual properties to control typography
+
+### Styling textual fields (`<input>` & `<textarea>`)
+
+For most styling purposes (e.g. colors, borders, backgrounds, typography, etc) treat these elements as normal text containers.
+
+- Use `:placeholder-shown` and `::placeholder` to style input placeholders.
+- Use `field-sizing: content` to make text fields size to content.
+- For `<textarea>` elements, use `resize: vertical` to disable horizontal resizing or `resize: none` to disable all resizing.
+
+### Multiple choice controls (select, radios, checkboxes)
+
+- To select one among many options presented in a dropdown: Use a `<select>` + `appearance: base-select` + `::picker(select)`. For more info see `branded-select-styling` (via `npx -y modern-web-guidance@latest retrieve "branded-select-styling"`)
+- Selecting one or more among multiple options laid out inline in the page: Use a `<input type=checkbox>` or `<input type=radio>` inside a `<label>` for each option. Style via `label:has(:checked)`.
+- Style checkboxes, radios and switches via `appearance: none` + generated content (`::before`/`::after`) or background images to draw the checked state.
+<!-- Customizable select listbox version currently buggy + this has much better browser support -->
+
+### Non-textual `<input>`s (buttons, sliders, file inputs etc.)
+
+- File inputs: Use `::file-selector-button` to style the button.
+- Do not use `<input>` with a `type` of `button`, `submit` or `reset`. Use `<button>` instead and style it as a regular element.
+- Sliders: Use `appearance: none` + thumb pseudo-elements (`::-webkit-slider-thumb`, `::-moz-range-thumb`, etc) and track pseudo-elements (`::-webkit-slider-runnable-track`, `::-moz-range-track`, etc) for more granular control.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/color.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/color.md
new file mode 100644
index 00000000..dc493c34
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/color.md
@@ -0,0 +1,43 @@
+# Color
+
+## Accessible color
+
+**Don't use color alone to indicate the presence of a user interface component or its state**: Use iconography and/or shape to help differentiate. Do not denote success/errors ONLY with color. Use icons or text.
+
+```html
+<!-- Good: Denotes state without colors alone -->
+<div class="error-msg">
+  <span aria-hidden="true">❌</span>
+  <span>The password entered was invalid.</span>
+</div>
+```
+
+### Contrast
+
+- **Minimum contrast standards**: Maintain 4.5:1 for normal text and 3:1 for large text or icons.
+- **Ensure non-text contrast standards**: Maintain a minimum contrast ratio of 3:1 for user interface component boundaries and states.
+  - This includes visual elements (borders, backgrounds, box-shadows, underlines) that form the boundary or indicate the presence of a UI component (e.g., input field borders).
+  - This also includes visual elements indicating active states within a component (e.g., checkbox checkmarks or switch thumbs).
+  - **Caveat**: Meeting 3:1 non-text contrast can challenge minimalistic designs. Soft gradients or subtle inset/outset shadows can soften visual boundaries while satisfying accessibility requirements.
+- **Use `prefers-contrast` only when warranted**: Reach for `@media (prefers-contrast: more)` when the design uses low-contrast accents (e.g., subtle borders, muted secondary text) that need to be reinforced; most sites that already meet baseline contrast won't need it.
+
+### Light and dark color schemes
+
+- **Support light and dark color schemes**: Honor `@media (prefers-color-scheme: dark)` and pair it with the `color-scheme` CSS property so form controls, scrollbars, and other UA-rendered surfaces match.
+See `dark-mode` (via `npx -y modern-web-guidance@latest retrieve "dark-mode"`) for more details.
+
+### Forced Colors Mode
+
+- **Support Forced Colors Mode**: In Forced Colors Mode (High Contrast on Windows), the browser overrides author colors with system keywords and strips `background-image`, `box-shadow`, and `border-image`. Define system color fallbacks for color tokens using `@media (forced-colors: active)`.
+- **Use `forced-color-adjust: none` only where color is essential information** (syntax highlighter, color picker swatch). **DON'T** use `forced-color-adjust: none` just to preserve aesthetics.
+- **Don't rely on `background-image`, `box-shadow`, or `border-image` to convey borders, separators, or state**: They disappear in forced colors (and often in print too). If you must, ensure there's an alternative in forced colors mode, such as `outline` or `border` with system color keywords (`CanvasText`, `LinkText`, `ButtonText`, `Highlight`, `GrayText`, etc.).
+
+## Generating tints
+
+Before generating tints dynamically, check if you can use an existing, predefined, design token. This allows much more designer control and ensures consistency.
+
+If you need to generate lighter or darker colors dynamically:
+- **DO NOT** just adjust the lightness channel in `oklch`/`oklab` or `lch`/`lab`, e.g. `oklab(from var(--primary) 0.9 a b)`. While that is theoretically the correct way, browsers do not yet implement gamut mapping, so the resulting color is unpredictable.
+- You can use `color-mix()` to mix with white or black (preferably in `oklab`). This keeps the color safely in gamut, but tends to over-desaturate colors and produce washed out tints and shades.
+- You MAY combine lightness adjustment with any of the other methods (e.g. `color-mix(in oklab, oklch(from var(--primary) 0.9 c h), white 30%)`) for a balance between the two, but avoid going above 30% for the lightness adjustment.
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/complex-shapes.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/complex-shapes.md
new file mode 100644
index 00000000..880ba3af
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/complex-shapes.md
@@ -0,0 +1,75 @@
+# Complex Shapes
+
+## Overview
+To clip elements to complex, free-form shapes like brush strokes or organic textures, use CSS Masking (`mask-image`). While `clip-path` is excellent for geometric shapes or vector paths, `mask-image` allows you to use images (like PNGs with transparency) or SVGs to define the visible area of an element. This approach is more expressive because it supports semi-transparency, allowing for soft edges and complex textures that are difficult or impossible to achieve with `clip-path`.
+
+## Implementation
+To implement complex shapes using CSS masks:
+
+### Using transparency from an image
+You can use the transparency of an image as a mask, with opaque parts visible and transparent parts hidden. This can be a PNG, SVG, or other image with transparency, or a generated image, like a CSS gradient.
+
+```css
+.shaped-element {
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: url('mask.svg');
+  -webkit-mask-size: cover; /* Scale mask to cover element */
+  -webkit-mask-repeat: no-repeat; /* Do not tile the mask */
+
+  /* Standard property for modern browsers */
+  mask-image: url('mask.svg');
+  mask-size: cover;
+  mask-repeat: no-repeat;
+}
+```
+
+### Using an SVG element in HTML
+You can also reference a `<mask>` element defined in an inline SVG in your page's HTML. Use `maskContentUnits="objectBoundingBox"` to make the mask scale automatically with the size of the element. This tells the browser to interpret all coordinates inside the mask as fractions from `0` to `1` (like `0.5` for 50%) instead of absolute pixels.
+
+> **Luminance vs. Alpha Masking**: By default, SVG masks use **luminance** (brightness) to determine opacity, where white reveals, black hides, and gray creates semi-transparency. If you want the mask to use the **alpha channel** (transparency) of your SVG shapes instead, you can specify `mask-type: alpha;` in your CSS or `mask-type="alpha"` directly on the SVG `<mask>` element.
+
+```html
+<!-- White areas reveal content, gray creates semi-transparency, black or transparent hides it -->
+<svg width="0" height="0">
+  <defs>
+    <!-- objectBoundingBox scales mask coordinates (0 to 1) with the element's size -->
+    <mask id="custom-shape" maskContentUnits="objectBoundingBox">
+      <!-- Use white shapes to define fully opaque areas -->
+      <circle cx="0.5" cy="0.5" r="0.5" fill="white" />
+      <!-- Use gray shapes to define semi-transparent/faded areas -->
+      <circle cx="0.5" cy="0.5" r="0.25" fill="gray" />
+    </mask>
+  </defs>
+</svg>
+
+<div class="masked-content">
+  <!-- Content to be masked -->
+</div>
+
+<style>
+.masked-content {
+  /* Reference the SVG mask ID */
+  -webkit-mask-image: url(#custom-shape);
+  mask-image: url(#custom-shape);
+}
+</style>
+```
+
+### Fallback strategies
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- The element will not be clipped and will display as a normal rectangle.
+- Ensure the content is still readable and the layout does not break without the mask (progressive enhancement).
+- Optionally, use feature detection to provide a simpler fallback shape with `clip-path`.
+
+```css
+/* Fallback for browsers that do not support masking */
+@supports (not (mask-image: url(x))) and (not (-webkit-mask-image: url(x))) {
+  .shaped-element {
+    /* Use a simple rounded rectangle as fallback */
+    clip-path: inset(5% round 15px);
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/contrast-color.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/contrast-color.md
new file mode 100644
index 00000000..687e2d45
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/contrast-color.md
@@ -0,0 +1,187 @@
+# Ensure text readability with dynamic background colors
+
+When building reusable UI components (like badges or buttons) or supporting dynamic themes, ensuring text is readable against an unpredictable background color can be challenging. The `contrast-color()` CSS function resolves to `black` or `white`, maximizing the contrast ratio against the specified background color.
+
+## Determine optimal text color
+
+When an element has a variable or dynamically injected background color, you can rely on the browser to compute the safest text color.
+
+MANDATORY: Set the `color` property using the `contrast-color()` function, passing the background color (or its custom property) as the argument.
+
+```css
+.badge {
+  /* Define the background color as a custom property */
+  --badge-bg: #e02424;
+  background-color: var(--badge-bg);
+  /* MANDATORY: Dynamic contrasting color */
+  color: contrast-color(var(--badge-bg));
+}
+```
+
+DO NOT: Use `contrast-color()` for `background-color`. It is specifically designed for foreground colors (like text or borders) to contrast against a given background color.
+
+## Integrate with theming
+
+Because `contrast-color()` accepts any valid `<color>` value, including CSS custom properties, it is especially powerful within design systems. By centralizing your background themes as variables, you ensure that foreground content automatically updates its contrast whenever the theme shifts, even to user-specified colors.
+
+DO: Reference shared background variables inside `contrast-color()` to guarantee synchronization across your application.
+
+```css
+.theme-card {
+  background-color: var(--theme-surface-color);
+  color: contrast-color(var(--theme-surface-color));
+}
+
+.theme-container[data-theme="light"] {
+  --theme-surface-color: #f4f4f4;
+}
+.theme-container[data-theme="dark"] {
+  --theme-surface-color: #1a1a1a;
+}
+.theme-container[data-theme="custom"] {
+  --theme-surface-color: var(--user-custom-theme);
+}
+```
+
+DO NOT: Hard-code a separate text color for each interaction state when the background is dynamic. Doing so reintroduces the very mismatch `contrast-color()` exists to prevent.
+
+## Fallback strategies
+
+Baseline status for contrast-color(): Newly available. It's been Baseline since 2026-04-10.
+Supported by: Chrome 147 (Apr 2026), Edge 147 (Apr 2026), Firefox 146 (Dec 2025), and Safari 26 (Sep 2025).
+
+To support browsers without `contrast-color()`, you must provide a fallback. If the background color is known and fixed, use a hard-coded contrasting color. For dynamic backgrounds where the color is unknown, choose a strategy from the table below based on your UI requirements and browser support targets.
+
+| Strategy | Best For... | Considerations |
+| :--- | :--- | :--- |
+| **Relative Color Syntax** | Automated, high-quality CSS-only contrast calculation. | Highest quality CSS-only fallback. |
+| **Text Shadow** | Quick readability boost on any background. | Can look "dirty" or "glowy"; may not fit all designs. |
+| **Text Stroke** | Preserving font weight while ensuring edge contrast. | Use `paint-order` to avoid thinning letterforms, if available. |
+| **Translucent Overlay** | Ensuring a minimum contrast area behind the text. | Changes the look of the background color under the text, requires a separate text element. |
+| **SVG Filters** | Reactive contrast that updates as the background changes. | Requires a separate text element; hacky implementation. |
+
+### Recommended: Relative Color Syntax (RCS)
+
+For browsers that support it, RCS provides the most robust automated fallback for dynamic colors.
+
+Baseline status for Relative colors: Newly available. It's been Baseline since 2024-09-16.
+Supported by: Chrome 125 (May 2024), Edge 125 (May 2024), Firefox 128 (Jul 2024), and Safari 18 (Sep 2024).
+
+```css
+@supports (color: oklch(from red l c h)) {
+  .badge {
+    /* Highest threshold that passes WCAG. Higher values may be more legible. */
+    --threshold: 0.623;
+    --l: max(0, sign(var(--threshold) - l));
+    color: oklch(from var(--badge-bg) var(--l) 0 h);
+  }
+}
+
+@supports (color: contrast-color(red)) {
+  .badge {
+    color: contrast-color(var(--badge-bg));
+  }
+}
+```
+
+### Alternative CSS Fallbacks
+
+DO: Select the fallback that best matches your design constraints if RCS is not sufficient or supported.
+
+#### Option 1: Text Stroke
+
+Baseline status for Text stroke and fill  (compatibility prefixes): Widely available. It's been Baseline since 2017-04-05.
+Supported by: Chrome 4 (Jan 2010), Edge 15 (Apr 2017), Firefox 49 (Sep 2016), Safari 3 (Oct 2007), and Safari iOS 2 (Jul 2008).
+
+```css
+.badge--stroke {
+  -webkit-text-stroke: 4px black;
+}
+```
+  
+#### Option 2: Text Stroke with `paint-order` to preserve letterforms
+
+Baseline status for paint-order: Widely available. It's been Baseline since 2024-03-22.
+Supported by: Chrome 123 (Mar 2024), Edge 123 (Mar 2024), Firefox ≤66, and Safari ≤12.
+
+```css
+.badge--stroke {
+  -webkit-text-stroke: 4px black;
+  paint-order: stroke fill;
+}
+```
+
+#### Option 3: Translucent background overlay
+
+```css
+.badge--overlay {
+  position: relative;
+  color: #fff;
+  overflow: hidden;
+}
+.badge--overlay::before {
+  content: "";
+  position: absolute;
+  inset: 0;
+  background-color: rgb(0 0 0 / 0.4);
+  z-index: 0;
+}
+.badge--overlay span {
+  position: relative;
+  z-index: 1;
+}
+```
+
+#### Option 4: Text Shadow
+
+```css
+.badge--shadow {
+  text-shadow: 0 1px 3px rgb(0 0 0 / 0.8);
+}
+```
+
+#### Option 5: SVG Filters
+
+Baseline status for SVG filters: Widely available. It's been Baseline since 2015-07-29.
+Supported by: Chrome 5 (May 2010), Edge 12 (Jul 2015), Firefox 3 (Jun 2008), and Safari 6 (Jul 2012).
+
+1. Load this SVG filter definition. It must be added directly to the HTML document if you need to support Safari versions affected by [this WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=320118), which prevents external and data url references for filters. Otherwise, it should be loaded from an external file, either an SVG file or inlined in CSS.
+
+```html
+<!-- Technique from https://miunau.com/posts/dynamic-text-contrast-in-css/ -->
+<svg xmlns="http://www.w3.org/2000/svg" version="1.1" height="0" style="display: none;">
+  <defs>
+    <filter id="contrast-filter" color-interpolation-filters="sRGB">
+      <feColorMatrix type="matrix"
+        values="0.2126 0.7152 0.0722 0 0
+          0.2126 0.7152 0.0722 0 0
+          0.2126 0.7152 0.0722 0 0
+          0 0 0 1 0"/>
+      <feMorphology operator="dilate" radius="2"/>
+      <feComponentTransfer>
+        <feFuncR type="linear" slope="-255" intercept="128"/>
+        <feFuncG type="linear" slope="-255" intercept="128"/>
+        <feFuncB type="linear" slope="-255" intercept="128"/>
+      </feComponentTransfer>
+      <feComposite operator="in" in2="SourceGraphic"/>
+    </filter>
+  </defs>
+</svg>
+```
+
+2. Wrap the text in a `<span>`.
+
+```html
+<div class="badge--svg">
+  <span>Badge content</span>
+</div>
+```
+
+3. Apply the filter to the `<span>`.
+
+```css
+.badge--svg span{
+  color: var(--badge-bg);
+  filter: url(#contrast-filter);
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/custom-text-decorations.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/custom-text-decorations.md
new file mode 100644
index 00000000..f255eb73
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/custom-text-decorations.md
@@ -0,0 +1,337 @@
+# Custom text decorations
+
+Use the native `text-decoration` properties to style underlines, overlines, and strikethroughs, instead of faking them with borders, background gradients, or pseudo-elements. A native decoration follows the text across wrapped lines, tracks the font's metrics, skips glyph descenders, and inherits through nested elements, so none of that needs to be reimplemented. Reach for the box-based techniques at the end of this guide only when the decoration must outline or wrap the text rather than run along it.
+
+Text decorations apply to any text, not only links. Where underlined text is not a link, make sure it cannot be mistaken for one. When decorating a link, use a real `<a href>` pointing at the destination (add `target="_blank" rel="noopener"` to open a new tab), not `href="javascript:void(0)"` with a script handler. A real link keeps middle-click, copy-link, and screen reader behavior.
+
+## Style the line
+
+Set line, style, color, and thickness with the `text-decoration` shorthand, and the gap from the text with `text-underline-offset`. Wrap the selector in `:where()` so the defaults have zero specificity and any later override wins, without needing custom properties.
+
+```css
+:where(.decorated) {
+  /* Thickness is relative to the font size (0.08em is an example value), so the line is not too heavy
+     on small text or too light on large text, and max() keeps it at least 1px so it never disappears. */
+  text-decoration: underline solid currentColor max(1px, 0.08em);
+  /* Use em so the gap scales with the font size. 0.2em clears most descenders; example value. */
+  text-underline-offset: 0.2em;
+}
+
+/* Example hover state: a softer line that firms up on hover and focus. The 50% mix and
+   0.12em thickness are example values. */
+:where(.decorated) {
+  text-decoration-color: color-mix(in srgb, currentColor, transparent);
+}
+
+:where(.decorated:is(:hover, :focus-visible)) {
+  text-decoration-color: currentColor;
+  text-decoration-thickness: max(1px, 0.12em);
+}
+
+/* Other lines are a different text-decoration-line on the same properties */
+.decorated-over    { text-decoration-line: overline; }
+.decorated-through { text-decoration-line: line-through; }
+```
+
+`text-decoration-style` accepts `solid`, `double`, `dotted`, `dashed`, and `wavy`. `text-underline-offset` applies to underlines only.
+
+Starting points for the design:
+
+* **Thickness:** about `0.06em` to `0.1em` for body text. Go thicker (`0.1em` to `0.15em`) for headings and emphasized states.
+* **Offset:** about `0.15em` to `0.25em`. Dotted and wavy lines need a little more room than solid ones, so raise the offset for them.
+* **Color:** `currentColor` keeps the line matched to the text. A softer mix of the text color that firms up on hover keeps long runs of links calm.
+* **Style:** `solid` for links, `dotted` for terms and abbreviations, and `wavy` for annotations such as errors.
+
+## Control where the line is skipped
+
+### Ink skipping
+
+By default, underlines and overlines break around glyph parts that cross them, such as descenders. Set `text-decoration-skip-ink` to choose the behavior:
+
+```css
+.decorated {
+  /* auto: skip ink for most scripts (default). none: draw straight through.
+     all: also skip ink in scripts where auto does not, such as Japanese or Chinese. */
+  text-decoration-skip-ink: all;
+}
+```
+
+* Keep `auto` for Latin text, and do not declare it: it is the default.
+* Use `all` when the underline sits close enough to the baseline to cross ideographic glyphs, or when mixed-script text must look consistent.
+* Use `none` for a very thick line, or a deliberately decorative one, where gaps would look like breaks.
+
+
+#### Skip spaces
+
+`text-decoration-skip-spaces` decides whether the line is drawn under spaces. The default, `start end`, leaves leading and trailing spaces undecorated.
+
+```css
+.decorated {
+  /* Spaces collapse by default, so there is nothing to skip. Preserve them when the
+     leading or trailing spaces are meaningful, such as padded input values. */
+  white-space: pre;
+  /* none: decorate every space. all: skip every space, so each word is underlined separately.
+     start | end | start end: skip only leading, trailing, or both. */
+  text-decoration-skip-spaces: all;
+}
+```
+
+Do not declare `text-decoration-skip-spaces` unless the decoration should visibly cover padding (`none`) or break between every word (`all`). Ordinary inline text, such as the text of a link, has no leading or trailing spaces, so the declaration does nothing.
+
+## Trim or extend the line with an inset
+
+`text-decoration-inset` moves the start and end of the line. A positive value pulls an end inward, a negative value pushes it outward. One value moves both ends; two values set start and end separately. Percentages refer to the inline size of the decorated box.
+
+```css
+/* Small insets soften the ends of the line; larger ones read as a deliberately short line.
+   Both values are examples. */
+.trimmed  { text-decoration-inset: var(--deco-inset, 0.1em); }
+.extended { text-decoration-inset: calc(var(--deco-inset, 0.1em) * -1); }
+```
+
+To reveal an underline on hover without a border or background gradient, trim the end by 100% and transition it back to 0:
+
+```css
+.reveal {
+  text-decoration: underline; /* Always visible, including for reduced motion */
+}
+
+/* Only hide and animate the line when the user has not asked for reduced motion. */
+@media (prefers-reduced-motion: no-preference) {
+  .reveal {
+    /* Trim the end by the full inline size so the line starts with zero length. */
+    text-decoration-inset: 0 100%;
+    /* 150ms to 300ms feels responsive without lagging; ease-out starts quickly. Example values. */
+    transition: text-decoration-inset var(--reveal-duration, 0.25s) ease-out;
+  }
+
+  /* Include :focus-visible so keyboard users get the same reveal as pointer users. */
+  .reveal:is(:hover, :focus-visible) {
+    text-decoration-inset: 0 0;
+  }
+}
+```
+
+## Draw a custom line with a pseudo-element
+
+Use a pseudo-element when the line must be a shape `text-decoration` cannot draw, such as a squiggle, and reveal it by clipping. No extra markup is needed, so the link stays a plain `<a>`.
+
+```html
+<a class="draw" href="#">Hover to draw underline</a>
+```
+
+```css
+.draw {
+  position: relative;
+  display: inline-block;
+  color: inherit;
+  text-decoration: none;
+  padding-block-end: 0.4em; /* Space for the line below the text; example value */
+}
+
+.draw::after {
+  content: "";
+  position: absolute;
+  inset: auto 0 0 0;
+  block-size: 0.4em; /* Height of the squiggle; example value */
+  pointer-events: none;
+  border: var(--deco-thickness, max(1px, 0.08em)) solid var(--deco-color, currentColor);
+  /* A single shape strokes along its path, using the border width as the stroke. Example squiggle. */
+  border-shape: shape(from 0% 50%,
+    curve to 20% 50% with 5% 0% / 15% 100%,
+    smooth to 40% 50% with 35% 100%,
+    smooth to 60% 50% with 55% 100%,
+    smooth to 80% 50% with 75% 100%,
+    smooth to 100% 50% with 95% 100%);
+}
+
+/* Only hide and animate the line when the user has not asked for reduced motion;
+   otherwise it stays fully drawn. */
+@media (prefers-reduced-motion: no-preference) {
+  .draw::after {
+    /* Clip the line away from the right edge. The negative block insets keep the stroke
+       from being cut off vertically. */
+    clip-path: inset(-1em 100% -1em 0);
+    /* A slightly slower draw than a hover reveal reads as drawing; example duration. */
+    transition: clip-path var(--draw-duration, 0.6s) ease-out;
+  }
+
+  .draw:is(:hover, :focus-visible)::after {
+    clip-path: inset(-1em 0 -1em 0); /* Fully drawn */
+  }
+}
+```
+
+For a freeform path or a draw-on that follows the stroke, see `line-drawing-animation` (via `npx -y modern-web-guidance@latest retrieve "line-drawing-animation"`).
+
+## Outline text with a box instead
+
+Two box properties decorate text by outlining it rather than running a line along it. Give the text padding so the outline does not touch it.
+
+```css
+/* Gradient outline with a see-through middle */
+.ring {
+  padding: 0.2em 0.75em; /* Example values: enough room that the outline does not touch the text */
+  /* The border width is the visible outline thickness. Relative to the font size, with a 2px
+     minimum so it stays visible on small text; example value. */
+  border: var(--ring-width, max(2px, 0.12em)) solid transparent;
+  background: linear-gradient(135deg, var(--ring-start, #2563eb), var(--ring-end, #db2777)) border-box;
+  /* Paint the background only under the border, so the inside stays transparent. */
+  background-clip: border-area;
+}
+
+/* Border that follows a shape that border-radius cannot draw, such as a tag with a pointed end */
+.tag {
+  padding: 0.2em 1.5em 0.2em 0.9em; /* Example values: extra room at the point so the text is not clipped */
+  border: var(--shape-stroke, max(2px, 0.08em)) solid var(--shape-color, currentColor); /* Example stroke width */
+  /* A single shape strokes along its path. Two shapes fill the area between them.
+     This polygon is an example; use shape() for curves. */
+  border-shape: polygon(0 0, 85% 0, 100% 50%, 85% 100%, 0 100%);
+}
+```
+
+`border-shape` replaces only the border. The background is still the rectangular box, so do not rely on it to fill a shape.
+
+When only the corners need a different shape, such as a beveled, scooped, or notched label, use `corner-shape` with `border-radius` instead. It keeps the background and border following the corners, and unsupported browsers fall back to ordinary rounded corners.
+
+```css
+.label {
+  padding: 0.2em 0.9em; /* Example values */
+  border: var(--shape-stroke, max(2px, 0.08em)) solid var(--shape-color, currentColor);
+  border-radius: 0.6em; /* Corner size; example value */
+  corner-shape: bevel; /* round (default) | scoop | bevel | notch | square | squircle */
+}
+```
+
+## Choose a technique
+
+* **`text-decoration`** (line, ink skipping, spaces, inset): the line should run along the text, wrap with it, and follow its font metrics. This is the default choice.
+* **Pseudo-element with `border-shape` and `clip-path`**: the line is a custom shape or needs a draw-on animation. Choose it only when `text-decoration-style` cannot produce the look, because it needs extra positioning. For vector path animations, see `line-drawing-animation` (via `npx -y modern-web-guidance@latest retrieve "line-drawing-animation"`).
+* **`background-clip: border-area`**: the text needs a gradient outline. Use plain `border-color` when a solid outline is enough. For complete gradient border styling, see `gradient-borders` (via `npx -y modern-web-guidance@latest retrieve "gradient-borders"`).
+* **`corner-shape`**: only the corners need a different shape, such as beveled, scooped, or notched. Pair it with `border-radius`, which sets the corner size.
+* **`border-shape`**: the outline needs a shape `border-radius` cannot draw, such as a tag or arrow. Use `border-radius` when rounded corners are enough. For shaped element styling, see `element-shape` (via `npx -y modern-web-guidance@latest retrieve "element-shape"`).
+* **Inset hover reveal**: worth adding when a link needs a hover affordance beyond a color change. Skip it for text that is not interactive.
+
+## Fallback Strategies
+
+Each fallback keeps the text readable and keeps the core decoration. Frame the need in terms of your Baseline target: if it includes browsers without a property, apply the matching fallback.
+
+### Ink skipping `all`
+
+Baseline status for text-decoration-skip-ink: all: Newly available. It's been Baseline since 2026-05-07.
+Supported by: Chrome 148 (May 2026), Edge 148 (May 2026), Firefox 75 (Apr 2020), and Safari 15.4 (Mar 2022).
+
+If your Baseline target does not support `text-decoration-skip-ink: all`, the declaration is ignored and the browser keeps `auto`. Latin descenders are still skipped; only scripts that `auto` does not cover, such as Japanese, lose ink skipping. This is graceful degradation, so no extra code is needed.
+
+### Skip spaces
+
+If your Baseline target does not support `text-decoration-skip-spaces`, the browser uses its own default handling of spaces. This is graceful degradation: the line is drawn under spaces the browser does not skip.
+
+### Inset
+
+If your Baseline target does not support `text-decoration-inset`, the
+declaration is ignored, so the link keeps its normal, fully visible underline
+and the transition has nothing to animate. This is graceful degradation: the
+hover reveal is lost and the link stays underlined.
+
+### Border area
+
+Browser support for background-clip: border-area: Limited availability.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+If your Baseline target does not support `background-clip: border-area`, the declaration is ignored and the background paints under the whole border box, filling the text instead of only its outline. Do NOT settle for a plain solid border when the gradient is part of the design. Reproduce the gradient instead, and apply `background-clip: border-area` only inside `@supports`.
+
+Use an opaque layer when the element's background is a known flat color. Paint the surface color over the padding box and the gradient under the border box, so the gradient shows only through the transparent border:
+
+```css
+.ring {
+  border: var(--ring-width, max(2px, 0.12em)) solid transparent; /* Example width */
+  /* Fallback: an opaque surface layer hides the gradient inside the border. */
+  background:
+    linear-gradient(var(--surface, canvas) 0 100%) padding-box,
+    linear-gradient(135deg, var(--ring-start, #2563eb), var(--ring-end, #db2777)) border-box;
+}
+
+@supports (background-clip: border-area) {
+  .ring {
+    background: linear-gradient(135deg, var(--ring-start, #2563eb), var(--ring-end, #db2777)) border-box;
+    background-clip: border-area; /* The inside stays transparent */
+  }
+}
+```
+
+Use a masked pseudo-element when the inside must stay transparent. The pseudo-element carries the gradient, and a mask cuts out everything but its padding ring:
+
+```css
+@supports not (background-clip: border-area) {
+  .ring {
+    position: relative;
+    border-color: transparent;
+  }
+
+  .ring::before {
+    content: "";
+    position: absolute;
+    inset: calc(var(--ring-width, max(2px, 0.12em)) * -1); /* Cover the border box */
+    padding: var(--ring-width, max(2px, 0.12em)); /* Ring thickness */
+    border-radius: inherit;
+    background: linear-gradient(135deg, var(--ring-start, #2563eb), var(--ring-end, #db2777));
+    /* Keep only the area between the content box and the border box. */
+    mask: linear-gradient(#000 0 0) content-box, linear-gradient(#000 0 0);
+    mask-composite: exclude;
+    pointer-events: none;
+  }
+}
+```
+
+### Border shape
+
+Browser support for border-shape: Limited availability.
+Supported by: Chrome 147 (Apr 2026) and Edge 147 (Apr 2026).
+Unsupported in: Firefox and Safari.
+
+If your Baseline target does not support `border-shape`, the declaration is ignored and the element keeps its rectangular border. A rounded rectangle is only an acceptable fallback when the shape is purely decorative. When the shape carries meaning, such as a tag, arrow, or callout, reproduce it as closely as possible, and apply `border-shape` only inside `@supports`.
+
+Draw the outline with a clipped pseudo-element. Keep a transparent border so the box is the same size as in the supported case, fill the pseudo-element with the outline color, and cut it into a ring with an `evenodd` `clip-path`: the outer shape, then the same shape inset by the stroke width.
+
+```css
+.tag {
+  --stroke: max(2px, 0.08em); /* Example stroke width */
+  position: relative;
+  padding: 0.2em 1.5em 0.2em 0.9em; /* Example values */
+  border: var(--stroke) solid transparent;
+}
+
+@supports not (border-shape: circle(50%)) {
+  .tag::before {
+    content: "";
+    position: absolute;
+    inset: calc(var(--stroke) * -1); /* Cover the border box */
+    background: var(--shape-color, currentColor);
+    pointer-events: none;
+    /* Outer shape, then the inner shape inset by the stroke. The inner points are approximate on
+       diagonal edges, so the stroke looks slightly thinner there. */
+    clip-path: polygon(evenodd,
+      0 0, 85% 0, 100% 50%, 85% 100%, 0 100%,
+      var(--stroke) var(--stroke),
+      calc(85% - var(--stroke)) var(--stroke),
+      calc(100% - var(--stroke) * 2) 50%,
+      calc(85% - var(--stroke)) calc(100% - var(--stroke)),
+      var(--stroke) calc(100% - var(--stroke)));
+  }
+}
+
+@supports (border-shape: circle(50%)) {
+  .tag {
+    border-color: var(--shape-color, currentColor);
+    border-shape: polygon(0 0, 85% 0, 100% 50%, 85% 100%, 0 100%);
+  }
+}
+```
+
+For a filled shape rather than an outline, put `clip-path: polygon(...)` with the same points directly on the element.
+
+For the pseudo-element underline, draw a straight line with `border-block-end` on `.draw::after`, and apply the `block-size`, `border`, and `border-shape` squiggle only inside `@supports (border-shape: circle(50%))`. The line is straight but still draws on, because the `clip-path` animation does not depend on the shape.
+
+`clip-path` also clips focus rings and `box-shadow`. Do not rely on an outline on the clipped element to show focus; style `:focus-visible` with a color or background change instead.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/customize-scrollbar-color-and-thickness.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/customize-scrollbar-color-and-thickness.md
new file mode 100644
index 00000000..0d9ae8b3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/customize-scrollbar-color-and-thickness.md
@@ -0,0 +1,59 @@
+# Customize the color or thickness of a scrollbar
+
+You can customize the appearance of scrollbars using the standard CSS properties `scrollbar-color` and `scrollbar-width`.
+
+*   **`scrollbar-color`**: Accepts two `<color>` values. The first applies to the thumb (the moving part), and the second to the track (the fixed background).
+*   **`scrollbar-width`**: Accepts `auto` (default), `thin` (a thinner variant), or `none` (hides the scrollbar completely while maintaining scrollability).
+
+## Apply `scrollbar-color` and `scrollbar-width`
+
+MANDATORY: Use `scrollbar-color` and `scrollbar-width` on the scrollable container.
+
+When using `scrollbar-color`, use CSS variables to keep thumb and track colors separate, for readability and maintainability (especially when using fallbacks).
+
+```css
+.scroller {
+  --scrollbar-thumb: var(--color-neutral-70);
+  --scrollbar-track: var(--color-neutral-90);
+
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+}
+```
+
+## Fallback strategies
+
+Baseline status for scrollbar-width: Newly available. It's been Baseline since 2024-12-11.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 18.2 (Dec 2024).
+
+### Fallbacks & browser support for scrollbar-color
+
+Baseline status for scrollbar-color: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 26.2 (Dec 2025).
+
+This feature is progressive enhancement and does not always require fallbacks.
+
+If the styling is important and the user's Baseline target is "Baseline Widely Available" or earlier, you SHOULD include the non-standard `::-webkit-scrollbar` pseudo-elements as fallbacks.
+
+Wrap legacy fallbacks in an `@supports not (scrollbar-color: auto)` block to prevent conflicts between standard properties and legacy WebKit selectors in browsers that support both natively.
+
+If you are using custom properties to define colors, these will cascade to the legacy WebKit selectors automatically. You do NOT need to duplicate them.
+
+```css
+/* Legacy fallback for WebKit/Blink browsers */
+@supports not (scrollbar-color: auto) {
+  .scroller::-webkit-scrollbar {
+    /* Must define base size in WebKit for custom colors to be visual */
+    width: 12px;
+    height: 12px;
+  }
+
+  .scroller::-webkit-scrollbar-thumb {
+    background: var(--scrollbar-thumb);
+  }
+
+  .scroller::-webkit-scrollbar-track {
+    background: var(--scrollbar-track);
+  }
+}
+```
+
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/dark-mode.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/dark-mode.md
new file mode 100644
index 00000000..dc40bac7
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/dark-mode.md
@@ -0,0 +1,339 @@
+# Dark mode
+
+The `color-scheme` property indicates which color schemes (such as light or dark) your page supports. This informs the browser that it can automatically theme native UI elements—like scrollbars, form controls, and the default canvas background—to match your site's design and help minimize white flashes during initial loading.
+
+## Implementation
+
+### 1. Declare supported schemes in HTML
+
+MANDATORY: To help prevent a "flash of un-themed content" (FOUC), place a `<meta>` tag in your `<head>` to ensure the browser knows which themes you support before it even starts rendering. While this `<meta>` tag helps to avoid FOUC by setting the initial canvas color early, it may not completely eliminate flashes in all browsers or loading conditions.
+
+```html
+<!-- MANDATORY: Declare support for both light and dark themes -->
+<meta name="color-scheme" content="light dark">
+```
+
+### 2. Apply page-wide color scheme to CSS :root or html
+
+MANDATORY: Apply the `color-scheme` property to the `html` element or the `:root` pseudo-class. Browsers specifically look to the root element to determine the theme for the entire viewport—including the root scrollbars and the initial "canvas" background. If applied only to the `body`, these global UI surfaces may remain in light mode because the `body` does not control the window's rendering context.
+
+```css
+/* MANDATORY: Apply color-scheme to :root or html for viewport-wide theming */
+:root {
+  /* MANDATORY: Automatically adapt native UI to user system preferences */
+  color-scheme: light dark;
+}
+```
+
+### 3. Define light and dark color tokens
+
+You can use the `light-dark()` function to define color tokens that automatically adapt to different `color-scheme` values.
+
+It is recommended that you also keep the raw color values in separate custom properties, which makes it easier to combine them in different ways (and makes fallback behavior easier, if needed).
+
+For more control over the colors of built-in UI such as `accent-color` or `scrollbar-color`, authors **can optionally** add their own dynamic colors with use of custom properties and/or the `light-dark()` function. This function automatically picks the correct color based on the computed `color-scheme` of the element and eliminates the need for redundant media queries, but is not required for a basic implementation.
+
+```css
+:root {
+  --color-brand-light: oklch(45% 0.23 270);
+  --color-brand-dark: oklch(85% 0.15 210);
+  --color-brand-text-light: white;
+  --color-brand-text-dark: oklch(40% 0.23 270);
+
+  --color-brand: light-dark(var(--color-brand-light), var(--color-brand-dark));
+  --color-brand-text: light-dark(var(--color-brand-text-light), var(--color-brand-text-dark));
+
+  /* MANDATORY: Automatically adapt native UI to user system preferences */
+  color-scheme: light dark;
+}
+
+button.primary {
+  /* These automatically adapt to color scheme */
+  background-color: var(--color-brand);
+  color: var(--color-brand-text);
+}
+```
+
+OPTIONAL: A number of system colors are available, which also automatically adapt to the used color scheme (and other color modes, e.g. forced colors), such as `canvas`, `canvastext`, `accentcolor` (check support) , `buttonborder` etc. These are typically too limited to be useful, beyond very specific cases where you need to exactly match certain default browser UI or as fallbacks/defaults.
+
+#### OPTIONAL: Tailor color pairs to context
+
+Even when overriding the system default, it can be useful to use the `prefers-color-scheme` media query to define **different** color pairs that take into account the colors of the browser and OS chrome around the page (or of the surrounding page, when the page is used as an iframe).
+
+For example, use a slightly dimmer light theme when the system setting is `dark`, or a more contrasting dark theme when the system setting is `light`, so the page is not visually overpowered by the surrounding UI.
+
+
+## Fine-grained browser UI customization
+
+Setting `color-scheme` already adapts browser UI to the used color scheme, but this will use OS defaults and/or system colors that may not perfectly align with the website design.
+Modern browsers expose several fine-grained customization hooks for these.
+Do not reimplement native controls simply to customize their appearance without exhausting the customization hooks modern browsers provide.
+
+### Setting the accent color
+
+Some browser UI (e.g. checked checkboxes or sliders) uses an accent color.
+This resolves to the OS setting by default, but you can use the `accent-color` property to set it to a color that better aligns with the page, such as the page's brand color.
+
+```css
+html {
+  accent-color: light-dark(var(--color-accent-light), var(--color-accent-dark));
+}
+```
+
+### Issues to be aware of when using accent-color
+
+Browser rendering of `accent-color` varies.
+For indicators generally painted over an accent color background, such as checkbox marks and radio-button dots, browsers may apply different treatments:
+- **Chromium** and **Firefox** generally select a contrasting indicator color.
+- **Safari** may instead preserve a white indicator in light mode or a black indicator in dark mode, while modifying the accent color behind it. This adjustment does not always provide sufficient contrast for every supplied color, so test important combinations in Safari, including both light and dark color schemes. Do not assume that Safari will automatically choose whichever indicator color provides the best contrast.
+
+### Scrollbar colors
+
+You can use `scrollbar-color` together with `light-dark()` to set custom scrollbar colors that adapt to the color scheme used.
+
+```css
+:root {
+  --color-scrollbar-track: light-dark(#eee, #222);
+  --color-scrollbar-thumb: light-dark(#999, #666);
+  scrollbar-color: var(--color-scrollbar-thumb) var(--color-scrollbar-track);
+}
+```
+
+### Issues to be aware of when using scrollbar-color
+
+- Do NOT animate or transition `scrollbar-color`. A [WebKit bug](https://bugs.webkit.org/show_bug.cgi?id=311752) causes the scrollbar to flicker every time `scrollbar-color` changes.
+- On macOS, `scrollbar-color` (standard) and `::-webkit-scrollbar` (legacy) properties are ignored by default because macOS uses native "overlay" scrollbars. You MUST pair custom colors with `scrollbar-width` (e.g., `thin` or `auto`) to force macOS to render them.
+- Even with `scrollbar-width` applied, macOS overlay scrollbars render the track (gutter) as transparent by default. If the design requires a visible track background color on MacOS, you MUST apply `scrollbar-gutter: stable;` to the scrollable container, but note that it only appears after the user hovers over the scrollbar.
+- Even with `scrollbar-gutter: stable` the track may be transparent on MacOS. The thumb should not depend on the track color to be visible.
+
+### Further customization
+
+Most browser UI exposes pseudo-elements to fully customize its appearance, such as:
+- `::placeholder`
+- `::spelling-error`
+- `::grammar-error`
+- `::selection`
+- `::search-text`
+- `::target-text`
+- `::file-selector-button`
+
+You can use `light-dark()` colors on any of these to apply colors that adapt to the used color scheme.
+
+## 4. Varying images for light and dark mode
+
+For CSS images, `light-dark()` can also be used to provide different image values.
+
+IMPORTANT: Both values in `light-dark()` must be the same type. You cannot combine a color with an image.
+If one of the two must be an image, use `image(<color>)` to wrap the color value.
+
+## JS-based theme detection
+
+Most color scheme branching should be done in CSS, which automatically adapts to changes.
+
+Any JS reading `matchMedia("(prefers-color-scheme: dark)").matches` MUST also handle its `change` event as the system preference can change at any time.
+
+## OPTIONAL: Implementing a color-scheme toggle
+
+If you want to allow users to manually override their system default for this site, you can implement a dark mode toggle.
+Most sites do not need a persistent toggle in the site UI.
+Simply defaulting to the system color scheme is usually enough, optionally with a setting in a separate settings surface.
+See `dark-mode-toggle` (via `npx -y modern-web-guidance@latest retrieve "dark-mode-toggle"`) for best practices around implementing a dark mode toggle (persistent or not).
+
+## OPTIONAL: Component-specific overrides
+
+You can override the global theme for specific elements by setting `color-scheme` on them.
+
+For more information and gotchas, see `component-specific-light-dark-theme` (via `npx -y modern-web-guidance@latest retrieve "component-specific-light-dark-theme"`).
+
+## Known issues to be aware of
+
+### Issues to be aware of when using color-scheme
+
+- Chrome and Firefox respect `color-scheme` for iframes: they render embedded pages in the correct color scheme and adjust the embedded page's `prefers-color-scheme` media query to reflect the embedding context's `color-scheme`. Safari does not, and resolves `prefers-color-scheme` to the system setting even inside iframes.
+  - **If you control both parent and iframe:** pass the parent's color scheme to the iframe explicitly — via a URL parameter (`?theme=dark`) at iframe construction time, or via `postMessage()` (which also lets you react to runtime changes). In the iframe, set a class on `<html>` (and/or `color-scheme` on `:root`) from that signal instead of relying on `prefers-color-scheme`.
+  - **If you only control the embedded page:** there is no reliable way to detect the embedding context's `color-scheme` from inside the iframe in Safari. Expose an explicit theme parameter on your embed API (e.g. a query string or `postMessage` protocol) and document it for embedders.
+
+## Fallback strategies
+
+### Fallbacks & browser support for color-scheme
+
+Baseline status for color-scheme: Widely available. It's been Baseline since 2022-02-03.
+Supported by: Chrome 98 (Feb 2022), Edge 98 (Feb 2022), Firefox 96 (Jan 2022), and Safari 13 (Sep 2019).
+
+The `color-scheme` property is **progressive enhancement**.
+Browsers that do not support it will ignore this property and use their default light-mode UI.
+
+To adapt to the user's preferences in older browsers, use `prefers-color-scheme` media queries to provide different colors when dark mode is preferred.
+
+- DO use the media query to switch custom properties on `:root` or `html`
+- Avoid using the media query on individual components unless the component requires a very specific type of dark mode customization beyond colors.
+
+```css
+:root {
+  /* Define brand colors for each mode */
+  --color-brand-light: #0056b3;
+  --color-brand-dark: #00e5ff;
+  --color-brand: var(--color-brand-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --color-brand: var(--color-brand-dark);
+  }
+
+  /* Ignored in older browsers */
+  color-scheme: light dark;
+}
+
+button.primary {
+	background-color: var(--color-brand);
+}
+```
+
+### Fallbacks & browser support for light-dark()
+
+Baseline status for light-dark(): Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 123 (Mar 2024), Edge 123 (Mar 2024), Firefox 120 (Nov 2023), and Safari 17.5 (May 2024).
+
+For browsers that support `color-scheme` but not yet `light-dark()`, light and dark versions of colors should first be defined as custom properties, and the `prefers-color-scheme` media query should be used to set colors for the respective mode like in the example below:
+
+```css
+:root {
+  /* Define browser UI accent color for each mode */
+  --brand-accent-light: #0056b3;
+  --brand-accent-dark: #00e5ff;
+  --accent-color: var(--brand-accent-light);
+
+  /* MANDATORY: Fallback for browsers without light-dark support */
+  @media (prefers-color-scheme: dark) {
+    --accent-color: var(--brand-accent-dark);
+  }
+
+  /* OPTIONAL: use light-dark() for more control of built-in UI colors */
+  @supports (color: light-dark(white, black)) {
+    --accent-color: light-dark(var(--brand-accent-light), var(--brand-accent-dark));
+  }
+
+  /* MANDATORY: Automatically adapt native UI to user system preferences */
+  color-scheme: light dark;
+
+  /* Example inherited color property */
+  accent-color: var(--accent-color);
+}
+
+pre, code {
+  color-scheme: dark;
+
+  /* **Mandatory**: any inherited color properties must be set again, even if to the same design tokens */
+  accent-color: var(--accent-color);
+}
+```
+
+### Fallbacks & browser support for light-dark() image values
+
+Baseline status for light-dark() image values: Newly available. It's been Baseline since 2026-09-14.
+Supported by: Chrome 150 (Jun 2026), Edge 150 (Jul 2026), Firefox 150 (Apr 2026), and Safari 27 (Sep 2026).
+
+For browsers that do not support `light-dark()` for images, use `image-set()` as a switch:
+give each option a `type()` from a custom property, and set the inactive one to an unsupported MIME type so the browser discards that option.
+The active option gets an empty value, so it is a plain `image-set()` option with no `type()`.
+
+Define the switch once on `:root`. Every use site then only needs both images inline, like `light-dark()`.
+
+```css
+:root {
+  --light-type: ;
+  --dark-type: type("image/do-not-use");
+
+  /* MANDATORY: Fallback for browsers without light-dark() image support */
+  @media (prefers-color-scheme: dark) {
+    --light-type: type("image/do-not-use");
+    --dark-type: ;
+  }
+}
+
+.hero {
+  background-image: image-set(url(hero-light.png) var(--light-type), url(hero-dark.png) var(--dark-type));
+
+  @supports (background-image: light-dark(url("a"), url("b"))) {
+    background-image: light-dark(url(hero-light.png), url(hero-dark.png));
+  }
+}
+```
+
+- Only the selected image is downloaded.
+- Resolutions still work: `image-set(url(a-1x.png) 1x var(--light-type), url(a-2x.png) 2x var(--light-type), url(b-1x.png) 1x var(--dark-type), url(b-2x.png) 2x var(--dark-type))`.
+- **DO NOT** use `type("")` for the active option. Browsers treat the empty string as unsupported and drop every option.
+- Unlike `light-dark()`, the switch does not follow `color-scheme` set on a subtree. A manual toggle, or any subtree that sets `color-scheme`, MUST also flip `--light-type` and `--dark-type`.
+
+### Alternative: one custom property per image
+
+Simpler when only a handful of images vary, but every image needs its own media query branch, and a manual toggle must flip each one.
+
+```css
+:root {
+  --hero-image: url(hero-light.png);
+
+  @media (prefers-color-scheme: dark) {
+    --hero-image: url(hero-dark.png);
+  }
+
+  @supports (background-image: light-dark(url("a"), url("b"))) {
+    --hero-image: light-dark(url(hero-light.png), url(hero-dark.png));
+  }
+}
+
+.hero {
+  background-image: var(--hero-image);
+}
+```
+
+### Fallbacks & browser support for image()
+
+image() is not natively supported by any major browser yet.
+
+Use a gradient with a single color stop and no positions, e.g. `linear-gradient(blue)`.
+
+Baseline status for the css.types.gradient.linear-gradient.single_color_stop capability: Newly available. It's been Baseline since 2025-04-04.
+Supported by: Chrome 135 (Apr 2025), Edge 135 (Apr 2025), Firefox 136 (Mar 2025), and Safari 18.4 (Mar 2025).
+
+For broader browser support, you can explicitly provide `0 100%` positions for the single color stop, e.g. `linear-gradient(blue 0 100%)`.
+
+### Fallbacks & browser support for scrollbar-color
+
+Baseline status for scrollbar-color: Newly available. It's been Baseline since 2025-12-12.
+Supported by: Chrome 121 (Jan 2024), Edge 121 (Jan 2024), Firefox 64 (Dec 2018), and Safari 26.2 (Dec 2025).
+
+This feature is progressive enhancement and does not always require fallbacks.
+
+If the styling is important and the user's Baseline target is "Baseline Widely Available" or earlier, you SHOULD include the non-standard `::-webkit-scrollbar` pseudo-elements as fallbacks.
+
+Wrap legacy fallbacks in an `@supports not (scrollbar-color: auto)` block to prevent conflicts between standard properties and legacy WebKit selectors in browsers that support both natively.
+
+If you are using custom properties to define colors, these will cascade to the legacy WebKit selectors automatically. You do NOT need to duplicate them.
+
+```css
+/* Legacy fallback for WebKit/Blink browsers */
+@supports not (scrollbar-color: auto) {
+  .scroller::-webkit-scrollbar {
+    /* Must define base size in WebKit for custom colors to be visual */
+    width: 12px;
+    height: 12px;
+  }
+
+  .scroller::-webkit-scrollbar-thumb {
+    background: var(--scrollbar-thumb);
+  }
+
+  .scroller::-webkit-scrollbar-track {
+    background: var(--scrollbar-track);
+  }
+}
+```
+
+### Fallbacks & browser support for accent-color
+
+Browser support for accent-color: Limited availability.
+Supported by: Chrome 93 (Aug 2021), Edge 93 (Sep 2021), Firefox 92 (Sep 2021), and Safari 26.2 (Dec 2025).
+
+The `accent-color` property is progressive enhancement.
+Browsers that do not support this property will ignore it and use their default UI colors.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/equal-width-text-lines.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/equal-width-text-lines.md
new file mode 100644
index 00000000..99733d13
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/equal-width-text-lines.md
@@ -0,0 +1,97 @@
+# Equal-Width Text Lines
+
+Poster-style lockups where each line is scaled so it spans the container's full width can create visually striking headings.
+Using `text-fit`, the browser scales each line during layout, so it stays correct on resize, copy changes, and font load.
+
+For a single line filling its container (e.g. a heading or pull quote), see `fit-text-to-container` (via `npx -y modern-web-guidance@latest retrieve "fit-text-to-container"`) instead.
+
+## Basic implementation
+
+Note: Line breaks in a lockup are either **forced** (each line is its own block) or **free** (the browser wraps). This is a continuum: a lockup can be all forced, all free, or a mix.
+
+For forced lines:
+- Wrap each line in a `<span>` with `display: block`.
+- Apply `white-space: nowrap` to each forced line `<span>`.
+
+Implementation guidelines:
+- Use `text-fit: grow per-line-all <percentage>` on the heading itself.
+- Use `per-line-all`, not `per-line`. `per-line` skips the last line and any line ending in a forced break, so with one block per line it scales nothing.
+- `grow` cannot be combined with `shrink`. Either set the base `font-size` to a maximum or a minimum depending on what would be a better fallback or easier to calculate, and set `text-fit` to `shrink` or `grow` accordingly. If you don’t have a reason to use `shrink`, prefer `grow` + setting `font-size` to a minimum, as it's safer for most cases.
+- Always limit growth or shrinkage with the percentage (e.g. `300%`) as a guardrail.
+- The container needs a definite inline size. `text-fit` never changes intrinsic size, so it does nothing on `fit-content`/`max-content` widths or content-sized flex/grid items.
+- Trim the leading above the first and below the last line: see `precise-text-alignment` (via `npx -y modern-web-guidance@latest retrieve "precise-text-alignment"`).
+- Keep `line-height` small, `1` or under, otherwise gaps between lines of different font-sizes become unwieldy.
+- IMPORTANT: Note that computed `font-size` is unchanged, so `em` spacing does not scale.
+- To avoid accidental over-emphasized orphans, apply `text-wrap: balance` or `text-wrap: pretty` if there are free lines.
+
+
+### Spacing
+
+If all lines are forced, this produces more control over spacing:
+- Apply `text-box: trim-both cap alphabetic` to each line block so its box hugs its own glyphs. It trims using the scaled metrics. See `precise-text-alignment` (via `npx -y modern-web-guidance@latest retrieve "precise-text-alignment"`) for more details.
+- Space lines using Flexbox or Grid + `gap` on the heading, not `line-height`. Gaps are then uniform instead of growing with each line's font-size.
+
+If some lines are free, do not use `text-box`: it only trims the first and last line, so the outer lines would hug the glyphs while interior gaps keep their leading. Let `line-height` govern all spacing.
+
+## Visual design
+
+- Lockups look best when there is significant variance in font sizes between lines. Avoid creating lockups from text with mostly uniform lines, as it will result in font sizes that are neither the same, nor sufficiently different, violating the design principle of _contrast_. You can ensure this by forcing short lines: wrap the words to emphasize in a block and let the rest wrap, i.e. a mixed lockup. This is especially important when combining with `text-wrap: balance`.
+- Prefer combining this with `text-transform: uppercase` when used with Western scripts, as ascenders and descenders tend to create trapped space and/or overlap adjacent lines, which creates a less aesthetically pleasing result.
+- When forcing short lines, pick words that would enhance the message if emphasized.
+- **Limitation:** Growing text will also increase in visual weight and its strokes will be perceived as stronger. There is currently no way to counterbalance this e.g. by reducing `font-weight` for larger text, since there is no unit to use in a calculation, since the scaling does not affect font-relative units like `em`.
+
+## Fallback strategies
+
+### For `text-box`
+
+Browser support for text-box: Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+`text-box` needs no separate fallback: keep the small `line-height` on fixed lockups too. It is a no-op under `text-box` and keeps gaps tight where it is unsupported, at the cost of gaps that scale with each line's font-size.
+
+### For `text-wrap: balance`
+
+Baseline status for text-wrap: balance: Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 121 (Dec 2023), and Safari 17.5 (May 2024).
+
+### For `text-fit`
+
+Browser support for text-fit: Limited availability.
+Supported by: Chrome 150 (Jun 2026) and Edge 150 (Jul 2026).
+Unsupported in: Firefox and Safari.
+
+Forced lines have a short, faithful fallback: measure each line at its base size and scale it by the ratio to the container, with the same cap.
+
+```css
+@supports not (text-fit: grow) {
+  .lockup > span {
+    /* Shrink-wrap each line so its width is the text width */
+    width: fit-content;
+    /* --text-fit-scale is measured by the script; the cap mirrors the text-fit percentage */
+    font-size: min(var(--text-fit-scale, 1) * 1em, 300%);
+  }
+}
+```
+
+```js
+if (!CSS.supports('text-fit', 'grow per-line-all')) {
+  const fit = lockup => {
+    const lines = [...lockup.querySelectorAll(':scope > span')];
+    // Unscale first: on a refit, offsetWidth would otherwise include the previous scale
+    for (const line of lines) line.style.removeProperty('--text-fit-scale');
+    // MANDATORY: all reads, then all writes. Interleaving them (e.g. reading
+    // lockup.clientWidth inside the write loop) forces one reflow per line.
+    const scales = lines.map(line => lockup.clientWidth / line.offsetWidth);
+    lines.forEach((line, i) => line.style.setProperty('--text-fit-scale', scales[i]));
+  };
+  // Refit on resize and font load
+  for (const lockup of document.querySelectorAll('.lockup')) {
+    new ResizeObserver(() => fit(lockup)).observe(lockup);
+  }
+}
+```
+
+Free lines have no faithful fallback (line breaks are unknown until layout): progressive enhancement to a balanced heading with a fluid base size such as `clamp(2rem, 1rem + 5cqi, 5rem)`. In a mixed lockup the script above still fits the forced lines; a wrapping block measures as wide as the container, so it keeps scale 1 and only gets the fluid base size.
+
+If text fitting is critical, consider using a JS library (e.g. `fitty`), conditionally loaded only if `text-fit` is not supported.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/export-html-media-from-canvas.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/export-html-media-from-canvas.md
new file mode 100644
index 00000000..20fdaf41
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/export-html-media-from-canvas.md
@@ -0,0 +1,327 @@
+# Export HTML content from canvas
+
+Web applications frequently need to capture and export rich HTML content—such as customized dashboards, styled documents, or interactive charts—as static images or video recordings. Historically, achieving this required bulky third-party libraries that manually parse DOM nodes and CSS properties to reconstruct a visual facsimile on a canvas. This approach is computationally expensive, error-prone, and frequently fails to support modern CSS layout features. With the HTML-in-Canvas API, developers can render real DOM elements directly into the canvas context. Because the browser's native rendering engine paints the HTML subtree with pixel-perfect accuracy, capturing the exact visual output as an image or video stream is highly efficient using built-in canvas methods like `toDataURL()`, `toBlob()`, or `captureStream()`.
+
+## How to implement
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```js
+if ('content' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+> [!NOTE]
+> HTML-in-Canvas is supported from Chrome 157.
+
+2. Initialize the canvas to support rendering of descendant HTML elements by adding the `content="drawable"` attribute to the `<canvas>` HTML element. Place your HTML content inside the `<canvas>` element, and add the `drawable` attribute to every element that you draw. An element with `drawable` captures its subtree, except nested descendants that are also `drawable`:
+
+```html
+<canvas id="canvas" content="drawable">
+  <div id="html-content" drawable></div>
+</canvas>
+```
+
+3. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+4. Render the HTML content to the canvas inside a `canvas.onpaint` event handler. 
+- In 2D context, use the `drawElementImage` method. It draws the last snapshot of a `drawable` element, and its drawable subtree (excluding other drawable children), starting at the element's border box, before CSS transforms:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  ctx.drawElementImage(form_element, 0, 0);
+};
+```
+
+- In WebGL and WebGPU contexts, you copy the element into a texture. Size the texture from `canvas.captureElementImage(element)`. Its `width` and `height` are in canvas grid (backing store) pixels, so round them up with `Math.ceil()`. `captureElementImage()` throws if the element has no paint record yet: call `requestPaint()`, and retry on the next `paint` event.
+
+```js
+// Returns the element's size in canvas grid pixels, or null if the element
+// has no paint record yet.
+function getElementImageSize(canvas, element) {
+  let elementImage;
+  try {
+    elementImage = canvas.captureElementImage(element);
+  } catch (err) {
+    canvas.requestPaint(); // No paint record yet: retry on the next paint event.
+    return null;
+  }
+  const width = Math.ceil(elementImage.width);
+  const height = Math.ceil(elementImage.height);
+  elementImage.close();
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+```
+
+- In WebGL context, pre-allocate the texture backing first using the `texImage2D` method. The snippets in this guide use a WebGL 2 context (`canvas.getContext("webgl2")`). Allocate texture storage by calling `texImage2D()` with `null` instead of pixel data, which reserves GPU memory of the given size and format without uploading any pixels. Follow these rules:
+  - Size the texture from `captureElementImage()`, as shown above.
+  - Allocate level 0 only on the first upload, or when the size changes, because reallocating clears the texture. Use mutable storage: immutable `texStorage2D()` storage can't be resized when the element changes size.
+
+```js
+// Binds the texture, and allocates its storage on the first upload, and when
+// the element size changes. `state` stores the allocated size.
+function allocateElementTexture(gl, texture, state, width, height) {
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  if (state.width === width && state.height === height) return;
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,                // Mipmap level
+    gl.RGBA8,         // Internal format: 8 bits per RGBA channel
+    width,            // Size in canvas grid pixels
+    height,
+    0,                // Border: must be 0
+    gl.RGBA,          // Format and type that match RGBA8
+    gl.UNSIGNED_BYTE,
+    null              // null reserves GPU memory without uploading pixels
+  );
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  state.width = width;
+  state.height = height;
+}
+
+const texture = gl.createTexture();
+const textureState = { width: 0, height: 0 };
+```
+
+- Then, in WebGL context, render the HTML content to the texture using the `texElementSubImage2D` method. Follow these rules:
+  - Pass `{ width, height }` in the config. It makes the copy fill the allocated texture regardless of how the canvas is scaled.
+  - Reallocate the texture if the size changed, as shown above.
+
+```js
+// Uploads the element into the texture. Returns false if the element has no
+// paint record yet. In that case, it's uploaded on the next paint event.
+function uploadElementWebGL(gl, canvas, texture, element, state) {
+  const size = getElementImageSize(canvas, element);
+  if (!size) return false;
+  const { width, height } = size;
+
+  // Bind the texture, and reallocate it if the size changed (see above).
+  allocateElementTexture(gl, texture, state, width, height);
+  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
+  return true;
+}
+
+canvas.onpaint = () => {
+  try {
+    uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+  } catch (err) {
+    console.error('texElementSubImage2D copy failed:', err);
+  }
+};
+```
+
+- In WebGPU context, use the `drawElementImageToTexture` method. Follow these rules:
+  - Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and add `TEXTURE_BINDING` to sample it in shaders. A wrong usage is reported as a WebGPU validation error, not as an exception.
+  - Pass the texture size as `size`. Without `size`, a larger element is clipped to the texture. With `size`, the element is scaled to fill it.
+  - Recreate the texture when the element size changes, and rebuild the bind groups that reference it.
+
+```js
+// Create the texture once, and recreate it
+// when the element size changes.
+function ensureElementTexture(device, state, width, height) {
+  if (state.texture?.width === width && state.texture?.height === height) {
+    return state.texture;
+  }
+  state.texture?.destroy();
+  state.texture = device.createTexture({
+    size: { width, height },
+    format: "rgba8unorm",
+    usage:
+      GPUTextureUsage.TEXTURE_BINDING |
+      GPUTextureUsage.COPY_DST |
+      GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+  return state.texture; // Recreate the bind groups that used the previous texture.
+}
+
+const textureState = { texture: null };
+
+canvas.onpaint = () => {
+  const size = getElementImageSize(canvas, uiElement);
+  if (!size) return;
+  const previousTexture = textureState.texture;
+  const texture = ensureElementTexture(device, textureState, size.width, size.height);
+  if (texture !== previousTexture) {
+    // New texture: create, or rebuild, the bind groups that reference it.
+  }
+  try {
+    device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
+  } catch (err) {
+    console.error('drawElementImageToTexture copy failed:', err);
+  }
+};
+```
+
+When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. `event.changedElements` lists the elements whose rendering changed. Make sure you only redraw the element, or re-upload its texture, if there has been an update to the descendant HTML elements:
+
+  ```js
+  function render() {
+    // Request to update the canvas
+    canvas.requestPaint();
+    requestAnimationFrame(render);
+  }
+  requestAnimationFrame(render);
+
+  canvas.onpaint = (event) => {
+    if (event.changedElements && event.changedElements.length > 0) {
+      // Redraw the element, or update its texture, as shown above
+    }
+    // In WebGL and WebGPU, render the scene, and sync the element geometry as shown in step 5
+  };
+  ```
+
+5. Sync the element geometry.
+
+The browser needs to know where the HTML element is drawn, so that its DOM position matches its drawn pixels, for example, so that users can click and type into it. A canvas only hit tests the elements that are drawn with the 2D `drawElementImage()` method, or registered with `updateElementGeometry()`.
+
+- For the 2D context case, the browser syncs the element automatically. `drawElementImage()` aligns the DOM hit-test bounds and screen reader focus rings with the drawn coordinates, so you don't need to set `style.transform`. To manage the geometry manually, for example, when you draw the same element more than once, pass `{ preserveElementGeometry: true }` to `drawElementImage()`, and apply transforms with `canvas.updateElementGeometry()`.
+
+- For the 3D case with WebGL or WebGPU, the canvas can't tell where the HTML element is drawn, so you have to tell it. Compute a `DOMMatrix` that maps the element's border box, in CSS pixels, to the canvas, in CSS pixels. The browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+  - Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from -0.5 to 0.5. If you don't normalize, your 200px button will look 200 times larger. This step also flips the Y-axis, because in CSS, down is positive, but in WebGL, up is positive.
+  - Convert the WebGL MVP Matrix to a DOM Matrix.
+  - Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the CSS pixel dimensions of your `<canvas>` element on the screen, and flips the Y-axis back.
+  - Calculate the final transform. Multiply the matrices in order: Viewport * MVP * Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element should sit to align with the 3D drawing. The browser performs the perspective divide.
+
+  ```js
+  // Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a
+  // quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix.
+  function computeCanvasTransform(canvas, element, mvp) {
+    const width = element.offsetWidth;
+    const height = element.offsetHeight;
+
+    // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space)
+    const toGLModel = new DOMMatrix()
+      // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+      .scale(1 / width, -1 / height, 1 / height)
+      // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+      .translate(-width / 2, -height / 2);
+
+    // 2. Convert WebGL MVP Matrix to DOM Matrix
+    const mvpDOM = new DOMMatrix(Array.from(mvp));
+
+    // 3. Map to the canvas viewport, in CSS pixels
+    const clipToCanvasViewport = new DOMMatrix()
+      // Move center (0,0) to center of canvas
+      .translate(canvas.clientWidth / 2, canvas.clientHeight / 2)
+      // Scale normalized clip (-1..1) to viewport size, and flip Y back
+      .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2);
+
+    // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+    return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel);
+  }
+  ```
+
+Then pass the transform to `canvas.updateElementGeometry()` as `canvasTransform`. This moves the HTML element to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element. The browser also uses the transform for the element's accessibility bounds, for example, for screen reader focus rings:
+
+  ```js
+  canvas.updateElementGeometry(targetHTMLElement, {
+    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
+  });
+  ```
+
+Use these options to control hit testing:
+  - Each `updateElementGeometry()` call moves the element to the top of the hit-testing order. Pass `{ preserveHitTestOrder: true }` to keep its position.
+  - Call `canvas.clearElementGeometry(element)` to remove an element from hit testing, for example, when you hide it.
+
+6. Use regular canvas export methods like `toDataURL()`, `toBlob()`, or `captureStream()`. The exported data will include the rendered HTML content.
+
+## Example code
+
+```html
+<body>
+    <canvas id="canvas" style="width: 400px; height: 200px;" content="drawable">
+        <input id="element" drawable>
+    </canvas>
+    
+    <button id="download">Download Image</button>
+
+    <script>
+        const canvas = document.getElementById('canvas');
+        const ctx = canvas.getContext('2d');
+        const element = document.getElementById('element');
+        const download = document.getElementById('download');
+
+        canvas.onpaint = (event) => {
+            ctx.reset();
+            // Draw the element into the canvas. The browser synchronizes its
+            // DOM position for hit testing (typing).
+            ctx.drawElementImage(element, 10, 10);
+        };
+
+        download.onclick = () => {
+            // Export the canvas content as an image
+            const dataURL = canvas.toDataURL('image/png');
+            const link = document.createElement('a');
+            link.download = 'exported-canvas.png';
+            link.href = dataURL;
+            link.click();
+        };
+
+        // Re-initialize canvas size on screen resize
+        const observer = new ResizeObserver(([entry]) => {
+            const dpc = entry.devicePixelContentBoxSize;
+            canvas.width = dpc ? dpc[0].inlineSize : Math.round(entry.contentRect.width * window.devicePixelRatio);
+            canvas.height = dpc ? dpc[0].blockSize : Math.round(entry.contentRect.height * window.devicePixelRatio);
+            canvas.requestPaint();
+        });
+        const supportsDevicePixelContentBox = 
+            typeof ResizeObserverEntry !== 'undefined' && 
+            'devicePixelContentBoxSize' in ResizeObserverEntry.prototype;
+        const options = supportsDevicePixelContentBox ? { box: 'device-pixel-content-box' } : {};
+        observer.observe(canvas, options);
+    </script>
+</body>
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: Always add the `content="drawable"` attribute to the `<canvas>` element.
+- **MANDATORY**: Add the `drawable` attribute to every element that you draw, including direct children of the canvas.
+- **MANDATORY**: Use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Use the `drawElementImage` method in 2D, or `drawElementImageToTexture` in WebGPU, to render the HTML content to the canvas.
+- **MANDATORY**: In WebGL, pre-allocate the texture buffer with `texImage2D()` once (when it's initialized or when the element size changes). Reallocate the texture only when the size changes, and set `TEXTURE_MIN_FILTER` to `LINEAR`.
+- **MANDATORY**: In WebGL, use the `texElementSubImage2D` method to render the HTML content to a texture that you pre-allocate with `texImage2D()`, sized from `captureElementImage()`.
+- **MANDATORY**: In WebGPU, size the texture from `captureElementImage()`, and recreate it only when the size changes. Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and pass the texture size as `size`.
+- **MANDATORY**: Sync the geometry of the HTML element with the rendered content. In 2D, `drawElementImage` does it automatically. In WebGL and WebGPU, call `canvas.updateElementGeometry(element, { canvasTransform })`.
+- **MANDATORY**: Use `ResizeObserver` to observe the screen size and update the canvas size to match device pixels.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+## Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required. However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+For the use case where HTML content needs to be exported from a canvas, use libraries like `html2canvas`, `dom-to-image`, or `snapdom`. 
+
+To capture HTML interactions frame by frame, for example, for streaming, capture DOM mutations using libraries like `rrweb`. 
+
+Alternatively, implement a warning that HTML media export is not supported in the browser because it doesn't support HTML-in-Canvas.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/expose-canvas-content-to-browser-features.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/expose-canvas-content-to-browser-features.md
new file mode 100644
index 00000000..85699759
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/expose-canvas-content-to-browser-features.md
@@ -0,0 +1,433 @@
+# Expose canvas content to browser features
+
+Regular `<canvas>` content is not exposed to browser features such as screen readers, indexing, translation tools, accessibility assistive tools, find-in-page, print, etc. With `HTML in canvas`, you can render real DOM directly in a canvas element. Adding the `content="drawable"` attribute to a `<canvas>` HTML element lays out its descendant HTML elements, and the `drawable` attribute marks the elements that you can render within the canvas's rendering context. You can use it to style and lay out text in a canvas, expose canvas content to browser features (like accessibility, translation, or find-in-page), and apply 2D and 3D effects to HTML.
+
+## How to implement
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```js
+if ('content' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+> [!NOTE]
+> HTML-in-Canvas is supported from Chrome 157.
+
+2. Add the `content="drawable"` attribute to the `<canvas>` HTML element.
+3. Place your HTML content inside the `<canvas>` element, and add the `drawable` attribute to every element that you draw. An element with `drawable` captures its subtree, except nested descendants that are also `drawable`.
+
+```html
+<canvas id="canvas" content="drawable">
+  <div id="html-content" drawable></div>
+</canvas>
+```
+
+4. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+5. Render the HTML content to the canvas inside a `canvas.onpaint` event handler. An element can only be drawn after the canvas has painted it: call `canvas.requestPaint()` to request a `paint` event.
+
+- In 2D context, use the `drawElementImage` method. It draws the last snapshot of a `drawable` element, and its drawable subtree, starting at the element's border box, before CSS transforms:
+
+```js
+canvas.onpaint = () => {
+  ctx.reset();
+  // Draw the form element at x:0, y:0
+  ctx.drawElementImage(form_element, 0, 0);
+};
+```
+
+- In WebGL and WebGPU contexts, you copy the element into a texture. Size the texture from `canvas.captureElementImage(element)`. Its `width` and `height` are in canvas grid (backing store) pixels, so round them up with `Math.ceil()`. `captureElementImage()` throws if the element has no paint record yet: call `requestPaint()`, and retry on the next `paint` event.
+
+```js
+// Returns the element's size in canvas grid pixels, or null if the element
+// has no paint record yet.
+function getElementImageSize(canvas, element) {
+  let elementImage;
+  try {
+    elementImage = canvas.captureElementImage(element);
+  } catch (err) {
+    canvas.requestPaint(); // No paint record yet: retry on the next paint event.
+    return null;
+  }
+  const width = Math.ceil(elementImage.width);
+  const height = Math.ceil(elementImage.height);
+  elementImage.close();
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+```
+
+- In WebGL context, pre-allocate the texture backing first using the `texImage2D` method. The snippets in this guide use a WebGL 2 context (`canvas.getContext("webgl2")`). Allocate texture storage by calling `texImage2D()` with `null` instead of pixel data, which reserves GPU memory of the given size and format without uploading any pixels. Follow these rules:
+  - Size the texture from `captureElementImage()`, as shown above.
+  - Allocate level 0 only on the first upload, or when the size changes, because reallocating clears the texture. Use mutable storage: immutable `texStorage2D()` storage can't be resized when the element changes size.
+
+```js
+// Binds the texture, and allocates its storage on the first upload, and when
+// the element size changes. `state` stores the allocated size.
+function allocateElementTexture(gl, texture, state, width, height) {
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  if (state.width === width && state.height === height) return;
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,                // Mipmap level
+    gl.RGBA8,         // Internal format: 8 bits per RGBA channel
+    width,            // Size in canvas grid pixels
+    height,
+    0,                // Border: must be 0
+    gl.RGBA,          // Format and type that match RGBA8
+    gl.UNSIGNED_BYTE,
+    null              // null reserves GPU memory without uploading pixels
+  );
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  state.width = width;
+  state.height = height;
+}
+
+const texture = gl.createTexture();
+const textureState = { width: 0, height: 0 };
+```
+
+- Then, in WebGL context, render the HTML content to the texture using the `texElementSubImage2D` method. Follow these rules:
+  - Pass `{ width, height }` in the config. It makes the copy fill the allocated texture regardless of how the canvas is scaled.
+  - Reallocate the texture if the size changed, as shown above.
+
+```js
+// Uploads the element into the texture. Returns false if the element has no
+// paint record yet. In that case, it's uploaded on the next paint event.
+function uploadElementWebGL(gl, canvas, texture, element, state) {
+  const size = getElementImageSize(canvas, element);
+  if (!size) return false;
+  const { width, height } = size;
+
+  // Bind the texture, and reallocate it if the size changed (see above).
+  allocateElementTexture(gl, texture, state, width, height);
+  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
+  return true;
+}
+
+canvas.onpaint = () => {
+  try {
+    uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+  } catch (err) {
+    console.error('texElementSubImage2D copy failed:', err);
+  }
+};
+```
+
+- In WebGPU context, use the `drawElementImageToTexture` method. Follow these rules:
+  - Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and add `TEXTURE_BINDING` to sample it in shaders. A wrong usage is reported as a WebGPU validation error, not as an exception.
+  - Pass the texture size as `size`. Without `size`, a larger element is clipped to the texture. With `size`, the element is scaled to fill it.
+  - WebGPU textures can't be resized. Recreate the texture when the element size changes, and rebuild the bind groups that reference it.
+
+```js
+// WebGPU textures can't be resized. Create the texture once, and recreate it
+// when the element size changes.
+function ensureElementTexture(device, state, width, height) {
+  if (state.texture?.width === width && state.texture?.height === height) {
+    return state.texture;
+  }
+  state.texture?.destroy();
+  state.texture = device.createTexture({
+    size: { width, height },
+    format: "rgba8unorm",
+    usage:
+      GPUTextureUsage.TEXTURE_BINDING |
+      GPUTextureUsage.COPY_DST |
+      GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+  return state.texture; // Recreate the bind groups that used the previous texture.
+}
+
+const textureState = { texture: null };
+
+canvas.onpaint = () => {
+  const size = getElementImageSize(canvas, uiElement);
+  if (!size) return;
+  const previousTexture = textureState.texture;
+  const texture = ensureElementTexture(device, textureState, size.width, size.height);
+  if (texture !== previousTexture) {
+    // New texture: create, or rebuild, the bind groups that reference it.
+  }
+  try {
+    device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
+  } catch (err) {
+    console.error('drawElementImageToTexture copy failed:', err);
+  }
+};
+```
+
+When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. `event.changedElements` lists the elements whose rendering changed. Make sure you only redraw the element, or re-upload its texture, if there has been an update to the descendant HTML elements:
+
+```js
+function render() {
+  // Request to update the canvas
+  canvas.requestPaint();
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+
+canvas.onpaint = (event) => {
+  if (event.changedElements && event.changedElements.length > 0) {
+    // Redraw the element, or update its texture, as shown above
+  }
+  // In WebGL and WebGPU, render the scene, and sync the element geometry as shown in step 6
+};
+```
+
+6. Sync the element geometry.
+
+The browser needs to know where the HTML element is drawn, so that its DOM position matches its drawn pixels. Hit testing, for example, for clicks and text selection, and accessibility use this geometry: a `drawable` element whose geometry isn't updated is still exposed to the accessibility tree, but without geometry information. A canvas only hit tests the elements that are drawn with the 2D `drawElementImage()` method, or registered with `updateElementGeometry()`.
+
+- For the 2D context case, the browser syncs the element automatically. `drawElementImage()` aligns the DOM hit-test bounds and screen reader focus rings with the drawn coordinates, so you don't need to set `style.transform`. To manage the geometry manually, for example, when you draw the same element more than once, pass `{ preserveElementGeometry: true }` to `drawElementImage()`, and apply transforms with `canvas.updateElementGeometry()`.
+
+- For the 3D case with WebGL or WebGPU, the canvas can't tell where the HTML element is drawn, so you have to tell it. Compute a `DOMMatrix` that maps the element's border box, in CSS pixels, to the canvas, in CSS pixels. The browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+  - Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from -0.5 to 0.5. If you don't normalize, your 200px button will look 200 times larger. This step also flips the Y-axis, because in CSS, down is positive, but in WebGL, up is positive.
+  - Convert the WebGL MVP Matrix to a DOM Matrix.
+  - Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the CSS pixel dimensions of your `<canvas>` element on the screen, and flips the Y-axis back.
+  - Calculate the final transform. Multiply the matrices in order: Viewport * MVP * Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element should sit to align with the 3D drawing. The browser performs the perspective divide.
+
+  ```js
+  // Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a
+  // quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix.
+  function computeCanvasTransform(canvas, element, mvp) {
+    const width = element.offsetWidth;
+    const height = element.offsetHeight;
+
+    // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space)
+    const toGLModel = new DOMMatrix()
+      // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+      .scale(1 / width, -1 / height, 1 / height)
+      // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+      .translate(-width / 2, -height / 2);
+
+    // 2. Convert WebGL MVP Matrix to DOM Matrix
+    const mvpDOM = new DOMMatrix(Array.from(mvp));
+
+    // 3. Map to the canvas viewport, in CSS pixels
+    const clipToCanvasViewport = new DOMMatrix()
+      // Move center (0,0) to center of canvas
+      .translate(canvas.clientWidth / 2, canvas.clientHeight / 2)
+      // Scale normalized clip (-1..1) to viewport size, and flip Y back
+      .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2);
+
+    // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+    return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel);
+  }
+  ```
+
+Then pass the transform to `canvas.updateElementGeometry()` as `canvasTransform`. This moves the HTML element to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element. The browser also uses the transform for the element's accessibility bounds, for example, for screen reader focus rings:
+
+  ```js
+  canvas.updateElementGeometry(targetHTMLElement, {
+    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
+  });
+  ```
+
+Use these options to control hit testing:
+  - Each `updateElementGeometry()` call moves the element to the top of the hit-testing order. Pass `{ preserveHitTestOrder: true }` to keep its position.
+  - Call `canvas.clearElementGeometry(element)` to remove an element from hit testing, for example, when you hide it.
+
+## Example code
+
+### 2D Canvas
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 200px;">
+  <div id="ui-element" drawable>
+    <p>
+      This text is rendered inside the canvas but is present in the DOM tree.
+    </p>
+    <input type="email" name="email" placeholder="enter your email" />
+    <button type="button">Submit</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const ctx = canvas.getContext("2d");
+  const uiElement = document.getElementById("ui-element");
+
+  canvas.onpaint = () => {
+    ctx.reset();
+    // Draw the HTML element at x:0, y:0. The browser syncs the DOM location
+    // with the drawn location.
+    ctx.drawElementImage(uiElement, 0, 0);
+  };
+
+  // Handle resizing to match device pixels
+  const observer = new ResizeObserver(([entry]) => {
+    const dpc = entry.devicePixelContentBoxSize;
+    canvas.width = dpc
+      ? dpc[0].inlineSize
+      : Math.round(entry.contentRect.width * window.devicePixelRatio);
+    canvas.height = dpc
+      ? dpc[0].blockSize
+      : Math.round(entry.contentRect.height * window.devicePixelRatio);
+    canvas.requestPaint();
+  });
+
+  const supportsDevicePixelContentBox =
+    typeof ResizeObserverEntry !== "undefined" &&
+    "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+  const options = supportsDevicePixelContentBox
+    ? { box: "device-pixel-content-box" }
+    : {};
+  observer.observe(canvas, options);
+</script>
+```
+
+### WebGL Canvas
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
+  <div id="ui-element" drawable>
+    <p>WebGL UI Element</p>
+    <button>Action</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const gl = canvas.getContext("webgl2");
+  const uiElement = document.getElementById("ui-element");
+
+  // getElementImageSize(), allocateElementTexture(), and uploadElementWebGL()
+  // are defined in step 5.
+  // computeCanvasTransform() is defined in step 6.
+
+  // Setup WebGL texture...
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  const textureState = { width: 0, height: 0 };
+
+  canvas.onpaint = () => {
+    // 1. Update texture with HTML content
+    try {
+      uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+    } catch (err) {
+      console.error('texElementSubImage2D copy failed:', err);
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position, hit testing, and accessibility bounds with 3D scene
+    canvas.updateElementGeometry(uiElement, {
+      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
+    });
+  };
+</script>
+```
+
+### WebGPU Canvas
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
+  <div id="ui-element" drawable>
+    <p>WebGPU UI Element</p>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const context = canvas.getContext("webgpu");
+  const uiElement = document.getElementById("ui-element");
+
+  // getElementImageSize() and ensureElementTexture() are defined in step 5.
+  // computeCanvasTransform() is defined in step 6.
+
+  // Setup WebGPU...
+  // const device = ...
+  const textureState = { texture: null };
+
+  canvas.onpaint = () => {
+    // 1. Copy HTML content to a texture that matches the element size
+    const size = getElementImageSize(canvas, uiElement);
+    if (size) {
+      const previousTexture = textureState.texture;
+      const texture = ensureElementTexture(device, textureState, size.width, size.height);
+      if (texture !== previousTexture) {
+        // New texture: create, or rebuild, the bind groups that reference it.
+      }
+      try {
+        device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
+      } catch (err) {
+        console.error('drawElementImageToTexture copy failed:', err);
+      }
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position, hit testing, and accessibility bounds (same matrix math as WebGL)
+    canvas.updateElementGeometry(uiElement, {
+      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
+    });
+  };
+</script>
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: Always add the `content="drawable"` attribute to the `<canvas>` element.
+- **MANDATORY**: Add the `drawable` attribute to every element that you draw, including direct children of the canvas.
+- **MANDATORY**: Use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: Use the `drawElementImage` method in 2D, or `drawElementImageToTexture` in WebGPU, to render the HTML content to the canvas.
+- **MANDATORY**: In WebGL, pre-allocate the texture buffer with `texImage2D()` once (when it's initialized or when the element size changes). Reallocate the texture only when the size changes, and set `TEXTURE_MIN_FILTER` to `LINEAR`.
+- **MANDATORY**: In WebGL, use the `texElementSubImage2D` method to render the HTML content to a texture that you pre-allocate with `texImage2D()`, sized from `captureElementImage()`.
+- **MANDATORY**: In WebGPU, size the texture from `captureElementImage()`, and recreate it only when the size changes. Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and pass the texture size as `size`.
+- **MANDATORY**: Sync the geometry of the HTML element with the rendered content. In 2D, `drawElementImage` does it automatically. In WebGL and WebGPU, call `canvas.updateElementGeometry(element, { canvasTransform })`.
+- **MANDATORY**: Use `ResizeObserver` to observe the screen size and update the canvas size to match device pixels.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+## Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required.
+
+However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+The fallback strategy depends on the use case. For example, for an interactive HTML content in canvas, if HTML-in-Canvas is not supported, place the HTML content on top of the canvas using CSS.
+
+### HTML-in-Canvas polyfills
+
+Use the following polyfill script to mimic the HTML-in-Canvas API in browsers that do not support it.
+
+1. Install or embed the library:
+
+```
+# Install
+npm install three-html-render
+```
+
+```
+# Embed
+<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
+```
+
+2. Run the `installHtmlInCanvasPolyfill()` method to translate HTML-in-Canvas.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/improve-text-layout-and-legibility.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/improve-text-layout-and-legibility.md
new file mode 100644
index 00000000..5d259bcf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/improve-text-layout-and-legibility.md
@@ -0,0 +1,77 @@
+# Improve Text Layout and Legibility
+
+The layout of text, particularly at the ends of lines and ends of paragraphs, can impact the legibility and aesthetic appeal of a page. CSS provides several text wrapping options that can improve specific use cases.
+
+For short text blocks like headings, use `text-wrap: balance`. This property instructs the browser to distribute text as evenly as possible across lines, creating a more symmetrical appearance.
+
+The `text-wrap: pretty` CSS property allows you to improve the typographic quality of body text by enabling a more sophisticated wrapping algorithm. It is specifically designed to prevent "orphans" (single words on the last line of a paragraph) and create a more pleasing visual "rag" for long blocks of text.
+
+## Implementation
+
+### 1. **Identify text elements**: 
+
+For `text-wrap: balance`, select short text blocks like headings and table headers. Avoid elements that have visible boxes such as borders or backgrounds, as this can create unexpected visually empty areas in the layout.
+
+For `text-wrap: pretty`, select elements potentially containing long runs of text where orphaned words (runts) or poor line breaks are most noticeable. This includes the following elements:
+  - `<p>`
+  - `<blockquote>`
+  - `<li>`
+  - Any other element potentially containing long runs of text.
+
+#### Choosing the Right Wrapping Method
+
+| Criteria | `text-wrap: balance` | `text-wrap: pretty` | `text-wrap: wrap` (Default) |
+| :--- | :--- | :--- | :--- |
+| **Best For** | Short blocks (Headings, Titles) | Long blocks (Paragraphs, Lists) | Performance-critical content |
+| **Visual Goal** | Symmetrical line lengths | Avoiding orphans ("runts") | Fast, standard wrapping |
+| **Line Constraints** | Up to 6–10 lines (algorithm limit) | Best for 3 to many lines | No limit |
+| **Perf Cost** | **High**: Binary search algorithm | **Medium**: Look-back algorithm | **Low**: Standard greedy algorithm |
+
+### 2. **Apply the chosen wrapping**: 
+
+Apply `text-wrap: balance` specifically to short, multi-line elements such as headings (`h1`-`h6`), subheadings, or pullquotes.
+
+```css
+/* Target specific heading elements for balanced wrapping */
+h1, h2, h3, h4, h5, h6 {
+  /* Enables balanced line-breaking logic */
+  text-wrap: balance;
+}
+```
+
+Use `text-wrap: pretty` to enable an optimized algorithm that evaluates the last few lines of a paragraph to find the best break points.
+
+```css
+/* Apply to multi-line text blocks to prevent orphaned words */
+p, blockquote, li, .pretty-text {
+  /* Enables pretty line-breaking logic for body copy */
+  text-wrap: pretty;
+}
+```
+
+### Critical Constraints and Performance
+
+#### text-wrap: balance
+
+*   **Line Limit:** Browsers impose a limit on the number of lines they will attempt to balance to maintain performance (typically **6 lines** in Chromium and **10 lines** in Firefox). If the text exceeds this limit, the browser reverts to standard `wrap` behavior. Avoid using `text-wrap: balance` on text blocks that are likely to exceed these limits.
+*   **Targeted Application:** DO NOT apply `text-wrap: balance` globally (e.g., `* { text-wrap: balance; }`). The iterative "binary search" algorithm used by browsers is computationally expensive. Limit its use to specific, short text elements.
+*   **Interaction with Width:** `text-wrap: balance` does not change the container's width (`inline-size`). It only affects how text wraps *within* that width. This can leave empty space at the end of the container, which may affect layouts relying on full-width text blocks.
+
+#### text-wrap: pretty
+
+*   **Performance vs. Quality**: MANDATORY: `text-wrap: pretty` is more computationally expensive than the default `wrap` (greedy) algorithm because it evaluates multiple lines (typically the last four) to optimize the break points. Avoid applying it globally to every element if your page has an extreme amount of text content.
+*   **Best for multi-line text**: The benefits of `pretty` are most apparent in paragraphs of three or more lines. It has little to no effect on short, single-line text.
+*   **Browser-specific behavior**: Be aware that implementation details vary. Chromium-based browsers typically focus on the last four lines, while other engines may evaluate the entire paragraph.
+
+### Fallback strategies
+
+Baseline status for text-wrap: balance: Newly available. It's been Baseline since 2024-05-13.
+Supported by: Chrome 114 (May 2023), Edge 114 (Jun 2023), Firefox 121 (Dec 2023), and Safari 17.5 (May 2024).
+
+Browser support for text-wrap: pretty: Limited availability.
+Supported by: Chrome 117 (Sep 2023), Edge 117 (Sep 2023), and Safari 26 (Sep 2025).
+Unsupported in: Firefox.
+
+In browsers that do not support `text-wrap: balance` or `text-wrap: pretty`, the property is ignored, and the text will wrap using the default `wrap` behavior. This is a progressive enhancement that gracefully degrades to standard typography. This ensures that your content remains perfectly readable across all browsers while providing a superior experience to those that support it.
+
+For critical layouts where refined text layout is a requirement, use a JavaScript library, but be aware that this may be slow and cause performance issues.
\ No newline at end of file
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/interactive-content-in-3d-scenes.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/interactive-content-in-3d-scenes.md
new file mode 100644
index 00000000..fc9aca8f
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/interactive-content-in-3d-scenes.md
@@ -0,0 +1,448 @@
+# Enable interactive HTML content in 3D scenes
+
+The HTML-in-Canvas API allows rendering real DOM directly inside a canvas element. When applied to 3D rendering contexts like WebGL, WebGPU, or Three.js, adding the `content="drawable"` attribute to the canvas, and the `drawable` attribute to its descendant HTML elements, enables those elements to be seamlessly projected into the 3D scene. Crucially, because the HTML elements remain part of the active DOM layout tree, they retain full interactivity—allowing users to click buttons, select text, and trigger focus states natively without requiring complex raycasting or custom event handling.
+
+## How to implement
+
+### WebGL and WebGPU
+When using WebGL or WebGPU, follow these steps:
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```
+if ('content' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+> [!NOTE]
+> HTML-in-Canvas is supported from Chrome 157.
+
+2. Initialize `<canvas>` to support descendant HTML elements by adding the `content="drawable"` attribute to the `<canvas>` HTML element. Place your HTML content inside the `<canvas>` element, and add the `drawable` attribute to every element that you draw. An element with `drawable` captures its subtree, except nested descendants that are also `drawable`:
+
+```html
+<canvas id="canvas" content="drawable">
+  <div id="html-content" drawable></div>
+</canvas>
+```
+
+3. Scale your canvas grid to match the device scale factor to prevent blurriness:
+
+```js
+const observer = new ResizeObserver(([entry]) => {
+  const dpc = entry.devicePixelContentBoxSize;
+  canvas.width = dpc
+    ? dpc[0].inlineSize
+    : Math.round(entry.contentRect.width * window.devicePixelRatio);
+  canvas.height = dpc
+    ? dpc[0].blockSize
+    : Math.round(entry.contentRect.height * window.devicePixelRatio);
+});
+
+const supportsDevicePixelContentBox =
+  typeof ResizeObserverEntry !== "undefined" &&
+  "devicePixelContentBoxSize" in ResizeObserverEntry.prototype;
+const options = supportsDevicePixelContentBox
+  ? { box: "device-pixel-content-box" }
+  : {};
+observer.observe(canvas, options);
+```
+
+4. Render the HTML content to a texture inside a `canvas.onpaint` event handler. An element can only be uploaded after the canvas has painted it: call `canvas.requestPaint()` to request a `paint` event.
+
+Size the texture from `canvas.captureElementImage(element)`. Its `width` and `height` are in canvas grid (backing store) pixels, so round them up with `Math.ceil()`. `captureElementImage()` throws if the element has no paint record yet: call `requestPaint()`, and retry on the next `paint` event.
+
+```js
+// Returns the element's size in canvas grid pixels, or null if the element
+// has no paint record yet.
+function getElementImageSize(canvas, element) {
+  let elementImage;
+  try {
+    elementImage = canvas.captureElementImage(element);
+  } catch (err) {
+    canvas.requestPaint(); // No paint record yet: retry on the next paint event.
+    return null;
+  }
+  const width = Math.ceil(elementImage.width);
+  const height = Math.ceil(elementImage.height);
+  elementImage.close();
+  return width > 0 && height > 0 ? { width, height } : null;
+}
+```
+
+- In WebGL context, pre-allocate the texture backing first using the `texImage2D` method. The snippets in this guide use a WebGL 2 context (`canvas.getContext("webgl2")`). Allocate texture storage by calling `texImage2D()` with `null` instead of pixel data, which reserves GPU memory of the given size and format without uploading any pixels. Follow these rules:
+  - Size the texture from `captureElementImage()`, as shown above.
+  - Allocate level 0 only on the first upload, or when the size changes, because reallocating clears the texture. Use mutable storage: immutable `texStorage2D()` storage can't be resized when the element changes size.
+
+```js
+// Binds the texture, and allocates its storage on the first upload, and when
+// the element size changes. `state` stores the allocated size.
+function allocateElementTexture(gl, texture, state, width, height) {
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  if (state.width === width && state.height === height) return;
+
+  gl.texImage2D(
+    gl.TEXTURE_2D,
+    0,                // Mipmap level
+    gl.RGBA8,         // Internal format: 8 bits per RGBA channel
+    width,            // Size in canvas grid pixels
+    height,
+    0,                // Border: must be 0
+    gl.RGBA,          // Format and type that match RGBA8
+    gl.UNSIGNED_BYTE,
+    null              // null reserves GPU memory without uploading pixels
+  );
+  gl.texParameteri(gl.TEXTURE_2D, gl.TEXTURE_MIN_FILTER, gl.LINEAR);
+  state.width = width;
+  state.height = height;
+}
+
+const texture = gl.createTexture();
+const textureState = { width: 0, height: 0 };
+```
+
+- Then, in WebGL context, render the HTML content to the texture using the `texElementSubImage2D` method. Follow these rules:
+  - Pass `{ width, height }` in the config. It makes the copy fill the allocated texture regardless of how the canvas is scaled.
+  - Reallocate the texture if the size changed, as shown above.
+
+```js
+// Uploads the element into the texture. Returns false if the element has no
+// paint record yet. In that case, it's uploaded on the next paint event.
+function uploadElementWebGL(gl, canvas, texture, element, state) {
+  const size = getElementImageSize(canvas, element);
+  if (!size) return false;
+  const { width, height } = size;
+
+  // Bind the texture, and reallocate it if the size changed (see above).
+  allocateElementTexture(gl, texture, state, width, height);
+  gl.texElementSubImage2D(gl.TEXTURE_2D, 0, 0, 0, element, { width, height });
+  return true;
+}
+
+canvas.onpaint = () => {
+  try {
+    uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+  } catch (err) {
+    console.error('texElementSubImage2D copy failed:', err);
+  }
+};
+```
+
+- In WebGPU context, use the `drawElementImageToTexture` method. Follow these rules:
+  - Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and add `TEXTURE_BINDING` to sample it in shaders. A wrong usage is reported as a WebGPU validation error, not as an exception.
+  - Pass the texture size as `size`. Without `size`, a larger element is clipped to the texture. With `size`, the element is scaled to fill it.
+  - WebGPU textures can't be resized. Recreate the texture when the element size changes, and rebuild the bind groups that reference it.
+
+```js
+// WebGPU textures can't be resized. Create the texture once, and recreate it
+// when the element size changes.
+function ensureElementTexture(device, state, width, height) {
+  if (state.texture?.width === width && state.texture?.height === height) {
+    return state.texture;
+  }
+  state.texture?.destroy();
+  state.texture = device.createTexture({
+    size: { width, height },
+    format: "rgba8unorm",
+    usage:
+      GPUTextureUsage.TEXTURE_BINDING |
+      GPUTextureUsage.COPY_DST |
+      GPUTextureUsage.RENDER_ATTACHMENT,
+  });
+  return state.texture; // Recreate the bind groups that used the previous texture.
+}
+
+const textureState = { texture: null };
+
+canvas.onpaint = () => {
+  const size = getElementImageSize(canvas, uiElement);
+  if (!size) return;
+  const previousTexture = textureState.texture;
+  const texture = ensureElementTexture(device, textureState, size.width, size.height);
+  if (texture !== previousTexture) {
+    // New texture: create, or rebuild, the bind groups that reference it.
+  }
+  try {
+    device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
+  } catch (err) {
+    console.error('drawElementImageToTexture copy failed:', err);
+  }
+};
+```
+
+When using a `requestAnimationFrame` loop to render the scene, call `canvas.requestPaint()` within the loop to ensure that the HTML content is rendered to the canvas. `event.changedElements` lists the elements whose rendering changed. Make sure you only re-upload the texture if there has been an update to the descendant HTML elements:
+
+```js
+function render() {
+  // Request to update the canvas
+  canvas.requestPaint();
+  requestAnimationFrame(render);
+}
+requestAnimationFrame(render);
+
+canvas.onpaint = (event) => {
+  if (event.changedElements && event.changedElements.length > 0) {
+    // Update the texture as shown above
+  }
+  // Render the scene, and sync the element geometry as shown in step 5
+};
+```
+
+5. Sync the element geometry.
+
+Compute a `DOMMatrix` that maps the element's border box, in CSS pixels, to the canvas, in CSS pixels. The browser needs to map from the 3D coordinate space into the CSS coordinate space using a viewport transform. To facilitate this, do the following:
+  - Normalize the HTML element. HTML elements are sized in pixels (for example, 200px wide). WebGL, however, usually treats objects as "unit squares", for example, ranging from -0.5 to 0.5. If you don't normalize, your 200px button will look 200 times larger. This step also flips the Y-axis, because in CSS, down is positive, but in WebGL, up is positive.
+  - Convert the WebGL MVP Matrix to a DOM Matrix.
+  - Map to the canvas viewport. This step is the "re-scaling" phase: it stretches that unit-space math back out to match the CSS pixel dimensions of your `<canvas>` element on the screen, and flips the Y-axis back.
+  - Calculate the final transform. Multiply the matrices in order: Viewport * MVP * Normalization. Combining them into one final transform produces a "map" that tells the browser exactly where that HTML element should sit to align with the 3D drawing. The browser performs the perspective divide.
+
+  ```js
+  // Maps the element's border box (CSS pixels) to the canvas (CSS pixels), for a
+  // quad that spans -0.5 to 0.5 in model space and is drawn with the `mvp` matrix.
+  function computeCanvasTransform(canvas, element, mvp) {
+    const width = element.offsetWidth;
+    const height = element.offsetHeight;
+
+    // 1. Normalize the HTML element (CSS pixels -> WebGL Model Space)
+    const toGLModel = new DOMMatrix()
+      // Scale pixels to 1 unit, flip Y (as in CSS it points down, and in WebGL it points up)
+      .scale(1 / width, -1 / height, 1 / height)
+      // Center the origin: (0,0) becomes (-width/2, -height/2) before scaling
+      .translate(-width / 2, -height / 2);
+
+    // 2. Convert WebGL MVP Matrix to DOM Matrix
+    const mvpDOM = new DOMMatrix(Array.from(mvp));
+
+    // 3. Map to the canvas viewport, in CSS pixels
+    const clipToCanvasViewport = new DOMMatrix()
+      // Move center (0,0) to center of canvas
+      .translate(canvas.clientWidth / 2, canvas.clientHeight / 2)
+      // Scale normalized clip (-1..1) to viewport size, and flip Y back
+      .scale(canvas.clientWidth / 2, -canvas.clientHeight / 2, canvas.clientHeight / 2);
+
+    // 4. Multiply: (Clip -> Pixels) * (MVP) * (pixels -> unit square)
+    return clipToCanvasViewport.multiply(mvpDOM).multiply(toGLModel);
+  }
+  ```
+
+Then pass the transform to `canvas.updateElementGeometry()` as `canvasTransform`. This moves the HTML element to sit directly on top of its rendered pixels. This ensures that when a user clicks a button or selects text, they are actually hitting the real HTML element. The browser also uses the transform for the element's accessibility bounds, for example, for screen reader focus rings:
+
+  ```js
+  canvas.updateElementGeometry(targetHTMLElement, {
+    canvasTransform: computeCanvasTransform(canvas, targetHTMLElement, htmlElementMVP),
+  });
+  ```
+
+Use these options to control hit testing:
+  - Each `updateElementGeometry()` call moves the element to the top of the hit-testing order. Pass `{ preserveHitTestOrder: true }` to keep its position.
+  - Call `canvas.clearElementGeometry(element)` to remove an element from hit testing, for example, when you hide it.
+
+### Three.js
+
+1. Check if HTML-in-Canvas is supported in the browser:
+
+```js
+if ('content' in HTMLCanvasElement.prototype) {
+  // Use HTML in Canvas API
+} else {
+  // Use fallback strategy
+}
+```
+
+> [!NOTE]
+> HTML-in-Canvas is supported from Chrome 157.
+
+2. Create a custom geometry and material for the HTML content.
+
+3. Pass the DOM element into THREE.HTMLTexture. The renderer adds the element to its canvas, and sets the required attributes:
+```js
+  material.map = new THREE.HTMLTexture(element);
+  mesh = new THREE.Mesh( geometry, material );
+  scene.add( mesh );
+```
+
+4. Register the mesh with `InteractionManager` to make the HTML element interactive. It keeps the element aligned with the mesh, and syncs the element geometry with the canvas, so that clicks and text selection hit the real HTML element. Call `interactions.update()` in the animation loop, before rendering:
+```js
+  import { InteractionManager } from 'three/addons/interaction/InteractionManager.js';
+
+  const interactions = new InteractionManager();
+  interactions.connect( renderer, camera );
+  interactions.add( mesh );
+
+  // In the animation loop
+  interactions.update();
+  renderer.render( scene, camera );
+```
+
+## Example code
+
+### WebGL Canvas
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
+  <div id="ui-element" drawable>
+    <p>WebGL UI Element</p>
+    <button>Action</button>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const gl = canvas.getContext("webgl2");
+  const uiElement = document.getElementById("ui-element");
+
+  // getElementImageSize(), allocateElementTexture(), and uploadElementWebGL()
+  // are defined in step 4.
+  // computeCanvasTransform() is defined in step 5.
+
+  // Setup WebGL texture...
+  const texture = gl.createTexture();
+  gl.bindTexture(gl.TEXTURE_2D, texture);
+  const textureState = { width: 0, height: 0 };
+
+  canvas.onpaint = () => {
+    // 1. Update texture with HTML content
+    try {
+      uploadElementWebGL(gl, canvas, texture, uiElement, textureState);
+    } catch (err) {
+      console.error('texElementSubImage2D copy failed:', err);
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position, hit testing, and accessibility bounds with 3D scene
+    canvas.updateElementGeometry(uiElement, {
+      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
+    });
+  };
+</script>
+```
+
+### WebGPU Canvas
+
+```html
+<canvas id="canvas" content="drawable" style="width: 400px; height: 400px;">
+  <div id="ui-element" drawable>
+    <p>WebGPU UI Element</p>
+  </div>
+</canvas>
+
+<script>
+  const canvas = document.getElementById("canvas");
+  const context = canvas.getContext("webgpu");
+  const uiElement = document.getElementById("ui-element");
+
+  // getElementImageSize() and ensureElementTexture() are defined in step 4.
+  // computeCanvasTransform() is defined in step 5.
+
+  // Setup WebGPU...
+  // const device = ...
+  const textureState = { texture: null };
+
+  canvas.onpaint = () => {
+    // 1. Copy HTML content to a texture that matches the element size
+    const size = getElementImageSize(canvas, uiElement);
+    if (size) {
+      const previousTexture = textureState.texture;
+      const texture = ensureElementTexture(device, textureState, size.width, size.height);
+      if (texture !== previousTexture) {
+        // New texture: create, or rebuild, the bind groups that reference it.
+      }
+      try {
+        device.queue.drawElementImageToTexture({ source: uiElement }, { texture, size });
+      } catch (err) {
+        console.error('drawElementImageToTexture copy failed:', err);
+      }
+    }
+
+    // ... Render your 3D scene here, calculating htmlElementMVP matrix ...
+
+    // 2. Sync DOM position, hit testing, and accessibility bounds (same matrix math as WebGL)
+    canvas.updateElementGeometry(uiElement, {
+      canvasTransform: computeCanvasTransform(canvas, uiElement, htmlElementMVP),
+    });
+  };
+</script>
+```
+
+### Three.js
+
+```js
+// 1. Initialize Three.js camera, scene, renderer, mesh, interactions;
+
+// 2. Ensure HTML-in-Canvas feature support
+if (!('content' in HTMLCanvasElement.prototype)) {
+  // Use a fallback strategy
+}
+
+// 3. Initialize the source HTML DOM element
+const element = document.createElement('div');
+element.innerHTML = '<h1>Hello World</h1>';
+
+// 4. Create geometry and material
+const geometry = new RoundedBoxGeometry( 100, 100, 100, 10, 10 );
+const material = new THREE.MeshStandardMaterial( { roughness: 0, metalness: 0.5 } );
+
+// 5. Pass the DOM element into THREE.HTMLTexture
+material.map = new THREE.HTMLTexture(element);
+
+mesh = new THREE.Mesh( geometry, material );
+scene.add( mesh );
+
+// 6. Make the HTML element interactive
+interactions = new InteractionManager();
+interactions.connect( renderer, camera );
+interactions.add( mesh );
+
+// 7. Render Loop
+function animate() {
+  // Keep the HTML element aligned with the mesh, so it receives input
+  interactions.update();
+  renderer.render(scene, camera);
+}
+```
+
+## Best Practices
+
+- **MANDATORY**: Check browser support for the HTML-in-Canvas API before using it.
+- **MANDATORY**: When using WebGL or WebGPU, always add the `content="drawable"` attribute to the `<canvas>` element.
+- **MANDATORY**: When using WebGL or WebGPU, add the `drawable` attribute to every element that you draw, including direct children of the canvas.
+- **MANDATORY**: When using WebGL or WebGPU, use an `onpaint` event handler to render the HTML content to the canvas.
+- **MANDATORY**: When using WebGL, pre-allocate the texture buffer with `texImage2D()` once (when it's initialized or when the element size changes). Reallocate the texture only when the size changes, and set `TEXTURE_MIN_FILTER` to `LINEAR`.
+- **MANDATORY**: When using WebGL, use the `texElementSubImage2D` method to render the HTML content to a texture that you pre-allocate with `texImage2D()`, sized from `captureElementImage()`.
+- **MANDATORY**: When using WebGPU, use the `drawElementImageToTexture` method to render the HTML content to the canvas. Size the texture from `captureElementImage()`, and recreate it only when the size changes. Create the texture with `COPY_DST` and `RENDER_ATTACHMENT` usage, and pass the texture size as `size`.
+- **MANDATORY**: When using WebGL or WebGPU, sync the geometry of the HTML element with the rendered content by calling `canvas.updateElementGeometry(element, { canvasTransform })`.
+- **MANDATORY**: When using Three.js, register the mesh with `InteractionManager`, and call `interactions.update()` in the animation loop, so the HTML element receives input.
+- **MANDATORY**: Observe the screen size and update the canvas size to match device pixels, for example, by using `ResizeObserver`.
+- **DO NOT** embed cross-origin content in a canvas, as it is not supported.
+- **DO NOT** initialize `ResizeObserver` within the `onpaint` event handler, as it may lead to memory leaks.
+
+### Fallback strategies
+
+HTML in canvas is not natively supported by any major browser yet.
+
+The HTML-in-Canvas API is not currently supported in all modern browsers, thus a fallback strategy is typically required.
+
+However, given the improved performance benefits of this API, HTML-in-Canvas should be used if the browser supports it.
+
+The fallback strategy depends on the use case. For example, for an interactive HTML content in canvas, if HTML-in-Canvas is not supported, place the HTML content on top of the canvas using CSS.
+
+### HTML-in-Canvas polyfill
+
+Use the following polyfill script to mimic the HTML-in-Canvas API in browsers that do not support it.
+
+1. Install or embed the library:
+
+```
+# Install
+npm install three-html-render
+```
+
+```
+# Embed
+<script src="https://cdn.jsdelivr.net/npm/three-html-render/dist/polyfill.js"></script>
+```
+
+2. Run the `installHtmlInCanvasPolyfill()` method to translate HTML-in-Canvas.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/precise-text-alignment.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/precise-text-alignment.md
new file mode 100644
index 00000000..b45f5f29
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/precise-text-alignment.md
@@ -0,0 +1,99 @@
+# Precise Text Alignment
+
+## The Problem
+
+Browsers automatically add extra whitespace above and below text characters to accommodate line-height and font-specific metrics like ascenders and descenders. This "ghost space" makes it impossible to achieve pixel-perfect vertical alignment using standard CSS.
+
+Common issues include:
+- **Misaligned Icons**: Text appears visually lower or higher than an adjacent icon even when using `align-items: center`.
+- **Inaccurate Padding**: A button with `padding: 12px` visually appears to have more space on top or bottom because of the font's internal leading.
+- **Flush Alignment**: You cannot align the top of a capital letter exactly with the top of a container or an adjacent image without using "magic number" negative margins.
+
+## The Solution
+
+The `text-box-trim` and `text-box-edge` properties (shorthand `text-box`) allow you to trim this internal leading based on specific font metrics. By trimming the text box to the **cap-height** (top of capital letters) and the **alphabetic baseline** (bottom of most letters), you can ensure that the element's bounding box matches its visual content.
+
+### Implementation Strategy
+
+1. **MANDATORY**: Apply `text-box-trim: trim-both` (or the `text-box` shorthand) to the element containing the text.
+2. **MANDATORY**: Specify which metrics to use for trimming with `text-box-edge`. For most UI alignment, use `cap alphabetic`.
+3. **DO** use this to achieve visual vertical centering in flex or grid containers.
+4. **DO** use it to ensure that your CSS `padding` values match the visual gap between the text and the container edge.
+5. **DO NOT** use it on long-form body text where traditional line-spacing is necessary for readability. It is best suited for headings, buttons, and UI labels.
+
+## Implementation Guide
+
+### Use case 1: Trim internal leading for badges
+
+Different fonts have different amounts of built-in spacing above and below the text. This can provide challenges in matching a design, or in visually centering text in a badge. When you want a container's padding to exactly hug the text, use `text-box: trim-both cap alphabetic`. This is especially useful for dense UI components like badges or tags. This allows the padding to start right at the text edge on all sides.
+
+```css
+.badge {
+  padding: 10px;
+  background: hotpink;
+  border-radius: 10px;
+  /* 
+    Trims the top to the cap-height and 
+    the bottom to the alphabetic baseline.
+  */
+  text-box: trim-both cap alphabetic;
+}
+```
+
+### Use case 2: Center text with icons
+
+When using Flexbox to align text and icons, the "ghost space" often makes the text look slightly off-center. Trimming the box ensures the layout engine uses the actual visible letter height for alignment.
+
+```css
+.button {
+  display: inline-flex;
+  align-items: center;
+  gap: 8px; 
+}
+/* 
+  text-box does NOT inherit, and must be applied directly to the text element.
+*/
+.button-text{
+  /* 
+    The flex container now centers against the 
+    visible letters, not the invisible font box.
+  */
+  text-box: trim-both cap alphabetic;
+}
+```
+
+### Use case 3: Align text flush with top edges
+
+To align a heading perfectly with the top of an adjacent image or decorative element, use `trim-start cap alphabetic`. Even though the end will not be trimmed, the end edge must be defined.
+
+```css
+.hero {
+  display: flex;
+  align-items: flex-start;
+}
+
+h1 {
+  /* MANDATORY: The bottom edge must also be defined, even though only the top is trimmed. */
+  text-box: trim-start cap alphabetic;
+}
+```
+
+## Best Practices
+
+- **DO** use the `text-box` shorthand for conciseness: `text-box: <trim-direction> <edges>`.
+- **DO** always specify both edges, even if only one edge is being trimmed (unless using the default `text` edge).
+- **DO** combine with `line-height` for controlled spacing. Trimming removes the leading before the first and last line of text, but `line-height` still affects the distance between lines in multi-line text.
+- **DO NOT** apply to every element. Use it only where precision alignment is a requirement.
+
+### Fallback strategies
+
+Browser support for text-box: Limited availability.
+Supported by: Chrome 133 (Feb 2025), Edge 133 (Feb 2025), and Safari 18.2 (Dec 2024).
+Unsupported in: Firefox.
+
+`text-box` is a progressive enhancement. In browsers that do not support it, the text will simply render with its default leading. Your layout will still be functional, though slightly less precise. No special fallback code is required as the properties are safely ignored by older browsers.
+
+## Other Considerations
+
+1. **Font Metrics**: Different fonts have different internal metrics. `cap alphabetic` is a reliable default, but some fonts or use cases may require `ex` (x-height) for better lowercase alignment.
+2. **Multi-line Text**: Trimming applies to the first and last line of the block. Internal lines are not affected.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/shaped-cutouts.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/shaped-cutouts.md
new file mode 100644
index 00000000..32970f91
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/shaped-cutouts.md
@@ -0,0 +1,148 @@
+# Shaped Cutouts
+
+## Overview
+CSS Masking allows you to clip an element to a custom shape, such as adding a notch to a card or creating a shaped border. When combining shapes for complex layouts, choose your masking strategy based on the type of content the element contains:
+
+| Masking strategy                | Best For                        | Text Impact                    |
+| ------------------------------- | ------------------------------- | ------------------------------ |
+| Direct Element SVG Masking      | Images, Icons, Decorative shapes, Complex shapes | Not recommended (can crop text) |
+| Adjacent Element SVG Masking    | Cards with Text, Crucial content | Text remains fully readable    |
+| Pure CSS Gradients              | Simple Geometric Shapes           | Not recommended (can crop text) |
+
+---
+
+## Implementation
+To implement shaped cutouts:
+
+### Using an SVG Mask
+SVG masks allow you to define shapes that subtract from or add to the visible area using white (reveal) and black (hide) fills.
+
+> **Luminance vs. Alpha Masking**: SVG masks default to **luminance** (brightness) mode, which is why we use `fill="white"` to reveal areas and `fill="black"` to cut them out. If you prefer to use the SVG's transparency (alpha channel) instead of colors, you can set `mask-type: alpha;` in CSS or `mask-type="alpha"` on the SVG `<mask>` element.
+
+#### Direct Element SVG Masking
+When there is no text inside the element to worry about (such as profile avatars, product images, or illustrations), you can apply the SVG mask directly to the element.
+
+Using `maskContentUnits="objectBoundingBox"` inside the SVG mask ensures that the mask scales automatically to the width and height of any element it is applied to.
+
+```html
+<!-- 1. Define the mask in SVG (hidden from view) -->
+<svg width="0" height="0" style="position: absolute;" aria-hidden="true">
+  <defs>
+    <!-- objectBoundingBox makes the mask scale from 0 to 1 along the element's borders -->
+    <mask id="splat-mask" maskContentUnits="objectBoundingBox">
+      <!-- Organic Bezier path defining an artistic paint splat shape -->
+      <path d="M 0.5 0.05 C 0.58 0.05, 0.58 0.21, 0.67 0.18 C 0.76 0.15, 0.79 0.08, 0.85 0.15 C 0.91 0.22, 0.83 0.32, 0.89 0.38 C 0.95 0.44, 1.03 0.45, 0.99 0.55 C 0.95 0.65, 0.82 0.62, 0.8 0.72 C 0.78 0.82, 0.89 0.92, 0.8 0.97 C 0.71 1.02, 0.64 0.88, 0.55 0.93 C 0.46 0.98, 0.44 1.06, 0.35 1.01 C 0.26 0.96, 0.31 0.81, 0.22 0.79 C 0.13 0.77, 0.01 0.88, 0.01 0.77 C 0.01 0.66, 0.16 0.62, 0.14 0.52 C 0.12 0.42, -0.02 0.39, 0.03 0.29 C 0.08 0.19, 0.23 0.27, 0.29 0.19 C 0.35 0.11, 0.3 0.01, 0.4 0.01 C 0.5 0.01, 0.42 0.05, 0.5 0.05 Z" fill="white" />
+    </mask>
+  </defs>
+</svg>
+
+<!-- 2. Apply the mask to the image element -->
+<img src="avatar.jpg" alt="User Profile" class="shaped-avatar">
+
+<style>
+.shaped-avatar {
+  width: 200px;
+  height: 200px;
+  object-fit: cover;
+  
+  /* Apply the SVG mask ID with standard and webkit-prefixed properties */
+  -webkit-mask-image: url(#splat-mask);
+  mask-image: url(#splat-mask);
+}
+</style>
+```
+
+#### Adjacent Element SVG Masking
+Apply the mask to an adjacent element rather than the parent element containing text. This ensures that text doesn't get clipped and remains readable.
+
+To solve this, structure your component into a two-part layout:
+1. A **safe, unmasked text container** (`.card-body`) for all readable content.
+2. An **empty decorative `div`** (`.card-accent`) placed next to it, which receives the custom SVG mask.
+
+By assigning both parts the same background color, they visually merge into a single, custom-shaped component.
+
+```html
+<!-- 1. Define the SVG mask (hidden from view) -->
+<svg width="0" height="0" style="position: absolute;" aria-hidden="true">
+  <defs>
+    <!-- Use objectBoundingBox to make the mask scale with the element -->
+    <mask id="accent-stencil" maskContentUnits="objectBoundingBox">
+      <!-- Fill the entire area with white (fully visible) -->
+      <rect width="1" height="1" fill="white" />
+      <!-- Draw a black shape to cut out a concave curve. Extending the path to x=1.1 guarantees it fully clears the right edge, preventing subpixel lines -->
+      <path d="M 1.1,0 C 0.4,0.1 0.4,0.9 1.1,1 L 1.1,0 Z" fill="black" />
+    </mask>
+  </defs>
+</svg>
+
+<!-- 2. Create the unified card layout -->
+<div class="unified-card">
+  <!-- The text-bearing element remains unmasked and perfectly rectangular -->
+  <div class="card-body">
+    <h3>Premium Membership</h3>
+    <p>Get exclusive weekly updates on modern web standards and premium UI designs.</p>
+  </div>
+  <!-- The empty accent element next to it is masked to form the custom shape -->
+  <div class="card-accent"></div>
+</div>
+
+<style>
+.unified-card {
+  display: flex;
+  width: 400px;
+}
+
+.card-body {
+  flex: 1;
+  background-color: #1e293b; /* Elegant slate color */
+  color: #f8fafc;
+  padding: 24px;
+  border-top-left-radius: 16px;
+  border-bottom-left-radius: 16px;
+}
+
+.card-accent {
+  width: 60px;
+  background-color: #1e293b; /* Same background color so they merge visually without seams */
+  border-top-right-radius: 16px;
+  border-bottom-right-radius: 16px;
+
+  /* Reference the SVG mask */
+  -webkit-mask-image: url(#card-accent-mask);
+  mask-image: url(#card-accent-mask);
+}
+</style>
+```
+
+### Using a Single CSS Gradient for Simple Cutouts
+When you only need simple geometric cutouts (such as a semi-circular top notch, side indentations, or straight diagonal cuts), you do not need to write or reference an external SVG. Instead, you can define a CSS radial or linear gradient directly inside the `mask-image` property.
+
+```html
+<div class="gradient-masked-card">
+  <h3>Notched Coupon Card</h3>
+  <p>This card uses a pure CSS radial gradient to cut out a semi-circular notch along its top edge.</p>
+</div>
+
+<style>
+.gradient-masked-card {
+  background: linear-gradient(135deg, #3b82f6, #1d4ed8);
+  color: white;
+  padding: 40px 24px 24px 24px; /* Extra top padding ensures content clears the notch */
+  border-radius: 16px;
+  text-align: center;
+
+  /* radial-gradient places a circle at 50% (horizontal center) and 0% (top edge), cutting out a 20px transparent notch */
+  -webkit-mask-image: radial-gradient(circle at 50% 0%, transparent 20px, black 21px);
+  mask-image: radial-gradient(circle at 50% 0%, transparent 20px, black 21px);
+}
+</style>
+```
+
+## Fallback strategies
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- **For Shaped Images**: The element will degrade gracefully, displaying as a normal rectangular element with its default fallback styles.
+- **For Shaped Cards**: The adjacent decorative `.card-accent` element will remain a solid, unmasked rectangle. Since it shares the same background color as the text container, the entire card will simply render as a standard, clean rectangular container.
+- **Progressive Enhancement**: By keeping text layers outside the mask entirely, your content is guaranteed to remain completely readable, structured, and accessible on older browsers.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/soft-edge-content-fade.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/soft-edge-content-fade.md
new file mode 100644
index 00000000..8ea24415
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/soft-edge-content-fade.md
@@ -0,0 +1,64 @@
+# Soft Edge Content Fade
+
+## Overview
+To apply a transparency gradient to the edges of a container (e.g., to indicate more content is available to scroll or to fade out text), use CSS Masking with a linear gradient. This approach is superior to using a semi-transparent overlay because it actually fades the content itself, allowing the background to show through naturally without interfering with text selection or pointer events.
+
+## Implementation
+To implement a soft edge fade:
+
+### Fading the bottom edge of a container
+This is useful for indicating that there is more content below in a scrollable area.
+
+```css
+.container {
+  /* Enable scrolling */
+  overflow-y: auto;
+  
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
+  
+  /* Standard property for modern browsers */
+  mask-image: linear-gradient(to bottom, black 80%, transparent 100%);
+}
+```
+
+### Fading both top and bottom edges
+You can use a single gradient with multiple color stops to fade both edges.
+
+```css
+.dual-fade-container {
+  /* Content is visible between 10% and 90% of the height */
+  -webkit-mask-image: linear-gradient(to bottom, transparent 0%, black 10%, black 90%, transparent 100%);
+  mask-image: linear-gradient(to bottom, transparent 0%, black 10%, black 90%, transparent 100%);
+}
+```
+
+## Fallback strategies
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- The content will not fade and will display with sharp edges.
+- Ensure the interface is still functional and content is readable without the fade (progressive enhancement).
+- You can use a semi-transparent overlay as a fallback, but be aware it requires knowing the background color and may interfere with text selection unless `pointer-events: none` is used.
+
+```css
+/* Fallback using an overlay for browsers that do not support masking */
+@supports (not (mask-image: linear-gradient(to bottom, black, transparent))) and (not (-webkit-mask-image: linear-gradient(to bottom, black, transparent))) {
+  .container {
+    position: relative;
+  }
+  
+  .container::after {
+    content: '';
+    position: absolute;
+    bottom: 0;
+    left: 0;
+    right: 0;
+    height: 20%;
+    /* Fallback assumes a solid background color (e.g., white) */
+    background: linear-gradient(to bottom, rgba(255,255,255,0), rgba(255,255,255,1));
+    pointer-events: none; /* Allow interaction with text underneath */
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/typography.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/typography.md
new file mode 100644
index 00000000..6f2d76aa
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/typography.md
@@ -0,0 +1,38 @@
+# Typography
+
+## Overall best practices
+
+- Use unitless numbers for `line-height` (e.g., `1.5`) to ensure relative scaling during font-size inheritance.
+- Use `overflow-wrap: break-word` (or `anywhere`) to contain long URLs.
+- **DON'T** use `px` for font-size. Prefer `rem` to honor the user's browser font-size preferences (root font size), or `em`/percentages for contextual sizing.
+
+## Readability
+
+- **Avoid long lines of text**: Cap paragraph blocks to a maximum of 80 characters width.
+- **Avoid rivers of whitespace**: Avoid `text-align: justify` as it can make text harder to read. If you must use it, combine it with `hyphens: auto` to avoid excessive whitespace between words.
+- **Don't use Ornate fonts**: Omit cursive typefaces for main reading content.
+- **Don't rely on all-caps for emphasis**: Prefer bolding for visual emphasis, and use `<em>`/`<strong>` when the emphasis is semantic.
+- **Limit emphasis overall**: Emphasis loses meaning when it's everywhere — apply it only where it changes how the content should be read.
+- **Support user zoom preferences**: Allow users to resize text up to 200% without loss of content or functionality.
+
+```css
+body {
+  line-height: 1.5;
+  text-align: start; /* Supports LTR and RTL */
+}
+article {
+  max-width: 80ch; /* Caps line length to ~80 characters for readability */
+}
+```
+
+## Text wrapping
+
+- Use `text-wrap: balance` for balanced headlines and headline-like content (e.g. `<th>`)
+- Use `text-wrap: pretty` for long-form body text (paragraphs, blockquotes, etc.)
+- Use `text-wrap: balance` or `text-wrap: pretty` deliberately, **DO NOT** apply it on `*` as it does have a performance cost.
+- Avoid `text-wrap: balance` on elements with a visible box (backgrounds, borders, shadows, etc) as it does not change the container's width, it only affects how text wraps *within* that width. This can leave empty space at the end of the container, which is usually undesirable.
+
+## Responsive Typography
+
+- **DO** combine viewport-relative and font-relative units in `clamp()` for font sizes that scale with the viewport size while ensuring they stay within a desired range. For example, `clamp(2rem, 1rem + 5vw, 4rem)`. Adjust the proportion of viewport-relative and font-relative units to control how quickly the font-size changes.
+- **DON'T** use `vw` alone for font-size without `clamp()`, as it can scale text too small or too large on extreme screens.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visual-effects.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visual-effects.md
new file mode 100644
index 00000000..adc287d3
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visual-effects.md
@@ -0,0 +1,100 @@
+# Visual effects
+
+### Depth and texture
+
+- Layer multiple shadows for realistic soft depth effects.
+- Use `filter: drop-shadow()` instead of `box-shadow` for non-rectangular shapes or transparent PNGs.
+- Use `mix-blend-mode` and `background-blend-mode` for lighting overlays (limit scope with `isolation: isolate`)
+
+```css
+.hero {
+  background-image: url('texture.png'), linear-gradient(to bottom, #fff, #eee);
+  background-blend-mode: soft-light;
+}
+```
+
+### Gradients and `color-mix()`
+
+Use `in oklch` or `in oklab` to explicitly specify the interpolation color space for gradients or `color-mix()`.
+- `in oklch` preserves chroma better, but can more easily get out of device gamut, especially for bigger differences between colors
+- `in oklab` stays in gamut more easily (assuming in-gamut endpoints) but can create washed out desaturated colors in the middle, especially when interpolating between opposite hues.
+- *DON'T* use `in srgb` unless you have a specific reason to do so (e.g. you are building a color picker that needs to interpolate in srgb).
+
+#### Fallback
+
+Some pre-2024 browsers do not support gradient color interpolation space.
+To support these browsers, use the token only when its usage is safe by defining a variable:
+
+```css
+:root {
+  --in-oklab: ;
+  --in-oklch: ;
+}
+
+@supports (linear-gradient(in oklab, white, black)) {
+  :root {
+    --in-oklab: in oklab;
+    --in-oklch: in oklch;
+  }
+}
+```
+
+Then use like:
+
+```css
+.card {
+  background: linear-gradient(to bottom var(--in-oklab), var(--accent-color), var(--darker));
+}
+```
+
+- **Important:** If you use this technique, make sure there is always a non-empty gradient preamble without it, otherwise it will be a syntax error in older browsers.
+- You do NOT need this for `color-mix()`. If a browser supports `color-mix()`, it also supports its `in <color-space>` argument.
+
+### Patterns
+
+Many patterns can be created via CSS gradients + hard stops, and these can be more flexible and performant than SVGs or external images as they can have access to CSS variables and lengths from the surrounding context.
+You don't need to repeat the position twice — just use `0` or `0%` and gradient fixup will auto-adjust it.
+
+Examples below.
+
+Vertical stripes of `1em` width each:
+
+```css
+background: linear-gradient(to right, var(--color-1) 50%, var(--color-2) 0) 0 / 2em;
+```
+
+Diagonal stripes of `1em` width each:
+
+```css
+background: repeating-linear-gradient(-45deg, var(--color-1) 0 1em, var(--color-2) 0 2em);
+```
+
+Checkerboard pattern with `1em` squares:
+
+```css
+background: repeating-conic-gradient(var(--color-1) 0 25%, var(--color-2) 0 50%) 0 / 2em 2em;
+```
+
+Polka dot with `.5em` radius dots spaced `2em` apart (horizontally/vertically — multiply by `sqrt(2)` for diagonal distance):
+
+```css
+--distance: 2em;
+--radius: .5em;
+--polka: radial-gradient(circle, var(--color-1) var(--radius), transparent calc(var(--radius) + 1px));
+background: var(--polka) 0 0, var(--polka) var(--distance) var(--distance) var(--color-2);
+background-size: calc(var(--distance) * 2) calc(var(--distance) * 2);
+```
+
+Simple pie chart:
+
+```css
+.pie {
+  --p: 80%;
+  width: 60px;
+  aspect-ratio: 1;
+  border-radius: 50%;
+  background: conic-gradient(var(--color-1) var(--p), transparent 0%) var(--color-2);
+}
+```
+
+**Important:** When using gradients to render charts, ensure there is a textual fallback for screen readers. MANDATORY: You MUST provide a semantic data table as an accessible alternative, as detailed in `accessibility` (via `npx -y modern-web-guidance@latest retrieve "accessibility"`) under the alternate text and media guidelines.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-font-fallbacks.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-font-fallbacks.md
new file mode 100644
index 00000000..62523adf
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-font-fallbacks.md
@@ -0,0 +1,51 @@
+# Visually Stable Font Fallbacks
+
+When web fonts load, they often replace a fallback font that has different dimensions, even if both are set to the same `font-size`. This causes "layout shift" (Cumulative Layout Shift) and can make text illegible if the fallback's lowercase letters (x-height) are significantly different than the preferred font.
+
+The `font-size-adjust` property solves this by normalizing the size of the font based on a specific metric (usually the x-height), ensuring that text occupies the same visual space regardless of which font is currently active.
+
+## Implementation steps
+
+### 1. Identify the aspect ratio of your preferred font
+To normalize fallbacks, you need the "aspect value" (the ratio of lowercase letters to the font size) of your primary font.
+
+*   **Automatic discovery (Recommended):** Use the `from-font` keyword to let the browser extract the ratio from your primary web font.
+*   **Manual calculation:** If you know the specific value (e.g., 0.545 for Verdana), you can provide it directly for more precise control.
+
+### 2. Apply font-size-adjust to the text container
+Apply the property to the element or a parent container. This ensures that if the primary font fails to load or is in the process of loading, the fallback font is scaled to match the visual size of the primary font.
+
+```css
+.text-content {
+  /* Define your font stack as usual */
+  font-family: "MyWebFont", "Arial", sans-serif;
+  font-size: 1rem;
+
+  /* MANDATORY: Normalize the font size based on the primary font's x-height.
+     This ensures that if 'Arial' is used as a fallback, it is scaled 
+     to match the x-height of 'MyWebFont'. */
+  font-size-adjust: from-font;
+}
+```
+
+### 3. (Optional) Adjust for specific metrics
+While x-height is the default and most common, you can normalize by other metrics like `cap-height` (useful for all-caps headers) or `ch-width` (useful for monospaced fonts).
+
+```css
+h1 {
+  /* Normalize based on the height of capital letters */
+  font-size-adjust: cap-height from-font;
+}
+```
+
+### 4. Verify visual stability
+Ensure that the `font-size-adjust` value correctly aligns the fallback. You can test this by temporarily blocking the web font or adjusting the `font-family` declaration in your browser's DevTools and verifying that the text layout remains stable.
+
+## Fallback strategies
+
+Baseline status for font-size-adjust: Newly available. It's been Baseline since 2024-07-25.
+Supported by: Chrome 127 (Jul 2024), Edge 127 (Jul 2024), Firefox 118 (Sep 2023), and Safari 17 (Sep 2023).
+
+In browsers that do not support `font-size-adjust`, the font will be rendered at its default scale. This may result in layout shifts or changes in readability during font swaps. 
+
+To mitigate this without `font-size-adjust`, you can use the `@font-face` descriptors `size-adjust`, `ascent-override`, and `descent-override` to manually tune fallback fonts, though these are more complex to calculate than a single `font-size-adjust` value.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-mixed-fonts.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-mixed-fonts.md
new file mode 100644
index 00000000..e2c3035a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-stable-mixed-fonts.md
@@ -0,0 +1,63 @@
+# Visually Stable Mixed Fonts
+
+When mixing different font families, for instance when inserting inline code snippets, or switching out font families for different themes, differences in "x-height" (the height of lowercase letters) can make one font appear much smaller or larger than the other font. This can lead to poor legibility and layout shifts.
+
+The `font-size-adjust` property allows you to normalize the visual size of text by adjusting the font size based on a specific font metric (usually the x-height).
+
+### Implementation Steps
+
+1.  **MANDATORY**: Apply `font-size-adjust` to elements where font consistency is critical, such as containers using web fonts or blocks with mixed font families.
+2.  **MANDATORY**: Use the `from-font` keyword on elements to automatically match font size in nested elements to the proportions of the primary font.
+3.  **MANDATORY**: Use a specific numeric aspect-ratio override value for `font-size-adjust` (e.g., `font-size-adjust: 0.5`) to normalize proportions independently when the font proportions to base on are from different themes.
+
+### Example: Normalizing x-height automatically
+
+Using `from-font` is the most robust approach. It extracts the aspect ratio of the x-height from the first available font and applies it to fonts in child elements.
+
+```css
+.content-area {
+  font-family: "MyCustomWebFont";
+  /* Automatically extract and apply x-height ratio from MyCustomWebFont */
+  font-size-adjust: from-font;
+}
+.content-area span{
+  font-family: "MyOtherCustomWebFont"
+}
+```
+
+### Example: Specifying a specific x-height
+
+When the font to adjust is not a child of the font to base the size on, specify a value to adjust the x-height by.
+
+```css
+.theme{
+  font-family: Verdana, sans-serif;
+}
+.theme.alternate{
+  font-family: Times;
+  /* Set to the aspect ratio (x-height / font-size) of the primary font */
+  font-size-adjust: 0.51;
+}
+```
+
+### Fallback strategies
+
+Baseline status for font-size-adjust: Newly available. It's been Baseline since 2024-07-25.
+Supported by: Chrome 127 (Jul 2024), Edge 127 (Jul 2024), Firefox 118 (Sep 2023), and Safari 17 (Sep 2023).
+
+**MANDATORY**: In browsers that do not support `font-size-adjust`, fonts will render at their natural `font-size` value. You must provide a valid fallback strategy for non-supporting browsers using a `@supports` block to mitigate this:
+
+- Use `@supports not (font-size-adjust: from-font)` to detect `font-size-adjust` support and provide fallback styles (e.g. adjusted line-height or font-size).
+- Choose fonts with similar x-heights to your primary font.
+- Apply specific `font-size` and `line-height` overrides for alternate and nested font families.
+
+```css
+/* Feature detection for font-size-adjust */
+@supports not (font-size-adjust: from-font) {
+  .content-area {
+    /* Manual adjustment for browsers without support (if needed) */
+    line-height: 1.6;
+    font-size: 1.2rem;
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-texture-content.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-texture-content.md
new file mode 100644
index 00000000..92eeffad
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/visual-design/visually-texture-content.md
@@ -0,0 +1,78 @@
+# Visually Texture Content
+
+## Overview
+To apply realistic weathering or texture patterns (like grunge, noise, or paper texture) to an element, use CSS Masking (`mask-image`) with a repeating texture image. This allows you to make the content itself appear textured by making parts of it semi-transparent, rather than just overlaying a texture on top. This creates a more realistic physical material appearance.
+
+## Implementation
+To apply a texture pattern:
+
+### Method 1: Using a repeating raster image (Recommended for realistic textures)
+This is the most common method for realistic textures.
+
+```css
+.weathered-element {
+  /* MANDATORY: Use vendor prefix for wider support in older browsers */
+  -webkit-mask-image: url('grunge-pattern.png');
+  -webkit-mask-repeat: repeat; /* Repeat the pattern to fill the area */
+  -webkit-mask-size: 300px; /* Control the scale of the texture */
+
+  /* Standard property for modern browsers */
+  mask-image: url('grunge-pattern.png');
+  mask-repeat: repeat;
+  mask-size: 300px;
+}
+```
+
+### Method 2: Using CSS Gradients for geometric patterns
+You can generate patterns using CSS gradients. This is self-contained and does not require external image files.
+
+```css
+.patterned-element {
+  --checkerboard-gradient: 
+    linear-gradient(45deg, #000 25%, transparent 25%), 
+    linear-gradient(-45deg, #000 25%, transparent 25%), 
+    linear-gradient(45deg, transparent 75%, #000 75%), 
+    linear-gradient(-45deg, transparent 75%, #000 75%);
+
+  /* Apply a checkerboard pattern as a mask */
+  -webkit-mask-image: var(--checkerboard-gradient);
+  -webkit-mask-size: 20px 20px;
+  -webkit-mask-position: 0 0, 0 10px, 10px -10px, -10px 0px;
+  
+  mask-image: var(--checkerboard-gradient);
+  mask-size: 20px 20px;
+  mask-position: 0 0, 0 10px, 10px -10px, -10px 0px;
+}
+```
+
+### Alpha vs Luminance Masking Modes
+
+By default, CSS masks use `mask-mode: match-source`. This means the browser automatically decides whether to use the **alpha channel** (transparency) or the **luminance** (brightness) of the mask based on what kind of source you provide:
+
+| Mask Source Type | Default Mask Mode | Masking Behavior |
+| :--- | :--- | :--- |
+| **Inline SVG `<mask>` element** | `luminance` | Opacity is determined by the brightness of colors. **White** reveals content, **black** hides it, and **gray** creates semi-transparency. |
+| **Direct Image File** (e.g. PNG, SVG file) | `alpha` | Opacity is determined by transparency. **Opaque** parts reveal content, and **transparent** parts hide it. |
+| **CSS Gradient** | `alpha` | Opacity is determined by transparency. **Opaque** colors (like `black`) reveal content, and **transparent** colors hide it. |
+
+> **Note:** You can explicitly override the default mask mode using the `mask-mode` CSS property (e.g., `mask-mode: luminance;` or `mask-mode: alpha;`).
+
+## Fallback strategies
+Baseline status for Masks: Widely available. It's been Baseline since 2023-12-07.
+Supported by: Chrome 120 (Dec 2023), Edge 120 (Dec 2023), Firefox 53 (Apr 2017), and Safari 15.4 (Mar 2022).
+
+If a browser does not support `mask-image` or the prefixed version:
+- The element will display without the texture (clean and solid fill).
+- Ensure the content is still readable without the texture (progressive enhancement).
+- You can use a background image or an overlay as a fallback to simulate the texture, although it will not affect the transparency of the content itself.
+
+```css
+/* Fallback: Use a background image for browsers without mask support */
+@supports (not (mask-image: url(x))) and (not (-webkit-mask-image: url(x))) {
+  .weathered-element {
+    /* Fallback adds texture on top or behind, depending on implementation */
+    background-image: url('grunge-pattern.svg');
+    background-color: #fff; /* Ensure background is solid if needed */
+  }
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/wasm/cpp-on-the-web.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/wasm/cpp-on-the-web.md
new file mode 100644
index 00000000..ebb90f01
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/wasm/cpp-on-the-web.md
@@ -0,0 +1,74 @@
+# Compiling C and C++ to WebAssembly with Emscripten
+
+Use Emscripten to compile C and C++ into high-performance WebAssembly (Wasm)
+modules for the browser.
+
+## 1. Modern Emscripten Compilation Flags
+
+When compiling and linking with `emcc` or `em++`, always use modern modular
+flags:
+
+- `-sEXPORT_ES6`: Emits standard ES6 module syntax (`import`/`export`) rather
+  than legacy global objects. This automatically sets `-sMODULARIZE`.
+- `-sENVIRONMENT=web`: Strips Node.js/shell runtime code to minimize bundle
+  size.
+- `-sSTRICT`: Enforces modern Emscripten defaults and fails on deprecated
+  flags.
+- `-sALLOW_MEMORY_GROWTH`: Allows the WebAssembly linear memory heap to expand
+  dynamically when allocating memory.
+- `-Oz` (or `-O3`) + `-flto`: Optimizes for minimal payload size in release builds.
+
+## 2. Avoid blocking the main thread
+
+If a call into WebAssembly is likely to take a significant amount of time (i.e.
+more than a few milliseconds) it should **not** be called on the main browser
+thread.
+
+To avoid running such code on the main browser thread there are several possible
+approaches:
+
+1. Run the whole WebAssembly program in a Web Worker.  This is often the
+   simplest solution since it doesn't involve setting up SharedArrayBuffer
+   access, or changing the program source.
+
+2. Use pthreads or Wasm Workers.  This allows the work to be shared across
+   many workers but requires SharedArrayBuffer access which can involve adding
+   COOP/COEP HTTP headers.
+
+3. Refactor the C/C++ code to avoid long running calls.  For example slicing
+   the work into small pieces that can be called from `requestIdleCallback`.
+
+## 3. Pay attention for runtime warnings and errors
+
+Make sure you actually test the resulting WebAssembly program and that no
+warnings or errors are generated on the console.
+
+Build and run the programs with `-sASSERTIONS` enabled and fix any runtime
+failures that are produced.
+
+## 4. Avoid dynamic linking if possible
+
+Emscripten works best with static libraries (`.a`). Shared libraries (`.so`,
+`.dylib`, `.dll`) are less useful in browser deployment and can complicate
+things unnecessarily.
+
+## 5. Porting Existing C/C++ Libraries
+
+When integrating existing C/C++ libraries with standard build systems:
+
+### CMake Projects
+
+Wrap CMake commands with `emcmake` and `emmake`:
+```bash
+mkdir build && cd build
+emcmake cmake .. -DCMAKE_BUILD_TYPE=Release
+emmake make
+```
+
+### Autoconf / Make Projects
+
+Use `emconfigure` to set cross-compilation toolchain targets:
+```bash
+emconfigure ./configure --host=wasm32-unknown-emscripten --disable-shared
+emmake make
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-forms.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-forms.md
new file mode 100644
index 00000000..c47d285a
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-forms.md
@@ -0,0 +1,127 @@
+# Agentic Forms
+
+The Declarative API transforms standard HTML `<form>` elements into WebMCP tools via attributes. The browser synthesizes a JSON Schema from the form inputs and handles agent interactions.
+
+**Angular Signal Forms:** **DO NOT** add `toolname`/`tooldescription` to forms built with `form()` from `@angular/forms/signals`. Instead, add `provideExperimentalWebMcpForms()` to the app providers and pass the `experimentalWebMcpTool: { name, description }` option to `form()`. Angular then registers the form through the Imperative API, building the schema from the signal model and wiring it to validation and submission. Using both approaches registers the same form twice.
+
+## Form Attributes
+
+*   `toolname`: Unique name for the tool.
+*   `tooldescription`: What the tool does and when an agent should use it. Do not list the form's fields, options, or limits: the browser already includes them in the schema it builds from the form controls.
+*   `toolautosubmit`: (Optional) If present, the agent can submit the form without waiting for user interaction. 
+*   `toolparamdescription`: (Optional) Provides a way to define a property description within the JSON Schema. Use it to explain what the value means (for example, with sample values), not to repeat the control's options or limits.
+    *   **Resolution Order**: The browser uses `toolparamdescription` if present. In its absence, it uses the `textContent` of the associated `<label>` (skipping labelable descendants). If no label exists, it falls back to the `aria-description`.
+    *   **Grouping (Fieldsets)**: To attach a description to a group of related elements (like `<input type="radio">` buttons), place `toolparamdescription` on the nearest parent `<fieldset>` element so it applies to the parameter group as a whole.
+
+### Example
+
+```html
+<form toolname="search-cars" 
+      tooldescription="Perform a car make/model search" 
+      toolautosubmit>
+  <label for="make">Vehicle Make</label>
+  <input type="text" id="make" name="make" required>
+  
+  <label for="model">Vehicle Model</label>
+  <input type="text" id="model" name="model" toolparamdescription="e.g., 330i, F-150" required>
+  
+  <button type="submit">Search</button>
+</form>
+```
+
+## Handling Submissions in JavaScript
+
+When an agent submits the form, the `SubmitEvent` includes `agentInvoked` (boolean) and `respondWith(promise)`.
+
+```javascript
+document.querySelector('form').addEventListener('submit', (event) => {
+  event.preventDefault();
+
+  // Validate the form
+  const formValidationErrors = myFormIsValid();
+
+  if (formValidationErrors.length > 0) {
+    if (event.agentInvoked) {
+      const errorString =
+        'Validation failed: ' +
+        formValidationErrors
+          .map((err) => `${err.field} (${err.message})`)
+          .join(', ');
+
+      event.respondWith(Promise.resolve(errorString));
+    }
+    return;
+  }
+
+  const resultPromise = performAsyncSearch(new FormData(event.target));
+
+  // Return the result directly to the agent without navigation
+  if (event.agentInvoked) {
+    event.respondWith(resultPromise);
+  }
+});
+```
+
+## Lifecycle Events
+
+`document.modelContext` emits events when agents start or stop interacting with a tool: `toolactivated` fires when tool execution starts, and `toolcancel` fires when it is canceled.
+
+```javascript
+// Starting in Chrome 156, these events are dispatched on `document.modelContext`.
+// Older versions dispatch them on `window`. Feature-detect the event handler
+// property to pick the right target for backward compatibility.
+const targetFor = (type, listener, options) =>
+  (`on${type}` in (document.modelContext ?? {}) ? document.modelContext : window)
+    .addEventListener(type, listener, options);
+
+targetFor('toolactivated', ({ toolName }) => {
+  console.log(`Tool "${toolName}" started execution.`);
+});
+
+targetFor('toolcancel', ({ toolName }) => {
+  console.log(`Tool "${toolName}" execution is cancelled.`);
+});
+```
+
+## Visual Feedback (CSS)
+
+Use pseudo-classes to highlight forms when an agent interacts with them:
+
+*   `:tool-form-active`: Applied to the `<form>` element actively used by the agent.
+*   `:tool-submit-active`: Applied to the submit button when the browser pauses for user review (if `toolautosubmit` is omitted).
+
+```css
+form:tool-form-active {
+  outline: 2px dashed blue;
+  background-color: rgba(0, 0, 255, 0.05);
+}
+
+button:tool-submit-active {
+  outline: 2px dashed red;
+  animation: pulse 2s infinite;
+}
+```
+
+## Form Suitability (When to Avoid)
+
+The Declarative API is best for self-contained, standard forms. It is a poor choice in these scenarios:
+
+* **Highly Dependent Fields**: Forms where inputs change options or visibility based on other inputs. The synthesized schema cannot express these dependencies well.
+* **Custom UI Components**: Forms relying on non-standard inputs (e.g., canvas, rich text editors) that don't auto-serialize values.
+* **Multi-Step Wizards**: Complex workflows requiring multiple form submissions. The Imperative API or standard DOM interaction is better suited here.
+
+## When to use toolautosubmit
+* **Read-Only Operations & Queries**: Searches, filters, fetching details, or checking status (e.g., a car model search, searching a directory, checking stock availability).
+* **Low-Risk, Reversible Actions**: Form actions that can easily be undone or refined by the user manually (e.g., adding items to a cart, applying a coupon code, saving a draft, or setting temporary layout options).
+
+## When to omit toolautosubmit
+* **Destructive or Irreversible Actions**: Deleting records, resetting system configurations, or clearing databases.
+* **Financial & Transactional Actions**: Submitting a checkout form, transferring funds, authorizing subscription payments, or final order placements.
+* **High-Impact User Communication**: Submitting a final job application, sending emails/messages to other real users, or publishing public-facing content.
+* **Sensitive Account Settings**: Changing passwords, modifying user roles/permissions, or updating billing/profile info.
+
+## Fallback strategies
+
+Form-associated WebMCP attributes is not natively supported by any major browser yet.
+
+The WebMCP Declarative API is safe to use in all browsers. Browsers that do not support WebMCP will ignore the `tool*` attributes, and the `<form>` will continue to function as a normal HTML form. No feature detection is required.
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md
new file mode 100644
index 00000000..fefe3ebb
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/agentic-javascript-tools.md
@@ -0,0 +1,423 @@
+# Agentic JavaScript Tools
+
+The Imperative API uses `document.modelContext.registerTool()` to programmatically define JavaScript tools. This is ideal for Single Page Applications (SPAs) where tools need to be added or removed based on the current route or user state.
+
+WebMCP operates on a producer/consumer architecture:
+* **Web pages are tool producers:** You define and register tools using `document.modelContext.registerTool()`. That is all a web page needs to implement. **You do not need to call `getTools()` or `executeTool()` on the page to expose tools to agents.**
+* **Browser and extension agents are the primary consumers:** Agents provided by or through the browser — including the browser's built-in agent, browser extensions, DevTools, and system-level assistants — discover and invoke registered tools out-of-band through internal platform mechanisms.
+* **In-page agents and test harnesses:** `getTools()` and `executeTool()` exist specifically for in-page JavaScript assistants (e.g. an embedded chat widget or `<iframe>`) and automated test suites that need to discover and invoke tools directly within the page context.
+
+## Registration and Lifecycle
+
+Tools are registered by passing a tool definition object and an optional options object (`ModelContextRegisterToolOptions`), which supports two optional members:
+* `signal`: An `AbortSignal` used to unregister the tool when it is no longer needed.
+* `exposedTo`: An array of origin strings controlling which documents in the document tree are allowed to discover and execute the tool across frame boundaries.
+
+### Lifecycle Handling with `AbortController`
+
+WebMCP does not provide an `unregisterTool()` method. To unregister a tool, you must pass an `AbortSignal` during registration and abort that signal when the tool is no longer needed.
+
+```javascript
+const controller = new AbortController();
+
+await document.modelContext.registerTool({
+  name: "get_user_preferences",
+  description: "Retrieves the user's saved preferences.",
+  inputSchema: { type: "object", properties: {} },
+  execute() {
+    const prefs = localStorage.getItem("user_prefs");
+    return prefs ? JSON.parse(prefs) : { theme: "light" };
+  },
+  annotations: { readOnlyHint: true }
+}, { signal: controller.signal });
+
+// To unregister the tool (e.g., on component unmount):
+controller.abort();
+```
+
+Aborting the registration signal only unregisters the tool — it does not cancel executions that are already running. Tools that start long-running work must also honor the per-execution signal described below, or unregistering will leave orphaned requests and stale UI updates behind.
+
+### Controlling cross-origin tool exposure with `exposedTo`
+
+By default, a registered tool is private to the registering document and same-origin frames. When your application is embedded in an `<iframe>` (or embeds third-party widgets) and you need ancestor or sibling frames to discover and invoke the tool, specify the allowed origins using `exposedTo`.
+
+```javascript
+const controller = new AbortController();
+
+await document.modelContext.registerTool({
+  name: "get_cart_items",
+  description: "Retrieves items currently in the user's shopping cart.",
+  inputSchema: { type: "object", properties: {} },
+  async execute(input, { signal }) {
+    return await cartService.getItems({ signal });
+  },
+  annotations: { readOnlyHint: true },
+}, {
+  signal: controller.signal,
+  exposedTo: ["https://checkout.example.com"],
+});
+```
+
+* **Mutual opt-in handshake**: Cross-origin tool discovery is a two-way opt-in. The tool provider frame authorizes the consumer origin via `exposedTo`, and the consumer frame must explicitly request that provider origin via `getTools({ fromOrigins: [...] })`. Without `fromOrigins`, `getTools()` queries only same-origin documents.
+* **Origin matching**: The registering document's own origin always has access. Origins specified in `exposedTo` are granted permission to discover the tool via `document.modelContext.getTools({ fromOrigins: [...] })` and execute it via `document.modelContext.executeTool()`.
+* **Security requirement**: Every origin in `exposedTo` MUST be potentially trustworthy (HTTPS or localhost). Passing an invalid or non-secure origin causes `registerTool()` to reject with a `SecurityError`.
+* **Scope**: `exposedTo` controls in-page cross-document discovery across frames in the document tree.
+
+## Defining Parameters
+
+Parameters (params) are defined using the `inputSchema` property. This must be a **JSON Schema** object that describes the structured data the tool expects.
+
+```javascript
+await document.modelContext.registerTool({
+  name: "calculate_area",
+  description: "Calculates the area of a rectangle.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      width: { type: "number", description: "The width of the rectangle." },
+      height: { type: "number", description: "The height of the rectangle." }
+    },
+    required: ["width", "height"]
+  },
+  execute(input) {
+    // input is { width: 10, height: 20 }
+    return input.width * input.height;
+  },
+  annotations: { readOnlyHint: true }
+});
+```
+
+## Writing Tool and Parameter Descriptions
+
+The agent already receives the full `inputSchema`, so the `description` only needs to say what the tool does and when to use it. **DO NOT** repeat parameter names, types, `enum` values, defaults, or limits in it; declare them in the schema (`enum`, `default`, `minimum`/`maximum`) instead. Parameter descriptions follow the same rule: say what the value means, not its type or allowed values.
+
+The browser does not validate arguments against `inputSchema` or apply `default` values, so do both in `execute`.
+
+```javascript
+const SORT_ORDERS = ["newest", "price_low_to_high"];
+
+await document.modelContext.registerTool({
+  name: "search_products",
+  // Don't list the sort orders here, even via SORT_ORDERS: `enum` already does.
+  description: "Searches the product catalog by keyword. Use when the user wants to find or compare products.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      query: { type: "string", description: "Words to search for." },
+      sort: { type: "string", enum: SORT_ORDERS, default: "newest", description: "Order of the results." },
+    },
+    required: ["query"],
+  },
+  async execute({ query, sort = "newest" }, { signal }) {
+    if (typeof query !== "string" || !SORT_ORDERS.includes(sort)) {
+      return { error: "Pass a search query and a supported sort order.", sortOrders: SORT_ORDERS };
+    }
+    return await productService.search({ query, sort }, { signal });
+  },
+  annotations: { readOnlyHint: true },
+});
+```
+
+## Execution Patterns
+
+The `execute` callback always receives two arguments: the input object, and an options object carrying an `AbortSignal` — `execute(inputObject, { signal })`.
+
+### When to use `async execute`
+Use `async` when the tool involves operations that return a Promise or take time to complete:
+- **Network calls**: Fetching data from an API.
+- **Asynchronous Storage**: Accessing IndexedDB.
+- **External Events**: Waiting for a specific state change or animation to finish.
+
+```javascript
+async execute(input, { signal }) {
+  const response = await fetch(`/api/data/${input.id}`, { signal });
+  return await response.json();
+}
+```
+
+### When to use `execute` (Synchronous)
+Use a standard synchronous function for immediate operations. A synchronous tool runs to completion before cancellation can be observed, so it can ignore the signal:
+- **Pure logic**: Math, filtering, or sorting data already in memory.
+- **Synchronous state**: Reading from `localStorage` or a synchronous state manager.
+
+```javascript
+execute(input) {
+  return input.items.filter(item => item.active);
+}
+```
+
+### Handling errors in `execute`
+
+When `execute` throws (or returns a rejected promise), the agent receives only a generic execution failure. The error message is not forwarded to the agent. If your tool encounters an actionable or recoverable error (such as invalid input, missing items, or a failed HTTP status), **DO NOT** `throw new Error(...)`. Instead, return a structured error payload via the tool's normal return value so the AI agent receives the diagnostic details and can self-correct or retry:
+
+```javascript
+execute({ itemName }) {
+  const item = menuItems.find((entry) => entry.name.toLowerCase() === itemName.toLowerCase());
+  if (!item) {
+    // Return the error as a value instead of throwing, so the agent receives the message:
+    return {
+      error: `Menu item "${itemName}" not found.`,
+      availableItems: menuItems.map((entry) => entry.name),
+    };
+  }
+  return item;
+}
+```
+
+Only re-throw when the execution was cancelled (`signal.aborted` is `true`).
+
+### Cancelling in-flight executions
+
+Cancellation is initiated by the user or the agent. **MANDATORY:** Any tool that performs network requests or other long-running async work MUST honor `signal`, otherwise cancelled executions keep consuming resources and can write stale data into the UI after the agent has moved on.
+
+* **APIs that accept a signal** (`fetch()`, `addEventListener()`, `ReadableStream` readers): pass `signal` straight through.
+* **APIs that do not** (`setTimeout`, `setInterval`, polling loops, `await`-heavy pipelines): call `signal.throwIfAborted()` between steps, and/or reject on `signal.addEventListener('abort', ...)`. Timers accept no signal, so you must clear them yourself in the abort listener.
+
+```javascript
+await document.modelContext.registerTool({
+  name: "fetch_tool",
+  description: "Fetch the text content of a URL and show it on the page.",
+  inputSchema: {
+    type: "object",
+    properties: {
+      url: { type: "string", description: "The URL to fetch" },
+      priority: {
+        type: "string",
+        enum: ["high", "low", "auto"],
+        description: "Relative network priority for the request",
+      },
+    },
+    required: ["url"],
+  },
+  execute: async ({ url, priority }, { signal }) => {
+    const output = document.querySelector("pre");
+    output.textContent = "Loading…";
+    try {
+      // Passing `signal` aborts the network request the moment execution is cancelled.
+      const response = await fetch(url, { priority, signal });
+      if (!response.ok) {
+        output.textContent = "";
+        return { error: `Request failed with status ${response.status}` };
+      }
+      const text = await response.text();
+      output.textContent = text;
+      return text;
+    } catch (err) {
+      // Roll back the UI state this execution set, so a cancelled run leaves no trace.
+      output.textContent = "";
+      if (signal.aborted) {
+        // The execution was cancelled: re-throw instead of returning an error value.
+        throw err;
+      }
+      // Return other errors as a value instead of throwing, so the agent receives the message.
+      return { error: err instanceof Error ? err.message : String(err) };
+    }
+  },
+  annotations: { readOnlyHint: true }
+});
+```
+
+## Flagging Consequential Tools
+
+Since Chrome 154, `annotations` supports `consequentialHint`. Set it to `true` for tools that take high-stakes, irreversible, or real-world actions — booking travel, moving money, sending messages, or deleting data. It signals agents to request explicit user confirmation before execution.
+
+```javascript
+await document.modelContext.registerTool({
+  name: 'book_flight',
+  description: 'Book a flight for the user with confirmed flight details.',
+  inputSchema: {
+    type: 'object',
+    properties: {
+      flightId: { type: 'string', description: 'ID of the flight to book' },
+      passengers: { type: 'number', description: 'Number of tickets to purchase' },
+    },
+    required: ['flightId', 'passengers'],
+  },
+  execute: async ({ flightId, passengers }, { signal }) => {
+    // Forward `signal` to the transaction API to honor cancellation:
+    return await bookFlightReservation({ flightId, passengers }, { signal });
+  },
+  annotations: {
+    readOnlyHint: false,      // This tool mutates state (it makes a booking).
+    consequentialHint: true,  // Spends money and is not trivially reversible.
+    untrustedContentHint: false, // Output is first-party data, not third-party content.
+  }
+});
+```
+
+**MANDATORY:** Treat `consequentialHint` as a hint, not an enforcement mechanism. It does not block execution on its own, and browsers that predate the hint will not prompt at all. Keep whatever in-app confirmation the action already warrants.
+
+## Flagging Debugging Tools
+
+Since Chrome 156, `annotations` supports `debugging`. Set `annotations.debugging` to `true` for tools built for debugging and developer tooling rather than end-user tasks. Examples: dumping internal app state, toggling feature flags, or seeding test data. This lets agents tell developer-only tools apart from tools meant to act for the user. It defaults to `false`. In-page agents and test harnesses can read it from `RegisteredTool.annotations.debugging` via `getTools()`.
+
+```javascript
+await document.modelContext.registerTool({
+  name: "dump_app_state",
+  description: "Returns a snapshot of the internal application store for debugging.",
+  execute() {
+    return appStore.getState();
+  },
+  annotations: {
+    readOnlyHint: true, // Only reads state.
+    debugging: true,    // Developer tooling, not an end-user action.
+  }
+});
+```
+
+## In-Page Agents and Testing (`getTools` and `executeTool`)
+
+**Web pages do not need `getTools()` or `executeTool()` to expose tools to AI agents.** Simply calling `document.modelContext.registerTool()` is all that is required for browser agents, browser extensions, DevTools, and system-level assistants to discover and execute your tools out-of-band.
+
+The `getTools()` and `executeTool()` methods exist specifically for consumers running inside the JavaScript environment:
+1. **In-page JavaScript agents:** An AI assistant, copilot widget, or chat interface embedded directly in the page (or running inside an `<iframe>`) that needs to discover what tools the surrounding page or accessible frames in the document tree offer, and invoke them on behalf of the user.
+2. **Automated testing and debugging:** Test suites (such as Playwright, Vitest, or in-browser unit tests) that inspect registered tool metadata and simulate agent tool invocations without requiring a live external LLM harness.
+
+### Discovering available tools with `getTools()`
+
+In-page agents call `document.modelContext.getTools()` to retrieve an array of `RegisteredTool` objects from the current document and any accessible frames in the document tree.
+
+Since Chrome 155, `RegisteredTool.inputSchema` is returned directly as a JavaScript object (a deep copy of the schema supplied at registration). Mutating this object does not alter the registered tool's actual schema.
+
+```javascript
+// Example: An in-page AI assistant discovering tools available on the page:
+const tools = await document.modelContext.getTools();
+
+// In-page agents can listen for tools being registered or unregistered dynamically:
+document.modelContext.addEventListener("toolchange", async () => {
+  const updatedTools = await document.modelContext.getTools();
+  console.log(`Active tools updated: ${updatedTools.map((t) => t.name).join(", ")}`);
+});
+```
+
+To discover tools registered inside cross-origin descendant iframes (which must explicitly grant access via `exposedTo` during registration), pass `fromOrigins` in the options dictionary:
+
+```javascript
+// Query tools registered in the embedded cart frame that exposed them to this checkout origin:
+const cartTools = await document.modelContext.getTools({
+  fromOrigins: ["https://cart.example.com"],
+});
+```
+
+### Invoking tools with `executeTool()`
+
+In-page agents and test scripts call `document.modelContext.executeTool(tool, inputObject, options)` to execute a registered tool. The tool runs on the document where it was registered, and the promise resolves to the stringified result returned by the tool's `execute` callback.
+
+Since Chrome 155, `executeTool()` accepts a plain JavaScript object directly for `inputObject`, matching the input format your tool's `execute` callback receives.
+
+```javascript
+// 1. Discover the tool (typically done during agent initialization or test setup):
+const tools = await document.modelContext.getTools();
+const areaTool = tools.find((t) => t.name === "calculate_area");
+
+if (areaTool) {
+  const controller = new AbortController();
+  // Example input payload matching the tool's inputSchema:
+  const inputObject = { width: 10, height: 20 };
+  const options = { signal: controller.signal };
+
+  // 2. Pass input arguments as a JavaScript object, with a JSON string fallback for Chrome <155:
+  let resultString;
+  try {
+    resultString = await document.modelContext.executeTool(areaTool, inputObject, options);
+  } catch (err) {
+    if (err?.message?.startsWith("Failed to parse input")) {
+      resultString = await document.modelContext.executeTool(
+        areaTool,
+        JSON.stringify(inputObject),
+        options
+      );
+    } else {
+      // Re-throw real tool execution or cancellation errors:
+      throw err;
+    }
+  }
+
+  console.log("Execution output string:", resultString);
+}
+```
+
+The returned promise rejects if:
+* `inputObject` is not an object or cannot be serialized to a JSON string (e.g. circular references or `BigInt` values). Note that values omitted by JSON serialization (such as functions and `undefined`) will be omitted from the object received by the tool rather than causing a rejection.
+* The execution is aborted via `options.signal`.
+* The tool was unregistered prior to execution or encounters an unhandled runtime error.
+
+## Tool Factory Pattern
+
+To pass context (like stores or application instances) to your tools, use factory functions.
+
+```javascript
+export function createInventoryTool(inventoryManager) {
+  return {
+    name: "get_inventory",
+    description: "Lists items in the inventory.",
+    inputSchema: { type: "object", properties: {} },
+    execute() {
+      return inventoryManager.getItems();
+    },
+    annotations: { readOnlyHint: true }
+  };
+}
+```
+
+## TypeScript Types
+
+In TypeScript projects, **DO NOT** hand-write declarations for `document.modelContext`. Install the official `webmcp-types` package (`npm install --save-dev webmcp-types`) and add it to `tsconfig.json`, since it is not picked up automatically:
+
+```jsonc
+{
+  "compilerOptions": {
+    "types": ["webmcp-types"]
+  }
+}
+```
+
+* `document.modelContext` is typed as optional, so guard it with `if (document.modelContext)` before use.
+* With an inline `inputSchema`, the `execute` input type is inferred from the schema.
+* Named types such as `WebMCP.ModelContextTool` are global (no import needed), useful for typing tool factories.
+
+## Framework support
+
+**MANDATORY:** If the app uses React, Angular, or Vue, register tools through that framework's official WebMCP integration, listed below. **DO NOT** call `document.modelContext.registerTool()` from components or write your own lifecycle wrapper. Each integration already handles feature detection, `AbortSignal` cleanup, and scoping tools to the component or injector lifecycle. These APIs are experimental, so before writing code, look up the current signature in the package's types or docs.
+
+| Framework | Package | API | Docs |
+|---|---|---|---|
+| React 18+ | `use-webmcp-tool` | `useWebMCP(options)`: one call per tool | npmjs.com/package/use-webmcp-tool |
+| Angular | `@angular/core`, `@angular/forms/signals` | `provideExperimentalWebMcpTools([...])` (app or route providers), `declareExperimentalWebMcpTool(...)` (inside services), `provideExperimentalWebMcpForms()` + the `experimentalWebMcpTool` option on Signal Forms | angular.dev/ai/webmcp |
+| Vue | `@vueuse/core` | `useWebMCP(options)` composable | vueuse.org/core/usewebmcp |
+
+All the rules in this guide still apply when you use these integrations:
+* Keep the tool definition shape the same: `name`, `description`, `inputSchema`, `execute(input, { signal })`, and `annotations`.
+* Follow the rules for descriptions and annotations.
+* Validate input and apply defaults inside `execute`.
+* Pass `signal` to long-running work.
+* To offer a tool only some of the time, pass `enabled` (React, Vue). **DO NOT** wrap the hook or composable call in a condition.
+* Integrations may wrap results and errors (for example as `{ content, isError }`). Check the integration's docs before relying on how errors reach the agent.
+
+## API Notes
+
+*   **annotations**: (Optional) A dictionary for tool metadata.
+    *   **readOnlyHint**: (Optional) Set to `true` if the tool does not modify any state and only reads data. This helps agents decide when it is safe to call the tool.
+    *   **consequentialHint**: (Optional, Chrome 154+) Set to `true` for high-stakes, irreversible, or real-world actions so agents request user confirmation first.
+    *   **untrustedContentHint**: (Optional) Set to `true` when the tool returns content your site does not control, such as user-generated text or third-party API responses.
+    *   **debugging**: (Optional, Chrome 156+) Set to `true` when the tool is meant for debugging and developer tooling, not end-user tasks. Defaults to `false`.
+*   **Registration Options**:
+    *   **signal**: (Optional) An `AbortSignal` used to unregister the tool when it is no longer needed.
+    *   **exposedTo**: (Optional) An array of secure origin strings controlling which documents in the document tree are allowed to discover and execute the tool across frame boundaries.
+*   **Tool Discovery Options (`ModelContextGetToolOptions`)**:
+    *   **fromOrigins**: (Optional) An array of secure origin strings to query in accessible frames. Calling `getTools()` without `fromOrigins` queries only same-origin documents.
+*   **Return Format**: The `execute` function can return any JSON-serializable value (object, array, string, number, boolean). The message of an exception thrown from `execute` is not forwarded to the agent, so return actionable errors as structured error payloads (e.g. `{ error: "..." }`) via the tool's return value so the agent can read and act on them.
+*   **Secure Context**: WebMCP requires HTTPS. All origins in `exposedTo` and `fromOrigins` must also be potentially trustworthy.
+*   **Deprecated/Removed**: `navigator.modelContext` (deprecated in Chromium 150), `unregisterTool()`, `provideContext()`, and `clearContext()` are no longer supported.
+
+## Fallback strategies
+
+document.modelContext is not natively supported by any major browser yet.
+
+The WebMCP Imperative API should be used with feature detection to ensure compatibility with browsers that do not yet support WebMCP.
+
+```javascript
+if ('modelContext' in document) {
+  // Register tools
+}
+```
diff --git a/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/webmcp.md b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/webmcp.md
new file mode 100644
index 00000000..93f36785
--- /dev/null
+++ b/plugins/modern-web-guidance/.agents/skills/modern-web-guidance/guides/webmcp/webmcp.md
@@ -0,0 +1,45 @@
+# WebMCP (Web Model Context Protocol)
+
+WebMCP is a browser-native JavaScript API that allows web pages to expose their client-side functionality as structured "tools" to AI agents, browser assistants, and assistive technologies. 
+
+IMPORTANT: WebMCP is currently in Early Preview on Chromium-based browsers (such as Chrome and Edge). It requires Chromium version `146.0.7672.0` or higher and the `#enable-webmcp-testing` flag.
+
+**Crucial Distinction:** WebMCP runs entirely **client-side** in the browser tab. It is *not* a backend server, and it does *not* use HTTP, Server-Sent Events (SSE), or `stdio` transports. The web page itself acts as the tool registry.
+
+Currently, WebMCP **only supports Tools**. It does not support the "Resources" or "Prompts" primitives found in the backend Model Context Protocol.
+
+## Quick Overview
+
+- **Imperative API**: Use `document.modelContext.registerTool()` for complex logic and dynamic interactions.
+- **Declarative API**: Annotate standard HTML `<form>` elements with `toolname` and `tooldescription` to turn them into tools.
+- **Frameworks (MANDATORY)**: React uses `useWebMCP` from `use-webmcp-tool`. Angular uses `provideExperimentalWebMcpTools` / `declareExperimentalWebMcpTool` from `@angular/core`. Vue uses `useWebMCP` from `@vueuse/core`. **DO NOT** call `registerTool()` from components.
+
+## Best Practices
+
+* **Naming and Semantics**: Use specific verbs describing exact behavior (e.g. `create-event` vs `start-event-creation-process`). Favor positive descriptions over listing limitations.
+* **Descriptions**: Say what the tool does and when to use it. Do not repeat parameter names, types, enum values, defaults, or limits: the agent already receives them in the input schema (your `inputSchema`, or the one the browser builds from a form's controls). Put those details in the schema, and explain a non-obvious value in that parameter's own description.
+* **Schema Design**: Accept raw user input (avoid agent math/calculation). Ensure all parameters have specific types and explain the purpose of options.
+* **Reliability**: Validate constraints in code and return descriptive errors for retries. Handle rate limiting gracefully. Ensure the function returns *after* UI state updates for consistency.
+* **Tool Strategy**: Tools should be atomic, composable, and distinct. Do not force flow control instructions ("Don't call B after A") — let the agent decide. Register/unregister tools dynamically depending on the current page context. Use `annotations: { readOnlyHint: true }` (placed after `execute`) for tools that do not modify state to inform the agent of safe execution.
+* **Clean Up**: Always use `AbortSignal` to unregister tools when pages transition or resources are released to avoid leaks and collisions. Do not use `unregisterTool`.
+* **Web Development Best Practices**: WebMCP tools run as client-side JavaScript in the browser tab. They must adhere to regular web development best practices (e.g., keeping secrets out of client-side code, accessing backend databases through secure API layers, and using Web Workers, WASM, or WebGPU for heavy compute).
+
+### When to Discourage WebMCP
+* **High-Risk Actions without Guardrails**: Avoid auto-submitting tools for destructive or irreversible actions (e.g., deleting data) unless the UI requires manual user confirmation outside the agent's control.
+* **Hyper-Dynamic State**: If data changes faster than the agent can react, it may work with stale context.
+
+### Anti-Patterns & Warnings (DO NOT DO THIS)
+
+* **Do not use backend transports.** WebMCP is for browser tabs, not Node.js background processes.
+* **Do not include Resources or Prompts.** These are not supported in the current WebMCP spec.
+* **Do not ignore `inputSchema` structure.** Always provide clear descriptions for every parameter to minimize agent hallucinations.
+* **Do not use outside of a Secure Context (HTTPS).**
+
+## Implementation Status
+
+WebMCP is currently in early preview in Chromium-based browsers (e.g., Chrome, Edge):
+
+* **Current Status**: Early preview.
+* **Required Version**: Chromium `146.0.7672.0` or higher.
+* **Activation**: Requires enabling the flag `chrome://flags/#enable-webmcp-testing` or `edge://flags/#enable-webmcp-testing`.
+* **Specification**: Evolving [Draft Community Group specification](https://webmachinelearning.github.io/webmcp/); not yet a standards-track recommendation.
diff --git a/plugins/modern-web-guidance/.claude-plugin/plugin.json b/plugins/modern-web-guidance/.claude-plugin/plugin.json
new file mode 100644
index 00000000..d51c6805
--- /dev/null
+++ b/plugins/modern-web-guidance/.claude-plugin/plugin.json
@@ -0,0 +1,20 @@
+{
+  "name": "modern-web-guidance",
+  "version": "0.0.196",
+  "description": "Keep your coding agent up to date with the latest web best practices",
+  "author": {
+    "name": "Google Chrome"
+  },
+  "homepage": "https://github.com/GoogleChrome/modern-web-guidance",
+  "repository": "https://github.com/GoogleChrome/modern-web-guidance",
+  "license": "Apache-2.0",
+  "keywords": [
+    "web",
+    "best-practices",
+    "chrome",
+    "baseline",
+    "css",
+    "performance"
+  ],
+  "skills": "./.agents/skills/"
+}
diff --git a/plugins/modern-web-guidance/.codex-plugin/plugin.json b/plugins/modern-web-guidance/.codex-plugin/plugin.json
new file mode 100644
index 00000000..555b9cf7
--- /dev/null
+++ b/plugins/modern-web-guidance/.codex-plugin/plugin.json
@@ -0,0 +1,33 @@
+{
+  "name": "modern-web-guidance",
+  "version": "0.0.196",
+  "description": "Keep your coding agent up to date with the latest web best practices",
+  "author": {
+    "name": "Google Chrome"
+  },
+  "interface": {
+    "displayName": "Modern Web Guidance",
+    "shortDescription": "Keep your coding agent up to date with the latest web best practices",
+    "longDescription": "Keep your coding agent up to date with the latest web best practices",
+    "developerName": "Google Chrome",
+    "category": "Development",
+    "capabilities": [
+      "Skill"
+    ],
+    "defaultPrompt": [
+      "Help me use Modern Web Guidance for my current task."
+    ],
+    "websiteURL": "https://github.com/GoogleChrome/modern-web-guidance"
+  },
+  "homepage": "https://github.com/GoogleChrome/modern-web-guidance",
+  "repository": "https://github.com/GoogleChrome/modern-web-guidance",
+  "license": "Apache-2.0",
+  "keywords": [
+    "web",
+    "best-practices",
+    "chrome",
+    "baseline",
+    "css",
+    "performance"
+  ]
+}
diff --git a/plugins/modern-web-guidance/.cursor-plugin/plugin.json b/plugins/modern-web-guidance/.cursor-plugin/plugin.json
new file mode 100644
index 00000000..d4d34089
--- /dev/null
+++ b/plugins/modern-web-guidance/.cursor-plugin/plugin.json
@@ -0,0 +1,25 @@
+{
+  "name": "modern-web-guidance",
+  "displayName": "Modern Web Guidance",
+  "description": "Keep your coding agent up to date with the latest web best practices",
+  "version": "0.0.196",
+  "author": {
+    "name": "Google Chrome"
+  },
+  "category": "Development",
+  "homepage": "https://github.com/GoogleChrome/modern-web-guidance",
+  "repository": "https://github.com/GoogleChrome/modern-web-guidance",
+  "license": "Apache-2.0",
+  "keywords": [
+    "web",
+    "best-practices",
+    "chrome",
+    "baseline",
+    "css",
+    "performance"
+  ],
+  "tags": [
+    "skill",
+    "web"
+  ]
+}
diff --git a/plugins/modern-web-guidance/LICENSE b/plugins/modern-web-guidance/LICENSE
new file mode 100644
index 00000000..d6456956
--- /dev/null
+++ b/plugins/modern-web-guidance/LICENSE
@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
diff --git a/plugins/modern-web-guidance/plugin.json b/plugins/modern-web-guidance/plugin.json
new file mode 100644
index 00000000..e93302b6
--- /dev/null
+++ b/plugins/modern-web-guidance/plugin.json
@@ -0,0 +1,20 @@
+{
+  "$schema": "https://antigravity.google/schemas/v1/plugin.json",
+  "name": "modern-web-guidance",
+  "version": "0.0.196",
+  "description": "Keep your coding agent up to date with the latest web best practices",
+  "author": {
+    "name": "Google Chrome"
+  },
+  "homepage": "https://github.com/GoogleChrome/modern-web-guidance",
+  "repository": "https://github.com/GoogleChrome/modern-web-guidance",
+  "license": "Apache-2.0",
+  "keywords": [
+    "web",
+    "best-practices",
+    "chrome",
+    "baseline",
+    "css",
+    "performance"
+  ]
+}
diff --git a/plugins/modern-web-guidance/skills-lock.json b/plugins/modern-web-guidance/skills-lock.json
new file mode 100644
index 00000000..855687ee
--- /dev/null
+++ b/plugins/modern-web-guidance/skills-lock.json
@@ -0,0 +1,17 @@
+{
+  "version": 1,
+  "skills": {
+    "chrome-extensions": {
+      "source": "GoogleChrome/modern-web-guidance",
+      "sourceType": "github",
+      "skillPath": "skills/chrome-extensions/SKILL.md",
+      "computedHash": "1e8525bb49647008dcd3a6b7e5d3c3207345f086e7a64d7e6d5bcc67dbba7a71"
+    },
+    "modern-web-guidance": {
+      "source": "GoogleChrome/modern-web-guidance",
+      "sourceType": "github",
+      "skillPath": "skills/modern-web-guidance/SKILL.md",
+      "computedHash": "8e91867cc20dda14251c78c8d905847314c8c196557e1181d586a456cddcb5dc"
+    }
+  }
+}
diff --git a/release-please-config.json b/release-please-config.json
index f9173b7d..378edf1f 100644
--- a/release-please-config.json
+++ b/release-please-config.json
@@ -232,6 +232,32 @@
         }
       ]
     },
+    "plugins/modern-web-guidance": {
+      "release-type": "simple",
+      "component": "modern-web-guidance",
+      "extra-files": [
+        {
+          "type": "json",
+          "path": ".claude-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".codex-plugin/plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": "plugin.json",
+          "jsonpath": "$.version"
+        },
+        {
+          "type": "json",
+          "path": ".cursor-plugin/plugin.json",
+          "jsonpath": "$.version"
+        }
+      ]
+    },
     "plugins/mastra": {
       "release-type": "simple",
       "component": "mastra",