Modern Web Guidance 為編碼智能體提供現代 Web 技能指引
Show HN: 让你的编程助手摆脱 2019 年的 JavaScript,转向现代 Web 原语
Modern Web Guidance 是一套供編碼智能體使用的技能,將 Web 平台知識、最佳實踐及瀏覽器相容性資料直接納入智能體的上下文。它涵蓋 250 項現代 Web 功能,CLI 可在本機離線搜尋及擷取指引,毋須網絡連線或 API keys;專案位於 https://github.com/GoogleChrome/modern-web-guidance。
它把專家整理的瀏覽器指引接入智能體檢索,並以真實網頁任務比較有無指引的通過率,展示這類技能的評估方法。
Modern Web Guidance 是一套技能,將網頁平台專業知識、最佳做法及瀏覽器相容性資料直接整合至你的編碼 Agent。它有助引導編碼 Agent 避免使用過時模式,轉而採用善用現代網頁平台功能與能力的方案。
由 Google Chrome、Microsoft Edge、Mozilla Firefox 及 MDN 團隊,聯同網頁開發社羣共同維護。
快速入門
npx modern-web-guidance@latest install
此命令會執行互動式精靈以安裝 Modern Web Guidance。請參閲下方的其他安裝方法。
試用(無需安裝)
# 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 .
為甚麼?
編碼 Agent 往往會預設使用較舊的模式,因為 LLM 訓練資料包含大量過時程式碼。因此,它們經常會為一些現今已有原生、高效能網頁平台方案的工作,產生臃腫的 JavaScript。
即使模型知道某個 API 存在,往往也缺乏足夠多的現代實際實作模式,難以產生可用於正式環境的程式碼。
Modern Web Guidance 填補了這個缺口。我們的技能 CLI 會將經專家策劃的針對性指引直接提供至 Agent 的上下文視窗,重點包括:
- 現代瀏覽器 API:協助模型正確使用它們經常誤用的 API。
- 效能與無障礙功能:優先採用可由瀏覽器最佳化,並內置無障礙支援的平台層級 API。
- 恰當的後備方案:引導模型採用合理而輕巧的後備方案,而非使用大型 polyfill 或過時程式庫。
內容包括甚麼?
我們涵蓋網頁平台過去數年推出的新功能,直至最新技術。指引經過精心設計,以提高 token 使用效率;我們會進行評測,剔除模型已掌握的最基本內容。
核心範疇
🎨 用戶體驗流暢的視覺狀態(View Transitions、進場/離場動畫、視差捲動、CSS |
📐 CSS 版面配置現代版面配置系統(容器查詢、 |
⚡ 效能速度最佳化(即時預載、Interaction to Next Paint (INP) 診斷,以及透過 |
📝 表單與 UI原生元件(用於工具提示的 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 架構指引,涵蓋層疊、選擇器、範圍界定、巢狀規則及設計 token。編寫樣式或管理設計系統時,可使用此指南。
- css-layout:現代 CSS 版面配置技術,例如 flexbox、grid、subgrid、容器查詢、錨點定位及固有尺寸。設計響應式 UI 元件或頁面版面配置時,可使用此技能。
- 設計 token 反應性:定義高階設計 token,例如密度模式(緊湊、舒適、寬敞)或主題,讓後代元件可直接以符合元件特性的方式,對變化作出反應。
- 動態兄弟元素樣式:建立動態視覺光譜或版面配置,令其可根據羣組中的元素數目自動調整。
- 流暢縮放:根據父級容器的大小,而非使用固定斷點,平滑地調整字體大小、間距及媒體尺寸等項目的大小。
- 個別 transform 屬性:在同一個元素上獨立於其他 transform 屬性,為個別 CSS transform 屬性(例如 translate、rotate、scale)加入動畫或覆寫其設定。
- 溢出裁切控制:調整元素的可見裁切邊界,使其對齊內容邊緣、內距邊緣或邊框邊緣,亦可設定相對於上述任一邊緣的偏移量,從而更精細地控制內容的裁切方式。
- 減少樣式重複:將複雜或動態的樣式邏輯封裝成可重用函式,以減少過多的樣式重複(例如根據一組輸入參數計算漸變的函式)。
- 響應式設計:建構可配合容器及視口大小調整的 UI,包括容器查詢、動態視口單位、長寬比及響應式字體排版。
- 選擇器與 at-rule 組合:根據選擇器與條件式 @-rules 的交集或聯集來指定元素,同時盡量減少重複。
- 尺寸感知樣式:建構樣式可視乎元件本身的闊度或高度而有條件地變化,而非取決於視口的闊度或高度。例如,卡片元件可按自身大小變更版面配置;行動呼籲按鈕亦可按闊度有條件地顯示輔助文字。
- 使用 :has 設定父元素樣式:當表單欄位無效時,為其父元素(例如標籤或欄位集)設定樣式。
- 按使用情境調整元件樣式:使用 CSS 容器樣式查詢,根據語意情境調整元件的視覺邏輯。
表單
- 動畫選取器:建立自訂選取元件,並為其下拉式選單加入動畫效果。例如,選單會淡入或滑入畫面,或選項會在選取時播放動畫。
- 支援自動填寫的地址表單:建構設有正確 autocomplete 屬性並支援自動填寫的地址表單。
- 自動填寫欄位醒目顯示:自訂已自動填寫、但尚未經用戶編輯的表單欄位樣式。
- 支援自動填寫的付款表單:建構可收集信用卡資料,並設有正確 autocomplete 值及支援自動填寫的付款表單。
- 支援自動填寫的登入表單:建構設有正確 autocomplete 值並支援自動填寫的登入表單。
- 支援自動填寫的註冊表單:建構設有正確 autocomplete 值並支援自動填寫的註冊表單。
- 符合品牌風格的表單:配合網站的色彩配搭設計核取方塊、單選按鈕、範圍滑桿及進度列,而無須以自訂元件取代它們。
- 品牌專屬選取樣式:建立自訂 select 元素,讓按鈕、選項面板、箭頭圖示和剔號均能與品牌或設計系統的字體、色彩、間距和邊框樣式無縫配合。
- 自訂選取器版面配置:建立自訂選取器,讓選項以獨特或有趣的方式排列,而非採用傳統的堆疊式選項清單。
- 表單欄位自動配合內容調整大小:讓表單欄位隨用戶輸入內容擴大或縮小,例如用戶輸入文字或選擇其他選項時。設定大小上限和下限,建立動態且回應迅速的表單欄位,使其配合頁面設計。
- 輸入法安全的 Enter 鍵提交:在文字區域和單行輸入欄位(聊天、搜尋、即時重新命名)中實作按 Enter 鍵提交功能,同時兼顧輸入法編輯器(Input Method Editor,IME)用戶,避免提交尚未完成的文字。
- 必填欄位提示:只有在用戶與表單互動後,才為被跳過或留空的必填欄位顯示錯誤訊息,避免過早提示錯誤,並確保提示適時且切合用戶當前的操作流程。
- 豐富媒體選取器:建立自訂選取元件,讓選項可包含複雜的 HTML 格式(例如圖片、圖示及其他豐富格式),而不只限於純文字。
- 選取選單互動:只有在用戶與選取控制項互動後,才驗證用戶是否已在選單中選擇非預設選項。
- 滑桿:為原生範圍滑桿設定自訂軌道、滑塊、填充部分和焦點狀態的樣式,同時保留原生功能和無障礙功能。
- SMS 一次性密碼表單:驗證用戶的電話號碼及透過 SMS 傳送的一次性密碼,並支援自動擷取驗證碼和無障礙表單輸入。
- 切換開關:使用原生 HTML switch 屬性建立無障礙切換開關;若不獲支援,則改用設有樣式的核取方塊。
- 互動後驗證輸入內容:只在用戶完成首次互動後,才顯示表單欄位驗證提示(例如密碼複雜度或電郵格式要求),避免在載入頁面時或用戶輸入期間過早顯示錯誤。
html
- 無障礙網頁元件:讓自訂元素預設具備無障礙功能,透過 ElementInternals ARIA 混入設定角色和 ARIA 狀態,使用 delegatesFocus 管理焦點,並確保 ARIA 關係維持在同一個 shadow root 內。
- 自訂元素:定義、註冊及管理獨立自訂元素的生命週期,涵蓋建構函式規則、生命週期回呼、升級時機、attribute 與 property 的反映,以及命名慣例。
- 與表單關聯的自訂元素:使用 formAssociated 和 ElementInternals,讓自訂控制項以原生方式參與表單,提交自身的值、整合約束驗證,並回應重設、停用和狀態還原。
- 預先呈現自訂元素:在伺服器端呈現自訂元素,然後在原位為其進行水合,無須重新呈現,也不會閃現尚未套用樣式的內容。
- shadow-dom:使用 Shadow DOM 封裝元件的 DOM 和樣式,透過 HTML 範本高效建構樹狀結構,並以 slots 投影使用端內容。
- styling-web-components:使用 :host 選擇器跨越 Shadow DOM 邊界設定樣式,運用繼承屬性和自訂屬性設定主題,並在元件內使用 ::slotted、::part、級聯層和容器查詢。
- web-components:介紹編寫和使用 Web Components 的基本概念及通用原則,涵蓋 Custom Elements、Shadow DOM、範本與 slots、宣告式 Shadow DOM、跨越 Shadow DOM 邊界設定樣式、與表單關聯的自訂元素(Form-Associated Custom Elements),以及無障礙要求。建立可重用 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:延後呈現用戶目前看不到的內容,以縮短內容繁多的網頁(例如有長篇動態消息、大量文章或複雜儀錶板的頁面)的呈現時間。
- 捲動結束後才執行工作:延後執行 DOM 更新、擷取資料、追蹤分析資料或重新計算版面配置等耗用大量資源的操作,直至捲動完成,以維持流暢的捲動效能。
- 提供經最佳化的裝飾圖片:同時提供新一代圖片格式(例如 AVIF 或 WebP)及多種像素密度(例如 1x 和 2x)的經最佳化裝飾圖片(例如背景、用戶介面圖示或複雜遮罩),讓瀏覽器根據用戶裝置的效能,動態選擇檔案大小與視覺質素之間的最佳組合。
- 降低背景資料擷取的優先級:降低透過 Fetch API 發出的背景資料擷取的優先級,避免與用戶主動發出的請求爭用網絡資源。
- 偵測初始可見狀態:可靠地判斷頁面最初是否在背景載入,即使指令碼在用戶已將頁面切換至前景後才非同步載入,也能作出判斷。
- 有效率地在背景處理:當元件位於螢幕可視範圍外時,暫停背景 JavaScript 執行(例如
<canvas>動畫、WebGL 繪圖或高頻率 WebSocket 數據輪詢),以節省系統資源和電池電量;待元件重新捲動至可視範圍時,再即時恢復執行。 - 加快 SPA 檢視畫面轉換:保留先前瀏覽過的檢視畫面的 DOM 結構狀態,而非每次導覽時都將其摧毀並重新建立,以加快在單頁應用程式(SPA)中返回這些檢視畫面的轉換速度。
- 避免用戶端 A/B 測試閃爍:透過用戶端 JavaScript 修改或插入 HTML、CSS 和 JavaScript,提供並呈現 A/B 測試、多變量測試或其他實驗,避免原有內容先行顯示,之後才閃爍或閃現實驗內容。
- 追蹤完整工作階段的分析資料:在用戶整次瀏覽頁面的期間,可靠地追蹤分析資料、Core Web Vitals、錯誤和遙測數據,並延後傳送資料,直至用戶離開頁面。
- 找出耗用大量資源的指令碼:找出最容易造成長時間動畫影格的指令碼
- 找出造成 INP 問題的原因:找出執行緩慢的 JavaScript,以及其他導致 Interaction to Next Paint (INP) 回應欠佳的原因。
- 提升下一頁的載入效能:預先擷取或預先呈現用戶可能接着瀏覽的頁面,以提升頁面載入效能。
- 互動繪製時間:量度用戶互動和用戶端導覽後,畫面呈現包含新內容的更新所需時間。
- 複雜版面配置中的互動:避免複雜版面配置(例如數據繁多的儀錶板或試算表式網格)重新計算版面配置,令互動更靈敏、回應更迅速,並降低 Interaction to Next Paint (INP) 分數。
- 延遲載入影片和音訊:延後下載位於可視範圍外的影片和音訊資產,包括影片封面圖片和預先載入的媒體資料,直至媒體播放器接近可視範圍,以節省頻寬,並減少頁面初次載入時的網絡資源爭用。
- optimize-image-priority:優化最大內容繪製(LCP)候選圖片的載入優先級,並降低非關鍵圖片的優先級,以減少關鍵資源載入延遲。
- optimize-preload-priority:優化預載內容的相對優先級,以減少關鍵資源載入延遲。
- optimize-script-priority:優化指令碼的載入優先級,提升關鍵非同步指令碼的優先級,並降低非必要或位於 body 後段的指令碼的優先級,從而改善載入次序並減少延遲。
- out-of-order-html-streaming:以宣告式方式,使用稍後串流至同一 HTML 文件的內容,或透過命令式 JavaScript API 更新頁面。
- resolution-optimized-pseudo-elements:在 CSS 偽元素中使用經解像度最佳化的圖片(例如
::before和::after),以減少 DOM 節點數量。 - schedule-tasks-by-priority:按優先級安排工作,確保關鍵工作優先執行,並延後背景工作。
私隱
- privacy:為網頁開發人員提供以行動為本的指引,協助他們在設計時保障私隱、減少資料收集、進行第三方審核,並安全地處理資料。設計應用程式、整合第三方服務、處理用戶資料或設定安全標頭時,請使用這項技能。
PWA
- install-web-app:透過由瀏覽器控制的同意介面,從頁面安裝網絡應用程式。
- migrate-web-app-origin:將已安裝的網絡應用程式轉移至新的來源,同時保留用戶設定及作業系統層級的捷徑。
保安
- client-side-encryption:使用公開金鑰封裝或金鑰協商(包括混合式及後量子保護)建立共享密鑰,並在瀏覽器中使用認證加密,為敏感資料加密。
- digital-signatures:在瀏覽器中使用傳統或抗量子(後量子)非對稱金鑰,簽署及驗證訊息、令牌或成品,以確保資料完整性及真確性。
- local-network-access:讓公開網絡應用程式存取用戶本機網絡或回送介面上的資源。
- passkey-authentication:使用通行密鑰驗證回訪用戶身份,以進行主要登入。
- passkey-conditional-create:用戶成功以密碼登入後,為現有用戶靜默註冊通行密鑰。
- passkey-management:讓用戶查看及管理其帳戶中已註冊的通行密鑰。
- passkey-reauthentication:在執行敏感操作前,使用用戶現有的通行密鑰驗證已登入用戶的身份。
- passkey-registration:為現有用戶帳戶註冊通行密鑰。
- passkeys:全面介紹在網絡應用程式中實作 WebAuthn 和通行密鑰的基本知識及跨領域原則。處理通行密鑰註冊、驗證、管理或重新驗證時,請使用本指南。
- quick-sign-ins:在回訪用戶前往登入頁面或其工作流程受到中斷之前,直接使用已儲存的通行密鑰或密碼驗證其身份。
- restrict-outbound-connections:限制頁面或 worker 只可與明確列出的網絡端點通訊,以防止未經授權的第三方請求及用戶端資料外洩。
- sanitize-untrusted-html:移除不安全的元素和屬性,安全地剖析及顯示來自用戶輸入的不可信 HTML 內容。
- secure-external-subresources:以密碼學方式驗證從第三方來源載入的外部指令碼、樣式表、字型和圖片的完整性,並控制這些請求是否傳送憑證或來源網址。
- trusted-types:建立 Trusted Types 政策以淨化不可信 HTML,並在寫入 innerHTML 等 DOM 寫入點時使用該政策,再透過內容安全政策強制執行 Trusted Types,藉此防止基於 DOM 的 XSS 攻擊。
- validate-origins:在跨文件訊息和網址中安全地比對及驗證網頁來源和網站,避免使用容易出錯的字串剖析方式。
- verify-email-ownership:在建立帳戶、登入或復原帳戶時,確認用戶擁有某個電郵地址,而毋須發送一次性密碼或魔法連結電郵。
ui-atoms
- carousel-slide-effects:建立包含圖片或其他視覺元素的投影片輪播,讓每張投影片在進入、移至中央或離開捲動區域時播放動畫。例如,投影片可以淡入或淡出、旋轉、放大或縮小等。
- component-specific-light-dark-theme:強制指定元素使用淺色或深色模式(例如程式碼區塊、媒體播放器等),不受頁面色彩配置影響。
- icons:顯示及管理圖示,讓圖示可透過 CSS 設定及調整參數、載入速度快、在任何解像度下都清晰,並能適當地向輔助技術顯示或隱藏。
- position-aware-tooltips:建立帶有方向箭頭(或其他視覺樣式)的工具提示和彈出式提示;當元素翻轉至後備位置時,箭頭會自動指向正確方向。
- pull-to-reveal:建立下拉以顯示內容的功能,讓用戶向下拉動畫面以顯示更多內容,例如搜尋列。
- responsive-table:建立用來呈現表格資料的數據表格,具備正確的標題語義,並確保在小螢幕上及使用輔助技術時仍易於閲讀和瀏覽。
- scroll-position-aware-elements:建立浮動按鈕或小工具(例如返回頂部、捲至底部、開啟聊天的按鈕等),根據用戶是否捲動畫面而顯示或隱藏。
- scroll-progress-indicator:建立捲動進度列、分段進度追蹤器或其他視覺提示,顯示用戶在頁面或區段中已捲動多遠。
- scrollability-affordance-hints:建立捲動陰影或漸淡邊緣,只有在該方向確實仍有更多內容可供捲動時才會顯示。
- shrinking-header-on-scroll:在捲動時,為固定頁首或全頁封面播放流暢的動畫,讓它在預先設定的捲動距離內動態縮小、加上陰影並調整版面。
- 單行溢出:在可能容納不下文字的空間中顯示必須維持單行的文字,例如分頁標籤、表格儲存格、導覽項目或檔案名稱,同時避免版面錯亂或文字遺失。
- 狀態感知黏附式標題:建立黏附式分區標題或導覽列,讓它們在真正黏附於頂部時改變外觀,例如轉換配色或加上陰影。
- 視區感知下拉選單:將下拉選單、飛出式選單或情境操作面板定位於觸發按鈕旁,並在視區邊緣自動反轉方向,避免內容被裁切。
UI 行為
- 二維平移:讓用戶可自由平移或捲動二維介面,例如地圖、放大後的圖片、無限畫布或大型數據網格,並可向任一方向移動(包括斜向移動或在手勢途中改變方向),而不會令手勢鎖定於單一水平或垂直軸向。
- 錨點定位分頁底線:讓元素在兩個目標元素的位置之間無縫轉換。例如,讓已選取分頁的底線在先前選取的分頁與目前選取的分頁之間移動。
- 元素進入及離開動畫:在元素加入或移除 DOM,或切換其 display 值時,平滑地隱藏或顯示元素。
- 頂層進出動畫:為對話框、彈出視窗和工具提示等元素加入動畫,呈現它們進入或離開頂層的效果。
- 輪播項目對齊醒目效果:在捲動對齊輪播、圖片集或全頁滑動體驗中,以視覺效果突顯目前對齊定位的非互動項目。例如,項目對齊定位時展開卡片,或顯示隱藏內容。
- 一致的跨文件轉場:確保關鍵頁面狀態已載入並保持穩定,才開始跨文件檢視轉場。這表示關鍵 CSS 樣式已載入並套用、關鍵 JavaScript 已載入並執行,而且用戶初次檢視頁面時會看到的 HTML 已完成剖析,轉場才會開始。
- 跨文件轉場:在整頁導覽之間建立流暢無縫的轉場,例如淡入淡出、自訂揭示效果,或讓內容從一個頁面變形至下一個頁面。
- 自訂按鈕操作:使用宣告式按鈕命令、呼叫方命令、按鈕命令、自訂命令或宣告式切換操作,以宣告方式連接按鈕與任何元素,觸發自訂且專屬於應用程式的操作。
- 宣告式對話框及彈出視窗控制:無須編寫 JavaScript,即可透過按鈕切換對話框或彈出視窗的顯示狀態。
- 方向感知導覽轉場:為視覺狀態變更加入動畫,以反映用戶導覽的方向,例如向前瀏覽時讓新內容從右方滑入,返回上一個畫面時則從左方滑入。
- 拖曳:支援拖曳,讓浮動元素可在頁面上移動。
- 拖放:支援沿單一軸向(水平或垂直)拖曳並重新排列容器內的子元素,同時保留它們的狀態及無障礙次序。
- dynamic-sibling-animations:在同層元素之間錯開動畫或轉場的時間,讓每個元素根據自己在同層元素清單中的位置,在計算所得的延遲後開始。
- dynamic-sort:以最佳做法處理用戶觸發的容器子元素動態重新排序(例如清單項目、表格列或卡片網格),並可選擇加入動畫效果;同時兼顧用戶偏好、良好的螢幕閲讀器使用體驗,以及大型清單的最佳效能。
- group-element-transitions:新增、移除、打亂或重新排序清單項目、卡片或網格元素時,讓它們同時平滑地移至新位置並播放動畫,例如從購物車移除商品。
- highlight-text-ranges:在頁面上標示任意文字範圍,例如搜尋結果、拼寫錯誤或協作編輯遊標。
- interactive-content-reveal:建立互動式揭示效果,例如讓聚光燈跟隨用戶的指標,顯示圖片或 UI 區域中的細節。
- interest-triggered-action-previews:當用戶表示感興趣時(例如遊標懸停、取得焦點或長按),在用戶確認點擊前即時預覽按鈕的效果。
- interest-triggered-tooltips:用戶將遊標移至互動元素上、令其取得焦點或長按時,顯示工具提示或補充資訊,無須點擊。
- light-dismiss-a-dialog:建立可透過輕觸式關閉方式關閉的模態對話框(即點擊或輕觸對話框以外的位置)。
- motion:使用 CSS 轉場、動畫、由捲動驅動的動畫及視圖轉場為 UI 加入動畫,讓動態效果由合成器處理,並遵從減少動態效果的偏好設定。
- move-dom-element-without-losing-state:移動或重新設定 DOM 元素的父元素時,不會失去重要的元素狀態,例如互動狀態(:focus/:active)、
<iframe>載入狀態、動畫/轉場狀態等。 - parallax-scroll-effects:建立以捲動為基礎的效果(例如視差效果),讓前景和背景圖層以不同速度移動,營造用戶捲動時的景深感。
- persistent-top-layer-ui:當底層 DOM 節點在 DOM 中被移動或重新設定父元素時,仍讓模態對話框、全螢幕元素或原生彈出層保持顯示及正常運作。
- physics-based-easing:建立自訂的物理效果動畫和轉場,例如彈跳和彈簧效果,令效果比傳統緩動曲線更自然、更吸引。
- platform-controls-dismiss-dialog:建立可透過平台標準操作關閉的模態對話框,例如在桌面平台按下
Esc鍵,或在流動平台使用「返回」或「關閉」手勢。 - prevent-page-scroll-under-modal-dialog:模態對話框開啟時,禁止捲動底層頁面。
- 同一文件轉場:在單頁應用程式(SPA)中,透過平滑變化元素的大小、位置或其他樣式屬性,以視覺方式連接不同頁面狀態或導覽中持續存在的元素(例如將產品縮圖展開為全幅主視覺圖片)。
- 元件範圍內轉場:為單一元件(卡片、清單、面板或其他子樹)內的狀態變化加入動畫,同時保持頁面其餘部分可供互動,並容許其他轉場同時執行。
- 捲動完成效果:平滑地以程式化方式捲動至目標元素,並在捲動完成後才觸發該元素的視覺效果、動畫或焦點變更。
- 捲動進入及離開效果:用戶捲動時,當元素進入或離開捲動視口(或視口),為元素建立淡入、放大或其他複雜的顯示效果。
- 捲動吸附即時回饋:用戶在對齊吸附位置的內容中捲動時,於捲動手勢完成前,為相關的使用者介面元素提供即時視覺回饋。
- 捲動吸附狀態同步:將導覽指示器、相關內容面板及分析追蹤,與可捲動容器中目前吸附定位的項目同步。
- 載入時捲動至目標:建立可捲動的元素清單(例如圖片輪播或聊天對話串),並在首次載入時將指定元素捲動至可視範圍內。
- 滾動敍事:動畫化目標元素的視覺屬性,例如淡出背景、變更背景顏色,或營造滾動敍事體驗;整個效果完全由另一個元素的捲動視口位置驅動。
- 搜尋隱藏內容:使用手風琴式元件、分頁標籤及「閲讀更多」區段等方式隱藏內容,同時確保隱藏文字會在原生「在頁面中尋找」搜尋時顯示、可供搜尋引擎編入索引、支援 URL 片段深層連結,並符合 ARIA 無障礙要求。
- 可排序表格:以漸進增強方式為資料表格加入功能,讓用戶按一下欄標題即可排序資料列。
- 空間導覽:使用方向鍵實現符合無障礙要求的空間導覽,並確保在不同版面模式(例如網格)下都能正常運作。
- 滑動以移除:讓用戶以水平滑動手勢處理清單中的項目(移除、封存、標記為已讀等),無須點按獨立控制項即可快速處理項目。
- 滑動以顯示:讓用戶在清單項目或內容窗格上水平滑動,以顯示相關操作按鈕或側邊選單,而不會自動觸發操作。
使用者介面元件
- 手風琴式元件:建立具備動畫、可選擇是否採用互斥式(一次只開啟一項)行為,並符合品牌風格的手風琴式元件。
- 應用程式選單:建立應用程式選單列,讓多個頂層選單(例如「檔案」、「編輯」及「檢視」)在鍵盤操作時共用單一停駐點,並可透過懸停或方向鍵在選單之間切換。
- breadcrumbs:建立導覽路徑,顯示用戶在網站階層中的位置,並讓用戶前往上層頁面。
- card:建立卡片元件,根據可用空間和內容調整呈現方式。
- carousel:建立輪播元件,以水平或垂直版面顯示一組項目。
- checkbox:設定核取方塊的樣式,包括自訂圖示、版面、顏色,以及勾選和取消勾選動畫,同時保留原生功能和無障礙支援。
- copy-button:建立複製按鈕,將任意元素中的文字複製到剪貼簿。
- dark-mode-toggle:建立深色模式切換元件,讓用戶可在目前網站覆寫系統的色彩配置偏好設定。
- dialog:建立模態或非模態對話框元件,確保無障礙使用、妥善管理焦點,並可按各平台用戶預期的方式關閉。
- hovercard:建立懸停卡片元件,當用戶將遊標移至特定類型的連結(例如用戶個人檔案)上時,顯示該連結所通往頁面的互動式結構化預覽。
- menu:建立選單元件,顯示選項或操作清單,並支援巢狀子選單。
- navbar:建立網站導覽列,能因應不同螢幕大小調整,並標示目前所在頁面。
- navigation-drawer:建立導覽抽屜元件;用戶按下選單按鈕後,抽屜會從側邊滑入並覆蓋現有頁面內容,關閉時則會滑出。用戶可透過滑動、點按外部區域或按下 Escape 鍵關閉。
- persistent-app-tours:使用錨定式原生覆蓋層建立持續顯示的新手引導流程,並在用戶互動期間保持開啟。
- persistent-toast-notifications:建立不打擾用戶的提示訊息和覆蓋層通知,用於持續顯示、可堆疊的訊息和狀態傳達。
- progress:建立樣式化進度列,顯示任務或流程的完成進度,並支援確定和不確定兩種狀態。
- progress-ring:建立進度環元件,以視覺方式顯示任務或流程的完成狀態,支援在中央放置內容,並採用符合品牌風格的樣式。
- scrollspy:在導覽選單中標示頁面上目前可見的部分。
- spinner:建立載入動畫,向所有用戶傳達目前正忙碌,並遵從減少動態效果的偏好設定,同時確保動畫運行流暢。
- stack-drill-down:建立全螢幕階層式導覽,讓用戶逐層瀏覽巢狀檢視畫面,並可透過滑動或導覽返回;同時與瀏覽器記錄保持同步。
- tabs:建立回應式分頁介面,即使畫面無法顯示所有分頁,也能提供良好的用戶體驗。
- toolbar:建立工具列元件,顯示一組可執行操作的控制項。
用戶體驗
- 以內容為先,減少幹擾:盡量呈現內容並減少幹擾:移除阻擋式彈出視窗,讓常駐導覽保持精簡,並將次要內容收納於按需展開的區域。
- 適應不同裝置形態:調整版面配置、控制項和文字,以適應任何裝置或容器,確保觸控目標方便操作、內容符合可用空間,而且不會與系統介面重疊。
- 自然互動:實現自然的互動方式,包括清晰的懸停、焦點和按下回饋、從觸發位置展開的動態效果、可滑動的內容,以及可透過鍵盤操作的功能。
視覺設計
- 配合對比偏好調整捲軸:提高捲軸的可見度,照顧偏好高對比介面的用戶
- 套用 WebGL 著色器:使用 WebGL 著色器為 HTML 內容套用自訂視覺效果。
- 為瀏覽器介面套用主題:使用 CSS 為瀏覽器產生的介面套用主題,例如文字選取區、捲軸、表單控制項和選擇器,而非用自訂元素重新建立這些介面。
- 色彩:網頁色彩指引,包括對比度要求、淺色及深色色彩方案、強制色彩模式,以及如何從基礎色產生較淺和較深的色調。
- 複雜形狀:將元素及其內容裁切成任何自由形狀,例如符號、筆觸或自然紋理,令設計更具表現力。
- 對比色彩:在會變化的背景色上選用對比度足夠、易於閲讀的文字顏色。
- 自訂文字裝飾:加入文字裝飾,例如底線、頂線、刪除線或完全自訂的形狀,並設定顯示動畫、自訂偏移及末端內縮,以及靈活控制裝飾線如何避開字形。
- 自訂捲軸顏色和粗幼:自訂捲軸的顏色或粗幼
- 深色模式:實作深色模式支援,尊重用戶對淺色或深色主題的偏好,並調整瀏覽器介面(例如捲軸、表單控制項等)。
- 等寬文字行:令多行標題或文字組合的每一行都橫跨相同寬度,適用於海報風格或層疊標題排版。與左右對齊文字不同,這種做法會調整文字本身的大小以符合寬度,而非拉闊字距。
- 從畫布匯出 HTML 媒體:在畫布內擷取動態 HTML 內容,並將其匯出為圖片或影片畫格。
- 讓瀏覽器功能讀取畫布內容:讓輔助技術、翻譯或閲讀模式等瀏覽器功能讀取畫布中繪製的內容。
- 改善文字排版和易讀性:改善簡短獨立文字內容(例如不超過幾行的標題)的排版和易讀性,讓瀏覽器在文字換行時能平均平衡各行的斷行位置。
- 在 3D 場景中加入互動內容:將互動式 HTML 元素整合至 3D 場景。
- 精確對齊文字:讓任何字體的文字都能精確垂直對齊。例如,令文字上下的視覺留白完全相等,或令文字與相鄰圖示或圖片完全貼齊。
- 形狀裁切:結合多個形狀,在元素中建立複雜的裁切或「挖空」效果,例如在元素上加入缺口。
- 柔邊內容淡出:在內容邊緣套用透明度漸層,提示用戶還可繼續捲動,或遮蔽受付費牆限制的文字。
- 排版:網頁排版的最佳做法,包括字體大小單位、行高、文字換行和平衡,以及會隨視窗大小縮放的流動字體排版。
- 視覺效果:運用 CSS 製作視覺效果,例如多層陰影、混合模式、色彩插值效果可預測的漸層,以及只用漸層繪製的條紋、棋盤格、圓點和圓餅圖等圖案。
- 視覺穩定的字體後備:設定字體樣式,讓首選字體與後備字體互相切換時,文字仍然清晰易讀,視覺效果一致。
- 視覺穩定的混合字體:設定字體樣式,讓單一文字區塊使用多種字體呈現時,文字仍然清晰易讀,視覺效果一致。
- 視覺紋理內容:為元素套用逼真的風化效果和紋理圖案,令其呈現自然、有年代感或實體材質的外觀。
wasm
- 網頁上的 C++:使用 Emscripten 將 C/C++ 編譯為 WebAssembly
WebMCP
- AI Agent 表單:在標準 HTML 表單上加入 WebMCP 屬性,將用戶端功能提供為 AI Agent 可使用的工具。
- AI Agent JavaScript 工具:使用 WebMCP Imperative API,以程式方式將用戶端 JavaScript 函數註冊為 AI Agent 的工具。
- WebMCP:使用本指南在瀏覽器應用程式中實作 WebMCP,透過宣告式或命令式 API,將用戶端功能提供為 AI Agent 可使用的工具。
安全採用現代功能
- 漸進式增強與周全的後備方案:我們會區分純粹增益型的強化(例如推測性預載)與關鍵行為(例如對話框控制或網絡信標)。舊版瀏覽器可安全地靜默忽略前者;對於後者,我們會編寫經審慎設計、開銷低的後備方案。
- 負責任的後備方案:我們優先採用輕量、針對特定情況的自訂後備方案(<50 LOC),或按條件載入的 polyfill,而非龐大的第三方套件。
- 注意事項與特殊情況:我們會記錄平台的隱藏限制,例如
fetchLater()的 64KB 負載配額,或 macOS 特有的捲軸行為。 - 兼顧 Baseline 的整合:我們會利用 Baseline 專案的即時相容性資料,讓 Agent 動態配合目前的瀏覽器支援情況。
- Origin Trial 與不穩定功能閘控:涵蓋實驗性 Origin Trial API 或不穩定功能(只在單一引擎推出未滿 3 個月,或仍在穩定階段的功能)的指南,仍可透過
search找到,但會以retrieve作為啟用條件,避免 Agent 在未獲開發人員明確同意前採用不穩定的 API。
專案設定(.mwgrc)
在儲存庫中設定 Origin Trial 和 volatile 功能的選用啟用設定:只需在專案根目錄放置可選的 .mwgrc JSON 檔案(或以 ~/.mwgrc 作為使用者層級的後備設定),並可將其提交至版本控制,供團隊共用:
| 命令列指令 | .mwgrc 鍵 |
效果 |
|---|---|---|
npx modern-web-guidance@latest set-allow-origin-trials |
"allowOriginTrials": true |
解鎖實驗性 Origin Trial API 的指南。 |
npx modern-web-guidance@latest set-allow-volatile-features |
"allowVolatileFeatures": true |
解鎖單一引擎 volatile 功能的指南。 |
運作方式
- 啟用:編碼 Agent 會因應相關任務啟用
modern-web-guidance技能。Agent 會收到指示,使用modern-web-guidanceCLI 查詢網絡平台資訊。 - 本機語義搜尋:Agent 執行
modern-web-guidance search "<query>"。此工具使用離線、零依賴的嵌入模型及 BM25 搜尋引擎,將查詢配對至最合適的指南(不會進行網絡呼叫,亦無需 API 金鑰)。 - 擷取指南:Agent 透過
modern-web-guidance retrieve <guide-id>擷取指南,將針對性的程式碼模式、注意事項及後備方案直接加入其上下文視窗。
提示
注意:我們使用 npx 確保內容不會過時,但 CLI 可完全離線運作,並完全私密地在本機執行。
npm 套件完整自足,不含額外依賴項,以確保低延遲及供應鏈安全。
其他安裝方法
Vercel Skills CLI(又稱 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
更新
如果你使用 npx modern-web-guidance@latest install 安裝技能,可透過以下指令更新:npx modern-web-guidance@latest update。
否則,請參閲 Agent 的説明文件,瞭解如何更新外掛程式和技能。
證明其運作良好的評測
我們開發了一套完善的評測工具,以確保內容經實證驗證並持續校準,讓 AI Agent 編寫更好的程式碼。我們透過閉環驗證流程進行自動評測:
[ 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
- 模擬開發者任務:我們以完整的基礎應用程式(
daily-grind、devtools-times)設計貼近現實的開發者提示詞,模擬真實世界的要求(例如:「令我的圖片載入得更快」)。提示詞不會提及 API 或功能名稱,以測試 Agent 能否自行找到並套用合適的指南。 - 靜態及瀏覽器端斷言:Playwright 評分器會驗證每項實作要求是否符合,包括檢查原始碼模式、計算樣式、執行時 DOM 行為及無障礙狀態。
- 自我修復校準:評分器會以多 Agent(Claude/Codex/AGY)的黃金標準解決方案(目標通過率為 100%),以及未修改的基礎應用程式(目標通過率為 0%)進行校準。
- 端對端測試:我們會衡量編碼 Agent 在有指引和沒有指引時處理真實任務的表現。機會值(100% - 無指引通過率)和提升幅度(有指引通過率 - 無指引通過率)是關鍵:如果模型在沒有指引時已能成功,我們便會刪除重複的建議;如果 Agent 遇到困難,我們便會完善指南,以盡量提升成效。
近期評測結果摘要
前往評測儀錶板,查看按 Agent 及指南劃分的完整細項。
| 日期 | Agent + 模型 | 任務/斷言 | 無指引 → 有指引(提升幅度) |
|---|---|---|---|
| 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) |
可用技能套件
你可以使用 --choose 標誌,自訂要安裝的技能套件:
npx modern-web-guidance@latest install --choose
modern-web-guidance(約 205 個 tokens):全面介紹現代瀏覽器 API、版面配置及效能。chrome-extensions(約 175 個 tokens):介紹 Manifest V3、背景工作程序、擴充功能 API,以及在 Chrome Web Store 發佈擴充功能。
遙測與私隱
Google 會收集匿名使用資訊,以改善工具的可靠性、相關性和效能。收集的資料包括安裝次數、呼叫工具的 Agent 名稱、指南擷取 ID,以及由 Agent 產生的 CLI 工具搜尋查詢(例如「深色模式 捲軸 配色方案」)。不會收集原始用戶提示詞。你可以在 modern-web.ts 查看收集的資料。
提示
如要退出:在 shell 設定檔中設定 DISABLE_TELEMETRY=1 環境變數(例如 .bashrc 或 .zshrc):
export DISABLE_TELEMETRY=1Google 會按照 Google Privacy Policy 處理這些資料。
貢獻者
發現錯誤、過時的模式或缺少的網絡平台功能?請提交問題,或在原始碼儲存庫(GoogleChrome/modern-web-guidance-src)查看 CONTRIBUTING.md。
衷心感謝所有作出貢獻的人!
授權條款
除非另有註明:
- 本專案中的軟件程式碼採用 Apache License 2.0 授權。
guides/下的文件及指南內容採用 Creative Commons Attribution 4.0 International (CC-BY 4.0) 授權。
本專案的部分文件內容取材自 Mozilla Contributors 編寫的 MDN Web Docs,以及 W3C、WHATWG 和 IETF 的規格。
來源:Hacker News 熱門(buzzing.cc 中文翻譯) · github.com