name	figma-integration
description	Guides design-to-code workflow using Figma integration. Helps extract designs, analyze components, and generate implementation specs. Auto-activates when users mention Figma URLs, design implementation, component conversion, or design-to-code workflows. Works with /ccpm:planning:design-ui, design-approve, design-refine, and /ccpm:utils:figma-refresh commands.

Figma Integration Skill

Transform Figma designs into implementation-ready specifications with CCPM's design-to-code workflow.

When This Skill Activates

This skill auto-activates when:

User mentions "Figma" or "design" in implementation context
User asks about "component", "design system", or "design tokens"
Running /ccpm:planning:design-ui (starts design process)
Running /ccpm:planning:design-refine (refine designs)
Running /ccpm:planning:design-approve (generate specs)
Running /ccpm:utils:figma-refresh (refresh cached designs)
User mentions "design-to-code", "design file", or "Figma component"

The Figma Workflow

Phase 1: Design Phase

Command: /ccpm:planning:design-ui ISSUE-ID

Start the design process by attaching Figma links to your Linear issue:

1. Create/update Linear issue with task description
2. Attach Figma design link in issue description
3. Run /ccpm:planning:design-ui TASK-123
4. CCPM extracts design metadata and creates options

What happens:

Detects Figma links from issue and related documents
Analyzes design file metadata (frames, components, assets)
Extracts design tokens (colors, typography, spacing)
Creates visual options or wireframes
Caches design data for instant access

Example:

/ccpm:planning:design-ui PSN-123

✅ Detected Figma link: https://figma.com/file/ABC123/UserDashboard
📦 Design Analysis:
   - 12 frames found
   - 15 components detected
   - Color palette: 8 colors
   - Typography: 4 font families
   - Spacing pattern: 4px, 8px, 16px grid

Ready for design review. Run: /ccpm:planning:design-refine PSN-123

Phase 2: Refinement Phase

Command: /ccpm:planning:design-refine ISSUE-ID [OPTION] [FEEDBACK]

Iterate on designs based on feedback:

1. Review design options from Phase 1
2. Provide feedback or request changes
3. Run /ccpm:planning:design-refine TASK-123 "feedback"
4. CCPM creates refined design options

What happens:

Analyzes your feedback
Generates refined design variations
Adjusts colors, layout, or components
Updates design cache with new versions
Shows side-by-side comparisons

Example:

/ccpm:planning:design-refine PSN-123 1 "Make the buttons larger, use primary color"

🎨 Refining Design Option 1...

Changes applied:
- Button height: 36px → 44px
- Button color: #6366F1 → primary color
- Button spacing: 12px → 16px

Preview: [design-option-1-v2]

Ready for approval? Run: /ccpm:planning:design-approve PSN-123 1

Phase 3: Approval & Spec Generation

Command: /ccpm:planning:design-approve ISSUE-ID OPTION-NUMBER

Approve final design and generate implementation specifications:

1. Review refined design options
2. Choose best option
3. Run /ccpm:planning:design-approve TASK-123 1
4. CCPM generates comprehensive specs

What happens:

Locks design as final reference
Extracts component specifications
Generates implementation specs with:
- Component breakdown
- Props and state recommendations
- Styling specifications
- Accessibility guidelines
- Responsive design rules
Creates Linear Document with specs
Updates issue description with spec link

Example:

/ccpm:planning:design-approve PSN-123 1

✅ Design Approved!

Generated Implementation Specs:
📄 Component Specifications
📄 Styling Guidelines
📄 Responsive Rules
📄 Accessibility Checklist

Specs saved to: https://linear.app/doc/ABC123
Ready for implementation!

Phase 4: Cache Management

Command: /ccpm:utils:figma-refresh ISSUE-ID

Refresh cached design data when designs change:

1. Update Figma designs
2. Run /ccpm:utils:figma-refresh TASK-123
3. CCPM re-extracts design data
4. Cache is updated with latest designs

When to refresh:

Design significantly changed
New components added to Figma
Colors or typography updated
Design tokens modified
Last refresh was >1 hour ago (cache TTL)

Design Analysis Deep Dive

What CCPM Extracts From Figma

Component Structure:

Dashboard
├── Header
│   ├── Logo
│   ├── Navigation
│   └── UserMenu
├── Sidebar
│   ├── NavItems
│   └── UserProfile
└── MainContent
    ├── Cards
    └── Charts

Design Tokens:

Color palette with hex/RGB values
Typography: font families, sizes, weights
Spacing: margin, padding, gap values
Shadows and effects
Border radius patterns

Component Metadata:

Frame dimensions (width, height)
Layout type (flex, grid, auto)
Constraints and responsive behavior
Text content and styles
Image assets and sizing

Component Detection

CCPM automatically identifies:

UI Components: Buttons, inputs, cards, modals, etc.
Layout Components: Headers, sidebars, grids, etc.
Screens/Pages: Full page layouts with multiple components
Variants: Different states (hover, active, disabled)
Assets: Icons, images, and design patterns

Example detection:

Frame: "Button / Primary / Large"
├── Detection: UI Component (Button)
├── Style: Primary (blue)
├── Size: Large (44px height)
├── State: Default
└── Variations: [Hover, Active, Disabled]

Implementation Specification Generation

What Gets Generated

When you approve a design, CCPM creates specs including:

1. Component Definition

Component: PrimaryButton
Props:
  - label: string (required)
  - size: "sm" | "md" | "lg" (default: "md")
  - disabled: boolean (default: false)
  - onClick: () => void
  - icon?: React.ReactNode

State:
  - loading: boolean
  - hover: boolean
  - focus: boolean

2. Visual Specifications

Sizing:
  - Small: 32px height
  - Medium: 40px height
  - Large: 44px height

Spacing:
  - Horizontal padding: 16px
  - Vertical padding: 8px

Typography:
  - Font: Inter
  - Weight: 600 (semibold)
  - Size: 14px

Colors:
  - Background: #6366F1
  - Text: #FFFFFF
  - Hover: #4F46E5

3. Responsive Rules

Breakpoints:
  - Mobile (< 768px): Single column
  - Tablet (768px - 1024px): Two columns
  - Desktop (> 1024px): Three columns

Mobile adjustments:
  - Button height: 40px → 36px
  - Padding: 16px → 12px
  - Font size: 14px → 12px

4. Accessibility Checklist

WCAG 2.1 AA Compliance:
- [ ] Color contrast ratio ≥ 4.5:1 for text
- [ ] Button hit target ≥ 44x44px
- [ ] Focus indicators visible
- [ ] ARIA labels for icons
- [ ] Keyboard navigation support

Practical Examples

Example 1: Simple Button Component

Start the workflow:

1. Create Linear issue: PSN-100 "Design primary button"
2. Add Figma link to issue description:
   https://figma.com/file/ABC123/Components?node-id=15:2
3. Run: /ccpm:planning:design-ui PSN-100

Design phase output:

✅ Design Analysis Complete

Component: Button / Primary
├── Size: 44px height
├── Color: #6366F1
├── Typography: Inter, 600, 14px
└── States: Default, Hover, Active, Disabled

Generated specs location: [Linear Document]
Ready for implementation.

Developer implements:

export function PrimaryButton({ label, onClick }) {
  return (
    <button
      onClick={onClick}
      className="h-11 px-4 bg-indigo-600 text-white font-semibold
                 rounded hover:bg-indigo-700 focus:outline-none
                 focus:ring-2 focus:ring-indigo-500"
    >
      {label}
    </button>
  );
}

Example 2: Dashboard Page

Complex multi-component design:

1. Create issue: PSN-200 "Design dashboard page"
2. Add Figma file: https://figma.com/file/XYZ789/Dashboard
3. Run: /ccpm:planning:design-ui PSN-200

Analysis reveals:

✅ Design Analysis Complete

Components detected: 12
├── Header (1)
├── Sidebar (1)
├── Cards (5)
├── Charts (3)
└── Tables (2)

Color palette:
├── Primary: #6366F1
├── Secondary: #EC4899
├── Neutral: #F3F4F6 - #1F2937
└── Success: #10B981

Typography:
├── Display: Space Mono
├── Body: Inter
└── Code: Monaco

Generated breakdown: [Linear Document]

Recommended approach:
1. Build layout shell (Header + Sidebar)
2. Implement card components
3. Add data visualization
4. Connect to API

Design refinement:

/ccpm:planning:design-refine PSN-200 1 "Increase sidebar width to 280px,
make cards taller"

✅ Refined Design Option 1

Adjustments:
- Sidebar width: 240px → 280px
- Card height: 220px → 280px
- Card padding: 16px → 20px
- Grid gap: 16px → 20px

Side-by-side comparison: [View]
Ready for approval!

Final approval:

/ccpm:planning:design-approve PSN-200 1

✅ Dashboard Design Approved!

Implementation specs generated:
📄 Layout Specification (Header, Sidebar, Grid)
📄 Card Component Specs (5 variations)
📄 Chart Integration Guide
📄 Responsive Breakpoints
📄 Accessibility Requirements

Linear Document: [docs/specs/dashboard-implementation]

Next: Run /ccpm:implementation:start PSN-200

Example 3: Design Iteration Workflow

Scenario: Design changed mid-implementation

Situation:
- Approved design shows 3-column layout
- Designer changes it to 2-column layout
- Specs are now outdated

Solution:
1. Update Figma file with new layout
2. Run: /ccpm:utils:figma-refresh PSN-300
3. Specs automatically update

Cache refresh process:

/ccpm:utils:figma-refresh PSN-300

🔄 Refreshing Figma cache...

Changes detected:
- ✅ Layout changed: 3-column → 2-column
- ✅ Card sizes updated
- ✅ Color palette modified (1 color added)
- ✅ Typography updated

Updated specs: [Linear Document]
Notified: Design changes affect layout components

Action items:
- Review responsive breakpoints
- Update card widths
- Check new color usage

Best Practices

Do's ✅

Organize your Figma file
- Use clear, descriptive frame names
- Group related components
- Label variants (e.g., "Button / Primary / Large")
- Document component purpose in descriptions
Keep designs up-to-date
- Update Figma as designs change
- Use design tokens consistently
- Document color meanings (primary, success, error)
- Update component descriptions with specs
Use descriptive Figma links
- Link to specific components, not entire file
- Use node IDs for precise targeting
- Example: /file/ABC123?node-id=15:2
Attach Figma links to Linear issues
- Always include design link in issue description
- Add to existing issues during planning
- Update links if design file changes
Review extracted specs
- Verify component detection is correct
- Check color values match your palette
- Ensure spacing recommendations work
- Validate responsive breakpoints

Don'ts ❌

Don't implement without approved specs
- Always run design-approve first
- Prevents scope creep
- Ensures design alignment
Don't ignore cache invalidation
- Refresh designs when file changes significantly
- Don't work with stale cache
- Keeps specs synchronized
Don't use vague frame names
- "Frame 15" is not helpful
- Use: "UserCard / Default / Light"
- Helps CCPM detect components correctly
Don't skip accessibility specs
- Review WCAG checklist before implementation
- Test color contrast
- Verify button sizes and spacing
Don't bypass refinement phase
- Always iterate with design-refine
- Get feedback before approval
- Prevents rework during implementation

Caching & Performance

How Caching Works

CCPM caches Figma data to provide instant access:

Cache storage:

Stored in Linear issue comments
Timestamped for validation
TTL: 1 hour (configurable)
Survives across sessions

Cache includes:

Component metadata
Design tokens (colors, typography, spacing)
Frame hierarchy
Text content
Asset references

Example cache entry:

## 🎨 Figma Design Cache (PSN-123)

Design File: Dashboard.fig
Cached: 2025-11-21 14:30:00 UTC
Expires: 2025-11-21 15:30:00 UTC
Server: figma-repeat

Components: 12
Colors: 8
Typography: 4 styles
Spacing grid: [4, 8, 16, 32]px

Status: ✅ Valid cache
Action: Use `figma-refresh` to update

When Cache Expires

Cache automatically invalidates if:

1 hour has passed
Design file was significantly modified
User explicitly runs figma-refresh
New Figma link was added

What happens when cache expires:

CCPM re-fetches design data from Figma
Analyzes updated design
Updates cache with new data
Notifies of any changes

Rate Limiting

CCPM respects Figma API rate limits:

Official Figma API (6 calls/month):

Used for critical operations
Careful rate limit management
Falls back to cache on limit

Community servers (60 calls/hour):

Higher rate limits
Recommended for active development
Better for iterative design workflows

Check rate limit status:

/ccpm:utils:figma-refresh PSN-123 --status

📊 Figma Rate Limit Status

Official API: 4/6 used (66%)
Community (figma-repeat): 42/60 used (70%)

Recommendation: Use community server to preserve official API calls

Integration with CCPM Commands

Works With Planning Commands

/ccpm:planning:design-ui

Starts design extraction
Creates design options
Caches metadata

/ccpm:planning:design-refine

Iterates on designs
Applies feedback
Updates cache

/ccpm:planning:design-approve

Finalizes design
Generates full specs
Creates Linear Document

Works With Implementation Commands

/ccpm:implementation:start

Loads approved specs
Uses component breakdown
References styling guidelines

/ccpm:implementation:sync

References design specs
Verifies implementation matches design
Flags design deviations

Works With Utility Commands

/ccpm:utils:figma-refresh

Force refresh design cache
Check rate limit status
View cache information

/ccpm:utils:context

Loads design specs for task context
Includes component breakdown
Shows styling guidelines

Troubleshooting

Design Not Detected

Problem: Figma link not found in issue

Solutions:

Verify link is in issue description

Add to issue: https://figma.com/file/ABC123/Project

Check link format

✅ Correct: https://figma.com/file/ABC123/Project
❌ Wrong: figma.com/file (missing protocol)

Try explicit link parameter

/ccpm:planning:design-ui PSN-123 --figma-url "https://..."

Colors Not Extracted

Problem: Design colors not in generated specs

Solutions:

Ensure colors are defined in Figma file
- Use color styles, not custom colors
- Name colors consistently (e.g., "Primary Blue")
Refresh cache
```
/ccpm:utils:figma-refresh PSN-123
```

Check server configuration

/ccpm:utils:figma-refresh PSN-123 --status

Rate Limit Exceeded

Problem: Too many Figma API calls

Solutions:

Switch to community server (higher limits)
- Community servers: 60/hour
- Official API: 6/month
Wait for rate limit reset
- Community servers reset hourly
- Official API resets monthly
Use cached data
- Cache remains valid even with rate limit
- Use figma-refresh only when needed

Spec Generation Failed

Problem: Linear Document creation failed

Solutions:

Check Linear permissions
- Verify write access to Linear workspace

Try again with larger issue ID

/ccpm:planning:design-approve PSN-123 1 --retry

Check cache validity
```
/ccpm:utils:figma-refresh PSN-123
```

Summary

This skill enables:

✅ Design extraction from Figma files
✅ Component detection and analysis
✅ Specification generation for implementation
✅ Design iteration with refinement
✅ Cache management for performance
✅ Best practices guidance throughout workflow

Typical workflow time:

Simple component: 2-5 minutes
Complex page: 10-15 minutes
Design iteration: 5-10 minutes per cycle

Key commands:

/ccpm:planning:design-ui PSN-123          # Start design
/ccpm:planning:design-refine PSN-123      # Iterate
/ccpm:planning:design-approve PSN-123 1   # Generate specs
/ccpm:utils:figma-refresh PSN-123         # Refresh cache

Integration: Works with /ccpm:planning:design-* and /ccpm:utils:figma-refresh commands MCP Servers: Figma MCP (figma-repeat, figma-trainer-guru, etc.) Linear Integration: Stores designs and specs in Linear Documents Shared Module: Uses _shared-figma-detection.md for link detection

figma-integration

Install Skill

SKILL.md

Figma Integration Skill

When This Skill Activates

The Figma Workflow

Phase 1: Design Phase

Phase 2: Refinement Phase

Phase 3: Approval & Spec Generation

Phase 4: Cache Management

Design Analysis Deep Dive

What CCPM Extracts From Figma

Component Detection

Implementation Specification Generation

What Gets Generated

Practical Examples

Example 1: Simple Button Component

Example 2: Dashboard Page

Example 3: Design Iteration Workflow

Best Practices

Do's ✅

Don'ts ❌

Caching & Performance

How Caching Works

When Cache Expires

Rate Limiting

Integration with CCPM Commands

Works With Planning Commands

Works With Implementation Commands

Works With Utility Commands

Troubleshooting

Design Not Detected

Colors Not Extracted

Rate Limit Exceeded

Spec Generation Failed

Summary