/component-audit

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