From 9774ac42f863433d94eb4538db9d59460dd81629 Mon Sep 17 00:00:00 2001
From: Kae <kaehehehe@gmail.com>
Date: Sun, 14 Sep 2025 23:07:08 +0900
Subject: [PATCH] docs: dd Japanese translations

---
 fundamentals/a11y/.vitepress/config.mts       |  83 +++++-
 fundamentals/a11y/ja/alt-text/image-alt.md    | 135 +++++++++
 fundamentals/a11y/ja/eslint/design-system.md  | 195 +++++++++++++
 fundamentals/a11y/ja/eslint/rules.md          | 273 ++++++++++++++++++
 fundamentals/a11y/ja/index.md                 |  56 ++--
 fundamentals/a11y/ja/overview.md              |  14 +
 fundamentals/a11y/ja/playground.md            |  33 +++
 .../a11y/ja/predictability/fake-button.md     |  82 ++++++
 fundamentals/a11y/ja/predictability/form.md   | 100 +++++++
 fundamentals/a11y/ja/principles.md            |  29 ++
 .../semantic/duplicate-interactive-element.md | 155 ++++++++++
 .../a11y/ja/semantic/required-label.md        | 148 ++++++++++
 .../a11y/ja/structure/button-inside-button.md | 128 ++++++++
 .../a11y/ja/structure/table-row-link.md       |  82 ++++++
 fundamentals/a11y/ja/why.md                   |  70 +++++
 15 files changed, 1553 insertions(+), 30 deletions(-)
 create mode 100644 fundamentals/a11y/ja/alt-text/image-alt.md
 create mode 100644 fundamentals/a11y/ja/eslint/design-system.md
 create mode 100644 fundamentals/a11y/ja/eslint/rules.md
 create mode 100644 fundamentals/a11y/ja/overview.md
 create mode 100644 fundamentals/a11y/ja/playground.md
 create mode 100644 fundamentals/a11y/ja/predictability/fake-button.md
 create mode 100644 fundamentals/a11y/ja/predictability/form.md
 create mode 100644 fundamentals/a11y/ja/principles.md
 create mode 100644 fundamentals/a11y/ja/semantic/duplicate-interactive-element.md
 create mode 100644 fundamentals/a11y/ja/semantic/required-label.md
 create mode 100644 fundamentals/a11y/ja/structure/button-inside-button.md
 create mode 100644 fundamentals/a11y/ja/structure/table-row-link.md
 create mode 100644 fundamentals/a11y/ja/why.md

diff --git a/fundamentals/a11y/.vitepress/config.mts b/fundamentals/a11y/.vitepress/config.mts
index dd762214..430d0ade 100644
--- a/fundamentals/a11y/.vitepress/config.mts
+++ b/fundamentals/a11y/.vitepress/config.mts
@@ -24,7 +24,88 @@ export default defineConfig({
     ja: {
       label: "日本語",
       lang: "ja",
-      themeConfig: { nav: [{ text: "ホーム", link: "/ja" }] }
+      themeConfig: {
+        nav: [{ text: "ホーム", link: "/ja/" }],
+        sidebar: [
+          {
+            text: "紹介",
+            items: [
+              { text: "はじめに", link: "/ja/overview" },
+              { text: "体験してみる", link: "/ja/playground" },
+              { text: "アクセシビリティを守る理由", link: "/ja/why" },
+              { text: "主要原則", link: "/ja/principles" }
+            ]
+          },
+          {
+            text: "実践ガイド",
+            items: [
+              {
+                text: "1. 構造を明確にする",
+                items: [
+                  {
+                    text: "ボタンの中にボタンを入れない",
+                    link: "/ja/structure/button-inside-button"
+                  },
+                  {
+                    text: "テーブル行に直接onClickを付けない",
+                    link: "/ja/structure/table-row-link"
+                  }
+                ]
+              },
+              {
+                text: "2. 意味を正確に伝える",
+                items: [
+                  {
+                    text: "インタラクティブ要素に名前を付ける",
+                    link: "/ja/semantic/required-label"
+                  },
+                  {
+                    text: "同じ名前の要素には説明を追加する",
+                    link: "/ja/semantic/duplicate-interactive-element"
+                  }
+                ]
+              },
+              {
+                text: "3. 予測可能な動作を作る",
+                items: [
+                  {
+                    text: "ボタンの役割と動作を一致させる",
+                    link: "/ja/predictability/fake-button"
+                  },
+                  {
+                    text: "入力要素は &lt;form&gt; で包む",
+                    link: "/ja/predictability/form"
+                  }
+                ]
+              },
+              {
+                text: "4. 視覚情報を補完する",
+                items: [
+                  {
+                    text: "画像とアイコンに適切な代替テキストを提供する",
+                    link: "/ja/alt-text/image-alt"
+                  }
+                ]
+              }
+            ]
+          },
+          {
+            text: "発展ガイド",
+            items: [
+              {
+                text: "ESLintでアクセシビリティを改善する",
+                items: [
+                  { text: "主要ルール紹介", link: "/ja/eslint/rules" },
+                  {
+                    text: "デザインシステムと組み合わせる",
+                    link: "/ja/eslint/design-system"
+                  }
+                ]
+              }
+            ]
+          }
+        ]
+      }
     },
     "zh-hans": {
       label: "简体中文",
diff --git a/fundamentals/a11y/ja/alt-text/image-alt.md b/fundamentals/a11y/ja/alt-text/image-alt.md
new file mode 100644
index 00000000..8b0b46e8
--- /dev/null
+++ b/fundamentals/a11y/ja/alt-text/image-alt.md
@@ -0,0 +1,135 @@
+# 画像やアイコンに適切な代替テキストを提供する
+
+画像やアイコンを使うときは、スクリーンリーダー利用者のために適切な代替テキストを提供する必要があります。ただし、すべての画像に代替テキストが必要というわけではありません。このドキュメントでは、いつ・どのように代替テキストを付けるべきかを説明します。
+
+## 代替テキストを提供すべきとき
+
+画像やアイコンが**情報を伝える、または機能を表す**場合は、必ず意味のある代替テキストを付けましょう。画像やアイコンしかない場面では、代替テキストが視覚情報を補う唯一の手段になるため、テキストがないとユーザー体験が大きく損なわれます。
+
+### ❌ 誤った例：意味のあるアイコンに代替テキストがない
+
+次のように代替テキストを空にすると、スクリーンリーダー利用者はこのボタンが何の機能なのか分かりません。
+
+```html
+<button>
+  <img src="search-icon.svg" alt="" />
+</button>
+```
+
+### ✅ 正しい例：意味のあるアイコンに代替テキストを付ける
+
+```html
+<button>
+  <img src="search-icon.svg" alt="検索" />
+</button>
+```
+
+## 代替テキストを付けなくてよいとき
+
+### 1. 装飾目的の画像
+
+画像が単なる装飾で、視覚的効果だけを目的としているなら、空の代替テキスト（`alt=""`）を使いましょう。
+
+#### ❌ 誤った例：装飾画像に不要な代替テキスト
+
+スクリーンリーダーがこのテキストを読み上げ、不要な情報となってしまいます。
+
+```html
+<img src="divider.png" alt="区切り線" />
+```
+
+#### ✅ 正しい例：装飾画像には空のalt属性
+
+```html
+<img src="divider.png" alt="" />
+```
+
+### 2. 画像の周辺に説明テキストがある場合
+
+画像の近くに十分な説明があるなら、画像側は空の代替テキストを使いましょう。
+
+#### ❌ 誤った例：重複する代替テキスト
+
+次のように周囲に説明があるのに、同じ内容を代替テキストとしても提供すると、スクリーンリーダーでは「新製品スマートフォン 新製品スマートフォン」のように重複して読み上げ、混乱の原因になります。
+
+```html
+<figure>
+  <img src="product.jpg" alt="신제품 스마트폰" />
+  <figcaption>新製品スマートフォン</figcaption>
+</figure>
+```
+
+#### ✅ 正しい例：キャプションがある画像では省略
+
+```html
+<figure>
+  <img src="product.jpg" alt="" />
+  <figcaption>新製品スマートフォン</figcaption>
+</figure>
+```
+
+### 3. アイコンがテキストと一緒に使われる場合
+
+アイコンがテキストと一緒にボタンやリンクで使われるときは、空の代替テキストを使いましょう。
+
+#### ❌ 誤った例：不要な重複情報
+
+スクリーンリーダーで「削除 アイコン 削除」と重複して読まれてしまい、かえってわかりにくくなります。
+
+```html
+<button>
+  <img src="trash-icon.svg" alt="削除アイコン" />
+  削除
+</button>
+```
+
+#### ✅ 正しい例：テキストがあるアイコンでは省略
+
+```html
+<button>
+  <img src="trash-icon.svg" alt="" />
+  削除
+</button>
+```
+
+## 効果的な代替テキストを書く
+
+良い代替テキストは短く、明確で、画像の目的に合っている必要があります。以下の原則を参考に、状況に合わせて記述しましょう。
+
+### 1. 明確かつ具体的に書く
+
+代替テキストは、その画像が伝える意味を正確に説明するべきです。あいまいな言葉や抽象的な表現は、ユーザーが画像から得るべき情報を理解しづらくします。
+
+| 区分       | 例                 | 説明                                                   |
+| ---------- | -------------------- | ------------------------------------------------------ |
+| ❌ 悪い例 | "アイコン"             | アイコンの用途や機能に関する情報がありません。       |
+| ✅ 良い例 | "検索"               | アイコンが何を意味するかを明確に伝えます。       |
+| ❌ 悪い例 | "グラフ"             | このグラフが何を示すのか分かりません。  |
+| ✅ 良い例 | "2023年の売上グラフ" | グラフがどのデータを示すかを具体的に説明します。 |
+
+### 2. 不要な語を省く
+
+代替テキストはスクリーンリーダーが読むためのものなので、「アイコン」「ボタン」のような語はたいてい冗長です。スクリーンリーダーは、画像を含む要素の役割（ボタンなど）を既に理解しているため、代替テキストでは情報だけを簡潔に伝えるのが望ましいです。
+
+| 区分       | 例          | 説明                                                                                    |
+| ---------- | ------------- | --------------------------------------------------------------------------------------- |
+| ✅ 良い例 | "検索"        |                                                                                         |
+| ❌ 悪い例 | "検索アイコン" | スクリーンリーダーは「検索、ボタン」と読むため、「アイコン」は重複して不要です。 |
+| ✅ 良い例 | "閉じる"        |                                                                                         |
+| ❌ 悪い例 | "閉じるボタン"   | ボタンという役割は既に明らかなので、テキストでは省略したほうがすっきりします。                  |
+
+### 3. 画像の目的と文脈を考慮する
+
+同じ画像でも、使われる文脈によって適切な代替テキストは変わり得ます。次のコードで「矢印」という説明は、見た目を述べているだけで、ユーザーにどんな操作が可能かは伝えません。
+
+「前のページへ移動」のような代替テキストは、機能を正確に説明し、ユーザーの期待と実際の動作を一致させます。
+
+```html
+<!-- ❌ 誤った例：文脈を考慮しない代替テキスト -->
+<img src="arrow.png" alt="矢印" />
+<img src="arrow.png" alt="矢印" />
+
+<!-- ✅ 正しい例：文脈に合った代替テキスト -->
+<img src="arrow.png" alt="前のページへ移動" />
+<img src="arrow.png" alt="次のページへ移動" />
+```
diff --git a/fundamentals/a11y/ja/eslint/design-system.md b/fundamentals/a11y/ja/eslint/design-system.md
new file mode 100644
index 00000000..04564a67
--- /dev/null
+++ b/fundamentals/a11y/ja/eslint/design-system.md
@@ -0,0 +1,195 @@
+# デザインシステムと組み合わせる
+
+多くの組織ではデザインシステムを導入し、`<MyButton>`や`<MyTxt>`のような独自コンポーネントを使用しています。しかし`eslint-plugin-jsx-a11y`は基本的に標準の HTMLタグに対してのみ動作するため、デザインシステムのコンポーネントにもアクセシビリティ規則を適用するには追加設定が必要です。
+
+## 1. 컴포넌트 매핑하기
+
+たとえば`<MyButton>`コンポーネントが実際には`<button>`を、`<MyTxt>`が`<span>`を出力するなら、次のようにESLint設定のsettingsにマッピングを追加してください。
+
+:::tabs key:bundler-object-entry
+== flat config
+
+```js{9-16}
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      'jsx-a11y/control-has-associated-label': 'error',
+    },
+    settings: {
+      'jsx-a11y': {
+        components: {
+          MyButton: 'button',
+          MyTxt: 'span'
+        },
+      },
+    }
+  }
+];
+```
+
+== legacy config
+
+```js{9-16}
+{
+  "plugins": ["jsx-a11y"],
+  "extends": [
+    "plugin:jsx-a11y/recommended"
+  ],
+  "rules": {
+    "jsx-a11y/control-has-associated-label": "error"
+  },
+  "settings": {
+    "jsx-a11y": {
+      "components": {
+        "MyButton": "button",
+        "MyTxt": "span"
+      },
+    },
+  }
+}
+```
+
+:::
+
+こうしておくと、`<MyButton>`・`<MyTxt>`にもbutton・spanに対するアクセシビリティ規則が同様に適用されます。
+
+## 2. Polymorphic prop（多様なタグレンダリング）対応
+
+複数のHTMLタグやコンポーネントに柔軟にレンダリングできるコンポーネントでは、`as`のようなプロパティ（prop）を使うことがよくあります。これを多相（polymorphic）コンポーネントと呼びます。
+
+たとえば、ボタンコンポーネントを`<button>`だけでなく`<a>`や`<div>`など他のタグでもレンダリングしたい場合、次のように`as`を使えます。
+
+```jsx
+<MyButton as="a" href="/home">
+  ホームへ
+</MyButton>
+```
+
+このように`as`などのpropで多相レンダリングを提供するコンポーネントを運用する際は、そのprop名を`polymorphicPropName`オプションで明示してください。そうすることで、アクセシビリティのESLint規則がデザインシステムのコンポーネントに正しく適用されます。
+
+:::tabs key:bundler-object-entry
+== flat config
+
+```js{11}
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      'jsx-a11y/control-has-associated-label': 'error',
+    },
+    settings: {
+      'jsx-a11y': {
+        polymorphicPropName: 'as',
+        components: {
+          MyButton: 'button',
+          MyTxt: 'span'
+        },
+      },
+    }
+  }
+];
+```
+
+== legacy config
+
+```js{11}
+{
+  "plugins": ["jsx-a11y"],
+  "extends": [
+    "plugin:jsx-a11y/recommended"
+  ],
+  "rules": {
+    "jsx-a11y/control-has-associated-label": "error"
+  },
+  "settings": {
+    "jsx-a11y": {
+      "polymorphicPropName": "as",
+      "components": {
+        "MyButton": "button",
+        "MyTxt": "span"
+      },
+    },
+  }
+}
+```
+
+:::
+
+## 3. control-has-associated-labelのカスタマイズ
+
+デザインシステムのコンポーネントが`children`の代わりに別のprop（例：`contents`）でテキストを受け取る場合、既定設定だけでは `jsx-a11y/control-has-associated-label`が通らないことがあります。
+
+たとえば次のように`contents`というpropでテキストを渡し、実際には`<button>`要素としてレンダリングされるケースを考えます。
+
+```jsx
+<MyCard contents="カード内容" />
+```
+
+この場合、ESLintは適切なラベルがないと判断してエラーにすることがあります。これを解決するには、`labelAttributes`オプションに該当のprop名を追加してください。
+
+:::tabs key:bundler-object-entry
+== flat config
+
+```js{7-9}
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      'jsx-a11y/control-has-associated-label': [2, {
+        'labelAttributes': ['contents']
+      }]
+    },
+    settings: {
+      'jsx-a11y': {
+        polymorphicPropName: 'as',
+        components: {
+          MyButton: 'button',
+          MyTxt: 'span',
+          MyCard: 'button'
+        },
+      },
+    }
+  }
+];
+```
+
+== legacy config
+
+```js{7-9}
+{
+  "plugins": ["jsx-a11y"],
+  "extends": [
+    "plugin:jsx-a11y/recommended"
+  ],
+  "rules": {
+    "jsx-a11y/control-has-associated-label": [2, {
+      "labelAttributes": ["contents"]
+    }]
+  },
+  "settings": {
+    "jsx-a11y": {
+      "polymorphicPropName": "as",
+      "components": {
+        "MyButton": "button",
+        "MyTxt": "span",
+        "MyCard": "button"
+      },
+    },
+  }
+}
+```
+
+:::
+
+この設定により、`<MyCard contents="カード内容" />`の`contents`がラベルとして認識され、アクセシビリティエラーなく利用できます。
+
+---
+
+このほかにも、デザインシステムにはさまざまなコンポーネントや prop パターンが存在します。詳細は[eslint-plugin-jsx-a11y 공식 문서](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)のsettingsとrulesのオプションを参照し、要件に合わせてカスタマイズしてください。
\ No newline at end of file
diff --git a/fundamentals/a11y/ja/eslint/rules.md b/fundamentals/a11y/ja/eslint/rules.md
new file mode 100644
index 00000000..f678b1c5
--- /dev/null
+++ b/fundamentals/a11y/ja/eslint/rules.md
@@ -0,0 +1,273 @@
+# 主要ルール紹介
+
+JSX 環境で[eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)を使うと、アクセシビリティの問題を事前に発見して改善できます。ここでは主要なルールと対処方法を紹介します。
+
+## 1. 設定ガイド
+
+### インストール
+
+```bash
+yarn add -D eslint-plugin-jsx-a11y
+```
+
+### 適用方法
+
+`.eslintrc`または`eslint.config.js`に次のように追加してください。
+
+:::tabs key:bundler-object-entry
+== flat config
+
+```js
+import jsxA11y from "eslint-plugin-jsx-a11y";
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      "jsx-a11y/control-has-associated-label": "error"
+    }
+  }
+];
+```
+
+== legacy config
+
+```json
+{
+  "plugins": ["jsx-a11y"],
+  "extends": ["plugin:jsx-a11y/recommended"],
+  "rules": {
+    "jsx-a11y/control-has-associated-label": "error"
+  }
+}
+```
+
+:::
+
+## 2. 主要ルールと対処法
+
+### alt-text
+
+`<img />`には[代替テキスト(alt)](../alt-text/image-alt.md)が必要です。情報を伝えない画像であっても`alt`属性自体は空でも必ず付け、画像の目的と文脈に合う内容にしましょう。
+
+#### リンク内に画像だけがある場合
+
+**❌ 誤った例**
+
+```jsx
+<a href="/home">
+  <img src="home.svg" />
+</a>
+```
+
+**✅ 正しい例**
+
+```jsx
+<a href="/home">
+  <img src="home.svg" alt="ホーム" />
+</a>
+```
+
+#### 情報を伝えない画像
+
+**❌ 誤った例**
+
+```jsx
+<img src="divider.png" alt="区切り線" />
+```
+
+**✅ 正しい例**
+
+```jsx
+<img src="divider.png" alt="" />
+```
+
+#### テキストと一緒のアイコン
+
+**❌ 誤った例**
+
+```jsx
+<button>
+  <img src="trash-icon.svg" alt="削除アイコン" />
+  削除
+</button>
+```
+
+**✅ 正しい例**
+
+```jsx
+<button>
+  <img src="trash-icon.svg" alt="" />
+  削除
+</button>
+```
+
+### control-has-associated-label
+
+インタラクティブ要素（入力フィールド、ボタン、セレクトなど）には、目的をユーザーに明確に伝える名前が必須です。名前がない／不明確な要素は、スクリーンリーダー利用者や音声アシスタント利用者に大きな不便を与えます。詳しくは[インタラクティブ要素に名前を付ける](../semantic/required-label)を参照してください。
+
+`eslint-plugin-jsx-ally`の recommendedではこのルールは既定で無効なので、次のように`rules`に明示的に追加して有効化してください。
+
+:::tabs key:bundler-object-entry
+== flat config
+
+```js{7}
+import jsxA11y from 'eslint-plugin-jsx-a11y';
+
+export default [
+  jsxA11y.flatConfigs.recommended,
+  {
+    rules: {
+      'jsx-a11y/control-has-associated-label': 'error',
+    }
+  }
+];
+```
+
+== legacy config
+
+```js{7}
+{
+  "plugins": ["jsx-a11y"],
+  "extends": [
+    "plugin:jsx-a11y/recommended"
+  ],
+  "rules": {
+    "jsx-a11y/control-has-associated-label": "error"
+  }
+}
+```
+
+:::
+
+#### アイコンボタンにラベルがない場合
+
+**❌ 誤った例**
+
+```jsx
+<button>
+  <img src="close.svg" alt="" />
+</button>
+```
+
+**✅ 正しい例**
+
+```jsx
+<button aria-label="閉じる">
+  <img src="close.svg" alt="" />
+</button>
+// または
+<button>
+  <img src="close.svg" alt="閉じる" />
+</button>
+```
+
+### no-noninteractive-element-interactions
+
+非インタラクティブ要素（`<div>`、`<span>`など）にクリックハンドラーを付ける場合は、必ず`role`などでインタラクティブ要素であることを明示してください。
+
+::: details インタラクティブ要素の一覧
+| 要素 | 条件 |
+|------|------|
+| `<a>` | - |
+| `<audio>` | controls属性がある場合 |
+| `<button>` | - |
+| `<details>` | - |
+| `<embed>` | - |
+| `<iframe>` | - |
+| `<img>` | usemap属性がある場合 |
+| `<input>` | typeがHidden stateでない場合 |
+| `<keygen>` | - |
+| `<label>` | - |
+| `<menu>` | typeがtoolbar stateの場合 |
+| `<object>` | usemap属性がある場合 |
+| `<select>` | - |
+| `<textarea>` | - |
+| `<video>` | controls属性がある場合 |
+:::
+
+::: info なぜ`role`のない非インタラクティブ要素にクリックハンドラーを付けてはいけないの？
+非インタラクティブ要素にクリックハンドラーだけを付けると、スクリーンリーダーなどの支援技術がその要素を正しく認識できず、スクリーンリーダー利用者やキーボード利用者を混乱させます。
+:::
+
+**❌ 誤った例**
+
+```jsx
+<div onClick={handleClick}>クリック</div>
+```
+
+**✅ 正しい例**
+
+```jsx
+<div role="button" tabIndex={0} onClick={handleClick}>
+  クリック
+</div>
+```
+
+### no-noninteractive-element-to-interactive-role
+
+`<main>`, `<area>`, `<h1>`, `<h2>`, `<img>`, `<li>`, `<ul>`, `<ol>`など意味のあるコンテナー要素に、`button`や`link`などの**インタラクティブな役割（role）**を与えてはいけません。意味に合ったタグを使いましょう。
+
+**❌ 誤った例**
+
+```jsx
+<main role="button" onClick={handleClick}>保存</main>
+<ul role="button" onClick={handleClick}>リスト</ul>
+<img role="button" onClick={handleClick} src="foo.png" />
+```
+
+**✅ 正しい例**
+
+```jsx
+<button onClick={handleClick}>保存</button>
+<a href="/list">リスト</a>
+```
+
+### no-noninteractive-tabindex
+
+非インタラクティブ要素に`tabIndex`を付けると警告になります。`tabIndex`はインタラクティブ要素にのみ使いましょう。不要なら削除し、必要なら適切なロールやイベントを付けてください。
+
+::: info なぜインタラクティブ要素にだけ`tabIndex`を付けるべき？
+`tabIndex`はキーボード利用者がTabで要素間を移動する際に使う属性です。非インタラクティブ要素に付けると次の問題を招きます。
+
+1. スクリーンリーダー利用者が、その要素を操作可能と誤解する
+2. キーボード利用者が予期しない要素にフォーカスしてしまう
+3. DOM の自然なフォーカス順序が崩れる
+
+したがって`tabIndex`は`<button>`、`<a>`、`<input>`、あるいは適切な`role`を付け実際に操作可能な要素に限定して使いましょう。
+
+:::
+
+**❌ 誤った例**
+
+```jsx
+<div tabIndex={0}>テキスト</div>
+```
+
+**✅ 正しい例**
+
+```jsx
+<span>テキスト</span>
+// または
+<div tabIndex={0} role="button">ボタン</div>
+```
+
+### tabindex-no-positive
+
+`tabIndex`に1以上の値を使うと、DOMの順序と異なるフォーカス移動になり、挙動の予測が難しくなります。0または-1のみを使いましょう。
+
+**❌ 誤った例**
+
+```jsx
+<button tabIndex={2}>確認</button>
+```
+
+**✅ 正しい例**
+
+```jsx
+<button tabIndex={0}>確認</button>
+```
+
+---
+
+さらに多くのルールと例は公式ドキュメントを参照してください: [eslint-plugin-jsx-a11y](https://github.com/jsx-eslint/eslint-plugin-jsx-a11y)
diff --git a/fundamentals/a11y/ja/index.md b/fundamentals/a11y/ja/index.md
index 2476dbfa..2307af29 100644
--- a/fundamentals/a11y/ja/index.md
+++ b/fundamentals/a11y/ja/index.md
@@ -1,33 +1,31 @@
 ---
+# https://vitepress.dev/reference/default-theme-home-page
 layout: home
-title: Bundling
-description: Frontend Bundling Guide (Coming Soon)
-comments: false
----
-
-<div class="coming-soon">
-  <h2>✨ Coming Soon</h2>
-  <p>Stay tuned! We're working on something awesome for you.</p>
-</div>
 
-<style>
-.coming-soon {
-  display: flex;
-  flex-direction: column;
-  align-items: center;
-  justify-content: center;
-  min-height: 60vh;
-  text-align: center;
-  color: var(--vp-c-text-2);
-}
+hero:
+  name: "A11y Fundamentals"
+  tagline: "フロントエンド・アクセシビリティのすべて"
+  image:
+    loading: eager
+    fetchpriority: high
+    decoding: async
+    src: /images/ff-symbol-gradient-webp-80.webp
+    alt: Frontend Fundamentals symbol
+  actions:
+    - text: はじめる
+      link: /overview
 
-.coming-soon h2 {
-  font-size: 2rem;
-  margin-bottom: 1rem;
-  border: none;
-}
-
-.coming-soon p {
-  font-size: 1.2rem;
-}
-</style>
+features:
+  - icon: 📦
+    title: なぜアクセシビリティを守るべきなのでしょうか？
+    details: 障害の有無にかかわらず、開発者を含むすべての人により良いWeb体験を提供できます。
+    link: /why
+  - icon: 🚀
+    title: 主要原則
+    details: 正しい構造、明確な意味、予測可能なインタラクション、視覚情報の補完という4つのコア原則を見ていきます。
+    link: /principles
+  - icon: 🔍
+    title: eslintでアクセシビリティを改善する
+    details: コード作成段階でアクセシビリティの問題を事前に発見・解決し、デザインシステムと組み合わせる方法を学びます。
+    link: /eslint/rules
+---
diff --git a/fundamentals/a11y/ja/overview.md b/fundamentals/a11y/ja/overview.md
new file mode 100644
index 00000000..d763cfe7
--- /dev/null
+++ b/fundamentals/a11y/ja/overview.md
@@ -0,0 +1,14 @@
+# はじめに
+
+アクセシビリティ（Accessibility、略して A11y）は、すべてのユーザーがより簡単・快適に Web を利用できるようにするための基本原則です。
+
+フロントエンド開発者はHTMLの構造を作り、インタラクションを定義します。ユーザーに最も近い場所でWeb体験を設計する立場であり、**アクセシビリティの出発点かつ中核的な役割**を担っています。だからこそ、フロントエンド開発者がアクセシビリティを意識すれば、誰もが利用できるWebを実現できます。
+
+本ドキュメントは「アクセシビリティは難しい」と感じている方に向けて、現場ですぐに適用できるアクセシビリティの核心概念と、つまずきやすいパターンを解説します。ボタンの中にボタンを入れてはいけない理由、`<a>`タグの中に`<button>`が入るとどんな問題が起きるのか、スクリーンリーダー利用者はどのようにコンテンツを読むのかなどを、実際の例とともに紹介します。
+
+## こんな方におすすめ
+
+- 🎯 何気なく書いたコードが、誰かにとって大きな障壁になり得ると気づいた開発者
+- 🔍 「アクセシビリティを考慮すべき」とは聞くものの、どこから始めればよいか見当がつかない開発者
+- 👀 「スクリーンリーダー」「キーボード操作」「ARIA」といった用語を聞いたことはあるが、実務で適用したことがない開発者
+- 🧩 HTML 構造の問題で自動テストが失敗したり、外部ライブラリ連携がうまくいかなかった経験がある開発者
diff --git a/fundamentals/a11y/ja/playground.md b/fundamentals/a11y/ja/playground.md
new file mode 100644
index 00000000..89f19fb1
--- /dev/null
+++ b/fundamentals/a11y/ja/playground.md
@@ -0,0 +1,33 @@
+---
+head:
+  - [
+      meta,
+      {
+        property: "og:image",
+        content: "https://static.toss.im/illusts/a11y-use-meta.jpg"
+      }
+    ]
+  - [
+      meta,
+      {
+        name: "twitter:image",
+        content: "https://static.toss.im/illusts/a11y-use-meta.jpg"
+      }
+    ]
+  - [meta, { name: "twitter:card", content: "summary_large_image" }]
+---
+
+<script setup>
+import ScreenReaderExperience from '../components/ScreenReaderExperience.vue';
+</script>
+
+# 体験してみる
+
+視覚障害のある方がモバイルをどのように利用しているか、実際に体験してみましょう。下の「はじめる」ボタンを押すと、スクリーンリーダー利用者のように画面を見ず、音声だけでTossの送金サービスを体験できます。
+
+PCではマウスのクリックとドラッグでタッチ操作を代替できます。真っ暗な画面は最初は戸惑うかもしれませんが、音声に耳を傾けながらゆっくり進めてみてください。
+
+<ScreenReaderExperience
+  url="https://service.toss.im/accessibility/screen-reader-experience"
+  title="スクリーンリーダー体験ページへ"
+/>
\ No newline at end of file
diff --git a/fundamentals/a11y/ja/predictability/fake-button.md b/fundamentals/a11y/ja/predictability/fake-button.md
new file mode 100644
index 00000000..9495f41f
--- /dev/null
+++ b/fundamentals/a11y/ja/predictability/fake-button.md
@@ -0,0 +1,82 @@
+# ボタンの役割と動作を一致させる
+
+## 問題：ボタンではない要素にクリックイベントリスナーを付与している
+
+通常の HTML 要素に`cursor: pointer`と`onclick`イベントだけを追加しても、本当のボタンにはなりません。このやり方だと、キーボード利用者はキーボードでフォーカス移動ができず、スクリーンリーダー利用者もボタンとして認識できない可能性があります。
+
+::: tip リンクにも同じことが当てはまります
+
+`<a>`タグを使わずにハイパーリンクを実装した場合も同じ問題が発生します。
+
+リンク可能な要素には必ず`<a>`タグを使用してください。`<button>`と違って`<a>`はブロック要素を子に含められるため、用途を取り違えて代替として使わないでください。
+
+:::
+
+### 誤った例
+
+次のようなコードは、上で説明したすべてのアクセシビリティ問題を引き起こします。
+
+```jsx
+<div class="button-style" style="cursor: pointer" onclick="handleAnything()">
+   お問い合わせ
+</div>
+```
+
+## ✅ 改善方法
+
+### 1. `<button>`要素を使う
+
+最もよい方法は、HTMLのセマンティック要素である`<button>`を使うことです。この要素は基本的なアクセシビリティ機能をすべて提供します。
+
+- キーボードフォーカス
+- Enter/Space キーでのクリック
+- スクリーンリーダーで「ボタン」として認識
+- 適切な ARIA 属性の自動付与
+
+```jsx
+<button onClick={handleClick}>문의하기</button>
+```
+
+### 2. `<button>`を使えない場合
+
+内部にブロック要素があり`<button>`を使えない場合は、次のようにアクセシビリティ属性を明示する必要があります。
+
+```jsx
+<div
+  role="button"
+  tabIndex={0}
+  onClick={handleClick}
+  onKeyDown={(e) => {
+    if (e.key === "Enter" || e.key === " ") {
+      handleClick();
+    }
+  }}
+>
+  <div>内部のブロック要素</div>
+</div>
+```
+
+- `role="button"`：スクリーンリーダーにこの要素がボタンであることを知らせます。
+- `tabIndex={0}`：キーボードでフォーカスできるようにします。
+- `onKeyDown`：キーボードアクセシビリティのため、EnterまたはSpaceキー入力時にクリック相当の動作を発生させます。
+
+### 3. `react-aria`を使う
+
+[React-Aria](https://react-spectrum.adobe.com/react-aria/index.html)ライブラリの [`useButton`](https://react-spectrum.adobe.com/react-aria/useButton.html)フックを使うと、アクセシブルなボタンをより簡単に実装できます。このフックは `role`、`tabIndex`、`onKeyDown` などの必須アクセシビリティ設定をまとめて提供してくれるため、個別に扱う必要がありません。
+
+```jsx
+import { useButton } from "react-aria";
+
+const buttonRef = useRef < HTMLDivElement > null;
+const { buttonProps } = useButton(
+  {
+    elementType: "div",
+    onPress: handleClick
+  },
+  buttonRef
+);
+
+<div ref={buttonRef} {...buttonProps}>
+  <div>内部のブロック要素</div>
+</div>;
+```
diff --git a/fundamentals/a11y/ja/predictability/form.md b/fundamentals/a11y/ja/predictability/form.md
new file mode 100644
index 00000000..96fffd1b
--- /dev/null
+++ b/fundamentals/a11y/ja/predictability/form.md
@@ -0,0 +1,100 @@
+# 入力要素は`<form>`で包む
+
+ユーザーは入力欄に内容を入力してEnterキーを押すとフォームが送信（submit）されることを期待します。この動作は`<form>`タグを正しく使えば、別途スクリプトなしで機能します。
+
+さらに、ブラウザの自動補完（autocomplete）、入力履歴の保存、モバイルでの入力最適化といったブラウザ標準の機能も、`<form>`を通じて自然に提供されます。
+
+::: info スクリーンリーダーのアクセシビリティの観点で`<form>`が重要な理由
+
+- **役割（Role）の案内** : スクリーンリーダーは`<form>`要素に到達すると「フォーム、（名前があればその名前、）フォームの開始」のように、その領域がフォームであることを明確に案内します。フォームが終わる箇所では「フォームの終わり」や「フォーム終了」といった案内を行います。
+
+- **高速なナビゲーション**: スクリーンリーダー利用者は、見出し・リンク・フォームなど意味のある構造単位へ素早く移動できます。`<form>`が明確にマークアップされていれば、ユーザーはショートカットキー（例：NVDAのf、JAWSのf）でフォーム領域だけを素早く探索できます。
+
+- **文脈の提供**: 複数の入力要素がある場合、それらが1つのフォームに属しているという文脈をスクリーンリーダーが伝えます。たとえば「ログインフォーム」というラベルがあれば、ユーザーは今入力している情報がログインに関するものであることを容易に理解できます。
+
+- **エラーや状態の案内**: フォーム送信時のエラーメッセージや必須入力の案内などもフォーム領域内で案内されるため、スクリーンリーダー利用者は全体の流れを逃さず情報を受け取れます。
+
+次のコード例を参考にしてください。
+
+```html
+<form aria-label="ログイン">
+  <label for="id">ID</label>
+  <input id="id" name="id" type="text" />
+  <label for="pw">パスワード</label>
+  <input id="pw" name="pw" type="password" />
+  <button type="submit">ログイン</button>
+</form>
+```
+
+スクリーンリーダーはフォームに入ると「ログイン、フォーム、ID、編集、パスワード、編集、ログイン、ボタン、フォーム終了」のように案内します。
+:::
+
+## `<form>`を正しく使うには
+
+- 入力要素（input、textarea など）は `<form>`要素で包みましょう。
+- ユーザーがフォームを送信したときに特定のページへ送るのではなく、現在のページでリロードなしに動作させたい場合は、`onsubmit`で`event.preventDefault()`を呼びます。
+- 送信ボタンは`<button type="submit">`で作成します。`<button>`のデフォルトタイプはsubmitなので、単なるクリック用ボタンには必ず`type="button"`を明示します。
+
+次の例で、アクセシビリティを考慮した正しいフォームの書き方を見てみましょう。
+
+```html
+<form onsubmit="event.preventDefault(); /* 望む動作 */">
+  <input type="text" name="username" />
+  <input type="password" name="password" />
+  <button type="submit">ログイン</button>
+  <button type="button">キャンセル</button> {/* 単純な動作用のボタン */}
+</form>
+```
+
+::: warning
+`<form>`内の`<button>`はデフォルトでsubmit動作を行います。単なるクリックイベントだけが必要なボタンには、必ず`type="button"`を指定してください。
+:::
+
+## ボタンが`<form>`の外にある場合
+
+実務では、submitボタンがフォーム本体から離れて配置されることがよくあります。この場合は`<button>`の`form`属性を使って`<form>`と関連付けられます。次のように`<form>`の`id`と結び付けてください。
+
+```html
+<form id="my-form" onsubmit="event.preventDefault(); /* 望む動作 */">
+  <input type="text" name="search" />
+</form>
+<button type="submit" form="my-form">検索</button>
+```
+
+このようにすると、ボタンが`<form>`の外にあってもそのフォームを送信できます。
+
+## 実戦例：ログインフォームを作る
+
+<img src="../images/login-form.png" style="max-width: 100%; width: 300px" alt="" />
+
+実際によく使われるログインフォームのマークアップをしてみます。IDとパスワードの入力欄があり、送信できるログインボタンがあります。各入力欄には、値があるときだけ表示される削除ボタンがあります。
+
+```html
+<form onsubmit="event.preventDefault(); /* 望む動作 */">
+  <label for="login-id">ID</label>
+  <div>
+    <input id="login-id" name="id" type="text" />
+    <!-- 入力値があるときだけ表示される削除ボタン -->
+    <button type="button" tabindex="{-1}" aria-label="ID の入力値を削除">
+      ❌
+    </button>
+  </div>
+  <label for="login-pw">パスワード</label>
+  <div>
+    <input id="login-pw" name="pw" type="password" />
+    <!-- 入力値があるときだけ表示される削除ボタン -->
+    <button type="button" tabindex="-1" aria-label="パスワードの入力値を削除">
+      ❌
+    </button>
+  </div>
+  <button type="submit">ログイン</button>
+</form>
+```
+
+上のように記述すれば、`<form>`を使うことでEnterキーでもログイン動作を実行できます。また、削除ボタンには`tabindex="-1"`を指定してキーボードフォーカスを受けないようにしています。
+
+::: info 入力値削除ボタンがキーボードユーザーに不要な理由？
+削除ボタンは、キーボードユーザーが入力値を消すのに必須ではないため、フォーカスを受けないようにしました。テキストは`Backspace`キーで削除できるからです。
+:::
+
+このようにすると、キーボードユーザーも不要なフォーカス移動なしに、慣れ親しんだ方法でフォームを利用できます。フォームの基本動作とブラウザーのさまざまな機能を最大限に活用するために、入力要素の上位には必ず`<form>`を使ってください！
diff --git a/fundamentals/a11y/ja/principles.md b/fundamentals/a11y/ja/principles.md
new file mode 100644
index 00000000..5b51c598
--- /dev/null
+++ b/fundamentals/a11y/ja/principles.md
@@ -0,0 +1,29 @@
+# 主要原則
+
+本ドキュメントでは、Webコンテンツのアクセシビリティを高めるための4つの核心原則を提示し、それぞれの原則を守るための具体的な方法を提案します。
+
+## 1. 🧱 正しい構造を作る
+
+HTML 要素を正しくラップし、適切に配置することがアクセシビリティの出発点です。
+
+- [ボタンの中にボタンを入れてはいけない理由](./structure/button-inside-button.md)
+- [テーブル行全体をクリック可能にする方法](./structure/table-row-link.md)
+
+## 2. 🗣️ 意味を正確に伝える
+
+ユーザーにこの要素が何で、どんな役割を持つのかを明確に伝える必要があります。
+
+- [インタラクティブ要素に名前を付ける](./semantic/required-label.md)
+- [同じ名前の要素には説明を付ける](./semantic/duplicate-interactive-element.md)
+
+## 3. 🎯 予測可能なインタラクションを作る
+
+見た目と実際の動作が一致している必要があります。
+
+- [ボタンの役割と動作を一致させる](./predictability/fake-button.md)
+
+## 4. 🌈 視覚情報だけに依存しない
+
+色・画像・アイコンは必ずテキストなどの別手段で補完すべきです。
+
+- [画像とアイコンに代替テキストを提供する](./alt-text/image-alt.md)
diff --git a/fundamentals/a11y/ja/semantic/duplicate-interactive-element.md b/fundamentals/a11y/ja/semantic/duplicate-interactive-element.md
new file mode 100644
index 00000000..ea10f068
--- /dev/null
+++ b/fundamentals/a11y/ja/semantic/duplicate-interactive-element.md
@@ -0,0 +1,155 @@
+# 同じ名前の要素には説明を付ける
+
+同じ名前のボタンが複数回登場する画面では、ユーザー（特にスクリーンリーダー利用者）が、それぞれのボタンがどの項目に結び付いているのか分かるように配慮する必要があります。
+
+たとえば下のような構成でボタン名がすべて「選択」だと、どの項目を選ぶボタンなのか分かりにくいため、**明確な文脈を合わせて提供する必要があります。**
+
+![重複するボタンの例](../images/duplicate-interactive-element.png)
+
+## 問題：意味を読み取れないスクリーンリーダー
+
+### 誤った例
+
+次のコードは見た目には問題なさそうに見えますが、スクリーンリーダーでは 2 つのボタンがどちらも「選択、ボタン」としか読み上げられません。したがって、利用者は異なるボタンがそれぞれどの項目に対応しているか分かりません。
+
+```html 10,20
+<div class="option-list">
+  <div>
+    <div>
+      <div class="paper-icon">📄</div>
+      <div>
+        <div>紙を使用する場合</div>
+        <div>紙にいろいろ書いてみましょう。</div>
+      </div>
+    </div>
+    <button>選択</button>
+  </div>
+  <div>
+    <div>
+      <div class="pencil-icon">✏️</div>
+      <div>
+        <div>鉛筆を使用する場合</div>
+        <div>鉛筆をよく削ってみましょう。</div>
+      </div>
+    </div>
+    <button>選択</button>
+  </div>
+</div>
+```
+
+## ✅ 改善方法
+
+### 1. `aria-label`でボタンの説明を追加する
+
+`aria-label`は視覚的には表示されなくても、スクリーンリーダーに読み上げられる説明を提供します。
+
+```html 10,20
+<div class="option-list">
+  <div>
+    <div>
+      <div class="paper-icon">📄</div>
+      <div>
+        <div>紙を使用する場合</div>
+        <div>紙にいろいろ書いてみましょう。</div>
+      </div>
+    </div>
+    <button aria-label="紙を使用する場合を選択">選択</button>
+  </div>
+  <div>
+    <div>
+      <div class="pencil-icon">✏️</div>
+      <div>
+        <div>鉛筆を使用する場合</div>
+        <div>鉛筆をよく削ってみましょう。</div>
+      </div>
+    </div>
+    <button aria-label="鉛筆を使用する場合を選択">選択</button>
+  </div>
+</div>
+```
+
+::: warning `aria-label`使用時の注意点
+
+`aria-label`を使うと、画面に見えている従来のテキストはスクリーンリーダーに露出しなくなります。したがって、ボタンに「選択」という視覚テキストがあるのに、aria-label="紙を使用する場合"のようにまったく別の文言で置き換えてしまうと、スクリーンリーダー利用者は「選択」という語をまったく聞けなくなります。
+
+可能であれば、視覚テキストを含めた文として`aria-label`を作成してください。たとえば「紙を使用する場合」ではなく「紙を選択」や「選択 − 鉛筆」のようにします。
+:::
+:::
+
+### 2. リストのマークアップとラベルを関連付ける
+
+`<li>`などのリスト構造に、見出し役のテキストを`aria-labelledby`で結び付け、各項目ごとにどのボタンか区別できるようにします。
+
+```html 2,10,12,20
+<ul class="option-list">
+  <li aria-labelledby="paper-title">
+    <div>
+      <div class="paper-icon">📄</div>
+      <div>
+        <div id="paper-title">紙を使用する場合</div>
+        <div>紙にいろいろ書いてみましょう。</div>
+      </div>
+    </div>
+    <button>選択</button>
+  </li>
+  <li aria-labelledby="pencil-title">
+    <div>
+      <div class="pencil-icon">✏️</div>
+      <div>
+        <div id="pencil-title">鉛筆を使用する場合</div>
+        <div>鉛筆をよく削ってみましょう。</div>
+      </div>
+    </div>
+    <button>選択</button>
+  </li>
+</ul>
+```
+
+最初のボタンはスクリーンリーダーで「選択、ボタン、紙を使用する場合、グループ（4個中1番目）」のように読み上げられます。
+
+::: warning リストのマークアップ使用時の注意点
+最新のスクリーンリーダーはリスト要素の名前まで適切に読み上げますが、**古いバージョンでは正しく読めない場合があります。** 次のセクションでその対処法を説明します。
+:::
+
+### 3. ボタンにも`aria-labelledby`を追加する
+
+上の2のようにリスト構造を使いつつ、ボタンにも直接説明を関連付けると、どのスクリーンリーダーでもより明確に動作します。
+
+```html 2,10,12,20
+<ul class="option-list">
+  <li aria-labelledby="paper-title">
+    <div>
+      <div class="paper-icon">📄</div>
+      <div>
+        <div id="paper-title">紙を使用する場合</div>
+        <div>紙にいろいろ書いてみましょう。</div>
+      </div>
+    </div>
+    <button id="paper-button" aria-labelledby="paper-title paper-button">
+      選択
+    </button>
+  </li>
+  <li aria-labelledby="pencil-title">
+    <div>
+      <div class="pencil-icon">✏️</div>
+      <div>
+        <div id="pencil-title">鉛筆を使用する場合</div>
+        <div>鉛筆をよく削ってみましょう。</div>
+      </div>
+    </div>
+    <button id="pencil-button" aria-labelledby="pencil-title pencil-button">
+      選択
+    </button>
+  </li>
+</ul>
+```
+
+`aria-labelledby`には空白区切りで複数の要素IDを並べられます。複数IDを指定すると、該当要素が持つテキストコンテンツを順番に連結してスクリーンリーダーが読み上げます。
+
+たとえば下のコードのように「紙を使用する場合」（paper-title）と「選択」（paper-button）が一緒に読まれ、スクリーンリーダーでは「紙を使用する場合 選択、ボタン」のように聞こえます。
+
+```html
+<button id="paper-button" aria-labelledby="paper-title paper-button">
+  選択
+</button>
+```
diff --git a/fundamentals/a11y/ja/semantic/required-label.md b/fundamentals/a11y/ja/semantic/required-label.md
new file mode 100644
index 00000000..64d2ac1d
--- /dev/null
+++ b/fundamentals/a11y/ja/semantic/required-label.md
@@ -0,0 +1,148 @@
+# インタラクティブ要素に名前を付ける
+
+インタラクティブ要素（入力フィールド、ボタン、セレクトボックスなど）には、目的をユーザーに明確に伝える名前が必須です。名前がない、または不明確な要素は、スクリーンリーダー利用者や音声アシスタント利用者に大きな不便を与えます。
+
+::: details インタラクティブ要素の一覧
+| 要素 | 条件 |
+|------|------|
+| `<a>` | - |
+| `<audio>` | `controls`属性がある場合 |
+| `<button>` | - |
+| `<details>` | - |
+| `<embed>` | - |
+| `<iframe>` | - |
+| `<img>` | `usemap`属性がある場合 |
+| `<input>` | `type`属性が"hidden"でない場合 |
+| `<keygen>` | - |
+| `<label>` | - |
+| `<menu>` | `type`属性がtoolbarの場合 |
+| `<object>` | `usemap`属性がある場合 |
+| `<select>` | - |
+| `<textarea>` | - |
+| `<video>` | `controls`属性がある場合 |
+:::
+
+インタラクティブ要素に名前を与える方法はいくつかあります。スクリーンリーダーは次の優先順位で名前を取得します。:
+
+1. `aria-labelledby` - スクリーンリーダーが最優先で読む属性
+2. `aria-label` - `aria-labelledby`がない場合に読む属性
+3. `<label>` - ARIA属性がない場合に読むHTMLのラベル
+4. `placeholder` - ラベルがない場合に読むことがあるが、ラベルの代用としては非推奨
+5. 요소의 내용 - 上記がすべてない場合（ボタン内のテキストなど）
+
+## 問題：入力フィールドに名前がなく、用途を把握できない
+
+デザイン上の理由や簡潔さのために入力フィールドのラベルを省略することがありますが、これはアクセシビリティの観点で重大な問題を引き起こします。
+
+### 誤った例 1
+
+次の入力フィールドは何の情報も提供しないため、すべてのユーザーを混乱させます。スクリーンリーダー利用者はこのフィールドが何であるかまったく分かりません。視覚ユーザーも、何を入力すべきか判断できません。
+
+```html
+<input type="text" />
+```
+
+### 誤った例 2
+
+次の入力フィールドは、見た目にはプレースホルダーで目的を示し、技術的には動作しますが、アクセシビリティの観点では不十分です。
+
+まず、一部の旧式スクリーンリーダーはプレースホルダーを認識しません。ユーザーが入力を始めるとプレースホルダーは消えるため、フィールドの目的を忘れてしまう可能性があります。さらに、プレースホルダーのテキストは一般にコントラストが低く、弱視のユーザーには読みにくいことが多いです。
+
+```html
+<input type="text" placeholder="名前を入力してください" />
+```
+
+## ✅ 改善方法
+
+### 1. `<label>`要素を使う
+
+HTMLでは、`<label>`要素を使って入力フィールドと関連付けるのが最善です。
+
+```html
+<label for="user-name">名前</label> <input id="user-name" type="text" />
+```
+
+ラベルの利点は多くあります。
+
+まず、スクリーンリーダー利用者に入力フィールドの目的を明確に伝えます。さらに、ラベルをクリックしても関連付けられた入力フィールドにフォーカスが移るため、タッチインターフェースで特に有用です。入力中でも常に表示されるため、ユーザーはフィールドの目的を忘れにくくなります。あらゆるユーザーに最も明確な体験を提供できる方法です。
+
+### 2. `aria-label`属性を使う
+
+デザイン上の制約で視覚的なラベルを表示できない場合は、次のように`aria-label`属性を使用できます。
+
+```html
+<input type="text" aria-label="名前" placeholder="名前を入力してください" />
+```
+
+`aria-label`は視覚的には表示されませんが、スクリーンリーダーでは要素の名前として読み上げられます。**デザイン上ラベルを出せないときの次善策としてのみ使用してください。**
+
+### 3. `aria-labelledby`属性を使う
+
+画面上に既にテキストがあり、それを入力フィールドのラベルとして使いたいときは、`aria-labelledby`を使用できます。
+
+```html
+<h2 id="address-heading">配送先住所</h2>
+
+<input
+  type="text"
+  aria-labelledby="address-heading"
+  placeholder="例：ソウル市 江南区"
+/>
+```
+
+## さらに詳しく
+
+### その他のインタラクティブ要素にも名前を付ける
+
+入力フィールド以外でも、すべてのインタラクティブ要素には明確な名前が必要です。
+
+#### ボタン(`<button>`)
+
+```html
+<!-- ✅ 正しい例：明確なテキスト -->
+<button>会員登録</button>
+
+<!-- ⚠️ 改善が必要な例：視覚アイコンだけのボタン -->
+<button>
+  <svg aria-hidden="true">...</svg>
+</button>
+
+<!-- ✅ 正しい例：アイコンボタンにアクセシビリティを追加 -->
+<button aria-label="閉じる">
+  <svg aria-hidden="true">...</svg>
+</button>
+```
+
+#### セレクト要素(`<select>`)
+
+```html
+<!-- ✅ 正しい例：ラベルがあるセレクトボックス -->
+<label for="country">国を選択</label>
+<select id="country">
+  <option value="kr">韓国</option>
+  <option value="us">米国</option>
+</select>
+
+<!-- ❌ 誤った例：ラベルがないセレクトボックス -->
+<select>
+  <option value="kr">韓国</option>
+  <option value="us">米国</option>
+</select>
+```
+
+### プレースホルダーの正しい使い方
+
+プレースホルダーだけではアクセシビリティを担保できません。プレースホルダーはラベルの代替ではなく補助であることを忘れないでください。入力形式に関するヒントを与える目的で使うのが適切です。
+
+#### ❌ 誤った例：プレースホルダーのみを使用
+
+```html
+<input type="email" placeholder="メールアドレス" />
+```
+
+#### ✅ 正しい例：ラベルとプレースホルダーを併用
+
+```html
+<label for="email">メールアドレス</label>
+<input id="email" type="email" placeholder="example@email.com" />
+```
diff --git a/fundamentals/a11y/ja/structure/button-inside-button.md b/fundamentals/a11y/ja/structure/button-inside-button.md
new file mode 100644
index 00000000..6319630f
--- /dev/null
+++ b/fundamentals/a11y/ja/structure/button-inside-button.md
@@ -0,0 +1,128 @@
+# ボタンの中にボタンを入れない
+
+ボタンやリンクのようにユーザーが操作する要素([interactive content](https://www.w3.org/TR/2011/WD-html5-20110405/content-models.html#interactive-content))は、HTML とアクセシビリティ（A11y）の観点で特別な注意が必要です。本ドキュメントでは、ボタンの中に別のボタンやリンクが入るとなぜ問題になるのか、そしてどのように解決すべきかを説明します。
+
+## 問題 1: ボタンのように見えるリンク
+
+### 誤った例
+
+次のように`<a>`タグの中に`<button>`を出力するコンポーネントを入れるのは間違いです。HTMLでは、インタラクティブな要素の中に別のインタラクティブ要素を入れることは許可されていないためです[^1].この構造ではアクセシビリティの問題が発生し、ブラウザで予期しない動作が起きる可能性があります。
+
+[^1]: https://www.w3.org/TR/2011/WD-html5-20110405/text-level-semantics.html#the-a-element
+のContent model項目を参考にしてください。
+
+```jsx
+<a href="/go-to">
+  <Button>確認しました。</Button>
+</a>
+```
+
+### ✅ 改善方法
+
+Buttonコンポーネントが`<a>`タグをレンダリングできるオプションを提供しましょう。
+
+```jsx
+<Button as="a" href="/go-to">
+  確認しました。
+</Button>
+```
+
+## 問題 2: ボタンの中に入った別のボタン
+
+UIの構成上、ボタンのように見えるカードの中に別のボタンを置く必要がある場合があります。このとき構造を誤るとアクセシビリティの問題が発生します。
+
+![カードUIパターンの例](../images/button-inside-button.png)
+
+### 誤った例
+
+ボタンの中にボタンを入れて`stopPropagation()`を使う方法は避けましょう。`stopPropagation()`でイベントの伝播を止めようとしても、HTML構造自体が誤っているためです。このような入れ子構造はスクリーンリーダーを混乱させ、キーボードフォーカスにも問題を引き起こします。
+
+```jsx
+<button>
+  サービス審査管理
+  <button aria-label="삭제" onClick={(event) => event.stopPropagation()}>
+    x
+  </button>
+</button>
+```
+
+### ✅ 改善方法
+
+ボタンのコンテナーと子ボタンを実装する際は、アクセシビリティとHTML標準に準拠しつつ、期待する機能を実現できます。
+
+`div`コンテナーと絶対配置を用いて、次のようにボタンをレイヤー化してみましょう。この構造は、全体の領域を仮想的なボタンのようにしつつ、視覚的には見えないボタン（`「詳細を見る」`）を上に重ねる方式です。削除ボタンは別位置に配置され、HTML標準にも違反しません。
+
+```jsx
+<div
+  style="position: relative; isolation: isolate;"
+  className="wrapper"
+  role="listitem"
+  aria-label="서비스 검토 관리"
+>
+  <button
+    className="detail-button"
+    style="position: absolute; inset: 0; opacity: 0"
+  >
+    詳細を見る
+  </button>
+  サービス審査管理
+  <div style="position: relative; z-index: 2;">
+    <button aria-label="삭제">x</button>
+  </div>
+</div>
+```
+
+::: tip フォーカススタイルも忘れずに
+上の例で「詳細を見る」ボタンは透明に設定しているため、キーボードフォーカスが当たってもフォーカス表示が見えない場合があります。親要素にCSSの [`:focus-within` 擬似クラス](https://developer.mozilla.org/ko/docs/Web/CSS/:focus-within)を使うと、子要素がフォーカスを受けたときにもスタイルを適用できます。
+
+```css
+.wrapper:focus-within {
+  outline: 2px solid blue;
+}
+```
+
+:::
+
+## なぜこの構造が問題になるのか？
+
+ボタンの中にボタンを入れてはいけない理由を詳しく説明します。
+
+### アクセシビリティの観点での問題
+
+#### 1. キーボード探索が混乱する
+
+スクリーンリーダーやキーボード利用者にとって、どのボタンが押されるのか不明確です。外側のボタンと内側のボタンのどちらのイベントが先に処理されるのか予測しづらいです。
+
+#### 2. スクリーンリーダーの読み上げが誤解を招く
+
+スクリーンリーダーが「ボタンの中に別のボタン」といった不自然な読み上げを行い、利用者が混乱する可能性があります。
+
+#### 3. フォーカス順が崩れる
+
+フォーカスがどこへ移動すべきか曖昧になり、意図しない操作につながることがあります。特にモバイルでは、タップで望まないボタンが押されることがあります。
+
+### HTML 標準の観点での問題
+
+[W3C HTML5 명세](https://www.w3.org/TR/2011/WD-html5-author-20110809/the-a-element.html)によると、`<a>`要素は content modelとしてtransparent（実質的に何でも）を含められますが、インタラクティブ要素を含むことはできません
+
+#### インタラクティブ要素の一覧
+
+以下の要素はいずれもインタラクティブ要素です。これらのいずれかを含む要素の中に、さらに別のインタラクティブ要素を入れてはいけません。
+
+| 요소         | 조건                                 |
+| ------------ | ------------------------------------ |
+| `<a>`        | -                                    |
+| `<audio>`    | controls属性がある場合           |
+| `<button>`   | -                                    |
+| `<details>`  | -                                    |
+| `<embed>`    | -                                    |
+| `<iframe>`   | -                                    |
+| `<img>`      | usemap属性がある場合              |
+| `<input>`    | type属性が Hidden state でない場合 |
+| `<keygen>`   | -                                    |
+| `<label>`    | -                                    |
+| `<menu>`     | type属性が toolbar 状態の場合     |
+| `<object>`   | usemap属性がある場合              |
+| `<select>`   | -                                    |
+| `<textarea>` | -                                    |
+| `<video>`    | controls属性がある場合            |
diff --git a/fundamentals/a11y/ja/structure/table-row-link.md b/fundamentals/a11y/ja/structure/table-row-link.md
new file mode 100644
index 00000000..f1ac3abe
--- /dev/null
+++ b/fundamentals/a11y/ja/structure/table-row-link.md
@@ -0,0 +1,82 @@
+# テーブル行にクリックイベントハンドラーを付けない
+
+テーブルUIで行全体をクリックして詳細ページへ遷移するパターンはよく使われます。ですが、これをアクセシブルに実装するにはいくつか重要な注意点があります。
+
+![テーブル行クリックパターンの例](../../images/table-row-link.png)
+
+## 問題：キーボードで選択できず、クリック可能であることが伝わらない
+
+### 誤った例
+
+開発者はしばしばテーブル行（`<tr>`）に直接クリックイベントを付け、行全体をクリック可能にしてしまいます。
+
+```jsx
+<tr onclick="location.assign('/detail/キムトス')">
+  <td>
+    キムトス <Icon />
+  </td>
+  <td>22</td>
+  <td>勉強</td>
+  <td>株式</td>
+  <td>-</td>
+</tr>
+```
+
+この方法には次のようなアクセシビリティの問題があります。
+
+1. **キーボードアクセシビリティの不足**
+   - テーブル行（`<tr>`）は既定でキーボードフォーカスを受けられず、キーボード利用者がアクセスできません。
+   - キーボード利用者はこの行を選択したりクリックしたりする手段がありません。
+
+2. **スクリーンリーダー利用者への情報不足**
+   - 行がクリック可能であることがスクリーンリーダー利用者に伝わりません。
+   - 行がどこへリンクしているかの情報がありません。
+
+## ✅ 改善方法
+
+行全体をクリック可能にしつつアクセシビリティを保つには、行内に実際のリンク要素を含め、CSSでリンクのヒット領域を拡張する方法が有効です。
+
+```jsx
+<style>
+  .link::after {
+    position: absolute;
+    display: block;
+    content: '';
+    inset: 0;
+  }
+</style>
+
+<tr style="position: relative;">
+  <td>
+    キムトス
+    <IconLink
+      label="자세히 보기"
+      href="/detail/김토스"
+      className="link"
+    />
+  </td>
+  <td>22</td>
+  <td>勉強</td>
+  <td>株式</td>
+  <td>-</td>
+</tr>
+```
+
+このように改善すると次の利点があります。
+
+1. **キーボードアクセスの提供**
+   - リンク要素は既定でキーボードフォーカスを受けられるため、キーボード利用者もアクセス可能です。
+   - Tabキーでリンクにフォーカスし、Enterキーでアクティブ化できます。
+
+2. **スクリーンリーダー利用者への明確な情報提供**
+   - リンク要素はスクリーンリーダーで「リンク」と認識され、クリック可能であることが伝わります。
+   - `label`属性（実際には`aria-label`に変換）の利用で、リンクの目的を明確に伝えられます。
+
+3. **마우스 사용자를 위한 편의성 유지**
+   - ブラウザのリンク機能（新規タブで開く、リンクアドレスのコピーなど）をそのまま提供できます。
+   - CSS`::after`疑似要素で行全体をクリック可能にし、マウス利用者の利便性を維持します。
+   - 小さなリンク領域だけを狙ってクリックする不便を解消します。
+
+4. **セマンティックなマークアップを遵守**
+   - HTMLの意味論的構造を保ちつつアクセシビリティを向上させます。
+   - リンクの目的を明確に表現できます。
diff --git a/fundamentals/a11y/ja/why.md b/fundamentals/a11y/ja/why.md
new file mode 100644
index 00000000..1167e9a0
--- /dev/null
+++ b/fundamentals/a11y/ja/why.md
@@ -0,0 +1,70 @@
+# アクセシビリティを守る理由
+
+アクセシビリティを守ることで、障害の有無にかかわらず、そして開発者自身にとってもメリットがあります。障害のあるユーザーはスクリーンリーダーなどの支援技術を通じてWebサイトを円滑に利用でき、一般のユーザーはより速く快適な体験を得られます。さらに開発者は、より堅牢で保守しやすいコードを書けるようになります。
+
+## 障害のあるユーザーにとって必要な理由
+
+ボタンの色、アイコンの形、レイアウト、チャートや画像といった視覚情報を見ることができないユーザーは、どのように Web サイトを使うでしょうか。答えはスクリーンリーダーなどの支援技術です。このとき、適切な役割（`role`）、ラベル（`label`）、代替テキスト（`alt`）といったアクセシビリティ属性が提供されていないと、必要な情報が得られなかったり、ボタン・リンクなどのインタラクティブ要素を見落として大きな不便を被ります。
+たとえば、単にクリックイベントを付けただけの`<div>`はスクリーンリーダーでボタンとして認識されず、ユーザーがその機能を利用できません。
+
+## 一般ユーザーにも有用な理由
+
+アクセシビリティを守ると、障害のない一般ユーザーでもWebをより速く、より便利に利用できます。ユーザーが慣れ親しんだWebの挙動が自然に提供されるからです。
+
+たとえば、リンク（`<a>`）を正しく使えば、右クリックで「新しいタブで開く」「リンクをコピー」などの機能を利用できます。しかし、単に`<div>`や `<span>`にクリックイベントだけを付与した場合、こうした基本機能は使えません。
+またフォームでは、適切な`<form>`、`<input>`、`<button type="submit">`を使うことで、ユーザーはEnterキーでフォームを送信できます。そうでない場合、ユーザーは期待する既定の挙動を得られません。
+加えて、キーボード中心で操作するユーザーは Tab／Shift+Tab、Enter、Space、矢印キーなどでサイトを移動します。ボタンやリンク、フォーム要素に正しい役割やフォーカス管理がされていないと、キーボードでは機能を利用できません。
+
+次の画像は、ブラウザでリンクを右クリックしたときに表示されるコンテキストメニューです。リンク要素を正しく使えば、ユーザーが期待するこうした基本機能をすべて提供できます。
+
+<img src="./images/browser-link.png" alt="" style="max-width: 100%; width: 300px" />
+
+このようにアクセシビリティは、障害のあるユーザーだけでなく、キーボード利用者、そして一般的なWeb体験を期待するすべての人に不便を与えないための基本原則です。アクセシビリティを考慮しないと、誰にでも起こり得る不便が生じます。
+
+## アクセシビリティを守ったときに開発者が得る利点
+
+アクセシビリティを適切に守ると、UI テストで要素を特定するのが非常に簡単になります。たとえば[testing-library](https://testing-library.com/docs/dom-testing-library/intro)では、[`ByRole`](https://testing-library.com/docs/queries/byrole)クエリで要素を選択することが推奨されています。これを使えば、ボタン・入力欄・リンクなど、役割（role）が明確な要素を容易に見つけられます。
+
+たとえば次のように、名前が「保存」の「ボタン」を明確に取得できます。
+
+```js
+// アクセシビリティが適切な場合
+render(<button>保存</button>);
+expect(screen.getByRole("button", { name: "保存" })).toBeInTheDocument();
+```
+
+同じ名前の要素が複数ある場合でも、上位要素のアクセシビリティラベルを活用すれば区別しやすく、ユーザーにとっても選択が容易です。
+
+```js
+// 同じ名前の要素を、上位のアクセシビリティ情報で特定する
+render(
+  <ul>
+    <li aria-labelledby="item1-title">
+      <span id="item1-title">りんご</span>
+      <button>保存</button>
+    </li>
+    <li aria-labelledby="item2-title">
+      <span id="item2-title">桃</span>
+      <button>保存</button>
+    </li>
+  </ul>
+);
+const 桃 = screen.getByRole("listitem", { name: "桃" });
+const 桃保存ボタン = within(복숭아).getByRole("button", { name: "保存" });
+expect(桃保存ボタン).toBeInTheDocument();
+```
+
+一方、`querySelector`で要素を選ぶと、マークアップ構造が少し変わっただけでテストが壊れやすくなります。`ByTestId`はテスト専用の属性を追加する必要があり、その値がサービスコードに残るという欠点があります。これに対し`ByRole`を使えば、実ユーザーと同じ方法で要素を探せ、固有の役割を持つ要素を容易に特定できます。これはアクセシビリティに配慮したマークアップ構造があってこそ可能なことです。
+
+```js
+// querySelector を使う場合（マークアップ構造の変更に弱い）
+expect(
+  document.querySelector("ul > li:nth-child(2) > button")
+).toBeInTheDocument();
+
+// getByTestId を使う場合（テスト用属性がサービスコードに残る）
+render(<button data-testid="save-btn">保存</button>);
+expect(screen.getByTestId("save-btn")).toBeInTheDocument();
+```
+
+つまりアクセシビリティは、すべてのユーザーのためであると同時に、開発者にとっても、より堅牢で保守しやすいコードを書く助けになるのです。