declarative-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Declarative Design

声明式设计

Bring UI designs into a project tied to a PRD requirement. Implements Phase 4 of the AI Development Framework V2.

将UI设计与PRD需求绑定带入项目。实现AI开发框架V2的第4阶段。

Core principle

核心原则

Designs are inputs to implementation, not after-the-fact polish. Each design MUST be traceable to a requirement (FR-N), machine-readable (HTML, not just a screenshot), and stored where the agent can find it (

docs/designs/<FR-N>-<slug>.html

). Pixel-pushing is replaced by vibe design: describe the intent, iterate on output.

设计是开发的输入，而非事后润色。每个设计必须可追溯到某一需求（FR-N格式）、机器可读（HTML格式，而非仅截图），且存储在Agent可检索的位置（

docs/designs/<FR-N>-<slug>.html

）。像素级调整被“氛围设计”替代：描述设计意图，迭代输出结果。

When to use

使用场景

Requirement exists, no designs yet → start at Phase 1 to identify needed screens, then generate via Stitch/Claude Design.
User already has HTML/screenshot exports → start at Phase 3 to place them.
Designs exist but are unlinked / poorly named → start at Phase 3 with the existing files as input.

Skip for: backend-only requirements, CLI tools, internal services with no UI.

已有需求但尚无设计 → 从第1阶段开始，先识别所需界面，再通过Stitch/Claude Design生成设计。
用户已拥有HTML/截图导出文件 → 从第3阶段开始，放置这些文件。
已有设计但未关联需求/命名不规范 → 以现有文件为输入，从第3阶段开始。

以下情况无需使用：仅后端需求、CLI工具、无UI的内部服务。

The 3 phases

三个阶段

Each phase has an INPUT, an OUTPUT, and a HUMAN GATE before advancing.

#	Phase	Input	Output	Prompt file
1	Identify screens	Requirement bundle ( `docs/prd/` )	Screen list (per state)	prompts/01-identify-screens.md
2	Acquire designs	Screen list	HTML + screenshot pairs in user's hands	prompts/02-acquire-designs.md
3	Place designs	Files from user	Files in `docs/designs/` , named per convention, cross-linked	prompts/03-place-designs.md

Phase 2 is the only phase that does not produce a file inside the repo — its output is the user going off to Stitch / Claude Design and returning with exports. The skill's job there is to give the user a useful design prompt and wait.

每个阶段都包含输入、输出，以及进入下一阶段前的人工审核环节。

#	阶段	输入	输出	提示文件
1	识别界面	需求包（ `docs/prd/` ）	按状态划分的界面列表	prompts/01-identify-screens.md
2	获取设计	界面列表	用户手中的HTML + 截图对	prompts/02-acquire-designs.md
3	放置设计	用户提供的文件	存储在 `docs/designs/` 路径下、符合命名规范并已交叉关联的文件	prompts/03-place-designs.md

第2阶段是唯一不会在仓库内生成文件的阶段——其输出是用户前往Stitch / Claude Design获取导出文件后返回。本Skill在此阶段的任务是为用户提供实用的设计提示并等待结果。

Operating protocol

操作流程

Identify the requirement ID. If not given, ASK. Use the same FR-N format as
```
generate-dev-plan
```
and
```
ai-driven-prd
```
.
Read the matching prompt file in
```
prompts/
```
. Treat the prompt body as a system instruction — follow its rules literally.
Stop at every phase boundary. Show artifact, ask: approved / refine / restart phase.
Phase 2 fork: at the start of Phase 2, ask the user "Do you already have HTML exports for these screens?" If yes, skip to Phase 3 with those files as input. If no, produce the vibe-design prompt from templates/vibe-prompt.md.tmpl.
Phase 3 final gate: score against references/checklist.md. All 6 items MUST pass.

确定需求ID。若未提供，则询问用户。使用与
```
generate-dev-plan
```
和
```
ai-driven-prd
```
相同的FR-N格式。
读取
prompts/
目录下对应的提示文件。将提示内容视为系统指令——严格遵循其规则。
在每个阶段边界处暂停。展示生成的成果，询问：批准/优化/重启本阶段。
第2阶段分支：在第2阶段开始时，询问用户*“您是否已拥有这些界面的HTML导出文件？”*。若是，则直接进入第3阶段，以这些文件为输入；若否，则根据templates/vibe-prompt.md.tmpl生成氛围设计提示。
第3阶段最终审核：依据references/checklist.md进行评分。必须全部通过6项检查。

Hard rules (non-negotiable)

硬性规则（不可协商）

Naming convention:
```
docs/designs/<FR-N>-<slug>.{html,png}
```
— no exceptions. The
```
<slug>
```
is a kebab-case short name (
```
login
```
,
```
password-reset
```
,
```
cart-empty-state
```
). Both HTML and PNG share the slug.
Pair invariant: every HTML MUST have a matching PNG screenshot. The PNG is for humans skimming
```
docs/designs/
```
; the HTML is for the agent.
One screen state per file. If a requirement has 3 states (empty / loading / error), produce 3 file pairs, not 1 with all states stacked.
Trace to AC. Each design's filename or sidecar note maps to the ACs it visualizes. If a design doesn't visualize any AC, ask the user why it's needed.
No raw Figma exports. Figma → static image is fine for screenshots only; the HTML must come from a tool that produces clean, semantic HTML (Stitch, Claude Design, hand-written). Pixel-perfect Figma HTML exports are unreadable and useless to the agent.
Don't hide constraints in screenshots. If a behavior matters (e.g. "submit button disabled until terms accepted"), it MUST live in the PRD's AC, not only in the design. Designs visualize; ACs specify.
Ambiguity → ASK. Never invent a screen the requirement doesn't call for.

命名规范：
```
docs/designs/<FR-N>-<slug>.{html,png}
```
——无例外。
```
<slug>
```
为短横线分隔的小写名称（如
```
login
```
、
```
password-reset
```
、
```
cart-empty-state
```
）。HTML和PNG文件共享同一slug。
配对规则：每个HTML文件必须对应一个PNG截图。PNG供快速浏览
```
docs/designs/
```
目录的人员查看；HTML供Agent使用。
单文件单状态：若某一需求包含3种状态（空状态/加载中/错误），则生成3组文件对，而非1个包含所有状态的文件。
关联验收标准（AC）：每个设计的文件名或附带说明需映射到其可视化的验收标准。若某设计未可视化任何验收标准，需询问用户其必要性。
禁止直接导出Figma文件：Figma导出为静态图片仅可用于截图；HTML必须来自能生成简洁、语义化HTML的工具（Stitch、Claude Design、手写代码）。Figma导出的像素级完美HTML文件可读性差，对Agent毫无用处。
约束不可仅隐藏在截图中：若某一行为至关重要（如“勾选条款前提交按钮禁用”），必须在PRD的验收标准中明确说明，不可仅体现在设计中。设计用于可视化；验收标准用于明确规则。
遇歧义必询问：绝不可凭空创造需求未提及的界面。

What NOT to do

禁止事项

See references/anti-patterns.md. Top three to watch:

Bundling unrelated requirements. One file pair per
```
<FR-N>-<slug>[-<state>]
```
. No
```
auth-screens.html
```
covering FR-001 + FR-002 + FR-003.
Inventing states. Phase 1's screen list is the contract. Don't add a "loading" or "error" design unless the requirement calls for one.
Stale designs. When the PRD changes meaningfully, rename affected designs to
```
<FR-N>-<slug>.STALE.html
```
and rerun Phase 2 — never silently use outdated designs.

详见references/anti-patterns.md。需重点关注以下三点：

捆绑无关需求：每个文件对应一组
```
<FR-N>-<slug>[-<state>]
```
。禁止使用
```
auth-screens.html
```
涵盖FR-001 + FR-002 + FR-003等多个需求。
凭空添加状态：第1阶段确定的界面列表为约定内容。除非需求明确要求，否则不可添加“加载中”或“错误”状态的设计。
使用过期设计：当PRD发生重大变更时，将受影响的设计重命名为
```
<FR-N>-<slug>.STALE.html
```
并重新运行第2阶段——绝不可静默使用过期设计。

References

参考资料

Vibe-design prompt scaffold: templates/vibe-prompt.md.tmpl
Phase prompts: prompts/01-identify-screens.md, prompts/02-acquire-designs.md, prompts/03-place-designs.md
6-point handoff checklist: references/checklist.md
Anti-patterns and remedies: references/anti-patterns.md
Naming convention details: references/naming.md
Source framework: ../../docs/framework.md
Tooling: Stitch — Google's vibe-design tool. Claude Design — Anthropic's design tool.

氛围设计提示模板：templates/vibe-prompt.md.tmpl
阶段提示文件：prompts/01-identify-screens.md、prompts/02-acquire-designs.md、prompts/03-place-designs.md
6项交接检查清单：references/checklist.md
反模式及解决方法：references/anti-patterns.md
命名规范细节：references/naming.md
源框架：../../docs/framework.md
工具：Stitch —— Google的氛围设计工具。Claude Design —— Anthropic的设计工具。