ns-proto-visual-guide

規範的なビジュアル記述

規範ガイドは、UI サーフェスの見た目を定めるものであり、実装方法を定めるものではありません。対象読者は、デザイン、プロダクト、ビジュアル QA です。ブロックの順序、階層、状態、同種要素間の一貫性が必要です。

プロジェクトに依存しません。標準となる見本は examples/ を参照してください。

ガイドの言語はプロジェクトのドキュメントの言語に合わせます（多くの場合は英語です。リポジトリに従ってください）。見出しをローカライズしても、各セクションの意図は同一です。

prototype/ がある場合、ユーザーから別の指示がない限り、レガシーなアプリツリーよりも prototype/ のコンポーネントを信頼できる情報源として優先してください。信頼できる情報源の表には prototype/ のパスを記載してください。

手順

1. サーフェスに名前を付ける — カード／フォーム／シェル／オーバーレイ。プロジェクトのドキュメントの言語に合わせます。
2. 書く前に読む — ソースコンポーネント（prototype/ を優先）と、同じサーフェスタイプの関連ドキュメントを確認します。存在しない UI を作り出すと、QA の信頼を損ないます。
3. 見本を読み込む — examples/ にある該当ファイルを 1 つ選び、文体、セクションの密度、表のスタイルを踏襲します。
4. まず範囲を定める — 本文を書く前に、兄弟ドキュメントへのリンクを含めて対象外を記述します。範囲が定まっていないガイドは、ビジネスルールやレイアウト計算まで取り込んでしまいます。
5. テンプレートから作成する — セクションの順序を保ち、長い説明文よりも Element | How it should appear の表を優先します。
6. ドキュメント間をつなぐ — ドキュメントのインデックスと相互リンクを更新します（カード ↔ フォーム ↔ シェル ↔ レイアウト）。孤立したドキュメントはレビューされません。
7. 事実に忠実にする — コードに現れている現状を記述します。期待される見た目と異なる場合は、その旨を明記します。
8. 必要に応じてリビング仕様を作成する — ガイドがプロダクト上で見える動作 UX（純粋な見た目の磨き込みではないもの）を記述する場合は、ガイドのパスと動作の差分の簡単な説明を指定して、ns-living-spec の appearance モードを実行します。見た目の磨き込みだけの場合は省略します。

これらの制約が必要な理由

制約	理由
規範的な表現（「must」／「should」）	検証チェックリストには、説明文ではなく合格／不合格の基準が必要です
ビジュアル形式のみ	ドメインの詳細はプロダクト／仕様ドキュメントに記載します。混在すると一覧性が損なわれます
1 ファイルにつき 1 サーフェス	カードとフォームでは確認すべきことが異なります
コードを信頼できる情報源とする	コンポーネントから仕様が乖離すると、装飾になってしまいます
すべての状態を記載する	空、オーバーフロー、無効、警告、条件付き表示 — QA で問題が起きる箇所です
動作は Action | What changes on screen 形式で記述する	インタラクションを目に見える変化に結び付けます。フックや状態の説明は不要です

出力テンプレート

新しいガイドは必ず次の構成にしてください（タイトルは調整できますが、冒頭の前提は維持してください）。

# [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 の確認によって検証可能でなければなりません。見た目の美しさの判断に依存してはいけません。良い例：Dismiss control present in header, aligned to trailing edge。悪い例：Header looks balanced。

任意のセクション（サーフェスに必要な場合）

• 表示対象外 — 関連するサーフェスとの違いを説明します（例：子項目とトップレベル項目）
• モード — 通常／バリアント、編集と追従
• 選択とホバー — コンテナーの状態
• ハンドル／アンカー — グラフカード

サーフェスタイプ

タイプ	ドキュメントの対象	含めないもの
キャンバスカード	領域、読み取り専用コンテンツ、バッジ、ハンドル、作成ボタン	パネルのフォームフィールド、レイアウト計算式
パネルフォーム	フィールドの順序、トグル、空の状態、モード	シェルの外枠、キャンバスカードの外枠
シェル	固定された外枠（幅、ヘッダー、スクロール）	選択項目ごとのフォーム本体
技術的なレイアウト	グリッド、間隔、サイズ変更	ビジュアルの見た目（関連する規範ドキュメントを参照）

1 ファイルにつき 1 サーフェスです。

アンチパターン

• シェルとコンテンツ、またはカードとフォームを混在させる — レビュー担当者が、どのサーフェスに問題があるのか判断できません
• 長いドメインルールをビジュアルガイドに貼り付ける — リンクを使い、内容を丸ごと貼り付けないでください
• 見た目ではなく実装（useState やクラス名を説明）を記述する
• 空の状態、警告、条件付き表示を省略する
• インデックス項目や相互リンクを追加せずに公開する
• 規範ガイドを要約マトリクスに置き換える（マトリクスはガイドへの参照を示すものです）
• レイアウトの根拠として vN/prototype/ を挙げる — プロダクトにある prototype/ ツリーは 1 つだけです。バージョン管理には 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 のドキュメント化後に使用する 外観 モード