コンポーネントのテンプレート

コンポーネントの説明と主な利用シーンを書きます。
1文目には、frontmatterのdescriptionと同じ文を記載します。一覧ページや検索結果、AIによる索引にも使われるため、以下の書式ルールに則ってください。

description書式ルール：〜のためのコンポーネントです。〜とき、〜ときに使います。

• 1文目：「何の代わりに使うか」または「何のためか」を冒頭に置き、対象（テキスト・日付など）と中心動詞（入力させる／表示する／選択する／切り替えるなど）を1セットで含める。詳細は2文目以降へ回す。
  • 例：「input[type="text"]の代替としてテキストや数値を1行で入力させるコンポーネントです。」
• 2文目：「〜するときに使います。」または「〜させるときに使います。」で利用シーンを書く。
  • 主語の使い分け
    • 入力系（フォーム系の要素）：システムを主語にして「〜させるとき」基調
      例:「金額値を入力させるときに使います。」
    • 操作系（上記以外のナビゲーション・操作系の要素）：ユーザーを主語にして「〜するとき」基調
      例:「アクションを選択するときに使います。」

さらに必要な説明があれば本文には続けて書けます。複数行に渡っても問題ありません。

使用上の注意

他のコンポーネントとの使い分けの基準、特に注意したいアンチパターンなど使用上の注意があれば書きます。
種類ごとの使いどころは種類に書きます。

{コンポーネント名}を使用したコンポーネント

開発で頻繁に利用する実装を別のコンポーネント化している場合は、子ページへのリンクや説明を書きます。

種類

コンポーネントのバリエーションを小見出しにわけて書きます。もし網羅的な比較が必要な場合、テーブル or previewでコンポーネントを一覧を表示します。

コンポーネント名（種類） 例: Primary

コンポーネント（種類）の説明が入ります。

単品

複数

iframeを使用したくない場合（非推奨）

プロダクト

レイアウト

メインの種類でなく、コンポーネントが持つその他の種類（サイズやアイコン付きなど）がある場合に書きます。

プレビューを埋め込む際の注意点

次のようなReactのAPIを使っていたり、PropsでReactコンポーネントを受け取るコンポーネントはMDX内で定義できません。

修正前：

このようなコンポーネントのプレビューを埋め込みたい場合は、別ファイルに切り出して import してください。

この際、内部でuseStateなどを使っている場合はclient:loadやclient:only="react"を付与してクライアントで動作するようにしてください。

修正後：

状態

コンポーネントが持つ（hoverやdisabledなど）状態がある場合に書きます。

ライティング

主題に種類がなく、ライティングルールを書きたい場合はここに書きます。〇〇の使い方..などはこのグループに所属させます。AirTableも必要であれば埋め込めます。

デザインパターン

コンポーネント独自のデザインパターンがあればこのグループ内に書きます。基準サイズなどもこのセクションで書きます。

アクセシビリティ

主題全体に対するアクセシビリティの考え方として、特段言及したい場合は書きます。

モバイル

モバイルでの表示について、特に言及したい場合はここに書きます。

モバイル表示におけるレイアウトやデザインパターンなどを記載する場合は、基本的にこのセクションにまとめて書くことを推奨します。 ただし、各セクションのなかでモバイル表示について言及するほうが都合がよい場合は、それぞれのセクションの中に書くことも問題ありません。

使い方チェックリスト

同ディレクトリのchecklist.yamlの内容を読者向けに表示するセクションです。（本文は不要です）
nameにはコンポーネント名（PascalCase。例: Button / ActionDialog）を指定します。見出しを目次に含めたい場合のみshowHeadingを付けます。

Button

参照元：使用上の注意 > type="button" について 「使用上の注意 > type="button" について」の本文へ移動

• Must

  form submit を使う場合は `type="submit"` を明記する

参照元：種類 > Primary 「種類 > Primary」の本文へ移動

• Must

  1 つの画面で Primary ボタンは最大 1 つまでにする

  • 主要な操作が複数ある場合は、画面内の主要な操作が 1 つになるように情報設計と画面構成を見直す
• Avoid

  ユーザーからの注目（視線）を集めることだけを目的に Primary ボタンを使用しない

参照元：種類 > Secondary 「種類 > Secondary」の本文へ移動

• Should

  Secondary ボタンが多い場合は情報設計・画面構成の見直しや DropdownMenuButton の利用を検討する

参照元：種類 > Tertiary 「種類 > Tertiary」の本文へ移動

• Must

  Tertiary ボタンを単独で利用する場合は prefix または suffix にアイコンを設定する
• Must

  他の画面へ移動するリンクとして使いたい場合は TextLink を使う
• Should

  Tertiary ボタンは Secondary ボタンより重要度の低い操作に使う

参照元：種類 > Danger 「種類 > Danger」の本文へ移動

• Should

  Danger ボタンは主に削除ダイアログで使用する
• Should

  警告色（DANGER）に頼らず、ボタン配置のコンテキストやラベルテキストだけでもユーザーに伝わるよう検討する

参照元：種類 > Text 「種類 > Text」の本文へ移動

• Must

  Text ボタンを単独で使う場合は prefix または suffix にアイコンを設定する
• Should

  Text ボタンは Secondary ボタンの装飾（枠線）が過剰な場合に使う

  • コンポーネントに内包する場合（例: DropdownMenuButton）
  • 多くのボタンを並べて表示する場合

参照元：種類 > AnchorButton 「種類 > AnchorButton」の本文へ移動

• Must

  アクションボタンとして表現したい場合は Button を使用する

参照元：レイアウト > ボタンサイズ 「レイアウト > ボタンサイズ」の本文へ移動

• Should

  レイアウトの都合上スペースを節約したいときはサイズ `小` を使う

参照元：レイアウト > アイコンの有無 > アイコン付きボタン 「レイアウト > アイコンの有無 > アイコン付きボタン」の本文へ移動

• Must

  同じ操作のボタンには同じアイコンを指定する
• Should

  アイコン付き（左）はボタンを押したときに実行される操作を想起させるために使用する
• Should

  アイコン付き（右）はボタンを押したときに特定の UI が表示される場合に使用する

参照元：レイアウト > アイコンの有無 > アイコン付きボタン > `アイコン付き`にする判断基準 「レイアウト > アイコンの有無 > アイコン付きボタン > `アイコン付き`にする判断基準」の本文へ移動

• Must

  アイコンは左右どちらかにのみ指定する

  • どちらにもアイコンをつけられそうな場合は、アイコン付き（右）（サフィックス）を優先し、アイコン付き（左）（プレフィックス）には指定しない

参照元：レイアウト > アイコンの有無 > アイコン付きボタン > `アイコン付き（左）`（プレフィックス）の判断基準 「レイアウト > アイコンの有無 > アイコン付きボタン > `アイコン付き（左）`（プレフィックス）の判断基準」の本文へ移動

• Avoid

  明確な必要性や理由がなければ、アイコンをつけることは極力避ける
• Should

  SmartHR 上で頻出する操作に関してはアイコンをつけるのを推奨する

参照元：レイアウト > アイコンの有無 > アイコンボタン 「レイアウト > アイコンの有無 > アイコンボタン」の本文へ移動

• Must

  アイコンには必ず代替テキストを含める
• Should

  アイコンのみのボタンは、ラベルテキストを表示するレイアウト上の余裕がない場合に使う

参照元：状態 > 無効（disabled） 「状態 > 無効（disabled）」の本文へ移動

• Avoid

  無効状態のボタンはできるだけ使わない

  • そもそも無効ではなくボタン自体を非表示にしたり、無効状態の理由を付近に表示することを検討する
  • 無効状態の理由を配置するスペースがどうしてもない場合、`disabledReason` props で理由を表示することを検討する

参照元：ライティング 「ライティング」の本文へ移動

• Must

  ボタンラベルには動詞の終止形を使用する

参照元：アクセシビリティ > 開発時の考慮点 > 色以外の情報でもボタンであることを伝える 「アクセシビリティ > 開発時の考慮点 > 色以外の情報でもボタンであることを伝える」の本文へ移動

• Must

  Tertiary ボタンや Text ボタンにはアイコンを追加し、色だけでなく形や見た目の違いからも操作できる要素であることが伝わるようにする

参照元：アクセシビリティ > 開発時の考慮点 > アイコンボタンにはアクセシブルネームを設定する 「アクセシビリティ > 開発時の考慮点 > アイコンボタンにはアクセシブルネームを設定する」の本文へ移動

• Must

  アイコンボタンはアイコンコンポーネントの `alt` props に操作内容を表すテキストを設定する

参照元：モバイル > ボタンの大きさ > 通常サイズのボタンを使う 「モバイル > ボタンの大きさ > 通常サイズのボタンを使う」の本文へ移動

• Must

  レイアウトの都合上 `サイズ小` のボタンにする必要がある場合、間隔を十分にあける

  • その場合、アイコンボタンとして使うことはなるべく避ける
• Avoid

  モバイルで `サイズ小` のボタンを使うことは避ける
• Should

  モバイルでは基本的に `通常` サイズを使用する

参照元：モバイル > 複数のボタンの並べ方 > ボタンを並べる方向 「モバイル > 複数のボタンの並べ方 > ボタンを並べる方向」の本文へ移動

• Should

  複数のボタンは基本的に垂直方向に並べる

参照元：モバイル > 複数のボタンの並べ方 > ボタンを並べる順番 「モバイル > 複数のボタンの並べ方 > ボタンを並べる順番」の本文へ移動

• Must

  複数の操作を並べる場合は Primary ボタンの位置を一貫させる

  • 水平方向に並べる場合は、識字方向の後方に Primary ボタンが来るようにレイアウトする（LTR では右側）
  • 垂直方向に並べる場合は、Primary ボタンの下に Secondary ボタンを置く

Props

コンポーネントが持つPropsを網羅して書きます。
グループに複数のサブコンポーネント（例: Dialog 配下の DialogTrigger / DialogContent など）がある場合は、それぞれComponentPropsTableを並べ、区別のためshowTitleを付けます。

関連リンク

• link

参考文献

• link