brandvm/webflow-style-guide

Webflow 风格指南：所有站点共享的单一布局

风格指南是原型中构建的第一个页面，也是在 Webflow 中构建的第一个页面（早于任何其他页面）。它确保变量、标签样式和类在依赖它们之前已经过验证，并且每个类都挂载在某个元素上，这样 Webflow 的清理未使用样式功能就永远不会删除那些仅由 CMS、脚本或未构建页面使用的类。

其布局是固定的。项目只提供内容，而不提供布局：

• sg.css 是页面的自身布局（Sg 类）。
• scripts/gen-style-guide.mjs 根据 Webflow 快照、CSS 和项目的标本生成页面。
• scripts/check-style-guide.mjs 在以下情况会失败：类缺失于页面、某个组合的类从未在同个元素上共存，或布局发生偏移。
• scripts/sections.mjs 是两个脚本共享的分区列表。
• 每个排版标本带有 data-sg-type（其名称），因此原型的 pnpm measure:type 可以输出在 1440 和 390 宽度下渲染的文字尺寸（字号、行高、字间距、字重），以便在类进入 Webflow 之前与设计团队的排版表进行比对。

遵循共享规则（webflow-build › rules.md：先设计师，未经确认不得提交或推送），在 Webflow 中遵循其自身的构建规则：每批操作前需获准。

布局

框架。 左侧一个固定侧边栏列出所有分区，带编号，并作为链接指向它们；当前阅读的分区高亮显示。右侧一个内容列。当宽度 ≤ 991px 时，侧边栏变为导航下方的一串可横向滚动的链接。

写给新人看。 页面必须让从未见过该网站的人（如客户或新入职的开发者）也能理解。

• 概览区以页面介绍开场，包含四张卡片说明如何使用（找到它、阅读一行、复用前先添加、在此添加），以及网站概览（计数）、字体、变量集合和断点。
• 每个分区都以它的编号、标题和一行文字开头，说明其用途与用法（文字在 scripts/sections.mjs 中，所有站点相同）。
• 按钮、表单和组件的标本置于面板上；类名放在标签块内；长表格在滚动时保持表头可见。
• 所有标签使用网站自身的字体。不使用等宽字体：Designer 类只包含一个字体系列，系统等宽字体会自带斜杠零。
• 框架颜色取自页面颜色（使用低透明度的中性色线条和面板），因此无论在浅色还是深色网站上，框架看起来都一样。

分区， 始终按以下顺序排列，使用这些名称和 id。如果某个分区没有内容，则省略；不得添加、重命名或重新排序。

#	分区	id	来源
1	概览	overview	自动生成：如何使用页面、计数、字体、集合、断点
2	颜色	colors	所有不在 Colors Semantic 中的颜色变量
3	主题	themes	分区、每个设置了 Colors Semantic 模式的类，以及每个模式下角色对照表
4	排版	typography	每个设置了 Typography Styles 模式的类、原生标签样式（标题、段落、链接）、Body 样式的字体特性以及字号比例尺
5	工具类	utilities	Size、Weight、Leading、Tracking、Text 和 Max Width 类
6	间距、圆角和布局	spacing	间距（每个带一条等长色条）、圆角和布局变量
7	按钮和链接	buttons	标本
8	表单	form-elements	标本（项目使用 section=forms；Webflow 拒绝 forms 作为元素 id）
9	组件	components	标本
10	页面区块	page-sections	标本，以半屏尺寸展示
11	其他类	other-classes	自动生成：以上均未涵盖的所有类

行。 页面上的每个项目都是一个 Sg 行：左侧显示 Designer 中看到的名称、CSS 类以及简要说明（它绑定到的内容、各断点下的值、状态）；右侧是实时示例。分区由标题和行列表组成。值表格（每个模式下的角色表、字号比例尺、间距、布局）作为一行中的标本呈现为一个 Sg 表：名称列，然后每个模式或值占一列。

框架中不出现项目类。 框架仅使用 Sg 类，因此无论项目的字号比例尺或区块内边距如何，页面外观始终一致。项目类仅出现在标本中。

变量是标准，不是限制

页面会展示网站拥有的所有内容。模板中的集合、名称和初始值（webflow-build 约定 §4，包括默认字体 Geist）是标准的布局和变量使用方式；项目可以自由更改值，并添加、重命名或删除变量、模式和集合。

• 任何不在语义集合中的颜色变量都是色板；任何设置了模式的类都是主题或排版行；任何生成器无法识别角色的集合都会在“间距、圆角和布局”下以表格形式展示。
• 如果网站对标准集合使用了不同的名称，则需在 design/style-guide/config.json 中说明，例如 { "collections": { "semantic": "Themes", "typeStyles": "Type Styles" } }（键：semantic、typeStyles、typeRole、typeScale、spacing、radius、layout）。
• 固定不变的是布局：框架、分区顺序、行。

标本（第 7 至 10 分区）

提供两种方式，效果相同。

1. 从真实页面提取， 因此与页面保持同步。将页面上标记包裹在注释中：

<!-- sg:start section=components | name=Card | class=.card | note=用于列表和首页 -->
<a class="card" href="/work/item" data-card>…</a>
<!-- sg:end -->

2. 手动编写， 适用于页面本身不展示的内容（如按钮状态、表单部件）。每个分区一个文件，放在 design/style-guide/items/ 中，每个项目由一段头注释及其标记组成：

<!-- sg: section=buttons | name=Button Is Secondary | class=.button.is-secondary | note=与 Button 组合使用 -->
<a class="button is-secondary" href="#buttons">次要按钮</a>

• section 可以是 buttons、forms、components 或 page-sections；name 必填；class 和 note 可选。
• 组件和页面区块优先使用真实页面块。手动复制的标本会与页面实际元素脱节，在早期构建中，从手动复制的预览构建的组件曾丢失脚本钩子 ———— 不要这样。
• 生成器会从标本中移除 id、for、data-* 钩子和 id 引用，并标记为 inert：它只是组件的静态图片，而非工作副本，因此没有脚本附着，且其中任何元素都无法获得焦点。
• 页面为 noindex，因此存在第二个 h1 是允许的：排版分区会展示一个真实的 h1 作为“所有 H1 标题”标签样式的示例，而标本中也可能包含 h1。
• page-sections 标本会在一个密封框架中以半尺寸显示。一旦该区块对应的页面在 Webflow 中存在，即可移除该标本：此后页面会保留其类。第 1 至 9 分区永久保留。
• 不允许使用内联 style 属性：Webflow 导入器会将每个内联样式转换为垃圾组合类。颜色色板、圆角框和间距条改用每个变量对应的单个生成的组合类。

在原型中（第一页）

1. 原型文件夹已存在（webflow-prototype › 项目设置）且其 Webflow 快照是最近的（pnpm css）。
2. 执行 pnpm style-guide。它会生成 design/style-guide/index.html 和 src/css/style-guide.css。切勿手动编辑这两个文件。
3. 添加项目的标本（按钮和表单项；组件和页面区块随页面构建进度添加）并再次运行。
4. 执行 pnpm check:style-guide 直到通过。
5. 人员在 1440、820、667 和 390 宽度下审查页面，并在开始第一个内容页面之前批准它。
6. 此后，每个新类或新组件都应在同一次工作中添加其行：添加标本，执行 pnpm style-guide，执行 pnpm check:style-guide。

在 Webflow 中（第一页）

在变量、标签样式、类和仓库包全部就位之后，并在任何其他页面之前。每批操作需要事先获准。

1. 页面。 位于 design 文件夹下的 /design/style-guide，使用标准外壳（webflow-build 约定 §1）。页面 Head 代码中包含 noindex, nofollow；在站点搜索和站点地图中排除（站点地图设置需要站点计划：对于没有站点计划的站点，noindex 标签就能使其不进入搜索结果，排除设置会在计划建立后设置）；指向它的链接会进行完整页面加载。
2. Sg 类。 从模板复制的站点已经包含这些类。否则，最快且保留所有值的方式是：使用 WHTML 构建器导入框架，并将 sg.css 作为其 css 传入（变量和 calc() 被替换为纯值，rgb(r g b / a) 写为 rgba()）。导入器会以长属性、状态和断点的形式创建每个类，名称使用其 slug；之后将每个类重命名为 Designer 应显示的名称（Sg Row、Sg Row Meta、Sg Table Key…）。.w--current 规则会变成 Sg Sidebar Link 的 Current 状态，而样式工具本身无法写入该状态。此操作仅在类为新建时有效：对于已存在的类，导入器会创建一个带编号的副本（webflow-build/lessons/mcp.md）。
3. 变量组合类。 对于每个颜色变量，组合类 Sg Swatch Color + Is … 绑定 background-color；对于每个圆角变量，组合类 Sg Radius + Is … 绑定 border-radius；对于每个间距变量，组合类 Sg Bar + Is … 绑定 width。生成的 src/css/style-guide.css 会列出这些组合类，每行一个。
4. 构建 页面时，从生成的页面按分区逐个构建，仅使用类。在导入标记之前创建每个类和组合类（如果缺少一个类，导入器会丢弃整个类列表）。然后将每个侧边栏链接指向其对应的分区（链接类型：页面锚点），这样 Webflow 就能高亮显示当前分区。
5. 组件的行 应使用组件实例，而不是复制其标记。
6. 在预发布环境中检查： 站点上的每个类都出现在已发布的页面或外壳中，且每个组合类出现在同一个元素上（组合类如果只分散在不同元素上，仍然会被清理功能删除）；侧边栏高亮显示当前可见的分区；noindex 出现在 <head> 中。只有在此时，清理未使用样式才是安全的。

在已有站点上

不是从模板构建的站点也可以获得相同的页面：从 webflow-prototype 技能的原型模板创建一个原型文件夹，获取站点快照，然后按照“在原型中”和“在 Webflow 中”的步骤操作。其 Sg 类尚不存在；在步骤 2 中创建它们。

关卡

• 原型风格指南已批准 [人员]：在原型中第一个内容页面开始之前。
• 风格指南基础完成 [Claude 检查，人员批准]：Webflow 页面包含当前存在的所有类；在三个宽度下发布并检查。
• 风格指南最终检查 [Claude 检查]：在构建交接时，pnpm check:style-guide 通过且已发布的页面包含所有类。

更改布局

布局的更改应在此处进行，一次性影响所有站点，而绝不在单个项目中：编辑模板中的 sg.css、分区列表或生成器，在同一轮工作中更新模板站点，并发布它（webflow-build › rules.md › 贡献）。项目通过 pnpm update-skills 和 pnpm style-guide 获取更新。