frontend-crafting

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Frontend Crafting

前端界面精修指南

Design and build interfaces that come from the subject, not from a template. This file is a router: it fixes the contract every workflow shares and points to the one reference file the current request actually needs. Design rules live in the references, never here.

设计并构建源于产品本身而非模板的界面。本文件是一个路由指南：它明确了所有工作流共同遵循的规范，并指向当前需求实际需要的参考文件。设计规则均存于参考文件中，本文件不包含具体规则。

Scope

适用范围

Use this skill when the request is about how an interface looks, reads, or behaves:

building a new page, screen, or component from a brief;
reworking an existing surface, whether the change preserves the current design or replaces it;
critiquing a UI and reporting what is wrong;
refining a surface that is already broadly right.

Do not use it to drive a browser, capture screenshots, or debug a running local app; that is

web-debug

. This skill also does not pick a framework, a hosting target, or a data layer.

当需求涉及界面的外观、可读性或交互行为时，可使用本指南：

根据需求文档构建新页面、界面或组件；
重构现有界面，无论是否保留当前设计风格；
评审UI并指出问题；
优化已基本符合要求的界面。

请勿将本指南用于驱动浏览器、截取屏幕截图或调试运行中的本地应用；这些场景属于

web-debug

范畴。本指南也不涉及框架选择、托管目标或数据层的决策。

Core principles

核心原则

The subject supplies the character. Typography, palette, rhythm, and imagery come from what the product actually is and who uses it. Generic character is the default failure mode, and no amount of styling covers it.
Structure carries information. Every panel, card, divider, and badge must encode something true about the content. Structure that exists to fill space is decoration wearing a layout.
Ambition is a function of the surface. A marketing page and an operations console want different amounts of risk. Mode detection decides this before any styling decision.
Correctness and accessibility are absolute; taste is not. Aesthetic rules are defaults with stated exceptions, never bans. Accessibility, semantics, and behavioral correctness do not bend.
Plan, critique, build, critique. Judge the intent before writing code and judge the result after. Both passes are cheap; a wrong concept rendered well is not.

产品本身决定风格。排版、配色、节奏和视觉元素均应源于产品本质及其目标用户。千篇一律的风格是默认的失败模式，再多的样式修饰也无法掩盖这一点。
结构承载信息。每个面板、卡片、分隔符和徽章都必须传递与内容相关的真实信息。仅为填充空间而存在的结构，只是披着布局外衣的装饰。
设计野心取决于界面类型。营销页面与操作控制台对设计风险的接受程度截然不同。在做出任何样式决策前，需先确定界面模式。
正确性与无障碍性是绝对要求，审美则不是。审美规则是带有明确例外情况的默认准则，而非禁令。无障碍性、语义正确性和交互行为正确性不容妥协。
规划、评审、构建、再评审。编写代码前先评估设计意图，完成构建后再评审结果。这两个环节成本很低，但一个错误的概念即使实现得再好也毫无价值。

Mode detection

模式识别

Announce both modes in one line before working. The announcement - and the design read it leads to - belongs in the visible reply before the first file is written or edited, never only in private reasoning: it is a commitment the requester checks the result against, and an unseen commitment binds nothing. If the two readings of the request genuinely diverge, ask exactly one question - never a questionnaire.

Workflow - what kind of change is being asked for:

Workflow	The request is
create	A surface that does not exist yet, or one being written from scratch
redesign	An existing surface changing its visual or structural design
review	A judgement of an existing surface, with no code change
polish	An existing surface that is broadly right and needs refinement

Surface mode - what the surface is for. Read the surface, not the product: a marketing site can contain a documentation page, and a product can contain a pricing page.

Mode	The surface exists to	Default posture
Persuade	Convince a first-time visitor to act	Authored risk allowed where the brief leaves an axis free
Operate	Let a returning user do work	Restraint by default; boldness needs a reason in the brief
Read	Deliver text a reader came for	Restraint by default; typography carries the design
Experience	Be the thing itself, not a route to it	Authored risk allowed; the concept is the product

开始工作前，需用一句话明确说明工作流模式和界面模式。该说明及其对应的设计解读需在编写或编辑首个文件前，呈现在可见的回复中，而非仅存在于内部思考中：这是供需求方验证结果的承诺，未明确的承诺不具备约束力。若对需求的两种解读存在真正分歧，只需提出一个问题——切勿使用问卷形式。

工作流模式——需求要求的变更类型：

工作流模式	需求内容
create（创建）	构建尚未存在的界面，或从零开始编写界面
redesign（重设计）	修改现有界面的视觉或结构设计
review（评审）	对现有界面进行评估，不涉及代码变更
polish（优化）	对已基本符合要求的界面进行精修

界面模式——界面的用途。需关注界面本身而非产品整体：营销网站中可能包含文档页面，产品中也可能包含定价页面。

界面模式	界面用途	默认设计姿态
Persuade（说服型）	说服首次访问者采取行动	若需求文档未限制相关维度，可允许设计创新
Operate（操作型）	供回头用户完成工作任务	默认保持克制；需有明确需求依据才可采用大胆设计
Read（阅读型）	为读者提供所需文本内容	默认保持克制；排版主导设计风格
Experience（体验型）	作为产品本身，而非通往产品的途径	允许设计创新；设计概念即为产品核心

Workflow routing

工作流路由

Read only the file the current work needs. Loading more than the request calls for costs context and produces rules that fight each other.

Read
```
references/direction.md
```
for any request that needs design intent: brief inference, the one-line design read, the surface modes in detail, and the optional reasoning axes. Create and redesign always start here. Review and polish read it only when the intent is unclear.
Read
```
references/create.md
```
when building a surface that does not exist yet.
Read
```
references/redesign.md
```
when changing the design of a surface that already exists, in either direction: preserving the current design language or replacing it.
Read
```
references/review.md
```
when the request is a critique, an audit, or a design review.
Read
```
references/polish.md
```
when refining a surface that is already broadly right, including requests phrased as an intent such as bolder, quieter, better typeset, or more delightful.
Read
```
references/quality-gate.md
```
before building a new surface or substantially modifying an existing one, and before writing any review findings. It is the technical floor: accessibility, semantics, focus, forms, motion, overflow, performance, states, and copy. A small local refinement does not need it;
```
polish.md
```
carries its own compact pre-flight.
Read
```
references/anti-patterns.md
```
when a design decision feels familiar and you want to know whether that is convergence or a defect, and when a review needs the catalogue of default failures. It is the single source of truth for anti-default material.

仅阅读当前工作所需的文件。阅读超出需求范围的文件会增加认知负担，还可能导致规则冲突。

若需求涉及设计意图（包括需求文档推导、一句话设计解读、详细界面模式及可选推理维度），请阅读
```
references/direction.md
```
。创建和重设计工作必须从此文件开始。评审和优化工作仅在意图不明确时才需阅读此文件。
构建尚未存在的界面时，请阅读
```
references/create.md
```
。
修改现有界面的设计（无论保留当前设计风格还是替换为新风格）时，请阅读
```
references/redesign.md
```
。
需求为评审、审计或设计评估时，请阅读
```
references/review.md
```
。
精修已基本符合要求的界面时（包括诸如“更大胆”“更简洁”“排版更优”或“更具愉悦感”等意图类需求），请阅读
```
references/polish.md
```
。
在构建新界面或大幅修改现有界面之前，以及撰写任何评审结论之前，请阅读
```
references/quality-gate.md
```
。此文件是技术底线，涵盖无障碍性、语义、焦点、表单、动效、溢出、性能、状态和文案等内容。小型局部优化无需阅读此文件；
```
polish.md
```
中包含了精简的前置检查内容。
当某个设计决策似曾相识，想确认是设计趋同还是缺陷时，或评审需要参考常见错误案例时，请阅读
```
references/anti-patterns.md
```
。此文件是反模式内容的唯一权威来源。

Precedence rules

优先级规则

When two considerations collide, resolve in this order.

The brief wins. An explicit instruction from the user overrides any default in this skill, including its aesthetic preferences. Quiet constraints count as brief: accessibility-first mandates, public sector work, regulated industries, and products for children all outrank visual ambition without being stated as design instructions.
The incumbent stack wins. Before introducing a dependency, a token, or a pattern, check what the project already uses: framework, styling approach, design system, component library, design tokens, animation library, naming conventions, and copy conventions such as capitalization. Match them. A new dependency needs a reason the existing one cannot cover.
Preserve and redesign never mix silently. Refinement keeps the existing design language; redesign replaces it. Splitting the difference produces a surface that is neither. If the right answer is the other one, say so and get agreement before switching.
No universal aesthetic bans. Absolutes are reserved for correctness and accessibility. Every aesthetic rule here is a default that a brief can earn back, and each one states when it legitimately does not apply.

当两种考量发生冲突时，按以下优先级解决：

需求文档优先。用户的明确指示优先于本指南中的任何默认规则，包括审美偏好。隐性约束也属于需求文档范畴：无障碍优先要求、公共部门项目、受监管行业以及面向儿童的产品，无需作为设计指令明确说明，其优先级均高于视觉设计野心。
现有技术栈优先。在引入新依赖、设计令牌或模式之前，需检查项目已使用的技术：框架、样式方案、设计系统、组件库、设计令牌、动画库、命名规范以及文案规范（如大小写规则）。需与现有技术保持一致。引入新依赖需有充分理由，证明现有依赖无法满足需求。
优化与重设计不可混为一谈。优化需保留现有设计语言；重设计则需替换现有设计语言。折中处理会导致界面不伦不类。若正确方案是另一种模式，需明确说明并获得同意后再切换。
无通用审美禁令。绝对要求仅适用于正确性与无障碍性。本指南中的所有审美规则均为默认准则，需求文档可允许例外情况，且每个规则均明确说明了其不适用的场景。

Framework neutrality

框架中立性

The core of this skill works for Vue and Nuxt, React and Next, Svelte and SvelteKit, and plain HTML, CSS, and JavaScript. Rules are written in terms of HTML, CSS, and DOM behavior. Where an example is specific to one framework or one styling approach it is labelled as such, for instance "Example (React)", and is illustration rather than requirement.

本指南的核心内容适用于Vue和Nuxt、React和Next、Svelte和SvelteKit，以及原生HTML、CSS和JavaScript。规则均基于HTML、CSS和DOM行为编写。若示例针对特定框架或样式方案，会进行标注（如“示例（React）”），此类示例仅作说明之用，并非强制要求。

Bounded verification

有限验证

Visual checking is bounded so it cannot become an open loop:

Build the surface completely first. Do not verify partial work.
Inspect desktop and mobile together in one batched pass.
Fix everything found in one batch.
Optionally confirm once that the batch landed. Then stop.

A review-only request never modifies code. Findings are reported, not applied, unless the user asks for the fix afterwards.

视觉检查需限定范围，避免陷入无限循环：

先完整构建界面，不要验证未完成的工作。
一次性批量检查桌面端和移动端。
一次性修复所有发现的问题。
可选择性地确认一次修复结果，然后停止检查。

仅评审类需求不得修改代码。评审结果仅作报告，不直接应用，除非用户后续要求修复。

Definition of done

完成标准

Workflow and surface mode were announced, and the work matches them.
Intent is traceable to the subject: someone could name why this looks the way it does.
Every requirement in
```
references/quality-gate.md
```
that applies at MUST level holds, including keyboard operability and visible focus.
Loading, empty, and error states exist wherever the surface can reach them.
Desktop and mobile were both inspected, in one pass, and the findings were fixed.
Nothing was silently replaced that the request only asked to refine.
What was approximated, faked, or left for later is stated plainly rather than implied as done.

已明确工作流模式和界面模式，且工作内容与模式相符。
设计意图可追溯至产品本身：任何人都能说明界面呈现当前样式的原因。
```
references/quality-gate.md
```
中所有标注为MUST级别的适用要求均已满足，包括键盘可操作性和可见焦点。
界面所有可能出现加载、空状态和错误状态的场景均已实现对应状态。
已一次性完成桌面端和移动端的检查，并修复了所有发现的问题。
未擅自替换任何仅要求优化的内容。
所有近似实现、模拟内容或待后续完成的部分均已明确说明，而非默认视为已完成。