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