Webflow Mcp:cms Best Practices

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

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:
<div>
  <text>Author: {{author.name}}</text> ← No collection context
</div>

✅ Correct:
<Collection List - Posts>
  <Collection Item>
    <text>Author: {{author.name}}</text> ← Inside collection context
  </Collection Item>
</Collection List>

Issue 4: Multi-Reference Display Error

Symptom: Only showing first item or nothing Diagnosis: Multi-reference needs nested collection list

Fix:

For Multi-Reference field (Post → Tags):

❌ Wrong: Direct binding
<text>Tags: {{post.tags}}</text>

✅ Correct: Nested collection list
<Collection List - Posts>
  <Collection Item - Post>
    <Collection List - Get Items from Post > Tags>
      <Collection Item - Tag>
        <text>{{tag.name}}</text>
      </Collection Item>
    </Collection List>
  </Collection Item>
</Collection List>

Issue 5: Deleted Referenced Item

Symptom: Reference field shows nothing despite being assigned Diagnosis: Referenced item was deleted from other collection

Fix:

1. Go to referring collection
2. Check reference field assignments
3. Re-assign to existing items
4. Or recreate deleted item

Prevention:

• Be careful when deleting referenced items
• Check "Used in X items" before deleting
• Archive instead of delete if possible

Issue 6: Collection Not Published

Symptom: Works in designer, not on live site Diagnosis: Referenced collection items are drafts

Fix:

1. Go to referenced collection (e.g., Authors)
2. Find draft items
3. Publish them
4. Republish main site

Check:

CMS Collections > Authors
- Look for "Draft" badge
- Publish all needed items
- Items must be published to display via reference

Step-by-Step Diagnostic

Step 1: Verify Collection Structure

Check in CMS:
1. Does the reference field exist?
2. Is it configured correctly (Reference or Multi-Reference)?
3. Is it pointing to the right collection?

Step 2: Verify Data Exists

Check collection items:
1. Open an item that should display
2. Check if reference field is populated
3. Verify referenced item exists and is published

Step 3: Verify Page Structure

Check in Designer:
1. Is element inside Collection List?
2. Is Collection List connected to correct collection?
3. Is element binding correct path?

Step 4: Test in Designer

In Designer:
1. Click Collection List
2. Set preview mode: "Item 1"
3. Cycle through items
4. Check if data appears

If it works in Designer but not live:
→ Publish issue (republish site)

Testing Reference Fields

Manual Test Checklist

• Create test item with reference populated
• Preview in Designer
• Check element binding path
• Publish and view live
• Verify all items display correctly
• Check items without references (should fail gracefully)

Common Binding Patterns

Single Reference (Author):

Collection List: Posts
Collection Item: Post
Element: Text Block
Binding: Get text from Post > author > name

Multi-Reference (Tags):

Collection List: Posts
Collection Item: Post
  Nested Collection List: Get items from Post > tags
  Collection Item: Tag
    Element: Text Block
    Binding: Get text from Tag > name

Self-Reference (Related Posts):

Collection List: Posts
Collection Item: Post (current)
  Nested Collection List: Get items from Post > related-posts
  Collection Item: Post (related)
    Element: Text Block
    Binding: Get text from Post > title

Prevention Tips

Best Practices:

1. Make critical references required

   • Required: Yes for author, category
   • Optional: Yes for tags, related items

2. Provide default content

   • If reference is empty, show "Uncategorized"
   • Use conditional visibility for optional references

3. Test with incomplete data

   • Create test items with missing references
   • Ensure graceful fallback

4. Document reference structure

   • Create guide for content editors
   • Explain which fields are required
   • Show how to assign references

5. Use descriptive field names

   • ❌ "ref-1", "link"
   • ✅ "author", "primary-category", "related-posts"

Quick Fixes by Symptom

Would you like me to walk through your specific setup to diagnose the exact issue? I can:

• Review your collection structure
• Check your reference field configuration
• Analyze your page layout
• Test your data bindings
• Provide custom troubleshooting

Let me know what you'd like me to check!

## Guidelines

### Phase 1: Discovery Best Practices

**Always Start With:**
1. **Identify plan limits** - Use `data_sites_tool` with action `get_site` to check collection/item limits
2. **Analyze existing structure** - List collections before recommending changes
3. **Understand content volume** - Check item counts to assess scale
4. **Review current pages** - See how content is currently displayed
5. **Ask clarifying questions** - Don't assume requirements

**Plan Limits Reference:**

Starter Plan:

• Collections: 1
• Items per collection: 50
• CMS pages: 50

Basic Plan:

• Collections: 2
• Items total: 200
• CMS pages: 150

CMS Plan:

• Collections: 20
• Items total: 2,000
• CMS pages: 2,000

Business Plan:

• Collections: 40
• Items total: 10,000
• CMS pages: 10,000

Enterprise Plan:

• Custom limits

**Key Questions to Ask:**
1. "What content needs to be managed?" (identify collections)
2. "Who will update the content?" (determine complexity level)
3. "How will content be displayed?" (affects fields and relationships)
4. "What's the expected content volume?" (plan for scale)
5. "Are there any special requirements?" (unique features, integrations)

### Phase 2: Field Selection Best Practices

**Field Type Selection Matrix:**

**For Text Content:**
- **<50 characters:** Plain Text (single line)
- **50-256 characters:** Plain Text (multi-line)
- **Need formatting:** Rich Text
- **Pure data (no display):** Plain Text (validation enabled)

**For Relationships:**
- **One parent:** Reference (e.g., Post → Author)
- **Multiple parents:** Multi-Reference (e.g., Post → Tags)
- **Self-referencing:** Reference to same collection (e.g., Category → Parent Category)

**For Media:**
- **Hero images:** Image field (1 image)
- **Galleries:** Multi-image field (up to 25 images)
- **Documents:** File field (PDFs, docs)
- **Videos:** Video field (YouTube/Vimeo embeds)

**For Metadata:**
- **Dates:** Date/Time field
- **Numbers:** Number field (prices, counts, ratings)
- **Colors:** Color field (brand colors, theme colors)
- **Switches:** Boolean field (featured, published, active)

**Field Naming Conventions:**

✅ Good Names:

• published-date (descriptive, hyphenated)
• author (clear purpose)
• main-image (specifies which image)
• post-summary (explains use case)

❌ Bad Names:

• date1 (unclear which date)
• img (which image?)
• text (what kind of text?)
• field1 (no meaning)

**Required vs Optional:**

Make REQUIRED:

• name (unique identifier)
• slug (URL generation)
• primary relationships (author, category)
• publish date (for sorting)

Make OPTIONAL:

• tags (not always applicable)
• secondary images
• advanced metadata
• related items

### Phase 3: Relationship Design Best Practices

**One-to-Many Guidelines:**

Use when:

• Each item has exactly ONE parent
• Parent data is reused across many items
• You want centralized data management

Examples: ✅ Post → Author (each post has one author) ✅ Product → Brand (each product has one brand) ✅ Event → Venue (each event has one venue)

Don't use when: ❌ Item can have multiple parents (use multi-reference) ❌ Relationship is temporary (consider option field) ❌ Data is simple and rarely changes (use option field instead)

**Many-to-Many Guidelines:**

Use when:

• Items can have multiple relationships
• Relationships need to be managed separately
• You want flexible cross-linking

Examples: ✅ Post ↔ Tags (posts have many tags, tags apply to many posts) ✅ Product ↔ Features (products have many features, features apply to many products) ✅ Course ↔ Topics (courses cover many topics, topics span many courses)

Remember: ⚠️ Max 5 multi-reference fields per collection ⚠️ Can only filter by ONE multi-reference at a time ⚠️ Cannot sort by referenced field values ⚠️ Performance impact (more queries)

**Self-Reference Guidelines:**

Use when:

• Building hierarchies (categories, menu structure)
• Related items from same collection
• Organizational trees

Implementation:

• Add Reference field pointing to same collection
• Name it clearly: parent-category, related-posts
• Limit depth to 2-3 levels for practical display
• Consider adding "level" number field for easier filtering

Example Structure: Categories: ├── Web Development (level 1, parent: null) │ ├── Frontend (level 2, parent: Web Development) │ └── Backend (level 2, parent: Web Development) └── Design (level 1, parent: null)

### Phase 4: Architecture Patterns

**Common Collection Patterns:**

**1. Blog Architecture:**

Minimal (1 collection):

• Blog Posts

Standard (3 collections):

• Blog Posts
• Authors
• Categories

Advanced (5+ collections):

• Blog P

…(truncated)