building-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Building Design

构建设计

Overview

概述

Produces one self-contained design folder per intention (a web app, a mobile app, a site, or part of one).

design.md

follows the DESIGN.md format with extension sections for motion, voice, implementation, and decisions. UI blocks and feature screens are runnable React previews, each with a

.design.ts

spec tied to its code by markers; features group screens into flows. A copied Vite viewer shows every flow and UI block as a Board and in Play. Building and amending follow the same steps and produce the same output.

为每个设计目标（Web 应用、移动应用、网站，或其中的一部分）生成一个自包含的设计文件夹。

design.md

遵循

DESIGN.md

格式，并增加动效、品牌语气、实施和决策等扩展章节。UI 区块和功能界面均为可运行的 React 预览，每个预览都配有

.design.ts

规格，并通过标记与代码关联；各项功能将界面组织成流程。配套的 Vite 查看器由模板整体复制而来，可通过 Board 和 Play 模式展示每个流程与 UI 区块。构建和修订遵循相同的步骤，并产生相同的输出。

Dependencies

依赖项

Item	Required	When	How
Node.js 20.19+ with npm	required	Viewer, type check, token export	https://nodejs.org

项目	是否必需	使用时机	使用方式
带有 npm 的 Node.js 20.19+	必需	查看器、类型检查、令牌导出	https://nodejs.org

Agent workflow

Agent 工作流

Authoring mode. Follow this skill when the user names it, or references a file under a design root marked by an

index.md

with this skill's author signature, to build or amend a design. Works wherever the agent can read and write repository files and run npm. Read design-contract.md and preview-contract.md first, then run the steps. An amend runs the same steps limited to what the change reaches.

创作模式。 当用户指定此 skill，或引用某个设计根目录下的文件，且该根目录由带有本 skill 作者签名的

index.md

标记时，应遵循此 skill 来构建或修订设计。只要 Agent 能够读写仓库文件并运行 npm，此工作流即可使用。首先阅读 design-contract.md 和 preview-contract.md，然后执行以下步骤。修订操作会执行相同的步骤，但仅限于变更所涉及的范围。

Steps

步骤

Resolve root — design-contract → Resolve design root; initialize when none exists. On an amend, read
```
design.md
```
and the
```
.design.ts
```
files of the surfaces named.
Fill inputs — design-contract → Inputs. Ask once for every empty required row the work needs. Map a supplied style guide per Existing guides.
Scope — list the features (screens, states, flows), UI blocks (props, presets, motion), and motion primitives in play. Build: everything. Amend: the surfaces and
```
design.md
```
sections the change reaches, plus every screen that renders a UI block whose props change. Reuse one UI block wherever the same element appears; derive from an
```
exact
```
reference artifact when one exists.

design.md — write or edit from

assets/design.md

: tokens,

## Components

index,

## Motion

## Voice

## Implementation

, and a

## Decisions

row for each settled choice. Then

npm run tokens

Motion system — in
```
system/motion.css
```
and
```
system/motion.ts
```
, declare every
```
--motion-*
```
token with its
```
design.md
```
value and implement each primitive once, marked
```
@motion <name>
```
, with its reduced-motion behavior.
UI blocks — per block in scope:
```
<Name>.tsx
```
,
```
<name>.css
```
,
```
<name>.design.ts
```
from
```
assets/surface/ui/
```
per preview-contract.
Features — per screen in scope:
```
<Screen>.tsx
```
,
```
<screen>.css
```
,
```
<screen>.design.ts
```
; per feature:
```
<feature>.design.ts
```
with its flows; all from
```
assets/surface/feature/
```
. Write copy per design-contract → Writing copy; build screen choreography from primitives only. To compare options, add them as presets or states (each reached by a flow); delete the rejected ones once the user picks.
Sync and confirm — design-contract → Sync and Checklist. Reply with paths (root,
```
design.md
```
), how to review (
```
npm run dev
```
in the root), what was built or changed, decisions recorded, and gaps (
```
[FACT?]
```
,
```
[TBD]
```
, defaults used). Ask the user to send changes as surface (feature › flow › step, or UI block › preset) + what to change.

解析根目录 — design-contract → 解析设计根目录；如果尚不存在，则进行初始化。修订时，读取
```
design.md
```
以及相关界面的
```
.design.ts
```
文件。
填写输入项 — design-contract → 输入项。针对本次工作所需的每一个空白必填项，只询问一次。按照 现有指南 映射所提供的风格指南。
确定范围 — 列出本次涉及的功能（界面、状态、流程）、UI 区块（props、预设、动效）和动效基础单元。构建：全部构建。修订：仅处理变更所涉及的界面和
```
design.md
```
章节，以及每一个渲染了 props 已发生变化的 UI 区块的界面。在相同元素出现的位置复用同一个 UI 区块；如果存在
```
exact
```
参考产物，则基于它进行派生。
编写
design.md
— 根据
```
assets/design.md
```
编写或编辑：设计令牌、
```
## Components
```
索引、
```
## Motion
```
、
```
## Voice
```
、
```
## Implementation
```
，并为每项已确定的决策在
```
## Decisions
```
中添加一行。然后运行
```
npm run tokens
```
。
动效系统 — 在
```
system/motion.css
```
和
```
system/motion.ts
```
中，声明每个
```
--motion-*
```
令牌，并使用
```
design.md
```
中的值；每个动效基础单元只实现一次，以
```
@motion <name>
```
标记，同时实现其 reduced-motion 行为。
UI 区块 — 对范围内的每个区块，根据
```
assets/surface/ui/
```
并遵循 preview-contract，创建
```
<Name>.tsx
```
、
```
<name>.css
```
、
```
<name>.design.ts
```
。
功能 — 对范围内的每个界面，创建
```
<Screen>.tsx
```
、
```
<screen>.css
```
、
```
<screen>.design.ts
```
；对每项功能，创建带有其流程的
```
<feature>.design.ts
```
；全部取自
```
assets/surface/feature/
```
。按照 design-contract → 编写文案 编写内容；界面编排只能使用上述基础单元构建。若要比较方案，将其添加为预设或状态（每项均可通过某个流程到达）；用户选定后，删除未采用的方案。
同步并确认 — design-contract → 同步和检查清单。回复中应包含路径（根目录、
```
design.md
```
）、审阅方式（在根目录中运行
```
npm run dev
```
）、已构建或修改的内容、已记录的决策，以及遗留项（
```
[FACT?]
```
、
```
[TBD]
```
、使用的默认值）。要求用户以“界面（功能 › 流程 › 步骤，或 UI 区块 › 预设）+ 需要修改的内容”的形式发送变更。

Reference index

参考索引

Contract

约定

design-contract.md — roots, layout, inputs, content roles, copy, sync, checklist. preview-contract.md — surfaces, screen or state, flows, design files, markers, triggers, viewer.

Doc	When to use
design-contract.md	Resolve or initialize a root; inputs; reference artifacts; content roles; writing copy; sync; checklist
preview-contract.md	Surface kinds and files, states and presets, flows, design file schema, markers, triggers, viewer

design-contract.md — 根目录、布局、输入项、内容角色、文案、同步、检查清单。preview-contract.md — 界面类型、界面或状态、流程、设计文件 schema、标记、触发器、查看器。

文档	使用时机
design-contract.md	解析或初始化根目录；输入项；参考产物；内容角色；编写文案；同步；检查清单
preview-contract.md	界面类型与文件、状态与预设、流程、设计文件 schema、标记、触发器、查看器

Templates

模板

```
assets/index.md
```
— root marker
```
assets/design.md
```
— DESIGN.md with default tokens, YAML rules, and extension sections

assets/app/

— viewer app and

system/

(

define.ts

type.css

motion.css

motion.ts

), copied whole on init

assets/surface/ui/

—

Component.tsx

component.css

component.design.ts

assets/surface/feature/

—

Screen.tsx

screen.css

screen.design.ts

feature.design.ts

```
assets/index.md
```
— 根目录标记
```
assets/design.md
```
— 包含默认令牌、YAML 规则和扩展章节的 DESIGN.md
```
assets/app/
```
— 查看器应用及
```
system/
```
（
```
define.ts
```
、
```
type.css
```
、
```
motion.css
```
、
```
motion.ts
```
），初始化时整体复制

assets/surface/ui/

—

Component.tsx

、

component.css

、

component.design.ts

assets/surface/feature/

—

Screen.tsx

、

screen.css

、

screen.design.ts

、

feature.design.ts