カードとサーフェスの階層
コンテンツカード、ワークスペースシェル、オーバーレイ、シャドウ、背景ぼかしの使用ルール。
コンテンツカードは平らのままです。外側のシェルがワークスペースのグループ化を示します。
標準のコンテンツカードは、外側の影を使用しません。
選択状態やステータスは、色と情報階層によって伝達されます。
カードマテリアルと階層の仕様
本文書では、Qokit のワークスペースインターフェースにおいて、シャドウ・透明度・グラデーション・背景ぼかしをどのような場面で使用するかを公開します。プラットフォーム拡張、Builder、CMS、Dashboard、Studio、Admin に適用されます。マーケティングページや生成サイトではより表現力を高められますが、効果は現在のテーマに帰属し、コンテンツの可読性を確保する必要があります。
基本原則
視覚効果は構造を表現するために使用し、各ブロックを装飾するために使用しません:
- コンテンツは背景色の違いで区別します。
- コンテナは透明度または控えめなグラデーションで帰属を表現します。
- オーバーレイはシャドウで階層を表現します。
- インタラクションは色とフォーカスリングで状態を表現します。
独立した不透明カードと入力フィールドは共通のレベル1シャドウを共有します。リスト、ネストされたサーフェス、透明なグループはフラットに保ちます。真のオーバーレイのみ明確なシャドウを使用します。
判断順序
マテリアル効果を追加する前に、まずサーフェスの役割を判断します:
- 独立した不透明カードまたは入力フィールドですか?共通のレベル1サーフェスまたはフィールドシャドウを使用します。
- リスト行、ネストされたカード、繰り返しオプション、透明なグループですか?フラットに保ちます。
- 複数の内部コンテンツカードを1つのワークスペースにまとめていますか?シェルを使用します。
- ページコンテンツを覆う、または現在の平面より上に表示されますか?オーバーレイシャドウを使用します。
- ドラッグ、ズーム、一時的なホバー状態ですか?一時的なシャドウを使用します。
- hover、選択、focus を表現するだけですか?共通の hover ロール、インタラクション背景色、フォーカスリングを使用します。
サーフェスの役割が本当に必要としない限り、シャドウ・透明度・グラデーション・ぼかしを同時に重ねないでください。
シーンマトリクス
| サーフェスの役割 | シャドウ | 透明度またはグラデーション | 背景ぼかし |
|---|---|---|---|
| 独立した不透明コンテンツカード、メトリクスカード | 共通レベル1軽シャドウ | 軽微な背景色の違いを許可 | なし |
| リスト行、ネストされたカード、透明なグループ、繰り返しオプション | なし | 軽微な背景色の違いを許可 | なし |
| ページ内グループシェル | なし | 推奨 | 通常不要 |
| サイドバーまたは常駐ワークスペースシェル | 軽量 | 推奨 | 背後に可視コンテンツがある場合に許可 |
| Dialog、Popover、Dropdown、コンテキストメニュー | 明確なオーバーレイシャドウ | 背景は可読性を確保するため十分に不透明であること | 許可 |
| ドラッグプレビュー、ズーム状態、ホバープレビュー | 一時的に強め | 任意 | 通常不要 |
| Hover | レベル1シャドウを維持またはわずかに強化 | 背景を変更可能 | 変更なし |
| 選択またはアクティブ状態 | なし | アクセントカラー背景または控えめなグラデーション | 変更なし |
| 入力フィールド、検索フィールド | 極軽フィールドシャドウ | コントロールサーフェス色を使用 | 通常不要 |
| 独立プライマリアクション、独立カプセル、セグメントコントロール外殻 | 極軽コントロールシャドウ | コントロールサーフェス色を使用 | 通常不要 |
| ツールバーと透明な内部コントロール | なし | コントロールサーフェス色または透明を使用 | 通常不要 |
| マーケティングページまたは生成サイトのビジュアルカード | テーマにより決定 | 許可 | 控えめに使用 |
コンポーネントマッピング
<Card>はデフォルトでlayer="content"を使用します:共通レベル1軽シャドウ、ボーダーなし、デフォルト20px角丸。muted、ネスト、リスト、透明バリアントはフラットに保ちます。<Card layer="shell">:ページ内ではグループ化のみを担当し、透明または軽グラデーションサーフェスを使用しフラットに保ちます。常駐ワークスペースシェルは所属モードごとに階層を提供します。<Card shape="pill">:コンパクトな1行カード用で、角丸は楕円カプセル形です。SidebarNavigation:独立したワークスペースシェルで、明確なグラデーション、透明度、ぼかし、軽シャドウを保持します。- Studio の
PromptPanelをワークスペースコンテナとして使用する場合:--workspace-shell-shadowを使用します。 DialogPanel、ドロップダウンメニュー、Popover、コンテキストメニュー、コンセプトブラウザ:オーバーレイシャドウを使用します。- Builder キャンバス、デバイスプレビュー、生成サイトプレビュー、ドラッグプレビュー、ズーム状態:独立したプレビュー平面または一時的なインタラクションレイヤーを表すため、専用シャドウを保持できます。
コンテンツカードを何重にも浮かせないでください。外側のグループ化が本当に必要な場合、それはフラットなシェルでなければなりません。真のオーバーレイを除き、同一の DOM 祖先チェーンには通常のコンテンツまたはコントロールシャドウを1つまでとします。
デザイン変数(トークン)の使用
共通トークンを優先し、効果をハードコードしないでください:
- コンテンツカードシャドウ:
--card-shadow: var(--qk-shadow-surface) - コンテンツカード hover シャドウ:
--card-shadow-hover: var(--qk-shadow-surface-hover) - フィールドシャドウ:
--input-shadow: var(--qk-shadow-field) - フィールドアクティブシャドウ:
--input-state-shadow: var(--qk-shadow-field-active) - コントロールシャドウ:
--qk-shadow-control/--qk-shadow-control-hover - プライマリアクションコントロールシャドウ:
--qk-shadow-control-accent/--qk-shadow-control-accent-hover - コンテンツカードぼかし:
--card-backdrop-filter: none - シェルサーフェス:
--card-shell-surface - シェルぼかし:
--card-shell-backdrop-filter - ワークスペースシェルシャドウ:
--workspace-shell-shadow - Dialog サーフェス:
--dialog-surface、控えめなテーマグラデーションを提供 - Dialog ぼかし:
--dialog-backdrop-filter - Dialog オーバーレイシャドウ:
--dialog-shadow - Dialog 角丸:
--card-radiusを再利用 - キーボードフォーカス:
--focus-ring - オーバーレイシャドウ:既存の Dialog、Dropdown、Menu またはページレベルオーバーレイトークンを使用
通常のコンテンツカードとワークスペースパネルには、強めの共通 --shadow トークンを使用しないでください。
グローバルシャドウは「短いオフセット、低透明度、配置階層に応じて段階的に増加」する静かなスケールを採用します。通常の Card、フィールド、コントロールはルーティング内で共通シャドウを濃くしたり拡大したりしないでください。Popover と Dialog は、暗い灰色の霧を重ねるのではなく、より大きなオフセットとぼかし範囲でページからの浮遊を表現します。
インタラクションルール
ホバー
- コンテンツカードは
--qk-shadow-surface-hover以上の階層に持ち上げないでください。 translateYでコンテンツカードを持ち上げないでください。- 軽微な背景変化または明確なコントロールフィードバックを使用してください。
- 形状を変更せず、角丸の不整合やシャドウのクリッピングを避けてください。
選択とアクティブ
- アクセントカラーサーフェス、アイコン状態、セマンティック状態、または控えめなグラデーションを使用してください。
- シャドウのみで状態を表現しないでください。
キーボードフォーカス
- 共通の focus-visible ルールまたは
--focus-ringを使用してください。 - 共通カードシャドウでフォーカスヒントを代替しないでください。
- ライトテーマとダークテーマの両方で明確に表示される必要があります。
ドラッグとズーム
- レイヤーが移動中またはリサイズ中の場合のみ、強めのシャドウを許可します。
- インタラクション終了後、一時的なシャドウを必ず除去してください。
- オーバーフローコンテナで移動レイヤーのフィードバック効果をクリッピングしないでください。
透明度と背景ぼかし
透明度は外側サーフェスとワークスペースの帰属関係を表現するために使用します。背景ぼかしは、サーフェスの背後に実際に可視コンテンツ、色、または画像がある場合にのみ意味を持ちます。
- 無地背景にぼかしを使用しないでください。レンダリングコストが増加するだけで、階層を表現できません。
- 背後の背景に関わらず、テキスト、アイコン、コントロールは明確に可読でなければなりません。
- ブラウザが背景ぼかしをサポートしていない場合、不透明または可読なフォールバック背景が必要です。
- 高密度ワークスペースインターフェースのぼかし強度は控えめにしてください。
- ライトテーマとダークテーマの両方で必ず検証してください。
シャドウ保持を許可する例外
- ワークスペースサイドバーシェル
- Dialog、Popover、Dropdown、メニュー、モーダルパネル
- Studio コンセプトブラウザと確認オーバーレイ
- Builder キャンバス、デバイスフレーム、生成サイトプレビュー平面
- ドラッグプレビュー、ズームフィードバック、一時的なホバーツール
- 共通ボタントークンでシャドウが定義されているプライマリアクションボタン
- 現在のテーマが制御するマーケティングページと生成サイトのビジュアル要素
これらの例外は、広範なセレクタや共通トークンを通じて通常のコンテンツカードに影響を与えてはなりません。
レビューチェックリスト
- 独立した不透明コンテンツカードと入力フィールドは共通レベル1軽シャドウロールのみ使用。
- 独立プライマリアクション、独立カプセル、セグメントコントロール外殻は共通極軽コントロールシャドウのみ使用。
- ページグループ、リスト行、ネストされたカード、透明なグループ、繰り返し Tab/Pill、ツールバー、複合コントロール内部項目はフラットに保つ。
- ツールバー内の検索、フィルタ、ソート、ビュー、インラインプライマリアクションはフラットに保つ。通常入力フィールドの軽シャドウはツールバーに漏れない(キーボードフォーカスリングを除く)。
- Segmented がシャドウ付きのカード、ダイアログ、ツールバー内部にある場合、外殻と選択項目はともにフラットに保つ。マウスクリックでキーボードフォーカスリングを表示しない。
- 真のオーバーレイを除き、同一祖先チェーンに複数の通常シャドウを重ねない。
- hover でコンテンツカードが垂直方向に移動しない。
- ネストされたコンテンツカードを削除済み、または外側を明示的にシェルとして定義済み。
- 真のシェルのみ
--workspace-shell-shadowを使用。 - 真のオーバーレイと一時的なインタラクションレイヤーのみ強めのシャドウを使用。
- 背景ぼかしの背後に可視コンテンツが存在し、可読なフォールバック背景がある。
- focus-visible はフォーカスリングを使用。
- ライトテーマとダークテーマの両方で十分なコントラストを維持。
- 角丸サーフェスが hover、focus、ドラッグ、オーバーレイフィードバックをクリッピングしない。
- デスクトップとモバイル幅で新たな横方向オーバーフローが発生しない。
npm run ui:check-card-surfaces --workspace @qokit-ai/webチェックに合格。