SuperAPI AI Directory
Partner中文AI newsFavorites
Skillsprd-to-uiux-rd-spec

prd-to-uiux-rd-spec

Frontend & websites

View repository

Updated 10-16 04:59

About this skill

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

Goal: transform the "Product PRD (master document)" intofront-end replicable implementationUI/UX R&D specification document package (UI behavior, state machines, data/event contracts, A11y, acceptance and test plans), and make the directory structure itself convey "what was done/what was not done".

Principles of this skill:

  • Documentation first: first freeze the "shell layer/common foundation/contracts", then write module page details.
  • Directory as evidence: opening the folder lets you judge coverage and implementability (it is not a collection of prose).
  • Evolvable: for "content sections that may increase or decrease in the future", use contracts/models to accommodate them (the front end does not hard-code chapters).
  • Secure by default: this skill by default does not modify business code; if the user asks for code writing, first write the specifications and contracts clearly, then start a separate task for implementation.

0) Inputs you need to confirm with the user (minimum set)

  1. PRD path/link (or minimal PRD framework)
  2. Whether there is aread-only reference foundation(for example legacy UI/UX spec, design system, competitor documents); if so, where is the path, and are modifications allowed
  3. Key front-end constraints (choose at least 1 set):
    • Chart library (such as ECharts)
    • Icon library (such as lucide-react)
    • Export formats (such as PDF by default, DOCX permissions, Markdown copy/export)
  4. Delivery granularity: L1 small change / L2 new module / L3 core shell layer (default delivery is L2)

If the PRD is missing: first use references/output-contract.md 's "minimal PRD skeleton" to fill it in, otherwise the UI/UX specification will drift.

1) Output contract (the files/structure you must produce)

Default recommendation (paths may be adjusted according to repository conventions, but the structure remains unchanged):

  • docs/specs/prds/<date>-<slug>-prd.md: Product PRD (master document)
  • docs/specs/ui-ux-rd-spec/: UI/UX R&D specification (replicable and implementable)
  • DOCS_INDEX.md: Repository-level documentation index (path + one-sentence description)
  • docs/worklog.md: Work record (commands + decisions + results)

docs/specs/ui-ux-rd-spec/ The directory must include:

  • OVERVIEW.md: UI/UX master document (capability map + TODO + entry points)
  • DOCS_INDEX.md: Index of this directory (entry point for each specification document)
  • 00_SourceInventory/: Sources/references/coverage mapping
  • 01_Foundation/: Common foundation (cross-module constraints such as tokens/layout/interaction/A11y/icons/charts, etc.)
  • 02_Components/: Reusable component specifications (including data/event contracts)
  • 03_Patterns/: Supplement to cross-module interaction patterns
  • 04_Pages/: Page replication-grade specifications (one per page, including state machine/acceptance/test plan)
  • 05_A11y/: A11y summary (constraints for new components/pages)

See templates 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-critical contract extraction Gate (to prevent "template-like emptiness")

Risk background: excessive templating of documents can cause the harm of "looking complete, but missing business-critical contracts".

Goal of this Gate: Before writing UI/UX details, first freeze the "objects/terminology/key flows/permission boundaries/core fields" into a referenceable contract.

Minimum requirements (if any item is missing, you must not enter the massive document production phase of Step A):

  1. Objects and terminology (Glossary): at minimum list the core objects and relationships (Work/Project/Run/Artifact/...）
  2. Key flows (Key Flows): for each flow, clearly write "trigger → state machine → outputs → return/export"
  3. Permission boundaries (Roles/Permissions): at minimum clearly write the rule of "default read-only vs step-up write" (if applicable)
  4. Key field definitions: the "display definitions" of fields such as cost/duration/status must be traceable to the field level (to avoid later UI disputes)

Template (optional):

  • references/glossary-template.md

Step A: First build the "replication-level skeleton" (let the structure prove itself first)

  1. Create ui-ux-rd-spec/ and set up the hierarchy and entry files according to the skeleton:
    • OVERVIEW.md: first write constraints and navigation (do not wait until it is finished to add them)
    • DOCS_INDEX.md: first register every module/page that will appear (stubs are fine)
  2. If a read-only reference foundation exists (old spec/design system):
    • Explicitly read-only: in OVERVIEW.md and 00_SourceInventory/ clearly write "reference but do not modify"
    • Directory isomorphism: keep it as isomorphic as possible with the read-only foundation to reduce "comparison cost"

Output checkpoint: the directory structure should at a glance look like a "deployable engineering specification", not a "collection of scattered articles".

Step B: Freeze the common foundation (Foundation) and shell (Shell)

  1. In 01_Foundation/FOUNDATION.md freeze cross-module constraints:
    • Color/spacing/typography tokens (reference them if a foundation already exists)
    • Three-column layout principles (left = context, center = operation area, right = instructions/monitoring)
    • Icon library constraints (such as lucide-react)
    • Chart strategy: the workspace must be interactive; only exports are static (if there are charts)
  2. In 04_Pages/ first create WorkbenchShell.md(or a synonymous shell page):
    • Slot contracts for TopBar / Sidebar / Left/Center/Right / Bottom Console
    • Allow the rule that "the left column content differs by stage": use slot + data-driven rendering, not hardcoding

Note: before the shell is frozen, do not start writing module page details, otherwise there will be major rework later.

Step C: Components first (component contract → page reference)

In 02_Components/ abstract component specifications that are "reused across modules and must be stable":

  • Import/input components (upload, paste, format whitelist, normalization)
  • Chart components (if needed): interaction, tooltip, click linkage, theme synchronization, static export
  • Execution status panel (similar to IDE Console): collapsed by default + automatically expanded once on failure (optional)
  • Document model for "evolvable reports/content" (strongly recommended): use a block/section model to support future additions and removals
  • Export components: PDF by default, DOCX permissions, Markdown copy/export; staticize charts during export

Approach: page specifications only reference component contracts, and do not repeat component details in pages.

Step D: Replication-level page specifications (one per page, must include a state machine)

For each page, output by references/page-spec-template.md , at least including:

  • Page goals, users, key tasks
  • Layout (left/center/right/bottom) and information zones
  • State machine (ready/running/completed/failed/cancelled, etc.)
  • Data contract (fields, sources, refresh strategy, empty/error states)
  • Event/interaction contract (click/hover/selection → filter/locate/highlight)
  • A11y (keyboard paths, ARIA, alternative views)
  • Acceptance criteria (AC) and test plan (how to verify offline regression)

Step E: Coverage mapping (Coverage) and list of outstanding items

In 00_SourceInventory/COVERAGE.md maintain an auditable mapping:

  • PRD/requirement points → specification landing points (pages/components/base)
  • Clearly identify "uncovered items" (left for the next version iteration) to avoid forgetting them

Step F: Index + Worklog (delivery closure)

  1. Update repository DOCS_INDEX.md: register PRD and UI/UX specification entry points
  2. Append docs/worklog.md: record key commands, key decisions, and results (do not write sensitive information)

3) Key decision rules (avoid going off track)

  1. TopBar vs Sidebar: TopBar holds "globally consistent items"; Sidebar holds "module-level navigation"; module stage/view switching is preferentially placed in the Canvas Header.
  2. Left column content: The left column is not a fixed component, but a "Context Slot". Different stages present different contexts (directory/settings/TOC/to-dos).
  3. Right column prioritized controls: The right side is mainly for commands and monitoring; cost monitoring can be at the bottom, but must not crowd out the command entry points.
  4. Evolvable content: Any "report sections/fields that will be added or removed in the future" must be handled through models/contracts, and must not be hardcoded in the frontend.
  5. Charts: Workspace charts must be interactive (hover/click reveals details and can link); only staticize them as images when exporting.

4) Self-check (Definition of Done for documentation)

Use references/replica-readiness-checklist.md for self-check. Minimum passing line:

  • The directory structure makes the layering of "common base/components/pages" obvious at a glance
  • Every page has a state machine + data contract + AC + test plan
  • There is a Coverage mapping, and outstanding items are explicitly registered
  • Repository DOCS_INDEX.md and docs/worklog.md have been updated

Recommended additional self-check (strongly recommended):

  • Use references/replica-scorecard.md to perform a 0/1/2 quantitative scoring, and record the score and weak items in the summary

5) Test tips (do a dry-run for yourself)

See tests/evals_prd-to-uiux-rd-spec.yaml, and self-test by scenario:

  • Will it be triggered incorrectly?
  • When input is missing, will it first supplement PRD/constraints?
  • Do the artifacts meet the "replica-level skeleton" and coverage mapping requirements?