コンテンツ
ナビゲーション、操作、状態で使うUI文言の書き方を確認できます。文言は、現在地、起きたこと、次の操作を具体的に伝えます。表示する文言とAccessible nameを一緒に決めます。
9. UIライティング
UI文言の役割、表記、状態メッセージの書き方を示します。表示する文言とAccessible nameを一緒に決めます。読者が次の操作を判断できることを確認します。
9-1. 声の性格
UIは、技術記事の静かな案内役です。
- 記事本文との関係
- 記事本文の個性とは分ける
- 役割
- 読者が探す・読む・戻る判断を短く支援する
| 特性 | 目指す状態 | 避ける状態 |
|---|---|---|
| 簡潔 | 判断に必要な情報だけを伝える | 背景説明をUIへ詰め込む |
| 具体的 | 「記事」「検索」「Cosense」と対象を示す | 「データ」「処理」だけで済ませる |
| 落ち着き | 確認できた事実を穏やかに伝える | 過剰な謝罪・煽り・感嘆符 |
| 中立 | 読者の選択とペースを尊重する | 急かす、読者に責任を向ける |
9-2. 文言設計の6原則
- 文脈から書き始める
- 周囲から明らかな情報は繰り返さない
- 1つの文言に1つの役割を持たせる
- 見出し、説明、操作、状態、補助を分ける
- 操作後を予測できるラベルにする
- 文法を機械的に揃えず、自然な言葉を選ぶ
- 読者が知っている言葉を使う
- 内部実装語ではなく画面上の対象を示す
- 状態は事実を先に伝える
- 役に立つ場合だけ次の手段を続ける
- Visible textとAccessible nameを一緒に決める
- 表示ラベルがある場合は、その文言をAccessible nameに含める
9-3. コンポーネント別の文法
| 部品 | 文法 | 例 |
|---|---|---|
| Navigation | 名詞 / 固定カテゴリ名 | Posts, Search |
| Button | 操作後を予測できる言葉 | トップへ戻る / さらに表示 |
| Icon button | 操作を示す短い名前 | メニューを開く |
| Search | 入力目的 / 進行状態 | 記事を検索 / 検索しています… |
| Empty | 状態 + 必要な次の手段 | 記事が見つかりません |
| Error | 完了できなかったこと | 検索できません |
| Success | 完了した操作 | コードをコピーしました |
| External link | 移動先 + 操作 | Cosense / すべて見る |
9-4. 表記
読者が操作対象、条件、結果を判断できるように書きます。短くするときも、判断に必要な情報を残します。
- 用語と文の構造
- 同じ対象と操作には同じ言葉を使う
- 一文では1つの内容を伝え、状態と次の操作は文を分ける
- 操作に条件がある場合は、操作より先に条件を書く
- 「適切に」だけで済ませず、判断できる条件や結果を示す
- 文体
- ボタンやリンクは短く書く
- 説明文と状態メッセージは「です・ます」で書く
- 日本語と英語
- Navigationのカテゴリ名とサービス固有名は英語を使用できる
- 説明・操作・状態は日本語を基本とする
- Pagefind、API、proxyなどの実装語は記事本文や開発者向けログで使い、読者向けの状態文には出さない
- 句読点
- ボタン、見出し、タグに句点を付けず、完全文には「。」を付ける
- 進行中は全角の「…」を1つ使う
- 数字・日付・件数
- 数字は算用数字を使う
- 記事日付は「2026年3月21日」と書く
- 件数は対象と隣接させる
「検索条件の変更を行ってください」は「キーワードを変えて検索してください」と書きます。短くしても、操作対象や条件は残します。
9-5. 状態メッセージ
- 構成
- 短い見出しと、必要な場合だけ本文または操作を組み合わせる
- 一貫性
- 同じ対象と状態には同じ文言を使う。検索結果0件とCosenseの取得結果0件は区別する
| 状態 | 見出し・通知 | 本文・操作 |
|---|---|---|
| 検索中 | 検索しています… | 追加説明なし |
| 検索結果0件 | 記事が見つかりません | キーワードを変えて検索してください。 |
| 検索エラー | 完了できなかったことを伝える | 再試行または記事一覧への導線がある場合だけ案内する |
| Cosense 0件 | 表示対象がないことを伝える | 補助領域では、空のNotes領域を畳む |
| Cosenseエラー | Cosenseを読み込めませんでした | 再読み込み |
| コピー完了 | コードをコピーしました | aria-live="polite" |
Specification docs/design/ui-writing-guidelines.md