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

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) Inputs You Need to Confirm from the User (Minimum Set)

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) Output Contracts (Mandatory Files/Structure)

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) Workflow (Execute in Order)

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

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: Build the "Replica-Grade Skeleton" First (Let the Structure Prove Its Value)

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: Finalize Common Foundation and Shell

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: Component-First Approach (Component Contracts → Page References)

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: Replica-Grade Page Specifications (One per Page, Must Include State Machine)

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 Mapping and Unfinished Items List

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: Index + Worklog (Delivery Closure)

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) Key Decision Rules (Avoid Deviation)

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) Self-Inspection (Definition of Done for Documentation)

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) Test Tips (Dry-Run for Yourself)

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

prd-to-uiux-rd-spec

NPX Install

Tags

SKILL.md Content (Chinese)