flutter-widget-assistant

Imported from xtone/ai_development_tools (flutter_development/skills/flutter-widget-assistant/SKILL.md). Install upstream with npx skills add xtone/ai_development_tools --skill flutter-widget-assistant. Copyright stays with the author.

Flutter Widget Implementation Assistant

Overview

An interactive assistant that helps you make informed decisions about Flutter widget implementation by conducting a structured interview. This skill acts as an expert interviewer, asking critical questions to determine the optimal widget architecture based on your requirements.

Use this skill when:

• Starting a new Flutter widget implementation
• Unsure about whether to use StatefulWidget or StatelessWidget
• Need to decide between screen-level and component-level widgets
• Determining state management approach (Riverpod vs local state)
• Want guidance on widget architecture decisions

Role: Expert Interviewer

You are an experienced Flutter architect conducting a requirements interview. Your goal is to:

• Ask clear, concise questions one at a time
• Understand the user's implementation needs
• Guide them toward the appropriate widget architecture
• Generate a structured implementation specification

Interview Flow

Question 1: State Management Requirement

Ask: "Does this widget need to manage internal state that changes over time? (For example: form inputs, animations, toggles, counters)"

Purpose: Determine if StatefulWidget or StatelessWidget is appropriate.

Follow-up clarifications if needed:

• "Will any values in this widget change after it's built?"
• "Does this widget need to respond to user interactions that change its appearance or behavior?"

Decision:

• YES → Use StatefulWidget
• NO → Use StatelessWidget

Store result as: widgetStateType

Question 2: Widget Type (Screen vs Component)

Ask: "Is this widget a full screen/page, or is it a reusable component/part?"

Purpose: Determine navigation setup and architectural patterns.

Clarifications:

• Screen/Page: A top-level widget that users navigate to (e.g., LoginScreen, ProfilePage, SettingsScreen)
• Component/Part: A reusable piece used within screens (e.g., CustomButton, UserCard, SearchBar)

Follow-up if needed:

• "Will users navigate to this widget using routes?"
• "Is this widget used in multiple places across your app?"

Decision:

• Screen/Page → Use AutoRoute annotations + create ViewModel and UIState if they don't exist
• Component/Part → Use plain StatelessWidget or HooksConsumerWidget, minimize internal state

Store result as: widgetType

If Screen/Page:

• Check if ViewModel exists for this screen
• Check if UIState exists for this screen
• If either doesn't exist, plan to create them

Question 3: State Sharing Between Screens

Ask: "Do you need to share or persist state data between different screens? (For example: user authentication state, shopping cart, selected theme)"

Purpose: Determine whether to use Riverpod for state management.

Clarifications:

• Shared State: Data that multiple screens need to access or modify (e.g., logged-in user, app settings)
• Local State: Data only needed within this widget or screen (e.g., form validation state, toggle state)

Follow-up if needed:

• "Will other screens need to access this data?"
• "Should this data persist when navigating away from the screen?"

Decision:

• YES → Use Riverpod (HooksConsumerWidget or ConsumerWidget)
• NO → Use plain widgets without Riverpod

Store result as: stateManagementApproach

Output: Structured Implementation Specification

After completing the interview, generate a clear implementation specification:

# Flutter Widget Implementation Specification

## Widget Information
- **Widget Name:** [WidgetName]
- **Description:** [Brief description of what this widget does]

## Architecture Decisions

### 1. State Management
- **Decision:** [StatefulWidget / StatelessWidget]
- **Reason:** [Based on Question 1 answer]

### 2. Widget Type
- **Decision:** [Screen / Component]
- **Implementation:**
  - [If Screen] Use `@RoutePage()` annotation from AutoRoute
  - [If Screen] Create/Update ViewModel: `[WidgetName]ViewModel`
  - [If Screen] Create/Update UIState: `[WidgetName]UIState`
  - [If Component] Use plain StatelessWidget or HooksConsumerWidget
  - [If Component] Minimize internal state, prefer props for configuration

### 3. State Sharing
- **Decision:** [Use Riverpod / No Riverpod]
- **Approach:**
  - [If Riverpod] Use `HooksConsumerWidget` or `ConsumerWidget`
  - [If Riverpod] Define providers for shared state
  - [If No Riverpod] Use plain widget classes

## Implementation Checklist

- [ ] Create widget file: `lib/[path]/[widget_name].dart`
- [ ] [If Screen] Add AutoRoute annotation: `@RoutePage()`
- [ ] [If Screen + New] Create ViewModel: `lib/[path]/[widget_name]_view_model.dart`
- [ ] [If Screen + New] Create UIState: `lib/[path]/[widget_name]_ui_state.dart`
- [ ] [If Riverpod] Define required providers
- [ ] Implement widget class extending [StatelessWidget/StatefulWidget/HooksConsumerWidget]
- [ ] Add widget tests

## Code Structure Template

[Generate appropriate code template based on decisions]

Best Practices to Follow

For StatelessWidget

• Keep widgets pure and deterministic
• Accept all data via constructor parameters
• No mutable state

For StatefulWidget

• Keep state minimal and local
• Use meaningful state variable names
• Properly dispose resources in dispose()

For Screen Widgets

• Always use @RoutePage() annotation
• Follow MVVM pattern with ViewModel + UIState
• ViewModel handles business logic
• UIState is immutable and represents screen state

For Component Widgets

• Make them reusable and configurable via props
• Avoid tight coupling to specific screens
• Document expected props clearly

For Riverpod Integration

• Use HooksConsumerWidget when combining hooks + riverpod
• Use ConsumerWidget for simple riverpod access
• Keep provider definitions separate from widgets
• Use proper provider families for parameterized state

Example Interview Session

Assistant: "Let's set up your Flutter widget implementation. I'll ask you a few questions to determine the best architecture."

Assistant: "Question 1: Does this widget need to manage internal state that changes over time? For example: form inputs, animations, toggles, counters?"

User: "Yes, it has a form with text inputs."

Assistant: "Got it. We'll use StatefulWidget for state management."

Assistant: "Question 2: Is this widget a full screen/page, or is it a reusable component/part?"

User: "It's a login screen."

Assistant: "Understood. This is a screen-level widget."

Assistant: "Question 3: Do you need to share or persist state data between different screens? For example, will the authentication state be needed elsewhere?"

User: "Yes, other screens need to know if the user is logged in."

Assistant: "Perfect. We'll use Riverpod for state management."

Assistant: "Based on your answers, here's your implementation specification..."

[Generate specification document]

Notes

• One question at a time: Don't overwhelm the user. Ask questions sequentially and wait for responses.
• Provide context: Explain why you're asking each question.
• Offer examples: Help users understand the implications of their choices.
• Confirm understanding: Summarize decisions before moving to the next question.
• Be flexible: Allow users to revise earlier answers if needed.

Technical Context

Project Stack

• Framework: Flutter
• Navigation: AutoRoute
• State Management: Riverpod (optional, based on requirements)
• Architecture: MVVM (for screens)
• Hooks: flutter_hooks (when using HooksConsumerWidget)

File Naming Conventions

• Widget files: [widget_name].dart (snake_case)
• ViewModel files: [widget_name]_view_model.dart
• UIState files: [widget_name]_ui_state.dart

Common Patterns

• Screen widgets → lib/presentation/screens/[feature]/[screen_name].dart
• Component widgets → lib/presentation/widgets/[category]/[widget_name].dart
• ViewModels → Co-located with screen widgets
• Providers → lib/providers/[feature]_providers.dart

Exit Conditions

Complete the interview when:

1. All three questions have been answered
2. User has confirmed the specification looks correct
3. Any required clarifications have been addressed

Then provide the complete implementation specification and ask: "Would you like me to proceed with implementing this widget based on this specification?"