webflow-code-component%3acomponent-audit（Webflow 代码 component 3acomponent 审核）

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

1. 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:

Audit my ProductCard component

Response:

## Audit: ProductCard

### Component Overview

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

---

### A. Prop Exposure Analysis

| Finding | Severity | Recommendation |
| --- | --- | --- |
| `imageUrl` is Text, not Image | Warning | Change to `props.Image()` for proper asset handling |
| "Add to Cart" button text is hardcoded | Suggestion | Expose as prop: `addToCartText: props.Text()` |
| Sale badge is conditionally rendered but not controllable | Suggestion | Add `showSaleBadge: props.Boolean()` |
| Badge color is hardcoded red | Suggestion | Add `badgeVariant: props.Variant({options: ["sale", "new", "featured"]})` |

**Hardcoded Content Found:**

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

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

**Recommended Props to Add:**

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

---

### B. State Management

| Finding | Severity |
| --- | --- |
| Uses `localStorage` for cart count | Warning |
| No React Context dependencies | OK |

**Issue: localStorage in render**

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

**Fix:**

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

---

### C. Slot Opportunities

| Current | Recommendation |
| --- | --- |
| Hardcoded button | Consider: `actions: props.Slot()` for flexible CTAs |

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

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

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

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

---

### D. Shadow DOM Compatibility

| Check | Status |
| --- | --- |
| Styles imported in.webflow.tsx | ✅ OK |
| CSS Modules used | ✅ OK |
| No global class references | ✅ OK |

---

### E. SSR Safety

| Check | Status |
| --- | --- |
| window usage | ✅ None |
| document usage | ✅ None |
| localStorage usage | ⚠️ Needs guard (see fix above) |

---

### F. Component Granularity

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

---

## Summary

| Category | Status |
| --- | --- |
| Designer Control | ⚠️ Needs work - 4 hardcoded items found |
| State Management | ⚠️ localStorage needs SSR guard |
| Shadow DOM | ✅ Good |
| SSR Safety | ⚠️ One issue |
| Granularity | ✅ Good |

**Priority Actions:**

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

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