Prompt Engineering

Creating high-quality Flutter screens with AI is not only about choosing the right AI coding agent. The quality of the generated result depends heavily on the quality of the prompt.

FlutKit includes a dedicated prompt framework in:

docs/ai_prompt_template.md

This document provides proven prompt structures for generating new screens, dashboards, CRUD modules, dialogs, and refactoring existing code while maintaining consistency with FlutKit’s architecture and design system.

Why Prompt Structure Matters

AI agents perform best when they understand:

• The goal of the feature
• The project’s architecture
• The design system requirements
• Available reusable components
• Expected file structure

A vague prompt often produces:

• Large single-file screens
• Duplicate widgets
• Inconsistent styling
• Poor separation of concerns

A structured prompt helps AI generate code that follows FlutKit conventions from the start.

The FlutKit Prompt Framework

Most prompts in FlutKit follow the same structure:

Goal

Required Rules

Expected File Structure

Screen Composition

Feature Requirements

Data Requirements

Implementation Rules

Output

This structure ensures that AI agents understand both the business requirements and the technical constraints.

Full Prompt Template

For complex screens, dashboards, and modules, use the Full Template from:

docs/ai_prompt_template.md

The template includes:

Goal

Define what the screen should accomplish.

Example:

Goal:
- follow the project's existing design system
- reuse existing widgets before creating new ones
- keep the result consistent with the admin/dashboard UI style

Required Rules

These rules enforce FlutKit standards.

Examples:

- use PortalMasterLayout
- use PageHeader and PortalFooter
- follow docs/ai_ui_rules.md
- use lib/ai_reference/ as the primary implementation reference

Expected File Structure

FlutKit follows a separation-of-concerns architecture.

Typical structure:

screen.dart
*_models.dart
*_data.dart
widgets/
dialogs/

This helps both developers and AI agents maintain clean project organization.

Screen Composition

Describe the expected layout.

Example:

- 4 summary cards
- 2 main content sections
- table or chart
- responsive layout

The more specific the structure, the more predictable the result.

Feature Requirements

Describe the business functionality.

Example:

- customer search
- filtering
- export actions
- create customer dialog

Data Requirements

Specify how data should be handled.

Example:

- use local mock data for now
- structure the code so data can be replaced with API integration later

Implementation Rules

These rules help keep generated code maintainable.

Examples:

- keep the main screen focused on orchestration
- extract reusable widgets
- move complex dialogs into dialogs/
- reuse existing base widgets

When to Use the Short Template

The Short Template is ideal when:

• Creating small screens
• Prototyping ideas
• Working with experienced AI agents
• Performing iterative development

Example:

Create a new Flutter screen for Customer Management using this project's existing design system.

Use:
- PortalMasterLayout
- PageHeader
- PortalFooter
- ResponsiveWrap

Follow docs/ai_ui_rules.md.

Use the Full Template whenever you need maximum consistency and predictable output.

Prompting Best Practices

Be Specific

Avoid:

Create a customer page.

Prefer:

Create a Customer Management screen.

Include:
- customer metrics
- searchable table
- add/edit dialogs
- responsive layout

The more context provided, the better the result.

Define Architectural Expectations

Always tell the AI how the code should be organized.

Example:

Split into:
- screen
- models
- data
- widgets
- dialogs

This prevents giant single-file implementations.

Mention Required Components

Always specify important FlutKit components.

Example:

Use:
- PortalMasterLayout
- PageHeader
- PortalFooter
- ResponsiveWrap

This ensures consistency across screens.

Reuse Existing Components

AI should prioritize existing widgets before creating new ones.

Reference:

lib/widgets/base_ui/
lib/widgets/form/
lib/widgets/portal_master_layout/

This reduces duplication and keeps the UI consistent.

Reference Existing Screens

One of the most effective prompt improvements is referencing an existing FlutKit screen.

Example:

Use the CRM Dashboard as the starting point.

Convert it into a Hospital Management Dashboard.

Keep:
- layout
- charts
- responsive behavior

Replace:
- leads with patients
- opportunities with appointments

This typically produces better results than generating a screen from scratch.

Avoid Building Everything at Once

Avoid prompts such as:

Create an ERP system.

Instead, break the project into modules:

1. Customer Management
2. Inventory Management
3. Billing
4. Reporting Dashboard

Smaller prompts generally produce higher-quality code.

Recommended Final Line

For maximum consistency, FlutKit recommends ending prompts with:

Use `lib/ai_reference/` as the primary reference.

This reinforces the project’s architecture, improves component reuse, and helps AI agents generate code that matches the latest FlutKit standards.