prd-to-uiux-rd-spec

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

PRD → UI/UX 研发规格（复刻级）交付流程

PRD → UI/UX R&D Specification (Replica-Grade) Delivery Process

目标：把“产品 PRD（总纲）”转化为前端可复刻实现的 UI/UX 研发规格文档包（UI 行为、状态机、数据/事件契约、A11y、验收与测试计划），并让目录结构本身就能传达“做到了什么/没做到什么”。

本 skill 的原则：

文档先行：先冻结“壳层/公共基座/契约”，再写模块页面细节。
目录即证据：打开文件夹即可判断覆盖度与可落地程度（不是散文集）。
可演进：对“未来会增减的内容版块”，用契约/模型承接（前端不写死章节）。
安全默认：本 skill 默认不改业务代码；若用户要求写代码，先把规格与契约写清，再另起任务实现。

Objective: Convert the "Product PRD (Master Outline)" into a front-end replicable UI/UX R&D specification document package (UI behaviors, state machines, data/event contracts, A11y, acceptance and test plans), and ensure the directory structure itself conveys "what has been accomplished/what is unfinished."

Principles of this skill:

Documentation First: Finalize the "shell/common foundation/contracts" before writing module and page details.
Directory as Evidence: The folder structure should allow immediate judgment of coverage and feasibility (not a collection of unstructured articles).
Evolvable: Use contracts/models to accommodate "content sections that will be added or removed in the future" (front-end does not hardcode sections).
Safe Default: This skill does not modify business code by default; if the user requests code implementation, first clarify the specifications and contracts before initiating a separate task for implementation.

0) 你需要向用户确认的输入（最少集）

0) Inputs You Need to Confirm from the User (Minimum Set)

PRD 路径/链接（或最小 PRD 框架）
是否存在只读参考基座（例如旧 UI/UX spec、设计系统、竞品稿件）；如果有，路径在哪里、是否允许改动
前端关键约束（至少选 1 套）：
- 图表库（如 ECharts）
- 图标库（如 lucide-react）
- 导出格式（如 PDF 默认、DOCX 权限、Markdown 复制/导出）
交付粒度：L1 小改 / L2 新模块 / L3 核心壳层（默认按 L2 交付）

如果缺 PRD：先用

references/output-contract.md

的“PRD 最小骨架”补齐，否则 UI/UX 规格会漂。

PRD path/link (or minimal PRD framework)
Whether a read-only reference foundation exists (e.g., old UI/UX spec, design system, competitor drafts); if yes, provide its path and whether modifications are allowed
Key front-end constraints (select at least one set):
- Chart libraries (e.g., ECharts)
- Icon libraries (e.g., lucide-react)
- Export formats (e.g., default PDF, DOCX permissions, Markdown copy/export)
Delivery granularity: L1 Minor Changes / L2 New Modules / L3 Core Shell (default to L2 delivery)

If PRD is missing: Use the "Minimal PRD Skeleton" in

references/output-contract.md

to supplement it, otherwise the UI/UX specifications will be inconsistent.

1) 输出契约（你必须产出的文件/结构）

1) Output Contracts (Mandatory Files/Structure)

默认推荐（可按仓库约定调整路径，但结构不变）：

```
docs/specs/prds/<date>-<slug>-prd.md
```
：产品 PRD（总纲）
```
docs/specs/ui-ux-rd-spec/
```
：UI/UX 研发规格（可复刻落地）
```
DOCS_INDEX.md
```
：仓库级文档索引（路径 + 一句话说明）
```
docs/worklog.md
```
：工作记录（命令 + 决策 + 结果）

docs/specs/ui-ux-rd-spec/

目录必须包含：

```
OVERVIEW.md
```
：UI/UX 总纲（能力地图 + TODO + 入口）
```
DOCS_INDEX.md
```
：本目录索引（每份规格文档的入口）
```
00_SourceInventory/
```
：来源/参考/覆盖映射
```
01_Foundation/
```
：公共基座（tokens/布局/交互/A11y/图标/图表等跨模块约束）
```
02_Components/
```
：可复用组件规格（含数据/事件契约）
```
03_Patterns/
```
：跨模块交互模式补充
```
04_Pages/
```
：页面复刻级规格（每页一份，含状态机/验收/测试计划）
```
05_A11y/
```
：A11y 汇总（新增组件/页面的约束）

模板见：

references/uiux-rd-spec-directory-skeleton.md

```
references/page-spec-template.md
```
```
references/component-spec-template.md
```
```
references/coverage-template.md
```

references/replica-readiness-checklist.md

Default recommendation (path can be adjusted according to repository conventions, but structure remains unchanged):

```
docs/specs/prds/<date>-<slug>-prd.md
```
: Product PRD (Master Outline)
```
docs/specs/ui-ux-rd-spec/
```
: UI/UX R&D Specification (Replica-Grade and Implementable)
```
DOCS_INDEX.md
```
: Repository-level document index (path + one-sentence description)
```
docs/worklog.md
```
: Work records (commands + decisions + results)

The

docs/specs/ui-ux-rd-spec/

directory must include:

```
OVERVIEW.md
```
: UI/UX Master Outline (capability map + TODO + entry points)
```
DOCS_INDEX.md
```
: Directory index (entry for each specification document)
```
00_SourceInventory/
```
: Source/reference/coverage mapping
```
01_Foundation/
```
: Common foundation (cross-module constraints for tokens/layout/interaction/A11y/icons/charts, etc.)
```
02_Components/
```
: Reusable component specifications (including data/event contracts)
```
03_Patterns/
```
: Supplementary cross-module interaction patterns
```
04_Pages/
```
: Replica-grade page specifications (one per page, including state machine/acceptance/test plan)
```
05_A11y/
```
: A11y summary (constraints for new components/pages)

Templates available at:

references/uiux-rd-spec-directory-skeleton.md

```
references/page-spec-template.md
```
```
references/component-spec-template.md
```
```
references/coverage-template.md
```

references/replica-readiness-checklist.md

2) 工作流（按顺序执行）

2) Workflow (Execute in Order)

Step 0：业务关键契约抽取 Gate（防“模板化空心”）

Step 0: Business Key Contract Extraction Gate (Prevent "Template Hollowing")

风险背景：文档过度模板化会出现“看起来很完整，但缺业务关键契约”的伤害。

本 Gate 的目标：在写 UI/UX 细节前，把“对象/术语/关键流程/权限边界/核心字段”先冻结到可引用的契约里。

最低要求（缺任何一项都不得进入 Step A 的大量产文档阶段）：

对象与术语（Glossary）：至少列出核心对象与关系（
```
Work/Project/Run/Artifact/...
```
）
关键流程（Key Flows）：每条流程写清“触发→状态机→产物→回流/导出”
权限边界（Roles/Permissions）：至少写清“默认只读 vs step-up 写入”的规则（若涉及）
关键字段口径：成本/耗时/状态等字段的“展示口径”必须能落到字段级（避免后续 UI 争议）

模板（可选）：

```
references/glossary-template.md
```

Risk Background: Over-template documentation may lead to "seemingly complete but lacking key business contracts" issues.

Goal of this Gate: Finalize "objects/terms/key workflows/permission boundaries/core fields" into referable contracts before writing UI/UX details.

Minimum requirements (cannot proceed to Step A's mass documentation phase if any item is missing):

Glossary: List at least core objects and relationships (e.g.,
```
Work/Project/Run/Artifact/...
```
)
Key Flows: For each flow, clarify "trigger → state machine → output → feedback/export"
Roles/Permissions: Clarify at least the rules for "default read-only vs step-up write access" (if applicable)
Core Field Definitions: The "display rules" for fields such as cost/duration/status must be specified at the field level (to avoid subsequent UI disputes)

Optional template:

```
references/glossary-template.md
```

Step A：先搭“复刻级骨架”（先让结构自证）

Step A: Build the "Replica-Grade Skeleton" First (Let the Structure Prove Its Value)

创建
```
ui-ux-rd-spec/
```
并按 skeleton 建好层级与入口文件：
- ```
OVERVIEW.md
```
  ：先写约束与导航（不要等写完再补）
- ```
DOCS_INDEX.md
```
  ：先登记每个将要出现的模块/页面（可先 stub）
如果存在只读参考基座（旧 spec/设计系统）：
- 明确只读：在
```
OVERVIEW.md
```
  与
```
00_SourceInventory/
```
  写清“引用但不修改”
- 目录同构：尽量与只读基座同构，降低“对照成本”

输出检查点：目录结构一眼看上去就像“能落地的工程规格”，而不是“零散文章集合”。

Create
```
ui-ux-rd-spec/
```
and build the hierarchy and entry files according to the skeleton:
- ```
OVERVIEW.md
```
  : Write constraints and navigation first (do not wait until all content is completed)
- ```
DOCS_INDEX.md
```
  : Register each module/page that will be created (can use stubs initially)
If a read-only reference foundation exists (old spec/design system):
- Explicitly Mark as Read-Only: Clarify "reference but do not modify" in
```
OVERVIEW.md
```
  and
```
00_SourceInventory/
```
- Isomorphic Directory: Align with the read-only foundation's directory structure as much as possible to reduce comparison costs

Output Checkpoint: The directory structure should look like "implementable engineering specifications" at a glance, not a collection of scattered articles.

Step B：冻结公共基座（Foundation）与壳层（Shell）

Step B: Finalize Common Foundation and Shell

在
```
01_Foundation/FOUNDATION.md
```
冻结跨模块约束：
- 颜色/间距/排版 tokens（若已有基座则引用）
- 三栏布局原则（左=上下文，中=操作区，右=指令/监控）
- 图标库约束（如 lucide-react）
- 图表策略：工作区必须可交互；导出才静态化（若有图表）
在
```
04_Pages/
```
先创建
```
WorkbenchShell.md
```
（或同义壳层页）：
- TopBar / Sidebar / Left/Center/Right / Bottom Console 的插槽契约
- 允许“不同阶段左栏内容不同”的规则：用 slot + data-driven 渲染，而不是写死

注意：壳层没冻结前，不要开始写模块页面细节，否则后续会大返工。

Freeze cross-module constraints in
```
01_Foundation/FOUNDATION.md
```
:
- Color/spacing/typography tokens (reference existing foundation if available)
- Three-column layout principles (left = context, middle = operation area, right = instructions/monitoring)
- Icon library constraints (e.g., lucide-react)
- Chart strategy: Workspace charts must be interactive; staticize only when exporting (if charts are involved)
Create
```
WorkbenchShell.md
```
(or equivalent shell page) in
```
04_Pages/
```
:
- Slot contracts for TopBar / Sidebar / Left/Center/Right / Bottom Console
- Rules for "dynamic left-panel content across stages": Use slot + data-driven rendering instead of hardcoding

Note: Do not start writing module/page details until the shell is finalized, otherwise major rework will be required later.

Step C：组件先行（组件契约 → 页面引用）

Step C: Component-First Approach (Component Contracts → Page References)

在

02_Components/

抽象出“跨模块复用且必须稳定”的组件规格：

导入/输入组件（上传、粘贴、格式白名单、规范化）
图表组件（若需要）：交互、tooltip、click 联动、主题同步、导出静态化
执行状态面板（类似 IDE Console）：默认折叠 + 失败自动展开一次（可选）
“可演进报告/内容”的文档模型（强烈建议）：用 block/section 模型承接未来增减
导出组件：PDF 默认、DOCX 权限、Markdown 复制/导出；导出时静态化图表

做法：页面规格只引用组件契约，不在页面里重复写组件细节。

Abstract specifications for "cross-module reusable and stable" components in

02_Components/

Import/input components (upload, paste, format whitelist, standardization)
Chart components (if needed): Interaction, tooltip, click linkage, theme synchronization, export staticization
Execution status panel (similar to IDE Console): Default collapsed + auto-expand once on failure (optional)
Document model for "evolvable reports/content" (highly recommended): Use block/section model to accommodate future additions/removals
Export components: Default PDF, DOCX permissions, Markdown copy/export; staticize charts during export

Practice: Page specifications only reference component contracts, do not repeat component details in pages.

Step D：页面复刻级规格（每页一份，必须含状态机）

Step D: Replica-Grade Page Specifications (One per Page, Must Include State Machine)

对每个页面按

references/page-spec-template.md

输出，至少包含：

页面目标、用户、关键任务
布局（左/中/右/底部）与信息分区
状态机（就绪/运行/完成/失败/取消等）
数据契约（字段、来源、刷新策略、空态/错误态）
事件/联动契约（click/hover/selection → 筛选/定位/高亮）
A11y（键盘路径、ARIA、可替代视图）
验收标准（AC）与测试计划（离线回归如何验证）

Output each page according to

references/page-spec-template.md

, including at least:

Page objective, users, key tasks
Layout (left/middle/right/bottom) and information partitioning
State machine (ready/running/completed/failed/canceled, etc.)
Data contracts (fields, sources, refresh strategies, empty/error states)
Event/linkage contracts (click/hover/selection → filtering/location/highlighting)
A11y (keyboard paths, ARIA, alternative views)
Acceptance Criteria (AC) and test plan (how to verify offline regression)

Step E：覆盖映射（Coverage）与未尽事宜清单

Step E: Coverage Mapping and Unfinished Items List

在

00_SourceInventory/COVERAGE.md

维护可审计映射：

PRD/需求点 → 规格落点（页面/组件/基座）
明确“未覆盖项”（留到下一版本迭代），避免遗忘

Maintain auditable mapping in

00_SourceInventory/COVERAGE.md

PRD/requirements → specification locations (pages/components/foundation)
Explicitly record "uncovered items" (to be addressed in the next iteration) to avoid forgetting

Step F：索引 + Worklog（交付闭环）

Step F: Index + Worklog (Delivery Closure)

更新仓库
```
DOCS_INDEX.md
```
：登记 PRD 与 UI/UX 规格入口
追加
```
docs/worklog.md
```
：记录关键命令、关键决策与结果（不写敏感信息）

Update the repository's
```
DOCS_INDEX.md
```
: Register entry points for PRD and UI/UX specifications
Append to
```
docs/worklog.md
```
: Record key commands, key decisions and results (do not include sensitive information)

3) 关键决策规则（避免跑偏）

3) Key Decision Rules (Avoid Deviation)

TopBar vs Sidebar：TopBar 放“全局一致项”；Sidebar 放“模块级导航”；模块阶段/视图切换优先放 Canvas Header。
左栏内容：左栏不是固定组件，而是“Context Slot”。不同阶段呈现不同上下文（目录/设定/TOC/待办）。
右栏优先操控：右侧以指令与监控为主；成本监控可在下部，但不要挤占指令入口。
可演进内容：凡是“未来会增减的报告版块/字段”，必须通过模型/契约承接，前端不写死。
图表：工作区图表必须可交互（hover/click 出细节并能联动）；只有导出时才静态化为图片。

TopBar vs Sidebar: Place "globally consistent items" in TopBar; place "module-level navigation" in Sidebar; prioritize placing module stage/view switches in Canvas Header.
Left-Panel Content: The left panel is not a fixed component, but a "Context Slot". Display different contexts (directory/settings/TOC/todos) across stages.
Right-Panel Priority for Controls: Focus on instructions and monitoring in the right panel; cost monitoring can be placed at the bottom, but do not occupy instruction entry points.
Evolvable Content: For any "report sections/fields that will be added or removed in the future", must be supported by models/contracts, front-end should not hardcode.
Charts: Workspace charts must be interactive (hover/click to show details and enable linkage); staticize as images only during export.

4) 自检（Definition of Done for 文档）

4) Self-Inspection (Definition of Done for Documentation)

用

references/replica-readiness-checklist.md

自检。最低通过线：

目录结构一眼看得出“公共基座/组件/页面”的分层
每个页面都有状态机 + 数据契约 + AC + 测试计划
有 Coverage 映射，且未尽事宜被显式登记
仓库
```
DOCS_INDEX.md
```
与
```
docs/worklog.md
```
已更新

建议补充自检（强烈建议）：

使用
```
references/replica-scorecard.md
```
进行一次 0/1/2 量化评分，并在总结中记录分数与短板项

Use

references/replica-readiness-checklist.md

for self-inspection. Minimum passing criteria:

The directory structure clearly shows the hierarchy of "common foundation/components/pages"
Each page includes a state machine + data contract + AC + test plan
Coverage mapping exists, and unfinished items are explicitly recorded
Repository
```
DOCS_INDEX.md
```
and
```
docs/worklog.md
```
have been updated

Recommended supplementary self-inspection (highly recommended):

Use
```
references/replica-scorecard.md
```
to conduct a 0/1/2 quantitative score, and record the score and shortcomings in the summary

5) 测试提示（给自己做 dry-run）

5) Test Tips (Dry-Run for Yourself)

见

tests/evals_prd-to-uiux-rd-spec.yaml

，按场景自测：

会不会被错误触发
缺输入时是否会先补 PRD/约束
产物是否符合“复刻级骨架”与覆盖映射要求

See

tests/evals_prd-to-uiux-rd-spec.yaml

, self-test according to scenarios:

Whether it will be triggered incorrectly
Whether it will first supplement PRD/constraints when inputs are missing
Whether the output meets the requirements of "replica-grade skeleton" and coverage mapping