| name | liquid-glass-lens |
| description | Retrofit an existing website with a concept-driven cursor-lens liquid glass system — flat-slab refraction with prism rim dispersion, zone-driven content magnification, iOS-style dock fusion into controls, zone-driven optics tied to scroll narrative, liquid inertia (squash & stretch with jelly settle), uneven jelly edge physics, ambient cursor light, and reveal/focus/secret payloads. Use when asked to add meaningful glass/lens/water-drop cursor effects, liquid-glass UI selection states, or to reproduce the Will Lens-quality optics on another project. |
Liquid Glass Lens
Apply the battle-tested cursor-lens optical system to an existing site. The reusable core is generic (engine + material + physics); what changes per site is the meaning assignment and the application map. Never ship the effect as decoration — every behavior must be explainable by the site's concept, or it is AI-slop.
Companion skill: curved-glass-refraction (displacement-map fundamentals). This skill supersedes it for full-page lens systems.
Workflow
1) Concept fit — decide if and what the lens means
Read the site's brand/concept material (or derive a one-line thesis from its copy). Assign meaning before writing any code:
| System part | Must answer |
|---|
| The glass/lens | What does "looking through" represent for this brand? |
| The cursor light | Whose light is it? What does it stand for? |
| Refraction / reveal | What changes when seen through the lens? (A→B word swap, blur→sharp, hidden→found) |
| Zones across scroll | What narrative arc do the sections form? Name zones after it. |
| Magnification slope | Why does the lens enlarge what it holds, and where most? (e.g. Will Lens: the deeper the question, the larger it appears) |
| Dock | What does "the glass settling onto a control" mean? (e.g. the tool yields when the human decides) |
| The finale | Where does the lens recede and leave only the user? |
If no honest mapping exists, recommend against the effect and say why. A lens without meaning is the failure mode this system was built to avoid.
2) Audit — application map
Walk the site (Playwright or source) and produce a table: section → zone name → physics (s/depth/glow/mag) → payloads. Candidate placements:
- Reveal stage (usually hero): A/B layer swap — the signature moment. Needs a containing block for both layers.
- Focus frames: imagery that sits soft and resolves sharp inside the lens (cards, future-state visuals).
- Dock targets: nav links, buttons, chips (≤ ~520×220). Identify oversized interactive rows to exclude.
- Quiet zones: dense text/forms — small droplet, shallow depth. Header bar is always
chrome.
- Finale zone: lens scale → 0, glow → max.
- Secrets: ≤3 hidden margin notes that reward exploration; place them where they deepen copy, never where the lens is absent.
3) Plan
Write a short plan: zone table, dock selector + exclusions, reveal/focus/secret inventory, palette derivation (glow tint and plate tint from the site's background family, fallback ring from its accent hues), z-index of the site header (for .over-header), and which existing :hover effects will be replaced by the fused .is-lens-docked state.
4) Implement
- Copy
references/optics-engine.js and references/optics.css into the project.
- Add the DOM scaffold (defs + cursor-light + lens — see the engine header comment) at the end of
<body>.
- Define
window.LENS_CONFIG before the engine script: zones, dockSelector, chromeBar, revealStage/autopilotZone if used.
- Tag sections with
data-optics="<zone>"; build reveal layers / .focus-frame (.if-soft + .if-sharp) / .lens-secret payloads.
- Adapt the CSS tints (marked in optics.css) to the site palette; fuse replaced hovers via
.is-lens-docked (keep :hover as reduced-motion/no-JS fallback).
- Reduced motion: verify the page is complete with the lens removed — sharp layers shown, reveals resolved to the B state.
5) Tune & validate
Tune with the cheat-sheet in references/engine-notes.md (depth, dispersion spread, flat plateau, spring constants, stretch gain, zone mag). Then run references/validation-playbook.md end-to-end — zone sweep, dock geometry, the menu-transit balloon regression, edge-squish asymmetry, liquid-inertia stretch/wobble/rigidity, glow discipline, containing-block Δ0 check, headless prism + magnification proofs, 390px overflow, reduced-motion. Finish with a real-Chrome pass (refraction/dispersion are Chromium-only; Safari/Firefox get the designed fallback).
Non-negotiables (the design bar)
- Flat-slab profile + rim-only dispersion — never a spherical soap bubble, never a round specular blob.
- Docked-and-settled glass must not blur UI text; liquid smear is for transit only.
- The cursor light has no hot core, tracks ~1:1, and yields entirely while docked.
- Edge deformation is uneven (per-side springs, per-corner flatten) and the frame is never touched — including by the stretched body (exact rotate-scale extents in the clamp).
- Static free lenses must not leak 1px red/cyan pixels on the top/left edge. Keep the live
.lens clipping overflow, inset .lens-glass by 1px, and use box-shadow for the outer shadow; never put filter: drop-shadow(...) on .lens, because it can kill backdrop-filter: url(#liquid-lens-refraction).
- Liquid inertia stretches the free body only: the docked plate stays rigid, and the settle wobble (soft underdamped spring) is required — a stretch that just fades reads as a rigid puck.
- Magnification is a pure linear field (uniform zoom, zero warp, no color fringe) applied before the prism stages; the settled docked plate stays at ×1.
- Menu gaps must not balloon the lens (grace timer + chrome zone + re-grow clamp).
- Independent hover effects on dock targets get fused into the plate, not stacked under it.
References
references/optics-engine.js — drop-in engine, configured via window.LENS_CONFIGreferences/optics.css — material, plates, focus frames, reveal layers, reduced-motionreferences/engine-notes.md — architecture, tuning cheat-sheet, all known pitfallsreferences/validation-playbook.md — numeric Playwright proofs for every behavior- Reference build:
~/Dev/ai-reboot-content/output/design/prototypes/will-lens-home/
