Modern Web Guidance

JetBrainsOfficialCreated by Google ChromeDistributed by JetBrains

Skill
Tool integration
Software development
Apache-2.0
Low risk

From the author

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, Glassmorphism/backdrop-filters, anchor positioning, container queries, `:has()`, `:user-valid`. - Scroll/Motion: View Transitions, Scroll-driven animations, scroll parallax/reveals. - Performance: CWV (LCP, INP), content-visibility, Fetch Priority, image optimization. - System/APIs: Local filesystem access, WebUSB, WebSockets sync, WebAssembly widgets. - Frameworks: Adapting layout/styles in React, Vue, Angular. - General Frontend: Forms, autofill, advanced inputs, custom scrollbars, modern component states, etc. DO NOT trigger for: - Backend: Database SQL, ORMs, Express API routes. - Pipelines: CI/CD deployment, Docker, Actions. - Generic: Local scripts (Python/Go tools), ESLint, Git.

— the description by Google Chrome

AutoGineer summary

Written by AutoGineer from the skill’s own files, not by the author

This skill provides a structured way to access up-to-date web development patterns, ensuring that implementations follow modern standards rather than relying on potentially outdated training data. It covers a wide range of frontend topics including UI components, performance optimization, browser APIs, and form handling. By integrating this tool, developers can search for specific use cases and retrieve detailed, framework-agnostic guides that include browser support and fallback recommendations.

What it does

Searches for standardized web development patterns and best practices.
Retrieves detailed implementation guides for specific frontend use cases.
Provides guidance on browser compatibility and necessary fallbacks.
Helps avoid ad-hoc solutions and unnecessary dependency bloat.
Supports modern web features like container queries, view transitions, and performance APIs.

When to use it

At the beginning of any frontend feature implementation.
Before creating new components to check for existing standardized patterns.
When evaluating the browser support requirements for modern web features.
When needing to implement performance optimizations like LCP or content-visibility.

Advantages

Ensures use of current, recommended web development practices.
Reduces technical debt by discouraging ad-hoc implementations.
Provides clear guidance on handling browser compatibility and fallbacks.
Promotes the use of native browser capabilities over heavy external dependencies.

Usage examples

“I need to implement a modal using modern web standards. What is the best approach?”: The agent searches for modal-related guides and retrieves the recommended implementation pattern, including any necessary browser fallbacks.
“How can I optimize the loading priority of my LCP images?”: The agent searches for image optimization guides and retrieves the specific instructions for using fetch priority to improve performance.

Install

Download the skill as a ZIP:
https://autogineer.com/agent-skills/jetbrains/modern-web-guidance/download

Unzip it into the cross-client skills folder of your project:

mkdir -p .agents/skills && unzip modern-web-guidance.zip -d .agents/skills

Documentation by Google Chrome

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 feature.
Before creating a new component, to check if a standardized pattern already exists.
To avoid implementing ad-hoc solutions or loading large dependencies unnecessarily.

Usage Instructions

Step 1. Search Use Cases

Search with an action-oriented query summarizing what you want to achieve using the search command. Run modern-web-guidance directly with npx.

npx -y modern-web-guidance@latest search "<query>" --skill-version 2026_05_16-c5e7870

Example Output:

[
  {
    "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: If search results are vague, return no matches, or show low similarity scores, run the list command to browse all guides:
npx -y modern-web-guidance@latest list

Step 2. Retrieve Best Practices

Once you have a relevant id from the search results, call this script using the retrieve command to get the full guide. You can pass multiple IDs separated by commas.

npx -y modern-web-guidance@latest retrieve "<id>"

Example Output: The markdown content of the guide describing implementation steps...

Using npx

IMPORTANT: on Windows, using npx may fail. Use npx.cmd ... instead.
Network access is required for fetching npm packages needed by the task.
If the npx -y modern-web-guidance… command hangs, you may be 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 are usually framework-agnostic; adapt them correctly to your setup.
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.

Files

ATTRIBUTION.mdAdded by AutoGineer939 B
LICENSE11.1 KiB
SKILL.md5.7 KiB
guides/accessibility/accessibility.md24.0 KiB
guides/accessibility/accessible-error-announcement.md6.9 KiB
guides/built-in-ai/language-detection.md3.5 KiB
guides/built-in-ai/language-model.md7.1 KiB
guides/built-in-ai/summarizer.md5.9 KiB
guides/built-in-ai/translator.md5.3 KiB
guides/css-layout/css-layout.md19.5 KiB
guides/css/css.md27.0 KiB
guides/css/highlight-text-ranges.md5.4 KiB
guides/forms/animated-select-picker.md7.8 KiB
guides/forms/autofill-address-form.md4.1 KiB
guides/forms/autofill-highlight-inputs.md2.3 KiB
guides/forms/autofill-payment-form.md8.5 KiB
guides/forms/autofill-sign-in-form.md9.9 KiB
guides/forms/autofill-sign-up-form.md11.0 KiB
guides/forms/brand-consistent-forms.md8.3 KiB
guides/forms/branded-select-styling.md5.5 KiB
guides/forms/custom-select-picker-layouts.md5.0 KiB
guides/forms/form-fields-automatically-fit-contents.md5.8 KiB
guides/forms/forms.md13.8 KiB
guides/forms/required-field-feedback.md6.8 KiB
guides/forms/rich-media-picker.md6.6 KiB
guides/forms/select-menu-interaction.md5.6 KiB
guides/forms/validate-input-after-interaction.md8.6 KiB
guides/html/html.md17.5 KiB
guides/passkeys/passkey-authentication.md9.7 KiB
guides/passkeys/passkey-conditional-create.md6.5 KiB
guides/passkeys/passkey-management.md9.3 KiB
guides/passkeys/passkey-reauthentication.md4.9 KiB
guides/passkeys/passkey-registration.md9.3 KiB
guides/passkeys/passkeys.md4.2 KiB
guides/performance/batch-analytics-events.md6.4 KiB
guides/performance/break-up-long-tasks.md2.1 KiB
guides/performance/calculate-total-foreground-time.md2.9 KiB
guides/performance/conditional-async-dependencies.md3.6 KiB
guides/performance/defer-rendering-heavy-content.md6.3 KiB
guides/performance/defer-work-until-scroll-ends.md3.3 KiB
guides/performance/deprioritize-background-fetches.md1.8 KiB
guides/performance/detect-initial-visibility-state.md4.5 KiB
guides/performance/efficient-background-processing.md5.0 KiB
guides/performance/faster-spa-view-transitions.md3.4 KiB
guides/performance/full-session-analytics.md5.7 KiB
guides/performance/identify-heavy-scripts.md4.2 KiB
guides/performance/identify-inp-causes.md5.4 KiB
guides/performance/improve-next-page-load-performance.md7.1 KiB
guides/performance/interactions-in-complex-layouts.md3.4 KiB
guides/performance/optimize-image-priority.md4.0 KiB
guides/performance/optimize-preload-priority.md3.3 KiB
guides/performance/optimize-script-priority.md2.6 KiB
guides/performance/performance.md17.9 KiB
guides/performance/resolution-optimized-pseudo-elements.md2.3 KiB
guides/performance/schedule-tasks-by-priority.md2.2 KiB
guides/performance/sequence-distributed-events.md3.5 KiB
guides/privacy/privacy.md11.0 KiB
guides/security/security.md25.2 KiB
guides/user-experience/adapt-scrollbar-to-contrast-preferences.md3.5 KiB
guides/user-experience/anchor-positioning-tab-underline.md2.9 KiB
guides/user-experience/animate-element-entry-exit.md5.0 KiB
guides/user-experience/animate-to-from-top-layer.md5.5 KiB
guides/user-experience/animate-to-intrinsic-sizes.md5.3 KiB
guides/user-experience/apply-webgl-shaders.md9.9 KiB
guides/user-experience/calculate-event-differentials.md4.4 KiB
guides/user-experience/calculate-with-intrinsic-sizes.md9.6 KiB
guides/user-experience/capture-location-agnostic-data.md3.6 KiB
guides/user-experience/carousel-slide-effects.md8.1 KiB
guides/user-experience/carousel-snap-highlights.md5.7 KiB
guides/user-experience/child-state-based-styling.md4.8 KiB
guides/user-experience/complex-shapes.md3.5 KiB
guides/user-experience/component-specific-light-dark-theme.md9.3 KiB
guides/user-experience/consistent-cross-document-transitions.md11.8 KiB
guides/user-experience/content-based-styling.md5.2 KiB
guides/user-experience/coordinate-global-events.md3.5 KiB
guides/user-experience/cross-document-transitions.md4.4 KiB
guides/user-experience/customize-scrollbar-color-and-thickness.md2.4 KiB
guides/user-experience/dark-mode.md15.2 KiB
guides/user-experience/declarative-button-actions.md5.4 KiB
guides/user-experience/declarative-dialog-popover-control.md9.2 KiB
guides/user-experience/deliver-optimized-decorative-images.md2.8 KiB
guides/user-experience/design-token-reactivity.md5.7 KiB
guides/user-experience/directional-navigation-transitions.md4.9 KiB
guides/user-experience/dynamic-sibling-animations.md2.6 KiB
guides/user-experience/dynamic-sibling-styling.md3.6 KiB
guides/user-experience/export-html-media-from-canvas.md11.2 KiB
guides/user-experience/expose-canvas-content-to-browser-features.md14.1 KiB
guides/user-experience/flicker-free-client-side-ab-testing.md8.5 KiB
guides/user-experience/fluid-scaling.md3.0 KiB
guides/user-experience/format-human-readable-durations.md4.2 KiB
guides/user-experience/group-element-transitions.md5.0 KiB
guides/user-experience/improve-text-layout-and-legibility.md5.1 KiB
guides/user-experience/individual-transform-properties.md3.6 KiB
guides/user-experience/interactive-content-in-3d-scenes.md13.3 KiB
guides/user-experience/interactive-content-reveal.md5.1 KiB
guides/user-experience/interest-triggered-action-previews.md4.1 KiB
guides/user-experience/interest-triggered-tooltips.md6.8 KiB
guides/user-experience/light-dismiss-a-dialog.md3.6 KiB
guides/user-experience/manage-recurring-intervals.md3.3 KiB
guides/user-experience/model-partial-time-concepts.md4.2 KiB
guides/user-experience/move-dom-element-without-losing-state.md2.5 KiB
guides/user-experience/navigation-drawer.md15.7 KiB
guides/user-experience/overflow-clipping-control.md8.0 KiB
guides/user-experience/parallax-scroll-effects.md8.8 KiB
guides/user-experience/persistent-app-tours.md3.9 KiB
guides/user-experience/persistent-toast-notifications.md1.8 KiB
guides/user-experience/persistent-top-layer-ui.md2.2 KiB
guides/user-experience/physics-based-easing.md5.8 KiB
guides/user-experience/platform-controls-dismiss-dialog.md2.6 KiB
guides/user-experience/position-aware-tooltips.md5.9 KiB
guides/user-experience/precise-text-alignment.md4.7 KiB
guides/user-experience/prevent-text-wrapping.md2.4 KiB
guides/user-experience/pull-to-reveal.md4.7 KiB
guides/user-experience/reduce-style-repetition.md3.9 KiB
guides/user-experience/resilient-context-menus-and-nested-dropdowns.md4.9 KiB
guides/user-experience/same-document-transitions.md8.3 KiB
guides/user-experience/scroll-entry-exit-effects.md7.8 KiB
guides/user-experience/scroll-position-aware-elements.md3.6 KiB
guides/user-experience/scroll-progress-indicator.md6.7 KiB
guides/user-experience/scroll-snap-realtime-feedback.md6.7 KiB
guides/user-experience/scroll-snap-state-sync.md3.9 KiB
guides/user-experience/scroll-target-on-load.md3.3 KiB
guides/user-experience/scrollability-affordance-hints.md3.6 KiB
guides/user-experience/scrollytelling.md8.3 KiB
guides/user-experience/search-hidden-content.md6.7 KiB
guides/user-experience/shaped-cutouts.md7.0 KiB
guides/user-experience/shrinking-header-on-scroll.md6.3 KiB
guides/user-experience/size-aware-styling.md2.9 KiB
guides/user-experience/soft-edge-content-fade.md2.6 KiB
guides/user-experience/stabilize-reactive-state.md3.5 KiB
guides/user-experience/stack-drill-down.md32.9 KiB
guides/user-experience/style-parent-with-has.md6.0 KiB
guides/user-experience/support-global-calendar-systems.md5.7 KiB
guides/user-experience/swipe-to-remove.md26.2 KiB
guides/user-experience/visually-stable-font-fallbacks.md2.9 KiB
guides/user-experience/visually-stable-mixed-fonts.md2.8 KiB
guides/user-experience/visually-texture-content.md3.7 KiB
guides/webmcp/agentic-forms.md5.0 KiB
guides/webmcp/agentic-javascript-tools.md4.1 KiB
guides/webmcp/webmcp.md3.7 KiB

guides/html/html.md

Fundamental Semantics and Validation
Content Grouping and Attribution
Resource Prioritization and Performance
Native Overlays: Dialogs and Popovers
Disclosures: Details and Summary
Focus Boundaries and Visibility
HTML APIs and Forms Grouping
Native Media Elements
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

<!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

<!-- 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 carousel items.

Code Example

<!-- 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

<!-- 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

<!-- 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

<!-- 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>

[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

<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

<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

<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>

.loading-bar {
  accent-color: hsl(var(--brand-hue, 200) 80% 50%);
  transition: accent-color 0.3s ease;
}

Requirements and compatibility

Works with: Claude Code, Claude apps, OpenAI Codex, GitHub Copilot, Cursor, Gemini CLI, Kiro, OpenCode, Goose, Amp, Roo Code, JetBrains Junie, Factory Droid, Devin (ex-Windsurf), Mistral Vibe, OpenHands, Letta

“Works with” means the tool reads the open Agent Skills format; a skill written for one tool may use features others lack.

Needs: Needs Node.js

Security

What our scanner noticed· Low risk

Instructions that use the network

A static scan is not a guarantee. Skills are third-party content: review a skill before you let an agent use it.

Attribution and licence

Created by

Google Chrome

Publisher

JetBrains (Official)

Distributed by

JetBrains

Source

JetBrains/skills · modern-web-guidance · commit 3f53782

Licence

Apache License 2.0 (redistribution allowed)

ATTRIBUTION.md (written by AutoGineer)

Synced

2026-11-09

AutoGineer is not affiliated with or endorsed by Google Chrome or JetBrains.

Download ZIP

The ZIP holds the skill’s files, its licence files and an ATTRIBUTION.md. Download modern-web-guidance.zip

From the author

AutoGineer summary

What it does

When to use it

Advantages

Usage examples

Install

Documentation by Google Chrome

Modern Web Guidance

When to use

Usage Instructions

Step 1. Search Use Cases

Step 2. Retrieve Best Practices

Using npx

Guidelines

Interpreting Browser Support & Fallbacks

Files

guides/html/html.md

Table of Contents

1. Fundamental Semantics and Validation

Guidelines

Code Example

2. Content Grouping and Attribution

Guidelines

Code Example

3. Resource Prioritization and Performance

Guidelines

Code Example

4. Native Overlays: Dialogs and Popovers

Guidelines

Code Example

Native UI Overlay & Disclosure Matrix

5. Disclosures: Details and Summary

Guidelines

Code Example

6. Focus Boundaries and Visibility

Guidelines

Code Example

7. HTML APIs and Forms Grouping

Guidelines

Code Example

8. Native Media Elements

Guidelines

Code Example

9. Dynamic Styles and Interactivity

Guidelines

Code Example

Requirements and compatibility

Security

Attribution and licence

Related skills

Web Artifacts Builder

Frontend UI Engineering

Anti UI Slop

Ask Sonner

Pick UI Library

Animate Expo

Download ZIP