interface-kit

インターフェースキット：優れたインターフェースを実装するためのガイド

プロジェクトのルートに DESIGN.md がある場合、そのトークンと仕様はこのスキルのすべてのデフォルト設定に優先します。このスキルでは、デザインシステムがない場合に使える妥当なデフォルト設定と、いずれの場合にも適用される実装ガイダンスを提供します。

各セクションの詳細については、このスキルの references/ ディレクトリにあるリファレンスファイルを参照してください。

---

1. 基本理念

センスは生まれつきのものではなく、鍛えられるものです。優れたインターフェースがしっくり感じられる理由を学びましょう。気に入ったアプリを分析してみてください。余白、タイミング、影の重みなどを観察します。「まあまあ」と「卓越」の差は、ユーザーが感じ取るものの意識して気づくことのない、何百もの細かな判断によって生まれます。

目に見えない細部が積み重なります。 丸みを帯びた角、滑らかなトランジション、適切に選ばれた影は、それぞれ単独では重要ではありません。しかし、組み合わさると「かすかに聞こえる何千もの声が調和して歌う」ようになります。こうした累積効果が、職人技と単なるアウトプットの違いを生みます。

美しさは力になります。 仕上げにこだわるのは見栄ではありません。適切なデフォルト設定、よく考えられたタイポグラフィ、意図的なモーションは、本当の差別化要因です。ユーザーは、細部まで配慮されたインターフェースを信頼します。投資家も注目します。競合他社がセンスを簡単に再現することはできません。

強さより意図を重視します。 大胆なマキシマリズムも、洗練されたミニマリズムも有効です。うまくいかないのは、明確な方向性がないことです。あらゆるビジュアル上の判断は、意図的なコンセプトの方向性に結びついているべきです。なぜその選択をしたのか説明できない場合は、見直してください。

方向性を決め、精密に実行します。 異なるスタイルの間で迷わないでください。ブルータリズムに徹したページは、「いろいろなものを少しずつ取り入れた」ページより、常に優れたものになります。方向性を決めてから、洗練させましょう。

ありきたりな「AIスロップ」の美学は絶対に生み出さないでください。 白い背景に意味なくグラデーションを使わないでください。ストックイラストを使った、型どおりのヒーローセクションを避けてください。どの製品にも当てはまりそうな、無難で印象に残らないレイアウトは避けましょう。すべてのインターフェースに、ひと目でそれと分かる明確な個性を持たせてください。

---

2. 優先順位

UI を実装するときは、以下の優先順位に沿って作業してください。上位の項目は必須です。下位の項目は、品質をさらに高めるための仕上げです。

優先度	レベル	意味
アクセシビリティ	CRITICAL	コントラスト比 4.5:1、キーボード操作、ARIA セマンティクス、視認できるフォーカスリング。ユーザーを排除するものはリリースしないでください。
パフォーマンス	HIGH	WebP/AVIF 画像、ファーストビューより下の遅延読み込み、CLS < 0.1、コンポジタースレッドでの transform のみを使ったアニメーション。
タイポグラフィ	HIGH	フォントスムージング、text-wrap の balance/pretty、データには tabular-nums、最大行長は 65ch。
レイアウトと空間	HIGH	4/8px グリッド、同心円状の角丸、幾何学的な配置より視覚的な整列を優先。
色とテーマ	MEDIUM	HSL カスタムプロパティ、セマンティックトークン、ダークモードの組み合わせは個別にテスト。
モーションとインタラクション	MEDIUM	アニメーションの頻度に基づく判断、150-300ms の時間、デフォルトは ease-out。
仕上げと細部	LOW	枠線の代わりに重ねた影、ボタンを押したときのフィードバック、段階的な表示アニメーション。

LOW の項目を追求するために、CRITICAL/HIGH の項目を決して後回しにしないでください。美しくアニメーションするボタンでも、キーボード操作に対応していなければ、全体としてマイナスです。

---

3. 美的方向性

CSS を一行も書く前に、大胆な美的方向性を定めてください。AI 生成 UI で最もよくある失敗は、どれも同じ無難で印象に残らない見た目に収束することです。

トーンを選ぶ

1 つ選び、徹底してください。

• 徹底的にミニマル — 余白をたっぷり取り、等幅フォントを使い、コントラストを際立たせ、装飾はほぼゼロにします
• マキシマリストな混沌 — テクスチャを重ね、フォントサイズを大胆に組み合わせ、情報を詰め込み、意図的な視覚的ノイズを加えます
• レトロフューチャー — CRT の発光効果、等幅のターミナル、走査線、暗い背景にネオンを取り入れます
• オーガニック／ナチュラル — アースカラー、角丸の形、紙のテクスチャ、手描きのアクセントを使います
• ラグジュアリー／洗練 — セリフ体の見出し、落ち着いた配色、広々とした余白、控えめなゴールドやクリーム色のアクセントを取り入れます
• エディトリアル／雑誌風 — 大胆なタイポグラフィの階層、画面いっぱいの画像、グリッドを崩したレイアウトを使います
• 遊び心／大胆 — 明るい原色、太い境界線、大げさな影、弾むような動きを取り入れます

ビジョンに合わせて複雑さを調整する

マキシマリストなデザインには、複雑なコードが必要です。背景を重ね、複雑なグリッド構造や複数のフォントスタックを使います。ミニマルなデザインには、細部まで緻密な調整が必要です。隠すものがないぶん、間隔の 1 ピクセルまで重要になります。

禁止リスト（DESIGN.md がない場合）

既存のデザインシステムなしで構築する場合、「AI 生成らしさ」を感じさせる、使い古された以下の既定パターンは避けてください。

• フォント：ディスプレイフォントとしての Inter、Roboto、Arial、system-ui、Space Grotesk
• 色：白い背景に紫から青へのグラデーション
• パターン：中央揃えのテキスト、CTA、ストックイラストを組み合わせた汎用的なヒーロー

ライトテーマとダークテーマ、異なるフォントの組み合わせ、異なる美的方向性を使い分けてください。プロジェクト間で同じ選択に収束させないでください。

視覚的な質感

グラデーションメッシュ、ノイズ／粒子のオーバーレイ（filter: url(#noise)）、半透明レイヤーの重ね合わせ、控えめな背景パターン、デュオトーンの画像処理を使って奥行きを加えます。

DESIGN.md はこのセクション全体に優先します。 DESIGN.md で Inter が指定されていれば、Inter を使ってください。紫のグラデーションが指定されていれば、それを使ってください。禁止リストが適用されるのは、デザインシステムが存在せず、ゼロから美的な選択をする場合に限ります。

---

4. タイポグラフィの基本

タイポグラフィは、最も効果の大きいデザイン要素です。適切に整えれば、平凡なレイアウトでも心地よく感じられます。間違えれば、ほかの要素で補うことはできません。

ルートの設定

html {
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
}

ルートレイアウトにフォントスムージングを適用します。macOS では、デフォルトのサブピクセルレンダリングにより、テキストがデザイナーの意図より太く表示されます。

テキストの折り返し

h1, h2, h3, h4, h5, h6 {
  text-wrap: balance;
}

p, li, dd, blockquote {
  text-wrap: pretty;
}

balance は見出しの行を均等に配置します。pretty は本文で単語だけが次の行に残るのを防ぎます。

数値の表示

.data-value, .price, .counter, [data-numeric] {
  font-variant-numeric: tabular-nums;
}

動的に更新される数値（価格、カウンター、テーブルの列など）には tabular-nums を使います。これを使わないと、数字の幅が変わるたびにレイアウトがずれます。

スケールとリズム

• 基本サイズ：本文は最低 16px にします。読み取り可能なコンテンツで 14px を下回らないようにしてください。
• 行の高さ：本文は 1.5～1.75、大きな見出しは 1.1～1.3 にします。
• 最大行長：本文には max-width: 65ch を設定します。長すぎる行は可読性を損ないます。
• 文字サイズのスケール：一貫したスケールを選び、統一して使います。12 / 14 / 16 / 18 / 24 / 32 / 48 / 64。

フォントの組み合わせ

個性のあるディスプレイフォントと、洗練された本文用フォントを組み合わせます。ディスプレイフォントは個性を表現し、本文用フォントは読みやすさを担います。同じフォントファミリー内の階層には font-weight を使います。

• 見出し：600～700（セミボールドからボールド）
• 本文：400（レギュラー）
• ラベル／UI：500（ミディアム）

フォントスタックには必ず代替フォントを含めます。

--font-display: "Instrument Serif", "Georgia", serif;
--font-body: "Söhne", "Helvetica Neue", sans-serif;
--font-mono: "JetBrains Mono", "Fira Code", monospace;

---

5. 色とテーマ

HSL カスタムプロパティ（shadcn パターン）

:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  --primary-foreground: 210 40% 98%;
  --secondary: 210 40% 96.1%;
  --secondary-foreground: 222.2 47.4% 11.2%;
  --muted: 210 40% 96.1%;
  --muted-foreground: 215.4 16.3% 46.9%;
  --accent: 210 40% 96.1%;
  --accent-foreground: 222.2 47.4% 11.2%;
  --destructive: 0 84.2% 60.2%;
  --destructive-foreground: 210 40% 98%;
  --border: 214.3 31.8% 91.4%;
  --ring: 222.2 84% 4.9%;
  --radius: 0.5rem;
}

primary、secondary、destructive、muted、accent、background、foreground などのセマンティックトークンを定義します。色はセマンティックな名前で参照し、コンポーネント内に 16 進数値を直接記述しないでください。

ダークモード

.dark {
  --background: 222.2 84% 4.9%;
  --foreground: 210 40% 98%;
  /* ... desaturated, lighter tonal variants — NOT simply inverted */
}

ダークモードは「色を反転する」ことではありません。彩度を抑えた明るい色調を使います。背景は暗くしますが、純粋な黒（#000）にはしません。テキストは明るくしますが、純粋な白（#fff）にはしません。コントラストはダークモード用に別途テストしてください。ライトモードで基準を満たしていても、ダークモードでは満たさない場合があります。

コントラスト要件

• WCAG AA の最小基準：通常のテキストは 4.5:1、大きなテキスト（太字で 18px 以上、または通常の太さで 24px 以上）は 3:1
• 色だけで情報を伝えないでください。必ずアイコン、ラベル、またはパターンを組み合わせてください
• ブラウザーの開発者ツールにあるコントラストチェッカー、または axe-core でテストしてください

色の自信

主役となる色に明確なアクセントを加えた配色は、控えめで均等に分散した配色よりも効果的です。主役となる色を 1 色か 2 色選び、残りの色は控えめにしましょう。自信のある配色には明確な階層がありますが、迷いのある配色は色が均等に広がり、平坦な印象になります。

---

6. 空間デザイン

同心円状の角丸

ネストされた UI 要素が「しっくりこない」と感じさせる最もよくある原因は、これです。

outer_radius = inner_radius + padding

/* Correct: concentric */
.card        { border-radius: 16px; padding: 8px; }
.card-inner  { border-radius: 8px; }  /* 16 - 8 = 8 */

/* Wrong: same radius on parent and child */
.card        { border-radius: 12px; }
.card-inner  { border-radius: 12px; }  /* Looks bloated */

幾何学的な中央揃えが不自然に見える場合は、視覚的なバランスを優先して配置してください。再生／一時停止アイコン、ドロップダウンのキャレット、非対称なグリフなどは、中央に見えるよう手動で 1～2px 調整が必要なことがよくあります。

境界線よりシャドウ

境界線を使う代わりに、透明度のある box-shadow を複数重ねて、自然な奥行きを表現してください。

.elevated {
  box-shadow:
    0 1px 2px rgba(0, 0, 0, 0.04),
    0 2px 4px rgba(0, 0, 0, 0.04),
    0 4px 8px rgba(0, 0, 0, 0.04);
}

広がりの異なる複数のシャドウを使うと、光の働きを再現できます。くっきりした単一のシャドウは不自然に見えます。

画像のアウトライン

背景が変わっても奥行きを一定に保てるよう、画像やメディアに控えめなインセットアウトラインを追加してください。

img, video {
  outline: 1px solid rgba(0, 0, 0, 0.06);
  outline-offset: -1px;
}

余白のスケール

4px／8px を基本単位とする段階的なシステムを使ってください。すべての余白値は 4 の倍数にします。

4 / 8 / 12 / 16 / 24 / 32 / 48 / 64 / 96 / 128

ヒット領域

すべてのインタラクティブ要素の最小サイズは 44x44px です。視覚的な要素がそれより小さい場合は、疑似要素を使ってヒット領域を広げてください。

.small-button::before {
  content: "";
  position: absolute;
  inset: -8px;
}

Z インデックスのスケール

階層化されたスケールを定義し、任意の値は使わないでください。

--z-base: 0;
--z-dropdown: 10;
--z-sticky: 20;
--z-overlay: 40;
--z-modal: 100;
--z-toast: 1000;

---

7. モーションとインタラクション

使用頻度に基づく判断フレームワーク

アニメーションを判断するうえで、最も重要な考え方です。

頻度	例	アニメーション
1 日 100 回以上	キーボードショートカット、コマンドパレットの操作、タブの切り替え	なし。 アニメーションはゼロ。即時に反応させます。
1 日に数十回	ホバー効果、リスト項目の移動、トグル	なくすか、大幅に減らします。 最大 50～100ms。
ときどき	モーダル、ドロワー、トースト、ページ遷移	標準的なアニメーション。 150～300ms。
まれ／初回	オンボーディング、お祝い、空の状態	楽しさを加えてもかまいません。 300～500ms、より凝った演出。

頻繁に使うアニメーションは動作を遅く感じさせます。使用頻度が低い要素にモーションがないと、違和感を覚えます。使用頻度に合わせてアニメーションの時間を調整してください。

カスタムイージング曲線

組み込みの CSS イージング（ease、ease-in-out）は表現力が足りません。カスタム曲線を定義してください。

:root {
  --ease-out: cubic-bezier(0.23, 1, 0.32, 1);
  --ease-in-out: cubic-bezier(0.77, 0, 0.175, 1);
  --ease-drawer: cubic-bezier(0.32, 0.72, 0, 1);
  --ease-spring: cubic-bezier(0.34, 1.56, 0.64, 1);
}

持続時間の目安

要素	持続時間
ボタン、トグル	100～160ms
ツールチップ	125～200ms
ドロップダウン、ポップオーバー	150～250ms
モーダル、ドロワー	200～500ms
ページ遷移	250～400ms

UI アニメーションは 300ms 未満にしてください。UI アニメーションで ease-in は使わないでください。動き出しが遅く、もたついた印象になります。

入場と退場の非対称性

退場は入場よりも控えめかつ速くしてください。入場アニメーションが 250ms なら、退場は 150～200ms にします。

入場アニメーションの分割と段階的な表示

複数の要素がビューポートに入るときは、意味のまとまりごとに分け、約 50～100ms の遅延をつけて段階的に表示してください。

.stagger-item {
  animation: fadeSlideIn 300ms var(--ease-out) both;
}
.stagger-item:nth-child(1) { animation-delay: 0ms; }
.stagger-item:nth-child(2) { animation-delay: 60ms; }
.stagger-item:nth-child(3) { animation-delay: 120ms; }

スケールアニメーション

scale(0) からアニメーションを始めないでください。scale(0.9) 以上から始め、不透明度の変化と組み合わせてください。

@keyframes scaleIn {
  from { opacity: 0; transform: scale(0.95); }
  to   { opacity: 1; transform: scale(1); }
}

押下時のフィードバック

押すことのできる要素には、すべて :active 時にわずかに縮小する動きをつけてください。

button:active {
  transform: scale(0.97);
}

割り込み可能性

インタラクティブな状態変化には、キーフレームアニメーションではなく CSS トランジションを使ってください。トランジションは途中で割り込めますが、キーフレームアニメーションは割り込めません。ホバー状態、トグル、ユーザーが素早く操作する可能性のある要素では、これが重要です。

ポップオーバーの起点

ポップオーバーの transform-origin を考慮し、中央からではなく、トリガー要素を起点に展開するようにしてください。ただし、モーダルは常に中央を起点にします。

ツールチップのホバー遅延

2 回目以降のホバーでは、ツールチップの遅延を省略してください。すでに 1 つ目のツールチップを待ったユーザーには、次のツールチップをすぐに表示します。

動きを抑える設定

@media (prefers-reduced-motion: reduce) {
  *, *::before, *::after {
    animation-duration: 0.01ms !important;
    transition-duration: 0.01ms !important;
  }
}

prefers-reduced-motion を尊重してください。アニメーションは減らします。ただし、重要なフィードバックを提供する不透明度や色のトランジションは完全になくさないでください。

ホバーの制御

タッチデバイスでホバー状態が解除されずに残らないよう、メディアクエリでホバーアニメーションを制御してください。

@media (hover: hover) and (pointer: fine) {
  .card:hover { transform: translateY(-2px); }
}

スプリング物理、ジェスチャー駆動アニメーション、複雑な振り付けについて詳しくは、references/animation-playbook.md を参照してください。

---

8. コンポーネントの作り込み

プリミティブ

アクセシブルでスタイルが設定されていない基盤として、Radix UI のプリミティブを使用してください。型安全なコンポーネントのバリアントには、CVA（class-variance-authority）を使用してください。

import { cva } from "class-variance-authority";

const buttonVariants = cva(
  "inline-flex items-center justify-center rounded-md font-medium transition-colors focus-visible:outline-none focus-visible:ring-2",
  {
    variants: {
      variant: {
        default: "bg-primary text-primary-foreground hover:bg-primary/90",
        destructive: "bg-destructive text-destructive-foreground hover:bg-destructive/90",
        outline: "border border-input hover:bg-accent hover:text-accent-foreground",
        ghost: "hover:bg-accent hover:text-accent-foreground",
      },
      size: {
        sm: "h-9 px-3 text-sm",
        default: "h-10 px-4 py-2",
        lg: "h-11 px-8 text-lg",
      },
    },
    defaultVariants: { variant: "default", size: "default" },
  }
);

ボタン

• 押したときに縮小する（:active に transform: scale(0.97) を指定）
• フォーカスリングを常に表示する（代替手段なしに outline: none を指定しない）
• 読み込み中はラベルをスピナーに置き換え、ボタンの寸法を維持する
• 無効状態では opacity: 0.5 と pointer-events: none を指定する

カード

• カードと内側の要素の角丸を同心円状にする
• 奥行きには境界線ではなく、重ねたシャドウを使用する
• ホバー状態では、さりげなく浮き上がらせる（translateY(-1px) とシャドウの強調）

ダイアログ／モーダル

• フォーカストラップ（キーボード操作で背後の要素に移動できないようにする）
• ESC キーまたはオーバーレイの外側をクリックして閉じる
• transform-origin: center を指定し、フェードと拡大のアニメーションで表示する
• aria-modal="true"、role="dialog"、aria-labelledby を指定する

フォーム

• 常にラベルを表示し、プレースホルダーだけの入力欄は使用しない
• スクリーンリーダー向けに、フィールドの近くに aria-live="polite" を指定したエラーメッセージを表示する
• プログレッシブディスクロージャーを採用し、必要な場合にのみ詳細フィールドを表示する
• バリデーションには React Hook Form と Zod を使用する

テーマ設定

すべてのコンポーネントの色には、shadcn の CSS 変数パターン（HSL 形式）を使用してください。Next.js App Router との互換性を確保するため、クライアントとのインタラクションがあるコンポーネントはサーバーコンポーネントでラップしてください。

コピーして使える実装を含むコンポーネントカタログ全体については、references/component-patterns.md を参照してください。

---

9. アクセシビリティの基本

セマンティック HTML を優先

ARIA を使う前に、<button>、<nav>、<main>、<header>、<footer>、<article>、<section> を使用してください。<button> を使えば、キーボード操作、フォーカス管理、スクリーンリーダー向けのセマンティクスを標準で利用できます。一方、<div onClick> では、そのどれも利用できません。

キーボード操作

• Tab／Shift+Tab：フォーカス可能な要素間を移動する
• Enter／Space：ボタンやリンクを実行する
• 矢印キー：リスト、メニュー、タブ、ラジオグループ内を移動する
• Escape：モーダル、ポップオーバー、ドロップダウンを閉じる
• Home／End：リストの先頭／末尾の項目に移動する

フォーカス管理

• すべてのインタラクティブ要素にフォーカスリングを表示する。代替手段なしに outline: none を指定してはいけません
• モーダル内にフォーカスを閉じ込める（Tab キーでモーダル内を巡回し、背後には移動しない）
• モーダルやポップオーバーを閉じたとき、トリガー要素にフォーカスを戻す
• マウスクリック時ではなく、キーボード操作時にのみリングを表示するには focus-visible を使用します。

:focus-visible {
  outline: 2px solid var(--ring);
  outline-offset: 2px;
}

ARIA 属性

• アイコンだけのボタンには aria-label を指定する：<button aria-label="Close menu">X</button>
• 見出しとセクションを関連付けるには aria-labelledby を指定する
• ヘルプテキストやエラーメッセージを入力欄に関連付けるには aria-describedby を指定する
• 動的なコンテンツの更新（トーストメッセージ、フォームエラー）には aria-live="polite" を指定する
• 装飾要素（テキストラベルの横にあるアイコン）には aria-hidden="true" を指定する
• 切り替え可能な要素（ドロップダウン、アコーディオン）には aria-expanded を指定する

色とコントラスト

• WCAG AA：通常のテキストは 4.5:1、大きなテキストは 3:1
• 色だけを唯一の識別手段にせず、アイコン、テキスト、パターンを併用する
• ライトモードとダークモードの両方でテストする

画像とメディア

• 意味のある画像には、内容を説明する alt テキストを指定する：alt="Dashboard showing 23% revenue growth"
• 装飾のみの画像には空の alt="" を指定する
• 動画には字幕、音声には文字起こしを用意する

ナビゲーション補助

• スキップリンク：最初にフォーカス可能な要素として配置し、フォーカスされるまで非表示にする：

<a href="#main-content" class="sr-only focus:not-sr-only">
  Skip to main content
</a>

• 見出しの階層：h1 から h6 まで順番に使用し、レベルを飛ばさない。1 ページにつき <h1> は 1 つにする。

タッチターゲット

• インタラクティブ領域は最低 44x44px
• 隣接するタッチターゲット間には最低 8px の間隔を確保
• 小さな視覚要素は、透明なパディングや疑似要素を使って拡張

テスト

• 自動：CI で axe-core を実行し、Lighthouse のアクセシビリティスコアは 90 以上
• 手動：キーボードのみでのナビゲーションを全体的にテスト
• スクリーンリーダー：VoiceOver（macOS）または NVDA（Windows）でテスト
• 表示：200% に拡大し、レイアウトが崩れたり重なったりしないことを確認

合否基準を含む監査ガイドの全文は references/accessibility-checklist.md を参照してください。

---

10. 納品前レビュー

UI の実装が完了したと判断する前に、次のチェックリストを確認してください。

タイポグラフィ

• フォントのスムージングを適用済み（-webkit-font-smoothing: antialiased）
• 見出しに text-wrap: balance を使用
• 動的な数値に font-variant-numeric: tabular-nums を使用

色

• すべての色をセマンティックトークン経由で指定し、コンポーネント内にハードコードされた hex 値がない
• 色のコントラストが WCAG AA に適合（通常のテキストは 4.5:1、大きなテキストは 3:1）
• ダークモードのコントラストを個別にテスト済み

空間

• 入れ子になった角丸要素に同心円状のボーダー半径を使用
• 間隔が一貫して 4px / 8px のスケールに沿っている
• インタラクティブ要素の最小ヒット領域が 44x44px
• 適切な場合はボーダーではなくシャドウを使用

モーション

• アニメーションの頻度が使用頻度に合っている（高頻度の操作にはアニメーションを使用しない）
• transition: all を一切使用せず、個別のプロパティのみを指定
• 複数の要素が表示される場合、開始アニメーションを分割し、時間差で表示
• prefers-reduced-motion を尊重

アクセシビリティ

• すべてのインタラクティブ要素をキーボードで操作可能
• キーボード操作時にフォーカスリングが見える（代替手段なしで outline: none を使用しない）
• ARIA よりもセマンティック HTML を優先
• 動的なコンテンツの更新に aria-live を設定

重大度評価と自動テスト用コマンドを含む、全 30 項目の拡張チェックリストは references/review-checklist.md を参照してください。