eduardopin/design-reference

design-reference — テンプレートではなく、リファレンスとなるインターフェース

インターフェースがリファレンスとなるのは、その分野に精通した人が、それがこのプロダクトのために、そしてその分野のトップクラスの人物によって作られたと認識したときです。敵はデフォルトです。つまり、あらゆるモデルが似たようなブリーフに対して生成するであろう出力です。

0. プロジェクトルール

すべてのレンダリング作品（画面、コンポーネント、HTMLドキュメント、Artifact、PDF、デッキ、図（cloud-diagram）、バナー）の最初のステップは、プロジェクトのデザインシステムをスイープすることです。これはセッションごとにプロジェクトごとに1回行います：

python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root>         # サマリー
python3 -I ~/.claude/skills/design-reference/scripts/sweep.py <root> --css   # `--ds-*`付きの:root

これは、記述された仕様（DESIGN.md、docs/design*）、トークン（tailwind.config.*、 :root/@theme付きCSS、*.tokens.json）、コンポーネントテーマ、package.json、components.json、StorybookおよびFigmaリンクを読み取り、判定を返します：プロジェクト固有（作品はそのトークンを纏う）またはニュートラル（チームの中立パレット）。--cssは--ds-bg --ds-surface --ds-fg --ds-fg-2 --ds-accent --ds-border --ds-font-display --ds-font-body --ds-font-monoとダークブロックを出力します；チームのテンプレートはこれらの変数を読み取ります。--jsonは完全な検出結果を返します。競合時の優先順位：仕様 > トークン > コンポーネント。1ページに1システム。作品がどのシステムを纏い、どこで見つかったかを一文で述べてください。クライアントやサードパーティのブランドの場合は、最初に尋ねてください。詳細はreferences/design-system-sweep.mdにあります。

次に、新しい画面が使用する共有コンポーネントを読み取ります。ブリーフとビジュアルワールドは、あなたのいかなる好みやここにあるいかなるルールよりも優先されます。 洗練はアイデンティティ、コピー、振る舞いを維持します；再デザインはビジュアルワールド全体を置き換えます — 破棄されたルックを磨くことは決してありません。プロジェクト独自のデザインスキル（.claude/skills/）は、このスキルよりも優先されます。

DESIGN.mdがないからといって、必ずしもグリーンフィールド（新規プロジェクト）であるとは限りません：エビデンスはコードと既存の画面であり、ファイル名ではありません。

1. サーフェスモード（後続のすべてを決定する）

要求されたサーフェスによって選択します。プロダクトによってではありません：

モード	訪問者の成功	例	ルールとなるもの
Persuade（説得）	決定し行動する	ランディングページ、価格設定、キャンペーン	注意、証拠、行動喚起 — デザイン は プロダクトである
Operate（操作）	タスクを完了する	アプリ、ダッシュボード、管理画面、エディタ、設定	スキャン容易性、一貫性、ネイティブへの期待；ブランドは細部に宿る
Read（読む）	何かを理解する	ドキュメント、記事、チェンジログ、ヘルプ	理解のための構造、そして読書の快適さ
Experience（体験）	作品の中にいる	ポートフォリオ、ギャラリー、美術館、ショーケース	最初の折り目から作品が主導する；インターフェースは後退する

ツールのランディングページはPersuadeです；ファッションブランドのドキュメントはReadです；美術館のツアーはExperienceです。

2. コードの前の方向性（2パス、必須）

パス1 — コンパクトな計画、コードファイルを開く前：

• 主題： 一文：誰のためのものか、この画面の単一の仕事は何か、そしてこの主題の世界（素材、道具、語彙、人工物）の中で何が視覚的な選択肢になり得るか。
• 色彩： 4～6の名前付き値（16進数またはoklch）、それぞれの意味上の役割付き。
• タイポグラフィ： 2つ以上の役割 — 使用を控えめにした特徴のあるディスプレイフェイス、補完的な本文フェイス、必要に応じてデータ用のユーティリティフェイス。他のプロジェクトで使うであろう組み合わせは決して使わない。
• レイアウト： 一文のコンセプト + ASCIIワイヤーフレーム。2つの代替案を比較する。
• シグネチャ： その画面が記憶されるための単一の要素。すべての大胆さはそこに集中し、残りは静かで規律を保つ。
• モーション： 1つのオーケストレーションされた瞬間、またはなし。どちらか述べる。

パス2 — 自己批判。 各項目について問いかける：「これを別のプロダクトの似たようなブリーフに対して生成するだろうか？」もし「はい」なら、それはデフォルトであり、選択ではありません — 書き直し、何を変えたかを述べてください。その後でのみコーディングを開始し、すべての色と書体を計画から導き出します。

AIが今日デフォルトで生成する3つのルック：（1）クリーム#F4F1EA + 高コントラストセリフ + テラコッタ；（2）ニアブラック + 1つの強烈なアクセント（ライムグリーンまたは朱色）；（3）細い罫線、ゼロ半径、密なカラムの大判シート。ブリーフがそれらを要求する場合は、すべて正当です。軸が自由である場合、その自由をそれらに費やさないでください。

スタイル、パレット、フォントペアリングのカタログをローカル検索するには、ui-ux-pro-max（python3 scripts/search.py "<ドメイン> <プロダクト>"）を使用してください；これはリファレンスエンジンであり、アートディレクターではありません — 決定は依然としてあなたのものです。

3. トークンが真実の源泉である

• 3層：プリミティブ → セマンティック → コンポーネント。コンポーネントは決してプリミティブや生の16進数を読み取らず、--gray-100ではなく--color-surface-raisedを読み取ります。
• 形式：プロジェクトにパイプラインがある場合はW3C DTCG 2025.10（tokens.json）；そうでない場合は、ダークモードを@media (prefers-color-scheme: dark)と[data-theme]で持つ:root上のCSSカスタムプロパティ。
• 色は可能な限りoklchで；コントラストは測定（APCAまたはWCAG）、推定ではありません。
• ダークテーマは輝度マッピングであり、反転ではありません。
• 終了時に、プロジェクトにDESIGN.mdがない場合は、生成することを提案してください（トークンをYAMLで + 各値の理由を散文で）— これにより次のセッションが今回と一貫性を保つことができます。

スケール、コンポーネント仕様（バリアント、サイズ、優先順位付き状態、アナトミー）、shadcn/Tailwind/ダークモードに関する注記：references/tokens-and-components.md。完全なシステムをDTCG + CSS/Tailwindで生成するには：sumi:tokens。

4. ビルド

• スタックとコンポーネント：プロジェクトのものを使用。shadcn/Tailwind → references/tokens-and-components.mdおよびcontext7を通じたライブドキュメント；Figmaからのデザイン → figma:figma-design-to-code（MCP）またはプロジェクト独自のローカルスキル（例：implement-from-figma、refactor-frontend-component）；Figmaへの書き込み → figma:figma-use。
• ネイティブモバイル：ブランドよりもプラットフォーム（HIG / Material）を尊重する。
• クラウドまたはインフラストラクチャアーキテクチャ図（AWS、OCI、GCP、Azure、Cloudflare）：常にcloud-diagramを使用。それがこのタスクのデザインスキルです；そのキット（そのスキルのreferencesにあるtemplate.html）をコピーし、そのrender.shで測定します。マーメイド図、汎用ボックス、外部画像アイコンは使用しません。
• 最初から実際のコンテンツを使用する：短い、中間、非常に長いコピーをテスト；空の状態；ローディング；エラー；権限なし。Loremプレースホルダーは欠陥です。
• コピーはデザイン素材です：コントロールは何が起こるかを述べます（「送信」ではなく「変更を保存」）；ボタンからトーストまで同じ動詞；エラーは何が起こったかとそこから抜け出す方法を述べます；空の状態は行動への招待です；能動態、文の先頭だけ大文字。
• CSS：自己打ち消しする詳細度（.section × .cta）に注意。transition: allは絶対に使用しません。デフォルトではtransform/opacityのみアニメーションします。
• ブラウザのサーフェスもデザインです：テキスト選択、キャレット、スクロールバー、フォーカス、アンダーラインオフセット、表組み数字。これらをパレットからテーマ設定します — それはページが構築されたことを示す最も安価なサインです。

プロダクトUI実装のコンパニオン

ネイティブまたはレスポンシブなプロダクトUIには、利用可能なmobile-design-studioスキルを唯一のオプションのデザインコンパニオンとして使用します：小さな実装単位、モバイル人間工学（タッチターゲット、セーフエリア、キーボード、テキストスケーリング、戻る）、状態/回復チェック、プラットフォームのエビデンス。design-referenceは唯一のデザイン方向性のソースのままです：承認済みのブリーフ、トークン、コンポーネントを再利用します；2番目のブランディング/方向性プロセスを実行したり、重複したトークンファイルを作成したりしないでください。現在のユニットに必要なコンパニオンリファレンスのみを読み取ります。デッキ、アート、ポスター、クラウド図のルートではありません；それらには専用のスキルが割り当てられています。

コンパニオンのディレクトリは、選択したスキルの元のインベントリパスから解決し、生成されたプロンプトキャッシュや想定される~/.claudeインストールから解決しないでください。コンパニオンがないか手動のみの場合は、宣伝したり自動ロードしたりしないでください；プロジェクトの方法を続行してください。プロジェクトスキルと必須のプラットフォーム/Figma前提条件（例：Expo概要、React Native、Figma設計からコード/使用）は依然として適用されます；それらはオプションの競合するデザイン方向性ではありません。2つのデザインスキルの上限を維持してください：この方法と1つのコンパニオン、決して追加のSumi/UIスタイルスタックはありません。

5. 品質基準（結果で検証、意図では検証しない）

UIを編集する直前に references/quality-floor.md を読んでください。譲れないポイント：

• コントラスト ≥ 4.5:1（テキスト）、≥ 3:1（大文字）；色付きサーフェス上のセカンダリテキストは、そのサーフェス自体の色相から着色され、灰色ではないこと。
• すべてのインタラクティブ要素に可視のフォーカスがあること；代替なしにアウトラインを削除しないこと。
• タッチターゲット ≥ 44×44（ネイティブ）/ 24×24 CSS px（Web）、ターゲット間8px。
• prefers-reduced-motionを尊重；アニメーションは中断可能；キーボードで開始されたものはアニメーションしない。
• 320pxまでレスポンシブで水平スクロールなし；フルブリードレイアウトでセーフエリア。
• 画像は宣言された寸法を持つ；フォントはfont-displayを持つ；長いリストは仮想化される。
• 状態：ホバー、アクティブ、フォーカス、無効、ローディング、エラー、空 — すべて。
• 絵文字をアイコンとしてゼロ使用；アイコンは1つのライブラリ、1つのストローク、1つの太さから。

ループではなく、制限されたラウンドでの検査： 全体を構築し、デスクトップとモバイルを一緒にキャプチャし（可能な場合はブラウザ経由のスクリーンショット）、すべてを1つのバッチで修正し、最大1ラウンドで確認し、停止します。無制限のQAは、sumi:auditがより良く行うことを、より悪い方法で所有者のお金を消費します。

6. ルールに基づいたモーション（Emil Kowalski）

1. アニメーションすべきか？ 100回以上/日（ショートカット、パレット）→ 決してしない。数十回/日（ホバー、リストナビゲーション）→ 大幅に削減。時々（モーダル、ドロワー、トースト）→ 標準。まれ（オンボーディング、お祝い）→ 喜びを与えてもよい。
2. 宣言された目的：空間的連続性、状態表示、説明、フィードバック、ハードカットの回避。「見た目が良い」は頻繁に見られるものの目的ではありません。
3. イージング： 出現/消滅 → 強いイーズアウト cubic-bezier(0.23, 1, 0.32, 1)；画面上での移動/変形 → イーズインアウト cubic-bezier(0.77, 0, 0.175, 1)；ホバー/色 → ease；一定の動き → linear；iOSドロワー → cubic-bezier(0.32, 0.72, 0, 1)。UIでイーズインは絶対に使用しない。
4. 持続時間： ボタン 100～160ms；ツールチップ 125～200ms；ドロップダウン 150～250ms；モーダル/ドロワー 200～500ms；UIはマーケティングを除き常に < 300ms。
5. 何もどこからともなく現れてはならない：scale(0)ではなくscale(0.95) + opacity 0。ポップオーバーはトリガーからスケールする（transform-origin）；モーダルは中央に留まる。 :active は scale(0.97) を使用。すべてのセクションに同一のエントランスがあるのはアンチパターンです；一つの作者による瞬間はアンチパターンではありません。

7. アート、キャンバス、クリエイティブワーク

リクエストがポスター、カバー、グラフィック作品、生成アート、3Dビジュアル、または「UIブリーフのない美しいもの」である場合、方法が変わります：最初にビジュアル哲学（1～2語で名前を付けたムーブメント + 空間、色彩、素材、スケール、リズム、構成に関する4～6段落）、次に実行。テーマへの参照は微妙に — それを知っている人は感じ、他の人は巧みな構成を見ます。90% ビジュアル、10% テキスト。マージンからはみ出るものはなく、重なるものもありません。

サーフェス	ツール
静的PNG/PDF（ポスター、アート、カバー）	vendor/canvas-design（Anthropic）
2D生成アート、フローフィールド、パーティクル	vendor/algorithmic-art（p5.js、再現可能なシード、スライダー）
3D / シェーダー / インタラクティブシーン	three.js（r160+）、GLSL ShaderMaterial；常に ティアダウン時にdispose()とリスナー削除
ソーシャルメディア / 広告 / バナー / 印刷物用ピース	references/identity-and-pieces.md（サイズ、セーフエリア、行動喚起）+ 正確なサイズでキャプチャされたHTML
スライド	slides
クラウドアーキテクチャ図	cloud-diagram
ブランドガイド、パレット、ロゴルール	references/identity-and-pieces.md；ブランドボイスとコピー → writing
AI生成のロゴ、アイコン、アイデンティティモックアップ	design（claudekit：APIを使用した生成スクリプト、キーが必要）
無限キャンバス上のサイドバイサイドバリアント	superdesignプラグイン（有料；ログインが必要 — 所有者の判断）
生成画像/ビデオ	sumi:generate または設定された画像MCP

特定可能なアーティストの作品を決してコピーしないでください；影響を引用し、独自のものを作成してください。フォント：適切な文字セットを持つフォントをダウンロードしてセルフホストしてください；「最も近い」システムフォントは失敗であり、フォールバックではありません。

8. 既存のものの監査と修正

• トップ修正によるクイックスコア：sumi:roast。完全監査（ヒューリスティック、認知、フロー）：sumi:audit。WCAG 2.2 AA アクセシビリティ：sumi:a11y。 Webチェックリスト（a11y、フォーム、モーション、タイポグラフィ、パフォーマンス、i18n）：references/quality-floor.md §B、file:lineとして出力。
• 生成されたUIコードの修正：sumi:fix。モーションレビュー：発見事項ごとに1行の| Before | After | Why |テーブル。
• 同じセッションで2つ以上のデザインスキルをロードしないでください：説明が競合し、回答が改善されることなくコンテキストが肥大化します。

9. デリバリー

Mode             [Persuade | Operate | Read | Experience]
Direction        [主題 · 名前付きパレット · フォントペアリング · シグネチャ · モーション]
What was default [自己批判で書き直した内容とその理由]
Tokens           [ファイルとレイヤー；DESIGN.md 生成/更新されたか？]
Floor            [§5の各チェックと測定値（「ok」ではない）]
States           [実装された状態のリスト]
Captures         [デスクトップ + モバイル（環境が許せば）]
Pending          [所有者のみが提供できるアセット；所有者の判断に委ねられる決定]