هيكل التطبيق

A Scaffold-style layout for liquid-glass UIs.

LiquidGlassScaffold owns a single LiquidGlassView internally so you don't have to wire one up by hand. Your page content goes in body and becomes the background that every glass slot refracts; the appBar, bottomNavigationBar, and bottomNavigationBarAction are placed on top of it as ordinary widgets (typically the package's LiquidGlassLens-based components).

The renderer is chosen automatically — Impeller devices sample the live backdrop, Skia / Web fall back to a captured snapshot — so the same scaffold runs on both.

Z-order

Slots are composited bottom-to-top: lenses → appBar → bottomNavigationBar → bottomNavigationBarAction → floatingActionButton → dialog.

With a glass-pill LiquidGlassTabBar the bar runs two views and places the slots by renderer. On Impeller they sit in its outer view, over the bar's cells and the moving pill, so the order above holds. On Skia they ride its inner view — over the captured body, above the bar's capsule but below its cells and the pill — and the outer view holds the pill and nothing else: that view captures the whole screen a second time, and keeping the chrome out of it is what lets the capture sleep whenever the pill is at rest. So on Skia the bar's cells and pill paint over a lenses entry that overlaps them, and the dialog barrier dims the body and the capsule but not the cells or the pill.

The scaffold's adaptivity: the palettes its glass chrome wears, and the edge strips that drive the system bars.

Two jobs, deliberately kept apart:

• System chrome. For every side systemChrome asks for — the status bar by default — the scaffold pins an invisible strip along that screen edge, the status bar's at the top and the navigation bar's at the bottom, samples it, and drives that bar's icon brightness from the result. A strip judges nothing but its own system bar.
• Chrome palettes. adaptivity is handed down to the app bar, the bottom bar, the action button and any lenses, each of which resolves its own verdict from the background directly behind itself. One config, one verdict per surface.

A strip never captures the chrome: the app bar is judged by the pixels behind the app bar, not by the status bar's strip. Coupling goes the other way round — point a strip at an area's link with topFollowLink / bottomFollowLink and the system bar mirrors that area's verdict. A following strip stops sampling entirely, so it has no region of its own and topHeight / bottomHeight no longer apply to it.

The config's own link is deliberately never inherited by the chrome — otherwise every surface would follow it by accident.

A surface escapes the inherited palettes with LiquidGlassAdaptivity.none; its own style.adaptivity overrides them. LiquidGlassScaffold.adaptivity left null (the default) → nothing adapts unless a widget opts in itself, and no strip is pinned: with nothing to sample there is nothing to tell the OS bars.

A floating, drop-in liquid-glass app bar — a translucent bar with an optional leading widget, a title, and trailing actions, all refracting the content behind it.

Place it wherever you want the bar to sit (a top-aligned Stack child, the appBar: slot of a LiquidGlassScaffold, …). It is a single LiquidGlassLens around its content, so on Impeller it works standalone and on Skia / Web it needs an ancestor LiquidGlassView with a background.

Styling uses the LiquidGlassLens vocabulary — shape, appearance, refraction — each defaulted to a tuned glass. Foreground color is applied to icons and text through an IconTheme / DefaultTextStyle, so a plain Icon(...) or Text(...) automatically picks up foregroundColor.

A floating, drop-in liquid-glass bottom navigation bar.

It is a single LiquidGlassLens capsule with the icons, labels, and the selection highlight baked into the lens child — so drop it wherever you want the bar to sit (most commonly the bottomNavigationBar: slot of a LiquidGlassScaffold).

The bar capsule's look is one LiquidGlassStyle (style — shape + appearance + refraction), plus grouped itemStyle / pillStyle descriptors for the icons and selection pill.

By default the selection moves instantly between tabs. Set the pill style's animated: true to make the selection pill slide. When pillStyle's mode enables the glass-refracting morph pill, a LiquidGlassScaffold swaps in the self-contained dual-pipeline variant via buildGlassPillBar.

Description of a single tab in LiquidGlassTabBar.

Companion floating action button rendered as its own liquid-glass pill, mirroring the pattern of pairing a tab bar with a separate, side-floating action (often Search).

Item group for LiquidGlassTabBar: how each tab's icon and label render. Defaults mirror the bar's flat parameters, so swapping APIs is lossless.

Selection pill group for LiquidGlassTabBar: everything about the highlight behind the active tab — its look, whether it slides, and whether/where it upgrades to the glass-refracting morphing pill. Defaults mirror the bar's flat parameters, so swapping APIs is lossless.

The three tiers, all configured here:

• glass-refracting morphing pill — the default (mode LiquidGlassPillMode.both): the dual-pipeline pill that refracts the bar itself. The distortion/growHeight/… knobs below apply to this tier only. A settled bar costs no shader pass, no clip and no capture, on either backend.
• sliding highlight — mode none + animated true: the pill slides between tabs with the iOS-26 icon-reveal, drawn inside the lens (works on every renderer);
• static highlight — mode none, animated false: the flat instant highlight, the cheapest tier of all.

Magnifier pill group for LiquidGlassTabPillStyle: the invisible second pill mounted under the moving glass pill on the Impeller path. It shares the glass pill's silhouette, lift, travel, squash and shed exactly, but is transparent, unblurred, undistorted, rimless and shadowless — its one job is to magnify the bar seen under the pill (it sits below the icon shell, so the icons keep their size).

Impeller only: stacked lenses chain there, so the glass pill above refracts this pill's output. The Skia capture path never mounts it, whatever these fields say.

Which renderer(s) get the full iOS-26 glass-refracting morphing pill (the dual-pipeline animated bar). See LiquidGlassTabBar.glassPill for how to opt in.

Everything a LiquidGlassGlyphBuilder needs to draw one glyph in the state its host is currently rendering it.

color is the already resolved color a plain Icon would have received for this exact layer — the item style's selected/unselected color, the action's foreground, the tile's glyph color. Tint with it and custom art follows every state change the built-in icons follow, including the nav bar's moving-pill reveal.

On the nav/tab bars a glyph is in one of three states:

• unselected — selected and underGlass both false;
• selected — selected true: the committed tab, whether or not a pill is on it (a bar may hide its pill entirely);
• under glass — underGlass true: the moving glass pill is over this layer right now — lifted on it, dragged across it, or sweeping past it mid-travel. A flat pill is not glass, so the static rest highlight never sets it.

Builds custom glyph content — an SVG, a PNG, a CustomPaint, a badge — anywhere the package would otherwise draw an Icon.

Called once per rendered layer, so on the nav bar's glass-pill tier it runs for both the inside-the-pill and outside-the-pill passes of the same tab, each with its own LiquidGlassGlyph.color and LiquidGlassGlyph.selected.

Multi-color art can simply ignore the color and stay as authored.

Everything a LiquidGlassLabelBuilder needs to draw one tab label in the state its host is currently rendering it.

Mirrors LiquidGlassGlyph: color, fontSize and fontWeight are the already resolved values the default Text would have received for this exact layer — the item style's selected/unselected color, its per-state font size and weight. Style with them and a custom label follows every state change the built-in labels follow, including the nav bar's moving-pill reveal. The same three states apply: unselected, selected (the committed tab), and underGlass (the moving glass pill is over this layer right now — see LiquidGlassGlyph.underGlass).

Builds custom label content — a different font, rich text, a badge row — anywhere the package would otherwise draw the item's label as a plain Text.

Called once per rendered layer, like LiquidGlassGlyphBuilder: on the nav bar's reveal tiers it runs for both the inside-the-pill and outside-the-pill passes of the same tab, each with its own resolved LiquidGlassLabel.color / LiquidGlassLabel.selected. The two passes share one layout, so return the same-sized widget for both states or the reveal clip will show a seam.