Skip to main content

Figma Workflow Guide

Design Handoff & Collaboration Processes​

Document Date: December 13, 2025

1. Figma File Structure​

STEMBlock.ai Design System
├── 📄 Cover Page
│   └── Version, changelog, quick links
│
├── 📐 Foundation
│   ├── Colors
│   ├── Typography
│   ├── Spacing & Grid
│   ├── Shadows & Effects
│   └── Icons Library
│
├── 🧩 Components
│   ├── Primitives
│   │   ├── Button
│   │   ├── Input
│   │   ├── Card
│   │   ├── Badge
│   │   └── ...
│   ├── Compositions
│   │   ├── Forms
│   │   ├── Modals
│   │   ├── Navigation
│   │   └── ...
│   └── Domain Components
│       ├── Assignment Card
│       ├── Submission Card
│       └── ...
│
├── 📱 Patterns
│   ├── Layout Patterns
│   ├── Navigation Patterns
│   └── Data Display
│
├── 🎨 Prototypes
│   ├── Student Dashboard
│   ├── Coach Review Flow
│   ├── Parent Reports
│   └── Admin Management
│
└── 📚 Documentation
    ├── Component Usage
    ├── Accessibility Notes
    └── Developer Handoff

2. Design Token Setup in Figma​

2.1 Color Styles​

Naming Convention:

Category/Intent/Shade

Examples:
- Brand/Blue/500
- Brand/Purple/500
- Semantic/Success/500
- Semantic/Error/500
- Neutral/Gray/50
- Text/Primary
- Text/Secondary
- Background/Primary
- Background/Secondary
- Border/Default
- Border/Focus

Organization:

Foundation/Colors
├── Brand
│   ├── STEM Blue
│   │   ├── 50 #EFF6FF
│   │   ├── 100 #DBEAFE
│   │   ├── 500 #2E7CF6 (Primary)
│   │   └── 900 #1E3A8A
│   └── STEM Purple
│       └── ...
├── Semantic
│   ├── Success (Green)
│   ├── Warning (Orange)
│   ├── Error (Red)
│   └── Info (Teal)
└── Neutral
    └── Gray (50-950)

Create Color Variables:

  1. Go to Local Variables
  2. Create Collection: "STEMBlock Colors"
  3. Add all color tokens with semantic names
  4. Link to color styles

2.2 Typography Styles​

Text Style Naming:

Category/Variant/Size

Examples:
- Display/Bold/XL
- Heading/Bold/H1
- Heading/Bold/H2
- Body/Regular/Medium
- Body/Semibold/Medium
- Caption/Regular/Small

Typography Setup:

Foundation/Typography
├── Display
│   ├── Display 1 (Poppins 72px Bold)
│   └── Display 2 (Poppins 60px Bold)
├── Headings
│   ├── H1 (Poppins 48px Bold)
│   ├── H2 (Poppins 36px Bold)
│   ├── H3 (Poppins 30px Bold)
│   ├── H4 (Poppins 24px Semibold)
│   ├── H5 (Poppins 20px Semibold)
│   └── H6 (Poppins 18px Semibold)
└── Body
    ├── Large (Inter 18px Regular)
    ├── Medium (Inter 16px Regular)
    ├── Small (Inter 14px Regular)
    └── XSmall (Inter 12px Regular)

2.3 Effect Styles​

Shadow Naming:

Shadow/Elevation

Examples:
- Shadow/SM
- Shadow/MD
- Shadow/LG
- Shadow/XL
- Shadow/Blue (Brand shadow)

Create Effects:

Foundation/Effects
├── Shadows
│   ├── Small (0 1px 3px rgba(0,0,0,0.1))
│   ├── Medium (0 4px 6px rgba(0,0,0,0.1))
│   ├── Large (0 10px 15px rgba(0,0,0,0.1))
│   ├── Blue Shadow (0 4px 14px rgba(46,124,246,0.25))
│   └── Purple Shadow
└── Blur
    └── Backdrop Blur

3. Component Library Creation​

3.1 Component Anatomy​

Every component should have:

1. Base Component

  • Default state
  • Clean, organized layers
  • Proper constraints (fixed, hug, fill)
  • Named layers (not "Frame 123")

2. Variants

  • Size variants (sm, md, lg)
  • State variants (default, hover, active, disabled)
  • Type variants (primary, secondary, etc.)

3. Properties

  • Boolean properties (icon, loading, fullWidth)
  • Variant properties (size, variant)
  • Text properties (label, description)

4. Documentation

  • Component description
  • Usage guidelines
  • Do's and Don'ts
  • Code snippet reference

3.2 Button Component Example​

Component Structure:

Button [Component Set]
├── Properties
│   ├── Variant (primary, secondary, success, danger, ghost)
│   ├── Size (sm, md, lg)
│   ├── State (default, hover, active, disabled)
│   ├── Loading (boolean)
│   ├── Icon (boolean)
│   └── Full Width (boolean)
│
├── Layers
│   ├── Background (Auto layout)
│   ├── Content (Auto layout, horizontal)
│   │   ├── Icon (Instance, optional)
│   │   ├── Label (Text)
│   │   └── Loader (Instance, conditional)
│   └── Focus Ring (Effect)
│
└── Variants (Examples)
    ├── Primary / Medium / Default
    ├── Primary / Medium / Hover
    ├── Primary / Medium / Active
    ├── Primary / Medium / Disabled
    ├── Primary / Medium / Loading
    ├── Secondary / Medium / Default
    └── ...

Auto Layout Settings:

Horizontal padding: 16px (md), 12px (sm), 24px (lg)
Vertical padding: 10px (md), 6px (sm), 12px (lg)
Gap between items: 8px
Horizontal resizing: Hug (or Fill for fullWidth)
Vertical resizing: Hug

Component Properties Panel:

Properties:
✓ Variant: Swap instance (create all variant combinations)
✓ Size: Variant property
✓ State: Variant property
✓ Icon: Boolean (show/hide icon layer)
✓ Loading: Boolean (show loader, hide label)
✓ Full Width: Boolean (changes horizontal resizing)

3.3 Responsive Card Component​

Card Component Setup:

Card [Component Set]
├── Properties
│   ├── Variant (default, outlined, elevated)
│   ├── Padding (sm, md, lg)
│   ├── Header (boolean)
│   ├── Footer (boolean)
│   └── Hoverable (boolean)
│
├── Auto Layout
│   ├── Direction: Vertical
│   ├── Gap: 0
│   ├── Padding: Dynamic based on padding property
│   └── Resizing: Fill container
│
└── Layers
    ├── Header (Optional, auto-layout)
    │   └── Header Content (Slot for content)
    ├── Body (Auto-layout, fill)
    │   └── Body Content (Slot for content)
    └── Footer (Optional, auto-layout)
        └── Footer Actions (Slot for content)

Interactive Component Features:

Interactions:
- Default → Hover (on mouse enter)
  - Change: Shadow from SM to MD
  - Animate: Smart animate, 200ms ease-out

- Hover → Default (on mouse leave)
  - Change: Shadow from MD to SM
  - Animate: Smart animate, 200ms ease-in

4. Design Handoff Process​

4.1 Developer Mode Setup​

Enable Dev Mode:

  1. Click "Dev Mode" in top right
  2. Configure code generation preferences
  3. Add code snippets as comments

Add Code Snippets:

// On Button component
Add comment in Dev Mode:

```tsx
<Button
  variant="primary"
  size="md"
  onClick=\{handleClick\}
>
  Click me
</Button>

// Tailwind classes: className="px-4 py-2.5 rounded-lg bg-gradient-to-r from-stem-blue-500 to-stem-blue-600 text-white font-semibold hover:from-stem-blue-600 hover:to-stem-blue-700 transition-all duration-200"


**Inspect Panel Configuration:**

Code Snippets: ✓ Show CSS ✓ Show iOS (Swift) ✓ Show Android (Kotlin) ✗ Hide unnecessary platforms

Measurement Units: ✓ Pixels (px) ✗ Points (pt)

Export Settings: ✓ PNG (2x, 3x) ✓ SVG ✓ PDF


### 4.2 Component Documentation Template

**For each component, include:**

```markdown
# Component Name

## Description
Brief description of the component and its purpose.

## Usage
When to use this component vs alternatives.

## Variants
- **Primary**: For main CTAs
- **Secondary**: For less important actions
- **Ghost**: For tertiary actions

## Sizes
- **SM**: 32px height, 12px padding
- **MD**: 40px height, 16px padding (default)
- **LG**: 48px height, 24px padding

## States
- Default
- Hover (shadow, transform)
- Active (pressed)
- Disabled (50% opacity)
- Loading (spinner visible)

## Properties
- `variant`: 'primary' | 'secondary' | 'ghost'
- `size`: 'sm' | 'md' | 'lg'
- `loading`: boolean
- `disabled`: boolean
- `icon`: boolean
- `fullWidth`: boolean

## Code Example
```tsx
<Button variant="primary" size="md" onClick=\{handleSubmit\}>
  Submit
</Button>

Accessibility​

  • Min touch target: 44x44px
  • Focus visible on keyboard nav
  • Disabled state not focusable
  • ARIA labels for icon-only buttons

Do's and Don'ts​

✅ DO: Use primary for main actions ❌ DON'T: Use more than one primary button per section

  • IconButton
  • Link

### 4.3 Annotation and Redlines

**Use Figma's Annotation Tools:**

1. **Spacing Annotations**
   - Select two layers
   - Right-click → "Show spacing"
   - Shows padding/margin values

2. **Measurement Annotations**
   - Select layer
   - Right-click → "Copy properties"
   - Shows width, height, position

3. **Color/Typography Annotations**
   - Auto-shown in Dev Mode
   - Links to design tokens

4. **Interactive States**
   - Create prototype flows
   - Annotate transition timing
   - Document hover/focus states

**Custom Annotation Frame:**

Create a frame called "Specs" with:

  • Component screenshot
  • Dimension callouts
  • Color values
  • Typography specs
  • Spacing diagram
  • State variations
  • Code snippet

---

## 5. Version Control & Branching

### 5.1 Branching Strategy

**Main Branches:**

Main Branch ├── Production (Published library) │ └── Current live version │ ├── Staging │ └── Ready for review/testing │ └── Development ├── Feature/new-component ├── Feature/update-buttons └── Fix/color-contrast


**Branch Naming:**

feature/component-name fix/issue-description update/component-name experiment/idea-name

Examples:

  • feature/achievement-badges
  • fix/button-hover-states
  • update/color-palette
  • experiment/dark-mode

### 5.2 Version Numbering

**Semantic Versioning:**

Major.Minor.Patch

Examples:

  • 1.0.0 - Initial release
  • 1.1.0 - New component added
  • 1.1.1 - Bug fix in existing component
  • 2.0.0 - Breaking change (component API change)

**Changelog Format:**
```markdown
# Design System Changelog

## [1.2.0] - 2025-12-13

### Added
- New Achievement Badge component
- Loading skeleton components
- Confetti animation component

### Changed
- Updated Button component hover states
- Improved Card component spacing

### Fixed
- Button disabled state contrast
- Input field focus ring visibility

### Deprecated
- Old Progress component (use new version)

### Removed
- Unused color tokens

6. Collaboration Workflows​

6.1 Designer → Developer Handoff​

Weekly Design Review:

  1. Monday: Designer creates/updates designs in feature branch
  2. Wednesday: Design review meeting
    • Walk through changes
    • Discuss implementation details
    • Address questions
  3. Thursday: Designer publishes to Staging
  4. Friday: Developer reviews in Dev Mode
    • Inspects components
    • Copies code snippets
    • Downloads assets

Handoff Checklist:

  • All components use design tokens
  • Responsive variants created (mobile, tablet, desktop)
  • All states documented (default, hover, active, disabled)
  • Accessibility notes added
  • Code snippets included
  • Assets exported (icons, images)
  • Prototype flows created for complex interactions
  • Comments added for special requirements

6.2 Feedback Loop​

Designer Feedback Process:

1. Developer implements component
2. Developer shares localhost URL or deployment
3. Designer reviews in browser
4. Designer leaves feedback using:
   - Figma comments (link to implementation)
   - Loom video walkthrough
   - Annotated screenshots
5. Developer makes adjustments
6. Repeat until approved

Feedback Template:

## Component Review: Button

**Implementation URL:** http://localhost:3000/storybook/?path=/story/button

### Visual Comparison
- [ ] Colors match design tokens
- [ ] Spacing matches spec (16px padding)
- [ ] Border radius correct (12px)
- [ ] Typography matches (16px semibold)

### Interaction Review
- [ ] Hover state smooth transition (200ms)
- [ ] Active state visible
- [ ] Disabled state correct opacity (50%)
- [ ] Loading state spinner size/color correct

### Responsive Behavior
- [ ] Works on mobile (320px+)
- [ ] Touch targets adequate (44x44px min)
- [ ] Stacks properly in small containers

### Accessibility
- [ ] Focus ring visible
- [ ] Keyboard navigation works
- [ ] Screen reader announces correctly
- [ ] Color contrast passes WCAG AA

### Feedback
1. Hover transition feels too fast, increase to 300ms
2. Disabled state needs lower opacity (40% instead of 50%)
3. Loading spinner should be white, not blue

### Approval Status
- [ ] Approved
- [x] Needs revisions (see feedback above)

7. Asset Export Workflow​

7.1 Icon Export​

Export Settings:

Icons/
├── SVG
│   ├── icon-name.svg
│   └── Settings:
│       ├── Format: SVG
│       ├── Outline stroke: checked
│       ├── Remove fill: unchecked
│       └── Include id attribute: checked
│
└── PNG
    ├── icon-name.png
    ├── icon-name@2x.png
    ├── icon-name@3x.png
    └── Settings:
        ├── Format: PNG
        ├── Scale: 1x, 2x, 3x
        └── Constraints: Scale

Naming Convention:

icon-{category}-{name}-{variant}.svg

Examples:
- icon-action-edit.svg
- icon-action-delete.svg
- icon-status-success.svg
- icon-nav-home-outline.svg
- icon-nav-home-filled.svg

7.2 Image Export​

Export Settings:

Images/
├── Optimized
│   ├── Format: WebP (primary)
│   ├── Quality: 80%
│   └── Progressive: checked
│
└── Fallback
    ├── Format: PNG/JPG
    ├── Quality: 85%
    └── Compression: checked

Image Specifications:

Hero Images:
- Width: 1920px (desktop)
- Width: 1200px (tablet)
- Width: 640px (mobile)
- Format: WebP + JPG fallback
- Quality: 80%

Thumbnails:
- Width: 400px
- Format: WebP
- Quality: 75%

Icons:
- Size: 24x24px (base)
- Exports: SVG, PNG @2x, @3x

8. Figma Plugins & Tools​

Design Workflow:

  • A11y - Color Contrast Checker - Verify WCAG compliance
  • Stark - Comprehensive accessibility toolkit
  • Content Reel - Generate realistic content
  • Unsplash - High-quality placeholder images
  • Lorem Ipsum - Text generation

Development Workflow:

  • Figma to Code - Generate React/Tailwind code
  • HTML to Figma - Import existing HTML
  • CSS Exporter - Export precise CSS values
  • Zeplin - Advanced developer handoff (alternative)

Productivity:

  • Auto Layout Absolute - Quick layout adjustments
  • Component Utilities - Batch component operations
  • Find and Replace - Text and style updates
  • Instance Finder - Locate component usage

8.2 Custom Plugin Development​

For STEMBlock.ai-specific needs:

// plugins/stemblock-token-exporter/code.ts
// Export design tokens to Tailwind config format

figma.showUI(__html__, { width: 400, height: 600 })

figma.ui.onmessage = async (msg) => {
  if (msg.type === 'export-tokens') {
    const localStyles = await figma.getLocalPaintStyles()

    const tokens = localStyles.reduce((acc, style) => {
      // Convert Figma styles to Tailwind format
      // Output: { 'stem-blue-500': '#2E7CF6', ... }
      return acc
    }, {})

    figma.ui.postMessage({
      type: 'tokens-exported',
      data: tokens,
    })
  }
}

9. Maintenance & Updates​

9.1 Regular Audits​

Monthly Component Audit:

  • Review usage statistics
  • Identify unused components
  • Check for detached instances
  • Update component variants as needed
  • Verify design token usage

Quarterly Design System Review:

  • Assess design token effectiveness
  • Evaluate component coverage
  • Review accessibility compliance
  • Update documentation
  • Gather developer feedback

9.2 Deprecation Process​

When deprecating a component:

  1. Announce (Week 1)

    • Add "DEPRECATED" label to component
    • Update documentation with migration guide
    • Notify team in design channel

  2. Provide Alternative (Week 2-4)

    • Offer new component as replacement
    • Create migration documentation
    • Support team during transition

  3. Remove (Week 5+)

    • Hide deprecated component from library
    • Archive in "Deprecated" page
    • Keep for reference (don't delete)

Deprecation Notice Template:

⚠️ DEPRECATED

This component will be removed in v2.0.0

Use [NewComponentName] instead.

Migration guide: [link to docs]

Last supported version: v1.5.0

Summary​

This Figma workflow ensures:

  • ✅ Organized, scalable design system
  • ✅ Smooth designer-developer handoff
  • ✅ Consistent component usage
  • ✅ Efficient asset management
  • ✅ Clear documentation and versioning

Next Document: Accessibility Checklist

Document Version: 1.0 Last Updated: December 13, 2025