feat: Figma content extraction mode - apply to existing templates

[rubenmarcus]

Summary

Extract text content and information architecture from Figma designs and apply directly to existing project templates/components.

Use Case

User has an existing project with a design system. They want to:

1. Extract content (text, labels, copy) from Figma mockups
2. Extract IA (page structure, navigation hierarchy)
3. Apply that content to their existing React/Vue/etc components

Usage

# Extract content from Figma and apply to existing project
ralph-starter run --from figma:<file-url> --figma-mode content

# Specify which components to update
ralph-starter run --from figma:<file-url> --figma-mode content --figma-target "src/pages"

Implementation

Task 1: Content Extraction

• Extract all text layers from Figma file
• Organize by frame/page hierarchy
• Identify semantic roles (heading, body, button, label, etc.)
• Map to content structure

Task 2: IA Extraction

• Detect page/screen structure
• Extract navigation patterns
• Identify component hierarchy
• Build content map

Task 3: Template Matching

• Scan existing project for components
• Match Figma frames to project components
• Identify text slots in templates
• Map Figma content to component props

Task 4: Content Application

• Update component props with extracted text
• Preserve existing styling/structure
• Handle dynamic content (arrays, conditionals)
• Generate content diff for review

Task 5: CLI Options

• Add --figma-mode content option
• Add --figma-target <path> for target directory
• Add --figma-preview to show changes without applying
• Add --figma-mapping <file> for custom content mapping

Task 6: Documentation

• Add content mode section to README.md
• Create docs/figma-content-mode.md for Docusaurus
• Document content mapping patterns
• Add examples for common frameworks

Content Structure Example

{
  "pages": {
    "home": {
      "hero": {
        "heading": "Welcome to Our App",
        "subheading": "The best solution for...",
        "cta": "Get Started"
      },
      "features": [
        { "title": "Feature 1", "description": "..." },
        { "title": "Feature 2", "description": "..." }
      ]
    }
  },
  "navigation": {
    "primary": ["Home", "Features", "Pricing", "Contact"],
    "footer": ["Privacy", "Terms", "Support"]
  }
}

Files to Create/Modify

• src/integrations/figma/content-extractor.ts (new)
• src/integrations/figma/template-matcher.ts (new)
• src/integrations/figma/content-applier.ts (new)
• src/integrations/figma/index.ts (add content mode)
• src/cli.ts (add --figma-target option)
• README.md (add content mode docs)
• docs/figma-content-mode.md (new - Docusaurus)

Considerations

• Handle component libraries (Chakra, MUI, etc.)
• Support multiple frameworks (React, Vue, Svelte)
• Preserve JSX structure when updating
• Handle edge cases (images with alt text, aria-labels)

[rubenmarcus]

✅ Shipped in ralph-starter v0.3.x — Figma content extraction mode is implemented in src/integrations/figma/parsers/content-extractor.ts. Extracts text content and information architecture (semantic roles: heading, subheading, body, button, label, link, caption) from Figma designs. See PR multivmlabs/ralph-starter#124 (Figma content extraction) and PR multivmlabs/ralph-starter#251 (enhanced Figma API coverage).