文言Voice & Tone
GunjoUI のボタン、説明文、エラー、空状態、ツールチップ、トーストを、同じ判断基準で設計するためのガイドラインです。文言は翻訳の後工程ではなく、コンポーネント品質の一部として扱います。
このページの使い方
新しいコンポーネント docs を直す時は、先に判断の流れを見てから、場面別パターンとメッセージ一覧を参照します。
このページで決めること
読む順番を固定し、必要な時だけ詳細へ進める構成にしています。
基本原則
文言は、UI の余白を埋めるものではありません。操作を決めるための情報として置きます。
操作結果が先にわかる
押した後に何が起こるかを、ボタンやツールチップで先に伝えます。
迷った時の行動を書く
空状態、エラー、無効化では、状態の説明だけで終わらせません。
日本語と英語の粒度を揃える
直訳ではなく、同じ操作意図と同じ情報量で読める文言にします。
判断の流れ
先に文言の目的を決めると、長いだけの説明や実装語の混入を避けられます。
誰が読むか
エンドユーザー向けか、実装者向けかを先に分けます。ユーザー向け文言に実装語を混ぜません。
何を判断する文言か
操作、状態、エラー、確認、案内のどれかを決めます。目的が曖昧な文は削ります。
次に何ができるか
無効化、空状態、エラーでは、理由と次の行動をセットで書きます。
日本語と英語で崩れないか
短い日本語、長い英語、折り返し、ツールチップの見切れまで確認します。
良い文言は、状態・理由・次の行動に分けられる
長く書くのではなく、ユーザーが判断する順番に情報を並べます。
通信が不安定です。時間をおいてもう一度お試しください。
何が起きたかを最初に書く。
原因がわかる場合だけ、短く添える。
ユーザーが次にできる操作を書く。
場面別パターン
読む人が最初に知りたいのは、文言の分類ではなく、いま見ている UI で何を書けばよいかです。
操作文言は、実行後の状態がわかるようにする
短いラベルで足りない場合は、ツールチップや補助説明で補います。
成功時は「保存しました」。
成功時は「コピーしました」。
取り消せない時だけ使う。
状態文言は、理由と次の行動まで含める
空状態、無効化、エラーは見た目だけでは伝わりません。必ず文言で補足します。
次の操作を説明に入れる。
有効化条件を書く。
回復方法を書く。
実装上の名前ではなく、使う場面で説明する
コンポーネントの内部名やプロパティ名は、コード例では必要です。ただし本文では「どんな場面で使うか」が先に伝わる言葉にします。
見た目の名前ではなく、使う場面として説明した例。
属性名などの実装詳細は、コード例の中で説明する。
選択状態のボタンやアイコンに使うツールチップ。
空状態
対象と次の操作をセットで書く。
アップロードすると、ここに表示されます。
無効化
理由と有効化条件を隠さない。
承認権限がないため公開できません。管理者に依頼してください。
破壊的操作
実行前に対象と不可逆性を確認する。
この操作は取り消せません。
画像と代替テキスト
画像の `alt` は翻訳のついでではなく、画像が UI の中で何を担っているかを説明する文言です。Img、ImagePreview、AssetCard、Avatar、グラフ、地図を確認する時は必ず見ます。
役割ごとに書き分ける
「画像」「写真」「イメージ」だけで終わらせず、必要な時だけ具体化します。
| 役割 | ルール | 例 |
|---|---|---|
| 装飾 | 見た目の装飾だけで、内容や操作を伝えない画像は `alt=""` にします。 | 背景装飾、区切り用の画像 |
| 内容を伝える画像 | 見た目ではなく、ユーザーに伝える内容を書きます。 | オフィスデスクの写真 |
| 商品・素材画像 | ファイル名だけにせず、対象名や内容がわかる言葉にします。 | ノートパソコンの商品写真 |
| 画像ボタン | 操作は画像の `alt` ではなく、ボタンの `aria-label` とツールチップで説明します。 | 拡大表示する / 画像を閉じる |
| グラフ・地図 | `alt` だけで完結させず、近くに要約や表を置きます。 | 東京都インシデントは新宿区が最多です。 |
良い例 / 悪い例
短いだけ、実装語のまま、理由がない文言は直します。比較で見ると判断しやすくなります。
エラー
何が失敗したかと回復方法が必要。
エラーが発生しました。
保存できませんでした。時間をおいてもう一度お試しください。
無効化
理由と次の行動がないと判断できない。
利用できません。
権限がないため変更できません。管理者に依頼してください。
実装語
利用者が判断できる言葉に置き換える。
destructive variant で表示します。
削除など取り消せない操作に使います。
空状態
対象と次の操作を明示する。
データなし
まだキャンペーンがありません。作成すると、ここに表示されます。
メッセージ一覧
文言は最終的に大量の辞書になります。ここではまず頻出する操作、状態、エラー、確認、docs 説明をカテゴリ別に並べ、今後追加する候補も同じ形式で増やします。
ボタン、メニュー、ツールバーで使う短い操作文言です。成功時のフィードバックとセットで管理します。
| 用途 | ラベル / 見出し | 表示メッセージ | 確認ポイント |
|---|---|---|---|
| 保存 | 保存 | キャンペーン設定を保存しました | 対象が画面上で明確な時は短くする。 |
| キャンセル | キャンセル | 変更は保存されません | 閉じる前の確認や補助文に使う。 |
| コピー | コピー | 共有URLをコピーしました | コピー対象が曖昧なら対象名を書く。 |
| 追加 | 追加 | 新しいフィルターを追加しました | 追加後に何が増えたかを伝える。 |
| 編集 | 編集 | 変更を保存しました | 編集開始ではなく保存結果を伝える。 |
| 削除 | 削除 | 選択したファイルを削除しました | 確認ダイアログと組み合わせる。 |
| 完全削除 | 完全に削除 | ファイルを完全に削除しました | 取り消せない時だけ使う。 |
| 選択 | 選択します / 選択を外します | 3件を選択中 | 状態に応じてラベルとツールチップを切り替える。 |
操作後に一時表示するトーストやステータスバーの文言です。短く、結果だけを伝えます。
| 用途 | ラベル / 見出し | 表示メッセージ | 確認ポイント |
|---|---|---|---|
| 保存完了 | 保存しました | キャンペーン設定を保存しました | 対象が曖昧なら対象名を含める。 |
| コピー完了 | コピーしました | 共有URLをコピーしました | URL、コード、色など対象を具体化する。 |
| 更新完了 | 更新しました | 一覧を最新の状態に更新しました | 一覧や設定の更新後に使う。 |
| 作成完了 | 作成しました | 新しいプロジェクトを作成しました | 作成対象が直前に見える場合。 |
| 削除完了 | 削除しました | 選択したファイルを削除しました | 取り消しがある場合はアクションを添える。 |
| 送信完了 | 送信しました | 招待メールを送信しました | メールや招待送信に使う。 |
失敗した操作、理由、回復方法の順番で書きます。原因不明なら原因を書き切らないようにします。
| 用途 | ラベル / 見出し | 表示メッセージ | 確認ポイント |
|---|---|---|---|
| 保存失敗 | 保存できませんでした | キャンペーン設定を保存できませんでした。通信が不安定です。時間をおいてもう一度お試しください。 | 再試行や入力修正を添える。 |
| 読み込み失敗 | 読み込めませんでした | ファイル一覧を読み込めませんでした。再読み込みしてください。 | 対象がある時は対象を書く。 |
| アップロード失敗 | アップロードできませんでした | ファイルをアップロードできませんでした。容量と形式を確認してください。 | 容量、形式、通信などの理由を添える。 |
| 入力形式 | 入力形式を確認してください | メールアドレスの形式を確認してください。 | 入力した人を責めない。 |
| 権限不足 | 権限がないため変更できません | 権限がないため変更できません。管理者に編集権限を依頼してください。 | 依頼先や必要権限を書く。 |
| 通信不安定 | 通信が不安定です | 通信が不安定です。時間をおいてもう一度お試しください。 | 回復可能な失敗に使う。 |
確認手順
コンポーネント詳細ページやパターンを更新する時は、見た目、操作、文言をまとめて確認します。
- 日本語ページで英語だけの説明が残っていない。
- 英語ページで日本語だけの説明が残っていない。
- ラベル、説明、表示メッセージを分け、文脈で不足する情報を本文メッセージに入れている。
- 画像の代替テキストが、装飾、内容、操作、データ可視化の役割に合っている。
- ボタン、アイコン、ツールチップが操作結果を示している。
- 無効化 UI に理由と有効化条件がある。
- エラーに回復方法がある。
- 破壊的操作に確認がある。
- 新しい文言が既存のメッセージ一覧にない場合は、追加候補として issue または作業ログに残している。
- 日本語と英語の長さで UI が崩れていない。
このページは公開向けの基準です。運用メモ、棚卸し、今後追加するメッセージ候補はリポジトリ内の docs/content-guidelines.md と Issue #234 で管理します。