modern-web-guidance is an agent skill (aka SKILL.md) to help ensure that when your coding agent works on a web application, it uses modern, high-performance, accessible, and secure APIs rather than legacy, outdated workarounds.

Why?

AI coding agents often default to older patterns/libraries because their training data contains vast amounts of legacy code. This often leads them to generate unnecessary, bloated JavaScript for common tasks that are now native.

Bridging the "High-Recall, Low-Coverage" Knowledge Gap

Every developer knows about the knowledge cutoff—but for coding agents, the real issue is knowledge representation. Even for web platform features released over the last 10 years, our current frontier models lack the density and coverage of high-quality, modern implementation patterns. The models have high recall (they know an API exists) but low coverage of actual production best practices.

This repository bridges that gap. We don't waste your agent's context on general knowledge it already has. Instead, we inject targeted, high-density, expert-curated guidance specifically focused on:

Advanced browser APIs models consistently misuse or fail to structure.
High-performance, accessible, and secure patterns that eliminate legacy bloat.
Responsible cross-browser fallback strategies that models are incapable of inventing on-the-fly.

What

Our content is evergrowing, but we cover from the bleeding edge of the web platform, through the past several years of new features handling fallback strategies. But we don't waste your tokens on stuff models already know.

Core disciplines

Just a tiny sampling of the 134+ use-case-centric guides:

User Experience: Smooth and modern visual states: View Transitions, CSS scrollbar-color styling, high-contrast adaptation, entry/exit transition animations, parallax scrolling.
CSS layout: container queries (both size and style queries), modern color spaces (oklch, color-mix) and subgrid, text-wrap tuning (balance, pretty), subgrid, and typography line height trimming (text-box)
Performance: instant page preloading, Interaction to Next Paint (INP) diagnostics, and background task scheduling using scheduler.yield.
Forms: auto-sizing input fields (field-sizing: content), precise validation with :user-invalid, and accent color synchronization.
Native UI Components: Direct control over dialogs, CSS Anchor Positioning for tooltips, same-document and cross-document View Transitions, and the Popover API.
Accessibility & Security: accessible error announcements, keyboard focus management.
Built-in AI: Leveraging local, on-device client models (native Language Detection, Summarization, and Translation APIs).

Full Skill Coverage (v0.0.124)

Includes expert guidance across 90 modern web features

Covers 112 real-world developer use cases with production-ready code patterns

accessibility

accessible-error-announcement: Synchronize programmatic accessibility states (like aria-invalid) with the visual :user-invalid state to ensure screen reader users receive error feedback only after interaction, mirroring the visual experience.

built-in-ai

language-detection: Detect the language of user-generated content or already present site content.
language-model: Run on-device natural language inference in the browser using the Prompt API, with streaming output, structured JSON responses, and multi-turn session management.
summarizer: Summarize text content using the on-device Summarizer API.
translator: Translate text between languages using the on-device Translator API.

forms

animated-select-picker: Create a custom select component whose dropdown is animated. For example, the menu fades or slides into view, or the options animate upon selection.
autofill-address-form: Build an address form with correct autocomplete attributes and autofill support.
autofill-highlight-inputs: Use CSS to highlight form fields that have been autofilled by the browser and not edited by the user.
autofill-payment-form: Build a payment form that collects card details with correct autocomplete values and autofill support.
autofill-sign-in-form: Build a sign-in form with correct autocomplete values and autofill support.
autofill-sign-up-form: Build a sign-up form with correct autocomplete values and autofill support.
brand-consistent-forms: Match checkboxes, radio buttons, range sliders, and progress bars to your site's color palette without replacing them with custom components.
branded-select-styling: Create custom select elements whose button, picker, arrow icon, and checkmark all seamlessly match your brand or design system's typography, colors, spacing, and border treatments.
custom-select-picker-layouts: Create custom select pickers whose options are positioned in unique or interesting ways, rather than the traditional stacked list of options.
form-fields-automatically-fit-contents: Allow form fields to grow and shrink to fit the user input, e.g. as the user types or selects a different option. Apply maximum and minimum size limits to create dynamic and responsive form fields that conform with the page design.
required-field-feedback: Provide error message for required form fields that were skipped or left empty only after user interaction, to avoid preemptive errors and ensure feedback is timely and contextually relevant to the user's flow.
rich-media-picker: Create a custom select component whose options can contain complex HTML formatting (e.g. images, icons, and other rich formatting) rather than just plain text.
select-menu-interaction: Validate that a non-default option has been chosen in a select menu only after the user has interacted with the control.
validate-input-after-interaction: Show form field validation feedback (e.g. password complexity or email format requirements) only after the user has finished their initial interaction, avoiding premature errors on page load or while the user is typing.

performance

batch-analytics-events: Debounce and batch multiple analytics events together in a single beacon to minimize network contention and reduce server load, while still delivering real-time updates.
break-up-long-tasks: Break up heavy synchronous processing (complex computations and/or long loops) or DOM updates, to let the browser handle user input and repaint the screen.
calculate-total-foreground-time: Calculate the total time a user actually spent viewing a page, excluding periods when the tab was in the background.
conditional-async-dependencies: Conditionally load or initialize async dependencies (such as importing polyfills for missing web features) without requiring complex orchestration across all of a page's script dependencies.
defer-rendering-heavy-content: Reduce rendering times in content-heavy web pages (e.g. pages with long feeds, lots of articles, or complex dashboards), by deferring rendering for any content that is not immediately visible to the user.
defer-work-until-scroll-ends: Defer expensive operations like DOM updates, data fetching, analytics tracking, or layout recalculation until after scrolling completes to maintain smooth scroll performance.
deprioritize-background-fetches: Deprioritize background data fetches made with the Fetch API to prevent network contention with user-initiated requests.
detect-initial-visibility-state: Reliably determine whether a page was initially loaded in the background, even in cases where the script is loaded asynchronously after the user foregrounded the page.
efficient-background-processing: Conserve system resources and battery life by pausing background JavaScript execution (such as <canvas> animations, WebGL rendering, or high-frequency WebSocket data polling) when the component is off-screen and then resume them just-in-time when they scroll back into view.
faster-spa-view-transitions: Enable faster transitions back to previously visited views in a Single-Page Application (SPA) by preserving their structural DOM state instead of destroying and rebuilding them on every navigation.
full-session-analytics: Reliably track analytics, errors, and telemetry data across the user's entire page visit, and defer sending of the data until the user leaves the page.
identify-heavy-scripts: Identify the scripts most responsible for long animation frames
identify-inp-causes: Identify slow running JavaScript that is impacting INP metric
improve-next-page-load-performance: Improve page load performance by prefetching or prerendering pages that the user is likely to visit next.
interactions-in-complex-layouts: Make interactions snappier and more responsive (reducing Interaction to Next Paint (INP) scores) by avoiding layout re-calculations in complex layouts, such as data-heavy dashboards or spreadsheet-style grids.
optimize-image-priority: Optimize the loading priority of Largest Contentful Paint (LCP) candidate images and deprioritize non-critical images to reduce critical resource load delays.
optimize-preload-priority: Optimize the relative priority of preloaded content to reduce critical resource load delays.
optimize-script-priority: Optimize the loading priority of scripts by boosting critical asynchronous scripts and deprioritizing non-essential or late-body scripts to improve sequencing and reduce delays.
resolution-optimized-pseudo-elements: Use resolution-optimized images in CSS pseudo-elements (such as ::before and ::after) to reduce the number of DOM nodes.
schedule-tasks-by-priority: Schedule tasks with different priorities to ensure critical work runs first while background work is deferred.
sequence-distributed-events: Log and sequence operations in distributed microservices or high-throughput tracing environments by recording timestamps with nanosecond resolution.

user-experience

adapt-scrollbar-to-contrast-preferences: Enhance scrollbar visibility for users who prefer high-contrast interfaces
adapt-scrollbar-to-light-dark-preferences: Ensure the scrollbar visually matches the user's operating system light/dark mode preference
anchor-positioning-tab-underline: Transition an element seamlessly between two target element positions. For example, moving a selected tab underline between the previously selected tab and the currently selected tab.
animate-element-entry-exit: Smoothly hide/show elements as they are added/removed from the DOM or as their display values are toggled.
animate-to-from-top-layer: Animate elements such as dialogs, popovers, and tooltips as they're entering/exiting the top layer.
animate-to-intrinsic-sizes: Smoothly animate interactive components (like accordions, menus, and expanding cards) to and from their natural dimensions.
browser-ui-color-theme: Configure built-in browser UI (e.g. scrollbars, form controls, etc) to respect the user's light/dark theme preference.
calculate-event-differentials: Calculate the duration and time remaining between dates and times.
calculate-with-intrinsic-sizes: Calculate the size of an element based on its intrinsic size, while ensuring it fits within given design constraints.
capture-location-agnostic-data: Record chronological data that should not change based on a user's location, such as birthdates, recurring alarms, or national holidays.
carousel-slide-effects: Create a carousel of slides with images or other visual elements, where each slide animates as they enter/center/exit their scroller. For example, the slides may fade-in/fade-out, rotate, get bigger or smaller, etc.
carousel-snap-highlights: Visually highlight the currently snapped non-interactive item in scroll-snapping carousels, galleries, or full-page swipe experiences. For example, expanding a card when snapped, or revealing hidden content.
child-state-based-styling: Build a component that changes its styling based on the state of one of its child elements. For example, a component that renders in light or dark mode based on whether a theme toggle is checked (or not).
component-specific-light-dark-theme: Create component-specific themes by forcing explicit color schemes on individual UI elements, giving users theme choices that are decoupled from their global operating system preferences
consistent-cross-document-transitions: Ensure critical page state is loaded and stable before initiating a cross-document view transition. This means critical CSS styles are loaded and applied, critical JavaScript is loaded and run, and the HTML visible for the user's initial view of the page has been parsed before the transition runs.
content-based-styling: Build a component that changes its layout based on whether it contains specific child elements (or not). For example, if the component contains an image, use a multi-column layout, otherwise default to a single-column layout.
coordinate-global-events: Schedule future meetings or events by explicitly binding them to a geographical IANA time zone so that event times remain accurate regardless of Daylight Saving Time (DST) transitions, "skipped" or "repeated" hours during clock changes.
cross-document-transitions: Create smooth, seamless transitions between full page navigations, such as cross-fades, custom reveal effects, or morphing of content from one page to the next.
customize-scrollbar-color-and-thickness: Customize the color or thickness of a scrollbar
declarative-button-actions: Declaratively connect a button to any element to trigger custom, application-specific actions using declarative button commands, invoker commands, button commands, custom commands, or declarative toggle actions.
declarative-dialog-popover-control: Toggle the visibility of a dialog or popover from a button without writing JavaScript.
deliver-optimized-decorative-images: Deliver optimized decorative images (such as backgrounds, UI icons, or complex masks) by simultaneously providing next-generation image formats (like AVIF or WebP) alongside multiple pixel densities (like 1x and 2x) so the browser can dynamically negotiate the best combination of file size and visual quality for the user's device capabilities.
directional-navigation-transitions: Animate visual state changes to reflect the direction of a user's navigational flow, such as sliding new content in from the right when advancing forward or from the left when returning to a previous screen.
dynamic-sibling-animations: Stagger animation or transition timing across sibling elements so each one starts after a computed delay based on its position in the sibling list.
dynamic-sibling-styling: Create dynamic visual spectrums or layout arrangements that automatically adapt to the number of elements in a group.
flicker-free-client-side-ab-testing: Deliver and render A/B tests, multi-variate tests, or other experiments using client-side JavaScript to alter or inject HTML, CSS, and JavaScript without the original content showing first before flickering or flashing to show the experiment content.
fluid-scaling: Scale items like font size, spacing, and media sizes smoothly based on the parent container's size rather than using fixed breakpoints
format-human-readable-durations: Present elapsed time or durations to users in a readable, localized format, with the flexibility to display either detailed unit breakdowns (e.g., "1 hour and 30 minutes") or total unit counts (e.g., "90 minutes") depending on context.
group-element-transitions: Transition a group of similar elements simultaneously using the same transition logic, such as removing a product from a shopping cart and having all the other products animate into their new positions.
improve-text-layout-and-legibility: Improve the layout and legibility of short standalone text content, such as headings no longer than a few lines, by enabling the browser to apply evenly balanced line breaks when wrapping text.
individual-transform-properties: Animate or override individual CSS transform properties (e.g. translate, rotate, scale) independently of other transform properties on a single element.
interactive-content-reveal: Create interactive reveal effects, such as a spotlight that follows the user's pointer to uncover details within an image or UI section.
interest-triggered-action-previews: Show a live preview of a button's effect when a user signals interest (e.g. hovering, focusing, or long-pressing) but before they commit to clicking.
interest-triggered-tooltips: Show a tooltip or supplemental information when a user hovers over, focuses on, or long-presses an interactive element, without requiring a click.
light-dismiss-a-dialog: Create a modal dialog that can be closed via light dismiss (i.e. clicking or tapping outside of the dialog)
manage-recurring-intervals: Calculate recurring intervals for subscription billings or payroll cycles, automatically adjusting for edge cases such as month-end transitions (e.g., adding one month to January 31st) to ensure accurate period calculations.
model-partial-time-concepts: Model date and time concepts that inherently lack a standard component (such as a specific year, day, or date) without using arbitrary placeholder values that introduce calculation errors.
move-dom-element-without-losing-state: Move or reparent a DOM element without losing important element state, such as interactivity states (:focus/:active),

Description

modern-web-guidance: 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…; chrome-extensions: Build and publish Chrome Extensions using Manifest V3 best practices. Use this skill whenever the user asks to create, modify, debug, or understand Chrome…

Readme Apache-2.0 20 MiB