Modern Web Guidance 提供技能,引導程式碼代理程式採用現代網頁技術
Show HN: Get your coding agent off ~2019 JavaScript, onto modern web primitives
Modern Web Guidance 推出一組可安裝至程式碼代理程式的技能,提供現代網頁平臺指南,協助代理程式使用瀏覽器原生功能與較新的實作模式。
- - 涵蓋內容:包含 CSS、HTML、JavaScript、效能、表單與無障礙等指南,並列出 203 個實務案例。
- CLI 可搜尋指南、依 ID 擷取內容,並掃描程式碼庫中的舊式模式。
AI 伴隨問答
針對這篇報導有疑問?可直接點選快捷問題或向 AI 追問背景脈絡與技術細節:
專案提供 203 個實務案例與多種代理程式安裝方式,並公佈引導前後的任務通過率,呈現其涵蓋範圍與評估依據。
譯文尚未完整,完整內容請切換至原文。
現代網頁指南是一組技能,將網頁平臺專業知識、最佳實務和瀏覽器相容性資料直接整合到你的程式設計代理中。它能引導程式設計代理避開舊式模式,轉而採用善用現代網頁平臺力量與功能的解決方案。
由 Google Chrome、Microsoft Edge、Mozilla Firefox 和 MDN 團隊與網頁開發社群共同維護。
快速入門
npx modern-web-guidance@latest install
這個指令會執行互動式精靈來安裝現代網頁指南。請參閱下方的其他安裝方式。
試用看看(無需安裝)
# Search for relevant guides npx modern-web-guidance@latest search "animate a dialog modal backdrop" # Retrieve a guide by ID npx modern-web-guidance@latest retrieve "animate-to-from-top-layer" # Scan a codebase for legacy patterns to modernize npx modern-web-guidance@latest legacy-scan .
為什麼?
程式設計代理經常採用較舊的模式,因為大型語言模型的訓練資料包含大量舊版程式碼。因此,它們常會為原本已有原生、高效能網頁平臺解決方案的任務,產生冗長的 JavaScript。
即使模型知道某個 API 存在,通常也缺乏足夠豐富的現代實作範例,無法產出可供正式環境使用的程式碼。
現代網頁指南彌補了這個落差。我們的技能 CLI 會將經專家篩選的目標指引直接提供到代理的上下文視窗,著重於:
- 現代瀏覽器 API:協助模型正確組織它們常誤用的 API。
- 效能與無障礙:優先採用可由瀏覽器最佳化,且內建無障礙功能的網頁平臺 API。
- 適切的備援方案:引導模型採用合理、輕量的備援方案,而非笨重的 polyfill 或舊版程式庫。
包含哪些內容?
我們涵蓋過去幾年網頁平臺推出的新功能,一直到最前沿的技術。指南經過精心設計,以節省 token;我們會執行評估,據此刪去模型已熟知、僅適用於最低共同標準的內容。
核心領域
🎨 使用者體驗流暢的視覺狀態(View Transitions、進入/離開動畫、視差捲動、CSS |
📐 CSS 排版現代排版系統(容器查詢、 |
⚡ 效能速度最佳化(即時預載、Interaction to Next Paint (INP) 診斷,以及透過 |
📝 表單與使用者介面原生元件(用於工具提示的 Anchor Positioning、Popover API、對話方塊、 |
♿ 無障礙重要考量(螢幕閱讀器和鍵盤操作、內容導覽與探索)。 |
🤖 內建 AI本機使用者端模型(原生翻譯、摘要和語言偵測 API)。 |
檢視範例:navigation-drawer 指南。
完整清單
250 項現代網頁功能
CSS 與排版(140 項功能)
HTML & DOM(36 項功能)
JavaScript & API(74 項功能)
203 個真實世界的開發者使用案例
無障礙
- accessible-error-announcement:同步程式化無障礙狀態(例如 aria-invalid)與視覺上的 :user-invalid 狀態,確保螢幕閱讀器使用者只在互動後收到錯誤回饋,與視覺體驗一致。
- accessible-generated-content:以無障礙的方式使用 CSS 產生內容(
::before/::after),包括為裝飾性內容提供替代文字。 - respect-os-text-scale:遵循作業系統的文字縮放偏好設定,讓頁面的字型大小、版面配置和以 rem 為基準的尺寸符合使用者的無障礙設定。
內建 AI
- language-detection:偵測使用者產生內容或網站現有內容的語言。
- language-model:使用 Prompt API 在瀏覽器中執行裝置端自然語言推論,支援串流輸出、結構化 JSON 回應,以及多輪對話工作階段管理。
- summarizer:使用裝置端 Summarizer API 摘要文字內容。
- translator:使用裝置端 Translator API 翻譯不同語言的文字。
CSS
- animate-to-intrinsic-sizes:讓互動元件(例如手風琴、選單和展開式卡片)平順地動畫至其自然尺寸,或從自然尺寸縮回。
- atrule-support-conditionals:只有在瀏覽器支援特定 at-rule 時,才有條件地套用某些 CSS 規則或宣告。
- calculate-with-intrinsic-sizes:根據元素的固有尺寸計算其大小,同時確保符合指定的設計限制。
- child-state-based-styling:建立會根據其中一個子元素的狀態改變樣式的元件。例如,元件會根據主題切換鈕是否勾選,呈現淺色或深色模式。
- content-based-styling:建立會根據是否包含特定子元素而改變版面配置的元件。例如,若元件包含圖片,就使用多欄版面配置;否則預設為單欄版面配置。
- css:現代 CSS 架構的行動導向指南,涵蓋層疊、選擇器、作用範圍、巢狀規則和設計權杖。撰寫樣式或管理設計系統時可參考本指南。
- css-layout:現代 CSS 版面配置技術,例如 flexbox、grid、subgrid、容器查詢、錨點定位和固有尺寸。規劃回應式 UI 元件或頁面版面配置時可使用此技能。
- 設計權杖反應性:定義高階設計權杖,例如密度模式(精簡、舒適、寬敞)或主題,讓後代元件直接以符合元件特性的方式回應變更。
- 動態同層元素樣式:建立動態視覺色階或版面配置,讓它們根據群組中的元素數量自動調整。
- 流暢縮放:根據父容器大小平滑縮放字型大小、間距和媒體尺寸等專案,而非使用固定的斷點
- 個別轉換屬性:對單一元素上的個別 CSS transform 屬性(例如 translate、rotate、scale)進行動畫處理或覆寫,不影響其他 transform 屬性。
- 溢位裁切控制:調整元素的可見裁切邊界,使其對齊內容邊緣、內距邊緣或框線邊緣,也可以指定相對於上述邊緣的偏移量,進一步精確控制內容的裁切方式。
- 減少樣式重複:將複雜或動態的樣式邏輯封裝成可重複使用的函式,減少過多的樣式重複(例如根據一組輸入引數計算漸層的函式)。
- 響應式設計:建構能依容器和檢視區大小調整的 UI,涵蓋容器查詢、動態檢視區單位、長寬比和響應式字型排版。
- 選擇器與 at 規則組合:根據選擇器與條件式 @-rules 的交集或聯集指定目標元素,同時減少重複。
- 尺寸感知樣式:建構樣式可依元件本身的寬度或高度(而非檢視區的寬度或高度)有條件地變化的元件。例如,卡片元件可以依自身大小變更版面配置;行動呼籲按鈕則可以依寬度決定是否顯示輔助文字。
- 使用 has 設定父元素樣式:當表單欄位無效時,為其父元素(例如標籤或 fieldset)設定樣式。
- 依使用情境調整元件樣式:使用 CSS 容器樣式查詢,根據語意情境調整元件的視覺邏輯。
表單
- 動畫式選取器:建立下拉選單具有動畫效果的自訂選取元件。例如,選單淡入或滑入畫面,或選項在選取時播放動畫。
- 地址表單自動填入:建構具備正確 autocomplete 屬性與自動填入支援的地址表單。
- 自動填入欄位醒目提示:自訂已自動填入且尚未由使用者編輯的表單欄位樣式
- 付款表單自動填入:建構可收集信用卡資料,並具備正確 autocomplete 值與自動填入支援的付款表單。
- 登入表單自動填入:建構具備正確 autocomplete 值與自動填入支援的登入表單。
- 登錄檔單自動填入:建構具備正確 autocomplete 值與自動填入支援的登錄檔單。
- 符合品牌風格的表單:讓核取方塊、單選按鈕、範圍滑桿和進度列符合網站的色彩配置,不必以自訂元件取代它們。
- 品牌化選取樣式:建立自訂選取元件,讓按鈕、選項面板、箭頭圖示和勾選標記在字型、色彩、間距與邊框樣式上,都能與品牌或設計系統完美一致。
- 自訂選取面板版面配置:建立自訂選取面板,讓選項以獨特或有趣的方式排列,而非傳統的垂直清單。
- 表單欄位自動符合內容大小:讓表單欄位隨使用者輸入內容而放大或縮小,例如使用者輸入文字或選擇其他選項時。設定最大與最小尺寸限制,打造符合頁面設計的動態、回應式表單欄位。
- 安全支援輸入法的 Enter 鍵送出:在文字區域和單行輸入欄位(聊天、搜尋、行內重新命名)中實作按 Enter 鍵送出,並確保輸入法(Input Method Editor,IME)使用者不會送出尚未完成的文字。
- 必填欄位錯誤提示:只有在使用者與必填欄位互動後,才針對略過或留空的欄位顯示錯誤訊息,避免過早顯示錯誤,並確保提示符合時機與使用者操作脈絡。
- 多媒體選取器:建立自訂選取元件,讓選項可包含複雜的 HTML 格式內容(例如圖片、圖示和其他豐富格式),而不只限於純文字。
- 選取選單互動:只有在使用者與選取控制項互動後,才驗證選取選單中是否已選擇非預設選項。
- 滑桿:自訂原生範圍滑桿的軌道、滑塊、填滿區域和焦點狀態,同時保留原生功能與無障礙支援。
- 簡訊 OTP 表單:驗證使用者的電話號碼和透過簡訊傳送的一次性密碼,並支援自動擷取驗證碼及無障礙表單輸入。
- 切換開關:使用原生 HTML switch 屬性打造無障礙切換開關;若瀏覽器不支援,則改用經樣式設計的核取方塊。
- 互動後驗證輸入內容:只有在使用者完成初步操作後,才顯示表單欄位驗證提示(例如密碼複雜度或電子郵件格式要求),避免頁面載入時或使用者輸入期間過早顯示錯誤。
html
- 無障礙網頁元件:讓自訂元素預設具備無障礙支援,透過 ElementInternals ARIA mixin 設定角色和 ARIA 狀態,使用 delegatesFocus 管理焦點,並讓 ARIA 關聯維持在同一個 shadow root 內。
- 自訂元素:定義、註冊並管理自主自訂元素的生命週期,涵蓋建構函式規則、生命週期回呼、升級時機、屬性與 property 的反映,以及命名慣例。
- 關聯表單的自訂元素:透過 formAssociated 和 ElementInternals,讓自訂控制項原生參與表單,提交自身值、整合約束驗證,並處理重設、停用和狀態還原。
- 預先渲染的自訂元素:在伺服器端渲染自訂元素,接著在原處完成 hydration,無須重新渲染,也不會閃現未套用樣式的內容。
- shadow-dom:使用 Shadow DOM 封裝元件的 DOM 與樣式,透過 HTML 範本有效率地建構樹狀結構,並以 slots 投影使用者提供的內容。
- styling-web-components:使用 :host 選取器、繼承屬性與自訂屬性設定主題,並透過 ::slotted 和 ::part 跨越 Shadow DOM 邊界套用樣式;在元件內使用級聯層與容器查詢。
- web-components:介紹撰寫與使用 Web Components 的基本概念和通用原則,涵蓋 Custom Elements、Shadow DOM、範本與 slots、宣告式 Shadow DOM、跨越 Shadow DOM 邊界套用樣式、與表單關聯的自訂元素,以及無障礙需求。建立可重複使用的 UI 元件、設計系統或伺服器端轉譯的自訂元素時,請參考本指南。
js
- calculate-event-differentials:計算日期與時間之間經過或剩餘的時間,平衡時間長度單位,並使用 Temporal.Duration 和 Intl.DurationFormat 格式化成易讀的在地化時間長度。
- capture-location-agnostic-data:使用 Temporal Plain 型別表示不受地點影響的日曆日期、壁鐘時間、部分日期(例如週年生日、信用卡到期日)和每月重複的時間間隔,避免因時區變動而產生偏差。
- coordinate-global-events:明確指定地理位置的 IANA 時區,安排未來的會議或活動,確保活動時間不受日光節約時間(DST)轉換,以及時鐘變更時「略過」或「重複」的時段影響。
- sort-high-precision-timestamps:使用 Temporal.Instant 剖析、排序並測量 ISO 8601 時間戳記之間的間隔,避免 Date 截斷次毫秒或奈秒精度的時間戳記,導致時間戳記碰撞。
- support-global-calendar-systems:為國際使用者準確顯示及計算非格里曆曆法系統(例如伊斯蘭曆、希伯來曆或中國曆法)的日期。
效能
- batch-analytics-events:使用防抖動將多個分析、遙測和 Core Web Vitals 事件批次合併到單一 beacon 中,以減少網路競爭和伺服器負載,同時仍能即時更新。
- break-up-long-tasks:拆分繁重的同步處理工作(複雜運算和/或冗長迴圈)或 DOM 更新,以提升 Interaction to Next Paint(INP)的回應速度,並讓瀏覽器能處理使用者輸入和重繪畫面。
- calculate-total-foreground-time:計算使用者實際瀏覽頁面的總時間,不包含分頁位於背景時的時間。
- conditional-async-dependencies:有條件地載入或初始化非同步相依專案(例如為缺少的網頁功能匯入 polyfill),無須對頁面中所有指令碼相依專案進行複雜的協調。
- defer-rendering-heavy-content:透過延後轉譯使用者目前無法立即看到的內容,縮短內容量大的網頁(例如包含長篇動態訊息、大量文章或複雜儀錶板的頁面)的轉譯時間。
- defer-work-until-scroll-ends:延後執行耗費資源的作業,例如 DOM 更新、資料擷取、分析追蹤或版面配置重新計算,直到捲動結束後才執行,以維持流暢的捲動效能。
- deliver-optimized-decorative-images:同時提供新一代圖片格式(例如 AVIF 或 WebP)及多種畫素密度版本(例如 1x 和 2x),以最佳化方式傳送裝飾圖片(例如背景、UI 圖示或複雜遮罩),讓瀏覽器根據使用者裝置的能力,動態協商檔案大小與視覺品質的最佳組合。
- deprioritize-background-fetches:降低透過 Fetch API 發出的背景資料擷取優先順序,避免與使用者主動發出的請求爭用網路資源。
- detect-initial-visibility-state:可靠判斷頁面最初是否在背景中載入,即使使用者已將頁面切換到前景後,指令碼才以非同步方式載入,也能判斷。
- efficient-background-processing:當元件位於畫面外時,暫停背景 JavaScript 執行(例如
<canvas>動畫、WebGL 繪製或高頻率 WebSocket 資料輪詢),以節省系統資源和電池電力;待元件重新捲動至畫面中時,再即時恢復執行。 - faster-spa-view-transitions:保留先前造訪畫面的結構性 DOM 狀態,而非每次導覽時都將其銷毀並重新建立,藉此加快單頁應用程式(SPA)切回先前畫面的速度。
- flicker-free-client-side-ab-testing:使用使用者端 JavaScript 執行 A/B 測試、多變數測試或其他實驗,以修改或插入 HTML、CSS 和 JavaScript,並在原始內容先顯示後閃爍切換成實驗內容之前,就先呈現實驗結果。
- full-session-analytics:在使用者整個造訪頁面的期間,可靠追蹤分析資料、Core Web Vitals、錯誤和遙測資料,並延後至使用者離開頁面後才傳送資料。
- identify-heavy-scripts:找出最容易造成動畫影格時間過長的指令碼
- identify-inp-causes:找出執行緩慢的 JavaScript,以及造成互動至下一次繪製(INP)回應速度不佳的其他原因。
- improve-next-page-load-performance:預先擷取或預先呈現使用者可能接著造訪的頁面,以改善頁面載入效能。
- interaction-paint-timing:測量使用者互動和使用者端導覽所觸發的新內容更新在螢幕上呈現所需的時間。
- interactions-in-complex-layouts:避免複雜版面配置(例如資料量龐大的儀錶板或試算表式格線)重新計算版面配置,讓互動更迅速、回應更即時,並降低互動至下一次繪製(INP)分數。
- lazy-load-video-and-audio:延後下載畫面外的影片和音訊資源,包括影片海報圖片和預先載入的媒體資料,直到媒體播放器接近視埠才下載,以節省頻寬並減少初次載入頁面時的網路資源爭用。
- optimize-image-priority:調整最大內容繪製(LCP)候選圖片的載入優先順序,並降低非關鍵圖片的優先順序,以減少關鍵資源載入延遲。
- optimize-preload-priority:調整預先載入內容的相對優先順序,以減少關鍵資源載入延遲。
- optimize-script-priority:調整指令碼的載入優先順序,提升關鍵非同步指令碼的優先順序,並降低非必要指令碼或位於本文底部的指令碼的優先順序,以改善載入順序並減少延遲。
- out-of-order-html-streaming:以宣告式方式更新頁面,將稍後串流至同一份 HTML 檔案的內容納入頁面,或透過命令式 JavaScript API 更新。
- resolution-optimized-pseudo-elements: Use resolution-optimized images in CSS pseudo-elements (such as
::beforeand::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.
privacy
- privacy: Action-oriented guidelines for web developers to implement privacy by design, data minimization, third-party audits, and secure data handling. Use this skill when designing applications, integrating third-party services, handling user data, or configuring security headers.
pwa
- install-web-app: Install web applications from a page using browser-controlled consent UI.
- migrate-web-app-origin: Transfer an installed web app to a new origin while preserving user configuration and OS-level shortcuts.
security
- client-side-encryption: Establish shared secrets using public-key encapsulation or key agreement—including hybrid and post-quantum protection—and encrypt sensitive data in the browser with authenticated encryption.
- digital-signatures: Sign and verify messages, tokens, or artifacts in the browser using classical or quantum-resistant (post-quantum) asymmetric keys to ensure data integrity and authenticity.
- local-network-access: Access resources on a user's local network or loopback interface from a public web application.
- passkey-authentication: Authenticate a returning user with a passkey for primary sign-in.
- passkey-conditional-create: Silently register a passkey for an existing user after a successful password login.
- passkey-management: Let users view and manage the passkeys registered to their account.
- passkey-reauthentication: Verify a signed-in user's identity using their existing passkeys before a sensitive action.
- passkey-registration: Register a passkey for an existing user account.
- passkeys: Comprehensive orientation and cross-cutting principles for implementing WebAuthn and Passkeys in web applications. Use this guide when handling passkey registration, authentication, management, or reauthentication.
- quick-sign-ins: Authenticate returning users in place with their saved passkeys or passwords before navigating to a sign-in page or interrupting their workflow.
- restrict-outbound-connections: Restrict a page or worker to communicating only with an explicit allowlist of network endpoints to prevent unauthorized third-party requests and client-side data exfiltration.
- sanitize-untrusted-html: Safely parse and display untrusted HTML content from user input by removing unsafe elements and attributes.
- secure-external-subresources: Verify the cryptographic integrity of external scripts, stylesheets, fonts, and images loaded from third-party origins, and control whether those requests send credentials or referrer URLs.
- trusted-types: Prevent DOM-based XSS attacks by defining a Trusted Types policy to sanitize untrusted HTML, using the policy when writing to DOM sinks like innerHTML, and enforcing Trusted Types via Content Security Policy.
- validate-origins: Compare and validate web origins and sites safely across cross-document messages and URLs without error-prone string parsing.
- verify-email-ownership: Verify that a user owns an email address during account creation, sign-in, or recovery without sending a one-time passcode or magic link email.
ui-atoms
- 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.
- component-specific-light-dark-theme: Force certain elements to be in light mode or dark mode (e.g. code blocks, media players, etc) independently of the page's color-scheme.
- icons: Display and manage icons that can be set and parameterized from CSS, are fast to load, crisp at any resolution and are properly exposed to (or hidden from) assistive technologies.
- position-aware-tooltips: Build tooltips and popovers with directional arrows (or other visual styling) that automatically point the correct way when the element flips to a fallback position.
- pull-to-reveal: Build a pull-to-reveal feature that would enable the user to pull down on the screen to reveal more content, like a search bar.
- responsive-table: Build a data table that presents tabular data with proper header semantics, and remains readable and navigable on small screens and with assistive technologies.
- scroll-position-aware-elements: Build floating buttons or widgets (back-to-top, scroll-to-bottom, chat launchers, etc.) that appear and disappear based on whether the user has scrolled at all.
- scroll-progress-indicator: Create a scroll progress bar, stepped progress tracker, or any visual affordance that communicates how far through a page or section the user has scrolled.
- scrollability-affordance-hints: Build scroll shadows or fading edges that appear only when there's actually more content to scroll to in that direction.
- shrinking-header-on-scroll: Smoothly animate a fixed header or full-page cover on scroll to dynamically shrink, gain shadows, and transform its layout over a predefined scroll distance.
- single-line-overflow: Show text that must stay on one line, such as a tab label, table cell, navigation item, or file name, in a space it may not fit, without breaking the layout or losing the text.
- state-aware-sticky-headers: Build sticky section headers or navbars that visually transform when they're actually "stuck" at the top, changing their color scheme or gaining a shadow.
- viewport-aware-dropdowns: Position dropdowns, flyouts, or contextual action panels tethered to a trigger button so they automatically flip axes at viewport edges instead of getting clipped.
ui-behaviors
- 2d-panning: Allow users to freely pan or scroll two-dimensional surfaces—such as maps, zoomed images, infinite canvases, or large data grids—across both directions (whether diagonally or changing direction mid-gesture) without the gesture locking to a single horizontal or vertical axis.
- 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.
- 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.
- 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.
- 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.
- custom-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.
- 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.
- drag: Support dragging to move a floating element around the page.
- drag-and-drop: Support dragging to rearrange the children of a container along one axis (horizontal or vertical) while preserving their state and accessible order.
- 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-sort: Best practices for handling dynamic user-triggered reordering of a container's children (e.g. list items, table rows, or a card grid), with optional animated reordering that respects user preferences, good screen reader UX, and optimal performance for large lists.
- group-element-transitions: Smoothly rearrange and animate list items, cards, or grid elements into their new positions simultaneously when adding, removing, shuffling, or reordering—such as removing a product from a shopping cart.
- highlight-text-ranges: Highlight arbitrary text ranges on a page such as search results, spelling errors, or collaborative editing cursors.
- 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)
- motion: Animate UI with CSS transitions, animations, scroll-driven animations, and view transitions while keeping motion on the compositor and respecting reduced-motion preferences.
- move-dom-element-without-losing-state: Move or reparent a DOM element without losing important element state, such as interactivity states (:focus/:active),
<iframe>loading state, animation/transition state, etc - parallax-scroll-effects: Create scroll-based effects (such as parallax) where foreground and background layers move at different rates, creating a sense of depth as the user scrolls.
- persistent-top-layer-ui: Keep a modal dialog, fullscreen element, or native popover visibly open and functionally active when its underlying DOM node is moved or reparented in the DOM.
- physics-based-easing: Create custom, physics-based animation and transition effects, like bounce and spring, that feel more natural and engaging than traditional easing curves.
- platform-controls-dismiss-dialog: Create a modal dialog that can be closed via standard platform-specific user actions, such as pressing the
Esckey on desktop platforms, or a "back" or "dismiss" gesture on mobile platforms - prevent-page-scroll-under-modal-dialog: Prevent the underlying page from scrolling while a modal dialog is open.
- same-document-transitions: Visually connect persisting elements across different page states or navigations in a Single Page Application (SPA) (e.g. expanding a product thumbnail into a full-bleed hero image) by smoothly morphing their size, position, or other styling properties.
- scoped-component-transitions: Animate state changes inside a single component (a card, list, panel, or other subtree) while the rest of the page remains interactive, and other transitions run concurrently.
- scroll-completion-effects: Trigger visual effects, animations, or focus changes on a target element only after a smooth programmatic scroll to that element has finished.
- scroll-entry-exit-effects: Create fade-in, scale-up, or other complex reveal-type effects on elements as they enter and exit the scrollport (or viewport) while the user is scrolling.
- scroll-snap-realtime-feedback: Provide real-time visual feedback in linked UI elements while a user scrolls through snap-aligned content, before the scroll gesture completes.
- scroll-snap-state-sync: Synchronize navigation indicators, linked content panels, and analytics tracking with the actively snapped item in a scrollable container.
- scroll-target-on-load: Build a scrollable list of elements (e.g. a carousel of images or a chat conversation thread) that can be displayed with a particular element scrolled into view on the initial render.
- scrollytelling: Animate visual properties on a target element — such as fading a backdrop, shifting a background color, or to create scrollytelling experiences — driven entirely by the scrollport position of a completely different element.
- search-hidden-content: Hide content from view using patterns such as accordions, tabs, and "Read more" sections, while ensuring the hidden text reveals itself during native "Find in page" searches, allows search engine indexing, supports URL fragment deep links, and maintains ARIA accessibility.
- sortable-table: Progressively enhance a data table with behaviors that allow users to sort rows by clicking on column headers.
- spatial-navigation: Implement accessible spatial navigation using arrow keys that works correctly in different layout modes (grid etc)
- swipe-to-remove: Let users act on items in a list (remove, archive, mark as read, etc.) with a horizontal swipe gesture, so they can process entries quickly without tapping a separate control.
- swipe-to-reveal: Let users swipe horizontally on a list item or content pane to reveal contextual action buttons or a side menu without automatically triggering an action.
ui-components
- accordion: Build an accordion component with animation, optional exclusive (one-open-at-a-time) behavior, and brand-consistent styling.
- app-menus: Build an application menu bar where several top-level menus (such as File, Edit, and View) act as a single keyboard stop and switch between each other on hover or arrow keys.
- breadcrumbs: Build a breadcrumb trail that shows the user's location within a site hierarchy and lets them navigate to ancestor pages.
- card: Build a card component that adapts its presentation to its own available space and contents.
- carousel: Build a carousel component that displays a set of items in a horizontal or vertical layout.
- checkbox: Style checkboxes, including custom icons, layout, colors, check/uncheck animations, while preserving native functionality and accessibility.
- copy-button: Build a copy button that copies text from arbitrary elements to the clipboard.
- dark-mode-toggle: Build a dark mode toggle component that allows users to override their system color scheme preference for the current site.
- dialog: Build a modal or non-modal dialog component that is accessible, manages focus appropriately, and can be dismissed the way users expect on each platform.
- hovercard: Build a hovercard component that displays an interactive structured preview of the page a certain type of link (e.g. a user profile) will navigate to when hovered over.
- menu: Build a menu component that displays a list of options or actions, with support for nested submenus.
- navbar: Build a site navigation bar that adapts across screen sizes and indicates the current page.
- navigation-drawer: Create a navigation drawer component that, when triggered from a menu button, slides in from the side overlaid on top of existing page content, and slides out when dismissed (by swiping away, tapping outside, or pressing escape).
- persistent-app-tours: Create persistent onboarding walkthroughs using tethered native overlays that stay open during user interaction.
- persistent-toast-notifications: Create non-intrusive toast and overlay notifications for persistent, stackable messaging and state communication.
- progress: Build a styled progress bar that communicates completion of a task or process, in both determinate and indeterminate states.
- progress-ring: Build a progress ring component that visually represents the completion status of a task or process, with support for content in the center and brand-consistent styling.
- scrollspy: Highlight the currently visible section of a page in a navigation menu
- spinner: Build a loading spinner that communicates busy state to all users, respects reduced-motion preferences, and animates efficiently.
- stack-drill-down: Build full-screen hierarchical navigation that lets users drill down into nested views and swipe or navigate back to return, with browser history kept in sync.
- tabs: Build a responsive tabbed interface with good UX when not all tabs fit on screen.
- toolbar: Build a toolbar component that displays a set of controls for performing actions.
user-experience
- content-first-noise-reduction: Maximize content and reduce noise by removing blocking popups, keeping persistent navigation compact, and moving secondary content behind on-demand disclosure.
- form-factor-adaptation: Adapt layouts, controls, and text to any device or container so touch targets stay usable, content fits its space, and nothing collides with system UI.
- natural-interactions: Implement natural interactions with clear hover, focus, and press feedback, motion that opens from its trigger, swipeable content, and keyboard-reachable actions.
visual-design
- adapt-scrollbar-to-contrast-preferences: Enhance scrollbar visibility for users who prefer high-contrast interfaces
- apply-webgl-shaders: Apply custom visual effects with WebGL shaders to HTML content.
- browser-ui-theming: Theme browser-generated UI such as text selection, scrollbars, form controls, and pickers with CSS instead of re-creating it with custom elements.
- color: Color guidance for the web, including contrast requirements, light and dark color schemes, Forced Colors Mode, and generating tints and shades from a base color.
- complex-shapes: Clip elements and their content to any free-form shape, like a symbol, brush stroke, or organic texture for more expressive designs.
- contrast-color: Select a readable text color with sufficient contrast on a dynamic background color.
- custom-text-decorations: Add text decorations such as underlines, overlines, strikethroughs, or entirely custom shapes, with reveal animations, custom offsets and end insets, and flexible ink skipping.
- customize-scrollbar-color-and-thickness: Customize the color or thickness of a scrollbar
- dark-mode: Implement dark mode support in a way that respects the user's light/dark theme preference and adapts browser UI (e.g. scrollbars, form controls, etc)
- equal-width-text-lines: Make every line of a multi-line heading or lockup span the same width, as in poster-style or stacked-headline typography. Unlike justified text, the text itself is sized to the width rather than the spacing stretched
- export-html-media-from-canvas: Capture and export dynamic HTML content as images or video frames from within canvas.
- expose-canvas-content-to-browser-features: Expose content rendered in a canvas to browser features like assistive technologies, translation, or reading mode.
- 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.
- interactive-content-in-3d-scenes: Integrate interactive HTML elements into a 3D scene.
- precise-text-alignment: Achieve precise vertical alignment with text of any font. For example, exactly equal visual padding above and below text, or aligning text perfectly flush with adjacent icons or images.
- shaped-cutouts: Combine multiple shapes to create complex cutouts or 'knockout' effects in elements, such as adding a notch to an element.
- soft-edge-content-fade: Apply a transparency gradient to content edges to indicate further scrollable areas or to obscure payment-walled text.
- typography: Typography best practices for the web, including font sizing units, line height, text wrapping and balancing, and fluid type that scales with the viewport.
- visual-effects: Visual effects with CSS such as layered shadows, blend modes, gradients with predictable color interpolation, and patterns like stripes, checkerboards, dots, and pie charts built from gradients alone.
- visually-stable-font-fallbacks: Define font styles such that text remains readable and visually consistent in the event that there's a swap between the preferred font and one of the fallbacks (or vice versa).
- visually-stable-mixed-fonts: Define font styles such that text remains readable and visually consistent in situations where multiple fonts are used to render a single block of text.
- visually-texture-content: Apply realistic weathering and texture patterns to elements to give them an organic, aged, or physical material appearance.
wasm
- cpp-on-the-web: Compile C/C++ to WebAssembly using Emscripten
webmcp
- agentic-forms: Expose client-side functionality as tools to AI agents by annotating standard HTML forms with WebMCP attributes.
- agentic-javascript-tools: Programmatically register client-side JavaScript functions as tools for AI agents using the WebMCP Imperative API.
- webmcp: Use this guide to implement WebMCP in browser applications, exposing client-side functionality as tools to AI agents via declarative or imperative APIs.
Safe Adoption of Modern Features
- Progressive Enhancement & Nuanced Fallbacks: We distinguish between purely additive enhancements (like speculative preloading) which are safe to let older browsers silently ignore, and critical behaviors (like dialog controls or network beacons) where we write highly considered, low-overhead fallbacks.
- Responsible Fallbacks: We prioritize lightweight, case-specific custom fallbacks (<50 LOC) or conditionally-loaded polyfills instead of heavy third-party bundles.
- Gotchas & Quirks: We document hidden platform limitations, such as the 64KB payload quota for
fetchLater()or macOS-specific scrollbar behaviors. - Baseline-Aware Integration: We leverage real-time compatibility data from the Baseline project so agents dynamically adapt to current browser support.
- Origin Trial & Volatile Feature Gates: Guides covering experimental Origin Trial APIs or volatile features (single-engine features shipped within the last 3 months or still stabilizing) remain discoverable via
search, but are gated onretrieveso agents do not adopt unstable APIs without explicit developer consent.
Project Configuration (.mwgrc)
Configure Origin Trial and volatile feature opt-ins for a repository with an optional .mwgrc JSON file in your project root (or ~/.mwgrc as a user-level fallback), which you can commit to share across your team:
| CLI Command | .mwgrc Key |
Effect |
|---|---|---|
npx modern-web-guidance@latest set-allow-origin-trials |
"allowOriginTrials": true |
Unlocks guides for experimental Origin Trial APIs. |
npx modern-web-guidance@latest set-allow-volatile-features |
"allowVolatileFeatures": true |
Unlocks guides for volatile single-engine features. |
How It Works
- Activation: The coding agent activates the
modern-web-guidanceskill because of a relevant task. The agent is instructed to use themodern-web-guidanceCLI for web platform queries. - Local Semantic Search: The agent runs
modern-web-guidance search "<query>". The tool matches the query to the best guide using an offline, zero-dependency embedding model and BM25 search engine (no network calls, no API keys). - Guide Fetch: The agent retrieves the guide via
modern-web-guidance retrieve <guide-id>, inserting targeted code patterns, gotchas, and fallbacks directly into its context window.
Tip
Note: We use npx to ensure the content doesn't go stale, but the CLI works offline, completely private and local.
The npm package is self-contained, with no extra dependencies to ensure both low-latency and supply-chain security.
Alternative Installation Methods
Vercel Skills CLI (aka npx skills)
npx skills add GoogleChrome/modern-web-guidance
GitHub CLI
gh skill install GoogleChrome/modern-web-guidance
Google Antigravity
agy plugin install https://github.com/GoogleChrome/modern-web-guidance
GitHub Copilot CLI
/plugin marketplace add GoogleChrome/modern-web-guidance /plugin install modern-web-guidance@googlechrome
Claude Code Plugin
/plugin marketplace add GoogleChrome/modern-web-guidance
/plugin install modern-web-guidance@googlechrome
/plugin # Select GoogleChrome marketplace, press enter, enable AutoUpdate
/reload-pluginsGrok Build CLI
grok plugin install https://github.com/GoogleChrome/modern-web-guidance --trust
Kimi Code
/plugins install https://github.com/GoogleChrome/modern-web-guidance
OpenAI Codex
codex plugin marketplace add GoogleChrome/modern-web-guidance codex plugin add modern-web-guidance@googlechrome
Updating
If you installed the skill using npx modern-web-guidance@latest install, you can update with: npx modern-web-guidance@latest update.
Otherwise, consult your agent's documentation for updating plugins and skills.
Evals to prove this works well
We developed a robust eval harness to ensure that the content is empirically proven and continuously calibrated so AI agents write better code. We run automated evaluations using a closed-loop validation pipeline:
[ Expert-authored guidance and demo ]
│
▼
[ Target generation ] ──> Tasks on real webapps, Golden solutions, Playwright graders
│
▼
[ Calibration loop ] ───> Runs Grader on Golden Solutions (Must Pass 100%)
│ Runs Grader on Unmodified Base App (Must Fail 100%)
▼
[ E2E agent evals ] ────> Runs coding agents in guided vs. unguided modes
Compares pass rates and accessibility w/ and w/o the skill
- Simulated Developer Tasks: We define realistic developer prompts against full base applications (
daily-grind,devtools-times) that mimic real-world requests (e.g., "make my images load faster"). Prompts avoid naming APIs or features, testing whether the agent can naturally discover and apply the right guides. - Static & Browser-Based Assertions: Playwright graders verify that each implementation requirement was followed—checking source patterns, computed styles, runtime DOM behaviors, and accessibility states.
- Self-Healing Calibration: Graders are calibrated against multi-agent (Claude/Codex/AGY) golden solutions (100% pass target) and an unmodified baseline application (0% pass target).
- E2E Testing: We measure coding agent performance on real tasks with and without guidance. The opportunity (100% - unguided pass rate) and uplift (guided - unguided pass rate) are key: if models already succeed without guidance, we prune redundant advice; where agents struggle, we refine guides to maximize uplift.
Recent eval results snapshot
Explore full per-agent and per-guide breakdowns on the Eval Dashboard.
| Date | Agent + Model | Tasks / Assertions | Unguided → Guided (Uplift) |
|---|---|---|---|
| Nov 8 | antigravity_cli (gemini-4-argon) | 214 / 1673 | 58% → 94% (+36pp) |
| Nov 8 | codex_cli (gpt-6.1-sol) | 215 / 1795 | 54% → 82% (+28pp) |
| Nov 8 | claude_code (opus-5-5) | 215 / 1801 | 57% → 88% (+31pp) |
| Nov 6 | codex_cli (gpt-6.1-sol) | 212 / 1773 | 53% → 86% (+33pp) |
| Nov 6 | claude_code (opus-5-5) | 212 / 1773 | 56% → 90% (+34pp) |
| Nov 6 | antigravity_cli (gemini-4-argon) | 212 / 1722 | 60% → 96% (+36pp) |
| Nov 4 | codex_cli (gpt-6.1-sol) | 209 / 1743 | 52% → 85% (+33pp) |
| Nov 4 | claude_code (opus-5-5) | 209 / 1743 | 57% → 90% (+33pp) |
| Nov 4 | antigravity_cli (gemini-4-argon) | 207 / 1722 | 60% → 96% (+36pp) |
| Nov 2 | codex_cli (gpt-6.1-sol) | 205 / 1729 | 55% → 82% (+27pp) |
Available Skill Packs
You can customize which skill packs are installed using the --choose flag:
npx modern-web-guidance@latest install --choose
modern-web-guidance(~205 tokens): Comprehensive guidance on modern browser APIs, layouts, and performance.chrome-extensions(~175 tokens): Guidance on Manifest V3, background workers, extension APIs, and Chrome Web Store publishing.
Telemetry & Privacy
Google collects anonymous usage information to improve the tool's reliability, relevance, and performance. Collected information includes installation counts, the calling agent name, guide retrieval IDs, and CLI tool search queries generated by the agent (e.g. "dark mode scrollbar color-scheme"). Raw user prompts are not collected. You can inspect what is collected in modern-web.ts.
Tip
To Opt-Out: set the DISABLE_TELEMETRY=1 env variable in your shell profile (e.g., .bashrc or .zshrc):
export DISABLE_TELEMETRY=1Google handles this data in accordance with the Google Privacy Policy.
Contributors
Found a bug, outdated pattern, or missing web platform feature? Open an issue or see CONTRIBUTING.md in the source repository (GoogleChrome/modern-web-guidance-src).
Huge thanks to everyone who has contributed!
License
Unless otherwise noted:
- Software code in this project is licensed under the Apache License 2.0.
- Documentation and guide content under
guides/are licensed under Creative Commons Attribution 4.0 International (CC-BY 4.0).
Portions of the documentation in this project are derived from MDN Web Docs by Mozilla Contributors and W3C, WHATWG, and IETF specifications.