Foundations topic

The material and the host it needs. Everything else in the package is built from these.

The host

GlassHost records what is painted under its glass into one atlas, at a resolution chosen against a measured quality budget, and only when something under the glass changed: a still screen captures nothing, and glass moving over still content inside a GlassTravel captures nothing either. It also takes what the application knows and the render tree does not: the GlassHost.backdrop behind the glass, GlassHost.richBackdrop, GlassHost.minLabelContrast, the GlassHost.thermal state, GlassHost.hardware and GlassHost.highContrast.

GlassHost(
  backdrop: const Color(0xFF101014), // what is behind the glass, on average
  ripple: const GlassRipple(viscosity: 0.3), // every surface answers a touch
  child: navigator!,
)

The surface

GlassSurface is the primitive: a region of the screen that is glass, with a corner radius drawn as the engine's round superellipse, an optional finish, and two ways in and out: materialize, the whole shape at once (blur first, tint last), and presence, which erodes it (for budding inside a GlassGroup).

GlassSurface(
  borderRadius: const BorderRadius.all(Radius.circular(28)),
  finish: GlassFinish.clear,
  child: const Padding(padding: EdgeInsets.all(20), child: Text('Clear glass')),
)

Most screens never use it directly: GlassBar, GlassButton and GlassCard are surfaces with a label colour chosen for legibility.

Finishes

A GlassFinish is what the glass does to the light: the blur, the tint, the rim and the GlassOptics of the edge. Four are calibrated against Apple's own materials on iOS 26:

Finish Looks like
GlassFinish.regularDark .regular over dark content: dark, and barely transmitting
GlassFinish.regularLight .regular over light content
GlassFinish.clear .clear: no blur, a light tint, the bend in full
GlassFinish.frosted heavy blur, a frosted pane

Name none and the host picks the branch of .regular the way Apple does: from the declared backdrop and the platform's appearance, or, with a GlassAdaptive on the host, from what each glass reads under it.

The theme

GlassTheme hands a subtree its GlassThemeData: the finish every surface wears unless it names its own, the tier, the label floor, the drop motion. GlassThemeData.legibility answers the label colour for a finish, as GlassLegibility.

Optional

  • GlassRipple: a viscous wave from the touch, from water to honey. No capture, no repaint; off under reduced motion.
  • GlassAdaptive: glass that reads its own backdrop and picks its branch and label from it.
  • GlassDropMotion: how the held drop of a switch, a slider, a segmented control or a tab bar stretches as it sets off and squashes as it stops.

Classes

GlassAdaptive Foundations
How a GlassHost's glass reads its own backdrop: pass one as GlassHost.adaptive to turn it on.
GlassBackdropReading Foundations
What one glass read of the backdrop under it: the mean of the captured pixels inside its box.
GlassDropMotion Foundations
How a held drop deforms as it moves: stretched along its travel while it speeds up, squashed while it slows down, round at a constant speed.
GlassDropStretch Foundations
The deformation of one drop, fed where the drop is once a frame.
GlassDropStretchDriver Foundations
Runs a GlassDropStretch off a ticker while its drop moves, and says when the deformation changed. The package's controls' half of the mechanism.
GlassFade Foundations
A fade across a glass surface: whole at begin, gone at end, a smoothstep between — in the surface's own logical coordinates.
GlassFinish Foundations
What the glass does to the light it lets through: how much it blurs and how much of it survives.
GlassHost Foundations
Owns the whole proxy pipeline for one screen: it captures what is painted under the glass and hands it to every GlassSurface below it.
GlassLegibility Foundations
What a surface under a theme actually draws: the finish after any dim, the label colour, and the outline under increase contrast.
GlassOptics Foundations
The shape of the refraction: how far in it reaches, how hard it bends, and how it falls off.
GlassRipple Foundations
How a glass surface answers a touch with a wave.
GlassSurface Foundations
Declares a region of the screen as glass.
GlassTheme Foundations
Carries GlassThemeData down the tree.
GlassThemeData Foundations
The tokens a screen's glass reads.
RenderGlassSurface Foundations
The render object behind GlassSurface.

Constants

kAppleDimmingOpacity → const double Foundations
The dimming layer Apple's guidelines put behind clear Liquid Glass over bright content: "consider adding a dark dimming layer of 35% opacity" (HIG, Materials).
kCalibratedRim → const Color Foundations
What the outline adds, and it adds rather than mixes.
kGlassCapsule → const BorderRadius Foundations
A radius larger than any box, which is how a capsule is declared.
kHighContrastRimWidthLogical → const double Foundations
Width of the outline under the platform's increase-contrast switch, logical px.
kMaterialScaleDeltaE → const double Foundations
ΔE between Glass.regular and Glass.clear on one backdrop (S4) — the only external unit this project has.
kMaxRippleWaves → const int Foundations
The most waves one draw evaluates; kMaxWaves in the shader.
kNonTextContrast → const double Foundations
WCAG 2.2's contrast floor for a component's boundary against what is next to it (SC 1.4.11, non-text contrast).
kRimWidthLogical → const double Foundations
Width of the outline, in logical pixels — measured, not chosen.
kTextContrastAA → const double Foundations
WCAG 2.2's AA floor for body text (SC 1.4.3).

Properties

debugPaintGlassSurfaces ↔ bool Foundations
Outlines every registered surface and prints nothing.
getter/setter pair