Communitygithub.com

Liquid Glass · 全功能實現

Apple WWDC25 Liquid Glass 全功能實現:26 項材質特性 + 82 個動作(點擊/雙擊/長按/右鍵/拖拽/慣性/虛影/展開收起/分離合併/融合/鍵盤/無障礙/滾動邊緣)。當用戶要求做蘋果液態玻璃、玻璃擬態 UI、透明折射玻璃、Liquid Glass 按鈕·選單·Dock,或需要按壓反饋、形變、光路分析時使用。附帶可直接運行的單檔案 liquid-glass-all.html(WebGL 片段著色器,2 個 program、10 次 draw call,已用無頭 Chrome 實跑並內建 ?selftest=1 自測)。

Liquid Glass · 全功能實現 是什麼?

此技能提供了一個完整的 WebGL 實現,用於模擬 Apple 在 WWDC25 上展示的 Liquid Glass(液態玻璃)效果。它是一個單檔案 HTML 應用程式,透過片段著色器(fragment shader)即時計算玻璃的折射、厚度、菲涅耳效應、色散和內部發光等 26 項材質特性。技能涵蓋了多達 82 種使用者互動動作,包括基本的點擊、雙擊、長按、拖拽,到較複雜的慣性滑動、形態展開/收起、分離/合併、按壓反饋和鍵盤控制,並支援無障礙功能。此實現主要用於開發者需要快速打造具備 Apple 設計語言的液態玻璃 UI 元件(如按鈕、選單、Dock),或需要進行光路分析與視覺驗證的場景。程式碼內建了自測模式(`?selftest=1`),可自動驗證 13 項核心功能,並提供效能預算與跨平台注意事項,確保實作在 Chrome/Edge 等瀏覽器上能穩定運行。

相容平台✓Claude Code~Codex CLI~Cursor
npx skills add https://github.com/Cyt-56/liquid-glass-webgl/tree/HEAD/skill

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

Liquid Glass · 全功能實現 是做什麼的?

單檔案 WebGL 實現,玻璃的折射/厚度/Fresnel/色散/唇/內發光全部在片段著色器裡計算,DOM 只承載文字、按鈕與落影。 不要從零手寫 shader:90 行就能跑,但 400 行從零寫的成功率極低。從 liquid-glass-all.html 改。

0. 最快路徑(1 分鐘看到效果)

  1. Chrome / Edge 打開 liquid-glass-all.html。
  2. 右側控制面板有 5 個滑塊(refract / mag / rim / disp / tint)+ 4 個配方鍵,改完立刻看變化。
  3. 動作全在裡面:點膠囊展開、按住拖拽、長按出氣泡、右鍵出另一套選單、雙擊抬升、Dock 分離鍵、鍵盤空格/S/W/Esc。
  4. 驗收用內建自測:網址後加 ?selftest=1,頁面左上角直接打出 13 條 PASS / FAIL。
  5. 截圖擺拍:?pose=1 一次擺出「展開 + 分離 + 氣泡」;?pose&wire=1 再疊光路診斷場。
chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=6000 ^
  --window-size=1280,800 --screenshot=out.png "file:///<絕對路徑>/liquid-glass-all.html?selftest=1"

截圖後真的去讀那張圖,確認左上角是 FAIL 0,不要只憑程式碼就說完成。

1. 資產

liquid-glass-all/
├── SKILL.md                       # 本檔案:路徑、動作、光路、坑、驗收
├── liquid-glass-all.html          # 全功能實現(唯一運行產物)
└── references/
    ├── action-matrix.md           # 82 個動作的完整表(觸發 / 改什麼 / 參數 / 反向)
    ├── feature-matrix.md          # 26 項材質特性 × 本實現覆蓋度
    ├── optics-model.md            # 光路物理模型與常量(寫 shader 前必讀)
    └── interaction-playbook.md    # 狀態機、時序、命中測試、驗收

2. 82 個動作速查(9 類)

完整表見 references/action-matrix.md,這裡只給骨架:

類數量內容
A 指標13hover 進入/移動/離開、鄰域衰減、press、release、單擊、拖拽啟動/跟隨/回彈、邊緣 clamp、右鍵選單、長按選單
B 拖拽慣性6方向拉伸、彈性平移、形變衰減、慣性滑行、拖拽抬升、滯後虛影
C 形態 Morph10展開/收起、選單項淡入、圓角跟隨、分離/右片長出/合併、分裂重音、零寬跳過、融合連接頸
D 按壓反饋8回縮、折射增強、厚度增厚、內發光、鄰板蔓延、底弧變亮、方向高光、flash 指路
E 光學動畫8三種折射模式、變體切換、tint 映射、明暗翻轉、環境溢色、自適應陰影、失焦退隱、背景光斑漂移
F 自適應7亮度/主色採樣、背景上傳、自適應解析度、光路重新整理、DPR 上限、降級鏈
G 系統與無障礙8resize 重排、滾動 soft/hard、三個無障礙開關、視窗失焦、Tab 焦點環、讀屏語意
H 控制項8主操作按鈕、5 滑塊、變體分段、模式三鍵、4 開關、4 配方、分離鍵、展開頭
K 鍵盤7Space / S / W / Esc / Tab / ↑↓ / Enter

動作監視條在頁面底部:每次動作打點並顯示最近 4 個,用來確認「這條到底有沒有觸發」。

3. 光路七步(順序不能變)

  1. 輪廓:sdRoundBox 取有符號距離 d;x = clamp(-d/band, 0, 1),0=輪廓、1=中心,band = max(5, min(hx,hy)*0.30)。
  2. 凸面高度場:H(x)=sqrt(1-(1-x)²),H'(x)=v/sqrt(1-v²)(v=clamp(1-x,0.02,0.9995))。用 sqrt 不用 pow。
  3. 入射角:sinI = min(H'/sqrt(1+H'²), 0.62),thT = asin(sinI/1.5168)。0.62 是硬上限,放到 0.93 會把邊緣推到 200px 級,整塊變黑。
  4. 厚度:tpx = mdim*(0.05+0.28*H)*(1+0.40*thick)*vg,vg = 1+0.24*(1-smoothstep(-0.85,0.35,q.y))(下厚上薄)。
  5. 位移:off = -dir*tan(thI-thT)*tpx*refract*Tf,再加貼邊項;最後 clamp(off,-10,10)。
  6. 焦點/唇:focal = mag*magMul*(0.50*cW - 0.40*eW);1-focal 必須恆正,否則局部 180° 翻轉、文字倒立。magMul 是面板級:lens 1.30 / capsule 0.85 / plate 0.55 / nav 0.90 / dock 0.80。
  7. 合成:sp = c + rel*(1-focal) - off;RGB 按 ±disp*7*eW 分離取樣;再 tint 亮度壓縮 0.58*L+0.133、環境溢色 0.10、Fresnel rim、乳白、頂部鏡面、底部弧、內發光。

紋理 Y 必須翻:uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y),少這一行就是鏡像畫面 + 倒立文字。

4. 狀態機與關鍵閾值

動作閾值 / 參數
hover面板內;面板外 180px 內 fade 衰減
presspress→1(k=0.19/幀)、scale 0.965、折射 ×1.3、底弧 ×1.75
單擊pointerup 且位移 ≤4px → 延後 240ms 觸發,避免和雙擊搶
雙擊兩次 pointerdown 間隔 <300ms,第二次 down 立刻取消單擊定時器
長按pointerdown 後 500ms,移動 >4px 取消;進度點在觸點上放大
拖拽位移 >4px 才轉拖拽;clamp 8px 內邊距
慣性鬆手速度 >6px/事件 → v*1.05 起步、每幀 ×0.94,<1px 結束並吸附
展開136×48 → 236×296,底邊不動:ty = lay.y + lay.h - 296;選單項由高度 110→250 淡入,過半才開 pointerEvents
分離Dock 300 → 左 140;右片 tx 釘死在 lay.x + lay.w - 140,寬度 0→140
合併右片先收寬度、位置不動(避免「滑走」)
融合分離後兩片之間保留 20px 縫隙、rim 相互呼應;真 metaball 並集需 SDF smooth-min,Web 單 pass 版未做
彈簧位置 ω=15、寬度 ω=18.5、ζ=0.66、dt=1/60 → 約 0.45s、6% 過衝

5. 參數配方

想要refractmagrimdisptintthick
厚玻璃膠囊1.200.350.950.220.24✓
透鏡壓彩條1.500.601.000.180.10✓
厚玻璃蓋小字1.250.420.800.300.16✓
頂部導航(克制)0.900.200.600.150.10✗
控制面板(可讀)1.000.150.550.120.14✗

調參順序:refract 定位移 → mag 定唇 → rim 定邊緣 → disp/tint 定質感,反過來一定來回打架。

6. 八個必踩的坑

  1. uniform 陣列不可靠:uGeo[12] 在 ANGLE/D3D 上賦值不報錯但進不去 → 每面板一次 draw call。
  2. 迴圈裡的 uniform 分支會被最佳化掉:迴圈內用 mix / step 無分支寫法。
  3. 宣告未用的 uniform 被最佳化,getUniformLocation 返回 null,誤報缺 uniform。
  4. gl.getUniform(prog, null) 拋 TypeError,整幀後面的程式碼全跳過(看起來像卡死)。
  5. 紋理 Y 軸:不翻就是鏡像 + 倒立文字。
  6. 只綁 click 會丟事件:用 pointerdown + pointerup + 位移閾值。
  7. half 是 GLSL ES 保留字:寫 vec2 half 整段編譯失敗,日誌只說 syntax error。同類雷區 filter / input / output / long / short / packed。
  8. 逆序 smoothstep 是未定義行為:smoothstep(1.0,-1.0,d) 換機器就翻車,一律寫 1.0 - smoothstep(小,大,x)。

另外兩條動作層專屬坑:

  • 長按後抬手不能再算單擊(longFired 標記),否則長按選單一開就跟緊一次展開。
  • 右鍵要攔在 pointerdown 之前(e.button !== 0 直接 return),否則右鍵會啟動拖拽。

7. 驗收(每次改完都跑)

?selftest=1 覆蓋 13 條:單擊展開/收起、長按氣泡、Esc 關氣泡、右鍵另一套選單、Dock 分離與合併、融合頸、方向鍵選中、Esc 全局收起、雙擊抬升、慣性、W 光路場。

再人工確認:

  • 玻璃裡的內容方向正確(無倒立、無鏡像)
  • 邊緣一圈 rim、頂部鏡面、底部亮弧齊全
  • 暗背景下玻璃內部不是死黑(有霧狀灰)
  • 拖拽時虛影滯後、鬆手有慣性再吸附
  • 分離時兩片是「裂開」,不是「對拉」
  • 滾動文字在邊緣漸隱,滾到端點切 hard 髮絲線
  • 三個無障礙開關都生效(降低透明度 / 增強對比 / 降低動態)

8. 效能預算

項預算
同螢幕玻璃≤10 塊(本實現 10 塊,含 0 寬度按需出現的 bubble / bridge)
draw call2 個 program + 每塊一次 AABB draw
背景上傳每 5 幀;靜止可 8 幀
亮度取樣每 10 幀,只採 w*h>24000 的面板
渲染倍率<42fps → 0.72,>56fps → 1.0,DPR 上限 2
降級鏈減面板 → 降倍率 → 降上傳 → 關色散 → 退 CSS 版

9. 紅線與平台邊界

  • 玻璃只在導航層;內容層不鋪玻璃。
  • 不疊玻璃(失去折射參照,像髒斑);Regular 與 Clear 不同螢幕混用。
  • tint 只給主操作;高光克制,rim > 1.2 會發假。
  • Web 做不到:玻璃上的文字/圖示不會被自身折射(那是 iOS 26 系統合成管線);CSS 兜底做不出逐像素透鏡唇與色散。
  • 自繪版未覆蓋:真 metaball 並集(本實現用窄頸近似)、設備傾角光照、對即時視訊的逐幀主色統計。

Individual skills in this repo

This repo contains 1 individual skill — each has its own dedicated page.

相關技能