“Replace this modal with modern HTML” sounds like a well-scoped coding-agent task. It leaves out the most important requirement: modern enough for which users? A smaller implementation that cannot open on a customer’s browser is not an optimization. It is a broken interaction with a cleaner diff.
Modern Web Guidance puts web-platform expertise, implementation advice, and browser-compatibility data into coding agents. Google’s documentation explicitly suggests tasks such as modernizing legacy modals and optimizing performance. That makes it interesting for teams trying to remove unnecessary JavaScript—but guidance should help implement a compatibility policy, not quietly choose one.
The useful adoption sequence is browser targets, behavior contract, targeted guidance, independent checks. A more fashionable prompt belongs after the first two.
What Modern Web Guidance Adds#
The project README describes the problem as agents defaulting to legacy patterns learned from older code. Its response is targeted guidance on browser APIs, accessibility, performance, and fallbacks rather than another application framework. I would treat that diagnosis as the project’s motivation, not as proof that every agent-generated component needs replacing.
The documented workflow separates discovery from retrieval: the agent searches for a relevant guide, then retrieves that guide’s implementation patterns and caveats. The distribution lives in GoogleChrome/modern-web-guidance, while development happens in the separate source repository. Keeping those identities straight matters when reviewing installation instructions or reporting a faulty recommendation.
The official quickstart offers commands like these:
# These commands execute a downloaded npm package; review it first.
npx modern-web-guidance@latest search "accessible modal dialog"
npx modern-web-guidance@latest retrieve "dialog"These are source-checked examples, not commands I ran to benchmark the tool. For a repeatable team trial, approve and record a specific package version rather than letting @latest silently change between runs. The npm metadata identifies the package’s source repository and runtime requirements; matching names alone is not a supply-chain review.
There is also a licensing distinction worth preserving: the current source README specifies Apache-2.0 for software code and CC-BY 4.0 for documentation and guide content. “Open source” does not erase attribution requirements when reusing documentation.
Baseline Is an Input, Not Your Support Contract#
MDN’s Baseline definition distinguishes newly available features, supported in the latest stable versions of the core browsers, from widely available features, which have had that support for at least two and a half years. Neither label means every browser used by your customers supports the feature.
MDN explicitly excludes several assumptions people might otherwise make: Baseline is not a substitute for accessibility or usability testing, and it may not describe older devices, operating-system webviews, or assistive technologies. A feature badge is useful evidence about interoperability. It is not evidence that a checkout flow works in an embedded browser your sales team promised to support.
Before asking an agent to modernize a component, I would put a short support contract in the repository:
- Named environments: supported browser versions, mobile platforms, embedded webviews, and any enterprise exceptions.
- Required behavior: opening, dismissal, focus movement, form submission, and recovery after errors.
- Fallback policy: which cosmetic enhancements may disappear, and which critical controls must remain functional.
- Verification: browser projects, manual accessibility checks, and a reviewer who owns exceptions.
That contract also prevents a subtle category error. Support for <dialog> is not automatically support for every newer way of controlling, dismissing, or animating it. Check the features used by the actual implementation, not just its headline element.
Modern Web Guidance’s declarative-control guide, for example, treats Invoker Commands and Popover support separately and documents conditional polyfills. A target that supports the dialog element can still require another opening mechanism. Choosing a small showModal() listener instead of a newer declarative control may be the simpler compatible design.
Replace the Behavior, Not Just the Markup#
A custom overlay is a good candidate for investigation because its implementation may duplicate browser behavior. But a migration has to begin by identifying what kind of interaction it is.
The project’s dialog guide distinguishes blocking modal dialogs, non-modal panels, and overlays that are not dialogs at all. That distinction should survive the rewrite:
| Existing interaction | Candidate platform approach | Acceptance question |
|---|---|---|
| Blocking confirmation | <dialog> opened with showModal() or a supported declarative equivalent | Does the page become inert, and can the user dismiss or complete the action? |
| Supplementary click-open help | A suitably structured element using popover | Can keyboard users reach it and return to their task? |
| Hover or focus tooltip | A dedicated tooltip interaction with appropriate semantics | Is the same information available without a pointer, without unexpectedly moving focus? |
According to MDN’s dialog reference, showModal() makes the rest of the document inert and provides modal behavior. The open attribute alone does not make a dialog modal. An agent that replaces a custom component with <dialog open> has changed more than the tag name.
Conversely, the Popover API produces non-modal content. A popover is not a drop-in replacement for a blocking confirmation, and its visibility mechanism does not choose the content’s application semantics for you. A tooltip and an interactive help panel should not become interchangeable just because both float above the page.
For the modal trial, retain an accessible name, deliberate initial focus, and a visible close or cancel path. Test Escape, focus containment, focus return, background scrolling, long content, and reopening after submission errors. Let native behavior replace redundant scaffolding where verified; do not keep an old focus trap simply because it was already there, or delete error handling because it looks like boilerplate.
Compare a Guided Migration With a Prompt-Only Rewrite#
I have not run a guided-versus-unguided migration benchmark for this article. The following is a proposed evaluation, not a claim of measured performance gains.
Start both implementations from the same commit and one representative component. Give both the same browser targets, behavior contract, model, tool permissions, and time budget. In the guided arm, add the relevant Modern Web Guidance material; in the prompt-only arm, omit it. Otherwise the comparison tests different requirements rather than different access to guidance.
A useful task prompt would look like this:
Modernize the account-settings modal only.
Read the repository's browser-support and interaction requirements first.
Preserve validation, cancellation, focus behavior, and error recovery.
List every proposed platform feature and its compatibility evidence.
Do not add experimental APIs, upgrade frameworks, or merge changes.
Report tests, retained fallbacks, removed dependencies, and uncertainties.Keep acceptance checks independent of the generated implementation. My earlier AI-assisted testing analysis addresses the danger of tests reinforcing the same assumption as the code. Here, a test that only asserts “a dialog element exists” misses whether anyone can open it.
Compare the resulting patches on observable behavior, shipped JavaScript after bundling, dependency removal, fallback complexity, and review effort. Record failures and repairs as well as successful attempts. One paired run is a useful case study, not a general success rate; repeat on other components before making the skill a team default.
This is a narrower version of the review boundaries for long-running coding agents: better context can improve a proposal without giving its author authority to accept it.
Measure the Page, Not the Promise#
Removing a component library may reduce shipped code—or may remove nothing from the bundle because other components still import it. Measure the production artifact before claiming a dependency or payload saving. Likewise, fewer event listeners are not an end-user performance result.
Google’s Core Web Vitals guidance uses LCP, INP, and CLS to assess loading, responsiveness, and visual stability. Its recommended good thresholds are LCP within 2.5 seconds, INP at or below 200 milliseconds, and CLS at or below 0.1, evaluated at the 75th percentile and segmented by mobile and desktop.
For a migration trial, capture comparable lab traces and representative interactions before and after. Keep device, network conditions, page content, and build settings fixed. Exercise opening, submitting, closing, and reopening the overlay, including its slow or failing network path. Look for layout movement from scrollbars or changed positioning, not just a smaller script file.
Do not label one Lighthouse navigation an INP improvement: the same Web Vitals documentation notes that a simulated page load without user input cannot measure INP. Lab interaction timings can diagnose the change; production field data is needed to assess real-user Core Web Vitals. An infrequently opened settings dialog may improve maintainability without visibly moving page-level percentiles, and that can still be a worthwhile outcome.
Finally, inspect the guidance integration itself. The project’s telemetry disclosure says collection includes agent-generated search queries and retrieved guide IDs, but not raw user prompts, and documents DISABLE_TELEMETRY=1 as the opt-out. Local search does not automatically mean no telemetry. Review that boundary before using private project details in queries, and treat retrieved instructions as advice subordinate to repository policy.
My Take#
Modern Web Guidance is useful because it gives agents a way to consult focused platform knowledge instead of relying entirely on remembered examples. I would adopt it as a reviewed reference layer, not as an instruction to replace every custom component with the newest API.
My first trial would be one modal with explicit browser targets and acceptance tests written before the rewrite. Success would mean less application-owned machinery with the same usable behavior—not simply fewer lines, a native tag, or a vendor evaluation score.
I expect compatibility policy to become more important as agents make large rewrites easier to propose. The team that records who must still be able to use the interface can delegate more implementation work safely. Set that boundary first; then let the agent find the modern solution inside it.
