ui-design-spec

UI Design Specification

This skill is responsible for organizing product or feature requirements into a handoff-ready design specification, and preparing the same contract for subsequent design. First clarify functions, pages, interactions, and tasks, then hand off to specialized skills within the authorized scope; when continuing existing work, preserve the specification, task IDs, approval decisions, and run identity.

When to use

Use when the user needs a complete menu and feature map, page-by-page design, subpages and interaction surfaces, success and failure flows, standalone design tasks, and consistency checks. Also applies to filling in existing specifications, or continuing to the next design item along an approved baseline. When only explanation or review is requested, remain read-only, and do not automatically start rendering, implementation, installation, or publishing because this skill was selected.

Capability Boundaries

User intent	This skill's responsibility or handoff
Design specification for the whole product or a clearly defined feature scope	Use spec mode, covering the six-item delivery contract
Continue existing design or prepare the next page	Restore the original task and baseline, prepare scoped handoff
Gaps in behavior rules, permissions, and side effects	Use as needed ui-design-feature, write back to the original specification
Gaps in routing, hierarchy, selected states, and back navigation	Use as needed ui-design-nav, preserve the original navigation
Theme or continuity constraints	ui-design-theme / ui-design-continuity
Candidate diagrams or cross-artifact consistency review	ui-design-review
Continuous execution, breakpoint recovery, and state management	After selecting a profile, hand off to ui-design-harness
Actual visual artifacts	After preparing the contract, hand off to the applicable renderer, such as ui-design-visual

Specialized responsibilities may be assumed by the same agent as needed. When optional skills are missing, use this skill's built-in contract, clearly state the specialized verification that was not completed, and do not automatically install or falsely claim to invoke them.

How to use · Workflow

Step 1: Confirm inputs and sources of truth

Read project instructions, existing modifications, product side, users, business objects, scope, specification, navigation, task sources, and the current version. Record source conflicts, open items, and actual maturity. After verifying existing complete content, reuse it and only fill gaps; do not create a second set of task states, and do not renumber.

Step 2: Choose the mode for this round

• spec: The user requests specification, planning, or documentation completion. Deliver according to scope, without requiring creation of a Harness run.
• execution: The user has requested actual design execution. Restore the baseline, theme, and original task; existing runs continue along the original identity. For a new run, choose product-to-ui、existing-product-next-page、page-family-batch、design-correction、stitch-high-fidelity-delivery or design-to-implementation, with the internal state machine managed by Harness.
• Harness dispatch: Handle only the packet's stage and scope. The baseline stage binds the sources of truth, and the task stage assembles the original task contract; follow the run/dispatch/evidence_stage returns, without rerouting or creating a run.

When the task boundary is clear, proceed directly; only ask when a missing decision would affect the current delivery. During handoff, read as neededresponsibilities and handoff contract。

Judge delivery scale and run mode separately: use the six-item contract for the full scope; a single module may reuse the existing single file; for vague ideas, deliver a draft marked with assumptions; for local corrections, expand only the target and the delta. When trimming by request, readgeneral design authoring rules, and do not expand the business scope on your own to fill in a catalog.

Step 3: Expand functions, pages, and interactions

Expand in the order of "Scope and Sources → Functional Detailed Specification → Navigation and Page Structure → User Flow → Surface Registry". For each page, clarify the users, core problems, fields, layout rationale, primary and secondary actions, permissions, states, and acceptance. Assess the applicability of tabs, details, create/edit, drawers, confirmation, results, errors, and empty states item by item; for each action, give the real source, preconditions, business changes, and the destinations for success/failure/cancellation and recovery.

The full product request covers all modules within scope; do not substitute a few demonstration pages for completion. When writing the detailed specification, useDetailed WorkflowandFilling Template。

Shared shell and component rules are defined centrally, and each page expands only the differences; specific control labels, data examples, and interaction feedback can be handed off directly. Review state applicability item by item, complete responsive, keyboard, and focus behavior; mark facts, recommendations, and items to be confirmed separately, and do not treat demonstration values as real data.

Step 4: Form Independent Design Tasks

Give each design object a stable ID, binding the function, Surface, original task location, source page, parent unit, master version, frozen/variable regions, unique artifact path, and observable acceptance. The initial master may explicitly not exist; before executing inherited units, verify the approval, hash, dimensions, and version of the real parent assets. Record the design execution order and the user operation flow separately.

The task mapping is derived from the original task source, preserving manual status; execution instructions for the same task are directly referenced, without copying a second checklist. When preparing units and dependencies, readTask ContractandTask Coverage Contract。

Step 5: Generation, Validation, and Correction

Register the six relationships in the existing Registry; if the original schema differs, retain it and provide equivalent inspection evidence. Use dual strict switches for complete new-standard packages; the generator writes only the derived map, and the original text, task status, and approval records are not edited by the generator.

python3 <skill>/scripts/validate_functional_design.py <package> --require-task-coverage --require-methodology
python3 <skill>/scripts/generate_design_maps.py <package> --write --format json
python3 <skill>/scripts/generate_design_maps.py <package> --check --format json

Resolve <skill> to the actual installation directory. On failure, correct the original text, relationships, or dependencies indicated by the error, then generate and recheck; if outdated due to source changes, first verify the projection and then rebuild. Historical snapshots use the corresponding compatibility checks and do not write back to the source. After machine validation passes, check semantics, actual scope, and actual assets according to theReview Checklist.

Step 6: Delivery or Continued Execution

By default, the document is placed in docs/functional-design/, including the scope and function list, navigation and layout, page-by-page contracts, flows and global surfaces, Registry, original task mapping, execution instructions, and status. Existing file names remain unchanged, and responsibility mappings are registered; for the complete file responsibilities, seeDelivery Contract。

After delivering the specification, continue only with visual or implementation work according to existing authorization. Before execution, pass on the same version of the function, navigation, theme, fixtures, and task contract; use initial for the first page, and inherit/correction for inheritance or correction. A single clearly bounded piece of work can be handed directly to a specialized skill, while continuous execution retains running and verification evidence through the Harness.

Validation checklist

• Every menu, function, object, and page within the declared scope has a source and corresponding relationship.
• The layout, fields, primary and secondary actions, permissions, and normal/abnormal states of each page can be handed off directly.
• Applicable partial views, interaction layers, results, and error surfaces are all registered, with clear sources and returns.
• Primary actions distinguish navigation, commands, and local switching, with a closed loop for success/failure/cancellation and recovery.
• Design units have stable IDs, original task positioning, parent dependencies, frozen/variable boundaries, and specific exit conditions.
• Relationship coverage, dependencies, output uniqueness, and derived map freshness pass actual checks; items not run are recorded truthfully.
• Manual semantic review and machine results each have evidence; specification, candidates, approval, implementation, and runtime acceptance are reported separately.
• Delivery scale matches the request; not-applicable status has justification, cross-platform and accessibility have concrete behavior, and local modifications do not cross frozen boundaries.

Not Applicable and Boundaries

When separately selecting color schemes, querying routes, reviewing candidate maps, fixing code, or installing skills, use the corresponding professional skill. This skill does not replace the renderer, production implementation, or deployment. Standard document directories and machine scripts do not require the target project to migrate authoritative sources; business states must not be trimmed or confirmed decisions rewritten just to pass scripts.

Gotchas

1. Menu Equals Page or Screenshot: Details, wizards, and drawers retain their true ownership; one Surface does not automatically equal a full-page image.
2. Retry Directly on Unknown Result: After a timeout, first verify the request and business state; closing the page does not equal canceling a background task.
3. Master Reference Passed Off as Approval: The initial page may have no baseline; inherited visuals must verify the real parent image, and dependencies cannot be released based on a reference alone.
4. Structural Pass Passed Off as Business Completeness: Scripts check declared relationships; missing requirements, field truthfulness, and screen frozen zones still require review.
5. Continuing a Task Rebuilds the Entire Flow: Preserve the original version, task, and run/dispatch; do not loop back into the main entry point.
6. Filling in Tables Without Concrete Content: Common rules are reused by reference; business differences must be expanded into inputs, outputs, recovery, and acceptance.

Best Practices

One requirements authority, one task execution source, the same set of stable IDs. Choose the layout around the first-screen problem, inherit the shell without mechanically reusing business areas. Professional skills fill only gaps within their scope of responsibility; review failures return to the affected original task for correction. Use local or external tools as requested; do not automatically install dependencies; scripts are implemented with the Python standard library,--help view parameters,--check perform a read-only review.

Output contract

Deliver mode/stage, scope coverage, unique specification and task sources, input versions, artifact paths, open items, actual verification, unverified/failed items, and next steps. A new complete standard includes Registry relationship projection, task-coverage, and derived maps; existing projects deliver equivalent mappings and check results. Harness workers return the corresponding stage evidence; file existence does not equal approval, implementation, or runtime completion.

References

• Six Design Delivery Contracts: Read when doing full-scope design or relationship projection.
• spec Mode: Read when establishing or completing a specification package.
• Detailed Design Workflow: Read when feature, per-page, and action depth are insufficient.
• Delivery Contract: Read when determining file responsibilities and mapping existing files.
• Fill in Templates: Use when writing per-page, flow, and task content.
• General Design Authoring Rules: Read when trimming delivery, refining controls, cross-platform design, local corrections, or handling conflicts/write failures.
• Design Task Contract、Task Coverage: Read when splitting and handing off tasks.
• Responsibilities and Handoff、Execution Routing: Read during professional handoff or in-run dispatch.
• Review checklist: Read before delivery or when an inspection finds a gap.

Examples

• Specification completion: "Complete the order export pages, error recovery, and design tasks, keeping the original menu." → spec; complete the page-by-page and action contract, stable units, and task mapping, run checks, and report open items.
• Continue design: "Use the approved pages to create the editing drawer." → execution; bind the parent asset and version, freeze the background, change only the current interaction layer, and review according to the existing approval rules.
• Read-only interpretation: "Check whether the specification missed cancel recovery." → List sources, gaps, and impacts; do not write files, do not create a run, and do not start rendering.

Keywords

UI design specification, feature catalog, menu map, page specification, interaction surface, user flow, design task, design handoff, feature design, menu map, page-by-page specification, interaction flow, independent design task, consistency check