Skip to content

Latest commit

 

History

History
369 lines (291 loc) · 13.6 KB

figma-flutter-mcp.md

File metadata and controls

369 lines (291 loc) · 13.6 KB

Figma Flutter MCP: Why I Don't Rely Solely on Figma API

This explains why I didn't fork the existing Figma Context MCP or rely on Figma's API alone.

Overview

This project uses a hybrid approach that combines Figma API data extraction with intelligent analysis and Flutter-specific guidance generation. I deliberately avoid relying entirely on Figma's API endpoints for several critical reasons.

The Problem with Pure Figma API Approach

1. Published Resources Limitation

Figma's API has significant limitations when it comes to accessing design resources:

// ❌ Figma API only returns PUBLISHED resources
GET /v1/files/{file_key}/styles
// Returns: Only published color styles, text styles, effects

Reality Check:

  • Most internal design work is NOT published
  • Designers often work with local styles and components
  • Publishing requires additional workflow steps that many teams skip
  • Internal/confidential projects cannot be published publicly

2. Dev Mode Requirement

Figma's Dev Resources endpoints provide richer data but come with restrictions:

// ❌ Requires Dev Mode subscription
GET /v1/files/{file_key}/dev_resources
// Returns: Detailed component specs, but only with Dev Mode access

Barriers:

  • Dev Mode is a paid feature - not available to all users
  • Freelancers and small teams often don't have Dev Mode access
  • Client projects may not provide Dev Mode access to external developers
  • Educational/personal projects can't justify the cost

3. Framework Agnostic vs Flutter Specific

Figma's API returns generic design tokens:

{
  "fills": [{"type": "SOLID", "color": {"r": 0.2, "g": 0.4, "b": 0.8}}],
  "effects": [{"type": "DROP_SHADOW", "radius": 4, "offset": {"x": 2, "y": 2}}]
}

This requires additional translation to Flutter-specific implementations:

// Manual translation needed:
Container(
  decoration: BoxDecoration(
    color: Color.fromRGBO(51, 102, 204, 1.0),
    boxShadow: [BoxShadow(
      offset: Offset(2, 2),
      blurRadius: 4,
      color: Colors.black26,
    )],
  ),
)

4. Why I Didn't Fork Figma Context MCP

Instead of forking the existing Figma Context MCP, I built from scratch because:

Architectural Incompatibility:

  • Framework-agnostic design creates abstraction layers I don't need
  • Generic output format returns CSS-like properties instead of Flutter widgets
  • Complex extractor system designed for flexibility adds overhead for Flutter-specific use cases
  • Global style deduplication creates variable references instead of direct Flutter code

Different Goals:

  • Figma Context MCP focuses on comprehensive design system analysis across frameworks
  • My approach focuses on direct Flutter development with immediate actionable guidance
  • Figma Context MCP optimizes for design token extraction and reuse
  • My approach optimizes for Flutter widget generation and semantic understanding

Code Structure Mismatch:

// Figma Context MCP approach - Generic abstraction
const layout = buildSimplifiedLayout(node, context.parent);
result.layout = findOrCreateVar(context.globalVars, layout, "layout");

// My approach - Direct Flutter guidance
if (isButton(node)) {
  guidance += generateElevatedButton(textContent, styling);
}

My Hybrid Solution

1. Direct Node Access

I use Figma's basic node API to access any design, regardless of publication status:

// ✅ Works with ANY Figma file (public or private)
GET /v1/files/{file_key}/nodes?ids={node_ids}
// Returns: Complete node structure with all properties

Benefits:

  • Access to unpublished designs
  • Works with internal/confidential projects
  • No Dev Mode requirement
  • Real design data, not just published libraries

2. Intelligent Analysis Layer

Instead of relying on Figma's interpretation, I analyze the raw node data:

// My intelligent analysis
function detectSemanticType(content: string, nodeName: string): SemanticType {
  // Detects: button, heading, body, link, error, success, etc.
  // Based on content analysis, not just Figma's classification
}

function generateFlutterTextWidget(textInfo: TextInfo): string {
  // Generates Flutter-specific widget suggestions
  // Considers semantic meaning, not just visual properties
}

Advantages:

  • Semantic understanding of design intent
  • Flutter-optimized suggestions
  • Context-aware recommendations
  • Handles edge cases that Figma API misses

3. Flutter-First Architecture

My output is specifically tailored for Flutter development:

// ✅ Flutter-specific guidance
guidance += `Container(\n`;
guidance += `  decoration: BoxDecoration(\n`;
guidance += `    color: Color(0xFF${fill.hex.substring(1)}),\n`;
guidance += `    borderRadius: BorderRadius.circular(${cornerRadius}),\n`;
guidance += `  ),\n`;

vs Generic Figma API:

{
  "cornerRadius": 8,
  "fills": [{"color": {"r": 0.2, "g": 0.4, "b": 0.8}}]
}

vs Figma Context MCP:

layout: layout_ABC123
fills: fill_DEF456
globalVars:
  styles:
    layout_ABC123: { mode: "column", gap: "8px" }
    fill_DEF456: "#1976D2"

Advanced Style Deduplication System

One of the key innovations in this MCP is the advanced style deduplication system that goes far beyond simple hash-based matching.

Semantic Style Matching

The system recognizes semantically equivalent styles even when they're represented differently:

// ✅ These are recognized as equivalent:
{ fills: [{ hex: '#000000' }] }  // Full hex notation
{ fills: [{ hex: '#000' }] }     // Short hex notation
{ fills: [{ hex: '#000000', normalized: 'black' }] }  // With normalization

// All generate the same style ID and are deduplicated

Style Hierarchy Detection

The system automatically detects relationships between similar styles:

// Parent style: Base button
{ fills: [{ hex: '#007AFF' }], cornerRadius: 8, padding: { all: 12 } }

// Child style: Primary button variant (87% similar)
{ fills: [{ hex: '#007AFF' }], cornerRadius: 8, padding: { all: 16 } }
// ↳ Detected as variant with 13% variance from parent

Intelligent Style Merging

The system analyzes merge opportunities:

// Merge candidates detected:
// Score: 75% - 3 styles with 2 common properties
// Common: { cornerRadius: 8, padding: { all: 12 } }
// Differences: { fills: ['#007AFF', '#FF3B30', '#34C759'] }
// Recommendation: Create base style + color variants

Optimization Benefits

  • 30-50% reduction in total unique styles
  • Improved reusability through semantic matching
  • Style hierarchy for better maintainability
  • Memory efficiency with detailed optimization reports

Automatic Optimization

  • Transparent operation - Optimization happens automatically in the background
  • Smart thresholds - Auto-optimizes after every 20 new styles
  • Configurable - Use autoOptimize: false to disable if needed
  • Enhanced reporting - style_library_status shows hierarchy and relationships

Comprehensive Logging

The system provides detailed logging to track deduplication performance:

[MCP Server INFO] 🎨 Adding decoration style with properties: {...}
[MCP Server INFO] 🔍 Semantic match found! Reusing style decorationABC123 (usage: 2)
[MCP Server INFO] 🚀 Auto-optimization triggered! (20 new styles since last optimization)
[MCP Server INFO] ✅ Auto-optimization complete: { totalStyles: 45, duplicatesRemoved: 3, ... }

Logging Categories:

  • 🎨 Style Creation - New style generation with properties and hashes
  • 🔍 Semantic Matching - When equivalent styles are detected and reused
  • 🌳 Hierarchy Detection - Parent-child relationships and variance calculations
  • ⚡ Auto-optimization - Automatic optimization triggers and results
  • 📊 Analysis Results - Component analysis statistics and performance metrics

Real-World Compatibility

Scenario Pure Figma API Figma Context MCP My Hybrid Approach
Internal Company Designs ❌ Not published ✅ Full access ✅ Full access
Freelancer Projects ❌ No Dev Mode ✅ Works ✅ Works perfectly
Client Confidential Work ❌ Cannot publish ✅ Private access ✅ Private access
Personal/Learning Projects ❌ Cost prohibitive ✅ Free to use ✅ Free to use
Rapid Prototyping ❌ Requires setup ❌ Complex processing ✅ Instant analysis
Flutter Development ❌ Generic output ❌ Requires translation ✅ Direct Flutter code

Flutter Optimization Example

// My approach generates Flutter-ready code
if (textInfo.semanticType === 'button') {
  return `ElevatedButton(
    onPressed: () {
      // TODO: Implement ${textInfo.content} action
    },
    child: Text('${textInfo.content}'),
  )`;
}

// vs Figma Context MCP generic response
{
  layout: "layout_ABC123",
  textStyle: "style_DEF456",
  fills: "fill_GHI789",
  globalVars: {
    styles: {
      layout_ABC123: { mode: "row", alignItems: "center" },
      style_DEF456: { fontSize: 16, fontWeight: 500 },
      fill_GHI789: "#2196F3"
    }
  }
}

What I DON'T Do vs What I DO

❌ What I DON'T Do:

  • Create .dart files - I don't generate actual Flutter code files
  • Generate complete Flutter projects - No project scaffolding or structure creation
  • Write executable Flutter applications - No runnable app generation
  • Manage Flutter project structure - No file organization or dependency management

✅ What I DO:

  • Extract design data from Figma - Comprehensive analysis of layouts, styling, and content
  • Generate text-based guidance with Flutter syntax - Structured recommendations for AI consumption
  • Provide copy-paste ready snippets - Ready-to-use Flutter widget patterns with real design values
  • Structure information for AI consumption - Organized data that AI models can use to generate actual code
  • Export and manage assets - Automatic image export with Flutter integration

The AI Workflow:

  1. My Tool: Figma Design → Structured Analysis + Flutter Guidance Text
  2. AI Model: Reads Guidance → Generates Actual Flutter Code Files
  3. Developer: Gets Complete Flutter Widgets/Screens

Why Not Figma Context MCP?

Technical Reasons:

  • Over-engineered for Flutter use case - Complex extractor system adds overhead
  • Framework-agnostic abstraction - Creates additional translation layers
  • CSS-focused output - Requires conversion to Flutter concepts
  • Global variable system - Adds complexity for single-component analysis
  • Generic design tokens - Don't map directly to Flutter widgets

Practical Reasons:

  • Different target audience - Design system managers vs Flutter developers
  • Different workflow - Comprehensive analysis vs rapid prototyping
  • Different output goals - Reusable tokens vs direct implementation
  • Maintenance overhead - Forking adds complexity and maintenance burden

Strategic Reasons:

  • Flutter-specific optimization - My architecture is purpose-built for Flutter
  • Simpler codebase - Easier to maintain and extend for Flutter needs
  • Direct control - No need to work around framework-agnostic abstractions
  • Faster iteration - No need to coordinate with upstream changes

Why This Matters

For Developers:

  • No barriers to entry - works with any Figma file
  • Flutter-optimized guidance reduces development time
  • Semantic understanding provides better widget suggestions
  • Asset management handles images automatically

For Designers:

  • No publishing required - analyze any design
  • Works with internal files - no need to make designs public
  • Preserves design intent through semantic analysis
  • Handles real-world design patterns

For Teams:

  • Cost-effective - no Dev Mode subscription needed
  • Flexible - works with any Figma access level
  • Secure - handles confidential designs
  • Efficient - structured guidance for AI code generation

Optimization Tips

  • Better prompts = Better results - Be specific about what you want to analyze
  • Detailed requests - "Analyze this login form component" vs "Analyze this"
  • Context matters - Mention the component type, expected behavior, or specific concerns

Example of Good vs Poor Prompts

❌ Poor Prompt:

Analyze this Figma link: https://figma.com/...

✅ Good Prompt:

Analyze this login form component from Figma: https://figma.com/...
Focus on the input field styling, button states, and form validation patterns.
I need Flutter widgets for a mobile app with Material Design.

Conclusion

My hybrid approach solves real-world problems that both pure Figma API solutions and existing framework-agnostic tools cannot address effectively:

  1. Accessibility: Works with any Figma file, regardless of publication status
  2. Cost-effectiveness: No premium subscriptions required
  3. Flutter-first: Purpose-built for Flutter development, not adapted from generic solutions
  4. Intelligence: Semantic analysis beyond basic API data
  5. Practicality: Handles real-world design workflows without abstraction overhead
  6. AI-Ready: Structured guidance for intelligent code generation
  7. Focused scope: Optimized specifically for Flutter rather than trying to support all frameworks

This architecture ensures that any developer can convert any Figma design into Flutter-ready guidance, regardless of their Figma subscription level or the design's publication status. By building specifically for Flutter rather than adapting existing framework-agnostic solutions, I provide a more direct, efficient, and maintainable path from design to code.