webflow-code-component:component-audit

组件审计

审计现有代码组件中的 Webflow 专属架构决策。此技能关注组件与 Webflow Designer 的集成效果，而非通用的 React 最佳实践。

何时使用此技能

适用场景：

• 用户希望改进组件在 Webflow Designer 中的表现
• 检查应将哪些内容公开为属性，而不是硬编码
• 检查状态管理模式是否兼容 Webflow
• 寻找让组件更便于设计师使用的机会
• 组件未按预期渲染或运行

不适用场景：

• 部署前验证（使用 pre-deploy-check）
• 创建新组件（使用 component-scaffold）
• 转换 React 组件（使用 convert-component）
• 通用代码质量审查（使用代码检查工具）

核心理念

此审计回答三个问题：

1. 设计师控制权：是否将合适的内容公开为属性，供设计师自定义？
2. Webflow 兼容性：组件能否在 Webflow 的限制条件下正常运行（Shadow DOM、SSR、隔离的 React 根节点）？
3. 组件架构：组件的粒度是否合适，还是应该拆分或合并？

说明

阶段 1：发现

1. 查找所有组件：

   • 定位 webflow.json
   • 查找所有 .webflow.tsx 文件
   • 阅读对应的 React 组件

2. 了解意图：询问用户组件的用途以及具体顾虑

阶段 2：分析

针对每个组件，分析以下 Webflow 专属方面：

A. 属性公开分析

目标：找出设计师应该能够控制、但目前无法控制的内容。

检查项	建议
硬编码的文本字符串	公开为 props.Text()
设计师应能在画布上编辑的文本	公开为 props.RichText()
从固定选项集中硬编码的值	公开为 props.Variant({ options: [...] })
硬编码的图片 URL	公开为 props.Image()
硬编码的链接 URL	公开为 props.Link()
硬编码的 HTML id 属性	公开为 props.Id()
使用布尔值进行条件渲染	公开为 props.Boolean() 或 props.Visibility()
会影响外观的内部状态	考虑将初始值公开为属性
未使用 Slot 的 children	转换为 props.Slot()

别名： props.String = props.Text，props.Children = props.Slot。审计时将它们视为等价项。

要提出的问题：

• “设计师会想修改什么？”
• “哪些内容需要进行本不该需要的代码修改？”

B. 状态管理架构

目标：找出无法在 Webflow 中正常运行的模式。

反模式	失效原因	替代方案
使用 React Context 管理跨组件状态	每个组件都有独立的 React 根节点	使用 nano stores、自定义事件或 URL 参数
通过 Slots 逐层传递属性	Slot 子项是独立的 React 应用	使用 nano stores 或自定义事件
通过模块级变量共享状态	可能导致 SSR 问题	使用浏览器存储或 nano stores
未清理的全局事件监听器	内存泄漏、SSR 问题	使用带清理逻辑的 useEffect

重构建议：

• 如果组件需要通信 → 建议使用跨组件状态模式
• 如果仅在内部使用 Context → 没问题，请记录说明
• 如果组件紧密耦合 → 建议拆分组件

C. 插槽机会

目标：找出应由设计师控制的硬编码内容。

当前模式	更好的模式
卡片内硬编码的按钮	为操作区域设置插槽
硬编码的图标组件	使用插槽或 Image 属性
固定的页眉/页脚结构	为页眉和页脚设置插槽
硬编码的列表项	考虑是否应将其拆分为多个组件

不应使用插槽的情况：

• 内容有特定的行为要求
• 内容需要与组件状态交互
• 结构确实固定且不可自定义

D. Shadow DOM 兼容性

目标：确保样式在隔离环境中正常工作。

问题	检测方法	修复方法
使用站点/全局 CSS 类	类名如 .container、.btn	使用 CSS Modules 或组件作用域样式
未配置 CSS-in-JS	使用 styled-components/Emotion，但没有装饰器	添加 globals.ts，并使用 styledComponentsShadowDomDecorator（styled-components）或 emotionShadowDomDecorator（Emotion/MUI）
缺少样式导入	已定义样式，但未在 .webflow.tsx 中导入	添加导入语句
依赖继承样式	预期父级样式会层叠应用	使用显式样式或 CSS 变量
需要标签选择器（h1、p 等）	Shadow DOM 内的标签未设置样式	在组件选项中启用 applyTagSelectors: true

SSR 说明： 使用 styled-components 或 Emotion 时，还必须在 webflow.json 中配置服务器渲染器，才能确保 SSR 正常工作：

• styled-components："library": { "renderer": { "server": "@webflow/styled-components-utils/server" } }
• Emotion："library": { "renderer": { "server": "@webflow/emotion-utils/server" } }

E. SSR 安全性

目标：找出在渲染期间运行的仅限浏览器的代码。

模式	问题	解决方案
在渲染中使用 window.innerWidth	SSR 错误	使用 useEffect 或设置 ssr: false
在渲染中使用 document.getElementById	SSR 错误	使用 useEffect 或 refs
在 useEffect 之外使用 localStorage.getItem	SSR 错误	用 useEffect 和 useState 包装
需要 window 的第三方库	SSR 错误	动态导入或设置 ssr: false

F. 组件粒度

目标：判断组件抽象层级是否合适。

组件应拆分的迹象：

• 属性过多（>10），导致 Designer 界面杂乱
• 包含多个可独立存在的不同部分
• 设计师希望单独使用其中的部分
• 组件处理多个互不相关的问题

组件应合并的迹象：

• 总是一起使用
• 状态紧密耦合，难以同步
• 组件很小，无法独立使用

第 3 阶段：报告

生成可执行的报告，包含：

1. 摘要：快速概述调查结果
2. 按组件分类：每个组件的具体问题和建议
3. 架构建议：跨组件的问题
4. 优先处理事项：首先要修复的内容

审计清单

设计师控制（对 Webflow 最重要）

检查项	问题
属性完整性	设计师能否自定义他们想要的所有内容？
属性类型	是否使用了正确的 Webflow 属性类型？
默认值	属性是否有合理的默认值？
属性命名	非开发人员是否能看懂名称？
插槽用法	嵌套内容是否通过插槽处理？
可见性属性	能否显示/隐藏各个部分？

Webflow 兼容性

检查项	问题
SSR 安全	组件是否无需浏览器 API 即可渲染？
样式隔离	样式在 Shadow DOM 中是否正常工作？
状态独立性	组件能否在没有父级 Context 的情况下工作？
无函数属性	是否存在无法使用的回调属性？

架构

检查项	问题
单一职责	组件是否能出色地完成一件事？
合适的粒度	这是否是适合 Designer 使用的大小？
跨组件状态	如果需要，是否正确实现？

示例

用户提示词：

Audit my ProductCard component

响应：

## Audit: ProductCard

### Component Overview

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

---

A. 属性暴露分析

发现	严重性	建议
imageUrl 是 Text，而不是 Image	警告	改为 props.Image()，以便正确处理资源
“Add to Cart” 按钮文本是硬编码的	建议	暴露为属性：addToCartText: props.Text()
Sale 徽标是有条件渲染的，但无法控制	建议	添加 showSaleBadge: props.Boolean()
徽标颜色被硬编码为红色	建议	添加 badgeVariant: props.Variant({ options: ["sale", "new", "featured"] })

发现的硬编码内容：

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

建议添加的属性：

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. 状态管理

发现	严重性
使用 localStorage 保存购物车数量	警告
没有 React Context 依赖	正常

问题：在渲染期间使用 localStorage

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

修复：

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

---

C. 插槽机会

当前情况	建议
硬编码的按钮	可以考虑使用 actions: props.Slot()，以灵活配置 CTA

如果设计师需要在操作区域放入不同内容（按钮、链接、自定义元素）：

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

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

不过，如果按钮行为与购物车逻辑绑定，请保留硬编码方式。

---

D. Shadow DOM 兼容性

检查项	状态
在 .webflow.tsx 中导入样式	✅ 正常
使用 CSS Modules	✅ 正常
没有全局类引用	✅ 正常

---

E. SSR 安全性

检查项	状态
window 使用情况	✅ 无
document 使用情况	✅ 无
localStorage 使用情况	⚠️ 需要添加保护（见上方修复）

---

F. 组件粒度

当前大小：4 个属性（按建议修改后为 7 个） 结论：粒度合适——用途单一，属性数量适中

---

总结

类别	状态
Designer 控制能力	⚠️ 需要改进——发现 4 个硬编码项
状态管理	⚠️ localStorage 需要 SSR 保护
Shadow DOM	✅ 良好
SSR 安全性	⚠️ 有一个问题
粒度	✅ 良好

优先处理事项：

1. 修复 localStorage 的 SSR 问题（会阻止部署）
2. 将 imageUrl 从 Text 属性改为 Image 属性
3. 将徽标控制项暴露为属性
4. 考虑暴露按钮标签

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