UIの観点
画面まわりで口に出す価値のある言葉です。どれも伝えればそのように作ってもらえるもので、後から入れ直すより最初に言う方が安く済みます。
コンポーネント
ボタンやフォームのような部品を共通化する考え方です。共通化されていれば、1箇所直せば全画面に反映されます。されていなければ、同じ修正を画面の数だけ繰り返します。画面が2つ以上になる製品では最初から指定します。
弊社では、共通部品の起点にshadcn/uiを使います。部品のコードをプロジェクトへ取り込み、製品に合わせて編集できるためです。新しく作るときは標準スタックの雛形から始め、既存の製品では取り込み済みの部品を先に使います。同じボタンやフォームを画面ごとに作り直さず、共通の見た目や挙動の変更は部品側へ反映します（コンポーネント）。
既存のshadcn/uiのボタンやフォームを使って画面を作って。共通の見た目は部品側で揃えて
デザイントークン
色、余白、文字サイズに名前を付けて一元管理する仕組みです。「この青」がコードのあちこちへ直接書かれていると、色の変更は全箇所の書き換えになります。トークンになっていれば定義を1つ変えるだけで済み、ダークモードやブランド変更にも一括で対応できます。
弊社では、色を変えるときに、画面ごとに似た色を足していく運用にしません。背景、文字、主な操作などの役割ごとに一緒に変えられる状態を保ちます。具体的な設定と部品への適用は、開発者向けのコンポーネントで扱います。
色やサイズは直接書かず、デザイントークンとして定義して使って
DESIGN.mdに判断を残す
見た目の判断を別の会話やAIへ引き継ぐ必要がある製品では、DESIGN.md（デザインの方針と使い方を共有する文書）へ残します。色や部品が揃っていても、「どの操作を強調するか」「情報をどの密度で並べるか」は、それだけでは伝わりません。製品の目的と利用者に合わせて選んだ理由、文字や余白の使い分け、避ける表現、例外を認める条件を書きます。
弊社では、文書と実装で別々のルールを育てません。DESIGN.mdには判断と理由を置き、対応するデザイントークンやshadcn/uiの部品の場所を示します。方針を変えるときは文書と実装を同じ変更で更新します。既存のデザイン文書がある場合はそこを正本にし、同じ本文を別のファイルへコピーしません。
ファイルを置いただけで毎回読まれるとは考えず、CLAUDE.mdなどの指示ファイルから参照し、UIの変更前に読んでもらいます。shadcn/uiは部品の土台、デザイントークンは見た目を実装する値、DESIGN.mdはその選び方と使い方を伝える役割です。
今合意した見た目の方針と理由をDESIGN.mdに残して。既存のトークンとshadcn/uiの部品の場所も示して。
今後のUI変更前に読むよう、CLAUDE.mdから参照して
レスポンシブ
画面の幅に応じて表示を変えることです。弊社では、スマホ幅とPC幅の両方で確認することを標準にしています。
スマホ幅とPC幅の両方で確認して、崩れているところを直して
アクセシビリティ
視覚や操作の条件が違う人でも使える状態にすることです。文字と背景のコントラスト、キーボードだけでの操作、画像の代替テキストが基本で、Claudeに指定すれば基本的な実装は入ります。ただし満たせているかは自動では判定しきれないため、キーボードだけで操作してみるといった実際の確認と組み合わせます。弊社では、公共性の高い製品で必ず対応します。そうでなくても、読みやすく操作しやすい画面は全員の使いやすさに効きます。
コントラスト、キーボード操作、代替テキストなど、アクセシビリティの基本を満たして
OGPとmeta情報
検索結果やSNSでリンクを共有した時の見え方を決める設定です。リンクは共有されて広がるものであり、未設定だとタイトルも画像もない裸のURLとして流れます。公開前に一度確認します。
OGP画像、タイトル、説明文を設定して。SNSで共有した時の見え方を確認して