design-it

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

design-it

生成设计文档

Overview

概述

Generate a technical design document as one self-contained HTML file in a fixed house style, so every new 需求 produces a visually identical page. The look is not improvised each time — it comes from a fixed

<style>

block and a fixed section skeleton. Your job is to fill content into that skeleton, never to redesign it.

Core principle: Copy

template.html

verbatim, then replace only the content. Keep the

<style>

block byte-for-byte. Consistency comes from not touching the design system.

生成符合固定内部风格的独立HTML格式技术设计文档，确保每个新需求对应的页面视觉效果完全一致。文档外观并非临时设计——它来自固定的

<style>

块和固定的章节框架。你的任务是将内容填充到该框架中，绝不能重新设计框架。

核心原则： 完整复制

template.html

，仅替换内容部分。

<style>

块需完全原样保留。一致性源于不修改设计系统。

When to Use

使用场景

The user gives a new requirement / spec / feature and wants a design doc.
Converting a
```
.md
```
technical spec into the shareable HTML form.
Any request like "生成同样的 html / 用这套模板 / 出一份设计文档".

When NOT to use: quick throwaway notes, a real Markdown deliverable the user wants to stay Markdown, or slide decks.

用户提供新需求/规格说明/功能，需要生成设计文档时。
将
```
.md
```
格式的技术规格转换为可共享的HTML格式时。
任何类似「生成同样的html / 用这套模板 / 出一份设计文档」的请求。

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

Workflow

工作流程

Copy the template. Start from
```
template.html
```
in this skill's directory. Do not hand-roll the
```
<head>
```
/
```
<style>
```
— copy it whole.
Gather real content first. Section titles, field names, SQL,
```
file:line
```
code positions, protoIds — all must come from the actual requirement doc and codebase. Read the code; do not invent identifiers. If a fact is unknown, mark it
```
<span class="pill todo">待确认</span>
```
, never guess.
Fill the skeleton. Rename/reorder
```
<section>
```
s to fit the feature. Keep the section kinds: 已对齐结论 → 业务规则 → 架构图 → 时序 → 数据模型 → 契约 → 清单 → 幂等降级 → 测试用例 → 代码索引 → 变更记录. Drop what doesn't apply; add feature-specific ones in the same style.
Keep TOC and sections in sync. Every
```
<a href="#x">
```
needs a matching
```
<section id="x">
```
, and vice versa. This is the #1 breakage — verify at the end (see Quick Reference).
Save as
```
docs/<需求名>.html
```
. Don't commit unless asked.

复制模板：从本技能目录下的
```
template.html
```
开始。不要手动编写
```
<head>
```
/
```
<style>
```
——完整复制整个文件。
先收集真实内容：章节标题、字段名、SQL语句、
```
file:line
```
代码位置、protoIds——所有内容必须来自实际需求文档和代码库。查看代码，不要编造标识符。如果某个信息未知，标记为
```
<span class="pill todo">待确认</span>
```
，绝不要猜测。
填充框架：重命名/调整
```
<section>
```
顺序以适配功能。保留章节类型：已对齐结论 → 业务规则 → 架构图 → 时序图 → 数据模型 → 契约 → 清单 → 幂等降级 → 测试用例 → 代码索引 → 变更记录。删除不适用的章节；以相同风格添加功能专属章节。
保持目录与章节同步：每个
```
<a href="#x">
```
必须对应一个
```
<section id="x">
```
，反之亦然。这是最常见的错误——最后务必验证（参见快速参考）。
保存为
```
docs/<需求名>.html
```
。除非被要求，否则不要提交代码。

House-Style Rules (non-negotiable)

内部风格规则（不可协商）

Element	Rule
`<style>` block	Copy verbatim. Never restyle. Colors come from `:root` CSS variables only.
Code / SQL / YAML	Always the template's `<pre style="background:#f8fafc;...">` . Inside `<pre>` , escape `<` → `<` , `>` → `>` , `&` → `&` . Unescaped `<` silently eats content.
Callout boxes	`.note` (橙, 提醒/易错), `.tip` (蓝, 正向补充), `.warn` (红, 风险). Use the right color for the meaning.
Diagrams	Hand-authored inline `<svg>` inside `<figure>` ; text uses `.svg-t` / `.svg-s` / `.svg-title` ; node fills use `:root` vars ( `var(--new-bg)` etc.), matching the `.legend` .
Intro	Each section opens with one `<p class="lead">` stating what it answers.
Pills	`.pill.new/.old/.infra/.mq/.prod/.tech/.done/.todo` for status tags — reuse, don't invent classes.
Tables	Plain `<table>` — the CSS handles zebra striping and header shading.
Lang	`<html lang="zh">` ; body copy in the doc's language (usually 中文).

元素	规则
`<style>` 块	完整原样复制。绝不要重新设置样式。颜色仅来自 `:root` CSS变量。
代码/SQL/YAML	始终使用模板中的 `<pre style="background:#f8fafc;...">` 。在 `<pre>` 内部，需将 `<>` 转义为 `<` ， `>` 转义为 `>` ， `&` 转义为 `&` 。未转义的 `<` 会导致内容丢失。
提示框	`.note` （橙色，提醒/易错点）、 `.tip` （蓝色，正向补充）、 `.warn` （红色，风险提示）。根据含义选择正确的颜色。
图表	在 `<figure>` 内手动编写内嵌 `<svg>` ；文本使用 `.svg-t` / `.svg-s` / `.svg-title` ；节点填充色使用 `:root` 变量（如 `var(--new-bg)` ），与图例匹配。
引言	每个章节开头使用一个 `<p class="lead">` 说明本章节要解答的问题。
状态标签	使用 `.pill.new/.old/.infra/.mq/.prod/.tech/.done/.todo` 作为状态标签——复用现有类，不要自定义类。
表格	使用普通 `<table>` ——CSS会处理斑马纹和表头着色。
语言	`<html lang="zh">` ；文档主体内容使用对应语言（通常为中文）。

Common Mistakes

常见错误

Redesigning the CSS. The whole point is identical output — don't "improve" colors, spacing, or fonts. Copy
```
<style>
```
untouched.
Unescaped angle brackets in
<pre>
.
```
List<String>
```
renders as a broken tag. Escape to
```
List&lt;String&gt;
```
.
Dead TOC links. Adding a section without its TOC entry (or renaming an
```
id
```
and forgetting the
```
href
```
). Always cross-check.
Inventing code positions.
```
file:line
```
, table names, protoIds must be read from the repo. Unknown →
```
待确认
```
pill, not a plausible-looking guess.
Making it a proposal. Keep it a design doc (what/how, locked decisions), not a persuasive pitch.

重新设计CSS：核心目标是输出一致的文档——不要「优化」颜色、间距或字体。完全复制
```
<style>
```
块。
<pre>
内未转义尖括号：
```
List<String>
```
会渲染为损坏的标签。需转义为
```
List&lt;String&gt;
```
。
无效目录链接：添加章节但未添加对应的目录条目（或重命名
```
id
```
但忘记更新
```
href
```
）。务必交叉检查。
编造代码位置：
```
file:line
```
、表名、protoIds必须从代码库中获取。未知内容→标记为
```
待确认
```
标签，不要猜测看似合理的内容。
将文档写成提案：保持文档为设计文档（说明内容和实现方式、已确定的决策），而非说服性的提案。

Quick Reference — final self-check

快速参考——最终自检

bash

f="docs/<需求名>.html"

bash

f="docs/<需求名>.html"

TOC hrefs vs section ids must match exactly (no output = perfect):

目录href与章节id必须完全匹配（无输出即为正确）：

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

在浏览器中打开，检查图表和代码块是否正常渲染

undefined

undefined