Radix Themes デザインシステム.

Radix Themes デザインシステムのビジュアルテーマと雰囲気

ムードボードではなく、実際に機能するインターフェース

Radix Themes は、人が読み、判断し、情報を入力し、未完了の作業に戻ってくるようなプロダクトにとって有用なリファレンスです。その視覚的な個性は、計算されたスペーシング、抑制された背景層、明確なタイプヒエラルキー、そして再現性のあるコンポーネントの状態から生まれます。このガイドは、プロジェクトのワークスペース、アカウント領域、設定画面、データレビューのフローを構築するために使ってください。目指すのは、実際のコンテンツを伴う一貫した作業画面であり、タスクから切り離されて並べられた見栄えのよいコンポーネントの寄せ集めではありません。

適切な出発点を選ぶ

React アプリケーションでは、実際の Radix Themes パッケージから始め、独自の置き換えを書く前にそのコンポーネントを使ってください。別のスタックでビジュアルコンセプトを検討する場合は、これらの原則をリファレンスとして用い、その結果をこのシステムに着想を得たものとして説明してください。Radix Themes と Radix Primitives は異なる出発点です。このガイドが扱うのは、スタイルが適用された Themes ライブラリです。OpenDesign のガイドは、任意の HTML モックアップをネイティブな Radix 実装に変えるものではありません。

具体的なタスクを中心に構築する

1. 最初の画面には、プロジェクトの作成やアカウント設定の保存など、主要なアクションを1つ選びます。
2. その判断に必要な情報は、アクションの前に配置します。
3. ナビゲーション、オブジェクトのメタデータ、編集可能なフィールド、フィードバックは、視覚的に明確に区別してください。
4. 設計中は、現実的な長いタイトル、混在したステータス値、空の状態を使ってください。
5. 短いプレースホルダーラベル3つでしか成立しない画面は、使えるシステムを確立したことにはなりません。

トーンとコンテンツ

短く説明的なラベル、具体的な動詞、直接的な説明を使います。ボタンは次に何が起きるかを示すべきです（変更を保存、メンバーを招待、プロジェクトを作成など）。見出しはセクションの主題のために取っておき、小さなコントロールの一つひとつにマーケティングのスローガンを与えるのは避けます。操作が失敗したときは、その人が修正できる点を説明し、作業内容を保持します。これらはリファレンスを適用するための OpenDesign の編集上の推奨事項であり、Radix が提供する追加の API ではありません。

Radix Themes デザインシステムのカラーパレットと役割

ブランドカラーと意味を切り離す

画面をハードコードせず Theme を使う

公式の Theme 設定は次のものを公開しています accentColor および grayColor。ルートでこれらを選択すると、コンポーネントが同じ決定を共有できます。カスタムコンポーネントでは、スクリーンショットから色をコピーするのではなく、現在のテーマの CSS 変数を参照してください。以下のトークンリファレンスには、実用的な最小限のサブセットを掲載しています。トークンは設定されたテーマ内での役割であり、ライトモード、ダークモード、そしてすべてのアクセントの選択にわたって単一の 16 進値が同じままであることを保証するものではありません。

サーフェスとボーダーの階層

まずは落ち着いたページ背景から始めます。カードや編集可能なパネルに独自のサーフェスを与えるのは、関連する作業をひとまとめにする場合だけにします。同じリストに属する行にはセパレーターを使います。すべての項目にボーダー、シャドウ、色付きの背景、バッジを一度に付けるのは避けてください。設定画面では、区切り線で分けられた単一のパネルのほうが、6 枚の浮いたカードよりもたいてい分かりやすくなります。低コントラストでも階層は見えるようにしつつ、重要なテキストを薄くしないようにします。

ライトとダークの外観

ネイティブコンポーネントには公式の外観設定を使い、同じ内容で両方の外観を確認します。色を無理に反転したり、ライトモードのシャドウを使い回したりしてダーク画面を作らないでください。オーバーレイ、非アクティブなフィールド、セパレーター、選択された行、アクセント上のテキストを個別に確認します。このページのインタラクティブな作例は、少数のテーマの選択肢を示したものです。完全なライブラリとそのネイティブな挙動については、公式のプレイグラウンドを参照してください。

コントラストと冗長な手がかり

アクセントや背景層（surface）を変更した後は、最終的な前景／背景の組み合わせを必ず確認してください。Pending、Complete、Failed などのステータスは、色だけでなくテキストと組み合わせて示します。選択済みの項目には、チェックマークなど視覚的に区別できる手がかりを付けます。アクセシブルなコンポーネントライブラリを使っていれば、あらゆるコンテンツやテーマの組み合わせがアクセシブルになるわけではありません。ラベル、ネストの構造、独自の CSS、情報の並び順は、画面全体を使えるかどうかに影響します。

Radix Themes デザインシステムのタイポグラフィルール

意図的に設計された読解の階層

画面にはっきりとしたタイトルを1つ付け、そのうえでセクション見出し、本文、フィールドラベル、補助的なメタデータを区別します。これらの関係を説明できる最小限のサイズ数で構成します。情報密度の高いプロダクト画面では、大きな表示用書体よりも読みやすいラベルのほうが重要です。説明用の段落は、それが説明するコントロールの近くに置き、入力に値が入った後もラベルは表示したままにします。プレースホルダーのテキストはヒントであり、フィールドラベルの代わりにはなりません。

タイプスケールとウェイト

Radix は、フォントサイズ・行の高さ・字間を組み合わせた9段階のタイポグラフィスケールを規定しています。このページの参照表は、ベーススケールにおけるそれらの値をそのまま示したものです。ステップを選ぶときは、無関係な行の高さを混ぜるのではなく、1つのまとまった組み合わせとして選びます。本文には標準のウェイトを、見出しや選択中のラベルにはより強いウェイトを使います。すべてを太字にすると階層が消え、二次的なテキストをすべて薄くすると画面が読みにくくなります。

フォントの選択とフォールバック

Radix Themes はデフォルトでシステムフォントスタックを使用します。特定のブランド書体よりも移植性を重視する場合はそのスタックを維持し、ライセンス済みのフォントを使いたい場合は規定のカスタマイズ機構を通じて設定します。周辺の OpenDesign サイトは Albert Sans を使用していますが、だからといって Albert Sans が Radix の公式フォントになるわけではありません。多言語アプリケーションでは、中国語、日本語、韓国語、および長い欧州言語のラベルを、実際のフォールバックフォントで検証してください。

数値、コード、折り返し

数値の列は揃えて、値を縦方向に比較できるようにします。コード、識別子、トークンなど、文字の区切りが重要なものには等幅フォントを用います。タイトルや説明は自然に折り返せるようにし、カードの高さを保つためだけに重要な指示を切り詰めないようにします。ID のように本当に区切りのない文字列には、制御された折り返しやコピー操作を用意します。モバイルでは、レイアウトが変わっても意味がすべて伝わるようにします。

コンテンツの長さもデザインの一部

コンポーネントを再利用可能と呼ぶ前に、長いプロジェクト名、2行にわたるメンバーの役割、翻訳されたアクションでテストする。すべてのボタンに固定幅を与えるのではなく、可能な限りボタンを伸縮させる。本文の段落は読みやすい行長に保ち、ユーザーが並行する事実を比較する必要がある場合はリストや表を使う。ページの見栄えをデザイン的にするためだけに、説明文を多数の小さな装飾カードに分割しない。

Radix Themes デザインシステムのコンポーネント スタイリングと状態

ボタンとアクションの階層

1つのアクショングループ内では、主要な意思決定を特定し、最も強い視覚的扱いを与える。副次的なアクションは、同等に競合することなく、見つけやすい状態を保つ。破壊的なアクションは通常の確認から切り離す。送信中は重複操作を防ぎ、進行状況を可視化する。完了後は実際の結果を表示する。無効化されたボタンには、その理由がフォームから明らかでない場合、近くに理解できる理由を添える。

入力欄とフォーム

• 各入力欄の上または横に、常時表示されるラベルを配置する。
• ヘルプテキストは該当するフィールドの近くに置き、検証メッセージは汎用のバナーだけに表示するのではなく、そのフィールドに紐付ける。
• 検証に失敗したときは、入力済みの値を保持する。
• 関連するフィールドは、意味のあるセクション見出しの下にまとめる。
• 適切な input type と autocomplete 値を用いることで、ブラウザと支援ツールがユーザーのタスク完了を支援できるようにする。

カード、リスト、表

意味のある要約とアクションを伴う自己完結したオブジェクトにはカードを使う。類似したレコードが連なる場合はリストを、レコード間で属性を比較する必要がある場合は表を使う。装飾的なチャートの断片ではなく、所有者、更新日時、ステータスといった実際のフィールドを表示する。カードは、ネストされたリンクやボタンと競合する形でクリック可能にしてはならない。明確なリンク先を選び、通常のキーボード操作を維持する。

ナビゲーションと選択

グローバルナビゲーションは、ページレベルのタブやローカルフィルターと分離しておく。現在の遷移先は、アクセントカラーだけに頼らず識別可能であるべき。ナビゲーションにはリンクを、その場での変更にはボタンを使う。タブパターンを実装する場合は、そのキーボード操作を含める。そうでなければ、明確にラベル付けされた通常のボタンのグループを使う。操作できないのであれば、視覚的にスタイルを施した span の行をインタラクティブに見せてはならない。

メニュー、ダイアログ、オーバーレイ

React 製品を実装する際は、複雑な挙動にはネイティブライブラリのコンポーネントを使う。ダイアログにはタイトル、明確な閉じる手段、適切なフォーカス管理、そして起動元のコントロールへのフォーカス復帰が必要である。そうした挙動を欠いたまま、絶対配置したカードでモーダルを組み立てるのは避ける。ダイアログは単一の判断に集中させる。長い編集ワークフローは、ますます混み合うオーバーレイではなく、専用のページにする価値があることが多い。

読み込み中、空、エラー、成功

• 各状態は、同一の実際のタスクに照らして設計する。
• 空のプロジェクト一覧では、最初のプロジェクトの作成方法を説明する必要がある。
• 読み込み状態では、表示が大きく飛ぶのを避けられるだけの構造を保つ必要がある。
• エラーでは意味のある次のアクションを提示し、完了済みの作業を消してはならない。
• 成功メッセージでは、何が変わったのかを明示する必要がある。
• このページの静的な見本ボタンは外観を示すものであり、それらの状態における本番の挙動を証明するものではない。

Radix Themes デザインシステムのレイアウト・スペーシング・密度

共有のスペーシングスケールを使う

文書化されたスペーシングスケールには 9 つの基本ステップがある: 4、8、12、16、24、32、40、48、64 ピクセル。密接に関連するコントロールの内部には小さなステップを、独立したセクションの間には大きなステップを使う。見出しとその内容の間には、視覚的な関係を保つ。画面を埋めるためだけに余白を均等に配分してはならない。近接性によって、どの情報が同じまとまりに属するかを伝えるべきである。

密度はタスクに従う

リソースディレクトリには、比較できるだけの十分な件数が表示される必要がある。設定フォームには、ラベル、ヘルプ、エラーのための余裕が必要である。閲覧ページには、安定した行長と見通しのよいアウトラインが必要である。どこでも同じカードサイズを当てはめるのではなく、タスクに合わせて密度を選ぶ。Radix には、関連する寸法をまとめて調整するスケーリング設定もある。コンパクトなスケールを製品の既定値にする前に、その結果としての可読性とターゲットサイズを評価すること。

グリッドとコンテナの挙動

まずページコンテナを用意し、次に主要なコンテンツと補助的なレールを定義する。外側のキャンバスが広くても、長いテキストは読みやすい行幅のカラムに保つ。幅が狭くなったら、補助コンテンツをメインコンテンツの下へ移すか、長いレールをアクセシブルなローカルナビゲーションコントロールに変換する。モバイルの流れとキーボードの順序が、デスクトップのグリッド配置に依存せずに筋が通るよう、ソース順を維持する。

ネストしたカードより行を優先する

コンパクトなトークンリファレンスでは、名前・値・用途を1行にまとめて一覧できるようにします。カタログでは、タイトル・カテゴリ・説明・遷移先をひとまとまりに保ちます。入れ子のボックスを繰り返すと視覚的なノイズが増し、本来コンテンツに割くべき幅を奪ってしまいます。関連する行の間には細い区切り線を優先し、囲みパネルはライブプレビューやコード例など、文脈が本当に切り替わる場合にのみ使います。

重要なコンテンツを見える状態に保つ

ページを短く見せるためだけに、詳細なガイドを短い要約に縮めてしまわないでください。目次と力強い小見出しを設け、読者が該当箇所から読み始められるようにします。フィルターやアコーディオンで表示が変わる場合は、空の状態と選択状態が明確にわかるようにします。本当のインタラクション上の必要性がない限り、内側だけが独立してスクロールするリストは避けてください。長いリソース集では、通常のページスクロールのほうがたいてい扱いやすくなります。

Radix Themes デザインシステム 角丸・奥行き・モーション

角丸は関係性である

Radix には名前付きの角丸設定と、コンテキストに応じたコンポーネントの挙動があります。すべての要素に同じ任意の角丸を割り当てるのではなく、テーマレベルで設定を選びます。ボタン、チェックボックス、大きなパネルでは構造上の役割が異なります。それらの役割を消してしまわないよう、形は関連性を保ちます。自作コンポーネントで角丸トークンを使う場合は、同じシステムに属すると判断する前に、ネイティブのボタンや入力欄と並べて確認してください。

エレベーションは階層を説明する

奥行きは、オーバーレイをその下のページから、あるいはインタラクティブなパネルを静かなキャンバスから区別するために使います。Radix は6段階のシャドウスケールを提供しています。シャドウの段数をカードの装飾的な人気ランキングのように扱わないでください。密度の高いカタログなら、ボーダーだけで十分機能することもよくあります。シャドウはライトとダークの両方の外観で確認してください。ライトモードのぼかしをダークな界面表面にそのまま持ち込むと、見えなくなったり、誤った奥行きを連想させるハローが生じたりします。

モーションは変化を明確にすべき

選択、開閉、進捗、関連する状態間の移動を説明するために、短いトランジションを使います。コンテンツを登場アニメーションの後ろに遅らせないでください。作業に集中する画面では、背景の継続的な動きは避けます。モーションを減らす設定を尊重し、トランジションを外しても最終状態が読み取れるようにします。独自実装におけるタイミングの選択はアプリケーション側の判断です。このガイドは、確認されていない公式の Radix のデュレーショントークンを勝手に作ることはしません。

装飾のないインタラクション

ホバー時の処理は、その要素が操作可能であることを裏付けるものであるべきです。フォーカス時の処理は、隣接する界面表面に対してはっきりと見える状態を保ちます。読んでいる最中に情報が動いてしまわないよう、密度の高い行全体をホバーで大きく動かさないでください。タッチスクリーンでは、必須の操作がホバーなしでも利用できるようにします。効果が成功と言えるのは、アニメーション自体に注意を引くときではなく、ユーザーがコントロールを理解する助けになるときです。

Radix Themes デザインシステム やるべきこと・避けるべきこと

推奨：1つの完全な画面を確立する

実際のナビゲーション、意味のあるコンテンツ、主要なアクション、そして少なくとも1つの例外状態を備えた画面を構築します。何十もの再利用可能なコンポーネントを抽出する前に、その画面をレビューしてください。アクセント、密度、タイポグラフィのステップ、空の状態の文言など、意図的な選択を記録します。これにより、コーディングエージェントが従うべき具体的な契約が生まれ、その後のイテレーションで逸脱を発見しやすくなります。

すること: ネイティブとカスタムの動作を一貫させる

ライブラリがすでにサポートしている動作には、その既存のコンポーネントを優先して使用します。カスタムラッパーではテーマ変数を使用し、それらのラッパーを両方の外観で確認してください。スタイルを適用する際も、ラベルとセマンティックHTMLを保持します。プロジェクトに既存のデザインシステムがある場合は、それを置き換える前にこのリファレンスと比較してください。制御されていない第2のテーマレイヤーは、取り除く以上に多くの不整合を生む可能性があります。

しないこと: 色を差し替えてブランドを再現すること

アクセントを変えるだけでは、一貫したインターフェースは確立できません。スペーシング、タイプ、コンテンツの階層、インタラクションパターン、レスポンシブの選択が、視覚的アイデンティティの大部分を担っています。モックアップがライブラリに似ているというだけの理由で、公式の統合であると主張しないでください。他の製品の商標、独自の資産、ビジネス上の主張を、新しい製品画面にコピーすることは避けてください。

しないこと: 見栄えのよいスクリーンショットのために意味を犠牲にすること

Radix Themes デザインシステムのレスポンシブでアクセシブルな動作

縮小する前に構造を適応させる

画面が狭くなったら、列を減らし、主要なアクションへの経路を短縮し、二次的な情報を通常の読み取りフローに移してください。デスクトップのダッシュボードを1枚の画像として縮小し、それをモバイルレイアウトと呼んではいけません。ラップ、スタッキング、適切なテーブル処理を使って、同じコンテンツを利用可能に保ってください。説明的なリンクテキストを保持し、周囲のデスクトップカードの外でもリンク先が意味をなすようにしてください。

文書化されたブレークポイントを意図的に使用する

公式のブレークポイント名は initial、xs、sm、md、lg、xl です。それぞれの最小幅は 0、520、768、1024、1280、1640 ピクセルです。これらはすべての段階で必須のレイアウト変更ではなく、利用可能なツールとして扱ってください。コンテンツが異なる配置を必要とするときにブレークポイントを追加します。ブレークポイントそのものだけでなく、名前付きブレークポイント間の幅もテストして、脆弱な中間レイアウトを見つけてください。

キーボードとフォーカス

• 意味のあるすべてのアクションには、キーボードによる操作経路が必要です。
• 視認できるフォーカス状態はホバーとは明確に区別し、コンテナが内容をクリップする場合でも見える状態を保つ。
• コントロールの順序を予測不能に変えてしまう正の tabindex 値は避ける。
• フィルターで結果が変わった後もフォーカスはそのコントロールに保ち、簡潔な結果件数を提示する。
• モーダルを閉じた後は、ドキュメントの先頭に置き去りにせず、妥当な場所にフォーカスを戻す。

ラベル、ターゲット、支援テキスト

アイコンのみのアクションには、アイコンの形状ではなくアクションを表すアクセシブルな名前を付ける。視覚的なアイコンが小さくても、タッチターゲットは快適なサイズにする。装飾的なアイコンはアクセシビリティツリーから除外する。保存された変更や検索結果の件数といった更新は、無関係なコンテンツを繰り返し読み上げることなく提示する。状態がアイコンとテキストの両方を用いる場合は、スクリーンリーダーに同じメッセージを二度伝えないようにする。

実際のコンテンツで検証する

• デスクトップ、タブレット、幅の狭いスマートフォンで確認する。
• テキストの伸長、画像の欠落、空のリスト、長く途切れない識別子を含める。
• ページを、モーションを減らす設定とキーボード操作の両方でテストする。
• 大幅な色の変更を行った後は、両方の外観を確認する。
• 自動チェックは構造的な問題を見つけられるが、階層、コンテンツ密度、全体的な視覚的性質が意図する製品要件を満たしているかどうかまでは判断できない。

Radix Themes デザインシステム AI エージェント向けプロンプトガイドと実装

プロジェクトのコンテキストを準備する

1. コーディングエージェントに、何を構築するのか、誰が使うのか、主要なアクションは何か、そして現在のデザインを定義している既存ファイルはどれかを伝える。
2. 特定されていないスクリーンショットを模倣させるのではなく、このガイドを参照資料として添付する。
3. React を使用する場合は、ネイティブの Radix Themes コンポーネントを優先すべきだと明記する。
4. 別のスタックを使用する場合は、明示的にラベル付けした解釈を求め、それが要求する追加のインタラクション作業を確認する。

最初の一巡を具体的に指定する

実際のコンテンツと少数の状態を備えた、動作する画面を1つ依頼する。ナビゲーション、フィールド、オブジェクトのメタデータ、主要アクションで期待される結果を指定する。キーボードフォーカス、空の状態、バリデーション、狭いレイアウトを依頼に含める。既存のヘッダー、本番データのコントラクト、以前に承認されたコンテンツブロックなど、維持すべき制約を明記する。

本当の問題を見つけられる順序でレビューする

1. まず、その画面が意図したタスクを支援しているかを確認する。
2. 次に、情報の階層、余白、タイポグラフィ、色を、選択した参照資料と比較する。
3. 最後に、インタラクティブな状態とレスポンシブレイアウトをテストする。
4. ページがコンパイルできるから、あるいはスクリーンショットが整って見えるからという理由だけで、視覚的な変更を受け入れてはならない。
5. 視覚的な調整の後も、より長いコンテンツ、エラー、繰り返しのアクションが引き続き機能することを確認する。

明示的な判断によって拡張する

最初の画面が動作したら、テーマ設定、書体の役割、スペーシングの選択、そして繰り返すべきコンポーネントパターンを記録します。承認済みの内容を無断で書き換えることなく、それらの決定を次の画面に適用するようエージェントに依頼します。新しい画面で別のパターンが必要になった場合は、その理由を記録し、以前の画面との一貫性を確認します。表面的に似ているだけのページを大量に生成するのではなく、検証済みの挙動を起点に拡張していきます。

既知のスコープと出典の境界