AI Agent Onboarding
Welcome to FlutKit’s AI-powered development workflow.
This guide explains how to use AI coding agents effectively when building applications with FlutKit. It provides the recommended workflow, reference materials, project structure conventions, and validation process used throughout the template.
Whether you use Cursor, Claude Code, GitHub Copilot, Codex, or another AI coding assistant, following this guide will help you generate code that is consistent with FlutKit’s architecture and design system.
Purpose
FlutKit is designed to be AI Coding Agent Friendly.
Unlike traditional UI templates, FlutKit provides a structured architecture that helps both developers and AI agents understand, generate, and maintain code more effectively.
The project already includes several AI-focused resources:
docs/
├── ai_ui_rules.md
├── ai_prompt_template.md
└── ai_screen_checklist.md
lib/
└── ai_reference/These resources work together to provide:
- Consistent UI generation
- Predictable file organization
- Better component reuse
- Faster feature development
- Higher quality AI-generated code
How AI Fits Into FlutKit
AI should be used as a development accelerator, not as a replacement for project architecture.
The recommended workflow is:
Understand Rules
↓
Prepare Prompt
↓
Generate Code
↓
Review Result
↓
Validate Output
↓
Production ReadyThe most successful AI-generated screens follow the existing FlutKit structure rather than introducing new patterns.
Primary References
Before generating any new screen, feature, or widget, review the following resources.
docs/ai_ui_rules.md
The primary source of UI and design rules.
Use this document to understand:
- Layout requirements
- Component usage
- Design consistency
- Reusable widget expectations
- Responsive behavior
docs/ai_prompt_template.md
Provides the recommended prompt structure.
Use this document when:
- Creating new screens
- Building CRUD pages
- Generating dashboards
- Refactoring existing features
Well-structured prompts produce significantly better AI output.
docs/ai_screen_checklist.md
The final validation checklist.
Before accepting AI-generated code, verify that it satisfies all project requirements defined in this document.
lib/ai_reference/
The primary implementation reference.
This directory contains examples of how FlutKit screens should be structured.
AI agents should treat this directory as the primary source of truth when generating new UI.
Recommended AI Workflow
Follow this workflow whenever you create a new screen or feature.
Step 1: Read the UI Rules
Start by reviewing:
docs/ai_ui_rules.mdThis establishes the visual and structural expectations for the generated code.
Step 2: Prepare a Prompt
Use:
docs/ai_prompt_template.mdto create a detailed prompt.
A good prompt should include:
- Feature description
- Layout requirements
- Existing references
- Component requirements
- Architectural constraints
Step 3: Review AI Reference Files
Before generating code, inspect relevant examples inside:
lib/ai_reference/Or find a screen that closely matches the feature you want to build from demo.
lib/demo/This helps AI produce more consistent results.
Step 4: Generate the Feature
Use your preferred AI coding agent to generate:
- Screens
- Widgets
- Dialogs
- Models
- Mock data
while following FlutKit conventions.
Step 5: Validate the Result
Finally, review the generated code using:
docs/ai_screen_checklist.mdEvery generated screen should pass the validation checklist before being merged into your project.
When to Use AI Agents
AI agents work particularly well for:
Creating New Screens
Examples:
- Analytics Dashboard
- CRM Dashboard
- Ecommerce Dashboard
- Settings Page
- User Management
Building CRUD Interfaces
Examples:
- Customer Management
- Product Management
- Employee Management
- Inventory Management
Creating Reusable Widgets
Examples:
- Statistics Cards
- Information Cards
- Chart Containers
- Table Components
Transform Templates Into Real Products Faster
Use AI coding agents to:
- Adapt existing screens
- Extend app workflows
- Connect APIs
- Add business-specific features
- Maintain UI consistency
Generating Dialogs and Forms
Examples:
- Create Dialog
- Edit Dialog
- Filter Dialog
- Settings Dialog
Core UI Expectations
Every AI-generated screen should follow FlutKit’s design system.
Layout
Use:
PortalMasterLayoutresponsible for dashboard layout.
Header
Include:
PageHeaderfor page titles and breadcrumbs.
Footer
Include:
PortalFooterfor consistent footer across app.
Responsive Layouts
Use:
ResponsiveWrapwhen sections need to adapt across screen sizes.
Design Tokens
Use values from:
lib/constants/dimens.dartfor:
- Spacing
- Radius
- Heights
- Breakpoints
Avoid hardcoded values whenever possible.
Theme Colors
Use:
Theme.of(context).colorSchemeor theme definitions provided by FlutKit.
Avoid hardcoded colors.
Component Reuse
Always check existing components in:
lib/widgets/base_ui/
lib/widgets/form/before creating new widgets.
Validation Checklist
Before finalizing AI-generated code, verify:
Layout
- PortalMasterLayout is used
- PageHeader is present
- PortalFooter is present
Responsiveness
- ResponsiveWrap is used where appropriate
- Layout works across desktop, tablet, and mobile
Design System
- Theme colors are used
- Design tokens are used
- No hardcoded styling values
Architecture
- Models are separated
- Mock data is separated
- Widgets are extracted
- Dialogs are separated
Consistency
- Follows
docs/ai_ui_rules.md - Matches existing FlutKit patterns
- Reuses components where possible
Quick Start
If you’re new to FlutKit, follow these steps:
1. Open docs/ai_ui_rules.md
2. Open docs/ai_prompt_template.md
3. Review a reference screen in lib/ai_reference/, or ready-made screens in lib/demo
4. Generate the feature with your AI coding agent
5. Validate using docs/ai_screen_checklist.md
6. Refine and integrate into your projectBy following this workflow, AI-generated code will remain consistent, maintainable, and aligned with FlutKit’s architecture and design standards.
