330 lines
12 KiB
Markdown
330 lines
12 KiB
Markdown
# 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
|