Liquid Glass · Full Implementation
Single-file WebGL implementation: glass refraction, thickness, Fresnel, dispersion, rim, and inner glow are all computed in the fragment shader. The DOM only carries text, buttons, and drop shadows.
Do not write a shader from scratch: 90 lines can run, but the success rate for a 400-line from-scratch shader is extremely low. Modify from liquid-glass-all.html.
0. Fastest Path (See Result in 1 Minute)
- Open
liquid-glass-all.htmlin Chrome / Edge. - The right control panel has 5 sliders (refract / mag / rim / disp / tint) + 4 preset keys. Change them and see results instantly.
- All actions are included: click capsule to expand, hold and drag, long-press for bubble, right-click for another menu, double-click to lift, Dock split key, keyboard Space/S/W/Esc.
- Acceptance test: add
?selftest=1to the URL, the top-left corner of the page will directly print 13PASS / FAILlines. - Screenshot pose:
?pose=1poses "expanded + split + bubble" in one go;?pose&wire=1overlays the light path diagnostic field.
chrome --headless=new --enable-unsafe-swiftshader --virtual-time-budget=6000 ^
--window-size=1280,800 --screenshot=out.png "file:///<absolute-path>/liquid-glass-all.html?selftest=1"
After taking the screenshot, actually read the image and confirm the top-left corner shows FAIL 0. Do not claim completion based on code alone.
1. Assets
liquid-glass-all/
├── SKILL.md # This file: paths, actions, light path, pitfalls, acceptance
├── liquid-glass-all.html # Full implementation (only runtime artifact)
└── references/
├── action-matrix.md # Complete table of 82 actions (trigger / what changes / parameters / reverse)
├── feature-matrix.md # 26 material properties × this implementation's coverage
├── optics-model.md # Light path physics model and constants (must read before writing shader)
└── interaction-playbook.md # State machine, timing, hit testing, acceptance
2. 82 Actions Quick Reference (9 Categories)
The complete table is in references/action-matrix.md. Here is only the skeleton:
| Category | Count | Content |
|---|---|---|
| A Pointer | 13 | hover enter/move/leave, neighborhood fade, press, release, single click, drag start/follow/spring-back, edge clamp, right-click menu, long-press menu |
| B Drag Inertia | 6 | direction stretch, elastic translation, deformation decay, inertial slide, drag lift, lagging ghost |
| C Morph | 10 | expand/collapse, menu item fade-in, rounded corner follow, split/right-panel grow/merge, split accent, zero-width skip, fusion connecting neck |
| D Press Feedback | 8 | shrink, refraction increase, thickness increase, inner glow, neighbor panel spread, bottom arc brighten, directional highlight, flash guide |
| E Optical Animation | 8 | three refraction modes, variant switch, tint mapping, brightness flip, environment spill, adaptive shadow, defocus fade, background light spot drift |
| F Adaptive | 7 | brightness/primary color sampling, background upload, adaptive resolution, light path refresh, DPR cap, degradation chain |
| G System & Accessibility | 8 | resize reflow, scroll soft/hard, three accessibility toggles, window blur, Tab focus ring, screen reader semantics |
| H Controls | 8 | main action button, 5 sliders, variant segment, mode three-key, 4 toggles, 4 presets, split button, expand header |
| K Keyboard | 7 | Space / S / W / Esc / Tab / ↑↓ / Enter |
Action Monitor Bar at the bottom of the page: each action is logged and the last 4 are displayed, used to confirm "whether this action was actually triggered".
3. Light Path Seven Steps (Order Must Not Change)
- Profile:
sdRoundBoxtakes signed distanced;x = clamp(-d/band, 0, 1),0=profile,1=center,band = max(5, min(hx,hy)*0.30). - Convex Height Field:
H(x)=sqrt(1-(1-x)²),H'(x)=v/sqrt(1-v²)(wherev=clamp(1-x,0.02,0.9995)). Use sqrt, not pow. - Incident Angle:
sinI = min(H'/sqrt(1+H'²), 0.62),thT = asin(sinI/1.5168). 0.62 is a hard upper limit; setting it to 0.93 pushes the edge to 200px level, turning the entire block black. - Thickness:
tpx = mdim*(0.05+0.28*H)*(1+0.40*thick)*vg,vg = 1+0.24*(1-smoothstep(-0.85,0.35,q.y))(thicker at bottom, thinner at top). - Displacement:
off = -dir*tan(thI-thT)*tpx*refract*Tf, plus edge-clamping term; finallyclamp(off,-10,10). - Focus / Rim:
focal = mag*magMul*(0.50*cW - 0.40*eW);1-focalmust always be positive, otherwise local 180° flip and upside-down text.magMulis panel-level: lens 1.30 / capsule 0.85 / plate 0.55 / nav 0.90 / dock 0.80. - Compositing:
sp = c + rel*(1-focal) - off; sample RGB separately by±disp*7*eW; then tint brightness compression0.58*L+0.133, environment spill 0.10, Fresnel rim, milky white, top specular, bottom arc, inner glow.
Texture Y must be flipped: uv0 = vec2(sp.x/uRes.x, 1.0 - sp.y/uRes.y). Missing this line results in a mirrored image + upside-down text.
4. State Machine and Key Thresholds
| Action | Threshold / Parameter |
|---|---|
| hover | Inside panel; outside panel within 180px fade decay |
| press | press→1 (k=0.19/frame), scale 0.965, refraction ×1.3, bottom arc ×1.75 |
| single click | pointerup and displacement ≤4px → trigger after 240ms delay to avoid conflict with double-click |
| double-click | Two pointerdown events <300ms apart; second down immediately cancels the single-click timer |
| long-press | 500ms after pointerdown; movement >4px cancels; progress dot magnifies at touch point |
| drag | Movement >4px transitions to drag; clamp 8px inner margin |
| inertia | Release velocity >6px/event → start with v*1.05, multiply by 0.94 each frame, end when <1px and snap |
| expand | 136×48 → 236×296, bottom edge stays: ty = lay.y + lay.h - 296; menu items fade in from height 110→250, enable pointerEvents only after halfway |
| split | Dock 300 → left 140; right panel tx fixed at lay.x + lay.w - 140, width 0→140 |
| merge | Right panel shrinks width first, position unchanged (avoid "sliding away") |
| fusion | After split, a 20px gap is maintained between the two panels, rim glow mutually responsive; true metaball union requires SDF smooth-min, not done in single-pass Web version |
| spring | Position ω=15, width ω=18.5, ζ=0.66, dt=1/60 → approx 0.45s, 6% overshoot |
5. Parameter Presets
| Desired Effect | refract | mag | rim | disp | tint | thick |
|---|---|---|---|---|---|---|
| Thick glass capsule | 1.20 | 0.35 | 0.95 | 0.22 | 0.24 | ✓ |
| Lens on colored strip | 1.50 | 0.60 | 1.00 | 0.18 | 0.10 | ✓ |
| Thick glass over small text | 1.25 | 0.42 | 0.80 | 0.30 | 0.16 | ✓ |
| Top navigation (restrained) | 0.90 | 0.20 | 0.60 | 0.15 | 0.10 | ✗ |
| Control panel (readable) | 1.00 | 0.15 | 0.55 | 0.12 | 0.14 | ✗ |
Tuning order: refract sets displacement → mag sets rim → rim sets edge → disp/tint sets texture; doing it in reverse causes constant conflicts.
6. Eight Must-Know Pitfalls
- Uniform arrays are unreliable:
uGeo[12]on ANGLE/D3D assigns without error but the value never reaches the shader → one draw call per panel. - Uniform branches inside loops get optimized away: Use
mix/stepbranchless writing inside loops. - Declared but unused uniforms are optimized away,
getUniformLocationreturns null, falsely reporting missing uniforms. gl.getUniform(prog, null)throws TypeError, and all code after that frame is skipped (appears as a freeze).- Texture Y axis: Not flipping results in a mirrored image + upside-down text.
- Binding only
clickmisses events: Usepointerdown + pointerup + displacement threshold. halfis a GLSL ES reserved word: Writingvec2 halfcauses the entire compilation to fail, the log only says syntax error. Similar landmines:filter,input,output,long,short,packed.- Reversed smoothstep is undefined behavior:
smoothstep(1.0,-1.0,d)fails on different machines; always write1.0 - smoothstep(small, large, x).
Two additional action-layer specific pitfalls:
- After long-press, release should not count as a click (use
longFiredflag); otherwise the long-press menu triggers an immediate expand. - Right-click must be intercepted before
pointerdown(e.button !== 0and return); otherwise right-click starts a drag.
7. Acceptance (Run After Every Change)
?selftest=1 covers 13 tests: single click expand/collapse, long-press bubble, Esc to close bubble, right-click alternate menu, Dock split and merge, fusion neck, arrow key selection, Esc global collapse, double-click lift, inertia, W light path field.
Manual verification:
- Content inside glass is correctly oriented (no upside-down, no mirror)
- Rim glow around the edge, top specular, bottom bright arc all present
- Under dark background, glass interior is not completely black (has misty gray)
- Ghost lags behind during drag, release has inertia then snap
- Split panels "crack apart", not "pull apart"
- Scrolling text fades at edges, switches to hard hairline at endpoints
- All three accessibility toggles work (reduce transparency / increase contrast / reduce motion)
8. Performance Budget
| Item | Budget |
|---|---|
| Concurrent glass panels | ≤10 (this implementation has 10, including zero-width bubble and bridge appearing on demand) |
| Draw calls | 2 programs + 1 AABB draw per panel |
| Background upload | Every 5 frames; can be 8 frames when static |
| Brightness sampling | Every 10 frames, only for panels with w*h>24000 |
| Render scale | <42fps → 0.72, >56fps → 1.0, DPR cap 2 |
| Degradation chain | Reduce panels → reduce scale → reduce upload → disable dispersion → fall back to CSS version |
9. Red Lines and Platform Boundaries
- Glass is only used on the navigation layer; content layers do not use glass.
- Do not stack glass (loss of refraction reference, looks like dirty smudge); Regular and Clear variants are not mixed on the same screen.
- Tint is only applied to primary actions; highlights should be restrained,
rim > 1.2looks fake. - Web cannot achieve: text/icons on glass are not refracted by themselves (that requires the iOS 26 system compositing pipeline); CSS fallback cannot produce per-pixel lens rim and chromatic dispersion.
- Not covered by this implementation: true metaball union (this impl uses narrow-neck approximation), device tilt lighting, per-frame dominant color statistics for live video.