Flutter AI UI Design Skill

Description

--- name: flutter-ai-ui-skill description: >- A master-level Flutter UI/UX design skill that equips AI coding assistants with curated design intelligence, colour palettes, typography pairings, animation patterns, component blueprints and actionable checklists for building beautiful, accessible, production-ready Flutter applications. Covers Material 3, Cupertino, adaptive layouts, animations, theming, state management integration, accessibility and performance optimization. --- # Flutter AI UI Skill 🎨 > **Design intelligence for Flutter** — turn any AI coding assistant into a Flutter UI expert. --- ## Overview This skill provides comprehensive design intelligence for building and refining Flutter applications. It combines curated Flutter-specific best practices with professional UI/UX heuristics to produce beautiful, accessible, performant, and maintainable mobile interfaces. ### When does this skill activate? The skill activates automatically when you: - Request UI/UX work in a Flutter project - Ask to build, create, design, or improve any screen or component - Use the `/flutter-ai-ui` slash command (Kiro, Copilot, Roo Code) --- ## How to Use This Skill ### Step 1 – Gather Context Before writing a single line of code, understand: - **App domain**: healthcare, fintech, e-commerce, social, productivity, etc. - **Target audience**: age group, technical literacy, accessibility needs - **Brand personality**: playful, professional, minimal, bold, luxurious, warm - **Platform priorities**: Android-first, iOS-first, cross-platform + web - **Color & font preferences**: any existing assets or brand guidelines ### Step 2 – Generate a Design System Use `data/flutter_colors.csv` to choose your primary, secondary, surface and error palette based on category. Use `data/flutter_typography.csv` to pick a font-pairing that matches the app mood. Then generate a `AppTheme` class: ```dart // Example — do NOT hardcode colours across widgets final theme = ThemeData( useMaterial3: true, colorScheme: ColorScheme.fromSeed( seedColor: const Color(0xFF2563EB), brightness: Brightness.light, ), textTheme: GoogleFonts.poppinsTextTheme(), ); ``` ### Step 3 – Apply Flutter Design Guidelines Consult `data/stacks/flutter_guidelines.csv` before implementing any component. Run the keyword search tool to find relevant dos & don'ts: ```sh python scripts/search_guidelines.py --keyword "animation" python scripts/search_guidelines.py --category "accessibility" python scripts/search_guidelines.py --severity "critical" ``` ### Step 4 – Scaffold or Analyse **New project:** ```sh python scripts/create_flutter_project.py --name my_app --template material3 python scripts/create_flutter_project.py --name my_app --template cupertino python scripts/create_flutter_project.py --name my_app --template adaptive ``` **Existing project:** ```sh python scripts/analyse_flutter_project.py --path path/to/project python scripts/analyse_flutter_project.py --path path/to/project --fix-suggestions ``` ### Step 5 – Pre-Delivery Checklist Before handing off any UI work, verify: #### ✅ Accessibility - [ ] All images have `semantic` labels or `excludeFromSemantics: true` for decorative ones - [ ] Interactive elements have `Tooltip` or `Semantics(label: ...)` - [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for UI components) - [ ] Dynamic text scaling works — wrap with `MediaQuery.textScalerOf` - [ ] `FocusTraversalGroup` and `onKey` keyboard navigation for desktop/web #### ✅ Responsiveness - [ ] `LayoutBuilder` or `AdaptiveLayout` used for breakpoints - [ ] Orientation not locked unless specifically required - [ ] Content scrollable on small screens — never overflow - [ ] Safe area respected with `SafeArea` widget #### ✅ Theming - [ ] `ThemeData` with `ColorScheme` — no hardcoded hex colors in widgets - [ ] `darkTheme` provided in `MaterialApp` - [ ] Dynamic color (`DynamicColorBuilder`) supported where possible - [ ] Custom fonts loaded via `pubspec.yaml` or `google_fonts` #### ✅ Performance - [ ] `const` constructors everywhere possible - [ ] `ListView.builder` / `GridView.builder` for long lists - [ ] `RepaintBoundary` around heavy or animated widgets - [ ] Images loaded via `cached_network_image` - [ ] Build methods < 50 lines; heavy logic extracted to helpers #### ✅ Navigation & State - [ ] Declarative routing via `GoRouter` (preferred) or Navigator 2.0 - [ ] `PopScope` handles Android predictive back gesture - [ ] State management chosen and applied consistently (Riverpod / Bloc / Provider) - [ ] Providers/Notifiers disposed correctly #### ✅ Code Quality - [ ] Widgets extracted into separate files once > 80 lines - [ ] No `setState` called inside `build()` - [ ] No `BuildContext` stored across async gaps without checking `mounted` - [ ] Widget tests cover critical UI flows --- ## Design Principles — Flutter Edition ### 1. Material 3 First Always use `useMaterial3: true`. Leverage `ColorScheme`, `Typography`, `NavigationBar`, `Card`, `FilledButton`, `ElevatedButton`, `InputDecoration` with Material 3 defaults. Avoid overriding M3 tokens unnecessarily. ### 2. Adaptive, Not Responsive Only Flutter runs on mobile, tablet, web, and desktop. Use `AdaptiveLayout` or `LayoutBuilder` with breakpoints: - Mobile: < 600px - Tablet: 600px – 1200px - Desktop: > 1200px ### 3. Animation as Communication Animations should communicate state changes, not just look pretty. - Use `AnimatedContainer`, `AnimatedOpacity`, `AnimatedSwitcher` for implicit animations - Use `AnimationController` + `Tween` for explicit control - Use `Hero` for shared element transitions - Keep durations between 150ms–400ms; 300ms is the sweet spot - Use `Curves.easeInOut` by default; `Curves.elasticOut` for playful UIs ### 4. Elevation & Depth Material 3 uses tonal elevation (color-based), not shadow-based by default. Use `elevation` with `surfaceTintColor` for cards. Use `BoxShadow` sparingly and consistently — define shadow tokens in your theme. ### 5. Typography Hierarchy Always define a complete `TextTheme`: - `displayLarge/Medium/Small` — Hero sections, splash screens - `headlineLarge/Medium/Small` — Page and section titles - `titleLarge/Medium/Small` — Card titles, list items, dialogs - `bodyLarge/Medium/Small` — Body copy, descriptions - `labelLarge/Medium/Small` — Buttons, tabs, chips ### 6. Spacing System Use an 8-point spacing grid. Define constants: ```dart class AppSpacing { static const double xs = 4; static const double sm = 8; static const double md = 16; static const double lg = 24; static const double xl = 32; static const double xxl = 48; } ``` ### 7. Color Token System Never use raw hex in widgets. Use semantic tokens: ```dart // ✅ Correct color: Theme.of(context).colorScheme.primary // ❌ Wrong color: const Color(0xFF2563EB) ``` --- ## UI Style Catalog The following Flutter-specific UI styles are supported. Reference these when asked to build in a particular aesthetic: | Style | Description | Key Widgets & Techniques | |-------|-------------|--------------------------| | **Material 3 Clean** | Google's latest design language, tonal color, gentle curves | `FilledButton`, `Card`, `NavigationBar`, `ColorScheme.fromSeed` | | **Cupertino Native** | iOS-native look and feel | `CupertinoApp`, `CupertinoNavigationBar`, `CupertinoButton` | | **Glassmorphism** | Frosted glass, blur, translucency | `BackdropFilter`, `ImageFilter.blur`, gradient overlays | | **Neumorphism** | Soft embossed shadows, monochromatic depth | Layered `BoxShadow` with light/dark offset | | **Dark Neon** | Dark background with glowing neon accents | Custom `ColorScheme`, `BoxShadow` with colored spread | | **Minimal Flat** | Ultra-clean, plenty of whitespace, subtle borders | `Container`, `Divider`, precise typography | | **Claymorphism** | Soft, pillowy 3D-like components | Large border radius, colored shadow, pastel palette | | **Brutalist** | Raw, high-contrast, bold typography | Borders, monochrome, loud text, tight spacing | | **Gradient Premium** | Layered gradients, depth and richness | `LinearGradient`, `RadialGradient`, `ShaderMask` | | **Organic Biophilic** | Natural forms, earthy colors, soft curves | Custom clip paths, earth tones, organic shapes | | **Retro/Y2K** | Nostalgic, pixel-inspired, bold colors | Custom painters, chunky UI, high saturation | | **Enterprise Dark** | Professional dark dashboard aesthetic | Dark surface colors, data-dense layout, subtle dividers | --- ## Flutter-Specific Component Blueprints ### Bottom Navigation ```dart // Prefer NavigationBar (M3) over BottomNavigationBar NavigationBar( destinations: const [ NavigationDestination(icon: Icon(Icons.home), label: 'Home'), NavigationDestination(icon: Icon(Icons.search), label: 'Search'), ], selectedIndex: _selectedIndex, onDestinationSelected: (i) => setState(() => _selectedIndex = i), ) ``` ### Loading States ```dart // Use Shimmer loading — never show empty containers Shimmer.fromColors( baseColor: Colors.grey.shade300, highlightColor: Colors.grey.shade100, child: Container(height: 80, color: Colors.white), ) ``` ### Error States ```dart // Always handle error states visually ErrorStateWidget( icon: Icons.cloud_off, title: 'Something went wrong', subtitle: error.toString(), onRetry: () => ref.refresh(myProvider), ) ``` ### Pull-to-Refresh ```dart RefreshIndicator.adaptive( // Use adaptive for iOS/Android onRefresh: () async => ref.refresh(myProvider), child: ListView.builder(...), ) ``` --- ## Supported AI Platforms This skill works with all major AI coding assistants: | Platform | Activation Mode | Setup Location | |----------|----------------|----------------| | **Antigravity** | Skill auto-activation | `.agents/skills/` | | **Claude Code** | CLAUDE.md / skill | `.claude/` | | **Cursor** | Rules file | `.cursor/rules/` | | **Windsurf** | Rules file | `.windsurf/rules/` | | **GitHub Copilot** | Slash command | `.github/copilot-instructions.md` | | **Gemini CLI** | GEMINI.md | `GEMINI.md` | | **Kiro** | Spec/hook | `.kiro/` | | **Roo Code** | Rules | `.roo/` | | **OpenCode** | Rules | `opencode.json` | | **Continue** | Config | `.continue/rules/` | | **Zed** | Rules | `.zed/settings.json` | --- ## File Structure Reference ``` flutter-ai-ui-skill/ ├── SKILL.md ← You are here (AI reads this) ├── README.md ← Human-facing documentation ├── data/ │ ├── flutter_colors.csv ← 30+ Flutter app-type palettes │ ├── flutter_typography.csv ← 15 Google Fonts pairings │ └── stacks/ │ └── flutter_guidelines.csv ← 120+ Flutter UI guidelines ├── scripts/ │ ├── analyse_flutter_project.py ← Project audit tool │ ├── search_guidelines.py ← Guideline keyword search │ └── create_flutter_project.py ← Project scaffolder └── templates/ ├── material3/ ← Material 3 starter ├── cupertino/ ← Cupertino/iOS starter └── adaptive/ ← Adaptive multi-platform starter ``` --- ## Quick Reference: Top 20 Flutter UI Rules | # | Rule | Severity | |---|------|----------| | 1 | Use `const` constructors for immutable widgets | 🔴 Critical | | 2 | Never hardcode colors — use `Theme.of(context).colorScheme` | 🔴 Critical | | 3 | Keep `build()` methods under 50 lines | 🔴 Critical | | 4 | Use `ListView.builder` for any list > 10 items | 🔴 Critical | | 5 | Provide `darkTheme` in `MaterialApp` | 🟠 High | | 6 | Add `Semantics` labels to all interactive/image widgets | 🟠 High | | 7 | Use `RepaintBoundary` around animated widgets | 🟠 High | | 8 | Check `mounted` before using `BuildContext` after async | 🟠 High | | 9 | Use `cached_network_image` for all network images | 🟠 High | | 10 | Use `GoRouter` for declarative routing | 🟡 Medium | | 11 | Prefer `AnimatedContainer` over explicit animations for simple transitions | 🟡 Medium | | 12 | Use `LayoutBuilder` for responsive breakpoints | 🟡 Medium | | 13 | Extract reusable widgets into separate files | 🟡 Medium | | 14 | Use `SafeArea` for content near edges | 🟡 Medium | | 15 | Prefer `Flexible`/`Expanded` over fixed sizes in rows/columns | 🟡 Medium | | 16 | Use `Hero` widget for page transition shared elements | 🟢 Low | | 17 | Apply `TextScaler` support for accessibility | 🟢 Low | | 18 | Use `PopScope` for Android back gesture | 🟢 Low | | 19 | Prefer `SelectableText` for copyable content | 🟢 Low | | 20 | Use `AdaptiveLayout` from `flutter_adaptive_scaffold` for multi-platform | 🟢 Low | --- *Flutter AI UI Skill — Built with ❤️ for the Flutter community.* *See README.md for installation instructions and full documentation.*

Security Status