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_CONFIG
references/optics.css — material, plates, focus frames, reveal layers, reduced-motion
references/engine-notes.md — architecture, tuning cheat-sheet, all known pitfalls
references/validation-playbook.md — numeric Playwright proofs for every behavior
Reference build: ~/Dev/ai-reboot-content/output/design/prototypes/will-lens-home/