---

name: flutter-widget-assistant description: Interactive Flutter Widget implementation assistant that guides you through widget implementation decisions by asking structured questions about state management, widget type (screen/component), and state sharing. Use this skill when you need help determining the appropriate Flutter widget architecture for your implementation.

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?"