better-writing

インターフェースに溶け込む文章

気の利いた表現より明快で簡潔な表現を、一貫性より多様さを優先します。また、最良のエラーメッセージとは、エラーが起きないようにインタラクションを設計し直したものです。ユーザー向けのテキストを作成またはレビューする際は、これらの原則を適用してください。

テキストの表示方法（text-transform による大文字・小文字の変換、切り捨て、スマート句読点）は better-typography スキルで、エラーのマークアップや通知（aria-invalid、ライブリージョン）は better-accessibility スキルで、翻訳後の文字列に必要な余白は better-layout スキルで扱います。

クイックリファレンス

カテゴリ	使用する場面
レビュー出力形式	重大度の尺度、指摘事項の表、検証、判定

基本原則

1. 既存の語調を調べる

作成またはレビューを始める前に、周辺のインターフェース文言、製品の用語、ローカライズの慣例、語調やコンテンツのスタイルガイドを確認してください。明快さが保たれ、状況にふさわしい範囲で、意図されたブランドらしさを維持してください。一般的な平易な表現と異なる点を指摘事項とするのは、それが不統一、曖昧さ、翻訳上のリスク、または不適切な語調につながる場合に限ります。

2. 声は一つ、語調は柔軟に

製品の声は、個別の編集時に新たに作るものではなく、既存のシステムによって定まっています。用語を統一してください。メニューで「アーカイブ」としているなら、トーストで「ストレージに移動」とはしません。状況に応じて語調を調整します。

状況	語調
成功、オンボーディング、空の状態	親しみやすく、軽やかでも構いません
日常的な操作、設定	中立的で、簡潔
エラー、破壊的な操作の確認	落ち着いて、平易に。遊び心は避けます
データ損失、セキュリティ	真剣に、明確に

3. 読み手に直接語りかける

操作を案内するインターフェース文言では、「ユーザー」ではなく「あなた」として読み手に直接語りかけます。エラーで曖昧さや責任逃れの印象を生む場合は、「私たち」を避けてください。「コンテンツを読み込めませんでした」のようにし、「コンテンツの読み込みに問題が発生しています」のような表現は避けます。明快さが保たれる低リスクの状況では、定着している一人称のブランド表現を維持してください。所有格は控えめに使い（「お気に入り」ではなく「あなたのお気に入り」とするなど）、視点を意図せず切り替えないでください。

4. 気の利いた表現より平易な言葉を

理解しやすい言葉を選び、不要な言葉はすべて削除してください。翻訳できない慣用句、口語表現、ユーモアは使いません。不要な性別表現は避けます。「各購読者は自分のレシピを投稿できます」ではなく、「購読者はレシピを投稿できます」とします。入力デバイスに合った表現を使います。タッチ操作では「タップ」、ポインター操作では「クリック」、どちらの場合もあるときは「選択」を使います。変数の前後に断片をつないで文を作ってはいけません（"You have " + n + " new messages"）。言語によって語順が異なるため、適切な複数形処理を含む完全なテンプレート文字列を使ってください。

5. ボタンは動詞から始める

ボタンのラベルは、具体的な操作を示す動詞から始めます。「送信」「下書きを保存」「プロジェクトを削除」のようにします。「OK！」「さあ、始めましょう！」や、重大な操作に対する「はい」「いいえ」だけの表現は使いません。確認ボタンでは、ダイアログの本文を読まなくても選択できるように、操作の結果を繰り返します。「このプロジェクトを削除しますか？」に対しては「はい」「いいえ」ではなく、Delete project と Cancel を提示します。

6. 一連の操作では用語を統一する

複数ステップのフローでは、用語を一貫させます。開始時は「始める」、次へ進むときは「続行」または「次へ」（どちらか一方を選ぶ）、完了時は「完了」を使います。各ステップで類義語を切り替えると、ボタンごとに異なる操作をするのかとユーザーを迷わせます。

7. リンク先が分かるリンクテキストにする

リンクテキストは、文脈から切り離しても意味が通じるようにします。スクリーンリーダーのユーザーは、ページ内のリンク一覧から移動するためです。「こちらをクリック」は使わず、「請求に関するドキュメントを読む」とします（タッチ操作ではデバイスに合った動詞という原則にも反します）。同じページに複数のリンクがある場合、「詳細はこちら」だけの表現も使いません。それぞれに対象を付けて、「エクスポートについて詳しく見る」のようにします。

8. 大文字・小文字の表記ルールを統一する

要素の種類ごと（すべてのボタン、すべての見出しなど）にタイトルケースまたはセンテンスケースを選び、一貫して適用してください。センテンスケースは、落ち着いた印象で、単語ごとの大文字・小文字のルールがなく、ローカライズもしやすいため、より安全なデフォルトです。「Save Changes」と「Discard changes」が並ぶと、雑な印象になります。

9. 設定項目ではオンの状態を説明する

トグルには、オンにしたときの動作をラベルとして付けます。「開封確認を送信する」とすれば、オフの状態はユーザーが推測できます。否定形（「開封確認を送信しない」）は使わないでください。トグルが二重否定になってしまいます。設定へのリンクは、そこまでの経路を説明するのではなく、参照先に直接リンクします。「設定 > 通知 > メールに移動」ではなく、「通知設定」へのリンクにします。

10. エラーには、問題が起きた場所のそばに修正方法を示す

エラーは指示です。問題が起きたフィールドのすぐそばに表示します。

悪い例	良い例
パスワードが短すぎます	8 文字以上のパスワードを設定してください
無効な名前です	名前には英字のみを使用してください
おっと！問題が発生しました。	保存できません。接続を確認して、もう一度お試しください。

責める表現、「おっと」、感嘆符は使いません。「数字や記号は使わないでください」ではなく「英字のみを使用してください」のように、肯定的なヒントを示します。また、間違いが起きた後ではなく、起きる前に表示します。同じエラーが多くのユーザーに繰り返し表示される場合は、文言を変更するのではなく、操作方法を見直してください。

11. 空の状態では次の行動を示す

空の状態では、その場所が何のためのものか、どうすれば内容を追加できるかを説明し、明確な次のアクションを 1 つ示します。

<p>No results.</p>


<p class="font-medium">No projects yet</p>
<p class="text-sm text-zinc-500">Projects keep your tasks and files together.</p>
<button class="mt-4">Create a project</button>

検索やフィルターの結果が空の場合は、検索語を示して、抜け出す方法を提示します。「「quarterly」に一致する結果はありません。フィルターをクリア」。重要な永続情報を空の状態にだけ表示しないでください。コンテンツが追加された時点で、その情報は表示されなくなります。

12. プレースホルダーはラベルではなく例

プレースホルダーには、期待される形式を示します（[email protected]、DD/MM/YYYY）。プレースホルダーだけをフィールドのラベルにしてはいけません。入力すると消えてしまうため、すべてのフィールドに常に表示されるラベルを付けます。

よくある間違い

間違い	修正方法
製品で確立された用語や文体を無視して、その場で文言を書き換える	変更案を出す前に、周辺の文言とスタイルガイドを確認する
説明的なインターフェース文言で「ユーザーは」と書く	読み手に直接「あなた」と呼びかける
「問題が発生しています…」のように、責任や復旧方法を曖昧にする	状況と次の手順を直接伝える：「コンテンツを読み込めません」
破壊的な操作を確認するダイアログで OK / はい と表示する	結果を繰り返して示す：「プロジェクトを削除」
手順 2 では「続行」、手順 3 では「次へ」と表示する	フロー全体で同じ用語を使う
「ここをクリック」やリンク先がわからない「詳細はこちら」	リンク先を説明する：「請求に関するドキュメントを読む」
「変更を保存」の横に「変更を破棄」と表示する	要素の種類ごとに大文字表記の方針を統一する
トグルに「開封確認を送信しない」と表示する	オンの状態をラベルにする：「開封確認を送信する」
「おっと！問題が発生しました。」	問題が起きた場所のそばに、対応方法を示す
空の状態全体が「結果はありません。」だけになっている	状況を説明し、次のアクションを示す
プレースホルダーにラベルの役割を持たせる	常に表示されるラベルを付け、プレースホルダーには形式を示す
"You have " + n + " messages"	複数形に対応した、完全なテンプレート文字列を使う

報告

単独のライティングレビューは、確認済みのすべての指摘事項が、検証と判定を含めてreview-output.mdに記載された形式で報告されると完了です。better-interfaceでは、そちらの形式が優先されます。