Modern Web Guidance
A reference and search tool for modern web platform APIs. Use before implementing any HTML/CSS/JS feature to check whether a standardised, modern pattern exists — web APIs evolve rapidly and training weights contain obsolete patterns.
Use this skill when
- Implementing HTML semantics, native overlays (dialogs, popovers), forms, or media elements
- Writing CSS — cascade management, dark mode, container queries, layout, animations, scroll effects
- Handling performance concerns — LCP, INP, CLS, image optimisation, code splitting, service workers
- Implementing accessibility — ARIA patterns, keyboard navigation, live regions, focus management
- Building forms — autofill, validation, branded selects, payment/sign-in flows
- Implementing UX patterns — view transitions, scroll-driven animations, carousels, tooltips, drawers
- Handling browser API questions — passkeys, WebMCP, built-in AI (Chrome APIs), privacy-preserving patterns
- Adapting web patterns to frameworks (React, Vue, Angular, Svelte)
Do not use this skill when
- Working on backend code — database SQL, ORMs, Express/Fastify API routes
- Working on CI/CD — pipelines, Docker, GitHub Actions workflows
- Writing tooling — ESLint config, Vite/Webpack config, Python/Go scripts
- Debugging a runtime error — use
systematic-debugging instead
- Reviewing an existing UI for concrete visual polish — use
make-interfaces-feel-better instead
- Typing TypeScript API boundaries — use
schema-boundary-typing instead
Routing boundary
| Situation |
Use this skill? |
Route instead |
| Implement a new UI component in HTML/CSS/JS |
✅ Yes |
— |
| Review an existing UI for concrete visual polish |
❌ No |
make-interfaces-feel-better |
| Debug a runtime CSS/JS error |
❌ No |
systematic-debugging |
| Type a TypeScript API edge contract |
❌ No |
schema-boundary-typing |
| Audit dead CSS/JS code |
❌ No |
fallow |
Inputs to gather
Required before starting
- The web technology or pattern question to address.
Helpful if present
- The existing framework or stack in use.
First move
- Identify the specific web guidance question or decision.
- Check the routing boundary to see if a more specific skill applies.
- Load the relevant reference file from the Navigation section.
Navigation
Static reference files — consult these first for the most common tasks:
| File |
Coverage |
references/css.md |
Cascade (@layer, :where()), dark mode, container queries, :has(), anchor positioning, reduced-motion |
references/html.md |
Semantics, resource prioritisation (fetchpriority), native dialogs/popovers, inert, media elements |
references/accessibility.md |
WCAG 2.2, ARIA patterns, .visually-hidden, live regions, focus management, native dialog usage |
references/performance.md |
CWV (LCP/INP/CLS), content-visibility, image optimisation, Service Workers (Workbox), code splitting |
references/forms.md |
Autofill, validation timing (:user-invalid), branded selects, payment/sign-in/address forms, security |
Dynamic retrieval — for UX patterns, animations, passkeys, security, built-in AI, WebMCP, and any topic not covered by the static files:
# Step 1: Search with an action-oriented query
npx -y modern-web-guidance@latest search "<query>"
# Returns: [{ id, description, category, featuresUsed, tokenCount, similarity }]
# Step 2: Retrieve the guide
npx -y modern-web-guidance@latest retrieve "<id>"
If search returns low-similarity results, use list to browse all guides:
npx -y modern-web-guidance@latest list
Requires Node.js ≥ 20. Works offline after first install (TensorFlow.js local search, no API keys).
On Windows: use npx.cmd instead of npx.
Workflow
- Pin the exact web platform decision (HTML, CSS, a11y, forms, performance, etc.).
- Check routing boundaries so a more specific skill does not own the task.
- Load the matching reference (
css, html, accessibility, performance, forms, or dynamic retrieval for niche topics).
- Prefer Baseline Widely Available features; call out Newly/Limited Availability with fallbacks.
- Adapt guidance to the project's framework and browser policy rather than pasting guide code blindly.
- Implement or recommend the modern pattern and note any polyfill or support risk.
- Verify with the project's lint/test/browser checks when code changes land.
Guardrails
Browser support policy:
- All guides assume Baseline Widely Available features are safe without fallbacks.
- For features marked Newly Available or Limited Availability, follow the fallback recommendations in the guide.
- If the project defines a custom browser support policy (e.g. "Safari 17.4+", "no polyfills"), apply it over the guide's default recommendations.
- Proactively suggest documenting a custom policy in
AGENTS.md if the developer: mentions a restricted runtime (Electron, Tauri), excludes specific browser targets, or expresses hesitation about polyfill complexity.
Framework adaptation:
- Guides are framework-agnostic. Always adapt patterns to the project's framework (React hooks, Vue composables, Angular directives).
- Do not copy guide code verbatim into JSX/SFC templates without adaptation.
Never:
- Implement an HTML/CSS/JS feature without checking for a modern pattern first.
- Use
:invalid/:valid for form validation UX — use :user-invalid/:user-valid.
- Use
position: absolute; clip: rect(0,0,0,0) for visually-hidden elements — use the clip-path: inset(50%) pattern from references/accessibility.md.
- Assume BEM is required — use
@layer + :where() for cascade management.
Validation
- should trigger: "implement a dark mode toggle with system preference detection"
- should trigger: "build an accessible modal dialog with light dismiss"
- should trigger: "improve the Largest Contentful Paint score on this page"
- should trigger: "implement a form with autofill and post-interaction validation"
- should trigger: "add a scroll-driven progress indicator to this article"
- should not trigger: "add a GitHub Actions workflow to run tests on push"
- should not trigger: "fix a TypeScript compiler error in my API type"
- should not trigger: "write a Terraform module for an S3 bucket"
Examples
Example 1 — Static reference (common task)
"Style a branded <select> element that matches our design system"
→ Read references/css.md → section on selectors/scoping → appearance: base-select + ::picker(select)
Example 2 — Dynamic retrieval (specific UX pattern)
"Animate a dialog sliding in and fading out when it opens/closes"
npx -y modern-web-guidance@latest search "animate dialog open close"
# → id: "animate-to-from-top-layer"
npx -y modern-web-guidance@latest retrieve "animate-to-from-top-layer"
Example 3 — Dynamic retrieval (passkeys)
"Implement passkey registration and conditional login"
npx -y modern-web-guidance@latest search "passkey registration"
# → id: "passkey-registration"
npx -y modern-web-guidance@latest retrieve "passkey-registration"
Reference files
| PROVENANCE.md | Skill provenance, changelog, and authorship |
references/css.md — CSS cascade, dark mode, container queries, :has(), anchor positioning, transitions; merged from upstream guides/css/css.md + guides/css-layout/css-layout.md (GoogleChrome/modern-web-guidance v0.0.169, Apache-2.0)
references/html.md — HTML semantics, resource prioritisation, native dialogs/popovers, inert; from upstream guides/html/html.md
references/accessibility.md — WCAG 2.2, ARIA, .visually-hidden, live regions, focus management; from upstream guides/accessibility/accessibility.md
references/performance.md — CWV, LCP/INP optimisation, CSS containment, images, Workbox; from upstream guides/performance/performance.md
references/forms.md — Autofill, validation, branded controls, security patterns; from upstream guides/forms/forms.md
- Full library of 130+ guides available via
npx modern-web-guidance@latest search/retrieve — covers UX animations, passkeys, built-in AI, scroll effects, WebMCP, security, privacy
1---2name: modern-web-guidance3description: "Modern web platform API guidance for avoiding legacy HTML, CSS, and JavaScript patterns. Use when implementing web interfaces, forms, accessibility, performance, browser APIs, or animations."4license: GNU GPL v35metadata:6 source: https://skillmd.com/skills/matt-riley/modern-web-guidance7 version: 2.0.1 # x-release-please-version8 category: workflow9 audience: general-coding-agent10 maturity: draft11 kind: reference12---1314# Modern Web Guidance1516A reference and search tool for modern web platform APIs. Use before implementing any HTML/CSS/JS feature to check whether a standardised, modern pattern exists — web APIs evolve rapidly and training weights contain obsolete patterns.1718## Use this skill when1920- Implementing HTML semantics, native overlays (dialogs, popovers), forms, or media elements21- Writing CSS — cascade management, dark mode, container queries, layout, animations, scroll effects22- Handling performance concerns — LCP, INP, CLS, image optimisation, code splitting, service workers23- Implementing accessibility — ARIA patterns, keyboard navigation, live regions, focus management24- Building forms — autofill, validation, branded selects, payment/sign-in flows25- Implementing UX patterns — view transitions, scroll-driven animations, carousels, tooltips, drawers26- Handling browser API questions — passkeys, WebMCP, built-in AI (Chrome APIs), privacy-preserving patterns27- Adapting web patterns to frameworks (React, Vue, Angular, Svelte)2829## Do not use this skill when3031- Working on backend code — database SQL, ORMs, Express/Fastify API routes32- Working on CI/CD — pipelines, Docker, GitHub Actions workflows33- Writing tooling — ESLint config, Vite/Webpack config, Python/Go scripts34- Debugging a runtime error — use `systematic-debugging` instead35- Reviewing an existing UI for concrete visual polish — use [`make-interfaces-feel-better`](../make-interfaces-feel-better/SKILL.md) instead36- Typing TypeScript API boundaries — use `schema-boundary-typing` instead3738## Routing boundary3940| Situation | Use this skill? | Route instead |41|-----------|----------------|---------------|42| Implement a new UI component in HTML/CSS/JS | ✅ Yes | — |43| Review an existing UI for concrete visual polish | ❌ No | [`make-interfaces-feel-better`](../make-interfaces-feel-better/SKILL.md) |44| Debug a runtime CSS/JS error | ❌ No | `systematic-debugging` |45| Type a TypeScript API edge contract | ❌ No | `schema-boundary-typing` |46| Audit dead CSS/JS code | ❌ No | `fallow` |4748## Inputs to gather4950**Required before starting**5152- The web technology or pattern question to address.5354**Helpful if present**5556- The existing framework or stack in use.5758## First move59601. Identify the specific web guidance question or decision.612. Check the routing boundary to see if a more specific skill applies.623. Load the relevant reference file from the Navigation section.6364## Navigation6566**Static reference files** — consult these first for the most common tasks:6768| File | Coverage |69|------|---------|70| `references/css.md` | Cascade (`@layer`, `:where()`), dark mode, container queries, `:has()`, anchor positioning, reduced-motion |71| `references/html.md` | Semantics, resource prioritisation (`fetchpriority`), native dialogs/popovers, `inert`, media elements |72| `references/accessibility.md` | WCAG 2.2, ARIA patterns, `.visually-hidden`, live regions, focus management, native dialog usage |73| `references/performance.md` | CWV (LCP/INP/CLS), `content-visibility`, image optimisation, Service Workers (Workbox), code splitting |74| `references/forms.md` | Autofill, validation timing (`:user-invalid`), branded selects, payment/sign-in/address forms, security |7576**Dynamic retrieval** — for UX patterns, animations, passkeys, security, built-in AI, WebMCP, and any topic not covered by the static files:7778```sh79# Step 1: Search with an action-oriented query80npx -y modern-web-guidance@latest search "<query>"81# Returns: [{ id, description, category, featuresUsed, tokenCount, similarity }]8283# Step 2: Retrieve the guide84npx -y modern-web-guidance@latest retrieve "<id>"85```8687If `search` returns low-similarity results, use `list` to browse all guides:88```sh89npx -y modern-web-guidance@latest list90```9192> Requires Node.js ≥ 20. Works offline after first install (TensorFlow.js local search, no API keys).93> On Windows: use `npx.cmd` instead of `npx`.9495## Workflow96971. Pin the exact web platform decision (HTML, CSS, a11y, forms, performance, etc.).982. Check routing boundaries so a more specific skill does not own the task.993. Load the matching reference (`css`, `html`, `accessibility`, `performance`, `forms`, or dynamic retrieval for niche topics).1004. Prefer Baseline Widely Available features; call out Newly/Limited Availability with fallbacks.1015. Adapt guidance to the project's framework and browser policy rather than pasting guide code blindly.1026. Implement or recommend the modern pattern and note any polyfill or support risk.1037. Verify with the project's lint/test/browser checks when code changes land.104105## Guardrails106107**Browser support policy:**108- All guides assume **Baseline Widely Available** features are safe without fallbacks.109- For features marked *Newly Available* or *Limited Availability*, follow the fallback recommendations in the guide.110- If the project defines a custom browser support policy (e.g. "Safari 17.4+", "no polyfills"), apply it over the guide's default recommendations.111- Proactively suggest documenting a custom policy in `AGENTS.md` if the developer: mentions a restricted runtime (Electron, Tauri), excludes specific browser targets, or expresses hesitation about polyfill complexity.112113**Framework adaptation:**114- Guides are framework-agnostic. Always adapt patterns to the project's framework (React hooks, Vue composables, Angular directives).115- Do not copy guide code verbatim into JSX/SFC templates without adaptation.116117**Never:**118- Implement an HTML/CSS/JS feature without checking for a modern pattern first.119- Use `:invalid`/`:valid` for form validation UX — use `:user-invalid`/`:user-valid`.120- Use `position: absolute; clip: rect(0,0,0,0)` for visually-hidden elements — use the `clip-path: inset(50%)` pattern from `references/accessibility.md`.121- Assume BEM is required — use `@layer` + `:where()` for cascade management.122123## Validation124125- should trigger: "implement a dark mode toggle with system preference detection"126- should trigger: "build an accessible modal dialog with light dismiss"127- should trigger: "improve the Largest Contentful Paint score on this page"128- should trigger: "implement a form with autofill and post-interaction validation"129- should trigger: "add a scroll-driven progress indicator to this article"130- should not trigger: "add a GitHub Actions workflow to run tests on push"131- should not trigger: "fix a TypeScript compiler error in my API type"132- should not trigger: "write a Terraform module for an S3 bucket"133134## Examples135136**Example 1 — Static reference (common task)**137> "Style a branded `<select>` element that matches our design system"138→ Read `references/css.md` → section on selectors/scoping → `appearance: base-select` + `::picker(select)`139140**Example 2 — Dynamic retrieval (specific UX pattern)**141> "Animate a dialog sliding in and fading out when it opens/closes"142```sh143npx -y modern-web-guidance@latest search "animate dialog open close"144# → id: "animate-to-from-top-layer"145npx -y modern-web-guidance@latest retrieve "animate-to-from-top-layer"146```147148**Example 3 — Dynamic retrieval (passkeys)**149> "Implement passkey registration and conditional login"150```sh151npx -y modern-web-guidance@latest search "passkey registration"152# → id: "passkey-registration"153npx -y modern-web-guidance@latest retrieve "passkey-registration"154```155156## Reference files157158159| [`PROVENANCE.md`](PROVENANCE.md) | Skill provenance, changelog, and authorship |160- `references/css.md` — CSS cascade, dark mode, container queries, `:has()`, anchor positioning, transitions; merged from upstream guides/css/css.md + guides/css-layout/css-layout.md (GoogleChrome/modern-web-guidance v0.0.169, Apache-2.0)161- `references/html.md` — HTML semantics, resource prioritisation, native dialogs/popovers, `inert`; from upstream guides/html/html.md162- `references/accessibility.md` — WCAG 2.2, ARIA, `.visually-hidden`, live regions, focus management; from upstream guides/accessibility/accessibility.md163- `references/performance.md` — CWV, LCP/INP optimisation, CSS containment, images, Workbox; from upstream guides/performance/performance.md164- `references/forms.md` — Autofill, validation, branded controls, security patterns; from upstream guides/forms/forms.md165- Full library of 130+ guides available via `npx modern-web-guidance@latest search/retrieve` — covers UX animations, passkeys, built-in AI, scroll effects, WebMCP, security, privacy