html-generator

HTML Generator Skill

根据设计系统创建独特、具有品牌特色的 HTML 页面和独立组件。

核心认知

创建 HTML 页面是以设计系统为驱动进行组合，而不是填充模板。每个组件都是独立的设计作品，既能单独使用，也能组合成页面。每个部分都应体现资深设计师的精心打磨——别具匠心、独树一帜、令人难忘。

• 你会收到：设计系统（canvas-philosophy.md + design-system.md），其中包含设计令牌、组件目录和品牌标识。
• 你要创建：独立的 HTML 组件 + 组合而成的单文件 HTML 页面。
• 标准：让观看者停下滚动的作品。大胆、鲜明，绝不平庸。

调用时

由 /html-page 和 /html-page-quick 调用。接收：设计系统文件（canvas-philosophy.md + design-system.md）、品牌理念（brand-philosophy.md 或子标识覆盖项）、组件选择、components/ 中的任何可复用组件、内容，以及 references/web-style-constraints.md 中的样式约束。

两种输出模式

• 组件生成——单个独立组件：包含嵌入式 <style> 的完整 HTML 片段、通过 CSS 自定义属性定义的设计令牌、属性/插槽元数据注释，以及带令牌回退值、可独立查看的内容。
• 页面组合——将组件组装到一个 .html 文件中：共享的 :root 令牌、带 meta viewport 的响应式包装器、按顺序排列并保持间距一致的组件、顶部导航 + 底部页脚、单个去重后的 <style> 块，以及仅在样式需要时添加的精简 <script>。

文件格式、样板代码以及完整的组件/页面结构，详见 references/html-technical.md。

第 1 部分：设计思考流程

编写任何 HTML 之前，先充分理解设计系统：

0. 确认品牌存在——如果项目中没有 design-system.md，请停止并建议先运行 /design-html。如果没有 brand-philosophy.md，请建议先运行 /brand-extract。绝不要使用默认/示例值继续操作。
1. 阅读画布理念——领会其美学运动，而不只是规则。
2. 加载设计令牌——将颜色、字体和间距设为 CSS 自定义属性。
3. 理解风格——阅读 references/web-style-constraints.md 中的强制约束。
4. 考虑内容——页面的目的是什么？谁会看到？你希望他们有何感受？
5. 规划差异化——这张页面在视觉上有何令人难忘之处，能使其区别于平庸设计？

差异化测试

生成前先问：“这张页面能属于任何品牌吗？”如果答案是肯定的，就进一步强化其特色。然后问：“别人会记住这张页面的哪一个特点？”——戏剧性的字体层级、出人意料的色彩亮点，或意想不到的布局突破。如果说不出来，说明设计还不够独特。

融入画布理念中独特的风格运动与精神、出人意料的布局选择（不对称、重叠、打破网格）、作为艺术的排版、氛围营造（渐变网格、噪点、图案、深度阴影），以及通过微交互展现的品牌个性。

意图优先于强度

**让实现复杂度与美学愿景相匹配。**极繁主义设计需要精巧的代码、大量动画和层叠效果；极简或精致的设计则需要克制、精准，以及对间距和排版的细致把控。关键在于意图，而非强度——以数学般的精准呈现的瑞士设计，与以奔放活力呈现的孟菲斯设计同样强大。切勿一概套用“大胆”风格；应根据具体风格调整。

第 2 部分：品牌整合

设计令牌 → CSS 自定义属性

读取项目的 design-system.md，并将所有令牌章节映射到 :root 自定义属性：颜色（--color-primary、--color-accent、--color-bg、--color-text，……）、排版（--font-heading、--font-body、--font-size-*）、间距（--space-xs……--space-2xl）、布局（--max-width、--border-radius、--min-tap-target）、交互时序／缓动，以及页面包含表单时使用的表单令牌。design-system.md 是唯一事实来源；绝不要硬编码值。

防止品牌偏见（生成任何 HTML 前先确认）

□ All colors use CSS custom properties from design-system.md (--color-primary, etc.)
□ No hardcoded hex values except #FFFFFF/#000000 for universal black/white
□ font-family from design-system.md, never "Inter", "Roboto", or "Arial" as defaults
□ If no design-system.md exists: STOP, suggest /design-html first
□ Background, accent, and text colors all traced to design tokens

绝不要将参考文件示例中的十六进制颜色代码或字体名称复制到生成的 HTML 中。 所有视觉值都应沿着以下路径传递：design-system.md → CSS 自定义属性 → 组件样式。

色彩主导原则

大胆的主色配以鲜明的点缀色，效果胜过拘谨且分布均匀的调色板。使用 --color-primary 作为主导色（标题、CTA、当前导航项），使用 --color-accent 作为鲜明的点缀（链接、悬停、高亮），并让 --color-bg／--color-text 承担安静的结构性作用。如果调色板感觉「平均」，就加强主色，或降低次要色的存在感。

字体加载

通过 <link> 加载有辨识度的 Google Fonts，并提供系统字体回退栈；绝不要默认使用 Inter、Roboto 或 Arial。<link> 的准确标记和回退栈见 references/html-technical.md § Font Loading Strategy。

第 3 部分：组件生成

每个组件都必须遵守的规则

1. 可独立运行——每个组件都能作为独立 HTML 文件使用。
2. 共享令牌——所有组件都引用相同的 CSS 自定义属性名称。
3. 命名一致——{type}-{variant}.html（例如 hero-centered.html）。
4. 属性／插槽元数据——使用 HTML 注释标记内容插入点。
5. 响应式——移动优先，并在全部 3 个断点下正常显示。
6. 无障碍——使用语义化 HTML，按需添加 ARIA 标签，并妥善管理焦点。
7. 交互状态——每个可点击元素都使用交互令牌定义悬停、焦点和激活样式。
8. 适用于触控操作——交互元素的尺寸符合 --min-tap-target，并留有足够间距。

元数据注释（必须）

每个组件都必须包含可直接用于转换的元数据注释，否则 design-system-converter 无法识别组件、属性或插槽：

• … 包裹整个组件
• `` 紧贴在其所注释的元素之前
• … 包裹重复／可插入内容
• `` 放在 SVG 之前

支持的属性类型：string、boolean。独立组件和组合页面中都必须包含这些注释。完整格式及示例见 references/html-technical.md § Convertibility Metadata Format。

组件 CSS

使用类 BEM 的命名方式（.hero、.hero__title、.hero__title--large）限定样式作用域，并引用设计令牌，绝不硬编码值。全部 15 种组件类型对应的 HTML 骨架和 CSS 模式见 references/html-components.md。

第 3.5 部分：图标集成

可通过 node "$BRAND_CONTENT_DESIGN_DIR/scripts/html-icons.js" get|search|category|categories 获取 1,500 多个 Lucide 图标，并以内联 SVG 的形式使用。图标的描边使用 currentColor，尺寸继承自容器。只有在存在明确的视觉隐喻时才使用图标；图标应与文本标签搭配；装饰性图标应标记为 aria-hidden="true"，有意义的图标应标记为 role="img" aria-label="…"。获取命令、嵌入模式和容器 CSS 见 references/html-technical.md § Icon Integration。

第 4 部分：样式约束

读取 references/web-style-constraints.md 中选定的样式，并遵守各章节的限制（词数／元素数量）、间距值、排版规则、配色策略、布局指令、JS 使用许可和反模式。将约束要求应用于每个组件和组合页面。

第 5 部分：响应式设计

移动端优先，设置 3 个断点：375px 为基础尺寸，平板使用 @media (min-width: 768px)，桌面端使用 @media (min-width: 1200px)。采用常见适配方式——汉堡菜单→水平导航，纵向排列→横向并排的主视觉区域，网格列数从 1→2→3-4 列，移动端字体缩小 15-20%，移动端区块内边距减少 30-40%。断点代码和字体缩放说明：references/html-technical.md § 响应式断点。

第 6 部分：优先使用 CSS 实现交互

优先使用 CSS；只有 CSS 无法实现效果时才使用 JS。

动效层级——将动效预算集中用于每个页面的一个高影响力时刻。精心编排、带有交错揭示效果的页面加载，胜过零散的微交互。做出选择：主视觉入场、统计数字递增，或卡片网格级联——选一个，做到出色，其余效果保持微妙。

仅用 CSS 实现的模式：悬停过渡效果（transform、box-shadow、opacity）、<details>/<summary> 折叠面板、scroll-snap、@keyframes、scroll-behavior: smooth、:focus-visible。当某种风格（动感字体、3D/沉浸式、视差）需要 JS 时：仅使用原生 JS，渐进增强，遵循 prefers-reduced-motion，代码控制在约 50 行以内。JS 模式代码（Intersection Observer、移动端导航切换、轻量视差）：references/html-technical.md § 原生 JS 模式。

第 7 部分：将字体排印作为艺术

字体排印是 HTML 页面的首要设计工具。大胆做出选择：

• 标题与正文的字体搭配——形成对比又彼此协调（衬线标题 + 无衬线正文，反之亦可）。
• 字重对比——充分利用 300-900 的字重范围构建层级。
• 字号对比——标题要比正文大得多（3 倍至 6 倍）。
• 字间距——大写标题采用较宽的字间距，大号展示文字采用较紧的字间距。
• 行高——正文宽松（1.6-1.8），标题紧凑（1.0-1.2）。

切勿使用 Inter/Roboto/Arial/Helvetica（除非品牌或风格的视觉特征明确指定使用这些字体）、单独使用系统字体栈、全篇只用一种字重，或采用统一字号。

避免趋同——不同生成批次之间绝不要总是选用相同的字体。如果将 10 个生成的页面并排放置，它们应该看起来像是出自 10 位不同设计师之手。在不同项目之间更换展示字体、正文字体、字重分布和字号比例。

第 8 部分：空间构图

• 不对称优于对称——完全对称会显得乏味；可控的不对称能营造动感。
• 重叠与分层——元素可以重叠（例如图片置于文字后方、装饰图形叠放）。
• 打破网格——先建立网格，再有意打破网格，突出关键时刻。
• 留出充足的负空间——使用 var(--space-xl)–var(--space-2xl) 的内边距，让区块更显舒展。
• 全宽区块——部分区块可突破最大宽度容器的限制。
• 营造氛围——渐变网格、微妙的 SVG 噪点/颗粒、CSS 生成的几何图案、多层 box-shadow 营造深度，以及交替变化的区块背景，形成节奏感。

第 9 部分：无障碍（必须遵守）

每个生成的页面都必须满足：使用语义化 HTML5 地标；遵循 h1→h2→h3 层级，不跳级；提供跳转导航链接；符合 WCAG AA 对比度（普通文本 4.5:1，大号文本 3:1）；提供清晰可见的 :focus-visible 指示器；提供描述性替代文本（或占位注释）；为导航/地标/交互元素添加 ARIA 标签；使用 @media (prefers-reduced-motion: reduce) 禁用动画；设置 <html lang="en">；添加 viewport 元标签。

新拟态警告——在相似背景上使用柔和阴影可能无法达到 WCAG AA 标准。请仔细检查对比度；必要时添加明确的边框，或增强阴影对比度。完整检查清单：references/html-technical.md § 无障碍检查清单。

第 10 部分：页面组合

将组件组合成完整页面时，每个组件区块都必须保留其元数据注释——这是确保可转换为框架的最关键要求。

• 在最外层元素之前放置 ，并在闭合标签之后放置 。
• 将 紧接在其注释对象之前；使用 … `` 包裹插槽区域。
• 请勿删除、概述或简化元数据，也不要用区块分隔注释（、）替代元数据。

组合页面中的 CSS 顺序如下：重置 → :root 令牌 → 基础排版 → 工具类（.container、.sr-only、.skip-link）→ 组件样式（去重后）。使用一致的区块内边距（桌面端为 var(--space-xl) 0，移动端为 var(--space-lg) 0），通过交替背景营造节奏，区块之间不显示边框。完整的组合页面示例和 HTML 样板代码见 references/html-technical.md § 页面组合格式。

第 11 部分：图像处理

Claude 无法生成图像——请使用智能占位内容：采用符合品牌调色板的 CSS 渐变、使用 aspect-ratio 保持比例、添加说明图像替换方式的 HTML 注释、使用装饰性 CSS 图案增加变化，以及用姓名首字母或图标作为团队照片的占位内容。占位 CSS 见 references/html-technical.md § 图像占位方案。

第 12 部分：可转换性结构

为将来转换为 Drupal SDC、React、Canvas 和其他框架来设计组件——第 3 和第 10 部分中的元数据注释正是实现转换的关键。使用语义化组件名称（hero、feature-grid、cta）、BEM CSS 类、表示所有品牌值的 CSS 自定义属性，以及用于行为挂钩的数据属性（data-reveal、data-parallax）。完整的 HTML 元数据 → SDC/React/Twig 映射表见 references/html-technical.md § 可转换性元数据格式。

反模式（绝不允许）

• 输出中不得使用 CSS 框架——不得使用 Bootstrap、Tailwind、Foundation。
• 输出中不得使用外部 JS——不得使用 jQuery、React、Alpine、HTMX。
• 不得使用损坏的图像——使用 CSS 占位内容，绝不要使用 <img src="missing.jpg">。
• 不得生成 AI 垃圾内容——避免泛泛的图库照片风格、过度使用渐变和陈词滥调的布局。
• 不得堆砌大段文字——遵守样式约束中的各区块字数限制。
• 不得使用内联样式——所有 CSS 都应放在 <style> 块中（CSS 自定义属性覆盖除外）。
• 排版不得使用像素单位——使用 rem/em，确保无障碍访问。
• 不得通过框架加载字体——仅使用 Google Fonts <link>。

参考资料

附带资料（插件专用）

• references/html-design-guide.md — 设计系统理念和内容类型指南
• references/web-style-constraints.md — 面向 Web 的 21 项样式强制规则
• references/html-components.md — 15 种组件类型及其 HTML/CSS 模式
• references/html-technical.md — 样板代码、元数据格式、响应式设计、字体、图标、JS、无障碍、页面组合、可转换性

在线开发指南（设计系统）

如需了解此插件视觉样式之外的设计系统基础知识，请使用关键词调用 /dev-guides-navigator，例如 “design system recognition”、“Bootstrap mapping”、“Radix SDC” 或 “component classification”。该导航器会处理缓存和消歧——切勿直接获取 dev-guides URL。