designing-ui

画面ごとにその場で型を選ぶと、同じ種類の移動・重ね方・通知がアプリの中で割れる。本スキルは、既存の型を棚卸しし、外枠を1回だけ決め、画面の中の型を決定表で選び、画面をまたいで照合する手順に固定する。

既存設定との関係

• PJ が明文化したデザインシステム・ガイドが優先する。本スキルは PJ に規定の無い論点の既定値として使う。食い違いを見つけたら PJ 側に合わせ、食い違いを報告する
• 既存画面の型は、明文化されていなくても新しい画面で揃える対象にする。ただし既存の型が本スキルの規則（特に Gotchas）に反しているときは、新しい画面へ広げる前にユーザーに確認する（既存を直すか、新しい画面だけ規則どおりにするか、既存に合わせるか）
• 誰がいつ何のために見るか、画面に出す文字の取捨、提示前の完了基準は ~/.claude/context/ui-artifact-standards.md が真実源。本スキルは型とレイアウトを扱う
• 文言（ボタン名・見出し・エラー文・空状態の文）は /writing-ui-text スキル、コードの実装原則は /writing-code スキルに従う
• 各規則の出典は各参照の「出典キー」、出典どうしの食い違いの採否は references/sources.md

手順

1. 見る人と目的を決める（ui-artifact-standards）。完了基準: 「誰が・いつ・何のために見るか」を1文で書けている
2. 既存の型を棚卸しする。同じアプリの既存画面が使っている型を、次の6区分で1つの表に書く: グローバルナビ / ローカルナビ / 重ね方 / 通知 / 空状態と読み込み / 外枠。各行には、その型を何の目的に使っているかも書く。既存があればそれに合わせる。同じ目的に違う型を使っている箇所と、本スキルの規則に反する型があれば、新しい画面を作る前にユーザーに報告し、揃え方を確認する（目的が違えば型が違ってよい）。完了基準: 6区分すべてに行がある（既存の無い区分は「なし」と書く）
3. 外枠をアプリで1回だけ決める（references/layout.md 1節、続けて references/navigation.md 2節）。既存の外枠があれば変えない（ヘッダの無い外枠にヘッダを足さない）。完了基準: 外枠の型と、狭い幅での畳み方が決まっている
4. 画面の中の型を決定表で選ぶ: 移動は references/navigation.md 5節、重ね方は references/overlays.md 3節、通知は references/feedback.md 3節。選んだ型と、当たった決定表の行を設計メモに残す。出典どうしが食い違う論点で迷ったら references/sources.md の採否を見る。決定表に行が無い論点（保存を自動にするか保存ボタンにするか、など）は、PJ の既存に合わせ、既存が無ければユーザーに確認する。完了基準: 画面にある全ての移動・重ね・通知に、決定表の行か確認事項が対応している
5. 状態を全部作る: 空状態（種類ごと）・読み込み・エラー・極端に短い／長い値（references/feedback.md 4〜6節、references/layout.md 7節）。完了基準: 各状態の表示が実装・モック・設計メモのどれかにある
6. スタック固有の対応を読む: PJ に components.json があるか、components/ui に shadcn の部品があれば references/stacks/shadcn.md
7. 文言を決める: 画面に出す文字（ボタン・見出し・空状態・エラー・確認ダイアログ）を確定するときは /writing-ui-text スキルを実行する
8. 画面をまたいで照合する: 手順2の表に今回の画面を足し、同じ目的に違う型を使っていないかを見る。各参照の a11y 節を確認する。PJ にデザイン用の lint があれば PJ 規定のコマンドで実行して直す。完了基準: 同じ目的には1つの型が対応している。揃っていない箇所は、ユーザーに確認した結果か確認事項として残っている

全体に効く原則

• 1つの目的に1つの型を使い、全画面で同じにする。画面ごとに選び直さない（別の画面で覚えた操作が使えなくなるから）
• 目的地と作業中の集合を分ける。アプリが固定で持つ行き先は縦に階層として並べ、畳んでよい。利用者が開いて切り替えている対象は横に並べて常時見せ、状態（未保存・実行中）を付ける。2つを1つの部品に混ぜない
• グローバルナビは全画面で同じ位置・同じ順序に出す
• 重ねる型（モーダル・シート・ポップオーバー）は、ページか元の画面への組み込みで済まないときだけ使う
• 確認ダイアログより undo を優先する。確認は元に戻せない操作に限る
• 結果は対象の近くに出す。画面の変化で結果が分かるなら通知しない
• 色・余白・角丸は役割のトークンとスケールから選び、値を直書きしない
• 状態・選択を色だけで示さない
• 画面幅の区切り・アニメーションの時間・寸法の数値はスキルに持たない。PJ と CSS フレームワークの値を使う

references

ファイル	読むとき
references/navigation.md	グローバル・ローカルのナビ、パンくず、2ペイン、作業中の横タブ、ステッパー、コマンドパレットを決めるとき
references/overlays.md	ページに移るか、重ねるか、その場で広げるかを決めるとき。確認ダイアログ・ツールチップ・メニューを置くとき
references/feedback.md	操作結果・エラー・空状態・読み込みの型と置き場所を決めるとき
references/layout.md	外枠・密度・トークン・面の重なり・状態の表現・モーション・長い値への備えを決めるとき
references/sources.md	規則の根拠を確かめるとき、出典が食い違う論点で判断に迷うとき
references/stacks/shadcn.md	PJ で shadcn を使っているとき（手順6）

Gotchas

• 見た目がタブでも、URL が変わるならリンクの列として作る（nav とリンクと aria-current）。tablist にしない。画面の中の切り替えと別ページへのリンクを1列に混ぜない
• サイドバーの階層を3段にしない。3段目はページの中のタブか、一覧と詳細の2ペインにする
• toast にエラー・警告・読む必要がある内容を出さない。項目の近くか領域の中に、解決するまで残す
• モーダルの上にモーダルを開かない。例外は、閉じると作業が失われるときの確認ダイアログ1枚だけ
• 元の画面を見ながら操作する詳細・フィルタに、モーダルの部品を使わない（UIライブラリの「シート」はモーダルとして実装されていることが多い）
• スケルトンを toast・メニュー・モーダル自体に使わない。カード・表・一覧など内容を入れる部品にだけ使う

例

例1: チャットのアプリで、過去の会話と、いま進めている会話を行き来できるようにする

• 過去の会話の一覧は、固定の場所にある履歴（目的地の集合）→ 縦のサイドバー。常時見せなくてよいので、畳める
• 利用者が開いて切り替えている会話（作業中の集合）→ 横のタブ。返答の生成中・入力待ち・未読の状態をアイコンと文字で付ける。会話にはそれぞれ URL があるので、tablist ではなくリンクの列にし、閉じるボタンは各リンクの隣に別のボタンとして置く
• 右側にプレビューのペインを開くときは、サイドバーを畳んで幅を回してよい（初期状態で隠したままにはしない）
• 送信の失敗は、失敗したメッセージのすぐ近くに出し、やり直す操作を付ける。toast にしない

例2: 集計のダッシュボードに、期間（日・週・月）と表示形式（グラフ・表）の切り替えを付ける

• どちらも同じデータの表示の切り替え → タブではなくセグメント。選んだらすぐ反映し、選んだ状態を URL に載せる
• グラフと表を見比べたいという要件があるなら、切り替えにせず両方を並べる
• 複数の取得元を持つので、読めたカードから順に出す。読み込み中はカードと同じ形のスケルトンにし、レイアウトを動かさない
• 期間の変更で結果が画面に出るので、変更の成功は通知しない