liquid-glass-widgets
Skill854 starsChanged 7 months agoMITView on GitHub
Mastery guide and architectural rules for liquid_glass_widgets. Trigger whenever generating, refactoring, or reviewing Flutter UI code using liquid glass, iOS 26/27 aesthetics, GlassScaffold, GlassTabBar, GlassModalSheet, or any Glass* components.
1 other project uses a version of this.
Adopted by
Most recently taken up by
- sesori-ai/sesori_apps_monorepotheir own version, first seen Nov 8, 2026
Other versions1 project uses a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 1
- sesori-ai/sesori_apps_monorepo★ 143same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repositoryOne other file it gives its agents.
- AGENTS.mdAGENTS.md
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 10
Follow this guide strictly when writing, refactoring, or reviewing UI code to ensure high visual fidelity, 60/120 fps GPU performance, and …
- Distinctive: line 173
When generating Flutter UI, replace standard Flutter widgets with their native liquid glass counterparts:
- Very specific: line 284
Do not build nested menus by opening a second GlassMenu from an item's onTap.
- Very specific: line 285
Use GlassMenuItem.semanticsSelected: true (alongside a checkmark trailing) to announce the active choice to VoiceOver/TalkBack …
- Very specific: line 426
Use GlassAppBar.pinned on destination screens.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Liquid Glass Widgets — AI Agent Guide
This skill defines the architecture, design principles, API dictionary, and strict implementation rules for building Flutter applications with liquid_glass_widgets.
Follow this guide strictly when writing, refactoring, or reviewing UI code to ensure high visual fidelity, 60/120 fps GPU performance, and zero hallucinations.
1. Golden Architectural Rules (Mandatory)
Rule 1: Glass is a Platter, Not a Wrapper
Glass in the iOS 26 design system is reserved for the navigation and control layer — floating chrome that sits above content.
- DO use glass for: Navigation bars (
GlassAppBar), tab bars (GlassTabBar), floating buttons (GlassButton,GlassIconButton), toolbars, modal sheets (GlassModalSheet), dialogs (GlassDialog), and standalone floating cards (GlassContainer.card). - DO NOT use glass for: Full-screen backgrounds, dense list view items, video players, image galleries, or text article bodies. Backgrounds should be rich wallpapers or gradients; content cards should be clean and readable. Cards, chips, and inputs inside scrolling lists should use
surfaceStyle: GlassSurfaceStyle.solid(onGlassContainer.card,GlassGroupedSection,GlassReorderableList.grouped,GlassDisclosureGroup.standalone,GlassDatePicker,GlassMultiDatePicker,GlassTextField,GlassSearchBar,GlassTextArea,GlassPasswordField,GlassPicker, orGlassChip): a flat opaque card or translucent input/pill well matching native iOS inset-grouped lists. Inputs, pickers, and chips placed inside a solid card/section inheritsolidautomatically viaInheritedGlassSurfaceStyle.glassis the 1.x default;solidbecomes the default in 2.0.0.
Rule 2: NEVER Nest Refractive Glass inside Refractive Glass
Placing refractive glass widgets inside another refractive glass container is an optical and performance anti-pattern.
- CRITICAL ANTI-PATTERN: Placing
GlassButton,GlassIconButton, or glass-modeGlassChipinside aGlassContainer.card,GlassGroupedSection,GlassDialog, orGlassContainer. - Why? These controls provide their own persistent refractive surface. Nesting creates severe double-refraction distortion, clips spring jelly animations, and wastes GPU fill-rate.
- Exception —
GlassSwitch,GlassSlider,GlassSegmentedControl: their glass is transient (only the thumb or pill turns to glass while it is touched or moving; at rest they look flat), so they are safe inside aGlassContainer.card/GlassGroupedSectionwithsurfaceStyle: GlassSurfaceStyle.solid, which has no glass layer at all. This is the native iOS Settings pattern. On a defaultglasscard, prefer placing them outside the card. - Correct Pattern:
- In a
solidcard orGlassGroupedSection: standard text and icons,GlassListTile,GlassTextField/GlassSearchBar/GlassTextArea/GlassPasswordField/GlassPicker/GlassChip(auto-inheritsolidwell styling),GlassSwitch,GlassSliderandGlassSegmentedControl. - In a
glasscard: standard text, icons, and non-refractive controls (orGlassListTile, which has no internal glass layer). - Outside the card / on the page platter:
GlassSegmentedControl,GlassButton,GlassSlider, or standaloneGlassSwitch(useOwnLayer: true).
- In a
Rule 3: Single Public Import
- ALWAYS:
import 'package:liquid_glass_widgets/liquid_glass_widgets.dart'; - NEVER import
package:liquid_glass_widgets/src/.... - NEVER instantiate
LiquidGlass(...)directly — it is an internal Impeller-only renderer. Always useAdaptiveGlassor the high-levelGlass*widgets.
Rule 4: Ban Obsolete Pre-1.0 APIs
GlassBottomBarandGlassSearchableBottomBarwere deleted in v1.0.0.- ALWAYS USE:
GlassTabBar.bottom(...)orGlassTabBar.searchable(...).
Rule 5: Honor Quality Tiers
GlassQuality.premium: Multi-pass Impeller shader with chromatic dispersion, realistic refraction, and dynamic specular highlights. Default underGlassStyle.ios27(default) andGlassStyle.ios26for:- Persistent navigation chrome (
GlassAppBar,GlassTabBar,GlassToolbar,GlassScaffold.bodyOverlays— automatically wrapped inGlassIsolationScope(defaultQuality: GlassQuality.premium)). - Transient overlays (
GlassDialog,showGlassActionSheet,GlassMenu,GlassPopover,GlassToast). - Hero interactive lenses (
GlassSwitch,GlassSlider,GlassSegmentedControl— whereGlassSwitchandGlassSliderlazy-mountLiquidGlass.withOwnLayeronly while pressed/dragged so resting list rows mount zero shader layers).
- Persistent navigation chrome (
GlassQuality.standard: Highly optimized single-pass fragment shader. Default for cards, containers, standalone body buttons, input fields, and all widgets whenGlassThemeData(style: GlassStyle.classic)is active.GlassQuality.minimal: Lightweight shader-free fallback (BackdropFilteronly). Use for ultra-dense scrolling lists or low-power modes.- Avoid setting
quality: GlassQuality.standardglobally onGlassThemeDataunless you intentionally want to downgrade navigation bars, overlays, and hero lenses across the app.
2. App Lifecycle & Initialization
In main.dart, always initialize the shader pipeline before runApp(), and wrap the application with LiquidGlassWidgets.wrap().
import 'package:flutter/cupertino.dart';
import 'package:flutter/material.dart';
import 'package:liquid_glass_widgets/liquid_glass_widgets.dart';
void main() async {
WidgetsFlutterBinding.ensureInitialized();
// Pre-warms fragment shaders in parallel to prevent first-frame white flashes or shader jank
await LiquidGlassWidgets.initialize();
runApp(
LiquidGlassWidgets.wrap(
adaptiveQuality: true, // Dynamically benchmarks device raster budget and scales quality
respectSystemAccessibility: true, // Automatically degrades on Reduce Motion / Reduce Transparency
// CRITICAL FOR MATERIAL APPS: Bridges Material ThemeMode without importing flutter/material in the engine
brightnessResolver: Theme.maybeBrightnessOf,
// Choose one of three built-in design-era presets:
// - const GlassThemeData() or const GlassThemeData.ios27() (default iOS 27 optics)
// - const GlassThemeData.ios26() (iOS 26.0 optics)
// - const GlassThemeData.classic() (v1.x classic look & GlassQuality.standard defaults)
// Or customize via GlassThemeData.simple(style: GlassStyle.ios27, ...):
theme: const GlassThemeData(),
child: const MyApp(),
),
);
}3. Screen Architecture: GlassScaffold
For any screen featuring liquid glass navigation bars or floating surfaces, always use GlassScaffold instead of Flutter's built-in Scaffold.
GlassScaffold solves complex compositing challenges automatically:
- Guaranteed Z-Ordering: App bars and bottom bars paint above scrolling body content, preventing body cards from overlapping navigation buttons.
- Edge Fading: Content fades smoothly as it scrolls under bars (
.scrollEdgeEffectStyle(.soft)matching iOS 26). - Content-Aware Brightness: Dynamically flips app bar icons and typography between light and dark depending on the luminosity of the content scrolling underneath.
- Auto-Padding: Automatically accounts for safe areas and bar heights.
class HomeScreen extends StatefulWidget {
const HomeScreen({super.key});
@override
State<HomeScreen> createState() => _HomeScreenState();
}
class _HomeScreenState extends State<HomeScreen> {
int _selectedTab = 0;
@override
Widget build(BuildContext context) {
return GlassScaffold(
// 1. Wallpaper background (image, gradient, or solid)
background: Image.asset('assets/wallpaper.jpg', fit: BoxFit.cover),
contentAwareBrightness: true,
// 2. Navigation Bar
// GlassAppBar uses `actions` (List<Widget>), not `trailing`.
appBar: GlassAppBar(
title: const Text('Dashboard'),
actions: [
GlassIconButton(
icon: const Icon(CupertinoIcons.bell_fill),
onPressed: () => _openNotifications(),
),
],
),
// 3. Unified Bottom Tab Bar
bottomBar: GlassTabBar.bottom(
selectedIndex: _selectedTab,
onTabSelected: (index) => setState(() => _selectedTab = index),
tabs: const [
GlassTab(icon: Icon(CupertinoIcons.house_fill), label: 'Home'),
GlassTab(icon: Icon(CupertinoIcons.chart_bar_fill), label: 'Stats'),
GlassTab(icon: Icon(CupertinoIcons.gear_alt_fill), label: 'Settings'),
],
),
// 4. Scrollable Body Content
body: ListView(
padding: const EdgeInsets.symmetric(horizontal: 16, vertical: 20),
children: [
// Content cards in scrolling lists use GlassSurfaceStyle.solid
GlassGroupedSection(
surfaceStyle: GlassSurfaceStyle.solid,
header: const Text('ACCOUNT'),
children: [
GlassListTile(
leading: const Icon(CupertinoIcons.person_fill),
title: const Text('Profile'),
trailing: GlassListTile.chevron,
onTap: () {},
),
GlassListTile(
leading: const Icon(CupertinoIcons.lock_shield_fill),
title: const Text('Privacy & Security'),
trailing: GlassListTile.chevron,
onTap: () {},
),
],
),
],
),
);
}
}4. Component Dictionary & Substitution Table
When generating Flutter UI, replace standard Flutter widgets with their native liquid glass counterparts:
| Flutter Standard Widget | Liquid Glass Replacement | Key Usage Notes |
Scaffold | GlassScaffold | Handles z-order, edge fading, content-aware brightness, and native rounded page clipping during route transitions (transitionCornerRadius). |
AppBar / CupertinoNavigationBar | GlassAppBar | Transparent iOS 26 style by default. Supports .pinned for gel morph. |
BottomNavigationBar / CupertinoTabBar | GlassTabBar.bottom | Unified glass navigation pill (GlassBottomBar is deleted). settings: styles the bar platter; indicatorSettings: (e.g. LiquidGlassSettings.classicIndicator) styles the animated pill. |
| Bottom nav that collapses to selected tab on scroll | GlassTabBar.minimizable | Minimizes to a single pill on scroll; supports an optional trailing action button. |
ElevatedButton / CupertinoButton | GlassButton | Refractive button with squeeze & stretch physics, touch glow, and optional pressLightColor (or GlassGlowColors.pressLight on GlassThemeData). |
IconButton | GlassIconButton | Refractive circular/squircle button with onPressed. |
Chip / FilterChip / ActionChip | GlassChip | Refractive pill (label is String, not Widget) with optional icon, selected, onDeleted, or shader-free pill well (surfaceStyle: GlassSurfaceStyle.solid or auto-inherited inside a solid card). |
PopupMenuButton / Pull-Down Menu | GlassPullDownButton | Combined trigger button and GlassMenu (menuSemanticLabel names the open panel; GlassMenu also supports opaqueColor and border). |
CupertinoSegmentedControl | GlassSegmentedControl<T> | Fluid animated glass indicator with jelly physics (settings: for track, indicatorSettings: for pill). Fine inside solid cards; on a glass card place it outside. |
Switch / CupertinoSwitch | GlassSwitch | Fluid spring jump animation, RTL-aware, honours MediaQuery.onOffSwitchLabelsOf (onLabelColor / offLabelColor). Pass onChanged: null to disable. Use useOwnLayer: true when standalone. |
Slider / CupertinoSlider | GlassSlider | Glass track with draggable jelly thumb and haptic snaps. |
Card | GlassContainer.card | Container for grouping content (surfaceStyle: GlassSurfaceStyle.solid for flat list cards). Content inside stays opaque. |
Grouped ListView | GlassGroupedSection | Inset grouped list container with automatic dividers between GlassListTiles. |
ListTile | GlassListTile | Grouped row item. Shares parent glass layer inside GlassGroupedSection. |
Divider | GlassDivider | Refractive subtle separator line. |
Dismissible / SwiftUI .swipeActions | GlassSwipeActions (or GlassListTile.trailingSwipeActions / leadingSwipeActions) | Leading/trailing circular action buttons with full-swipe. Wrap the list in GlassSwipeActionScope so only one row is open. See Section 6. |
ExpansionTile / SwiftUI DisclosureGroup | GlassDisclosureGroup | Rotating-chevron accordion. Use inside GlassGroupedSection, or GlassDisclosureGroup.standalone(surfaceStyle: ...) for its own card. |
ReorderableListView + edit toggle | GlassEditScope + GlassEditButton + GlassReorderableList.grouped | Edit mode with delete badges, reorder grabbers, selection. See Section 6. |
Long-press context menu / SwiftUI .contextMenu | GlassContextMenu (or .glassContextMenu(), GlassListTile.contextMenuActions) | Row-lift menu with optional previewBuilder. Use GlassPullDownButton for tap-triggered menus. |
Full-screen showDialog / .fullScreenCover | showGlassFullScreenCover + GlassFullScreenCover | Edge-to-edge slide-up cover with swipe-down dismiss. |
showDatePicker / CupertinoDatePicker | GlassDatePicker (.compact, .graphical, .wheel), GlassMultiDatePicker | showGlassDatePicker(...) returns DateTime?. |
Navigator.push rows / SwiftUI NavigationStack | GlassNavigationStack + GlassNavigationLink + GlassPageRoute | Typed value routing via destinations, or a destination builder. Automatically clips pages with rounded superellipse corners during push/pop and swipe-back (transitionCornerRadius; use GlassPageTransitionsBuilder in MaterialApp.theme.pageTransitionsTheme). |
TextField / CupertinoTextField | GlassTextField / GlassSearchBar / GlassTextArea / GlassPasswordField / GlassPicker | Refractive glass input with press glow/scale (glass), or shader-free iOS tertiarySystemFill well (surfaceStyle: GlassSurfaceStyle.solid or auto-inherited inside a solid card). |
showModalBottomSheet | GlassModalSheet.show | Multi-detent fluid sheet (peek, half, full) with spring physics. |
showDialog / CupertinoAlertDialog | GlassDialog.show | Centered 320 pt iOS 26/27 alert platter with 48 pt capsule GlassDialogAction buttons (280 pt on GlassStyle.classic). |
showCupertinoModalPopup / CupertinoActionSheet | showGlassActionSheet | Centered 320 pt iOS 26/27 action sheet platter with stacked capsule GlassActionSheetAction buttons (bottom-docked sheet on GlassStyle.classic). |
SnackBar / Banner | GlassToast | Floating glass HUD banner. |
5. Overlays: Modal Sheets, Dialogs & Transitions
GlassModalSheet
Presents an iOS 26 fluid modal sheet with detents:
GlassModalSheet.show(
context: context,
initialState: GlassSheetState.half,
halfSize: 0.5,
peekSize: 90.0,
builder: (sheetContext) {
return ListView(
padding: const EdgeInsets.all(20),
children: const [
Text(
'Modal Sheet Content',
style: TextStyle(fontSize: 20, fontWeight: FontWeight.bold),
),
],
);
},
);GlassDialog
Presents a native alert dialog:
GlassDialog.show(
context: context,
title: 'Discard Draft?',
message: 'This action cannot be reversed.',
actions: [
GlassDialogAction(
label: 'Cancel',
onPressed: () => Navigator.of(context).pop(),
),
GlassDialogAction(
label: 'Discard',
isDestructive: true,
onPressed: () {
Navigator.of(context).pop();
_discardDraft();
},
),
],
);Pass onPressed: null on a GlassDialogAction to keep it in place as a disabled action (for example, while waiting on valid input).
GlassMenu Submenus
Give a GlassMenuItem a submenu list to open a native iOS-style card over the parent (the parent recedes and dims; tapping the card's header or the exposed parent collapses one level). Submenus nest. Works in GlassMenu and GlassPullDownButton:
GlassPullDownButton(
icon: const Icon(CupertinoIcons.ellipsis_circle),
items: [
GlassMenuItem(
title: 'Share…',
icon: const Icon(CupertinoIcons.share),
// onTap is required but never called on a submenu row:
// activating it opens the card instead.
onTap: () {},
submenu: [
GlassMenuItem(title: 'Messages', icon: const Icon(CupertinoIcons.chat_bubble_fill), onTap: _sendMessage),
GlassMenuItem(title: 'Mail', icon: const Icon(CupertinoIcons.mail_solid), onTap: _sendMail),
],
),
const GlassMenuDivider(),
GlassMenuItem(title: 'Delete', icon: const Icon(CupertinoIcons.trash), isDestructive: true, onTap: _delete),
],
)- A submenu row shows a chevron automatically unless you pass
trailing. - Do not build nested menus by opening a second
GlassMenufrom an item'sonTap; usesubmenu. - Use
GlassMenuItem.semanticsSelected: true(alongside a checkmarktrailing) to announce the active choice to VoiceOver/TalkBack (semanticsCheckedon macOS where VoiceOver expects radio checked state) without keeping the hover highlight visible, andsemanticLabelwhentrailingadds visual-only text like keyboard shortcuts.
GlassMaterialize
For widgets appearing or disappearing dynamically, use GlassMaterialize to match iOS 26's progressive defogging transition:
GlassMaterialize(
visible: _showFilterPill,
// GlassChip.label is a String, not a Widget
child: GlassChip(
label: 'Active Filters',
onDeleted: () => setState(() => _showFilterPill = false),
),
)6. Lists, Pickers & Declarative Navigation
Use surfaceStyle: GlassSurfaceStyle.solid on list cards (GlassGroupedSection, GlassReorderableList.grouped, GlassDisclosureGroup.standalone, date pickers) and standalone scrolling inputs/chips (GlassTextField, GlassSearchBar, GlassTextArea, GlassPasswordField, GlassPicker, GlassChip). Inputs, pickers, and chips placed inside a solid card or GlassGroupedSection inherit GlassSurfaceStyle.solid automatically via InheritedGlassSurfaceStyle. For an app-wide iOS 27 material pass theme: const GlassThemeData.ios27() to LiquidGlassWidgets.wrap() (or wrap a subtree in GlassTheme(data: const GlassThemeData.ios27(), ...)).
Swipe actions, context menu, disclosure
GlassSwipeActionScope( // one open row at a time; wrap the whole list
child: ListView(children: [
GlassGroupedSection(
surfaceStyle: GlassSurfaceStyle.solid,
children: [
GlassListTile(
title: const Text('Alex Rivera'),
trailingSwipeActions: [
GlassSwipeAction(
icon: const Icon(CupertinoIcons.trash),
label: const Text('Delete'),
isDestructive: true,
onTap: _delete, // GlassSwipeAction uses onTap
),
],
onDismissed: _delete, // full-swipe collapse
contextMenuActions: [
GlassContextMenuAction(
icon: const Icon(CupertinoIcons.star),
child: const Text('Favorite'), // label is `child`, handler is `onPressed`
onPressed: _favorite,
),
],
),
GlassDisclosureGroup(
title: const Text('Privacy'),
children: [
GlassListTile(
title: const Text('AirDrop'),
trailing: GlassSwitch(value: _airDrop, onChanged: (v) => setState(() => _airDrop = v)),
),
],
),
],
),
]),
)Edit mode and reordering
GlassEditScope provides ambient edit state; GlassEditButton toggles it. GlassListTile reacts via canDelete/onDelete, canReorder/reorderIndex, canSelect/isSelected/onSelectedChanged:
GlassEditScope(
child: Column(children: [
const GlassEditButton(),
GlassReorderableList.grouped(
surfaceStyle: GlassSurfaceStyle.solid,
itemCount: items.length,
onReorderItem: (oldIndex, newIndex) =>
setState(() => items.insert(newIndex, items.removeAt(oldIndex))),
itemBuilder: (context, i) => GlassListTile(
key: ValueKey(items[i]), // key required
title: Text(items[i]),
canReorder: true,
reorderIndex: i,
canDelete: true,
onDelete: () => setState(() => items.removeAt(i)),
),
),
]),
)Full-screen cover and date pickers
showGlassFullScreenCover<void>(
context: context,
builder: (ctx) => GlassFullScreenCover(
title: const Text('New Contact'),
closeButtonLabel: 'Done',
child: const ContactForm(),
),
);
GlassDatePicker.compact(
initialDateTime: DateTime.now(),
mode: GlassDatePickerMode.dateAndTime,
surfaceStyle: GlassSurfaceStyle.solid,
onDateTimeChanged: (d) => setState(() => _date = d),
)GlassDatePicker.graphical and .wheel share these parameters; GlassMultiDatePicker(selectedDates: Set<DateTime>, onDatesChanged: ...) selects multiple days.
Navigation stack
GlassNavigationStack(
path: _path, // optional GlassNavigationPath; _path.append(value) pushes
destinations: {String: (context, value) => DetailPage(value as String)},
root: const HomePage(),
)
// Inside a GlassGroupedSection on the root page:
GlassNavigationLink<String>(value: 'Optics', title: const Text('Optics'))
// or: GlassNavigationLink(destination: (ctx) => const DetailPage(), title: ...)
// Inside a page, `.navigationTitle('Detail')` supplies the title of a GlassAppBar / GlassAppBar.pinned that has `title: null`.7. Advanced Navigation: Gel Morph with GlassNavigationShell
To achieve the signature iOS 26 navigation bar transition — where the capsule swells, bounces, and cross-fades icons between routes:
- Wrap the Navigator in
GlassNavigationShell(typically inCupertinoApp.builder):
CupertinoApp(
builder: (context, child) => GlassNavigationShell(
swipeCommitTransition: GlassSwipeCommitTransition.crossFade, // optional: plain cross-fade on back-swipe
verticalBarBehavior: GlassVerticalBarBehavior.automatic, // optional: iPhone Duo vertical strip
child: child!,
),
home: const HomeScreen(),
)- Use
GlassAppBar.pinnedon destination screens. Items are declared asGlassBarItemdata (not arbitrary widgets), which allows the shell to hoist them above theNavigatorand morph them across routes:
GlassAppBar.pinned(
title: const Text('Detail'),
actions: [
// GlassBarItem.icon uses `onTap` (not `onPressed`)
GlassBarItem.icon(
icon: const Icon(CupertinoIcons.square_and_arrow_up),
onTap: () => _share(),
),
// Tinted capsule (iOS 26 prominent action): set tintColor + separate background.
// The capsule fills with the colour; foreground icon auto-flips to white/black.
GlassBarItem.icon(
icon: const Icon(CupertinoIcons.checkmark),
onTap: _save,
background: GlassBarItemBackground.separate,
tintColor: CupertinoColors.activeBlue,
),
],
)Note: Without
GlassNavigationShell,GlassAppBar.pinnedfalls back gracefully — items render inside the bar in-route, so all screens work either way.
iPhone Duo: Under the shell, pinned bars,
GlassTabBar.bottom/.searchable,GlassToolbarandGlassLargeTitlemove into the vertical bar strip on their own; pass a large title's controller to itsGlassAppBar.pinned, which draws the title there. AGlassAppBar.pinnedinside aGlassModalSheetfollows the sheet, whoseplacementmirrorspresentationPlacement(_:). UseGlassBarItem.custom(axisBehavior: GlassBarItemAxisBehavior.verticalPreferred)for custom content that should go with them, and readGlassVerticalBar.maybeOf(context)to fit a bar the package does not draw.
8. Common Agent Pitfalls (Checklist before outputting code)
- Did you import the public API only? (
import 'package:liquid_glass_widgets/liquid_glass_widgets.dart';). Never importsrc/. - Did you call
await LiquidGlassWidgets.initialize()inmain()? Shaders must be pre-warmed. - Did you wrap your app in
LiquidGlassWidgets.wrap()? Required for theme and accessibility scaling. - Are you using
GlassScaffoldinstead ofScaffold? Prevents z-index glitches with glass nav bars. - Did you avoid nesting glass in glass? Never put
GlassButton,GlassIconButton, or a glass-modeGlassChipinside aglass-modeGlassContainer.cardorGlassGroupedSection. Inside asolidcard/section (surfaceStyle: GlassSurfaceStyle.solid),GlassSwitch,GlassSlider, andGlassSegmentedControlare safe (their glass is transient) andGlassChip/GlassTextField/GlassPickerauto-inheritsolid. - Did you use
GlassTabBar.bottominstead ofGlassBottomBar?GlassBottomBaris deleted. GlassButtonusesonTap, notonPressed. (GlassButton(onTap: () {})) — the opposite ofElevatedButton.GlassIconButtonusesonPressed, notonTap. (GlassIconButton(onPressed: () {})).GlassAppBarusesactions: [...](a List), nottrailing:. There is notrailingparameter.GlassChip.labelis aString, not aWidget. Passlabel: 'text', notlabel: Text('text').GlassBarItem.iconusesonTap(required), notonPressed.GlassBarItem.customtakes an optionalonTap— omit it when the child is already a button. OmittingonTapleaves the slot passive; passing a no-oponTap: () {}wraps the child in a second, unlabelled button for screen readers.- Nested menus use
GlassMenuItem(submenu: [...]). The parent row still needsonTap: () {}(required, never called). Don't open a secondGlassMenufromonTap. tintColoronGlassBarItemrequiresbackground: GlassBarItemBackground.separate. A shared-background item cannot be tinted (asserts in debug mode). The foreground icon colour is flipped automatically — do not also set a manualIcon(color:)on the child.GlassSwipeActionusesonTap;GlassContextMenuActionuseschild+onPressed. Wrap swipeable lists inGlassSwipeActionScope.- Don't hand-roll
Dismissible,ExpansionTile,showDatePickeror aReorderableListViewedit mode — useGlassSwipeActions,GlassDisclosureGroup,GlassDatePickerandGlassEditScope+GlassReorderableList. GlassReorderableListitems need a stablekey, and eitheronReorderoronReorderItemmust be provided.GlassCardis deprecated. UseGlassContainer.card.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

