AI编码Agent的HTML利器：effective-html项目完全解析

作者：比特财商

---

在AI编码Agent的工作流中，如何让AI生成高质量的HTML工件（artifact）一直是一个核心挑战。传统的做法是依赖详细的文字描述和示例，但这种方式效率低、歧义多、难以精确控制输出质量。plannotator/effective-html项目提供了一个系统性的解决方案——通过一组精心设计的技能（skills），让AI能够像专业前端开发者一样，为不同场景创建高度适配的HTML工件。

本文将对该项目进行完整的深度解析，从核心理念到具体技能，从设计哲学到实战教程，帮助中高级读者全面掌握这一强大的AI编码工具。

---

一、项目概述与核心定位

1.1 项目背景与来源

plannotator/effective-html是GitHub上的一个技能集合（skill collection），由Plannotator组织开发和维护。该项目的核心使命是：为AI编码Agent提供一套创建高质量HTML工件的系统化工作流程。

项目的诞生源于一个朴素但深刻的观察：现代AI模型的能力已经足够强大，真正缺少的不是生成能力，而是有用的参考资料和清晰的表达方式。当AI需要理解一个复杂的界面构思时，一段冗长的文字描述远不如一个直观的HTML artifact有效——HTML可以可视化几乎任何东西，从数据报表到用户流程，从产品原型到技术架构图。

1.2 核心价值主张：Fat Artifacts + Fat Context

effective-html项目用一句简洁的话概括其核心理念：Fat artifacts + fat context（胖工件 + 胖上下文）。

所谓"胖上下文"，是指为AI模型提供充足、有结构、有针对性的参考资料。这些资料不是简单的示例展示，而是涵盖了设计原则、技能路由逻辑、渲染方法选择、状态建模指南等系统性知识。AI模型在这些"胖上下文"的武装下，能够做出更精准的设计决策。

所谓"胖工件"，是指生成的HTML artifact本身要具备足够的完整性和表现力。不是低保真的线框图，不是只有框架的半成品，而是能够在浏览器中直接运行、交互、验证的生产级HTML。

这两者结合，构成了一个高效的人机协作闭环：人类给出方向和约束，AI在丰富的参考资料中寻找最佳方案，用HTML artifact呈现结果，人类再基于artifact进行评审和迭代。

1.3 技术定位

从技术定位上看，effective-html不是简单的HTML模板库，也不是传统的设计系统。它更像是一套AI友好的设计方法论，通过技能化的架构，让AI能够像人类设计师一样思考设计问题——理解场景需求、选择合适的表达方式、遵循设计原则、在约束中发挥创意。

项目的技能化架构是其区别于其他方案的显著特征。整个集合由六个独立但协同的技能组成，每个技能负责一个特定的HTML创作场景。通用技能作为路由器，根据请求特征将任务分发给最窄的专业技能。这种架构既保证了输出的专业性，又保持了整体的灵活性。

---

二、六大技能深度解析

effective-html技能集合包含六个各司其职的技能：html、design-artifact、html-wireframe、html-prototype、html-plan和html-diagram。下面逐一进行深度解析。

2.1 html——通用路由技能

角色定位

html是整个集合中唯一的隐式路由器，负责处理不在其他专业技能覆盖范围内的HTML请求。它的设计哲学是：广覆盖、精确路由。

当用户提出一个HTML相关请求时，html技能首先判断这个请求最适合由哪个专业技能处理。如果请求涉及信息架构和布局探索，路由到html-wireframe；如果需要可交互的产品原型，路由到html-prototype；如果要创建图表或架构图，路由到html-diagram；诸如此类。

覆盖范围

html技能直接处理的请求类型包括：

• 报告和仪表板：数据可视化与信息呈现
• 解释器和文档：知识传递与教程
• 着陆页：营销和引导页面
• 演示文稿：幻灯片式的展示内容
• 工具类界面：功能性Web应用
• 混合型artifact：上述类型的组合

核心原则

html技能遵循一个重要原则：一致的关注，而非一致的外观（Consistent Care, Not Consistent Look）。这意味着每个artifact都应该被精心对待，但并不意味着所有artifact要看起来相似。恰恰相反，每个artifact都应该有自己独特的视觉身份，匹配其主题的原生领域。

举例来说，一个金融数据报告的artifact和一个儿童教育游戏的artifact，如果视觉风格过于相似，那恰恰说明设计出了问题——前者需要严谨和权威感，后者需要活泼和亲和力。这些差异不是需要消除的"不一致"，而是需要尊重的主题特性。

Build Contract

所有通过html技能产出的artifact都遵循严格的Build Contract：

• 产出一个独立的.html文件
• CSS和JavaScript内联在文件中
• 无需构建步骤，浏览器直接打开即可运行
• 无外部网络依赖，所有资源自包含

这一契约确保了artifact的可移植性和可验证性——在任何浏览器中打开都能保持一致的呈现，不依赖CDN或外部服务。

2.2 design-artifact——创意方向技能

角色定位

design-artifact是整个集合中的创意指导中心。它的核心职责是为特定主题定制创意方向，但关键在于——它不强制统一外观。不同的项目、不同的受众、不同的场景，需要不同的视觉语言。design-artifact提供的是一套设计流程和判断框架，而非一套可以复用的视觉模板。

两种注册模式

design-artifact支持两种注册模式，分别对应不同类型的项目：

工作型（workmanlike） 适用于计划、简报、演示等以信息传递为核心的场景。这类artifact追求工艺精湛但不张扬——功能清晰、层次分明、视觉克制，让内容本身说话，而不是靠视觉特效吸引注意。

编辑型（editorial） 适用于着陆页、游戏、应用等需要强烈品牌印记的场景。这类artifact需要有 conviction——明确的审美立场和诚实的美学赌注。设计师需要敢于为这个主题创造独特的视觉语言，而不是套用安全的通用方案。

关键设计原则

design-artifact总结了九条必须内化的设计原则，这些原则是判断设计质量的根本标准：

第一，Defer to prior art（遵循先例）。在开始任何设计工作之前，先寻找现有的设计系统、样式规范和组件库。如果项目中已经有AGENTS.md、tokens或现有组件，设计应该从那里出发，遵循既有的视觉约定，而不是另起炉灶。这不仅是效率的考虑，更是对产品一致性的尊重。

第二，Anchor everything to the subject（锚定主题）。设计的视觉方向应该从主题的原生领域挖掘独特风格，而非从通用模板库中挑选。例如，一个海洋保护主题的页面，其视觉语言应该从海洋、大海、生物中获取灵感——波浪的曲线、珊瑚的色彩、潜水的体验——而不是用通用的"科技感蓝+白"来敷衍。

第三，Put two typefaces in conversation（双字体对话）。选择两个相互对话的字体：一个有特色的display字体用于标题和强调，一个配合的body字体用于正文。这是创造视觉层次和品牌识别度的最有效手段之一。重要的是，永远不要从CDN加载字体，而应该使用@font-face data URI将字体文件内嵌到HTML中，确保artifact的自包含性。

第四，Neutrals are choices too（中性色也是选择）。灰色不是中性色。在选择中性色时，应该让它朝accent方向轻微偏移——偏暖、偏冷、偏绿、偏紫——每一种偏移都会影响整体的情绪基调。设计者应该对每一个"中性"色做出有意识的选择。

第五，Both themes, equal care（两种主题，同等关注）。现代Web应用通常需要同时支持浅色和深色模式。effective-html的要求是：两种主题都要被同等认真地设计。深色模式不是浅色模式的简单反转——它需要独立的设计思考，关注对比度、可读性、氛围营造。机械的反转只会产出一个看起来"将就"的深色版本。

第六，Dodge the telltale AI aesthetic（避免AI美学通病）。这一条尤为重要，因为effective-html正是为了解决AI生成内容同质化问题而诞生的。项目明确指出了当前AI输出的常见审美缺陷：

• 米黄底色搭配衬线字体和赤陶土色的组合
• 近黑色背景搭配酸绿或朱红的强调色
• 等宽字体搭配报纸风格的排版
• 紫蓝渐变的hero区域配白底内容区
• Inter或Space Grotesk作为"安全"选择
• 使用emoji作为章节标记
• 大量居中对齐的布局
• 泛用的rounded-lg圆角类名
• 圆角卡片搭配accent色边栏

这些模式之所以成为"AI美学通病"，是因为AI在缺乏具体指导时会倾向于最常见的解决方案。而design-artifact的工作，正是引导AI走出这些安全区，进入为主题量身定制的视觉领域。

第七，Engineer it soundly（工程要扎实）。设计不只是视觉，还有技术质量。语义化的HTML标签、响应式的布局设计、无障碍的对比度标准、可见的键盘焦点状态、prefers-reduced-motion的动画兼容——这些都是一个合格artifact必须满足的技术要求。

第八，Mind the cascade（注意层叠）。CSS的特异性管理是一个容易被忽视但影响深远的问题。design-artifact要求设计者理清自己样式表中选择器的优先级，避免类名和元素选择器相互覆盖导致的样式冲突。良好的CSS架构应该是可预测的，而不是依赖hack和覆盖。

第九，Copy is a material（文案是材料）。文字内容不是装饰，而是承载结构的材料。设计者应该使用人们认识的名称和术语，而不是后端开发人员才懂的内部术语。文案的质量直接影响artifact的专业感和可信度。

设计流程

design-artifact推荐的设计流程分为三个阶段：

第一步：写出简短设计计划。在写任何代码之前，先用文字描述设计方向。这个计划应该包含三个要素：

• Token系统：颜色（4-6个hex值，每个有名称和用途）、字体（2种以上字体，每个有角色定位）
• 布局：一句话描述组织理念

第二步：代码紧随其后。设计计划不是束之高阁的蓝图，而是要与代码实现同步进行。每一个颜色值、每一个字体选择，都应该在代码中得到落实和验证。

第三步：originality check（原创性检查）。这是防止设计泛化的关键步骤。在完成设计后，问自己一个问题：如果把这个主题换成相邻领域的另一个主题，同样的视觉概念还合理吗？ 如果答案是"是"，那说明这个视觉方向太泛了，缺乏对主题的深度锚定。例如，一个"科技感"的设计——如果把它换成"金融科技"、"医疗科技"、"教育科技"都看起来合理，那就说明它其实什么主题都没有真正表达。

2.3 html-wireframe——低保真线框图

角色定位

html-wireframe专注于创建低保真线框图。它的核心目的是：在视觉设计之前，测试信息层级、内容组织、导航结构和任务流程。

这里有一个关键的认知转折：wireframe的价值恰恰在于它的"未完成"感。一个设计完善的线框图会让评审者陷入对品牌和审美的讨论，而一个刻意保持粗糙的线框图，能让评审者聚焦在真正重要的问题上——信息的组织是否合理？用户的任务流是否顺畅？响应式布局是否work？

权威顺序

wireframe的设计决策遵循严格的权威顺序：

1. 用户明确的指令和已接受的决策：如果用户明确说了"导航在顶部"或"卡片左对齐"，这就是最高优先级
2. 产品现有结构和术语：如果项目中已有导航结构或术语体系，wireframe应该继承而非另创
3. 用户、任务、内容模型：基于对目标用户和他们要完成的任务的理解所做的推断
4. 自己的布局判断：作为设计者的专业判断

这个顺序确保了wireframe反映的是真实需求和约束，而不是设计师的自我表达。

探索策略

当面临不确定的布局问题时，html-wireframe推荐一个高效策略：创建2-3个有实质差异的方向，保持在同一个HTML文件中，用键盘可操作的selector在它们之间切换对比。

每个方向应该：

• 有一个简短的描述性名称（如"顶部导航双栏"）
• 附有一句话的权衡说明（如"适合内容密集型页面，但移动端需要折叠"）
• 在桌面和移动两种宽度下都能展示

这种对比式探索比在白板上争论更有效——因为它可以直接在浏览器中体验和交互。

保持故意未完成

wireframe的"未完成"是有意识的设计选择。具体实现上：

• 使用约束的灰度色板，而不是品牌色
• 使用系统字体，而不是自定义字体
• 使用朴素边框和简单色块，而不是阴影和渐变
• 避免装饰性图像和插图
• 有限的圆角和间距——足够判断层级，但不足以引发品牌评审
• 图片或富媒体位置用标注占位符（如"[产品截图]"）

2.4 html-prototype——交互原型

角色定位

html-prototype的目标是建立产品决策的可信模型。这里的关键词是"可信"——原型不仅要看起来像最终产品，还要在用户上下文中的行为方式与最终产品一致。

两种模式

html-prototype区分了两种场景：

Mockup（静态模型） 适用于视觉设计已基本确定的情况。此时需要验证的是：视觉层级是否清晰？布局是否和谐？字体大小是否合适？颜色搭配是否达到产品契合度？

Prototype（交互原型） 适用于需要测试交互行为的情况。此时需要验证的是：导航是否按预期工作？表单输入和验证是否顺畅？状态变化是否正确响应？加载、空状态、错误、禁用等边界状态是否都有建模？

Scope管理原则

原型制作中最容易陷入的陷阱是"做太多"。html-prototype强调选择最小流来回答评审问题的原则。具体而言：

• 选择最小流：不要做一个包含所有功能的完整应用，而是做一个只覆盖核心评审问题的最小流程。例如，如果评审问题是"用户能否顺利完成结账"，那就只做结账流程，其他功能都是假的或跳转桩。
• 使用真实内容：原型中的名称、日期、状态、数量都应该是真实可信的。虚构的数据会让人出戏，影响评审效果。
• 建模相关状态：每个交互都涉及多种状态——loading、empty、error、success、disabled、mobile特定状态。原型应该覆盖与评审问题相关的所有状态。
• 交互要完整：键盘可操作、焦点可见、dialog有可访问名称、Escape可关闭、错误与关联控件正确关联。
• prefers-reduced-motion兼容：动画应该有开关，尊重用户的运动偏好设置。

2.5 html-plan——计划文档

角色定位

html-plan的目的是将源材料（需求文档、会议记录、邮件讨论等）转化为可检查、可执行的计划。它的核心价值是保持traceability——源材料中的范围、排序、承诺和术语，必须在最终artifact中清晰可辨。

Traceability的重要性

在AI辅助工作的场景中，traceability是一个容易被忽视但至关重要的质量保障。当AI帮助整理和呈现一份计划时，它可能在"优化"过程中不知不觉地改变了原始意图——删掉一个它认为不重要的功能点、调换两个需求的优先级、把一个模糊的承诺改成了一个精确的表述。这些改变可能都是善意的，但累积起来可能导致最终交付物与原始期望大相径庭。

html-plan要求：原始材料中的每一个承诺，在最终artifact中都应该是可定位、可对照的。这不是为了推卸责任，而是为了建立清晰的责任边界——什么是用户原本就同意的，什么是AI的假设，什么是开放问题。

设计原则

• 不添加时间线、进度百分比、状态徽章或仪表板摘要，除非源材料中明确支持这些元素
• 用表格做精确映射：当需要对比多个维度的信息时，表格是最清晰的表达方式
• 只有当顺序使内容更容易理解时才用流程或时间线：不是所有计划都需要线性的时间轴
• 长prose保持可读性：不要为了"现代化"而强制把文字内容拆成卡片形式

2.6 html-diagram——图表技能

角色定位

html-diagram的目的是构建最小的视觉模型，使关系比纯文字更容易理解。这个"最小"很重要——图表的目的是增强理解，不是展示技术能力。一个复杂的图表如果不能让人一眼看懂，那就是失败的。

选择正确的模型

不同类型的信息关系需要不同的图表模型：

• Topology（拓扑）：展示组件和连接关系，适合系统架构图
• Sequence（序列）：展示时间有序的消息流，适合API调用、用户交互流程
• Process（流程）：展示步骤、分支和交接，适合业务流程
• State（状态）：展示状态转换和条件，适合状态机、生命周期
• Hierarchy（层级）：展示包含或所有权关系，适合组织结构、文件树
• Timeline（时间线）：展示随时间变化的多个维度，适合项目计划、历史版本
• Matrix（矩阵）：展示重复关系，适合对比分析、网格数据
• Quantitative（定量）：当幅度重要时使用，适合数据可视化

选择渲染方法

effective-html的一个重要观点是：不要因为输出是diagram就用SVG。渲染方法应该根据具体需求选择：

• HTML+CSS：适合静态布局的图表，响应式、可交互、无学习曲线
• SVG：适合矢量图形、路径动画
• Canvas：适合大量数据点的绘制
• WebGL：适合3D图形或高性能渲染

html-diagram会根据图表的复杂度、交互需求和目标受众，自动选择最合适的渲染方法。

---

三、核心设计哲学归纳

3.1 Fat Artifacts + Fat Context（胖工件 + 胖上下文）

这是effective-html最核心的理念。传统的AI prompt是文字的、线性的、上下文受限的。当人类尝试用文字描述一个界面时，总会遗漏大量细节，而这些遗漏的细节往往成为AI的理解歧义和输出偏差的来源。

effective-html的答案是：给AI足够的参考资料，用HTML artifact来展示意图。HTML是万能的视觉语言——几乎任何东西都可以用它来可视化，而且比文字描述更清晰。当AI生成一个artifact，人类可以直接看到、触摸、交互、验证——这是一个双向的、实时的、精确的沟通过程。

"胖上下文"的意义在于，它不仅提供了示例，更提供了决策框架。AI不是简单地模仿示例，而是学会了在什么场景下做什么决策。这使得AI的输出具有了系统性的质量保障，而非依赖随机性。

3.2 Separating Creative Freedom from Reliability（创意自由与可靠性分离）

effective-html的架构哲学体现了对AI辅助设计核心矛盾的深刻理解：一方面，我们希望AI有足够的创意空间，能够为每个主题创造独特的视觉表达；另一方面，我们又需要足够的约束来保证输出质量，避免AI陷入"安全但平庸"的陷阱。

effective-html的解法是分层解耦：

• 视觉方向来自对话、项目、受众和主题——这是创意的来源，不可压缩
• design-artifact提供可复用的设计流程和判断框架——这是可靠性的保障
• 每个专业技能（wireframe/prototype/plan/diagram）独立拥有其保真度和行为标准——这是专业性的体现

这种分层架构使得effective-html能够同时满足创意和可靠性的需求，而不是在两者之间做trade-off。

3.3 Consistent Care, Not Consistent Look（一致的关注，而非一致的外观）

这是对抗AI生成内容同质化的根本性对策。在effective-html看来，当前AI生成内容最大的问题不是"做不好"，而是"做得太像"。当所有AI都用Inter字体、rounded-lg圆角卡片、紫蓝渐变hero时，AI输出的价值就大打折扣了——因为缺乏独特性，缺乏对主题的深度回应。

effective-html要求每个artifact都有自己独特的视觉身份。同一套设计原则应用于所有artifact——遵循先例、锚定主题、双字体对话、避免AI美学通病——但最终的外观因主题而异。一个海洋保护网站和一个金融仪表板的视觉风格差异，应该像它们主题之间的差异一样大。

这意味着effective-html不是在建立一套"AI设计系统"，而是在建立一套"设计判断框架"。框架是通用的，应用是特定的。

3.4 The Artifact Is the Interface（artifact就是界面）

在effective-html的工作流中，HTML artifact不是中间产物，而是核心交付物。这要求每个artifact从一开始就是production-ready的：

• 响应式设计，适配各种屏幕宽度
• 可访问性，符合WAI-ARIA标准
• 自包含，不依赖外部资源
• 在浏览器中验证，所有功能可交互

这一理念对AI编码Agent的工作方式有深刻影响。AI不是在"写代码"，而是在"创造界面"。每一个输出的artifact都是可以直接服务于人类用户的。

3.5 Source Commitments Must Remain Verifiable（源承诺必须保持可验证）

对于计划类artifact，traceability原则是质量保障的关键。effective-html要求：原始材料中的范围、排序、承诺和术语，必须在最终artifact中清晰可辨。

这一原则防止了AI辅助工作中的"善意偏差"——AI在整理、优化、呈现信息的过程中，可能不知不觉地改变了原始意图。traceability使得任何人都可以对照原始材料，验证最终artifact是否忠实地反映了原始需求。

这对于需要严格合规的工作场景（如金融、医疗、法律领域）尤为重要。AI可以辅助工作，但不能替代责任。traceability是建立人机协作信任的基础。

3.6 No Placeholder, No Bullshit（不用占位符，不用废话）

effective-html对内容质量有近乎苛刻的要求：

• 不用lorem ipsum：任何文本内容都应该是有意义的、可读的、符合上下文的
• 用真实内容：名称、日期、数量、状态都应该是真实可信的虚构，而非占位符
• 每个控件都有功能：按钮要能点击、下拉框要能展开、表单要能提交
• 错误信息要诊断问题并给出修复方案：不能只说"出错了"，要说"文件大小超过10MB限制，请压缩后重试"

这些要求看似理所当然，但在AI生成的代码中却常常被忽视。effective-html将内容质量视为artifact可信度的基础——一个充斥着占位符和假控件的原型，没有人会认真对待。

---

四、实战教程：从安装到精通

4.1 安装技能集合

effective-html支持多种安装方式，覆盖了主流的AI编码环境。

安装整个集合

对于大多数用户，直接安装整个技能集合是最简单的方式：

npx skills add plannotator/effective-html

这条命令会安装所有六个技能，AI编码工具在处理HTML请求时就能自动路由到相应的专业技能。

列出并选择安装单个技能

如果只需要某个特定技能，可以先列出所有可用技能，然后选择性安装：

npx skills add plannotator/effective-html --list
npx skills add plannotator/effective-html --skill design-artifact
npx skills add plannotator/effective-html --skill html-wireframe
npx skills add plannotator/effective-html --skill html-prototype

Claude Code用户

Claude Code用户可以通过插件市场安装：

/plugin marketplace add plannotator/effective-html
/plugin install plannotator-effective-html@effective-html

Codex用户

Codex用户的安装方式：

codex plugin marketplace add plannotator/effective-html
codex plugin add plannotator-effective-html@effective-html

4.2 理解技能路由逻辑

理解技能的路由逻辑，是高效使用effective-html的前提。当用户提出HTML请求时，html技能会判断最窄的专业技能来处理。

以下是一个路由决策的参考表：

请求特征	路由目标
结构/层级/navigation/任务流未确定	html-wireframe
需要polished mockup或工作交互流	html-prototype
计划/路线图/实施序列	html-plan
关系/序列/拓扑/状态/系统行为	html-diagram
颜色/字体/构图/整体视觉基调待定	design-artifact + 相应专业技能
报告/解释器/着陆页/演示/工具/混合artifact	html（直接处理）

在实际使用中，用户不需要手动指定路由——html技能会根据请求内容自动判断。但如果用户明确知道自己的需求属于哪个场景，也可以直接调用相应技能以获得更专业的输出。

4.3 创建你的第一个Wireframe

让我们通过一个具体场景来演示wireframe的创建过程。假设需要为一个博客平台创建文章详情页的wireframe。

第一步：明确评审问题

在开始设计之前，先问自己：这次wireframe要回答什么问题？

对于博客文章详情页，核心评审问题可能是：

• 用户能否快速找到文章的标题、作者和发布时间？
• 正文内容的阅读体验是否舒适（行宽、字间距、段落间距）？
• 相关文章推荐的位置是否合理？
• 移动端导航是否能正常展开和收起？

第二步：确定必须包含的信息和操作

基于评审问题，列出必须包含的元素：

• 文章标题（h1）
• 作者头像、名称、发布日期
• 文章正文区域
• 标签/分类
• 评论区入口
• 相关文章推荐区块
• 移动端汉堡菜单

第三步：创建2-3个有实质差异的布局方向

为了高效探索布局方案，在同一HTML中创建多个方向供对比：

<!-- 方向A：左侧边栏布局 -->
<div class="layout-sidebar-left">
  <nav class="sidebar-nav">...</nav>
  <main class="article-content">...</main>
</div>

<!-- 方向B：右侧边栏布局 -->
<div class="layout-sidebar-right">
  <main class="article-content">...</main>
  <aside class="sidebar-recommendations">...</aside>
</div>

<!-- 方向C：居中单栏布局 -->
<div class="layout-single-column">
  <main class="article-content">...</main>
</div>

每个方向用selector隐藏/显示，键盘可以切换对比。

第四步：故意保持未完成

Wireframe中：

• 使用#888、#ccc等灰度色，不使用任何品牌色
• 使用font-family: system-ui，不用任何自定义字体
• 使用简单的1px #ddd边框，不用阴影或圆角
• 正文区域用"[这里是文章正文内容...]"这样的标注占位符

第五步：验证

在不同宽度下检查：

• 桌面宽度（1200px+）：阅读顺序是否自然？
• 平板宽度（768px）：换行是否合理？侧栏是否折叠？
• 移动宽度（375px）：内容是否溢出？导航是否可操作？

4.4 创建工作原型

继续上面的场景，当我们确定了布局方向（比如选择方向B右侧边栏），就需要创建更完整的原型来验证视觉设计和交互细节。

第一步：确定模式

这次需要创建的是交互原型（prototype），因为要验证评论区的展开、标签的点击、相关推荐卡片的hover效果等。

第二步：推导视觉方向

从博客平台的主题出发：

• 这是一个知识分享类博客，受众是技术从业者和学习者
• 需要传达专业性和可信赖感
• 但也要有适度的亲和力，不能太严肃

视觉方向的推导：

• Color: 主色调用深蓝（#1a365d）传达专业，蓝绿（#319795）作为accent传达活力，背景用米白（#fafafa）保证阅读舒适度
• Type: 选用思源宋体（display，用于标题）和思源黑体（body，用于正文）——一个有文化感，一个清晰易读
• Layout: 右侧边栏固定宽度（约280px），正文区域最大宽度680px（保证阅读舒适度），整体居中对齐

第三步：选择最小流

原型只覆盖核心评审路径：

1. 文章详情页加载
2. 点击评论区入口，评论区展开
3. 点击一个标签，进入标签文章列表
4. hover相关推荐卡片，显示简要信息

其他功能（搜索、用户登录、收藏等）都做静态桩。

第四步：建模相关状态

对于评论区块，需要建模的状态：

• 正常加载状态：显示评论列表
• Loading状态：骨架屏
• 空状态：显示"暂无评论，成为第一个评论者"
• 错误状态：显示错误信息和重试按钮

第五步：实现完整交互

• 所有按钮和链接键盘可聚焦，焦点状态可见
• 评论区块是一个dialog，有可访问名称
• Escape键可以关闭评论区块
• 错误信息与相关控件正确关联

4.5 使用design-artifact进行创意指导

让我们通过另一个场景来演示design-artifact的使用：为一个海洋保护公益组织设计年度捐款页面。

第一步：读懂简报

这是一个着陆页，用于号召用户捐款。属于**编辑型（editorial）**模式——需要conviction和诚实的美学赌注。捐款页面的单一目的是：让访客完成捐款动作。这意味着设计需要建立信任、传递紧迫性、展示影响力。

第二步：寻找先例

检查项目中是否有现有的设计系统。假设这是一个全新的项目，没有既有的样式规范。那么需要从零开始建立视觉方向。

第三步：锚定主题

海洋保护主题的视觉语言应该从哪里挖掘？

• 海洋的蓝——但不是通用的"科技蓝"，而是深海的那种深邃的、层次丰富的蓝
• 波浪的曲线——动态但有序，不是混乱的
• 海洋生物的形态——哺乳动物、珊瑚礁的形状可以作为装饰元素
• 海洋的尺度——广袤、深远、人类在其中显得渺小但又有行动的力量

锚定方向：深邃的海洋感 + 行动的希望感。

第四步：制定设计计划

在写代码之前，先写设计计划：

Color:
- Deep Ocean: #0a2540 (主背景，传达深邃和信任)
- Seafoam: #00c9a7 (accent，传达行动和希望)
- Coral: #ff6b6b (次要accent，用于紧迫性提示如倒计时)
- Sand: #f5f0e8 (浅色文字背景区域)
- Pearl: #ffffff (正文文字)
- Slate: #8898aa (次要文字和边框)

Type:
- Display: Playfair Display (衬线，传达公益组织的文化感和严肃性)
- Body: Source Sans Pro (清晰易读，用于所有正文内容)
- Mono: JetBrains Mono (用于数据展示，如捐款金额)

Layout:
- 单栏叙事布局，从上到下引导用户完成"理解问题→看到行动方案→做出捐款决定"的流程
- Hero区域全屏，用深蓝色背景和波浪SVG装饰
- 后续内容区域用浅色背景，与Hero形成节奏对比

第五步：Originality Check

设计完成后，做原创性检查：

• 如果把这个视觉方向换成一个"医疗援助公益组织"，合理吗？——不太合理，海洋的视觉语言太独特了
• 如果换成"儿童教育公益组织"呢？——不合理，教育组织需要更温暖、更亲和的视觉

通过检查，说明这个视觉方向是主题特定的，不是泛化的。

第六步：严格执行计划

代码中：

• 每个颜色都要追溯到设计计划中的定义
• 字体用@font-face data URI内嵌
• 布局严格按照计划执行

4.6 发布Artifact（用tot）

当artifact完成并通过评审后，下一步是分享。effective-html推荐使用tot工具将artifact发布为公开可访问的URL。

安装tot

npm install -g @plannotator/tot

发布artifact

tot path/to/artifact.html

命令执行后，tot会返回生成的公开URL。这个URL可以直接分享给任何人，他们可以在浏览器中打开并与artifact交互。

tot的设计理念与effective-html一致——artifact应该是自包含的、可移植的、可验证的。通过tot发布的页面不依赖任何外部服务，所有CSS、JavaScript和字体都内联在HTML中。

---

五、项目启发：对AI编码Agent未来的思考

5.1 HTML作为AI到人类的通信协议

effective-html最深刻的洞察，可能是HTML在AI-人类通信中的独特地位。当AI需要向人类传达复杂的概念、结构或交互时，HTML是一种比文字更高效、比代码更直观的媒介。

传统的AI coding工作流是：人类用文字描述需求，AI生成代码，人类阅读代码理解结果。这种方式的问题是，代码的语义和视觉效果之间存在gap——人类需要通过想象力将代码翻译成界面，这个过程容易出错且效率低下。

effective-html倡导的直接产出HTML artifact，让人类可以直接看到和交互结果。这是一个从文字到视觉的范式转变，它意味着：

• AI的输出本身就是交付物，而非中间产物
• 人机协作的反馈循环大大缩短
• AI生成内容的可验证性大幅提升

对于AI编码Agent的未来，这意味着HTML可能会成为AI-人类通信的"第二语言"。不是所有场景都需要HTML——对于简单查询，文字回复仍然高效——但对于复杂的信息结构、界面设计、数据可视化，HTML artifact的优势是无可替代的。

5.2 技能路由是Agent架构的核心问题

effective-html用"窄技能路由"解决了一个AI领域的经典问题：通用模型在所有任务上都强，但在特定任务上不如专用技能。

传统的解法有几种：

• 微调：为特定任务训练专用模型。效果精准，但成本高、不灵活
• Prompt engineering：用更详细的prompt引导通用模型。灵活但不稳定，质量依赖prompt质量
• 模型选择：根据任务类型选择不同的模型。效果好但需要管理多个模型实例

effective-html的方案是：在通用层和专用层之间建立路由机制。html技能作为通用层，处理广泛的HTML请求，同时将任务分发给最窄的专业技能。这种架构的优势：

• 不需要微调，通用模型的能力通过技能化调用得到发挥
• 不依赖完美的prompt，路由逻辑是结构化的、可预测的
• 不需要管理多个模型，所有技能运行在同一个模型上
• 扩展性好，新增技能只需要定义路由规则和技能内容

对于AI编码Agent的架构设计，技能路由提供了一个有价值的思路：不是换一个更强的模型，而是让模型更好地调用自己的能力。

5.3 设计系统的范式转移

传统设计系统的目标是为团队建立一致的视觉语言。这套范式在人类设计师协作的场景下非常有效——它减少了重复决策、建立了视觉一致性、加速了设计开发流程。

但effective-html让我们看到另一种设计系统的可能：为每个artifact建立独特的主题视觉。

这两种范式的核心差异：

维度	传统设计系统	effective-html设计哲学
目标	一致性	主题适切性
核心假设	同一团队应该有相同品味	同一主题应该有相同视觉语言
可复用性	高，大量组件和模式	低，每个artifact独特
维护重点	组件库和样式规范	设计原则和判断框架

在AI生成的语境下，后者更合理。原因在于：AI生成的内容天然缺乏对主题的深度响应。如果没有明确的指导，AI会倾向于最常见的解决方案——这就是"AI美学通病"的来源。effective-html的设计哲学，正是通过设计原则和判断框架，引导AI走出安全区，进入为主题量身定制的视觉领域。

这种范式转移对设计系统的构建者提出了新的要求：不是维护一个组件库，而是维护一个设计知识库——包含设计原则、场景分析、常见错误、反模式案例等。effective-html技能集合正是这种新范式的实践。

5.4 "故意未完成"作为认知工具

Wireframe故意保持"未完成"状态，这不是偷懒，而是一个认知设计选择。

在人类的设计评审中，有一个常见的陷阱：审美先于功能。当评审者看到一个视觉上不完美的设计时，他们往往会陷入对颜色、字体、间距的讨论，而忽略了更根本的问题——这个信息架构合理吗？用户的任务流顺畅吗？这个优先级正确吗？

Wireframe的"未完成"是对这个陷阱的反制。当一切都看起来像半成品，评审者就无法沉浸在对审美的讨论中，只能聚焦在结构和逻辑上。这是一个巧妙的认知技巧——通过降低审美期望来提升功能反馈的质量。

对于AI协作，这一洞察有更广泛的应用。AI的输出不一定总要"看起来完整"。有时候，一个"粗糙但结构清晰"的中间产物，比一个"精致但结构存疑"的成品更有价值。关键在于让评审者能够聚焦在真正重要的问题上。

Effective-html将这个洞察系统化了。Wireframe要"故意未完成"，Prototype要建模所有状态、Plan要traceable to source——这些都是为了让每个artifact在其生命周期中承担正确的认知功能。Wireframe用来探索结构，Prototype用来验证交互，Plan用来追溯承诺。功能分离，认知清晰。

---

六、相关资源

项目主页与文档

Effective HTML指南：https://www.effectivehtml.com/

这是effective-html项目的官方指南网站，包含了项目理念、技能介绍、使用教程等核心内容。对于想要深入理解项目设计的读者，这是最佳的起点。

Plannotator项目主页：https://github.com/backnotprop/plannotator

Plannotator是effective-html的开发和维护组织。该GitHub仓库包含了所有技能的最新源码，以及issue跟踪和社区讨论。

教程与深度阅读

HTML Wireframes and Prototypes for Coding Agents：https://docs.plannotator.ai/learn/code-context/html-wireframes-and-prototypes-for-coding-agents

这是官方文档中关于wireframe和prototype的深度教程，包含了许多实战案例和最佳实践。对于想要系统学习effective-html方法论的读者，这是最权威的学习资源。

Thariq Shihipar "The unreasonable effectiveness of HTML"：https://thariqs.github.io/html-effectiveness

这是一篇来自Plannotator团队的深度文章，阐述了HTML作为AI-人类通信媒介的理论基础。文章从历史、认知和实践三个维度，分析了HTML在AI coding场景下的独特优势。

工具与扩展

tot（HTML发布工具）：https://github.com/plannotator/tot

tot是effective-html生态中的发布工具，用于将HTML artifact发布为公开可访问的URL。它的设计理念与effective-html一致——产出的页面是自包含的，不依赖外部服务。

社区与生态

effective-html作为一个开源项目，其发展离不开社区的贡献。Plannotator组织在GitHub上维护着多个相关项目，覆盖了从HTML artifact创作到发布的完整工作流。对于有开发能力的读者，可以深入研究源码，理解技能的具体实现；对于产品背景的读者，官方文档和教程已经足够上手使用。

---

结语

plannotator/effective-html项目代表了一种新兴的AI编码范式：不是用更强的模型，而是用更好的工作流程。通过技能化的架构、设计原则的体系化、以及对"胖上下文"和"胖工件"的强调，effective-html让AI能够在HTML artifact创作这件事上，达到接近专业前端开发者的水准。

对于已经在使用或计划使用AI编码Agent的开发者而言，effective-html提供了两个层面的价值：

工具层面，它提供了一套可直接使用的技能集合，覆盖了从线框图到高保真原型的完整场景。只要安装配置好，AI就能在各种HTML创作任务中提供系统性的高质量输出。

思维层面，它提供了一种重新思考AI-人类协作方式的视角。HTML作为通信媒介、技能作为路由架构、"故意未完成"作为认知工具——这些洞察不仅适用于HTML创作，对于AI coding agent的整体设计也有广泛的启发意义。

AI编码工具正在快速进化，effective-html是这场进化中的一个重要节点。它展示的不仅是"怎么做"，更是"为什么这么做"。理解这些背后的思考，或许比掌握具体技能更有长远的价值。

---

作者：比特财商

完稿日期：2026年8月