| 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:
// 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
✅ Responsiveness
✅ Theming
✅ Performance
✅ Navigation & State
✅ Code Quality
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 screensheadlineLarge/Medium/Small — Page and section titlestitleLarge/Medium/Small — Card titles, list items, dialogsbodyLarge/Medium/Small — Body copy, descriptionslabelLarge/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.
