Webflow Development

Webflow Development

Build pixel-perfect websites in the Webflow Designer using MCP tools and browser automation.

Prerequisites

• Webflow MCP Bridge Chrome extension connected (provides mcp__webflow__* tools)
• Claude in Chrome extension for browser automation (navigation, clicks, JS injection)
• Webflow Designer open in Chrome with the target site loaded

Core Workflow

1. Discover — Use element_tool to explore the current page structure and find elements by style name
2. Build — Use element_builder to create new elements (DivBlock, Heading, Paragraph, LinkBlock, Image, etc.)
3. Style — Use style_tool to apply CSS properties at each breakpoint
4. Content — Use set_text (via element_tool) to set text content on Heading/Paragraph elements
5. Components — Use element_builder with component param to insert component instances
6. Code Embeds — Use browser automation to add Code Embed elements for SVGs, custom CSS, or complex patterns
7. QA — Use element_snapshot_tool to capture screenshots, resize browser for responsive checks
8. Publish — Use data_sites_tool to publish the site

Tool Quick Reference

Breakpoint System (Critical)

Webflow uses a desktop-first cascade. Styles set on main inherit downward unless overridden.

When transferring from a local mobile-first codebase, see references/breakpoints-and-styles.md for the mapping table.

Setting Styles at Breakpoints

style_tool → set_styles:
  styleName: "my-element"
  breakpoint: "main"          # or "medium", "small", "tiny", "xl"
  pseudo: "noPseudo"          # REQUIRED when updating existing properties on main
  properties:
    font-size: "18px"
    color: "#1A2332"

Known Gotchas (Must-Know)

1. pseudo: "noPseudo" is required when updating existing properties on main breakpoint. Without it, the value silently fails to change.
2. overflow is a shorthand — use overflow-x and overflow-y separately.
3. TextBlock type creates a DivBlock that does NOT support set_text. Use Heading or Paragraph types for text elements.
4. element_builder with component: "" (empty string) causes timeouts. Always pass a valid component ID or omit the parameter.
5. Large element trees — element_tool with get_elements on complex pages can return 100K+ characters. Filter by style name or save to file and parse with jq/Python.
6. Designer in preview mode — URLs with workflow=sitePreview block style edits. Navigate to the designer URL without this parameter.
7. MCP connection drops — If you get "Unable to connect to Webflow Designer", navigate to the designer URL with the ?app= parameter to reconnect the MCP Bridge.
8. Inline styles override CSS — Some Webflow interactions (e.g., animations) leave stuck inline styles like transform: translate3d(...). Override with !important in a Code Embed.

For the complete gotchas reference with solutions, see references/gotchas.md.

Section Container Pattern

Every page section should include container constraints to prevent content from touching viewport edges:

• main: max-width: 1200px, margin-left: auto, margin-right: auto
• medium: padding-left: 40px, padding-right: 40px
• small: padding-left: 20px, padding-right: 20px

Workflow: Transferring a Local Project to Webflow

When the user has a local web project (React, Vue, HTML/CSS, etc.) and wants to replicate it in Webflow:

1. Read the local component (TSX/HTML + CSS) to understand structure, styles, and content
2. Map CSS variables to pixel values at each breakpoint (resolve var(--x) to actual values)
3. Map local breakpoints to Webflow breakpoints (see breakpoint mapping reference)
4. Build the element tree in Webflow using element_builder
5. Apply styles using style_tool with resolved pixel values at each Webflow breakpoint
6. Set text content using element_tool → set_text
7. Handle SVGs/custom code via Code Embed (see references/code-embeds-and-svgs.md)
8. QA — screenshot and compare with local dev site

For the full detailed guide, see references/local-to-webflow.md.

Workflow: Building from Scratch (Figma or No Design)

1. Establish design tokens — Create Webflow variables for colors, fonts, spacing via variable_tool
2. Build page structure — Create sections, containers, grids via element_builder
3. Style top-down — Start with main breakpoint, then override for medium, small, tiny
4. Componentize repeating patterns — Use de_component_tool → transform_element_to_component
5. Add interactions/animations — Use Code Embeds for CSS animations, or Webflow's native interactions
6. Responsive QA — Check each breakpoint, screenshot at 1440px, 992px, 768px, 480px, 375px

Workflow: Creating Reusable Components

1. Build and style the element as a regular element first
2. Select the root element via element_tool
3. Use de_component_tool → transform_element_to_component with a name
4. Insert instances on other pages via element_builder with component: "<component-id>"
5. Override text content on instances via element_tool → set_text

Using Design Variables

Prefer Webflow variables over hardcoded values for consistency:

variable_tool → set_variable:
  collection_id: "<collection-id>"
  variable_id: "<variable-id>"
  value: "#FF4733"

Reference variables in styles:

style_tool → set_styles:
  properties:
    color: "var(--variable-id)"

Discover existing variables with variable_tool → get_variables.

Reference Files

• references/breakpoints-and-styles.md — Breakpoint mapping table, typography scale patterns, style_tool examples
• references/local-to-webflow.md — Detailed guide for transferring local web projects to Webflow
• references/code-embeds-and-svgs.md — Code Embed insertion, SVG conversion (JSX→HTML), CodeMirror injection, custom CSS patterns
• references/gotchas.md — Complete list of known issues, error messages, and workarounds