skills/flutterflow-designer/builder-reference.md

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