Liquid Glass Web
一個將 Liquid Glass 材質模型適配到瀏覽器的網頁設計系統。內容位於不透明層上，而導航與控制項的薄半透明功能層則浮動於內容之上。本系統是 Apple「Adopting Liquid Glass」公開指南的獨立改編版，不包含任何 Apple 字型、符號或資產。
此技能包含的內容
| 路徑 | 用途 |
|---|---|
assets/tokens.json | 真相來源：顏色（主題 light、dark、contrast）、字體、間距、圓角、尺寸、材質、陰影。 |
assets/tokens.css | 編譯後的 CSS 自訂屬性與字體類別。修改 tokens 後請執行 scripts/build_tokens_css.py 重新產生。 |
assets/liquid-glass.css | 元件樣式（lg-* 類別）。與框架無關。 |
assets/liquid-glass.react.js | 選用的 React 18 套件，暴露 window.LG（經典腳本；需要 window.React 和 window.ReactDOM）。 |
assets/liquid-glass.d.ts | 元件 props，作為文件使用。 |
assets/example.html | 純 HTML 的完整畫面。可複製其結構。 |
references/brand-book.md | 原則、語氣、顏色、材質、字體、佈局、動畫、圖示、無障礙。設計前請務必閱讀。 |
references/html-api.md | 無需 React 的每個元件標記方式。 |
references/components/<Name>.md | 每個元件的指南：使用者需提供的內容、注意事項。 |
scripts/contrast_check.py | 對每個主題中的每個權杖配對進行 WCAG 檢查，包含最差情況的玻璃效果。失敗時回傳 Exit 1。 |
scripts/build_tokens_css.py | 將 tokens.json 編譯為 tokens.css。 |
工作流程
A. 建構或重新設計 UI
- 閱讀
references/brand-book.md，然後閱讀references/components/中你需要的元件檔案。 - 將
assets/tokens.css和assets/liquid-glass.css複製到專案中，並依序載入。在 React 專案中，可以使用套件或移植references/html-api.md中的標記。在其他框架中，請移植標記。 - 佈置兩層：
- 內容層： 不透明，位於
canvas和surface上。所有供閱讀的內容都放在此處。 - 玻璃層： 僅限導航與控制項，浮動於滾動內容之上（工具列、分頁列、群組、選單、中型 sheet）。
- 內容層： 不透明，位於
- 使用權杖名稱（例如
var(--accent)）。絕不硬編碼權杖涵蓋的顏色、圓角或間距值。 - 完成前執行下方的檢查清單。
B. 重新品牌（新的強調色或中性色）
- 僅修改
assets/tokens.json中的值。保留權杖名稱，因為 CSS 依賴它們。 - 每個變更的強調色需要在每個主題中有其配套：
accent、on-accent、accent-text、accent-glass、focus-ring。如果暗色主題的強調色是淺色，則on-accent必須是深色。 - 執行
python3 scripts/contrast_check.py assets/tokens.json。調整數值直到顯示RESULT: PASS。請勿降低閾值。 - 執行
python3 scripts/build_tokens_css.py assets/tokens.json > assets/tokens.css。 - 除非有特殊要求，否則保留玻璃權杖（
glass-fill、glass-edge、glass-lift、glass-blur）。玻璃層保持無色。
不可妥協的規則
- 玻璃僅用於功能層。絕不使用於列表行、內容卡片或頁面區塊，且不可玻璃疊玻璃。
- 常規玻璃上的文字僅使用
ink、ink-glass-muted、accent-glass或critical-glass。絕不在玻璃上使用ink-secondary、accent-text或critical：它們在深色或亮色內容上會失效。 - 透明玻璃（
lg-glass--clear）僅用於照片、影片或地圖之上，且下方需有lg-dim。僅在其上放置符號和 19px 以上的粗體標籤。 - 每個視圖最多一個
prominent按鈕。所有控制項皆為膠囊形狀（radius-full）。嵌套圓角需同心：內層 = 外層 − inset。 - 點擊區域至少為
target-min（44px）。每個僅限圖示的控制項都必須有aria-label。 - 狀態必須同時使用圖形和文字；顏色本身從不傳達意義。
- 尊重
prefers-reduced-transparency、prefers-contrast和prefers-reduced-motion。CSS 已處理這些設定；請勿覆寫。 - 請勿使用 Apple 的 SF Symbols、Apple 字型或商標。字型堆疊使用裝置的系統字型；React 套件中的圖示集為原始佔位符。
交付前檢查清單
- 工具列後方無自訂背景；內容在其下方滾動，並在工具列與內容重疊處使用
lg-edge滾動邊緣效果。 - 玻璃數量很少（工具列、群組、選單、sheet）。其他項目都不是玻璃。
- 已在
data-theme="light"、"dark"和"contrast"下檢查畫面。 - 如果權杖已變更：
contrast_check.py顯示 PASS，且tokens.css已重新產生。 - 鍵盤：每個控制項都可觸及，並顯示
focus-ring外框。 - 文案：動作使用 sentence case，僅列表區段標題使用 Title Case，動詞優先，無 emoji。