webflow-code-component:component-audit
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.
webflow · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add webflow/webflow-skills --skill webflow-code-component: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:
- Designer Control: Are the right things exposed as props for designers to customize?
- Webflow Compatibility: Does the component work within Webflow's constraints (Shadow DOM, SSR, isolated React roots)?
- Component Architecture: Is this the right level of granularity, or should it be split/combined?
Instructions
Phase 1: Discovery
-
Find all components:
- Locate webflow.json
- Find all .webflow.tsx files
- Read corresponding React components
-
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.jsonfor 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 |