ns-proto-visual-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Normative visual description

规范性视觉描述

Normative guides: how UI surface must look — not how implemented. Audience: design, product, visual QA. Need block order, hierarchy, states, sibling consistency.

Project-agnostic. Canonical specimens: examples/.

Guide language = project docs language (often English; follow repo). Section intent identical even when localizing headings.

When

prototype/

exists, prefer its components as source of truth over legacy app trees unless user points elsewhere. Cite

prototype/

paths in source-of-truth table.

规范性指南：UI界面必须呈现的外观——而非实现方式。受众：设计、产品、视觉QA人员。需包含块顺序、层级结构、状态、同类组件一致性。

与项目无关。标准示例：examples/。

指南语言需与项目文档语言一致（通常为英文；遵循仓库设定）。即使本地化标题，章节意图需保持一致。

若

prototype/

目录存在，除非用户指定其他来源，否则优先将其中的组件作为事实来源，而非旧版应用组件树。在事实来源表格中引用

prototype/

路径。

Instructions

操作步骤

Name surface — card / form / shell / overlay; match project doc language.
Read before write — open source components (prefer
```
prototype/
```
) + sibling docs same surface type. Invent absent UI → QA trust break.
Load specimen — one matching file under examples/; mirror tone, section density, table style.
Boundary first — write Does not cover (links to siblings) before body. Unscoped guides swallow business rules + layout math.
Draft from template — keep section order; prefer
```
Element | How it should appear
```
tables over long prose.
Wire graph — update docs index + cross-links (card ↔ form ↔ shell ↔ layout). Orphans never reviewed.
Stay honest — document what code shows today; desired look differs → say explicit.
Living specs (when needed) — guide documents product-visible behavioral UX (not pure chrome polish) → invoke
```
ns-living-spec
```
appearance mode with guide path + short behavioral delta. Skip polish-only.

命名界面——卡片/表单/外壳/覆盖层；需与项目文档语言匹配。
先读再写——查阅开源组件（优先
```
prototype/
```
）+ 同类型界面的同类文档。凭空创造不存在的UI会破坏QA信任。
加载示例——选择examples/下的匹配文件；模仿其语气、章节密度、表格样式。
先明确边界——在正文前撰写不涵盖内容（链接至同类文档）。范围模糊的指南会混入业务规则和布局计算内容。
基于模板撰写——保持章节顺序；优先使用
```
元素 | 应呈现的外观
```
表格，而非长篇文字。
关联文档图谱——更新文档索引及交叉链接（卡片 ↔ 表单 ↔ 外壳 ↔ 布局）。孤立文档永远不会被审核。
如实记录——记录当前代码呈现的外观；若期望外观不同，请明确说明。
动态规范（必要时）——若指南涉及产品可见的行为UX（而非单纯的界面美化），则需调用
```
ns-living-spec
```
的外观模式，提供指南路径及简短的行为差异说明。仅美化的内容无需此步骤。

Why these constraints

为何设置这些约束

Constraint	Reason
Normative voice ("must" / "should")	Validation checklists need pass/fail, not narrative
Visual form only	Deep domain in product/spec docs; mix kills scanability
One file = one surface	Card and form answer different questions
Code as source of truth	Specs drift from components → decoration
Full states	Empty, overflow, disabled, warning, conditional visibility — where QA fails
Behavior as `Action \| What changes on screen`	Ties interaction to visible change; no hooks/state story

约束	原因
使用规范性语气（“必须”/“应当”）	验证检查表需要明确的通过/失败标准，而非叙述性内容
仅关注视觉形式	产品/规范文档有各自的深度领域；混合内容会降低可读性
一个文件对应一个界面	卡片和表单解决的是不同问题
以代码为事实来源	规范与组件脱节会沦为装饰性内容
覆盖完整状态	空状态、溢出状态、禁用状态、警告状态、条件可见性——这些是QA常出错的地方
行为采用 `动作 \| 屏幕变化内容` 格式	将交互与可见变化关联；无需涉及钩子/状态逻辑

Output template

输出模板

ALWAYS structure new guides like this (adapt titles; keep opening contract):

markdown

undefined

新指南必须按以下结构撰写（可调整标题；保留开篇说明）：

markdown

undefined

[Surface] — appearance [on the canvas / in the side panel / on screen]

[界面类型] — 外观 [画布中 / 侧边面板中 / 屏幕上]

Normative guide for how [surface] must appear in [context]: [short scope].

For design, product, and visual validation. Does not describe [explicit limits].

Does not cover:

[Item] — see [sibling doc link]

Source of truth in code: | File | Responsibility |

Related documents:

[links]

[场景下][界面类型]必须呈现的外观规范性指南：[简短范围说明]。

面向设计、产品及视觉验证人员。不描述[明确限制内容]。

不涵盖：

[内容项] — 参见[同类文档链接]

代码中的事实来源： | 文件 | 职责 |

相关文档：

[链接]

What it is

定义

[1–3 short paragraphs: role, read-only vs editable, relation to siblings]

[1–3段简短内容：角色、只读/可编辑属性、与同类组件的关系]

What it [does not show / does not cover in the body] ← optional; useful for forms

不展示的内容 / 正文中不涵盖的内容 ← 可选；适用于表单

| Absent section | Reason |

| 缺失章节 | 原因 |

Overview — block order

概述 — 块顺序

[ASCII of vertical/horizontal structure]

[垂直/水平结构的ASCII图]

[Modes / branches] ← when mutually exclusive modes exist

[模式 / 分支] ← 当存在互斥模式时

| State | Body shown | [mermaid if it clarifies branching]

| 状态 | 显示内容 | [若能清晰说明分支，可使用mermaid图]

[Block / section name]

[块 / 章节名称]

| Element | How it should appear |

| 元素 | 应呈现的外观 |

Palette and style

调色板与样式

| Element | Appearance |

| 元素 | 外观 |

Expected visual behavior

预期视觉行为

| User action | What changes on screen |

| 用户操作 | 屏幕变化内容 |

Quick visual checklist

快速视觉检查表

undefined

undefined

Optional sections (when surface needs)

可选章节（按需添加）

What it does not show — contrast sibling surface (e.g. child item vs top-level)
Modes — normal/variant; edit vs follow-along
Selection and hover — container states
Handles / anchors — graph cards

不展示的内容——区分同类界面（如子项与顶层项）
模式——常规/变体；编辑模式与跟随模式
选中与悬停——容器状态
手柄 / 锚点——图形卡片

Surface types

界面类型

Type	Doc focus	Keep out
Canvas card	Zones, RO content, badges, handles, create buttons	Panel form fields; layout formulas
Panel form	Field order, toggles, empty states, modes	Shell chrome; canvas card chrome
Shell	Fixed chrome (width, header, scroll)	Per-selection form bodies
Technical layout	Grid, gaps, resize	Visual appearance (sibling normative doc)

One file = one surface.

类型	文档重点	排除内容
画布卡片	区域、只读内容、徽章、手柄、创建按钮	面板表单字段；布局公式
面板表单	字段顺序、开关、空状态、模式	外壳界面元素；画布卡片界面元素
外壳	固定界面元素（宽度、页眉、滚动）	选中项对应的表单主体
技术布局	网格、间距、调整大小	视觉外观（参考同类规范性文档）

一个文件对应一个界面。

Anti-patterns

反模式

Mix shell with content, or card with form — reviewers cannot tell which surface failed
Paste long domain rules into visual guide — link; no dump
Describe implementation (
```
useState
```
, class names as story) instead of appearance
Skip empty states, warnings, conditional visibility
Publish without index entry or cross-links
Replace normative guide with summary matrix (matrix points to guide)
Cite
```
vN/prototype/
```
as layout — product has one
```
prototype/
```
tree; versioning = git

混合外壳与内容，或卡片与表单——审核人员无法判断哪个界面出现问题
将冗长的领域规则粘贴到视觉指南中——应使用链接，而非直接粘贴
描述实现细节（
```
useState
```
、类名等）而非外观
遗漏空状态、警告状态、条件可见性
发布时未添加索引条目或交叉链接
用汇总矩阵替代规范性指南（矩阵应指向指南）
将
```
vN/prototype/
```
作为布局依据——产品仅有一个
```
prototype/
```
树；版本控制通过git实现

Examples

示例

Before draft, open specimen for surface:

Intent	Read first
Canvas card	examples/card-canvas.md
Panel form	examples/form-panel.md
Panel chrome only	examples/shell-panel.md

Naming + publish checklist: examples/README.md.

撰写草稿前，请查阅对应界面的示例：

用途	先阅读
画布卡片	examples/card-canvas.md
面板表单	examples/form-panel.md
仅面板界面元素	examples/shell-panel.md

命名及发布检查表：examples/README.md。