flutter-visual-effects git:20260823.0ed4f99A

Immutable. This exact content is served forever at /api/v1/blob/6bde3480959cdeca.

---
name: flutter-visual-effects
description: Implement or review advanced Flutter visual rendering such as frosted or liquid glass, backdrop blur, refraction, shaders, custom painting, glow, masks, and effect fallbacks. Use when the request explicitly needs a nontrivial visual effect; route art direction, ordinary styling, animation timing, and evidence-based performance diagnosis to their dedicated skills.
---

# Flutter Visual Effects

Translate an intended material or optical behavior into a maintainable Flutter rendering stack without treating an effect package as a design system.

## Scope

Own effect fidelity, layer composition, blur and refraction implementation, shader or `CustomPainter` selection, effect grouping, platform/backend fallbacks, and rendered effect verification.

Route whether the product should use the effect to `flutter-ui-design`. Route timing, choreography, springs, Hero, and interruption behavior to `flutter-animation`; measured jank diagnosis to `flutter-performance`; and native views or platform channels to `flutter-platform-integration`.

## Preflight

1. Inspect `pubspec.yaml`, Flutter/Dart constraints, enabled platforms, existing graphics packages, and the rendering code around the target surface.
2. Inspect the supplied reference at equivalent content, background, state, and viewport. An isolated translucent rectangle is not enough evidence for a backdrop-dependent effect.
3. State the optical behavior that matters: blur, tint, edge highlight, depth, refraction, shape blending, glow, noise, or responsive deformation.
4. Establish required platform coverage, acceptable fidelity loss, accessibility fallbacks, and whether representative hardware can be profiled.
5. Preserve the project's current packages unless core Flutter cannot meet an explicit fidelity requirement.

## Choose the least costly faithful layer

1. Use decoration, gradients, masks, shadows, and `CustomPainter` for effects that do not sample rendered content behind them.
2. Use a clipped `BackdropFilter` for ordinary frosted material. Use `ImageFiltered` when filtering one known child rather than the existing backdrop.
3. Use a fragment shader only when refraction, distortion, procedural texture, dissolve, or another per-pixel behavior is part of the acceptance criteria.
4. Consider a package only after checking its current SDK constraints, renderer and platform support, maintenance, license, limitations, and fallback path. Do not add a package merely because its demo resembles the reference.
5. Use native integration only when native rendering itself is a requirement; preserve a defined behavior for every other supported target.

For an ordinary core-material implementation, make the decision record explicit: `BackdropFilter` samples already painted content behind the surface, `ImageFiltered` filters one owned child, no effect package is being added, and decorative layers expose neither semantics nor press, hover, or focus affordances.

## Implementation invariants

- Clip filters to the smallest useful bounds; an unbounded backdrop filter can process far more of the scene than the visible surface.
- Build glass as layers: sampled backdrop, controlled blur or refraction, tint, border/highlight, then readable content. Opacity alone is not glass.
- Keep optical effects behind semantics and hit testing. Decorative or read-only layers must not expose press, hover, focus, or interactive-glow affordances; only real controls receive them.
- Reuse or group shared effect layers where the SDK and composition allow it. Do not place an independent live blur or shader behind every scrolling row.
- Keep effect configuration semantic and centralized, with opaque or lower-cost alternatives for unsupported renderers, reduced transparency, high contrast, and constrained hardware.
- Preserve stable identity while shapes morph. The animation owner controls time; the effect layer derives its geometry and uniforms from that state.
- Never claim pixel parity with an Apple-native material. Report which transferable properties were reproduced and which native optical behaviors were approximated.

## Conditional references

- Read [iOS effect translation](references/ios-effect-translation.md) when a SwiftUI, Liquid Glass, Material, PhaseAnimator, or matched-geometry reference must be reproduced in Flutter.
- Read [shaders, packages, and performance](references/shaders-packages-performance.md) when custom GLSL, `FragmentProgram`, backdrop distortion, an effect package, renderer compatibility, or GPU cost is in scope.

## Verification

Render the effect over representative quiet and busy backgrounds in light and dark themes. Keep viewport, content, effect geometry, and interaction state equal when comparing normal, high-contrast, and opaque or low-cost fallback fixtures. Capture the interactive or morphed state where relevant. Check legibility, clipping, edge artifacts, scroll behavior, text scaling, high contrast, reduced motion, and the available reduced-transparency path.

Golden tests can lock deterministic geometry and paint output, but device screenshots are required for claims involving platform compositing, system chrome, or backend-specific shaders. Profile nontrivial blur, shader, or continuously animated effects in profile mode on representative hardware; report the tested renderer, device class, scene, and fallback rather than generalizing from debug mode.

## Sources

- [Custom drawing and graphics](https://docs.flutter.dev/ui/design/graphics)
- [Writing and using fragment shaders](https://docs.flutter.dev/ui/design/graphics/fragment-shaders)
- [BackdropFilter](https://api.flutter.dev/flutter/widgets/BackdropFilter-class.html)
- [ImageFilter](https://api.flutter.dev/flutter/dart-ui/ImageFilter-class.html)