التكيّف والوضوح

iOS-style adaptivity: the glass tint and the lens content switch between two palettes depending on whether the background behind the lens is dark or light.

Attach it to a style and LiquidGlassLens does the rest:

How the verdict is decided, in priority order:

1. permanentBrightness, when set — a manual override; no sampling runs at all. 2. Automatic sampling, when the lens sits inside a LiquidGlassView: the view captures its backgroundWidget at a very low pixel ratio and frame rate (see LiquidGlassView.adaptiveSampling), converts the sampled sRGB pixels to perceptual CIE L* lightness, and classifies the area with temporal smoothing and hysteresis. 3. brightnessFallback, as a last resort (a standalone Impeller lens has no readable backdrop) — the app theme's brightness by default, or the platform's.

What gets tinted. The glass fill uses the active glassColorOn* (overriding appearance.color while adaptivity is enabled). The child is wrapped in IconTheme + DefaultTextStyle carrying the active contentColorOn*, so any Icon or Text that doesn't hardcode its own color adapts automatically. Both animate together over duration on every flip.

Tuning for the background sampling that powers LiquidGlassAdaptivity inside a LiquidGlassView.

The sampler is a second, tiny capture of the view's backgroundWidget — completely separate from the rendering capture. It runs only while at least one descendant lens has adaptivity enabled, is self-paced (a new sample never starts before the previous readback finished), and reads back a few kilobytes per sample. It is also idle-gated: while no frames are being rendered (a fully static screen), no captures run at all — pixels can only change through a rendered frame, so a frameless stretch is guaranteed unchanged.

An invisible region that drives adaptivity for everything inside it — the group form of LiquidGlassStyle.adaptivity, with zero wiring.

The area paints nothing. Its laid-out bounds are the measured region: through the enclosing LiquidGlassView's luminance sampler it reads the background under itself, decides one dark/light verdict (hysteresis, animated flips — the same machine every adaptive widget uses), and every adaptive descendant follows it automatically. One region, one verdict, lockstep flips for the whole cluster:

What descendants do. A descendant with no adaptivity of its own inherits the area's (palettes, duration, everything). A descendant with its own adaptivity keeps its palettes but still follows the area's verdict — unless it carries an explicit permanentBrightness (manual always wins) or its own link (an explicit channel wins over the enclosing area).

Outside followers. Give the area's adaptivity a LiquidGlassAdaptivity.link and the area publishes its verdict there, so widgets that can't sit inside the subtree (other overlays, pipelines) can follow the same verdict by carrying the same link.

Verdict sources, in the usual priority order: a manual permanentBrightness on adaptivity; else sampling through the enclosing LiquidGlassView (opt in with its adaptiveSampling); else the platform brightness. Without a view (standalone Impeller) the area still works — it just can't sample.

What a LiquidGlassAdaptiveArea exposes to its descendants: the adaptivity to inherit and the link carrying the area's verdict.

Makes bare content adaptive — icons and text that sit directly on the page with no glass behind them (a hero title over a photo, a floating caption) follow the animated adaptive content color exactly like a lens child would.

A LiquidGlassLens installs the adaptive content color only for its own child; content outside any lens has no way to adapt. This wrapper closes that gap: it runs the same verdict machine and installs the animated IconTheme + DefaultTextStyle over child, so any Icon or Text inside that doesn't hardcode a color adapts automatically.

Verdict sources — the standard consumer chain: adaptivity's manual permanentBrightness → its explicit link → the enclosing LiquidGlassAdaptiveArea → own sampling of this widget's bounds through the enclosing LiquidGlassView (needs its adaptiveSampling) → platform brightness. With adaptivity null the enclosing area's config is inherited entirely; with no area either, the widget is inert and just returns child.

Shares one adaptivity verdict between widgets that can't sit in the same subtree, so they flip together — same state, same instant.

The common case doesn't need a link at all: wrap the widgets in a LiquidGlassAdaptiveArea and they follow it automatically. Reach for a link when a follower lives in a different subtree or pipeline: a LiquidGlassAdaptiveArea publishes to the link it's given, and any consumer widget given the same link follows it. Give publisher and followers the same duration and their transitions run in lockstep.

Use exactly one publisher per link. The link is a plain ValueNotifier<Brightness?>, so an app can also drive a whole group by setting value itself.

Runtime pause/resume switch for LiquidGlassAdaptivity — attach one via LiquidGlassAdaptivity.controller and every widget carrying that config obeys it. Share one instance across configs for a page-wide master switch.

Disabled = hold, not off. The palettes stay applied, frozen at the current verdict (at mount that's the initialBrightness guess), and background sampling stops completely — zero captures while disabled. A manual permanentBrightness still applies (it is an explicit override, not adaptation). On enable sampling resumes and the next verdict animates in; adaptOnce instead takes a single on-demand look while staying disabled. For a permanent opt-out use LiquidGlassAdaptivity.none instead.

The classic use is entry control — mount frozen on the guess, adapt only once the page has settled:

Owned by the developer — dispose it like any controller.

Where a verdict comes from when there is nothing better: no permanentBrightness, no link to follow, no enclosing area, no sampler, and no initialBrightness guess.

It is the bottom of the chain, so it only decides anything for glass that cannot read its backdrop — a lens over a live Impeller backdrop, or any surface in a view that never opted into adaptiveSampling.

Which system bars an adaptive widget's verdict also drives — the glass and the OS chrome flip together, like Android's own gesture pill.

Honored by LiquidGlassAdaptiveArea.systemChrome and LiquidGlassScaffold.systemChrome. Implemented declaratively with Flutter's AnnotatedRegion, so the influence exists exactly while the widget covers the system bar's probe point (bottom-center of the screen for the navigation bar, top-center for the status bar) and vanishes on unmount — no global state, nothing to undo.

Only the icon brightness of the bars is driven; their colors are never touched. With none no AnnotatedRegion exists in the tree at all — the feature is completely off. LiquidGlassAdaptiveArea defaults to none; LiquidGlassScaffold defaults to statusBar.

iOS-style scroll edge treatment: a fading dim band pinned over a scrollable's edge so floating glass elements (nav pills, app bars) stay legible over whatever scrolls beneath — the "subtle dimming" variant of Apple's scroll edge effect, without any blur of its own.

Place it inside a LiquidGlassView's child, pinned to an edge, under your floating glass elements:

Adaptivity (optional). With adaptivity set and an ancestor LiquidGlassView, the band registers with the view's shared luminance sampler (same one LiquidGlassLens uses — no extra captures) and animates between two tints: glassColorOnDark while the background under the band is dark, glassColorOnLight while it is light. A child placed in the band gets the matching contentColorOn* through IconTheme/DefaultTextStyle, exactly like the lens. Without a view, the verdict falls back to adaptivity.permanentBrightness, then platform brightness. With adaptivity left null the band is a static fade of color — no sampling, no animation, no cost beyond one gradient.

Blur. blur blurs the backdrop under the band as exactly one `BackdropFilter` — one backdrop read, one blur pass, at any sigma and on every backend. It defaults to 5; pass 0 to switch it off, and then no filter exists in the tree at all. Inside a LiquidGlassBatch that pass joins the batch: it reads the batch's one copy of the backdrop instead of taking its own, like every lens in there. The band is pinned over what scrolls under it, so it is an overlap in the batch's sense — see LiquidGlassBatch for what that costs and when to keep it out.

style decides only whether that pass is feathered: LiquidGlassScrollEdgeStyle.soft — the default — fades the blur out across the band with a dstIn ramp so it meets sharp content without a seam, while LiquidGlassScrollEdgeStyle.hard leaves it uniform and ends on a line. Neither costs more than the other.

curve shapes the tint's falloff; blurCurve shapes the blur's, and by default keeps nearly all of it across the first half of the band so chrome stays legible over what passes under it.

The fade itself never blocks touches: scrolls and taps pass through to the content beneath. Only child is hit-testable.

Which screen edge a LiquidGlassScrollEdge hugs. The fade is fully opaque at that edge and dissolves to transparent toward the content.

How a LiquidGlassScrollEdge layers its backdrop blur. Both styles paint the same tint ramp; only the blur differs.