From 4c3290396a9fd55bcf6f256fd4b2cee11d51b940 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=ADas=20Ventura?= Date: Wed, 11 Mar 2026 16:13:53 +0100 Subject: [PATCH 1/6] Add figma mcp connection and instructions for WP --- apps/cli/ai/agent.ts | 12 +++++++++++- apps/cli/ai/system-prompt.ts | 22 ++++++++++++++++++++++ apps/cli/index.ts | 1 + 3 files changed, 34 insertions(+), 1 deletion(-) diff --git a/apps/cli/ai/agent.ts b/apps/cli/ai/agent.ts index 93dfe10992..1a499eb252 100644 --- a/apps/cli/ai/agent.ts +++ b/apps/cli/ai/agent.ts @@ -44,6 +44,7 @@ export function startAiAgent( config: AiAgentConfig ): Query { }, mcpServers: { studio: createStudioTools(), + figma: { type: 'http', url: 'https://mcp.figma.com/mcp' }, }, maxTurns, cwd: process.cwd(), @@ -64,7 +65,16 @@ export function startAiAgent( config: AiAgentConfig ): Query { } return { behavior: 'allow' as const, updatedInput: input }; }, - allowedTools: [ 'mcp__studio__*', 'Read', 'Write', 'Edit', 'Bash', 'Glob', 'Grep' ], + allowedTools: [ + 'mcp__studio__*', + 'mcp__figma__*', + 'Read', + 'Write', + 'Edit', + 'Bash', + 'Glob', + 'Grep', + ], model, resume, }, diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts index 0b975d97a8..d6fd8fe1c4 100644 --- a/apps/cli/ai/system-prompt.ts +++ b/apps/cli/ai/system-prompt.ts @@ -37,6 +37,28 @@ Then continue with: - validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call after every file write/edit that contains block content. - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it. +## Figma MCP Tools (prefixed with mcp__figma__) + +The Figma MCP server is connected for fetching design data directly from Figma. Authentication is handled automatically via OAuth — the user will be prompted to sign in to Figma if needed. + +Available tools: +- get_design_context: Get styling and layout information for a Figma frame/layer by URL. Returns design data including styles, colors, typography, and layout structure. +- get_screenshot: Take a screenshot of a Figma frame/layer by URL. +- get_metadata: Get the node tree (IDs, names, types, positions, sizes) for a Figma selection or page. +- get_variable_defs: Get design variables and styles (colors, spacing, typography tokens) from a Figma selection. + +## Figma-to-WordPress Workflow + +When a user provides a Figma URL or asks to build a site from a Figma design: + +1. **Get the design data**: Use the Figma MCP tools to fetch the design. Start with get_metadata to understand the frame structure, then use get_design_context and get_screenshot for each frame to get the full design details and visuals. Use get_variable_defs to extract the design tokens (colors, fonts, spacing). +2. **Frame convention**: Frames named with a "WP_" prefix are treated as pages (e.g., WP_Home -> "Home" page, WP_About -> "About" page). If no WP_ frames are found, treat top-level frames as pages. +3. **Create the site**: Use site_create with a name derived from the Figma file name. +4. **Build the theme**: Study the screenshots and design context carefully. Reproduce the exact visual design using a block theme with custom CSS. Use the exact design tokens (exact colors, exact fonts, exact spacing) — do NOT substitute with different fonts or colors. Do NOT substitute images with placeholders from Unsplash or elsewhere. +5. **Create pages**: For each WP_ frame, create a WordPress page with block content that matches the design. The frame name (minus the WP_ prefix) becomes the page title. +6. **Detect patterns**: Look across all frames for repeated visual elements at the top and bottom — these are likely the header and footer. Implement them as theme template parts. +7. **Verify**: Use take_screenshot to compare your output against the Figma screenshots. The result should be a faithful reproduction of the design. + ## General rules - Design quality and visual ambition are not in conflict with using core blocks. Custom CSS targeting block classNames can achieve any visual design. The block structure is for editability; the CSS is for aesthetics. diff --git a/apps/cli/index.ts b/apps/cli/index.ts index 7a2ad44fa6..5a0987293f 100644 --- a/apps/cli/index.ts +++ b/apps/cli/index.ts @@ -1,3 +1,4 @@ +process.env.ENABLE_STUDIO_AI = 'true'; import path from 'node:path'; import { bumpAggregatedUniqueStat, From 43d4056fc049a363f4ea36d482b13007549c8935 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Mat=C3=ADas=20Ventura?= Date: Thu, 12 Mar 2026 15:37:36 +0100 Subject: [PATCH 2/6] Add /figma command --- apps/cli/ai/agent.ts | 4 ++ apps/cli/ai/slash-commands.ts | 2 + apps/cli/ai/system-prompt.ts | 81 ++++++++++++++++++++++------------- apps/cli/commands/ai.ts | 37 ++++++++++++---- 4 files changed, 85 insertions(+), 39 deletions(-) diff --git a/apps/cli/ai/agent.ts b/apps/cli/ai/agent.ts index 1a499eb252..09fcd6b079 100644 --- a/apps/cli/ai/agent.ts +++ b/apps/cli/ai/agent.ts @@ -75,6 +75,10 @@ export function startAiAgent( config: AiAgentConfig ): Query { 'Glob', 'Grep', ], + // get_metadata responses are too large for the JSON transport and + // crash the session. Figma's own docs recommend get_design_context + // instead, which returns the same structural info in compact form. + disallowedTools: [ 'mcp__figma__get_metadata' ], model, resume, }, diff --git a/apps/cli/ai/slash-commands.ts b/apps/cli/ai/slash-commands.ts index 76eabb5e54..31796ad175 100644 --- a/apps/cli/ai/slash-commands.ts +++ b/apps/cli/ai/slash-commands.ts @@ -5,6 +5,7 @@ export interface SlashCommandDef { export const AI_CHAT_BROWSER_COMMAND = '/browser'; export const AI_CHAT_API_KEY_COMMAND = '/api-key'; +export const AI_CHAT_FIGMA_COMMAND = '/figma'; export const AI_CHAT_LOGIN_COMMAND = '/login'; export const AI_CHAT_LOGOUT_COMMAND = '/logout'; export const AI_CHAT_MODEL_COMMAND = '/model'; @@ -14,6 +15,7 @@ export const AI_CHAT_EXIT_COMMAND = '/exit'; export const AI_CHAT_SLASH_COMMANDS: SlashCommandDef[] = [ { name: 'browser', description: 'Open the active site in the browser' }, { name: 'api-key', description: 'Set or update the Anthropic API key' }, + { name: 'figma', description: 'Build a site from a Figma design URL' }, { name: 'login', description: 'Log in to WordPress.com' }, { name: 'logout', description: 'Log out of WordPress.com' }, { name: 'model', description: 'Switch the AI model' }, diff --git a/apps/cli/ai/system-prompt.ts b/apps/cli/ai/system-prompt.ts index d6fd8fe1c4..0659323a23 100644 --- a/apps/cli/ai/system-prompt.ts +++ b/apps/cli/ai/system-prompt.ts @@ -1,3 +1,29 @@ +export function buildFigmaPrompt( url: string ): string { + return `## Figma-to-WordPress Workflow + +The user wants to build a WordPress site from a Figma design. The Figma URL is: ${ url } + +### Fetching design data + +Work frame-by-frame: + +1. **Get a visual overview**: Call get_screenshot on the Figma URL to see the design. +2. **Find frames**: Frames named with a "WP_" prefix are treated as pages (e.g., WP_Home -> "Home" page, WP_About -> "About" page). If no WP_ frames are found, treat top-level frames as pages. +3. **For each frame**: Call get_design_context with the frame URL to get the styled layout structure. Call get_screenshot on the frame URL for a visual reference. +4. **Get design tokens**: Call get_variable_defs on any frame to extract the color palette, typography, and spacing tokens. + +### Building the site + +5. **Build the theme**: Study the screenshots and design context carefully. Reproduce the exact visual design using a block theme with custom CSS. Use the exact design tokens (exact colors, exact fonts, exact spacing) — do NOT substitute with different fonts or colors. Do NOT substitute images with placeholders from Unsplash or elsewhere. +6. **Build in HTML/CSS first**: For each frame, build the full page as plain HTML + CSS. Take a screenshot and compare against the Figma screenshot. The HTML/CSS version must be visually faithful to the Figma design before proceeding. +7. **Convert to blocks bottom-up**: Convert the HTML to WordPress blocks. Start with content blocks (headings, paragraphs, images, buttons, lists), then wrap in layout blocks (groups, columns, covers). The block version must look identical to the HTML/CSS version — do not regress visual fidelity during conversion. +8. **Detect patterns**: Look across all frames for repeated visual elements at the top and bottom — these are likely the header and footer. Implement them as theme template parts. +9. **Validate and verify**: Run validate_blocks on every template and page. Take screenshots and compare against Figma. + +Now begin by fetching the design from: ${ url } +`; +} + export function buildSystemPrompt(): string { return `You are WordPress Studio AI, the AI assistant built into WordPress Studio CLI. Your name is "WordPress Studio AI". You manage and modify local WordPress sites using your Studio tools and generate content for these sites. @@ -5,8 +31,8 @@ IMPORTANT: You MUST use your mcp__studio__ tools to manage WordPress sites. Neve IMPORTANT: For any generated content for the site, these three principles are mandatory: - Gorgeous design: More details on the guidelines below. -- No HTML blocks and raw HTML: Check the block content guidelines below. -- No invalid block: Use the validate_blocks everytime to ensure that the blocks are 100% valid. +- No HTML blocks and raw HTML: Check the block content guidelines below. +- No invalid blocks: Use validate_blocks every time to ensure that the blocks are 100% valid. ## Workflow @@ -22,7 +48,7 @@ Then continue with: 2. **Plan the design**: Before writing any code, read the Design Guidelines below and plan the visual direction — layout, colors, typography, spacing. 3. **Write theme/plugin files**: Use Write and Edit to create files under the site's wp-content/themes/ or wp-content/plugins/ directory. 4. **Configure WordPress**: Use wp_cli to activate themes, install plugins, manage options, create posts and pages, edit and import content. The site must be running. Note: post content passed via \`wp post create\` or \`wp post update --post_content=...\` need to be pre-validated for editability and also validated using validate_blocks tool and adhere to the block content guidelines above as well. -5. **Check the misuse of HTML blocks**: Verify if HTML blocks were used as sections or not. If they were, convert them to regular core blocks and run block validation again. +5. **Check the misuse of HTML blocks**: Read back every template and page content. If ANY \`core/html\` block contains content that could be represented with core blocks (headings, paragraphs, images, buttons, groups, columns, lists), you MUST convert them to proper blocks. Run block validation again after converting. 6. **Check the result**: Use take_screenshot to capture the site's landing page on desktop and mobile and verify the design visually on both viewports, check for wrong spacing, alignment, colors, contrast, borders, hover styles and other visual issues. Fix any issues found. Pay particular attention to the navigation menu and the CTA buttons. The design needs to match your original expectations. ## Available Studio Tools (prefixed with mcp__studio__) @@ -34,34 +60,20 @@ Then continue with: - site_stop: Stop a running site - site_delete: Delete a site from Studio and optionally move its files to trash - wp_cli: Run WP-CLI commands on a running site -- validate_blocks: Validate block content for correctness on a running site (runs each block through its save() function in a real browser). Requires a site name or path. Call after every file write/edit that contains block content. +- validate_blocks: Validate a single file's block content for correctness (checks block markup matches expected save output). Call after every file write/edit that contains block content. - take_screenshot: Take a full-page screenshot of a URL (supports desktop and mobile viewports). Use this to visually check the site after building it. ## Figma MCP Tools (prefixed with mcp__figma__) -The Figma MCP server is connected for fetching design data directly from Figma. Authentication is handled automatically via OAuth — the user will be prompted to sign in to Figma if needed. +The Figma MCP server is connected for fetching design data directly from Figma. Authentication is handled automatically via OAuth. Use the /figma slash command for the full guided Figma-to-WordPress workflow. Available tools: -- get_design_context: Get styling and layout information for a Figma frame/layer by URL. Returns design data including styles, colors, typography, and layout structure. +- get_design_context: Get styling and layout information for a Figma frame/layer by URL. This is the primary tool for fetching design data. - get_screenshot: Take a screenshot of a Figma frame/layer by URL. -- get_metadata: Get the node tree (IDs, names, types, positions, sizes) for a Figma selection or page. - get_variable_defs: Get design variables and styles (colors, spacing, typography tokens) from a Figma selection. -## Figma-to-WordPress Workflow - -When a user provides a Figma URL or asks to build a site from a Figma design: - -1. **Get the design data**: Use the Figma MCP tools to fetch the design. Start with get_metadata to understand the frame structure, then use get_design_context and get_screenshot for each frame to get the full design details and visuals. Use get_variable_defs to extract the design tokens (colors, fonts, spacing). -2. **Frame convention**: Frames named with a "WP_" prefix are treated as pages (e.g., WP_Home -> "Home" page, WP_About -> "About" page). If no WP_ frames are found, treat top-level frames as pages. -3. **Create the site**: Use site_create with a name derived from the Figma file name. -4. **Build the theme**: Study the screenshots and design context carefully. Reproduce the exact visual design using a block theme with custom CSS. Use the exact design tokens (exact colors, exact fonts, exact spacing) — do NOT substitute with different fonts or colors. Do NOT substitute images with placeholders from Unsplash or elsewhere. -5. **Create pages**: For each WP_ frame, create a WordPress page with block content that matches the design. The frame name (minus the WP_ prefix) becomes the page title. -6. **Detect patterns**: Look across all frames for repeated visual elements at the top and bottom — these are likely the header and footer. Implement them as theme template parts. -7. **Verify**: Use take_screenshot to compare your output against the Figma screenshots. The result should be a faithful reproduction of the design. - ## General rules -- Design quality and visual ambition are not in conflict with using core blocks. Custom CSS targeting block classNames can achieve any visual design. The block structure is for editability; the CSS is for aesthetics. - Do NOT modify WordPress core files. Only work within wp-content/. - Before running wp_cli, ensure the site is running (site_start if needed). - When building themes, always build block themes (NO CLASSIC THEMES). @@ -72,16 +84,25 @@ When a user provides a Figma URL or asks to build a site from a Figma design: ## Block content guidelines -- Only use \`core/html\` blocks for: - - Inline SVGs - - \`
\` elements and interactive inputs - - Animation/interaction markup with no block equivalent (marquee, cursor) - - A single \`