Legibility & theme

Text on glass sits over whatever the glass sits over, so its colour cannot be fixed in advance. The components (GlassBar, GlassButton, GlassCard, the text field, the alert, the menu and the popover) choose black or white for their labels, from the finish and from what you told the host is behind the glass.

All of that lives in a GlassTheme: the host installs one, and you can nest another to give a subtree its own finish, tier or backdrop.

When to use

• Declare the backdrop on the host, always: backdrop: for a flat colour, richBackdrop: true for images and feeds.
• Add minLabelContrast: kTextContrastAA when text sits on clear glass or over bright content.
• Nest a GlassTheme below the host when one part of a screen differs: a light panel, a cheaper list.
• Read GlassTheme.of(context).legibility() when you put your own text on a raw GlassSurface.
• Don't put a GlassTheme above the host: the host installs its own and overrides it.

Usage

// A panel over a light page, below the app's host.
GlassTheme(
  data: GlassTheme.of(context).copyWith(
    backdrop: const Color(0xFFF2F2F7),
    finish: GlassFinish.regularLight,
  ),
  child: const GlassCard(child: Text('Black text, chosen for you')),
)

How the label is chosen

• A flat backdrop (backdrop: declared, richBackdrop false): the label is whichever of black or white stands out more against the glass laid over that colour. Exact, because every pixel under the glass is that colour.
• A rich backdrop, or none declared: the label is whichever has the better worst case over any backdrop. In debug, the package warns once when that worst case cannot reach WCAG AA.
• A contrast floor (minLabelContrast:): when neither colour reaches it, the glass is dimmed by the least amount that does. Dimming is a change of tint, so it costs nothing to draw. regularDark needs no dim for AA over any backdrop; clear does.

Glass with labelled: false has no label to protect and is never dimmed.

The demo shows it: drag the backdrop from dark to light and watch the label flip and the contrast change, then switch the floor on with clear glass.

Custom glass

A raw GlassSurface does not colour its child. Ask the theme:

final GlassLegibility look = GlassTheme.of(context).legibility(GlassFinish.clear);
Text('Now playing', style: TextStyle(color: look.label));

look.finish is the finish actually drawn (dimmed, if a floor asked for it), and look.rim the opaque outline under increased contrast, or null.

Code

import 'package:flutter/material.dart';
import 'package:g1455/g1455.dart';

/// A light settings panel inside a dark app, and custom glass that reads
/// its label colour from the theme. Assumes a GlassHost above.
class LightPanel extends StatelessWidget {
  const LightPanel({super.key});

  static const Color page = Color(0xFFF2F2F7);

  @override
  Widget build(BuildContext context) {
    final GlassThemeData outer = GlassTheme.of(context);
    return ColoredBox(
      color: page,
      child: GlassTheme(
        // Inherit the host's tier and contrast; only the backdrop and finish differ.
        data: outer.copyWith(
          backdrop: page,
          richBackdrop: false,
          finish: GlassFinish.regularLight,
          minLabelContrast: kTextContrastAA,
        ),
        child: Builder(
          builder: (BuildContext context) {
            final GlassLegibility look = GlassTheme.of(context).legibility(GlassFinish.clear);
            return Column(
              mainAxisSize: MainAxisSize.min,
              children: <Widget>[
                // A component picks its own label colour.
                const GlassCard(child: Text('Notifications')),
                const SizedBox(height: 16),
                // A raw surface: take the colour from the theme.
                SizedBox(
                  width: 200,
                  height: 56,
                  child: GlassSurface(
                    borderRadius: kGlassCapsule,
                    finish: GlassFinish.clear,
                    child: Center(
                      child: Text('Clear glass', style: TextStyle(color: look.label)),
                    ),
                  ),
                ),
              ],
            );
          },
        ),
      ),
    );
  }
}

API

GlassTheme

GlassLegibility

Constants