ux-writing-content-design

UX ライティングとコンテンツデザイン

目的

ユーザーがインターフェースを理解し、操作し、問題から復旧し、製品を信頼できるよう支援するプロダクトコピーを、AI エージェントが作成・評価できるようにします。言葉は、インターフェース完成後に付け加える飾りではなく、デザインシステムとインタラクションモデルの一部として扱います。

このスキルでは、プロダクトの UX コピーを扱います。マイクロコピー、ボタンラベル、リンク、ラベル、ヒント、説明、空の状態、オンボーディング、入力検証、エラー、成功メッセージ、読み込み・進行状況の状態、通知、用語、ボイス、トーン、コンテンツ戦略が含まれます。長文のマーケティングコピーは、製品体験内でのユーザー理解、操作、信頼、オンボーディング、コンバージョンに直接影響する場合を除き、対象外です。

このスキルを使う場面

ユーザーから次の依頼を受けた場合に、このスキルを使います。

• UI テキスト、プロダクトコピー、UX コピー、マイクロコピー、フォームの文言、ナビゲーションラベル、CTA、オンボーディング、空の状態、エラー、確認、読み込み状態、通知、ヘルプテキスト、デザインシステムのコンテンツガイダンスを作成、書き直し、批評する。
• UI、モックアップ、スクリーンショット、フロントエンドコンポーネント、フロー、プロトタイプ、デザインシステムを、明瞭さ、トーン、使いやすさ、信頼、復旧、アクセシビリティの観点からレビューする。
• コピーがユーザーの理解や行動に影響するフロントエンドの状態を設計、実装する。
• コンテンツルール、ボイスとトーンのガイダンス、用語、コンテンツパターン、UX ライティングのチェックリストを作成する。

このスキルを使わない場面

次の場合、このスキルを主要なスキルとして使わないでください。

• 製品内の UX フローに影響する場合を除き、長文のマーケティングページ、広告、ブランドキャンペーン、広報、SEO 記事、セールスコピーを作成する。
• インターフェースのテキスト、状態、理解に関する課題がない、純粋なビジュアルスタイリング、レイアウト、イラスト、アニメーションのタスク。
• 有資格の専門家による確認が必要な法律、医療、金融、コンプライアンス関連の文言。明瞭さを高めることはできますが、専門家による確認が必要であることを明示してください。
• 翻訳・ローカライズそのもの。このスキルを使って、翻訳・ローカライズしやすく、文脈に配慮したソースコピーを作成し、その後は別途、翻訳・ローカライズの専門知識を活用してください。

基本原則

1. 言葉はデザインの素材です。 単に「素敵な言葉」を選ぶのではなく、言葉を使ってユーザーの課題を解決し、インタラクションの振る舞いを形作ります。
2. ユーザーのタスクと製品の目的から始めます。 コピーが効果を発揮するのは、ユーザーの目的と、製品が正当に必要とすることを支える場合に限られます。
3. 気の利いた表現より、役立つ表現を優先します。 個性や楽しさは、理解、操作、信頼、復旧よりも優先度が低いものです。
4. 個々の文言ではなく、会話全体を設計します。 導入点、操作、システムの応答、次のステップ、元に戻す操作、失敗時の経路を確認します。
5. 状態に合ったパターンを使います。 ラベル、ヒント、ツールチップ、インラインエラー、バナー、空の状態、通知、確認には、それぞれ異なる役割があります。
6. 文脈の中で書きます。 周囲の UI、コンポーネントの制約、状態、プラットフォーム、デバイスを踏まえ、表示される場所でテキストを作成・評価します。
7. 操作の結果が伝わるようにします。 ボタンやリンクでは、入力方法ではなく、何が起きるかを示します。
8. エラーは、ストレスがかかる状況です。 可能な限りエラーを未然に防ぎ、発生した場合は明確に説明し、ユーザーが解決できるよう支援します。
9. 不利な立場に置かれやすい人々に配慮します。 デリケートな質問、選択の強制、デフォルトの提案、「害のない」クイック返信でも、人を排除したり傷つけたりすることがあります。
10. 簡潔に、ただし不明瞭にならないようにします。 短いコピーに価値があるのは、ユーザーがすぐに理解できる場合に限られます。
11. 重要度に応じて測定します。 コピーの変更がアクティベーション、コンバージョン、リテンション、復旧、信頼に影響する場合は、ユーザビリティテスト、行動指標、サポートデータ、A/B テストを活用します。
12. 実装可能なコピーにします。 コンテンツは、セマンティック HTML、アクセシビリティ API、ローカライズ、デザイントークン、コンポーネントの状態、デザインシステムのパターンに対応できるようにします。

各原則を再利用可能なカードとしてまとめたものは、references/principle-cards.md を参照してください。

デフォルトの推奨事項

ユーザーがより強い製品固有のコンテキストを提供しない限り、これらのデフォルト設定を使用してください。

領域	デフォルトの推奨事項	通常、最適である理由	例外とする場合	例外とする前に確認すること
製品の目標	不確実さを最小限に抑え、ユーザーが目の前のタスクを完了できるよう支援します。	製品の文言の大半は機能的なものであり、ユーザーは読むために製品を利用しているわけではありません。	フローの目的が、学習を促すこと、警告すること、または重大な影響を伴う意思決定を変えることである場合。	最も重視する成果が、理解、コンバージョン、完了、継続、安全性、サポートの削減のどれかを確認します。
対象者	平易な言葉を使い、幅広く忙しい、能力の異なるユーザーに向けて書きます。	認知負荷を軽減し、アクセシビリティとローカライズを改善できます。	製品の対象が、専門用語を必要とする専門家である場合。	対象者が専門用語を期待しているか確認します。
ボイス	プロフェッショナルで、親しみやすく、率直で、人間味のある表現にします。	多くの SaaS、生産性、コマース、公共サービスの製品に適しています。	文書化されたブランドボイスや、規制に準拠したトーンがある場合。	ブランドの個性やボイスチャートを確認します。
トーン	落ち着いた、役に立つトーンにします。感情的な重要度に合わせます。	ユーザーが不確実な状況や中断された状況で文言に触れることはよくあります。	成功や喜びを伝える場面では、より温かい表現が適しています。深刻な状況やデリケートな場面では、控えめにします。	その場面がどれほどストレスを伴うか、またはデリケートかを確認します。
CTA ラベル	可能な限り、動詞から始め、具体的にし、1～3語にします。必要に応じて対象や結果を含めます。	ユーザーはボタンやリンクで意思決定します。	法的措置、破壊的操作、有料操作、取り消せない操作には、より具体的な表現が必要です。	操作の後に具体的に何が起きるかを確認します。
フォームのラベル	フィールドの上または横に、常に表示されるラベルを配置します。ヒントは追加の案内にのみ使います。	入力後もラベルを確認でき、アクセシビリティにも役立ちます。	非常に制約の多い UI で、アクセシビリティ対応済みのパターンがテストされている場合。	プラットフォームやコンポーネントの制約を確認します。
プレースホルダーテキスト	例や書式の説明にのみ使い、唯一のラベルとしては使いません。	プレースホルダーは入力後に消え、コントラストが低い場合があり、アクセシビリティの支援としても不十分です。	デザインシステムにアクセシビリティ対応済みのフローティングラベルがある場合。	コンポーネントにアクセシブルなラベルとエラーとの関連付けがあるか確認します。
ヘルプ／手順の文言	ラベルだけでは不十分な場合に限り、操作の近くに案内を配置します。	追加の文言は役立つこともありますが、不要な説明は読む負担を増やします。	タスクに不慣れなユーザーが多い場合、リスクが高い場合、またはポリシーや形式の制約がある場合。	ユーザーがよく誤解する点を確認します。
機微なデータの要求	データが必要な理由と、その利用方法を説明します。	背景を伝えることで信頼が高まり、単純なカテゴリに当てはまらないユーザーへの不利益も減らせます。	理由が明白で、データが機微なものではない場合。	製品がその情報を必要とする理由と、ユーザーが入力を省略できるかを確認します。
エラー処理	まず防止し、次に説明し、その後に解決します。	予防によって手間を減らせます。予防できなかった場合でも、復旧のための文言でユーザーを支援する必要があります。	バックエンドや法的な制約により、予防できない場合。	技術的に利用できる復旧方法を確認します。
無効なコントロール	無効な UI だけを唯一の案内として使わないようにします。	無効なコントロールはアクセシビリティ上の問題となることがあり、ユーザーを行き詰まらせます。	プログレッシブアクティベーションに、アクセシブルなステータス表示やヘルプが追加されている場合。	無効なコントロールにアクセシブルな説明があるか確認します。
空の状態	何が空なのか、それがなぜ重要なのか、次に役立つ操作を示します。	空の状態は、オンボーディングや復旧の機会になります。	空であることが自明で、実行できる操作もない場合。	ユーザーが次に何をできるか確認します。
成功メッセージ	何が起きたかを確認し、役立つ場合は次の手順や結果も伝えます。	ユーザーには完了したことの確認が必要です。また、公開範囲、配信、取り消しの可否を知る必要がある場合もあります。	UI の状態から完了したことが明確に分かる場合。	成功によって公開範囲、課金、権限、データが変わるか確認します。
読み込み／進捗	何が起きているかを伝え、遅延が目立つ場合は所要時間の見込みを示します。	待機中にフィードバックを示すことで不安を軽減できます。	遅延をほとんど感じない場合。	所要時間が既知か、変動するかを確認します。
通知	タイムリーで、関連性があり、行動につながるメッセージのみを送ります。	通知はユーザーの作業を中断するため、その価値は中断による負担を上回る必要があります。	コンプライアンスや運用上の必要性から、行動を促さない通知が必要な場合。	通知がどのユーザーの操作や意思決定を支援するのか確認します。
楽しさ	文言が機能的で役立ち、感情的にも適切であることを確認してから、個性を加えます。	ユーモアは成功時やストレスの少ない場面では役立つことがありますが、エラー時やストレスのある場面では逆効果になることがあります。	ブランドボイスが意図的に遊び心のあるもので、状況にも問題がない場合。	その場面がストレスを伴うか、デリケートか、取り消せないものか確認します。
指標	まずタスクの成功と理解度を重視します。コンバージョンは、ユーザーの利益と一致する場合にのみ使います。	文言によって、ユーザーが目標から離れるよう誘導してはいけません。	ビジネス目標が明示的な最適化対象である場合。	重視する指標とガードレール指標を確認します。
アクセシビリティのレベル	WCAG に準拠した製品の基本要件（ラベル、プログラムによるエラー通知、フォーカス、キーボード操作、スクリーンリーダー向けの状態、読みやすいテキスト）を満たします。	アクセシビリティは使いやすさの一部であり、誰かを排除するかどうかは設計上の選択です。	ポリシーによって、より高い適合レベルが求められる場合。	コンプライアンスが重要な場合は、必要なアクセシビリティ基準を確認します。
ローカライズ	慣用句、文化固有のジョーク、展開できない短い文字列、曖昧な変数を避けます。	製品の文言は UI 文字列になることが多く、ローカライズによってレイアウトや意味が崩れる場合があります。	製品が単一ロケール向けで、今後も変更されない場合。	製品が翻訳される予定か確認します。

必須のユーザーへの質問

文章を明確、簡潔、または分かりやすくするかどうかなど、日常的なベストプラクティスに関する質問はしないでください。標準の方針を適用してください。

回答によって文章、パターン、トーン、または実装が大きく変わる場合に限り、質問してください。ユーザーが明示的に詳細な確認を求めない限り、一度に焦点を絞った質問を1つだけしてください。

次のいずれかが不明で、確認が必要な場合に質問してください。

• 主要なユーザータスクまたは機能の目的が不明確である。
• 対象ユーザーが専門的、支援を必要とする立場、多言語、非常に若年または高齢、規制対象、あるいはその他の理由で状況に応じた対応が必要である。
• フローで、機微な個人データ、法的同意、支払い、健康、本人確認、セキュリティ、または取り消せない操作を求める。
• 求められるトーンが、ユーザーのストレス、インクルージョン、アクセシビリティ、または信頼と相反する。
• 文章が、技術的制約、バックエンドの検証、復旧手段、デザインシステムのパターン、またはローカライズ要件に依存する。
• ユーザーが指標の最適化を求めているが、指標またはガードレールが不明確である。
• 判断に法務／コンプライアンス部門の承認が必要である。

質問のデフォルトの形式：

question({
  question: "What is the primary user task this copy needs to support?",
  recommended_default: "Assume the user wants to complete the immediate visible action with as little uncertainty as possible.",
  options: [
    "Complete a task",
    "Learn how something works",
    "Recover from a problem",
    "Make a high-stakes decision",
    "Other / custom"
  ]
})

判断に関する質問の全項目については、references/decision-prompts.md にある質問ツールですぐに使えるプロンプトを使用してください。

ワークフロー

A. 既存のUIコピーを批評する

次の順序で確認してください。

1. タスクとの適合性： ユーザーは何をしようとしていますか？コピーはそのタスクを助けていますか、それとも注意をそらしていますか？
2. ユーザーとビジネスの整合性： コピーは、強制、隠蔽、または操作をせずに、正当な製品目標に貢献していますか？
3. 会話の流れ： 入口 → 説明 → 操作 → フィードバック → 次の手順 → 反対の操作 → 失敗時の経路。
4. パターンの選択： 各文字列は適切なコンポーネント／状態を使っていますか？ ラベル、ヒント、CTA、ツールチップ、インライン検証、バナー、モーダル、空の状態、確認、通知などを確認してください。
5. 操作の明確さ： ボタンやリンクは、実行される結果を明示していますか？
6. 理解しやすさ： コピーは平易で具体的、ひと目で把握しやすく、不要な専門用語がありませんか？
7. ストレスと復旧： エラーはユーザーを責めず、問題を説明し、現実的な次の手順を提示していますか？
8. 信頼とインクルージョン： 機微な情報を求める理由が説明されていますか？ 選択肢はインクルーシブですか？ デフォルトや提案は安全ですか？
9. ボイスと一貫性： 表現は製品の原則、用語、文法、大文字・小文字の使い方、トーンに従っていますか？
10. アクセシビリティとフロントエンドでの実現可能性： ラベル、説明、エラー、ステータス更新、フォーカスの挙動、ローカライズは実装可能ですか？
11. 測定： 重要度が高い場合、コピーの効果を検証または測定する方法を特定してください。

批評を報告する際は、指摘事項を重要度別にまとめてください。

• ブロッキング： 理解、操作、アクセシビリティ、信頼、または復旧を妨げる。
• 重要： 認知負荷、不確実性、または一貫性の欠如を増大させる。
• 仕上げ： 基本的なユーザビリティを解決した後に、トーン、流れ、または楽しさを向上させる。

各問題について、現在の問題、改善したコピーまたはパターン、理由、および実装上の注意点を提示してください。

B. 新しいUXコピーを作成または改善する

次の順序で進めます。

1. 製品を利用する場面を明確にする。 ユーザー、タスク、状態、プラットフォーム、制約、成功基準を特定します。コンテキストが不足していて、推奨内容が変わる場合に限り質問します。
2. 会話の流れを整理する。 ユーザーは今、何を知っていますか？ 何を知る必要がありますか？ どのような操作ができますか？ その後、システムは何をしますか？
3. パターンを選ぶ。 コピーをタイトル、ラベル、ヒント、本文、CTA、インライン検証、バナー、モーダル、空の状態、トースト、通知、読み込みメッセージ、ヘルプ項目のどこに置くかを決めます。
4. まず役立つコピーを作成する。 短くしたり、ブランドに合わせたりする前に、正確で、タスクに即し、結果が具体的に伝わるコピーにします。
5. 4つの観点から編集する。
   • 目的にかなっているか：ユーザーと製品の目標に役立ちますか？
   • 簡潔か：意味を損なわずに削れる部分はありますか？
   • 会話的か：システムログではなく、人とのやり取りのように聞こえますか？
   • 明快か：想定するユーザーがすぐに理解できますか？
6. 例外状態や緊急時の状態に対応する。 必要に応じて、空の状態、読み込み中、成功、検証エラー、失敗、権限、オフライン、破壊的な操作、取り消し／再試行の状態を含めます。
7. 実装可能な形にする。 必要に応じて、コンポーネント／状態の対応付け、セマンティックラベル、エラーの関連付け、ARIA ライブリージョンのガイダンス、文字列トークン、ローカライズに関する注意点を提示します。
8. テストまたは検証する。 重要度に応じて、ユーザビリティテストの質問、理解度チェック、サポートデータの確認、A/B テストを提案します。
9. 判断の理由を説明する。 推奨内容を、タスクの完了、理解、信頼、問題からの回復、アクセシビリティ、製品の目標に結び付けます。

判断のフレームワーク

コンテンツのパターンを選ぶには、次のフレームワークを使います。

ユーザーのニーズ	優先するパターン	コンテンツの基本構成
現在の場所を把握する	ページタイトル／セクション見出し	オブジェクト名またはタスク名。具体性が重要な場合は、「詳細」のような一般的な表現を避けます。
フィールドの内容を把握する	常に表示されるラベル	名詞句：「仕事用メールアドレス」、「入金額」。
形式や制約を把握する	ヒント／補助テキスト	制約または例：「8～64文字で入力してください。」
何が起きるか判断する	ボタン／リンク	動詞＋オブジェクト／結果：「投稿を作成」、「24ドルを支払う」、「レポートをダウンロード」。
機微な情報の要求を理解する	文脈に沿った説明	必要な理由＋使用方法＋任意かどうか。
処理中であることを把握する	読み込み中／進行状況	現在の処理＋所要時間／見込み（わかる場合）。
操作が成功したことを把握する	確認／トースト	何が起きたか＋重要な結果＋必要に応じて次の手順。
まだ何もないことを把握する	空の状態	何もない状態であること＋理由／タイミング＋次の操作。
問題から回復する	インラインエラーまたはエラーページ	何が起きたか＋必要に応じて理由＋解決／再試行／終了の方法。
操作を妨げずに学ぶ	インラインヘルプ／ドキュメントへのリンク	その場で役立つ簡潔な説明＋詳しいヘルプへのリンク。
変化にタイムリーに対応する	通知	タイムリーに伝える理由＋ユーザーにとっての利点＋明確な操作または閉じる方法。
害を防ぐ	確認ダイアログ／インタースティシャル	結果＋取り消せない範囲＋安全なキャンセル方法＋具体的な確定操作。

実践的なルール

ボタンとリンク

• 操作方法ではなく、操作の結果を使います。「ここをクリック」、「送信」、「保存」のような曖昧な表現よりも、対象や操作が重要な場合は「レポートをダウンロード」、「投稿を作成」、「料金を見る」のような表現を優先します。
• 支払い、削除、送信、公開、共有、権限、取り消せない操作では、最も重要な結果をラベルに含めます。
• 主要な操作と副次的な操作を、意味のある形で区別します。ユーザーが結果を把握する必要がある場合、「OK／キャンセル」のような組み合わせは避けます。
• 「戻る」、「キャンセル」、「元に戻す」、「除去」、「削除」は、それぞれ取り消し可能性の意味が異なるため、慎重に使います。

フォーム

• すべての入力欄に常に表示されるラベルを付けてください。プレースホルダーをラベル代わりにしないでください。
• 制約が一般的でない場合、例を示す場合、プライバシーに関する懸念がある場合、または情報が必要な理由を説明する場合は、補足テキストを使用してください。
• エラーは該当する入力欄の近くに表示してください。フォームが長い場合や送信に失敗した場合に限り、フォームの上部にもエラーの概要を表示してください。
• 必要な形式に合った例を使用してください。ただし、実際に保存されたデータのように見える例は避けてください。
• 長い説明よりも段階的な開示を優先してください。ただし、タスクの完了に必要な情報は隠さないでください。

センシティブな質問と個人データ

• 身元、属性、健康、金融、位置情報、連絡先、または法的情報を尋ねる前に、その理由を平易な言葉で説明してください。
• 法律上の要件がない限り、二択式、選択肢が過度に限定された形式、または文化に特有の分類を強制しないでください。
• 適切かつ実現可能な場合は、「回答しない」「自分で記述する」「該当する選択肢がない」、またはスキップの選択肢を用意してください。
• 監視、強制、またはデータ収集を和らげるために、ふざけた口調を使わないでください。

エラーと入力検証

「防ぐ → 説明する → 解決する」を使用してください。

1. 防ぐ： 明確なラベル、制約、入力マスク、例、段階的な検証、より良いインタラクションデザインによって、エラーを防いでください。
2. 説明する： 何が起きたのかを、人に分かる言葉で伝えてください。生のエラーコード、スタックトレース、責任を問う表現は避けてください。
3. 解決する： 次に何をすればよいかを伝えてください。修正、再試行、取り消し、サポートへの問い合わせ、別の方法の利用、または待機などです。

エラーメッセージの構成：

[Problem in user terms]. [Specific fix or next step].

構成例であり、固定文言ではありません：

• 「有効なメールアドレスを入力してください。」
• 「ファイルが大きすぎます。10 MB 未満のファイルをアップロードしてください。」
• 「変更を保存できませんでした。接続を確認して、もう一度お試しください。」

緊張を伴う状況、法律、金融、医療、本人確認、セキュリティ、または破壊的な操作に関する場面では、落ち着いた、明確で、ユーモアのない文言を使用してください。

空の状態

空の状態は、ユーザーが状況を把握し、次に進めるようにするために使用してください。

基本構成：

Title: No [objects] yet
Description: [What will appear here or why it matters]
Action: [Next useful action]

すべての空の状態をマーケティング文句にしないでください。有用な次の操作がない場合は、その状態を説明し、元に戻る手段を示してください。

読み込み中と進行状況の状態

• 待ち時間が目立つ場合は、何が起きているのかをユーザーに伝えてください。
• 所要時間を予測できる場合は、あらかじめ目安を伝えてください。
• 処理が失敗する可能性がある場合は、復旧手段を用意してください。
• ブランドらしさは控えめに使用してください。ふざけた読み込み中の文言で、リスク、費用、不確実性を隠してはいけません。

成功と確認

• 完了した操作を具体的に確認してください。
• 公開、表示範囲、支払い、配信、権限、データの変更、メールの送信など、重要な影響を含めてください。
• 現在のタスクに役立つ場合に限り、次の手順を加えてください。
• センシティブな操作が成功したときは、祝うような口調を避けてください。

通知

• 通知は少なく、質の高いものにしてください。
• 適切なタイミングで、関連性があり、行動につながる内容にしてください。
• 曖昧なエンゲージメント目的の誘導は避けてください。
• ユーザーの言語と現在の状況に合わせてください。
• 適切な場合は、頻度の調整と配信停止の手段を用意してください。

文体とトーン

形容詞だけでなく、プロダクトの原則に基づいて文体を構築してください。

以下を定義します：

• コンセプト： プロダクトが一貫して強調すべきこと。
• 語彙： 推奨する用語と避ける用語。
• 説明の詳しさ： 状況ごとに適切な説明の量。
• 文法： 文の構造、視点、短縮形、時制。
• 句読点と大文字・小文字の表記： 一貫した表記ルール。
• トーンの変化： 成功、エラー、法律、プライバシー、オンボーディング、緊張を伴う場面で文体をどう変えるか。

文体の指定がない場合は、プロフェッショナルで温かみのある、率直な文体を使用してください。

編集

次の4段階で編集してください：

1. 目的が明確か
2. 簡潔か
3. 会話として自然か
4. 分かりやすいか

最初に文章を短くしようとしないでください。まず、その文章が適切な問題を解決していることを確認してください。その後、必要な意味を損なわずに短くしてください。

アクセシビリティとインクルージョンの要件

• 入力項目には、画面上に表示されるラベルとプログラムで認識できるラベルを付けます。
• アクセシブルな説明を使って、補足テキストやエラーを各フィールドに関連付けます。
• 状態の伝達を色、アイコン、位置、アニメーションだけに頼らないでください。
• エラー、成功、読み込みの更新が、支援技術に適切に通知されるようにします。
• ダイアログ、エラー、状態の変化を通じて、フォーカスとキーボード操作を維持します。
• 無効化されたコントロールだけで指示を伝えないでください。コントロールを無効にする場合は、その理由と有効にする方法をアクセシブルなテキストで説明します。
• 読みやすく平易な言葉を使い、短い文と親しみやすい用語を選びます。
• 対象ユーザー向けにテストされていない限り、機能に関する文言では慣用句、冗談、比喩、文化特有の表現を避けます。
• アイデンティティに関する質問では、インクルーシブな選択肢を用意し、情報が必要な理由を説明します。
• 感情的な状況を考慮します。ユーザーは、ストレスを感じていたり、悲嘆に暮れていたり、病気だったり、アクセスできなくなっていたり、金銭面を心配していたり、時間に追われていたりする可能性があります。
• 翻訳で文字列が長くなる場合や、変数の位置変更、複数形への対応、翻訳者向けのコンテキストメモに対応できるようにします。

フロントエンド実装のガイダンス

フロントエンドに関する推奨事項を示す際は、コンポーネントの動作の一部として文言も含めます。

セマンティック HTML と ARIA

• 入力項目に関連付けた実際の <label> 要素を使用します。
• アクションには <button>、ナビゲーションには <a> を使用します。
• 情報の階層を反映した見出しを使用します。
• aria-describedby を使って、補足テキストやエラーテキストをフィールドに関連付けます。
• 検証に失敗した場合は、aria-invalid="true" を使用します。
• 緊急性の高い検証や状態の更新には、role="alert" または適切なライブリージョンを使用します。ただし、過剰な通知は避けます。
• モーダルを開いた後、フォーム送信に失敗した後、ルートが変わった後、破壊的な操作を確認した後に、フォーカスを管理します。
• フォーカスアウトラインを削除しないでください。

コンポーネント／状態の構成

関連する各状態の文言を記載します。

• デフォルト
• ホバー／フォーカス時にテキストが変化する場合
• 読み込み中
• 空
• 一部表示
• 成功
• 警告
• エラー
• オフライン
• 権限なし
• 無効
• 破壊的な操作の確認
• 元に戻す／再試行

デザインシステムとの統合

• 個々の文字列だけでなく、再利用可能なコンテンツパターンに名前を付けます。
• 推奨用語と使用禁止用語を保存します。
• ラベル、CTA ラベル、補足テキスト、エラー、空の状態、読み込み中、確認、通知の例を示します。
• 実装で再利用が必要な場合はコンテンツトークンまたは文字列 ID を使用しますが、コンテキストが分からなくなる抽象的な ID は避けます。
• 原文の文字列はローカライズ可能な状態に保ちます。コード内で文の断片を連結しないでください。

レスポンシブ対応とローカライズに関する考慮事項

• 翻訳によって文言が長くなることを想定します。
• 英語の短い文字列にしか対応できないレイアウトは避けます。
• 改行だけで意味を表現しないでください。
• CTA、タブ、ナビゲーション、トースト、表の見出しの切り詰め動作をテストします。
• 変数、トーン、コンテキストに関する翻訳者向けコメントを追加します。

品質チェックリスト

UX の文言を確定する前に、次の点を確認します。

• ユーザーの主なタスクが明確です。
• 各文字列に、案内、指示、動機付け、確認、警告、問題解決、説明のいずれかの役割があります。
• 再設計すべき壊れたインタラクションを、文言で補おうとしていません。
• ボタンとリンクで、実行される結果が分かります。
• フォームに表示ラベルと役立つ制約が付いています。
• 機微な情報を尋ねる際、そのデータが必要な理由を説明しています。
• エラーはユーザーを責めずに、問題と次のステップを示しています。
• 空の状態には、可能な場合は役立つ次のアクションが含まれています。
• 成功の状態では、重要な結果を確認できます。
• トーンが感情的な状況に合っています。
• 表現と用語に一貫性があります。
• 文言は簡潔でありながら、分かりにくくありません。
• アクセシビリティに関する状態を実装できます。
• ローカライズによって UI が崩れません。
• 影響の大きい文言には、検証または測定の計画があります。
• 実装が重要な場合、推奨事項にフロントエンド向けの注記が含まれています。

references/checklists.md のチェックリスト全体を使用してください。

避けるべきよくある間違い

• UI の完成後に、UX ライティングを言葉選びの作業として扱う。
• 明確さを標準で適用せずに、ユーザーに「分かりやすくしましょうか？」と尋ねる。
• 操作の結果が重要な場面で、「送信」「続行」「OK」「保存」を使う。
• 表示ラベルをプレースホルダーテキストに置き換える。
• UI の不具合を修正せず、説明だけで済ませる。
• 親しみやすい言葉で、ユーザーを操るビジネス上の目的を隠す。
• エラー、拒否、支払い失敗、本人確認、法務、セキュリティ、医療、金融に関する状態でユーモアを使う。
• 理由を説明せずに、デリケートな人口統計情報や個人情報を尋ねる。
• ユーザー向けの文面に、技術的なエラーコードやバックエンド用語を使う。
• ナビゲーション、フォーム、手順、エラーでブランド色を過度に打ち出す。
• 行き止まりになる空の状態を作る。
• ユーザーの行動に役立たない通知を送る。
• ローカライズできない、または支援技術で読み上げられない文字列を書く。

アンチパターンの全一覧は、references/anti-patterns.md を参照してください。

• 状態、制約、実装の背景を示さずに文面を納品する。

ユーザーへの推奨事項の説明方法

個人の好みではなく、ユーザーへの影響を基準に推奨事項を説明してください。

次の構成を使ってください。

I recommend [copy/pattern] because [user goal or risk]. It improves [comprehension/action/trust/recovery/accessibility]. Use [alternative] only if [context/constraint].

複数の選択肢を提示する場合は、目的を明示してください。

• 明確さ重視／標準
• より親しみやすく
• よりフォーマルに
• 信頼感を高める
• UI のスペースが限られる場合に短く
• アクセシブル／エラーに配慮
• レビュー待ちの法務／コンプライアンス対応

タスク、状態、ユーザーのニーズを説明せずに、「こちらのほうがよく聞こえます」とだけ言うのは避けてください。