Button コンポーネント仕様
Button と IconButton のセマンティクス、サイズ、形状、状態、アクセシビリティに関する仕様。
AIButton は、ボタンのサイズと意味論を再利用しながら、特徴的で明確な Qokit AI 状態を追加します。
AI ボタンを選択して、作業中の状態をプレビューしてください。
Qokit ボタンコンポーネント仕様
本文書では、Qokit プラットフォーム、Builder、CMS、Dashboard、Admin、マーケティングページ、および生成サイトにおけるボタンの使用ルールを定義します。ボタンのコンポーネント、セマンティクス、形状、サイズ、アイコン、状態、アクセシビリティを統一し、各ルートでローカル CSS によりボタンを再設計することを避けることを目的とします。
1. コアモデル
ボタンは「楕円形、円形」だけで分類されるものではなく、5つの独立した次元で構成されます:
Component type × semantic priority × size × shape × spatial elevation
Button / IconButton × primary / secondary / ghost / danger × sm / md / lg × pill / rounded × flat / raised / floating- コンポーネントタイプは、ボタンに表示テキストがあるかどうか、および正方形のクリック領域を維持する必要があるかどうかを決定します。
- セマンティック優先度は、現在のタスクにおけるボタンの優先度と色を決定します。
- サイズは、安定した高さ、テキストのフォントサイズ、タッチ領域を決定します。
- 形状は角丸のみを決定し、優先度やビジネスセマンティクスを表しません。
- 空間階層は、コントロールが現在の平面から浮いているかどうかのみを示し、操作のセマンティクスは変更しません。
新しいクラス名を組み合わせて新しいボタンタイプを作成しないでください。まず共有コンポーネントの既存プロパティから選択してください。
2. コンポーネント選択
Button
表示テキストを含むすべての操作に使用します。対象:
- テキストのみのボタン;
- テキストの前にアイコンがあるボタン;
- テキストの後にアイコンがあるボタン;
- ボタンとして表示されるページリンク。
プラットフォームの Button は、デフォルトで全角丸の pill を使用し、視覚的に楕円形になります。ボタンに表示テキストが含まれる場合、円形アイコンボタンに変更すべきではありません。
variant はシャドウと切り離されています:primary はデフォルトで raised を使用し、secondary、danger、ghost はデフォルトで flat を使用します。リスト行、カード内部、ツールバー、複合カプセル内部の操作は flat でなければなりません。独立したメイン操作には raised を使用でき、コンテンツの上に浮く操作のみ floating を使用します。独立したカプセルまたはセグメントコントロールは、最外層でのみ1回シャドウを描画し、ルートはローカル CSS で共有階層を書き換えてはなりません。
import { Button } from '@qokit/components/ui';
<Button type="button" variant="primary">
保存
</Button>
<Button
leadingIcon={<SaveIcon aria-hidden="true" />}
type="button"
variant="primary"
>
保存
</Button>
<Button
href="/projects"
trailingIcon={<ArrowRightIcon aria-hidden="true" />}
variant="secondary"
>
查看项目
</Button>IconButton
アイコンのみで表示テキストがないコンパクトなツール操作に使用します。例:閉じる、その他、戻る、メニュー切り替え、削除。
IconButton は各サイズで等幅・等高さ・全角丸を維持するため、視覚的には円形ボタンです。デフォルトで ghost を使用し、型レベルで aria-label を強制します。
import { IconButton } from '@qokit/components/ui';
<IconButton aria-label="关闭" tooltip="关闭" type="button">
<CloseIcon aria-hidden="true" />
</IconButton>ルール:
- アイコン自体は
aria-hidden="true"を使用し、ボタン名はaria-labelで提供します。 - 馴染みのないアイコンや意味が不明確な可能性のあるアイコンは、共有
Tooltipも併用すべきです。tooltip はaria-labelの代替にはなりません。 - DOM の
title属性を製品ヒントとして使用しないでください。また、tooltipを設定しつつ Tooltip を手動でラップすることも避けてください。 - Tooltip は読み取り専用の情報レイヤーであり、楕円ボタンではありません。共有のコンパクト Tooltip 角丸を使用し、
pill、ボタンの hover、pressed、focus の視覚効果を再利用してはなりません。 - 空テキスト、非表示テキスト、または固定幅の
ButtonでIconButtonを模擬しないでください。 IconButtonにshapeを設定しないでください。円形はそのコンポーネント契約です。
Button を使用すべきでない場面
- タブには Tabs/PillTabs/Segmented などの対応コンポーネントを使用します。
- メニュー項目には Menu/ActionMenu の対応コンポーネントを使用します。
- ステータス、ラベル、フィルタ結果には Pill またはステータスコンポーネントを使用します。
- 通常のテキストナビゲーションにはセマンティックリンクを使用します。ボタンレベルの視覚的強調が必要な場合のみ、
href付きのButtonを使用します。
3. セマンティック階層 variant
| Variant | 意味 | 典型的な場面 | 使用制限 |
|---|---|---|---|
primary | 現在の領域のメイン操作 | 保存、公開、作成、今すぐ試す | 1つのタスク領域には通常1つのメイン操作のみ |
secondary | 明確だが二次的な操作 | プレビュー、キャンセル、戻る、インポート | メイン操作と視覚的注意を競合させてはならない |
ghost | 低強調、コンテキストツール操作 | 閉じる、その他、ツールバー操作、ライトな戻る | デフォルトで透明、唯一の重要な CTA としては使用不可 |
danger | 削除または明らかな破壊を伴う操作 | 項目削除、コンテンツ削除、データ消去 | 破壊的セマンティクスのみ表現、通常の強調色としては使用しない |
variant はセマンティクスと視覚階層を表現するものであり、形状ではありません。例えば ghost はテキスト付きの楕円ボタンでも、円形の IconButton でも構いません。
選択順序:
- 現在のタスクで唯一最も重要な次のステップを見つけ、それを
primaryに設定します。 - 明確に表示すべき補助操作には
secondaryを使用します。 - ツールバーまたはコンテキスト内の低強調操作には
ghostを使用します。 - 実際の破壊的操作にのみ
dangerを使用し、既存の確認フローを踏襲します。
「どの色が見栄えが良いか」で variant を選択しないでください。
4. サイズ size
| Size | 高さ/直径 | テキストフォントサイズ | 推奨場面 |
|---|---|---|---|
sm | 40px | 14px | トップナビゲーション、コンパクトツールバー、密集ワークスペース |
md | 44px | 15px | デフォルトフォーム、CMS、ダイアログ、通常操作 |
lg | 48px | 16px | マーケティングページのメイン CTA、より強いタッチ性が必要なメイン操作 |
デフォルトサイズは md です。
- 同じボタングループでは同じサイズを使用します。
- コンパクトコントロールは 40px 未満にしてはなりません。モバイルのメイン操作は少なくとも 44px を優先します。
Buttonの高さとIconButtonの直径は同じサイズトークンを使用するため、同じツールバー内で整列できます。IconButtonの表示アイコンサイズは 18px に統一します。Buttonのテキストフォントサイズは size に対応する共有トークンで決定され、Header、Dialog、その他の親コンテナのフォントサイズを継承しません。- ルート CSS はボタンの配置、間隔、必要な幅を制御できますが、共有ボタンの高さやフォントサイズを再定義してはなりません。
- コピーが長い場合は、レイアウトやボタンコンテナを調整することを優先し、高さ、フォント、左右の間隔を圧縮して解決しないでください。
5. 形状 shape
| Shape | 表現 | 使用範囲 |
|---|---|---|
pill | 全角丸。テキスト付きの場合は楕円形 | プラットフォームデフォルト。マーケティングページ、Dashboard、Builder、CMS、Admin に適用 |
rounded | 12px 角丸 | 生成サイトのテーマで明示的に小さい角丸が要求される場合のみ |
Button のデフォルトは shape="pill" です。プラットフォームのフロントエンドは rounded を明示的に設定せず、ローカル CSS で角丸をオーバーライドもしないでください。
// 平台默认:省略 shape 即为 pill
<Button type="button" variant="primary">保存</Button>
// 仅生成站点主题有明确视觉要求时使用
<Button shape="rounded" type="button" variant="primary">
预约咨询
</Button>IconButton は常に円形であり、pill / rounded のビジネス選択には関与しません。
6. アイコンルール
- テキスト前のアイコンは
leadingIconを使用し、テキスト後のアイコンはtrailingIconを使用します。 - 1つのボタンには通常1つの補助アイコンのみ使用します。
- 保存、追加、戻るなどの馴染みのある操作はアイコンで認識を強化できますが、アイコンは重要ボタンの表示テキストの代替にはなりません。
- 矢印が続行、進入、展開を表す場合は通常テキストの後に配置し、戻るアイコンは通常テキストの前に配置します。
children内でアイコンとテキストのレイアウトを手動で記述しないでください。コンポーネントが icon と label のスロットを提供しています。- 共有アイコンを使用し
currentColorを継承してください。ルート CSS でアイコンの色やサイズをハードコードしないでください。 - ローディング状態はボタンの元の高さと幅を維持し、理解可能な短いテキストまたは既存のローディングフィードバックを提供してください。テキストの切り替えによりツールバーが跳ねないようにしてください。
7. ボタンとリンク
操作とナビゲーションには正しいセマンティクスを使用しなければなりません:
- 送信、保存、ポップアップを開く、状態を切り替えるなどの現在のページ内操作には、
hrefなしのButtonを使用し、最終的に<button>としてレンダリングします。 - 別のルートまたはリソースへ遷移するには、
href付きのButtonを使用し、最終的に Next.js<Link>としてレンダリングします。 - フォーム内の非送信ボタンは
type="button"を明示的に記述しなければなりません。送信ボタンはtype="submit"を明示的に記述します。 onClickで通常のページナビゲーションを模擬しないでください。
無効化されたリンクは aria-disabled を使用し Tab 順序から除外します。無効化されたネイティブボタンは disabled を使用します。無効状態は透明度を下げるだけで表現してはならず、ビジネスロジックでも操作を阻止しなければなりません。
8. 状態とアクセシビリティ
共有コンポーネントが hover、focus-visible、disabled、色の状態を統一的に担当します。ビジネスコードは以下を満たす必要があります:
- 通常の未選択ボタンの hover には
--control-surface-hoverを使用し、押下、選択、展開状態には--control-surface-activeを使用します。focus-visibleは中立なサーフェス上で--focus-ringを保持し、ルートスタイルで hover と持続状態を同じ浅い青のルールに統合してはなりません。 - ボタン名は直接的で具体的であり、何が起こるかを説明しなければなりません。例:「保存」「サイトを公開」「項目を削除」。
IconButtonはローカライズされたaria-labelを提供しなければなりません。- 装飾アイコンは
aria-hidden="true"を使用し、スクリーンリーダーによる重複読み上げを避けます。 - キーボードフォーカスは可視でなければなりません。ルート CSS は共有 focus ring を削除してはなりません。
- hover を唯一のヒントとして使用しないでください。インタラクションはキーボードとタッチの両方に対応しなければなりません。
- 無効ボタンはユーザーが一時的に実行できない操作にのみ使用します。理由を説明する必要がある場合は、近接する説明または tooltip を提供してください。
- エラー、権限要求、リスク、費用、その他のタスク重要情報は可視を維持しなければなりません。Tooltip は情報の補足にのみ使用し、これらの情報を発見する唯一の方法にしてはなりません。
- 非同期操作は二重送信を防ぎ、理解可能な進行中フィードバックを維持しなければなりません。
- 危険な操作には
dangerを使用し、既存の危険確認パターンを再利用してください。リスクの伝達を赤色にのみ依存しないでください。 - 中国語またはその他の言語のボタンテキストは理解不能になるほど切り詰めてはなりません。長いテキストとモバイル幅の検証を必ず実施してください。
9. スタイル責任境界
共有ボタンの構造、セマンティクス、状態は Button / IconButton が担当します。視覚トークンと共有 CSS はコンポーネントパッケージが担当し、ルートはレイアウトのみ担当します。
共有層が担当するもの
- DOM、リンク/ボタンのセマンティクス、disabled 動作;
- icon/label スロットとアクセシビリティ型制約;
- variant、size、shape クラス;
- 高さ、角丸、パディング、フォントサイズ、フォントウェイト;
- 背景、テキスト色、シャドウ、hover、focus-visible、disabled 状態。
ルート層が担当できるもの
- ボタングループの方向、間隔、配置、折り返し;
- レスポンシブ配置;
- 特定のワークフローに必要な
width: 100%またはコンテナ幅; - 基本視覚を変更しない位置指定クラス名。
ルート層が担当してはならないもの
- ボタンの高さ、フォントサイズ、角丸、背景、テキスト色、シャドウ、focus ring の書き換え;
- ハードコードされた色や
border-radius: 999pxで共有ボタンを再実装すること; primary-alt、outline-blue、icon-roundなどのローカル視覚バリアントの新規追加;!importantで共有ボタンの契約と競合すること;.qk-ui-buttonの基本スタイルを直接コピーすること。
複数のページで必要とされる新しいセマンティックバリアントが実際に存在する場合は、まず共有 ButtonVariant、トークン、primitives.css に統一契約を確立し、ルートで新規スタイルを追加しないようにしてください。
10. API クイックリファレンス
type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
type ButtonSize = 'sm' | 'md' | 'lg';
type ButtonShape = 'rounded' | 'pill';Button の主要プロパティ:
| プロパティ | デフォルト値 | 説明 |
|---|---|---|
variant | primary | セマンティックおよび視覚階層 |
size | md | 高さ、テキストフォントサイズ、横パディング |
shape | pill | Button の角丸形状 |
leadingIcon | なし | テキスト前アイコン |
trailingIcon | なし | テキスト後アイコン |
href | なし | 指定時にリンクとしてレンダリング |
disabled | false | インタラクションの無効化 |
tooltip | なし | 共有 Tooltip の補足コンテンツ。表示される重要情報または aria-label の代替にはならない |
tooltipPlacement | bottom | 優先方向。共有 Tooltip はビューポート内に収まるよう反転する場合がある |
tooltipPortal | true | クリッピングコンテナの外側にレンダリングし、レイアウトラッパーを追加しない |
skin | なし | skeleton/skin 契約に従い class スロットと変数適応を提供 |
IconButton は該当する Button プロパティを継承しますが、shape、leadingIcon、trailingIcon は提供しません。aria-label を要求し、デフォルトは variant="ghost" です。
ビジネスコードでは variant とネイティブボタンの type を明示的に記述し、コードレビューで操作セマンティクスが明確になるようにすることを推奨します。
11. 一般的な組み合わせ
// 主要操作:椭圆形文字按钮
<Button type="submit" variant="primary">
保存
</Button>
// 次要操作
<Button type="button" variant="secondary" onClick={onPreview}>
预览
</Button>
// 低强调文字操作
<Button type="button" variant="ghost" onClick={onCancel}>
取消
</Button>
// 图标 + 文字,仍然使用 Button
<Button
leadingIcon={<PlusIcon aria-hidden="true" />}
type="button"
variant="primary"
>
新建内容
</Button>
// 纯图标:圆形按钮
<IconButton aria-label="更多操作" tooltip="更多操作" type="button">
<MoreIcon aria-hidden="true" />
</IconButton>
// 危险操作
<Button type="button" variant="danger" onClick={openDeleteConfirm}>
删除项目
</Button>12. レビューチェックリスト
ボタン関連の UI を提出する前に以下を確認してください:
ButtonまたはIconButtonの再利用を優先したか?- テキスト付きボタンとアイコンのみのボタンで正しいコンポーネントを選択したか?
- 現在のタスク領域に明確な
primaryが1つだけあるか? secondary、ghost、dangerは色ではなくセマンティクスに基づいて使用したか?- プラットフォームの
Buttonはデフォルトのpillを維持し、IconButtonは円形を維持しているか? - 各 Tooltip はクリック可能な楕円ボタンのように見えず、コンパクト角丸の情報レイヤーのままであるか?
- ブラウザネイティブの
title、CSSdata-tooltipバブル、重複ヒント、テキストボタンの同義 Tooltip を排除したか? - サイズは
sm、md、lgのみを使用し、同じグループの高さとフォントサイズは統一されているか? - ネイティブボタンに正しい
typeが明示的に設定されているか? - アイコンは重複するスクリーンリーダー情報を隠しており、
IconButtonにはローカライズされたaria-labelがあるか? - focus-visible、disabled、非同期、危険確認の状態は完全か?
- ルート CSS はレイアウトのみ処理し、ボタンの基本視覚をオーバーライドしていないか?
- デスクトップとモバイル幅で長いテキスト、タッチサイズ、ボタングループの配置を検証したか?
13. 実装ソース
- コンポーネント API:
packages/components/src/ui/Button/Button.tsx - コンポーネントエクスポート:
packages/components/src/ui/Button/index.ts - サイズとカラートークン:
packages/components/src/styles/foundations.css - 共有ボタンスタイル:
packages/components/src/styles/primitives.css - 公開コンポーネント接続契約:
docs/public/design/component-integration.md
ドキュメントと実装に差異が生じた場合は、同じ変更内でコンポーネント、トークン、スタイル、本文書を同期してください。