writing-ui-text

画面とbotがユーザーに見せる日本語の規則。文章の書き方（/ukwhatn-writing）とは別の規約で、短さと一貫性を読みやすさより優先する場面が多い。

既存設定との関係

• PJに文言ガイド・用語表があれば、そちらが優先する。本スキルは、PJ側に規定の無い論点の既定値として使う。PJのガイドと本スキルが食い違う箇所を見つけたら、PJ側に合わせたうえで食い違いを報告する
• 画面に置く文字の取捨（何を画面に出すか）は ~/.claude/context/ui-artifact-standards.md、型の選び方とレイアウトは /designing-ui スキルが真実源。本スキルは、出すと決めた文字の書き方を扱う
• 各規則の出典と、ソース間で食い違う論点の採否は references/sources.md。用字用語と操作の語彙は references/terms.md

手順

1. 対象の画面・応答に出る文字を全部列挙する。見出し・ラベル・ボタン・説明・空状態・読み込み中・エラー・通知・aria-label・title 属性・サーバーから届いて表示される文を含める。コード上の置き場所が分かれていても1つの表にする
2. PJの文言ガイドと用語表を読む。無ければ、同じ対象を指す語が複数無いかを列挙した文字から拾い、用語表を先に作る（1つの対象に1つの語）
3. 下の規則で1件ずつ判定し、直す。直す理由を規則の名前で言えないものは直さない（好みの書き換えは、別の画面との不一致を新しく作る）
4. 同じ種類の要素を横に並べて揃っているかを見る（全画面の保存ボタン、全画面の空状態、全エラー文）。1画面の中で整っていても、画面間で割れていれば直す
5. 文言を変えたら、その文言を期待値に持つテストと、同じ文言の複製（クライアントの既定文とサーバーの文など）を検索して合わせる

規則

1. 画面に書かないもの

その文を消しても、読む人の次の操作と判断が変わらないなら書かない。

• 仕組みの説明を書かない: 処理の経路・ジョブ名・キャッシュ・同期の周期・データの保存先・内部の分類名・テーブルやキューの名前
• 「何をしないか」の説明を書かない（「〜は変更されません」）。書くのは、ユーザーが変更されると誤解して操作を誤る場面だけ
• 要素が何であるかの説明・凡例をラベルに書かない。説明が要ると感じたら、要素の名前か配置を直す
• 反映までの時間のように操作の後で要る情報は、入力欄の説明に置かず、保存後の通知に書く。数値は、約束できるものだけを書く
• 内部の識別子・英語のエラー文・HTTPステータス・例外の文字列を出さない。調査に要る値はログに出す
• 役割名・開発上の呼称・略語をそのまま出さない。その領域の利用者が普段使う語にする。利用者の間で定着した略語は残してよい（定着しているかは推測せず、PJの用語表か利用者に確認する）

2. ボタン・メニュー

• 押すと起きる操作を動詞で書く。和語の動詞は終止形（戻る・閉じる・取り込む）、「漢語＋する」は「する」を省く（保存・削除・追加）
• 対象を付けるときの助詞は「を」（権限を追加・CSVを取り込む）
• 「OK」「はい」「実行」を、操作を確定するボタンに使わない。確定するボタンは、その操作の動詞にする
• 取りやめるボタンは「キャンセル」に固定する
• 同じ操作には全画面で同じ語を使う（保存／登録／更新を混ぜない）。語の選び方は references/terms.md
• 移動先を示すときは、具体的な場所なら「に」（一覧に戻る）、相対的な位置なら「へ」（次へ・前へ）
• リンクを「こちら」「詳細」にしない。移動先の名前を書く

3. 見出し・画面タイトル・項目名

• 名詞で書く。対象を付けるときの助詞は「の」（権限の追加）。ボタン（権限を追加）と助詞で区別する
• 一覧の画面タイトルと表の見出しに「一覧」を付けない（対象の名前だけにする）。戻るリンクは「◯◯一覧に戻る」と書く
• 句点を付けない
• 英語の見出し・列名を残さない。ライブラリや雛形の既定値（Loading、No data、Page Information の類）も対象
• 固有名詞（サービス名・製品名）と、利用者がその綴りで認識している語は原語のままにする

4. 入力欄

• ラベルは項目の名前だけにする。入力の条件（形式・文字数・使える文字）は説明文に書き、入力する前から見える位置に出す
• 説明と入力例をプレースホルダーに書かない（入力を始めると消え、入力中に確認できない）。プレースホルダーは空のままにするか、書式の見本（name@example.com）に限る
• 説明文は敬体で、動詞まで書く（「100文字以内で入力してください。」）。1つの説明に書くのは入力の条件だけ
• 読まなくても入力できる補足は、説明文と分けて入力欄の下に置くか、書かない
• 必須・任意の示し方は、PJで1つに決める（少ない方にだけ印を付ける）。印はラベルに付け、プレースホルダーに書かない
• 入力例は「例：」で始める

5. 空状態・読み込み中

• 空状態は「何が無いか」を1文で書き、次に取れる操作があればボタンかリンクを置く（「案件はありません」＋［案件を追加］）
• 検索・絞り込みの結果が0件のときは、データが無いときと文を分ける（「条件に合う案件はありません」）
• 読み込み中の表示は全画面で1つの語にする（「読み込み中…」）
• 表や定義リストで値が無い項目は空白にする。ユーザーが入力できない項目だけ「-」を出す

6. エラー

• 事象・原因・対処の3要素で書く（「保存できませんでした。タイトルが100文字を超えています。100文字以内にしてください。」）
• 幅が足りないときは、原因、対処、事象の順に残す
• 事象は「〜できませんでした」と、ユーザーができなかったことで書く（PJが「〜に失敗しました」で統一済みならそれに従う。混ぜない）
• 原因が分からないときは、事象と対処だけ書く（「保存できませんでした。時間をおいて、やり直してください。」）。「エラーが発生しました」だけで終わらせない
• ユーザーを責める語（不正・無効・違反）を使わず、正しい入力の仕方を書く（「半角数字で入力してください」）
• 「申し訳ございません」は、サービス側の障害で操作が続けられないときだけ使う
• 入力欄のエラーは、その入力欄の近くに出す
• サーバーのエラーメッセージをそのまま画面に出す経路では、サーバー側の文もUI文言として扱う。利用者に届く文と、ログ・開発者向けの文を分け、届く文には本節の規則を適用する。入力検証ライブラリの既定の応答（英語・JSON）がそのまま届く経路が無いかも確かめる

7. 確認ダイアログ

• 確認を挟むのは、元に戻せない操作と、影響が他のデータ・他の人に及ぶ操作に限る
• タイトルは「{対象}の{操作}」、確定ボタンは「{操作}」、取りやめは「キャンセル」。タイトルとボタンの操作名を一致させる
• 本文は疑問文で、対象を名前で示す（「「{名前}」を削除しますか？　この操作は元に戻せません。」）。「〜してもよろしいですか？」は使わない
• 他に消えるもの・止まるものがあれば、具体的に1文で足す（「このキーを使っている連携は動かなくなります。」）
• ボタンが何をするかの説明を本文に書かない

8. 完了・進行の通知

• 操作の結果は「{対象}を{操作}しました」と書く。「〜が完了いたしました」「〜完了」にしない
• 画面の変化で結果が分かるときは通知を出さない（一覧に行が増えた、詳細画面に移った）。完了を知らせるだけのダイアログは出さない
• 後で処理される操作は「{処理}を受け付けました」と書き、終わったことにしない
• 状態を示すラベルは「◯◯前・未◯◯・◯◯中・◯◯待ち・◯◯済み・完了」の型で書き、操作の結果の文（〜しました）と混ぜない

9. 文体

• 説明・エラー・通知は敬体（です・ます）。常体と混ぜない
• 敬語は「〜してください」「〜しました」まで。「ご確認ください」「いただけますよう」「させていただきます」「ございます」は使わない
• 主語と二人称は省く（「あなたの」「私たちは」を書かない）
• 「〜することができます」は「〜できます」、「〜を行う」は「〜する」。格助詞は省かない（「項目名を変更します」）
• 二重否定を使わない
• 1文に指示を1つ。3つ以上の条件は箇条書きにする

10. 表記

references/terms.md に表がある。要点:

• 数字は半角の算用数字、3桁区切りは半角カンマ。「か月」「か所」
• 英数字と日本語の間に空白を入れない（PJが入れる方式で統一済みならそれに従う）
• 括弧・コロン・疑問符は全角。「？」の後に文が続くときは全角の空白を1つ置く
• 省略は三点リーダー「…」を1つ。ピリオドを並べない
• カタカナ語の長音は、-er・-or・-ar で終わる語に付け、-y で終わる語に付けない

11. チャットbotの応答

• 画面と同じ規則を適用する。成功は「〜しました」、エラーは事象・原因・対処
• コマンドやオプションの説明は、何が起きるかを名詞止めか「〜します」のどちらかに統一して書く。内部の実装方針（確認の有無、経由するサービス）を書かない
• 絵文字で状態を示すなら、意味ごとに1つに決めて表にする。色と絵文字で同じ意味を二重に示さない
• コマンド名・メニュー名のようにプラットフォームへ登録する文字列は、変更すると再登録まで動かなくなることがある。変える前に登録の仕組みを確かめ、手順を変更の説明に書く

悪い例と直した例

悪い例	直した例	規則
（入力欄の説明）テキスト形式で100文字まで入れてください。保存すると数分で表示が変わります。元の一覧は書き換えません。	（説明）100文字以内で入力してください。改行と装飾は使えません。<br>（保存後の通知）自己紹介を保存しました。反映まで数分かかります。	1・4・8
（ボタン）保存する / OK / 登録 が画面ごとに違う	（ボタン）保存	2
（見出し）Page Information	（見出し）ページ情報	3
エラーが発生しました (500)	保存できませんでした。時間をおいて、やり直してください。	6
不正な値です	半角数字で入力してください。	6
（確認）本当に削除してもよろしいですか？［OK］［キャンセル］	（タイトル）APIキーの削除<br>「{名前}」を削除しますか？　この操作は元に戻せません。［キャンセル］［削除］	7
データがありません	条件に合う案件はありません	5
同期をリクエストしました（jobId: 123）。次回の定期実行までに反映されます。	同期を受け付けました。	1・8
ご確認いただけますようお願いいたします	確認してください	9

Gotchas

• 既定文言は部品の中にある。共有部品のpropsの既定値・aria-label・読み上げ専用の文字は、画面のファイルを検索しても出てこない。部品側を先に直すと、呼び出し側の上書きとの不一致が見えるようになる
• 同じ文が複数の場所に複製されている。クライアントの予備の文とサーバーの文、定数と直書き。片方だけ直すと、経路によって違う文が出る
• 画面に出る経路を確かめてから直す。サーバーの文のうち、クライアントが固定文に置き換えて捨てているものは画面に出ない。逆に、クライアントが想定していない形の応答は、想定外の文字列として出ることがある。応答の形は実際に1件取得して確かめる
• 文言を直しても読みにくさが残るときは、要素の設計を疑う。長い注意書きが要る画面は、文を磨くより先に、操作の順序か部品を直す
• 用語を置き換えるときは、利用者が検索・口頭で使っている語を消さない。漢字語への言い換えは、言い換えた語のほうが利用者に通じるときだけ行う