shape

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Context: this sub-skill is one lens of the broader

ui-craft

skill. If the

ui-craft

skill is also installed, read its SKILL.md first for Discovery + Anti-Slop + Craft Test, then apply the specific lens below.

Shape the UI for

$ARGUMENTS

before writing code. Load the

ui-craft

skill.

This command produces a shape artifact, not JSX. The point is to force low-fi thinking — content inventory, layout regions, state coverage, open questions — before any component is written. Skipping this step is how generic AI UIs get built: straight to hi-fi, no discovery, every screen looks the same.

Step 1 — Clarify (3-5 questions). Ask the user before shaping. Don't guess. Minimum questions:

What's the primary user action on this screen? (One verb, one object.)
What data is visible by default vs hidden behind a click or tab?
What does success look like — a state, a redirect, a toast?
Who's the primary user — first-timer, power user, mobile-first?

Step 2 — Content inventory. Bullet list of every piece of content that will appear. Annotate each by priority:

P0 — must be visible on first paint. Cut it and the screen fails.
P1 — one click away (tab, accordion, drawer).
P2 — settings-level; rarely accessed.

Example:

- P0  Headline (one line, the value prop)
- P0  Primary CTA
- P0  Hero chart / metric
- P1  Secondary nav tabs
- P1  Recent activity list
- P2  Export / integrations menu

Step 3 — ASCII layout. Low-fi sketch showing regions. No specific copy, no colors, no font sizes. One desktop variant + one mobile variant. Use box characters:

Desktop
┌──────────────────────────────────────────────┐
│ [logo]                 [nav]         [user]  │
├──────────────────────────────────────────────┤
│  ┌────────────────┐   ┌───────────────────┐  │
│  │ Headline + sub │   │                   │  │
│  │                │   │   Hero visual     │  │
│  │ [Primary CTA]  │   │                   │  │
│  └────────────────┘   └───────────────────┘  │
│                                              │
│  ── Social proof row ──                      │
│                                              │
│  ┌─── Feature 1 ───┐   ┌─── Feature 2 ───┐   │
│  └─────────────────┘   └─────────────────┘   │
└──────────────────────────────────────────────┘

Mobile
┌──────────────────┐
│ [logo]     [☰]   │
├──────────────────┤
│  Headline + sub  │
│                  │
│  [Primary CTA]   │
│                  │
│  ┌── Hero ──┐    │
│  └──────────┘    │
│                  │
│  Social proof    │
│                  │
│  Feature 1       │
│  Feature 2       │
└──────────────────┘

Asymmetry is fine and often better — don't force center-everything.

Step 4 — State list. Enumerate the states this screen must handle. Point at references/state-design.md for the contracts.

idle — default state, data present.
loading — skeletons that mirror final layout, 200ms delay before showing.
empty — first-run or no data; doubles as onboarding.
error — specific cause + recovery action + support ID.
partial — some data loaded, some failed (e.g., one widget erred).
conflict — user-edit collision (rare but load-bearing on collaborative surfaces).
offline — queue writes, reconcile on reconnect.
success — confirmation state after the primary action completes.

Mark each as required / optional (why) / N/A.

Step 5 — Open questions. Do NOT start coding until these are answered. Default set:

Accent color — brand-defined, or to be chosen? (See Discovery in
```
SKILL.md
```
.)
Typography — existing tokens, or new system? (Reference
```
typography.md
```
.)
Responsive breakpoints — what's the minimum supported width?
Stack — CSS only, or Motion / GSAP / Three.js? (Only load
```
stack.md
```
if the user opts in.)
Data source — real API ready, or mock for shape?
Keyboard / a11y requirements — anything beyond the baseline from
```
accessibility.md
```
?

Knob awareness.

At
```
CRAFT_LEVEL ≥ 7
```
, add two more sections:
- Motion shape — which elements enter, in what order, with what stagger. Pick from the duration scale in
```
references/motion.md
```
  .
- Typography hierarchy plan — display / headline / body / label sizes and weights, before code.
At
```
CRAFT_LEVEL ≤ 4
```
, strip Step 4 to
```
idle / loading / error
```
only. Skip the motion shape.

Step 6 — Offer to persist to
.ui-craft/spec.md
(opt-in).

After printing all five steps, offer to write the output as a spec section:

"Write this shape to
.ui-craft/spec.md
as
## Surface: <name>
? (Persists the composition choice, layout, and acceptance bar for the build phase.)"

User confirms → format the output as a
```
## Surface: <name>
```
section following the template in
```
../skills/ui-craft/references/spec.md
```
, then write or append to
```
.ui-craft/spec.md
```
. Confirm in one line: "Written to
```
.ui-craft/spec.md
```
→
```
## Surface: <name>
```
."
User declines → do not write any file. The printed output stands. Note: "spec.md not written — the pipeline continues without a persisted acceptance bar."

Print-only is the default when

/shape

is run standalone. Step 6 is the offer; it does not execute unless the user explicitly confirms.

Output contract.

Produce a single Markdown block with all five steps, in order. Step 6 is the optional offer that follows.
Do NOT write JSX, CSS, or component code in this command.
End the output with: "Ready to build? Review the shape, confirm the open questions, then run
/ui-craft:audit
(or use Build mode) once the code exists."

Next step:

/craft

— build the surface you just wireframed (rung 1).

背景： 本子技能是更广泛的

ui-craft

技能的一个视角。如果同时安装了

ui-craft

技能，请先阅读其SKILL.md中的「探索（Discovery）+ 反冗余（Anti-Slop）+ 工艺测试（Craft Test）」部分，再应用以下特定视角。

在编写代码前，为

$ARGUMENTS

设计UI雏形。加载

ui-craft

技能。

该命令生成的是雏形产物（shape artifact），而非JSX。其核心目的是强制进行低保真思考——在编写任何组件前，梳理内容清单、布局区域、状态覆盖和待解决问题。跳过这一步正是生成通用AI UI的原因：直接做高保真，没有探索过程，所有界面都千篇一律。

步骤1 — 明确需求（3-5个问题）。在设计雏形前先询问用户，不要猜测。最少需要问以下问题：

这个界面的核心用户动作是什么？（一个动词+一个宾语。）
哪些数据是默认可见的，哪些是需要点击或切换标签页才显示的？
成功状态是什么样的——是一个状态提示、页面跳转，还是toast通知？
核心用户是谁——是新手用户、高级用户，还是移动端优先用户？

步骤2 — 内容清单。用无序列表列出所有会出现的内容，按优先级标注：

P0 — 首屏必须可见。去掉它的话，这个界面就失去了核心价值。
P1 — 一次点击即可到达（标签页、手风琴、抽屉）。
P2 — 设置级内容，很少访问。

示例：

- P0  Headline (one line, the value prop)
- P0  Primary CTA
- P0  Hero chart / metric
- P1  Secondary nav tabs
- P1  Recent activity list
- P2  Export / integrations menu

步骤3 — ASCII布局。展示区域划分的低保真草图，不需要具体文案、颜色或字号。需要一个桌面端版本和一个移动端版本，使用方框字符绘制：

Desktop
┌──────────────────────────────────────────────┐
│ [logo]                 [nav]         [user]  │
├──────────────────────────────────────────────┤
│  ┌────────────────┐   ┌───────────────────┐  │
│  │ Headline + sub │   │                   │  │
│  │                │   │   Hero visual     │  │
│  │ [Primary CTA]  │   │                   │  │
│  └────────────────┘   └───────────────────┘  │
│                                              │
│  ── Social proof row ──                      │
│                                              │
│  ┌─── Feature 1 ───┐   ┌─── Feature 2 ───┐   │
│  └─────────────────┘   └─────────────────┘   │
└──────────────────────────────────────────────┘

Mobile
┌──────────────────┐
│ [logo]     [☰]   │
├──────────────────┤
│  Headline + sub  │
│                  │
│  [Primary CTA]   │
│                  │
│  ┌── Hero ──┐    │
│  └──────────┘    │
│                  │
│  Social proof    │
│                  │
│  Feature 1       │
│  Feature 2       │
└──────────────────┘

非对称布局是可以的，而且通常更好——不要强行把所有内容都居中。

步骤4 — 状态列表。枚举这个界面必须处理的所有状态。相关约定请参考references/state-design.md。

idle（空闲） — 默认状态，数据已加载。
loading（加载中） — 与最终布局一致的骨架屏，延迟200ms显示。
empty（空状态） — 首次使用或无数据的状态，可兼作新手引导。
error（错误） — 显示具体原因、恢复操作和支持ID。
partial（部分加载） — 部分数据加载成功，部分失败（例如某个小部件出错）。
conflict（冲突） — 用户编辑冲突（少见，但在协作界面中至关重要）。
offline（离线） — 写入操作进入队列，重新连接后再同步。
success（成功） — 核心操作完成后的确认状态。

将每个状态标记为必需 / 可选（说明原因） / 不适用。

步骤5 — 待解决问题。在这些问题得到解答前，不要开始编码。默认问题集：

强调色——是品牌已定义的，还是需要选择？（请参考
```
SKILL.md
```
中的探索（Discovery）部分。）
字体排版——使用现有设计令牌（tokens），还是新建一套系统？（参考
```
typography.md
```
。）
响应式断点——最小支持宽度是多少？
技术栈——仅用CSS，还是搭配Motion / GSAP / Three.js？（仅在用户同意时加载
```
stack.md
```
。）
数据源——真实API已就绪，还是用mock数据来做雏形设计？
键盘操作 / 无障碍（a11y）要求——有没有超出
```
accessibility.md
```
中基线要求的部分？

参数调整说明。

当
```
CRAFT_LEVEL ≥ 7
```
时，额外增加两个部分：
- 动效雏形（Motion shape） —— 哪些元素会进入、进入顺序是什么、错开时间是多少。从
```
references/motion.md
```
  中的时长刻度中选择。
- 字体层级规划 —— 在编码前确定大标题（display）/ 标题（headline）/ 正文（body）/ 标签（label）的字号和字重。
当
```
CRAFT_LEVEL ≤ 4
```
时，步骤4仅保留
```
idle / loading / error
```
三个状态，跳过动效雏形部分。

步骤6 — 提议保存到
.ui-craft/spec.md
（用户可选）。

在输出完所有五个步骤后，询问用户是否要将输出内容写入规范文档的对应章节：

"是否要将此雏形以
## Surface: <name>
的形式写入
.ui-craft/spec.md
？（将保存构建阶段的布局选择、排版和验收标准。）"

用户确认 → 按照
```
../skills/ui-craft/references/spec.md
```
中的模板，将输出格式化为
```
## Surface: <name>
```
章节，然后写入或追加到
```
.ui-craft/spec.md
```
中。用一行文字确认：「已写入
```
.ui-craft/spec.md
```
→
```
## Surface: <name>
```
。」
用户拒绝 → 不写入任何文件，已输出的内容继续有效。提示：「未写入spec.md —— 流程将在没有持久化验收标准的情况下继续。」

单独运行

/shape

命令时，默认仅输出内容。步骤6是可选提议，除非用户明确确认，否则不会执行。

输出约定。

按顺序输出包含所有五个步骤的单个Markdown块，步骤6是后续的可选提议。
该命令中禁止编写JSX、CSS或组件代码。
输出的结尾为：「准备好构建了吗？请先确认雏形设计和待解决问题，待代码编写完成后运行
/ui-craft:audit
（或使用构建模式）。」

下一步：

/craft

—— 构建你刚刚绘制线框的界面（第1阶）。