docs-voice

React ドキュメントの音声とスタイル

共通ルール

• 見出しや独立した概念として React の概念を指す場合は、React の用語を大文字で表記します。
  • コア：Hook、Effect、State、Context、Ref、Component、Fragment
  • 並行処理：Transition、Action、Suspense
  • サーバー：Server Component、Client Component、Server Function、Server Action
  • パターン：Error Boundary
  • Canary：Activity、View Transition、Transition Type
  • 文章中： 説明語と組み合わせる場合は小文字を使います：「state variable」「state updates」「event handler」。概念が単独で使われる場合や見出しでは大文字にします：「State is isolated and private」
  • 一般的な用法では小文字のままにします：「the page transitions」「takes an action」
• 製品名： ESLint、TypeScript、JavaScript、Next.js（小文字にしない）
• 重要な概念には太字を使います：state variable、event handler
• 新しく定義する用語にはイタリック体を使います：event handlers
• API にはインラインコードを使います：useState、startTransition、<Suspense>
• 「simple」「easy」「just」や所要時間の目安は避けます
• 違いは「利点・欠点」ではなく「機能」として説明します
• 受け身の表現や専門用語を避けます

ページの種類ごとのトーン

種類	トーン	例
学習	会話調	「このようになります……」「こう思うかもしれません……」
リファレンス	技術的	「useState は最上位で呼び出します……」「この Hook は……を返します」
ブログ	正確	マーケティングではなく、事実に焦点を当てる

注： Pitfall コンポーネントと DeepDive コンポーネントでは、リファレンスページであっても、説明的な補足として多少会話調の表現（「こう疑問に思うかもしれません……」「こうしたくなるかもしれません……」）を使えます。

専門用語を避ける

パターン： まず動作を説明し、その後で名称を示します。

✅ 「React は、イベントハンドラー内のすべてのコードが実行されるまで待ってから、state の更新を処理します。これをバッチ処理と呼びます。」

❌ 「React はバッチ処理を使って state の更新をアトミックに処理します。」

避けるか、説明を加える用語：

専門用語	平易な表現
atomic	すべて実行するか、まったく実行しない／まとめて処理する
idempotent	同じ入力なら同じ出力
deterministic	予測可能／毎回同じ結果
memoize	結果を記憶し、再計算を省く
referentially transparent	（避ける — 動作を説明する）
invariant	常に真でなければならないルール
reify	（避ける — 何が作られるのかを説明する）

リファレンスページで使用できる技術用語：

• 「stale closures」— 標準的な JavaScript／React 用語で、注意点の説明に使えます
• 「stable identity」— レンダリング間で一貫したオブジェクト参照を表す React 用語です
• 「reactive」— 値が変わると再レンダリングを引き起こすことを表す React 用語です
• リファレンスページでは、これらを説明する必要はありません（読者は知っていることが前提です）

定着した比喩は控えめに使います。概念を導入するときに一度だけ使い、繰り返しません。

概念	比喩
Components／React	キッチン（コンポーネントは料理人、React はウェイター）
レンダーフェーズ	レストランでの注文（トリガー／レンダー／コミット）
State のバッチ処理	ウェイターが注文をすべて集めてからキッチンに伝える
State の動作	ある時点のスナップショット／写真
State の保存先	React が state を「棚」に置いておく
State の目的	コンポーネントの記憶
純粋関数	レシピ（同じ材料なら同じ料理）
純粋関数	数式（y = 2x）
Props	調整できる「つまみ」
Children prop	親が埋める「穴」
Keys	フォルダー内のファイル名
JSX の波括弧	「JavaScript をのぞく窓」
宣言型 UI	タクシー運転手（道順ではなく目的地を伝える）
命令型 UI	曲がり方を順番に示すナビゲーション
State の構造	データベースの正規化
Refs	React が追跡しない「秘密のポケット」
Effects／Refs	React から抜け出す「非常口」
Context	CSS の継承／「テレポート」
カスタム Hook	デザインシステム

よく使う文章のパターン

間違ったコードと正しいコード：

\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`

\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`

表での比較：

| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |

リンク：

[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)

コードスタイル

• createElement より JSX を優先します
• const／let を使用し、var は使用しません
• トップレベルの関数には名前付き関数宣言を優先します
• this の保持が必要なコールバックにはアロー関数を使用します

バージョンのドキュメント

API がバージョン間で変更される場合：

Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`

In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`

パターン：

• 新しい API には「React 19 以降では…」を使用します
• レガシーパターンには「以前のバージョンの React では…」を使用します