rantlieu-blip/flutter-ai-ui-skill

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:

// 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:

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:

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:

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:

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:

// ✅ 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

// 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

// 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

// Always handle error states visually
ErrorStateWidget(
  icon: Icons.cloud_off,
  title: 'Something went wrong',
  subtitle: error.toString(),
  onRetry: () => ref.refresh(myProvider),
)

Pull-to-Refresh

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.