brandvm/webflow-prototype

Webflow 原型：Figma 设计 → 已批准的本地原型

项目的第一阶段。每个站点都从 Figma 文件开始，其设计以代码形式构建，使用真实的 URL 和断点，采用 Webflow 将拥有的变量和类名，并逐页获得批准。产出的不是模拟图：而是 Webflow 构建所依赖的标记、类、模块和手动步骤清单。

此阶段从不写入 Webflow。 它读取站点（快照）并提出更改；写入操作属于 webflow-build 技能，在其自己的会话中，在原型获得批准后进行。

• checklists.md 把关输入、每个原型页面和移交。
• prototype-starter/ 是项目启动时的原型文件夹（pnpm new-project 会复制它）。
• figma.md 通过 Figma 连接器读取 Figma 文件：每个断点的画板、截图、变量、尺寸。
• 从一个画板构建一个页面的步骤位于 webflow-build （SKILL.md › 原型，来自 Figma），与 Bench 的 AI 遵循的步骤相同。其 checklists.md 中的 原型 阶段跟踪原型直至客户批准。
• webflow-style-guide 技能制作样式指南，即原型的第一个页面。
• conventions.md （位于 webflow-build）设置了原型遵循的页面和分区结构以及类和变量命名规则；lessons/ 记录了以前版本中耗费时间的经验教训。
• rules.md 包含所有 Webflow 技能共享的规则（未经确认不提交或推送、先使用 Designer、聊天中不包含凭据）、会话总结以及如何回馈贡献。

每个清单项都表明谁来做：[Claude]、[Claude 检查]（Claude 验证并报告；无法修复的问题由人员处理）或 [人员]（Claude 可以提醒并跟踪，但从不声称自己完成）。

会话开始（每次会话）

1. 读取工作区 CLAUDE.md，然后是仓库的 AGENTS.md 和 GOTCHAS.md，接着是 docs/handoff/。略读 lessons/README.md；lessons/mcp.md 中的导入器经验教训决定了原型标记的编写方式。
2. 读取项目记忆：上次会话停止的位置、未解决的问题。用一句话说明当前状态和下一步计划。
3. 对于新项目，首先运行 checklists.md 中的 原型之前。如果缺少输入，则请求提供；不要猜测内容、状态或 SEO 字段。
4. 原型开发服务器正在运行（在 prototype/ 目录下执行 pnpm dev）。
5. 今日范围是一个页面。说明是哪一个。

项目设置（新项目）

在 Bench 中， 通过添加客户 › 从 Figma 设计 设置客户文件夹、基于此模板的仓库和空的 prototype/，然后根据人员选择的画板构建原型（步骤 6）。人员的步骤（4）和输入仍然适用。

不在 Bench 中， 流程从一条消息开始（README › 启动项目），例如 "新项目：Webflow 站点 <名称>，Figma <链接>。设置仓库和工作区，运行原型之前，然后根据 Figma 文件逐页构建原型；在进行任何 Webflow 更改之前等待我的许可。"

在此之前，人员已根据 GitHub 上的模板创建了仓库，将其克隆到自己的客户文件夹中（<Client>/wf-<client>/），并将启动站点复制到客户名称下（starter-site.md）。

1. 首先处理技能。 提供 pnpm update-skills（询问；它会替换本地技能编辑），以便项目从最新的经验教训开始。

2. 查找站点。 通过 Webflow 连接器，列出站点并匹配人员提供的名称：站点 ID 和短名称（暂存子域名 <短名称>.webflow.io）。找到两个或无匹配 → 询问。从 git remote get-url origin 读取 GitHub 组织和仓库。

3. 填充仓库并设置工作区：

   pnpm install
   pnpm new-project --client "<Client>" --slug <短名称> --org <org> --site-id <id>
   

   这会填充 AGENTS.md 中的项目事实、package.json 名称、loader.html 中的 REPO 以及移交标题，并写入 webflow-build.config.json。绕仓库创建工作区：<Client>/CLAUDE.md（导入 AGENTS.md、GOTCHAS.md 和 docs/handoff/）、.mcp.json、指向技能的链接、prototype/（prototype-starter/ 的副本）和 Assets/。将 Figma 链接写入工作区 CLAUDE.md（设计行）。询问任何找不到的值；切勿猜测。

4. 列出人员的步骤，按此顺序， 并在 docs/handoff/MANUAL-TODO.md 中跟踪直至完成：

   1. 仓库设置 → 页面 → 来源：GitHub Actions；添加开发者团队。
   2. 首次推送：Claude 请求提交设置；推送后，暂存工作流必须通过（https://<org>.github.io/<repo>/styles.css 加载）。
   3. 从 loader.html 粘贴加载器（ORG 和 REPO 现在已填充）：站点设置中的头部代码和页脚代码。嵌入代码 2a 和 2b 已经存在于 G | 组件中，并带有占位符：Claude 在获得许可后通过 MCP 填充它们，或者人员粘贴它们。
   4. 启用暂存密码和 noindex 直到上线。

5. 移动到工作区。 从下一次会话开始，Claude 在 <Client>/ 目录下打开，而不是在仓库中：这是设置 MCP 服务器、技能和导入的位置。在 prototype/ 中运行 pnpm install。

6. 输入，然后是原型。 运行 checklists.md 中的 原型之前（包括组件计划和视频列表），读取 Figma 文件（figma.md），获取 Webflow 快照，并从文件构建原型：首先是样式指南（webflow-style-guide 技能），在任何内容页面之前获得批准，然后从选定的画板逐页构建（webflow-build › 原型，来自 Figma），每个页面都通过 原型页面完成 检查。

7. 根据设计填充 docs/handoff/HANDOFF.md；从第一次会话开始保持 MANUAL-TODO.md 和 BUILD-NOTES.md 的更新。

原型

• 它镜像 Webflow： 相同的 URL、相同的断点（991、767、479）、Webflow 类名以及 conventions.md 的页面外壳和分区结构。导航和页脚是单一局部组件（每个一个组件）。
• 它标记组件和 CMS： 在组件实例的根元素上使用 data-component="<组件名称>"（导航和页脚局部组件已有），在组件属性设置的内容上使用 data-prop="<属性名称>"，在集合列表包装器上使用 data-collection="<集合名称>"，在绑定到 CMS 字段的元素上使用 data-field="<字段名称>"（在列表项中或 CMS 模板页面上）。视觉上无变化，并且这些标记不会在 Webflow 中创建，Webflow 有自己的组件和 CMS 绑定（prototype-starter/README.md › 组件和 CMS 标记）。
• 它读取站点的变量 来自 Webflow 的快照（prototype-starter/README.md › Webflow 快照）。在写入或刷新快照后：运行 pnpm css，然后 pnpm check:snapshot，然后 pnpm check:drift，它将快照与暂存站点发布的样式表进行比较，并列出每个不同的变量、类和值（首先发布到暂存）。
• 没有 Webflow 连接器？（尚未设置，登录到另一个站点，或不允许 MCP 调用）pnpm css:published <暂存 URL> 从站点发布的 CSS 构建 tokens.css、webflow.css 和 webflow-base.css（仅 GET；逐页读取每页 CSS 并合并），并尽可能恢复快照。CSS 是准确的；Designer 名称、模式名称、空类和交互不在其中（脚本的头部列出了它猜测的所有内容），因此在 HANDOFF.md 中说明快照是临时替代品，切勿使用猜测的名称提出变量或类而不在 Designer 中检查，并在 MCP 可用时立即从 MCP 替换快照（删除 webflow-snapshot/source.json，然后 pnpm css）。当 source.json 存在时，pnpm css 拒绝运行。
• 变量更改是提议的，从未执行： 以 proposed.css 中的 old → new 形式，分组并编好字母以供批准。新类放在 new-classes*.css 中，按照 Designer 可以保存的方式编写。
• 标记是为导入器编写的： 形状使用 div，不使用空 span；表单控件放在 <form> 内；布尔属性带有值；换行前有  ；模块依赖于 data-* 钩子，而不是类名。pnpm wf:preflight 检查所有内容。

顺序。

1. 快照，pnpm css，pnpm check:snapshot，pnpm check:drift（无连接器：pnpm css:published，然后进行相同的检查）。
2. 样式指南（webflow-style-guide 技能），在任何内容页面之前获得批准。
3. 页面，一次一个，来自其 Figma 画板（webflow-build › 原型，来自 Figma）。对于每个页面：构建它；为它引入的每个类或组添加行（pnpm style-guide）；pnpm screens（从 2560 到 360 的每个宽度：溢出和错误）和 pnpm check:states（焦点和按下状态）；运行 原型页面完成；人员在 1440、820、667 和 390 宽度下批准。
4. 客户以书面形式批准原型。
5. 移交（见下文）。

移交给构建

运行 checklists.md 中的 原型移交。构建会话开始的包：

• docs/handoff/HANDOFF.md：页面、变量和类、CMS、要制作的组件、模块及其钩子、视频列表。
• pnpm wf:styles：每个新类分类到连接器可以创建的内容、人员在 Designer 中手动设置的内容（已在 MANUAL-TODO.md 中列出）以及进入仓库 CSS 的内容。
• pnpm wf:preflight：每个页面已知的导入器步骤。
• 已批准的原型本身，正在运行，作为构建比较的参考（pnpm wf:compare，wf:pass）。

然后向人员提供启动构建会话的消息，已填充，以便粘贴到在工作区文件夹中打开的新会话中：

继续 ：在 Webflow 中构建。原型已批准（所有页面和样式指南，<日期>）。读取工作区 CLAUDE.md、docs/handoff/ 和 webflow-build 技能。从基础开始：从 proposed.css 提议变量批次，并在每次 Webflow 写入之前等待我的许可。然后处理样式标签、类（根据样式计划）、CMS 集合、仓库端口和加载器、样式指南页面、媒体页面（如果视频列表有条目）、组件和页面，每个会话一个页面。

构建在其自己的会话中运行，以便仅加载构建规则，并且原型保持不受影响作为参考。

工作节奏

• 每个会话一个页面，完整完成： 构建，在每个宽度下检查，状态完成，运行 原型页面完成，更新移交。
• docs/handoff/ 在会话期间保持最新，而不是在最后：做出决定时立即写入 HANDOFF.md。
• 回馈经验教训。 在总结时，向模板提供每个 template-candidate 经验教训（rules.md › 贡献）。