design-it

design-it

概述

按照固定的风格生成一份独立的 HTML 文件技术设计文档，让每一项新需求都生成视觉效果一致的页面。样式不是每次临时设计的，而是来自固定的 <style> 块和固定的章节骨架。你的工作是将内容填入骨架，而不是重新设计。

核心原则： 原样复制 template.html，然后只替换内容。<style> 块必须逐字节保持不变。一致性来自不触碰设计系统。

适用场景

• 用户提出新的需求 / 规格 / 功能，并希望获得设计文档。
• 将 .md 技术规格转换为便于分享的 HTML 格式。
• 任何类似“生成同样的 html / 用这套模板 / 出一份设计文档”的请求。

不适用场景： 临时速记、用户希望保留 Markdown 格式的 Markdown 交付物，或幻灯片。

工作流

1. 复制模板。 从此技能目录中的 template.html 开始。不要手动编写 <head> / <style>，要完整复制。
2. 先收集真实内容。 章节标题、字段名称、SQL、file:line 代码位置、protoIds 等，都必须来自实际需求文档和代码库。阅读代码，不要编造标识符。如果某项事实未知，请标记为 <span class="pill todo">待确认</span>，绝不要猜测。
3. 填充骨架。 根据功能重命名 / 重新排序 <section>。保留章节类型：已对齐结论 → 业务规则 → 架构图 → 时序 → 数据模型 → 契约 → 清单 → 幂等降级 → 测试用例 → 代码索引 → 变更记录。删除不适用的章节；按照相同风格添加特定于功能的章节。
4. 保持目录与章节同步。 每个 <a href="#x"> 都必须有对应的 <section id="x">，反之亦然。这是最常见的故障点——最后务必检查（参见快速参考）。
5. 保存为 docs/<需求名>.html。除非有人要求，否则不要提交。

统一风格规则（不可妥协）

元素	规则
<style> 块	原样复制。绝不重新设计样式。颜色只能来自 :root CSS 变量。
代码 / SQL / YAML	始终使用模板中的 <pre style="background:#f8fafc;...">。在 <pre> 内，将 < 转义为 &lt;，将 > 转义为 &gt;，将 & 转义为 &amp;。 未转义的 < 会悄无声息地吞掉内容。
提示框	.note（橙色，提醒 / 易错）、.tip（蓝色，正向补充）、.warn（红色，风险）。根据含义使用正确的颜色。
图表	在 <figure> 中手工编写内联 <svg>；文本使用 .svg-t / .svg-s / .svg-title；节点填充色使用 :root 变量（如 var(--new-bg)），并与 .legend 保持一致。
引言	每个章节以一个 <p class="lead"> 开头，说明该章节要回答的问题。
状态标签	状态标签使用 .pill.new/.old/.infra/.mq/.prod/.tech/.done/.todo，重复使用这些类，不要另创类名。
表格	使用普通 <table>，CSS 会处理斑马纹和表头底色。
语言	使用 <html lang="zh">；文档正文使用文档对应的语言（通常为中文）。

常见错误

• 重新设计 CSS。 整份文档的核心就是输出一致——不要“改进”颜色、间距或字体。原样复制 <style>。
• 在 <pre> 中未转义尖括号。 List<String> 会被渲染为损坏的标签。应转义为 List<String>。
• 目录链接失效。 添加章节时漏掉目录项，或重命名 id 后忘记修改 href。务必交叉检查。
• 编造代码位置。 file:line、表名、protoIds 必须从代码库中读取。未知内容 → 使用 待确认 标签，不要给出看似合理的猜测。
• 把文档写成提案。 保持它是一份设计文档（内容与实现方式、已确定的决策），而不是一份说服性提案。

快速参考 — 最终自检

f="docs/<需求名>.html"
# TOC hrefs vs section ids must match exactly (no output = perfect):
diff <(grep -oE 'href="#[a-z0-9-]+"' "$f" | sed 's/.*#//;s/"//' | sort -u) \
     <(grep -oE '<section id="[a-z0-9-]+"' "$f" | sed 's/.*"//' | sort -u)
# open in browser to eyeball diagrams + code blocks render cleanly