design-system

デザインシステム

使用するタイミング

フロントエンドデザインの実装における不変条件、つまりトークンの設計、タイポグラフィの階層、読み込み順序、FOUT の防止、クロームの安定性、モーションのタイミング、色の意味付けが必要な場合に、このスキルを使用します。コンポーネント、ページ、デザインシステムを構築する際は、design と併用します。美的な方向性は、これらの実装ガイドラインとは別のものです。

UI を実装する際は、design と併用します。色、書体、モーションに関するすべての選択は、これらのルールに基づく必要があります。

トークンの設計

すべての色は、少数のプリミティブに対応させます。場当たり的な 16 進数値は使いません。

• 前景色：テキストの階層（プライマリ、セカンダリ、控えめ）。
• 背景色：サーフェスの高さ（ベース、浮き上がり、オーバーレイ）。
• 境界線：区切りの階層（控えめ、標準、強調）。
• ブランド：ブランドの識別とプライマリアクセント。
• セマンティック：破壊的操作、警告、成功（必要に応じて情報）。

コードではトークン（CSS 変数、テーマオブジェクト）を使用し、UI に 16 進数値を直接記述しないでください。

タイポグラフィ

• 階層：見出し — 存在感を出すため、ウェイトを重くし、文字間隔を狭くします。本文 — 読みやすい、無理のないウェイトにします。ラベル／UI — 小さいサイズでも使えるミディアムウェイトにします。データ — 等幅フォントを使い、tabular-nums で位置を揃えます。
• サイズ、ウェイト、文字間隔を組み合わせて、ひと目で階層がわかるようにします。目を細めたときに見出しと本文の違いがわからなければ、階層が弱すぎます。
• フォント：ディスプレイフォントと本文用フォントを組み合わせ、ひと目で階層がわかるようにします。どのフォントを選ぶかはデザインの方向性であり、実装上の決まりではありません。ドメインに合わせて選び、最初に思いついた選択肢（平均的な選択肢）から離れてみましょう。design-spatial §2 を参照してください。
• データ（機能目的のみ）：桁を揃える必要がある実際の数値、ID、タイムスタンプには、tabular-nums を指定した等幅フォントを使用します。等幅フォントの価値は、列内で値を揃えられるときに発揮されます。「テクニカル」な見た目にするために、装飾的な眉見出しやメタデータの極小テキスト（「35MM · DEVELOP · SCAN」、架空の仕様キャプションなど）へ等幅フォントを無闇に使わないでください。これはデータではなく、現在の流行に乗っただけの粗雑なデザインです。design-spatial §2 を参照してください。

読み込み順序 — 最初に見えるものを最初に読み込む

最初のビューポートは、正しく完成した状態で、すばやく描画される必要があります。ユーザーが最初に目にするかどうかに応じて、すべてのリソースの読み込み順を決めます。それ以外は後回しにします。

• 優先するのはファーストビューに表示される要素だけです（ヒーローテキスト、ヒーロー画像／動画、ブランドマーク）。すべてをプリロードするのは、何もプリロードしないのと同じです。本当に重要なリソースが帯域幅の競争に負けてしまいます。最初の画面に表示される要素を少数だけ選び、それらを優先します。
• フォント：WOFF2 でセルフホストします。 OTF/TTF を WOFF2 に変換します（Brotli によりバイト数は約半分になり、グリフは同一です）。最初のビューポートで使うウェイトには、<link rel="preload" as="font" type="font/woff2" crossorigin> を指定します。描画を妨げるサードパーティ製フォントのスタイルシートは使わないでください。Google Fonts の <link> は CSS のラウンドトリップを追加し、フォントのダウンロード開始前に余分な DNS/TLS 処理も発生させます。代わりにセルフホストしてください。
• LCP 画像／動画： ヒーロー画像（または動画のポスター）に fetchpriority="high" を指定します。CSS から参照される場合（パーサーは CSS の url() を早期に認識できないため）は、<link rel="preload" as="image"> でプリロードします。ヒーロー領域を空にしてはいけません。空白のフレームが表示されないよう、ポスター画像または低解像度のプレースホルダーを用意します。
• ファーストビューより下： 画像には loading="lazy" decoding="async" を指定し、動画には preload="none"（または "metadata"）を指定します。重要でない JS には defer を指定します。遅延読み込みされるメディアによってレイアウトがずれないよう、常に領域を確保します（aspect-ratio、または width と height）。これにより CLS を防げます。
• 描画を妨げる <head> の内容は最小限にします。クリティカル CSS はインライン化し、残りは遅延読み込みします。

フォントの読み込み — 読みやすさと安定したメトリクス

font-display: swap はポップ効果を生みます。フォールバックフォントを描画した後、Web フォントに切り替えて再レイアウトします。ユーザーが読み込みを見守るテキスト（タイトル、ワードマーク、ヒーローコピー）には使わないでください。視覚的な安定性とすぐに読めることのバランスを取り、フォントの読み込みを待つ間、重要な見出しやコントロールを非表示にしないでください。

• 重要ではない装飾的なディスプレイテキストに限り、任意で本来のフォントが読み込まれるまで表示を遅らせます。 <head> 内で同期的に、<html> に fonts-pending クラスを追加し、ディスプレイフォントのテキストを opacity: 0 にします。document.fonts.ready のタイミングで — 重要な各フォントに対して document.fonts.load('<weight> 1em "Family"') を実行して読み込みを開始し — fonts-ready に切り替えて、テキストをフェードインさせます（約0.5秒）。フォントの読み込みに失敗してテキストが永久に非表示にならないよう、必ず約2.5秒の安全タイムアウトを設け、どのような場合でも表示させてください。
• これにプリロードと WOFF2（上記）を組み合わせると、非表示の時間が数秒ではなく数百ミリ秒になり、フェードが読み込みの遅延ではなく意図的な演出として見えます。
• 知覚しにくい切り替えで許容できる本文テキストの場合は、最低限、再レイアウトをなくします。size-adjust / ascent-override / descent-override で調整したフォールバック用の @font-face（または font-family のフォールバック）を定義し、フォールバックのメトリクスが Web フォントと同じになるようにして、切り替え時に何もずれないようにします。

実装例 — AR 製品リサーチページ：<head> のスクリプトで fonts-pending → fonts-ready を切り替え（タイトルは fonts.ready でフェードインし、2.5秒後にフォールバック）、ファーストビューに表示される4種類の WOFF2 ウェイトをプリロードし、ブランドフォントをセルフホストして Google への往復リクエストをなくします。

読み込みに時間がかかるコンテンツ — 見苦しい中間状態を決して表示しない

準備に目立つ時間がかかる可能性のあるもの、つまり上記のフォント、大きな画像、動画、<canvas> シーン、Three.js／WebGL、遅延読み込みされる React アイランド、ネットワーク経由で取得するものやメインスレッドで重いセットアップを行うものは、素早く表示するか、スムーズに読み込む必要があります。ブラウザーのデフォルトの動作（空白の領域 → 部分的な描画 → リフロー → 最終状態）は見苦しい中間状態です。対策してください。

対策は 2 つあります。両方を使いましょう。

• より速く表示する。 圧縮します（フォントには WOFF2、glTF には Draco、画像には WebP／AVIF、動画には preload="metadata" を指定した h264／h265）。最初のビューポートで実際に必要な少数のアセットをプリロードします（<link rel="preload">）。LCP 対象との競合を避けるため、ファーストビューより下のコンテンツは遅延読み込みします。領域をあらかじめ確保しておき（aspect-ratio、width と height）、遅延コンテンツによる CLS を防ぎます。
• スムーズに読み込む。 読み込み中の状態をスタイル付きのプレースホルダーで隠し、実際のコンテンツをフェードインさせます。スケルトンボックス、ぼかした低解像度ポスター、単一の ASCII グリフ、あるいはコンテナーの背景色だけでも構いません。デザインに一貫した表示なら、デフォルトの部分描画より優れています。

具体的な「見苦しい」状態と、その対処法は次のとおりです。

症状	対処法
JS が位置を設定するまで、注釈ラベルが translate(0,0)（コンテナーの左上）に重なって表示される	ラベルを opacity: 0 で開始し、transition: opacity ~0.35s を設定します。最初の投影でインラインの opacity を設定すると、CSS によってフェードインします。
初回レンダリング時、Canvas／WebGL が 1 フレームだけ空白または黒で描画される	同じ領域にプレースホルダー（CSS アート、低解像度のポスター画像、または紙のようなスケルトン塗り）を表示し、最初の実フレームが描画されたら取り除きます。
遅延画像の取得後、レイアウトが跳ねるように表示される	aspect-ratio と、ファーストビューでは <link rel="preload">、それより下では loading="lazy" decoding="async" を使います。初回描画時には load イベントで opacity:0 からフェードインさせます。
再生開始時に動画のポスターから最初のフレームへ突然切り替わる	自分で用意した静止画に一致する poster を指定します。playing イベントが発火する頃には、スムーズな切り替えが完了しています。
3D モデルが画面中央に突然現れ、切り替えがない	Canvas は表示状態のまま opacity: 0 にしておきます。最初の tick() の後、GLTFLoader の成功コールバック内で .viewer-ready クラスを切り替えるか、インラインの opacity を設定します。
遅延読み込みされる React アイランドで、UI がない方がましに見えるフォールバックが点滅する	Suspense のフォールバックをスピナーではなく、最終的なレイアウトをなぞるスケルトンに置き換えます。

目安として、読み込み途中のページをユーザーがスクリーンショットに撮ったときに気まずく感じるなら、スムーズな表示状態を用意する必要があります。プレースホルダーは凝ったものでなくても構いません。意図的にデザインされ、適切なサイズで、表示されるコンテンツのデザイン言語に沿っていることが重要です。

固定表示領域は動かさない — ステータステキストでレイアウトを変えない

ヘッダー、ナビゲーション、ツールバー、検索バー、ステータス領域などの固定表示領域は、どのようなテキストが表示されても高さを一定に保つ必要があります。「モデルを読み込み中…」「N 件が一致・M 件をインデックス済み」、空状態のヒントといった一時的なステータス、読み込み中の表示、説明文は、2 行目に折り返されて隣接するコントロールを押し下げてはいけません。メッセージの変化に応じて伸び縮みするステータス領域は、動的コンテンツではなくレイアウトのガタつきです。

• 任意のステータス要約に限り、1 行に制限します： white-space: nowrap; overflow: hidden; text-overflow: ellipsis を指定し、最長のメッセージは折り返さず省略表示します。
• 領域をあらかじめ確保します： メッセージが収まる固定の height（または min-height）をコンテナーに指定し、最短の状態、最長の状態、空状態で占める領域を同じにします。

固定表示領域を動かさず、動かすのはコンテンツ領域だけにしてください。一時的なテキストによるレイアウトシフトは、仕上がりが粗雑な印象を与えます。（これで防げる具体例：検索アプリで、モデルの読み込みメッセージが 2 行に折り返され、検索バーを下に押し下げてしまう。）

モーション

• タイミングに一貫性と意図を持たせます。animation-delay を使ったページ読み込み時の段階的なアニメーションのように、よく練られた一つの演出は、散発的なマイクロインタラクションより効果的です。HTML では CSS のみを、React では Motion ライブラリを優先してください。（一般公開または複数ユーザー向けのプロジェクトでは、prefers-reduced-motion を尊重してください。）
• 控えめでプロフェッショナルな UI のデフォルト（絶対的なルールではなく、出発点です）：マイクロインタラクションは約 150ms、大きなトランジションは 200〜250ms、イージングは ease-out。遊び心のあるおもちゃのようなトーン（デザイン思考）では、スプリングやバウンス、長めの間が適している場合もあります。こうした数値をデフォルトにするのではなく、選んだ方向性に動きの感触を合わせてください。
• 演出設計 — 単一のマイクロインタラクションを超えるもの（ルート／ページ遷移、リストの並べ替え、表示演出、共有要素）には、references/motion-choreography.md を読み込んでください。トランジションを加える価値がある条件（何かを伝える必要があり、そうでなければ削除する）、どの種類をどの順序で実装するか、ナビゲーションの種類に応じたスタイル（方向性のあるスライドは階層的／順序のあるものにのみ使用し、同列の要素間のスライドは奥行きを誤って伝えるため、水平方向の遷移にはフェードを使用）、時間の一覧表、実装上の工夫（コンポジターのみで処理できるプロパティ、モーフ時のモーションブラー、テキストをラスタースケールしないこと、常時表示される UI 要素の分離）が記載されています。フレームワークに依存しません。

スクロール連動のナラティブ（スクロールテリング）

解説／エディトリアル／データを順に追うコンテンツでは、クリック操作型ウィジェットよりも、スクロール連動のグラフィックを優先してください。読者は通常スクロールするため、説明を進めるために切り替えボタンを探してクリックさせると、操作の妨げになり、読み飛ばされます。NYT／Pudding のパターンを使います。グラフィックを 1 つ position: sticky で固定し、短いテキストの「ステップ」をスクロールさせ、各ステップに応じてグラフィックの状態を切り替えます。

• 仕組み： rootMargin: '-48% 0px -48% 0px'（threshold 0）を指定した IntersectionObserver を 1 つ使います。これにより、ステップがビューポートの中央線を越えた時点で正確に「アクティブ」になります。アクティブなインデックスによって固定されたグラフィックを再描画します。約 30 行で実装できます。これは依存関係を除いた scrollama そのものです。スクロール用ライブラリは追加しないでください。
• レイアウト： 2 列にし、一方にスクロールするステップを、もう一方に sticky top-0 h-screen のグラフィックを配置します。モバイルでは縦に積み、グラフィックを上部に固定します。各ステップを約 85vh にして、一度にちょうど 1 つが中央に来るようにします。非アクティブなステップカードを暗くし（opacity:.3）、表示中のものを読み取りやすくします。
• グラフィックはアクティブなステップの純粋関数（graphic(active)）とし、クリック状態を持たせません。これにより、スクリーンショットやエクスポートでも決定論的な結果が得られ、静的な図としても機能します。スクロールを段階的ではなく連続的に感じさせるため、状態間（色／幅／不透明度）をアニメーションさせます（300〜700ms）。
• 使用しない場面： ダッシュボード、ツール、フォームなど、ユーザーが読むのではなく操作するものは、インタラクティブなままにします。スクロールテリングは、順序をこちらで決めるナレーション向けです。（一般公開または複数ユーザー向けのビルドでは、上記のモーションに関する注意事項に従って prefers-reduced-motion を尊重してください。状態の変化は維持しつつ、トゥイーンは省きます。）

空間構成とレイアウト

グリッドシステム、8 ポイントのスペーシングスケール、視覚的な重みのバランス、配置、描画後の批評ループについては、design-spatial（../design-spatial/SKILL.md）を参照してください。これは、このファイルのトークン／タイポグラフィ／色に対応する、実装面の指針です。ページ、ダッシュボード、コンポーネントを構成するときは必ず読み込んでください。（ここに含めるべき方向性のヒント：構成の野心度はビジョンに合わせます。マキシマリストなら精緻で重層的なコードが適し、ミニマルで洗練された方向性なら、抑制と正確なスペーシングが求められます。）

入れ子になった角丸（角丸要素が別の要素の内側にある場合のみ）

角丸にすることを推奨するものではありません。角丸要素が別の要素の内側にある場合（カード内のボタンや、コンテナ内のインセットパネルなど）に適用されます。入れ子の場合：

• 子要素の角丸半径 ≤ 親要素の角丸半径とし、決して大きくしないでください（子要素の角が親要素より丸いと、外側に膨らんでいるように見えます）。
• 理想は同心円状です：child_radius = max(0, parent_radius − gap)（要素間のパディング）とすると、2つの曲線が平行に走り、内側の角が外側の角を反映します。角丸の親要素の中に、角丸でない、または平坦な子要素を置いても問題ありません。崩れて見えるのは、曲線が一致せず、同心円状になっていない場合です。

色

• ドメインに根差したパレット：色は上から付け足したようではなく、プロダクトの世界観から生まれたように感じられるべきです。
• 温度感だけにとどめない：静かかにぎやかか、密かゆったりか、真面目か遊び心があるか、幾何学的か有機的か——暖色系か寒色系かだけではありません。
• 色に意味を持たせる：グレーは構造を作り、色はステータス、アクション、強調、アイデンティティを伝えます。根拠のない色使いはノイズです。（抑制すること——アクセントは5色ではなく1色にすること——は方向性を定める原則です。design-thinking → インパクトは句読点のように要所に使うを参照してください。）
• コントラスト — 判断にはAPCA、適合性の基準にはWCAG。 知覚上のコントラスト（この面の上のテキストは無理なく読めるか？）を判断する場合は、APCA（apcacontrast.com）を優先してください。APCAは、明るい文字色を暗い背景に置いた場合や中間調の評価を誤りやすいWCAG 2の比率よりも、明度の知覚をはるかによくモデル化しています。WCAG 2（4.5 / 3:1）は適合性の最低基準として維持してください。design-spatialのlayout-audit.jsが判定基準とし、アクセシビリティ規格が求めている基準です。APCAはデザイン上の判断材料になりますが、WCAGへの適合には、コントラスト比だけでなく、該当するすべての達成基準を満たす必要があります。
• インタラクティブな状態ではコントラストを高めます。 :hover、:active、:focusは、通常時よりも目立つようにしてください。コントラストを下げるのではなく、高めます。ホバー時にコントラストが低下する（例：テキストを背景色に近づけるよう明るくする）と、無効状態のように見えます。

一般的な流行の見た目（Inter、白地に紫、同じようなダークガラスのカード）を避け、世代ごとに変化をつける方法については、design-spatial §2に記載されているため、ここでは繰り返しません。

背景とディテール

単色塗りつぶしよりも雰囲気を重視します。ただし、選んだ美的方向性に合わせてください。反射的に使われるグラデーションメッシュ／ノイズ／粒子による「プレミアム」表現そのものが、デザイントレンドの平均にすぎません（design-spatial §2）。その方向性が本当に求めている場合にのみ採用し、装飾のためだけに使わないでください。

例

ユーザーの依頼：

@design-system を使ってこのインターフェースをレビューし、最も影響の大きいデザイン上の問題を特定して、実装可能な改善案を提案してください。

制限事項

• タスクが上流の情報源およびローカルプロジェクトのコンテキストに明確に合致する場合にのみ、このスキルを使用してください。
• 変更を適用する前に、コマンド、生成コード、依存関係、認証情報、外部サービスの動作を検証してください。
• 例を、環境固有のテスト、セキュリティレビュー、破壊的または高コストな操作に対するユーザーの承認の代わりとして扱わないでください。

アクセシビリティとフォールバックの要件

読みやすいフォールバックと、障害発生時／JavaScript 無効時の経路を用意して、重要なテキストが常に表示されるようにしてください。フォントの読み込みによってタスクへのアクセスが遅れたり、フォーカス可能なコントロールが見えない状態になったりしてはなりません。フォントの変換やセルフホストにはライセンス上の許可が必要であり、バイト数の削減や同一の描画結果が保証されるわけではありません。すべてのステータス／エラーテキストは、アクセス可能な展開機能または同等の可視情報によって維持してください。ズーム時、幅が狭い場合、またはローカライズ時に、重要なメッセージが切り詰められないようにしてください。すべてのユーザーの動きの低減設定を尊重し、トランジション中に情報を隠さないでください。また、スティッキースクロリーテリングには、静的でキーボードからアクセスできるナラティブ形式の代替手段を用意してください。コントラストのみの監査ではWCAGへの適合を証明できません。キーボード／フォーカス、セマンティクス、リフロー、テキストによる代替、該当する達成基準をテストしてください。外部のデザイン関連ツールやlayout-auditヘルパーはこのツリーに同梱されていないため、呼び出す前に利用可能か確認してください。