Webflow Code Component:Component Audit

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.

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.

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.

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.

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.

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)

Webflow Compatibility

Architecture

Example

User prompt:

Copy code
Audit my ProductCard component

Response:

markdownCopy code
## Audit: ProductCard

### Component Overview

```typescript
// Current props
props: {
  title: props.Text(),
  price: props.Number(),
  imageUrl: props.Text()  // ⚠️ Should be Image
}

A. Prop Exposure Analysis

Hardcoded Content Found:

typescriptCopy code
// Line 24 - hardcoded, should be prop
<button>Add to Cart</button>

// Line 18 - hardcoded, should be prop or removed
{onSale && <span className="badge">SALE</span>}

Recommended Props to Add:

typescriptCopy code
props: {
  // ...existing
  addToCartLabel: props.Text({
    name: "Button Label",
    defaultValue: "Add to Cart"
  }),
  showBadge: props.Boolean({
    name: "Show Badge",
    defaultValue: false
  }),
  badgeType: props.Variant({
    name: "Badge Type",
    options: ["sale", "new", "featured"],
    defaultValue: "sale"
  })
}

B. State Management

Issue: localStorage in render

typescriptCopy code
// Line 8 - will break SSR
const cartCount = localStorage.getItem('cart');

Fix:

typescriptCopy code
const [cartCount, setCartCount] = useState(0);
useEffect(() => {
  setCartCount(parseInt(localStorage.getItem('cart') || '0'));
}, []);

C. Slot Opportunities

If designers need to put different content (button, link, custom element) in the action area:

typescriptCopy code
props: {
  actions: props.Slot({
    name: "Actions"
  })
}

// Component
<div className={styles.actions}>
  {actions}
</div>

However, if button behavior is tied to cart logic, keep it hardcoded.

D. Shadow DOM Compatibility

E. SSR Safety

F. Component Granularity

Current size: 4 props (will be 7 after recommendations) Verdict: Good granularity - single purpose, manageable props

Summary

Priority Actions:

1. Fix localStorage SSR issue (blocks deployment)
2. Change imageUrl from Text to Image prop
3. Expose badge controls as props
4. Consider exposing button label

Copy code

## Guidelines

### What This Audit Does NOT Check

This is not a generic code quality audit. Skip:
- Generic React performance patterns (let users use React DevTools)
- Generic accessibility (let users use axe or similar)
- Code formatting (let users use Prettier/ESLint)
- Generic TypeScript best practices

Focus only on Webflow-specific concerns.

### Prop Exposure Heuristics

**Should be a prop:**
- Any text visible in the UI
- Any image or media
- Any color or size that might vary
- Any boolean that controls visibility
- Any value that changes per-use

**Should NOT be a prop:**
- Internal implementation details
- State that changes during interaction
- Values derived from other props
- Animation timing/easing (unless explicitly customizable)

### When to Recommend Slots vs Props

**Use Slot when:**
- Designer wants to put arbitrary Webflow elements inside
- Content structure is flexible
- Nested content doesn't need to interact with component state

**Use Props when:**
- Content is simple (text, image, link)
- Component needs to process/transform the content
- Specific structure is required

### State Pattern Recommendations

If components need to share state, recommend in this order:
1. **URL parameters** - if state should be shareable/bookmarkable
2. **Nano stores** - for real-time sync between components
3. **Custom events** - for fire-and-forget communication
4. **Browser storage** - for persistence across sessions