
webflow-skills
Manage Webflow CMS content, audit site health, optimize assets, build Designer pages and components, create Code Components, run CLI workflows, and safely publish changes with built-in validation workflows
- GitHub stars
- 136
Install
/plugin install webflow-skills@webflow-skillsRun it inside Claude Code after adding the marketplace with /plugin marketplace add webflow/webflow-skills.
Contents
Discovered from sourceSkills 33
Accessibility Audit
Comprehensive WCAG 2.1 accessibility audit for Webflow pages with detailed issue detection and actionable fixes.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before starting - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify available sites - Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve site details - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto get all pages and their page IDs - Use Webflow MCP's
data_element_toolwith actionget_all_elements(passing the page ID directly) to get detailed element information - Use Webflow MCP's
data_element_toolwith actionset_attributesto fix accessibility issues - Use Webflow MCP's
element_snapshot_toolto get visual previews of elements — this is a Designer tool and requires a Designer connection if used - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective) - No Designer connection is required for the audit or fixes.
data_element_tooloperates headlessly on any page ID fromlist_pages. Designer is only needed if you choose to useelement_snapshot_toolfor optional visual previews.
Instructions
Phase 1: Site & Page Selection
- Get site information: Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify target site - Ask for page selection:
- If user provides page ID, use it directly
- Otherwise, use
data_pages_toolwith actionlist_pagesto show available pages - Let user select which page(s) to audit
- Confirm audit scope: Ask user what to check:
- Full audit (all accessibility checks)
- Critical issues only (WCAG Level A)
- Specific categories (forms, buttons, navigation, etc.)
Phase 2: Element Extraction & Analysis
- Extract all elements: Use
data_element_toolwith actionget_all_elements, passing the target page's ID from Phase 1, for detailed analysis — no Designer connection needed- Set
include_style_properties: trueto check focus styles - Set
include_all_breakpoint_styles: falseto minimize data
- Set
- Parse element data: Identify interactive and content elements:
- Buttons (Button, LinkBlock with button role)
- Links (TextLink, Link, LinkBlock)
- Form inputs (Input, Select, Textarea)
- Headings (Heading elements with levels)
- Interactive divs/spans (check for onClick or interactive roles)
- Images (Image elements) - SKIP for this audit
- Extract attributes for each element:
- ARIA attributes (aria-label, aria-describedby, role, tabIndex)
- DOM attributes (id, domId, href, type, placeholder)
- Text content
- Style properties (outline, border for focus states)
- Element metadata (canHaveAttributes, tag name)
Phase 3: Accessibility Checks
Critical Issues (Must Fix - WCAG Level A)
-
Icon-only buttons without labels (WCAG 4.1.2)
- Find: Button elements with no text content
- Check: Missing
aria-labeloraria-labelledby - Impact: Screen readers cannot identify button purpose
- Fix: Add
aria-labelattribute with descriptive text
-
Form inputs without labels (WCAG 1.3.1)
- Find: Input, Select, Textarea elements
- Check: Missing associated label or
aria-label - Impact: Users don't know what input is for
- Fix: Add
aria-labelor associate with<label>usingid
-
Non-semantic click handlers (WCAG 2.1.1)
- Find: Div or Span elements (identified by element type)
- Check: Interactive behavior without proper role/keyboard support
- Impact: Not keyboard accessible, screen readers miss interactivity
- Fix: Add
role="button",tabIndex="0", suggest using real<button>
-
Links without destination (WCAG 2.1.1)
- Find: Link elements with no
hrefattribute - Check: Links that only use onClick without href
- Impact: Not keyboard accessible, breaks browser features
- Fix: Add proper
hrefor convert to button
- Find: Link elements with no
Serious Issues (Should Fix - WCAG Level AA)
-
Focus outline removed without replacement (WCAG 2.4.7)
- Find: Elements with
outline: nonestyle - Check: No visible alternative focus indicator
- Impact: Keyboard users can't see focus
- Fix: Add visible focus style (border, box-shadow, background change)
- Find: Elements with
-
Missing keyboard handlers (WCAG 2.1.1)
- Find: Elements with onClick handlers
- Check: Missing onKeyDown for Enter/Space keys
- Impact: Not usable with keyboard alone
- Fix: Add keyboard event handlers
-
Touch target too small (WCAG 2.5.5)
- Find: Clickable elements (buttons, links)
- Check: Width or height < 44px
- Impact: Hard to tap on mobile devices
- Fix: Increase padding or min-width/min-height to 44px
Moderate Issues (Consider Fixing)
-
Heading hierarchy problems (WCAG 1.3.1)
- Find: Heading elements (h1-h6)
- Check: Skipped levels (h1 → h3, skipping h2)
- Impact: Confusing document structure
- Fix: Use proper sequential heading levels
-
Positive tabIndex (WCAG 2.4.3)
- Find: Elements with tabIndex > 0
- Check: Disrupts natural tab order
- Impact: Confusing keyboard navigation
- Fix: Use tabIndex="0" or "-1" only, let natural DOM order work
-
Role without required attributes (WCAG 4.1.2)
- Find: Elements with ARIA roles
- Check: Missing required ARIA attributes (e.g., role="button" without tabIndex)
- Impact: Incomplete accessibility semantics
- Fix: Add required attributes for role
Phase 4: Issue Categorization & Scoring
-
Categorize all findings:
- Critical: Must fix (blocks access)
- Serious: Should fix (significantly impacts usability)
- Moderate: Consider fixing (improves experience)
-
Calculate accessibility score (0-100):
- Start at 100
- Critical issue: -10 points each
- Serious issue: -5 points each
- Moderate issue: -2 points each
- Minimum score: 0
-
Generate severity summary:
- Total issues found
- Breakdown by severity
- Most common issue types
- Pages/sections most affected
Phase 5: Report Generation
-
Create detailed report with specific format:
═══════════════════════════════════════════════════ ACCESSIBILITY AUDIT: [Page Name] ═══════════════════════════════════════════════════ CRITICAL (X issues) ─────────────────── [A11Y] Element: Button "Submit" Issue: Button missing accessible name Location: Form section, element ID: {component: "abc", element: "xyz"} Current: <button><CloseIcon /></button> Fix: Add aria-label="Close" WCAG: 4.1.2 Name, Role, Value [A11Y] Element: Input field Issue: Form input without label Location: Contact form, element ID: {component: "def", element: "uvw"} Current: <input type="email" /> Fix: Add aria-label="Email address" or associate with <label> WCAG: 1.3.1 Info and Relationships SERIOUS (X issues) ────────────────── [A11Y] Element: Link "Read more" Issue: Focus outline removed without visible alternative Location: Blog section Current: outline: none Fix: Add visible focus style (e.g., border: 2px solid blue) WCAG: 2.4.7 Focus Visible MODERATE (X issues) ─────────────────── [A11Y] Element: Heading Issue: Heading hierarchy skipped (h1 → h3) Location: Article section Current: <h3>Subsection</h3> after <h1>Title</h1> Fix: Change to <h2> or add intermediate h2 WCAG: 1.3.1 Info and Relationships ═══════════════════════════════════════════════════ SUMMARY ─────────────────────────────────────────────────── Total Issues: X - Critical: X issues - Serious: X issues - Moderate: X issues Accessibility Score: XX/100 Most Common Issues: 1. [Issue type] - X occurrences 2. [Issue type] - X occurrences 3. [Issue type] - X occurrences ═══════════════════════════════════════════════════ -
Provide actionable insights:
- Prioritized fix list (critical first)
- Quick wins (easy fixes with big impact)
- Design pattern recommendations
- Resources for learning more
Phase 6: Fix Suggestions & Approval (Optional)
-
Offer to fix issues automatically: Fixes don't require Designer, so offer auto-fixes directly
-
Show preview of fixes:
Which issues would you like to fix? [1] ✓ Add aria-label to Submit button Element: Button in contact form Fix: Add aria-label="Submit contact form" Safe: Yes (adding attribute only) [2] ✓ Add aria-label to email input Element: Input in contact form Fix: Add aria-label="Email address" Safe: Yes [3] ⚠️ Fix heading hierarchy Element: h3 in article section Fix: Change heading level from h3 to h2 Safe: May affect visual styling Type numbers to skip (e.g., "3"), "all" for all, "none" to cancel -
Apply approved fixes: Use
data_element_toolwith actionset_attributes- Process in batches
- Show progress for large fix sets
- Report success/failure for each
-
Generate post-fix report:
- Issues fixed: X
- Issues remaining: Y
- New accessibility score: XX/100 (improved from YY/100)
Phase 7: Export & Resources (Optional)
-
Offer export formats:
- Markdown (readable documentation)
- JSON (machine-readable for tracking)
- CSV (spreadsheet for team review)
-
Provide resources:
- WCAG 2.1 quick reference links
- Webflow accessibility best practices
- Recommended testing tools (browser extensions, screen readers)
Important Considerations
What This Skill Checks
✅ Button accessibility (labels, roles) ✅ Form input labels and associations ✅ Link semantics and keyboard access ✅ Focus visibility and keyboard navigation ✅ Heading hierarchy and structure ✅ ARIA roles and attributes ✅ Touch target sizes ✅ Interactive element semantics
What This Skill Does NOT Check
❌ Image alt text (use asset-audit skill instead) ❌ Color contrast ratios (requires visual analysis) ❌ Animation/motion preferences ❌ Screen reader testing (needs manual verification) ❌ Content readability (language level, clarity)
Limitations
- Cannot detect visual-only issues (color contrast, small text)
- Cannot test actual screen reader behavior
- Cannot validate content quality or clarity
- Relies on element attributes and structure only
Examples
Example 1: Full Page Audit
User prompt:
Run an accessibility audit on my homepage
Step 1: Site & Page Selection
🔍 Accessibility Audit: Page Selection
I'll help you audit your homepage for accessibility issues.
First, let me get your site information...
Available sites:
1. Company Website
2. Portfolio Site
Which site? (1/2)
User response: 1
Step 2: Page Selection
Available pages in Company Website:
1. Home (/)
2. About (/about)
3. Contact (/contact)
4. Blog (/blog)
Which page would you like to audit? (1 for Home)
User response: 1
Step 3: Audit Scope
What level of audit would you like?
1. Full audit (all WCAG checks) - Recommended
2. Critical issues only (Level A compliance)
3. Specific categories (buttons, forms, navigation)
Your choice: (1/2/3)
User response: 1
Step 4: Audit Progress
🔄 Running Accessibility Audit...
Progress:
✅ Extracted page content (45 elements)
✅ Analyzing buttons and interactive elements
✅ Checking form inputs and labels
✅ Validating heading hierarchy
✅ Checking keyboard navigation
🔄 Analyzing focus states...
Analysis complete!
Step 5: Report
═══════════════════════════════════════════════════
ACCESSIBILITY AUDIT: Home
═══════════════════════════════════════════════════
CRITICAL (3 issues)
───────────────────
[A11Y] Element: Button (navigation toggle)
Issue: Icon-only button missing accessible name
Location: Header navigation
Element ID: {component: "nav-01", element: "btn-menu"}
Current: <button><MenuIcon /></button>
Fix: Add aria-label="Open navigation menu"
WCAG: 4.1.2 Name, Role, Value
[A11Y] Element: Input (email subscription)
Issue: Form input without label
Location: Footer, newsletter signup
Element ID: {component: "footer-01", element: "email-input"}
Current: <input type="email" placeholder="Enter email" />
Fix: Add aria-label="Email address for newsletter"
WCAG: 1.3.1 Info and Relationships
[A11Y] Element: Div (clickable card)
Issue: Non-semantic interactive element
Location: Services section, card 2
Element ID: {component: "services-01", element: "card-02"}
Current: <div onClick={...}>Service card</div>
Fix: Convert to <button> or add role="button" + tabIndex="0"
WCAG: 2.1.1 Keyboard
SERIOUS (5 issues)
──────────────────
[A11Y] Element: Link "Learn more"
Issue: Focus outline removed without visible alternative
Location: Hero section
Element ID: {component: "hero-01", element: "cta-link"}
Current: outline: none
Fix: Add focus style - border: 2px solid #0066cc or box-shadow
WCAG: 2.4.7 Focus Visible
[A11Y] Element: Button "Subscribe"
Issue: Touch target too small (30px × 36px)
Location: Footer newsletter form
Element ID: {component: "footer-01", element: "submit-btn"}
Current: Small button
Fix: Increase padding or set min-height: 44px
WCAG: 2.5.5 Target Size
[continues with 3 more serious issues...]
MODERATE (4 issues)
───────────────────
[A11Y] Element: Heading "Our Services"
Issue: Heading hierarchy skipped (h1 → h3)
Location: Services section
Element ID: {component: "services-01", element: "heading"}
Current: <h3>Our Services</h3> follows <h1>Welcome</h1>
Fix: Change to <h2> to maintain proper hierarchy
WCAG: 1.3.1 Info and Relationships
[continues with 3 more moderate issues...]
═══════════════════════════════════════════════════
SUMMARY
───────────────────────────────────────────────────
Total Issues: 12
- Critical: 3 issues (must fix)
- Serious: 5 issues (should fix)
- Moderate: 4 issues (consider fixing)
Accessibility Score: 64/100
Most Common Issues:
1. Missing button labels - 2 occurrences
2. Focus styles removed - 3 occurrences
3. Heading hierarchy problems - 2 occurrences
Quick Wins (Easy + High Impact):
✨ Add aria-label to icon buttons (2 min, +20 score points)
✨ Add input labels (5 min, +10 score points)
✨ Add focus styles (10 min, +15 score points)
═══════════════════════════════════════════════════
💡 Next Steps:
1. Fix critical issues first (blocks access for some users)
2. Add visible focus styles for keyboard users
3. Test with keyboard navigation (Tab, Enter, Space keys)
4. Consider testing with screen reader (NVDA/JAWS/VoiceOver)
Would you like me to help fix these issues?
Example 2: Multi-Page Audit
User prompt:
Audit accessibility across my entire site
Agent response:
🔍 Multi-Page Accessibility Audit
I'll audit all pages on your site for accessibility issues.
Found 8 pages:
1. Home
2. About
3. Services
4. Team
5. Blog
6. Blog Post Template (CMS)
7. Contact
8. Privacy Policy
This will take approximately 2-3 minutes.
Proceed with full site audit? (yes/no)
User: yes
Progress:
🔄 Auditing Site Accessibility...
Progress: ████████████░░░░░░░░ 60% (5/8 pages)
✅ Home - Score: 64/100 (12 issues)
✅ About - Score: 78/100 (6 issues)
✅ Services - Score: 71/100 (9 issues)
✅ Team - Score: 85/100 (4 issues)
✅ Blog - Score: 82/100 (5 issues)
🔄 Analyzing Blog Post Template...
Final Report:
═══════════════════════════════════════════════════
SITE-WIDE ACCESSIBILITY AUDIT
═══════════════════════════════════════════════════
OVERALL SCORE: 73/100
Pages Audited: 8
Total Issues: 48
- Critical: 11 issues
- Serious: 21 issues
- Moderate: 16 issues
═══════════════════════════════════════════════════
ISSUES BY PAGE
═══════════════════════════════════════════════════
🔴 Lowest Scores (Need Attention):
1. Home - 64/100 (12 issues: 3 critical, 5 serious, 4 moderate)
2. Services - 71/100 (9 issues: 2 critical, 5 serious, 2 moderate)
3. About - 78/100 (6 issues: 1 critical, 3 serious, 2 moderate)
🟢 Highest Scores:
1. Team - 85/100 (4 issues: 0 critical, 2 serious, 2 moderate)
2. Blog - 82/100 (5 issues: 1 critical, 2 serious, 2 moderate)
═══════════════════════════════════════════════════
SITE-WIDE PATTERNS
═══════════════════════════════════════════════════
Most Common Issues Across Site:
1. Missing button labels (icon buttons) - 8 occurrences
Pages affected: Home, Services, Blog, Contact
2. Focus outline removed - 12 occurrences
Pages affected: All pages (site-wide CSS issue)
3. Form inputs without labels - 5 occurrences
Pages affected: Home, Contact
4. Small touch targets (<44px) - 9 occurrences
Pages affected: Home, About, Services, Contact
═══════════════════════════════════════════════════
RECOMMENDATIONS
═══════════════════════════════════════════════════
🎯 Site-Wide Fixes (Fix Once, Helps Everywhere):
1. Add focus styles to global CSS (affects 12 issues across all pages)
2. Update button component to require aria-label (affects 8 issues)
3. Increase minimum touch target size in design system (affects 9 issues)
📋 Page-Specific Priorities:
1. Home page: Fix navigation menu button and newsletter form
2. Services page: Add labels to service card interactions
3. Contact page: Add proper labels to all form inputs
💡 Design System Improvements:
- Create accessible button component with required aria-label
- Add focus state variants to all interactive components
- Set minimum touch target size standard (44px)
Would you like:
1. Detailed report for specific page
2. Export findings to file (Markdown/JSON/CSV)
3. Help fixing site-wide issues
Example 3: Critical Issues Only
User prompt:
Check my contact page for critical accessibility issues only
Agent response:
🔍 Critical Issues Audit: Contact Page
Running quick scan for blocking accessibility issues...
✅ Page analyzed
═══════════════════════════════════════════════════
CRITICAL ISSUES: Contact Page
═══════════════════════════════════════════════════
Found: 4 critical issues
[1] Form Input Missing Label
Element: Email input field
Location: Contact form, top
Issue: No accessible name for screen readers
Fix: Add aria-label="Your email address"
WCAG: 1.3.1 (Level A)
[2] Form Input Missing Label
Element: Message textarea
Location: Contact form, bottom
Issue: No accessible name for screen readers
Fix: Add aria-label="Your message"
WCAG: 1.3.1 (Level A)
[3] Button Missing Label
Element: Submit button
Location: Contact form, bottom
Issue: Icon-only button with no text
Fix: Add aria-label="Submit contact form"
WCAG: 4.1.2 (Level A)
[4] Non-Semantic Interactive Element
Element: Social media link (Instagram)
Location: Footer
Issue: Div with onClick instead of proper link
Fix: Convert to <a href="..."> with aria-label="Instagram"
WCAG: 2.1.1 (Level A)
═══════════════════════════════════════════════════
⚠️ Impact: These issues prevent screen reader users from using your contact form.
🔧 Estimated fix time: 5 minutes
Would you like me to:
1. Run full audit (includes serious and moderate issues)
2. Fix these 4 critical issues now
3. Export this report (Markdown/JSON/CSV)
Safety Rules
Preview & Confirmation
- Always show detailed issue list before suggesting fixes
- Clearly mark severity levels (critical/serious/moderate)
- Explain impact of each issue in user-friendly terms
- Provide specific WCAG reference for each finding
Granular Approval for Fixes
- Allow user to select which issues to fix
- Warn about fixes that might affect visual design
- Process fixes in batches with progress indicators
- Report success/failure for each fix attempt
Error Handling
- If page cannot be accessed, explain clearly
- If element cannot be modified, suggest manual fix
- Separate automated fixes from manual review items
Validation
- Verify element types before suggesting fixes
- Check if element supports attributes before adding
- Test that suggested fixes are valid for element type
- Warn if fix might break existing functionality
Output Standards
Icons & Formatting
- 🔍 Discovery/Analysis
- 🔄 Processing
- ✅ Pass/Success
- ❌ Fail/Critical Issue
- ⚠️ Warning/Serious Issue
- 💡 Suggestion/Moderate Issue
- 📊 Report/Summary
- 🎯 Priority/Action Item
- 🔴 Critical Priority
- 🟡 Medium Priority
- 🟢 Low Priority
Report Structure
- Clear severity categorization
- Specific element identification with IDs
- Current state vs recommended fix
- WCAG reference for each issue
- Summary with actionable priorities
- Score for measurable progress
Communication
- Use clear, jargon-free language
- Explain WHY something is an issue (impact on users)
- Provide specific, actionable fixes
- Encourage testing with real assistive technology
- Emphasize that automated checks are just the start
Resources to Include
WCAG 2.1 Quick Reference
Webflow Accessibility Resources
- Webflow University: Accessibility best practices
- Using semantic HTML in Webflow
- Adding ARIA attributes in Webflow
Testing Tools
- Keyboard: Tab, Shift+Tab, Enter, Space
- Screen readers: NVDA (Windows), JAWS, VoiceOver (Mac/iOS)
- Browser extensions: axe DevTools, WAVE, Lighthouse
Common Fixes
- Button labels: Always include visible text or aria-label
- Form labels: Use Webflow's label element or aria-label
- Focus styles: Use :focus-visible pseudo-class
- Semantic HTML: Use proper elements (button, a, label)
Asset Audit
Analyze assets on a Webflow site for SEO optimization.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
data_assets_toolfor fetching and updating assets - Use Webflow MCP's
get_asset_preview(with the asset'sasset_id) for analyzing image content - Use Webflow MCP's
data_sites_toolwith actionlist_sitesfor listing available sites - Use Webflow MCP's
webflow_guide_toolto get best practices before starting - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Site Selection & Asset Discovery
- Get site: Identify the target site. If user does not provide site ID, ask for it.
- Fetch all assets: Use Webflow MCP's
data_assets_toolto get all assets from the site (each asset record includes itsasset_id, needed for previews)- For sites with 50+ assets, process in batches of 20
- Show progress: "Processing assets 1-20 of 150..."
- Detect patterns: Analyze asset naming for common patterns:
- Camera uploads (IMG_, DSC_, etc.)
- Screenshots (screenshot, Screen Shot, etc.)
- Generic names (untitled, image-1, etc.)
- Date-based names (2024-01-10, etc.)
Phase 2: Issue Analysis & Pattern Recognition
- Identify issues: List all assets which:
- Do not have alt text set (null or empty string)
- Have existing alt text but it's poor quality (too short, redundant phrases, etc.)
- Do not have SEO-friendly asset names
- Are duplicates or very similar
- Pattern detection report: Show detected patterns:
🔍 Detected patterns: - 15 assets start with "IMG_" (camera uploads) - 8 assets contain "screenshot" - Suggest: Bulk rename these patterns - Ask user preference: Ask if they want to generate:
- Alt text only
- SEO-friendly names only
- Both
- Apply naming pattern/template
Phase 3: Analysis & Suggestion Generation
- Analyze assets: Use Webflow MCP's
get_asset_previewtool, passing each asset'sasset_id(from Phase 1), to analyze the assets that need updates- Error handling: If Webflow MCP's
get_asset_previewfails, use fallback:- Extract description from existing filename
- Use generic placeholder with warning
- Continue with other assets
- Process in batches to avoid timeout
- Error handling: If Webflow MCP's
- Generate suggestions with validation:
- Alt text validation:
- Max 125 characters (warn if longer)
- No redundant phrases ("image of", "picture of", "photo of")
- Must end with punctuation
- Flag generic descriptions (confidence < 50%)
- SEO name validation:
- Only lowercase a-z, 0-9, hyphens
- No double extensions (.webp.webp) - strip existing extension first
- Max 100 characters
- Replace spaces/underscores with hyphens
- No special characters
- Alt text validation:
- Folder organization suggestions: If patterns detected, suggest folder structure:
💡 Organization suggestions: - Create "team-photos" folder for 8 team images - Create "product-images" folder for 15 product shots
Phase 4: Granular Approval & Application
- Present suggestions with granular approval:
- Show numbered list with checkboxes
- Allow individual toggle: "Enter numbers to skip (e.g., '2,4')"
- Options: "all", "none", or specific numbers
- Show validation warnings for each suggestion
- Offer naming template (if many similar assets):
🎨 Apply naming pattern? 1. [category]-[description] (e.g., team-john-headshot) 2. [description]-[location] (e.g., office-workspace-desk) 3. Custom pattern... 4. Skip patterns, use individual names - Store rollback data: Before applying changes, store:
- Original asset names
- Original alt text
- Timestamp
- Assets modified
- Apply updates: Use Webflow MCP's
data_assets_toolto update approved assets only- Show progress for batch updates
- Handle partial failures gracefully
- Report successes and failures separately
- Offer rollback option: After changes applied:
📋 Rollback Available: Last update: 4 assets modified 2 minutes ago Type "undo" to revert these changes
Examples
User prompt:
Run an asset audit on my site.
Step 1: Initial Audit Report
📊 SEO Asset Audit: MCP Demo #2
Total: 4 assets
🔍 Detected patterns:
- 4 assets have generic numeric names (1.webp, 2.webp, 3.webp, 4.webp)
- All assets are in WebP format ✓
⚠️ Missing Alt Text (4 assets):
├── 1.webp (empty alt text)
├── 2.webp (empty alt text)
├── 3.webp (empty alt text)
└── 4.webp (empty alt text)
⚠️ Non-SEO-Friendly Names (4 assets):
├── 1.webp (generic numeric name)
├── 2.webp (generic numeric name)
├── 3.webp (generic numeric name)
└── 4.webp (generic numeric name)
---
What would you like to generate?
1. Alt text only
2. SEO-friendly names only
3. Both alt text and SEO-friendly names
Please select an option (1, 2, or 3).
Example with Validation Warnings:
📋 Suggested Improvements:
[1] ✓ IMG_1234.jpg
Alt text: "Professional team member headshot with blue background."
New name: professional-team-member-headshot.jpg
✅ Validation passed
[2] ✓ screenshot-2024.png
Alt text: "Dashboard analytics overview showing user engagement metrics."
New name: dashboard-analytics-overview.png
✅ Validation passed
[3] ⚠️ untitled-image.webp
Alt text: "Photo"
⚠️ Warning: Alt text too short (< 10 chars) - needs more detail
New name: untitled-image.webp
⚠️ Warning: Unable to generate better name (image preview failed)
[4] ⚠️ TeamPhoto2024!!!.jpg
Alt text: "Image of a person working on laptop in modern office with plants and natural lighting through large windows in the background."
⚠️ Warning: Alt text too long (137 chars) - consider shortening for screen readers
New name: team-photo-2024.jpg
✅ Validation passed (special characters removed)
Which assets would you like to update?
Step 2: After user selects option 3 and images are analyzed
📋 Suggested Improvements:
[1] ✓ 1.webp
Alt text: "Podcast host with headphones and microphone recording Webflow podcast episode in studio."
New name: webflow-podcast-host-recording-studio.webp
✅ Validation passed
[2] ✓ 2.webp
Alt text: "Professional developer wearing glasses working on laptop with Webflow logo in modern office."
New name: developer-working-laptop-webflow-office.webp
✅ Validation passed
[3] ✓ 3.webp
Alt text: "Webflow homepage hero section with tagline and email signup form."
New name: webflow-homepage-hero-section.webp
✅ Validation passed
[4] ✓ 4.webp
Alt text: "Speaker presenting on stage at Webflow Conf with audience watching."
New name: webflow-conf-speaker-presentation-stage.webp
✅ Validation passed
---
Which assets would you like to update?
- Type numbers to skip (e.g., "2,4" to skip items 2 and 4)
- Type "all" to proceed with all
- Type "none" to cancel
Step 3: After user confirms with "all"
🔄 Applying updates...
Progress: ████████████████████ 100% (4/4 assets)
✅ Updates Applied Successfully!
SEO Asset Audit Complete: MCP Demo #2
Summary:
- ✅ 4 assets updated successfully
- ❌ 0 assets failed
- ⏭️ 0 assets skipped
Changes Applied:
┌─────────────────────────────────────────────────────────────────┐
│ [1] webflow-podcast-host-recording-studio.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
├─────────────────────────────────────────────────────────────────┤
│ [2] developer-working-laptop-webflow-office.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
├─────────────────────────────────────────────────────────────────┤
│ [3] webflow-homepage-hero-section.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
├─────────────────────────────────────────────────────────────────┤
│ [4] webflow-conf-speaker-presentation-stage.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
└─────────────────────────────────────────────────────────────────┘
📋 Rollback Available:
Last update: 4 assets modified just now
Type "undo" to revert these changes
---
🎉 Your site's assets are now fully optimized for SEO and accessibility!
Alternative Step 3: User selects specific assets (e.g., "1,3")
🔄 Applying updates to assets 1 and 3...
Progress: ████████████████████ 100% (2/2 assets)
✅ Partial Update Complete!
Summary:
- ✅ 2 assets updated successfully
- ❌ 0 assets failed
- ⏭️ 2 assets skipped (as requested)
Changes Applied:
┌─────────────────────────────────────────────────────────────────┐
│ [1] webflow-podcast-host-recording-studio.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
├─────────────────────────────────────────────────────────────────┤
│ [3] webflow-homepage-hero-section.webp │
│ ✓ Alt text added │
│ ✓ Filename updated │
└─────────────────────────────────────────────────────────────────┘
Skipped Assets (can run audit again later):
- [2] 2.webp
- [4] 4.webp
📋 Rollback Available:
Type "undo" to revert these 2 changes
Guidelines
Phase 1: Critical Validations (Must Follow)
File Extension Handling:
- ALWAYS strip existing extension before adding new one
- Bad:
image.webp→new-name.webp.webp - Good:
image.webp→new-name.webp - Implementation: Use filename without extension + new extension
Alt Text Quality Rules:
- Max length: 125 characters (accessibility best practice)
- Must end with punctuation (period, exclamation, question mark)
- Remove redundant phrases:
- ❌ "Image of a person" → ✅ "Person working at desk"
- ❌ "Picture of logo" → ✅ "Company logo on blue background"
- ❌ "Photo showing" → ✅ Direct description
- Flag if too short (< 10 chars): ⚠️ "Too generic - needs more detail"
- Flag if too long (> 125 chars): ⚠️ "Consider shortening for screen readers"
SEO Filename Rules:
- Only allow: lowercase a-z, numbers 0-9, hyphens
- Max length: 100 characters (before extension)
- Convert spaces to hyphens:
team photo→team-photo - Convert underscores to hyphens:
team_photo→team-photo - Remove special characters:
photo!@#$→photo - Convert to lowercase:
TeamPhoto→team-photo - Remove consecutive hyphens:
team--photo→team-photo - Trim leading/trailing hyphens:
-photo-→photo
Phase 2: Batch Processing & Performance
Large Site Handling:
- Sites with 50+ assets: Process in batches of 20
- Show progress: "Processing batch 1 of 5 (assets 1-20)..."
- Allow user to process specific batches
- Timeout protection: If Webflow MCP's
get_asset_previewtakes > 30s, skip to next batch
Pattern Detection: Detect and report these patterns:
- Camera uploads:
IMG_,DSC_,DCIM_,P_ - Screenshots:
screenshot,Screen Shot,Capture - Generic names:
untitled,image-1,photo,asset - Date formats:
2024-01-10,20240110,01-10-2024 - Suggest bulk rename when 3+ assets match a pattern
Error Handling:
- If Webflow MCP's
get_asset_previewfails:- Log the error (don't show to user)
- Use fallback: Extract description from filename
- Mark with ⚠️ warning: "Generated from filename (image preview failed)"
- Continue with other assets
- Partial success handling:
- Report successes separately from failures
- Show: "✅ 15 updated, ❌ 2 failed, ⏭️ 3 skipped"
- Offer to retry failed assets
Phase 3: Advanced Features
Granular Approval System:
- Number each suggestion:
[1],[2],[3], etc. - Show checkmark status:
✓or✗ - Accept multiple formats:
- "all" - approve all
- "none" - cancel operation
- "1,3,5" - skip items 1, 3, and 5
- "2-5" - skip items 2 through 5
- Always show validation status per item
Naming Templates: Offer templates when 5+ similar assets detected:
[category]-[description]-[modifier]- Example:
product-laptop-front-view.jpg
- Example:
[description]-[location]-[year]- Example:
team-photo-office-2024.jpg
- Example:
[type]-[name]-[variant]- Example:
icon-arrow-blue.svg
- Example:
Folder Organization: Suggest folders when detecting:
- 5+ images with "team", "staff", "employee" →
team-photosfolder - 5+ images with "product", "item" →
product-imagesfolder - 5+ images with "logo", "brand" →
brandingfolder - 5+ images with "screenshot", "capture" →
screenshotsfolder
Rollback System: Before any update, store in memory:
{
"timestamp": "2026-01-10T00:45:00Z",
"assets": [
{
"id": "asset-id",
"originalName": "1.webp",
"originalAltText": "",
"newName": "podcast-host.webp",
"newAltText": "Podcast host recording..."
}
]
}
- Offer undo for 5 minutes after changes
- Clear rollback data after next audit starts
- Show rollback option in final summary
Duplicate Detection:
- Compare asset sizes (exact match = likely duplicate)
- Compare filenames (similar names = potential duplicate)
- Report: "⚠️ Potential duplicates: asset1.jpg (2.4MB) and asset1-copy.jpg (2.4MB)"
- Don't auto-delete - let user decide
General Best Practices
- Always use Webflow MCP's
get_asset_preview(withasset_id, not a URL) to understand image content - Generate specific, descriptive suggestions (not generic)
- Validate all suggestions before presenting to user
- Handle partial operations gracefully
- Provide clear progress indicators for long operations
- Group similar issues together in reports
- Use visual indicators: ✅ ⚠️ ❌ 🔍 💡 📋 🎉
- Be conversational but concise
- Always offer rollback after changes
Bulk CMS Update
Create or update multiple CMS items with comprehensive validation, granular approval, and rollback capability.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
data_sites_toolwith actionlist_sitesfor listing available sites - Use Webflow MCP's
data_cms_toolwith actionget_collection_listfor listing CMS collections - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsfor fetching collection schemas - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsfor retrieving existing items - Use Webflow MCP's
data_cms_toolwith actioncreate_collection_itemsfor creating items (draft or published) - Use Webflow MCP's
data_cms_toolwith actionupdate_collection_itemsfor updating items (draft or published) - Use Webflow MCP's
data_cms_toolwith actionpublish_collection_itemsfor publishing draft items - Use Webflow MCP's
webflow_guide_toolto get best practices before starting - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Site & Collection Selection
- Get site: Identify the target site. If user does not provide site ID, ask for it.
- List collections: Use Webflow MCP's
data_cms_toolwith actionget_collection_listto show available collections - Ask user to select collection: User specifies which collection to work with
- Fetch collection schema: Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto retrieve:- All field definitions with types
- Required vs optional fields
- Field validations (max length, patterns, etc.)
- Reference field targets
Phase 2: Data Collection & Parsing
-
Ask operation type: Clarify what user wants to do:
- Create new items only
- Update existing items only
- Both create and update
-
Receive data from user: Accept data in flexible formats:
- Structured format (JSON-like)
- Natural language descriptions
- CSV-style data
- Bullet lists
-
Parse and normalize: Convert user data into structured format
-
Fetch existing items (if updates involved): Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsto get current dataIMPORTANT - Efficient Item Lookup:
- When searching for specific items by name, ALWAYS use the
nameparameter to filter (e.g.,name: "Pikachu") - When searching by slug, use the
slugparameter to filter - NEVER fetch all items first and then search through the results - this wastes API calls and tokens
- Only fetch the full list when you need to display all items or don't know which specific items to target
- When searching for specific items by name, ALWAYS use the
Phase 3: Validation & Analysis
- Validate all data:
- Field names: Check all field names exist in schema
- Required fields: Ensure all required fields are provided
- Field types: Validate data types match schema
- Constraints: Check max lengths, patterns, allowed values
- Slugs: Ensure slugs are unique and valid
- Reference fields: Verify referenced items exist
- Detect conflicts:
- Duplicate slugs (within batch or with existing items)
- Missing required fields
- Invalid data types
- Constraint violations
- Analyze impact:
- Count creates vs updates
- Identify which fields will change
- Calculate batch size and processing time
Phase 4: Preview & Granular Approval
- Generate detailed preview:
- Show each item with validation status
- Display warnings for any issues
- For updates, show diffs (old → new)
- For creates, show all field values
- Number each item for selective approval
- Present granular approval options:
- Allow user to select specific items to process
- Options: "all", "none", specific numbers, number ranges
- Show estimated processing time
- Offer publish options:
- Publish immediately (use
*_liveendpoints) - Create as drafts (use regular endpoints + manual publish)
- Publish immediately (use
Phase 5: Execution & Reporting
- Store rollback data: Before any changes, save:
- Original values for all updated items
- Timestamp
- Operation details
- Process in batches:
- Maximum 50 items per batch
- Show progress indicator
- Handle rate limits gracefully
- Execute operations: Use appropriate Webflow MCP tools based on user choice
- Handle errors gracefully:
- Continue processing on single item failures
- Track successes and failures separately
- Provide detailed error messages
- Generate comprehensive report:
- Summary (success/failure counts)
- Detailed results per item
- Item IDs for created/updated items
- Error details for failed items
- Offer rollback option: Allow user to undo changes if needed
Examples
User prompt:
Add 2 blog posts about Webflow MCP and update the first blog to say "Top" instead of "Best"
Step 1: Site & Collection Selection
📋 Bulk CMS Update Setup
Available Sites:
1. MCP Demo#1
2. MCP Demo#2
3. MCP Demo#3
Please select a site (1-3):
User selects: 1
Available Collections in MCP Demo#1:
└── Blog Posts (9 items)
Fields: name, slug, post-body, post-summary, main-image, thumbnail-image, featured, color
Proceed with Blog Posts collection? (yes/no)
User confirms: yes
Step 2: Data Collection
🔍 Collection Schema: Blog Posts
Required Fields:
- name (PlainText, max 256 chars)
- slug (PlainText, max 256 chars, alphanumeric only)
Optional Fields:
- post-body (RichText)
- post-summary (PlainText)
- main-image (Image)
- thumbnail-image (Image)
- featured (Switch, true/false)
- color (Color, hex format)
I'll parse your request:
- Create 2 new posts about Webflow MCP
- Update first post: "Best" → "Top"
Generating items...
Step 3: Validation & Preview
📋 Preview: Bulk CMS Update
Collection: Blog Posts
Operations: Create 2 items + Update 1 item
---
### 🆕 Items to Create (2)
[1] ✓ NEW POST
name: "Webflow MCP: The Future of Web Development"
slug: "webflow-mcp-future-web-development"
post-summary: "Discover how Webflow MCP is revolutionizing..."
post-body: "<h1>The Future is Here</h1><p>..."
featured: true
color: "#9B59B6"
✅ All validations passed
[2] ✓ NEW POST
name: "Why Webflow MCP Will Transform Your Workflow in 2026"
slug: "webflow-mcp-transform-workflow-2026"
post-summary: "Learn how Webflow MCP's integration..."
post-body: "<h1>Transform Your Workflow</h1><p>..."
featured: true
color: "#3498DB"
✅ All validations passed
---
### ✏️ Items to Update (1)
[3] ✓ UPDATE EXISTING
Item ID: 69615f84fc6ce1aa444d24d5
Slug: why-webflow-is-best-2026-ai
Changes:
name: "Why Webflow is the Best Choice for 2026" → "Why Webflow is the Top Choice for 2026"
✅ All validations passed
---
**Summary:**
- ✅ 2 items will be created
- ✅ 1 item will be updated
- ⚠️ 0 warnings
- ❌ 0 errors
**Publish Options:**
1. Publish immediately (recommended)
2. Save as drafts
Which items would you like to process?
- Type "all" to process all 3 items
- Type numbers to skip (e.g., "2" to skip item 2)
- Type "none" to cancel
Select publish option (1/2): _
Select items: _
User selects: 1, all
⚠️ You're about to:
- Create 2 new blog posts (published live)
- Update 1 existing blog post (changes published live)
Type "confirm" to proceed.
User confirms: confirm
Step 4: Execution & Results
🔄 Processing bulk update...
Creating items: ██████████ 100% (2/2)
Updating items: ██████████ 100% (1/1)
✅ Bulk CMS Update Complete!
---
### 🆕 Created Items (2)
✓ [1] "Webflow MCP: The Future of Web Development"
ID: 6961640c66de07bed9aacf3e
Slug: webflow-mcp-future-web-development
Published: Jan 9, 2026, 8:24 PM
✓ [2] "Why Webflow MCP Will Transform Your Workflow in 2026"
ID: 6961640c66de07bed9aacf41
Slug: webflow-mcp-transform-workflow-2026
Published: Jan 9, 2026, 8:24 PM
---
### ✏️ Updated Items (1)
✓ [3] "Why Webflow is the Top Choice for 2026"
ID: 69615f84fc6ce1aa444d24d5
Changed: title updated
Published: Jan 9, 2026, 8:24 PM
---
**Summary:**
- ✅ 2 items created successfully
- ✅ 1 item updated successfully
- ❌ 0 failures
- ⏱️ Completed in 3.2 seconds
**Total Items:** 11 (was 9)
📋 Rollback Available:
Last update: 3 items modified just now
Type "undo" within 5 minutes to revert all changes
Alternative: With Validation Warnings
📋 Preview: Bulk CMS Update
[1] ⚠️ NEW POST
name: "Test Post"
slug: "test"
post-summary: "Hi"
⚠️ Warning: post-summary too short (< 20 chars) - may affect SEO
⚠️ Warning: slug too generic - consider more descriptive slug
⚠️ Warning: missing post-body - content will be empty
✅ Required fields present (can proceed)
[2] ❌ NEW POST
name: "Another Post!!!"
slug: "another post"
❌ Error: slug contains spaces (must be alphanumeric with hyphens only)
❌ Error: name contains special characters not allowed
🔴 Cannot proceed - fix errors first
---
**Summary:**
- ✅ 1 item can be created (with warnings)
- ❌ 1 item has errors (cannot create)
Fix item 2 or skip it? (fix/skip)
Guidelines
Phase 1: Critical Requirements
Site & Collection Selection:
- Always fetch actual site list using
data_sites_toolwith actionlist_sites - Never assume site IDs
- Show collection names and item counts
- Display field schema before accepting data
- Confirm collection selection with user
Phase 2: Data Parsing
Flexible Input Formats: Accept data in multiple formats:
- Structured (JSON-like):
CREATE:
- name: "Post Title"
slug: "post-slug"
featured: true
- Natural Language:
"Add a blog post called 'Getting Started' with slug 'getting-started'"
- CSV-style:
name,slug,featured
"Post 1","post-1",true
"Post 2","post-2",false
- Bullet Lists:
- Post 1: "Title" (slug: title-slug)
- Post 2: "Another" (slug: another-slug)
Parsing Rules:
- Be lenient with format variations
- Infer missing optional fields
- Ask for clarification if ambiguous
- Never assume required field values
Efficient Item Lookup: When fetching existing items for updates, use filter parameters to minimize API calls:
# Good - Filter by name when you know the item name
data_cms_tool(action: "list_collection_items", collection_id, name: "Pikachu")
# Good - Filter by slug when you know the slug
data_cms_tool(action: "list_collection_items", collection_id, slug: "pikachu")
# Bad - Fetching all items then searching through results
data_cms_tool(action: "list_collection_items", collection_id) # Returns 100 items
# Then manually searching for "Pikachu" in results...
- ALWAYS use
nameorslugparameters when searching for specific items - This reduces API calls, response size, and token usage
- Only fetch unfiltered lists when displaying all items or when the target is unknown
Phase 3: Validation Rules
Field Name Validation:
- Check all field names exist in schema
- Case-sensitive matching
- Suggest corrections for typos
- Example: "autor" → Did you mean "author"?
Required Fields:
nameandslugare ALWAYS required for Webflow CMS- Check collection-specific required fields from schema
- List all missing required fields clearly
- Cannot proceed if required fields missing
Field Type Validation:
PlainText:
- Check max length constraints
- Validate patterns if specified
- No HTML allowed
RichText:
- Must be valid HTML
- Check for unclosed tags
- Allow common HTML elements
Image/File:
- Accept file IDs or URLs
- Validate file exists (if possible)
- Optional alt text
Switch (Boolean):
- Accept: true/false, yes/no, 1/0
- Normalize to boolean
Color:
- Must be hex format (#RRGGBB)
- Validate hex characters
- Example: #FF5733 ✓, red ✗
Reference Fields:
- Must reference existing item IDs
- Validate referenced items exist
- Show referenced item names for clarity
Slug Validation:
- CRITICAL: Must be alphanumeric with hyphens only
- No spaces, underscores, or special characters
- Max 256 characters
- Must be unique (check against existing + batch)
- Auto-suggest slugs from titles if missing
- Example:
- ❌ "My Post!" → ⚠️ Contains special characters
- ✅ "my-post" → Valid
Constraint Validation:
- Max length: Warn if approaching limit, error if exceeds
- Patterns: Test regex patterns from schema
- Allowed values: Check against enumerated options
Phase 4: Preview & Approval
Preview Format:
For Create Operations:
[1] ✓ NEW POST
field1: "value1"
field2: "value2"
field3: "value3"
✅ All validations passed
For Update Operations:
[2] ✓ UPDATE EXISTING
Item ID: xxx
Slug: existing-slug
Changes:
field1: "old value" → "new value"
field2: (no change)
field3: "old" → "new"
✅ All validations passed
For Items with Warnings:
[3] ⚠️ NEW POST
name: "Title"
⚠️ Warning: Missing optional field 'post-body'
⚠️ Warning: Slug may be too generic
✅ Can proceed (warnings only)
For Items with Errors:
[4] ❌ NEW POST
name: "Title!!!"
slug: "bad slug"
❌ Error: slug contains spaces
❌ Error: name has special characters
🔴 Cannot proceed - must fix errors
Granular Approval:
- Number each item: [1], [2], [3]...
- Allow selective processing
- Accept formats:
- "all" - process everything
- "none" - cancel operation
- "1,3,5" - process items 1, 3, and 5
- "1-5" - process items 1 through 5
- "2" - skip only item 2, process rest
Publish Options:
- Immediate publish: Use
*_liveendpoints (recommended) - Draft mode: Use regular endpoints, publish later
- Explain implications of each choice
Phase 5: Execution & Reporting
Batch Processing:
- Maximum 50 items per batch
- Show progress bar:
Processing: ████████░░ 80% (40/50 items) - Estimated time remaining
- Handle rate limits (pause/retry)
Error Handling:
For Single Item Failures:
Processing item 3/10...
❌ Failed: "Post Title"
Error: Slug already exists
→ Skipping to next item
Continue Processing:
- Don't fail entire batch for one error
- Track all successes and failures
- Report both separately
For Critical Failures:
❌ Critical Error: API connection lost
Items processed before error: 7/50
- 5 created successfully
- 2 updated successfully
- 43 not processed
Retry failed items? (yes/no)
Success Report Format:
✅ Operation Complete
Created: 25 items
- Show first 5 with IDs
- "[+20 more]" if > 5
Updated: 10 items
- Show first 5 with IDs
- "[+5 more]" if > 5
Failed: 2 items
- "Item Name": Error reason
- "Item Name": Error reason
Total time: 12.5 seconds
Items per second: 2.8
Rollback Capability:
Store Before Changes:
{
"timestamp": "2026-01-09T20:24:44Z",
"operations": [
{
"type": "update",
"itemId": "xxx",
"originalValues": {
"name": "Old Title",
"featured": false
},
"newValues": {
"name": "New Title",
"featured": true
}
}
]
}
Offer Rollback:
📋 Rollback Available:
Last update: 15 items modified 2 minutes ago
Rollback will:
- Restore 10 updated items to previous values
- Delete 5 newly created items
⚠️ Type "undo" to rollback all changes
⚠️ Rollback expires in 3 minutes
Performance Optimization
Batch Size:
- Default: 50 items per batch
- Adjust based on field complexity
- Heavy images: 20 items per batch
- Simple text fields: 100 items per batch
Progress Indicators:
Creating items...
Batch 1/3: ████████████████████ 100% (50/50)
Batch 2/3: ████████████████████ 100% (50/50)
Batch 3/3: ██████░░░░░░░░░░░░░░ 30% (15/50)
Rate Limiting:
- Respect Webflow API rate limits
- Pause between batches if needed
- Show user why waiting
- Retry failed requests automatically (max 3 attempts)
Error Messages
Clear and Actionable:
❌ Bad:
"Error: validation failed"
✅ Good:
"Validation Error on item 3:
- Slug 'my post' contains spaces
- Change to: 'my-post' (alphanumeric with hyphens only)"
Error Categories:
- 🔴 Critical: Cannot proceed at all (API down, invalid auth)
- ❌ Error: This item cannot be processed (fix or skip)
- ⚠️ Warning: Can proceed but not recommended (missing optional fields)
- 💡 Suggestion: Best practices (slug too generic, summary too short)
Best Practices
Always:
- ✅ Show preview before any changes
- ✅ Require explicit confirmation
- ✅ Validate all data thoroughly
- ✅ Process in batches for large operations
- ✅ Report successes and failures separately
- ✅ Offer rollback for recent changes
- ✅ Use granular approval for flexibility
Never:
- ❌ Apply changes without user confirmation
- ❌ Fail entire batch for single item error
- ❌ Assume field names or values
- ❌ Process without validating first
- ❌ Hide validation warnings from user
Edge Cases:
- Duplicate slugs: Auto-append number (post-title-2)
- Missing optional fields: Leave empty (don't invent values)
- Large batches: Warn about processing time
- Reference fields: Validate targets exist
- Image fields: Accept URLs or file IDs
User Experience:
- Show collection schema upfront
- Number items for easy reference
- Use visual hierarchy (├── └──)
- Provide actionable error messages
- Estimate processing time
- Allow cancellation mid-process
Webflow Cloud Apps
Use data_apps_tool to create GitHub-source apps, answer operational questions,
and manage environments for Webflow Cloud apps. Start from the user's outcome,
gather only the evidence needed, and distinguish observations from conclusions.
Use the webflow-cli:cloud skill when the task requires CLI/local-source app
creation or deployment, or creating or updating environment variables.
Client-side build output is not sent to Webflow and cannot be recovered through
MCP.
Instructions
1. Establish scope
Use the Webflow MCP connection established by the user's request or existing task context. If only one connection is active, use it without asking the user to choose or reconfirm a region. If multiple connections are active and the intended target remains ambiguous, ask the user to disambiguate before proceeding with target-dependent operations. Do not switch regions to recover from missing resources or access errors.
Before handing an existing MCP app or environment to the CLI for configuration writes or deployment, compare their configured regions. If they differ, do not assume either is correct or silently retarget either tool. Resolve the intended target from explicit task context; if that does not resolve the conflict, ask the user. Pause dependent mutations until the conflict is resolved.
Once the intended region is established, verify that the CLI can read the exact MCP app and environment IDs, and carry that region and those IDs explicitly into subsequent mutations. Login status or a region label alone is insufficient. If verification fails, report the failure without inferring its cause and pause dependent mutations. Continue independent work whose target is established.
- Call
webflow_guide_toolbefore any other Webflow MCP tool. The live guide and action schemas are authoritative for current arguments and responses. - Use Webflow MCP tools for Webflow operations except the explicit CLI handoff for environment-variable values. Never call Webflow APIs directly.
- Include the required
contextparameter in every tool call. Write 15-25 words in third-person perspective. - Route by the capability the task requires:
- Use
data_apps_toolto create GitHub-source apps; inspect apps, environments, domains, deployment records, logs, and variable metadata; manage GitHub sources and environments; and enqueue GitHub deployments. - Use
data_variable_toolfor Designer color, size, font, and CSS variables. - Use
webflow-cli:cloudfor CLI/local-source apps, local builds and deployments, or creating and updating environment-variable values.
- Use
- If
data_apps_toolis unavailable, report that the Cloud Apps MCP capability is not enabled. Do not bypass it with a direct API request.
Never ask the user to paste an environment-variable value or secret into chat.
For a create or update, delegate to webflow-cli:cloud and require a hidden
prompt, stdin, or protected file. Never pass a secret as a positional argument.
2. Resolve the target
Discover identifiers in this order:
list_apps -> app_id
list_environments(app_id) -> env_id
list_deployments(app_id, env_id) -> deployment_id
Use list_deployments to discover existing deployments, including a retry or
rollback source. For a deployment queued by trigger_deployment or redeploy,
use the returned deploymentId directly as get_deployment's deployment_id.
App names are unique only within a site, so resolve a named app with
site_id + name. If multiple resources match, present distinguishing metadata
and require the user to select one before any mutation. Use the live guide for
filter, pagination, cursor, and action-batching mechanics.
Environment mount rules
Before create_environment or a mount-changing update_environment, call
get_app and use siteAttached: standalone apps (false) allow / or a
non-root mount; site-attached apps (true) require a non-root mount. Do not
infer attachment from siteId.
Branches must be unique within the app; mounts must be unique across the site,
including sibling apps. This app's environment list alone cannot rule out a
mount conflict with a sibling app. While / is occupied, another environment
needs a different mount. Keeping an environment's existing mount is a no-op,
not a conflict.
3. Follow the matching user story
Create a GitHub-source app
- Establish the app name, canonical GitHub repository URL, branch, optional description, and whether it is standalone or attached to an existing site.
- For a site-attached app, resolve the site ID. Omit
site_idfor standalone. - Apply the mount contract before previewing:
- Standalone
create_appprovisions its initial environment at/; omitmountor use/. - A site-attached app defaults to
/app, rejects/, and requires a valid non-root mount when overriding the default.
- Standalone
- Explain that standalone creation requires a workspace-scoped user token. Webflow derives the GitHub installation and validates repository access; do not request an installation ID.
- Call
create_appwith its default dry run. Show the repository, branch, attachment, site when applicable, mount, and initial-deployment attempt. - Require
confirm. Immediately after confirmation and before execution, record the start time and generate one stableidempotency_key; execute withdry_run: false, then record the completion time. Reuse that key only for exact retries of this creation. - Treat creation and initial deployment as separate outcomes. A returned app
means creation succeeded even if
deployStatusisskippedorfailed. Fortriggered, inspect the environment and deployment; forskipped, check the branch or push a commit; forfailed, preserve the app and inspect or retry deployment separately. - If the app or outcome is unreadable, reconcile before retrying:
- For a site-attached app, collect candidates with
site_id + name; for a standalone app, collect candidates by name. - In both cases, compare each candidate's name,
sourceUrl, andcreatedAtwith the requested repository and recorded execution window. - Continue to environments and deployments only when exactly one candidate matches. Do not retry while the created app remains ambiguous.
- For a site-attached app, collect candidates with
- Never delete a created app automatically because deployment failed. Do not treat an initial deployment dashboard link as the environment's public URL.
Which app and environment am I looking at?
- Use
list_appsto find the app andget_appfor its metadata, includingsourceUrlandsiteAttached. - Use
list_environmentsto report the branch, mount,publicUrl, and latest deployment status. IfpublicUrlis null, report that no user-facing environment address is available; do not construct one. - Use
get_app_domainswhen the user asks where the app is reachable. - Explain that custom-domain results exclude the default
*.webflow.iohostname. Domains for an app attached to a regular Webflow site may belong to the parent site and be shared by sibling apps.
What is deployed, and is it healthy?
- Use
list_environmentsfor the environment's latest deployment status. - Use
list_deployments, newest first, thenget_deploymentfor the selected deployment's detailed timeline and version metadata. - Treat
starting,building, anddeployingas active states. Report any other status exactly rather than guessing its meaning. - A failed phase sets
buildFailedAtordeployFailedAtwhile its matching finished timestamp remains null. A null finished timestamp by itself does not prove the phase is still running. - Report what is observable: selected app and environment, deployment status, version or commit metadata if returned, phase timestamps, and evidence gaps.
Why did the deployment fail?
- Fetch the deployment with
get_deploymentand identify the failed phase from its status and timestamps. - Call
get_build_logsonly whenlogsAvailableis true. Start with a narrowsincewindow orqfilter, then broaden only if needed. - Page until
nextCursoris null when a complete result is required. - Treat
logsAvailableas a retention and retrieval signal, not proof that every phase produced log entries. - Treat an empty result as "no matching retrievable server-side logs," not as proof that the build succeeded or produced no errors.
- Build output produced on a user's machine is outside MCP. Mention this only when the user says the deployment was built with the CLI; direct them to the originating CLI output for local build failures.
- Report the failed phase, relevant timestamps, the smallest useful evidence, the inferred cause, and any uncertainty. Do not merely restate raw logs.
Why is the running app failing?
- Resolve the exact environment and call
get_runtime_logs. - Narrow by
sinceandqbefore retrieving a broad window. Page completely when the conclusion depends on absence. - Runtime logs may be unavailable because of retention. Treat an empty result as no retrievable logs and report the limitation.
- Correlate runtime evidence with the latest deployment record when useful, but do not claim causation from timing alone.
- Report the observed error pattern, affected interval, likely cause, evidence, and limitations.
Is required configuration present?
- Establish the required key set from an authoritative source: a user-provided key list, a project configuration schema or documented requirement, or a reference environment the user explicitly designates as complete.
- If the source is a protected file containing values, run deterministic key-only extraction locally and emit only key names. Never open the source through a model-visible read or include its values in chat or tool output.
- Obtain an authoritative secrecy designation for every required key from the
user, a project schema or documented requirement, or a reference environment
explicitly designated as authoritative for secrecy. An
.envfile or plain key list establishes names only; never infer secrecy from key names. - Resolve the environment, call
list_variables, and compare its keys and secrecy metadata with the established requirements. It proves what is configured, not what is required. Exhaust pagination before concluding that a key is missing. - Report keys and metadata only. Secret entries have
isSecret: trueand no value; a missing secret value is expected. - If the required set or any secrecy designation is unresolved, stop before a CLI mutation or dependent deployment unless the user explicitly establishes that no configuration is required.
- For missing or misclassified keys, route to
webflow-cli:cloudwithout requesting values in chat. After the write, verify required keys and secrecy withlist_variables. If it partially fails, report failed keys without values and stop before deployment; preserve successful keys and the environment.
Why is this environment serving the wrong branch or route?
- Resolve the exact environment and report its current branch, mount,
publicUrl, and latest deployment status. Report a nullpublicUrlwithout constructing an address. - Compare the current branch and mount with the user's intended mapping. If the request is only diagnostic, stop after reporting the mismatch.
- If the correction changes the mount, apply the environment mount rules above.
- For a correction, show the exact before-and-after mapping. Explain that
update_environmentis immediate, has no dry run, and does not deploy code. - Require
confirm, callupdate_environmentonce, and report the returned environment,publicUrl, andmountRefreshStatus. - For an unreadable or uncertain result, locate the original
env_id. If using the expected new branch as a filter, accept a returned environment only when its ID equals that originalenv_id, then compare its branch and mount with the requested values. A different ID or no uniquely matched original target is ambiguous: do not continue or retry. Never reuse the old branch filter after a branch-changing update. - A failed or unknown mount refresh does not mean the environment update was rolled back. Report routing as uncertain and do not retry solely because the refresh failed.
- If the branch changed and the user wants its code deployed, treat
trigger_deploymentas a separate previewed and confirmed mutation.
Create an isolated environment for a branch and deploy it
- Resolve the existing app and apply the environment mount rules above.
- Page through
list_environmentsto check for an existing branch or mount. - Show the proposed branch and mount. Explain that
create_environmentis immediate, has no dry run, and creates a mapping without deploying code. - Generate one stable
idempotency_key, requireconfirm, and callcreate_environment. Reuse that key only for exact retries. - Report the returned environment,
publicUrl, andmountRefreshStatus. If the result is uncertain, search for the expected branch and compare the environment ID, branch, and mount; use a returned ID to distinguish concurrent creations. Do not retry while the created environment remains ambiguous. - A failed refresh means creation succeeded but routing may be incomplete. Do not retry creation or delete the environment automatically.
- Before deploying this new environment, follow "Is required configuration present?" as a mandatory gate. Continue only after requirements and secrecy are verified, or the user explicitly establishes that none are required. Then use the deployment workflow below for preview, confirmation, attribution, and monitoring.
Can this deployment be retried, rolled back, or rebuilt from branch HEAD?
Use the mutation's default dry run as the capability check. Do not infer eligibility from missing logs, app metadata, or deployment metadata.
For a new deployment from the connected branch or a prior exact commit:
- Resolve the environment. For a retry or rollback, also resolve the exact prior deployment.
- Perform configuration discovery only when the user requests it, deployment evidence indicates missing or misclassified variables, the selected commit has documented configuration requirements, or the server rejects the deployment for configuration reasons. Follow "Is required configuration present?" when one of these conditions applies. If a preview or execution rejection creates the condition, resolve it before retrying. Otherwise add no configuration prerequisite.
- Preview
trigger_deploymentfor branch HEAD orredeployfor a prior commit. If preview rejects the source, make no mutation and route local-source deployment towebflow-cli:cloud. - For
redeploy, explain that the older commit runs with the environment's current configuration, so compatibility is not guaranteed. - Show the returned branch or commit and explain that execution creates a new GitHub build, not a deployment of local files.
- Require
confirm, then execute withdry_run: falseand one stableidempotency_key. Reuse the key only for exact retries of this request. - Interpret the execution result before monitoring:
queued: the response identifies the enqueued deployment withdeploymentId. A completed idempotency replay preserves the original ID; it does not enqueue another deployment.skippedfromtrigger_deployment: the branch has no commit, so no deployment was enqueued. Stop monitoring.processing: an earlier call with this key is already in flight; this call did not enqueue a duplicate and returns no deployment ID. Use the original queued response's ID if available; otherwise report attribution as unresolved.- An unknown or unreadable status leaves the outcome uncertain.
- Poll
get_deploymentwith the selectedapp_id,env_id, and the returneddeploymentIdasdeployment_id. Forredeploy, this is the new deployment's ID, not the source deployment's ID. If no ID is available, report it explicitly and leave attribution unresolved. Do not fall back to polling deployment lists or infer an ID from recency. - Continue polling that exact ID while its status is
starting,building, ordeploying. Stop when it leaves those states or the bounded monitoring period ends. If monitoring ends first, report the deployment ID, last status, and timestamp; do not call it failed or enqueue a replacement for that reason. - For a retry or rollback, preview the prior deployment's exact commit hash and message. A rollback creates a new build at that commit; it does not move the environment branch.
4. Apply shared evidence and safety rules
- Treat build, deploy, and runtime logs as potentially sensitive customer output. Inspect for tokens, credentials, cookies, authorization headers, and presigned URLs before quoting or saving them.
- Quote only the minimum log evidence needed. Redact sensitive values and URLs.
- A request to inspect, diagnose, or preview does not authorize a mutation.
- Require an itemized preview and the exact word
confirmbefore every mutation. - Reconcile an uncertain mutation through observable state before retrying it.
- Reuse an idempotency key only for exact retries of the same logical request.
- Never delete a newly created app or environment automatically when configuration or deployment fails. Report the partial state.
5. Handle explicit administrative requests
These operations are supported but are not the skill's primary workflow.
For update_app:
- Fetch the current app with
get_app. - For a name or description change, prepare and show the exact change. Pass
description: nullto clear a description. - For
source_url, compare the currentsourceUrlwith the requested canonical GitHub repository URL. Explain that the immediate update requires a user-authorized token; machine tokens return403. - Require
confirm, callupdate_apponce, and verify withget_app. An unreadable response requires reconciliation before retrying. - A source update does not change an environment branch or deploy code. Treat those as separate confirmed mutations.
- Renaming a standalone app also attempts to rename its backing site; a sync failure can leave the old site name. Site-attached parent names are unchanged.
For delete_variable:
- Preview with the default dry run.
- If
existsis false, report that nothing was deleted and stop. - If
existsis true, show the app, environment, and key; warn that deletion is permanent and requireconfirm. - Call once with
dry_run: false. Treatdeleted: trueas success. Reconcile an uncertain response with an exact key lookup before retrying.
For delete_environment:
- Preview with the default dry run. Identify the app, environment, branch, and mount, and explain that its worker, KV/D1/R2 storage, deployments, and variables will be permanently removed.
- Explain that deletion is irreversible and is rejected for the app's last
environment. Require
confirm. - Call once with
dry_run: false. Treatdeleted: trueas success. - A failed or null
mountRefreshStatusmeans deletion succeeded but routing cleanup is failed or uncertain. Report it and never retry the delete. - For an uncertain response, page until the original
env_idis found or the listing ends. Do not use a branch filter whose value may have changed.
For delete_app:
- Preview with the default dry run and report
deletionMode. - Explain that
archiveunpublishes the app and removes it from the dashboard, whilehard_deletepermanently deletes the app and all its environments and cannot be undone. - Require
confirm, then call once withdry_run: false. - Treat
deleted: trueas success. Reconcile uncertainty withget_appor the app's exact site-and-name lookup before retrying.
6. Handle errors and report
- Duplicate environment branch or mount: report the conflicting environment; do not silently update or delete it.
- Partial CLI variable write: report failed keys without values and stop before deployment. Do not roll back successful keys or delete the environment.
GITHUB_APP_NOT_INSTALLEDorGITHUB_REPO_NOT_CONNECTED: provide the returnedinstallUrland retry only after the user completes the connection.- An unsupported deployment preview is a capability boundary, not a reason to bypass MCP with a direct API call.
For each final-report field below, include it only when applicable: the selected app; a resolved environment; evidence inspected; observed status; supported cause; limitations; mutations performed; partial state; and, when blocked, the next required user action.
Examples
Create a site-attached GitHub app
User: "Create search-app from https://github.com/acme/search on the
main branch and attach it to my marketing site at /search."
Resolve the site, preview create_app with its site ID and non-root mount, and
use the GitHub-source creation workflow. Report creation separately from the
automatic initial-deployment outcome.
Diagnose a failed deployment
User: "Why did the latest production deployment fail?"
Use the deployment-diagnostics workflow for the latest production deployment. Retrieve logs only when available and report empty results as unavailable evidence, not success.
Correct an environment mapping
User: "Production is serving the preview branch at /app. Point it back to
main at /."
Use the environment-mapping workflow and validate / against siteAttached.
Treat a requested deployment as a separate mutation.
Provision, configure, and deploy a branch environment
User: "Create a /preview environment for feature/search and deploy it.
It needs the variables in .env.preview."
Use the new-environment workflow, then apply its mandatory configuration gate before routing to deployment. Preserve the environment if a later step fails.
Guidelines
- Start from the user's operational question, not the action inventory.
- Prefer observable evidence over assumptions about how an app was built.
- Use mutation previews and returned errors as capability checks.
- Use CLI for local-source apps and deployments, and for variable values.
- Never use
data_apps_toolfor Designer variables. - Never expose secrets from variables, logs, errors, or URLs.
- Never mutate without an exact preview and explicit
confirm. - Never retry an uncertain mutation before reconciling observable state.
- Keep repository, environment, configuration, and deployment changes separate.
- Preserve partial resources unless the user explicitly requests deletion.
CMS Best Practices
Provide expert guidance on Webflow CMS architecture, relationships, optimization, and troubleshooting.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before starting - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify available sites - Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve site details and plan limits - Use Webflow MCP's
data_cms_toolwith actionget_collection_listto analyze existing collections - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto examine collection schemas - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsto assess content volume - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto understand page structure - Use Webflow MCP's
ask_webflow_aifor specific API questions - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Discovery & Analysis
- Identify the request: Determine if user is:
- Planning new CMS structure
- Optimizing existing collections
- Troubleshooting performance issues
- Setting up relationships
- Seeking architecture guidance
- Get site information: Use Webflow MCP's
data_sites_toolwith actionslist_sitesandget_siteto understand plan limits - Analyze existing structure: Use Webflow MCP's
data_cms_toolwith actionsget_collection_listandget_collection_detailsto examine current setup - Assess content volume: Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsto understand scale - Review pages: Use Webflow MCP's
data_pages_toolwith actionlist_pagesto see how content is displayed
Phase 2: Requirements Gathering
- Understand use case: Ask clarifying questions:
- What content needs to be managed?
- Who will update the content?
- How will content be displayed?
- What relationships are needed?
- Expected content volume?
- Identify constraints: Consider plan limits, technical constraints, team skills
- Define success criteria: Performance goals, editorial workflow, scalability needs
Phase 3: Architecture Planning
- Design collection structure: Plan collections, fields, and relationships
- Select field types: Choose appropriate field types for each content element
- Plan relationships: Design one-to-many and many-to-many connections
- Consider taxonomy: Determine categories, tags, and organizational structure
- Plan for scale: Design for growth (pagination, performance, limits)
- Document decisions: Explain tradeoffs and reasoning
Phase 4: Recommendations & Validation
- Generate recommendations: Provide specific, actionable guidance
- Prioritize changes: Organize by impact (quick wins vs. long-term)
- Explain tradeoffs: Help users understand limitations and workarounds
- Validate against best practices: Check against Webflow limitations and patterns
- Provide alternatives: Offer multiple approaches when applicable
- Create implementation roadmap: Break down into phases
Phase 5: Implementation Guidance
- Provide step-by-step instructions: Clear guidance for implementation
- Offer to assist: Suggest using other skills (cms-collection-setup, bulk-cms-update)
- Document structure: Recommend documentation for team reference
- Suggest testing approach: Guide on how to validate changes
- Plan for migration: If refactoring, provide migration strategy
Collection Architecture
When to Use CMS vs Static
Use CMS when:
- Content updates frequently (weekly or more)
- Multiple similar items (blog posts, products, team members, projects)
- Non-technical users need to edit content
- Content needs filtering/sorting on the frontend
- Same content appears on multiple pages (author bios, product features)
- Content follows a consistent structure across items
- You need to dynamically generate pages
Use Static when:
- Content rarely changes (annual updates or less)
- Unique one-off sections (about page hero, homepage special features)
- Complex custom layouts per item that don't follow patterns
- No need for dynamic filtering or search
- Content is highly customized and doesn't share structure
- Performance is critical and content doesn't change
- You need complete design flexibility per section
Hybrid Approach:
- Static pages with CMS-driven sections (e.g., static homepage with CMS testimonials)
- CMS for recent content, static archives for old content
- Static landing pages, CMS for subpages
Field Type Selection
| Content Type | Recommended Field | Notes | Character Limits |
|---|---|---|---|
| Short text | Plain Text | Titles, names, slugs | Max 256 chars |
| Long text (no formatting) | Plain Text (long) | Descriptions, excerpts | Unlimited |
| Formatted content | Rich Text | Blog content, bios, articles | Unlimited |
| Single image | Image | Photos, thumbnails, headers | 4MB max per image |
| Multiple images | Multi-image | Galleries, product photos | Up to 25 images |
| File downloads | File | PDFs, documents, downloads | 4MB max per file |
| Yes/No values | Switch | Featured flags, visibility toggles | Boolean |
| Single choice | Option | Status, type, category | Unlimited options |
| Date/time | Date/Time | Publish dates, events, deadlines | ISO 8601 format |
| Link to one item | Reference | Author → Post, Category → Post | One item |
| Link to multiple items | Multi-reference | Post → Tags, Post → Related Posts | Multiple items |
| External URL | Link | Social links, external resources | Max 2048 chars |
| Numeric values | Number | Prices, ratings, order, counts | Integer or decimal |
| Phone numbers | Phone | Contact numbers | E.164 format |
| Email addresses | Contact emails | Valid email format | |
| Color values | Color | Theme colors, accents, brand colors | Hex format |
| Video embeds | Video | YouTube, Vimeo embeds | Embed URL |
Field Type Decision Tree
Need to store:
├── Text?
│ ├── Short (≤256 chars)? → Plain Text
│ ├── Long + Formatting? → Rich Text
│ └── Long + No Formatting? → Plain Text (long)
├── Media?
│ ├── Single image? → Image
│ ├── Multiple images? → Multi-image
│ ├── Video? → Video
│ └── File download? → File
├── Choice/Selection?
│ ├── Yes/No? → Switch
│ ├── One option? → Option
│ └── Link to item? → Reference/Multi-reference
├── Structured data?
│ ├── Number? → Number
│ ├── Date/Time? → Date/Time
│ ├── Phone? → Phone
│ ├── Email? → Email
│ └── URL? → Link
└── Visual?
└── Color? → Color
Relationship Patterns
One-to-Many (Reference Field)
Example: Posts → Author
Authors Collection:
├── name (Text, required)
├── slug (Text, required)
├── bio (Rich Text)
├── photo (Image)
├── title (Text) - job title
├── email (Email)
└── social-links (Link)
Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── author (Reference → Authors) ← Each post has ONE author
Display: On post page, access author.name, author.photo, author.bio
Filtering: Can filter posts by specific author
Advantages:
- ✅ Centralized author data (update once, reflects everywhere)
- ✅ Easy to maintain consistency
- ✅ Can create author profile pages showing all their posts
- ✅ Efficient (one reference per post)
Use cases:
- Blog posts → Author
- Products → Brand
- Events → Venue
- Projects → Client
- Testimonials → Customer
Many-to-Many (Multi-Reference)
Example: Posts ↔ Tags
Tags Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
└── color (Color) - optional visual grouping
Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── tags (Multi-Reference → Tags) ← Each post has MANY tags
Display: On post page, loop through tags to show all tags
Filtering: Can filter posts by specific tag
Advantages:
- ✅ Flexible content organization
- ✅ Cross-linking related content
- ✅ Better SEO (topic clustering)
- ✅ Enhanced user navigation
Limitations:
- ⚠️ Max 5 multi-reference fields per collection
- ⚠️ Can only filter by ONE multi-reference value at a time in collection lists
- ⚠️ Cannot sort by referenced field values
- ⚠️ Each reference = additional query (impacts performance)
Workarounds for multiple tag filtering:
- Create combined tags (e.g., "vegan-gluten-free")
- Use Finsweet CMS Filter for client-side filtering
- Create separate filtered collection lists for common combinations
- Use custom code with Webflow API
Use cases:
- Blog posts ↔ Tags
- Products ↔ Features
- Projects ↔ Technologies
- Recipes ↔ Ingredients
- Courses ↔ Topics
Self-Reference (Nested Collections)
Example: Categories with subcategories
Categories Collection:
├── name (Text, required)
├── slug (Text, required)
├── description (Plain Text)
├── parent (Reference → Categories) ← Self-reference for hierarchy
└── level (Number) - 1, 2, 3 for display logic
Use cases:
- Categories with subcategories
- Menu items with sub-menu items
- Organizational hierarchy
- Product taxonomy
Advantages:
- ✅ Flexible hierarchy
- ✅ Unlimited depth (theoretically)
- ✅ Easy to reorganize
Limitations:
- ⚠️ Complex to display nested levels in Webflow
- ⚠️ Max 2-3 levels recommended for practical implementation
- ⚠️ Requires custom logic for deep nesting
Alternative: Use Option field for simple 1-2 level categorization
Bidirectional Relationships
Example: Related Posts
Posts Collection:
├── title (Text, required)
├── slug (Text, required)
├── content (Rich Text)
└── related-posts (Multi-Reference → Posts) ← Self-reference to other posts
Display: Show related posts at bottom of post page
Advantages:
- ✅ Keeps users engaged longer
- ✅ Better SEO (internal linking)
- ✅ Flexible content connections
Challenges:
- ⚠️ Not truly bidirectional (A → B doesn't automatically create B → A)
- ⚠️ Must manually maintain both directions if needed
- ⚠️ Can be time-consuming for content editors
Solutions:
- Use tags for automatic "related by tag" logic
- Manual curation for most important connections
- Hybrid: Manual + automated based on tags/category
Examples
Example 1: Planning New CMS Structure
User prompt:
I'm building a recipe site. How should I structure the CMS?
Step 1: Requirements Gathering
📐 CMS Planning: Recipe Site
Let me ask a few questions to design the best structure:
1. **Content Volume**: How many recipes do you plan to have?
- Small (≤50): Simple structure
- Medium (50-200): Moderate organization
- Large (200+): Advanced taxonomy needed
2. **Recipe Attributes**: What information will each recipe have?
- Basic: Name, ingredients, instructions, image
- Advanced: Prep time, cook time, difficulty, nutrition, dietary tags
3. **Organization Needs**: How will users find recipes?
- By meal type (breakfast, lunch, dinner)
- By cuisine (Italian, Mexican, Asian)
- By dietary restrictions (vegan, gluten-free, keto)
- By cooking method (baking, grilling, slow cooker)
- By ingredients (chicken, pasta, vegetables)
4. **Author Setup**: Single or multiple authors?
- Single: You manage all content
- Multiple: Team of recipe creators
5. **User Engagement**: What interactive features?
- Comments/reviews
- Ratings
- Save favorites
- Print recipe cards
Based on your answers, I'll design the optimal CMS architecture.
Step 2: After User Responds
📐 Recommended CMS Architecture: Recipe Site
Based on your requirements (Medium volume, Multiple authors, Advanced filtering):
---
## Collections Needed: 4
### 1. Recipes (Main Content)
├── name (Text, required) - "Homemade Pasta Carbonara"
├── slug (Text, required) - "homemade-pasta-carbonara"
├── description (Plain Text, 160 chars) - Brief summary for SEO
├── featured-image (Image) - Hero image for detail page
├── thumbnail-image (Image) - Smaller image for grid cards
├── prep-time (Number, required) - Minutes of prep
├── cook-time (Number, required) - Minutes of cooking
├── total-time (Number) - Auto-calculated or manual
├── servings (Number, required) - Number of servings
├── difficulty (Option: Easy, Medium, Hard)
├── ingredients (Rich Text, required) - Ingredient list with quantities
├── instructions (Rich Text, required) - Step-by-step directions
├── notes (Rich Text) - Cook's notes, tips, substitutions
├── nutrition-info (Plain Text) - Calories, protein, etc.
├── author (Reference → Authors, required)
├── category (Reference → Categories, required) - Primary meal type
├── cuisine (Reference → Cuisines) - Italian, Mexican, etc.
├── dietary-tags (Multi-Reference → Dietary Tags) - Vegan, GF, etc.
├── cooking-methods (Multi-Reference → Methods) - Baking, Grilling, etc.
├── featured (Switch) - Highlight on homepage
├── published-date (Date, required)
└── view-count (Number) - Track popularity
**Total fields:** 22 fields
**Plan required:** CMS plan minimum (20 collections, 2000 items)
### 2. Authors
├── name (Text, required)
├── slug (Text, required)
├── title (Text) - "Head Chef", "Recipe Developer"
├── bio (Rich Text)
├── photo (Image)
├── specialty (Plain Text) - "Italian Cuisine", "Baking"
├── social-instagram (Link)
├── social-website (Link)
└── email (Email)
**Purpose:** Reusable author information across all recipes
### 3. Categories
├── name (Text, required) - "Breakfast", "Lunch", "Dinner", "Desserts"
├── slug (Text, required)
├── description (Plain Text)
├── image (Image) - Category hero image
├── color (Color) - Brand color for UI
└── sort-order (Number) - Control display order
**Purpose:** Primary meal type classification
**Suggested Categories (8):**
- Breakfast & Brunch
- Appetizers & Snacks
- Lunch
- Dinner & Main Courses
- Side Dishes
- Salads
- Desserts & Sweets
- Drinks & Beverages
### 4. Cuisines
├── name (Text, required) - "Italian", "Mexican", "Asian"
├── slug (Text, required)
├── description (Plain Text)
└── flag-icon (Image) - Optional visual
**Purpose:** Filter by cuisine type
**Suggested Cuisines (12):**
- American, Italian, Mexican, Asian, Mediterranean, French, Indian, Thai,
Chinese, Japanese, Greek, Middle Eastern
### 5. Dietary Tags
├── name (Text, required) - "Vegan", "Gluten-Free", "Keto"
├── slug (Text, required)
├── description (Plain Text)
├── icon (Image) - Badge icon
└── color (Color) - Badge color
**Purpose:** Multi-select dietary filters
**Suggested Tags (10):**
- Vegetarian, Vegan, Gluten-Free, Dairy-Free, Keto, Paleo, Low-Carb,
High-Protein, Nut-Free, Pescatarian
### 6. Cooking Methods
├── name (Text, required) - "Baking", "Grilling", "Slow Cooker"
├── slug (Text, required)
└── description (Plain Text)
**Purpose:** Filter by cooking technique
**Suggested Methods (8):**
- Baking, Grilling, Slow Cooker, Instant Pot, Stovetop, No-Cook,
Air Fryer, Sous Vide
---
## Relationship Map
Recipe → Author (one-to-many) ↓ Recipe → Category (one-to-many) ↓ Recipe → Cuisine (one-to-many) ↓ Recipe → Dietary Tags (many-to-many) ↓ Recipe → Cooking Methods (many-to-many)
**Multi-reference count:** 2 fields (within 5-field limit ✅)
---
## Recommended Page Structure
### 1. Homepage (/)
- Hero section with featured recipe
- Category cards (8 categories)
- Latest recipes (collection list, 6 items)
- Popular recipes (sorted by view-count)
- Call-to-action
### 2. Recipes Index (/recipes)
- Collection list showing all recipes
- Filter sidebar:
- Category (tabs or dropdown)
- Cuisine (multi-select)
- Dietary tags (checkboxes)
- Cooking time (< 30 min, 30-60 min, 60+ min)
- Difficulty (easy, medium, hard)
- Pagination (12 recipes per page)
- Search bar (Finsweet CMS Filter)
### 3. Recipe Detail (/recipes/[slug])
- Hero image + title
- Prep/cook/total time + servings
- Difficulty badge + dietary badges
- Ingredients list
- Step-by-step instructions
- Author card with bio
- Related recipes (same category or tags)
- Print button
### 4. Category Pages (/category/[slug])
- Category hero image + description
- Filtered recipes by category
- Breadcrumbs: Home > Recipes > [Category]
- Related categories
### 5. Cuisine Pages (/cuisine/[slug])
- Cuisine description + flag
- Filtered recipes by cuisine
- Popular cuisines sidebar
### 6. Author Profiles (/authors/[slug])
- Author photo + bio
- Author's recipes (collection list)
- Social links
- Author stats (total recipes, join date)
### 7. Dietary Filter Pages (/diet/[slug])
- Dietary tag description
- Filtered recipes by tag
- Related dietary tags
---
## SEO Optimization
### Collection Template SEO
Recipe Detail Page (/recipes/[slug]):
- SEO Title: {{recipe.name}} | Your Site Name
- Meta Description: {{recipe.description}}
- OG Image: {{recipe.featured-image}}
- Schema: Recipe structured data (JSON-LD)
### Structured Data (Recipe Schema)
```json
{
"@context": "https://schema.org/",
"@type": "Recipe",
"name": "{{recipe.name}}",
"image": "{{recipe.featured-image}}",
"author": {
"@type": "Person",
"name": "{{recipe.author.name}}"
},
"datePublished": "{{recipe.published-date}}",
"description": "{{recipe.description}}",
"prepTime": "PT{{recipe.prep-time}}M",
"cookTime": "PT{{recipe.cook-time}}M",
"totalTime": "PT{{recipe.total-time}}M",
"recipeYield": "{{recipe.servings}} servings",
"recipeIngredient": [...],
"recipeInstructions": [...]
}
Benefits:
- Rich snippets in Google search
- Better CTR (images, ratings, cook time in results)
- Voice search optimization
- Better recipe discovery
Performance Optimization
For 50-200 Recipes:
1. Pagination Strategy
Recipes Index page:
- Limit: 12 recipes per page
- Enable Webflow pagination
- "Load More" button for smoother UX
2. Image Optimization
Thumbnail: 400x300px (grid cards)
Featured: 1200x800px (detail pages)
Format: WebP when possible
Loading: lazy for below-fold images
3. Reference Field Strategy
Display only needed fields:
- Author name + photo (don't bind entire author object)
- Category name + color (skip unused fields)
- Each reference = query, so minimize bindings
4. Collection List Limits
Homepage: 6 featured recipes
Category pages: 12 recipes per page
Author pages: 12 recipes per page
Related recipes: 3-4 max
Content Strategy
Phase 1: Foundation (Weeks 1-2)
- Create Authors (3-5 authors)
- Create Categories (8 categories)
- Create Cuisines (10-12 cuisines)
- Create Dietary Tags (8-10 tags)
- Create Cooking Methods (6-8 methods)
Phase 2: Initial Content (Weeks 3-4)
- Add 20-30 flagship recipes
- Ensure even distribution across categories
- High-quality photos for all
- Complete metadata (all fields filled)
Phase 3: Growth (Ongoing)
- Add 5-10 recipes per week
- Monitor popular recipes (view-count)
- Update seasonal recipes
- Maintain content quality
Implementation Roadmap
Week 1: Setup
- Create all 6 collections with fields
- Define relationships (references)
- Set required fields
- Add help text for editors
Week 2: Content Structure
- Populate support collections (Authors, Categories, etc.)
- Create test recipes (3-5) with all fields
- Validate data structure
Week 3: Pages
- Build homepage layout
- Create recipe index page with filters
- Design recipe detail template
- Build category/cuisine/author pages
Week 4: Polish
- Implement SEO (titles, descriptions, schema)
- Add breadcrumbs and navigation
- Optimize images
- Test pagination and filters
Week 5: Launch
- Add 20-30 initial recipes
- Final QA testing
- Publish site
- Monitor performance
Quick Wins
1. Use View Count for "Popular Recipes"
- Add Number field: view-count
- Sort collection list by view-count (descending)
- Show "Most Popular" section on homepage
2. Auto-Calculate Total Time
- Option 1: Manual (editors enter prep + cook)
- Option 2: Display logic (show prep + cook sum in UI)
- Best for: Performance (no extra calculation)
3. Print-Friendly Recipe Cards
- Add "Print Recipe" button
- Use custom code to format for printing
- Include: Ingredients, Instructions, Image
- Exclude: Navigation, Ads, Comments
4. Related Recipes Logic
Automatic (no manual curation):
- Filter by same category
- Filter by shared dietary tags
- Sort by published-date (recent first)
- Limit to 3-4 recipes
Ready to implement? I can help you:
- Create these collections using cms-collection-setup skill
- Add initial content using bulk-cms-update skill
- Build the page structure
- Optimize for SEO and performance
Which would you like to start with?
### Example 2: Optimizing Existing CMS
**User prompt:**
My collection list is slow with 500+ items. How do I optimize?
**Response:**
⚡ CMS Performance Optimization
Analyzing your performance issue with 500+ items...
Current Issue Diagnosis
Problem: Loading 500+ items on a single page Impact:
- Slow page load (5-10 seconds or more)
- High bounce rate
- Poor SEO rankings
- Bad user experience
- Server stress
Root Causes:
- Too many items loaded at once
- Possibly too many reference field lookups
- Large unoptimized images
- No pagination or lazy loading
- Complex nested collection lists
Immediate Fixes (High Impact, Low Effort)
1. Implement Pagination ⚡ CRITICAL
Current: Loading all 500+ items Fix: Limit to 12-20 items per page
In Webflow Designer:
- Select your Collection List
- Settings > Limit items: 20
- Enable "Paginate items"
- Style pagination controls
Impact: 95% faster page load ✅ Time to implement: 5 minutes Effort: Low
2. Optimize Image Loading 🖼️
Current: Full-resolution images loading immediately Fix: Use proper image sizes + lazy loading
Implementation:
Thumbnail images in grid:
- Size: 400x300px (not full resolution)
- Format: WebP (smaller file size)
- Loading: lazy (below fold images)
In Collection List Image settings:
- Set custom size: 400x300
- Enable lazy loading
- Use srcset for responsive images
Impact: 60-70% faster load ✅ Time to implement: 15 minutes Effort: Low
3. Reduce Visible Reference Fields 🔗
Current: Binding all reference fields Fix: Only display what you actually need
Check your Collection List:
❌ Bad: Binding entire author object
{
author.name,
author.bio,
author.photo,
author.email,
author.social-links
}
✅ Good: Bind only displayed fields
{
author.name,
author.photo
}
Why: Each reference field = separate database query Impact: 30-40% faster ✅ Time to implement: 10 minutes Effort: Low
Medium-Term Solutions (Moderate Impact, Moderate Effort)
4. Filter at Collection Level
Current: Loading all items, then hiding with conditional visibility Fix: Use collection list filters
Example:
Instead of:
- Load all 500 posts
- Hide if published-date > today (conditional)
Do this:
- Collection List Filter: published-date ≤ today
- Only loads matching items
Implementation:
- Collection List Settings
- Add Filter: [field] [condition] [value]
- Combine multiple filters with AND/OR
Impact: 50% faster + cleaner ✅ Time to implement: 30 minutes Effort: Medium
5. Implement "Load More" Button
Alternative to pagination: Smoother UX
Options: a) Webflow native: Pagination with "Load More" styling b) Finsweet: CMS Load plugin (free) c) Custom code: AJAX load more
Benefits:
- Users stay on same page (no page refresh)
- Better for mobile UX
- Smooth scrolling experience
Impact: Better UX, same performance as pagination ✅ Time to implement: 1-2 hours Effort: Medium
6. Create Filtered Views
Instead of: One giant "All Posts" page Create: Multiple filtered pages
Example:
/blog → Recent posts (20 items)
/blog/featured → Featured posts only (10 items)
/blog/category/tech → Tech category (filtered)
/blog/archive → Older posts with pagination
Benefits:
- Faster individual pages
- Better SEO (targeted pages)
- Easier navigation
- Reduced cognitive load
Impact: Significant UX improvement ✅ Time to implement: 2-3 hours Effort: Medium
Long-Term Solutions (High Impact, High Effort)
7. Archive Old Content
Strategy: Dynamic recent + static archives
Implementation:
Recent Content (Dynamic CMS):
- Last 50-100 posts
- Full dynamic filtering
- Fast performance
Older Content (Static):
- Archive pages for older posts
- Yearly/quarterly archives
- Still accessible but static HTML
- Rarely updated
When to use:
- 1000+ items
- Clear separation between recent/old content
- Archive content rarely accessed
Impact: Maintains fast performance at scale ✅ Time to implement: 1-2 weeks Effort: High
8. Denormalize Data
Problem: Too many reference lookups Solution: Copy frequently-accessed data
Example:
Current (Normalized):
Post → Author (reference)
Display: {{post.author.name}}
= 2 queries (post + author)
Denormalized:
Post has author-name field (text)
Display: {{post.author-name}}
= 1 query (just post)
When to use:
- Reference data rarely changes (author names)
- Performance is critical
- You can maintain consistency
Tradeoff: ⚠️ Must update in multiple places if data changes
Impact: 40-50% faster for reference-heavy pages ✅ Time to implement: Varies (requires data migration) Effort: High
9. Implement Client-Side Filtering
Use: Finsweet CMS Filter (free)
Benefits:
- Load once, filter instantly
- No page refreshes
- Multiple simultaneous filters
- Search functionality
- Better UX
Best for:
- 100-500 items
- Users need advanced filtering
- Desktop-first audience
Limitation: All items loaded initially (use with pagination)
Impact: Instant filtering ✅ Time to implement: 2-4 hours Effort: Medium-High
Comprehensive Optimization Checklist
Immediate Actions (Today):
- Limit collection list to 20 items
- Enable pagination
- Optimize image sizes (400x300 for thumbnails)
- Enable lazy loading on images
- Remove unused reference field bindings
This Week:
- Add collection list filters (date, category)
- Create filtered category pages
- Test performance on mobile
- Implement "Load More" if desired
- Audit all collection lists on site
This Month:
- Consider Finsweet CMS Filter for advanced filtering
- Create archive structure if >1000 items
- Optimize all images (WebP format)
- Review and optimize reference relationships
- Set up performance monitoring
Performance Benchmarks
Before Optimization:
- Load time: 8-12 seconds
- Items loaded: 500+
- Images: Full resolution
- References: All fields
After Quick Fixes (Pagination + Images):
- Load time: 1-2 seconds ✅
- Items loaded: 20
- Images: Optimized thumbnails
- References: Only displayed fields
After Full Optimization:
- Load time: <1 second ✅
- Lighthouse score: 90+ ✅
- Smooth pagination
- Instant client-side filtering
Testing Your Changes
Before deploying:
-
Test on staging:
- Publish to staging domain first
- Verify pagination works
- Check image quality
- Test all filters
-
Performance testing:
- Use Google PageSpeed Insights
- Test on mobile (3G/4G)
- Check Lighthouse scores
- Verify Core Web Vitals
-
User testing:
- Navigate through pages
- Test search/filter
- Check mobile experience
- Verify no broken links
-
Monitor after launch:
- Watch analytics (bounce rate, time on page)
- Check error logs
- Monitor load times
- Gather user feedback
Quick Implementation Priority
Priority 1 (Do First):
- Pagination (20 items per page)
- Optimize images (thumbnails)
- Remove unused reference bindings
Priority 2 (This Week): 4. Add lazy loading 5. Create filtered views 6. Implement "Load More" option
Priority 3 (If Needed): 7. Finsweet CMS Filter 8. Archive old content 9. Denormalize critical data
Would you like me to walk you through implementing any of these optimizations? I can provide:
- Step-by-step Webflow Designer instructions
- Custom code snippets
- Testing checklist
- Performance monitoring setup
Let me know which optimization you'd like to tackle first!
### Example 3: Troubleshooting Relationships
**User prompt:**
My reference fields aren't showing up on the page. What's wrong?
**Response:**
🔍 Troubleshooting: Reference Fields Not Displaying
Let me help you diagnose and fix this issue.
Common Causes & Solutions
Issue 1: Reference Field Not Bound to Element
Symptom: Empty space where data should be Diagnosis: Element exists but has no data binding
Fix:
- Select the element (text, image, etc.)
- Settings panel > Get text/image from [Collection Item]
- Select your reference field
- Choose the specific field to display
Example:
Element: Text Block
Binding: Blog Post > Author (reference) > Name
Correct path:
Collection Item > author > name
Issue 2: Reference Field Has No Value
Symptom: Some items show data, others don't Diagnosis: Not all collection items have the reference assigned
Fix:
- Go to CMS Collections
- Open your collection
- Check items that aren't displaying
- Ensure reference field is populated
Prevention:
- Make reference fields "Required" if critical
- Provide default/fallback content
Issue 3: Wrong Collection Context
Symptom: Reference field not appearing in dropdown Diagnosis: Element is outside collection list context
Fix:
❌ Wrong:
<div>
<text>Author: {{author.name}}</text> ← No collection context
</div>
✅ Correct:
<Collection List - Posts>
<Collection Item>
<text>Author: {{author.name}}</text> ← Inside collection context
</Collection Item>
</Collection List>
Issue 4: Multi-Reference Display Error
Symptom: Only showing first item or nothing Diagnosis: Multi-reference needs nested collection list
Fix:
For Multi-Reference field (Post → Tags):
❌ Wrong: Direct binding
<text>Tags: {{post.tags}}</text>
✅ Correct: Nested collection list
<Collection List - Posts>
<Collection Item - Post>
<Collection List - Get Items from Post > Tags>
<Collection Item - Tag>
<text>{{tag.name}}</text>
</Collection Item>
</Collection List>
</Collection Item>
</Collection List>
Issue 5: Deleted Referenced Item
Symptom: Reference field shows nothing despite being assigned Diagnosis: Referenced item was deleted from other collection
Fix:
- Go to referring collection
- Check reference field assignments
- Re-assign to existing items
- Or recreate deleted item
Prevention:
- Be careful when deleting referenced items
- Check "Used in X items" before deleting
- Archive instead of delete if possible
Issue 6: Collection Not Published
Symptom: Works in designer, not on live site Diagnosis: Referenced collection items are drafts
Fix:
- Go to referenced collection (e.g., Authors)
- Find draft items
- Publish them
- Republish main site
Check:
CMS Collections > Authors
- Look for "Draft" badge
- Publish all needed items
- Items must be published to display via reference
Step-by-Step Diagnostic
Step 1: Verify Collection Structure
Check in CMS:
1. Does the reference field exist?
2. Is it configured correctly (Reference or Multi-Reference)?
3. Is it pointing to the right collection?
Step 2: Verify Data Exists
Check collection items:
1. Open an item that should display
2. Check if reference field is populated
3. Verify referenced item exists and is published
Step 3: Verify Page Structure
Check in Designer:
1. Is element inside Collection List?
2. Is Collection List connected to correct collection?
3. Is element binding correct path?
Step 4: Test in Designer
In Designer:
1. Click Collection List
2. Set preview mode: "Item 1"
3. Cycle through items
4. Check if data appears
If it works in Designer but not live:
→ Publish issue (republish site)
Testing Reference Fields
Manual Test Checklist
- Create test item with reference populated
- Preview in Designer
- Check element binding path
- Publish and view live
- Verify all items display correctly
- Check items without references (should fail gracefully)
Common Binding Patterns
Single Reference (Author):
Collection List: Posts
Collection Item: Post
Element: Text Block
Binding: Get text from Post > author > name
Multi-Reference (Tags):
Collection List: Posts
Collection Item: Post
Nested Collection List: Get items from Post > tags
Collection Item: Tag
Element: Text Block
Binding: Get text from Tag > name
Self-Reference (Related Posts):
Collection List: Posts
Collection Item: Post (current)
Nested Collection List: Get items from Post > related-posts
Collection Item: Post (related)
Element: Text Block
Binding: Get text from Post > title
Prevention Tips
Best Practices:
-
Make critical references required
- Required: Yes for author, category
- Optional: Yes for tags, related items
-
Provide default content
- If reference is empty, show "Uncategorized"
- Use conditional visibility for optional references
-
Test with incomplete data
- Create test items with missing references
- Ensure graceful fallback
-
Document reference structure
- Create guide for content editors
- Explain which fields are required
- Show how to assign references
-
Use descriptive field names
- ❌ "ref-1", "link"
- ✅ "author", "primary-category", "related-posts"
Quick Fixes by Symptom
| Symptom | Most Likely Cause | Quick Fix |
|---|---|---|
| Nothing shows | Not bound | Bind element to reference field |
| Some items empty | Reference not assigned | Assign reference in CMS |
| Works in designer, not live | Items not published | Publish referenced collection items |
| Only first tag shows | Using text binding on multi-ref | Use nested collection list |
| Shows random data | Wrong collection context | Check collection list nesting |
| Broken after deletion | Referenced item deleted | Re-assign or recreate item |
Would you like me to walk through your specific setup to diagnose the exact issue? I can:
- Review your collection structure
- Check your reference field configuration
- Analyze your page layout
- Test your data bindings
- Provide custom troubleshooting
Let me know what you'd like me to check!
## Guidelines
### Phase 1: Discovery Best Practices
**Always Start With:**
1. **Identify plan limits** - Use `data_sites_tool` with action `get_site` to check collection/item limits
2. **Analyze existing structure** - List collections before recommending changes
3. **Understand content volume** - Check item counts to assess scale
4. **Review current pages** - See how content is currently displayed
5. **Ask clarifying questions** - Don't assume requirements
**Plan Limits Reference:**
Starter Plan:
- Collections: 1
- Items per collection: 50
- CMS pages: 50
Basic Plan:
- Collections: 2
- Items total: 200
- CMS pages: 150
CMS Plan:
- Collections: 20
- Items total: 2,000
- CMS pages: 2,000
Business Plan:
- Collections: 40
- Items total: 10,000
- CMS pages: 10,000
Enterprise Plan:
- Custom limits
**Key Questions to Ask:**
1. "What content needs to be managed?" (identify collections)
2. "Who will update the content?" (determine complexity level)
3. "How will content be displayed?" (affects fields and relationships)
4. "What's the expected content volume?" (plan for scale)
5. "Are there any special requirements?" (unique features, integrations)
### Phase 2: Field Selection Best Practices
**Field Type Selection Matrix:**
**For Text Content:**
- **<50 characters:** Plain Text (single line)
- **50-256 characters:** Plain Text (multi-line)
- **Need formatting:** Rich Text
- **Pure data (no display):** Plain Text (validation enabled)
**For Relationships:**
- **One parent:** Reference (e.g., Post → Author)
- **Multiple parents:** Multi-Reference (e.g., Post → Tags)
- **Self-referencing:** Reference to same collection (e.g., Category → Parent Category)
**For Media:**
- **Hero images:** Image field (1 image)
- **Galleries:** Multi-image field (up to 25 images)
- **Documents:** File field (PDFs, docs)
- **Videos:** Video field (YouTube/Vimeo embeds)
**For Metadata:**
- **Dates:** Date/Time field
- **Numbers:** Number field (prices, counts, ratings)
- **Colors:** Color field (brand colors, theme colors)
- **Switches:** Boolean field (featured, published, active)
**Field Naming Conventions:**
✅ Good Names:
- published-date (descriptive, hyphenated)
- author (clear purpose)
- main-image (specifies which image)
- post-summary (explains use case)
❌ Bad Names:
- date1 (unclear which date)
- img (which image?)
- text (what kind of text?)
- field1 (no meaning)
**Required vs Optional:**
Make REQUIRED:
- name (unique identifier)
- slug (URL generation)
- primary relationships (author, category)
- publish date (for sorting)
Make OPTIONAL:
- tags (not always applicable)
- secondary images
- advanced metadata
- related items
### Phase 3: Relationship Design Best Practices
**One-to-Many Guidelines:**
Use when:
- Each item has exactly ONE parent
- Parent data is reused across many items
- You want centralized data management
Examples: ✅ Post → Author (each post has one author) ✅ Product → Brand (each product has one brand) ✅ Event → Venue (each event has one venue)
Don't use when: ❌ Item can have multiple parents (use multi-reference) ❌ Relationship is temporary (consider option field) ❌ Data is simple and rarely changes (use option field instead)
**Many-to-Many Guidelines:**
Use when:
- Items can have multiple relationships
- Relationships need to be managed separately
- You want flexible cross-linking
Examples: ✅ Post ↔ Tags (posts have many tags, tags apply to many posts) ✅ Product ↔ Features (products have many features, features apply to many products) ✅ Course ↔ Topics (courses cover many topics, topics span many courses)
Remember: ⚠️ Max 5 multi-reference fields per collection ⚠️ Can only filter by ONE multi-reference at a time ⚠️ Cannot sort by referenced field values ⚠️ Performance impact (more queries)
**Self-Reference Guidelines:**
Use when:
- Building hierarchies (categories, menu structure)
- Related items from same collection
- Organizational trees
Implementation:
- Add Reference field pointing to same collection
- Name it clearly: parent-category, related-posts
- Limit depth to 2-3 levels for practical display
- Consider adding "level" number field for easier filtering
Example Structure: Categories: ├── Web Development (level 1, parent: null) │ ├── Frontend (level 2, parent: Web Development) │ └── Backend (level 2, parent: Web Development) └── Design (level 1, parent: null)
### Phase 4: Architecture Patterns
**Common Collection Patterns:**
**1. Blog Architecture:**
Minimal (1 collection):
- Blog Posts
Standard (3 collections):
- Blog Posts
- Authors
- Categories
Advanced (5+ collections):
- Blog Posts
- Authors
- Categories
- Tags
- Topics/Series
**2. E-commerce Architecture:**
Minimal (1 collection):
- Products
Standard (4 collections):
- Products
- Categories
- Brands
- Features/Specifications
Advanced (7+ collections):
- Products
- Categories
- Brands
- Features
- Reviews
- Collections (curated product groups)
- Related Products
**3. Portfolio Architecture:**
Minimal (1 collection):
- Projects
Standard (3 collections):
- Projects
- Clients
- Services/Categories
Advanced (5+ collections):
- Projects
- Clients
- Services
- Team Members
- Technologies Used
**4. Directory Architecture:**
Minimal (1 collection):
- Listings
Standard (4 collections):
- Listings
- Categories
- Locations
- Owners/Managers
Advanced (6+ collections):
- Listings
- Categories
- Subcategories
- Locations (hierarchical)
- Amenities/Features
- Reviews/Ratings
### Phase 5: Performance Optimization
**Pagination Strategy:**
Content Volume → Items Per Page:
- 0-50 items: No pagination needed
- 50-100 items: 20 items per page
- 100-500 items: 15-20 items per page
- 500-1000 items: 12-15 items per page
- 1000+ items: 10-12 items per page + advanced filtering
**Image Optimization:**
Usage → Recommended Size:
- Thumbnail (grid cards): 400x300px
- Featured image (hero): 1200x800px
- Gallery images: 800x600px
- Background images: 1920x1080px
Format Priority:
- WebP (best compression, modern browsers)
- JPEG (photos, complex images)
- PNG (transparency needed, simple graphics)
- SVG (logos, icons, simple graphics)
**Reference Field Strategy:**
Optimization Levels:
Level 1 - Display Only What's Needed: ❌ Binding entire author object: {{author}} ✅ Binding specific fields: {{author.name}}, {{author.photo}}
Level 2 - Denormalize Critical Data: Instead of: Post → Author.name (2 queries) Store: Post.author-name (1 query) When: Performance critical + data rarely changes
Level 3 - Lazy Load Related Content: Show main content immediately Load related items on interaction (click, scroll) Reduces initial page load
**Collection List Optimization:**
Best Practices:
-
Filter at Collection Level: ✅ Use native collection list filters ❌ Load all items then hide with conditionals
-
Limit Items: ✅ Set reasonable limit (12-20 items) ❌ Load unlimited items
-
Optimize Nested Lists: ✅ Limit nested collection lists to 3-5 items ❌ Nest multiple unlimited lists
-
Use Conditional Loading: ✅ Load content based on viewport ❌ Load everything upfront
-
Implement Pagination: ✅ Enable Webflow pagination or "Load More" ❌ Infinite scroll with all items
### Phase 6: SEO Best Practices
**Collection Template SEO:**
Required Fields:
- SEO Title (dynamic from item name)
- Meta Description (dynamic from summary/description)
- OG Image (dynamic from featured image)
- Canonical URL (automatic)
Recommended: 5. Schema.org structured data (JSON-LD) 6. Open Graph tags (Facebook/LinkedIn) 7. Twitter Card tags 8. Alt text for all images
**Slug Best Practices:**
✅ Good Slugs:
- webflow-cms-best-practices
- ultimate-guide-to-seo
- 2026-web-design-trends
❌ Bad Slugs:
- Post1
- new-post-copy-3
- untitled-entry
Rules:
- Lowercase only
- Hyphens (not underscores)
- No special characters
- Descriptive (include keywords)
- Max 50-60 characters
**Structured Data Implementation:**
Common Types:
Blog Post (Article schema):
- headline, author, datePublished, image
- Use for: Blog posts, news articles
Product (Product schema):
- name, description, price, availability, image
- Use for: E-commerce products
Event (Event schema):
- name, startDate, location, organizer
- Use for: Events, webinars, conferences
Recipe (Recipe schema):
- name, ingredients, instructions, cookTime
- Use for: Recipe sites, food blogs
Local Business (LocalBusiness schema):
- name, address, phone, openingHours
- Use for: Directories, business listings
### Phase 7: Editorial Workflow
**Content Editor Guidelines:**
**Field Usage Documentation:**
Create guide for each collection:
Example - Blog Posts Collection:
-
Name* (required)
- Post title
- Keep under 60 characters for SEO
- Make it catchy and descriptive
-
Slug* (required)
- Auto-generated from name
- Can be edited for SEO optimization
- Use hyphens, lowercase only
-
Post Summary
- Brief description (160 characters max)
- Used for: Grid cards, meta description, social sharing
- Make it compelling - this is what users see first
-
Featured Image*
- Hero image for post
- Minimum size: 1200x800px
- Always add alt text for accessibility
-
Author*
- Select from Authors list
- Can't find author? Ask admin to create in Authors collection
... (document all fields)
**Required Field Checklist:**
Before Publishing: □ Name filled □ Slug set (no generic slugs like "untitled") □ Summary written (compelling, 160 chars) □ Featured image uploaded with alt text □ Author assigned □ Category selected □ Published date set □ Content proofread □ Links tested □ Images optimized □ SEO reviewed
**Draft → Published Workflow:**
-
Create as Draft:
- Fill required fields minimum
- Save to preserve work
-
Complete Content:
- Write/upload all content
- Add images with alt text
- Set metadata
-
Internal Review:
- Proofread
- Check formatting
- Test links
- Verify references
-
Publish:
- Set published date
- Change from draft to published
- Verify on live site
- Share/promote
-
Ongoing:
- Update as needed
- Monitor performance
- Refresh outdated content
- Archive if no longer relevant
### Phase 8: Migration Strategy
**When Refactoring Existing CMS:**
**Assessment Phase:**
-
Audit Current Structure:
- List all collections
- Count items per collection
- Map relationships
- Identify problems
-
Design New Structure:
- Plan improvements
- Design new collections
- Define new relationships
- Create migration plan
-
Validate Approach:
- Test with sample data
- Verify relationships work
- Check performance
- Get stakeholder approval
**Migration Approaches:**
**Approach 1: Parallel Build (Safest)**
- Build new collections alongside old
- Migrate content gradually
- Test thoroughly
- Switch pages to new collections
- Archive old collections
Pros: ✅ No downtime ✅ Easy rollback ✅ Test before fully committing
Cons: ❌ Temporarily doubled content ❌ Longer timeline ❌ Must manage both systems temporarily
**Approach 2: Direct Migration (Faster)**
- Create new collections
- Export data from old collections
- Transform data format
- Import to new collections
- Update pages to use new collections
- Delete old collections
Pros: ✅ Faster completion ✅ Clean cutover ✅ No duplicate content
Cons: ❌ Higher risk ❌ Potential downtime ❌ Harder to rollback
**Approach 3: Hybrid (Recommended)**
- Create new structure
- Migrate in batches (50-100 items)
- Test each batch
- Update pages incrementally
- Monitor for issues
- Complete full migration
Pros: ✅ Balanced risk/speed ✅ Can catch issues early ✅ Incremental testing
Cons: ❌ Requires careful planning ❌ More complex execution
### Phase 9: Troubleshooting Common Issues
**Issue: "Collection won't save"**
Possible causes:
- Required field empty
- Slug conflict (duplicate)
- Invalid characters in slug
- Reference pointing to deleted item
- Field validation failing
Diagnosis:
- Check for red highlighted fields
- Verify slug is unique
- Test without optional fields
- Check browser console for errors
Fix:
- Fill all required fields
- Change slug to be unique
- Remove special characters
- Re-assign references
- Contact Webflow support if persists
**Issue: "Reference field not showing options"**
Possible causes:
- Referenced collection has no items
- Referenced collection items not published
- Wrong collection selected in reference settings
- Browser cache issue
Fix:
- Create items in referenced collection first
- Publish all items in referenced collection
- Double-check reference field configuration
- Clear cache and refresh
**Issue: "Collection list showing wrong items"**
Possible causes:
- Wrong collection selected
- Filters configured incorrectly
- Limit set too low
- Items not published
- Wrong CMS locale selected
Diagnosis:
- Check collection list settings
- Review filter conditions
- Check item publish status
- Verify correct locale
Fix:
- Select correct collection
- Adjust or remove filters
- Increase limit
- Publish items
- Switch to correct locale
**Issue: "Pagination not working"**
Possible causes:
- Pagination not enabled
- Limit set equal to or greater than total items
- JavaScript conflict
- Custom code interfering
Fix:
- Enable pagination in collection list settings
- Set limit lower than total items (e.g., 20)
- Test with all custom code disabled
- Check for JavaScript errors in console
**Issue: "Multi-reference only showing first item"**
Cause: Wrong display method
Fix: Must use nested collection list: ❌ Direct text binding ✅ Collection List > Get items from [field] > Collection Item > Display
Example: <Collection List - Posts> <Collection Item - Post> Tags: <Collection List - Get items from Post > tags> <Collection Item - Tag> {{tag.name}} </Collection Item> </Collection List> </Collection Item> </Collection List>
### Phase 10: Advanced Techniques
**Conditional Display Based on References:**
Use Case: Show different layouts based on category
Implementation:
- Add conditional visibility to elements
- Condition: Category = "Video Posts"
- Show video player layout
- Condition: Category = "Image Posts"
- Show image gallery layout
Limitation: Can only check one value at a time Alternative: Use option field with class name, apply class dynamically
**Scheduled Publishing:**
Implementation:
- Add "Published Date" field (Date/Time)
- In collection list settings:
- Add filter: Published Date ≤ Current Date
- Set future dates on items to schedule
Benefits:
- No plugins needed
- Native Webflow functionality
- Items auto-appear on set date
Limitation: Items exist but filtered, not truly unpublished
**Dynamic Sorting:**
Option 1: Manual Sort Order
- Add "Sort Order" number field
- Manually assign: 1, 2, 3, 4...
- Sort collection list by Sort Order (ascending)
Option 2: Auto Sort by Engagement
- Add "View Count" number field
- Increment on page view (requires custom code)
- Sort by View Count (descending) for "Popular" lists
Option 3: Date-Based Sorting
- Sort by Published Date (descending) for "Recent"
- Sort by Created Date for "Chronological"
- Combine with filters for "This Month's Top Posts"
**Multi-Lingual Content:**
Approach 1: Separate Collections per Language
- Blog Posts EN
- Blog Posts ES
- Blog Posts FR
Pros: Simple, native Webflow Cons: Must duplicate structure, harder to maintain
Approach 2: Language Field + Filter
- Add "Language" option field (EN, ES, FR)
- Filter collection lists by language
- Use URL parameter or cookie for language switch
Pros: Single structure, easier to maintain Cons: All content in one collection
Approach 3: Webflow Localization (CMS Plan+)
- Use Webflow's native localization
- Create secondary locales
- Translate CMS content per locale
Pros: Official solution, best SEO Cons: Requires CMS plan+, setup complexity
**Search Functionality:**
Option 1: Native (Limited)
- Use filter inputs on collection lists
- Basic keyword matching only
- No fuzzy search or relevance ranking
Option 2: Finsweet CMS Filter (Free)
- Client-side search and filtering
- Works with existing collection lists
- Multiple simultaneous filters
- Requires JavaScript
Option 3: Algolia/Custom (Advanced)
- Server-side search with AI
- Typo-tolerance, synonyms
- Fast and scalable
- Requires integration, costs money
Recommendation:
- <100 items: Native or Finsweet
- 100-1000 items: Finsweet
- 1000+ items: Consider Algolia
## Production Checklist
Before launching CMS-driven site:
**Structure:**
- [ ] All collections created with proper field types
- [ ] Required fields set appropriately
- [ ] Help text added for content editors
- [ ] Relationships configured correctly
- [ ] Self-references working properly
- [ ] Validation rules set on text fields
**Content:**
- [ ] Test items created for all collections
- [ ] All reference fields populated in test items
- [ ] Images optimized (size, format, alt text)
- [ ] Slugs follow naming conventions
- [ ] Published dates set on items
- [ ] Draft items clearly marked
**Pages:**
- [ ] Collection lists limited appropriately (12-20 items)
- [ ] Pagination enabled on large lists
- [ ] Filters configured correctly
- [ ] Multi-reference fields use nested collection lists
- [ ] Conditional visibility works as expected
- [ ] Empty states handled gracefully
**SEO:**
- [ ] Collection template has SEO title binding
- [ ] Meta descriptions bound to summary fields
- [ ] OG images bound to featured images
- [ ] Structured data implemented (if applicable)
- [ ] Alt text present on all images
- [ ] Slugs are SEO-friendly
**Performance:**
- [ ] Images lazy loading enabled
- [ ] Only displayed reference fields bound
- [ ] Collection lists use filters (not conditional hiding)
- [ ] Pagination prevents loading too many items
- [ ] Performance tested on mobile
- [ ] Lighthouse score >80
**Documentation:**
- [ ] Field usage guide created for editors
- [ ] Collection structure documented
- [ ] Relationship map created
- [ ] Publishing workflow defined
- [ ] Troubleshooting guide available
- [ ] Contact for technical support identified
**Testing:**
- [ ] All collection lists display correctly
- [ ] Pagination works
- [ ] Filters work
- [ ] Search works (if implemented)
- [ ] Reference fields display data
- [ ] Multi-reference lists show all items
- [ ] Empty states handled
- [ ] Mobile experience tested
- [ ] Cross-browser tested
- [ ] Performance benchmarked
**Launch:**
- [ ] Content editors trained
- [ ] Editorial calendar established
- [ ] Publishing workflow in place
- [ ] Monitoring setup (analytics, errors)
- [ ] Backup strategy defined
- [ ] Support plan in place
CMS Collection Setup
Create a new CMS collection with custom fields, relationships, and proper configuration.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before starting - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify available sites - Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve site details and plan limits - Use Webflow MCP's
data_cms_toolwith actionget_collection_listto check for naming conflicts - Use Webflow MCP's
data_cms_toolwith actioncreate_collectionto create the collection - Use Webflow MCP's
data_cms_toolwith actioncreate_collection_static_fieldto create static fields - Use Webflow MCP's
data_cms_toolwith actioncreate_collection_option_fieldto create option fields - Use Webflow MCP's
data_cms_toolwith actioncreate_collection_reference_fieldto create reference/multi-reference fields - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto verify collection was created correctly - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Site Selection & Discovery
- Get site information: Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify target site - Confirm site: Ask user to select site if multiple available
- Check plan limits: Use Webflow MCP's
data_sites_toolwith actionget_siteto verify collection limits - List existing collections: Use Webflow MCP's
data_cms_toolwith actionget_collection_listto check for conflicts - Validate naming: Ensure new collection name doesn't conflict with existing
Phase 2: Requirements Gathering
- Get collection details: Ask user for:
- Collection display name (e.g., "Blog Posts")
- Singular name (e.g., "Blog Post")
- Optional: Custom slug (default: auto-generated from display name)
- Get field definitions: For each field, gather:
- Field name (e.g., "Author Name", "Publish Date")
- Field type (Text, Rich Text, Image, Option, Reference, etc.)
- Required vs optional
- Any validation rules or help text
- Identify relationships: Determine if collection needs:
- Reference fields (one-to-many relationships)
- Multi-reference fields (many-to-many relationships)
- Option fields (controlled vocabulary)
Phase 3: Schema Validation & Planning
- Validate field types: Check all field types are supported
- Check field limits: Ensure within Webflow limits:
- Max fields per collection: varies by plan
- Max 5 multi-reference fields per collection
- Plan creation order: Organize fields by dependency:
- Create collections in order if references exist
- Create referenced collections first
- Create option fields before reference fields
- Generate preview: Show complete schema with all fields
Phase 4: User Approval
- Show complete preview: Display:
- Collection name and slug
- All fields with types and properties
- Any relationships to other collections
- Plan limit verification
- Validate schema: Check for common issues:
- Missing required fields (name, slug always required)
- Invalid field types
- Reference to non-existent collections
- Exceeding plan limits
- Request confirmation: Wait for explicit "create" approval
Phase 5: Collection Creation
- Create collection: Use Webflow MCP's
data_cms_toolwith actioncreate_collectionwith:- Display name
- Singular name
- Optional slug
- Capture collection ID: Save for field creation
- Show progress: Report collection created successfully
Phase 6: Field Creation
- Create fields in order: For each field:
- Use appropriate creation tool based on type
- Static fields:
data_cms_toolwith actioncreate_collection_static_field - Option fields:
data_cms_toolwith actioncreate_collection_option_field - Reference fields:
data_cms_toolwith actioncreate_collection_reference_field
- Set field properties:
- Display name
- Required flag
- Help text (if provided)
- Validation rules (if applicable)
- Show progress: Report each field created
- Handle errors: If field creation fails, report and continue
Phase 7: Verification & Reporting
- Verify collection: Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto retrieve full schema - Confirm all fields: Check that all requested fields were created
- Generate report: Show:
- Collection ID
- Collection name and slug
- All fields created with IDs
- Any failures or warnings
- Provide next steps: Suggest:
- Use bulk-cms-update to add initial items
- Create collection pages in Designer
- Set up relationships if applicable
Field Type Reference
Static Field Types
PlainText - Short text (max 256 chars) or long text
- Use for: Titles, names, descriptions, excerpts
- Properties: maxLength validation (256 for short)
- Example: "Title", "Author Name", "Excerpt"
RichText - Formatted text with HTML
- Use for: Blog content, bios, articles, long descriptions
- Properties: No length limit
- Example: "Post Content", "Bio", "Description"
Email - Email address
- Use for: Contact emails, author emails
- Properties: Email format validation
- Example: "Contact Email", "Author Email"
Phone - Phone number
- Use for: Contact numbers
- Properties: E.164 format
- Example: "Phone Number", "Mobile"
Link - External URL or internal link
- Use for: Website links, social media, external resources
- Properties: URL validation
- Example: "Website", "LinkedIn Profile"
Number - Numeric values
- Use for: Prices, ratings, counts, order numbers
- Properties: Integer or decimal
- Example: "Price", "Rating", "Order"
Image - Single image
- Use for: Featured images, photos, thumbnails
- Properties: Max 4MB per image
- Example: "Featured Image", "Photo", "Thumbnail"
MultiImage - Multiple images (up to 25)
- Use for: Galleries, product photos
- Properties: Max 25 images, 4MB each
- Example: "Gallery", "Product Photos"
File - File upload
- Use for: PDFs, documents, downloads
- Properties: Max 4MB per file
- Example: "Resume PDF", "Brochure", "Manual"
Video - Video embed (YouTube/Vimeo)
- Use for: Video content
- Properties: Embed URL
- Example: "Tutorial Video", "Demo"
DateTime - Date and/or time
- Use for: Publish dates, event dates, deadlines
- Properties: ISO 8601 format
- Example: "Publish Date", "Event Date"
Switch - Boolean (true/false)
- Use for: Featured flags, visibility toggles
- Properties: Boolean value
- Example: "Featured", "Published", "Active"
Color - Color value
- Use for: Theme colors, accents, brand colors
- Properties: Hex format
- Example: "Brand Color", "Accent Color"
Option Field Type
Option - Single choice from predefined list
- Use for: Status, category, type, priority
- Properties: List of option names
- Example: "Status" (Draft, Review, Published)
- Creation: Use
data_cms_toolwith actioncreate_collection_option_fieldwith options array
Example:
{
"type": "Option",
"displayName": "Status",
"metadata": {
"options": [
{"name": "Draft"},
{"name": "In Review"},
{"name": "Published"}
]
}
}
Reference Field Types
Reference - Link to one item in another collection (one-to-many)
- Use for: Author → Post, Category → Post, Brand → Product
- Properties: Collection ID of referenced collection
- Example: "Author" (reference to Authors collection)
- Creation: Use
data_cms_toolwith actioncreate_collection_reference_fieldwith collectionId
MultiReference - Link to multiple items in another collection (many-to-many)
- Use for: Post → Tags, Product → Features, Project → Technologies
- Properties: Collection ID of referenced collection
- Limit: Max 5 multi-reference fields per collection
- Example: "Tags" (reference to Tags collection)
- Creation: Use
data_cms_toolwith actioncreate_collection_reference_fieldwith collectionId
Reference Field Example:
{
"type": "Reference",
"displayName": "Author",
"metadata": {
"collectionId": "abc123..."
}
}
Multi-Reference Field Example:
{
"type": "MultiReference",
"displayName": "Tags",
"metadata": {
"collectionId": "xyz789..."
}
}
Examples
Example 1: Simple Blog Collection
User prompt:
Create a Blog Posts collection with title, content, author, and publish date
Step 1: Discovery
🔍 CMS Collection Setup
Available sites:
1. Company Website
2. Blog Site
Which site? (1/2)
Step 2: After User Selects Site
📊 Existing Collections on Company Website:
Currently: 0 collections
Plan limit: 20 collections (CMS Plan)
✅ You have capacity to create new collections.
---
📋 Collection Requirements
Display Name: Blog Posts
Singular Name: Blog Post
Slug: blog-posts (auto-generated)
Fields to create:
1. Title - Text (required)
2. Content - Rich Text (required)
3. Author - Text
4. Publish Date - Date/Time (required)
Is this correct? (yes/no)
If you want to add/modify fields, describe the changes.
Step 3: Preview
📋 Preview: Create "Blog Posts" Collection
Collection:
├── Display Name: Blog Posts
├── Singular Name: Blog Post
├── Slug: blog-posts
└── Site: Company Website
Fields (6 total):
├── name (PlainText, required) ← Auto-created
├── slug (PlainText, required) ← Auto-created
├── title (PlainText, required)
├── content (RichText, required)
├── author (PlainText)
└── publish-date (DateTime, required)
✅ Validation Passed:
- Collection name available
- Within plan limits (0/20 collections)
- All field types valid
- No dependency issues
⚠️ Type "create" to proceed.
Step 4: Creation
🔄 Creating Collection...
✅ Collection created: Blog Posts (ID: 64f1a2b3...)
Adding fields...
├── ✅ title (PlainText)
├── ✅ content (RichText)
├── ✅ author (PlainText)
└── ✅ publish-date (DateTime)
Progress: ████████████████████ 100% (4/4 fields)
🎉 Collection Setup Complete!
Collection: Blog Posts
ID: 64f1a2b3...
Fields: 6 (2 auto-created + 4 custom)
---
💡 Next Steps:
1. Use bulk-cms-update to add initial blog posts
2. Create collection template page in Designer
3. Set up collection list page for blog index
4. Configure SEO settings for dynamic pages
Example 2: Collection with Relationships
User prompt:
Create a Products collection with name, price, description, images, brand, and tags
Step 1: After Initial Gathering
📋 Collection Analysis
I see you want:
- Brand: This should be a reference field
- Tags: This should be a multi-reference field
This requires creating additional collections first:
1. Brands collection
2. Tags collection
Then we can create Products with references to them.
Would you like me to:
A) Create all three collections (Brands, Tags, Products)
B) Just create Products (you'll add relationships later)
C) Modify the requirements
Your choice? (A/B/C)
Step 2: After User Selects "A"
📋 Preview: Create 3 Collections
---
### 1. Brands Collection
Fields (4 total):
├── name (PlainText, required) ← Auto
├── slug (PlainText, required) ← Auto
├── logo (Image)
└── description (PlainText)
---
### 2. Tags Collection
Fields (3 total):
├── name (PlainText, required) ← Auto
├── slug (PlainText, required) ← Auto
└── color (Color)
---
### 3. Products Collection
Fields (9 total):
├── name (PlainText, required) ← Auto
├── slug (PlainText, required) ← Auto
├── price (Number, required)
├── description (RichText)
├── images (MultiImage)
├── brand (Reference → Brands)
└── tags (MultiReference → Tags)
---
Creation Order:
1. Brands (no dependencies)
2. Tags (no dependencies)
3. Products (references 1 & 2)
✅ Validation:
- All collections available
- Within plan limits (0/20 collections)
- Multi-reference limit: 1/5 ✅
- All dependencies resolvable
⚠️ Type "create" to proceed with all 3 collections.
Step 3: Creation
🔄 Creating Collections...
[1/3] Creating Brands...
✅ Brands collection created (ID: abc123...)
├── ✅ logo (Image)
└── ✅ description (PlainText)
[2/3] Creating Tags...
✅ Tags collection created (ID: def456...)
└── ✅ color (Color)
[3/3] Creating Products...
✅ Products collection created (ID: ghi789...)
├── ✅ price (Number)
├── ✅ description (RichText)
├── ✅ images (MultiImage)
├── ✅ brand (Reference → Brands)
└── ✅ tags (MultiReference → Tags)
Progress: ████████████████████ 100% (3/3 collections)
🎉 All Collections Created!
Summary:
├── Brands (ID: abc123...)
├── Tags (ID: def456...)
└── Products (ID: ghi789...)
---
💡 Next Steps:
1. Add brand items first (use bulk-cms-update)
2. Add tag items (use bulk-cms-update)
3. Then add products with brand/tag references
4. Create collection pages in Designer
Example 3: Team Members with Option Field
User prompt:
Create a Team Members collection with name, role (dropdown: Designer, Developer, Manager), bio, photo, email
Step 1: Preview
📋 Preview: Create "Team Members" Collection
Collection:
├── Display Name: Team Members
├── Singular Name: Team Member
└── Slug: team-members
Fields (7 total):
├── name (PlainText, required) ← Auto
├── slug (PlainText, required) ← Auto
├── role (Option, required)
│ Options:
│ ├── Designer
│ ├── Developer
│ └── Manager
├── bio (RichText)
├── photo (Image)
└── email (Email)
✅ Validation Passed
⚠️ Type "create" to proceed.
Step 2: Creation
🔄 Creating Collection...
✅ Collection created: Team Members (ID: jkl012...)
Adding fields...
├── ✅ role (Option: 3 options)
├── ✅ bio (RichText)
├── ✅ photo (Image)
└── ✅ email (Email)
Progress: ████████████████████ 100% (4/4 fields)
🎉 Collection Setup Complete!
Collection: Team Members
Fields: 6 (2 auto + 4 custom)
Field Details:
- role: Option field with 3 choices
• Designer
• Developer
• Manager
---
💡 Next Steps:
1. Add team member items
2. Create team page in Designer
3. Consider adding:
- LinkedIn profile (Link field)
- Years of experience (Number field)
- Specializations (MultiReference to Skills collection)
Example 4: Complex E-commerce Setup
User prompt:
Create an e-commerce setup with Products, Categories, Brands, and Features
Step 1: Requirements Clarification
📋 E-commerce Collection Planning
I'll create 4 collections:
1. **Categories** - Product categories
2. **Brands** - Product brands
3. **Features** - Product features (e.g., "Waterproof", "Wireless")
4. **Products** - Main product catalog
Relationships:
- Product → Category (Reference)
- Product → Brand (Reference)
- Product → Features (MultiReference)
Fields per collection:
**Categories:**
- Name, Slug (auto)
- Description
- Parent Category (self-reference for hierarchy)
- Icon
**Brands:**
- Name, Slug (auto)
- Logo
- Description
**Features:**
- Name, Slug (auto)
- Icon
- Description
**Products:**
- Name, Slug (auto)
- Price
- Sale Price
- Description
- Images (MultiImage)
- Category (Reference → Categories)
- Brand (Reference → Brands)
- Features (MultiReference → Features)
- In Stock (Switch)
- SKU (PlainText)
Is this structure good? (yes/modify/cancel)
Step 2: Preview (User says "yes")
📋 Preview: Create E-commerce Collections
---
### Collection 1: Categories
Fields (5 total):
├── name (PlainText, required)
├── slug (PlainText, required)
├── description (PlainText)
├── parent-category (Reference → Categories) ← Self-reference
└── icon (Image)
---
### Collection 2: Brands
Fields (4 total):
├── name (PlainText, required)
├── slug (PlainText, required)
├── logo (Image)
└── description (PlainText)
---
### Collection 3: Features
Fields (4 total):
├── name (PlainText, required)
├── slug (PlainText, required)
├── icon (Image)
└── description (PlainText)
---
### Collection 4: Products
Fields (12 total):
├── name (PlainText, required)
├── slug (PlainText, required)
├── price (Number, required)
├── sale-price (Number)
├── description (RichText)
├── images (MultiImage)
├── category (Reference → Categories)
├── brand (Reference → Brands)
├── features (MultiReference → Features)
├── in-stock (Switch)
└── sku (PlainText)
---
Creation Order:
1. Categories (self-reference OK)
2. Brands (no dependencies)
3. Features (no dependencies)
4. Products (references 1, 2, 3)
✅ Validation:
- Within plan limits (0/20 collections)
- Multi-reference count: 1/5 ✅
- All field types valid
- Self-reference supported
⚠️ Type "create" to proceed with all 4 collections.
Step 3: Creation with Progress
🔄 Creating E-commerce Collections...
[1/4] Creating Categories...
✅ Categories created (ID: aaa111...)
Progress: ████████░░░░░░░░░░░░ 25%
[2/4] Creating Brands...
✅ Brands created (ID: bbb222...)
Progress: ████████████░░░░░░░░ 50%
[3/4] Creating Features...
✅ Features created (ID: ccc333...)
Progress: ████████████████░░░░ 75%
[4/4] Creating Products...
✅ Products created (ID: ddd444...)
Progress: ████████████████████ 100%
---
🎉 E-commerce Setup Complete!
Collections Created (4):
├── Categories (ID: aaa111..., 5 fields)
├── Brands (ID: bbb222..., 4 fields)
├── Features (ID: ccc333..., 4 fields)
└── Products (ID: ddd444..., 12 fields)
Relationships Configured:
- Products → Categories (one-to-many)
- Products → Brands (one-to-many)
- Products → Features (many-to-many)
- Categories → Parent Category (self-reference)
---
💡 Recommended Content Order:
1. Add categories first (including parent relationships)
2. Add brands
3. Add features
4. Finally add products (with all references)
💡 Next Steps:
1. Use bulk-cms-update for initial data
2. Create product template page
3. Create product listing page with filters
4. Set up category landing pages
5. Configure e-commerce integration
Guidelines
Phase 1: Discovery Best Practices
Site Selection:
- Always use
data_sites_toolwith actionlist_sitesto get available sites - Never assume site ID
- Verify user has correct site selected
Plan Limit Checking:
Check limits before creation:
- Starter: 1 collection, 50 items
- Basic: 2 collections, 200 items
- CMS: 20 collections, 2,000 items
- Business: 40 collections, 10,000 items
- Enterprise: Custom
Warn user if approaching limits.
Naming Conflict Prevention:
- Check existing collection names
- Suggest alternative names if conflict
- Validate slug availability
Phase 2: Requirements Gathering Best Practices
Display Name vs Singular Name:
Display Name: Plural form shown in CMS
Singular Name: Singular form for individual items
Examples:
- Display: "Blog Posts" → Singular: "Blog Post"
- Display: "Team Members" → Singular: "Team Member"
- Display: "Products" → Singular: "Product"
- Display: "Categories" → Singular: "Category"
Field Naming Conventions:
✅ Good names:
- author-name (descriptive, hyphenated)
- publish-date (clear purpose)
- featured-image (specifies which)
- main-content (explains use)
❌ Bad names:
- text1 (meaningless)
- field (too generic)
- data (unclear)
- img (which image?)
Detecting Relationships:
If user says:
"... with author" → Likely reference field
"... with tags" → Likely multi-reference field
"... with category" → Likely reference field
"... with related products" → Likely multi-reference field
Ask clarifying questions:
- Is [author] the same across items? → Reference
- Can items have multiple [tags]? → Multi-reference
- Do you have a [Categories] collection? → Check existence
Phase 3: Schema Validation Best Practices
Field Type Validation:
Common field type mappings:
User says... → Field type:
"title", "name" → PlainText
"description", "summary" → PlainText (long)
"content", "bio", "article" → RichText
"photo", "image", "thumbnail" → Image
"gallery", "photos" → MultiImage
"document", "PDF", "file" → File
"video" → Video
"link", "URL", "website" → Link
"email" → Email
"phone", "mobile" → Phone
"price", "cost", "amount" → Number
"date", "published", "deadline" → DateTime
"featured", "active", "published" → Switch
"status", "type", "category" → Option (if fixed choices)
"color", "theme" → Color
Multi-Reference Limit Check:
Count multi-reference fields requested:
If > 5:
⚠️ Warning: Collection Limit Exceeded
Webflow allows max 5 multi-reference fields per collection.
You requested: 7 multi-reference fields
Options:
1. Choose 5 most important relationships
2. Convert some to reference fields (one-to-many)
3. Create bridging collections
4. Use option fields for simple categorization
Which would you prefer?
Dependency Resolution:
For reference fields:
1. Check if referenced collection exists
2. If not, add to creation queue
3. Create in correct order
Example:
Products needs:
- Categories collection (create first)
- Brands collection (create first)
Then create Products
Phase 4: Preview Best Practices
Complete Preview Format:
📋 Preview: Create "[Collection Name]"
Collection Details:
├── Display Name: [Name]
├── Singular Name: [Singular]
├── Slug: [slug]
└── Site: [Site Name]
Fields ([X] total):
├── name (PlainText, required) ← Auto-created
├── slug (PlainText, required) ← Auto-created
├── [field-1] ([Type], [required/optional])
├── [field-2] ([Type], [required/optional])
│ [Additional info if Option or Reference]
└── [field-n] ([Type], [required/optional])
Relationships:
├── [field] → [Collection] (Reference)
└── [field] → [Collection] (MultiReference)
✅ Validation Results:
- Collection name available: Yes
- Within plan limits: X/Y collections
- Multi-reference count: X/5
- All field types valid: Yes
- Dependencies resolved: Yes
⚠️ Type "create" to proceed.
Validation Checks:
Before showing preview:
1. ✅ Collection name available
2. ✅ Within plan collection limit
3. ✅ All field types supported
4. ✅ Multi-reference limit ≤ 5
5. ✅ Referenced collections exist or queued
6. ✅ No circular dependencies
7. ✅ Field names follow conventions
Phase 5: Creation Best Practices
Collection Creation:
Required fields:
- displayName (required)
- singularName (required)
- slug (optional, auto-generated if omitted)
Always include both names for clarity:
✅ {"displayName": "Blog Posts", "singularName": "Blog Post"}
❌ {"displayName": "Blog Posts"} (missing singular)
Error Handling:
If collection creation fails:
❌ Collection Creation Failed
Error: [Error message from API]
Common causes:
- Collection name already exists
- Invalid characters in name/slug
- Plan limit reached
- API authentication issue
Would you like to:
1. Try a different collection name
2. Check existing collections
3. Upgrade plan
4. Cancel operation
Phase 6: Field Creation Best Practices
Field Creation Order:
Create fields in this order:
1. Static fields (Text, Rich Text, Number, etc.)
2. Option fields (with options defined)
3. Reference fields (after referenced collections exist)
For each field:
- Set displayName
- Set isRequired flag
- Add helpText if provided by user
- Set validation rules if applicable
Field Creation Tools:
Field Type → Tool to use:
PlainText, RichText, Email, Phone, Link, Number,
Image, MultiImage, File, Video, DateTime, Switch, Color
→ data_cms_tool with action create_collection_static_field
Option
→ data_cms_tool with action create_collection_option_field
(requires metadata.options array)
Reference, MultiReference
→ data_cms_tool with action create_collection_reference_field
(requires metadata.collectionId)
Progress Reporting:
For each field created:
✅ [field-name] ([FieldType])
If field fails:
❌ [field-name] - [Error message]
Continue with remaining fields even if one fails.
Report all failures at end.
Option Field Creation:
{
"type": "Option",
"displayName": "Status",
"isRequired": false,
"metadata": {
"options": [
{"name": "Draft"},
{"name": "Published"},
{"name": "Archived"}
]
}
}
Notes:
- Options have name property
- Options cannot have ID (auto-generated)
- Minimum 2 options required
- Maximum: unlimited
Reference Field Creation:
{
"type": "Reference",
"displayName": "Author",
"isRequired": true,
"metadata": {
"collectionId": "abc123..."
}
}
For MultiReference:
{
"type": "MultiReference",
"displayName": "Tags",
"metadata": {
"collectionId": "def456..."
}
}
Notes:
- Must provide collectionId of referenced collection
- Referenced collection must already exist
- Max 5 MultiReference fields per collection
Phase 7: Verification Best Practices
Post-Creation Verification:
After creating collection and fields:
1. Call data_cms_tool with action get_collection_details with collection ID
2. Verify all fields present
3. Check field properties match request
4. Confirm relationships configured correctly
Final Report Format:
🎉 Collection Setup Complete!
Collection: [Name]
ID: [collection-id]
Slug: [slug]
Fields Created ([X]):
├── name (PlainText, required) ← Auto
├── slug (PlainText, required) ← Auto
├── [field-1] ([Type])
├── [field-2] ([Type])
└── [field-n] ([Type])
[If relationships exist]
Relationships:
├── [field] → [Collection]
└── [field] → [Collection]
[If any failures]
⚠️ Failed Fields ([Y]):
├── [field]: [error]
└── [field]: [error]
---
💡 Next Steps:
[Relevant suggestions based on collection type]
Next Steps Suggestions:
For any collection:
1. Use bulk-cms-update to add initial items
2. Create collection template page in Designer
3. Create collection list page
4. Configure SEO settings
For collections with relationships:
5. Create referenced collections first
6. Add items in dependency order
7. Test relationship displays
For e-commerce:
5. Set up payment integration
6. Configure inventory management
7. Create checkout flow
Phase 8: Error Handling
Common Errors:
1. Collection Name Conflict:
❌ Collection Already Exists
A collection named "Blog Posts" already exists on this site.
Existing collection:
- Name: Blog Posts
- ID: xyz789...
- Created: 2025-12-15
Would you like to:
1. Choose a different name
2. View existing collection
3. Add fields to existing collection
4. Cancel
2. Plan Limit Reached:
❌ Plan Limit Reached
Cannot create collection. You've reached your plan limit.
Current: 20/20 collections (CMS Plan)
Options:
1. Upgrade to Business Plan (40 collections)
2. Delete unused collections
3. Contact Webflow support
Would you like me to show your existing collections?
3. Invalid Field Type:
❌ Invalid Field Type
Field type "dropdown" is not supported by Webflow.
Did you mean:
- "Option" - Single choice from list
- "Reference" - Link to another collection
- "MultiReference" - Link to multiple items
Which would you like to use?
4. Referenced Collection Not Found:
❌ Referenced Collection Not Found
Cannot create reference field to "Authors" collection.
Issue: "Authors" collection doesn't exist yet.
Solutions:
1. Create "Authors" collection first
2. Remove reference field for now
3. Let me create both collections in order
Your choice? (1/2/3)
5. Multi-Reference Limit Exceeded:
❌ Too Many Multi-Reference Fields
You requested 6 multi-reference fields.
Webflow limit: 5 per collection
Requested:
1. Tags
2. Categories
3. Related Products
4. Features
5. Certifications
6. Compatible Products ← Exceeds limit
Choose 5 to keep, or convert one to Reference field.
Phase 9: Advanced Scenarios
Self-Referencing Collections:
Example: Categories with parent categories
Collection: Categories
Fields:
├── name (PlainText, required)
├── slug (PlainText, required)
├── parent-category (Reference → Categories)
└── level (Number) - 1, 2, 3 for hierarchy
Implementation:
{
"type": "Reference",
"displayName": "Parent Category",
"isRequired": false,
"metadata": {
"collectionId": "[same-collection-id]"
}
}
Note: Must create collection first, then add self-reference field
Multi-Collection Setup:
When creating multiple related collections:
1. Identify dependencies:
- Which collections reference others?
- What's the creation order?
2. Create in order:
- Independent collections first
- Dependent collections after
3. Show overall progress:
[1/4] Creating Categories...
[2/4] Creating Brands...
[3/4] Creating Tags...
[4/4] Creating Products...
4. Report collectively:
All 4 collections created successfully!
Complex Option Fields:
For complex dropdowns:
User: "Create status field with Draft, In Review, Approved, Published, Archived"
Option field with 5 choices:
{
"type": "Option",
"displayName": "Status",
"isRequired": true,
"metadata": {
"options": [
{"name": "Draft"},
{"name": "In Review"},
{"name": "Approved"},
{"name": "Published"},
{"name": "Archived"}
]
}
}
Tip: Use workflow order for options
Production Checklist
Before considering collection setup complete:
✅ Discovery
- Site selected and confirmed
- Plan limits checked
- Existing collections listed
- No naming conflicts
- User has appropriate permissions
✅ Requirements
- Display name gathered
- Singular name gathered
- All fields defined with types
- Required vs optional specified
- Relationships identified
✅ Validation
- All field types valid
- Multi-reference count ≤ 5
- Referenced collections exist or queued
- No circular dependencies
- Field names follow conventions
- Within plan limits
✅ Preview
- Complete schema shown
- All fields listed with properties
- Relationships displayed
- Validation results shown
- User confirmation obtained
✅ Creation
- Collection created successfully
- Collection ID captured
- All fields created
- Field creation errors handled
- Progress shown to user
✅ Verification
- Collection retrieved and verified
- All fields present
- Field properties correct
- Relationships configured
- Any errors reported
✅ Reporting
- Final summary provided
- Collection ID shared
- Fields listed
- Failures reported (if any)
- Next steps suggested
✅ Error Handling
- Collection conflicts handled
- Plan limits checked
- Invalid field types caught
- Missing references detected
- Partial failures reported
Code Component
Create, build, and deploy React components to Webflow Designer with comprehensive validation and deployment verification.
Important Note
ALWAYS use Bash tool for all Webflow CLI operations:
- Execute
webflowCLI commands via Bash tool - Use Read tool to examine generated files (never modify)
- Use Glob tool to discover project files
- Verify CLI installation:
webflow --version - Check authentication: On first
webflow library share, workspace authentication happens automatically - DO NOT use Webflow MCP tools for CLI workflows
- All CLI commands require proper descriptions (not context parameters)
Package Manager Detection:
- Check for lock files:
package-lock.json(npm),pnpm-lock.yaml(pnpm),yarn.lock(yarn) - If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
- Use detected package manager for all install/build commands
Instructions
Phase 1: Environment Verification
- Verify CLI installed: Run
webflow --versionto confirm CLI is installed - Check project state: Determine if user has existing React project or needs guidance
- Identify workspace: Explain that workspace authentication happens on first share
- Review configuration: Check if webflow.json exists with library configuration
Phase 2: Project Configuration
- Ask operation type: Clarify what user wants to do:
- Configure existing React project for Code Components
- Add components to already-configured project
- Build and share existing library
- Configure webflow.json: Add library configuration to webflow.json:
- Library name (appears in Webflow Designer)
- Components glob pattern (e.g.,
./src/**/*.webflow.tsx) - Optional bundleConfig for custom webpack
- Read configuration files: Use Read tool to show:
webflow.json- Library configurationpackage.json- Dependencies and scripts- Component file structure
- Verify dependencies: Ensure React is installed and build scripts exist
Phase 3: Build & Bundle Validation
- Run build: Execute user's build command (e.g.,
npm run build,yarn build) - Validate build output: Check for build errors or warnings
- Run bundle command: Execute
webflow library bundlefor local validation - Analyze bundle:
- Bundle size (should be < 2MB)
- Dependencies included
- Output location (default:
./dist) - Validation warnings
- Preview bundle details: Show bundle summary with validation status
Phase 4: Preview & Approval
- Show deployment preview:
- Library name from webflow.json
- Component files included
- Bundle size and validation status
- Target workspace (will be selected on first share)
- Explain workspace authentication if first time
- Explain deployment: What happens when library is shared
- Require explicit confirmation: User must type "share" or "deploy" to proceed
- Confirm workspace: Explain browser will open for workspace selection (first time only)
Phase 5: Deployment & Verification
- Execute share command: Run
webflow library share - Monitor deployment: Show CLI output and progress
- Handle workspace auth: If first time, guide user through browser authentication
- Verify deployment success: Confirm library appears in workspace
- Show .env updates: Explain WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_TOKEN added
- Provide next steps:
- How to use components in Designer
- How to update components
- Testing recommendations
- Using
webflow library logfor debugging
Examples
Example 1: Configure Existing React Project
User prompt:
I have a React project with some components I want to share to Webflow
Step 1: Environment Verification
🔍 Webflow CLI Environment Check
Checking CLI installation...
✓ Webflow CLI installed: v1.5.2
Current directory: /Users/user/projects/my-components
✓ Found package.json with React project
✓ Found src/ directory with components
Checking webflow.json...
⚠️ No webflow.json found - needs configuration
Ready to configure for Code Components? (yes/no)
User confirms: yes
Step 2: Project Configuration
📋 Configure Code Components Library
I'll help you add the library configuration to webflow.json.
Questions:
1. What should your library be called in Webflow Designer?
Example: "My Component Library"
2. Where are your component files located?
Pattern examples:
- "./src/**/*.webflow.tsx" (components with .webflow.tsx extension)
- "./src/components/**/*.tsx" (all components in src/components/)
- "./src/Button.tsx" (specific files)
Let me know the library name and component pattern.
User provides: "Acme Components" and "./src/**/.webflow.tsx"*
Creating webflow.json configuration...
{
"library": {
"name": "Acme Components",
"components": ["./src/**/*.webflow.tsx"]
}
}
✓ Configuration ready
Found component files:
- src/Button.webflow.tsx
- src/Card.webflow.tsx
- src/Hero.webflow.tsx
Next: Build your components and run bundle command.
Step 3: Build & Bundle Validation
🔨 Building Components
What build command do you use? (e.g., npm run build, yarn build)
User responds: npm run build
Executing: npm run build
Output:
✓ TypeScript compilation successful
✓ Components built to dist/
Creating bundle for validation...
Executing: webflow library bundle
Output:
✓ Analyzing 3 components
✓ Bundling dependencies
✓ Creating bundle
✓ Bundle created: dist/bundle.js
📦 Bundle Analysis:
- Size: 287 KB (✓ within 2MB limit)
- Components: 3 (Button, Card, Hero)
- Dependencies: react@18.2.0, react-dom@18.2.0
- Output: ./dist
- Validation: ✅ All checks passed
Step 4: Preview & Approval
📋 Deployment Preview
Library: Acme Components
Components: 3 (Button, Card, Hero)
Bundle Size: 287 KB
Workspace Authentication:
⚠️ This appears to be your first deployment. When you run 'share':
1. Browser will open for workspace authentication
2. Select your target Webflow workspace
3. Grant access to deploy components
4. CLI will create .env with credentials:
- WEBFLOW_WORKSPACE_ID
- WEBFLOW_WORKSPACE_API_TOKEN
Validation Status: ✅ Ready to deploy
- Bundle size: ✓ 287 KB (< 2MB limit)
- Dependencies: ✓ Valid (React 18.2.0)
- Configuration: ✓ webflow.json valid
- Components: ✓ 3 components found
⚠️ Type "share" to deploy this library to your workspace.
User confirms: share
Step 5: Deployment & Verification
🚀 Deploying Library
Executing: webflow library share
Output:
✓ Bundling library (287 KB)
✓ Opening browser for workspace authentication...
[Browser opens - user authenticates and selects workspace]
✓ Workspace authenticated: Acme Corp
✓ Uploading bundle
✓ Validating components
✓ Registering with workspace
✓ Library deployed successfully
✅ Library Deployed: Acme Components
Workspace: Acme Corp
Components: 3 (Button, Card, Hero)
Version: Latest
Status: Active
📁 Environment Updated:
Created .env file with:
- WEBFLOW_WORKSPACE_ID=workspace_abc123
- WEBFLOW_WORKSPACE_API_TOKEN=************
⚠️ Important: Add .env to your .gitignore file!
📋 Next Steps:
1. Open Webflow Designer
2. Go to Add Elements → Code Components
3. Find "Acme Components" in the list
4. Drag components onto canvas to use
💡 To update components:
1. Make changes to your component files
2. Run: npm run build
3. Run: webflow library share
(No re-authentication needed - uses .env credentials)
🔍 For debugging:
- View logs: webflow library log
- Bundle locally: webflow library bundle
- Check bundle size: webflow library bundle --verbose
Component Library URL: https://webflow.com/dashboard/workspaces/acme-corp/components
Example 2: Update Existing Library
User prompt:
Update my Code Components library with new changes
Step 1: Environment Verification
🔍 Code Components Library Check
Checking configuration...
✓ webflow.json found with library config
✓ Library name: Acme Components
✓ Components pattern: ./src/**/*.webflow.tsx
Checking authentication...
✓ Found .env with workspace credentials
✓ Workspace: Acme Corp
Found components:
- src/Button.webflow.tsx (modified)
- src/Card.webflow.tsx
- src/Hero.webflow.tsx
- src/Form.webflow.tsx (new)
Ready to build and share updates? (yes/no)
Step 2-3: Build & Bundle
🔨 Building Components
Executing: npm run build
✓ Build complete
Bundling for validation...
Executing: webflow library bundle
📦 Bundle Analysis:
- Size: 312 KB (✓ within 2MB limit)
- Components: 4 (Button, Card, Hero, Form) [+1 new]
- Changes: Button updated, Form added
- Validation: ✅ All checks passed
Step 4: Preview
📋 Update Preview
Library: Acme Components
Workspace: Acme Corp (already authenticated)
Changes:
✓ Button component (updated)
✓ Form component (new)
Card component (unchanged)
Hero component (unchanged)
Bundle Size: 312 KB (+25 KB from 287 KB)
No re-authentication needed - using existing workspace credentials.
⚠️ Type "share" to update the library.
Step 5: Deployment
🚀 Updating Library
Executing: webflow library share
Output:
✓ Bundling library (312 KB)
✓ Using workspace: Acme Corp
✓ Uploading bundle
✓ Validating components
✓ Updating library
✓ Library updated successfully
✅ Library Updated: Acme Components
Changes deployed:
- Button: Updated ✨
- Form: Added 🆕
- Card: Unchanged
- Hero: Unchanged
💡 Refresh Webflow Designer to see changes:
1. Open Designer
2. Components may auto-refresh
3. Or refresh browser if needed
Components updated in workspace!
Example 3: First-Time Bundle Testing
User prompt:
I want to test my bundle locally before sharing
Step 1-2: Verification & Configuration
🔍 Local Bundle Testing
✓ webflow.json configured
✓ Library: My Components
✓ Components: ./src/**/*.webflow.tsx
Running local bundle only (no deployment)...
Step 3: Bundle Validation
🔨 Building Components
Executing: npm run build
✓ Build complete
Creating local bundle...
Executing: webflow library bundle
Output:
✓ Analyzing components
✓ Bundling dependencies
✓ Optimizing output
✓ Bundle created: dist/bundle.js
📦 Bundle Details:
Size: 1.2 MB (✓ within 2MB limit)
Components (5):
├── Button.webflow.tsx (25 KB)
├── Card.webflow.tsx (18 KB)
├── Hero.webflow.tsx (45 KB)
├── Form.webflow.tsx (32 KB)
└── Modal.webflow.tsx (28 KB)
Dependencies:
├── react@18.2.0 (included)
├── react-dom@18.2.0 (included)
└── classnames@2.3.1 (included)
Output Directory: ./dist/
- bundle.js (1.2 MB)
- manifest.json
Validation: ✅ All checks passed
💡 Bundle is valid and ready to share!
Run: webflow library share (when ready to deploy)
Example 4: Bundle Too Large
User prompt:
Share my components library
Bundle Validation Error:
🔨 Building and Bundling
Executing: npm run build
✓ Build complete
Executing: webflow library bundle
Output:
✓ Analyzing components
✓ Bundling dependencies
⚠️ Bundle size check...
📦 Bundle Analysis:
- Size: 2.4 MB (❌ exceeds 2MB limit)
- Components: 6
- Dependencies: react@18.2.0, react-dom@18.2.0, lodash@4.17.21, moment@2.29.4
- Validation: ❌ Issues found
❌ Bundle Too Large
Current size: 2.4 MB
Maximum allowed: 2 MB
Exceeded by: 400 KB
📊 Size Breakdown:
- React + React DOM: ~800 KB
- lodash: ~500 KB ⚠️
- moment: ~350 KB ⚠️
- Your components: ~750 KB
💡 Recommendations:
1. Remove lodash (use native JS instead)
- Replace _.map with Array.map
- Replace _.filter with Array.filter
- Or use lodash-es and import specific functions
2. Replace moment with lighter alternative
- Use date-fns (~15 KB vs 350 KB)
- Or use native Intl.DateTimeFormat
3. Optimize component code
- Remove unused imports
- Enable tree-shaking
- Split large components
4. Use external assets
- Host large images externally
- Use CDN for static assets
Would you like to:
1. Continue anyway (using --force flag, not recommended)
2. Review component imports to optimize
3. Cancel and fix manually
Example 5: CI/CD Deployment
User prompt:
How do I deploy in CI/CD pipeline?
Response:
🤖 CI/CD Deployment Setup
For automated deployments, use non-interactive mode with API tokens.
### Setup Steps:
1. **Get Workspace API Token**
- Open Workspace Settings in Webflow
- Go to Integrations → Workspace API Token
- Generate new token
- Copy token securely
2. **Add to CI/CD Secrets**
- Add as environment variable: WORKSPACE_API_TOKEN
- Never commit tokens to version control
3. **Deployment Command**
```bash
webflow library share --api-token $WORKSPACE_API_TOKEN --no-input
Example: GitHub Actions
name: Deploy Components
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v3
- name: Setup Node
uses: actions/setup-node@v3
with:
node-version: 18
- name: Install dependencies
run: npm install
- name: Install Webflow CLI
run: npm install -g @webflow/webflow-cli
- name: Build components
run: npm run build
- name: Deploy to Webflow
run: |
webflow library share \
--api-token ${{ secrets.WORKSPACE_API_TOKEN }} \
--no-input \
--force
env:
WORKSPACE_API_TOKEN: ${{ secrets.WORKSPACE_API_TOKEN }}
Multiple Workspaces:
# Deploy to workspace 1
webflow library share \
--api-token $WORKSPACE_1_TOKEN \
--no-input
# Deploy to workspace 2
webflow library share \
--api-token $WORKSPACE_2_TOKEN \
--no-input
Options:
--no-input- Disables interactive prompts--force- Continues even with warnings--verbose- Shows detailed output--dev- Bundles in development mode (for testing)
⚠️ Security:
- Never commit .env files
- Use secrets management in CI/CD
- Rotate tokens regularly
- Limit token permissions
## Guidelines
### Phase 1: CLI Verification
**Installation Check:**
```bash
# Check if CLI is installed
webflow --version
# If not installed, guide user:
npm install -g @webflow/webflow-cli
Project Check:
# Check for existing configuration
ls webflow.json
# Check for React project
ls package.json
# Check for components
ls src/
Authentication Note:
Unlike site authentication, workspace authentication for Code Components happens automatically on first webflow library share. The CLI will:
- Open browser for authentication
- Let user select workspace
- Create .env with WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_TOKEN
Phase 2: Project Configuration
webflow.json Structure:
{
"library": {
"name": "<Your Library Name>",
"components": ["./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"],
"bundleConfig": "./webpack.webflow.js"
}
}
Configuration Fields:
- name (required): Library name as it appears in Webflow Designer
- components (required): Glob pattern matching component files
- Example:
"./src/**/*.webflow.tsx"- all .webflow.tsx files in src/ - Example:
"./src/components/**/*.tsx"- all .tsx files in src/components/
- Example:
- bundleConfig (optional): Path to custom webpack configuration
Component Naming Convention:
- Add
.webflowbefore extension:Button.webflow.tsx - Or use glob pattern to include all files in specific directory
- Components must be React components
No Init Command:
Unlike other CLI products, Code Components don't have an init command. Users configure existing React projects by adding webflow.json with library configuration.
Phase 3: Build & Bundle
Build Process:
# Use project's build script
npm run build
# or
yarn build
# or
pnpm build
# Check for errors
echo $? # 0 = success, non-zero = failure
Bundle Command:
# Bundle locally (optional - for testing/validation)
webflow library bundle
# Bundle output: ./dist/ (default)
# Can override: webflow library bundle --output-path ./build
Bundle Options:
--output-path <path>- Override output directory (default:./dist)--public-path <path>- Override public path--force- Force bundling even with warnings--debug-bundler- Show webpack configuration--dev- Bundle in development mode--verbose- Show detailed output
Bundle Validation: Check these aspects:
- Size limit: Must be < 2MB
- Dependencies: React versions compatible
- Output: Bundle created in dist/ directory
- Components: All component files included
Common Build Errors:
- TypeScript compilation errors → Fix type issues
- Missing dependencies → Run npm install
- Import errors → Check file paths
- Bundle too large → Optimize dependencies
Phase 4: Deployment Preview
Preview Format:
📋 Deployment Preview
Library: [Name from webflow.json]
Components: [Count] ([List of components])
Bundle Size: [Size in KB/MB]
Workspace Authentication:
[First time: Explain browser auth flow]
[Subsequent: Show workspace from .env]
Validation Status:
✓ Bundle size: [X KB] (< 2MB limit)
✓ Dependencies: Valid
✓ Configuration: webflow.json valid
✓ Components: [N] components found
⚠️ Type "share" to proceed
First-Time Authentication: Explain clearly:
- Browser will open
- User authenticates with Webflow
- User selects target workspace
- CLI creates .env with credentials
- Future shares use these credentials (no re-auth)
Phase 5: Deployment Execution
Share Command:
# Standard share (interactive)
webflow library share
# Non-interactive (for CI/CD)
webflow library share --api-token <TOKEN> --no-input
# Force share (ignore warnings)
webflow library share --force
# Development mode
webflow library share --dev
Share Options:
--manifest- Path to webflow.json (default: scans current directory)--api-token- Workspace API token (for CI/CD)--no-input- Disable interactive prompts--force- Force bundling even with warnings--debug-bundler- Show bundler configuration--dev- Bundle in development mode--verbose- Show detailed output
Success Indicators:
- Bundle uploaded successfully
- Library registered in workspace
- Components available in Designer
- .env file created/updated (first time)
Environment File (.env): After first successful share:
WEBFLOW_WORKSPACE_ID=your-workspace-id
WEBFLOW_WORKSPACE_API_TOKEN=your-api-token
⚠️ Critical: Always add .env to .gitignore!
Verification Steps:
- Check CLI output for success message
- Verify .env file created (first time)
- Provide Designer access instructions
- Show workspace dashboard URL
Phase 6: Debugging
Log Command:
# Show latest log file location
webflow library log
# Example output:
# Latest log: /Users/user/.webflow/logs/library-2024-01-20-15-30-45.log
Use this command when:
- Bundle fails with unclear error
- Share command produces warnings
- Need to debug webpack configuration
- Investigating dependency issues
Common Issues:
Issue: "Could not find webflow.json"
❌ Configuration Not Found
The CLI couldn't find webflow.json in the current directory.
Solution:
1. Ensure you're in the project root
2. Create webflow.json with library configuration:
{
"library": {
"name": "Your Library Name",
"components": ["./src/**/*.webflow.tsx"]
}
}
3. Run command again
Issue: "No components found"
❌ No Components Found
The components glob pattern didn't match any files.
Current pattern: "./src/**/*.webflow.tsx"
Solution:
1. Check component files have correct naming
2. Verify glob pattern in webflow.json
3. Common patterns:
- "./src/**/*.webflow.tsx" (requires .webflow in name)
- "./src/components/**/*.tsx" (all tsx in folder)
- "./src/Button.tsx" (specific file)
Found files:
- src/Button.tsx (not matching pattern)
- src/Card.tsx (not matching pattern)
Suggestion: Rename to Button.webflow.tsx or update pattern
Error Handling
CLI Not Installed:
❌ Webflow CLI Not Found
The Webflow CLI is required for Code Components.
Installation:
npm install -g @webflow/webflow-cli
After installation, verify:
webflow --version
Documentation: https://developers.webflow.com/cli
Build Failures:
❌ Build Failed
Error: [Specific error message]
Common Fixes:
- TypeScript errors: Review type definitions
- Missing deps: Run npm install
- Import errors: Check file paths
- Syntax errors: Check React component syntax
Show build output for details.
Need help? Run: webflow library log
Bundle Failures:
❌ Bundle Failed
Error: [Specific error from CLI]
Common Causes:
- Invalid component files
- Webpack configuration errors
- Dependency conflicts
- File path issues
View detailed logs: webflow library log
Possible solutions:
1. Check component file syntax
2. Verify webflow.json configuration
3. Remove bundleConfig to use defaults
4. Check dependencies in package.json
Deployment Failures:
❌ Share Failed
Error: [Specific error from CLI]
Possible Causes:
- Network connection issues
- Workspace authentication expired
- Bundle validation failed
- Workspace permissions
Solutions:
1. Check internet connection
2. Re-authenticate: Remove .env and run share again
3. Fix bundle issues: Run webflow library bundle first
4. Verify workspace access in Webflow dashboard
Retry share? (yes/no)
File Operations
Reading Files: Always use Read tool (never modify):
# View library configuration
Read: webflow.json
# View package dependencies
Read: package.json
# View component source
Read: src/Button.webflow.tsx
# View environment (if exists)
Read: .env
Discovering Files: Use Glob tool to find files:
# Find all webflow components
Glob: **/*.webflow.tsx
# Find configuration files
Glob: *.json
# Find source files
Glob: src/**/*
# Find build output
Glob: dist/**/*
Never Use Write/Edit Tools:
- Don't create webflow.json with Write (show user the structure)
- Don't modify component files
- Don't edit package.json
- Let user make file changes
- Only read files to show content
Progress Indicators
For Bundling:
🔄 Bundling Components...
Analyzing components... ✓
Resolving dependencies... ✓
Building bundle... ⏳
Optimizing... ⏳
Elapsed: 8s
For Deployment:
🚀 Sharing Library...
Creating bundle... ✓
Uploading to workspace... ⏳
Validating components... ⏳
Uploaded: 287 KB
Elapsed: 12s
Safety Patterns
Confirmation Keywords:
- "share" - Share library to workspace
- "deploy" - Alternative to "share"
- "proceed" - Continue with operation
- "cancel" - Cancel operation
- "skip" - Skip optional step
Preview Before Share: Always show:
- What will be shared (library name, components)
- Where it will go (workspace, or first-time auth needed)
- Bundle size and validation status
- Impact of changes (new/updated components)
Transparency:
- Show all CLI commands before execution
- Display CLI output in full
- Report success/failure clearly
- Provide troubleshooting guidance
- Show log location for debugging
Best Practices
Component Development:
- Use TypeScript for type safety
- Follow React best practices
- Keep bundle size small (< 1MB ideal)
- Name files with .webflow extension for clarity
- Document component props
Dependency Management:
- Keep dependencies minimal
- Avoid large libraries (lodash, moment)
- Use tree-shakeable packages
- Check bundle impact:
webflow library bundle --verbose - Peer dependencies for React (not bundled)
Updates and Versioning:
- Build before sharing
- Test bundle locally:
webflow library bundle - Share to update:
webflow library share - No version numbers needed (always "latest")
- Test in Designer after deployment
Workspace Management:
- One workspace per .env file
- Use --api-token for multiple workspaces
- Add .env to .gitignore
- Rotate tokens in CI/CD
- Document which workspace is configured
Configuration:
- Keep webflow.json in project root
- Use clear library names
- Use specific component glob patterns
- Add bundleConfig only if needed
- Version control webflow.json (not .env)
Component Lifecycle
Initial Setup:
- Create/have React project
- Add webflow.json with library configuration
- Name component files (e.g., .webflow.tsx)
- Build:
npm run build - Test bundle:
webflow library bundle - Share:
webflow library share(authenticates first time)
Making Updates:
- Edit component source files
- Build:
npm run build - Share:
webflow library share(uses saved credentials) - Refresh Designer to see changes
Testing:
- Bundle locally:
webflow library bundle - Check bundle size and validation
- Fix any issues
- Share when ready:
webflow library share - Open Webflow Designer
- Add components to page
- Test functionality
Debugging:
- View logs:
webflow library log - Bundle with verbose:
webflow library bundle --verbose - Check configuration: cat webflow.json
- Verify build: npm run build
- Test in development mode:
webflow library share --dev
CLI Command Reference
Installation:
# Install CLI globally
npm install -g @webflow/webflow-cli
# Verify installation
webflow --version
Library Commands:
# Bundle locally (testing/validation)
webflow library bundle [options]
# Share to workspace (bundle + deploy)
webflow library share [options]
# View latest log file
webflow library log
Bundle Options:
# Custom output path
webflow library bundle --output-path ./build
# Force bundling (ignore warnings)
webflow library bundle --force
# Development mode
webflow library bundle --dev
# Show bundler config
webflow library bundle --debug-bundler
# Verbose output
webflow library bundle --verbose
Share Options:
# Standard interactive share
webflow library share
# Non-interactive (CI/CD)
webflow library share --no-input --api-token <TOKEN>
# Force share (ignore warnings)
webflow library share --force
# Development mode
webflow library share --dev
# Custom manifest location
webflow library share --manifest ./config/webflow.json
Global Options:
# Show version
webflow --version
# Show help
webflow --help
webflow library --help
webflow library share --help
Quick Reference
Workflow: configure webflow.json → build → bundle → share
Key Commands:
webflow library bundle- Bundle locally for testingwebflow library share- Bundle and deploy to workspacewebflow library log- View debug logs
Configuration: webflow.json with library section
Authentication: Automatic on first webflow library share (opens browser)
Environment: WEBFLOW_WORKSPACE_ID and WEBFLOW_WORKSPACE_API_TOKEN in .env
Verification: Always check webflow --version first
Preview: Show bundle details before sharing
Confirmation: Require "share" keyword to proceed
Documentation: https://developers.webflow.com/code-components/introduction
Component Audit
Audit existing code components for Webflow-specific architecture decisions. This skill focuses on how well components integrate with Webflow Designer, not generic React best practices.
When to Use This Skill
Use when:
- User wants to improve how their components work in Webflow Designer
- Reviewing whether the right things are exposed as props vs hardcoded
- Checking if state management patterns are Webflow-compatible
- Looking for opportunities to make components more designer-friendly
- Component isn't rendering or behaving as expected in Webflow
Do NOT use when:
- Validating before deployment (use pre-deploy-check instead)
- Creating new components (use component-scaffold instead)
- Converting a React component (use convert-component instead)
- Generic code quality review (use a linter)
Core Philosophy
This audit answers three questions:
- Designer Control: Are the right things exposed as props for designers to customize?
- Webflow Compatibility: Does the component work within Webflow's constraints (Shadow DOM, SSR, isolated React roots)?
- Component Architecture: Is this the right level of granularity, or should it be split/combined?
Instructions
Phase 1: Discovery
-
Find all components:
- Locate webflow.json
- Find all .webflow.tsx files
- Read corresponding React components
-
Understand intent: Ask user what the components are for and any specific concerns
Phase 2: Analysis
For each component, analyze these Webflow-specific areas:
A. Prop Exposure Analysis
Goal: Identify what designers SHOULD be able to control but currently can't.
| Look For | Recommendation |
|---|---|
| Hardcoded text strings | Expose as props.Text() |
| Text that designers should edit on canvas | Expose as props.RichText() |
| Hardcoded values from a fixed set of options | Expose as props.Variant({ options: [...] }) |
| Hardcoded image URLs | Expose as props.Image() |
| Hardcoded link URLs | Expose as props.Link() |
Hardcoded HTML id attributes | Expose as props.Id() |
| Conditional rendering with boolean | Expose as props.Boolean() or props.Visibility() |
| Internal state that affects appearance | Consider exposing initial value as prop |
children not using Slot | Convert to props.Slot() |
Aliases:
props.String=props.Text,props.Children=props.Slot. Treat these as equivalent during audit.
Questions to ask:
- "What would a designer want to change?"
- "What requires a code change that shouldn't?"
B. State Management Architecture
Goal: Identify patterns that won't work in Webflow.
| Anti-Pattern | Why It Fails | Alternative |
|---|---|---|
| React Context for cross-component state | Each component has isolated React root | Use nano stores, custom events, or URL params |
| Prop drilling through Slots | Slot children are separate React apps | Use nano stores or custom events |
| Shared state via module-level variables | May cause SSR issues | Use browser storage or nano stores |
| Global event listeners without cleanup | Memory leaks, SSR issues | Use useEffect with cleanup |
Refactoring recommendations:
- If components need to communicate → suggest cross-component state pattern
- If using Context internally only → that's fine, document it
- If components are tightly coupled → suggest decomposition
C. Slot Opportunities
Goal: Identify hardcoded content that should be designer-controlled.
| Current Pattern | Better Pattern |
|---|---|
| Hardcoded button inside card | Slot for actions area |
| Hardcoded icon component | Slot or Image prop |
| Fixed header/footer structure | Slots for header and footer |
| Hardcoded list items | Consider if this should be multiple components |
When NOT to use Slots:
- When content has specific behavioral requirements
- When content needs to interact with component state
- When the structure is truly fixed and not customizable
D. Shadow DOM Compatibility
Goal: Ensure styles work in isolation.
| Issue | Detection | Fix |
|---|---|---|
| Using site/global CSS classes | Class names like .container, .btn | Use CSS Modules or component-scoped styles |
| CSS-in-JS not configured | styled-components/Emotion without decorator | Add globals.ts with styledComponentsShadowDomDecorator (styled-components) or emotionShadowDomDecorator (Emotion/MUI) |
| Missing style imports | Styles defined but not imported in .webflow.tsx | Add import statement |
| Relying on inherited styles | Expecting parent styles to cascade | Use explicit styles or CSS variables |
| Needs tag selectors (h1, p, etc.) | Tags not styled inside Shadow DOM | Enable applyTagSelectors: true in component options |
SSR Note: When using styled-components or Emotion, you must also configure the server renderer in
webflow.jsonfor SSR to work correctly:
- styled-components:
"library": { "renderer": { "server": "@webflow/styled-components-utils/server" } }- Emotion:
"library": { "renderer": { "server": "@webflow/emotion-utils/server" } }
E. SSR Safety
Goal: Identify browser-only code that runs during render.
| Pattern | Problem | Solution |
|---|---|---|
window.innerWidth in render | SSR error | Use useEffect or set ssr: false |
document.getElementById in render | SSR error | Use useEffect or refs |
localStorage.getItem outside useEffect | SSR error | Wrap in useEffect with useState |
| Third-party library that requires window | SSR error | Dynamic import or ssr: false |
F. Component Granularity
Goal: Determine if component is at the right level of abstraction.
Signs a component should be SPLIT:
- Too many props (>10) making Designer UI cluttered
- Multiple distinct sections that could be independent
- Designers want to use parts separately
- Component handles multiple unrelated concerns
Signs components should be COMBINED:
- Always used together
- Tightly coupled state that's awkward to sync
- Small components with no standalone use
Phase 3: Report
Generate actionable report with:
- Summary: Quick overview of findings
- By Component: Specific issues and recommendations for each
- Architecture Recommendations: Cross-cutting concerns
- Priority Actions: What to fix first
Audit Checklist
Designer Control (Most Important for Webflow)
| Check | Question |
|---|---|
| Prop completeness | Can designers customize everything they'd want to? |
| Prop types | Are the right Webflow prop types used? |
| Default values | Do props have sensible defaults? |
| Prop naming | Are names clear for non-developers? |
| Slot usage | Is nested content handled via Slots? |
| Visibility props | Can sections be shown/hidden? |
Webflow Compatibility
| Check | Question |
|---|---|
| SSR safe | Does component render without browser APIs? |
| Style isolation | Do styles work in Shadow DOM? |
| State independence | Does component work without Context from parent? |
| No function props | Are there callback props that won't work? |
Architecture
| Check | Question |
|---|---|
| Single responsibility | Does component do one thing well? |
| Right granularity | Is this the right size for Designer use? |
| Cross-component state | If needed, is it implemented correctly? |
Example
User prompt:
Audit my ProductCard component
Response:
## Audit: ProductCard
### Component Overview
```typescript
// Current props
props: {
title: props.Text(),
price: props.Number(),
imageUrl: props.Text() // ⚠️ Should be Image
}
A. Prop Exposure Analysis
| Finding | Severity | Recommendation |
|---|---|---|
imageUrl is Text, not Image | Warning | Change to props.Image() for proper asset handling |
| "Add to Cart" button text is hardcoded | Suggestion | Expose as prop: addToCartText: props.Text() |
| Sale badge is conditionally rendered but not controllable | Suggestion | Add showSaleBadge: props.Boolean() |
| Badge color is hardcoded red | Suggestion | Add badgeVariant: props.Variant({ options: ["sale", "new", "featured"] }) |
Hardcoded Content Found:
// Line 24 - hardcoded, should be prop
<button>Add to Cart</button>
// Line 18 - hardcoded, should be prop or removed
{onSale && <span className="badge">SALE</span>}
Recommended Props to Add:
props: {
// ...existing
addToCartLabel: props.Text({
name: "Button Label",
defaultValue: "Add to Cart"
}),
showBadge: props.Boolean({
name: "Show Badge",
defaultValue: false
}),
badgeType: props.Variant({
name: "Badge Type",
options: ["sale", "new", "featured"],
defaultValue: "sale"
})
}
B. State Management
| Finding | Severity |
|---|---|
Uses localStorage for cart count | Warning |
| No React Context dependencies | OK |
Issue: localStorage in render
// Line 8 - will break SSR
const cartCount = localStorage.getItem('cart');
Fix:
const [cartCount, setCartCount] = useState(0);
useEffect(() => {
setCartCount(parseInt(localStorage.getItem('cart') || '0'));
}, []);
C. Slot Opportunities
| Current | Recommendation |
|---|---|
| Hardcoded button | Consider: actions: props.Slot() for flexible CTAs |
If designers need to put different content (button, link, custom element) in the action area:
props: {
actions: props.Slot({
name: "Actions"
})
}
// Component
<div className={styles.actions}>
{actions}
</div>
However, if button behavior is tied to cart logic, keep it hardcoded.
D. Shadow DOM Compatibility
| Check | Status |
|---|---|
| Styles imported in .webflow.tsx | ✅ OK |
| CSS Modules used | ✅ OK |
| No global class references | ✅ OK |
E. SSR Safety
| Check | Status |
|---|---|
| window usage | ✅ None |
| document usage | ✅ None |
| localStorage usage | ⚠️ Needs guard (see fix above) |
F. Component Granularity
Current size: 4 props (will be 7 after recommendations) Verdict: Good granularity - single purpose, manageable props
Summary
| Category | Status |
|---|---|
| Designer Control | ⚠️ Needs work - 4 hardcoded items found |
| State Management | ⚠️ localStorage needs SSR guard |
| Shadow DOM | ✅ Good |
| SSR Safety | ⚠️ One issue |
| Granularity | ✅ Good |
Priority Actions:
- Fix localStorage SSR issue (blocks deployment)
- Change imageUrl from Text to Image prop
- Expose badge controls as props
- Consider exposing button label
## Guidelines
### What This Audit Does NOT Check
This is not a generic code quality audit. Skip:
- Generic React performance patterns (let users use React DevTools)
- Generic accessibility (let users use axe or similar)
- Code formatting (let users use Prettier/ESLint)
- Generic TypeScript best practices
Focus only on Webflow-specific concerns.
### Prop Exposure Heuristics
**Should be a prop:**
- Any text visible in the UI
- Any image or media
- Any color or size that might vary
- Any boolean that controls visibility
- Any value that changes per-use
**Should NOT be a prop:**
- Internal implementation details
- State that changes during interaction
- Values derived from other props
- Animation timing/easing (unless explicitly customizable)
### When to Recommend Slots vs Props
**Use Slot when:**
- Designer wants to put arbitrary Webflow elements inside
- Content structure is flexible
- Nested content doesn't need to interact with component state
**Use Props when:**
- Content is simple (text, image, link)
- Component needs to process/transform the content
- Specific structure is required
### State Pattern Recommendations
If components need to share state, recommend in this order:
1. **URL parameters** - if state should be shareable/bookmarkable
2. **Nano stores** - for real-time sync between components
3. **Custom events** - for fire-and-forget communication
4. **Browser storage** - for persistence across sessions
Component Scaffold
Generate a new Webflow Code Component with proper file structure, React component, and .webflow.tsx definition file.
When to Use This Skill
Use when:
- Creating a new code component from scratch
- User asks to scaffold, generate, or create a component
- Starting a new component with proper Webflow file structure
Do NOT use when:
- Converting an existing React component (use convert-component skill)
- Modifying existing components (answer directly or use component-audit)
- Just asking questions about components (answer directly)
- Setting up a complex project with custom bundler config (use local-dev-setup instead)
Note: This skill can handle basic setup (webflow.json + dependencies) automatically. Use local-dev-setup only for complex setups requiring Tailwind, custom webpack config, or monorepo configurations.
Instructions
Phase 0: Prerequisites Check (Run First)
Before gathering any requirements, verify the project is set up for Webflow Code Components:
-
Check for webflow.json:
# Look for webflow.json in project root- If missing: Offer to create it or invoke local-dev-setup skill
-
Check for required dependencies in package.json:
{ "devDependencies": { "@webflow/webflow-cli": "...", "@webflow/data-types": "...", "@webflow/react": "..." } }- If missing: Offer to install them:
npm i --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
- If missing: Offer to install them:
-
Check for components directory:
- Look for existing pattern (e.g.,
src/components/) - If no components exist, determine where to create them based on webflow.json config
- Look for existing pattern (e.g.,
-
Report setup status:
If all prerequisites met:
✅ Project ready for code components - webflow.json: Found - Dependencies: Installed - Components path: src/components/ Let's create your component...If prerequisites missing:
⚠️ Project Setup Required Missing: - [ ] webflow.json configuration file - [ ] @webflow/webflow-cli dependency - [ ] @webflow/data-types dependency - [ ] @webflow/react dependency Would you like me to: 1. Set up the missing items now (quick setup) 2. Run full project initialization (local-dev-setup skill) Choose an option:Quick setup creates minimal config:
// webflow.json { "library": { "name": "My Component Library", "components": ["./src/components/**/*.webflow.tsx"] } }And installs dependencies.
Optional:
webflow.jsonalso supports a"globals"field pointing to a globals file (e.g.,"globals": "./src/globals.webflow.ts"). The globals file is used for global CSS imports (e.g., Tailwind) and exporting decorator arrays. Add this when using styled-components, Emotion, or Tailwind.
Only proceed to Phase 1 after prerequisites are confirmed.
Phase 1: Gather Requirements
-
Get component name: Ask user for the component name
- Must be PascalCase (e.g., "Accordion", "ProductCard")
- Suggest name if user provides description instead
-
Determine component type: Ask what kind of component
- Interactive (buttons, forms, accordions)
- Display (cards, banners, testimonials)
- Layout (grids, containers, sections)
- Data-driven (lists, tables, charts)
-
Identify props needed: Based on component type, suggest props
- Text content →
props.Text()orprops.RichText() - Canvas-editable text →
props.TextNode() - Images →
props.Image() - Links →
props.Link() - Numeric values →
props.Number() - Variants/styles →
props.Variant() - Nested content →
props.Slot() - Toggles →
props.Boolean() - Show/hide sections →
props.Visibility() - HTML element IDs →
props.Id()
- Text content →
-
Styling approach: Ask preferred styling method
- CSS Modules (default, recommended)
- Tailwind CSS
- styled-components
- Emotion
- Sass / Less
- Plain CSS
- Other supported: MUI (uses Emotion), Shadcn/UI (uses Tailwind)
-
SSR requirements: Determine if component needs client-only features
- Uses browser APIs? →
ssr: false - Pure presentation? →
ssr: true(default)
- Uses browser APIs? →
Phase 2: Validate Project Setup
-
Check project structure:
- Verify
webflow.jsonexists - Check for required dependencies
- Identify components directory pattern
- Verify
-
Check for conflicts:
- Ensure component name doesn't already exist
- Verify no
.webflow.tsxfile with same name
Phase 3: Generate Files
- Create directory structure:
src/components/[ComponentName]/
├── [ComponentName].tsx
├── [ComponentName].webflow.tsx
└── [ComponentName].module.css (if CSS Modules)
- Generate React component (
[ComponentName].tsx):
import React from "react";
import styles from "./[ComponentName].module.css";
export interface [ComponentName]Props {
// Props interface based on user requirements
}
export const [ComponentName]: React.FC<[ComponentName]Props> = ({
// Destructured props with defaults
}) => {
return (
<div className={styles.container}>
{/* Component JSX */}
</div>
);
};
- Generate definition file (
[ComponentName].webflow.tsx):
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { [ComponentName] } from "./[ComponentName]";
import "./[ComponentName].module.css";
export default declareComponent([ComponentName], {
name: "[ComponentName]",
description: "[User-provided or generated description]",
group: "[Category]",
props: {
// Props configuration based on requirements
},
options: {
applyTagSelectors: true,
ssr: true // or false based on requirements
}
});
Note on decorators: declareComponent also accepts an optional decorators array for wrapping components with providers. Built-in decorators include styledComponentsShadowDomDecorator (for styled-components) and emotionShadowDomDecorator (for Emotion). Global decorators can be exported from a globals file referenced in webflow.json — see the globals file note below.
- Generate styles (if CSS Modules):
.container {
/* Base styles */
}
Phase 4: Provide Guidance
-
Show created files: List all files created with paths
-
Explain next steps:
- Implement component logic
- Add styling
- Test locally by running the React project (e.g.,
npm run dev) - Deploy to Webflow with
npx webflow library share
-
Shadow DOM awareness:
Note: Code components run inside Shadow DOM. Site-level CSS classes won't work
inside your component. Use component-scoped styles (CSS Modules, etc.).
Site CSS variables DO work — use var(--variable-name, fallback).
- Warn about naming:
⚠️ Important: Do not rename the .webflow.tsx file after deployment.
Renaming creates a new component and breaks existing instances.
Examples
User prompt:
Create an accordion component
Step 1: Requirements Gathering
📦 New Component: Accordion
I'll create an accordion component. Let me confirm the requirements:
**Props to include:**
1. `title` (Text) - The accordion header text
2. `content` (Rich Text) - The expandable content
3. `defaultOpen` (Boolean) - Whether to start expanded
4. `icon` (Variant) - Chevron style: "arrow" | "plus" | "none"
**Styling:** CSS Modules (recommended for Shadow DOM)
**SSR:** Enabled (no browser-only APIs needed)
Does this look right? Any props to add or remove?
Step 2: After User Confirms
📁 Creating Component Files...
Created:
├── src/components/Accordion/Accordion.tsx
├── src/components/Accordion/Accordion.webflow.tsx
└── src/components/Accordion/Accordion.module.css
✅ Component scaffold complete!
---
**Accordion.tsx** - React component with:
- Props: title, content, defaultOpen, icon
- State management for open/closed
- Accessible keyboard navigation
- CSS Module classes
**Accordion.webflow.tsx** - Webflow definition with:
- All props configured for Designer editing
- Default values set
- SSR enabled
---
💡 Next Steps:
1. Review and customize the generated code
2. Test locally by running your React project (e.g., `npm run dev`)
3. Deploy to Webflow: `npx webflow library share`
⚠️ Remember: Don't rename .webflow.tsx files after deployment!
Generated Accordion.tsx:
import React, { useState } from "react";
import styles from "./Accordion.module.css";
export interface AccordionProps {
title: string;
content: string;
defaultOpen?: boolean;
icon?: "arrow" | "plus" | "none";
}
export const Accordion: React.FC<AccordionProps> = ({
title,
content,
defaultOpen = false,
icon = "arrow"
}) => {
const [isOpen, setIsOpen] = useState(defaultOpen);
return (
<div className={styles.accordion}>
<button
className={styles.header}
onClick={() => setIsOpen(!isOpen)}
aria-expanded={isOpen}
>
<span className={styles.title}>{title}</span>
{icon !== "none" && (
<span className={`${styles.icon} ${isOpen ? styles.open : ""}`}>
{icon === "arrow" ? "▼" : "+"}
</span>
)}
</button>
{isOpen && (
<div
className={styles.content}
dangerouslySetInnerHTML={{ __html: content }}
/>
)}
</div>
);
};
Generated Accordion.webflow.tsx:
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { Accordion } from "./Accordion";
import "./Accordion.module.css";
export default declareComponent(Accordion, {
name: "Accordion",
description: "Expandable content section with customizable header and icon",
group: "Interactive",
props: {
title: props.Text({
name: "Title",
defaultValue: "Accordion Title"
}),
content: props.RichText({
name: "Content",
defaultValue: "<p>Accordion content goes here.</p>"
}),
defaultOpen: props.Boolean({
name: "Start Expanded",
defaultValue: false
}),
icon: props.Variant({
name: "Icon Style",
options: ["arrow", "plus", "none"],
defaultValue: "arrow"
})
},
options: {
applyTagSelectors: true,
ssr: true
}
});
Guidelines
Prop Type Selection
| User Wants | Prop Type | Notes |
|---|---|---|
| Editable text | props.Text() | Single line, max 256 chars |
| Long formatted text | props.RichText() | HTML content |
| Canvas-editable text | props.TextNode() | Double-click to edit |
| Image upload | props.Image() | Returns image object |
| URL/link | props.Link() | Returns { href, target, preload } |
| Number input | props.Number() | Numeric values |
| Toggle/flag | props.Boolean() | true/false |
| Style options | props.Variant() | Dropdown selection |
| Nested content | props.Slot() | Other components inside |
| HTML ID | props.Id() | For accessibility |
Component Categories (Groups)
- Interactive: Buttons, forms, accordions, tabs, modals
- Display: Cards, banners, testimonials, badges
- Layout: Grids, containers, sections, dividers
- Navigation: Menus, breadcrumbs, pagination
- Media: Galleries, video players, carousels
- Data: Tables, lists, charts, counters
SSR Decision Tree
Set ssr: false if ANY of these apply:
1. Browser APIs — Uses window, document, localStorage, or similar
2. Dynamic/personalized content — User-specific dashboards, authenticated views, client data
3. Heavy/interactive UI — Charts, 3D scenes, maps, animation-driven elements
4. Non-deterministic output — Random numbers, time-based values, anything that renders differently server vs client
Otherwise → Keep ssr: true (default)
File Naming Rules
- Component name: PascalCase (
ProductCard) - Files use same name:
ProductCard.tsx,ProductCard.webflow.tsx - CSS modules:
ProductCard.module.css - Directory:
src/components/ProductCard/
Default Values Best Practice
Always provide meaningful defaults:
props: {
title: props.Text({
name: "Title",
defaultValue: "Card Title" // ✅ Good
}),
count: props.Number({
name: "Count",
defaultValue: 0 // ✅ Good
})
}
Not:
props: {
title: props.Text({
name: "Title"
// ❌ Missing defaultValue
})
}
Error Handling
Component name already exists:
⚠️ Component "Button" already exists at src/components/Button/
Options:
1. Choose a different name
2. Update existing component (use component-audit skill)
3. Delete existing and create new
Which would you like to do?
Missing webflow.json:
❌ No webflow.json found in project root
This file is required for code components. Would you like me to:
1. Create a basic webflow.json
2. Run local-dev-setup skill for full project initialization
Choose an option (1/2):
Invalid component name:
⚠️ Invalid component name: "my-button"
Component names must be:
- PascalCase (e.g., "MyButton")
- Start with a letter
- Contain only letters and numbers
Suggested name: "MyButton"
Use this name? (yes/no)
Convert Component
Convert an existing React component into a Webflow Code Component by analyzing its structure and generating the appropriate .webflow.tsx definition file.
When to Use This Skill
Use when:
- User has an existing React component they want to use in Webflow
- User asks to "convert", "adapt", or "make this work with Webflow"
- User provides a React component file and wants a Webflow definition
- User is migrating components from another React project
Do NOT use when:
- Creating a component from scratch (use component-scaffold)
- User just wants to understand code components (answer directly)
- Component is already a Webflow code component (use component-audit)
Instructions
Phase 1: Analyze Existing Component
-
Read the React component file: Get the full source code
-
Extract component information:
- Component name (function/const name)
- Props interface or type definition
- Each prop's TypeScript type
- Default values if defined
- Whether component uses
children
-
Identify incompatible patterns:
Pattern Issue Resolution React Context usage Context doesn't work across Webflow components Refactor to props or use nano stores window/documentin renderSSR will fail Wrap in useEffect or set ssr: falselocalStorage/sessionStoragein renderSSR will fail Wrap in useEffect or set ssr: falseComplex object props Can't map to Webflow prop types Break into individual props Function props (callbacks) Not supported in Webflow Remove or internalize logic useContexthookWon't work across components Use alternative state patterns External CSS imports May not work in Shadow DOM Import in .webflow.tsx instead CSS class references to global styles Won't work in Shadow DOM Use component-scoped styles styled-components Needs Shadow DOM decorator Set up globals.ts with decorator Emotion (@emotion/styled) Needs Shadow DOM decorator Set up globals.ts with decorator -
Detect styling approach and note required setup:
If using styled-components:
npm i @webflow/styled-components-utils styled-componentsCreate/update
globals.ts:import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator];If using Emotion:
npm i @webflow/emotion-utils @emotion/cache @emotion/reactCreate/update
globals.ts:import { emotionShadowDomDecorator } from "@webflow/emotion-utils"; export const decorators = [emotionShadowDomDecorator];For both CSS-in-JS approaches, update
webflow.json:styled-components:
{ "library": { "globals": "./src/globals.ts", "renderer": { "server": "@webflow/styled-components-utils/server" } } }Emotion:
{ "library": { "globals": "./src/globals.ts", "renderer": { "server": "@webflow/emotion-utils/server" } } } -
Flag any dependencies that might cause issues:
- Large libraries (bundle size concern)
- Browser-only libraries
- Libraries that manipulate DOM directly
Phase 2: Map Props to Webflow Types
-
Apply TypeScript → Webflow prop type mapping:
TypeScript Type Webflow Prop Notes stringprops.Text()Default for short text string(long/HTML content)props.RichText()If prop name suggests content/body/description React.ReactNode/childrenprops.Slot()For nested content numberprops.Number()Numeric values booleanprops.Boolean()Toggles "option1" | "option2"props.Variant()String literal unions (requires optionsarray)enumprops.Variant()Convert enum values to optionsarray (required){ href: string; ... }props.Link()Returns { href, target?, preload? }object — may need wrapper if component expects separatehref/targetpropsImage-related types props.Image()Image src, url, etc. string(canvas-editable text)props.TextNode()For text editable directly on canvas; has multilineparamboolean(show/hide)props.Visibility()Semantic show/hide toggle string(for HTML id)props.Id()If prop is named "id" or used for accessibility Complex objects SPLIT Break into multiple simple props Functions/callbacks REMOVE Not supported Arrays SPECIAL May need component redesign -
Handle special cases:
Complex object props - Break them down:
// Original interface Props { author: { name: string; avatar: string; bio: string; } } // Converted to flat props props: { authorName: props.Text({ name: "Author Name" }), authorAvatar: props.Image({ name: "Author Avatar" }), authorBio: props.RichText({ name: "Author Bio" }) }Union types with more than simple strings:
// Original - complex union type Size = "sm" | "md" | "lg" | { width: number; height: number }; // Convert to Variant with only string options size: props.Variant({ name: "Size", options: ["sm", "md", "lg", "custom"], defaultValue: "md" }) // Note: Custom size would need additional Number propsOptional props - Provide defaultValue for prop types that support it. Note: Link, Image, Slot, and Id do not accept defaultValue.
// Original interface Props { title?: string; } // Converted - provide default for types that support it title: props.Text({ name: "Title", defaultValue: "" // Empty string or sensible default })
Phase 3: Check Project Setup
-
Verify Webflow setup exists:
- Check for
webflow.jsonin project root - Check for required dependencies (@webflow/webflow-cli, @webflow/data-types, @webflow/react)
- If using styled-components/Emotion, check for decorator packages
- If missing, offer to set up or direct to local-dev-setup skill
- Check for
-
Determine file locations:
- Identify where the original component lives
- Determine where
.webflow.tsxshould be created (same directory) - Check for existing styles that need to be imported
Phase 4: Generate Definition File
- Create the
.webflow.tsxfile:
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { ComponentName } from "./ComponentName";
// Import styles if they exist
import "./ComponentName.module.css"; // or .css
export default declareComponent(ComponentName, {
name: "ComponentName",
description: "[Generated from component purpose]",
group: "[Appropriate category]",
props: {
// Mapped props here
},
// decorators: [], // Optional — per-component decorators (e.g., for CSS-in-JS Shadow DOM support)
options: {
applyTagSelectors: true, // Default is false. Set to true to apply Webflow's tag selectors (e.g., h1, p styles) inside the component.
ssr: true // or false if browser APIs detected
}
});
- Provide the complete file with all props mapped
Phase 5: Document Required Changes
- List modifications needed to the original component:
## Required Changes to [ComponentName].tsx
### Must Fix (Component won't work without these):
- [ ] Issue 1: [Description and how to fix]
- [ ] Issue 2: [Description and how to fix]
### Recommended (Will improve Webflow integration):
- [ ] Recommendation 1
- [ ] Recommendation 2
### Props Mapping Summary:
| Original Prop | Webflow Prop | Notes |
|---------------|--------------|-------|
| title: string | props.Text() | Direct mapping |
| isOpen: boolean | props.Boolean() | Direct mapping |
| data: object | SPLIT → dataTitle, dataValue | Flattened |
| onClick: function | REMOVED | Not supported |
- Provide modified component code if changes are needed:
- Show the updated TypeScript interface
- Show any useEffect wrappers needed for SSR
- Show style import changes
- Note CSS-in-JS setup requirements if applicable
Examples
Example 1: Simple Component Conversion
User prompt:
Convert this React component to work with Webflow:
// TestimonialCard.tsx
interface TestimonialCardProps {
quote: string;
authorName: string;
authorTitle?: string;
rating?: number;
}
export const TestimonialCard: React.FC<TestimonialCardProps> = ({
quote,
authorName,
authorTitle = "",
rating = 5
}) => {
return (
<div className="testimonial-card">
<div className="stars">{"★".repeat(rating)}</div>
<blockquote>{quote}</blockquote>
<div className="author">
<strong>{authorName}</strong>
{authorTitle && <span>{authorTitle}</span>}
</div>
</div>
);
};
Response:
## Component Analysis: TestimonialCard
### Props Detected:
| Prop | TypeScript Type | Webflow Mapping |
|------|-----------------|-----------------|
| quote | string | props.Text() |
| authorName | string | props.Text() |
| authorTitle | string (optional) | props.Text() |
| rating | number (optional) | props.Number() |
### Issues Found:
- **CSS class "testimonial-card"** - Uses global class that won't work in Shadow DOM
- Fix: Convert to CSS Modules or import scoped styles
### No blocking issues - ready to convert!
---
## Generated Files
### TestimonialCard.webflow.tsx
```typescript
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { TestimonialCard } from "./TestimonialCard";
import "./TestimonialCard.module.css";
export default declareComponent(TestimonialCard, {
name: "TestimonialCard",
description: "Display customer testimonials with rating stars",
group: "Display",
props: {
quote: props.Text({
name: "Quote",
defaultValue: "This product changed my life!"
}),
authorName: props.Text({
name: "Author Name",
defaultValue: "Jane Doe"
}),
authorTitle: props.Text({
name: "Author Title",
defaultValue: "CEO, Company"
}),
rating: props.Number({
name: "Rating",
defaultValue: 5,
min: 1,
max: 5
})
},
options: {
applyTagSelectors: true,
ssr: true
}
});
Required Changes to TestimonialCard.tsx
- Convert to CSS Modules - Rename
TestimonialCard.csstoTestimonialCard.module.cssand update imports:
import styles from "./TestimonialCard.module.css";
// Default CSS Modules uses bracket notation:
<div className={styles["testimonial-card"]}>
<div className={styles["stars"]}>
// Dot notation (styles.testimonialCard) requires camelCase class names
// or a webpack override for css-loader.
Setup Check
- Verify webflow.json exists
- Install dependencies if needed:
npm i --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
---
### Example 2: Component with Incompatible Patterns
**User prompt:**
Make this work as a Webflow code component:
// Modal.tsx import { createContext, useContext, useState } from 'react';
const ModalContext = createContext<{ isOpen: boolean; toggle: () => void } | null>(null);
export const useModal = () => { const context = useContext(ModalContext); if (!context) throw new Error('useModal must be used within ModalProvider'); return context; };
interface ModalProps { trigger: React.ReactNode; children: React.ReactNode; onOpen?: () => void; onClose?: () => void; }
export const Modal: React.FC = ({ trigger, children, onOpen, onClose }) => { const [isOpen, setIsOpen] = useState(false);
const toggle = () => { const newState = !isOpen; setIsOpen(newState); if (newState && onOpen) onOpen(); if (!newState && onClose) onClose(); };
useEffect(() => { if (isOpen) { document.body.style.overflow = 'hidden'; } else { document.body.style.overflow = ''; } }, [isOpen]);
return ( <ModalContext.Provider value={{ isOpen, toggle }}>
**Response:**
```markdown
## Component Analysis: Modal
### Issues Found:
| Issue | Severity | Resolution |
|-------|----------|------------|
| React Context (ModalContext) | Critical | Context won't work across Webflow components. Since this is internal to Modal, it's OK but exported useModal hook won't work. |
| document.body manipulation | Critical | SSR incompatible. Must set `ssr: false` or wrap in useEffect check. |
| onOpen/onClose callbacks | Warning | Function props not supported in Webflow. Must remove. |
| Global CSS classes | Warning | "modal-overlay", "modal-content" won't work in Shadow DOM. |
### Props Detected:
| Prop | TypeScript Type | Webflow Mapping | Status |
|------|-----------------|-----------------|--------|
| trigger | React.ReactNode | props.Slot() | OK |
| children | React.ReactNode | props.Slot() | OK |
| onOpen | function | REMOVE | Not supported |
| onClose | function | REMOVE | Not supported |
---
## Required Changes
### 1. Remove function props (onOpen, onClose)
These cannot be passed from Webflow Designer. Remove from interface and component.
### 2. Fix SSR issue with document.body
Either set `ssr: false` or add typeof check:
```typescript
useEffect(() => {
if (typeof document === 'undefined') return;
// ... rest of effect
}, [isOpen]);
3. Convert to CSS Modules
Rename styles and update class references.
4. Remove exported useModal hook
This won't work for external components. Keep ModalContext internal only.
Generated Files
Modal.webflow.tsx
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { Modal } from "./Modal";
import "./Modal.module.css";
export default declareComponent(Modal, {
name: "Modal",
description: "Overlay modal dialog with trigger element",
group: "Interactive",
props: {
trigger: props.Slot({
name: "Trigger"
}),
children: props.Slot({
name: "Content"
})
},
options: {
applyTagSelectors: true,
ssr: false // Required due to document.body usage
}
});
Updated Modal.tsx
import { useState, useEffect } from 'react';
import styles from "./Modal.module.css";
interface ModalProps {
trigger: React.ReactNode;
children: React.ReactNode;
// Removed: onOpen, onClose - not supported in Webflow
}
export const Modal: React.FC<ModalProps> = ({ trigger, children }) => {
const [isOpen, setIsOpen] = useState(false);
const toggle = () => setIsOpen(!isOpen);
useEffect(() => {
if (typeof document === 'undefined') return;
if (isOpen) {
document.body.style.overflow = 'hidden';
} else {
document.body.style.overflow = '';
}
return () => {
document.body.style.overflow = '';
};
}, [isOpen]);
return (
<>
<div onClick={toggle}>{trigger}</div>
{isOpen && (
<div className={styles["overlay"]} onClick={toggle}>
<div className={styles["content"]} onClick={e => e.stopPropagation()}>
{children}
</div>
</div>
)}
</>
);
};
Setup Required
npm i --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
---
### Example 3: Component with Complex Object Props
**User prompt:**
Convert to Webflow:
interface Product { id: string; name: string; price: number; image: string; category: 'electronics' | 'clothing' | 'home'; }
interface ProductCardProps { product: Product; showBadge?: boolean; }
export const ProductCard = ({ product, showBadge = true }: ProductCardProps) => (
{product.name}
${product.price}
Response:
## Component Analysis: ProductCard
### Complex Props Detected:
The `product` prop is a complex object that must be flattened for Webflow:
| Original | Flattened Props |
|----------|-----------------|
| product.id | (Not needed in UI - remove) |
| product.name | productName: props.Text() |
| product.price | productPrice: props.Number() |
| product.image | productImage: props.Image() |
| product.category | productCategory: props.Variant() |
| showBadge | showBadge: props.Boolean() |
---
## Generated Files
### ProductCard.webflow.tsx
```typescript
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { ProductCard } from "./ProductCard";
import "./ProductCard.module.css";
export default declareComponent(ProductCard, {
name: "ProductCard",
description: "Product display card with image, name, price, and category",
group: "Display",
props: {
productName: props.Text({
name: "Product Name",
defaultValue: "Product Title"
}),
productPrice: props.Number({
name: "Price",
defaultValue: 29.99
}),
productImage: props.Image({
name: "Product Image"
}),
productCategory: props.Variant({
name: "Category",
options: ["electronics", "clothing", "home"],
defaultValue: "electronics"
}),
showBadge: props.Boolean({
name: "Show Category Badge",
defaultValue: true
})
},
options: {
applyTagSelectors: true,
ssr: true
}
});
Updated ProductCard.tsx
import styles from "./ProductCard.module.css";
interface ProductCardProps {
productName: string;
productPrice: number;
productImage?: { src: string; alt?: string };
productCategory: 'electronics' | 'clothing' | 'home';
showBadge?: boolean;
}
export const ProductCard = ({
productName,
productPrice,
productImage,
productCategory,
showBadge = true
}: ProductCardProps) => (
<div className={styles["card"]}>
{productImage && (
<img src={productImage.src} alt={productImage.alt || productName} />
)}
{showBadge && <span className={styles["badge"]}>{productCategory}</span>}
<h3>{productName}</h3>
<p>${productPrice.toFixed(2)}</p>
</div>
);
Migration Notes:
- The
productobject has been flattened into individual props - Each prop is now directly editable in Webflow Designer
product.idwas removed as it's not displayed in the UI- Image prop now uses Webflow's Image type (provides { src, alt })
---
### Example 4: Component with styled-components
**User prompt:**
Convert this styled-components React component to Webflow:
// Button.tsx import styled from 'styled-components';
const StyledButton = styled.button<{ variant: 'primary' | 'secondary' }>` padding: 12px 24px; border-radius: 8px; font-weight: 600; background: ${props => props.variant === 'primary' ? '#3b82f6' : '#e5e7eb'}; color: ${props => props.variant === 'primary' ? 'white' : '#1f2937'};
&:hover { opacity: 0.9; } `;
interface ButtonProps { label: string; variant?: 'primary' | 'secondary'; disabled?: boolean; }
export const Button = ({ label, variant = 'primary', disabled = false }: ButtonProps) => ( {label} );
**Response:**
```markdown
## Component Analysis: Button
### Styling Approach Detected: styled-components
styled-components requires a Shadow DOM decorator to work in Webflow.
### Props Detected:
| Prop | TypeScript Type | Webflow Mapping |
|------|-----------------|-----------------|
| label | string | props.Text() |
| variant | 'primary' \| 'secondary' | props.Variant() |
| disabled | boolean | props.Boolean() |
### No blocking issues - ready to convert!
---
## Required Setup for styled-components
**1. Install dependencies:**
```bash
npm i @webflow/styled-components-utils styled-components
npm i -D @types/styled-components
2. Create/update src/globals.ts:
import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils";
export const decorators = [styledComponentsShadowDomDecorator];
3. Update webflow.json:
{
"library": {
"name": "My Library",
"components": ["./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"],
"globals": "./src/globals.ts"
}
}
Generated Files
Button.webflow.tsx
import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { Button } from "./Button";
// No CSS import needed - styled-components handles styles
export default declareComponent(Button, {
name: "Button",
description: "Styled button with primary and secondary variants",
group: "Interactive",
props: {
label: props.Text({
name: "Label",
defaultValue: "Click me"
}),
variant: props.Variant({
name: "Variant",
options: ["primary", "secondary"],
defaultValue: "primary"
}),
disabled: props.Boolean({
name: "Disabled",
defaultValue: false,
trueLabel: "Disabled",
falseLabel: "Enabled"
})
},
options: {
applyTagSelectors: true,
ssr: true
}
});
No changes needed to Button.tsx
The component can remain as-is. The styled-components decorator in globals.ts will handle Shadow DOM style injection automatically.
Setup Checklist
- Install @webflow/styled-components-utils
- Create globals.ts with decorator
- Update webflow.json to reference globals
- Deploy with
npx webflow library share
## Guidelines
### When to Recommend Component Redesign
Some components fundamentally don't fit the Webflow model:
1. **Heavy Context usage**: If component relies on app-wide context, suggest redesign
2. **Complex state machines**: May need simplification
3. **Tightly coupled components**: Each needs to be independent in Webflow
4. **Components that render portals**: Consider if portal is necessary
### Default Value Strategy
Always provide sensible defaults:
- Text props: Representative example text
- Numbers: Common/typical value
- Booleans: Most common use case
- Variants: Most popular option
- Images: Can be undefined (optional)
- Slots: No default needed
### Props Naming for Webflow
Make prop names designer-friendly:
- Use descriptive names: `buttonText` not `txt`
- Avoid abbreviations: `imageSource` not `imgSrc`
- Group related props with prefixes: `authorName`, `authorAvatar`, `authorBio`
### SSR Decision
Set `ssr: false` if component:
- Accesses `window`, `document`, `navigator`
- Uses `localStorage` or `sessionStorage`
- Manipulates DOM directly
- Uses libraries that require browser APIs
- Renders canvas, WebGL, or maps
Custom Code Management
Add, review, and manage inline custom scripts on a Webflow site — analytics, tracking pixels, chat widgets, or any custom JavaScript.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before any other tool call - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify available sites - Use Webflow MCP's
data_scripts_toolwith actionlist_registered_scriptsto list all registered scripts - Use Webflow MCP's
data_scripts_toolwith actionlist_applied_scriptsto list scripts applied to pages - Use Webflow MCP's
data_scripts_toolwith actionadd_inline_site_scriptto register a new inline script - Use Webflow MCP's
data_scripts_toolwith actiondelete_all_site_scriptsto remove ALL site scripts (no selective delete) - Use Webflow MCP's
data_scripts_toolwith actionget_page_scriptto get custom code for a specific page - Use Webflow MCP's
data_scripts_toolwith actionupsert_page_scriptto add or update page-level custom code - Use Webflow MCP's
data_scripts_toolwith actiondelete_all_page_scriptsto remove all custom code from a page - All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Discovery
- Call
webflow_guide_toolfirst — always the first MCP tool call - Get the site: Use
data_sites_toolwith actionlist_sites. If only one site, use it automatically.
Phase 2: Analysis
- List scripts: Call
list_registered_scriptsandlist_applied_scriptsin parallel - Check page-level scripts (if relevant): Use
get_page_scriptfor specific pages - Present findings: Name, version, location (header/footer), registration vs application status
Phase 3: Planning & Confirmation
Before any mutation, present the plan and require explicit confirmation:
- Adding scripts: user must type "add"
- Removing ALL site scripts: user must type "delete all" (warn: no selective delete)
- Page-level changes: user must type "update"
Phase 4: Execution
- Add site script:
add_inline_site_scriptwith displayName, sourceCode, version, location, canCopy - Remove all site scripts:
delete_all_site_scripts - Add/update page script:
upsert_page_script - Remove page scripts:
delete_all_page_scripts
Phase 5: Verification
- Re-list scripts to confirm success
- Report what changed (name, location, version, char count)
- Remind user to publish — suggest using
safe-publishskill
Examples
Example 1: View scripts
User: "What scripts are on my site?"
webflow_guide_tool→data_sites_tool→list_registered_scripts+list_applied_scriptsin parallel- Present summary of all scripts
Example 2: Add Google Tag Manager
User: "Add GTM to my site"
webflow_guide_tool→data_sites_tool→ ask for GTM container ID- Preview script, require "add" →
add_inline_site_script(header, version "1.0.0") - Verify and remind to publish
Example 3: Remove all scripts
User: "Remove all scripts"
webflow_guide_tool→data_sites_tool→ list current scripts- Warn: removes ALL scripts. Require "delete all" →
delete_all_site_scripts - Verify and remind to publish
Example 4: Page-specific tracking
User: "Add conversion tracking to my thank-you page"
webflow_guide_tool→data_sites_tool→get_page_scriptto check existing- Preview, require "update" →
upsert_page_script - Verify and remind to publish
Guidelines
webflow_guide_toolalways first — before any other MCP tool- No
<script>tags — Webflow adds them automatically - Max 10,000 characters per script;
displayName+versionmust be unique - Site-level scripts (
add_inline_site_script) apply to all pages; page-level scripts (upsert_page_script) apply to one page - No selective delete —
delete_all_site_scriptsremoves everything; always list scripts first so user knows what will be lost - Hosted/external scripts not available via MCP — inline only
- Recommend header for analytics (GA, GTM); footer for chat widgets and non-critical scripts
- If
displayName + versionexists, suggest incrementing the version - Always remind users to publish after changes
Deploy Guide
Guide users through deploying their code component library to Webflow.
When to Use This Skill
Use when:
- User is ready to deploy components to Webflow
- User asks how to share, publish, or deploy their library
- First-time deployment to a workspace
- Step-by-step deployment walkthrough needed
Do NOT use when:
- Deployment failed (use troubleshoot-deploy instead)
- Just validating before deploy (use pre-deploy-check instead)
- Setting up local development (use local-dev-setup instead)
Note: The CLI command is webflow library share. This skill uses "deploy" as the user-facing term.
Instructions
Phase 1: Pre-Flight Checks
-
Verify project is ready:
- Check webflow.json configuration
- Ensure all dependencies installed
- Run pre-deploy-check skill checks
-
Check authentication status:
- Look for existing .env with API token
- Verify WEBFLOW_WORKSPACE_API_TOKEN if set
- Prepare for authentication if needed
-
Confirm deployment target:
- Which workspace?
- New library or update existing?
Phase 2: Authentication
- Guide authentication:
- Interactive: Follow CLI prompts
- CI/CD: Use --api-token flag
- Show how to get workspace API token if needed
Phase 3: Deployment
- Execute deployment:
- Run
npx webflow library share - Monitor for errors
- Capture output
- Run
Phase 4: Verification
-
Verify deployment:
- Check Webflow Designer for components
- Test component functionality
- Confirm all components appear
-
Provide next steps:
- How to use components in Designer
- How to update in future
- Common post-deploy tasks
- If deployment fails, use troubleshoot-deploy to diagnose and fix issues
Deployment Workflow
Standard Deployment
📦 Deploying Code Components
Step 1: Pre-flight checks
├── webflow.json ✅
├── Dependencies ✅
└── Build test ✅
Step 2: Authentication
├── Checking for existing auth...
└── Found valid token ✅
Step 3: Deploying
├── Bundling components...
├── Uploading to workspace...
└── Processing...
Step 4: Verification
├── Library registered ✅
└── 4 components available ✅
🎉 Deployment Complete!
CI/CD Deployment
# Set environment variable
export WEBFLOW_WORKSPACE_API_TOKEN=your-token-here
# Deploy without prompts
npx webflow library share --no-input
Examples
User prompt:
Deploy my components to Webflow
Response:
🚀 Deploy Guide: Code Components
Let me guide you through deploying your component library.
---
## Step 1: Pre-Flight Checks
Running validation...
✅ webflow.json configured
✅ Dependencies installed
✅ Build succeeds
✅ Bundle size: 2.3MB (under 50MB limit)
All checks passed! Ready to deploy.
---
## Step 2: Authentication
**Option A: Interactive (Recommended for first time)**
Run the deploy command:
```bash
npx webflow library share
This will:
- Open your browser for Webflow login
- Ask you to authorize the app
- Save credentials to .env
Option B: API Token (For CI/CD or returning users)
-
Get your Workspace API Token:
- Go to Webflow Dashboard
- Navigate to your Workspace Settings
- Find "Apps & Integrations" → "Manage"
- Under "Workspace API Access", click "Generate API Token"
- Copy the token
-
Run with token:
npx webflow library share --api-token YOUR_TOKEN_HERE
Or set environment variable:
export WEBFLOW_WORKSPACE_API_TOKEN=YOUR_TOKEN_HERE
npx webflow library share
Step 3: Deploy
Ready to deploy? Run:
npx webflow library share
Expected output:
✓ Bundling components...
✓ Authenticating...
✓ Uploading library...
✓ Processing...
Library "My Component Library" successfully shared!
Components:
- Button
- Card
- Accordion
- Modal
View in Designer: Open any site in your workspace
Step 4: Verify in Designer
After deployment:
- Open Webflow Designer for any site in your workspace
- Open Add Panel (A key or + button)
- Find "Components" section
- Look for your library under custom components
- Drag a component onto the canvas to test
Step 5: Next Steps
✅ Your components are live!
To update components later:
# Make your changes, then re-deploy
npx webflow library share
Important notes:
- Updates replace the entire library (no partial updates)
- Existing component instances will update automatically
- Don't rename .webflow.tsx files (breaks instances)
💡 Tips:
- Add .env to .gitignore to protect your token
- Use
--verboseflag for debugging issues - Run
npx webflow library logto see recent deploy logs
---
**Example: First-Time Setup**
🚀 Deploy Guide: First-Time Setup
I see this is your first deployment. Let me walk you through the full setup.
Step 1: Get Workspace API Token
You'll need a Workspace API token to deploy:
-
Open Webflow Dashboard Go to webflow.com and log in
-
Navigate to Workspace Settings Click your workspace name → Settings
-
Find API Access Go to "Apps & Integrations" → "Manage"
-
Generate Token Under "Workspace API Access":
- Click "Generate API Token"
- Copy the token (you won't see it again!)
-
Save Token Add to your .env file:
WEBFLOW_WORKSPACE_API_TOKEN=your-token-here⚠️ Add .env to .gitignore:
echo ".env" >> .gitignore
Step 2: Deploy
Now run:
npx webflow library share
The CLI will:
- Read your token from .env
- Bundle your components
- Upload to your workspace
Step 3: Verify
After successful deploy:
- Open Webflow Designer
- Press 'A' to open Add panel
- Find your components in the Components section
- Drag onto canvas to test
🎉 First deployment complete!
Future deployments are simpler:
# Just run this after making changes
npx webflow library share
---
**Example: CI/CD Setup**
🚀 Deploy Guide: CI/CD Setup
Setting up automated deployments for your pipeline.
GitHub Actions Example
Create .github/workflows/deploy.yml:
name: Deploy to Webflow
on:
push:
branches: [main]
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Setup Node.js
uses: actions/setup-node@v4
with:
node-version: '20'
cache: 'npm'
- name: Install dependencies
run: npm ci
- name: Deploy to Webflow
env:
WEBFLOW_WORKSPACE_API_TOKEN: ${{ secrets.WEBFLOW_WORKSPACE_API_TOKEN }}
run: npx webflow library share --no-input
Add Secret to GitHub
- Go to your repo → Settings → Secrets and variables → Actions
- Click "New repository secret"
- Name:
WEBFLOW_WORKSPACE_API_TOKEN - Value: Your workspace API token
- Click "Add secret"
Key Flags for CI/CD
npx webflow library share --no-input
--no-input: Disables interactive prompts- Uses
WEBFLOW_WORKSPACE_API_TOKENenv var automatically
Optional: Add TypeScript Check
- name: Type check
run: npx tsc --noEmit
✅ CI/CD configured!
Now every push to main will automatically deploy your components.
## Validation
After deployment, verify success with these checks:
| Check | How to Verify |
|-------|---------------|
| Deploy completed | `npx webflow library share` exited without errors |
| Components visible | Open Designer Add panel → find your library |
| Import logs clean | `npx webflow library log` shows successful import |
| Bundle size OK | Output shows bundle under 50MB |
| Props work | Drag component onto canvas, verify props in right panel |
## Guidelines
### Terminology
The CLI command is `webflow library share`. This skill uses "deploy" as the user-facing term for consistency with common developer vocabulary. See the [CLI reference](../../references/CODE_COMPONENTS_REFERENCE.md) (Section 12) for full command documentation.
### Authentication Methods
| Method | Use Case | Command |
|--------|----------|---------|
| Interactive | First time, local dev | `npx webflow library share` |
| Environment variable | CI/CD, automation | Set `WEBFLOW_WORKSPACE_API_TOKEN` |
| CLI flag | One-off with different token | `--api-token TOKEN` |
### Pre-Deploy Checklist
Before every deployment:
- [ ] `npm install` is up to date
- [ ] Build succeeds locally
- [ ] Bundle under 50MB
- [ ] All component tests pass
- [ ] No SSR-breaking code (or ssr: false set)
- [ ] Props have default values where supported (not available for Link, Image, Slot, ID)
### Common Deploy Issues
| Issue | Cause | Solution |
|-------|-------|----------|
| "Authentication failed" | Invalid/expired token | Regenerate workspace token |
| "Bundle too large" | Over 50MB | Optimize dependencies |
| "Library not found" | Wrong workspace | Check token workspace |
| "Build failed" | Code errors | Fix compilation errors |
### CLI Flags Reference
All flags for `npx webflow library share`:
| Flag | Description | Default |
|------|-------------|---------|
| `--manifest` | Path to `webflow.json` file | Scans current directory |
| `--api-token` | Workspace API token | Uses `WEBFLOW_WORKSPACE_API_TOKEN` from `.env` |
| `--no-input` | Skip interactive prompts (for CI/CD) | No |
| `--verbose` | Display more debugging information | No |
| `--dev` | Bundle in development mode (no minification) | No |
### Rollback & Versioning
- Each `library share` replaces the **entire** library — there are no partial updates
- There is **no built-in rollback** — use git to revert changes and re-deploy
- **Never rename `.webflow.tsx` files** — renaming creates a new component and removes the old one, breaking all existing instances in projects
### Debugging Commands
```bash
# Check recent deploy logs
npx webflow library log
# Verbose deploy output (detailed errors)
npx webflow library share --verbose
# Local bundle verification (catches build errors before deploying)
npx webflow library bundle --public-path http://localhost:4000/
CI/CD Deployment
The GitHub Actions example above applies to any CI system. The key elements are:
# Generic CI pattern:
npm ci # Install dependencies
npx webflow library share --no-input # Deploy without prompts
# Requires WEBFLOW_WORKSPACE_API_TOKEN env var
Post-Deploy Verification
Always verify after deployment:
- Check Designer: Components appear in Add panel
- Test drag-and-drop: Component renders on canvas
- Test props: Props editable in right panel
- Test preview: Component works in preview mode
- Test publish: Component works on published site
Designer Extension
Create and develop Designer Extensions for Webflow with template selection, local development server, and bundling for distribution.
Important Note
ALWAYS use Bash tool for all Webflow CLI operations:
- Execute
webflow extensioncommands via Bash tool - Use Read tool to examine generated files and schema (never modify)
- Use Glob tool to discover project files
- Verify CLI installation:
webflow --version - Check authentication:
webflow auth login(if needed) - DO NOT use Webflow MCP tools for CLI workflows
- All CLI commands require proper descriptions (not context parameters)
Package Manager Detection:
- Check for lock files:
package-lock.json(npm),pnpm-lock.yaml(pnpm),yarn.lock(yarn) - If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
- Use detected package manager for all install/build commands
Instructions
Phase 1: Environment Verification
- Verify CLI installed: Run
webflow --versionto confirm CLI is installed - Check project state: Check if already in an extension project (look for webflow.json with extension schema)
- Identify operation type: Determine if user wants to:
- List available templates
- Initialize new extension
- Bundle existing extension
- Serve extension locally
Phase 2: Template Listing & Selection
- List templates (if user asks or before init): Run
webflow extension list - Show available templates:
default- Basic HTML/CSS/JavaScript templatereact- React-based templatetypescript-alt- Alternative TypeScript template
- Ask user to select template if initializing new extension
Phase 3: Extension Initialization
- Choose project name: Ask user for project directory name
- Run init command: Execute
webflow extension init <project-name> <template> - Read generated schema: Use Read tool to examine webflow.json
- Show schema structure: Display the 5 schema fields:
name(required) - Extension name as it appears in WebflowapiVersion(required) - API version (2)publicDir(required) - Directory to build from (dist)appIntents(optional) - Element types that can create connectionsappConnections(optional) - Connection configurations
- Install dependencies: Run
npm installin project directory
Phase 4: Local Development
- Start dev server: Execute
webflow extension serve [port] - Show dev server info:
- Default port: 1337 (unless user specifies different port)
- Local URL: http://localhost:[port]
- How to load in Designer
- Provide loading instructions:
- Open Webflow Designer
- Load extension from local URL
- Test functionality
Phase 5: Bundling for Upload
- Run bundle command: Execute
webflow extension bundle - Show bundle output: Display bundle.zip location and size
- Provide upload instructions: Guide for uploading to Webflow
- Document next steps: Testing and distribution guidance
Examples
Example 1: List Available Templates
User prompt:
Show me the available Designer Extension templates
Response:
🔍 Designer Extension Templates
Listing available templates...
Executing: webflow extension list
Output:
Available templates:
1. default - Basic HTML, CSS, and JavaScript
2. react - React-based extension
3. typescript-alt - Alternative TypeScript template
To create a new extension:
webflow extension init <project-name> <template>
Example:
webflow extension init my-extension react
Example 2: Initialize New Extension
User prompt:
Create a new Designer Extension called gallery-manager using React
Step 1: Initialize Project
📋 Initialize Designer Extension
Project name: gallery-manager
Template: react
Executing: webflow extension init gallery-manager react
Output:
✓ Created extension project at ./gallery-manager
✓ Generated project structure
✓ Created webflow.json with extension schema
✓ Set up React template
📁 Project Structure:
./gallery-manager/
├── webflow.json # Extension schema
├── package.json # Dependencies
├── src/
│ ├── index.html
│ ├── index.tsx
│ └── styles.css
├── dist/ # Build output
└── README.md
Installing dependencies...
Executing: cd gallery-manager && npm install
✓ Dependencies installed (45 packages)
Step 2: Show Schema
📋 Extension Schema (webflow.json)
Reading webflow.json...
{
"name": "Gallery Manager",
"apiVersion": "2",
"publicDir": "dist",
"appIntents": {},
"appConnections": []
}
Schema Fields:
✓ name (required) - Extension name in Webflow
✓ apiVersion (required) - API version: 2
✓ publicDir (required) - Build directory: dist
appIntents (optional) - Element connection types
appConnections (optional) - Connection configs
Extension ready for development!
Example 3: Serve Extension Locally
User prompt:
Run the extension on my local dev server
Default Port (1337):
🚀 Starting Development Server
Executing: webflow extension serve
Output:
✓ Building extension
✓ Starting dev server
✓ Extension ready
📋 Development Server Running
Local URL: http://localhost:1337
Status: ✓ Active
How to Load in Designer:
1. Open Webflow Designer
2. Open any site
3. Load extension from URL: http://localhost:1337
Press Ctrl+C to stop server
Custom Port:
User: "Run on port 3000 instead"
🚀 Starting Development Server
Executing: webflow extension serve 3000
Output:
✓ Building extension
✓ Starting dev server on port 3000
✓ Extension ready
📋 Development Server Running
Local URL: http://localhost:3000
Status: ✓ Active
Load in Designer: http://localhost:3000
Example 4: Bundle Extension
User prompt:
Bundle my extension for upload
Step 1: Bundle
📦 Bundling Extension
Executing: webflow extension bundle
Output:
✓ Building production bundle
✓ Creating bundle.zip
✓ Bundle created successfully
Bundle Details:
- File: bundle.zip
- Location: ./dist/bundle.zip
- Size: 245 KB
✅ Bundle ready for upload!
Step 2: Upload Instructions
📤 Upload Instructions
Your extension is bundled and ready to upload.
Upload Steps:
1. Go to Webflow Designer Extensions dashboard
2. Upload bundle.zip
3. Test the extension
4. Submit for review (if distributing)
Bundle location: ./dist/bundle.zip
Example 5: Complete Workflow
User prompt:
Create a new Designer Extension for managing colors
Step 1: List Templates
🔍 Designer Extension Workflow
First, let me show available templates.
Executing: webflow extension list
Available templates:
1. default - Basic HTML/CSS/JavaScript
2. react - React-based (recommended)
3. typescript-alt - TypeScript alternative
Which template would you like to use? (default/react/typescript-alt)
User selects: react
Step 2: Initialize
📋 Creating Extension
Project name: color-manager
Template: react
Executing: webflow extension init color-manager react
✓ Project created at ./color-manager
✓ webflow.json generated
✓ React template configured
Installing dependencies...
✓ npm install complete
📋 Extension Schema:
{
"name": "Color Manager",
"apiVersion": "2",
"publicDir": "dist",
"appIntents": {},
"appConnections": []
}
Step 3: Start Development
🚀 Starting Dev Server
Executing: webflow extension serve
✓ Server running at http://localhost:1337
Load in Designer:
1. Open Webflow Designer
2. Load extension from: http://localhost:1337
3. Start developing!
Server running... (Press Ctrl+C to stop)
Guidelines
Phase 1: CLI Verification
Installation Check:
# Check if CLI is installed
webflow --version
# If not installed, guide user:
npm install -g @webflow/cli
Authentication (if needed):
# Site authentication if required
webflow auth login
Phase 2: Template Management
List Templates Command:
webflow extension list
Available Templates:
- default - Basic HTML, CSS, and JavaScript template
- react - React-based extension with modern tooling
- typescript-alt - Alternative TypeScript template
Phase 3: Initialization
Init Command:
webflow extension init <project-name> <template>
Arguments:
<project-name>(required) - Name of the new project directory<template>(required) - One of: default, react, typescript-alt
Example Commands:
# Initialize with default template
webflow extension init my-extension default
# Initialize with React template
webflow extension init my-extension react
# Initialize with TypeScript template
webflow extension init my-extension typescript-alt
Project Structure After Init:
/project-name/
├── webflow.json # Extension schema (required)
├── package.json # Dependencies
├── src/ # Source files
│ ├── index.html
│ ├── index.tsx (or .js)
│ └── styles.css
├── dist/ # Build output directory
└── README.md
Phase 4: Extension Schema
Schema in webflow.json:
{
"name": "<Your Extension Name>",
"apiVersion": "2",
"publicDir": "dist",
"appIntents": {
"image": ["manage"],
"form": ["manage"]
},
"appConnections": [
"myAppImageConnection",
"myAppFormConnection"
]
}
Schema Fields:
| Field | Description | Default | Required |
|---|---|---|---|
name | Extension name as it appears in Webflow | - | Yes |
apiVersion | API version to use for extension | 2 | Yes |
publicDir | Directory to build and serve extension from | dist | Yes |
appIntents | Element types that can create connections | {} | No |
appConnections | Connection configurations for extension | [] | No |
Required Fields:
name- Must be unique and descriptiveapiVersion- Currently must be "2"publicDir- Directory where built files are placed (default: "dist")
Optional Fields:
appIntents- Defines which element types can connect to your extension- Example:
{"image": ["manage"], "form": ["manage"]}
- Example:
appConnections- Array of connection identifiers- Example:
["myAppImageConnection", "myAppFormConnection"]
- Example:
Phase 5: Local Development
Serve Command:
# Serve on default port (1337)
webflow extension serve
# Serve on custom port
webflow extension serve 3000
Arguments:
[port](optional) - Port number to serve on (default: 1337)
Development Server:
- Default URL: http://localhost:1337
- Custom port: http://localhost:[port]
- Auto-rebuilds on file changes
- Hot reload for faster development
Loading in Designer:
- Open Webflow Designer
- Open any site
- Go to Extensions menu
- Load extension from local URL: http://localhost:[port]
- Extension appears in Designer
Phase 6: Bundling
Bundle Command:
webflow extension bundle
Output:
- Creates
bundle.zipfile in project directory - Contains all built files from
publicDir - Ready to upload to Webflow
Bundle Contents:
- Built JavaScript and CSS files
- HTML entry points
- Assets from publicDir
- Extension schema
Error Handling
CLI Not Installed:
❌ Webflow CLI Not Found
Designer Extensions require the Webflow CLI.
Installation:
npm install -g @webflow/cli
After installation, verify:
webflow --version
Documentation: https://developers.webflow.com/cli
Invalid Template:
❌ Invalid Template
Error: Template "vue" not found
Available templates:
- default
- react
- typescript-alt
Retry with valid template:
webflow extension init my-extension react
Port Already in Use:
❌ Development Server Failed to Start
Error: Port 1337 is already in use
Solutions:
1. Stop other process on port 1337
2. Use different port:
webflow extension serve 3000
Find process using port:
lsof -ti:1337 | xargs kill -9
Missing webflow.json:
❌ Extension Schema Not Found
Error: webflow.json not found in current directory
This directory is not an extension project.
Solutions:
1. Initialize new extension:
webflow extension init <name> <template>
2. Navigate to existing extension directory
3. Create webflow.json with required schema
Bundle Failed:
❌ Bundle Creation Failed
Error: Build failed with errors
Common Causes:
- Missing dependencies (run: npm install)
- Build errors in source files
- Invalid webflow.json schema
- Missing publicDir directory
Fix errors and retry:
webflow extension bundle
File Operations
Reading Extension Files: Always use Read tool (never modify):
# View extension schema
Read: webflow.json
# View package dependencies
Read: package.json
# View source files
Read: src/index.html
Read: src/index.tsx
Discovering Project Files: Use Glob tool to find files:
# Find all source files
Glob: src/**/*
# Find configuration files
Glob: *.json
# Find built files
Glob: dist/**/*
Never Use Write/Edit Tools:
- Don't create or modify webflow.json with Write tool
- Don't edit generated files
- Let CLI generate all project files
- Only read files to show content
Progress Indicators
For Init:
📋 Creating Extension...
[████████████████████████] 100%
✓ Project created
✓ Dependencies installed
Elapsed: 12s
For Bundle:
📦 Bundling Extension...
[████████████████████████] 100%
✓ Bundle created: bundle.zip
Elapsed: 5s
For Serve:
🚀 Starting Server...
[████████████████████████] 100%
✓ Server ready at http://localhost:1337
Elapsed: 3s
Best Practices
Template Selection:
- Use react template for modern component-based development
- Use default template for simple extensions or learning
- Use typescript-alt for TypeScript-based projects
Development Workflow:
- List available templates
- Initialize project with chosen template
- Install dependencies
- Serve locally for development
- Test in Designer
- Bundle for upload
- Upload to Webflow
Schema Configuration:
- Always include required fields: name, apiVersion, publicDir
- Set appropriate appIntents if your extension connects to elements
- Define appConnections for element integrations
- Keep name descriptive and unique
Local Development:
- Use default port 1337 for consistency
- Keep dev server running during development
- Test frequently in Designer
- Check console for errors
Bundling:
- Bundle only when ready for upload or distribution
- Verify build completes without errors
- Check bundle.zip size
- Test bundled version before uploading
Quick Reference
Workflow: list templates → init → serve → develop → bundle → upload
Key Commands:
webflow extension list- Show available templateswebflow extension init <project-name> <template>- Create new extensionwebflow extension serve [port]- Start dev server (default: 1337)webflow extension bundle- Create bundle.zip for upload
Templates: default, react, typescript-alt
Schema Fields (webflow.json):
name(required) - Extension nameapiVersion(required) - API version (2)publicDir(required) - Build directoryappIntents(optional) - Element connection typesappConnections(optional) - Connection configs
Dev Server: http://localhost:1337 (or custom port)
Bundle Output: bundle.zip in project directory
Documentation: https://developers.webflow.com/designer/reference/introduction
Page Structure
Build, inspect, and manage page elements and components in the Webflow Designer.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before any other tool call - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify the target site - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto find the target page by name or slug — headless, works against any page - Use Webflow MCP's
data_pages_toolwith actioncreate_pageto create new pages — headless - Use Webflow MCP's
data_element_toolwith actionget_all_elementsorquery_elementsto retrieve or filter page elements — headless, pass the page's ID directly - Use Webflow MCP's
data_element_builderto create new elements — headless, pass the page's ID and a parent element ID - Use Webflow MCP's
data_element_toolwith actionset_attributes,set_text,set_style, orset_linkto modify elements — headless - Use Webflow MCP's
element_snapshot_toolto get visual previews of elements before and after changes — this is a Designer tool and requires a Designer connection - Use Webflow MCP's
data_style_toolto create and update styles on elements — headless - Use Webflow MCP's
webflow_guide_toolto check supported style properties - Use Webflow MCP's
data_component_toolwith actionget_all_componentsorquery_componentsto list site components — headless - Use Webflow MCP's
data_component_toolwith actionget_componentto inspect a component's metadata — headless - Use Webflow MCP's
data_element_toolscoped withscope_component_idto inspect or edit a component's internal elements (its "content") — headless - Use Webflow MCP's
data_component_props_toolto manage prop definitions and set prop values on component instances — headless - Use Webflow MCP's
data_component_variants_toolto manage variants and per-variant style overrides — headless - Use Webflow MCP's
data_component_toolwith actioninsert_component_instanceorunlink_component_instanceto manage component instances on a page — headless, not Designer-gated - Use Webflow MCP's
designer_toolonly for actions that need a live canvas:get_current_page/switch_page(what's open in Designer right now),select_element/get_selected_element(interactive canvas selection),create_page_folder(page folders are Designer-only, unlike page creation itself), andopen_component_view(viewing a component's canvas) - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective) - Designer connection is required for
designer_toolactions and forelement_snapshot_tool. Building, styling, inspecting, and updating elements, components, props, and variants (thedata_tools) runs headlessly against an explicit page ID fromdata_pages_tool'slist_pages— but the before/after visual snapshots this skill relies on for safe mutation need Designer open and connected. If Designer isn't available, skip the snapshot steps and rely onquery_elementsoutput to describe changes instead.
Instructions
Phase 1: Discovery
- Call
webflow_guide_toolfirst — always the first MCP tool call in any workflow - Get the site: Use
data_sites_toolwith actionlist_sitesto identify the target site. If only one site exists, use it automatically. - Get the target page: Use
data_pages_toolwith actionlist_pagesto find the page by name or slug — no Designer connection needed. If the user is actively working in an open Designer session and wants "the page I have open," usedesigner_toolwith actionget_current_pageinstead. - If user specifies a different page: Just use that page's ID directly in later calls — no page "switch" is needed for headless operations. Only use
designer_toolwith actionswitch_pageif the user wants the Designer canvas itself to navigate there. - Identify the task type:
- Inspect: List elements, view structure, preview → go to Phase 2
- Build/Modify/Delete: Add, update, restructure, remove → go to Phase 3
- Components: List, inspect, update → go to Phase 2 or Phase 3 depending on read vs write
Phase 2: Inspection (read-only operations)
- List page elements: Use
data_element_toolwithget_all_elements(orquery_elementsto filter by type/text/attribute) to retrieve page structure, passing the page ID from Phase 1. Present a summary of sections, elements, and nesting. - Preview elements: Use
element_snapshot_toolto get visual previews of specific sections — requires Designer - List components: Use
data_component_toolwith actionget_all_componentsorquery_componentsto list all site components - Inspect a component: Use
data_component_toolwith actionget_componentfor metadata (props, variants), ordata_element_toolwithscope_component_idset to the component's ID to inspect its internal elements
Phase 3: Planning (before any mutation)
Before creating, updating, or deleting anything:
10. Snapshot current state: Use element_snapshot_tool to capture the area being changed — requires Designer; if unavailable, describe the current state from query_elements output instead
11. Present the plan: Describe exactly what will be created, modified, or deleted
12. Request explicit confirmation: Ask the user before proceeding:
- "Would you like me to proceed with these changes?"
- "Shall I go ahead and create this?"
- "Do you want me to apply these changes?"
- "Before I make changes, here's what I'll do: [plan]. Confirm to proceed."
13. For destructive operations (delete, restructure): Require "confirm" or "delete", warn about child elements that will also be affected
Phase 4: Execution (after confirmation only)
- Build elements: Use
data_element_builderto create new elements (max 3 levels deep), passing the page ID and the parent element ID. For deeper structures, build in multiple passes. - Style elements: Use
data_style_toolto apply or update styles on created or existing elements - Modify elements: Use
data_element_toolwithset_attributes,set_text,set_style, orset_linkto update attributes, text, or links - Update components: Use
data_element_tool(scoped withscope_component_id) to edit a component's internal elements;data_component_props_toolto change prop definitions or instance prop values;data_component_variants_toolto manage variants;data_component_toolwithinsert_component_instance/unlink_component_instanceto add or unlink instances on a page - Create pages: Use
data_pages_toolwith actioncreate_page. To create a page folder, usedesigner_toolwith actioncreate_page_folder— this specific action requires a Designer connection
Phase 5: Verification
- Snapshot the result: Use
element_snapshot_toolto capture the new state — requires Designer; if unavailable, summarize the change from the tool response instead - Report what changed: Summarize the changes made
Examples
Example 1: List page elements
User: "Show me all elements on the homepage"
- Call
webflow_guide_toolfor best practices - Call
data_sites_toolwithlist_sitesto identify the site - Call
data_pages_toolwithlist_pagesto find the homepage's page ID - Call
data_element_toolwithget_all_elements(using that page ID) to retrieve page structure - Present organized summary of sections, elements, and nesting
Example 2: Build a hero section
User: "Add a hero section with a heading and CTA button"
- Call
webflow_guide_toolfor best practices - Call
data_sites_toolwithlist_sitesto identify the site - Call
data_pages_toolwithlist_pagesto find the target page's ID - Call
element_snapshot_toolto capture current state - Present plan: "I'll create a Section with a Heading and Button. Would you like me to proceed?"
- After confirmation: call
data_element_builderwith nested structure - Call
data_style_toolto apply styles (padding, background, typography) - Call
element_snapshot_toolto show the result
Example 3: Update a component
User: "Update the footer copyright text to 2026"
- Call
webflow_guide_toolfor best practices - Call
data_sites_toolwithlist_sitesto identify the site - Call
data_component_toolwithquery_componentsto find the footer component - Call
data_element_tool(scoped withscope_component_id) to inspect its internal elements and find the copyright text element - Present: "I'll update the copyright text from '2025' to '2026'. Would you like me to proceed?"
- After confirmation: call
data_element_toolwithset_text(scoped withscope_component_id) - Report the change
Example 4: Restructure a section
User: "Restructure the hero section layout"
- Call
webflow_guide_toolfor best practices - Call
data_sites_toolwithlist_sitesto identify the site - Call
data_pages_toolwithlist_pagesto find the target page's ID - Call
element_snapshot_toolto capture current hero section - Call
data_element_toolwithquery_elementsto inspect current structure - Present restructuring plan with before/after description
- After confirmation: apply changes using
data_element_tool(move_element,set_style, etc.) and/ordata_element_builder - Call
element_snapshot_toolto show the result
Example 5: Create a two-column layout
User: "Create a two-column layout with text on left and image on right"
- Call
webflow_guide_toolfor best practices - Call
data_sites_toolwithlist_sitesto identify the site - Call
data_pages_toolwithlist_pagesto find the target page's ID - Call
element_snapshot_toolto capture current state - Present plan: "I'll create a Grid with two columns — text block on left, image on right. Would you like me to proceed?"
- After confirmation: call
data_element_builderwith grid structure - Call
data_style_toolto set grid layout properties - Call
element_snapshot_toolto show the result
Guidelines
webflow_guide_toolalways first — before any other MCP tool in every workflow- Snapshot before and after — use
element_snapshot_toolbefore mutations and after to show results - Never silently mutate — every write operation requires explicit user confirmation
- Headless for building and editing — get the page ID once via
data_pages_tool'slist_pages, then pass it directly todata_element_tool,data_element_builder, anddata_style_tool. Reach fordesigner_toolonly when the task specifically needs the live canvas (current-page detection, interactive selection, page folders, component canvas view). - Visual snapshots need Designer —
element_snapshot_toolis a Designer tool; if Designer isn't connected, fall back to describing changes fromquery_elements/tool response data instead of skipping the before/after check entirely. - Batch changes need itemized preview — if modifying multiple elements, list each change
- Prefer Webflow's native layout tools (Grid, Flexbox) over manual positioning
- Components shared across pages should be updated via
data_element_toolscoped to the component (changes propagate to all instances) - Component instance management (
insert_component_instance,unlink_component_instance) is headless viadata_component_tool— not Designer-gated data_element_buildersupports max 3 levels per call — build deeper structures in stages- Check
webflow_guide_toolfor supported style properties when unsure
DevLink
Export and sync Webflow Designer components to React/Next.js code with validation, diffs, and integration guidance.
Important Note
ALWAYS use Bash tool for all Webflow CLI operations:
- Execute
webflow devlink syncvia Bash tool - Use Read tool to examine synced files and webflow.json (never modify)
- Use Glob tool to discover generated components
- Verify CLI installation:
webflow --version - Check authentication: Use
webflow auth loginfor site authentication - DO NOT use Webflow MCP tools for CLI workflows
- All CLI commands require proper descriptions (not context parameters)
Package Manager Detection:
- Check for lock files:
package-lock.json(npm),pnpm-lock.yaml(pnpm),yarn.lock(yarn) - If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
- Use detected package manager for all install/build commands
Instructions
Phase 1: Environment Verification
- Verify CLI installed: Run
webflow --versionto confirm CLI is installed - Check authentication: Verify site authentication (created via
webflow auth login) - Discover project state: Check if webflow.json exists with devlink configuration
- Identify target framework: Determine if React, Next.js, or other
Phase 2: DevLink Configuration
- Check for existing config: Look for
webflow.jsonwith devlink section - Read configuration: If exists, show current devlink settings:
rootDir: Directory to export components intocssModules: Whether to use CSS modulesfileExtensions: File extensions for generated files- Other configuration options
- Ask operation type: Clarify what user wants to do:
- Configure DevLink for first time
- Sync all components
- Sync specific components (using
componentsregex pattern) - Update existing sync
- Store baseline (if updating): Use Read tool to capture current files before sync
Phase 3: Sync Execution
- Run sync command: Execute
webflow devlink syncwith options:--api-tokenor-t: Override API token from .env--site-idor-s: Override site ID from .env
- Monitor sync progress: Show CLI output and sync status
- Capture sync results: Record files created/modified in rootDir
- Validate generated code:
- Check for TypeScript errors (if using TS)
- Verify import statements
- Confirm component exports
- Check CSS module references
Phase 4: Analysis & Diff Preview
- Compare before/after: Show what changed:
- New files created in rootDir
- Existing files modified
- Components added or updated
- Show file diffs: Display key changes for modified files
- Analyze component structure:
- Component count
- New components added
- Updated components
- CSS files generated
- List dependencies: Show what needs to be imported
Phase 5: Integration Guidance
- Provide import statements: Show exact code to import components
- Show usage examples: Demonstrate how to use each component
- Document sync timestamp: Record when sync occurred
- Provide next steps: Guide user on testing and integration
Examples
Example 1: First-Time DevLink Setup
User prompt:
Sync my Webflow components to my Next.js project
Step 1: Environment Verification
🔍 DevLink Environment Check
Checking CLI installation...
✓ Webflow CLI installed: v1.5.2
Current directory: /Users/user/projects/my-nextjs-app
Framework detected: Next.js 14
Checking for DevLink configuration...
⚠️ No webflow.json with devlink configuration found
This appears to be your first DevLink sync.
Ready to configure? (yes/no)
User confirms: yes
Step 2: Configuration Setup
📋 DevLink Configuration
DevLink syncs Webflow components to your local project as React code.
Configuration needed in webflow.json:
{
"devlink": {
"rootDir": "./devlink", // Where to export components
"cssModules": true, // Use CSS modules
"fileExtensions": {
"js": "jsx" // or "tsx" for TypeScript
}
}
}
I'll help you create this configuration.
Questions:
1. Where should components be exported? (default: ./devlink)
2. Use TypeScript? (yes for tsx, no for jsx)
3. Use CSS modules? (recommended: yes)
User provides: ./src/devlink, yes (TypeScript), yes (CSS modules)
Creating webflow.json configuration...
{
"devlink": {
"rootDir": "./src/devlink",
"cssModules": true,
"fileExtensions": {
"js": "tsx"
}
}
}
✓ Configuration created
⚠️ Authentication Required:
DevLink needs your Webflow site ID and API token.
Run: webflow auth login
This will create a .env file with:
- WEBFLOW_SITE_ID
- WEBFLOW_SITE_API_TOKEN
After authentication, run sync again.
Example 2: First Sync After Configuration
User prompt:
Run the DevLink sync
Step 1: Verification
🔍 DevLink Sync Check
Checking configuration...
✓ webflow.json found with devlink config
✓ Root directory: ./src/devlink
✓ CSS modules: enabled
✓ File extensions: tsx
Checking authentication...
✓ .env found with WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN
Ready to sync components from Webflow.
Step 2: Sync Execution
🔄 Syncing Components
Executing: webflow devlink sync
Output:
✓ Connecting to Webflow site
✓ Fetching components
✓ Exporting components to ./src/devlink
✓ Generating React components
✓ Creating CSS module files
✓ Creating index file
Sync complete!
📁 Generated Files:
./src/devlink/
├── index.ts (module exports)
├── Navigation.tsx (component)
├── Navigation.module.css (styles)
├── Hero.tsx (component)
├── Hero.module.css (styles)
├── Footer.tsx (component)
├── Footer.module.css (styles)
└── _webflow-style.css (global styles)
📊 Sync Summary:
- Components synced: 3
- Files created: 8
- Total size: 45 KB
Step 3: Integration Guidance
✅ DevLink Sync Complete!
📋 Components Available:
1. Navigation
2. Hero
3. Footer
💡 How to Use:
Import components in your Next.js pages:
```tsx
import { Navigation, Hero, Footer } from './src/devlink'
export default function Home() {
return (
<>
<Navigation />
<Hero />
<Footer />
</>
)
}
Global Styles: Import the global DevLink styles in your _app.tsx or layout:
import '../src/devlink/_webflow-style.css'
📦 No additional dependencies required! DevLink components use only React (already in your project).
🔄 Future Updates:
Run webflow devlink sync again to pull latest design changes.
### Example 3: Update Existing Sync
**User prompt:**
Sync latest changes from Webflow
**Step 1: Pre-Sync State**
🔍 DevLink Update Check
Current state: ✓ Configuration: ./src/devlink ✓ Existing components: 3 (Navigation, Hero, Footer) ✓ Last sync: 2 days ago
Capturing current state for comparison... ✓ Baseline captured
**Step 2: Sync**
🔄 Syncing Updates
Executing: webflow devlink sync
Output: ✓ Connecting to Webflow site ✓ Fetching components ✓ Detecting changes ✓ Updating components ✓ Regenerating files
Sync complete!
**Step 3: Diff Analysis**
📊 Sync Analysis
Changes detected:
Modified Components:
-
Navigation.tsx
- Added new "Contact" link
- Updated styles for mobile view
-
Hero.tsx
- Changed heading text
- Updated button styling
New Components: 3. CallToAction.tsx (new)
- New CTA section added
Unchanged:
- Footer.tsx
📁 Files Updated:
- ./src/devlink/Navigation.tsx (modified)
- ./src/devlink/Navigation.module.css (modified)
- ./src/devlink/Hero.tsx (modified)
- ./src/devlink/Hero.module.css (modified)
- ./src/devlink/CallToAction.tsx (new)
- ./src/devlink/CallToAction.module.css (new)
- ./src/devlink/index.ts (updated exports)
✅ 3 components updated, 1 new component added
💡 New Component Available:
import { CallToAction } from './src/devlink'
<CallToAction />
### Example 4: Sync Specific Components
**User prompt:**
Only sync the navigation component from Webflow
**Configuration Update:**
📋 Filtering Components
To sync only specific components, update webflow.json:
Current configuration: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" } } }
Add components regex pattern: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" }, "components": "Navigation" // Regex pattern to match } }
Pattern options:
- "Navigation" - Only Navigation component
- "Nav.*" - All components starting with "Nav"
- "Navigation|Footer" - Multiple specific components
- ".*" - All components (default)
Update webflow.json? (yes/no)
*User confirms: yes*
✓ Configuration updated
Syncing with filter: "Navigation"
Executing: webflow devlink sync
Output: ✓ Connecting to Webflow site ✓ Fetching components ✓ Applying filter: Navigation ✓ Exporting 1 component
📁 Generated: ./src/devlink/ ├── index.ts ├── Navigation.tsx └── Navigation.module.css
✅ Synced 1 component (Navigation only)
### Example 5: Override Site ID and Token
**User prompt:**
Sync from a different Webflow site
**Response:**
🔄 Sync from Different Site
To sync from a different site, use --site-id and --api-token options.
Get credentials:
- Go to Webflow site settings
- Get Site ID
- Generate API token (if needed)
Sync command:
webflow devlink sync --site-id <SITE_ID> --api-token <API_TOKEN>
Example:
webflow devlink sync \
--site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
--api-token wfp_1234567890abcdef
This overrides the .env file values for this sync only.
⚠️ Note: You can also:
- Update .env file with new WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN
- Or maintain multiple .env files (.env.site1, .env.site2)
- Then run: webflow devlink sync (uses .env)
Proceed with override? (yes/no)
### Example 6: TypeScript Configuration
**User prompt:**
Set up DevLink with TypeScript
**Response:**
📋 DevLink TypeScript Configuration
For TypeScript projects, configure file extensions:
webflow.json: { "devlink": { "rootDir": "./src/devlink", "cssModules": true, "fileExtensions": { "js": "tsx" // Use .tsx for TypeScript } } }
Benefits: ✓ Type-safe components ✓ Better IDE support ✓ Auto-completion ✓ Compile-time error checking
After sync, components will be generated as:
- Navigation.tsx (instead of .jsx)
- Hero.tsx
- Footer.tsx
Usage with TypeScript:
import { Navigation } from '@/src/devlink'
export default function Layout({ children }: { children: React.ReactNode }) {
return (
<div>
<Navigation />
{children}
</div>
)
}
Ready to sync? (yes/no)
## Guidelines
### Phase 1: CLI Verification
**Installation Check:**
```bash
# Check if CLI is installed
webflow --version
# If not installed, guide user:
npm install -g @webflow/webflow-cli
Authentication Check:
# Site authentication creates .env file
# Check for:
cat .env
# Should contain:
# WEBFLOW_SITE_ID=your-site-id
# WEBFLOW_SITE_API_TOKEN=your-token
# If missing, authenticate:
webflow auth login
Phase 2: Configuration
webflow.json DevLink Schema:
{
"devlink": {
"rootDir": "./devlink",
"cssModules": true,
"fileExtensions": {
"js": "jsx"
}
}
}
All Configuration Options:
| Option | Description | Default | Required |
|---|---|---|---|
host | Webflow API host URL | https://api.webflow.com | No |
rootDir | Directory to export components into | ./devlink | Yes |
siteId | Webflow site ID | process.env.WEBFLOW_SITE_ID | No |
authToken | Webflow API authentication token | process.env.WEBFLOW_SITE_API_TOKEN | No |
cssModules | Enable CSS modules for component styles | true | No |
allowTelemetry | Allow anonymous usage analytics | true | No |
envVariables | Inject environment variables into exported components | {} | No |
components | Regex pattern to match components to export | .* | No |
overwriteModule | Whether to overwrite the module file | true | No |
fileExtensions | File extensions for exported components | { js: ".js", css: ".css" } | No |
skipTagSelectors | Exclude tag/ID/attribute selectors from global CSS | false | No |
relativeHrefRoot | Control how relative href attributes are resolved | / | No |
Common Configurations:
React with JavaScript:
{
"devlink": {
"rootDir": "./src/components/webflow",
"cssModules": true,
"fileExtensions": {
"js": "jsx"
}
}
}
Next.js with TypeScript:
{
"devlink": {
"rootDir": "./src/devlink",
"cssModules": true,
"fileExtensions": {
"js": "tsx"
}
}
}
Sync Specific Components:
{
"devlink": {
"rootDir": "./src/devlink",
"cssModules": true,
"components": "Navigation|Hero|Footer"
}
}
Phase 3: Sync Command
Basic Sync:
# Uses webflow.json config and .env credentials
webflow devlink sync
Sync with Options:
# Override site ID
webflow devlink sync --site-id 5f8a9b2c3d4e5f6g7h8i9j0k
# Override API token
webflow devlink sync --api-token wfp_1234567890abcdef
# Override both
webflow devlink sync \
--site-id 5f8a9b2c3d4e5f6g7h8i9j0k \
--api-token wfp_1234567890abcdef
# Short flags
webflow devlink sync -s <site-id> -t <api-token>
Sync Options:
--api-token/-t: The API token to use, overriding the.envfile--site-id/-s: The site ID to sync from, overriding the.envfile
Phase 4: Generated Files
Directory Structure: After sync, rootDir contains:
./devlink/
├── index.ts // Module exports
├── ComponentName.tsx // Component file
├── ComponentName.module.css // Component styles (if cssModules: true)
├── AnotherComponent.tsx
├── AnotherComponent.module.css
└── _webflow-style.css // Global Webflow styles
Component Structure: Generated components are React functional components:
import React from 'react'
import styles from './ComponentName.module.css'
export function ComponentName() {
return (
<div className={styles.container}>
{/* Component markup */}
</div>
)
}
Index File: Exports all components for easy importing:
export { ComponentName } from './ComponentName'
export { AnotherComponent } from './AnotherComponent'
Error Handling
CLI Not Installed:
❌ Webflow CLI Not Found
The Webflow CLI is required for DevLink.
Installation:
npm install -g @webflow/webflow-cli
After installation, verify:
webflow --version
Documentation: https://developers.webflow.com/cli
Not Authenticated:
❌ Not Authenticated
DevLink needs authentication to access your Webflow site.
Steps:
1. Run: webflow auth login
2. Follow authentication prompts in browser
3. Select your site when prompted
4. Verify: .env file created with:
- WEBFLOW_SITE_ID
- WEBFLOW_SITE_API_TOKEN
5. Retry sync
Need help? https://developers.webflow.com/cli/authentication
No Configuration:
❌ DevLink Not Configured
No webflow.json with devlink configuration found.
Create webflow.json in project root:
{
"devlink": {
"rootDir": "./devlink",
"cssModules": true,
"fileExtensions": {
"js": "jsx" // or "tsx" for TypeScript
}
}
}
Required fields:
- rootDir: Where to export components
After configuration, run: webflow devlink sync
Sync Failures:
❌ Sync Failed
Error: [Specific error from CLI]
Common Causes:
- Network connection issues
- Invalid site ID or API token
- Insufficient permissions
- Site has no components to export
Solutions:
1. Check internet connection
2. Verify credentials in .env
3. Check site permissions in Webflow
4. Ensure site has published components
5. Try: webflow devlink sync --site-id <id> --api-token <token>
Retry sync? (yes/no)
Invalid Site ID:
❌ Invalid Site ID
The provided site ID is invalid or inaccessible.
Check:
1. Verify WEBFLOW_SITE_ID in .env
2. Ensure you have access to the site
3. Check site ID in Webflow dashboard
Get site ID:
1. Open site in Webflow
2. Go to Site Settings
3. Find Site ID in General tab
Update .env and retry sync.
File Operations
Reading Files: Always use Read tool (never modify):
# View DevLink configuration
Read: webflow.json
# View environment
Read: .env
# View generated component
Read: ./devlink/Navigation.tsx
# View generated styles
Read: ./devlink/Navigation.module.css
Discovering Files: Use Glob tool to find files:
# Find all generated components
Glob: ./devlink/**/*.tsx
# Find all CSS modules
Glob: ./devlink/**/*.module.css
# Find configuration
Glob: webflow.json
Never Use Write/Edit Tools:
- Don't create webflow.json with Write (show user the structure)
- Don't modify generated components
- Let CLI handle file generation
- Only read files to show content and diffs
Progress Indicators
For Sync:
🔄 Syncing Components...
Connecting to Webflow... ✓
Fetching components... ✓
Generating React code... ⏳
Creating CSS modules... ⏳
Processed: 3/5 components
Elapsed: 8s
Best Practices
Configuration:
- Keep webflow.json in project root
- Use TypeScript (.tsx) for better type safety
- Enable CSS modules for scoped styling
- Use specific component regex patterns for large sites
Development Workflow:
- Design in Webflow Designer
- Publish changes
- Run
webflow devlink sync - Review diffs before integrating
- Test components in your app
Integration:
- Import global styles (_webflow-style.css) in app entry point
- Import components where needed
- Don't modify generated files (will be overwritten)
- Wrap DevLink components if customization needed
Version Control:
- Commit webflow.json
- Add .env to .gitignore
- Commit generated devlink/ directory (or add to .gitignore)
- Document last sync timestamp
Multiple Sites:
- Use different rootDir for each site
- Or use
componentspattern to filter - Override credentials with --site-id and --api-token
- Maintain separate .env files
Quick Reference
Workflow: configure webflow.json → authenticate → sync
Key Commands:
webflow devlink sync- Sync components from Webflowwebflow devlink sync -s <id> -t <token>- Sync with overrides
Sync Options:
-s/--site-id- Override site ID-t/--api-token- Override API token
Configuration: webflow.json with devlink section
Schema (Required):
{
"devlink": {
"rootDir": "./devlink" // Required
}
}
Schema (Common):
{
"devlink": {
"rootDir": "./devlink",
"cssModules": true,
"fileExtensions": {
"js": "jsx" // or "tsx"
}
}
}
Authentication: Site authentication via webflow auth login
Environment: WEBFLOW_SITE_ID and WEBFLOW_SITE_API_TOKEN in .env
Verification: Check webflow --version and site authentication first
Generated Files: React components in rootDir with CSS modules
Documentation: https://developers.webflow.com/devlink
Figma → Webflow
Translate a Figma design into a live Webflow project: real elements, styles, assets, fonts, and (optionally) custom code + interactions.
Instructions
Follow this order exactly. When a step says to read a reference file, read it before doing that work; those files contain the failure modes for that step.
Non-Negotiable Gates
Treat these as build gates, not suggestions. If you cannot satisfy one, stop and explain the tradeoff instead of silently substituting.
- Bridge gate: Designer Bridge is the default build mode. If selected, provide the Designer launch link (opens Designer with the MCP Bridge App) and wait for the user to open it with that tab foregrounded before bridge-dependent steps. If the bridge disconnects, keep structural work headless and reconnect before snapshots/canvas inspection.
- Native style gate: apply styles with
data_style_tool, never with thedata_whtml_buildercssparam or rawvar()strings. Otherwise styles land in Custom properties instead of native controls. Bind Webflow variables withvariable_as_value. - Visible element gate: build with real Designer-visible elements and native classes. Do not use embed
<style>blocks,::before/::after, or other hidden constructs for normal layout/decorative elements. - Class existence gate: create every class with
data_style_tool create_stylebefore using it in WHTML/element class lists. Webflow can silently drop class names that do not exist yet. - Variables gate: decide the Webflow variable/design-system strategy before creating styles. Do not hard-code repeated colors/type/spacing/radii unless the user explicitly chooses hard-coded output.
- Vector gate: logos, icons, and marks must be inline SVG embeds, not PNG/JPG uploads, unless the user explicitly approves raster fallback.
- Raster quality gate: hero/product/mockup images must use a confirmed 2x source where crispness matters.
- Dashed accent gate: dashed lines, dividers, grids, accents, and underlines must use
repeating-linear-gradient, notborder-style:dashed, unless the user explicitly accepts browser-default dash rhythm. - Navbar gate: custom navbar mobile behavior must be CSS-only, not JavaScript. Use the checkbox/sibling-selector pattern in
references/navbar.md. - Verification gate: never call a build done until you have verified rendered output. If visual verification is blocked, say what is unverified and ask the user to check it.
- Capability gate: do not assert that Webflow or MCP "can't" do something until you have tested the relevant tool path or clearly label it as untested.
- Publish gate: do not publish by default. Offer
.webflow.iopublish only after build/review, and only proceed on explicit user confirmation.
Tool Surfaces
| Surface | Examples | Needs Designer open? |
|---|---|---|
| Data API (headless) | data_whtml_builder, data_element_builder, data_element_tool, data_style_tool, data_fonts_tool, data_pages_tool, data_scripts_tool, data_assets_tool, publish | No |
| Designer Bridge | element_snapshot_tool, designer_tool canvas/selection/navigation, asset_tool upload_image_by_url | Yes — Designer tab open AND foregrounded |
- Call
webflow_guide_toolonce before other Webflow tools. Confirm auth/site withwhoami+get_site. - Prefer bridge-assisted builds by default for better visual feedback, while still using
data_*tools for DOM, classes/styles, text, semantic tags, responsive overrides, fonts, scripts, pages, and asset records. - If Designer is disconnected, continue structural work headlessly with
query_styles,get_all_elements, andquery_elements; reconnect the bridge for snapshots, canvas inspection, and any still-required bridge-gated image processing fallback. - If a bridge tool returns
status:falseor "Unable to connect to Webflow Designer," provide the Designer launch link (opens Designer with the MCP Bridge App) and ask the user to open it and keep that browser tab in the foreground — it idles/disconnects when backgrounded. Retry before assuming anything broke.
Workflow
1. Gather And Decide
- Use Figma MCP:
get_metadatafor structure.get_design_contextfor major frames/sections.get_variable_defsfor colors, type, spacing, radii.- Read page/canvas background; do not assume white.
- Use Webflow MCP:
webflow_guide_toolfirst.- Confirm target site/page and inspect existing variables/styles.
- Ask the required setup prompts below.
- Confirm ambiguous design intent before building. If Figma component instances contain repeated placeholder labels, ask for intended copy instead of copying placeholders.
Required Prompts
Before creating Webflow variables, classes, or CSS, ask these four questions:
- Build mode: Designer Bridge during build (default, better visual QA; requires Designer tab open/foregrounded) or headless first (faster, structural checks only until bridge needed).
- Variables/design system: read existing variables and create missing ones (default), create a new design system from scratch, use existing variables only, or hard-code with no Webflow variables.
- Style naming: FlowKit naming (default; reference
webflow-mcp:flowkit-naming), existing Webflow design-system naming, or clear semantic kebab-case names. - Units:
px(default),rem, orem. Keep units consistent; only mix when there is a clear reason.
If the user does not choose, use the defaults above. For a blank site, recommend creating a new design system from scratch and explain why.
2. Build Foundations And Sections
Before creating variables/classes/styles, read CSS rules.
- Create or map Webflow variables according to the selected strategy.
- Create reusable primitives first: page wrapper, containers, typography, spacing, buttons, image-fill, cards, nav.
- Create needed classes with
data_style_tool create_stylebefore referencing them in WHTML/element class lists. - Use
data_whtml_builderfor DOM/structure only: one root section per action, semantic tags, nesting, text, and existing class names. - Style with
data_style_tool update_style. Repeat: do not use the WHTMLcssparam or embed<style>blocks for normal styling. - Capture returned element ids. Re-find later with
query_elements, then filter by exact class/type before acting. - Build in section-sized batches. Prefer structural verification with
query_elements/query_stylesbetween visual checks.
3. Attach Assets
Before handling images or vectors, read Assets and SVG.
- Use
data_assets_tool create_assetfor raster assets. Download source bytes locally, compute MD5, POST to presigned S3, then verify nonzero size/variants before placement. - For hero/product/mockup images, confirm 2x source before placement.
- Bind images by asset ID with
set_image_asset; never rely on raw<img src="...">. - Inline vector marks as
HtmlEmbedSVGs and set embed code withdata_element_tool set_settings. - Upload fonts with
data_fonts_tool; never add Google Fonts<link>tags to head.
4. Navbar And Custom Behavior
If the build includes a navbar, read Navbar before building it.
- Ask which breakpoint should collapse to hamburger.
- Webflow native Navbar cannot be created via API/WHTML. Build a semantic custom nav or ask the user to add the native element in Designer.
- Put CSS-only component behavior in an HtmlEmbed inside the component root. Do not use JavaScript for the custom navbar.
5. Responsive And QA
Before responsive/final verification, read Verification.
- Use
data_style_tool update_stylewith breakpoint ids (main,medium,small,tiny). Desktop-first: set base, override downward. - If Designer Bridge is selected, snapshot groups/wrappers rather than every element. Keep the Designer tab foregrounded.
- Verify overlays/layering with a full-page composite, not isolated-section snapshots.
- Do not trust first snapshots for fonts; warm cache and re-snapshot before changing font implementation.
- Test tool capabilities before asserting limitations. If you cannot test, say "untested" and describe the uncertainty.
- Do not claim embed behavior, custom code, blur, WebGL, animation, or mobile widths are verified from your side. Ask the user to confirm in preview/published site.
- Offer publish/review next steps. Default remains no publish.
Checklist before declaring done
- Required reference files were read at their point of use.
- All CSS longhand; correct breakpoints; flexbox-first.
- Styles applied via
data_style_tool(native controls), variables bound withvariable_as_value, and only truly non-native CSS (backdrop-filter,aspect-ratio,repeating-linear-gradient, etc.) left as custom properties. - All class names used in WHTML/element class lists exist as Webflow styles; none were silently dropped.
- No embed
<style>blocks or::before/::afterpseudo-elements used for normal layout/decorative elements. - Build mode followed: bridge-assisted by default with Designer tab open and foregrounded, or headless-first if the user chose it.
- Webflow variables handled according to the selected strategy; repeated colors/type/spacing/radii are mapped or created unless hard-coding was explicitly selected.
- Images attached by asset ID (not orphan
<img src>); 2× source confirmed where crispness matters. - Vector marks are clean inline-SVG embeds (backgrounds stripped), or user explicitly approved raster fallback.
- Dashed accents/dividers/grids use
repeating-linear-gradient, notborder-style:dashed, unless user explicitly approved browser-default dashes. - Fonts uploaded + referenced by exact family name; temp
<head>link removed. - Runtime-toggled classes have guaranteed CSS (not stripped).
- Responsive overrides at medium/small/tiny.
- Rendered output verified visually, or unverified items clearly reported to the user.
- No untested capability limitation was stated as fact.
- If published to subdomain, user asked to confirm anything you can't self-verify (embeds, WebGL, blur, mobile).
Flowkit Naming System
Apply FlowKit CSS naming conventions in Webflow projects using Webflow Designer tools.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before starting - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify the target site - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto find the target page by name or slug — headless, no Designer needed - Use Webflow MCP's
data_element_toolto inspect current classes and apply new ones — headless, pass the page's ID directly - Use Webflow MCP's
data_style_toolto create and update FlowKit-compliant styles — headless - Use Webflow MCP's
webflow_guide_toolto understand supported style properties - Use Webflow MCP's
designer_toolonly if the user wants to work with whatever page is currently open in Designer, or wants to interactively select an element on the canvas - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective) - No Designer connection is required for the core workflow. Getting the page, inspecting classes, creating styles, and applying classes all run headlessly against an explicit page ID. Designer is only needed for the optional
designer_toolconveniences above.
Instructions
Phase 1: Discovery & Setup
- Identify the task: Determine if user is:
- Creating new component classes
- Auditing existing class names
- Building complete page sections
- Refactoring non-FlowKit classes to FlowKit
- Get target page: Use Webflow MCP's
data_pages_toolwith actionlist_pagesto find the page by name or slug — no Designer connection needed. If the user wants to work with whatever page they currently have open in Designer, usedesigner_toolwith actionget_current_pageinstead. - Ask for scope: Clarify which elements or sections to work with
Phase 2: Analysis (if auditing existing)
- Get all elements: Use Webflow MCP's
data_element_toolto retrieve elements from the target page - Extract classes: Identify all class names currently applied
- Categorize issues:
- Missing
fk-prefix - Incorrect case (uppercase/mixed case)
- Wrong separators (underscores instead of hyphens)
- Non-semantic naming
- Inconsistent component structure
- Missing
- Generate audit report: Show current vs suggested FlowKit-compliant names
Phase 3: Suggestion Generation
- Apply FlowKit patterns: Generate class names following FlowKit v2 conventions
- Structure by type:
- Component wrappers:
fk-[component] - Child elements:
fk-[component]-[element] - State modifiers: combo classes with
is-[state] - Layout utilities:
fk-flex,fk-grid,fk-stack - Spacing utilities:
fk-space-[size],fk-py-[size],fk-px-[size] - Typography utilities:
fk-text-[style]
- Component wrappers:
- Validate suggestions: Ensure all suggestions follow FlowKit conventions
- Show preview: Display hierarchical structure with suggested classes
Phase 4: Application (if user confirms)
- Create styles: Use Webflow MCP's
data_style_toolto create new FlowKit-compliant class styles - Update elements: Use Webflow MCP's
data_element_toolto apply classes to elements - Process in batches: If many elements, process in groups of 10-15
- Show progress: Display which elements are being updated
Phase 5: Verification & Reporting
- Verify application: Check that classes were applied correctly
- Generate report: Show what was created/updated
- Provide documentation: Explain the FlowKit structure used
- Suggest next steps: Recommend additional FlowKit patterns to implement
FlowKit Naming Reference
Core Naming Patterns
| Pattern | Purpose | Example |
|---|---|---|
fk-[component] | Component wrapper (base class) | fk-card, fk-nav, fk-hero |
fk-[component]-[element] | Child element within component | fk-card-title, fk-nav-link |
fk-[component].[modifier] | Combo class modifier (state/variant) | fk-card.is-featured |
fk-text-[style] | Typography utility | fk-text-xl, fk-text-bold |
fk-flex / fk-grid | Layout utilities | fk-flex-center, fk-grid-3 |
fk-space-[size] | Spacing utilities | fk-space-md, fk-py-lg |
is-[state] | State modifiers (combo) | is-active, is-hidden, is-disabled |
Layout Utilities
fk-section Section wrapper with padding
fk-container Max-width container (centered)
fk-flex Flexbox container
fk-flex-center Centered flex (both axes)
fk-flex-between Space-between flex
fk-flex-around Space-around flex
fk-flex-col Flex column direction
fk-grid Grid container (base)
fk-grid-2 2-column grid
fk-grid-3 3-column grid
fk-grid-4 4-column grid
fk-grid-6 6-column grid
fk-stack Vertical stack (gap between items)
fk-row Horizontal row
fk-wrap Flex wrap enabled
Typography Utilities
fk-text-xs Extra small text (12px)
fk-text-sm Small text (14px)
fk-text-md Medium text (16px - default)
fk-text-lg Large text (18px)
fk-text-xl Extra large text (24px)
fk-text-2xl 2x large text (32px)
fk-text-3xl 3x large text (48px)
fk-text-bold Bold weight (700)
fk-text-semibold Semibold weight (600)
fk-text-medium Medium weight (500)
fk-text-light Light weight (300)
fk-text-center Center aligned
fk-text-left Left aligned
fk-text-right Right aligned
fk-text-uppercase Uppercase transform
fk-text-lowercase Lowercase transform
fk-text-capitalize Capitalize transform
Spacing Utilities
fk-space-xs 4px spacing
fk-space-sm 8px spacing
fk-space-md 16px spacing (default)
fk-space-lg 24px spacing
fk-space-xl 32px spacing
fk-space-2xl 48px spacing
fk-space-3xl 64px spacing
Directional Spacing:
fk-py-[size] Padding vertical (top + bottom)
fk-px-[size] Padding horizontal (left + right)
fk-pt-[size] Padding top
fk-pb-[size] Padding bottom
fk-pl-[size] Padding left
fk-pr-[size] Padding right
fk-my-[size] Margin vertical (top + bottom)
fk-mx-[size] Margin horizontal (left + right)
fk-mt-[size] Margin top
fk-mb-[size] Margin bottom
fk-ml-[size] Margin left
fk-mr-[size] Margin right
Color Utilities
fk-bg-primary Primary background color
fk-bg-secondary Secondary background color
fk-bg-accent Accent background color
fk-bg-light Light background
fk-bg-dark Dark background
fk-text-primary Primary text color
fk-text-secondary Secondary text color
fk-text-muted Muted text color
Border & Visual Utilities
fk-rounded Border radius (default)
fk-rounded-sm Small border radius
fk-rounded-lg Large border radius
fk-rounded-full Fully rounded (pill/circle)
fk-border Border (1px solid)
fk-border-top Border top only
fk-border-bottom Border bottom only
fk-shadow Box shadow (default)
fk-shadow-sm Small shadow
fk-shadow-lg Large shadow
State Modifiers (Combo Classes)
is-active Active state (navigation, tabs)
is-hidden Hidden visibility
is-visible Visible visibility
is-disabled Disabled state
is-loading Loading state
is-error Error state
is-success Success state
is-primary Primary variant
is-secondary Secondary variant
is-featured Featured/highlighted variant
is-horizontal Horizontal layout variant
is-vertical Vertical layout variant
Examples
Example 1: Creating Hero Section
User prompt:
Build a hero section with FlowKit naming
Step 1: Analysis
🎨 FlowKit Hero Section Structure
I'll create a hero section following FlowKit v2 conventions.
Structure:
fk-section (wrapper with padding)
└── fk-container (max-width container)
└── fk-hero (component wrapper)
├── fk-hero-content + fk-flex + fk-flex-col + fk-flex-center
│ ├── fk-hero-eyebrow + fk-text-sm + fk-text-uppercase + fk-mb-sm
│ ├── fk-hero-title + fk-text-3xl + fk-text-bold + fk-mb-md
│ ├── fk-hero-subtitle + fk-text-lg + fk-text-muted + fk-mb-lg
│ └── fk-hero-actions + fk-flex + fk-space-md
│ ├── fk-button.is-primary
│ └── fk-button.is-secondary
└── fk-hero-image + fk-rounded-lg
Total classes to create: 12 base classes + 2 combo classes
Ready to create these in Webflow Designer? (yes/no)
Step 2: After user confirms
🔄 Creating FlowKit Hero Classes...
Progress: ████████████████████ 100% (14/14 classes)
✅ Classes Created:
**Layout Classes:**
- ✅ fk-section - Section wrapper with padding
- ✅ fk-container - Max-width container
- ✅ fk-hero - Hero component wrapper
**Element Classes:**
- ✅ fk-hero-content - Hero content container
- ✅ fk-hero-eyebrow - Small label above title
- ✅ fk-hero-title - Main hero heading
- ✅ fk-hero-subtitle - Supporting text
- ✅ fk-hero-actions - Button container
- ✅ fk-hero-image - Hero image wrapper
**Utility Classes:**
- ✅ fk-flex, fk-flex-col, fk-flex-center
- ✅ fk-text-sm, fk-text-lg, fk-text-3xl
- ✅ fk-text-uppercase, fk-text-bold, fk-text-muted
- ✅ fk-mb-sm, fk-mb-md, fk-mb-lg
- ✅ fk-space-md, fk-rounded-lg
**Component Classes:**
- ✅ fk-button (with combo classes: is-primary, is-secondary)
---
📋 Usage Guide:
1. Create a Section element → Apply `fk-section`
2. Add Container inside → Apply `fk-container`
3. Add Div inside → Apply `fk-hero`
4. Build content structure following the hierarchy above
5. Use combo classes for button variants: `fk-button.is-primary`
🎉 Your FlowKit hero section structure is ready!
Example 2: Auditing Existing Classes
User prompt:
Check these classes: feature-card, FK-Button, fk_hero_title, cardTitle
Response:
📋 FlowKit Audit Report
Checking 4 classes against FlowKit v2 conventions...
---
## Issues Found: 4
### 1. `feature-card` ⚠️
**Issue:** Missing FlowKit prefix
**Reason:** All FlowKit classes must start with `fk-`
**Suggested:** `fk-feature-card` or `fk-card.is-feature`
**Fix:** Rename class to include `fk-` prefix
### 2. `FK-Button` ❌
**Issue:** Incorrect case (uppercase)
**Reason:** FlowKit uses lowercase only
**Suggested:** `fk-button`
**Fix:** Convert to lowercase: `fk-button`
### 3. `fk_hero_title` ❌
**Issue:** Wrong separator (underscore)
**Reason:** FlowKit uses hyphens, not underscores
**Suggested:** `fk-hero-title`
**Fix:** Replace underscores with hyphens
### 4. `cardTitle` ❌
**Issue:** Multiple violations
- Missing `fk-` prefix
- CamelCase instead of kebab-case
**Reason:** FlowKit requires `fk-` prefix and hyphen separation
**Suggested:** `fk-card-title`
**Fix:** Add prefix and convert to kebab-case
---
## FlowKit Naming Rules:
✅ **Correct patterns:**
- `fk-card` (component)
- `fk-card-title` (element)
- `fk-button.is-primary` (with modifier)
- `fk-text-xl` (utility)
❌ **Incorrect patterns:**
- `card` (no prefix)
- `FK-Card` (wrong case)
- `fk_card` (wrong separator)
- `cardTitle` (camelCase)
Would you like me to rename these classes in Webflow Designer? (yes/no)
Example 3: Building Card Component
User prompt:
Create a product card component with FlowKit classes
Response:
🎨 FlowKit Product Card Component
Structure:
fk-card (base component)
├── fk-card-image-wrapper
│ └── fk-card-image + fk-rounded-lg
├── fk-card-badge + fk-text-xs + fk-text-uppercase + fk-bg-accent
├── fk-card-content + fk-space-md
│ ├── fk-card-category + fk-text-sm + fk-text-muted
│ ├── fk-card-title + fk-text-lg + fk-text-bold
│ ├── fk-card-description + fk-text-md
│ └── fk-card-price + fk-text-xl + fk-text-bold + fk-text-primary
└── fk-card-footer + fk-flex + fk-flex-between + fk-pt-md + fk-border-top
├── fk-card-rating + fk-flex + fk-space-xs
└── fk-button.is-primary + fk-text-sm
---
## Variants (Combo Classes):
### Featured Card
`fk-card.is-featured`
- Highlighted border/shadow
- Accent background
- Use for promoted products
### Horizontal Layout
`fk-card.is-horizontal`
- Side-by-side image/content
- Better for list views
- Image on left, content on right
### Compact Size
`fk-card.is-compact`
- Reduced padding
- Smaller text sizes
- Use in tight layouts
---
## Responsive Modifiers:
Desktop (default):
- `fk-grid-3` (3 cards per row)
Tablet:
- Add combo: `fk-grid-3.tablet-2`
Mobile:
- Add combo: `fk-grid-3.tablet-2.mobile-1`
---
Ready to create these classes? (yes/no)
Example 4: Refactoring to FlowKit
User prompt:
Refactor my navigation to use FlowKit naming
Step 1: Current Analysis
🔍 Analyzing Current Navigation Classes...
Found 8 elements with non-FlowKit classes:
├── navbar → fk-nav
├── navbar-container → fk-nav-container
├── logo-wrapper → fk-nav-logo
├── menu → fk-nav-menu
├── menu-item → fk-nav-link
├── menu-item active → fk-nav-link.is-active
├── button-group → fk-nav-actions
└── btn-primary → fk-button.is-primary
---
## Migration Plan:
**Phase 1: Create FlowKit Classes** (8 classes)
- Create all `fk-nav-*` classes
- Create utility classes: `fk-flex`, `fk-flex-between`, `fk-flex-center`
- Create `fk-button` with `is-primary` modifier
**Phase 2: Update Elements** (8 elements)
- Replace old classes with new FlowKit classes
- Apply combo classes where needed
- Preserve existing styles
**Phase 3: Cleanup** (optional)
- Old classes can be removed after verification
- Keep for now to maintain backwards compatibility
---
Proceed with migration? (yes/no)
Step 2: After Migration
✅ Navigation Refactored to FlowKit
**Classes Created:** 8
**Elements Updated:** 8
**Time elapsed:** ~3 seconds
---
## Updated Structure:
fk-nav
├── fk-nav-container + fk-flex + fk-flex-between
│ ├── fk-nav-logo
│ ├── fk-nav-menu + fk-flex + fk-flex-center + fk-space-md
│ │ ├── fk-nav-link (x5)
│ │ └── fk-nav-link.is-active (current page)
│ └── fk-nav-actions + fk-flex + fk-space-sm
│ ├── fk-button.is-secondary
│ └── fk-button.is-primary
---
## Before → After:
| Old Class | New FlowKit Class |
|-----------|-------------------|
| navbar | fk-nav ✅ |
| navbar-container | fk-nav-container ✅ |
| logo-wrapper | fk-nav-logo ✅ |
| menu | fk-nav-menu ✅ |
| menu-item | fk-nav-link ✅ |
| menu-item active | fk-nav-link.is-active ✅ |
| button-group | fk-nav-actions ✅ |
| btn-primary | fk-button.is-primary ✅ |
---
🎉 Navigation is now FlowKit compliant!
**Next steps:**
- Test navigation on all breakpoints
- Verify active states work correctly
- Consider adding `fk-nav.is-transparent` for transparent header variant
- Consider adding `fk-nav.is-sticky` for sticky navigation
Guidelines
Phase 1: Critical Requirements
FlowKit Prefix Rule:
- ALL component and element classes MUST start with
fk- - Exception: State modifiers use
is-prefix (as combo classes) - Exception: Utility classes for third-party integrations may omit prefix
Case Sensitivity:
- All class names are lowercase only
- No uppercase letters anywhere
- No camelCase or PascalCase
Separator Rule:
- Use hyphens (
-) to separate words - Never use underscores (
_) - Never use spaces or special characters
Naming Structure:
Component: fk-[component]
Element: fk-[component]-[element]
Sub-element: fk-[component]-[element]-[detail]
Utility: fk-[property]-[value]
State modifier: is-[state] (combo class only)
Responsive: .[breakpoint]-[value] (combo class)
Phase 2: Component Naming Rules
Component Names:
- Keep concise and semantic
- Use common web component terms:
card,nav,hero,footer - Avoid overly specific names: prefer
fk-cardoverfk-product-feature-card - Use modifiers for variants:
fk-card.is-featurednotfk-card-featured
Element Hierarchy:
- Parent component:
fk-card - Direct children:
fk-card-[element](e.g.,fk-card-title) - Deep nesting: Avoid more than 3 levels
- Bad:
fk-card-content-section-text-wrapper - Good:
fk-card-content,fk-card-text
Common Component Patterns:
Cards:
fk-card
├── fk-card-image
├── fk-card-content
│ ├── fk-card-title
│ └── fk-card-text
└── fk-card-footer
Navigation:
fk-nav
├── fk-nav-logo
├── fk-nav-menu
│ └── fk-nav-link
└── fk-nav-actions
Hero:
fk-hero
├── fk-hero-content
│ ├── fk-hero-title
│ ├── fk-hero-subtitle
│ └── fk-hero-actions
└── fk-hero-media
Forms:
fk-form
├── fk-form-group
│ ├── fk-form-label
│ └── fk-form-input
└── fk-form-actions
Phase 3: Utility Classes
Utility Naming:
- Format:
fk-[property]-[value] - Examples:
fk-text-lg,fk-space-md,fk-grid-3
Spacing Utilities:
- Use t-shirt sizing:
xs,sm,md,lg,xl,2xl,3xl - Directional:
py(vertical),px(horizontal),pt(top),pr(right),pb(bottom),pl(left) - Same for margins:
my,mx,mt,mr,mb,ml
Typography Utilities:
- Size:
fk-text-[xs|sm|md|lg|xl|2xl|3xl] - Weight:
fk-text-[light|medium|semibold|bold] - Alignment:
fk-text-[left|center|right] - Transform:
fk-text-[uppercase|lowercase|capitalize]
Layout Utilities:
- Flexbox:
fk-flex,fk-flex-col,fk-flex-center,fk-flex-between - Grid:
fk-grid,fk-grid-2,fk-grid-3,fk-grid-4,fk-grid-6 - Container:
fk-container,fk-section
Phase 4: State Modifiers (Combo Classes)
State Modifier Rules:
- Always use as combo classes with
is-prefix - Applied in addition to base class
- Example:
<div class="fk-button is-primary">...</div>
Common States:
is-active Currently active/selected
is-disabled Disabled interaction
is-hidden Hidden visibility
is-visible Visible (override hidden)
is-loading Loading state
is-error Error state
is-success Success state
is-primary Primary variant
is-secondary Secondary variant
is-tertiary Tertiary variant
is-featured Featured/highlighted
is-horizontal Horizontal layout
is-vertical Vertical layout
is-expanded Expanded state (accordions, dropdowns)
is-collapsed Collapsed state
Applying Combo Classes in Webflow:
- Select element
- Add base class:
fk-button - Add combo class:
is-primary - Element has both classes:
fk-button is-primary - Style the combo:
.fk-button.is-primary { ... }
Phase 5: Responsive Design
Responsive Modifiers:
- FlowKit uses combo classes for responsive behavior
- Format:
.[breakpoint]-[value] - Example:
fk-grid-4.tablet-2.mobile-1
Breakpoints:
Desktop (default): No modifier needed
Tablet: .tablet-[value]
Mobile: .mobile-[value]
Responsive Grid Example:
Base: fk-grid-4 (4 columns on desktop)
+ Combo: .tablet-2 (2 columns on tablet)
+ Combo: .mobile-1 (1 column on mobile)
Result: <div class="fk-grid-4 tablet-2 mobile-1">
Responsive Text Example:
Base: fk-text-3xl (48px on desktop)
+ Combo: .tablet-2xl (32px on tablet)
+ Combo: .mobile-xl (24px on mobile)
Result: <div class="fk-text-3xl tablet-2xl mobile-xl">
Phase 6: Best Practices
Always:
- ✅ Use
fk-prefix for all components and elements - ✅ Use hyphens to separate words
- ✅ Use lowercase only
- ✅ Keep component names semantic and concise
- ✅ Use combo classes for modifiers and states
- ✅ Combine utilities freely (
fk-flex fk-flex-center fk-space-md) - ✅ Follow component-element hierarchy
- ✅ Use responsive combo classes for breakpoints
Never:
- ❌ Omit
fk-prefix from components - ❌ Use underscores or spaces
- ❌ Use uppercase or camelCase
- ❌ Create overly specific class names
- ❌ Nest elements more than 3 levels deep
- ❌ Mix FlowKit with other naming systems
- ❌ Create standalone modifier classes (use combo classes)
Component vs Utility:
Use components when:
- Building reusable UI patterns (cards, buttons, navigation)
- Need semantic meaning
- Multiple instances across site
- Example:
fk-card,fk-nav,fk-hero
Use utilities when:
- Applying single-purpose styling (spacing, typography, layout)
- Quick adjustments without new classes
- Consistent spacing/sizing across site
- Example:
fk-text-lg,fk-space-md,fk-flex-center
Utility Stacking: Utilities can be freely combined:
<div class="fk-flex fk-flex-center fk-space-md fk-py-lg">
Content
</div>
Component + Utility Combo:
<div class="fk-card fk-shadow-lg fk-rounded-lg">
<div class="fk-card-content fk-space-lg">
<h3 class="fk-card-title fk-text-xl fk-text-bold">Title</h3>
</div>
</div>
Phase 7: Common Mistakes & Fixes
Mistake 1: Missing Prefix
❌ card, button, nav
✅ fk-card, fk-button, fk-nav
Mistake 2: Wrong Case
❌ FK-Card, fk-Button, Fk-nav
✅ fk-card, fk-button, fk-nav
Mistake 3: Wrong Separator
❌ fk_card_title, fk.card.title
✅ fk-card-title
Mistake 4: camelCase/PascalCase
❌ fkCardTitle, FkCardTitle
✅ fk-card-title
Mistake 5: Modifier as Standalone Class
❌ <div class="fk-button-primary">
✅ <div class="fk-button is-primary">
Mistake 6: Too Much Nesting
❌ fk-hero-content-wrapper-section-title-text
✅ fk-hero-content, fk-hero-title
Mistake 7: Overly Specific Names
❌ fk-product-feature-card-with-image-and-price
✅ fk-card (use combo: is-product)
Mistake 8: Wrong Responsive Pattern
❌ fk-grid-3-tablet-2 (single class)
✅ fk-grid-3 tablet-2 (two classes)
Phase 8: FlowKit Version Notes
FlowKit v2 (Current):
- New naming conventions (documented here)
- Enhanced grid system with responsive combos
- Expanded utility collection
- Improved component library
- Better variable system
Key v2 Changes:
- Standardized
fk-prefix across all components - Introduced
is-prefix for state modifiers (combo classes) - Added responsive combo classes (
.tablet-,.mobile-) - Expanded spacing scale (xs to 3xl)
- More semantic utility names
Migration from v1: If user has v1 FlowKit classes:
- Add
fk-prefix where missing - Convert modifiers to
is-combo classes - Update responsive classes to combo format
- Check spacing utilities for new scale
Phase 9: Performance Optimization
Class Creation:
- Create base component classes first
- Then create element classes
- Finally create utility classes
- Use
data_style_toolin batches of 10-15 classes
Element Updates:
- Process elements in groups of 10-15
- Show progress for large batches
- If >50 elements, ask user to confirm batch size
Designer Connection (only if using the optional designer_tool convenience):
- Class inspection, style creation, and element updates (
data_element_tool,data_style_tool) never need Designer — this only applies if the user asked to work with the page currently open in Designer, or to interactively select elements - If connection lost mid-batch, pause and ask user to reconnect before the next
designer_toolaction - Save progress between batches
Phase 10: Error Handling
Common Errors:
1. Designer Not Connected (only relevant when using designer_tool):
❌ Error: Cannot get current page or select elements - Designer not connected
Solution:
1. Open Webflow Designer
2. Open the target site
3. Connect to Designer in Claude Code
4. Retry operation
(Not needed for the default headless workflow — use `data_pages_tool` with `list_pages` instead.)
2. Class Already Exists:
⚠️ Warning: Class 'fk-button' already exists
Options:
1. Skip creation (use existing)
2. Update existing class
3. Create with different name
3. Invalid Class Name:
❌ Error: Class name 'fk-My Button' is invalid
Issues:
- Contains spaces
- Contains uppercase
Suggested: 'fk-my-button'
4. Style Property Not Supported:
⚠️ Warning: Property 'custom-property' not supported
This may be:
- Custom CSS property
- Webflow doesn't support via Designer API
- Typo in property name
Recommendation: Apply manually in Designer
Edge Cases
Case 1: Third-Party Integration Classes If integrating with third-party libraries (e.g., animations, sliders):
- Keep third-party classes separate
- Add FlowKit wrapper:
<div class="fk-slider"><div class="swiper">...</div></div> - Don't force FlowKit naming on third-party classes
Case 2: Legacy Code Migration When migrating large existing site:
- Create FlowKit classes first
- Apply to new sections
- Gradually refactor old sections
- Keep both systems temporarily for backwards compatibility
Case 3: Custom Naming Requirements If client has existing naming system:
- Discuss FlowKit benefits
- Show side-by-side comparison
- Offer hybrid approach: FlowKit for new components, keep old for existing
- Or fully refactor (more time, better long-term)
Case 4: Component Library Conflicts If site uses another framework (Bootstrap, Tailwind):
- FlowKit can coexist but not recommended
- Choose one primary system
- Use FlowKit for custom components
- Use other framework for pre-built components
Case 5: Utility Class Explosion If too many utility classes on single element:
- Consider creating component class instead
- Example: Instead of
fk-flex fk-flex-center fk-space-md fk-py-lg fk-px-xl fk-rounded-lg fk-shadow - Create:
fk-panelwith those properties built-in
Production Checklist
Before considering FlowKit implementation complete:
Setup:
- Target site identified
- Target page found (via
data_pages_toollist_pages, ordesigner_toolif using the current open page) - Scope defined with user
Component Structure:
- All components use
fk-prefix - Component hierarchy is logical (max 3 levels)
- Element names are semantic
- Modifiers use combo classes with
is-prefix
Utilities:
- Spacing utilities use t-shirt sizing (xs-3xl)
- Typography utilities cover all text styles
- Layout utilities handle flex/grid needs
- Color utilities align with brand
Responsive:
- Responsive combo classes defined for key components
- Breakpoint modifiers tested (tablet, mobile)
- Grid systems adapt properly
States:
- State modifiers defined (is-active, is-disabled, etc.)
- Hover/focus states work correctly
- Active states styled properly
Documentation:
- Component structure documented
- Utility classes listed
- Responsive behavior explained
- State modifiers documented
Validation:
- All classes follow naming conventions
- No uppercase letters
- No underscores
- All have proper prefixes
Performance:
- Classes created in batches
- Progress shown for large operations
- No duplicate classes created
User Experience:
- Clear feedback provided
- Progress indicators shown
- Success confirmation given
- Next steps recommended
Interactions
Create and edit IX3 interactions (GSAP animations) through Webflow MCP.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before any other tool call. It includes a short Interactions section that namesdata_interactions_tooland tells you to call actionguidebefore writing. Payload shapes come from thatguideaction, not from the short section. - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify the target site - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto find the target page by name or slug - Use Webflow MCP's
data_interactions_toolfor guide / list / get / create / update / delete - Use Webflow MCP's
data_style_toolto resolve class style-block ids before targetingwf:class - DO NOT use any other tools or methods for Webflow interaction CRUD
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective) - No Designer or MCP Bridge required.
data_interactions_toolis headless, the same waydata_element_toolis. Designer is only useful afterward, to inspect the Interactions panel or Preview. Do not ask the user to open the Bridge app in order to list or write interactions. - If
data_interactions_toolis absent from the tool list and the session containssite/interactions/interactions.ix3.json, edit that file. Otherwise usedata_interactions_tool. This skill is the MCP path.
Tool surface
- Scopes:
pages:read/pages:write - Compound tool:
data_interactions_tool - Actions:
guide,list_interactions,get_interaction,create_interaction,update_interaction,delete_interaction siteIdandpageIdare top-level tool arguments (page context / create bookkeeping). They are not insidecreate_interactionargs.guideis live. Calldata_interactions_toolwith actionguide, or readwebflow://guides/interactions. Same markdown either way. Prefer it for legal payload shapes. This skill is the workflow around those shapes;references/are the set-pieces the guide does not carry.create_interactionargs:name(required),scope(optional, default site),triggers(required array),timelines(required array), optionaltimelineDefaults, optionalconditionalPlayback- Component and variant scope work.
{type:"component", componentId, variants?}is accepted on create and update.variantsholds variant option ids fromdata_component_variants_tool— omitting it or passing[]both mean every variant. Do not setlibraryProfileId; it marks the interaction library-owned. A component or variant id that does not exist is rejected. See references/envelope-and-targets.md.
Instructions
Phase 1: Discovery
- Call
webflow_guide_toolfirst — always the first MCP tool call. It covers general MCP conventions and includes a short Interactions section (data_interactions_tool, its actions, top-levelsiteIdandpageId). That section is not the payload contract. Get legal shapes fromdata_interactions_tool→guide. - Get the site:
data_sites_toolwithlist_sites. If only one site exists, use it. - Get the page:
data_pages_toolwithlist_pages. You need that page's ID as top-levelpageIdon everydata_interactions_toolcall. - Confirm the tool is registered: if
data_interactions_toolis unregistered, stop and tell the user rather than working around it. Do not treat a missing tool as a missing Bridge session, and do not ask the user to open Designer or the MCP Bridge. If the session containssite/interactions/interactions.ix3.json, edit that file instead. - An empty list is not proof the site has none.
data_interactions_toolreads IX3 only. A site whose interactions are IX2 returns{items: [], total: 0}with no error, indistinguishable from a site that has none. Never conclude a site has no motion from an empty read: tell the user what you got and have them check the version selector at the bottom of the Interactions panel. A create still succeeds on an IX2 site, and the site then carries both runtimes.
Phase 2: Read the contract for what you are building
- Call
data_interactions_tool→guidefor legal payload shapes. Then read thereferences/file for your trigger when you need a set-piece the guide does not carry. See the Reference map below. Do this before your first write on anything beyond the five inline examples in this file. - Do not invent
+=/</>timing.positionstrings or{reducedMotion:"skip"}. A bare number fortiming.durationis seconds (0.4, not400).
Reference map
| User asks for | Read |
|---|---|
| Click | references/trigger-click.md |
| Hover, mouse enter/leave | references/trigger-hover.md |
| Page load | references/trigger-load.md |
| Scroll, scrub, parallax | references/trigger-scroll.md |
| Mouse move, cursor follow | references/trigger-mouse-move.md |
| Custom JS event | references/trigger-custom.md |
| Navbar, dropdown, conditions | references/gated-capabilities.md |
| Variable, Rive, Animate Rive | data_interactions_tool action guide |
| Envelope, IDs, scope, targets, filters | references/envelope-and-targets.md |
Properties, values, tt, timing, splitText | references/actions-and-properties.md |
| Roles, groups, percent canvas | references/timelines-and-groups.md |
| Reduced motion, breakpoint playback | references/conditional-playback.md |
| Editing an existing interaction | references/updating-interactions.md |
| Size and count limits | references/limits-and-budgets.md |
| A write succeeded but the user cannot edit it | references/panel-traps.md |
| A write succeeded but nothing animates | references/rejects-index.md → "nothing to decode" |
| Decoding a rejection message | references/rejects-index.md |
| Which triggers and properties exist at all | references/capabilities.generated.md |
Start at references/index.md if you are unsure. It also
explains the enforcement tags — in particular [PANEL-TRAP], which means the
write will succeed but leave the user with something they cannot edit in the
Designer, and [LEGACY-OK-ON-UPDATE], which means you must pass a stored value
through untouched rather than "fixing" it.
Phase 3: Plan (before any write)
- Resolve class targets: prefer style-block id arrays from
data_style_tool; class name strings are accepted. Confirm withquery_stylesthat the class resolves to exactly one style block — a name reused as the leaf of several combo chains returns several, and each targets a different element. When an element needs its own class, create it withcreate_stylenaming the fullparent_style_nameschain you intend to apply, then apply that same chain withdata_element_toolset_style; a chain that does not already exist as a style block is refused - Plan the payload against the reference you read in Phase 2: object format, legal trigger/target, fresh action ids
- Request explicit confirmation before create/update/delete:
- "Would you like me to create this click fade?"
- "Before I write this interaction: [plan]. Confirm to proceed."
Phase 4: Write (after confirmation only)
create_interactionorupdate_interactionondata_interactions_toolupdate_interactionis a partial: omitted fields stay, provided values replace,nullclearstimelineDefaults/conditionalPlayback.timelinesis a full replace when sent.
Phase 5: Verify
get_interactionwith the returned id- Report what was created/updated
- On reject: read the error, look it up in references/rejects-index.md, fix the payload. Do not invent GSAP position operators, and do not retry the same shape hoping for a different result — every rejection here is deterministic.
- A successful write is not proof the animation runs. Several legal payloads save, read back byte-identical, and do nothing: a
[from, to]pair on a To tween, a class array that is not one combo chain, a mouse-move trigger with no target,control: "reverse"on a first click.get_interactioncannot detect any of them. Check the payload against the Guidelines below before reporting success, and if the user says nothing happens, start at references/rejects-index.md → "When there is nothing to decode" instead of rewriting the interaction.
Examples
Replace STYLE_BLOCK_ID with a style-block id. Mint a fresh unique id on every action.
Example 1: Click fade
User: "Add a click fade interaction"
- Call
webflow_guide_tool list_sites→list_pages→ resolveSTYLE_BLOCK_IDviadata_style_tool- Call
data_interactions_tool→guidefor payload shapes. Read references/trigger-click.md only if you need a set-piece the guide does not carry. - Present the plan and wait for confirmation
- After confirmation,
create_interaction:
{
"name": "Click fade",
"triggers": [
{
"extensionKey": "wf:click",
"config": { "control": "play" },
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
}
],
"timelines": [
{
"actions": [
{
"id": "act-click-fade",
"name": "Fade",
"tt": 2,
"timing": { "duration": 0.4 },
"properties": { "wf:transform": { "opacity": ["0%", "100%"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
get_interactionto verify
A FromTo holds its from-state at rest, so this element renders at opacity: 0 until the first click — measured on a published page. That is what fading in means, but tell the user, because an element they cannot see reads as a failed write rather than a working interaction. If it should be visible before the click, animate a property whose rest value is already visible (an x offset, a colour) or use a To.
Example 2: Page load fade
User: "Fade this section in when the page loads"
Same discovery, reference read, and confirmation. Load omits the trigger target. Action targets must not be wf:trigger-only.
{
"name": "Load fade",
"triggers": [{ "extensionKey": "wf:load", "config": { "control": "play" } }],
"timelines": [
{
"actions": [
{
"id": "act-load-fade",
"name": "Fade",
"tt": 2,
"timing": { "duration": 0.4 },
"properties": { "wf:transform": { "opacity": ["0%", "100%"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
Example 3: Scroll scrub
User: "Scrub a fade as the user scrolls"
Scroll is standalone. A scrub needs a numeric scrub (not true), a roleless timeline with canvasDuration: 1, and action timing.duration equal to that canvas so the tween spans the full pass. Omit playback control / delay / jump / speed. Omitting scrub is a one-shot play when the range is crossed — not a scrub.
{
"name": "Scroll scrub fade",
"triggers": [
{
"extensionKey": "wf:scroll",
"config": {
"scrollTriggerConfig": {
"start": "top bottom",
"end": "top 10%",
"scrub": 0.3
}
},
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
}
],
"timelines": [
{
"canvasDuration": 1,
"actions": [
{
"id": "act-scroll-scrub",
"name": "Fade",
"tt": 2,
"timing": { "duration": 1 },
"properties": {
"wf:transform": { "opacity": ["0%", "100%"], "xPercent": [-40, 0] }
},
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
Play-once variant (a reveal, not a scrub). Drop scrub and canvasDuration, put timing.duration back in seconds — and send enter: "play". The host stamps absent toggle keys on create and on trigger replacement (enter: "play", the other three "none") and leaves an explicit "none" alone, so an omission is repaired rather than left inert. Send enter anyway: it is what the panel writes, and it is correct on both sides of that rollout.
{
"extensionKey": "wf:scroll",
"config": {
"scrollTriggerConfig": {
"start": "top 90%",
"end": "bottom 15%",
"enter": "play",
"leaveBack": "reset"
}
},
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
}
leaveBack: "reset" is optional and replays the reveal when the user scrolls back up. Use a From (tt: 1) for the reveal itself so the element starts hidden.
Example 4: Hover enter / leave
User: "Fade in on hover enter and out on leave"
Use the role form: one wf:hover trigger with multiTimeline: true, and two timelines tagged mouseEnter and mouseLeave via triggerMetadata. Roles must be exactly those strings and unique per timeline. Do not mix this with legacy hover type / hover / custom.
{
"name": "Hover fade",
"triggers": [
{
"extensionKey": "wf:hover",
"config": { "pluginConfig": { "multiTimeline": true } },
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
}
],
"timelines": [
{
"triggerMetadata": { "role": "mouseEnter" },
"actions": [
{
"id": "act-hover-in",
"name": "Fade in",
"tt": 2,
"timing": { "duration": 0.3 },
"properties": { "wf:transform": { "opacity": ["0%", "100%"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
},
{
"triggerMetadata": { "role": "mouseLeave" },
"actions": [
{
"id": "act-hover-out",
"name": "Fade out",
"tt": 2,
"timing": { "duration": 0.3 },
"properties": { "wf:transform": { "opacity": ["100%", "0%"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
No caveat needed any more. An earlier version of this skill warned that the panel would not offer a remove button for either action group. That was true when written, and webflow#117817 fixed it on 2026-08-19 — Remove now renders for this shape when a Hover owner exists. Confirmed in the Designer afterwards: a role-form hover authored through MCP animates correctly and shows a delete control on both Actions groups, the same as the split form.
The two-trigger split the panel prefers is authorable, but the discriminator
is config.pluginConfig.eventMode, with the values 'enter' / 'leave' —
not mouseEnter/mouseLeave, and not at config level, where it is silently
discarded (see the first Guidelines section). eventMode also requires a boolean
multiTimeline beside it, and the interaction needs control: "play" once it has
two or more action groups.
Use multiTimeline: false on the split, not true. The runtime branches on
that flag: true is two-group role mode, which emits mouseEnter / mouseLeave
role callbacks and is the role form above; false is single-group mode, where each
trigger drives its own group and eventMode gates which event binds
(bindEnter = eventMode !== 'leave'). The split routes by groupId, so it wants
false.
"triggers": [
{
"extensionKey": "wf:hover",
"config": {
"control": "play",
"assignedGroupId": "grp-in",
"pluginConfig": { "multiTimeline": false, "eventMode": "enter" }
},
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
},
{
"extensionKey": "wf:hover",
"config": {
"control": "play",
"assignedGroupId": "grp-out",
"pluginConfig": { "multiTimeline": false, "eventMode": "leave" }
},
"target": { "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
}
]
with groupId: "grp-in" / "grp-out" on the two timelines. groupId survives to
the host, and an assignedGroupId matching no timeline group is rejected rather
than stored inert. Note multi-timeline hover routes by timeline role first,
then by group.
Both forms work, and neither costs the user anything measurable. Verified
side by side in the Designer, both authored through MCP against the same element:
identical playback (y 0 → -24 on enter, -24 → 0 on leave) and a delete
control on both action groups in both forms.
So this is a weak preference: prefer the split form above, because it is the shape the panel writes itself and the user sees what they would have built by hand. The role form (Example 4) is equally valid — the panel does not write it, but it does edit it.
Earlier versions of this skill told agents to trade playback fidelity against a missing remove button. There is no such tradeoff. See references/trigger-hover.md.
For enter only, send one trigger with pluginConfig: { "multiTimeline": false } and a single timeline.
If the user only wants an enter animation, send one trigger with pluginConfig: { "multiTimeline": false } — omitting the key drops to the legacy editor instead. Either way, the panel may not offer "Add separate hover out" on a single-timeline hover, so author the full split above whenever the user wants both directions.
Example 5: Mouse-move
User: "Move this element with the cursor"
Mouse-move is standalone. It validates without a target but never fires without one, so always send a target — wf:viewport (value: "") for page-wide tracking, or wf:inst / wf:class to scope it. Every timeline needs a unique role from mouseX / mouseY / interval. Omit playback control / delay / jump / speed. See references/trigger-mouse-move.md.
{
"name": "Mouse follow",
"triggers": [
{
"extensionKey": "wf:mouse-move",
"config": {},
"target": { "extensionKey": "wf:viewport", "value": "" }
}
],
"timelines": [
{
"triggerMetadata": { "role": "mouseX" },
"actions": [
{
"id": "act-mouse-x",
"name": "Follow X",
"tt": 2,
"timing": { "duration": 0.4 },
"properties": { "wf:transform": { "x": ["0px", "40px"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
},
{
"triggerMetadata": { "role": "mouseY" },
"actions": [
{
"id": "act-mouse-y",
"name": "Follow Y",
"tt": 2,
"timing": { "duration": 0.4 },
"properties": { "wf:transform": { "y": ["0px", "40px"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
Example 6: Custom JS event
User: "Play this when my script fires an event"
Three non-obvious requirements, all mandatory:
- The trigger target must be
wf:body(value: ""). Any other key is rejected. - The event name lives at
config.pluginConfig.eventName. Atconfiglevel it is silently discarded and the trigger can never fire. - It is not a DOM
CustomEvent. Dispatching one does nothing. The site fires it through the IX3 module.
{
"name": "Custom event flash",
"triggers": [
{
"extensionKey": "wf:custom",
"config": {
"control": "play",
"pluginConfig": { "eventName": "my-event" }
},
"target": { "extensionKey": "wf:body", "value": "" }
}
],
"timelines": [
{
"actions": [
{
"id": "act-custom-flash",
"name": "Flash",
"tt": 2,
"timing": { "duration": 0.4 },
"properties": { "wf:transform": { "opacity": ["100%", "20%"] } },
"targets": [
{ "extensionKey": "wf:class", "value": ["STYLE_BLOCK_ID"] }
]
}
]
}
]
}
Tell the user how to fire it. This is the part that looks broken otherwise:
const wfIx = Webflow.require('ix3');
wfIx.emit('my-event');
emit is the only firing method — the module exposes
{getInstance, emit, destroy, ready, instance}. There is no trigger, dispatch,
or fire. A non-string or whitespace-only eventName is rejected at the write
boundary; an absent one is accepted for backward compatibility and yields a
trigger that never fires. See references/trigger-custom.md.
Guidelines
Read this one first: unknown config keys are silently discarded
triggerConfigSchema is a non-strict Zod object, so any key you put on
trigger.config that is not a declared field is dropped without an error. The
write succeeds, the response looks clean, get_interaction round-trips
byte-identically, and your field is gone.
Declared config fields: control, delay, jump, speed, controlType,
scrollTriggerConfig, pluginConfig, assignedGroupId, assignedTimelineRole,
conditionalLogic.
Everything plugin-specific goes inside config.pluginConfig — eventName,
eventMode, multiTimeline, smoothness, and anything else a plugin defines.
Putting one of those at config level is the single most expensive mistake on
this surface, because nothing tells you:
// WRONG — silently discarded, trigger never fires
"config": { "eventName": "my-event" }
// RIGHT
"config": { "pluginConfig": { "eventName": "my-event" } }
A dogfood run lost three fields this way (eventName, eventMode, and a
mistyped easing) and misfiled all three as missing API features. If a field you
sent is absent from the response, assume you addressed it wrong before you
conclude it is unsupported.
Easing: timing.ease is a number, not a string
ease is either a non-negative integer index into the built-in easing table
or an advanced-ease object. A string is rejected with a bare Invalid input that
does not tell you this.
| Index | Name | Index | Name | Index | Name | ||
|---|---|---|---|---|---|---|---|
| 0 | none (Linear) | 11 | power4.out | 22 | elastic.in | ||
| 1 | power1.in | 12 | power4.inOut | 23 | elastic.out | ||
| 2 | power1.out | 13 | back.in | 24 | elastic.inOut | ||
| 3 | power1.inOut | 14 | back.out | 25 | expo.in | ||
| 4 | power2.in | 15 | back.inOut | 26 | expo.out | ||
| 5 | power2.out | 16 | bounce.in | 27 | expo.inOut | ||
| 6 | power2.inOut | 17 | bounce.out | 28 | sine.in | ||
| 7 | power3.in | 18 | bounce.inOut | 29 | sine.out | ||
| 8 | power3.out | 19 | circ.in | 30 | sine.inOut | ||
| 9 | power3.inOut | 20 | circ.out | ||||
| 10 | power4.in | 21 | circ.inOut |
The panel's "Power 1 out" is 2; its "Linear" is 0.
"timing": { "duration": 0.4, "ease": 2 }
Advanced eases are objects discriminated on type. Just write one — no guard
rejects an advanced ease at the write boundary:
back {curve,power}, elastic {curve,amplitude,period}, steps {stepCount},
rough {templateCurve,points,strength,taper,randomizePoints,clampPoints},
slowMo {linearRatio,power,yoyoMode}, expoScale {startingScale,endingScale,templateCurve},
customWiggle {wiggles,wiggleType}, customBounce {strength,squash,endAtStart},
customEase {bezierCurve}. curve is in / out / inOut.
"timing": { "duration": 0.4, "ease": { "type": "back", "curve": "out", "power": 1.7 } }
timing.stagger.ease takes the same shape. A 4-number bezier array is not
accepted — use {type: "customEase", bezierCurve: "..."}.
Class change: wf:class
One property, named class, Set-only (tt: 3):
"tt": 3,
"properties": {
"wf:class": {
"class": { "operation": "addClass", "selectors": ["STYLE_BLOCK_ID"] }
}
}
operation is addClass / removeClass / toggleClass. A bare array, a bare
string, or {add: [...]} are all rejected.
stagger is an object
{amount?, axis?, each?, ease?, from?, grid?}. A bare number is rejected.
each/amount— seconds, or a"250ms"stringaxis—'x'/'y'ease— the same index-or-object shape astiming.easefrom—'start' | 'center' | 'end' | 'edges' | 'random', a number, ornullgrid—'auto', a[columns, rows]number pair, ornull.'none'is rejected.
"timing": { "duration": 0.5, "stagger": { "each": 0.05, "from": "start", "grid": [2, 2] } }
filterContext.relationship enum
none · within · direct-child-of · contains · direct-parent-of ·
next-to · next-sibling-of · prev-sibling-of. CSS-flavoured guesses like
descendants are rejected.
Target value shapes
| Key | Value |
|---|---|
wf:class | style-block id array, or a class name string |
wf:inst | [componentId, elementId] — for a page-level element the componentId slot is the page id. Which form is legal follows scope: component scope takes the component-definition id, site and pages scope require the page id |
wf:selector | a CSS selector string, e.g. "body". This is how you target the body from an action; wf:body is trigger-context-only |
wf:body, wf:viewport | "" — trigger targets only |
wf:any-element | "*" — not "". Action targets only |
wf:trigger-only, wf:trigger-only-parent | "". Action targets only |
wf:attribute | an attribute name or a full selector. "data-thing" is stored as [data-thing] and matches every element carrying it; pass '[data-thing="x"]' when several elements share the attribute |
wf:id is not a target key. It is refused in every context with
target type "wf:id" is not offered by the Designer (shouldShow: false in all contexts). Use wf:selector, wf:class, or wf:inst instead.
To target by DOM id, use wf:selector with '#the-id'. There are seven
authorable target keys, not eight.
wf:any-element is the one key whose value is a wildcard, not a placeholder.
The three action-only keys look interchangeable and are not: "" on
wf:any-element is refused with "wf:any-element" value must be "*". Because
these are usually authored one row per filterContext relationship, getting it
wrong loses the whole batch rather than one row.
wf:inst and wf:trigger-only reject an active filterContext; the stamped
relationship: 'none' placeholder is fine.
Caps
Triggers per interaction 20 · timelines per interaction 5 · actions per
timeline 200 · targets per action 20 · canvasDuration ≤ 12s ·
groupId 1–64 chars · random-array sets 2–12 values · IX3 value total
65,536 bytes.
MCP applies these as Zod .max() on create and update. The Designer host
raises the ceiling for already-stored over-cap interactions; MCP does not. So
reading a 200+-action timeline and resubmitting it to change one action fails
over MCP.
Tool-schema errata
The data_interactions_tool JSON Schema currently describes
conditionalPlayback as {"type": "object"} with the example
{reducedMotion:"skip"}. Both are wrong. The server validator requires an
array; see the conditionalPlayback bullet below. Trust this skill over the
tool description on that field.
Also note siteId/pageId placement differs across the tool family: top-level
for data_interactions_tool, data_style_tool, and data_element_tool; nested
site_id inside the action for data_pages_tool, data_assets_tool, and
data_agent_instructions_tool.
Everything else
- Object format only:
{ extensionKey, value, filterContext? }. NestedfilterByis a 2-tuple["wf:class", ["STYLE_BLOCK_ID"]], never an object. - IDs: omit timeline
idon create (the host mints it). Every action needs a fresh uniqueid. Do not send triggerid. - Opacity lives under
wf:transform(e.g.["0%","100%"]), neverwf:style. - Class targets: style-block id arrays preferred; class name strings are accepted.
- A
wf:classid array is ANDed into one compound selector, not a list of alternatives:["a","b"]resolves to.a.b. The host expands a combo class's parents for you, so pass the one leaf id. Ids from two different combo chains produce a selector no element carries, and the target resolves to nothing with no error. One target means one class or one combo chain — animate two different sets of elements with two actions. - A leaf class name reused across chains (
.btn.liftand.btn.cta.liftare two style blocks both namedlift) is rejected when passed as a name string and matches the wrong element when passed as ids. Give each element its own class instead. - Send only what the Interactions panel can author. Worker Zod is lenient; illegal shapes fail on the Designer write path.
conditionalPlaybackis an array of{ type, behavior }(and breakpoint form), not{reducedMotion:"skip"}. Example:[{ "type": "prefers-reduced-motion", "behavior": "dont-animate" }].- Load omits trigger
targetandpluginConfig. - Scroll and mouse-move omit playback
control/delay/jump/speed. - A scroll without
scrubneedsenter: "play". The host stamps absent toggle keys on persist (enter: "play", the rest"none") and keeps an explicit"none", but sendenteryourself: the panel always writes all four toggles, and being explicit is correct regardless of where that stamp has rolled out.scrollTriggerConfigitself is never invented — missing or null is rejected. - Scroll scrub: send numeric
scrub,canvasDuration: 1, and actiontiming.duration: 1. A tiny duration occupies ~1% of the scroll range and looks like nothing happened. control: "reverse"is a no-op on the first click (the playhead starts at 0). For a reverse the user can try in Preview, usetogglePlayReverse(pluginConfig.clickomitted or"each").- A To tween reads only its
toslot.[from, to]ontt: 0is half discarded and GSAP animates from the element's live value, soscale: [0.55, 1.15]on an unscaled element goes 1 → 1.15 andopacity: ["20%","100%"]on an opaque element does nothing at all. Usett: 2whenever the animation needs a start value. - Do not put a click or hover trigger on an element its own from-state collapses (
scaleX: 0,width: 0). No box is left to click. Trigger on a parent and animate the child. - Grouped timelines are authorable.
groupId(1–64 characters) is accepted on the MCP timeline input, andconfig.assignedGroupIdon a click or hover trigger routes to it. AnassignedGroupIdthat matches no timelinegroupIdis rejected rather than stored inert, so mismatches surface as an error instead of a dead interaction. Load, scroll, and continuous triggers ignoreassignedGroupId. wf:navbarandwf:dropdownare not authorable, and neither arewf:focus,wf:blur, orwf:change. The guards take no flag or session argument, so this holds for every caller regardless of Statsig state — no flag turns it on for you. Navbar and dropdown are registered in the Designer and excluded from the default capability set; focus, blur, and change have no Designer schema at all. Tell the user the trigger is unavailable rather than attempting a write. See references/gated-capabilities.md.wf:variable,wf:rive, andwf:animate-riveare authorable; callguidefor their shapes.- No GSAP position operators (
+=,<,>) intiming.position. Use a finite number (seconds) or'500ms'. - Duration is seconds.
timing.duration: 0.4is 400ms.400is 400 seconds. Use"400ms"if you think in milliseconds. - From / FromTo (
tt: 1/2) sit at the from-state until the trigger fires. Prefer To (tt: 0or omit) when the element should be visible at rest. splitTextneeds a target that already contains copy — in itself or a descendant. The element type is not the constraint: a Block / Div whose text is a child node splits fine (verified on a published page: a.pg-cardBlock containing "Card one" produced twogsap_split_wordspans). What fails silently is a target with no text anywhere inside it — that saves and animates nothing.- Roles live on
timelines[].triggerMetadata, not on the trigger. Mouse-move needs a uniquemouseX/mouseY/intervalper timeline. - On reject: read the error, look it up in references/rejects-index.md, do not invent fields.
Install
npx -y skills add webflow/webflow-skills --skill 'webflow-mcp:interactions' --yes
Optional --agent claude-code (or cursor). Callers need scopes pages:read / pages:write.
Link Checker
Audit and fix broken or insecure links across your Webflow site to improve SEO and user experience.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolto get best practices before starting - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify available sites - Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve site details - Use Webflow MCP's
data_pages_toolwith actionlist_pagesto get all pages - Use Webflow MCP's
data_pages_toolwith actionget_page_contentto extract links from static pages - Use Webflow MCP's
data_pages_toolwith actionupdate_static_contentto fix links on static pages - Use Webflow MCP's
data_cms_toolwith actionget_collection_listto get all CMS collections - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto get collection schemas - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsto get CMS items with links - Use Webflow MCP's
data_cms_toolwith actionupdate_collection_itemsto fix links in CMS (draft) - Use Webflow MCP's
data_cms_toolwith actionpublish_collection_itemsto publish fixed CMS items - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective) - No Designer connection is required — both static page and CMS link fixes go through
data_tools
Instructions
Phase 1: Site Selection & Discovery
- Get site information: Use Webflow MCP's
data_sites_toolwith actionlist_sitesto identify target site - Confirm scope: Ask user if they want to check:
- Static pages only
- CMS content only
- Both static pages and CMS content
- List pages: Use Webflow MCP's
data_pages_toolwith actionlist_pagesto get all pages - List collections: Use Webflow MCP's
data_cms_toolwith actionget_collection_listto get all CMS collections
Phase 2: Link Extraction & Validation
- Extract links from static pages: Use Webflow MCP's
data_pages_toolwith actionget_page_contentfor each page- Identify all link elements (Link, Button, TextLink, LinkBlock)
- Capture: pageId, nodeName, URL, link text
- Extract links from CMS: Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsfor each collection- Identify Link fields and Rich Text fields with links
- Capture: collectionId, itemId, fieldName, URL
- Validate each link: Test URL accessibility
- Check for 4xx/5xx errors (broken links)
- Check for HTTP vs HTTPS (insecure links)
- Test if HTTP has HTTPS equivalent available
- Flag redirects (3xx status codes)
- Categorize results:
- ✅ Working links (2xx status)
- ❌ Broken links (4xx/5xx errors)
- ⚠️ Insecure links (HTTP when HTTPS available)
- 🔄 Redirects (3xx status)
- ⚪ Manual review needed (timeouts, DNS errors, etc.)
Phase 3: Analysis & Reporting
- Calculate statistics:
- Total links scanned
- Links by type (internal vs external)
- Links by status (working, broken, insecure, redirects)
- Links by location (static pages vs CMS)
- Generate health score: Calculate link health (0-100)
- Working links: +1 point each
- Broken links: -5 points each
- Insecure links: -2 points each
- Redirects: -1 point each
- Normalize to 0-100 scale
- Identify critical issues: Prioritize fixes
- 🔴 Critical: Broken links on high-traffic pages
- ⚠️ Warning: Insecure HTTP links
- 💡 Suggestion: Optimize redirects
Phase 4: Suggestion Generation & Approval
- Generate fix suggestions: For each problematic link, suggest fix
- Broken links: Remove link or update to correct URL
- Insecure links: Upgrade HTTP to HTTPS
- Redirects: Update to final destination URL
- Show preview with validation:
[1] ✓ Fix insecure link Page: About Us Element: Button "Learn More" Current: http://example.com Suggested: https://example.com ✅ HTTPS version verified working [2] ⚠️ Fix broken link Page: Blog Post "Getting Started" Element: Text link Current: https://oldsite.com/page Suggested: [REMOVE LINK or provide correct URL] ❌ URL returns 404 - manual review needed - Implement granular approval: Ask user which fixes to apply
- Type numbers to skip (e.g., "2,4")
- Type "all" to proceed with all automatic fixes
- Type "none" to cancel
- Flag manual review items separately
Phase 5: Execution & Confirmation
- Apply fixes to static pages: Use Webflow MCP's
data_pages_toolwith actionupdate_static_content- Update link URLs in nodes
- Process in batches of 20 links
- Apply fixes to CMS content: Use Webflow MCP's
data_cms_toolwith actionupdate_collection_items- Update Link fields directly
- Update links in Rich Text fields
- Process in batches of 50 items
- Publish changes (if requested): Use Webflow MCP's
data_cms_toolwith actionpublish_collection_items - Show progress: Display progress indicators for large operations
- Generate final report:
- Links scanned: X
- Links fixed: Y
- Links requiring manual review: Z
- Health score improvement: Before → After
Phase 6: Verification & Recommendations
- Verify fixes: Re-check fixed links to confirm success
- Report failures: Clearly identify any fixes that failed
- Provide recommendations:
- Schedule regular link checks (monthly/quarterly)
- Set up monitoring for critical external links
- Consider using 301 redirects for changed URLs
- Export report (optional): Offer to export findings
Examples
Example 1: Complete Site Audit
User prompt:
Run a complete link check on my site and fix any issues
Step 1: Site Selection
🔍 Link Checker: Site Selection
Available sites:
1. Company Website
2. Blog Site
3. Portfolio
Which site would you like to audit? (1/2/3)
Step 2: Scope Confirmation
📋 Link Checker Scope
What would you like to check?
1. Static pages only (faster)
2. CMS content only
3. Both static pages and CMS content (comprehensive)
Recommendation: Option 3 for complete audit
Your choice? (1/2/3)
Step 3: Extraction & Validation
🔄 Scanning Links...
Progress: ████████████████████ 100%
Found 247 links:
├── Static pages: 89 links (15 pages)
├── CMS content: 158 links (3 collections)
│ ├── Blog Posts: 142 links
│ ├── Team Members: 12 links
│ └── Products: 4 links
Validating links...
Progress: ████████████████████ 100% (247/247 checked)
✅ Working: 215 links (87%)
❌ Broken: 8 links (3%)
⚠️ Insecure: 18 links (7%)
🔄 Redirects: 6 links (2%)
Step 4: Analysis Report
📊 Link Health Report: Company Website
Overall Health Score: 76/100 ⚠️
## Issues Found:
### 🔴 Critical: Broken Links (8)
├── [1] Page: "About Us"
│ └── Link to: https://partner-site.com/old-page
│ Status: 404 Not Found
│ Impact: High (homepage)
│
├── [2] CMS: Blog Post "Product Launch"
│ └── Link to: https://press-release.com/announcement
│ Status: 404 Not Found
│ Impact: Medium
│
├── [3-8] 6 more broken links...
### ⚠️ Warning: Insecure Links (18)
├── [9] Page: "Contact"
│ └── Link: http://social-media.com/company
│ Fix: https://social-media.com/company
│ ✅ HTTPS verified working
│
├── [10] CMS: Blog Post "Getting Started"
│ └── Link: http://tutorial-site.com
│ Fix: https://tutorial-site.com
│ ✅ HTTPS verified working
│
├── [11-26] 16 more insecure links...
### 💡 Suggestion: Redirects (6)
├── [27] Page: "Services"
│ └── Link: https://example.com/old-url
│ Redirects to: https://example.com/new-url
│ Suggestion: Update to final destination
│
├── [28-32] 5 more redirects...
---
💡 Recommendations:
1. Fix 8 broken links immediately (SEO impact)
2. Upgrade 18 HTTP links to HTTPS (security)
3. Update 6 redirects to final URLs (performance)
Estimated time to fix: ~5 minutes
Step 5: Fix Preview
🔧 Proposed Fixes (26 total)
### Automatic Fixes Available (24):
[1] ✓ Upgrade to HTTPS
Page: Contact
Element: Button "Follow Us"
Current: http://social-media.com/company
New: https://social-media.com/company
✅ HTTPS verified working
[2] ✓ Upgrade to HTTPS
CMS: Blog Posts > "Getting Started" > content field
Current: http://tutorial-site.com
New: https://tutorial-site.com
✅ HTTPS verified working
[3] ✓ Update redirect
Page: Services
Element: Text link "Learn more"
Current: https://example.com/old-url
New: https://example.com/new-url
✅ Final destination verified
[4-24] ... 21 more automatic fixes
### Manual Review Required (2):
[25] ⚠️ Broken link - needs correction
Page: About Us
Element: Button "View Partner Site"
Current: https://partner-site.com/old-page
Issue: 404 Not Found
Action needed: Provide correct URL or remove link
[26] ⚠️ Broken link - needs correction
CMS: Blog Posts > "Product Launch" > content field
Current: https://press-release.com/announcement
Issue: 404 Not Found
Action needed: Update with correct URL or remove
---
Which fixes would you like to apply?
- Type "all" to apply all 24 automatic fixes
- Type numbers to skip (e.g., "3,5,7")
- Type "none" to cancel
Step 6: After User Approves "all"
✅ Applying Fixes...
Progress: ████████████████████ 100%
Static Pages:
- Updated 8 links on 5 pages
- ✅ Contact page: 3 links fixed
- ✅ Services page: 2 links fixed
- ✅ About page: 1 link fixed
- ✅ Blog page: 2 links fixed
CMS Content:
- Updated 16 links in 12 items
- ✅ Blog Posts: 14 links fixed
- ✅ Team Members: 2 links fixed
---
🎉 Link Fixes Complete!
Summary:
- Links scanned: 247
- Links fixed: 24 ✅
- Manual review needed: 2 ⚠️
- Failed: 0 ❌
Health Score: 76 → 95 (+19) ✨
---
⚠️ Manual Review Items:
[1] About Us page - broken partner link
Current: https://partner-site.com/old-page
Action: Update or remove manually
[2] Blog post "Product Launch" - broken press release
Current: https://press-release.com/announcement
Action: Update or remove manually
---
💡 Next Steps:
1. Fix the 2 manual review items
2. Re-run link checker in 1 month
3. Set up monitoring for critical external links
4. Consider 301 redirects for any URL changes
Would you like to export this report? (yes/no)
Example 2: CMS-Only Link Check
User prompt:
Check all links in my blog posts
Step 1: Collection Selection
🔍 Link Checker: CMS Collections
Found 3 collections:
1. Blog Posts (47 items)
2. Team Members (8 items)
3. Categories (6 items)
You requested blog posts. Checking "Blog Posts" collection...
Step 2: Link Extraction
🔄 Extracting Links from Blog Posts...
Progress: ████████████████████ 100% (47/47 items)
Found 142 links in Blog Posts:
├── Link fields: 23 links
├── Rich Text content: 119 links
└── Total unique URLs: 87 (55 appear multiple times)
Validating links...
Progress: ████████████████████ 100% (87/87 unique URLs checked)
Results:
✅ Working: 79 links (91%)
❌ Broken: 3 links (3%)
⚠️ Insecure: 5 links (6%)
🔄 Redirects: 0 links
Step 3: Issue Report
📊 Blog Posts Link Health: 91/100 ✅
## Issues Found:
### 🔴 Broken Links (3):
[1] Post: "Getting Started with Webflow"
Field: content (Rich Text)
Link: https://old-docs.example.com/guide
Status: 404 Not Found
Appears in: 3 posts
[2] Post: "Best Practices 2024"
Field: external-link (Link)
Link: https://expired-resource.com
Status: 410 Gone
[3] Post: "Tutorial Series Part 3"
Field: content (Rich Text)
Link: https://video-host.com/deleted-video
Status: 404 Not Found
### ⚠️ Insecure Links (5):
[4] Post: "Case Study: Company A"
Field: content (Rich Text)
Link: http://company-a-site.com
Fix: https://company-a-site.com
✅ HTTPS available and working
[5-8] 4 more insecure links...
---
🔧 Proposed Fixes:
[1] ⚠️ Remove broken link (manual review)
Posts affected: 3 (Getting Started, Tutorial 1, Tutorial 2)
Link: https://old-docs.example.com/guide
Suggestion: Update to new docs URL if available
[2] ⚠️ Remove broken link (manual review)
Post: "Best Practices 2024"
Link: https://expired-resource.com
Suggestion: Remove or replace with alternative
[3] ⚠️ Remove broken link (manual review)
Post: "Tutorial Series Part 3"
Link: https://video-host.com/deleted-video
Suggestion: Update with new video URL
[4] ✓ Upgrade to HTTPS
Post: "Case Study: Company A"
Current: http://company-a-site.com
New: https://company-a-site.com
✅ HTTPS verified working
[5-8] ... 4 more HTTPS upgrades
---
Which fixes would you like to apply?
- Type "4-8" to apply only HTTPS upgrades
- Type "all" for all automatic fixes
- Type "none" to cancel
Example 3: Static Pages Only (Quick Check)
User prompt:
Quick check on my static pages for broken links
Response:
🔍 Quick Link Check: Static Pages
Scanning 15 static pages...
Progress: ████████████████████ 100%
Found 89 links across 15 pages
Validation Results:
✅ All links working! (89/89)
Health Score: 100/100 ✨
Your static pages have no broken or insecure links.
💡 Tip: Run a full audit including CMS content for comprehensive coverage.
Example 4: Fixing Specific Issues
User prompt:
I have some broken links on my About page. Can you fix them?
Response:
🔍 Checking Links on "About" Page...
Found 12 links on About page
Validation Results:
✅ Working: 9 links
❌ Broken: 2 links
⚠️ Insecure: 1 link
---
Issues Found:
[1] ❌ Broken: Partner site link
Element: Button "Visit Partner"
Link: https://partner-old-site.com
Status: 404 Not Found
Fix: Manual review needed
[2] ❌ Broken: Team member profile
Element: Text link "Meet Sarah"
Link: /team/sarah-old-profile
Status: 404 Not Found
Fix: Update to /team/sarah-johnson?
[3] ⚠️ Insecure: Social media link
Element: Link "Follow us"
Link: http://social.com/company
Fix: https://social.com/company
✅ HTTPS verified
---
Which fixes would you like to apply?
- Type "3" to only fix the insecure link
- Type "2,3" to fix items 2 and 3
- Type "all" for automatic fixes
- Type "none" to cancel
Note: Item [1] requires manual correction with correct URL
Guidelines
Phase 1: Discovery Best Practices
Site Selection:
- Use
data_sites_toolwith actionlist_sitesto get available sites - Never assume site ID
- Confirm site name with user
Scope Definition:
- Ask if checking static pages, CMS, or both
- Estimate time based on scope:
- Static pages only: 1-3 minutes
- CMS only: 2-5 minutes (depends on item count)
- Full site: 5-10 minutes
Collection Selection:
- List all collections with item counts
- If user specifies collection, focus on that
- If "all CMS", check all collections
Phase 2: Link Extraction Best Practices
Static Page Link Extraction:
- Use
data_pages_toolwith actionget_page_contentto get page nodes - Look for these node types:
- Link (a tag)
- Button (with link)
- TextLink
- LinkBlock
- Extract href/url property
- Capture link text for reporting
- Track nodeId for fixing later
CMS Link Extraction:
- Use
data_cms_toolwith actionget_collection_detailsto identify Link and Rich Text fields - Use
data_cms_toolwith actionlist_collection_itemsto get all items - For Link fields: Extract URL directly
- For Rich Text fields: Parse HTML to extract tags
- Track: collectionId, itemId, fieldName for fixing
Link Validation:
- Test each unique URL (avoid duplicate tests)
- Use HEAD request first (faster than GET)
- Fallback to GET if HEAD fails
- Handle timeouts (10 second max)
- For HTTP links: Test HTTPS equivalent
- Record status code and final URL (after redirects)
Categorization Rules:
✅ Working (2xx):
- 200 OK
- 201 Created
- 204 No Content
❌ Broken (4xx/5xx):
- 400 Bad Request
- 401 Unauthorized
- 403 Forbidden
- 404 Not Found
- 410 Gone
- 500 Internal Server Error
- 502 Bad Gateway
- 503 Service Unavailable
⚠️ Insecure (HTTP):
- URL starts with http://
- HTTPS equivalent exists and returns 2xx
- Mark as "upgrade to HTTPS"
🔄 Redirects (3xx):
- 301 Moved Permanently
- 302 Found
- 307 Temporary Redirect
- 308 Permanent Redirect
⚪ Manual Review:
- Timeout errors
- DNS resolution failures
- Connection refused
- SSL certificate errors
Phase 3: Analysis Best Practices
Health Score Calculation:
Formula:
1. Base score = 100
2. Working links: No change
3. Broken links: -5 points each
4. Insecure links: -2 points each
5. Redirects: -1 point each
6. Minimum score: 0
7. Maximum score: 100
Example:
- Total links: 200
- Working: 180 (no penalty)
- Broken: 5 (−25 points)
- Insecure: 10 (−20 points)
- Redirects: 5 (−5 points)
- Score: 100 − 25 − 20 − 5 = 50/100
Issue Prioritization:
🔴 Critical (fix immediately):
- Broken links on homepage
- Broken links on high-traffic pages
- Broken links in navigation
- 404 errors on important external references
⚠️ Warning (fix soon):
- Insecure HTTP links (security risk)
- Broken links on blog posts
- Broken links in footer
- 410 Gone errors
💡 Suggestion (optimize):
- 301 redirects (update to final destination)
- 302 redirects (may change, monitor)
- External links with slow response times
Statistics to Report:
Essential:
- Total links scanned
- Working links count & percentage
- Broken links count & percentage
- Insecure links count & percentage
- Redirect links count & percentage
Detailed:
- Links by location (static vs CMS)
- Links by type (internal vs external)
- Most common issues
- Pages/items with most issues
- External domains with most broken links
Phase 4: Suggestion Generation Best Practices
Automatic Fix Criteria:
Can auto-fix:
✅ HTTP → HTTPS (if HTTPS verified working)
✅ Redirects → Final destination (if final URL verified)
✅ Relative URLs → Absolute URLs (for external sites)
Needs manual review:
⚠️ Broken links (404, 410, 5xx) - requires correct URL
⚠️ HTTP with no HTTPS equivalent
⚠️ Timeouts or connection errors
⚠️ SSL certificate errors
⚠️ Authentication required (401, 403)
Preview Format:
[X] ✓ Auto-fix available
Location: [Page name or CMS item]
Element: [Element type + text]
Current: [Current URL]
New: [Proposed URL]
✅ Verification: [Status]
[Y] ⚠️ Manual review needed
Location: [Page name or CMS item]
Element: [Element type + text]
Current: [Current URL]
Issue: [Error description]
Suggestion: [What to do]
Granular Approval:
- Number each fix starting from 1
- Show all automatic fixes first
- Show manual review items separately
- Allow user to select specific fixes
- Options: "all", "none", or specific numbers
- Example: "1,3,5-10" applies fixes 1, 3, and 5 through 10
Phase 5: Execution Best Practices
Static Page Updates:
Requirements:
- Use data_pages_tool with action update_static_content
- Update nodes array with new URLs
- Process in batches of 20 links per page
- Verify updates after each batch
Error Handling:
- If Designer not connected: Report and skip static pages
- If update fails: Mark link and continue with others
- Report partial successes separately
CMS Updates:
For Link Fields:
- Direct update: fieldData[fieldName] = "new-url"
- Use data_cms_tool with action update_collection_items
- Option: update live or draft
For Rich Text Fields:
- Parse HTML content
- Find and replace <a> tags
- Preserve other HTML formatting
- Update fieldData[fieldName] with new HTML
Batch Processing:
- Process 50 items per batch
- Show progress for large collections
- Handle API rate limits gracefully
Publishing:
Ask user:
"Would you like to publish the changes immediately?"
- Yes: Use data_cms_tool with action publish_collection_items
- No: Leave as drafts
For static pages:
- Changes are immediate (Designer updates live)
- Warn user that static page changes are live
Phase 6: Verification Best Practices
Re-validation:
- Re-check all fixed links
- Confirm status changed (404 → 200, HTTP → HTTPS)
- Report any fixes that didn't work
- Calculate new health score
Failure Reporting:
If any fixes failed:
❌ Fixes that failed (X):
[1] Failed to update
Location: Contact page
Reason: Page content changed since last read (conflict)
Action: Re-fetch the page and retry
[2] URL still broken
Location: Blog post "Guide"
Reason: HTTPS version returned 404
Action: Manual correction needed
Success Reporting:
✅ Summary:
Before:
- Health Score: 76/100
- Broken links: 8
- Insecure links: 18
- Redirects: 6
After:
- Health Score: 95/100 (+19)
- Broken links: 2 (6 fixed, 2 need manual review)
- Insecure links: 0 (18 fixed)
- Redirects: 0 (6 fixed)
Changes:
- Static pages: 8 links updated on 5 pages
- CMS content: 16 links updated in 12 items
- Total fixes: 24 ✅
- Manual review: 2 ⚠️
Recommendations:
Always provide:
1. Schedule for next check (monthly/quarterly)
2. Monitoring suggestions for critical links
3. Best practices for avoiding broken links
4. URL redirect strategies if applicable
Example:
💡 Recommendations:
1. **Schedule regular checks**
- Run link checker monthly for active sites
- Run quarterly for static sites
- Set calendar reminder
2. **Monitor critical external links**
- Key partners: company-a.com, partner-site.com
- Documentation: docs.example.com
- Social media profiles
3. **Set up URL redirects**
- If changing URLs, create 301 redirects
- Test redirects before going live
- Keep redirect map updated
4. **Best practices**
- Test external links before adding
- Use relative URLs for internal links
- Avoid deep linking to external pages
- Verify links after major redesigns
Phase 7: Export Options
Report Formats:
Offer to export findings:
1. **Markdown** - Human-readable report
- Include all statistics
- List all issues found
- Show fixes applied
- Add recommendations
- Great for documentation
2. **CSV** - Spreadsheet format
- Columns: Location, Element, URL, Status, Issue, Fix Applied
- Easy to filter and analyze
- Good for sharing with team
3. **JSON** - Machine-readable data
- Complete raw data
- Useful for integrations
- Archive for historical tracking
Export Example (Markdown):
# Link Audit Report: Company Website
Date: January 10, 2026
## Summary
- Total links scanned: 247
- Health score: 95/100
- Links fixed: 24
- Manual review needed: 2
## Issues Found
### Broken Links (8)
1. About Us > Button "Visit Partner"
- URL: https://partner-old-site.com
- Status: 404 Not Found
- Fix: Manual review needed
...
## Recommendations
1. Schedule monthly link checks
2. Monitor key external links
3. Set up 301 redirects for URL changes
Phase 8: Performance Optimization
Batch Processing:
For large sites:
- Process pages in batches of 10
- Process CMS items in batches of 50
- Show progress: "Processing batch 1 of 5..."
- Timeout protection: Skip after 30s per batch
Caching Validation Results:
- Cache validation results by unique URL
- If same URL appears 10 times, validate once
- Report: "Checking 87 unique URLs (out of 247 total links)"
- Reduces validation time significantly
Parallel vs Sequential:
Parallel (faster):
- Link validation (test multiple URLs simultaneously)
- Page content extraction (fetch multiple pages)
Sequential (required):
- Link updates (one at a time to avoid conflicts)
- Publishing (one batch at a time)
Phase 9: Error Handling
Common Errors:
1. Designer Not Connected:
❌ Error: Cannot update static pages
Reason: Designer MCP app not connected
Solution:
1. Open Webflow Designer
2. Open the target site
3. Connect Designer MCP app
4. Retry static page fixes
Note: CMS fixes can proceed without Designer
2. Rate Limits:
⚠️ Warning: Rate limit reached
Pausing for 60 seconds...
Progress will resume automatically.
Current: 50/200 links validated
3. Timeout Errors:
⚠️ Link validation timeout
Link: https://very-slow-site.com
Timeout: 10 seconds exceeded
Marked for manual review.
Continuing with remaining links...
4. SSL Certificate Errors:
⚠️ SSL Certificate Error
Link: https://expired-cert-site.com
Issue: Certificate expired
Cannot verify HTTPS. Marked for manual review.
Phase 10: Edge Cases
Case 1: No Issues Found
🎉 Excellent! No Issues Found
All 247 links are working correctly!
Health Score: 100/100 ✨
Your site has:
✅ No broken links
✅ No insecure HTTP links
✅ No unnecessary redirects
💡 Recommendation:
Run this check monthly to maintain link health.
Case 2: All Links Broken
❌ Critical: Multiple Broken Links
Found 89 broken links across all pages.
This suggests a possible site-wide issue:
- Domain migration not configured?
- External service outage?
- Relative URL path issues?
🔍 Recommended Action:
1. Check if external services are down
2. Verify domain and SSL configuration
3. Test a few links manually
4. Contact Webflow support if needed
Shall I still proceed with individual link fixes? (yes/no)
Case 3: Mixed HTTP/HTTPS Site
⚠️ Mixed Content Warning
Your site uses HTTPS but has 18 HTTP links.
This creates:
- Security warnings in browsers
- SEO penalties
- Trust issues for visitors
🔧 Recommendation:
Upgrade all HTTP links to HTTPS (all 18 can be auto-fixed)
Proceed with upgrade? (yes/no)
Case 4: Redirect Chains
⚠️ Redirect Chain Detected
Link: https://example.com/old
→ 301 to: https://example.com/temp
→ 301 to: https://example.com/final
Recommendation: Update directly to final URL
- Improves page load speed
- Reduces redirect overhead
- Better for SEO
Fix: Update to https://example.com/final
Apply fix? (yes/no)
Production Checklist
Before considering link checker implementation complete:
✅ Discovery
- Sites listed with all details
- Scope confirmed (static/CMS/both)
- All pages retrieved
- All collections identified
- User understands time estimate
✅ Link Extraction
- Static page links extracted correctly
- CMS link fields identified
- Rich Text links parsed correctly
- All link elements captured (nodeId, URL, text)
- Duplicate URLs consolidated for validation
✅ Validation
- Each unique URL validated
- Status codes captured correctly
- HTTP/HTTPS checking works
- Redirects detected and final URLs captured
- Timeout handling implemented
- Error categorization accurate
✅ Analysis
- Health score calculated correctly
- Issues prioritized (Critical/Warning/Suggestion)
- Statistics complete and accurate
- Internal vs external links separated
- Location tracking (page/CMS) accurate
✅ Suggestion Generation
- Automatic fixes identified correctly
- Manual review items flagged
- HTTPS upgrades verified before suggesting
- Redirect final destinations verified
- Preview format clear and detailed
- Validation status shown for each fix
✅ Approval System
- Granular approval implemented
- User can select specific fixes
- "all"/"none"/numbers format works
- Manual review items separated
- Clear instructions provided
✅ Execution
- Static page updates work (Designer connected)
- CMS Link field updates work
- CMS Rich Text link updates work
- Batch processing implemented
- Progress indicators shown
- Error handling graceful
✅ Verification
- Fixed links re-validated
- New health score calculated
- Failures reported clearly
- Partial successes vs full failures separated
- Before/after comparison shown
✅ Reporting
- Final summary complete
- Statistics accurate
- Recommendations provided
- Export options offered
- Next steps clear
✅ Error Handling
- Designer disconnected handled
- Timeout errors handled
- Rate limits handled
- SSL errors handled
- Partial failures reported separately
✅ Performance
- Batch processing for scale
- URL deduplication for validation
- Progress indicators for long operations
- Timeout protection implemented
- Efficient API usage
✅ User Experience
- Clear feedback at each step
- Progress indicators shown
- Warnings shown before changes
- Success confirmation clear
- Recommendations actionable
Local Dev Setup
Set up a new Webflow Code Components project from scratch.
When to Use This Skill
Use when:
- Starting a brand new code components project
- User asks to set up, initialize, or create a new project
- Adding code components to an existing React project
- Setting up the development environment for the first time
Do NOT use when:
- Project already exists and is configured (just answer questions directly)
- Creating individual components (use component-scaffold instead)
- Deploying components (use deploy-guide instead)
Instructions
Phase 1: Assess Current State
-
Check if project exists:
- Is there an existing package.json?
- Is there an existing webflow.json?
- What's the current project structure?
-
Determine setup type:
- New project from scratch
- Add to existing React project
- Add to existing Next.js/Vite project
Phase 2: Project Initialization
-
Create project structure (if new):
- Initialize npm project
- Set up TypeScript
- Create folder structure
-
Install dependencies:
- Core: React, TypeScript
- Webflow: CLI, data-types, react utils
- Optional: Styling libraries
Phase 3: Configuration
-
Create webflow.json:
- Set library name
- Configure component glob pattern
- Set up globals if needed
-
Configure TypeScript:
- Set up tsconfig.json
- Enable JSX support
Phase 4: Create Starter Files
-
Create example component:
- Simple Button component
- Definition file
- Basic styling
-
Create globals file (optional):
- For shared styles
- For decorators
Phase 5: Verify Setup
-
Verify bundle compiles:
- Run
npx webflow library bundle --public-path http://localhost:4000/to catch build errors locally - This verifies your components, imports, and configuration are correct
- Full testing in the Webflow Designer requires deploying with
npx webflow library share
- Run
-
Provide next steps:
- How to create more components
- How to deploy
- Development workflow
Examples
For detailed step-by-step examples, see references/EXAMPLES.md.
Available examples:
- New Project from Scratch - Complete setup with React, TypeScript, and CSS Modules
- Add to Existing React Project - Integrate code components into an existing codebase
- With Tailwind CSS - Setup with Tailwind CSS support
Quick Start (New Project):
# 1. Create project
mkdir my-webflow-components && cd my-webflow-components
npm init -y
# 2. Install dependencies
npm install react react-dom
npm install -D typescript @types/react @types/react-dom
npm install -D @webflow/webflow-cli @webflow/data-types @webflow/react
# 3. Create webflow.json
echo '{"library":{"name":"My Library","components":["./src/**/*.webflow.tsx"]}}' > webflow.json
# 4. Create component directory
mkdir -p src/components/Button
Then create your component files (.tsx, .webflow.tsx, .module.css). See Example 1 in references/EXAMPLES.md for complete file contents including component, definition, and CSS files.
Deploy with:
npx webflow library share
Validation
After setup, verify the project is correctly configured:
| Check | How to Verify |
|---|---|
webflow.json exists in project root | cat webflow.json |
| Dependencies installed | npm list @webflow/webflow-cli |
| Bundle compiles without errors | npx webflow library bundle --public-path http://localhost:4000/ |
| At least one component found | Check bundle output for "Found N component(s)" |
Guidelines
Minimum Requirements
Every code components project needs:
- package.json with dependencies
- webflow.json with library config
- tsconfig.json (for TypeScript)
- At least one
.webflow.tsxfile
Recommended Structure
project/
├── src/
│ ├── components/
│ │ └── [ComponentName]/
│ │ ├── [ComponentName].tsx
│ │ ├── [ComponentName].webflow.tsx
│ │ └── [ComponentName].module.css
│ ├── hooks/ # Custom hooks
│ ├── utils/ # Utilities
│ ├── declarations.d.ts # CSS module types
│ ├── globals.ts # Decorators/global imports
│ └── globals.css # Global styles
├── package.json
├── tsconfig.json
├── webflow.json
└── .gitignore
Development Workflow
- Create component: Use component-scaffold skill
- Develop locally: Run React project to iterate (e.g.,
npm run dev) - Validate: Use pre-deploy-check skill
- Deploy: Use deploy-guide skill or run
npx webflow library share - Test in Webflow: Add component to page in Designer
Build Validate
Validate code components before deployment to catch issues early.
When to Use This Skill
Use when:
- User is about to deploy and wants to check for issues first
- Proactively before running
webflow library share - User asks to validate, check, or verify their components
- After making significant changes to components
Do NOT use when:
- Deployment already failed (use troubleshoot-deploy instead)
- Just building for local development
- Auditing code quality (use component-audit instead)
Instructions
Phase 1: Project Structure Check
-
Verify webflow.json exists:
- Check for required fields (
library.name,library.components) - Validate glob pattern matches component files — the recommended pattern is
"./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"covering all supported extensions - Check
globalspath if specified — file must exist and be importable - Check
bundleConfigpath if specified — file must exist
- Check for required fields (
-
Check dependencies:
- Verify
@webflow/webflow-cliinstalled - Verify
@webflow/data-typesinstalled - Verify
@webflow/reactinstalled - Check for version compatibility (check installed versions, don't assume specific versions)
- Verify
-
Verify component files:
- Find all
.webflow.tsx/.webflow.tsfiles matching the glob pattern - Ensure matching React components exist
- Check for orphaned definition files
- Find all
-
Validate imports in
.webflow.tsxfiles:- Must import
declareComponentfrom@webflow/react - Must import
propsfrom@webflow/data-types(if props are defined) - Must import the actual React component being declared
- Must import
Phase 2: Component Analysis
-
For each component, check:
declareComponentis called with the component and a config objectnameis provided in the config- All props have
nameproperties and appropriatedefaultValuewhere applicable - Prop types are valid — the 11 supported types are:
- Text (alias: String) — single line text input
- RichText — multi-line text with formatting
- TextNode — single/multi-line text editable on canvas
- Link — URL input (returns
{ href, target, preload }object) - Image — image upload and selection
- Number — numeric input
- Boolean — true/false toggle
- Variant — dropdown with predefined options (requires
optionsarray) - Visibility — show/hide controls
- Slot — content areas for child components
- ID — HTML element ID
-
Validate component options:
- If
optionsobject is present, validate:applyTagSelectorsis a boolean (default:false) — enables site tag selectors in Shadow DOMssris a boolean (default:true) — controls server-side rendering
- If
-
Check for SSR issues:
- Scan for browser-only API usage outside of
useEffector guarded blocks:window,document,localStorage,sessionStorage,navigator
- Flag dynamic/personalized content patterns (user-specific dashboards, authenticated views)
- Flag heavy/interactive UI that doesn't benefit from SSR (charts, 3D scenes, maps, animation-heavy elements)
- Flag non-deterministic output (random numbers, time-based values that differ server vs client)
- Suggest
ssr: falsein options if component is purely interactive or browser-dependent
- Scan for browser-only API usage outside of
-
Check styling:
- Verify styles are imported in
.webflow.tsxor via globals file - Check for site class usage — site classes do NOT work in Shadow DOM
- Site variables DO work:
var(--variable-name, fallback) - Inherited CSS properties DO work:
font-family: inherit - Tag selectors work IF
applyTagSelectors: trueis set in component options - Validate CSS-in-JS setup if used (see CSS-in-JS detection below)
- Verify styles are imported in
-
Check for Shadow DOM + React Context issues:
- If a component uses slots (
props.Slot) AND imports/usesuseContextor a Context Provider:- Warn that parent and child components in slots cannot share React Context — each child renders in its own Shadow DOM with a separate React root
- Suggest alternatives: Nano Stores, custom events, URL parameters, or browser storage
- If a component uses slots (
Phase 3: Build Test
-
Run TypeScript/build check:
- Check for TypeScript compilation errors
- Verify all imports resolve correctly
- Identify any build-time issues
-
Check bundle size:
- If a build output exists, verify total bundle size is under 50MB (maximum bundle limit)
- If over limit, flag as error and suggest optimization
-
Run local bundle test (optional, suggest to user):
- Suggest running
npx webflow library bundle --public-path http://localhost:4000/to test bundling before sharing - If bundling issues occur, suggest
--debug-bundlerflag to inspect the final webpack config
- Suggest running
Phase 4: Detect Framework-Specific Setup
-
CSS-in-JS library detection:
- If project uses styled-components: verify
@webflow/styled-components-utilsis installed andstyledComponentsShadowDomDecoratoris exported from globals decorators array - If project uses Emotion or Material UI (
@emotion/styled,@emotion/react,@mui/material): verify@webflow/emotion-utilsis installed andemotionShadowDomDecoratoris exported from globals decorators array
- If project uses styled-components: verify
-
Tailwind CSS detection:
- If project uses Tailwind CSS (
tailwindcssin dependencies):- Verify
@tailwindcss/postcssis installed - Verify
postcss.config.mjsexists with@tailwindcss/postcssplugin - Verify Tailwind CSS is imported in globals file (e.g.,
@import "tailwindcss"in globals.css)
- Verify
- If project uses Tailwind CSS (
-
Sass/Less preprocessor detection:
- If project uses Sass (
.scssfiles orsassin dependencies): verifysassandsass-loaderare installed, and a webpack config adds the.scssrule - If project uses Less (
.lessfiles orlessin dependencies): verifylessandless-loaderare installed, and a webpack config adds the.lessrule - For either: verify
bundleConfigis set inwebflow.jsonpointing to the webpack config
- If project uses Sass (
-
Webpack custom config validation (if
bundleConfigis specified):- Verify the file exists at the specified path
- Verify it uses CommonJS exports (
module.exports) - Warn if it attempts to override blocked properties:
entry,output,target(these are silently filtered out) - Verify
module.rulesuses function syntax(currentRules) => { ... }, not an array
Phase 5: Report Results
- Generate validation report:
- List all checks performed
- Show passed/failed/warning status
- Provide fix suggestions for failures
- Indicate deployment readiness
Validation Checks
Required Checks
| Check | Severity | Description |
|---|---|---|
| webflow.json exists | Error | Required for CLI |
| Dependencies installed | Error | @webflow/webflow-cli, @webflow/data-types, @webflow/react |
| Component files exist | Error | React + definition files present |
| declareComponent called | Error | Required in .webflow.tsx with correct imports |
| Valid prop types | Error | Only the 11 supported types (Text/String, RichText, TextNode, Link, Image, Number, Boolean, Variant, Visibility, Slot, ID) |
| Build succeeds | Error | No compilation errors |
| Bundle size < 50MB | Error | Maximum bundle limit enforced by Webflow |
Warning Checks
| Check | Severity | Description |
|---|---|---|
| Props have defaults | Warning | Better designer experience |
| SSR compatibility | Warning | Browser APIs, dynamic content, heavy UI, non-deterministic output |
| Styles imported | Warning | Styles may not appear in Shadow DOM |
| Site class usage | Warning | Site classes don't work in Shadow DOM — use component-specific classes |
| Shadow DOM + Context | Warning | Slots prevent React Context sharing between parent/child |
| CSS-in-JS decorator | Warning | styled-components/Emotion need Shadow DOM decorators |
| Tailwind setup | Warning | Missing postcss config or globals import |
| Sass/Less setup | Warning | Missing loaders or webpack config |
| Webpack blocked props | Warning | entry, output, target overrides are silently ignored |
| Webpack rules format | Warning | Must use function syntax, not array |
| Component options | Warning | applyTagSelectors and ssr must be booleans |
| Glob pattern coverage | Warning | Pattern should cover all supported extensions (.js, .jsx, .mjs, .ts, .tsx) |
| bundleConfig file | Warning | File must exist if specified in webflow.json |
Info Checks
| Check | Severity | Description |
|---|---|---|
| Component count | Info | Number of components |
| Prop count | Info | Props per component |
| Bundle size | Info | Current bundle size vs 50MB limit |
| Frameworks detected | Info | CSS-in-JS, Tailwind, Sass/Less usage |
Examples
User prompt:
Check if my components are ready to deploy
Response:
🔍 Build Validation: My Component Library
Running pre-deployment checks...
---
## Project Structure
✅ webflow.json found
✅ library.name: "My Component Library"
✅ library.components: "./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"
✅ globals: "./src/globals.ts"
✅ bundleConfig: not specified (using defaults)
---
## Dependencies
✅ @webflow/webflow-cli: installed
✅ @webflow/data-types: installed
✅ @webflow/react: installed
✅ react: installed
✅ typescript: installed
---
## Frameworks Detected
✅ Tailwind CSS detected
✅ @tailwindcss/postcss installed
✅ postcss.config.mjs found
✅ globals.css imports Tailwind
---
## Components Found (4)
### 1. Button ✅
- File: src/components/Button/Button.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Button component
- Props: label (Text), variant (Variant), disabled (Boolean)
- All props have defaults ✅
- SSR compatible ✅
- Options: applyTagSelectors: true ✅
- Styles imported ✅
### 2. Card ✅
- File: src/components/Card/Card.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Card component
- Props: title (Text), image (Image), content (RichText), link (Link)
- All props have defaults ✅
- SSR compatible ✅
- Styles imported ✅
### 3. Modal ⚠️
- File: src/components/Modal/Modal.webflow.tsx
- Imports: ✅ declareComponent, ✅ props, ✅ Modal component
- Props: title (Text), isOpen (Boolean), content (Slot)
- All props have defaults ✅
- ⚠️ SSR Issue: Uses `document.body` in render
→ Suggestion: Add `ssr: false` to options or wrap in useEffect
- Styles imported ✅
### 4. CartIcon ⚠️
- File: src/components/CartIcon/CartIcon.webflow.tsx
- Imports: ✅ declareComponent, ✅ CartIcon component
- Props: none
- ⚠️ Missing props - component has no editable properties
→ Suggestion: Consider adding props for designer customization
- ⚠️ Uses localStorage without SSR guard
→ Suggestion: Wrap in useEffect or useState initializer
- Styles imported ✅
---
## Build Test
✅ Build completed successfully
✅ No TypeScript errors
✅ No webpack errors
✅ Bundle size: 2.3MB / 50MB limit
---
## Summary
| Category | Status |
|----------|--------|
| Project Structure | ✅ Pass |
| Dependencies | ✅ Pass |
| Frameworks | ✅ Pass |
| Components | ⚠️ 2 warnings |
| Build | ✅ Pass |
---
## Ready to Deploy: ⚠️ WITH WARNINGS
You can deploy, but consider fixing these issues:
1. **Modal SSR Issue**
Add to Modal.webflow.tsx:
```typescript
options: {
ssr: false
}
- CartIcon localStorage Usage
Update CartIcon.tsx:
const [count, setCount] = useState(() => { if (typeof window === "undefined") return 0; return parseInt(localStorage.getItem("cartCount") || "0"); });
💡 To deploy: npx webflow library share
💡 To test locally first: npx webflow library bundle --public-path http://localhost:4000/
---
**Example: Build Failure**
🔍 Build Validation: My Component Library
Running pre-deployment checks...
Project Structure
✅ webflow.json found ⚠️ library.components uses narrow glob: "./src//*.webflow.tsx" → Recommendation: Use "./src//*.webflow.@(js|jsx|mjs|ts|tsx)" to cover all supported extensions
Dependencies
❌ Missing: @webflow/react Fix: npm install --save-dev @webflow/react
Build Test
❌ Build Failed
Error in src/components/Button/Button.webflow.tsx:
Module not found: Error: Can't resolve '@webflow/react'
Summary
| Category | Status |
|---|---|
| Dependencies | ❌ 1 error |
| Build | ❌ Failed |
Ready to Deploy: ❌ NO
Fix the following before deployment:
-
Install missing dependency
npm install --save-dev @webflow/react -
Re-run validation After installing, run this check again.
---
**Example: CSS-in-JS Missing Decorator**
🔍 Build Validation: My Component Library
Frameworks Detected
⚠️ styled-components detected but Shadow DOM decorator not configured
→ Install: npm install @webflow/styled-components-utils
→ Add to globals.ts:
typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator];
→ Reference globals in webflow.json:
json { "library": { "globals": "./src/globals.ts" } }
Without this, styled-components styles will be injected into document.head instead of the Shadow DOM, and your components will appear unstyled.
---
**Example: Webpack Config Issues**
🔍 Build Validation: My Component Library
Webpack Configuration
⚠️ webpack.webflow.js: module.rules uses array syntax
→ Must use function syntax: rules: (currentRules) => { return [...]; }
→ Array syntax will not work — the function receives current rules to extend
⚠️ webpack.webflow.js: overrides output property
→ The output property is blocked and will be silently ignored
→ Blocked properties: entry, output, target
💡 Use --debug-bundler flag to inspect the final merged webpack config:
npx webflow library bundle --debug-bundler
---
**Example: Shadow DOM Context Warning**
Components Found (2)
1. ThemeProvider ⚠️
-
File: src/components/ThemeProvider/ThemeProvider.webflow.tsx
-
Props: theme (Variant), children (Slot)
-
⚠️ Shadow DOM + React Context Issue: Component uses Slot prop AND React Context (ThemeContext). Children placed in slots render in separate Shadow DOM containers with their own React roots — they cannot access this Context.
Alternatives for cross-component state:
- Nano Stores (lightweight reactive state)
- Custom events (window.dispatchEvent/addEventListener)
- URL parameters (for shareable state)
- Browser storage (localStorage/sessionStorage)
---
## Guidelines
### Validation Order
Run checks in this order for efficiency:
1. Project structure (fast, catches obvious issues)
2. Dependencies (medium, required for build)
3. Component analysis (medium, catches code issues)
4. Framework detection (medium, validates CSS-in-JS/Tailwind/Sass setup)
5. Build test (slow, but required)
### SSR Detection Patterns
Look for these patterns that indicate SSR issues:
```typescript
// Direct browser API usage (will break SSR)
window.innerWidth
document.getElementById
localStorage.getItem
navigator.userAgent
sessionStorage.getItem
// Dynamic/personalized content (may cause hydration mismatch)
// User-specific dashboards, authenticated views
// Heavy/interactive UI (SSR adds no value, re-renders anyway)
// Charts, 3D scenes, maps, animation-driven elements
// Non-deterministic output (differs server vs client)
Math.random()
new Date().toLocaleString()
// Safe patterns (in useEffect or state initializer)
useEffect(() => {
// Browser APIs here are fine
}, []);
useState(() => {
if (typeof window === "undefined") return default;
return window.innerWidth;
});
When SSR issues are found, prominently suggest the ssr: false option:
export default declareComponent(MyComponent, {
name: "My Component",
options: {
ssr: false // Disables server-side rendering
},
});
CSS-in-JS / Tailwind / Preprocessor Detection
Check project dependencies and files to detect styling frameworks:
styled-components:
- Detect:
styled-componentsin package.json dependencies - Require:
@webflow/styled-components-utilsinstalled - Require:
styledComponentsShadowDomDecoratorin globals decorators array
Emotion / Material UI:
- Detect:
@emotion/styled,@emotion/react, or@mui/materialin dependencies - Require:
@webflow/emotion-utilsinstalled - Require:
emotionShadowDomDecoratorin globals decorators array
Tailwind CSS:
- Detect:
tailwindcssin dependencies - Require:
@tailwindcss/postcssinstalled - Require:
postcss.config.mjswith@tailwindcss/postcssplugin - Require: Tailwind import in globals CSS (
@import "tailwindcss")
Sass:
- Detect:
.scssfiles in src orsassin dependencies - Require:
sassandsass-loaderinstalled as dev dependencies - Require: webpack config with
.scssrule using function syntax for module.rules - Require:
bundleConfigset in webflow.json
Less:
- Detect:
.lessfiles in src orlessin dependencies - Require:
lessandless-loaderinstalled as dev dependencies - Require: webpack config with
.lessrule using function syntax for module.rules - Require:
bundleConfigset in webflow.json
Webpack Config Validation Rules
When bundleConfig is specified in webflow.json:
- File must exist at the specified path
- Must use CommonJS:
module.exports = { ... } - Blocked properties that are silently ignored:
entry,output,target module.rulesmust be a function, not an array:rules: (currentRules) => { ... }ModuleFederationPluginandMiniCssExtractPluginare auto-deduplicated
Common Build Errors
| Error | Cause | Fix |
|---|---|---|
| "Can't resolve '@webflow/react'" | Missing dependency | npm i -D @webflow/react |
| "Cannot find module './Component'" | Wrong import path | Check relative paths |
| "Type 'X' is not assignable" | TypeScript error | Fix type mismatch |
| "Unexpected token" | Syntax error | Check JSX/TS syntax |
| "Maximum call stack" | Circular import | Break dependency cycle |
| Bundle exceeds 50MB | Too many/large dependencies | Tree-shake, lazy load, replace heavy libs |
| Styles not appearing | Missing Shadow DOM decorator | Add CSS-in-JS decorator or import styles in .webflow.tsx |
Bundle Size Optimization
Quick wins for reducing bundle size:
- Use production build: Ensure minification is enabled
- Tree-shake imports: Import specific exports
- Replace heavy libraries: moment → date-fns, lodash → lodash-es
- Lazy load: Dynamic imports for heavy components
- Check for duplicates: Multiple React versions, etc.
- Monitor size: Bundle must stay under 50MB limit
Review open comment threads on a Webflow site and triage each one.
Input: $ARGUMENTS — a site name (e.g. "Workhaus"), site ID (e.g. 6808fd4eff835ee3af009d6f), or either with the -reply flag (e.g. Workhaus -reply).
Flags:
-reply— in addition to writing the report, post a bot reply to each non-open thread. Without this flag, the skill runs in report-only mode (read-only).
Parse $ARGUMENTS at the start: strip -reply from the input to get the site identifier, and set replyMode = true if -reply was present, false otherwise.
Step 1 — Resolve the site
If the site identifier is empty or blank — cross-site comment survey
- Call
data_sites_tool > list_sitesto get all sites. Page through until all are collected. - For each site, call
data_comments_tool > list_comment_threadswithisResolved: falseandlimit: 100. Page through until all unresolved threads are collected. If the API does not supportisResolvedfiltering, fetch all threads and filter client-side toisResolved === false. Process sites in batches of 20 (batch multiple actions in a single tool call). After each batch completes, log a progress line:Batch {N}/{total} done (sites {start}–{end}): {summary of findings, e.g. "all 0 threads" or "SiteName has X threads, rest 0"}. - For each site, compute:
unresolvedCount= total unresolved threadsnewestDate= the maximumlastUpdatedvalue across all unresolved threads for that site (ISO → human-readable date, e.g. "Apr 3, 2026"). If no threads, show—.oldestDate= the minimumlastUpdatedvalue across all unresolved threads for that site (ISO → human-readable date). If no threads, show—.
- Sort sites by
unresolvedCountdescending. Take the top 10. - Above the table, show a heading line:
### Checked {totalSiteCount} sites — {sitesWithUnresolved} have unresolved comments. - Display a table in this format (link just the site name to
https://webflow.com/design/{siteId}):
| Site | Unresolved Comments | Newest / Oldest |
|------|---------------------|-----------------|
| [Site Name](https://webflow.com/design/{siteId}) ({siteId}) | {N} | {newestDate} / {oldestDate} |
- After the table, tell the user: "Run
/webflow-mcp:review-comments <site name or ID>to review a specific site." - Write the survey output to a file:
- Ensure
comment-reviews/exists (create withmkdir comment-reviewsif not). - Filename:
comment-reviews/triage-report-{YYYY-MM-DD-HH-MM}.mdusing the current local time (zero-padded). - File contents: a bold H1 title
# **Webflow Comment Review**, then a blank line, then an H3 line### Report created on: {human-readable date, time, and timezone, e.g. "April 16, 2026 at 10:39 AM PDT"}, then a blank line, then the H3 heading line (### Checked …) and the full table from steps 5–6 above, in markdown. - Log the path after writing, e.g.
Report written to comment-reviews/triage-report-2026-04-16-14-30.md.
- Ensure
- Stop — do not proceed to Step 2.
If the site identifier looks like a Webflow site ID (24-char hex), use it directly.
Otherwise call data_sites_tool > list_sites and find the site whose displayName matches the identifier (case-insensitive). If no match, tell the user and stop.
Step 2 — Fetch all open threads
Always make a fresh API call here — never reuse thread data from earlier in the conversation. The user may have added or resolved comments since the last run.
Call data_comments_tool > list_comment_threads with isResolved: false and limit: 100. Page through results until all threads are collected.
Log: Site: {displayName} and Found {N} open thread(s).
Step 3 — Build page-level element map
From the already-fetched thread list, build a frequency map of elementId.element → Set<pageId> across all threads. Any elementId.element that appears on 2 or more distinct pages is almost certainly the page root/body element (a real element ID would be page-scoped; only shared structural roots repeat across pages).
No API calls needed — this is a local computation on the thread data.
Step 4 — Triage each thread
For each thread:
4a — Fetch replies
Call data_comments_tool > list_comment_replies for this thread.
4b — Dedup check
Look for replies whose content includes the string — 🤖 Comment Review Agent.
If found, note the most recent one (lastAgentReply). If no human reply exists with a createdOn after lastAgentReply.createdOn, skip this thread (increment skipped count, continue to next thread).
4c — Compute element context
elementId=thread.elementId?.elementisPageLevel=elementIdappears on 2 or more distinctpageIds in the frequency map from Step 3
4d — Classify the thread
Use the following criteria:
noise — No real design or engineering value:
- Test/placeholder text ("hello world", "testing", "asdf", random characters)
- Casual reactions with no ask ("looks nice", "nice!", "hey hey")
- Duplicate sentiments that add nothing
stale — Real concern, but old and likely handled:
- Substantive comments older than 14 days with no replies and no follow-up
- Questions that are probably resolved ("beta for how long?", "is this good contrast?")
- Action items that normal review would have caught
open — Real, actionable concern needing attention:
- Explicit tasks ("Should be sentence case", "fix image", "Look at name wrt L10N")
- Design decisions still required
- Specific and concrete concerns
page-level — Comment is on the page root, not a specific element:
- Use this when
isPageLevelis true - The comment is not anchored to any specific element — it may be intentional or may be an orphan from a deleted element
4e — Compose reply
Always compose the reply text (it appears in the report regardless of mode):
- noise: one sentence confirming it's safe to resolve. E.g.
"Looks like test text — safe to resolve." - stale: state the age in days, suggest resolving, invite reopen. E.g.
"This is 302 days old with no follow-up. Safe to resolve — reply here if it's still relevant." - open: no reply text — surface in report only.
- page-level: one sentence noting it's not attached to a specific element. E.g.
"This comment is on the page root rather than a specific element — it may be an orphan from a deleted element. Safe to resolve if no longer relevant."
Append \n\n— 🤖 Comment Review Agent to every reply text.
4f — Post reply (only if replyMode = true)
If replyMode is true and verdict is not open, call data_comments_tool > create_reply with the composed reply content.
Log each thread as:
{VERDICT_EMOJI} {verdict} "{preview (60 chars)}"
{one-sentence classification reason}
↳ {reply posted | no reply — report only | skipped}
Verdict emojis: noise = 🗑, stale = 🕰, open = 🔴, page-level = 📄
Step 5 — Write the report
After processing all threads:
- Check whether a
comment-reviews/directory exists at the top level of the working directory. If it does not exist, create it withmkdir comment-reviews. - Write a markdown report to
comment-reviews/{slugified-site-name}-comments-triage-report.md(lowercase, hyphens, no special chars).
Report format:
# Comment Review — [{siteName} ({siteId})](https://webflow.com/design/{siteId})
**Run:** {human-readable date and time}
**Mode:** {Report only | Report + replies posted}
**Threads:** {total} total | 🔴 {open} open | 🕰 {stale} stale | 📄 {page-level} page-level | 🗑 {noise} noise | ⏭ {skipped} skipped
---
## 🔴 Needs Attention ({count})
| Comment | Author | Age | Link |
|---------|--------|-----|------|
| "{first 80 chars of content}" | {author.name} | {age in days}d | [Open ↗]({thread.url}) |
## 🕰 Stale — Candidates to Resolve ({count})
| Comment | Author | Age | Suggested Reply | Link |
|---------|--------|-----|-----------------|------|
| "{first 80 chars of content}" | {author.name} | {age in days}d | {composed reply text, without the `— 🤖 Comment Review Agent` suffix} | [Open ↗]({thread.url}) |
## 📄 Page-level — Not Anchored to a Specific Element ({count})
| Comment | Author | Age | Suggested Reply | Link |
|---------|--------|-----|-----------------|------|
...
---
**🗑 Noise:** {count} thread(s) — {if replyMode: "replied to" | if report-only: "suggested replies in report"}. Safe to bulk-resolve.
Use _None._ for any section with no entries.
Log a summary line and confirm the report path.
Safe Publish
Publish a Webflow site with comprehensive preview, validation, and explicit confirmation workflow.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
data_sites_toolwith actionlist_sitesfor listing available sites - Use Webflow MCP's
data_sites_toolwith actionget_sitefor detailed site information - Use Webflow MCP's
data_pages_toolwith actionlist_pagesfor retrieving all pages - Use Webflow MCP's
data_cms_toolwith actionget_collection_listfor listing CMS collections - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsfor checking draft items - Use Webflow MCP's
data_sites_toolwith actionpublish_sitefor publishing the site - Use Webflow MCP's
webflow_guide_toolto get best practices before starting - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Site Selection & Status Check
- Get site: Identify the target site. If user does not provide site ID, ask for it.
- Fetch site details: Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve:- Last published date
- Last updated date
- Custom domains configured
- Locale settings
- Check publish status: Determine if site has unpublished changes:
- Compare
lastUpdatedvslastPublishedtimestamps - If
lastPublishedis null, site has never been published - If
lastUpdated>lastPublished, site has unpublished changes
- Compare
Phase 2: Change Detection & Analysis
- List all pages: Use Webflow MCP's
data_pages_toolwith actionlist_pages - Identify modified pages:
- Compare each page's
lastUpdatedwith site'slastPublished - Flag pages modified after last publish
- Categorize by type (static, CMS template, archived, draft)
- Compare each page's
- List all collections: Use Webflow MCP's
data_cms_toolwith actionget_collection_list - Check for draft items:
- For each collection, use Webflow MCP's
data_cms_toolwith actionlist_collection_items - Count items where
isDraft: true - Count items modified since last publish
- For each collection, use Webflow MCP's
- Detect issues:
- Draft items that won't be published unless explicitly included
- Pages missing SEO metadata
- Broken references (if detectable)
Phase 3: Pre-Publish Validation & Preview
- Run pre-publish checks:
- Verify no broken collection references
- Check for pages with missing required fields
- Warn about draft items that will remain unpublished
- Generate detailed preview:
- Show all pages to be published
- Show all CMS items to be published
- Display warnings for any issues found
- Show which domains will be updated
- Ask for publish scope:
- Webflow subdomain only
- Custom domains only
- Both subdomain and custom domains
Phase 4: Confirmation & Publishing
- Require explicit confirmation:
- User must type "publish" to proceed
- "yes" or "y" should NOT trigger publish
- Show clear warning about what will go live
- Execute publish:
- Use Webflow MCP's
data_sites_toolwith actionpublish_sitewith correct parameters - Handle
customDomainsas empty array if no custom domains - Set
publishToWebflowSubdomainbased on user choice
- Use Webflow MCP's
- Capture publish timestamp:
- Fetch site info again after publish
- Record exact publish time from
lastPublishedfield
Phase 5: Verification & Reporting
- Verify publish success:
- Check that
lastPublishedtimestamp updated - Verify site is accessible at published URL(s)
- Report any verification failures clearly
- Check that
- Generate success report:
- Show publish timestamp
- List what went live (pages, items)
- Provide published URL(s)
- Show verification status
- Handle failures gracefully:
- If publish fails, show clear error message
- Suggest remediation steps
- Do not retry automatically
Examples
User prompt:
Publish my site
Step 1: Site Selection
🚀 Safe Publish - Site Selection
Available Sites:
1. **MCP Demo#1**
- Last published: January 9, 2026 at 20:05:38 UTC
- Last updated: January 9, 2026 at 20:49:37 UTC
- ⚠️ **Has unpublished changes** (updated 44 minutes after last publish)
2. **MCP Demo#2**
- Last updated: January 9, 2026 at 19:32:53 UTC
- Status: Not yet published
Which site would you like to publish? (1-2)
Step 2: Change Detection & Preview
🚀 Publish Preview: MCP Demo#1
**Last published:** January 9, 2026 at 20:05:38 UTC
**Time since last publish:** ~1 hour 5 minutes
---
## Changes to Publish:
### 📄 Pages Modified: 1
└── **Home** (/)
- SEO title updated to "Home Page"
- Last modified: 21:10:52 UTC
### 📝 CMS Items: 2 draft items to publish
**Blog Posts (2 drafts):**
1. **"Why Webflow MCP Will Transform Your Workflow in 2026!"**
- Status: Draft
- Created: 20:24:44 UTC
- Last modified: 21:11:03 UTC
- Featured: Yes
- Slug: webflow-mcp-transform-workflow-2026
2. **"Webflow E-commerce: The Future of Online Shopping in 2026!"**
- Status: Draft
- Created: 20:05:24 UTC
- Last modified: 21:11:11 UTC
- Featured: Yes
- Slug: webflow-ecommerce-2026
---
**Pre-Publish Checks:**
- ✅ No broken references detected
- ✅ All required fields populated
- ⚠️ 2 draft items will become published
**Publish Targets:**
- Webflow subdomain: mcp-demo-1-e88499.webflow.io
- Custom domains: None configured
**⚠️ Type "publish" to make these changes live.**
Step 3: After user types "publish"
🔄 Publishing MCP Demo#1...
Progress: ████████████████████ 100%
✅ Published Successfully!
**Site:** MCP Demo#1
**Published at:** 2026-01-09 21:12:52 UTC (January 9, 2026 at 21:12:52)
---
## What Went Live:
### 📄 Pages (1)
- ✅ Home (/) - SEO title updated
### 📝 Blog Posts (2)
- ✅ "Why Webflow MCP Will Transform Your Workflow in 2026!"
- ✅ "Webflow E-commerce: The Future of Online Shopping in 2026!"
---
## Verification:
- ✅ **Site accessible:** Yes
- ✅ **URL:** https://mcp-demo-1-e88499.webflow.io
- ✅ **Status:** Page loading successfully
- ✅ **Content delivery:** Webflow CDN responding
---
**🎉 Your site is now live with all changes published!**
All unpublished changes have been successfully published to the Webflow subdomain. The 2 draft blog posts are now visible on your site.
Alternative: With Warnings
🚀 Publish Preview: Company Site
**Last published:** January 8, 2026 at 14:30:00 UTC
---
## Changes to Publish:
### 📄 Pages Modified: 3
├── **About** (/about)
│ └── Content updated
├── **Contact** (/contact)
│ └── Form fields changed
└── **Home** (/)
└── Hero section updated
### 📝 CMS Items
**Blog Posts:**
- 5 published items modified
- 2 draft items (will NOT be published automatically)
**Products:**
- 3 new items created
- 1 item updated
---
**Pre-Publish Checks:**
⚠️ **Warnings Found:**
1. **Missing SEO Metadata (2 pages):**
- /about - No meta description
- /contact - No meta title or description
- 💡 Recommendation: Add SEO metadata before publishing
2. **Draft Items (2):**
- "Upcoming Product Launch" (Blog Post)
- "Holiday Sale Announcement" (Blog Post)
- ⚠️ These will remain unpublished
3. **Large Change Set:**
- 3 pages + 9 CMS items will be updated
- Consider reviewing changes carefully
**Publish Targets:**
- Webflow subdomain: company-site.webflow.io
- Custom domains: example.com, www.example.com
---
**Would you like to:**
1. Proceed with publish (type "publish")
2. Cancel and review (type "cancel")
Guidelines
Phase 1: Critical Requirements
Site Status Check:
- Always fetch complete site details using
data_sites_toolwith actionget_site - Compare
lastUpdatedvslastPublishedto detect unpublished changes - If timestamps are identical, inform user "No changes to publish"
- If
lastPublishedis null, warn "First publish - entire site will go live"
Timestamp Handling:
- Store both ISO format and human-readable format
- Calculate time elapsed since last publish
- Show timezone (prefer UTC for clarity)
Phase 2: Change Detection Rules
Page Change Detection:
- Compare page
lastUpdatedwith sitelastPublished - Only flag pages where
lastUpdated > lastPublished - Categorize changes:
- Content changes (hard to detect via API)
- SEO metadata changes (compare if available)
- Structural changes (page created/deleted)
CMS Item Detection:
- Check
isDraftfield for all items - Compare
lastUpdatedwith sitelastPublished - Count items in each state:
- Published + not modified
- Published + modified
- Draft (won't be published)
- Archived (won't appear on site)
Collections to Check:
- Query all collections with
data_cms_toolwith actionget_collection_list - For each collection, list items with
data_cms_toolwith actionlist_collection_items - Batch queries if site has many collections (10+ collections)
Phase 3: Pre-Publish Validation
Required Checks:
-
Broken References:
- Check if referenced items exist
- Warn if reference field points to deleted/archived item
- Note: API may not expose this easily - best effort
-
Missing Required Fields:
- Verify all required CMS fields are populated
- Warn if required fields are empty (shouldn't be possible, but check)
-
SEO Completeness:
- Check pages for missing
seo.titleorseo.description - Warn but don't block publish
- Provide recommendations for improvement
- Check pages for missing
-
Draft Item Warning:
- Clearly list all draft items
- Explain they will remain unpublished
- Offer to cancel if user wants to publish drafts first
Warning Levels:
- 🔴 Critical: Would break site (broken refs, missing required fields)
- ⚠️ Warning: Suboptimal but publishable (missing SEO, drafts)
- 💡 Suggestion: Best practices (add meta descriptions, optimize images)
When to Block Publish:
- Only block if critical errors found
- For warnings and suggestions, allow user to proceed
- Always show warnings prominently
Phase 4: Confirmation & Publishing
Confirmation Requirements:
- User MUST type "publish" (case-insensitive)
- Do NOT accept: "yes", "y", "ok", "go", "confirm"
- Rationale: Prevents accidental publishes from generic confirmations
- If user types anything else, ask again or treat as cancel
Publish API Usage:
// Correct format for data_sites_tool with action publish_site
{
"site_id": "site-id-here",
"publishToWebflowSubdomain": true, // or false
"customDomains": [] // MUST be array, even if empty
}
// If custom domains exist:
{
"site_id": "site-id-here",
"publishToWebflowSubdomain": false,
"customDomains": ["example.com", "www.example.com"]
}
Domain Selection:
- If no custom domains: Publish to subdomain only
- If custom domains exist: Ask user which to publish to
- Subdomain only
- Custom domains only
- Both
- Default to subdomain if user doesn't specify
Error Handling:
- If
customDomainsvalidation error: Ensure it's an array - If
400 Bad Request: Check request format - If
403 Forbidden: Check site publish permissions - If
500 Server Error: Retry once after 5 seconds, then report failure
Phase 5: Verification & Reporting
Post-Publish Verification:
-
Fetch Updated Site Info:
- Call
data_sites_toolwith actionget_siteagain - Verify
lastPublishedtimestamp updated - If timestamp didn't update, publish may have failed
- Call
-
Site Accessibility Check:
- Use WebFetch to check published URL
- Verify site returns 200 OK
- Check that content is served (not error page)
- Measure response time
-
Custom Domain Checks:
- If published to custom domains, verify each domain
- Some domains may take time to propagate (DNS)
- Note: "Domain may take a few minutes to update" if slow
Verification Failure Handling:
- If site not accessible: Report clearly
- Note: Changes ARE published even if verification fails
- Possible causes:
- DNS propagation delay
- CDN cache not yet cleared
- Temporary Webflow infrastructure issue
- Suggest: "Try accessing the site in 2-3 minutes"
Success Report Format:
✅ Published Successfully!
Site: [Site Name]
Published at: [ISO Timestamp] ([Human Readable])
What Went Live:
- X pages modified
- Y CMS items published
- Z draft items promoted to published
Verification:
✅ Site accessible
✅ URL: [primary URL]
✅ Response time: [Xms]
[If custom domains]
Custom Domains:
✅ example.com - accessible
⚠️ www.example.com - propagating (may take 2-3 minutes)
Best Practices
Always:
- ✅ Show comprehensive preview before publishing
- ✅ Require explicit "publish" confirmation
- ✅ Verify site after publish
- ✅ Report exact publish timestamp
- ✅ List all changes going live
- ✅ Warn about draft items
Never:
- ❌ Publish without explicit user confirmation
- ❌ Accept generic confirmations like "yes"
- ❌ Hide warnings from user
- ❌ Retry failed publishes automatically
- ❌ Proceed if critical errors detected
Edge Cases:
No Changes to Publish:
ℹ️ No Changes to Publish
Last published: January 9, 2026 at 20:05:38 UTC
Last updated: January 9, 2026 at 20:05:38 UTC
All changes are already published. Your site is up to date!
First Publish (Never Published Before):
⚠️ First Publish Warning
This site has NEVER been published before.
This will make the ENTIRE site publicly accessible:
- All pages (2 pages)
- All CMS items (47 items across 3 collections)
- All assets
Are you ready to make this site live?
Type "publish" to proceed, or "cancel" to abort.
Publish to Staging Subdomain:
- If site has custom domains but user chooses subdomain only
- Useful for testing before publishing to production domain
- Explain: "Publishing to subdomain only. Custom domains will continue showing old version."
Partial Publish Not Supported:
- Webflow publishes entire site, not individual pages
- Cannot publish specific pages or collections
- If user asks to "publish just the homepage", explain limitation
- Alternative: Use staging subdomain for testing
Performance Optimization
For Large Sites:
- Sites with 100+ pages or 1000+ items may take time to analyze
- Show progress: "Analyzing 150 pages..."
- Batch API calls when possible
- Consider skipping detailed diff for very large change sets
Caching:
- Cache site info during workflow (don't refetch unnecessarily)
- Only refetch after publish to verify
Timeouts:
- Publish API may take 10-30 seconds for large sites
- Don't timeout too quickly
- Show: "Publishing... this may take up to 30 seconds for large sites"
Error Messages
Clear and Actionable:
❌ Bad:
"Publish failed"
✅ Good:
"Publish Failed: Validation Error
The Webflow API returned an error:
- customDomains parameter must be an array
This is likely a configuration issue. Retrying...
Common Errors:
-
Validation Error (customDomains):
- Fix: Ensure
customDomains: []is an array - Don't pass null or omit the field
- Fix: Ensure
-
Site Not Found:
- User may have provided wrong site ID
- List available sites and ask user to select
-
Insufficient Permissions:
- Site may require specific publish permissions
- Check workspace access settings
-
Publish Already in Progress:
- Another publish may be running
- Wait 30 seconds and try again
Site Activity
Query, analyze, and summarize Webflow site activity logs for enterprise sites. Provides natural-language querying of recent changes, filtered summaries by event type or user, and formatted reports for team sharing.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
data_sites_toolwith actionlist_sitesfor listing available sites - Use Webflow MCP's
data_sites_toolwith actionget_sitefor detailed site information - Use Webflow MCP's
data_enterprise_toolwith actionlist_site_activity_logsfor retrieving activity log events - Use Webflow MCP's
webflow_guide_toolto get best practices before starting - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Enterprise Only: Activity logs are only available for sites on Enterprise hosting plans. If the tool returns an error, inform the user that this feature requires an Enterprise plan.
Tool Parameters for list_site_activity_logs:
site_id(required): The site's unique identifierlimit(optional): Maximum records to return (max 100)offset(optional): Pagination offset for fetching beyond the first page
Instructions
Phase 1: Site Selection & Context
-
Identify target site: If the user does not provide a site ID, use
data_sites_toolwith actionlist_sites. Each site in the response hasdisplayName,lastPublished, andlastUpdated.Sort order:
- ⚠️ sites (unpublished changes) before ✅ sites (up to date)
- Within each group, most recently updated first (by
lastUpdateddescending)
Truncation: Show the top 10 sites only. If there are more than 10 total, append a line
…and N more sites. Reply "show all" to see the rest.below the list. When the user replies "show all" (or similar), re-present the full list in the same format.Present the list in this exact format:
📋 Site Activity — Site Selection Available Enterprise Sites: 1. <Site Name> ⚠️ — last published <short date>, updated <short date> (<N> days unpublished) 2. <Site Name> ✅ — published & updated <short date> 3. <Site Name> ⚠️ — never published, updated <short date> …and 4 more sites. Reply "show all" to see the rest. Which site would you like to review?Format rules:
- Dates: abbreviated ("Mar 6", "Apr 14"). Add the year only if it isn't the current year.
- Use ⚠️ when
lastUpdated > lastPublishedORlastPublishedis null; ✅ whenlastUpdated <= lastPublished. - When
lastPublished == lastUpdated, collapse the right-hand side to "published & updated ". - Omit the "…and N more sites" line when the workspace has 10 or fewer sites.
- Do not omit the status flag or the dates — they are required for every site.
-
Fetch selected-site details: After the user selects a site (or when a site ID was provided up front), call
data_sites_toolwith actionget_siteonce, for the selected site only, to retrieve fields not returned bylist_sites— in particular:- Custom domains
- Locale / localization settings
- Any additional site metadata needed for the analysis
lastPublishedandlastUpdatedare already known from step 1 (or fromget_siteif the user provided a site ID directly). Keep these in memory for the pre-publish filter in Phase 3. -
Infer intent from the prompt (do not ask a follow-up question if the prompt is clear). Map the request to one of:
- Recent activity summary ("what changed this week?")
- Specific user's activity ("what did Sarah change?")
- Specific activity type ("any CMS changes recently?")
- Pre-publish review ("what's changed since last publish?")
- General overview (default when the prompt is ambiguous)
Only ask a clarifying question if the request is genuinely ambiguous (e.g., "show me activity" with no time window, user, or event type context).
Phase 2: Fetch Activity Logs
- Fetch activity logs: Use
list_site_activity_logswith the site ID- Default to
limit: 100(maximum per request) for comprehensive results - The API returns events in reverse chronological order (newest first)
- Default to
- Handle pagination: If the user needs older activity or the results suggest more data exists:
- Use
offsetparameter to fetch additional pages - Combine results across pages for analysis
- Warn the user if going back further than available data
- Use
Phase 3: Analysis & Summarization
-
Parse each activity log entry: Each event contains:
id: Unique event identifiercreatedOn: Timestamp (ISO 8601)lastUpdated: Last update timestampevent: Event type string (see Event Types below)user: Object withidanddisplayName(absent for system events like backups)resourceOperation: The operation performed (CREATED,MODIFIED,DELETED)resourceId: ID of the affected resource (when applicable)resourceName: Human-readable name of the affected resourcepayload: Additional event-specific details (see Payload Details below)
-
Categorize events into human-readable groups (41 event types):
Page Changes:
page_dom_modified— Page structure/element changespage_created— New page creationpage_deleted— Page deletionpage_duplicated— Page duplicationpage_renamed— Page renamepage_settings_modified— Page settings updates (SEO, slug, etc.)page_custom_code_modified— Page-level custom code changespage_settings_custom_code_modified— Page settings custom code changes
Style & Variable Changes:
styles_modified— Style/class changesvariable_modified— Single variable changevariables_modified— Multiple variable changes
Component Changes:
symbols_modified— Component/symbol created, modified, or deleted
Interactions:
ix2_modified_on_page— Interaction changes on a pageix2_modified_on_component— Interaction changes on a componentix2_modified_on_class— Interaction changes on a class
CMS Changes:
cms_item— Collection item created, modified, or deletedcms_collection— Collection schema created, modified, or deleted
Site Management:
site_published— Site publishedsite_unpublished— Site unpublishedsite_custom_code_modified— Site-level custom code changesbackup_created— Automatic or manual backupbackup_restored— Backup restored
Localization:
secondary_locale_page_content_modified— Localized page content changedlocale_added— New locale addedlocale_removed— Locale removedlocale_enabled— Locale enabledlocale_disabled— Locale disabledlocale_display_name_updated— Locale display name changedlocale_subdirectory_updated— Locale subdirectory changedlocale_tag_updated— Locale tag changed
Branches:
branch_created— Branch createdbranch_merged— Branch mergedbranch_deleted— Branch deletedbranch_review_created— Branch review requestedbranch_review_approved— Branch review approvedbranch_review_canceled— Branch review canceled
Library:
library_shared— Library shared with other siteslibrary_unshared— Library unsharedlibrary_installed— Library installed from another sitelibrary_uninstalled— Library uninstalledlibrary_update_shared— Library update publishedlibrary_update_accepted— Library update accepted
Note: If an event type not listed above appears, categorize it as "Other" and display the raw
eventstring. -
Apply filters based on user's request:
- By event category (e.g., only CMS changes)
- By user (match on
user.displayName) - By time window (filter
createdOntimestamps client-side) - By resource (match on
resourceName) - Pre-publish review: When the user wants to see changes since the last publish, use the site's
lastPublishedtimestamp (from Phase 1) and filter to events wherecreatedOn > lastPublished. IflastPublishedis null (never published), all events qualify as unpublished.
-
Generate insights (include in the Highlights section of the report):
- Most active user in the time period
- Event type distribution (which category dominated)
- Busiest day or hour
- Single-user concentration (flag when one person made 40%+ of changes)
- Unpublished changes (count of events where
createdOn > lastPublished)
Phase 4: Reporting
-
Generate summary report with these sections:
- Time range covered and total event count
- Breakdown by activity type
- Breakdown by user
- Highlights — call out patterns such as high-frequency changes to a single page/collection, multiple users editing the same resource, unpublished changes (since last publish), and system events vs. user-initiated changes
-
Answer the user's specific question: If the user asked something specific, lead with the direct answer before the structured report.
-
Pick the detail level from the prompt:
- "counts only" / "how many" / "just numbers" → Quick summary (counts by category only)
- default → Standard report (categorized events with user attribution — see Example 1)
- "walk me through" / "show every change" / "timeline" → Detailed report (chronological per-event view with payload)
- "share" / "export" / "for my team" / "summary to send" → Shareable/Export report (see Example 3)
The detail-level switch is always surfaced as one of the follow-up options in step 13 so the user can request a different level.
-
Always end every report with a follow-up options section. This is required, not optional. Use the exact format below, tailoring the numbered options to what's relevant for the query just answered:
--- Would you like to: 1. Filter by a specific user 2. Filter by activity type 3. Fetch older activity (pagination) 4. Switch to a quick summary (counts only) or a detailed view (per-event payloads) 5. Export as markdown or JSONIf the report was a shareable/export format (e.g., "summary I can share"), place this block outside the shareable content so the user can copy the report cleanly without the follow-up menu in it.
Event Payload Details
Different event types include different payload fields:
page_dom_modified:
pageTitle: Name of the modified pagepageId: ID of the modified pagecount: Number of modifications in this batchbranchId/branchName: Branch context (null if main)
cms_item:
cmsCollectionId: ID of the parent collectioncmsCollectionName: Name of the parent collectioncount: Number of items affectedname: Locale name (e.g., "English", "Spanish")
styles_modified:
selector: CSS selector (if applicable)variant: Breakpoint/pseudo-class variant stringparentChain: Array of parent style names (combo class chain)type: Style type (e.g., "class")branchId/branchName: Branch context
symbols_modified:
branchId/branchName: Branch context
page_settings_modified:
pageTitle: Name of the modified pagebranchId/branchName: Branch context
backup_created:
- No payload;
resourceNameindicates backup type (e.g., "Automatic backup", "Maintenance backup") - No
userfield (system-initiated)
Examples
User prompt:
What happened on my site this week?
Step 1: Site Selection
📋 Site Activity — Site Selection
Available Enterprise Sites:
1. Acme Corp Website ⚠️ — last published Apr 14, updated Apr 16 (2 days unpublished)
2. Acme Blog ✅ — published & updated Apr 10
Which site would you like to review?
Step 2: Activity Summary
📋 Site Activity: Acme Corp Website
April 10–16, 2026 (93 events)
**93 events this week from 3 team members. 28 are unpublished since the last publish on Apr 14.**
---
## Activity Breakdown
📄 Page modifications 34 events
🎨 Class changes 22 events
📝 CMS updates 18 events
🧩 Component changes 8 events
🔤 Variable changes 5 events
🚀 Publishes 3 events
💾 Backups 2 events
🌿 Branch activity 1 event
---
## Activity by User
**Sarah Chen** — 42 events
└── Page modifications (18), Class changes (15), CMS updates (9)
**Alex Kim** — 31 events
└── CMS updates (9), Page modifications (12), Component changes (8), Variables (2)
**Jordan Lee** — 17 events
└── Class changes (7), Page modifications (4), Publishes (3), Backups (2), Branch (1)
**System** — 3 events
└── Backups (auto)
---
## Highlights
- ⚠️ **Unpublished changes**: 28 events since last publish (Apr 14)
- 📊 **Busiest day**: April 15 (41 events)
- 👤 **Most active**: Sarah Chen (45% of all activity)
- 🧩 8 component changes by Alex Kim — may affect multiple pages
---
Would you like to:
1. Filter by a specific user
2. Filter by activity type
3. See details for unpublished changes only
4. Switch to a quick summary (counts only) or detailed view (per-event payloads)
5. Fetch older activity
User prompt:
Show me CMS changes on site 6924868ede9d3fbbc3195eb0
Response:
📋 CMS Activity: Acme Corp Website
April 10–16, 2026 (18 CMS events)
**18 CMS events from 2 users over 5 days. 3 changes are unpublished.**
---
## CMS Breakdown
📝 Items modified 11 events
➕ Items created 5 events
📚 Collection changes 2 events
---
## Activity by User
**Sarah Chen** — 10 events
└── 2 items created, 7 items modified, 1 collection modified
**Alex Kim** — 8 events
└── 3 items created, 4 items modified, 1 bulk publish
---
## Highlights
- ⚠️ **Unpublished**: 3 CMS changes since last publish (Apr 14)
- 📊 **Busiest day**: April 15 (8 events)
- 📚 **Schema changes**: 2 collection edits this week (review carefully before publish)
---
Would you like to:
1. Filter to a specific collection
2. Filter by user (Sarah or Alex)
3. See only the unpublished CMS changes
4. Switch to a timeline view (chronological per-event) or counts only
5. Fetch older CMS activity
User prompt:
Give me a weekly summary I can share with my team for Acme Corp Website
(Naming the site inline skips Phase 1 step 1. If the user doesn't name a site, run the site-selection list first before producing this report.)
Response:
📋 Weekly Site Activity Report
Acme Corp Website — Week of April 10–16, 2026
---
### Overview
- **93 total changes** across 3 team members
- **3 publishes** (Apr 10, Apr 12, Apr 14)
- **28 unpublished changes** pending review
- **Last publish:** April 14 at 18:30 UTC
### What Changed
- 34 page modifications across 8 pages
- 22 class/style updates
- 18 CMS content changes (5 new items, 11 edits, 2 schema changes)
- 8 component updates
- 5 variable changes
### Team Activity
| Team Member | Changes | Top Activity |
|-------------|---------|-------------------------------|
| Sarah Chen | 42 | Page edits, style updates |
| Alex Kim | 31 | CMS content, components |
| Jordan Lee | 17 | Styles, publishing, backups |
### Action Items
- ⚠️ 28 changes are unpublished — consider reviewing and publishing
- 🧩 8 component changes may affect shared layouts — verify before publish
- 💾 Last backup: April 14 — consider creating a fresh backup
---
Generated from Webflow Site Activity Log
Would you like to:
- Filter to a specific user's changes
- Break down unpublished changes in detail
- Regenerate with a different date range
- Switch to a quick summary (counts only) or detailed per-event view
- Export as JSON instead of markdown
Guidelines
Enterprise-Only Access
Plan Requirement:
list_site_activity_logsis available only on Enterprise hosting plans- If the API returns a permissions error, clearly inform the user:
⚠️ Site Activity Logs require an Enterprise hosting plan. This site does not appear to have Enterprise access. - Do not retry on permissions errors — the issue is plan-level, not transient
API Constraints
Pagination:
- Maximum 100 events per request
- Use
offsetto paginate: first call offset=0, second call offset=100, etc. - 100 events typically covers approximately one week for an active enterprise site
- No native date filtering — all filtering must be done client-side after fetching
When to paginate:
- User asks for more than one week of activity
- User needs a complete picture and first page returns exactly 100 events
- Always tell the user how much data you have: "Showing the last 93 events (Apr 10–16)"
Rate awareness:
- Avoid unnecessary pagination — fetch only what is needed to answer the question
- If user asks "any publishes recently?" — 100 events is likely enough
- If user asks "full month of activity" — explain the limitation and paginate up to 300 events maximum
Error Handling
Common errors:
- 403 / Permission denied: Enterprise plan required — inform user clearly
- 404 / Site not found: Verify site ID, offer to list available sites
- Empty results: Site may have no recent activity — confirm with user and check site details
Graceful degradation:
- If site details fetch fails, still attempt activity logs
- If pagination fails mid-way, report what was successfully fetched
- Always show partial results rather than nothing
Site Audit
Comprehensive audit of a Webflow site's structure, content health, and quality with detailed analysis and multiple export formats.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
data_sites_toolwith actionlist_sitesfor listing available sites - Use Webflow MCP's
data_sites_toolwith actionget_sitefor detailed site information - Use Webflow MCP's
data_pages_toolwith actionlist_pagesfor retrieving all pages - Use Webflow MCP's
data_cms_toolwith actionget_collection_listfor listing CMS collections - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsfor detailed collection schemas - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsfor counting items - Use Webflow MCP's
webflow_guide_toolto get best practices before starting - DO NOT use any other tools or methods for Webflow operations
- All tool calls must include the required
contextparameter (15-25 words, third-person perspective)
Instructions
Phase 1: Site Selection & Discovery
- Get site: Identify the target site. If user does not provide site ID, ask for it.
- Fetch site details: Use Webflow MCP's
data_sites_toolwith actionget_siteto retrieve:- Site name and ID
- Last published date
- Last updated date
- Timezone
- Locales (primary and secondary)
- Custom domains
- Ask user preferences: Ask what level of detail they want:
- Quick summary (counts only)
- Standard inventory (pages + collections + counts)
- Detailed inventory (includes all field schemas, item samples, SEO data)
- Full export (everything + export to file format)
Phase 2: Pages Inventory
- List all pages: Use Webflow MCP's
data_pages_toolwith actionlist_pagesto fetch all pages - Categorize pages:
- Static pages (no collectionId)
- CMS template pages (has collectionId)
- Archived pages
- Draft pages
- Analyze page structure:
- Count pages by type
- Identify pages missing SEO metadata
- Detect orphaned pages (no navigation links)
- Check for duplicate slugs
Phase 3: CMS Collections Inventory
- List all collections: Use Webflow MCP's
data_cms_toolwith actionget_collection_list - For each collection:
- Get detailed schema using Webflow MCP's
data_cms_toolwith actionget_collection_details - Count items using Webflow MCP's
data_cms_toolwith actionlist_collection_items - Analyze field types and requirements
- Identify required vs optional fields
- Detect reference fields and relationships
- Get detailed schema using Webflow MCP's
- Collection analysis:
- Empty collections (0 items)
- Unused collections (no template page)
- Large collections (100+ items)
- Collections with missing required fields
Phase 4: Analysis & Insights
- Generate insights:
- Total content count (pages + items)
- Content health score
- SEO readiness
- Recommended improvements
- Identify issues:
- Missing SEO metadata
- Empty collections
- Orphaned pages
- Draft content ratio
- Show relationships:
- Which pages use which collections
- Reference field connections
- Content dependencies
Phase 5: Export & Formatting
- Ask export format (if user wants full export):
- Markdown (readable, great for documentation)
- JSON (machine-readable, for migrations)
- CSV (spreadsheet-friendly, for analysis)
- Text summary (console output only)
- Generate report in requested format
- Provide actionable insights: Suggest next steps based on findings
Examples
User prompt:
Give me a complete inventory of my site.
Step 1: Initial Report (Standard Inventory)
📊 Site Audit: MCP Demo#1
**Site Details:**
- Site ID: 6924868ede9d3fbbc3195eb0
- Last published: January 9, 2026
- Last updated: January 9, 2026
- Timezone: Asia/Calcutta
- Primary locale: English (en)
---
**Pages (2 total):**
Static Pages (1):
├── Home (/)
CMS Template Pages (1):
└── Blog Posts Template (/post)
- Collection: Blog Posts
---
**CMS Collections (1):**
Blog Posts (9 items)
├── Slug: post
├── Fields (8):
│ ├── Name (PlainText, required)
│ ├── Slug (PlainText, required)
│ ├── Post Body (RichText)
│ ├── Post Summary (PlainText)
│ ├── Main Image (Image)
│ ├── Thumbnail image (Image)
│ ├── Featured? (Switch)
│ └── Color (Color)
---
**Summary:**
- ✅ 2 pages (1 static, 1 CMS template)
- ✅ 1 CMS collection with 9 published items
- ✅ Site fully published and up-to-date
Would you like a detailed analysis or export in a specific format?
Step 2: Detailed Analysis (when user requests)
🔍 Detailed Analysis: MCP Demo#1
**Content Health Score: 85/100**
✅ Strengths:
- All collections have items (no empty collections)
- All pages are published (no drafts)
- Site recently published (Jan 9, 2026)
- Consistent field structure in Blog Posts
⚠️ Areas for Improvement:
- No SEO metadata on template page (missing meta description)
- Limited page count (consider adding About, Contact pages)
- No reference fields (could link categories/authors to posts)
💡 Recommendations:
1. Add meta descriptions to all pages for better SEO
2. Consider creating a Categories collection for post organization
3. Add an Authors collection for multi-author blog support
4. Create navigation pages (About, Contact, Privacy Policy)
**Collection Breakdown:**
Blog Posts:
- 9 published items (0 drafts, 0 archived)
- 5 featured posts (56%)
- All required fields populated ✓
- Field usage:
- Name: 100% (9/9)
- Slug: 100% (9/9)
- Post Body: 100% (9/9)
- Post Summary: 100% (9/9)
- Main Image: 100% (9/9)
- Thumbnail: 100% (9/9)
- Featured: 100% (9/9)
- Color: 100% (9/9)
**Sample Items:**
1. "Why Webflow is the Best Choice for 2026" (featured)
2. "Top Webflow Features to Look Forward to in 2026"
3. "Webflow vs. Competitors: Who Will Win in 2026?" (featured)
---
Export this inventory? (markdown/json/csv/no)
Step 3: Export Options
📥 Export Format Options:
1. **Markdown** - Human-readable documentation
- Great for README files, wikis, documentation
- Preserves structure and formatting
2. **JSON** - Machine-readable structured data
- Perfect for migrations, integrations
- Includes all raw API data
3. **CSV** - Spreadsheet-friendly
- Easy to analyze in Excel/Google Sheets
- Separate files for pages and collections
Which format would you like? (1/2/3)
Guidelines
Phase 1: Critical Requirements
Site Information:
- Always fetch complete site details using
data_sites_toolwith actionget_site - Include last published and last updated dates
- Show timezone and locale information
- Display custom domains if configured
User Options: Offer multiple detail levels:
- Quick: Just counts
- Standard: Pages + collections + basic info
- Detailed: Full schema + analysis + insights
- Export: Everything + file output
Phase 2: Pages Analysis
Page Categorization:
- Separate static pages from CMS template pages
- Flag archived and draft pages separately
- Show page slugs/URLs for reference
- Identify pages with missing SEO metadata
Page Health Checks:
- Missing meta descriptions
- Missing OG tags
- Duplicate slugs (error condition)
- Orphaned pages (not linked in nav)
Phase 3: Collections Analysis
Collection Details: For each collection, show:
- Display name and singular name
- Slug (URL structure)
- Total field count
- Required vs optional fields breakdown
- Item count (published/draft/archived)
- Last updated date
Field Analysis: Categorize by type:
- Text fields (PlainText, RichText)
- Media fields (Image, Video, File)
- Relationship fields (Reference, MultiReference)
- Data fields (DateTime, Number, Color)
- Boolean fields (Switch)
- Selection fields (Option)
Field Validation:
- Show max length constraints
- Show validation patterns
- Flag required fields
- Identify reference field targets
Phase 4: Analysis & Insights
Content Health Score (0-100): Calculate based on:
- SEO metadata completeness (25 points)
- Content-to-page ratio (20 points)
- Field utilization (20 points)
- Recent updates (15 points)
- Structure quality (20 points)
Issue Detection:
- 🔴 Critical: Missing required fields, duplicate slugs
- ⚠️ Warning: Empty collections, missing SEO, drafts
- 💡 Suggestion: Add pages, create relationships, organize
Recommendations: Suggest improvements based on:
- Missing page types (About, Contact, etc.)
- Underutilized collections
- Missing relationships between collections
- SEO optimization opportunities
Phase 5: Export Formats
Markdown Export:
# Site Audit: [Site Name]
## Site Information
- ID: [site-id]
- Last Published: [date]
## Pages
### Static Pages
- Home (/)
- About (/about)
### CMS Templates
- Blog Post (/post/[slug])
## Collections
### Blog Posts (47 items)
**Fields:**
- Title (PlainText, required)
- Slug (PlainText, required)
- Content (RichText)
...
JSON Export:
{
"site": {
"id": "...",
"name": "...",
"lastPublished": "..."
},
"pages": [...],
"collections": [...]
}
CSV Export: Generate separate files:
pages.csv: All pages with metadatacollections.csv: Collection metadatafields.csv: All fields across collectionsitems.csv: Item counts per collection
Performance Optimization
Batch Processing:
- For sites with 20+ collections, show progress
- For collections with 100+ items, paginate counts
- Provide estimated time for large sites
Error Handling:
- If
data_pages_toolwith actionlist_pagesfails, continue with collections - If
data_cms_toolwith actionget_collection_detailsfails, show basic collection info - Report partial successes separately
- Offer to retry failed operations
Data Efficiency:
- Use pagination for large result sets
- Only fetch detailed schemas when needed
- Limit item samples to 3-5 per collection
- Cache site info for repeat operations
Best Practices
Read-Only Operation:
- No confirmation needed (read-only)
- Safe to run multiple times
- No side effects or modifications
Clear Organization:
- Group by content type (pages/collections)
- Use visual hierarchy (├── └──)
- Show counts prominently
- Highlight issues with icons (✅ ⚠️ 🔴 💡)
Actionable Output:
- Always end with recommendations
- Offer export options for detailed inventories
- Suggest next steps based on findings
- Provide comparison against best practices
Version Tracking: If user runs inventory multiple times:
- Compare with previous run
- Show changes (new pages, deleted collections)
- Track content growth over time
- Alert on significant changes
Troubleshoot Deploy
Debug and fix deployment issues for Webflow Code Components.
When to Use This Skill
Use when:
webflow library sharefailed with an error- Components deployed but aren't working correctly
- User shares an error message from deployment
- Bundle or compilation errors occurred
Do NOT use when:
- Deployment hasn't been attempted yet (use deploy-guide instead)
- Validating before deployment (use pre-deploy-check instead)
- General code quality issues (use component-audit instead)
Instructions
Phase 1: Gather Information
-
Get error details:
- Ask for exact error message
- Request output from
npx webflow library share - Check if
npx webflow library loghas additional info
-
Understand context:
- First deploy or update?
- Recent changes made?
- Working previously?
Phase 2: Diagnose
-
Identify error category:
- Authentication errors
- Build/compilation errors
- Bundle size errors
- Network/upload errors
- Configuration errors
-
Analyze root cause:
- Parse error message
- Check common causes
- Identify specific issue
Phase 3: Provide Solution
-
Give specific fix:
- Step-by-step resolution
- Code examples if needed
- Verification steps
-
Prevent recurrence:
- Explain why it happened
- Suggest preventive measures
Common Error Reference
For detailed solutions to each error, see references/ERROR_CATALOG.md.
Quick Reference
| Error | Category | Quick Fix |
|---|---|---|
| "Authentication failed" | Auth | Regenerate API token in Workspace Settings |
| "Insufficient permissions" | Auth | Check workspace role and token |
| "Module not found" | Build | npm install --save-dev @webflow/react |
| "TypeScript errors" | Build | Run npx tsc --noEmit to find error |
| "Unexpected token" | Build | Check file extension is .tsx |
| "Bundle size exceeds limit" | Bundle | Tree-shake imports, lazy load heavy components |
| "Component not rendering" | Runtime | Check SSR issues, browser console |
| "Styles not appearing" | Runtime | Import CSS in .webflow.tsx file |
| "webflow.json not found" | Config | Create webflow.json in project root |
| "No components found" | Config | Check glob pattern and file extension |
| "Invalid JSON in webflow.json" | Config | Fix JSON syntax (trailing commas, comments) |
| "429 Too Many Requests" | Network | Wait 60 seconds and retry |
| "Request timed out" | Network | Check connectivity, proxy, Webflow status |
| "JavaScript heap out of memory" | Memory | NODE_OPTIONS="--max-old-space-size=4096" |
| "Circular dependency" | Build | Extract shared code, break import cycles |
Most Common Fixes
Authentication:
# Regenerate token, then:
export WEBFLOW_WORKSPACE_API_TOKEN=your-new-token
npx webflow library share
Missing Dependencies:
npm install --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
SSR Issues:
// Wrap browser APIs in useEffect or disable SSR:
declareComponent(Component, { options: { ssr: false } });
Missing Styles:
// In .webflow.tsx, import styles:
import "./Component.module.css";
Debugging Commands
# Check recent deploy logs
npx webflow library log
# Verbose deploy output (shows detailed errors)
npx webflow library share --verbose
# Type check without deploying
npx tsc --noEmit
Validation
The issue is resolved when all of the following are true:
| Success Criteria | How to Verify |
|---|---|
| Deploy completes without errors | npx webflow library share exits cleanly |
| Components appear in Designer | Open Add panel in Designer and find your library |
| Import logs confirm success | npx webflow library log shows successful import |
Guidelines
Error Analysis Process
- Read the full error message - Often contains the solution
- Check the error category - Auth, build, bundle, or runtime
- Look for file paths - Points to exact location
- Check line numbers - For code errors
- Search error message - May be a known issue
When to Escalate
If none of the solutions work, gather this data before escalating:
- Deploy logs:
npx webflow library log - Verbose output:
npx webflow library share --verbose - Node.js version:
node -v - Package versions:
npm list @webflow/webflow-cli @webflow/data-types @webflow/react - Configuration: Contents of
webflow.json - Error message: Full error output (not just the summary line)
Then:
- Check Webflow status page for outages
- Search the Webflow Community Forum for your error message
- Contact Webflow Support with the collected data above
WAF Rules
Review and change the Web Application Firewall (WAF) rules and Bot bypass settings Webflow enforces on a site's connected custom domains. Changes reach live traffic without a site publish and can lock out real visitors, so validate rule configs, preview changes, and get user confirmation first.
Important Note
ALWAYS use Webflow MCP tools for all operations:
- Use Webflow MCP's
webflow_guide_toolbefore any other tool call - Use Webflow MCP's
data_sites_toolwith actionlist_sitesto find the site - Use Webflow MCP's
data_enterprise_toolwith these WAF actions. Each takessite_id.get_waf_rules: current rules per domain and thesiteStateHashvalidate_waf_rule: checks a candidate config and explains it in plain language. Changes nothing.test_waf_rules: previews an update or deletion and returns apreviewToken. Changes nothing.update_waf_rule,delete_waf_rule: write the live firewalltest_waf_settings: previews Bot bypass settings and returns apreviewToken. Changes nothing.update_waf_settings: writes the live Bot bypass settingssuggest_waf_changes: proposes rule changes and applies none. Read-only.
- DO NOT call the Webflow API directly or use any other tool to change WAF rules or settings
- Include the
contextparameter when the tool schema asks for it (15-25 words, third-person perspective)
Before You Start
The API refuses a call by name when one of these is missing (see Errors):
- Enterprise plan: WAF MCP needs an Enterprise plan that includes WAF.
- Settings action availability: discover the
data_enterprise_toolaction schema before offering a settings change. Iftest_waf_settingsorupdate_waf_settingsis absent, say Bot bypass changes are unavailable through this connection and point to Dashboard > Site settings > Security. Don't claim success or try to change settings through a rule config. - Role: the user must be able to manage the site's custom domains: Site manager, Designer, Limited designer, or a custom role with that permission. Designer (needs approval), Marketer, Content editor, and Reviewer can't.
- Scopes:
site_config:readfor reads andvalidate_waf_rule,site_config:writefortest_waf_rules,update_waf_rule,delete_waf_rule,test_waf_settings, andupdate_waf_settings. The Webflow MCP app requests both. If a call returnsmissing_scopes, the user has to reauthorize the connection.
Instructions
Phase 1: Read the current rules
- Call
webflow_guide_tool. It includes a WAF section. - Resolve the site with
list_sites. If the user didn't name one, or the name matches several, ask. - Call
get_waf_rulesand keep:byDomain: each connected custom domain's config, ornullwhen it has none. A config holds up to four rule types (ipRules,geoRules,asnRules,userAgentRules) plus the bot bypass settings.uniform: true when every domain has the same config.rulesthen holds it.hostnamesSkipped: connected domains WAF can't apply rules to yet.siteStateHash: all rule and settings previews and writes require it asexpectedSiteStateHash. Read again before each change; a hash from an earlier read is refused withWafSiteStateChanged.
- If the user asked for a review or an explanation, follow "Reviewing rules" and stop. A review doesn't authorize a change. For Bot bypass changes, follow "Changing Bot bypass settings" instead of Phases 2–4.
Phase 2: Build and validate the change
- Change one rule type at a time. An update replaces that rule type's entire config on its target domains, and any entry left out is removed. Copy the current config from
byDomain[domain][ruleType], apply the user's edit, and keep every other entry in its order. LeavebypassVerifiedBotsandbypassAuthorizedBotsout: they're settings, not part of a rule type. - Choose the scope (see "Domain scope"): site-wide when the change is for every domain and they share the current config, otherwise
domainspluspreviousDomains. - Call
validate_waf_rulewithruleType,config, and thedomainsandpreviousDomainsyou plan to use. It's read-only and needs no hash, so call it as often as needed.success: falsewithValidationError: fix the config fromerror.details(field path and message) anderror.schema(the JSON Schema for the rule type, present when the shape itself is wrong). Cross-field user-agent rules appear only indetails. Validate again. If an entry that's already live is what fails (older rules can predate today's checks), tell the user instead of dropping or rewriting it silently.success: true: read everyexplanationline and check it against what the user asked for. If it describes anything they didn't ask for, such as "blocks every other country", fix the config or ask. Use the normalizedconfigit returns from here on.- Non-empty
riskFindings: tell the user now that applying will need a second confirmation (see "High-risk changes"), and offerpathsto narrow the rule.
- If the request spans several rule types, make one change per rule type, in sequence. You can validate them all and confirm them together, but re-read and test each one right before applying it: every apply changes the
siteStateHash.
Phase 3: Preview and confirm
- Call
test_waf_ruleswith the sameruleType,config,domains, andpreviousDomains, plusexpectedSiteStateHashfrom your latestget_waf_rules. - Show the user a preview: rule type and scope, current and new entries, which domains change (
targets[].changed), eachriskFindingsmessage, anyhostnamesSkipped, and size headroom whencandidateBytesis close tocandidateBytesLimit. The test checks configuration, not traffic, so it can't say which visitors will be blocked. - Ask the user to type
confirm. "Yes" or "ok" isn't enough. ThepreviewTokenexpires atexpiresAt, about 5 minutes after the test. If it lapses, test again, and show the preview again if the targets or risks changed.
Phase 4: Apply and verify
- Call
update_waf_rulewith exactly the testedruleType,config,domains, andpreviousDomains, the sameexpectedSiteStateHash, and thepreviewToken. - On
HighRiskWafChange, follow "High-risk changes". On any othersuccess: false, see "Errors". - On success, report
hostnamesApplied,hostnamesCleared(domain-scoped updates), and anyhostnamesSkipped. Then callget_waf_rulesand check that each target domain has the new config.
Changing Bot bypass settings
- Confirm both settings actions are available, then read with
get_waf_rules. Buildsettingswith onlybypassVerifiedBotsand/orbypassAuthorizedBots: each is an optional boolean, at least one is required, and no other keys are allowed. A combined "enable Bot bypass" or "disable Bot bypass" request always sends both booleans with the same value; change just one only when the user explicitly asks for that setting. - Settings changes are site-wide across connected custom domains: don't send
domains,previousDomains,ruleType, orconfig. Each domain keeps its own rules, omitted settings, and existing bot tokens. Don't create or revoke tokens, ask the user to paste one, or expose one. - Call
test_waf_settingswithsite_id,settings, andexpectedSiteStateHashfrom the latestget_waf_rules. It changes nothing and returnstargets(hostname,changed,candidateBytes,candidateBytesLimit),hostnamesSkipped,previewToken, andexpiresAt. It checks the candidate settings, not traffic; don't usevalidate_waf_rulefor settings or claim a preview proves traffic is safe. - Show current and proposed values per domain, which targets change, skipped hostnames, and size headroom when close to the limit. Turning bypass off makes customer WAF rules apply to verified crawlers and bots using valid tokens, which may affect search indexing. Turning it on lets eligible bots skip customer rules, never Webflow's own security protections. For a single-setting change, describe only the affected bot category.
- Ask the user to type
confirm; "yes" or "ok" isn't enough. After confirmation, callupdate_waf_settingswith the exact samesite_id,settings, andexpectedSiteStateHash, plus thepreviewTokenfrom that test. If the preview expires, test again; if state changed, re-read and rebuild. Show any changed preview and get confirmation again. - On success, report the result and any skipped hostnames. Re-read with
get_waf_rulesand verify the requested settings on each target domain and that rules and omitted settings were preserved. Don't claim success from the preview alone.
Deleting a rule type
- Call
test_waf_ruleswithoperation: "delete",ruleType, optionaldomains, andexpectedSiteStateHash. Don't sendconfigorpreviousDomains. - Show which domains lose the rule type and ask for
confirm. - Call
delete_waf_rulewith the sameruleTypeanddomains,expectedSiteStateHash, and thepreviewToken. Other rule types and settings stay. ReporthostnamesCleared.
To remove the last entry from ips, countryList, or asnList, delete the rule type: those lists can't be empty.
Applying without a preview
directApply: true on update_waf_rule, delete_waf_rule, or update_waf_settings skips the corresponding test action. Use it only when the user explicitly asks to apply without a preview, and never together with previewToken. Still read, validate rule configs, show the change and its warnings, and get confirm. The high-risk confirmation still applies to rule changes.
High-risk changes
These shapes can block nearly all traffic:
- a geo or ASN
ALLOWlist withoutpaths - a user-agent
matchMode: "any"BLOCK withoutpaths - IP BLOCK entries that cover a whole address family (
0.0.0.0/0,::/0, or ranges that add up to one)
Only the rule type being changed is checked. validate_waf_rule and test_waf_rules report these in riskFindings, and update_waf_rule answers HighRiskWafChange and changes nothing. Then:
- Show the user
error.highRiskChange:targetHostnames, each risk'stitleandmessage, and theconfirmationPhrase(for exampleAPPLY TO 2 DOMAINS). - Ask the user to type that phrase. Only the user can confirm. Don't type it for them, and don't treat an earlier
confirmor your own judgment as confirmation. - After the user types it, resend the same
update_waf_rulerequest withhighRiskChangeConfirmation:candidateHash,currentStateHash,confirmationPhrase,expiresAt, andconfirmationTokencopied unchanged fromerror.highRiskChange, andacknowledgedRiskIdslisting everyrisks[].idfrom the challenge (not theriskFindingscodes). - The challenge expires about 5 minutes after it's issued. An expired or edited confirmation gets a new challenge: show it and ask again. If the preview token lapsed (
WafPreviewExpired), test again first.
Reviewing rules
- Read with
get_waf_rulesand describe each domain's rules in plain language, in evaluation order (see "How rules combine"). Say when domains differ. - Flag what's likely to surprise the user: geo or ASN allow-lists and user-agent catch-alls; IP or user-agent
ALLOWentries the user may expect to exempt traffic from other rule types; entries that can never match because an earlier entry catches the same traffic;bypassVerifiedBots: false(search crawlers can be blocked); domains with no config;hostnamesSkipped. - For a plain-language reading of a rule type, pass its current config to
validate_waf_ruleand useexplanation. When domains differ, setdomainsandpreviousDomainsto that one domain. suggest_waf_changesproposes changes and applies none. A ruleproposedChangeis a single entry: merge it into the full config and take it through the normal flow. For a suggestion of typesetting, use "Changing Bot bypass settings" only forbypassVerifiedBotsorbypassAuthorizedBots, and only after the user requests the change. Other settings aren't supported by these actions.
Drafting rules from traffic findings
Use this when the user brings findings (User-Agents, paths, IPs, ASNs, countries) instead of a specific rule. Draft the configs, then take each one through Phase 2 onward. Drafting changes nothing.
Classification comes from the user's own traffic analysis. Don't guess it: a wrong category produces a wrong scope. If a User-Agent arrives without one, ask.
| Category | Meaning | Examples | Rule |
|---|---|---|---|
| A. Certain bot | Self-evidently automated | curl, HeadlessChrome/..., an empty UA, a run of sequential synthetic browser versions | BLOCK, global |
| B. Cooperative crawler | Identifies itself and respects robots.txt | Googlebot, Bingbot, GPTBot | ALLOW, before any BLOCK |
| C. Monitoring | Health checks and uptime monitors | Route 53 health checks, Pingdom | No rule. The fix is stopping the health check. |
| D. Suspicious | Looks like a browser but with unusual volume or a uniform path pattern | A current Chrome UA hitting / millions of times | BLOCK, paths limited to the confirmed bot paths. A global BLOCK is valid if the user asks. |
- Treat Category C as a hypothesis until the traffic matches what that service does. For Category D, report behavior and volume only. Don't call it a confirmed bot.
- An obsolete browser version (before 2020, such as Chrome/69) is a global BLOCK. A current version is a BLOCK with
pathsonly. To track new releases without hardcoding a version, usebrowserVersionFloorwithminVersionandpaths. - Put every
ALLOWbefore anyBLOCK, and specific patterns before broad ones (GooglebotALLOW before abotBLOCK). SetblockEmpty: truewhen an empty User-Agent is confirmed. - IPs must come from the user's own origin, proxy, or CDN logs: Webflow doesn't provide raw IP logs. IP rules have no
paths, so use a path-scoped ASN or user-agent rule for a path-scoped block. - Scope broad cloud ASNs (AWS 16509, DigitalOcean 14061, Hetzner 24940, OVH 16276, Azure 8075) to the confirmed bot paths. Otherwise real cloud-hosted traffic on other paths is blocked.
- If a known automated client (an uptime check, an integration) would be locked out by a catch-all or an allow-list, explain that a bot token can bypass customer rules only while
bypassAuthorizedBotsis enabled. - A rule type with no data gets a note only, never an empty list.
- Above each draft, give the data behind it, the false-positive risk, and what is missing.
Don't measure or promise safety. Repeat any impact figures the user supplies and name their source. Otherwise write Impact on real visitors: not assessed. Blocking a real visitor means lost traffic that the product gives no way to see afterward. Warn about:
| Scenario | Warn the user |
|---|---|
| A current browser version in a BLOCK | Real users on that version are blocked. Use paths. |
| An ASN block that covers residential or mobile networks | Real users on those networks are blocked. |
A geo or ASN ALLOW list with a short list | Every unlisted country or network is denied, including requests with no signal. |
A common substring such as bot | It can match legitimate crawlers. Put ALLOW entries first. |
An any BLOCK or ALLOW list on a site with automated clients | The client can be locked out. Consider a bot token. |
A browserVersionFloor BLOCK without minVersion | If Webflow's version data is unavailable, it applies to every version of that browser. |
When a rule seems not to work
Check in this order before calling a rule broken:
- A
*bot*pattern is matched as the literal text*bot*, which never appears in a real User-Agent. Use{ "pattern": "bot", "matchMode": "contains" }or specific names such asGPTBot. - The bot is verified and Bot bypass is on (see "Blocking bots and AI crawlers").
- The request carries a valid bot token and
bypassAuthorizedBotsis enabled, ormatchModeand the pattern text don't match what the user expects. - The traffic goes to a different hostname than the one carrying the rule. A hostname with no config isn't checked.
- The change was saved moments ago. Test again once before concluding it failed.
- The request was allowed because the WAF couldn't reach a verdict. This is rare and can't explain a steady stream getting through. Treat it as the cause only after the other checks, and suggest contacting Webflow support.
Rule Reference
mode is BLOCK or ALLOW. validate_waf_rule names the exact field when something is wrong.
ipRules
{
"ips": [
{ "ip": "198.51.100.7", "mode": "ALLOW" },
{ "ip": "198.51.100.0/24", "mode": "BLOCK" },
{ "ip": "2001:db8::/32", "mode": "BLOCK" }
]
}
- 1-100 entries: IPv4 or IPv6 addresses or CIDR ranges. The size limit can run out before 100 (see "Size limit"). IPv4 needs all four parts (
10.0.0.0/8, not10/8). - First match wins. Above,
198.51.100.7isn't blocked by the/24because it matches first. ALLOWonly skips the rest of the IP list. It doesn't exempt the request from geo, ASN, or user-agent rules.- IP entries can't have
paths.
geoRules
{ "countryList": ["RU", "KP"], "mode": "BLOCK" }
- 1-250 ISO 3166-1 alpha-2 codes:
GB, notUK. Unofficial codes such asEUandXKare rejected. Lowercase is accepted and stored uppercase. BLOCKblocks the listed countries.ALLOWblocks every country that isn't listed, and also blocks requests with no country data, becauseALLOWis default-deny.BLOCKlets requests with no country data through (see IP geolocation).- One
modeand one optionalpathsfor the whole list, so a domain can't have a country block list and allow list at the same time.
asnRules
{ "asnList": [14061, 24940], "mode": "BLOCK", "paths": [{ "path": "/api" }] }
- 1-100 ASNs as numbers, not strings like
"AS14061". Examples: 16509 Amazon/AWS, 14061 DigitalOcean, 24940 Hetzner, 16276 OVH. modeandpathswork as in geoRules, so anALLOWlist also blocks requests with no ASN data (default-deny), whileBLOCKlets them through. Blocking a hosting network blocks everything that runs there, not only scrapers.
userAgentRules
{
"blockEmpty": true,
"patterns": [
{ "pattern": "AcmeApp/", "mode": "ALLOW", "paths": [{ "path": "/api" }] },
{ "matchMode": "any", "mode": "BLOCK", "paths": [{ "path": "/api" }] },
{ "pattern": "BadBot", "mode": "BLOCK" }
]
}
Above, only AcmeApp can call /api, BadBot is blocked everywhere, and requests with no User-Agent are blocked everywhere.
- Up to 50 patterns. First match wins, and a request that matches none is allowed.
ALLOWonly skips the remaining patterns. blockEmpty(defaultfalse) blocks requests with no User-Agent, on every path, before patterns are checked.matchMode:contains(default): case-insensitive substring. Plain text:*and?aren't wildcards.exact: the whole User-Agent must equalpattern(case-sensitive).any: matches every request, including ones with no User-Agent. Omitpattern. Put it after theALLOWentries as a catch-all BLOCK to build an allow-list.browserVersionFloor: matchesbrowser(chrome,edge, orfirefox; Safari isn't supported) at or above a version floor set bywithinLatest(the latest N major versions, 1-100),minVersion(1-1000), or both, in which case the higher floor applies. Omitpattern. Usually anALLOWbefore a broader BLOCK. If Webflow's browser version data is unavailable, a rule withoutminVersionapplies to the whole browser family: a BLOCK then over-blocks and an ALLOW over-allows. SetminVersion, and scope a BLOCK withpaths.
browser,withinLatest, andminVersionare only allowed withbrowserVersionFloor.pattern: up to 256 characters, using letters, digits, spaces, and. , ; : / ( ) [ ] - _ + ! ~ * ? @ # =.pathsis set per pattern. A pattern whosepathsdon't match the request is skipped and the next one is checked.
To let recent Chrome through on /api and block every other User-Agent there, put a browserVersionFloor ALLOW before the catch-all. minVersion keeps the ALLOW from applying to every Chrome version if Webflow's version data is unavailable:
{
"blockEmpty": false,
"patterns": [
{ "matchMode": "browserVersionFloor", "browser": "chrome", "withinLatest": 12, "minVersion": 100, "mode": "ALLOW", "paths": [{ "path": "/api" }] },
{ "matchMode": "any", "mode": "BLOCK", "paths": [{ "path": "/api" }] }
]
}
Blocking bots and AI crawlers
Bot bypass runs before all of the site's WAF rules. While it's on (bypassVerifiedBots: true, the default), every bot Cloudflare verifies skips them. Cloudflare's verified list includes the major search engines and can include AI crawlers.
- While Bot bypass is on, a User-Agent block can't stop a verified crawler. Cloudflare's bot directory lists which bots are verified. If a block on a crawler doesn't take effect, the crawler is probably verified. Say this in the preview for any crawler block.
- Enable or disable Bot bypass through "Changing Bot bypass settings" when both settings actions are available; otherwise point to Dashboard > Site settings > Security. The combined control changes both
bypassVerifiedBotsandbypassAuthorizedBots. Turning it off makes rules apply to verified crawlers and token-authorized bots, and may affect indexing. - Bots with Webflow bot tokens skip the rules when
bypassAuthorizedBotsis enabled (absent means enabled). The client sendsx-wf-waf-authorization: wf_wafbot_<64 hex characters>. Customers create tokens in the Dashboard's Bot access section (up to 5 per site, each with a list of allowed methods that defaults toGETandHEAD). A token skips the site's WAF rules, but never Webflow's own protections. Don't create or revoke tokens, ask the user to paste one, or print one.
Path scope
"paths": [{ "path": "/admin" }, { "path": "/login", "matchMode": "exact" }]
- 1-20 entries. Each
pathstarts with/. Omitpathsto apply everywhere; an empty list is rejected. prefix(default) matches the path and everything under it:/apimatches/apiand/api/v1, not/api-docs.exactmatches only that path. Trailing slashes count.- With
prefix,/blogcovers/blogand the pages under it, while/blog/covers only/blog/itself, not/blog/post. { "path": "/" }matches only the home page, not the whole site.- geoRules and asnRules take
pathson the rule, userAgentRules on each pattern, and ipRules not at all.
How rules combine
- For each request, Webflow's own protections run first, and these rules can't override them. Bot bypass comes next (see "Blocking bots and AI crawlers"), then
ipRules,geoRules,asnRules, anduserAgentRules, in that order. The first BLOCK stops evaluation. If nothing blocks, the request is served. - Geo, ASN, and user-agent rules are independent: there is no country-and-network combination, and each applies to everything on the hostname unless it has its own
paths. - A path-scoped entry whose
pathsdon't match the request is skipped, so it doesn't use up the first-match slot. ALLOWnever overrides another rule type. An IPALLOWdoesn't let a visitor past a geo block.
Domain scope
- For rule changes, omit
domainsto change every connected custom domain. Each domain keeps its other rule types. When the domains' configs differ, a site-wide rule change can be refused withWafConfigDrift; use domain scope instead. Settings changes are always site-wide and preserve each domain's rules. domainsnames target domains as they appear inbyDomain. A domain-scoped update also needspreviousDomains: the domains the rule you're editing covered before the edit, or[]for a new rule. The rule type is removed from every domain inpreviousDomainsthat isn't indomains. Domains in neither list don't change.- To move a geo rule from
www.example.comtoshop.example.com, senddomains: ["shop.example.com"]andpreviousDomains: ["www.example.com"]. - Deletions take
domainsonly.
Size limit
Each domain's whole WAF config, all rule types together, has a storage limit of 3,584 bytes, measured as the config's JSON. A write over it fails with WAF configuration exceeds the storage limit (N of 3584 bytes used). targets[].candidateBytes and candidateBytesLimit show the headroom, and going over is a ValidationError. Long IP lists and many paths entries use it up fastest: an IP list in the high double digits can reach it before the 100-entry cap.
Cloudflare references
Webflow's WAF uses Cloudflare's data about each request (its country, ASN, and verified-bot status), but the rule format and behavior above are Webflow's own. Cloudflare's WAF custom rules, managed rules, rate limiting rules, and rule expressions aren't available through Webflow's WAF, so don't suggest or write them.
- IP geolocation: when a visitor's country looks wrong. Country data is Cloudflare's estimate, updated several times a week, and the page has a correction form.
- Radar IP lookup: to check an IP's country and ASN while writing
ipRules,geoRules, orasnRules. ASN pages followhttps://radar.cloudflare.com/as<number>, for example radar.cloudflare.com/as13335. Radar challenges automated requests, so if you can't load a page, give the user the link. - Verified bots: what makes a bot verified. Verified bots skip all WAF rules while Bot bypass is on; to check a specific crawler, see "Blocking bots and AI crawlers".
Errors
Every WAF action answers {success: true, ...} or {success: false, error: {name, message, ...}}. Relay error.message to the user. Refusals before the action runs arrive as an action error with status, code, and message.
| Result | Meaning and what to do |
|---|---|
ValidationError | Invalid config or request: the shape (details, plus schema from validate_waf_rule), an unknown domain, the size limit, or a date range. Fix it and validate again. |
WafSiteStateChanged, WafPreviewStale | The rules or settings changed after your read or test. Don't resend. Read again, rebuild the change on the new state, show the user if it differs, then validate rule configs and test again. |
WafPreviewExpired, WafPreviewInvalid | The token lapsed or doesn't match the request. Test again and apply exactly the tested values. |
WafPreviewRequired | No previewToken was sent. Test first. |
WafConflictingApplyMode | Both previewToken and directApply were sent. Send only the token. |
HighRiskWafChange | Nothing was applied. Follow "High-risk changes". |
WafMutationRateLimited | Too many changes on the site. Wait retryAfterSeconds, then retry once. Every update or delete attempt counts. |
WafPartialMutation | Some domains changed and others didn't. Show error.recovery (applied, failed, unknown, pending), read again, and reconcile with the user's OK. If a domain's state is unknown, suggest contacting Webflow support. |
WafChangeInProgress, WafChangeUnavailable | Another change is running, or changes are briefly unavailable. Retry shortly. |
WafChangeInterrupted | Another change interrupted this one. Read again and review before retrying. |
WafConfigDrift | The domains have different configs, so a site-wide rule change is refused. Use domain scope for rules, not settings. |
NoCloudflareHostnames | No custom domain WAF can apply to yet: none is connected, or setup hasn't finished. Tell the user. |
WafTestedApplyUnavailable | Applying a tested preview is off for this site. Nothing changed. Use directApply only if the user explicitly asks. |
403 waf_not_included_in_plan | The site's plan doesn't include WAF, which is available on Enterprise plans. Don't retry. |
403 forbidden | The user's role can't manage this site's domains. Don't retry. |
403 missing_scopes | The connection lacks site_config:read or site_config:write. The user reauthorizes the Webflow MCP connection. |
| 404 | The site isn't in this authorization or isn't active. |
503 waf_access_unavailable | WAF access couldn't be checked, and nothing changed. Retry in a few minutes. |
| Anything else | Relay error.message. Don't retry a write more than once. |
Examples
Example 1: Add countries to an existing block list
User prompt:
Block traffic from Russia and North Korea.
get_waf_rules:uniformis true, and both domains havegeoRules: {"countryList": ["CN"], "mode": "BLOCK"}.- Merge, keeping CN, and validate site-wide:
The{ "ruleType": "geoRules", "config": { "countryList": ["CN", "RU", "KP"], "mode": "BLOCK" } }explanationsays it blocks CN, RU, and KP on every domain, and there are no risk findings. test_waf_ruleswith the same values andexpectedSiteStateHash, then show:Country rule, all domains Now: block CN After: block CN, RU, KP Changes: example.com, www.example.com Risks: none Type "confirm" to apply.- After
confirm,update_waf_rulewith thepreviewToken, thenget_waf_rulesto verify.
Example 2: Allow only some countries (high-risk)
User prompt:
Only let visitors from the US and Canada in.
validate_waf_rulewith{"countryList": ["US", "CA"], "mode": "ALLOW"}returns anexplanationdescribing the allow-list and ageo_allow_list_default_denyrisk finding. Tell the user that every other country will be blocked, and ask whether it should apply only to some paths, such as/admin.- The user wants it everywhere. Test, preview, and get
confirm.update_waf_ruleanswersHighRiskWafChange. Show:High-risk change: Geo allow-list (default deny) Visitors from every country not in the allow list are blocked site-wide. Only traffic from the listed countries can continue. Domains: example.com, www.example.com To apply it, type: APPLY TO 2 DOMAINS - After the user types the phrase, resend the same request with:
"highRiskChangeConfirmation": { "candidateHash": "<copied from error.highRiskChange>", "currentStateHash": "<copied>", "confirmationPhrase": "APPLY TO 2 DOMAINS", "acknowledgedRiskIds": ["geo-allow-list"], "expiresAt": "<copied>", "confirmationToken": "<copied>" }
Example 3: Block a script on one path, but keep an integration working
User prompt:
Block python-requests on /api. Our sync job sends "AcmeSync/2.0 python-requests/2.31", so keep that working.
The site has userAgentRules: {"blockEmpty": false, "patterns": [{"pattern": "BadBot", "mode": "BLOCK"}]}. Keep the existing entry and put the ALLOW before the BLOCK it has to get past:
{
"blockEmpty": false,
"patterns": [
{ "pattern": "BadBot", "mode": "BLOCK" },
{ "pattern": "AcmeSync/", "mode": "ALLOW" },
{ "pattern": "python-requests", "mode": "BLOCK", "paths": [{ "path": "/api" }] }
]
}
Validate, check that the explanation scopes the python-requests block to /api, then test, confirm, and apply.
Example 4: Remove a rule type from one domain
User prompt:
Remove the country rules from shop.example.com.
test_waf_ruleswith{"operation": "delete", "ruleType": "geoRules", "domains": ["shop.example.com"], "expectedSiteStateHash": "<latest>"}.- Show that only shop.example.com loses its country rule, and that its other rules and the other domains don't change. Ask for
confirm. delete_waf_rulewithruleType,domains,expectedSiteStateHash, and thepreviewToken.
Example 5: Review the current rules
User prompt:
What is my firewall blocking right now?
Response:
WAF rules for Acme Site (2 custom domains, same rules on both)
1. IP: allows 198.51.100.7, blocks the rest of 198.51.100.0/24
2. Country: allows only US and CA, so every other country is blocked
3. User-Agent: blocks requests with no User-Agent, and anything containing "BadBot"
Bot bypass is on, so verified crawlers such as Googlebot skip these rules.
Worth knowing: the IP allow for 198.51.100.7 doesn't exempt that address from
the country rule. If it's outside the US and Canada, it's still blocked.
Example 6: Draft rules from traffic findings
User prompt:
Traffic analysis found curl, HeadlessChrome/112, an empty UA, an old Chrome/69 UA, and Chrome/145 hitting / and /manifest.json. Googlebot is present. Write the rules.
get_waf_rulesshows no user-agent rules. No IP, geo, or ASN data was given, so those get a note only.- Classify: Googlebot is B,
curlandHeadlessChromeare A, Chrome/69 is obsolete, and Chrome/145 is current, so its block getspaths. - Draft the user-agent config with a note above it: "
blockEmpty: truebecause an empty UA was confirmed. GooglebotALLOWcomes first. ⚠️Chrome/145is a current version, so it is limited to/and/manifest.json. Real users on Chrome/145 who open those paths will be blocked. Impact on real visitors: not assessed."
{
"blockEmpty": true,
"patterns": [
{ "pattern": "Googlebot", "matchMode": "contains", "mode": "ALLOW" },
{ "pattern": "curl", "matchMode": "contains", "mode": "BLOCK" },
{ "pattern": "HeadlessChrome", "matchMode": "contains", "mode": "BLOCK" },
{ "pattern": "Chrome/69.0.3497.100", "matchMode": "contains", "mode": "BLOCK" },
{
"pattern": "Chrome/145.0.0.0",
"matchMode": "contains",
"mode": "BLOCK",
"paths": [{ "path": "/", "matchMode": "exact" }, { "path": "/manifest.json", "matchMode": "exact" }]
}
]
}
- Validate, check that the
explanationlimits the Chrome/145 block to the two paths, then test, confirm, and apply as usual.
Example 7: Enable or disable Bot bypass
User prompt:
Turn Bot bypass off for Acme Site.
- Discover both settings actions and read the current state. Build
settings: {"bypassVerifiedBots": false, "bypassAuthorizedBots": false}. For "turn Bot bypass on", send both astrueinstead. test_waf_settingswithsite_id, those settings, and the latestexpectedSiteStateHash. Show affected domains and explain: "Verified crawlers and bots using valid tokens will be subject to your WAF rules. This may affect search indexing. Your rules and existing tokens stay unchanged. Typeconfirmto apply."- Wait for
confirm. Only then callupdate_waf_settingswith the identical settings and hash plus the returnedpreviewToken, then re-read to verify. If either action is missing, explain that MCP settings changes are unavailable and point to Site settings > Security; don't try a rule update instead.
Guidelines
- Never write without the user typing
confirmafter seeing the preview (or the change summary when they explicitly skipped preview). A request to review, explain, or suggest isn't permission to change anything. - Never send
highRiskChangeConfirmationunless the user typed theconfirmationPhraseafter seeing that challenge. - Never use
directApplyunless the user explicitly asked to skip the preview. - Change one rule type at a time, and always send its complete config, merged from a fresh
get_waf_rules. - Keep settings separate from rule configs. Combined Bot bypass changes send both booleans with the same value; preserve rules, omitted settings, and tokens.
- Don't resend a failed write unchanged: read again, rebuild, and test again. Every update or delete attempt counts against the site's change limit.
- Warn before blocking search crawlers, whole countries, or hosting networks, and suggest
pathsto limit broad rules. - Don't paste
previewTokenorconfirmationTokenvalues into chat. - When the API refuses a call, relay
error.message. Don't work around a refusal with another tool or a direct API call. - Don't guess a classification when drafting. Ask for it.
- Rate limiting isn't available in this WAF, so don't suggest it. Don't draft
pathRulesor generate bot tokens.
Webflow CLI Troubleshooter
Diagnose and resolve Webflow CLI issues with diagnostic commands and automated fixes.
Important Note
ALWAYS use Bash tool for all diagnostic operations:
- Execute diagnostic commands via Bash tool
- Use Read tool to examine configuration files
- Verify CLI installation:
webflow --version - Check authentication:
webflow auth login(if needed) - Use CLI diagnostic flags:
--verbose,--debug-bundler,--help - DO NOT use Webflow MCP tools for CLI workflows
- All CLI commands require proper descriptions (not context parameters)
Package Manager Detection:
- Check for lock files:
package-lock.json(npm),pnpm-lock.yaml(pnpm),yarn.lock(yarn) - If no lock file found, ask user which package manager to use (npm/pnpm/yarn)
- Use detected package manager for all install/build commands
Instructions
Phase 1: Issue Identification
- Ask user to describe issue: What command failed or what error occurred
- Determine error category:
- CLI not installed or wrong version
- Authentication failed
- Build/bundle failed
- Command not recognized
- Capture error message: Get exact error output
Phase 2: Run Diagnostics
- Check CLI installation: Run
webflow --version - Check authentication: Run
webflow auth loginif needed - Run command with --verbose: Execute failed command with
--verboseflag for detailed output - Use --debug-bundler (if bundle issue): Run with
--debug-bundlerflag to see bundler config - Check --help: Run
webflow <command> --helpto verify command syntax
Phase 3: Analyze & Fix
- Identify root cause: Parse error messages and diagnostic output
- Present fix: Show specific solution based on CLI error
- Apply fix: Execute fix commands
- Verify: Re-run original command to confirm resolution
Examples
Example 1: CLI Not Installed
User prompt:
Getting "webflow: command not found"
Diagnostics:
🔍 Checking CLI Installation
Executing: webflow --version
Error: bash: webflow: command not found
❌ Webflow CLI not installed
Fix:
📋 Fix: Install Webflow CLI
Executing: npm install -g @webflow/cli
✓ CLI installed
Verifying...
Executing: webflow --version
Output: @webflow/cli/1.5.2
✅ Issue resolved
Example 2: Build Failed
User prompt:
Build is failing but I don't know why
Diagnostics:
🔍 Running Build with Diagnostics
Executing: webflow library bundle --verbose
Output:
[verbose] Loading webflow.json
[verbose] Found library config
[verbose] Building components from ./src/**/*.webflow.tsx
[verbose] Running bundler
Error: Failed to resolve import './missing-file.ts'
❌ Build failed: Missing import file
Fix:
📋 Fix: Missing Import
Issue: Component imports './missing-file.ts' which doesn't exist
Solutions:
1. Create the missing file
2. Fix the import path
3. Remove the import if not needed
Check your component imports and ensure all files exist.
Example 3: Bundle Configuration Issue
User prompt:
Bundle is failing with webpack errors
Diagnostics:
🔍 Checking Bundle Configuration
Executing: webflow library bundle --debug-bundler
Output:
[debug-bundler] Final bundler configuration:
{
"entry": "./src/Component.tsx",
"output": {
"path": "/dist",
"filename": "bundle.js"
},
"resolve": {
"extensions": [".ts", ".tsx", ".js"]
}
}
Error: Module not found: Can't resolve 'styled-components'
❌ Bundle failed: Missing dependency
Fix:
📋 Fix: Install Missing Dependency
Executing: npm install styled-components
✓ Dependency installed
Retrying bundle...
Executing: webflow library bundle
✓ Bundle created successfully
✅ Issue resolved
Guidelines
CLI Diagnostic Commands
Version Check:
webflow --version
# or
webflow -V
Command Help:
webflow --help # General help
webflow library --help # Library commands help
webflow library bundle --help # Specific command help
Verbose Output:
# Add --verbose to any command for detailed debugging
webflow library bundle --verbose
webflow cloud deploy --verbose
webflow extension bundle --verbose
Debug Bundler:
# Show final bundler configuration
webflow library bundle --debug-bundler
webflow extension bundle --debug-bundler
Common Issues & Fixes
Issue: CLI Not Found
- Diagnostic:
webflow --versionfails - Fix:
npm install -g @webflow/cli - Verify:
webflow --versionshows version
Issue: Wrong CLI Version
- Diagnostic:
webflow --versionshows old version - Fix:
npm update -g @webflow/cli - Verify: Latest version installed
Issue: Command Not Recognized
- Diagnostic: "Unknown command" error
- Fix: Check command with
webflow --help - Verify: Use correct command syntax
Issue: Authentication Failed
- Diagnostic: "Not authenticated" error
- Fix:
webflow auth login - Verify: Authentication succeeds
Issue: Build Failed
- Diagnostic: Run with
--verboseflag - Fix: Fix errors shown in verbose output
- Verify: Build succeeds
Issue: Bundle Configuration Error
- Diagnostic: Run with
--debug-bundlerflag - Fix: Adjust bundler config in webflow.json
- Verify: Bundle succeeds
Issue: Missing Dependencies
- Diagnostic: "Module not found" errors
- Fix:
npm installor install specific package - Verify: Build/bundle succeeds
Issue: Corrupted node_modules
- Diagnostic: Unexplained build failures
- Fix:
rm -rf node_modules && npm install - Verify: Build succeeds
Error Handling
CLI Not Installed:
❌ Webflow CLI Not Found
Install:
npm install -g @webflow/cli
Verify:
webflow --version
Docs: https://developers.webflow.com/cli
Authentication Required:
❌ Authentication Failed
Fix:
webflow auth login
Follow browser prompts to authenticate
Build/Bundle Failed:
❌ Build Failed
Run with diagnostics:
webflow library bundle --verbose --debug-bundler
This shows:
- Detailed build steps
- Import resolution
- Bundler configuration
- Exact error location
Fix the errors shown in output
Unknown Error:
❌ Unknown Issue
Gather info:
1. What command are you running?
2. Run command with --verbose flag
3. Check command syntax with --help
4. Share full error output
This helps identify the specific problem
File Operations
Reading Config Files:
# View webflow.json
Read: webflow.json
# View package.json
Read: package.json
# View build output
Read: dist/
Discovering Files:
# Find config files
Glob: **/webflow.json
# Find components
Glob: src/**/*.webflow.tsx
# Find logs
Glob: **/*.log
Best Practices
Always Start With:
- Check CLI version:
webflow --version - Check command syntax:
webflow <command> --help - Run with verbose: Add
--verboseflag
For Build/Bundle Issues:
- Use
--verbosefor detailed output - Use
--debug-bundlerto see config - Check import paths
- Verify dependencies installed
For Authentication Issues:
- Run
webflow auth login - Follow browser prompts
- Verify workspace access
For Installation Issues:
- Check Node.js version:
node --version - Install CLI globally:
npm install -g @webflow/cli - Verify installation:
webflow --version
Quick Reference
Workflow: identify → diagnose → fix → verify
Diagnostic Flags:
--version/-V- Check CLI version--help/-h- Show command help--verbose- Detailed debugging output--debug-bundler- Show bundler config
Common Fixes:
- Not installed →
npm install -g @webflow/cli - Wrong version →
npm update -g @webflow/cli - Auth failed →
webflow auth login - Build failed → Check
--verboseoutput - Bundle error → Check
--debug-bundleroutput - Missing deps →
npm install
Documentation: https://developers.webflow.com/cli
Webflow Cloud
Initialize new projects from templates or an existing GitHub repository, deploy to Webflow Cloud, and manage existing apps (list, inspect, logs, deployments, environments, environment variables). Deploys support two modes: site-attached (deploy to an existing Webflow site) and project app (deploy as an independent app, no existing site required).
Namespaces: apps (canonical) vs cloud (deprecated alias)
webflow apps <command> is the canonical namespace for Webflow Cloud. webflow cloud <command> still works — its init / deploy forms are aliases of the same handler — but is deprecated in favor of apps.
| Canonical | Deprecated cloud alias | Notes |
|---|---|---|
webflow apps init | webflow cloud init | Same options + handler — except --import and its repo-intake flags, which attach to apps init only. |
webflow apps deploy | webflow cloud deploy | Same handler — except --json and --dry-run, which attach to apps deploy only. |
| — | webflow cloud create <name> | Deprecated ahead of removal; prefer apps init (or cloud init if staying on the legacy namespace). |
| — | webflow cloud list | Lists scaffold templates, not apps. Stays under cloud; there is no apps equivalent. Do not confuse with apps list, which lists workspace apps. |
webflow apps list / get / domains / link / update / delete / environments … / deployments … / logs … / env-vars … | — | No cloud equivalent. Canonical-only. |
Running a command through cloud init / cloud deploy prints a one-time deprecation notice on stderr pointing at the apps form (suppressed with --json).
Prefer the apps forms in all new work. This skill shows apps commands throughout; every apps init / apps deploy invocation can be run as cloud init / cloud deploy with identical flags, apart from --import (init) and --json/--dry-run (deploy).
Instructions
Step 0: Verify CLI is installed
webflow --version
If the command is not found, install it:
npm install -g @webflow/webflow-cli@latest
# or yarn global add @webflow/webflow-cli@latest
# or pnpm add -g @webflow/webflow-cli@latest
Then proceed to state detection.
Step 1: Detect project state
Run both checks before deciding which path to follow:
# Is this project already set up on Webflow Cloud?
cat webflow.json
# Is there a git remote?
git remote get-url origin 2>/dev/null
Quick reference (the CLI now writes cloud.app_id; older manifests may carry the legacy cloud.project_id, which is still read as a fallback):
cloud.app_id in webflow.json (or legacy cloud.project_id) | git remote | → Path |
|---|---|---|
| No | — | A — new project |
| Yes | No | B — existing project, no git |
| Yes | Yes | C — ideal state |
You are running without a TTY. The CLI's interactive prompts only fire when
process.stdin.isTTYis true. As an agent invoking the CLI through a subprocess, you do not have a TTY — every prompt is silently skipped, and any required value that wasn't passed as a flag triggers a hard error like--app-name cannot be empty.Rule for every command in this skill: pass all required flags explicitly. Never rely on prompts. Pass
--no-inputwhen the CLI accepts it to make this contract explicit. The required flag set per command:
Command Always pass apps init(site-attached)--no-input --app-name <3–39 chars> --framework <astro|nextjs|vite> --mount <path> --site-id <id>apps init --new(app)--no-input --app-name <3–39 chars> --framework <astro|nextjs|vite|static> --workspace-id <id>apps init --import(site-attached)--no-input --import <repo-url> --site-id <id> --mount <non-root path> --idempotency-key <key>apps init --import --new(project app)--no-input --import <repo-url> --new --idempotency-key <key>— no--mountapps deploy(site-attached)--no-input --mount <path> --environment <env> --site-id <id>plus--app-nameon first deployapps deploy(project app, first deploy)--no-input --mount <path> --environment <env> --workspace-id <id> --app-name <name>
--site-id,--app-id,--framework, and--workspace-idonapps deploylet agents override what's inwebflow.jsonat deploy time.Multi-workspace tokens used to be an agent-fatal hang because workspace selection had no non-TTY path. Now pass
--workspace-idto skip the picker. The workspace ID is not surfaced anywhere in the Webflow dashboard UI — users can't look it up by hand. If the agent doesn't have it, ask the user to runwebflow apps deployinteractively once from inside their project. The preflight prompts for workspace selection and writescloud.workspace_idtowebflow.json; from that point the agent can read it from the manifest and pass--workspace-idon subsequent runs. Do not suggestapps init --newfor ID discovery — on an existing project it creates a discarded scratch directory. Exception: in Path A2 (empty directory) it is safe to tryapps init --newwithout--workspace-idto auto-resolve a single-workspace token — see Path A2.Site IDs are visible in the dashboard. When
--site-idis needed but unknown, do not ask the user for a rawsite_XXXXvalue — usewebflow sites listto fetch their sites and present a picker keyed by display name. Users can still check their dashboard to fetch it.Read/manage commands don't need
--workspace-id. Theapps list/get/domains/environments/deployments/logs/env-varscommands derive the workspace server-side from the OAuth token — they have no--workspace-idflag and never prompt for a workspace. See Managing apps.
Path A: No app_id — new project
The project has not been deployed yet. Before doing anything else, ask the user two questions:
- "Do you already have source code for this project (an existing Next.js or Astro codebase), or are you starting from an empty directory and want a Webflow starter scaffold?"
- If they have code: "Is it already pushed to a GitHub repository, and do you want Webflow to build from that repo (rather than from your local files)?"
Those answers choose the branch — and the three are meaningfully different:
| User has... | Branch | Init step |
|---|---|---|
| Existing code, deploying from local files | Path A1 | Skip apps init. It would create a ./<app-name>/ subfolder with a hello-world scaffold inside their repo, which they don't want. |
| Empty directory or wants a Webflow starter | Path A2 | Run apps init to scaffold from Webflow-Examples/hello-world-*. |
| Existing code already on GitHub, wants Webflow to build from the repository | Path A3 | Run apps init --import <repo-url> — creates a GitHub-connected app bound to the repo. apps-only; there is no cloud init --import. |
The A1 vs A3 choice is not cosmetic — it decides what the app can do later. A GitHub-connected app (A3) can use apps deployments trigger / redeploy, and is the only kind eligible for dashboard push-to-deploy. An app first created by a local apps deploy (A1) is not GitHub-connected, so trigger / redeploy refuse it. If the user's code is already on GitHub and they say anything about CI, automatic deploys, rollbacks, or "deploy when I push", route to A3, not A1.
Recoverable either way: an A1 app can be pointed at a repo afterwards with apps update --github-source <repo-url> (see apps update) — but choosing A3 up front avoids the extra step.
After the branch decision, also ask site-attached vs app (only relevant before the first deploy):
| User says... | Mode | Outcome |
|---|---|---|
"deploy to my Webflow site <name>", "site-attached", references an existing site | Site-attached | App is bound to an existing Webflow site; site URL hosts the app at the chosen mount path. Requires --site-id. |
| "project app", "just an app", "no site", or no existing site mentioned | Project app | First deploy provisions a brand-new Webflow site (<app-name>-<hash>.webflow.io). |
If the user is ambiguous on either question, ask. Do not default.
Path A1: existing codebase, deploying from local files
Check A3 first if the code is on GitHub. This path uploads and builds local files, producing an app that is not GitHub-connected —
apps deployments trigger/redeployand dashboard push-to-deploy will all refuse it. If the repo is on GitHub and the user wants Webflow to build from it, use Path A3 instead.
The user has working source. apps deploy handles everything — framework detection runs against package.json, and the preflight phase resolves identity from flags or prompts the user. No apps init needed, no webflow.json to hand-write up front.
Step 1: One-time auth (human-only). Tell the user to run this locally; agents cannot drive the browser flow:
webflow auth login
Step 2: Deploy. The exact form depends on what the agent knows.
A1-a — Site-attached, --site-id is known:
webflow apps deploy --no-input \
--site-id site_abc123 \
--app-name my-app \
--framework nextjs \
--mount /app \
--environment main \
--skip-mount-path-check \
--skip-update-check
--framework is optional if package.json has a detectable signal: the Cloudflare adapter for nextjs/astro (@opennextjs/cloudflare, @astrojs/cloudflare), or the vite package itself for vite. Pass it explicitly for monorepos or when auto-detection is unreliable.
If the agent doesn't know the user's --site-id, do not ask for a raw site_XXXX value — use webflow sites list to fetch the user's sites and present readable display names to pick from.
A1-b — Project app, --workspace-id is known:
webflow apps deploy --no-input \
--workspace-id ws_abc123 \
--app-name my-app \
--framework nextjs \
--mount / \
--environment main \
--skip-mount-path-check \
--skip-update-check
A1-c — Project app, workspace ID is unknown (the common gap):
The workspace ID is not visible anywhere in the Webflow dashboard UI. Users cannot look it up by hand — the only way to discover it is to run the CLI. So the path is:
Ask the user to run one interactive deploy locally. From inside their project directory:
webflow apps deploy
With no --no-input and no identity flags, the preflight prompts: "This project isn't initialized for Webflow Cloud. How would you like to deploy?" → user picks "Create a new app" → workspace picker → done. After this one human-driven deploy, cloud.workspace_id and siteId are written to webflow.json and WEBFLOW_SITE_ID to .env. The agent can then run all subsequent deploys with --site-id (the newly provisioned site).
Do not ask the user to run
apps init --newto "discover" their workspace ID. On an existing project that creates a discarded./<app-name>/scratch directory with a hello-world scaffold inside the user's repo. Use the interactiveapps deploypath above — it discovers the workspace ID and completes the first deploy in the same step.
Step 3: Set up git (if not already) — same as Path A2 step 3 below.
Path A2: empty directory, scaffold from scratch
-
Scaffold the project — pick the form that matches the user's intent:
# Project app (no site attachment). --workspace-id avoids the multi-workspace hang. webflow apps init --new --no-input \ --app-name my-app \ --framework astro \ --workspace-id ws_abc123# Site-attached (connect to an existing Webflow site). Requires --site-id. webflow apps init --no-input \ --app-name my-app \ --framework astro \ --mount /app \ --site-id site_abc123See
apps initfor all flags.Workspace ID discovery for project apps in Path A2 only: because Path A2 starts from an empty directory,
apps init --newcreates a fresh scaffold either way — there's nothing to pollute. So if the agent doesn't have--workspace-id, it's safe to tryapps init --newwithout it first:# Try this first if --workspace-id is unknown (Path A2 only — empty dir) webflow apps init --new --no-input \ --app-name my-app \ --framework astro- Single-workspace tokens: the CLI auto-selects the only workspace, writes
cloud.workspace_idtowebflow.json, and exits 0. Read it back from the manifest and pass it as--workspace-idtoapps deployin step 2. - Multi-workspace tokens: the workspace picker fires and the command hangs (no TTY). Set a 30-second timeout on the Bash call (or wrap the command in
timeout 30s ...) — a successful single-workspace init completes in 10–20 seconds (OAuth check +GET /v2/workspaces+ scaffold download from GitHub), so anything past 30s with no output is the picker hanging. Once the timeout fires, ask the user for the workspace ID directly and re-run with--workspace-id.
For site-attached in Path A2, there is no equivalent auto-discovery —
--site-idis always required up front. Use the site picker pattern below to help the user pick.Path A1 (existing codebase) does not get this trick. Running
apps init --newin an existing project creates a discarded scratch subdirectory. The Path A1 workspace-ID discovery path stays as documented in Path A1-c. - Single-workspace tokens: the CLI auto-selects the only workspace, writes
Path A3: existing GitHub repository, GitHub-connected app
The user's code is already on GitHub and they want Webflow to build from the repository rather than from local files. apps init --import <repo-url> creates the app bound to that repo and clones it locally.
apps-only.--importexists only underapps init— there is deliberately nocloud init --import. If the user is on thecloudnamespace for another reason, fall back to Path A1 and attach the repo later withapps update --github-source.
Step 0: Prerequisite — the Webflow GitHub App. It must be installed on the repository owner and connected to the workspace. The CLI cannot do this; it's dashboard/GitHub-side setup. If the import fails on permissions, this is the first thing to check.
Step 1: One-time auth (human-only). Same as A1 — agents cannot drive the browser flow:
webflow auth login
Step 2: Import. Exactly one of --site-id or --new is required — the CLI will not infer the target from anything inside the repo.
A3-a — Site-attached (--mount is required and must be non-root):
webflow apps init --import https://github.com/acme/site \
--site-id 6234abc --mount /app --dry-run
webflow apps init --import https://github.com/acme/site \
--site-id 6234abc --mount /app
A3-b — Project app (--mount is not allowed — a project app's initial environment uses /):
webflow apps init --import https://github.com/acme/site --new
A3-c — Non-interactive / CI. --idempotency-key is required here. Use a retry-stable key unique to this repo + target (e.g. $GITHUB_RUN_ID-$REPOSITORY-$SITE_ID) so a retry replays the original app instead of creating a second one:
webflow apps init --import https://github.com/acme/site --new --no-input \
--idempotency-key "$GITHUB_RUN_ID-acme-site" \
--branch main --json
Add --skip-clone to register the app without writing anything to the filesystem — the app and environment IDs are printed instead. Useful when the repo is already checked out, or when running somewhere you don't want a clone.
--branch picks which branch builds; it defaults to the repository's default branch.
Step 3: Enable push-to-deploy (dashboard, manual). The import connects the app to the repo, but pushing does not deploy until the dashboard wiring is done — see the full workflow example, steps 3 onward. Until then, build on demand:
webflow apps deployments trigger --json
Do not run apps deploy on an A3 app to "push an update". That uploads local files and is the A1 model; for a GitHub-connected app the equivalents are deployments trigger (build current HEAD) and deployments redeploy <depId> (re-run a past commit, i.e. roll back).
Picking a --site-id from a list
When --site-id is needed (Path A1 site-attached, Path A2 site-attached, or anywhere else) and the user hasn't given one, use webflow sites list --json to enumerate sites the token can see, then present a short list of readable names for the user to choose from. The site ID is visible in the Webflow dashboard URL config, but a numeric-ID prompt is bad UX; surface display names instead unless asked for IDs.
# Returns a JSON array of sites with id, displayName, lastPublished, etc.
webflow sites list --json
Workflow:
-
Run
webflow sites list --json. The CLI exits 0 with a JSON array. -
Parse the output. Show the user a short list keyed by
displayName(andlastPublishedif the user has many sites). Example:Which site should this project deploy to? 1. Acme Marketing (last published 2 days ago) 2. Acme Docs (last published 3 weeks ago) 3. Acme Internal (never published) -
Map the user's pick back to its
idfield. Pass that as--site-id.
If webflow sites list errors (auth missing / expired), surface the error and ask the user to run webflow auth login locally; do not try to drive it from the agent.
-
Deploy: pick the form matching the init form above. Pass
--site-id(or--workspace-idfor project-app first deploy) so the deploy can't misread the manifest if something is half-written.# Project-app first deploy — provisions the Cloud site/app/env webflow apps deploy \ --no-input \ --app-name my-app \ --workspace-id ws_abc123 \ --mount / \ --environment main \ --skip-mount-path-check \ --skip-update-check# Site-attached first deploy — uses the existing Webflow site webflow apps deploy \ --no-input \ --app-name my-app \ --site-id site_abc123 \ --mount /app \ --environment main \ --skip-mount-path-check \ --skip-update-checkThis creates the app on Webflow Cloud and sets
cloud.app_idinwebflow.json. Commit the updatedwebflow.json. -
Set up git (if not already):
git init && git add . && git commit -m "init" git remote add origin https://github.com/your-org/my-app.git git push -u origin main -
(Optional) Enable push-to-deploy via the Webflow dashboard. Pushing to GitHub alone does not trigger deploys — that wiring lives in the Webflow dashboard, not in the CLI or the repo. Tell the user:
- Open the Webflow dashboard → their Cloud app → Settings → Git
- Connect their GitHub account, then select the repository and branch
- Confirm — the dashboard runs one initial deploy automatically to verify the connection
- From that moment on, every push to the connected branch triggers a deploy
The CLI cannot perform any of these steps. If the user skips this, every deploy must be a manual
webflow apps deployinvocation (Path B–style) or a CI/CD pipeline.
If a deploy auth error occurs in step 2: run
webflow auth login, complete the browser flow, then retry.
Path B: app_id exists, no git remote — existing project, no git
The project is already on Webflow Cloud but has no git repo. Deploy directly and nudge toward git setup.
-
Deploy: read
webflow.jsonfirst. IfsiteIdis set, pass--site-idmatching it. If onlycloud.workspace_idis set, pass--workspace-idmatching it.webflow apps deploy \ --no-input \ --site-id site_abc123 \ --mount / \ --environment main \ --skip-mount-path-check \ --skip-update-check -
Nudge toward push-to-deploy: suggest the user initialize a git repo, push to GitHub, and then connect the repo in the Webflow dashboard (app → Settings → Git). The dashboard step is what activates push-to-deploy — the CLI can't do this. See Path A, steps 3–4.
If a deploy auth error occurs: run
webflow auth login, complete the browser flow, then retry step 1.
Path C: app_id exists + git remote — possibly ideal
The project is deployed and has a git remote, but the existence of a remote is not proof that push-to-deploy is wired up. That wiring is a dashboard-side connection that the CLI can't introspect. Confirm before suggesting anything.
Always ask the user: "Is this repo connected to your Webflow Cloud app in the dashboard (app → Settings → Git, with a branch selected)?" The answer changes the recommendation:
- Yes, connected — push-to-deploy is active. The only action needed is
git push. Do not suggest re-linking or re-deploying.- No, not connected —
git pushdoes nothing on the Webflow side. Either run a manual deploy now, or have the user connect the repo in the dashboard first to activate push-to-deploy for future commits.- Don't know — assume not connected and recommend the dashboard connection (one-time setup, then push-to-deploy is permanent).
-
If connected — just commit and push:
git add . git commit -m "your message" git pushWebflow Cloud picks up the push and deploys automatically. The first deploy after connection is run by the dashboard itself; subsequent pushes are picked up automatically.
-
If not connected — two routes:
- Activate push-to-deploy for future commits (recommended). Tell the user to open the Webflow dashboard → their Cloud app → Settings → Git, connect the repo, select the branch. The dashboard runs an initial deploy automatically to verify the connection. From then on, every
git pushto that branch deploys. - One-off manual deploy now, without enabling push-to-deploy. Pass
--site-idmatching thesiteIdinwebflow.json:
This deploys the current state but does not wire up push-to-deploy. The nextwebflow apps deploy \ --no-input \ --site-id site_abc123 \ --mount / \ --environment main \ --skip-mount-path-check \ --skip-update-checkgit pushwill still be a no-op on the Webflow side.
- Activate push-to-deploy for future commits (recommended). Tell the user to open the Webflow dashboard → their Cloud app → Settings → Git, connect the repo, select the branch. The dashboard runs an initial deploy automatically to verify the connection. From then on, every
If a deploy auth error occurs: run
webflow auth login, complete the browser flow, then retry.
Tool usage
- Use the Bash tool for all
webflow apps/webflow cloudcommands - Use the Read tool to examine
webflow.json,package.json— never modify these directly - Use the Glob tool to discover project files
- Do not use Webflow MCP tools for CLI workflows
Authentication
# Interactive — local-only, opens a browser. NOT for agents or CI.
webflow auth login
webflow auth loginperforms an OAuth flow in the user's browser and then writes the token to.env. It refuses to run with--no-input(exits withNo-input mode enabled. Aborting OAuth authentication). Agents cannot drive this command. Ifwebflow auth loginis needed (missing or expired token), ask the user to run it locally once and report back when it's done.
The CLI writes the same token env var for both modes. There is no per-mode split.
webflow auth login writes to .env:
| Variable | Always written? | Description |
|---|---|---|
WEBFLOW_API_TOKEN | Yes (both modes) | OAuth access token. The canonical token env var. Set by webflow auth login. |
WEBFLOW_SITE_ID | Site-attached only (or after first project-app deploy) | Site ID. Written by apps init for site-attached projects, or by apps deploy for project apps after the first deploy provisions a site. |
After the first project-app deploy, the CLI provisions a site on the backend and writes WEBFLOW_SITE_ID to .env. From that point on, the project behaves like a site-attached project — but the token env var is still WEBFLOW_API_TOKEN.
Deprecated legacy: WEBFLOW_SITE_API_TOKEN (and WEBFLOW_WORKSPACE_API_TOKEN) are read-only legacy fallbacks. The CLI never writes them, but if it finds one of them set in the environment when WEBFLOW_API_TOKEN is not set, it uses the legacy value and prints a deprecation warning on every run. Do not put WEBFLOW_SITE_API_TOKEN in .env or CI secrets for new projects — use WEBFLOW_API_TOKEN.
Other env vars (any mode):
| Variable | Description |
|---|---|
DO_NOT_TRACK | Set to 1 to opt out of telemetry. |
WEBFLOW_SKIP_UPDATE_CHECKS | Set to true to skip the @webflow package update check. |
WEBFLOW_SITE_IDenv var is read-only. Used at runtime when no flag or manifest value is set, but never written back towebflow.json. SettingWEBFLOW_SITE_ID=Xin.envwill not update the manifest — onlyapps init,apps deploy, and the manifest itself drive that.
GitHub Secrets: use
WEBFLOW_API_TOKENfor the token in every mode. Also setWEBFLOW_SITE_IDfor site-attached projects and project apps that have already had their first deploy. Never commit.envfiles. If existing CI usesWEBFLOW_SITE_API_TOKEN, rename it — the deploy will still succeed but every run prints a deprecation warning until you switch.
Configuration — webflow.json
{
"siteId": "site_abc123",
"cloud": {
"app_id": "app_xyz",
"environment_id": "env_xyz",
"workspace_id": "ws_xyz",
"framework": "nextjs",
"skipMountPathCheck": false
}
}
All cloud.* keys are snake_case (app_id, not appId).
| Key | When set | Notes |
|---|---|---|
siteId | Site-attached: at apps init. Project app: after first deploy (CLI provisions a site). | Absent on project apps that have not been deployed yet. |
cloud.framework | At apps init. | Required for deploy resolution — see below. |
cloud.app_id | After first deploy. | Canonical. Auto-written. Replaces the legacy cloud.project_id. |
cloud.project_id | Legacy only. | Deprecated. Read as a fallback when cloud.app_id is absent (manifests created before the Project → App rename). New deploys never write it; will be removed in a future major release. |
cloud.environment_id | After first project-app deploy. | Auto-written by createCloudApp. |
cloud.workspace_id | At project-app apps init (--new). | Used by the first deploy to provision the site. |
cloud.skipMountPathCheck | User-managed. | Equivalent to --skip-mount-path-check. |
The CLI also writes cloud.deployment_type ("ssr" | "ssg" | "spa"), cloud.entrypoint_path, and cloud.framework_version into the bundled webflow.json at build time (these power the cosmic deployer's wrangler config and telemetry). They're build-time outputs — do not strip them from the source webflow.json if you find them there; missing values silently break Next.js server-side deploys.
ID resolution and env vars
A shared resolver resolves siteId, appId, environmentId, and workspaceId in a strict priority order:
explicit flag / positional arg > env var > webflow.json manifest > interactive prompt > error
| Resource | Flag / arg | Env var (read-only) | webflow.json |
|---|---|---|---|
| App ID | --app-id / [appId] arg | WEBFLOW_APP_ID | cloud.app_id (falls back to legacy cloud.project_id) |
| Environment ID | --environment-id / [envId] arg | WEBFLOW_APP_ENVIRONMENT_ID | cloud.environment_id |
| Site ID | --site-id | WEBFLOW_SITE_ID | siteId |
| Workspace ID | --workspace-id | WEBFLOW_WORKSPACE_ID | cloud.workspace_id |
Env vars are read-only — they are never persisted back to the manifest. When a value comes from the manifest, the CLI logs a Using <resource> from webflow.json line (suppressed with --json). When nothing resolves and the command can't prompt (--no-input, CI=true, or no TTY), it exits with a machine-readable missingFlag on the error — see the --no-input contract in Managing apps.
cloud.framework resolution at deploy time:
webflow.jsonexists withcloud.framework— used as-is. Invalid value exits with code 1.webflow.jsonexists butcloud.frameworkis absent — falls back to detecting frompackage.json.- No
webflow.json— auto-detected frompackage.json. CLI writes a newwebflow.jsonon success.
Projects created via apps init always land in case 1.
Commands
webflow cloud list
webflow cloud list
Lists available scaffold templates (used by init). Check this before apps init --framework to confirm valid scaffold IDs. This is distinct from apps list (which lists your deployed apps) and lives only under the cloud namespace. Deprecated ahead of removal — it still works but prints a warning; prefer apps init --framework <bad-value> or --help to see valid scaffold IDs.
webflow apps init
Bootstrap a new app locally. Two modes: site-attached and app. (webflow cloud init is a deprecated alias with identical flags.)
Site-attached (connects to an existing Webflow site):
# Agent / non-TTY — always pass every flag
webflow apps init \
--no-input \
--app-name my-app \
--framework nextjs \
--mount /app \
--site-id site_abc123
# Human at a real terminal — interactive prompts will fill in any missing flag
webflow apps init
Flags:
| Flag | Short | Description |
|---|---|---|
--app-name <name> | -n | App name. Must be 3–39 characters — the CLI rejects anything outside this range at init and at the first project-app deploy. |
--project-name <name> | — | Deprecated alias of --app-name. Still accepted. |
--framework <framework> | -f | Must match a scaffold ID from cloud list. Currently: nextjs, astro, vite, static (static is standalone-only — see Frameworks). |
--mount <path> | -m | Mount path (default / for new domain, /app for existing site). Substituted into config files at scaffold time. Not stored in webflow.json. |
--site-id <id> | -s | Required in non-interactive site-attached mode. Mutually exclusive with --workspace-id. |
--workspace-id <id> | -w | Skips the workspace picker for --new (app mode). Mutually exclusive with --site-id. |
--new | — | Project-app mode (no site). |
--no-input | — | CI mode. Requires --app-name and --framework. Without --new, defaults to app behavior. |
Credential resolution for --no-input site-attached: --site-id flag → siteId in webflow.json → WEBFLOW_SITE_ID env var → error.
After scaffolding a site-attached project, the CLI automatically runs a DevLink sync.
Project app (no site attachment):
# Agent / non-TTY — always pass --workspace-id to skip the workspace picker
webflow apps init --new --no-input \
--app-name my-app \
--framework nextjs \
--workspace-id ws_abc123
# Human at a real terminal — prompts for workspace if not passed
webflow apps init --new
If the token sees multiple workspaces and the agent doesn't have a workspace ID, ask the user to run
webflow apps deployinteractively from inside their project — the preflight prompt picks a workspace and writescloud.workspace_idtowebflow.jsonfor subsequent agent-driven runs. The workspace ID is not exposed in the Webflow dashboard UI, so the interactive CLI run is the only practical way to discover it.
| Site-attached | Project app (--new) | |
|---|---|---|
| OAuth / site selection | Required at init | Skipped (workspace selection instead) |
WEBFLOW_SITE_ID in .env | Written at init | Written after first deploy only |
WEBFLOW_API_TOKEN in .env | Written | Written |
cloud.workspace_id in webflow.json | Not set | Set at init (used by first deploy) |
| Scaffold | astro, nextjs, vite | astro, nextjs, vite, static |
| Initial mount path | Configurable (default /app) | / |
| DevLink sync | Runs after init | Skipped |
Workspace selection (project-app mode only): if --workspace-id is not passed, the CLI calls GET /v2/workspaces to enumerate workspaces the token has access to. Single workspace is auto-selected; multiple workspaces trigger an interactive picker. With --workspace-id the API roundtrip is skipped — the CLI trusts the flag and surfaces a 404 later via createCloudApp if it's invalid. The chosen ID is persisted as cloud.workspace_id in webflow.json.
Agent caveat: if the user's token sees more than one workspace and the agent can't pass --workspace-id, the picker fires and hangs in non-TTY contexts. The workspace ID is not visible in the Webflow dashboard UI, so the recovery is: ask the user to run webflow apps deploy interactively once from inside their project. The preflight prompt picks the workspace, completes a first deploy, and writes cloud.workspace_id (plus siteId, app_id, environment_id) to webflow.json. The agent can then read the workspace ID from the manifest and pass --workspace-id (or --site-id, now that the site exists) on subsequent runs. To target a different workspace later, delete cloud.workspace_id and have the user repeat the interactive deploy.
webflow apps init --import <repo-url> (apps only)
Creates a Cloud app from an existing GitHub repository instead of a starter template, and clones it locally. This is the intake path for a codebase that already exists on GitHub — no scaffold is generated and no framework is chosen.
This flag attaches to apps init only. There is deliberately no cloud init --import: the repo-intake path creates real apps, so it stays on the canonical namespace rather than the deprecated alias.
Prerequisite: the Webflow GitHub App must be installed on the repository and connected to your workspace. Without it the create fails — the CLI cannot install it for you, and this is dashboard-side setup.
| Flag | Notes |
|---|---|
--import <repo-url> | https://github.com/<owner>/<repo>. Must be non-empty. |
--site-id <siteId> | Attach to an existing site. Mutually exclusive with --new; exactly one is required. |
--new | Create a project app instead of attaching to a site. |
--mount <path> | Required (and non-root) with --site-id. Not allowed with --new — a project app's initial environment uses /. |
--branch <branch> | Branch to build. Defaults to the repository's default branch. |
--idempotency-key <key> | Required for non-interactive runs (CI, --no-input). Use a retry-stable key unique to this repo + target, e.g. $GITHUB_RUN_ID-$REPOSITORY-$SITE_ID, so a retry replays the original app instead of creating a second one. |
--skip-clone | Create the app without cloning locally. Nothing is written to the filesystem; the app and environment IDs are printed instead. |
--json | Import path only — the scaffold path has no single response object to serialize. |
--dry-run | Shared with the scaffold path: validate and preview without side effects. |
A siteId found inside the repository is never used to pick the target — you must say --site-id or --new explicitly.
The import-only flags (--branch, --idempotency-key, --skip-clone, --json) are rejected, not ignored, when --import is absent; likewise --framework / --workspace-id / --project-name are rejected with --import (a repo brings its own code, and the workspace is derived from the token). Each refusal names the offending flag machine-readably via missingFlag, so an agent can correct the call without parsing prose.
# Attach an existing repo to an existing site at /app
webflow apps init --import https://github.com/acme/site \
--site-id 6234abc --mount /app --dry-run
webflow apps init --import https://github.com/acme/site \
--site-id 6234abc --mount /app
# Project app from a repo, CI-safe (note: --idempotency-key required, no --mount)
webflow apps init --import https://github.com/acme/site --new --no-input \
--idempotency-key "$GITHUB_RUN_ID-acme-site" \
--branch main --json
# Register the app without touching the local filesystem
webflow apps init --import https://github.com/acme/site --new --skip-clone --json
webflow cloud create (deprecated)
webflow cloud create <name> still works but emits a deprecation warning and will be removed in a future major release. It's hardcoded to /app mount in site-attached mode and offers a strict subset of apps init. Always prefer apps init (or apps init --new for app mode).
webflow apps deploy
webflow cloud deploy is a deprecated alias of apps deploy with identical flags and handler.
Preflight phase: identity resolution. Before any backend call, apps deploy runs a preflight step that resolves whether this is a site-attached deploy or a project-app first deploy. Resolution order (first match wins):
| # | Source | Result |
|---|---|---|
| 1 | --site-id <id> flag | Site-attached, overrides env and manifest |
| 2 | --workspace-id <id> flag | Project-app first deploy, overrides env and manifest. Mutually exclusive with --site-id |
| 3 | WEBFLOW_SITE_ID env var | Site-attached (read-only; never persisted back to webflow.json) |
| 4 | manifest.siteId (from webflow.json) | Site-attached |
| 5 | WEBFLOW_WORKSPACE_ID env var | Project-app first deploy (read-only; never persisted) |
| 6 | manifest.cloud.workspace_id | Project-app first deploy |
| 7 | No match + --no-input | Hard error listing required flags |
| 8 | No match, interactive | Picker: create a new app / attach to existing site / cancel |
Env vars beat the manifest, and site beats workspace. Both halves matter: an exported
WEBFLOW_SITE_IDoverridesmanifest.siteId, and any resolved site short-circuits before workspace resolution is even attempted — so a staleWEBFLOW_SITE_IDin the environment silently wins over a manifest configured for a project-app deploy. Unset it, or pass--workspace-idexplicitly, when that isn't what you want.
This preflight phase exists to prevent the project-app deploy path from running and provisioning a Cloud app before identity is locked in — earlier versions could orphan a new Webflow site if any later step failed.
Pass
--site-idor--workspace-idexplicitly whenever you can. It defends against half-written manifests and removes the dependence on whatever stateapps inithappened to leave behind. If the user wants site-attached, pass--site-id. For project-app first deploy, pass--workspace-id.
Project-app first deploy (triggered by --workspace-id flag or manifest.cloud.workspace_id) calls POST /cosmic/workspaces/:workspace_id/cloudApps to atomically create a site, app, and environment. On success it writes siteId, cloud.app_id, and cloud.environment_id into webflow.json, writes WEBFLOW_SITE_ID into .env, and forces --skip-mount-path-check for that one deploy. Subsequent deploys behave like normal site-attached deploys.
If --app-name is omitted on the first project-app deploy, the CLI uses the cwd folder name (when 3–39 chars) and falls back to "Cloud App". Provide --app-name explicitly in CI to avoid surprises.
Uninitialized projects (no siteId, no workspace_id, no flag): the CLI prompts the user to create a new project app, attach to an existing site, or cancel. With --no-input it hard-errors listing the required flags. Agents running with --no-input must always supply --site-id or --workspace-id on the first deploy of an uninitialized project.
There are two deployment approaches. GitHub-linked deployment is recommended — it requires no CI configuration. After a one-time dashboard setup (which the CLI can't do), every push to the connected branch triggers a deploy.
Option 1 (recommended): GitHub-linked deployment
Once a one-time dashboard setup is done, every push to the connected branch triggers a deploy — no CLI commands, no workflow file. The setup is dashboard-only — the CLI cannot reach this state on its own. Pushing a repo to GitHub does not, by itself, enable push-to-deploy.
- Push the project to GitHub (the user needs at least one commit pushed)
- Tell the user to open the Webflow dashboard → their Cloud app → Settings → Git and connect their GitHub account if not already connected
- Select the repository, then the branch to deploy from (e.g.
main) - Confirm — the dashboard runs an initial deploy automatically to verify the connection
- From that point on:
git pushto the connected branch = deploy
Steps 2–4 cannot be scripted. If the user wants push-to-deploy, they have to click through the dashboard once. After that, the agent's job for this project is essentially done — future deploys happen on push.
When suggesting a deployment setup to a user, always lead with this option. Only suggest GitHub Actions if the user needs custom pre/post steps, secrets injection, or multi-environment logic that the native GitHub integration does not cover.
Option 2: GitHub Actions (manual CI/CD)
Use when you need custom build steps, environment-specific secrets, or deploy gates not supported by the native GitHub integration. See the GitHub Actions example in the Examples section.
Option 3: Local / manual deploy
For development and one-off deploys:
webflow apps deploy \
--no-input \
--mount / \
--environment main \
--skip-mount-path-check \
--skip-update-check
All apps deploy flags:
| Flag | Short | Description |
|---|---|---|
--no-input | — | CI mode. Disables most prompts but not the project-select prompt — see callout below. |
--mount <path> | -m | Mount path. Always pass it with --no-input — it is not enforced. Omitting it does not error; it silently deploys at root (/). Not auto-read from webflow.json. See the warning below. |
--environment <env> | -e | Environment name. Creates if it does not exist. Must be passed with --mount. |
--app-name <name> | -n | Required on first deploy with --no-input when no cloud.app_id in webflow.json. Must be 3–39 characters for project-app first deploy. |
--project-name <name> | — | Deprecated alias of --app-name. Still accepted. |
--site-id <id> | -s | Webflow site ID for site-attached deploys. Overrides siteId in webflow.json. Mutually exclusive with --workspace-id. Use this to recover from a half-written manifest without editing JSON. |
--workspace-id <id> | -w | Workspace ID for project-app first deploys. Overrides cloud.workspace_id in webflow.json. Mutually exclusive with --site-id. |
--app-id <id> | -a | Cloud app ID. Skips the app picker. Overrides cloud.app_id in webflow.json. |
--project-id <id> | — | Deprecated alias of --app-id. Still accepted. |
--framework <fw> | -f | Override framework detection. Must be nextjs, astro, vite, or static. Writes the value back into webflow.json. Use when auto-detection from package.json is unreliable (monorepos, missing dependencies, etc.). |
--directory <path> | -d | App directory (default: cwd). Use for monorepos. |
--description <text> | — | App description for the first deploy. |
--skip-mount-path-check | — | Skip domain manifest validation. Required in CI. Can also be set in webflow.json as cloud.skipMountPathCheck: true. |
--auto-publish | — | Publish the Webflow site to sync mount path routing. Does not affect app deployment. |
--skip-update-check | — | Skip @webflow package update check. |
--dry-run | — | apps deploy only — not on the cloud deploy alias. Resolves everything from flags/env vars/webflow.json, makes no network calls, and reports which of create / select / deploy the real run would take. |
--json | — | apps deploy only — not on the cloud deploy alias. Emits one document instead of build/upload progress text: {appId, environmentId, deploymentId, deployUrl} on success (deployUrl is null on older backends), an error document on failure, or the dry-run plan when combined with --dry-run. |
# Preview what a deploy would do, no side effects
webflow apps deploy --no-input --mount /app --environment main --site-id site_abc123 --dry-run --json
# Deploy and parse the result instead of scraping progress output
webflow apps deploy --no-input --mount /app --environment main --site-id site_abc123 --json
Agents: pass
--mountAND--environmenttogether, every time. The deploy prompts (select existing app, name a new app, pick an environment) are gated on whether--mountand--environmentare both set — not on--no-input. Pass--no-inputwithout both and the app-select prompt still fires and hangs in non-TTY contexts. The minimum agent-safe deploy flag set is--no-input --mount <path> --environment <env> --site-id <id>(or--workspace-id <id>for project-app first deploy), plus--app-namewhenevercloud.app_idis absent fromwebflow.json.
⚠️ Omitting
--mountunder--no-inputdeploys to root, silently. This is a wrong-deploy risk, not a hard failure — nothing errors and nothing warns. The mount prompt supplies a/appdefault but no validator, and the no-input path only returns a default that passes validation; with no validator it returns nothing at all, which normalizes to/. Root is a valid mount, so the deploy proceeds there. Never rely on the/appdefault in a non-interactive run — pass--mountexplicitly every time. This is also why "assume the default mount" is called out as a cause ofENVIRONMENT_MOUNT_MISMATCHfurther down: the failure surfaces later, at a different layer, far from the flag that caused it.
Managing apps
Commands for inspecting and operating existing Cloud apps. They complement init / deploy:
- Workspace is server-side. Every read command derives the workspace from the OAuth token — there is no
--workspace-idflag on any of them, and they never prompt for a workspace. - ID resolution.
appIdandenvIdresolve via the shared resolver: explicit arg/flag → env var (WEBFLOW_APP_ID/WEBFLOW_APP_ENVIRONMENT_ID) →webflow.json(cloud.app_id/cloud.environment_id, legacycloud.project_idfallback) → interactive TTY prompt. Running inside the app directory (sowebflow.jsonresolves the IDs) is the common case, not a requirement. - Auto-select vs.
--no-inputcontract. When the ID isn't given, the picker auto-selects a workspace's single app / an app's single environment, so single-app/single-env setups work non-interactively (including CI). When several exist and the command can't prompt (--no-input,CI=true, no TTY, or--json), it exits non-zero with a machine-readablemissingFlagon the error so an agent can recover by re-running with the flag. The human-readable form is e.g.Missing required appId. Pass --app-id, set WEBFLOW_APP_ID, or add it to webflow.json.
Webflow CMS Image Compression
Compress and reformat image fields on a Webflow CMS item to .webp or .avif.
This skill does not support images embedded inside Rich Text fields at this time. Tell the user that limitation before starting and only process CMS fields whose schema type is Image or MultiImage.
Important Note
ALWAYS use Webflow MCP tools for Webflow operations:
- Use Webflow MCP's
data_sites_toolwith actionlist_sitesto discover the site ID when needed - Use Webflow MCP's
data_cms_toolwith actionget_collection_detailsto fetch collection schemas - Use Webflow MCP's
data_cms_toolwith actionlist_collection_itemsto fetch the target CMS item - Use Webflow MCP's
data_assets_toolwith actioncreate_assetto create presigned asset uploads - Use Webflow MCP's
data_cms_toolwith actionupdate_collection_itemsto update CMS image fields - Use Webflow MCP's
data_cms_toolwith actionpublish_collection_itemsto publish the updated item - All Webflow MCP calls must include the required
contextparameter (15-25 words, third-person perspective) - Mutating operations require explicit user confirmation. Ask the user to type
confirmbefore uploading assets, updating CMS fields, or publishing. - Rich Text embedded images are not supported. Do not parse or rewrite Rich Text HTML for image compression.
Instructions
Phase 1: Gather Parameters
Collect all required inputs in one shot when possible:
- Collection ID: Ask "What is the Collection ID?"
- Item ID: Ask "What is the Item ID?"
- Image fields: Ask "Which image fields should be compressed?"
- "All image fields" - compress every Image or MultiImage field found on the item
- "Specify field names" - user will name specific field slugs
- Target format: Ask "Target format?"
- "webp (Recommended)" - best browser support, good compression
- "avif" - better compression, slightly less support
- Quality (1-100): Ask "Quality (1-100)?"
- "85 - Recommended (webp)" - visually lossless for most photos
- "75 - Recommended (avif)" - avif is efficient at lower quality
- "Custom" - user types their own value
If the user chose "Specify field names", follow up for comma-separated field slugs. If the user chose "Custom" quality, follow up for the numeric value. Validate custom quality is an integer from 1 to 100.
Phase 2: Discover Image Fields
- Call
data_cms_toolwith actionget_collection_detailsand the collection ID. - Filter fields where
type === "Image"ortype === "MultiImage". - Select target fields:
- If the user chose "All image fields", use every Image and MultiImage field found.
- If the user named specific fields, validate each slug exists and is an Image or MultiImage field.
- Warn and skip requested fields that do not exist or are not image fields.
- Stop and report if no valid image fields remain.
Phase 3: Fetch the CMS Item
Call data_cms_tool with action list_collection_items to fetch the target item. Use the item ID to identify the item directly when the tool supports it; otherwise filter or search the returned items.
Extract current fieldData for each target field:
- For Image fields, capture
urlandfileId. - For MultiImage fields, capture each array entry's
urlandfileId. - Skip null, empty, or malformed image values.
- Skip images already in the target format unless the user explicitly asks to recompress them.
Phase 4: Preview and Confirm
Before downloading or uploading anything, show a preview:
Compression Preview
Collection: [collection ID]
Item: [item ID]
Target format: webp
Quality: 85
Fields to process:
- main-image: hero.jpg -> hero.webp
- gallery: 3 images -> webp
Skipped:
- thumbnail: already webp
Type `confirm` to download, convert, upload, update the CMS item, and publish.
Proceed only after the user types confirm.
Phase 5: Convert Each Image
For each image:
- Download to
/tmp/:
curl -sL "{url}" -o "/tmp/cms_img_{fieldSlug}_{index}.orig"
- Ensure Pillow is available:
python3 -c "from PIL import Image" 2>/dev/null || pip3 install Pillow -q
For avif, also try:
pip3 install pillow-avif-plugin -q
- Convert with the user's quality setting:
python3 - <<'EOF'
from PIL import Image
import os
try:
import pillow_avif
except ImportError:
pass
source = "/tmp/cms_img_{fieldSlug}_{index}.orig"
target = "/tmp/cms_img_{fieldSlug}_{index}.{ext}"
img = Image.open(source)
img.save(target, "{FORMAT}", quality={quality})
orig = os.path.getsize(source)
new = os.path.getsize(target)
print(f"Original: {orig:,} bytes -> {FORMAT}: {new:,} bytes ({(1 - new / orig) * 100:.1f}% smaller)")
EOF
If avif conversion fails, report the error and ask whether to fall back to webp or abort.
- Compute the MD5 hash of the converted file:
md5 -q "/tmp/cms_img_{fieldSlug}_{index}.{ext}"
On Linux:
md5sum "/tmp/cms_img_{fieldSlug}_{index}.{ext}" | cut -d' ' -f1
Phase 6: Upload to Webflow Assets
For each converted file:
- Determine
site_id. If it is not known from the collection or prior context, calldata_sites_toolwith actionlist_sites. If multiple sites are available, ask the user which one owns the collection. - Call
data_assets_toolwith actioncreate_asset:site_id: the target site IDfile_name: original base name plus the new extension, such ashero.webpfile_hash: the MD5 hex string
- Capture the response values:
uploadUrl: S3 endpointuploadDetails: form fieldsid: new asset IDhostedUrl: CDN URL to use as the CMS source reference
- POST to S3 as multipart/form-data. Map
uploadDetailskeys to curl fields:xAmzAlgorithm->X-Amz-AlgorithmxAmzCredential->X-Amz-CredentialxAmzDate->X-Amz-DatexAmzSignature->X-Amz-SignaturesuccessActionStatus->success_action_statuscontentType->Content-TypecacheControl->Cache-Control- Pass
acl,bucket,key, andpolicyas-is - Append the file last:
-F "file=@/tmp/cms_img_{fieldSlug}_{index}.{ext};type=image/{ext}"
- Expect HTTP 201. If the response is not 201, log the response body and report the upload error. Presigned URLs have a one-hour TTL; restart from asset creation if the URL expires.
Phase 7: Update and Publish
Call data_cms_tool with action update_collection_items using only fields that were successfully converted and uploaded.
For Image fields, set:
{
"fieldSlug": {
"fileId": "{newAssetId}",
"url": "{hostedUrl}"
}
}
For MultiImage fields, reconstruct the full image array and replace only successfully processed entries with the new { "fileId", "url" } values. Preserve skipped entries exactly as they were.
After a successful update, call data_cms_tool with action publish_collection_items for the item ID. The CMS may re-process the image and generate its own CDN URL; the hostedUrl from the asset upload is the source reference.
Phase 8: Report Results
Print a concise summary table:
| Field | Original | Converted | Savings |
|---|---|---|---|
| main-image | 118,044 B (JPEG) | 113,260 B (webp) | 4.1% |
Also report:
- Fields skipped because they were null, empty, malformed, already in the target format, or not image fields
- Conversion failures and whether the user chose fallback or abort
- Upload failures, including response bodies when available
- New asset IDs for uploads that succeeded when a later CMS update or publish failed
Examples
User prompt:
Compress the main image on this CMS item to webp.
Response flow:
I need the collection ID, item ID, image fields, target format, and quality before compressing the CMS image.
Compression Preview
Collection: 65f...
Item: 66a...
Target format: webp
Quality: 85
Fields to process:
- main-image: blog-hero.jpg -> blog-hero.webp
Type `confirm` to download, convert, upload, update the CMS item, and publish.
Final report:
CMS Image Compression Complete
| Field | Original | Converted | Savings |
|-------|----------|-----------|---------|
| main-image | 842,911 B (JPEG) | 214,330 B (webp) | 74.6% |
Updated and published item 66a...
Guidelines
- Handle one CMS item at a time. For bulk operations across many items, rerun the skill for each item or extend the workflow with an explicit loop.
- Do not delete the original JPEG or PNG from Webflow's asset store; only update the CMS field reference.
- Preserve filenames by stripping the original extension and appending the target extension. Avoid double extensions such as
hero.jpg.webp. - Continue processing other selected fields after a single image conversion or upload failure unless the failed field is the only target.
- Never update or publish the CMS item if no image was successfully converted and uploaded.
- Keep a local in-memory rollback note with the original image field values and include it in the final report when an update succeeds.
🎓 Webflow University: Getting started with MCP
About this skill
This skill is a Webflow University resource that guides you through your first real Webflow MCP workflow. Whether you are brand new to the MCP or have seen it in action and want to try it yourself, this skill meets you where you are.
When invoked, run the full guided activity below. Do not summarize or skip steps. Be conversational, encouraging, and adaptive. Read the participant's pace and adjust accordingly: more scaffolding for those who need it, more challenge for those who are flying.
How to invoke this skill
If using Claude, type / in a new chat window and select WFU MCP Getting Started from the menu. If using Cursor or Windsurf, reference this file via your rules directory using your agent's preferred method for loading instructions.
Skill instructions
Tone and personality guidelines
- Warm, conversational, and encouraging throughout
- A little playful: this should feel fun, not like homework
- Proactive: do not wait for the participant to ask what to do next. Guide them forward
- Adaptive: read their responses. Short answers or confusion = more scaffolding. Long answers or fast progress = more challenge and encouragement to go further
- Use formatting generously: headers, bullets, bold text, and emojis to make the experience feel structured and engaging, not like a wall of text
- Celebrate small wins genuinely, not robotically
- If the participant indicates they have run this skill before or are returning for another session, acknowledge it lightly and vary the language: swap "first real Webflow MCP workflow" for "another real Webflow MCP workflow," open with something like "back for more, let's go," and lean toward suggesting a different activity than they may have tried last time. Keep everything else the same.
- Adapt activity suggestions naturally based on role: if they are a Developer, lean toward the activity log summary or class cleanup. If they are a Marketer, lean toward the SEO audit or CMS collection. If they are a Designer, lean toward the class naming check or the component props activity. Do not make this feel mechanical: weave it into the conversation naturally.
Activity flow
Step 1 — Welcome
Open with this message, formatted exactly as shown:
🎉 Welcome.
This is your hands-on introduction to the Webflow MCP: a Webflow University guided activity designed to take you from setup to your first real MCP workflow.
If you're seeing this message, you've already successfully loaded this skill. That's step one, and you nailed it.
Here's what we're going to do together:
- ✅ Make sure you're connected to Webflow
- 💾 Create a quick site backup
- 🎯 Pick something you want to try
- ✍️ Write a real MCP prompt, with my help
- 🚀 Run it and see what happens
This should take 15 to 30 minutes, depending on how deep you want to go. And yes, you are allowed to have fun with it.
Ready when you are: just say "let's go" and we will get started. 🚀
Wait for their affirmative response before continuing. Then open the next step:
👋 First, a couple of quick questions.
What's your name, and what's your role on your web team? (Designer, Marketer, Developer, or something else entirely?)
Also, if you know it: what is your site role in Webflow? (e.g. Designer, Editor, Marketer, Content Editor, or a custom role.)
💡 Why this matters: With MCP 2.0, Webflow's role and permissions system applies directly to AI actions. Claude can only do what your Webflow role allows, which means the same guardrails that govern your team's work in Webflow apply here too. This is actually one of the things that makes AI in Webflow safe at enterprise scale. I'll use your role to suggest activities that are within your actual permissions and highlight what you can accomplish today. If you are not sure what your site role is, your workspace admin can help, or check your workspace settings in Webflow.
Wait for their response. Use their name throughout the rest of the activity. Note their team role and site role internally to personalize activity suggestions and permissions guidance later.
Step 2 — Check Webflow connection
After they respond, attempt a lightweight Webflow MCP tool call (e.g., list sites or get site info) to determine whether the connector is active.
If connected:
✅ Webflow is already connected — nice work.
Looks like you've already set up the Webflow connector. One less thing to worry about.
Quick check: I can see you are authorized to [workspace name if available from tool call: surface it here if possible]. Make sure that is the workspace containing the test site you want to use today. If you are not sure or want to switch sites, just let me know and I can pull a list of your available sites.
⚠️ Important reminder: Please use a test site or a clone of your site for this activity, not your live production site. If something unexpected happens (it probably won't, but still), you want to be able to walk it back without stress. If you don't have a test site ready, I can help you think through your options.
Ready to move on? Tell me when you're set.
If not connected:
🔌 Let's get you connected to Webflow
No Webflow connection detected yet: no worries, it only takes a few minutes.
💡 Using Cursor? Follow the setup instructions at developers.webflow.com/mcp/installing/cursor. Using Windsurf? Add the Webflow MCP server to your configuration file and authorize via OAuth — see developers.webflow.com/mcp/reference/getting-started for details. Then come back and say "I'm connected" and we'll verify it together.
If you're using Claude, here's exactly what to do:
Step 1: In Claude, find the Customize menu (often in the left sidebar or within your profile). Choose Customize Claude.
Step 2: Go to Connectors and search for Webflow
Step 3: Click Connect and sign into your Webflow account when prompted
Step 4: Authorize access to the workspace or site you want to work with today
Step 5: Come back here and say "I'm connected" and I'll verify it for you
⚠️ Important: When you choose which site to authorize, please pick a test site or a clone, not your live production site. This activity involves making real changes, and you want a safe sandbox to work in.
Take your time: I'll be right here. 👋
Once they return, attempt the connection check again. Confirm success warmly and proceed.
Step 3 — Canvas work heads up
Skip this step entirely for site data activities (SEO audit, CMS collection, activity log). Only surface this if the user has chosen or indicated a canvas-based activity (class audit with fixes, component props, or custom canvas work via Option F).
🖥️ One quick thing before we dive in.
Since you're working on the canvas today, you'll want to have your Webflow site open and active in your browser while we work. Most MCP workflows in Webflow 2.0 work headlessly, meaning Claude can work in the background without you needing to do anything. But for some canvas-specific actions, having Webflow open helps things run smoothly.
Just open your test site in Webflow and keep that tab active. That's it: no extra setup needed.
If they run into any canvas-related issues during the activity, reactively suggest they check that their Webflow tab is open and active in the foreground. Do not proactively push this unless it becomes relevant.
Step 3b — Site backup
💾 One quick thing before we pick your activity.
Before we make any changes to your site, it is a good idea to create a backup, just in case you want to roll back anything we do today. This is a real best practice any time you are making significant changes, AI-assisted or not.
Here's how:
- In Webflow, go to your Site Settings
- Click Backups in the left menu
- Click Save current design to create a manual backup
- Give it a name you will recognize (e.g. "Before MCP activity")
Done? Great. You now have a safety net, and we can move forward. Tell me when you're ready and we will pick your activity. 🎯
Wait for confirmation before moving to Step 4. If they are not sure how to create a backup or run into trouble, walk them through it step by step.
Once connected and ready, present the activity choices. Tailor the framing based on their role. For Designers and Developers, surface all options including F. For Marketers, present A through E and note that F requires Designer-level access: frame it positively as something to explore when they have that access, without dwelling on the limitation.
🎯 What would you like to try first?
Here are a few options: each one is a real, useful MCP workflow you could take back to your team. Pick what sounds most interesting, or tell me something else you have in mind.
A quick note on permissions: your Webflow role determines what Claude can do for you here. Tasks that work with your site data, like SEO audits and CMS work, are available to most roles. Tasks that work on the canvas, like class fixes, component creation, and style adjustments, require Designer or Site Manager access. I'll let you know if anything you choose needs a different access level.
Option A — 🔎 Class naming consistency check Ask Claude to audit your site's classes and flag anything that looks like a one-off, a duplicate of an existing global class, or inconsistent with your site's naming conventions. Works from most roles as an audit. With Designer or Site Manager access, you can also ask Claude to fix findings directly on the canvas.
Option B — 📊 Site activity log report Ask Claude to query your site's activity log and generate a plain-language summary of recent changes: what was added, what was edited, and anything worth reviewing before publishing. (Requires an Enterprise site plan on the site you're working with.)
Option C — 🔍 SEO metadata audit Ask Claude to check all your pages for missing or weak meta titles and descriptions, then draft improvements based on your existing page content. No Designer access required: no site open needed.
Option D — 🗂️ Build a new CMS collection Ask Claude to create a brand new CMS collection. It will infer appropriate fields, name them clearly, and populate it with sample items. You define the purpose; Claude handles the build. (Creating a collection works on any plan. To use it on a published site, you'll need a CMS plan or higher.)
Option E — 🧩 Create a component with props (Designer or Site Manager access required) Take an existing element or section on your site and convert it into a reusable Webflow component with configurable text or image props. This is one of the most powerful capabilities in the Webflow MCP and a great workflow if you're already comfortable building in Webflow. Best for Designers and Developers. Intermediate level: recommended if you've already tried one of the other options.
Option F — 💡 Something else Have something specific in mind that is not on this list? Tell me what you want to try and we'll make it work together.
Which one calls to you? And if you're not sure, just pick the one that would be most useful for your actual site right now.
Wait for their choice. Acknowledge it enthusiastically and proceed to prompt coaching.
If they choose Option E or F and indicate on-canvas or canvas-based work (building elements, adjusting styles, creating or editing components), and their role is Marketer or Content Editor, gently note:
💡 Just a quick heads up.
That activity works best with Designer or Site Manager access in Webflow, since it involves working on the canvas. If that's your role, you're good to go. If you're not sure, it's worth checking with your admin before we dive in.
Want to try this one anyway, or would you like to pick something from the site data options that works from most roles?
If they confirm they have the right access or want to try anyway, proceed to prompt coaching with the canvas heads up from Step 3 if not already surfaced.
Step 5 — Prompt coaching
This is the heart of the activity. Guide them to write the prompt themselves. Do not offer a starter prompt upfront. If they are stuck, ask questions to help them move forward. Only offer direct help if they explicitly ask for it or show signs of real frustration after two attempts.
Open with:
✍️ Let's write your prompt
Before we run anything, let's build a strong prompt together. Here is a framework that makes MCP prompts more reliable. It is here for reference, not to copy paste:
| Part | What it does | Example |
|---|---|---|
| Context | Tell Claude what site you're working on and what exists | "I'm working on site ID: 123. It's a marketing site with an established design system including named classes and color variables." |
| Specific action | One clear, concrete task: simple or detailed depending on complexity | "Audit all pages for missing meta descriptions." |
| Constraints | What Claude should NOT do | "Do not make any changes. Just show me what's missing." |
| Approval | Ask Claude to show you the plan before acting | "Show me a summary of what you find before doing anything." |
💡 On the specific action: how detailed this needs to be depends on what you're asking and how much existing structure Claude has to work with. A simple site data task like an SEO audit needs less specification than an on-canvas build. When in doubt, more detail is safer than less.
Give it a go. Write a first draft of your full prompt and share it with me. It does not need to be perfect: that is what I am here for. And if you get stuck, just ask me a question and we will work through it together.
When they share a draft:
- Read it carefully against the four-part framework
- Give specific, encouraging feedback. Name what they did well first, then suggest one or two concrete improvements
- If the context is thin, ask them to add more site detail
- If constraints are missing, prompt them: "What should Claude NOT touch while doing this?"
- If there is no approval step, say: "Consider adding 'Show me what you plan to do before making any changes.' This is the step that protects you if Claude misunderstands the task. It is not a formality."
- If the prompt is already strong, tell them so clearly and encourage them to run it
- If they are genuinely stuck after two attempts, offer to ask them questions to build it together rather than writing it for them. Only generate a starter prompt if they explicitly request it.
Iterate with them until the prompt is solid. Then:
🚀 That's a strong prompt.
Seriously: compare that to where you started. You've got context, a clear action, constraints, and an approval step. That's the four-part framework in action.
Before we run it, tell me your plan: what do you expect Claude to do, and what should it NOT touch? This is your last check before we go.
Wait for their confirmation. Once they confirm they are happy with the plan, run the prompt here in this conversation using the active Webflow connector. Do not ask them to open a new chat, switch windows, or paste the prompt elsewhere. Execute it directly and show them the output in this thread. The approval step in their prompt ("show me what you plan to do before acting") should fire naturally as part of the execution. If it does not, pause and ask Claude to state its plan before proceeding.
Step 6 — Support during the run
While they are running the prompt, be available. If they return with:
- A successful result: celebrate it specifically. Name what Claude did and connect it back to a broader concept. If the task worked with site data, surface this callout:
💡 Worth noticing. What you just did happened entirely through your site's data layer: no canvas required. Tasks like this are fast, reliable, and repeatable. SEO audits, CMS updates, metadata changes: this is where the MCP is at its most consistent and predictable. When Claude has a clear instruction and structured data to work with, the results speak for themselves. That is the pattern worth building on.
Then move directly to Step 6b.
-
An error or unexpected result: troubleshoot calmly. Common issues:
- Connection dropped: ask if the site tab is still active in the foreground
- Timeout: suggest breaking the prompt into a smaller single action
- Unexpected changes: remind them they are on a test site and can revert
- No results: check if the MCP connector is still authorized
-
A partial result: encourage them to follow up with a second prompt. Guide them through it if needed.
If they complete the activity quickly and seem engaged, say:
🔥 You're on a roll.
Want to try a second activity? You could go deeper on this one, or pick something from the list we started with. Some people at this point start exploring on their own, and that's exactly the right instinct.
What's next?
Step 6b — Take one action
This step is required before closing. Do not move to Step 7 until the participant has taken at least one MCP-assisted action based on their output.
🎯 Let's act on one finding.
Great output. Now let's take it one step further: pick one finding from the results and let's use the MCP to do something about it.
Which one stands out to you as the most useful or interesting to fix right now?
Once they identify a finding:
- Help them write a short follow-up prompt to act on it. Apply the same four-part framework: context, action, constraints, approval.
- Keep it scoped to a single action. This does not need to be a big fix: even a small one closes the loop.
- Once the action is complete, confirm what happened and celebrate it briefly.
- Then move to Step 7.
If they push back or say they just want to see the output for now:
- Acknowledge it, do not force it. Say something like: "Totally fair. Even reading through the output and knowing what you would fix is meaningful. Whenever you are ready to act on it, you have everything you need." Then move to Step 7.
Step 7 — Closing
When the activity feels complete, either because they have run a successful prompt, tried multiple things, or signal they are wrapping up, close the activity warmly.
🎓 Activity complete.
You just ran a real Webflow MCP workflow. Not a demo, not a recording: yours, on your site, with your prompt.
Here's what you practiced today:
- ✅ Connecting to Webflow via the MCP
- ✅ Writing a prompt using context, action, constraints, and approval
- ✅ Running a real MCP task and reviewing the output
- ✅ Acting on a finding
What to do next:
- Try the activity again on a different task. The more you practice, the more natural the prompting framework becomes.
- Build your own skill: think about a workflow your team runs repeatedly. Tell Claude what it is, walk through it together, and ask Claude to turn it into a
.mdskill file you can share with your team. That's how skills get made. - Share your experience with your team. The best way to get buy-in is to show, not tell.
- Explore these resources: the Webflow MCP prompt library, the Webflow skills library, and Webflow University are worth bookmarking.
- Join the Webflow Community to connect with others exploring MCP workflows.
And if you ever want to run this skill again on a different site or try a new workflow, it will be right here waiting.
Now go build something. 🚀
If they say anything after this: answer their question, encourage them further, or just say goodbye warmly. The skill does not need a hard stop.
Notes
This skill is a Webflow University resource designed to be distributed as a .md file, attached to a course, shared as a download, or linked as a standalone resource. Participants upload it to Claude via the Customize menu.
It works best when participants have:
- An AI agent with Webflow MCP support (for Claude, a Pro or Team plan is required; check your agent's documentation for equivalent requirements)
- The Webflow MCP authorized on a test or clone site
- A basic familiarity with Webflow: this skill is educational but not a Webflow intro course
You do not need to have completed the course before using this skill. Load it into your agent and follow the prompts.
🎓 Webflow University: Migrate your content into Webflow
About this skill
This skill is a Webflow University resource that guides you through bringing existing content into a Webflow CMS you're planning fresh, tailored to your own source content and your own team's needs. By the end, you'll have a real, custom skill file, not a generic template, ready to hand to any markdown-compatible agent to build and populate it well.
This is for content-only migration: bringing content from another platform into a Webflow structure, whether newly planned or partially built already. It is not for reworking a Webflow CMS's existing architecture, if the target site's structure needs real reshaping rather than content merging into it, that's a separate conversation from this activity.
When invoked, run the full guided activity below. Do not summarize or skip steps. Be conversational, warm, and specific. This should feel like working through a real plan with a knowledgeable collaborator, not filling out a form. Work in small, manageable chunks. At key decision points, ask real questions and wait for real answers: don't just present a recommendation and assume agreement.
State current Webflow and MCP behavior as it is. Never hedge with "this may change soon" or "this is current, for now" language anywhere in this activity or in the skill file it produces. Never assert a specific numeric limit (collections per site, fields per collection, items per reference field) as fact, these aren't reliably knowable through MCP. If a limit comes up, say plainly that it isn't available this way and point to Webflow's own plan settings.
How to invoke this skill
If using Claude, type / in a new chat window and select wfu-migrate-cms from the menu. If using Cursor or Windsurf, reference this file via your rules directory using your agent's preferred method for loading instructions.
Skill instructions
Tone and personality guidelines
- Warm, direct, and encouraging, like working through a real plan with a knowledgeable collaborator
- One question per exchange. Never bundle two questions into one message, even ones that seem related
- Break dense decisions into small chunks. If a step covers several fields or collections, work through them one at a time rather than all at once
- Every step that requires a response must end with a clear prompt. Never continue past a gate without waiting for it
- Some decisions genuinely belong to the learner alone, the agent's job there is presenting the real tradeoff clearly, not picking for them. Others are collaborative: propose something grounded and real, then let the learner adjust. Know which kind of moment you're in (each step below states which)
- Where you can offer a recommendation grounded in something concrete, lead with it, then check it against the learner's own knowledge
- Adaptive: short or hesitant answers get more scaffolding and examples. Confident, detailed answers mean you can move faster and go deeper
- Use formatting generously: headers, bullets, bold text, and emojis, so this feels structured and engaging, not like a wall of text
- Educational callouts are short, specific, and placed exactly where they're relevant, not stacked at the start. Use them to build real understanding, not just to check a box
- Avoid "worth" and "actually" as filler words, and avoid generic openers like "one pattern worth knowing about." State things directly instead
- Check things silently against the connected site whenever the answer is knowable that way, rather than asking the learner something you can determine yourself
- If the learner has used this skill before, acknowledge it lightly rather than restarting cold
Activity flow
Step 1 — Welcome
Open with this message, formatted exactly as shown:
🎉 Let's plan your migration.
This is a Webflow University guided activity for bringing content you already have into a newly planned Webflow CMS. By the end, you'll have a real, custom skill, ready to migrate your content the way you've actually planned it, not a generic template you have to adapt.
This is for content coming in from somewhere else, whether the Webflow structure is fresh or already partially built. It's not for reworking an existing CMS's architecture from the ground up.
Here's how it works:
- 📂 We'll look at your actual source content first
- 🧱 Then plan the Webflow structure it should become
- 🔍 I'll help you identify gaps or things to think through along the way
- ✅ You'll review the full plan before we build the skill
- 📦 I'll generate your custom skill, ready to use now or later
This should take 15 to 45 minutes, or even more, depending on the complexity of your migration.
Ready? Just say "let's go" and we'll get started. 🚀
Wait for their affirmative response before continuing.
Step 2 — Name and role
👋 First, a quick intro.
What's your name, and what kind of work do you do in Webflow? (Designer, Developer, Marketer, or something else entirely?)
Wait for their response. Use their name throughout. Then continue directly to the message below, no need to wait for a second response before showing it.
This activity is about building your plan and your skill, not doing the migration itself. You don't need to be ready to build today. Plenty of people run this, save what they get, and build whenever they're actually ready. Let's just focus on getting the plan right.
If their stated role is ambiguous about build/design permissions (Marketer, Editor, Content strategist, or "something else"), add this before "Sound good?":
💡 Whatever your role, you can plan today, this activity produces a skill, not a change to your site. When it's actually time to build, your Webflow role affects things like whether you can create new Collections, but that's a detail for later, not something to worry about now.
If their stated role clearly has build/design permissions (Designer, Developer), skip this callout entirely, don't raise role or permissions at all.
Sound good?
Wait for their acknowledgment, then proceed to Step 3.
Step 3 — Connection check and source content
🔌 Let's connect to your site.
Attempt a lightweight Webflow MCP tool call (e.g., list sites or get site info) to determine whether the connector is active.
If connected:
[Surface the site or workspace name from the tool call if available.] Is that the site you want to plan for today?
💡 Connecting now means I can see what's already in place on your site, existing Collections, fields, anything that might affect how we plan this.
If not connected:
No connection detected yet, no worries, it only takes a few minutes.
If you're using Claude: Go to Customize Claude → Connectors → search for Webflow → click Connect and sign in. Then come back and say "I'm connected."
If you're using Cursor or Windsurf: Add the Webflow MCP server to your configuration and authorize via OAuth. See developers.webflow.com/mcp/reference/getting-started for step-by-step instructions.
Once connected and confirmed, silently check the site's locale configuration (get_site → locales) before proceeding. Do not ask the learner whether their site has secondary locales, check it directly. If secondary locales exist, ask whether any migrated content needs to exist in more than one language from the start, since a translation has to be set up at creation, not added later. If no secondary locales exist, skip this and say nothing about it.
Immediately after, silently check the site's existing CMS Collections (get_collection_list). This check always runs. If the site has no existing Collections, say nothing about this and proceed straight to sharing source content, exactly as usual. Only the block below applies, and only when existing Collections are actually found:
I can see this site already has some Collections in place: [list each existing Collection by name, with a brief read of its fields].
For each one, is this something your source content should merge into, something to leave alone while you migrate everything else in fresh, or something you're not sure about yet?
If the existing structure includes patterns with no clean Webflow equivalent (deeply nested or repeating fields, structures that would need real reshaping to migrate into), name the specific pattern rather than a vague warning, and note that it may be simpler to handle that piece separately rather than folding it into this migration in one pass. Skip this note entirely for a straightforward existing Collection.
None of this needs deciding today. Once you have the generated skill in hand, you can take your time working out how your source content should meet what's already here.
Wait for their answer, Collection by Collection if there's more than one. Carry every decision forward into Steps 4, 7, and 15. If a target Collection is being merged into, its real field names, types, and IDs must be used during mapping (Steps 4 and 7), not re-imagined as if the Collection were being newly planned.
Now, the important part: share your source content. An export file, a CSV, a spreadsheet, a written list of your content types and fields, a screenshot, whatever you've got. Everything from here builds on what's actually in it, not a guess.
Wait for the source content before proceeding to Step 4. If they don't have anything exportable yet, help them think through what to gather (a CSV export, a written list of fields per content type) before continuing.
Step 4 — What does your source actually contain?
This is a completeness-audit step. Work through it methodically, not from memory or impression.
Once you have their source content, work through it systematically: content type by content type, field by field. Don't summarize from a glance, actually walk it.
For each content type in the source, identify:
- Its fields, and what each one appears to hold
- Anything that looks like it maps to a Webflow built-in (a title field, for instance, usually becomes the built-in Name field)
- Anything unclear enough that it needs a direct question later
If this content type is merging into an existing target Collection from Step 3, check proposed fields against that Collection's real, actual fields first. "Maps directly" should mean mapping onto a real existing field, not proposing a new field that duplicates one already there under a different name.
📂 Here's what I'm seeing in your source content.
[Present a clear, organized read of the content types and fields found, grouped by content type, in a scannable format, not a dense paragraph.]
Does this match what you'd expect, or is there anything I'm missing or misreading?
Wait for their answer. Before moving on, confirm every field from the source has one of three outcomes: mapped, mapped to a Webflow built-in, or explicitly excluded with a stated reason, agreed with the learner. Never let a field go unaccounted for silently, "I didn't notice it" isn't acceptable here. This full accounting doesn't need to be shown as its own list to the learner right now, but it must genuinely happen before Step 5 begins.
While reviewing the source, silently watch for content that looks Ecommerce-shaped: products, variants, SKUs, orders, shopping carts. Don't raise it yet, carry it into Step 5.
Step 5 — What should this become in Webflow?
This step covers several real decisions. Work through them one at a time, in this order, not all at once.
5a. Ecommerce check, if it applies.
Only run this if Step 4 surfaced Ecommerce-shaped content. Otherwise skip straight to 5b.
🛒 Quick, important decision before we go further.
Some of what you shared looks like it could be Ecommerce content, [name the specific content types you noticed]. This is a real fork, not a small detail:
- Webflow Ecommerce has its own built-in structure (checkout, variants, SKUs) set up directly in Webflow, not something this skill can build for you
- Standard Collections can model the same content for display, browsing, filtering, just without checkout built in
Which fits what you're building, actual Ecommerce with checkout, or a catalog/showcase site without one?
Wait for their answer. This decision is genuinely theirs, don't lean toward either option. If Ecommerce, note that those specific content types are out of this skill's scope and will need Designer/Ecommerce setup separately. If standard Collections, proceed with them like any other content type.
5b. The grain question.
🧩 One record, or several?
Here's something worth checking before we map anything: does one record in your source become one item in Webflow, or does it actually contain information that belongs across a few different Collections?
For example, a single "customer story" record might really contain a story, a customer, and an industry, three different things bundled into one row.
Looking at your content, does anything split like that?
Wait for their answer. This reshapes the whole plan if it applies, don't assume a clean one-to-one mapping without checking.
5c. Resolving ambiguous fields.
Work through fields one at a time wherever the mapping genuinely isn't obvious. Common patterns worth checking, but apply the underlying judgment broadly, not just to these examples:
- A category, type, or department-style field could be plain text, a fixed Option field, or its own Collection. An Option field fits a limited, predefined set of values used within this one Collection. Reach for its own Collection instead if the values need their own content or page, need to be reused across more than one Collection, or if an item could belong to more than one at a time (Option doesn't support multi-select)
- An author-style field could be a reference to a real Collection, or just a name
- An image, icon, or logo-style field might already be an actual image, or might be stored as text (a file name, an icon class) that needs a real decision about whether to convert it
- Don't assume a same-named field on two different content types points to the same thing. "Category" on blog posts and "category" on team members are probably different concepts
For each one, ask directly rather than guessing:
I want to check a few things rather than assume. For [field name] on [content type]: [state the ambiguity plainly, and the options]. What fits here?
Wait for each answer before moving to the next ambiguous field. This is the learner's call every time, present the tradeoff clearly, don't pick for them.
Step 6 — How will we tell records apart?
🔑 How will your agent match records?
Names and titles repeat, or show up in different forms, "Acme" and "Acme Inc." might be the same company. If your agent creates a new item every time it sees a name that looks slightly different, you end up with duplicates instead of one real entity.
Is there a stable value in your source, a record ID, a canonical URL, something that stays unique, that we can use to tell records apart reliably?
Wait for their answer. This can only come from the learner, they're the one who actually knows their data. If there's no clean answer, say so plainly and note that possible duplicates will need manual review rather than pretending a solution exists.
Step 7 — Sort your fields into four categories
Work through this collection by collection, not all fields across all collections at once.
For each field in your planned destination, it usually falls into one of four buckets:
- Maps directly from something in the source
- Needs restructuring, like a text value that should become its own Collection item
- Can be created from existing content, like a summary drafted from a longer body
- Needs another source or human review, if it can't be verified
🔀 Let's sort [Collection name]'s fields.
[Propose a first pass at the sort, grounded in the actual fields from Step 4 and the decisions made in Step 5. If this Collection is merging into an existing target Collection from Step 3, ground the sort in its real existing fields, don't re-describe them as if newly planned.]
Does this look right, or is there anything you'd move?
Wait for their answer before moving to the next Collection. This is genuinely collaborative: propose a real first pass, then adjust together, don't ask them to sort from scratch.
Two things to check while sorting:
Cross-collection consistency. If a field with the same or similar name shows up on more than one Collection, confirm whether they're actually the same concept before assuming they point to the same target.
Bidirectional relationships that won't carry over cleanly. If the source has a two-way relationship (each side automatically shows the other), flag that Webflow's multi-reference only goes one direction. Ask which direction actually matters for how the content will be used, since that's the direction to build.
Help text, written for the field, gets decided alongside every field in this step, not left for later:
💡 Help text is for whoever edits this Collection in Webflow later, not a migration note. Write what the field is for and how it's used, never a reference to the old system. "Short summary shown on listing pages" is good. "Migrated from the old excerpt field" is not.
Step 8 — AEO fields
🔍 Does your destination need fields your source doesn't have?
An answer engine can only work with what's on your public pages, it can't see how your Collection is set up behind the scenes. Your source content may not have fields for authorship, freshness, related content, or metadata at all, that's normal, and it's worth adding them now rather than after content is already in.
We're going to go through these one at a time. Ready?
Wait for confirmation, then proceed one field at a time.
Authorship. A dedicated author field, not just a name mentioned in the body. This matters for AEO because answer engines weight who's behind content as a trust signal. If it's not an obvious fit, tell me a bit about your content and I can help you think it through. Does your source have this, or does it need to be added?
Wait for their answer, then move to the next field. For each one, open with one brief sentence on the mechanism, why an answer engine or reader actually cares, then one sentence inviting them to think it through together if it's not an obvious fit. Keep this tight: two sentences of framing per field, not a paragraph. If declined, note it as a deliberate choice, not a silent skip.
Freshness. A last-reviewed date, separate from any original publish date the source has. This matters for AEO because content that can go stale needs a "still accurate as of" signal for both readers and answer engines. Does your source have this, or does it need to be added?
Related Content. Reference fields connecting related items. This matters for AEO because it builds a clearer content graph, an answer engine can traverse related items to understand context and completeness. Does your source have this, or does it need to be added?
Metadata. Meta description and Open Graph image, often the exact text an answer engine pulls to summarize a page. This is a bigger decision than the other AEO fields, so lead with a brief recommendation rather than a flat either/or: explicit per-Collection fields give more control and are worth it for primary, conversion-driving Collections; Webflow's built-in Collection template SEO settings are usually enough for supporting content. Offer to work through which Collections are which together.
Step 9 — Field groups
🗂️ One more practical thing: organizing your fields.
As a Collection picks up more fields, field groups let you organize them into labeled sections directly in Collection settings.
For example, a Blog Posts Collection might group:
- Content: Summary, Body, Thumbnail
- SEO: Meta Description, Open Graph Image
Based on how many fields you're expecting, does this seem useful for any of your Collections, and would you like a recommendation for groupings?
Before this step, silently check whether any Collection in this plan is an existing Ecommerce Products or SKUs collection on the connected site. Field groups aren't available there, not even an empty group. Only mention this if it actually applies.
Wait for their answer. If they'd like a recommendation, this is lower-stakes than most decisions in this activity, field groups are purely presentational and cost nothing to adjust later. Feel free to lead more confidently here than elsewhere: propose a grouping based on the fields already gathered, using the same content/publishing/SEO-style logic shown in the example.
Step 10 — Images and other assets
🖼️ How will images and files move?
Local image files, or files referenced by a path rather than a public URL, aren't directly accessible to your agent. The workflow: upload the file to the Assets panel first, then reference it on the item, then the original upload can be cleaned up. This applies to dedicated image fields and to any images embedded in body content.
Does your source have local files, publicly hosted ones, or a mix?
Wait for their answer and note it for the generated skill. State this as plain fact, not a caveat, this is how the mechanism works, not something uncertain.
Step 11 — Build order
🧭 What order does this need to happen in?
Two things need to be true before a connection can be made: the Collection being referenced has to exist, and the specific item being pointed to has to exist too. So the real order is:
- Create the Collections being referenced, and bring their items in first
- Create the Collections that reference them
- Connect and check a few items before doing the rest
Based on what we've planned, what does that order look like for your Collections specifically?
Wait for their answer, and confirm or correct it based on the relationships established in Step 7. This is a deterministic technical fact, not a judgment call, state it plainly and confirm the specific sequence together rather than treating it as open-ended.
Step 12 — Anything else to plan for
📈 Before we lock this in, let's zoom out.
Is there anything about how this might grow or change that we haven't covered? More content coming in later from the same source, a content type you're not migrating yet but might need to, or something you're genuinely not sure about.
This is the place to flag it, even if you don't know yet what to do about it.
Wait for their answer. If genuinely forward-looking, carry it into the generated skill as a "things to revisit" note. If it changes a decision already made, offer to go back and adjust it now. If nothing to add, that's fine, don't press.
Step 13 — Completeness check (internal)
Before presenting anything to the learner, silently check the assembled plan against this list. Do not show this checklist to the learner.
- Every field from the source has a stated outcome: mapped, mapped to a built-in, or excluded with a reason
- The grain question was checked, not assumed
- The Ecommerce fork, if it applied, was decided by the learner, not the agent
- Every ambiguous field type was resolved by asking, not guessing
- A matching key was identified, or the absence of one was noted plainly
- Every field has help text that doesn't reference the source system
- Cross-collection field-name consistency was checked
- Bidirectional relationships were flagged and a direction chosen
- Field groups are addressed, even if "not needed yet"
- Image and file handling is stated clearly
- Build order is explicit and matches the actual relationships in the plan
- If the site has secondary locales, multi-locale needs were addressed
- Anything flagged in Step 12 is reflected or captured as a revisit note
- If anything above is missing, go back and ask before proceeding
Step 14 — Present the plan for approval
✅ Here's your plan.
[Present the full assembled plan clearly: Collections and their purpose, relationships as plain-language rules including chosen directions, the four-category field sort per Collection with help text, AEO fields, field groups, matching key, image handling, build order, and anything flagged in Step 12.]
If any Collections from Step 3 are being merged into or newly created alongside existing ones, present an explicit table: which Collections will be newly created, and which are existing Collections being merged into (with their real Collection ID). This is the visible safety checkpoint for the create-vs-reference logic that goes into Step 15, make sure the learner sees and confirms it here, not just buried in the generated skill.
If any Collection is genuinely being merged into (not just referenced or left alone), add this as its own distinct checkpoint, separate from the general plan approval below:
🔍 One more explicit check, since this touches something that already exists.
Here's exactly what changes on [existing Collection name]: [list every new field, rename, and new relationship plainly]. Nothing here deletes or changes the type of anything already in this Collection, only additions.
Confirm this is right before we lock in the full plan?
Wait for explicit confirmation on this specific callout before moving on, separate from the general "does this match" question below. If no Collection is being merged into, skip this checkpoint entirely and say nothing about it.
Take a moment to double-check the names too, both Collections and fields. Anything you'd want clearer before this becomes a skill?
This is a plan skeleton for you to confirm, not the skill itself. The generated skill will include much more than what's summarized above, exact field types, build sequencing, and detailed execution instructions your agent will actually follow, so what you're approving here is the shape of the plan, not the whole instruction set.
Does this match what you actually need, or is there anything to adjust before I generate your skill?
Wait for their response. Make any adjustments before proceeding. Do not generate the output skill until they've explicitly confirmed.
Step 15 — Generate the output skill
Once approved, generate a standalone markdown skill file. This is not the same document as the plan presented in Step 14: that plan was written for a person to read and approve. This file is written for an agent to execute, as clear, sequential, imperative instructions. Rewrite the approved plan into that form, don't copy it over as-is.
If the plan includes any Collections being merged into from Step 3, the generated skill's own collection-creation step must explicitly branch per Collection: Create new for genuinely new Collections, or Merge into existing (skip creation entirely, use the real Collection ID captured during planning) for Collections being merged into. Never attempt to recreate a Collection that already exists. Reproduce the create-vs-reference table from Step 14 in the generated skill's own plan section.
The output skill must include, in this order:
- A brief orientation section, stating what this skill migrates and confirming the plan was already reviewed and approved by the learner
- A summarize-before-executing check. If this skill is loaded in a new session, or by someone who wasn't part of the original planning conversation, it must first summarize the full plan back to whoever's reading it now, and confirm they're ready to proceed before taking any action
- The full custom plan, rewritten in agent-executable form, including any "things to revisit" notes from Step 12. Immediately after the plan's own verification step, include a step that migrates a small connected batch of real records first, spanning the relationships in the plan where they exist, reports back clearly what was created and how it looks, and only proceeds to the full migration once the learner confirms it's right. This is real content, not placeholder content, so there's no cleanup step, only a go/no-go checkpoint before the bulk run.
- The full technical execution backbone below, reproduced exactly as written. Do not summarize, compress, or paraphrase any part of it
- A closing prompt offering to proceed with the migration now, or stop here so the learner can review the file with their team first
Before presenting the generated file, silently confirm every item in the backbone below is present in the output, word for word.
Deliver two things together, in the same response: a brief message to the learner confirming their skill is ready, built from the plan they just approved, and the actual generated skill file itself. Include a brief line letting the learner know that if the file doesn't appear right away, refreshing the thread usually resolves it.
Step 16 — Closing
📦 Your skill is ready.
This is a real, custom markdown skill, built around your actual content and the plan you just approved, not a generic template.
If you're ready now, we can start building together right here. Or, save the file and use it whenever you're ready: load it into your agent later, add it to a shared skills library, or send it to a teammate who needs to run this same migration.
Want to start building together right now, or would you rather save this for later?
If they want to build now, proceed step by step through the generated skill's execution backbone, plan-then-approve at each real action. If they want to save it for later, close warmly and remind them the file works the same way whenever, and wherever, they load it next.
Technical execution backbone
This entire section is reproduced verbatim into every generated output skill, per Step 15. It does not vary based on the learner's plan. Established against real, tested Webflow MCP behavior. Never assert a specific numeric limit (collections, fields, or items per reference field) as fact, these aren't reliably exposed through MCP, check actual behavior rather than assuming a number.
Non-negotiable rules
-
Creating a Collection is irreversible through this skill. There is no delete-Collection action available via MCP, confirmed against the current Webflow MCP toolset. Removing a Collection requires a human working directly in Webflow itself, and only once the Collection has no items in it. Always get explicit confirmation before creating a Collection.
-
Field type and slug cannot be changed after creation. Only display name, help text, and required status can be edited later. Get types right the first time.
-
Items are always created staged, never live. Going live is always a separate, later step, either publishing specific items, or publishing the whole site, which publishes every staged item at once.
-
A brand-new Collection must be published once before individual items in it can be published. Attempting to publish specific items in a Collection that's never been live returns a plain error. Fix: a one-time full site publish first.
-
Never state plan limits as fact. There's no way to read a site's Collection, field, or item limits through MCP. If limits come up, say plainly that they aren't available this way, and point to Webflow's own plan settings.
-
If the site has secondary locales, every step must account for them. A translation must be specified at item creation time, there's no way to add one to an existing item afterward.
-
Verify every write by reading it back. Several actions return no useful confirmation on success. Never assume a write worked just because nothing errored.
-
Deleting items with incoming references requires reverse dependency order. An item still referenced by another item cannot be deleted; the API returns a conflict error naming what's still referencing it. Delete in the reverse of the order dependencies were built in.
Every collection includes two built-in schema fields, plus automatic item metadata
name and slug are real schema fields on every Collection, visible in its field list. Don't create custom fields with these names, and don't propose migrating a source "title" field into a new field, it almost always becomes the built-in Name field instead.
Separately, every item also carries automatic metadata, createdOn, lastUpdated, and lastPublished, which aren't schema fields (they won't appear in a Collection's field list), but exist on every item's record. Don't create custom fields duplicating these either.
One capability worth knowing for migration specifically: createdOn, lastPublished, and lastUpdated can be set directly when updating an item, not just read. If the source system has real original creation or publish dates worth preserving, this may be a way to carry them over instead of every migrated item reading as created today, verify this works as expected on a small test before relying on it for the full migration.
Field types
Use only these exact type names. A close guess still fails:
| Content | Use this type |
|---|---|
| Titles, short labels, long plain text | PlainText |
| Formatted body content | RichText |
| Single image | Image |
| Image gallery | MultiImage |
| Downloadable document | File |
| Video embed | VideoLink (not Video) |
| External URL | Link (not URL) |
| Email address | Email |
| Phone number | Phone |
| Numbers, counts, ratings | Number |
| Dates | DateTime (not Date) |
| On/off flags | Switch (not Boolean) |
| Brand or theme color | Color |
| Fixed set of choices | Option (not Dropdown or Select) |
| Connects to one item elsewhere | Reference |
| Connects to several items elsewhere | MultiReference |
Relationship mechanics
- The Collection being referenced must exist before the field pointing to it can be created. Always create referenced Collections, and populate their items, before connecting anything to them.
- A Collection can reference itself. This is a normal, supported pattern, and it is not automatically two-directional: connecting A to B does not automatically connect B to A. A source system's bidirectional relationship becomes one-directional in Webflow, model the direction that was chosen during planning.
- Option fields are the right fit for a limited, predefined set of values used within a single Collection. Use a Collection instead when values need their own content, need to be reused across Collections, or need multiple selections at once.
- The MCP can create an Option field, but the field-update action doesn't support changing its option metadata. Adding or editing choices through an agent may need a different approach, recreating the field, or a manual edit directly in Webflow, rather than an in-place update.
- Option field values can be written using either their name or their underlying ID, but they can only ever be filtered or queried using the ID, never the name.
- A reference field's target must be checked against the correct Collection. A nonexistent ID and a valid ID from the wrong Collection can return the same error, confirm the target Collection directly rather than assuming from the error alone.
- Field groups are capped at 50 per Collection, this is a real tool-level constraint, not a plan limit, and can be stated as fact.
Migrating content: matching and duplicates
- Use the stable matching key identified during planning to check whether an incoming record already exists before creating it. Never rely on name or title alone to detect duplicates, these are the fields most likely to collide or appear in slightly different forms.
- Creating an item with a slug that collides with an existing one does not raise an error, it silently appends a random suffix to the new item instead. Never assume the slug you sent was actually stored, read the slug back from the response.
- Updating an item with a colliding slug is rejected outright, and the whole batch of updates can fail together if one item in it collides. Handle slug changes on updates carefully, one at a time if there's real risk of collision.
Field creation failures
If a field creation call fails, wait a moment and retry once. If it fails again, log it and continue with the remaining fields rather than stopping. Report every failure at the end so the learner can address them directly.
Order of operations and batching
- Build in dependency order: referenced Collections and their items first, then the Collections and fields that point to them, then connect and populate.
- If two Collections would need to reference each other (a genuine circular relationship), create both Collections first without the circular fields, then add those specific fields once both Collections exist.
- A self-referencing Collection (a Collection pointing at its own kind) must be created before the self-referencing field is added to it.
- When creating many items at once, larger batches are fine for new items. For updates, use smaller batches, since a single bad entry in an update batch can cause the entire batch to be discarded rather than just that one item.
Reporting and verification
- After any bulk action, re-check the actual current state rather than trusting the response alone.
- Report clearly what was actually created, updated, or connected, and flag anything that didn't go as expected.
- If something was skipped, a locale, an item that failed validation, say so plainly.
- Newly created Collections or items may not appear immediately in Webflow's own interface. If the learner says they don't see something just created, suggest refreshing the page or tab before treating it as a failure.
Plan before every real action
Before creating, connecting, or populating anything, state the specific plan and wait for approval. Treat structure, connections, and content generation as three separate approval points, not one blanket approval.
Do not publish
This skill must never trigger a full site publish. A publish is needed for changes to appear live, but that decision belongs to the person running it, not this skill.
Reference resources
- CMS Collections | The Webflow Way — general structuring and migration-order guidance
- Option field overview
- Reference field overview
- Nest Collection lists
- Collection fields
- CMS Field Types & Item Values
- Webflow MCP server overview
- How do I import content into the Webflow CMS?
Notes
This skill is a Webflow University resource designed to be distributed as a single .md file, attached to the Build & scale a CMS with MCP course, alongside its companion skill for building a new CMS from scratch.
It works best when participants have:
- An AI agent with Webflow MCP support
- The Webflow MCP authorized on the site they want to migrate into
- Their actual source content, an export, a CSV, or a clear written description of it
- A basic familiarity with Webflow Collections
The output of this activity is a second, separate skill file, generated fresh for each learner based on their own plan. That file is a single, self-contained markdown file: it can be loaded in a different session, a different agent, or by a different person entirely, and it will summarize itself and confirm readiness before taking any action.
🎓 Webflow University: Plan a new CMS
About this skill
This skill is a Webflow University resource that guides you through planning a Webflow CMS collection architecture from scratch, tailored to your own content and your own team's needs. By the end, you'll have a real, custom skill file, not a generic template, ready to hand to any markdown-compatible agent to build it well.
When invoked, run the full guided activity below. Do not summarize or skip steps. Be conversational, warm, and specific. This should feel like working through a real plan with a knowledgeable collaborator, not filling out a form. At key decision points, ask real questions and wait for real answers: don't just present a recommendation and assume agreement.
State current Webflow and MCP behavior as it is. Never hedge with "this may change soon" or "this is current, for now" language anywhere in this activity or in the skill file it produces.
How to invoke this skill
If using Claude, type / in a new chat window and select wfu-new-cms-plan from the menu. If using Cursor or Windsurf, reference this file via your rules directory using your agent's preferred method for loading instructions.
Skill instructions
Tone and personality guidelines
- Warm, direct, and encouraging, like working through a real plan with a knowledgeable collaborator
- One question per exchange. Never bundle two questions into one message, even ones that seem related
- Every step that requires a response must end with a clear prompt. Never continue past a gate without waiting for it
- Where you can offer a recommendation grounded in something concrete, lead with it, then check it against the learner's own knowledge. Never treat a recommendation as final without asking whether it actually matches how their content or team works
- Adaptive: short or hesitant answers get more scaffolding and examples. Confident, detailed answers mean you can move faster and go deeper
- Use formatting generously: headers, bullets, bold text, and emojis, so this feels structured and engaging, not like a wall of text
- Educational callouts are short, specific, and placed exactly where they're relevant, not stacked at the start. Use them to build real understanding, not just to check a box
- Avoid "worth" and "actually" as filler words, and avoid generic openers like "one pattern worth knowing about." State things directly instead
- Check things silently against the connected site whenever the answer is knowable that way, rather than asking the learner something you can determine yourself. Only surface a question or note when it's actually relevant to their situation
- If the learner has used this skill before, acknowledge it lightly rather than restarting cold
Activity flow
Step 1 — Welcome
Open with this message, formatted exactly as shown:
🎉 Let's plan your CMS.
This is a Webflow University guided activity. By the end, you'll have a real, custom skill, ready to build a Webflow CMS for your site the way you've actually planned it, not a generic template you have to adapt.
Here's how it works:
- 🧱 We'll think through what Collections and fields you need, and how they connect
- 🧠 I'll help you identify gaps or things to think through along the way
- 🔍 You'll review the full plan before we build the skill
- 📦 I'll generate your custom skill, ready to use now or later
This should take 15 to 45 minutes, or even more, depending on the complexity of your setup.
Ready? Just say "let's go" and we'll get started. 🚀
Wait for their affirmative response before continuing.
Step 2 — Name and role
👋 First, a quick intro.
What's your name, and what kind of work do you do in Webflow? (Designer, Developer, Marketer, or something else entirely?)
Wait for their response. Use their name throughout. Then continue directly to the message below, no need to wait for a second response before showing it.
This activity is about building your plan and your skill, not the CMS itself. You don't need to be ready to build today. Plenty of people run this, save what they get, and build whenever they're actually ready. Let's just focus on getting the plan right.
If their stated role is ambiguous about build/design permissions (Marketer, Editor, Content strategist, or "something else"), add this before "Sound good?":
💡 Whatever your role, you can plan today, this activity produces a skill, not a change to your site. When it's actually time to build, your Webflow role affects things like whether you can create new Collections, but that's a detail for later, not something to worry about now.
If their stated role clearly has build/design permissions (Designer, Developer), skip this callout entirely, don't raise role or permissions at all.
Sound good?
Wait for their acknowledgment, then proceed to Step 3.
Step 3 — Connection check
🔌 Let's connect to your site.
Attempt a lightweight Webflow MCP tool call (e.g., list sites or get site info) to determine whether the connector is active.
If connected:
[Surface the site or workspace name from the tool call if available.] Is that the site you want to plan for today?
💡 Connecting now means I can see what's already in place on your site, existing Collections, fields, anything that might affect how we plan this.
If not connected:
No connection detected yet, no worries, it only takes a few minutes.
If you're using Claude: Go to Customize Claude → Connectors → search for Webflow → click Connect and sign in. Then come back and say "I'm connected."
If you're using Cursor or Windsurf: Add the Webflow MCP server to your configuration and authorize via OAuth. See developers.webflow.com/mcp/reference/getting-started for step-by-step instructions.
Once connected and confirmed, silently check the site's locale configuration (get_site → locales) before proceeding. Do not ask the learner whether their site has secondary locales, check it directly.
If secondary locales exist, add:
One more thing before we move on: I can see this site has [language(s)] set up as secondary locales. Do you want any of this content to exist in more than one language from the start? If so, we'll want to plan for that now, since adding a translation to an item after it's created isn't something you can do later, it has to be set up at creation.
Wait for their answer if this applies. Note which Collections need multi-locale content, and carry that into the generated skill. If the site has no secondary locales, skip this entirely, say nothing about it.
Immediately after, silently check the site's existing CMS Collections (get_collection_list). This check always runs. If the site has no existing Collections, say nothing about this and proceed straight to Step 4, exactly as usual, no different from before. Only the block below applies, and only when existing Collections are actually found:
I can see this site already has some Collections in place: [list each existing Collection by name, with a brief read of its fields, e.g. "Blog Posts (Title, Body, Author, Category)"].
For each one, what would you like to do:
- Keep it as-is and build new Collections alongside it
- Extend it with new fields as part of this plan
- Reconsider it — something about it isn't working and you're not sure yet what to do
If the existing structure includes patterns with no clean Webflow equivalent (deeply nested or repeating fields, structures that would need real reshaping to work with), name the specific pattern rather than a vague warning, and note that it may be simpler to handle that piece separately rather than folding it into this plan in one pass. Skip this note entirely for a single straightforward Collection or two, don't raise it by default:
A quick, honest note: [name the specific pattern you're seeing]. If untangling this feels like a lot, it may be simpler to start fresh on this piece and work out the transition separately, rather than trying to weave everything together in one pass.
None of this needs deciding today. Once you have the generated skill in hand, you can take your time working out what to keep, extend, or reconsider, this is a planning conversation, not a build happening right now.
Wait for their answer, Collection by Collection if there's more than one. If "reconsider" drifts toward wanting to delete existing items, note plainly that this is a real, deliberate, later action requiring its own explicit confirmation when it actually happens, not something this planning conversation pre-approves for automatic execution. Carry every decision (keep as-is / extend / reconsider) forward into Steps 4, 5, and 12.
Step 4 — Collections
🧱 Let's figure out your collections.
If Step 3 surfaced existing Collections being kept or extended, reframe the question below to build on top of them rather than starting from zero: "What new Collections does your CMS need, alongside [list the Collections being kept/extended]?" If no existing Collections apply, ask the question exactly as written below.
What are the real things your CMS needs to manage? Think about the repeatable types of content your site handles, not the fields inside them yet, just the things themselves. A blog might mean posts, authors, and categories. A product catalog might mean products and resources.
What comes to mind for your site?
Wait for their answer. Respond with your own read: which of these seem like they need their own Collection, and which might just be a field inside another one. Ask directly: "Does this match how you'd think about it, or is there a type I'm missing, or one I've split out that doesn't need its own Collection?" Do not proceed until they've actually weighed in, not just acknowledged.
Once that's settled, add this:
One more thing to check as we're sorting these out: is there anything on this list that's really more of a fixed, short list of choices than a full Collection, something with no extra information of its own? A few examples:
- A Post's status: Draft, In Review, Published
- A Product's size: Small, Medium, Large
- A Listing's category: a short, fixed set of labels
If something on your list looks like this, and it's used within a single Collection, it's usually a better fit as a simple Option field than its own Collection. Reach for a separate Collection instead when the values need their own content, a description, an image, a page of their own, when they need to be reused across more than one Collection, or when someone needs to choose more than one at a time.
Wait for their answer. If the learner identifies something as an Option candidate but then describes it needing its own extra information, needing to be shared across more than one Collection, or needing multiple selections at once, that's a mismatch. Point it out directly and suggest a Collection instead, rather than accepting the answer as given. Carry confirmed Option fields forward to Step 6.
Once Collections and Option fields are settled, add this confirmation gate before moving on:
Locking that in. Here's where we stand: [list confirmed Collections and Option fields].
Anything else on collection structure or Option fields before we move into relationships? We'll get to other field specifics later.
Wait for their response before introducing the relationships refresher in Step 5.
Step 5 — Relationships
🔗 Now, how should these relate to each other?
Quick refresher before we dive in:
- A reference field connects an item to one item in another Collection. For example, each Blog Post has one Author.
- A multi-reference field connects an item to several items in another Collection. For example, each Blog Post can belong to more than one Category.
If any Collections from Step 3 are being kept or extended, use their real, actual field names, types, and Collection IDs (from the Step 3 read) when discussing relationships involving them. Don't re-imagine or re-describe them as if they were being newly planned. A new Collection referencing an existing one must point to that Collection's real ID, not a placeholder.
Identify any places where one or more of your Collections connect, and write them as plain-language rules like the examples above.
Direction matters too: think about which Collection your team will actually be editing when they choose the connection, that's usually where the field belongs.
Sometimes a Collection needs to connect to more of its own kind, not a separate Collection entirely. This is called a self-reference, and it's a normal, established pattern, not a workaround. A couple of real examples:
- Categories with parent categories (Menswear sits under Clothing)
- Blog posts referencing other related blog posts
If any of your relationships sound like "this connects to another one of the same thing," that's this pattern.
What are the real relationships between your Collections?
Not sure how these should connect? Just tell me what you're picturing for how content shows up on the site, and I can help you reason through it.
Wait for their answer. Push gently on anything stated too loosely: "You said a Post has a Category, could it ever need more than one?" Also probe for two things that are easy to miss: whether more than two Collections connect to each other (not just simple pairs), and, for each relationship, where the connection will actually be selected from. If the learner describes needing to select the connection from both Collections, not just one, flag that this is the one case that genuinely needs a second field, since otherwise the relationship only works one way. If the learner describes what sounds like two separate Collections holding the same underlying kind of content, for example, a "Related Articles" Collection sitting alongside an "Articles" Collection, question that gently rather than accepting it as two Collections: ask whether this is really one Collection referencing itself, rather than two Collections that would end up duplicating structure. Confirm each rule explicitly before moving on.
Once the relationships are settled, add this callout:
💡 Check this before you build: reference and multi-reference fields have limits, and so do the nested Collection lists often used to display them. If your plan involves a lot of connected content, check the current reference field limits and nested Collection list limits before your agent builds.
Proceed to Step 6.
Step 6 — Content fields
📋 Let's start with content fields, the fields for what people actually see and engage with.
For example, if you're building a Blog Posts Collection, you'll probably need fields for:
- Title
- Body
- Summary
- Thumbnail image
One thing worth naming clearly: how you name a field matters. A field called Info tells your agent almost nothing. A field called Post Summary tells it exactly what to expect. We'll keep this in mind for every field we name from here on, including AEO fields in the next step.
Go Collection by Collection, not all at once. For each Collection, ask "What does [Collection] need?" and end the question with a concrete, field-shaped nudge tailored to that specific Collection: tangible nouns that map directly to a field (a description, a price, a hero image, a gallery, a stat), never thematic or moodboard language (vibe, scenery, feel). For example, for a Packages Collection: "Think about what someone sees on a Package page, the itinerary, the price, the photos." For a Destinations Collection: "Think about a destination name, a description of the golf scene there, a hero image, maybe a stat like average temperature, and a gallery of photos." Tailor the nudge to what's realistic for each specific Collection rather than reusing a generic list.
Wait for their answer on each Collection before moving to the next. If it seems thin relative to what they've described the Collection doing, ask if there's anything they may have missed, rather than assuming the list is complete. We're just starting with the known content here, AEO fields come next, so if they seem unsure whether this step covers everything, reassure them directly that this is intentional. Apply the naming standard from the callout above to any field they propose, and gently suggest a clearer name if one is vague, without turning it into its own detour. Once every Collection's content fields are settled, proceed to Step 7.
Step 7 — AEO fields
🔍 Now let's make sure this content can be found.
An answer engine can only work with what's on your public pages, it can't see how your Collection is set up behind the scenes. So fields like authorship, freshness, and related content aren't just nice to have, they're what gives an answer engine, and your own team, something real to work with. A few of these live in Collection settings and won't be obvious until you're setting up your Collection page template or a Collection list, so this is the right time to plan for them.
We're going to go through these one at a time. Ready?
Wait for confirmation, then proceed one field at a time.
Authorship. A dedicated author field, not just a name mentioned in the body, so it's something your site and your agent can actually reference. This matters for AEO because answer engines weight who's behind content as a trust signal, especially for advice-heavy content like travel or product recommendations. If it's not an obvious fit, tell me a bit about who creates your content and I can help you think it through, the way we would for a blog byline. Does this apply to any of your Collections?
Wait for their answer, then move to the next field. Ask about each of the following individually, not as one bundled list: freshness, related content, and metadata. For each field, open with one brief sentence on the mechanism, why an answer engine or reader actually cares, then one sentence inviting them to think it through together if it's not an obvious fit, before asking whether it applies. Keep this tight: two sentences of framing per field, not a paragraph. If they decline one, note that explicitly as a deliberate choice, not a silent skip, so it's clear in the final plan that it was considered and ruled out, not missed. As each field name comes up, briefly check that it's clear and specific, the same naming standard from Step 6, without making this its own separate question each time.
Freshness. A last-reviewed date, separate from publish date. This matters for AEO because content that can go stale (pricing, availability, details) needs a "still accurate as of" signal for both readers and answer engines, not just a publish date that ages indefinitely. Does this apply to any of your Collections?
Related Content. Reference fields connecting related items. This matters for AEO because it builds a clearer content graph, an answer engine can traverse related items to understand context and completeness, not just isolated pages. Does this apply to any of your Collections?
Metadata. Meta description and Open Graph image, the text and image that show up in search results and social shares, and often the exact text an answer engine pulls to summarize a page. This is a bigger decision than the other AEO fields, so lead with a brief recommendation rather than a flat either/or: explicit per-Collection fields give more control and are worth it for primary, conversion-driving Collections; Webflow's built-in Collection template SEO settings are usually enough for supporting content. Offer to work through which Collections are which together, rather than asking the learner to decide unprompted with no framing.
Step 8 — Field groups
🗂️ One more practical thing: organizing your fields.
As a Collection picks up more fields, field groups let you organize them into labeled sections directly in Collection settings.
For example, a Blog Posts Collection might group:
- Content: Summary, Body, Thumbnail
- SEO: Meta Description, Open Graph Image
Based on how many fields you're expecting, does this seem useful for any of your Collections, and would you like a recommendation for groupings?
Before this step, silently check whether any Collection in this plan involves extending an existing Ecommerce Products or SKUs collection on the connected site. Field groups aren't available on those, not even an empty group. Only surface this if it actually applies: "Since [Collection] is an Ecommerce collection, field groups aren't available there, we'll skip that step for it." For everyone else, say nothing and proceed with the step as written.
Wait for their answer. If they'd like a recommendation, group the fields already gathered using the same content/publishing/SEO-style logic shown in the example, based on what's actually been discussed for their Collections, not a generic template.
Step 9 — Anything else to plan for
📈 Before we lock this in, let's zoom out.
Is there anything about how this might grow or change that we haven't covered? A few examples of what that could look like: more contributors adding content later, a new content type you're not planning for yet but might need, or something you're genuinely not sure about and might want to revisit.
This is the place to flag it, even if you don't know yet what to do about it.
Wait for their answer. If what they raise is genuinely forward-looking or uncertain, carry it into the final plan and the generated skill as an explicit "things to revisit" note. If it's something concrete that changes a decision already made earlier in this conversation, offer to go back and adjust that part of the plan together now, rather than only logging it for later. If they have nothing to add, that's a fine answer too, don't press.
Step 10 — Completeness check (internal)
Before presenting anything to the learner, silently check the assembled plan against this list. Do not show this checklist to the learner.
- Every Collection has a clear, stated purpose
- Every relationship is written as a plain-language rule, with cardinality (one or several) and direction explicit
- Option field candidates were checked against Webflow's real criteria, needing their own content, needing reuse across Collections, or needing multiple selections, not accepted automatically
- Self-reference was considered wherever a Collection seemed to connect to its own kind
- Field and Collection names are clear and specific, not vague
- Each AEO field category was explicitly asked about, and anything declined is noted as a deliberate choice, not silently omitted
- Field groups are addressed, even if the answer is "not needed yet," and Ecommerce exclusions are noted where relevant
- If the site has secondary locales, multi-locale needs were addressed for every Collection, not just mentioned once in passing
- Anything flagged in Step 9 is either reflected in an updated decision or captured as an explicit revisit note
- If anything above is missing, go back and ask before proceeding, don't fill it in on the learner's behalf
Step 11 — Present the plan for approval
✅ Here's your plan.
[Present the full assembled plan in this order: Collections and their purpose, relationships as plain-language rules (including any Option field decisions and self-references), content fields, AEO fields with what was included and what was deliberately left out, field groups, locale notes if applicable, and anything flagged in Step 9 as a note to revisit.]
If any Collections from Step 3 are being kept, extended, or newly created alongside existing ones, present an explicit table as part of the plan: which Collections will be newly created, and which are existing Collections being referenced or extended (with their real Collection ID). This is the visible safety checkpoint for the create-vs-reference logic that goes into Step 12, make sure the learner sees and confirms it here, not just buried in the generated skill.
If any Collection is genuinely being extended (not just kept as-is or newly created), add this as its own distinct checkpoint, separate from the general plan approval below:
🔍 One more explicit check, since this touches something that already exists.
Here's exactly what changes on [existing Collection name]: [list every addition and rename plainly, e.g. "Description renamed to Sub-headline (display name only, no type change). Three new fields: Customer name, Result/stat, Pull quote. Three new relationships: Reference to Plans, MultiReference to Features, self-referencing MultiReference for Related stories."]. Nothing here deletes or changes the type of anything already in this Collection, only additions and the rename noted above.
Confirm this is right before we lock in the full plan?
Wait for explicit confirmation on this specific callout before moving on, separate from the general "does this match" question below. Only proceed to Step 12 once both are confirmed. If no Collection is being extended, skip this checkpoint entirely and say nothing about it.
Take a moment to double-check the names too, both Collections and fields. Anything you'd want clearer before this becomes a skill?
This is a plan skeleton for you to confirm, not the skill itself. The generated skill will include much more than what's summarized above, exact field types, build sequencing, and detailed execution instructions your agent will actually follow, so what you're approving here is the shape of the plan, not the whole instruction set.
Does this match what you actually need, or is there anything to adjust before I generate your skill?
Wait for their response. Make any adjustments before proceeding. Do not generate the output skill until they've explicitly confirmed.
Step 12 — Generate the output skill
Once approved, generate a standalone markdown skill file. This is not the same document as the plan presented in Step 11: that plan was written for a person to read and approve. This file is written for an agent to execute, as clear, sequential, imperative instructions. Rewrite the approved plan into that form, don't copy it over as-is.
If the plan includes any Collections being kept or extended from Step 3, the generated skill's own collection-creation step must explicitly branch per Collection: Create new (call the create action) for genuinely new Collections, or Reference existing (skip creation entirely, use the real Collection ID captured during planning) for Collections being kept or extended. Never attempt to recreate a Collection that already exists. Reproduce the create-vs-reference table from Step 11 in the generated skill's own plan section, so it's visible to whoever executes it, not just implied.
The output skill must include, in this order:
- A brief orientation section, stating what this skill builds and confirming the plan was already reviewed and approved by the learner
- A summarize-before-executing check. If this skill is loaded in a new session, or by someone who wasn't part of the original planning conversation, it must first summarize the full plan back to whoever's reading it now, and confirm they're ready to proceed before taking any action
- The full custom plan, rewritten in agent-executable form, including any "things to revisit" notes from Step 9. Immediately after the plan's own verification step (confirming every Collection and field was built and reads back correctly), include a step offering to populate sample content:
- Default to one draft item per Collection, but stay flexible if the learner wants more or fewer.
- Clearly label each as a sample (e.g. a "SAMPLE — " prefix on the Name field).
- Create with
isDraft: trueand never publish sample content to the live site. - Chain relationships between the sample items wherever the plan has them, a sample item in one Collection referencing the sample item it would realistically connect to.
- After creating them, proactively offer to delete them once the learner is done reviewing, and note that deleting referenced items requires reverse dependency order (innermost referencing item first).
- Close with one line pointing to the wfu-migrate-cms companion skill as the next step for real content, not a full detour.
- The full technical execution backbone below, reproduced exactly as written. Do not summarize, compress, or paraphrase any part of it. This is fixed reference content, not a paraphrasing target, treat it the same way you'd treat boilerplate in a contract: copied whole, not rewritten
- A closing prompt offering to proceed with the build now, or stop here so the learner can review the file with their team first
Before presenting the generated file, silently confirm every item in the backbone below is present in the output, word for word. If anything was trimmed or reworded, fix it before delivering.
Deliver two things together, in the same response: a brief message to the learner confirming their skill is ready, built from the plan they just approved, and the actual generated skill file itself. Include a brief line letting the learner know that if the file doesn't appear right away, refreshing the thread usually resolves it.
Step 13 — Closing
📦 Your skill is ready.
This is a real, custom markdown skill, built around your actual Collections, fields, and relationships, not a generic template.
If you're ready now, we can start building together right here. Or, save the file and use it whenever you're ready: load it into your agent later, add it to a shared skills library, or send it to a teammate who needs to build this same structure.
Want to start building together right now, or would you rather save this for later?
If they want to build now, proceed step by step through the generated skill's execution backbone, plan-then-approve at each real action. If they want to save it for later, close warmly and remind them the file works the same way whenever, and wherever, they load it next.
Technical execution backbone
This entire section is reproduced verbatim into every generated output skill, per Step 12. It does not vary based on the learner's plan, it's the consistency and correctness guarantee across every skill this activity produces. Established against real, tested Webflow MCP behavior. Where this conflicts with a tool's own description, this wins.
Non-negotiable rules
-
Creating a Collection is irreversible through this skill. There is no delete-Collection action available via MCP, in any form, confirmed against the current Webflow MCP toolset. Removing a Collection requires a human working directly in Webflow itself, and only once the Collection has no items in it, so this isn't a permanent dead end, just not something this skill can do on its own. Always get explicit confirmation before creating a Collection. Never create a Collection just to try something out.
-
Field type and slug cannot be changed after creation. Only a field's display name, help text, and required status can be edited later. If a field's type needs to change, the only path is deleting that field and recreating it, which destroys that field's data across every item that had it. This is exactly why the planning done in this activity matters: get types right the first time.
-
Items are always created staged, never live. There's no action that creates a live item directly. Going live is always a separate, later step, either publishing specific items, or publishing the whole site, which publishes every staged item at once, not just the ones this workflow created.
-
A brand-new Collection must be published once before individual items in it can be published. Attempting to publish specific items in a Collection that's never been live returns a plain "not found" error with no further explanation. The fix is a one-time full site publish first; after that, publishing specific items works normally. Note that the same site publish will also publish anything else already staged at that moment, not just this Collection.
-
Never state plan limits as fact. There's no way to read a site's Collection or item limits through MCP. If limits come up, say plainly that they aren't available this way, and point to Webflow's own plan settings. Never state or imply a specific number.
-
If the site has secondary locales, every step must account for them. An item that exists only in one locale is invisible from every other locale, including the primary one. A secondary locale must be specified when an item is first created, there's no way to add a translation to an existing item afterward. Every read and write on a localized site needs to be locale-aware, not just the first one.
-
Verify every write by reading it back. Several actions return no useful confirmation at all on success. Never assume a write worked just because nothing errored, and never assume a write fully failed just because something did, some actions apply partially before throwing. Always re-check the actual state afterward.
-
Deleting items with incoming references requires reverse dependency order. An item still referenced by another item, via a Reference or MultiReference field, cannot be deleted; the API returns a conflict error naming exactly what's still referencing it. Delete in the reverse of the order dependencies were built in: delete the item that references others first, then work backward through the chain.
Field types
Use only these exact type names. A close guess still fails:
| Content | Use this type |
|---|---|
| Titles, short labels, long plain text | PlainText |
| Formatted body content | RichText |
| Single image | Image |
| Image gallery | MultiImage |
| Downloadable document | File |
| Video embed | VideoLink (not Video) |
| External URL | Link (not URL) |
| Email address | Email |
| Phone number | Phone |
| Numbers, counts, ratings | Number |
| Dates | DateTime (not Date) |
| On/off flags | Switch (not Boolean) |
| Brand or theme color | Color |
| Fixed set of choices | Option (not Dropdown or Select) |
| Connects to one item elsewhere | Reference |
| Connects to several items elsewhere | MultiReference |
Relationship mechanics
- The Collection being referenced must exist before the field pointing to it can be created. Always create referenced Collections first.
- A Collection can reference itself. This is a normal, supported pattern for hierarchy (a category with a parent category) or related-item connections (a post linking to related posts), and it is not automatically two-directional: connecting A to B does not automatically connect B to A.
- There is no hard-enforced cap on the number of multi-reference fields a Collection can have, but treat five as a practical, performance-minded ceiling rather than a technical one. Each multi-reference connection costs an extra lookup wherever it's displayed.
- Option fields are the right fit for a limited, predefined set of values used within a single Collection. Use a Collection instead when values need their own content, need to be reused across Collections, or need multiple selections at once.
- The MCP can create an Option field, but the field-update action doesn't support changing its option metadata. Adding or editing choices through an agent may need a different approach, recreating the field, or a manual edit directly in Webflow, rather than an in-place update.
- Option field values can be written using either their name or their underlying ID, but they can only ever be filtered or queried using the ID, never the name. Filtering by name silently returns zero results, with no error to indicate the mistake.
- A reference field's target must be checked against the correct Collection. A nonexistent ID and a valid ID from the wrong Collection can return the same error, confirm the target Collection directly rather than assuming from the error alone.
Field groups
- Field groups organize how fields are displayed in Collection settings. They don't affect the underlying data at all.
- When updating field groups, the full set of groups must be sent every time, this replaces the entire group configuration rather than adding to it. Omitting a group removes it.
- A Collection's built-in name and slug fields can never be included in a group.
- Field groups are not available on Ecommerce Collections at all, not even as an empty group.
- Field groups are capped at 50 per Collection, this is a real tool-level constraint, not a plan limit, and can be stated as fact.
Order of operations and batching
- Build in dependency order: referenced Collections and their items first, then the Collections and fields that point to them, then connect and populate.
- When creating many items at once, larger batches are fine for creating new items. For updating existing items, use smaller batches, since a single bad entry in an update batch can cause the entire batch to be discarded rather than just that one item.
- Before writing anything in bulk, validate what you're about to send. Creates typically fail as an all-or-nothing batch, one bad entry means nothing in that batch gets created.
Reporting and verification
- After any bulk action, re-check the actual current state rather than trusting the response alone. Some actions confirm exactly what happened; others confirm almost nothing.
- Report clearly what was actually created, updated, or connected, and flag anything that didn't go as expected rather than presenting the intended outcome as the actual one.
- If something was skipped, a locale, an item that failed validation, say so plainly rather than letting it pass silently.
- Newly created Collections or items may not appear immediately in Webflow's own interface. If the learner says they don't see something that was just created, suggest refreshing the page or tab before treating it as a failure.
Plan before every real action
Before creating, connecting, or populating anything, state the specific plan and wait for approval. Treat structure, connections, and content generation as three separate approval points, not one blanket approval covering everything.
Verify before connecting
For any reference or multi-reference field, confirm the relationship matches what was planned before finalizing the connection. Undoing a populated connection is difficult and can mean losing data.
Reference resources
- CMS Collections | The Webflow Way — general structuring guidance
- Option field overview
- Reference field overview
- Nest Collection lists
- Collection fields
- CMS Field Types & Item Values
- Webflow MCP server overview
Notes
This skill is a Webflow University resource designed to be distributed as a single .md file, attached to the Build & scale a CMS with MCP course, or shared as a standalone download, alongside its companion skill for migrating existing content.
It works best when participants have:
- An AI agent with Webflow MCP support
- The Webflow MCP authorized on the site they want to plan for
- A basic familiarity with Webflow Collections
The output of this activity is a second, separate skill file, generated fresh for each learner based on their own plan. That file is a single, self-contained markdown file: it can be loaded in a different session, a different agent, or by a different person entirely, and it will summarize itself and confirm readiness before taking any action.
Sponsors
Details
- Marketplace
- webflow/webflow-skills
- Source
- plugins/webflow-skills
- Author
- Webflow
- Category
- Productivity