modern-web-guidance

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

1. Identify the specific web guidance question or decision.
2. Check the routing boundary to see if a more specific skill applies.
3. 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

1. Pin the exact web platform decision (HTML, CSS, a11y, forms, performance, etc.).
2. Check routing boundaries so a more specific skill does not own the task.
3. Load the matching reference (css, html, accessibility, performance, forms, or dynamic retrieval for niche topics).
4. Prefer Baseline Widely Available features; call out Newly/Limited Availability with fallbacks.
5. Adapt guidance to the project's framework and browser policy rather than pasting guide code blindly.
6. Implement or recommend the modern pattern and note any polyfill or support risk.
7. 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