# FlutterFlow Builder Interface Reference

Complete mapping of FlutterFlow Designer's UI for browser automation via `mcp__claude-in-chrome__*` tools. Use this to locate any panel, button, or property.

## Application Layout

```
┌─────────────────────────────────────────────────────────┐
│                    Top Toolbar                          │
├──────┬──────────────────────────────────┬───────────────┤
│      │                                  │               │
│ Left │         Canvas Area              │   Properties  │
│ Side │    (Device Frame Preview)        │    Panel      │
│ bar  │                                  │   (Right)     │
│      │                                  │               │
│      ├──────────────────────────────────┤               │
│      │      Widget Tree (Bottom)        │               │
└──────┴──────────────────────────────────┴───────────────┘
```

## Left Sidebar — Navigation Menu

| Menu Item | Icon Hint | Purpose | How to Find |
|-----------|-----------|---------|-------------|
| Pages | page/document icon | Page list, create/delete pages | `find "Pages"` or `find "Page Selector"` |
| Widget Tree | tree/hierarchy icon | Hierarchical widget view | `find "Widget Tree"` |
| Storyboard | flow/diagram icon | Visual page flow connections | `find "Storyboard"` |
| Theme Settings | palette/paint icon | Design system configuration | `find "Theme Settings"` or `find "Theme"` |
| API Calls | cloud/api icon | REST and GraphQL API setup | `find "API Calls"` or `find "API"` |
| Custom Functions | code/function icon | Dart function definitions | `find "Custom Functions"` |
| Custom Actions | action/play icon | Async Dart action definitions | `find "Custom Actions"` |
| Firestore | database icon | Firebase/Supabase database | `find "Firestore"` or `find "Database"` |
| App State | state icon | App-level state variables | `find "App State"` |
| Media Assets | image/media icon | Upload images, videos, fonts | `find "Media"` or `find "Assets"` |
| Settings | gear icon | Project settings, platforms | `find "Settings"` or `find "Project Settings"` |

### Automation for Left Sidebar

```
Opening a sidebar panel:
1. find "[Panel Name]" in left sidebar area → click
2. read_page → verify panel content loaded
3. Panel slides open or replaces current sidebar content
```

## Top Toolbar

| Element | Position | Purpose | How to Find |
|---------|----------|---------|-------------|
| Project Name | Left | Current project identifier | Top-left text, usually the project name |
| Search / Cmd+K | Center-left | Command palette for quick access | `find "Search"` or use `press_key "Meta+k"` |
| Undo | Left of center | Undo last action | `find "Undo"` or `press_key "Meta+z"` |
| Redo | After Undo | Redo undone action | `find "Redo"` or `press_key "Meta+Shift+z"` |
| Device Preview | Center | Switch device frame sizes | `find device size dropdown` (e.g., "iPhone 14") |
| Zoom Controls | Center | Canvas zoom in/out | `find zoom percentage` or +/- buttons |
| Preview / Run | Right area | Launch app preview | `find "Preview"` or `find "Test"` or `find "Run"` |
| Developer Menu | Right area | Code view, download, custom code | `find "</>"`  or `find "Developer"` or `find "Code"` |
| Share | Right area | Project sharing and permissions | `find "Share"` |
| Publish / Deploy | Far right | Deploy to web/app stores | `find "Deploy"` or `find "Publish"` |

### Device Preview Sizes

```
Switching device preview:
1. find device size dropdown in toolbar → click
2. Options typically include:
   - iPhone 14 Pro (390 x 844)
   - iPhone SE (375 x 667)
   - Pixel 7 (412 x 915)
   - iPad (768 x 1024)
   - Desktop (1440 x 900)
   - Custom dimensions
3. click → desired size
4. Canvas updates to show that frame
```

## Properties Panel (Right Side)

The properties panel appears when a widget is selected. It has multiple tabs:

### Properties Tab

Contains widget-specific configuration. Content varies per widget type.

**Common properties across most widgets:**

| Property | Type | Notes |
|----------|------|-------|
| Width | number/dropdown | Fixed, %, Expand, Shrink |
| Height | number/dropdown | Fixed, %, Expand, Shrink |
| Padding | 4-value input | Top, Right, Bottom, Left (or uniform) |
| Margin | 4-value input | Top, Right, Bottom, Left (or uniform) |
| Alignment | grid selector | 9-point alignment grid |
| Visibility | toggle | Show/hide widget |
| Conditional Visibility | expression | Show based on condition |

### Style Tab

Visual appearance properties:

| Property | Type | Notes |
|----------|------|-------|
| Background Color | color picker | Theme color or custom hex |
| Border Color | color picker | With width and style |
| Border Radius | number | All corners or individual |
| Shadow | shadow config | Offset X/Y, blur, spread, color |
| Opacity | slider | 0.0 to 1.0 |
| Gradient | gradient config | Linear, radial, sweep |
| Clip | toggle | Clip child content to bounds |

```
Editing a color:
1. find the color swatch next to property label → click
2. Color picker modal opens
3. Option A: find hex input → clear → form_input "#D4A012"
4. Option B: find "Theme Colors" section → click desired theme color
5. click outside picker or find "Done" → close
```

### Actions Tab

Event handler configuration:

| Action Trigger | When Fires |
|---------------|------------|
| On Tap | Widget tapped/clicked |
| On Long Press | Widget held for ~500ms |
| On Load | Widget first renders |
| On Change | Value changes (inputs) |
| On Submit | Form submitted |
| On Swipe | Swipe gesture detected |

```
Adding an action:
1. Select widget → find "Actions" tab → click
2. find "Add Action" or "+" → click
3. Select trigger (e.g., "On Tap")
4. Select action type:
   - Navigate To (page navigation)
   - Backend Call (API/database)
   - Update State (change variable)
   - Show Snackbar/Dialog
   - Custom Action (Dart code)
5. Configure action parameters
6. read_page → verify action added
```

### Backend Query Tab

Data binding for widgets:

| Query Type | Purpose |
|-----------|---------|
| Firestore Query | Bind to Firestore collection |
| API Call | Bind to REST/GraphQL endpoint |
| Supabase Query | Bind to Supabase table |
| Local State | Bind to app/page state variable |

### Animations Tab

Motion effects applied to widgets:

| Animation | Properties |
|-----------|-----------|
| Fade In/Out | Duration, delay, curve |
| Slide | Direction, offset, duration |
| Scale | From/to scale, duration |
| Rotate | Angle, duration |
| Shimmer | Color, duration (loading states) |
| Custom | Keyframe-based animation |

### Responsive Tab

Breakpoint-specific overrides:

| Breakpoint | Width Range | Typical Use |
|-----------|-------------|-------------|
| Mobile | 0–479px | Default layout |
| Mobile Landscape | 480–767px | Horizontal phone |
| Tablet | 768–991px | iPad/tablets |
| Desktop | 992px+ | Web/desktop |

```
Adding responsive override:
1. Select widget → find "Responsive" tab → click
2. find target breakpoint (e.g., "Desktop") → click
3. Override specific properties (padding, visibility, layout)
4. Preview at that breakpoint using device preview
```

## Widget Palette

The widget palette is the source for adding new widgets to the canvas.

```
Opening widget palette:
1. find "Widget Palette" or "Add Widget" or "+" button → click
2. Panel opens showing widget categories
3. Categories are expandable sections
4. Click a widget to add it to the currently selected container
```

### Widget Categories

| Category | Contains |
|----------|----------|
| Layout Elements | Column, Row, Stack, Container, ListView, GridView, Wrap, Expanded, Spacer, Card, ListTile, TabBar, PageView |
| Base Elements | Text, Button, Image, Icon, IconButton, Badge, Divider, CircleImage, RichText, Markdown, Tooltip, Transform |
| Form Elements | TextField, DropDown, RadioButton, Checkbox, CheckboxGroup, Slider, RatingBar, PinCode, ChoiceChips, Form, Signature, CreditCardForm |
| Page Elements | AppBar, FloatingActionButton, Drawer, BottomNavigationBar, TabBar |
| Composite | DataTable, Calendar, Chart, Stepper, ExpansionPanel, Timeline |
| Custom | Custom widgets (user-defined), Component instances |

See `widget-catalog.md` for complete widget details and automation steps.

## Canvas Interaction

### Selection
- **Single click** on widget: Selects it, opens properties panel
- **Click in widget tree**: More reliable selection, especially for nested widgets
- **Click empty canvas**: Deselects all

### Context Menu (Right-Click)
| Option | Action |
|--------|--------|
| Wrap in... | Wrap widget in Container, Column, Row, Stack, etc. |
| Copy | Copy widget to clipboard |
| Paste | Paste copied widget as child |
| Duplicate | Create duplicate sibling |
| Delete | Remove widget |
| Move Up/Down | Reorder among siblings |
| Extract Component | Make widget a reusable component |

### Inline Editing
- **Double-click** on Text widget: Edit text content inline on canvas
- **Drag** widgets in widget tree: Rearrange hierarchy
- **Drag edges**: Resize (in some contexts)

## Keyboard Shortcuts

| Shortcut | Action | Automation Alternative |
|----------|--------|----------------------|
| Cmd/Ctrl + K | Command palette | `press_key "Meta+k"` |
| Cmd/Ctrl + Z | Undo | `press_key "Meta+z"` |
| Cmd/Ctrl + Shift + Z | Redo | `press_key "Meta+Shift+z"` |
| Delete / Backspace | Delete selected | `press_key "Delete"` |
| Cmd/Ctrl + C | Copy widget | `press_key "Meta+c"` |
| Cmd/Ctrl + V | Paste widget | `press_key "Meta+v"` |
| Cmd/Ctrl + D | Duplicate widget | `press_key "Meta+d"` |
| Cmd/Ctrl + S | Save (usually auto) | `press_key "Meta+s"` |
| Cmd/Ctrl + P | Preview | `press_key "Meta+p"` |
| Escape | Deselect / close panel | `press_key "Escape"` |

## Pages Panel

```
Creating a new page:
1. find "Pages" in left sidebar → click
2. find "+" or "Add Page" → click
3. Modal appears with page template options:
   - Blank Page
   - Page with AppBar
   - Page with Bottom Nav
   - From Template
4. form_input → page name (e.g., "SplashScreen")
5. click → "Create" or "Add"
6. New page opens in canvas
```

```
Setting page as home/initial:
1. find "Pages" → click
2. find target page → right-click or find options menu
3. find "Set as Home Page" or "Set as Entry Point" → click
```

## Theme Settings Panel

```
Opening theme settings:
1. find "Theme Settings" in left sidebar → click
2. Sub-tabs appear: Colors, Typography, Icons, Widget Themes
```

See `design-system-setup.md` for complete ZIVVO theme configuration.

## App State Panel

```
Creating app state variable:
1. find "App State" in left sidebar → click
2. find "Add Field" or "+" → click
3. form_input → variable name (e.g., "currentUserRole")
4. Select type (String, int, bool, List, custom model)
5. Set initial value if needed
6. Set persistence (local, session, none)
```

## Media Assets Panel

```
Uploading an asset:
1. find "Media Assets" or "Assets" in left sidebar → click
2. find "Upload" → click
3. File picker opens → select file
4. Wait for upload → verify in asset list
5. Asset is now available for Image widgets and backgrounds
```

## Developer Menu

```
Viewing generated code:
1. find "</>" or "Developer Menu" in top toolbar → click
2. Options:
   - View Code: See generated Dart for selected widget/page
   - Download Code: Export full project as ZIP
   - Custom Code: Add custom Dart functions/actions
   - Custom Widgets: Create widgets from Dart code
```

## Tips for Reliable Automation

1. **Prefer widget tree over canvas**: Clicking in the widget tree is more reliable than clicking on the canvas, especially for nested or overlapping widgets
2. **Use get_page_text first**: Before interacting, dump the page text to understand the current state
3. **Wait after navigation**: After clicking sidebar items or changing pages, wait for content to load before interacting
4. **Use command palette**: Cmd+K is the most reliable way to access any feature by name
5. **Check for modals**: Before interacting with the main UI, check if a modal/dialog is open
6. **Escape to reset**: If the UI is in an unexpected state, press Escape to close panels/modals