Local-Cursor/internal/skills/builtin/fd-engineering/references/uiux.md

# UI/UX: brief, web options, and design handoff

For /FD-uiux and interface-design proposals. Apply core language, scope, evidence, and protocol workflow rules. The deliverable is an approved design expressed through web prototypes, not production implementation. Record UIUX sub-stage as discovery, brief confirmation, prototype generation, selection, refinement, or handoff. Use [todo.md](todo.md) for substantial artifact work, checks, and cleanup, within the same task record.

## 1. Ground the task

Read relevant product/task documents, existing interfaces or captures, design rules, components, tokens, and assets. Identify the actual output project separately from reference projects. Work with empty projects, reference collections, and existing applications without assuming all are greenfield.

Identify the target platform, audience, primary tasks, and whether the request is new design, refinement, or redesign. Preserve existing identity and behavior for refinement; clarify replacement scope before redesign. Missing design documentation alone does not authorize replacing an existing visual system.

Use [grill.md](grill.md) for consequential unknowns, one question per round, with evidence, a recommendation, and cost. Investigate discoverable facts yourself and reuse effective decisions.

## Decision coverage before proposing

Check these categories: purpose/audience and priorities; platform/viewports/input; primary flow and information/navigation organization; tone and visual constraints; density/layout direction and meaningful copy/states; existing components/reuse constraints; reference permission; explicit candidate count and output scope.

For each consequential choice, keep evidence and status: confirmed, explicitly delegated, verified fact, open, or deliberately deferred. Confirm or obtain scoped delegation for preference-driven choices; do not turn a guess, a generic adjective, or one broad answer into approval of the rest. Low-level spacing details can follow the confirmed direction.

Ask one Chinese question per round in conversation, starting upstream. Keep the context to a few short bullets and wait for the answer. Do not dump a full brief, many decisions, or prototypes while categories remain open. Present the consolidated brief only after blockers are resolved. Reuse explicit existing decisions rather than adding a fixed question quota.

## 2. References require the appropriate scope

Inspect user-supplied references within their stated scope. If none are supplied, ask whether external visual/competitor research is wanted, unless the user already decided this for the task. Wait for affirmative authorization before such research; asking without an answer is not approval.

If declined, continue from local material and confirmed constraints. Record unknown competitors or reference gaps without inventing research. Do not silently expand supplied references into new competitor/style searches. Apply this gate when using Grill or other design guidance too.

Separate observed reference facts, design inference, and unverified assumptions. Extract applicable principles rather than copying an entire site or template. Prefer existing/local assets and system fonts; additional remote resources or dependencies must be justified in the brief and respect the research decision.

## 3. Confirm the brief and candidate count

Do not silently default to any number of candidates. Ask the user when the count is unspecified; recommend a number with its effort and comparison cost. Reuse an explicit count. Additional directions require a new explicit count, not automatic expansion; refining the selected direction does not reopen that question.

Present a short Chinese brief covering applicable decisions:

- Product purpose, audience, primary task, and observable design goals.
- Target platform, primary viewport(s), input conventions, and product-copy language.
- New/refine/redesign scope, tone, existing identity, components, and assets.
- Supplied references, external-research decision, evidence gaps, and assumptions.
- User-chosen count and meaningful differences to explore.
- Key pages, operable controls and important action/state/recovery mappings, approved product copy and annotation restrictions, layout scales, output location, and reuse/dependency choices.

Request brief confirmation before creating prototypes. A previously explicit approval of the same complete brief is reusable. Resolve blockers first; update and reconfirm materially changed goals or scope, not every spacing adjustment.

## 4. Make design choices accountable

- Avoid gradients, rounded corners, and glow as default styling. Use them only when the confirmed brief explicitly requires or justifies them. Respect a confirmed existing identity rather than imposing a new universal style.
- Tie choices to the product's content, audience, task, and setting. For multiple candidates, vary layout, information organization, interaction organization, or visual expression meaningfully; palette-only reskins do not qualify.
- Give each direction a clear rationale and tradeoff. Avoid generic style labels as substitutes for design decisions. Instructions cannot change the model's decoding mechanism or guarantee originality.
- Apply the product-copy boundary below. Preserve factual content; use realistic, identified fixtures when real content is unavailable, without fabricated endorsements or metrics. Keep fixture explanations outside the product canvas.
- Define coherent alignment, spacing, type hierarchy, control sizes, density, and grouping for the target platform. A rough coverage prototype still needs deliberate layout details.
- Evaluate existing components, native semantics, and necessary dependencies before custom controls. Do not let a component kit dictate the composition or rebuild mature behavior merely to escape a template. New frameworks, full UI kits, or templates require necessity and cost in the confirmed brief.

## Product-copy boundary

Do not add explanatory annotations beside, beneath, or around controls, cards, charts, or other product elements. This concerns visible interface text, not source-code comments. Do not spontaneously explain a control's purpose, teach its operation, justify the design, describe implementation/mock behavior, or add generic summary/helper lines. Perceived usefulness alone is not permission.

Keep real product content: button/field names, units, actual values, actual loading/success states, and genuine validation/error feedback in the appropriate state. For example, 项目名称, 元, 已保存, and 名称不能为空 are allowed; an unrequested line 给项目起一个容易识别的名字，方便以后查找 is not.

Additional explanatory help copy requires the user's explicit request or confirmation of that concrete wording/purpose; a broad brief approval is not blanket approval for invented notes. Do not evade the rule by moving the same commentary into tooltips, info icons, placeholders, or page corners. Preserve established/user-provided product content within the agreed refinement scope rather than silently deleting it.

Put design/implementation explanations in conversation or the handoff record. Keep selection rationale in a dedicated gallery comparison area outside the product canvas, never attached to product controls. Enforce this boundary during prototype refinement and carry it into production planning, execution, and review.

## Key actions, states, and recovery

For each important operation specify the user's trigger, observable result, and how to continue on failure. Include applicable waiting/success/error, repeated submission, retry/cancel, retained input, and unsaved-change behavior; do not force irrelevant states onto every button. Resolve consequential behavior choices through Grill, and keep the agreed mapping in the same brief/task record.

For saving, clarify whether duplicate submission is blocked, when success appears, whether input survives failure, and how retry/leaving works. Prototype states are simulated and cannot prove real persistence; production acceptance must exercise the actual path. Do not compensate for undefined behavior by adding explanatory notes.

## 5. Generate isolated web prototypes

After the complete brief and explicit candidate count are approved, enter the prototype-generation sub-stage and verify actual write/preview capabilities under the host's permissions. Approval covers only the agreed prototype artifacts and related checks. It does not approve business-code, project-dependency/configuration changes, real business actions, publication, or deployment.

Follow existing prototype conventions. Otherwise use prototypes/uiux/<task-slug>/ under the target project. Provide exactly one index.html selection interface with tabs, radio buttons, or a selector that switches candidates inside the same page/viewport. Candidate files can be separate internally, but do not open one window/tab or start one server per candidate. Keep selection controls, rationale, fixture/validation notes, and limitations outside the product canvas. Avoid collisions and unrelated overwrites.

Default to lightweight HTML/CSS/JavaScript. Reuse suitable assets, tokens, or components when they work inside the isolated artifact without production changes. Do not introduce a new application framework or build pipeline just for a preview.

Implement the agreed key controls, such as tabs, expansion, dialogs, toggles, and form feedback, with a small set of local simulated states. Actions must produce the described prototype behavior, not decorative buttons or generic click alerts. Do not connect real services or imply that mocked state proves working business integration.

The browser is a cross-platform design medium, not a decision to replace the production stack. Follow the target platform's density, navigation, and input expectations; state which native behaviors the HTML cannot validate.

## Preview ownership and cleanup

Prefer a directly openable local page when the available browser supports it. If a server is necessary, use one task-owned preview session for the entire gallery. Before launch record the intended command, directory, and port; immediately after launch record the actual returned session/PID, URL, and ownership evidence. Never guess a PID. Reuse a suitable existing user-owned server only without taking ownership; never terminate it or the user's browser application.

When the user explicitly selects a candidate, record the selection, then immediately close the task-created selection tabs and stop every task-started preview server/watcher/child process using its actual handle or verified PID. Verify exit; do not merely print that cleanup happened. Never kill all node/python/browser processes or terminate a process by port/name without proving ownership.

While awaiting selection, the gallery workflow is still active: keep at most one necessary owned preview session and retain its handle. Ending a chat turn while waiting is not final workflow completion. On resumption, reuse and verify the recorded session rather than launching duplicates.

Refine the selected files after closing the selection session. If a further render is needed, open only the selected direction in one temporary task-owned session, then close/stop it before handoff. Apply the same owned-session cleanup on cancellation, failure, or final completion. Preserve artifact files. On resumption, inspect recorded handles before starting duplicates. Report any cleanup failure and remaining owned handles honestly.

## 6. Inspect, select, and refine

When tools permit, open and render each candidate at the agreed viewport(s). Inspect actual alignment, dimensions, spacing, overflow/clipping, content length, focus, important feedback, and the agreed operable controls/states. Fix what one inspection reveals before repeatedly capturing again. Report only checks actually performed.

Present a concise Chinese comparison, costs/limits, and the single switchable gallery entry. Ask for selection in conversation and wait for the user's explicit choice; do not infer it from a default or silently pick a favorite. Run the cleanup transition above as soon as selection is received.

Refine the selected direction's layout details, approved product copy, and key states. Check for unrequested adjacent commentary while preserving real names, units, states, and error feedback. Preserve the selected concept and brief unless the user changes them; record substantive revisions and confirm the affected scope. Do not polish all rejected directions or generate extras without request.

If rendering or interaction tools are unavailable, retain manually openable artifacts and distinguish generated files from unverified visuals and interactions. Ask for user review where necessary; never claim to have seen or tested them. A render cannot prove user research or all native-platform behavior.

## 7. Handoff and resume

Use the same record described in [task-record.md](task-record.md) for the brief, research authorization, candidate count, differences, selection, revisions, artifact locations, real tool/check results, preview process ownership/cleanup, and actual validation. Do not create parallel global design documents by default.

Deliver in Chinese: the selected/refined prototype, user flow, key action/state/recovery mappings, approved copy and annotation restrictions, visual/layout rules, justified exceptions, reuse guidance, remaining assumptions/limits, and implementation acceptance points. The user can reference this in /FD-plan, then approve production implementation for /FD-execute. Do not automatically perform that implementation.

## Guidance provenance

The visible-annotation prohibition, fixed protocol markers, and production handoff restrictions are FD user requirements, not claims that the source design skills prescribe these exact rules.


Distilled from frontend-design (intentional visual direction and useful copy), impeccable (brief priority, refinement/redesign boundaries, rendered craft checks), and ui-ux-pro-max (platform-aware UX, states, layout, and component guidance). Their installation, scripts, and databases are not runtime requirements. Load only relevant optional guidance and preserve FD scope and research gates.