---
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:

```markdown
# 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?"