skills/flutterflow-designer/design-system-setup.md

ZIVVO Design System Setup in FlutterFlow

Complete automation workflow to configure ZIVVO's design system in FlutterFlow Designer. Run this once when creating a new FlutterFlow project, before building any screens.

Setup Sequence

1. Open Theme Settings
2. Configure Colors (light mode)
3. Configure Colors (dark mode)
4. Upload and assign custom fonts
5. Configure typography styles
6. Create theme widgets (reusable styled components)

---

Step 1: Open Theme Settings

1. find "Theme Settings" in left sidebar → click
2. read_page → verify theme settings panel opened
3. Look for tabs: Colors, Typography, Icons, Widget Themes

---

Step 2: Configure Colors — Light Mode

Navigate to Colors tab:

1. find "Colors" tab → click
2. read_page → see list of color fields

Primary Colors

Token	Hex Code	FlutterFlow Field	Notes
Primary	#D4A012	Primary	Savanna Gold — main brand color
Primary Dark	#B8860B	Primary Dark	Pressed/active state
Primary Light	#E8C44A	Primary Light	Hover/highlight state
Primary Wash	#FDF6E3	Primary Background	Tinted background

Setting Primary color:
1. find "Primary" color field → click the color swatch
2. Color picker opens
3. find hex input field → clear existing value
4. form_input "#D4A012"
5. click outside picker or find "Done" to confirm
6. Repeat for Primary Dark (#B8860B), Primary Light (#E8C44A)

Secondary Colors

Token	Hex Code	FlutterFlow Field	Notes
Secondary	#0D8B7D	Secondary	Forest Teal — action/active color
Secondary Dark	#076B60	Secondary Dark	Pressed state
Secondary Light	#39B5A6	Secondary Light	Hover state
Secondary Wash	#E6F7F5	Secondary Background	Tinted background

Setting Secondary color:
1. find "Secondary" color field → click the color swatch
2. Color picker opens
3. find hex input field → clear existing value
4. form_input "#0D8B7D"
5. click outside picker or find "Done" to confirm
6. Repeat for Secondary Dark (#076B60), Secondary Light (#39B5A6)

Semantic Colors

Token	Hex Code	FlutterFlow Field	Notes
Error / Volcanic Red	#C83E2D	Error	Error states, SOS
Success / Canopy Green	#2D7A4F	Custom: success	Confirmations, completed
Warning / Savanna Gold	#D4A012	Custom: warning	Cautions (same as primary)
Info / Harmattan Blue	#5B8DB8	Custom: info	Informational

Adding custom colors (success, warning, info):
1. find "Add Custom Color" or "+" in colors section → click
2. form_input → color name "success"
3. click color swatch → form_input "#2D7A4F"
4. Repeat for "warning" (#D4A012) and "info" (#5B8DB8)

Surface & Text Colors

Token	Hex Code	FlutterFlow Field
Background	#FAFAF7	Primary Background
Card Surface	#FFFFFF	Secondary Background
Text Primary	#1A1815	Primary Text
Text Secondary	#6B6560	Secondary Text
Divider	#E8E4DC	Custom: divider
Disabled	#D1CCC4	Custom: disabled

---

Step 3: Configure Colors — Dark Mode

Switching to dark mode:
1. find "Dark Mode" toggle or "Dark Theme" tab → click
2. read_page → verify dark mode color fields shown

Dark Mode Color Values

Token	Hex Code	FlutterFlow Field
Background	#12110F	Primary Background (Dark)
Card Surface	#1E1C18	Secondary Background (Dark)
Elevated	#2A2722	Custom: elevated
Text Primary	#F0EDE6	Primary Text (Dark)
Text Secondary	#A69E94	Secondary Text (Dark)
Primary (brighter)	#E8C44A	Primary (Dark)
Secondary	#39B5A6	Secondary (Dark)
Divider	#3A3631	Custom: divider (Dark)
Disabled	#5A554D	Custom: disabled (Dark)

Setting each dark mode color:
1. find color field label → click swatch
2. Clear hex input → form_input new hex value
3. Repeat for all dark mode colors
4. read_page → verify all colors updated

---

Step 4: Upload Custom Fonts

ZIVVO uses three font families: Plus Jakarta Sans (headings), Inter (body), JetBrains Mono (monospace).

Navigating to font upload:
1. find "Typography" tab in Theme Settings → click
   OR: find "Media Assets" → "Fonts" section
2. find "Upload Font" or "Custom Fonts" → click

Font Files to Upload

Plus Jakarta Sans:

• PlusJakartaSans-Medium.ttf (500)
• PlusJakartaSans-SemiBold.ttf (600)
• PlusJakartaSans-Bold.ttf (700)
• PlusJakartaSans-ExtraBold.ttf (800)

Inter:

• Inter-Regular.ttf (400)
• Inter-Medium.ttf (500)
• Inter-SemiBold.ttf (600)

JetBrains Mono:

• JetBrainsMono-Medium.ttf (500)

Uploading each font:
1. find "Upload Font" → click
2. File picker opens → select .ttf file
3. Wait for upload confirmation
4. read_page → verify font appears in custom fonts list
5. Repeat for each font file

Alternative — Use Google Fonts (if available in FlutterFlow):

1. find font family dropdown → click
2. Search for "Plus Jakarta Sans" → select
3. Search for "Inter" → select
4. These are available as Google Fonts in FlutterFlow

---

Step 5: Configure Typography Styles

Navigate to typography configuration:

1. find "Typography" tab → click
2. read_page → see text style list

Text Style Definitions

Style Name	Font Family	Weight	Size (sp)	Line Height (px)	Letter Spacing
Display Large	Plus Jakarta Sans	800 (ExtraBold)	32	40	-0.5
Display Medium	Plus Jakarta Sans	700 (Bold)	28	36	-0.25
Heading Large	Plus Jakarta Sans	700 (Bold)	24	32	0
Heading Medium	Plus Jakarta Sans	600 (SemiBold)	20	28	0.15
Heading Small	Plus Jakarta Sans	600 (SemiBold)	18	24	0.1
Title Large	Plus Jakarta Sans	600 (SemiBold)	16	22	0.15
Body Large	Inter	400 (Regular)	16	24	0.5
Body Medium	Inter	400 (Regular)	14	20	0.25
Body Small	Inter	400 (Regular)	12	16	0.4
Label Large	Inter	600 (SemiBold)	14	20	0.1
Label Medium	Inter	500 (Medium)	12	16	0.5
Label Small	Inter	500 (Medium)	11	16	0.5
Mono	JetBrains Mono	500 (Medium)	20	28	0

Configuring each text style:
1. find style name (e.g., "Display Large") → click to expand
2. find "Font Family" → select "Plus Jakarta Sans"
3. find "Font Weight" → select "ExtraBold" or "800"
4. find "Font Size" → form_input "32"
5. find "Line Height" → form_input "40" (or 1.25 multiplier)
6. find "Letter Spacing" → form_input "-0.5"
7. find "Color" → select "Primary Text" from theme
8. Repeat for each text style

FlutterFlow Style Name Mapping

FlutterFlow has predefined style slots. Map ZIVVO styles to these:

FlutterFlow Slot	ZIVVO Style
displayLarge	Display Large
displayMedium	Display Medium
headlineLarge	Heading Large
headlineMedium	Heading Medium
headlineSmall	Heading Small
titleLarge	Title Large
bodyLarge	Body Large
bodyMedium	Body Medium
bodySmall	Body Small
labelLarge	Label Large
labelMedium	Label Medium
labelSmall	Label Small

---

Step 6: Theme Widgets (Reusable Styled Components)

Create reusable component variants matching ZIVVO's design system.

ZivvoButton — Primary

Creating theme widget:
1. find "Widget Themes" or "Components" → click
2. find "Create Component" or "+" → click
3. Name: "ZivvoButtonPrimary"
4. Base widget: Button
5. Configure properties:
   - Background Color: Primary (#D4A012)
   - Text Color: #1A1815 (dark text on gold)
   - Font: Inter SemiBold 16sp
   - Height: 52
   - Width: Expand (full width)
   - Border Radius: 14
   - Padding: horizontal 24, vertical 14
   - Elevation: 0
   - Hover: Primary Dark (#B8860B)
   - Disabled: opacity 0.5
6. Save component

ZivvoButton — Secondary (Outline)

1. Create component "ZivvoButtonSecondary"
2. Base widget: Button
3. Properties:
   - Background Color: transparent
   - Border: 1.5px, Primary (#D4A012)
   - Text Color: Primary (#D4A012)
   - Font: Inter SemiBold 14sp
   - Height: 44
   - Border Radius: 12
   - Padding: horizontal 20, vertical 10

ZivvoButton — Ghost (Text Only)

1. Create component "ZivvoButtonGhost"
2. Base widget: Button
3. Properties:
   - Background Color: transparent
   - Border: none
   - Text Color: Secondary (#0D8B7D)
   - Font: Inter Medium 14sp
   - Height: 36
   - Padding: horizontal 12, vertical 8

ZivvoButton — Danger

1. Create component "ZivvoButtonDanger"
2. Base widget: Button
3. Properties:
   - Background Color: Error (#C83E2D)
   - Text Color: #FFFFFF
   - Font: Inter SemiBold 14sp
   - Height: 48
   - Border Radius: 12

ZivvoCard — Default

1. Create component "ZivvoCard"
2. Base widget: Container
3. Properties:
   - Background Color: #FFFFFF (light) / #1E1C18 (dark)
   - Border Radius: 16
   - Padding: 16 all sides
   - Shadow: offset(0, 2), blur 8, color rgba(0,0,0,0.06)
   - Clip: true

ZivvoCard — Elevated

1. Create component "ZivvoCardElevated"
2. Base widget: Container
3. Properties:
   - Background Color: #FFFDF5 (cream) / #2A2722 (dark)
   - Border Radius: 16
   - Padding: 16 all sides
   - Shadow: offset(0, 4), blur 16, color rgba(0,0,0,0.1)
   - Border: 1px, #E8E4DC (light) / #3A3631 (dark)

ZivvoInput — Default

1. Create component "ZivvoInput"
2. Base widget: TextField
3. Properties:
   - Border Radius: 12
   - Border: 1.5px, #E8E4DC
   - Fill Color: #FAFAF7 (light) / #1E1C18 (dark)
   - Padding: horizontal 16, vertical 14
   - Font: Inter Regular 16sp
   - Hint Color: #A69E94
   - Focus Border: Primary (#D4A012)
   - Error Border: Error (#C83E2D)
   - Height: 52

ZivvoAvatar

1. Create component "ZivvoAvatar"
2. Base widget: Container with CircleImage
3. Properties:
   - Size: 48 (default), variants at 32, 40, 56, 72
   - Border Radius: 50% (circular)
   - Border: 2px, Primary (#D4A012) for active drivers
   - Placeholder: Icon(person), background Secondary Wash

ZivvoChip

1. Create component "ZivvoChip"
2. Base widget: Container with Row(Icon + Text)
3. Properties:
   - Background: Primary Wash (#FDF6E3)
   - Border Radius: 20
   - Padding: horizontal 12, vertical 6
   - Text: Label Medium, Primary (#D4A012)
   - Icon Size: 16
   - Selected state: Background Primary, Text dark

---

Spacing System

ZIVVO uses a 4px base grid. Standard spacing values:

Token	Value	Use Case
xs	4px	Tight spacing, icon gaps
sm	8px	Related elements
md	12px	Standard padding
base	16px	Section spacing, card padding
lg	24px	Section gaps
xl	32px	Major section breaks
2xl	48px	Page section spacing
3xl	64px	Hero spacing

When setting padding/margin in FlutterFlow, always use these values.

---

Border Radius System

Token	Value	Use Case
sm	8px	Small chips, tags
md	12px	Input fields, small cards
lg	14px	Buttons
xl	16px	Cards, panels
2xl	20px	Bottom sheets, modals
full	9999px	Circles, pills

---

Shadow System

Level	Values	Use Case
sm	offset(0,1), blur 3, rgba(0,0,0,0.08)	Subtle elevation
md	offset(0,2), blur 8, rgba(0,0,0,0.06)	Cards, dropdowns
lg	offset(0,4), blur 16, rgba(0,0,0,0.1)	Elevated cards, modals
xl	offset(0,8), blur 32, rgba(0,0,0,0.12)	Bottom sheets, overlays

---

Gradients

ZIVVO uses named gradients for special surfaces:

Gradient Name	Type	Colors	Use Case
Sunrise	Linear (top→bottom)	Primary Light (#E8C44A) → transparent	Splash screen, hero backgrounds
Dusk	Linear (top→bottom)	#1A1815 → #2A2722	Dark mode headers
Gold Shimmer	Linear (left→right)	Primary Dark → Primary → Primary Light	Loading states, premium badges
Teal Depth	Linear (top→bottom)	Secondary → Secondary Dark	Active states, selected items

Creating a gradient in FlutterFlow:
1. Select Container widget
2. Style tab → find "Background" → select "Gradient"
3. Choose gradient type (Linear)
4. Set start and end colors
5. Set direction (angle or alignment points)
6. Adjust stops if needed

---

Verification Checklist

After completing design system setup, verify:

• All primary colors entered correctly (preview gold/teal on canvas)
• Dark mode colors configured (toggle dark mode preview)
• Custom fonts uploaded and visible in font picker
• All 13 typography styles configured with correct font/weight/size
• Theme widgets created and functional (test in a blank page)
• Colors reference correctly in theme (not hardcoded hex values)

Verification automation:
1. Create a blank test page
2. Add Text widget → set to each text style → verify rendering
3. Add Button → apply ZivvoButtonPrimary theme → verify gold background
4. Add Container → apply ZivvoCard theme → verify rounded corners
5. Toggle dark mode in preview → verify colors switch correctly
6. Delete test page when verified