---
name: premium-game-ui
description: >
  Create professional, layered, high-impact game screens in Flutter without flattening the UI into a single image.
  Trigger: when designing, generating, reviewing, or implementing premium game UI screens, reward screens, medal screens, avatar screens, overlays, transparent assets, visual effects, or cinematic game feedback.
license: Apache-2.0
metadata:
  author: gentleman-programming
  version: "1.0"
---

## When to Use

- A screen must look premium, cinematic, or game-like.
- Assets are being generated for Flutter UI.
- The user mentions transparent backgrounds, overlays, rewards, medals, avatars, glows, bursts, particles, confetti, Lottie, Rive, or visual polish.
- A prototype/mockup must be converted into real app UI.

## Critical Patterns

1. **Never flatten a real screen into one PNG.** Use real Flutter layout for text, buttons, state, progress, localization, and accessibility.
2. **Generate a layered asset kit.** Separate opaque backgrounds from transparent overlays.
3. **Transparent means technically transparent.** For overlays, image corners should usually be `alpha=0`; reject white/black baked backgrounds.
4. **Right size, not maximum size.** Icons/avatars usually 128–256 px. Hero bursts 512–1024 px. Full backgrounds can be larger.
5. **Use animation by responsibility.**
   - `flutter_animate`: widget entrances, shimmer, scale, blur, staggered UI.
   - `confetti`: short celebrations; keep particles controlled.
   - `Rive`: interactive/stateful vector animation.
   - `Lottie`: After Effects JSON animations.
6. **Avoid expensive composition.** Do not wrap large areas in `Opacity` when a semitransparent color/image or pre-baked alpha asset works.
7. **Plan before generating.** First write the layer list: filename, role, size, alpha requirement, anchor, and Flutter usage.

## Asset Acceptance Checklist

- [ ] Correct role: background, overlay, hero element, icon, or animation.
- [ ] Correct format: PNG/WebP alpha for pictorial overlays, SVG for simple vector, Rive/Lottie for motion.
- [ ] Correct alpha: overlay corners transparent unless intentionally full-canvas.
- [ ] Centered visible content; no neighboring sprite fragments.
- [ ] No unnecessary 2048+ px icons.
- [ ] Registered in `pubspec.yaml` only at the needed directory level.
- [ ] Integrated through `Stack`/widgets, not as a full-screen screenshot.

## Flutter Integration Pattern

```dart
Stack(
  children: [
    const PremiumBackground(), // opaque base
    Positioned.fill(child: Image.asset('assets/fx/vignette.png', fit: BoxFit.cover)),
    Positioned(top: 80, left: 0, right: 0, child: RewardHero()),
    Positioned.fill(child: IgnorePointer(child: ConfettiWidget(confettiController: controller))),
    SafeArea(child: RealScreenContent()), // text/buttons/progress remain widgets
  ],
)
```

## Documentation

- Main pipeline: `docs/premium_game_ui_pipeline.md`