Skip to main content

Source: ocean/docs/figma-design-system.md | ✏️ Edit on GitHub

Figma Design System Integration

This document outlines how to integrate Figma with our Ocean project using shadcn/ui as the baseline design system.

Design Tokens​

We're using shadcn/ui's default zinc theme as our baseline. The design tokens are defined in /src/styles/tokens.css using HSL color values that can be easily converted for Figma.

Color Palette​

Light Theme​

  • Background: hsl(0 0% 100%) → #FFFFFF
  • Foreground: hsl(240 10% 3.9%) → #09090B
  • Primary: hsl(240 5.9% 10%) → #18181B
  • Primary Foreground: hsl(0 0% 98%) → #FAFAFA
  • Secondary: hsl(240 4.8% 95.9%) → #F4F4F5
  • Secondary Foreground: hsl(240 5.9% 10%) → #18181B
  • Muted: hsl(240 4.8% 95.9%) → #F4F4F5
  • Muted Foreground: hsl(240 3.8% 46.1%) → #71717A
  • Accent: hsl(240 4.8% 95.9%) → #F4F4F5
  • Accent Foreground: hsl(240 5.9% 10%) → #18181B
  • Destructive: hsl(0 84.2% 60.2%) → #EF4444
  • Destructive Foreground: hsl(0 0% 98%) → #FAFAFA
  • Border: hsl(240 5.9% 90%) → #E4E4E7
  • Input: hsl(240 5.9% 90%) → #E4E4E7
  • Ring: hsl(240 10% 3.9%) → #09090B

Dark Theme​

  • Background: hsl(240 10% 3.9%) → #09090B
  • Foreground: hsl(0 0% 98%) → #FAFAFA
  • Primary: hsl(0 0% 98%) → #FAFAFA
  • Primary Foreground: hsl(240 5.9% 10%) → #18181B
  • Secondary: hsl(240 3.7% 15.9%) → #27272A
  • Secondary Foreground: hsl(0 0% 98%) → #FAFAFA
  • Muted: hsl(240 3.7% 15.9%) → #27272A
  • Muted Foreground: hsl(240 5% 64.9%) → #A1A1AA
  • Accent: hsl(240 3.7% 15.9%) → #27272A
  • Accent Foreground: hsl(0 0% 98%) → #FAFAFA
  • Destructive: hsl(0 62.8% 30.6%) → #7F1D1D
  • Destructive Foreground: hsl(0 0% 98%) → #FAFAFA
  • Border: hsl(240 3.7% 15.9%) → #27272A
  • Input: hsl(240 3.7% 15.9%) → #27272A
  • Ring: hsl(240 4.9% 83.9%) → #D4D4D8

Typography​

Using Tailwind's default font stack:

  • Font Family: font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji", "Segoe UI Symbol", "Noto Color Emoji"
  • Base Font Size: 16px
  • Line Height: 1.5

Spacing​

Using Tailwind's default spacing scale (1 unit = 0.25rem = 4px):

  • 0: 0px
  • 1: 4px
  • 2: 8px
  • 3: 12px
  • 4: 16px
  • 5: 20px
  • 6: 24px
  • 8: 32px
  • 10: 40px
  • 12: 48px
  • 16: 64px
  • 20: 80px
  • 24: 96px
  • 32: 128px

Border Radius​

  • Default: 0.5rem (8px)
  • Small: calc(0.5rem - 4px) (4px)
  • Medium: calc(0.5rem - 2px) (6px)
  • Large: 0.5rem (8px)

Setting Up Figma​

1. Create a Figma File Structure​

Ocean Design System/
├── 🎨 Colors
│   ├── Light Theme
│   └── Dark Theme
├── 📐 Typography
│   ├── Headings
│   └── Body Text
├── 📏 Spacing & Grid
├── 🧩 Components
│   ├── Buttons
│   ├── Inputs
│   ├── Cards
│   ├── Dialogs
│   └── [Other shadcn components]
└── 📱 Page Templates

2. Install Figma Plugins​

Recommended plugins for maintaining consistency:

  • Figma Tokens: For managing design tokens
  • Design Tokens: Export tokens to code
  • Tailwind CSS: Generate Tailwind classes
  • shadcn/ui Figma: Community file with shadcn components

3. Import shadcn Components​

  1. Visit the shadcn/ui Figma Community file
  2. Duplicate to your workspace
  3. Use as a reference for component structure

4. Token Synchronization​

To keep Figma and code in sync:

  1. Export from Code to Figma:

    # Install token transformer
    npm install -g token-transformer

    # Create a tokens.json from CSS variables
    node scripts/css-to-tokens.js

  2. Import to Figma:

    • Use Figma Tokens plugin
    • Import the generated tokens.json
    • Apply to your design system

Best Practices​

1. Component Naming​

  • Match shadcn/ui component names exactly
  • Use the same variant names (e.g., default, destructive, outline)

2. Layer Structure​

  • Follow shadcn's component structure
  • Use Auto Layout extensively
  • Name layers semantically

3. Design Tokens​

  • Always use tokens for colors, spacing, and radii
  • Never use hard-coded values
  • Keep light/dark themes in sync

4. Documentation​

  • Document component states
  • Include usage guidelines
  • Link to code implementation

Workflow Integration​

1. Design Handoff​

  • Use Figma's Dev Mode for developers
  • Include Tailwind classes in component descriptions
  • Export assets using agreed naming conventions

2. Design Review​

  • Compare Figma components with live shadcn/ui examples
  • Validate against the design tokens
  • Test both light and dark themes

3. Updates and Maintenance​

  • When updating tokens, update both code and Figma
  • Use version control for Figma files
  • Regular design system audits

Resources​

Next Steps​

  1. Set up the Figma file with the structure above
  2. Import the color tokens
  3. Create base components matching shadcn/ui
  4. Establish a regular sync process between design and development