Transform Your Workflow

..." 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_tool` with action `list_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: 1. **Structured (JSON-like):** ``` CREATE: - name: "Post Title" slug: "post-slug" featured: true ``` 2. **Natural Language:** ``` "Add a blog post called 'Getting Started' with slug 'getting-started'" ``` 3. **CSV-style:** ``` name,slug,featured "Post 1","post-1",true "Post 2","post-2",false ``` 4. **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 `name` or `slug` parameters 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:** - `name` and `slug` are 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 `*_live` endpoints (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:** ```json { "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 --- ## 4. webflow-mcp:cms-best-practices - **Source:** https://github.com/webflow/webflow-skills/blob/main/plugins/webflow-skills/skills/cms-best-practices/SKILL.md - **Raw:** https://raw.githubusercontent.com/webflow/webflow-skills/main/plugins/webflow-skills/skills/cms-best-practices/SKILL.md - **Markdown:** https://skillsdocs.com/webflow/webflow-skills/cms-best-practices.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: webflow-mcp:cms-best-practices description: Expert guidance on Webflow CMS architecture and best practices. Use when planning collections, setting up relationships, optimizing content structure, or troubleshooting CMS issues. --- # 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_tool` to get best practices before starting - Use Webflow MCP's `data_sites_tool` with action `list_sites` to identify available sites - Use Webflow MCP's `data_sites_tool` with action `get_site` to retrieve site details and plan limits - Use Webflow MCP's `data_cms_tool` with action `get_collection_list` to analyze existing collections - Use Webflow MCP's `data_cms_tool` with action `get_collection_details` to examine collection schemas - Use Webflow MCP's `data_cms_tool` with action `list_collection_items` to assess content volume - Use Webflow MCP's `data_pages_tool` with action `list_pages` to understand page structure - Use Webflow MCP's `ask_webflow_ai` for specific API questions - DO NOT use any other tools or methods for Webflow operations - All tool calls must include the required `context` parameter (15-25 words, third-person perspective) ## Instructions ### Phase 1: Discovery & Analysis 1. **Identify the request**: Determine if user is: - Planning new CMS structure - Optimizing existing collections - Troubleshooting performance issues - Setting up relationships - Seeking architecture guidance 2. **Get site information**: Use Webflow MCP's `data_sites_tool` with actions `list_sites` and `get_site` to understand plan limits 3. **Analyze existing structure**: Use Webflow MCP's `data_cms_tool` with actions `get_collection_list` and `get_collection_details` to examine current setup 4. **Assess content volume**: Use Webflow MCP's `data_cms_tool` with action `list_collection_items` to understand scale 5. **Review pages**: Use Webflow MCP's `data_pages_tool` with action `list_pages` to see how content is displayed ### Phase 2: Requirements Gathering 6. **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? 7. **Identify constraints**: Consider plan limits, technical constraints, team skills 8. **Define success criteria**: Performance goals, editorial workflow, scalability needs ### Phase 3: Architecture Planning 9. **Design collection structure**: Plan collections, fields, and relationships 10. **Select field types**: Choose appropriate field types for each content element 11. **Plan relationships**: Design one-to-many and many-to-many connections 12. **Consider taxonomy**: Determine categories, tags, and organizational structure 13. **Plan for scale**: Design for growth (pagination, performance, limits) 14. **Document decisions**: Explain tradeoffs and reasoning ### Phase 4: Recommendations & Validation 15. **Generate recommendations**: Provide specific, actionable guidance 16. **Prioritize changes**: Organize by impact (quick wins vs. long-term) 17. **Explain tradeoffs**: Help users understand limitations and workarounds 18. **Validate against best practices**: Check against Webflow limitations and patterns 19. **Provide alternatives**: Offer multiple approaches when applicable 20. **Create implementation roadmap**: Break down into phases ### Phase 5: Implementation Guidance 21. **Provide step-by-step instructions**: Clear guidance for implementation 22. **Offer to assist**: Suggest using other skills (cms-collection-setup, bulk-cms-update) 23. **Document structure**: Recommend documentation for team reference 24. **Suggest testing approach**: Guide on how to validate changes 25. **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 | Email | 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:** 1. Create combined tags (e.g., "vegan-gluten-free") 2. Use Finsweet CMS Filter for client-side filtering 3. Create separate filtered collection lists for common combinations 4. 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:** 1. Use tags for automatic "related by tag" logic 2. Manual curation for most important connections 3. 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: 1. Create these collections using cms-collection-setup skill 2. Add initial content using bulk-cms-update skill 3. Build the page structure 4. 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:** 1. Too many items loaded at once 2. Possibly too many reference field lookups 3. Large unoptimized images 4. No pagination or lazy loading 5. 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:** 1. Select your Collection List 2. Settings > Limit items: 20 3. Enable "Paginate items" 4. 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:** 1. Collection List Settings 2. Add Filter: [field] [condition] [value] 3. 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:** 1. **Test on staging:** - Publish to staging domain first - Verify pagination works - Check image quality - Test all filters 2. **Performance testing:** - Use Google PageSpeed Insights - Test on mobile (3G/4G) - Check Lighthouse scores - Verify Core Web Vitals 3. **User testing:** - Navigate through pages - Test search/filter - Check mobile experience - Verify no broken links 4. **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):** 1. Pagination (20 items per page) 2. Optimize images (thumbnails) 3. 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:** 1. Select the element (text, image, etc.) 2. Settings panel > Get text/image from [Collection Item] 3. Select your reference field 4. 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:** 1. Go to CMS Collections 2. Open your collection 3. Check items that aren't displaying 4. 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:

Author: {{author.name}} ← No collection context

Author: {{author.name}} ← Inside collection context

Tags: {{post.tags}}

Tags> {{tag.name}}

Tags: tags> {{tag.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/ - **bundleConfig** (optional): Path to custom webpack configuration **Component Naming Convention:** - Add `.webflow` before 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:** ```bash # 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:** ```bash # 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 ` - Override output directory (default: `./dist`) - `--public-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: 1. Browser will open 2. User authenticates with Webflow 3. User selects target workspace 4. CLI creates .env with credentials 5. Future shares use these credentials (no re-auth) ### Phase 5: Deployment Execution **Share Command:** ```bash # Standard share (interactive) webflow library share # Non-interactive (for CI/CD) webflow library share --api-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:** 1. Check CLI output for success message 2. Verify .env file created (first time) 3. Provide Designer access instructions 4. Show workspace dashboard URL ### Phase 6: Debugging **Log Command:** ```bash # 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:** 1. Create/have React project 2. Add webflow.json with library configuration 3. Name component files (e.g., .webflow.tsx) 4. Build: `npm run build` 5. Test bundle: `webflow library bundle` 6. Share: `webflow library share` (authenticates first time) **Making Updates:** 1. Edit component source files 2. Build: `npm run build` 3. Share: `webflow library share` (uses saved credentials) 4. Refresh Designer to see changes **Testing:** 1. Bundle locally: `webflow library bundle` 2. Check bundle size and validation 3. Fix any issues 4. Share when ready: `webflow library share` 5. Open Webflow Designer 6. Add components to page 7. Test functionality **Debugging:** 1. View logs: `webflow library log` 2. Bundle with verbose: `webflow library bundle --verbose` 3. Check configuration: cat webflow.json 4. Verify build: npm run build 5. Test in development mode: `webflow library share --dev` ### CLI Command Reference **Installation:** ```bash # Install CLI globally npm install -g @webflow/webflow-cli # Verify installation webflow --version ``` **Library Commands:** ```bash # 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:** ```bash # 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:** ```bash # Standard interactive share webflow library share # Non-interactive (CI/CD) webflow library share --no-input --api-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:** ```bash # 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 testing - `webflow library share` - Bundle and deploy to workspace - `webflow 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 --- ## 7. webflow-code-component:component-audit - **Source:** https://github.com/webflow/webflow-skills/blob/main/plugins/webflow-skills/skills/component-audit/SKILL.md - **Raw:** https://raw.githubusercontent.com/webflow/webflow-skills/main/plugins/webflow-skills/skills/component-audit/SKILL.md - **Markdown:** https://skillsdocs.com/webflow/webflow-skills/component-audit.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: webflow-code-component:component-audit description: Audit Webflow Code Components for architecture decisions - prop exposure, state management, slot opportunities, and Shadow DOM compatibility. Focused on Webflow-specific patterns, not generic React best practices. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: author: webflow version: "2.0" --- # 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: 1. **Designer Control**: Are the right things exposed as props for designers to customize? 2. **Webflow Compatibility**: Does the component work within Webflow's constraints (Shadow DOM, SSR, isolated React roots)? 3. **Component Architecture**: Is this the right level of granularity, or should it be split/combined? ## Instructions ### Phase 1: Discovery 1. **Find all components**: - Locate webflow.json - Find all .webflow.tsx files - Read corresponding React components 2. **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.json` for 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: 1. **Summary**: Quick overview of findings 2. **By Component**: Specific issues and recommendations for each 3. **Architecture Recommendations**: Cross-cutting concerns 4. **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:** ```markdown ## 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:** ```typescript // Line 24 - hardcoded, should be prop

{isOpen && (

)}

); }; ``` **Generated Accordion.webflow.tsx:** ```typescript 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: "

Accordion content goes here.

" }), 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: ```typescript props: { title: props.Text({ name: "Title", defaultValue: "Card Title" // ✅ Good }), count: props.Number({ name: "Count", defaultValue: 0 // ✅ Good }) } ``` Not: ```typescript 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) ``` --- ## 9. webflow-code-component:convert-component - **Source:** https://github.com/webflow/webflow-skills/blob/main/plugins/webflow-skills/skills/convert-component/SKILL.md - **Raw:** https://raw.githubusercontent.com/webflow/webflow-skills/main/plugins/webflow-skills/skills/convert-component/SKILL.md - **Markdown:** https://skillsdocs.com/webflow/webflow-skills/convert-component.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html Bundled files (1), referenced from this skill's directory: - `references/prop-types.md` — https://raw.githubusercontent.com/webflow/webflow-skills/main/plugins/webflow-skills/skills/convert-component/references/prop-types.md --- name: webflow-code-component:convert-component description: Convert an existing React component into a Webflow Code Component. Analyzes TypeScript props, maps to Webflow prop types, generates the .webflow.tsx definition file, and identifies required modifications. compatibility: Node.js 18+, React 18+, TypeScript, @webflow/webflow-cli metadata: author: webflow version: "1.0" --- # 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 1. **Read the React component file**: Get the full source code 2. **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` 3. **Identify incompatible patterns**: | Pattern | Issue | Resolution | |---------|-------|------------| | React Context usage | Context doesn't work across Webflow components | Refactor to props or use nano stores | | `window`/`document` in render | SSR will fail | Wrap in useEffect or set `ssr: false` | | `localStorage`/`sessionStorage` in render | SSR will fail | Wrap in useEffect or set `ssr: false` | | Complex object props | Can't map to Webflow prop types | Break into individual props | | Function props (callbacks) | Not supported in Webflow | Remove or internalize logic | | `useContext` hook | Won'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 | 4. **Detect styling approach** and note required setup: **If using styled-components:** ```bash npm i @webflow/styled-components-utils styled-components ``` Create/update `globals.ts`: ```typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator]; ``` **If using Emotion:** ```bash npm i @webflow/emotion-utils @emotion/cache @emotion/react ``` Create/update `globals.ts`: ```typescript import { emotionShadowDomDecorator } from "@webflow/emotion-utils"; export const decorators = [emotionShadowDomDecorator]; ``` **For both CSS-in-JS approaches**, update `webflow.json`: styled-components: ```json { "library": { "globals": "./src/globals.ts", "renderer": { "server": "@webflow/styled-components-utils/server" } } } ``` Emotion: ```json { "library": { "globals": "./src/globals.ts", "renderer": { "server": "@webflow/emotion-utils/server" } } } ``` 5. **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 6. **Apply TypeScript → Webflow prop type mapping**: | TypeScript Type | Webflow Prop | Notes | |-----------------|--------------|-------| | `string` | `props.Text()` | Default for short text | | `string` (long/HTML content) | `props.RichText()` | If prop name suggests content/body/description | | `React.ReactNode` / `children` | `props.Slot()` | For nested content | | `number` | `props.Number()` | Numeric values | | `boolean` | `props.Boolean()` | Toggles | | `"option1" \| "option2"` | `props.Variant()` | String literal unions (requires `options` array) | | `enum` | `props.Variant()` | Convert enum values to `options` array (required) | | `{ href: string; ... }` | `props.Link()` | Returns `{ href, target?, preload? }` object — may need wrapper if component expects separate `href`/`target` props | | Image-related types | `props.Image()` | Image src, url, etc. | | `string` (canvas-editable text) | `props.TextNode()` | For text editable directly on canvas; has `multiline` param | | `boolean` (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 | 7. **Handle special cases**: **Complex object props** - Break them down: ```typescript // 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**: ```typescript // 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 props ``` **Optional props** - Provide defaultValue for prop types that support it. Note: Link, Image, Slot, and Id do not accept defaultValue. ```typescript // 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 8. **Verify Webflow setup exists**: - Check for `webflow.json` in 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 9. **Determine file locations**: - Identify where the original component lives - Determine where `.webflow.tsx` should be created (same directory) - Check for existing styles that need to be imported ### Phase 4: Generate Definition File 10. **Create the `.webflow.tsx` file**: ```typescript 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 } }); ``` 11. **Provide the complete file** with all props mapped ### Phase 5: Document Required Changes 12. **List modifications needed** to the original component: ```markdown ## 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 | ``` 13. **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 = ({ quote, authorName, authorTitle = "", rating = 5 }) => { return (

{"★".repeat(rating)}

{quote}

{authorName} {authorTitle && {authorTitle}}

); }; ``` **Response:** ```markdown ## 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 1. **Convert to CSS Modules** - Rename `TestimonialCard.css` to `TestimonialCard.module.css` and update imports: ```typescript import styles from "./TestimonialCard.module.css"; // Default CSS Modules uses bracket notation:

// 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 (

{trigger}

{isOpen && (

e.stopPropagation()}> {children}

)} ); }; ``` **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 ```typescript 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 ```typescript 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 = ({ 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 ( <>

{trigger}

{isOpen && (

e.stopPropagation()}> {children}

)} ); }; ``` ### Setup Required ```bash 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) => (

{showBadge && {product.category}}

{product.name}

${product.price}

); ``` **Response:** ```markdown ## 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 ```typescript 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) => (

{productImage && ( {productImage.alt

)} {showBadge && {productCategory}}

{productName}

${productPrice.toFixed(2)}

); ``` ### Migration Notes: - The `product` object has been flattened into individual props - Each prop is now directly editable in Webflow Designer - `product.id` was 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`:** ```typescript import { styledComponentsShadowDomDecorator } from "@webflow/styled-components-utils"; export const decorators = [styledComponentsShadowDomDecorator]; ``` **3. Update `webflow.json`:** ```json { "library": { "name": "My Library", "components": ["./src/**/*.webflow.@(js|jsx|mjs|ts|tsx)"], "globals": "./src/globals.ts" } } ``` --- ## Generated Files ### Button.webflow.tsx ```typescript 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 --- ## 10. webflow-mcp:custom-code-management - **Source:** https://github.com/webflow/webflow-skills/blob/main/plugins/webflow-skills/skills/custom-code-management/SKILL.md - **Raw:** https://raw.githubusercontent.com/webflow/webflow-skills/main/plugins/webflow-skills/skills/custom-code-management/SKILL.md - **Markdown:** https://skillsdocs.com/webflow/webflow-skills/custom-code-management.md - **Licence:** MIT — https://spdx.org/licenses/MIT.html --- name: webflow-mcp:custom-code-management description: Add, review, or remove inline custom scripts on a Webflow site (up to 10,000 chars). Use for analytics, tracking pixels, chat widgets, or any custom JavaScript. Also manages page-level scripts. --- # 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_tool` to get best practices **before any other tool call** - Use Webflow MCP's `data_sites_tool` with action `list_sites` to identify available sites - Use Webflow MCP's `data_scripts_tool` with action `list_registered_scripts` to list all registered scripts - Use Webflow MCP's `data_scripts_tool` with action `list_applied_scripts` to list scripts applied to pages - Use Webflow MCP's `data_scripts_tool` with action `add_inline_site_script` to register a new inline script - Use Webflow MCP's `data_scripts_tool` with action `delete_all_site_scripts` to remove ALL site scripts (no selective delete) - Use Webflow MCP's `data_scripts_tool` with action `get_page_script` to get custom code for a specific page - Use Webflow MCP's `data_scripts_tool` with action `upsert_page_script` to add or update page-level custom code - Use Webflow MCP's `data_scripts_tool` with action `delete_all_page_scripts` to remove all custom code from a page - All tool calls must include the required `context` parameter (15-25 words, third-person perspective) ## Instructions ### Phase 1: Discovery 1. **Call `webflow_guide_tool` first** — always the first MCP tool call 2. **Get the site**: Use `data_sites_tool` with action `list_sites`. If only one site, use it automatically. ### Phase 2: Analysis 3. **List scripts**: Call `list_registered_scripts` and `list_applied_scripts` in parallel 4. **Check page-level scripts** (if relevant): Use `get_page_script` for specific pages 5. **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 6. **Add site script**: `add_inline_site_script` with displayName, sourceCode, version, location, canCopy 7. **Remove all site scripts**: `delete_all_site_scripts` 8. **Add/update page script**: `upsert_page_script` 9. **Remove page scripts**: `delete_all_page_scripts` ### Phase 5: Verification 10. Re-list scripts to confirm success 11. Report what changed (name, location, version, char count) 12. Remind user to publish — suggest using `safe-publish` skill ## Examples ### Example 1: View scripts **User:** "What scripts are on my site?" 1. `webflow_guide_tool` → `data_sites_tool` → `list_registered_scripts` + `list_applied_scripts` in parallel 2. Present summary of all scripts ### Example 2: Add Google Tag Manager **User:** "Add GTM to my site" 1. `webflow_guide_tool` → `data_sites_tool` → ask for GTM container ID 2. Preview script, require "add" → `add_inline_site_script` (header, version "1.0.0") 3. Verify and remind to publish ### Example 3: Remove all scripts **User:** "Remove all scripts" 1. `webflow_guide_tool` → `data_sites_tool` → list current scripts 2. Warn: removes ALL scripts. Require "delete all" → `delete_all_site_scripts` 3. Verify and remind to publish ### Example 4: Page-specific tracking **User:** "Add conversion tracking to my thank-you page" 1. `webflow_guide_tool` → `data_sites_tool` → `get_page_script` to check existing 2. Preview, require "update" → `upsert_page_script` 3. Verify and remind to publish ## Guidelines - **`webflow_guide_tool` always first** — before any other MCP tool - **No `

Subsection

Title

Our Services

Welcome

The Future is Here

Transform Your Workflow

{product.name}

{productName}