ns-proto-visual-guide

规范性视觉描述

规范指南：规定 UI 表面必须呈现的样子，而非实现方式。面向设计、产品和视觉 QA。需要关注区块顺序、层级、状态及同类项的一致性。

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

指南语言 = 项目文档语言（通常为英语；遵循仓库的语言）。即使本地化标题，各章节的意图也必须相同。

如果存在 prototype/，除非用户另有指定，否则优先将其中的组件视为事实来源，而非旧版应用目录。在事实来源表中引用 prototype/ 路径。

说明

1. 命名界面——卡片 / 表单 / 外壳 / 覆层；使用与项目文档一致的语言。
2. 先读再写——打开源组件（优先查看 prototype/）以及同类界面的配套文档。臆造不存在的 UI 会破坏 QA 信任。
3. 加载示例——从 examples/ 中选择一个匹配文件；沿用其语气、章节密度和表格样式。
4. 先划定边界——在正文前撰写不涵盖的内容（附上配套文档链接）。未限定范围的指南会把业务规则和布局计算也纳入其中。
5. 根据模板起草——保持章节顺序；优先使用 元素 | 应呈现的样子 表格，而非长篇叙述。
6. 连通文档图谱——更新文档索引和交叉链接（卡片 ↔ 表单 ↔ 外壳 ↔ 布局）。孤立文档不会被审阅。
7. 如实记录——描述代码当前呈现的内容；如果期望外观与之不同，明确说明。
8. 活文档规格（必要时）——指南描述产品可见的行为式 UX（而非纯粹的界面装饰优化）时，使用指南路径和简短的行为差异说明，调用 ns-living-spec 的外观模式。仅涉及优化时跳过。

这些约束的原因

约束	原因
规范性措辞（“必须” / “应该”）	验证清单需要明确的通过 / 失败标准，而非叙述
仅描述视觉形式	深层领域内容应放在产品 / 规格文档中；混在一起会降低可扫读性
一个文件对应一个界面	卡片和表单要回答不同的问题
以代码为事实来源	规格若与组件脱节，就会沦为装饰
完整覆盖各种状态	空状态、溢出、禁用、警告、条件显示——这些都是 QA 容易出问题的地方
行为写成 操作 | 屏幕上的变化	将交互与可见变化关联起来；不写钩子 / 状态的实现过程

输出模板

新指南始终采用以下结构（标题可调整；保留开篇约定）：

# [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]

## 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]

### [Modes / branches]  ← when mutually exclusive modes exist
| State | Body shown |
[mermaid if it clarifies branching]

## [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
- [ ] ...

**检查清单规则：**每一项都必须能通过检查渲染后的界面或 DOM 验证，不得依赖审美判断。好的示例：关闭控件位于页眉中，并与末端边缘对齐。不好的示例：页眉看起来很平衡。

可选章节（视界面需要添加）

• 不显示的内容——与配套界面进行对比（例如：子级项与顶级项）
• 模式——常规 / 变体；编辑与跟随
• 选中和悬停——容器状态
• 控制点 / 锚点——图谱卡片

界面类型

类型	文档关注点	不包括
画布卡片	区域、只读内容、徽章、控制点、创建按钮	面板表单字段；布局公式
面板表单	字段顺序、切换开关、空状态、模式	外壳界面装饰；画布卡片界面装饰
外壳	固定界面装饰（宽度、页眉、滚动）	每个选中项对应的表单正文
技术布局	网格、间距、尺寸调整	视觉外观（参见配套规范文档）

一个文件对应一个界面。

反模式

• 将外壳与内容混写，或将卡片与表单混写——审阅者无法判断哪个界面有问题
• 将冗长的领域规则粘贴到视觉指南中——改为链接；不要整段复制
• 描述实现方式（用 useState、类名讲故事），而非外观
• 遗漏空状态、警告和条件显示
• 未添加索引条目或交叉链接便发布
• 用摘要矩阵取代规范指南（矩阵应指向指南）
• 将 vN/prototype/ 引作布局依据——产品只有一个 prototype/ 目录；版本管理由 git 负责

示例

开始起草前，先打开示例文件了解界面效果：

意图	先阅读
画布卡片	examples/card-canvas.md
面板表单	examples/form-panel.md
仅面板外框	examples/shell-panel.md

命名与发布检查清单：examples/README.md。

相关技能

• ns-proto-creator — 捕获实时 UI；创建或演进单一 prototype/ 树
• ns-living-spec — 行为 UX 文档完成后的 外观 模式