Figma → RadTools Design System Sync

Import or update the RadTools design system from Figma. This is for design system setup, not everyday component building.

When to Use This Skill

✅ Use this skill for:

• Initial project setup: importing colors, typography, spacing from Figma
• Design system updates: syncing new tokens after Figma design changes
• Adding new color palettes or typography scales

❌ Do NOT use for:

• Building individual pages from Figma (use Figma MCP + existing tokens)
• Creating components from Figma frames (use Figma MCP + component rules)
• Everyday development with Figma references

Prerequisites

• Figma MCP connected
• RadTools installed (check for devtools/ folder)
• Development environment (NODE_ENV=development)

Critical Rule

Never edit app/globals.css directly. Use POST /api/devtools/write-css — this is RadTools' own persistence mechanism.

Import Workflow

Step 1: Extract from Figma

Use Figma MCP tools:

get_variable_defs(nodeId, fileKey) → colors, spacing variables
get_design_context(nodeId, fileKey) → component styles, typography

Step 2: Transform to RadTools Data Structures

Colors → BaseColor[]:

interface BaseColor {
  id: string;           // "primary" or "sun-yellow"
  name: string;         // CSS variable suffix: "primary" → --color-primary
  displayName: string;  // UI label: "Primary"
  value: string;        // "#3B82F6"
  category: 'brand' | 'neutral';
}

Map Figma variables to semantic names:

• Brand/Primary → { id: 'primary', name: 'primary', category: 'brand' }
• Surface/Background → { id: 'surface', name: 'surface', category: 'brand' }
• Neutral/50 → { id: 'lightest', name: 'lightest', category: 'neutral' }

Typography → TypographyStyle[]:

interface TypographyStyle {
  id: string;
  element: string;        // "h1", "h2", "p", "code", etc.
  fontFamilyId: string;   // References FontDefinition.id
  fontSize: string;       // Tailwind class: "text-4xl"
  lineHeight?: string;    // Tailwind class: "leading-tight"
  fontWeight: string;     // Tailwind class: "font-bold"
  baseColorId: string;    // References BaseColor.id
  displayName: string;
  utilities?: string[];   // Additional classes: ["underline"]
}

Map Figma text styles:

• Display/Large → element: "h1"
• Heading/Primary → element: "h2"
• Body/Regular → element: "p"
• Code/Mono → element: "code"

Fonts → FontDefinition[]:

interface FontDefinition {
  id: string;
  name: string;           // "Inter"
  family: string;         // CSS font-family value
  files: FontFile[];
  weights: number[];      // [400, 700]
  styles: string[];       // ["normal", "italic"]
}

interface FontFile {
  id: string;
  weight: number;
  style: string;
  format: 'woff2' | 'woff' | 'ttf' | 'otf';
  path: string;           // "/fonts/Inter-Regular.woff2"
}

Step 3: Call RadTools API

POST to /api/devtools/write-css:

await fetch('/api/devtools/write-css', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    baseColors: BaseColor[],      // Colors for @theme blocks
    borderRadius: {               // Border radius tokens
      sm: '0.25rem',
      md: '0.5rem',
      lg: '1rem'
    },
    fonts: FontDefinition[],      // Font definitions for @font-face
    typographyStyles: TypographyStyle[], // Typography for @layer base
    colorModes: ColorMode[]       // Optional dark mode overrides
  })
});

The API:

• Creates backup at .globals.css.backup
• Surgically updates only managed sections
• Preserves scrollbar, animations, custom CSS

Step 4: Upload Assets

Save extracted assets to public/assets/:

• Icons: public/assets/icons/
• Images: public/assets/images/
• Logos: public/assets/logos/

Step 5: Create Components

For component creation, use the radtools-component-create skill which covers:

• Default export requirements
• Default prop values (visual editor requirement)
• TypeScript props interface
• Preview file setup for visual editing

Quick reference — components must use imported tokens:

// ✅ Uses tokens from @theme block
<button className="bg-sun-yellow text-black border-black rounded-md">

// ❌ Hardcoded colors
<button className="bg-[#FCE184] text-gray-900">

Tailwind v4 Token Generation

RadTools uses Tailwind CSS v4's @theme block for automatic utility class generation:

@theme {
  --color-{name}: {value};  /* → bg-{name}, text-{name}, border-{name} */
  --radius-{name}: {value}; /* → rounded-{name} */
  --shadow-{name}: {value}; /* → shadow-{name} */
}

Example: --color-sun-yellow: #FCE184 automatically generates:

• bg-sun-yellow
• text-sun-yellow
• border-sun-yellow

Semantic Token Naming

Map Figma variables to meaningful token names. Tailwind v4 generates utilities from whatever names you choose:

Note: Token names become both the CSS variable suffix (--color-{name}) and the generated utility classes. The id field is used for internal references (e.g., baseColorId in typography), while name determines the CSS output.

Validation

After import:

1. Open RadTools (Shift+Cmd+K)
2. Check Variables tab for colors
3. Check Typography tab for text styles
4. Check Components tab for component discovery

RadTools reads from globals.css on mount and should reflect all API-written changes.

Error Handling & Rollback

If Import Fails

The write-css API creates a backup before writing. To rollback:

# Check for backup
ls -la app/.globals.css.backup

# Restore from backup
cp app/.globals.css.backup app/globals.css

Common Errors

Partial Import Recovery

If import partially succeeds (e.g., colors work but typography fails):

1. Don't re-run full import — this overwrites working data
2. Fix the failing section in the request payload
3. Re-run with only the fixed section:

// Only update typography, keep existing colors
await fetch('/api/devtools/write-css', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    typographyStyles: [...],  // Only the fixed data
    // Omit baseColors, fonts, etc. to preserve existing
  })
});

Note: All fields are optional. The API only updates sections you provide:

• baseColors — updates @theme color variables
• fonts — updates @font-face declarations
• typographyStyles — updates @layer base element styles
• borderRadius — updates @theme radius variables
• colorModes — updates dark mode overrides

Typography can reference fontFamilyId values even if fonts array is omitted — existing font definitions are preserved.

Font File Workflow

Before importing fonts, ensure files exist:

1. Extract from Figma using get_design_context to identify font families
2. Obtain font files (.woff2 preferred):
   • Google Fonts: google-webfonts-helper
   • Licensed fonts: Export from font management tool
3. Upload to public/fonts/
4. Then run import with FontDefinition[] pointing to those paths

Reference Files

See references/data-structures.md for complete type definitions and examples.