webflow-code-component:component-scaffold

组件脚手架

生成新的 Webflow Code Component，并创建规范的文件结构、React 组件和 .webflow.tsx 定义文件。

何时使用此技能

适用于：

• 从头创建新的代码组件
• 用户要求搭建、生成或创建组件
• 开始创建新的组件，并需要规范的 Webflow 文件结构

不适用于：

• 转换现有的 React 组件（使用 convert-component 技能）
• 修改现有组件（直接回答或使用 component-audit）
• 仅询问有关组件的问题（直接回答）
• 使用自定义打包器配置搭建复杂项目（改用 local-dev-setup）

**注意：**此技能可以自动处理基本设置（webflow.json + 依赖项）。仅在需要 Tailwind、自定义 webpack 配置或 monorepo 配置等复杂设置时，使用 local-dev-setup。

说明

阶段 0：检查前置条件（首先运行）

收集任何需求之前，请确认项目已完成 Webflow Code Components 的相关设置：

1. 检查是否存在 webflow.json：

   # Look for webflow.json in project root
   

   • 如果缺失：提供创建该文件的选项，或调用 local-dev-setup 技能

2. 检查 package.json 中是否包含所需依赖项：

   {
     "devDependencies": {
       "@webflow/webflow-cli": "...",
       "@webflow/data-types": "...",
       "@webflow/react": "..."
     }
   }
   

   • 如果缺失：提供安装选项：

     npm i --save-dev @webflow/webflow-cli @webflow/data-types @webflow/react
     

3. 检查组件目录：

   • 查找现有的目录模式（例如：src/components/）
   • 如果不存在组件，请根据 webflow.json 配置确定创建目录的位置

4. 报告设置状态：

   如果所有前置条件均已满足：

   ✅ Project ready for code components
   - webflow.json: Found
   - Dependencies: Installed
   - Components path: src/components/
   
   Let's create your component...
   

   如果缺少前置条件：

   ⚠️ Project Setup Required
   
   Missing:
   - [ ] webflow.json configuration file
   - [ ] @webflow/webflow-cli dependency
   - [ ] @webflow/data-types dependency
   - [ ] @webflow/react dependency
   
   Would you like me to:
   1. Set up the missing items now (quick setup)
   2. Run full project initialization (local-dev-setup skill)
   
   Choose an option:
   

   快速设置会创建最小配置：

   // webflow.json
   {
     "library": {
       "name": "My Component Library",
       "components": ["./src/components/**/*.webflow.tsx"]
     }
   }
   

   并安装依赖项。

   可选：webflow.json 还支持 "globals" 字段，用于指向一个 globals 文件（例如 "globals": "./src/globals.webflow.ts"）。globals 文件用于导入全局 CSS（例如 Tailwind）并导出装饰器数组。使用 styled-components、Emotion 或 Tailwind 时，请添加此字段。

仅在确认前置条件后，才可继续阶段 1。

---

阶段 1：收集需求

1. 获取组件名称：询问用户组件名称

   • 必须使用 PascalCase（例如，“Accordion”、“ProductCard”）
   • 如果用户提供的是描述而非名称，请建议一个名称

2. 确定组件类型：询问组件的类型

   • 交互式（按钮、表单、手风琴）
   • 展示型（卡片、横幅、客户评价）
   • 布局型（网格、容器、区块）
   • 数据驱动型（列表、表格、图表）

3. 确定所需 props：根据组件类型建议 props

   • 文本内容 → props.Text() 或 props.RichText()
   • 可在画布中编辑的文本 → props.TextNode()
   • 图片 → props.Image()
   • 链接 → props.Link()
   • 数值 → props.Number()
   • 变体/样式 → props.Variant()
   • 嵌套内容 → props.Slot()
   • 开关 → props.Boolean()
   • 显示/隐藏区块 → props.Visibility()
   • HTML 元素 ID → props.Id()

4. 样式方案：询问用户偏好的样式方法

   • CSS Modules（默认，推荐）
   • Tailwind CSS
   • styled-components
   • Emotion
   • Sass / Less
   • 纯 CSS
   • 其他受支持的方案：MUI（使用 Emotion）、Shadcn/UI（使用 Tailwind）

5. SSR 要求：确定组件是否需要仅客户端功能

   • 是否使用浏览器 API？→ ssr: false
   • 是否为纯展示型？→ ssr: true（默认）

阶段 2：验证项目设置

6. 检查项目结构：

   • 确认 webflow.json 存在
   • 检查是否包含所需依赖项
   • 确定组件目录模式

7. 检查冲突：

   • 确保组件名称尚未存在
   • 确认没有同名的 .webflow.tsx 文件

阶段 3：生成文件

8. 创建目录结构：

src/components/[ComponentName]/
├── [ComponentName].tsx
├── [ComponentName].webflow.tsx
└── [ComponentName].module.css (if CSS Modules)

9. 生成 React 组件（[ComponentName].tsx）：

import React from "react";
import styles from "./[ComponentName].module.css";

export interface [ComponentName]Props {
  // Props interface based on user requirements
}

export const [ComponentName]: React.FC<[ComponentName]Props> = ({
  // Destructured props with defaults
}) => {
  return (
    <div className={styles.container}>
      {/* Component JSX */}
    </div>
  );
};

10. 生成定义文件（[ComponentName].webflow.tsx）：

import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { [ComponentName] } from "./[ComponentName]";
import "./[ComponentName].module.css";

export default declareComponent([ComponentName], {
  name: "[ComponentName]",
  description: "[User-provided or generated description]",
  group: "[Category]",
  props: {
    // Props configuration based on requirements
  },
  options: {
    applyTagSelectors: true,
    ssr: true // or false based on requirements
  }
});

装饰器说明： declareComponent 还接受可选的 decorators 数组，用于通过提供程序包装组件。内置装饰器包括 styledComponentsShadowDomDecorator（适用于 styled-components）和 emotionShadowDomDecorator（适用于 Emotion）。全局装饰器可以从 webflow.json 中引用的 globals 文件导出——请参阅下方的 globals 文件说明。

11. 生成样式（如果使用 CSS Modules）：

.container {
  /* Base styles */
}

阶段 4：提供指导

12. 显示已创建的文件：列出创建的所有文件及其路径

13. 说明后续步骤：

    • 实现组件逻辑
    • 添加样式
    • 运行 React 项目进行本地测试（例如，npm run dev）
    • 使用 npx webflow library share 部署到 Webflow

14. 注意 Shadow DOM：

Note: Code components run inside Shadow DOM. Site-level CSS classes won't work
inside your component. Use component-scoped styles (CSS Modules, etc.).
Site CSS variables DO work — use var(--variable-name, fallback).

15. 提醒命名注意事项：

⚠️ Important: Do not rename the .webflow.tsx file after deployment.
Renaming creates a new component and breaks existing instances.

示例

用户提示：

Create an accordion component

步骤 1：收集需求

📦 New Component: Accordion

I'll create an accordion component. Let me confirm the requirements:

**Props to include:**
1. `title` (Text) - The accordion header text
2. `content` (Rich Text) - The expandable content
3. `defaultOpen` (Boolean) - Whether to start expanded
4. `icon` (Variant) - Chevron style: "arrow" | "plus" | "none"

**Styling:** CSS Modules (recommended for Shadow DOM)

**SSR:** Enabled (no browser-only APIs needed)

Does this look right? Any props to add or remove?

步骤 2：用户确认后

📁 Creating Component Files...

Created:
├── src/components/Accordion/Accordion.tsx
├── src/components/Accordion/Accordion.webflow.tsx
└── src/components/Accordion/Accordion.module.css

✅ Component scaffold complete!

---

**Accordion.tsx** - React component with:
- Props: title, content, defaultOpen, icon
- State management for open/closed
- Accessible keyboard navigation
- CSS Module classes

**Accordion.webflow.tsx** - Webflow definition with:
- All props configured for Designer editing
- Default values set
- SSR enabled

---

💡 Next Steps:
1. Review and customize the generated code
2. Test locally by running your React project (e.g., `npm run dev`)
3. Deploy to Webflow: `npx webflow library share`

⚠️ Remember: Don't rename .webflow.tsx files after deployment!

生成的 Accordion.tsx：

import React, { useState } from "react";
import styles from "./Accordion.module.css";

export interface AccordionProps {
  title: string;
  content: string;
  defaultOpen?: boolean;
  icon?: "arrow" | "plus" | "none";
}

export const Accordion: React.FC<AccordionProps> = ({
  title,
  content,
  defaultOpen = false,
  icon = "arrow"
}) => {
  const [isOpen, setIsOpen] = useState(defaultOpen);

  return (
    <div className={styles.accordion}>
      <button
        className={styles.header}
        onClick={() => setIsOpen(!isOpen)}
        aria-expanded={isOpen}
      >
        <span className={styles.title}>{title}</span>
        {icon !== "none" && (
          <span className={`${styles.icon} ${isOpen ? styles.open : ""}`}>
            {icon === "arrow" ? "▼" : "+"}
          </span>
        )}
      </button>
      {isOpen && (
        <div
          className={styles.content}
          dangerouslySetInnerHTML={{ __html: content }}
        />
      )}
    </div>
  );
};

生成的 Accordion.webflow.tsx：

import { declareComponent } from "@webflow/react";
import { props } from "@webflow/data-types";
import { Accordion } from "./Accordion";
import "./Accordion.module.css";

export default declareComponent(Accordion, {
  name: "Accordion",
  description: "Expandable content section with customizable header and icon",
  group: "Interactive",
  props: {
    title: props.Text({
      name: "Title",
      defaultValue: "Accordion Title"
    }),
    content: props.RichText({
      name: "Content",
      defaultValue: "<p>Accordion content goes here.</p>"
    }),
    defaultOpen: props.Boolean({
      name: "Start Expanded",
      defaultValue: false
    }),
    icon: props.Variant({
      name: "Icon Style",
      options: ["arrow", "plus", "none"],
      defaultValue: "arrow"
    })
  },
  options: {
    applyTagSelectors: true,
    ssr: true
  }
});

指南

属性类型选择

用户需求	属性类型	说明
可编辑文本	props.Text()	单行，最多 256 个字符
长格式文本	props.RichText()	HTML 内容
可在画布中编辑的文本	props.TextNode()	双击即可编辑
图片上传	props.Image()	返回图片对象
URL/链接	props.Link()	返回 { href, target, preload }
数字输入	props.Number()	数值
开关/标记	props.Boolean()	true/false
样式选项	props.Variant()	下拉选择
嵌套内容	props.Slot()	内含其他组件
HTML ID	props.Id()	用于辅助功能

组件类别（分组）

• 交互：按钮、表单、手风琴、标签页、模态框
• 展示：卡片、横幅、用户评价、徽章
• 布局：网格、容器、区块、分隔线
• 导航：菜单、面包屑、分页
• 媒体：图库、视频播放器、轮播
• 数据：表格、列表、图表、计数器

SSR 决策树

Set ssr: false if ANY of these apply:

1. Browser APIs — Uses window, document, localStorage, or similar
2. Dynamic/personalized content — User-specific dashboards, authenticated views, client data
3. Heavy/interactive UI — Charts, 3D scenes, maps, animation-driven elements
4. Non-deterministic output — Random numbers, time-based values, anything that renders differently server vs client

Otherwise → Keep ssr: true (default)

文件命名规则

• 组件名称：PascalCase（ProductCard）
• 文件使用相同名称：ProductCard.tsx、ProductCard.webflow.tsx
• CSS 模块：ProductCard.module.css
• 目录：src/components/ProductCard/

默认值最佳实践

始终提供有意义的默认值：

props: {
  title: props.Text({
    name: "Title",
    defaultValue: "Card Title"  // ✅ Good
  }),
  count: props.Number({
    name: "Count",
    defaultValue: 0  // ✅ Good
  })
}

不要这样：

props: {
  title: props.Text({
    name: "Title"
    // ❌ Missing defaultValue
  })
}

错误处理

组件名称已存在：

⚠️ Component "Button" already exists at src/components/Button/

Options:
1. Choose a different name
2. Update existing component (use component-audit skill)
3. Delete existing and create new

Which would you like to do?

缺少 webflow.json：

❌ No webflow.json found in project root

This file is required for code components. Would you like me to:
1. Create a basic webflow.json
2. Run local-dev-setup skill for full project initialization

Choose an option (1/2):

组件名称无效：

⚠️ Invalid component name: "my-button"

Component names must be:
- PascalCase (e.g., "MyButton")
- Start with a letter
- Contain only letters and numbers

Suggested name: "MyButton"

Use this name? (yes/no)