swift-accessibility-skill

プラットフォームのアクセシビリティ

概要

すべての対応プラットフォームで、SwiftUI、UIKit、AppKit のアクセシビリティを適用します。App Store のアクセシビリティに関する栄養ラベルの全 9 カテゴリ（VoiceOver、音声コントロール、大きな文字、ダークインターフェイス、色に依存しない識別、十分なコントラスト、モーションの軽減、字幕、音声解説）を対象とします。

このスキルでは、ネイティブのプラットフォーム API（自動で利用できるサポートを提供）を優先し、アーキテクチャに関する意見を交えず、事実に基づいたガイダンスを提供します。

初稿のルール

初稿にアクセシビリティを含めてください。何も設定していない要素を作成し、後から修正することは避けてください。既存コードへのアクセシビリティの後付けは、最初から組み込むより難しく、抜け漏れが生じやすく、結果も劣ります。

パターンが自明でない場合を除き、コード内にコメントを追加しないでください。推測したラベルには // [VERIFY] を付けてください。SF Symbol の名前が、ユーザーに提示する意図した意味と一致しないことがあるためです。

状況	初回の記述で必須の対応
Button ／ NavigationLink — アイコンのみ	// [VERIFY] を付けて .accessibilityLabel("…")
Button ／ NavigationLink — 表示テキストあり	追加設定なし — テキストが自動的にラベルになります
Image — 意味のある画像	.accessibilityLabel("…")
Image — 装飾用	.accessibilityHidden(true)
withAnimation ／ .transition ／ .animation	@Environment(\.accessibilityReduceMotion) を使い、アニメーションを条件付きで適用
.font(.system(size:))	.font(.body) または @ScaledMetric に置き換え
色で状態やステータスを示す	色に加えて、図形、アイコン、またはテキストを追加
Button 以外の要素での onTapGesture	.accessibilityElement(children: .ignore) + .accessibilityAddTraits(.isButton) + .accessibilityLabel
カスタムスライダー ／ トグル ／ ステッパー	.accessibilityRepresentation { … } または .accessibilityValue + .accessibilityAdjustableAction
非同期のコンテンツ変更	利用可能性を確認するガードを付けて通知を投稿（iOS 17 以降では AccessibilityNotification.Announcement、それより前では UIAccessibility.post にフォールバック）
システムの .sheet ／ .fullScreenCover	追加設定なし — SwiftUI が自動的にフォーカスを閉じ込めます（カスタムオーバーレイではフォーカス管理が必要です）
AVPlayer ／ 動画	AVPlayerViewController を使用 — 字幕と音声解説を標準で利用できます
タップ可能なカスタムビュー	.frame(minWidth: 44, minHeight: 44)
新しい SwiftUI ビュー	Xcode Canvas Variants で検証（Accessibility Summary を参照）
NSButton — アイコンのみ（AppKit）	// [VERIFY] を付けて setAccessibilityLabel("…")
カスタムの NSView インタラクティブ要素（AppKit）	setAccessibilityElement(true) + ロール（setAccessibilityRole(.button)）+ ラベル
AppKit のモーダル ／ ポップアップ UI	フォーカスを閉じ込め、キーボードと VoiceOver から閉じる操作にアクセスできるようにする
新しい AppKit ビュー ／ コントローラー	Accessibility Inspector とキーボードのみでの完全な操作で検証

ネイティブコントロール（Button、Toggle、Stepper、Slider、Picker、TextField）を優先してください。これらはアクセシビリティを完全に自動でサポートします。カスタムのインタラクティブビューには明示的な対応が必要です。 AppKit では、カスタムの NSView による操作を実装する前に、ネイティブコントロール（NSButton、NSPopUpButton、NSSlider、NSSegmentedControl、NSTextField）を優先してください。

例 — アイコンのみのボタン：

Button {
    shareAction()
} label: {
    Image(systemName: "square.and.arrow.up")
}
.accessibilityLabel("Share") // [VERIFY] confirm label matches intent

例 — Reduce Motion に応じたアニメーションの適用：

@Environment(\.accessibilityReduceMotion) private var reduceMotion

withAnimation(reduceMotion ? nil : .spring()) {
    isExpanded.toggle()
}

テストと検証の詳しい手順 → references/testing-auditing.md

ワークフロー

参照先の選択ルール

回答する前に、ユーザーの意図に最も合う参照ファイルを主参照ファイルとして 1 つ選び、最初に読み込んでください。 追加の参照ファイルは、依頼が複数の領域に明示的にまたがる場合（例：VoiceOver + Dynamic Type + WCAG マッピング）、または主参照ファイルに必要な基準が記載されていない場合にのみ読み込んでください。

1) 新しいコードを実装する

初稿のルールを適用し、初稿からアクセシビリティに対応してください。コメントは追加しないでください。 iOS 15 より後に導入された API には、必ず #available ガードを追加し、古い OS での代替動作を用意してください。 記述した後、初稿のルールの表に照らして確認し、抜け漏れを出力前に修正してください。 コードの後に Accessibility Summary（以下を参照）を追加してください。

2) 既存コードの改善または修正

コメントを付けずに修正を適用します。 iOS 15以降で導入されたAPIには、必ず#availableガードを追加し、古いOS向けのフォールバック動作を用意します。 修正後、First-Draft Rulesの表に照らして確認し、不足があれば出力前に修正します。 コードの後にアクセシビリティの概要を追加します。

• 変換パターンの場合 → examples/before-after-swiftui.md、examples/before-after-uikit.md、またはexamples/before-after-appkit.md
• プラットフォーム固有の問題の場合 → references/platform-specifics.md

3) 既存コードの監査

ユーザーが明示的に「audit」「how accessible is this?」「review accessibility」と依頼した場合のみ行います。

クイック修正モード — ユーザーがブロッカーのみ／重大な問題のみを対象とするよう依頼した場合（例：「ブロッカーだけを修正」「クイック修正」「重大な問題のみ」）：Blocks Assistive TechとDegrades Experienceの問題のみを対処します。Incomplete Supportは対象外とします。

包括モード（デフォルト）— Incomplete SupportやNutrition Labelの不足を含む、すべての重大度に対処します。

• トリアージプレイブックに従ってカテゴリ別に問題を特定します
• 以下の監査出力形式に従って書式を整えます
• WCAG準拠の対応付けについては、references/wcag-mapping.mdを参照します
• QAへの引き継ぎには、resources/qa-checklist.mdを使用します

4) Nutrition Labelの推奨案を作成

→ references/nutrition-labels.md — 公式の合格／不合格基準を含む、全9カテゴリ

ユーザーがApp Store Accessibility Nutrition Labelの推奨案の作成または下書きを依頼した場合は、次の形式で出力します。

**Accessibility Nutrition Label recommendation**

**App version evaluated:** [version or "Current build"]
**Scope reviewed:** [common tasks / screens evaluated]

**You could claim:**
- [labels where every common task is ✅ or —]

**Why you could claim them:**
- [label]: [brief reason tied to completed common-task coverage]

**You should not claim:**
- [labels blocked by any ❌]
- [labels that are not applicable]

**Why you should not claim them:**
- [label]: [blocked task or why the label is not applicable]

**Common-task verification**
| Common Task | VoiceOver | Voice Control | Larger Text | Dark Mode | No Color | Contrast | Motion | Captions | Audio Desc |
|---|---|---|---|---|---|---|---|---|---|
| [task] | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — | ✅ / ❌ / — |

**Recommendation summary**
- You could claim: [labels]
- You should not claim: [labels]

「claim」と無条件に述べないでください。レビュー対象の範囲に基づく推奨案として表現します。 その列の一般的なタスクに❌が1つでもある場合は、ラベルを提案しないでください。—は、そのアプリまたはフローにラベルが本当に該当しない場合にのみ使用します。

アクセシビリティの概要

コードの生成および修正タスク（モード1、2）の後に追加します。ただし、ユーザーがコードのみを明示的に要求した場合を除きます。前置きは不要です。

**Accessibility applied:**
- [one bullet per pattern added — e.g. "`.accessibilityLabel` on icon-only Share button"]

**Verify in Xcode:**
- Use Canvas **Dynamic Type Variants** (grid icon → Dynamic Type Variants) to check layout at all text sizes
- Use Canvas **Color Scheme Variants** to check light and dark mode
- Use **Accessibility Inspector** (Xcode → Open Developer Tool) Settings tab to simulate Increase Contrast, Reduce Motion, Bold Text on the Simulator

**If Xcode is unavailable:**
- Run equivalent checks with platform accessibility inspector tools and manual setting toggles (Dynamic Type, Contrast, Reduce Motion, VoiceOver/Voice Control)

**Test on device:**
- [relevant items from Must Test on Device checklist]

何も追加していない場合（すべてネイティブコントロールの場合）は、「アクセシビリティを適用しました」を完全に省略します。 ユーザーから依頼がない限り、「Nutrition Labelの準備状況」は省略します。

監査出力形式

ユーザーが明示的に監査を依頼した場合のみ使用します。コードの生成または修正中は使用しません。

🔴 支援技術を利用できない — 完全に到達不能で、直ちに修正が必要 🟡 操作性が低下する — 到達可能だが、重大な操作上の支障がある 🟠 サポートが不十分 — Nutrition Labelの表示を妨げる不足がある ✅ コードで確認済み — 静的解析で正しいことを確認済み

次の内容で締めくくります。

実機でのテストが必要：Review Checklistの該当項目。 Nutrition Labelの準備状況：達成可能／[問題]により不可／該当なし。

基本ガイドライン

原則

• まずフレームワークとプラットフォームを特定します。 SwiftUIとUIKitではAPIが異なります。誤ったAPIを使うと、気付かないまま失敗することがあります。
• 各モディファイアには意味上の根拠が必要です。 表示テキストのあるButtonに.accessibilityLabelを追加すると、VoiceOverが自動的に読み上げるテキストを上書きしてしまい、かえって問題になります。
• iOS 17以降のAPIには#availableを使用します。 バージョン固有のAPIは、利用可能性を確認しないと古いOSでクラッシュします。
• 推測したラベルには[VERIFY]を付けます。 SF Symbol名（例：square.and.arrow.up）は、ユーザーが期待する読み上げ内容（「共有」など）と一致しないことがよくあります。推測したラベルは人による確認が必要です。
• UIAccessibility.isVoiceOverRunningに基づいて、UIの基本的な意味やレイアウトを変更しないでください。 関連するアクセシビリティ設定を直接確認し、実際のユーザーニーズに合わせてください。読み上げの重複を避けたり、支援技術の使用中に一時的なタイムアウトを延長したりするなど、限定的な調整は問題ありません。
• Nutrition Labelには、フロー全体を網羅する必要があります。 「VoiceOverに対応」と表示するなら、メイン画面だけでなく、ログイン、オンボーディング、購入、設定など、すべてのユーザーフローが機能する必要があります。
• ライトモードとダークモードの両方でコントラストをテストします。 ライトモードでWCAG 4.5:1を満たす色の組み合わせでも、背景色の違いによりダークモードでは基準を満たさないことがよくあります。

VoiceOver

• 装飾目的ではないすべての要素に、簡潔でコンテキストに依存しないラベルが必要です
• アイコンのみのボタンには .accessibilityLabel が必要です — 空欄は認められません
• 装飾画像：.accessibilityHidden(true)
• 状態はラベルではなく特性です：「Selected photo」ではなく .accessibilityAddTraits(.isSelected) を使います
• 関連する要素をグループ化します：.accessibilityElement(children: .combine)
• 動的な変更を通知します：iOS 17 以降では AccessibilityNotification.Announcement("Upload complete").post()、それ以前は UIAccessibility.post(notification: .announcement, argument: "Upload complete") を使用します
• 詳細なリファレンス → references/voiceover-swiftui.md または references/voiceover-uikit.md

Voice Control

• ラベルは表示されているテキストと完全に一致させる必要があります — 一致しないと「Tap [name]」が通知なく機能しなくなります
• アイコンのみの要素には .accessibilityInputLabels(["Compose", "New Message"]) を使用します
• すべてのインタラクティブ要素が「Show numbers」と「Show names」のオーバーレイに表示される必要があります
• スワイプでのみ表示される UI には、音声でアクセスできる代替手段が必要です（.accessibilityAction）
• 詳細なリファレンス → references/voice-control.md

Dynamic Type

• テキストスタイルのみを使用します：.font(.system(size: 16)) ではなく .font(.body) を使います
• カスタム値を拡大縮小します：@ScaledMetric(relativeTo: .body) var spacing: CGFloat = 8
• サイズ固定の UI 要素：.accessibilityShowsLargeContentViewer()
• アダプティブレイアウト：手動で dynamicTypeSize を確認するより、ViewThatFits（iOS 16 以降）を優先します — 収まるレイアウトを自動的に選択します
• 詳細なリファレンス → references/dynamic-type.md

Display Settings

• 視差効果を減らす：意味のあるアニメーションはディゾルブ／フェードに置き換え、装飾的なアニメーションは削除します
• コントラスト：セマンティックカラー（Color(.label)）を使用します。テキストは WCAG 4.5:1、テキスト以外は 3:1 です
• 色以外でも区別できるようにする：色に加えて形状／アイコン／テキストを追加します
• 透明度を下げる：有効時は .ultraThinMaterial を不透明なものに置き換えます
• 詳細なリファレンス → references/display-settings.md

Semantic Structure

• 読み上げ順：.accessibilitySortPriority(_:)（値が高いほど先に読み上げられます）
• 新しい画面にフォーカスする：.screenChanged 通知をポストします
• モーダルのフォーカス：accessibilityViewIsModal = true
• カスタムナビゲーション：accessibilityRotor(_:entries:)
• 詳細なリファレンス → references/semantic-structure.md

Motor / Input

• タッチターゲット：最小 44×44pt
• キーボード：Tab ですべての要素に移動でき、Escape ですべてのモーダルを閉じられるようにします
• Switch Control：スワイプのみのジェスチャには UIAccessibilityCustomAction を使用します
• 詳細なリファレンス → references/motor-input.md

クイックリファレンス

SwiftUI モディファイア

モディファイア	目的
.accessibilityLabel(_:)	テキスト以外の要素に対する VoiceOver 用テキスト
.accessibilityHint(_:)	結果の簡潔な説明
.accessibilityValue(_:)	現在の値（スライダー、進捗状況）
.accessibilityHidden(true)	装飾要素を非表示にする
.accessibilityAddTraits(_:)	セマンティックな役割または状態
.accessibilityRemoveTraits(_:)	継承した特性を削除する
.accessibilityElement(children:)	.combine / .contain / .ignore
.accessibilitySortPriority(_:)	読み上げ順（値が高いほど先になります）
.accessibilityAction(_:_:)	名前付きのカスタムアクション
.accessibilityAdjustableAction(_:)	増減
.accessibilityInputLabels(_:)	Voice Control 用の別名
.accessibilityFocused(_:)	プログラムによるフォーカス
.accessibilityRotor(_:entries:)	カスタム VoiceOver ローター
.accessibilityRepresentation(_:)	カスタムコントロールの AX ツリーを置き換える
.accessibilityIgnoresInvertColors(true)	スマート反転時に画像を保護する
.accessibilityShowsLargeContentViewer()	サイズ固定の UI 用ラージコンテンツビューア

@Environment の値

値	目的
\.accessibilityReduceMotion	アニメーションの適用を制御する
\.accessibilityReduceTransparency	ぼかし効果を置き換える
\.accessibilityDifferentiateWithoutColor	色以外のインジケーターを追加する
\.colorSchemeContrast	.standard / .increased
\.dynamicTypeSize	現在のテキストサイズ

Nutrition Labels → API

ラベル	主な API	参照
VoiceOver	accessibilityLabel、traits、actions、rotors	voiceover-swiftui.md、voiceover-uikit.md
Voice Control	accessibilityInputLabels、表示テキストとの照合	voice-control.md
Larger Text	@ScaledMetric、テキストスタイル、Large Content Viewer	dynamic-type.md
Dark Interface	colorScheme、セマンティックカラー	display-settings.md
Differentiate Without Color	形状＋色	display-settings.md
Sufficient Contrast	WCAG 4.5:1（テキスト）／3:1（非テキスト）	display-settings.md
Reduced Motion	accessibilityReduceMotion、アニメーションの制御	display-settings.md
Captions	AVPlayerViewController	media-accessibility.md
Audio Descriptions	AVMediaCharacteristic.describesVideoForAccessibility	media-accessibility.md

レビューチェックリスト

コードで確認できる項目

• アイコンのみのボタンに .accessibilityLabel が設定されている
• 装飾画像に .accessibilityHidden(true) が設定されている
• 状態はラベルではなく traits で表現されている
• フォントサイズがハードコードされていない — テキストスタイルまたは @ScaledMetric を使用している
• アニメーションが accessibilityReduceMotion に応じて制御されている
• セマンティックカラーを使用している（16 進数カラーをハードコードしていない）
• アイコンのみの要素に .accessibilityInputLabels が設定されている
• タッチターゲットが 44×44pt 以上である
• モーダルで .sheet() または accessibilityViewIsModal を使用している
• スワイプのみのアクションに .accessibilityAction による代替手段がある
• 動画に AVPlayerViewController を使用している
• 写真／地図／動画に .accessibilityIgnoresInvertColors() が設定されている
• XCUITest に #available ガード（iOS 17+／macOS 14+）付きの performAccessibilityAudit() と、古い OS バージョンでのフォールバックアサーションが含まれている

デバイスでテストする必要がある項目

• VoiceOver：ナビゲーション順、読み上げの流れ、画面遷移／モーダル表示後のフォーカス
• Voice Control：「番号を表示」で対象を網羅できること、「[name]をタップ」でアクティベートできること
• Switch Control：スキャン経路、カスタムアクションにアクセスできること
• Full Keyboard Access：Tab の順序、Escape キーでの閉じる操作
• Dynamic Type：最大サイズでのレイアウト — クリッピングや重なりがないこと
• Reduce Motion：すべてのアニメーションを確認すること
• グレースケールフィルター：色がなくても情報を理解できること
• Dark ＋ Increase Contrast：両モードでコントラストを確認すること
• キャプションと音声解説：自動的に有効になること

テスト手順の全文 → references/testing-auditing.md

トリアージ手順

支援技術を妨げる — 直ちに修正

• アイコンのみのボタンにラベルがない → references/voiceover-swiftui.md
• 画像に代替テキストがない → references/voiceover-swiftui.md
• カスタムビューがアクセシビリティツリーに含まれていない → references/voiceover-uikit.md
• VoiceOver がループする、または要素から抜け出せない → references/semantic-structure.md

エクスペリエンスを低下させる — 大きな使いづらさ

• Voice Control が要素を認識しない → references/voice-control.md
• VoiceOver ラベルが表示テキストと一致しない → references/voice-control.md
• タッチターゲットが 44×44pt 未満 → references/motor-input.md
• 色だけで違いを示している → references/display-settings.md
• 読み上げ順が不適切 → references/semantic-structure.md
• モーダルがフォーカスを閉じ込めない → references/semantic-structure.md

サポートが不完全 — Nutrition Label の申告を妨げる

• テキストが Dynamic Type に合わせて拡大されない → references/dynamic-type.md
• アニメーションが Reduce Motion を考慮しない → references/display-settings.md
• ダークモードでコントラストが低い → references/display-settings.md
• キャプションまたは音声解説がない → references/media-accessibility.md
• プラットフォームがアクセシブルでない → references/platform-specifics.md
• Nutrition Label の準備 → references/nutrition-labels.md

トラブルシューティング

誤ったフレームワークの API を適用している

症状： SwiftUI のモディファイアを UIKit／AppKit のコードで使用している、または異なるフレームワークのプラットフォーム API が混在している。 修正方法： API を適用する前に、import（import SwiftUI、import UIKit、import AppKit）からフレームワークを特定します。SwiftUI ではモディファイア、UIKit では UIAccessibility プロパティ、AppKit では NSAccessibility API を使用します。

ネイティブコントロールへのラベルの付けすぎ

症状： すでに表示テキストがある Button("Save") や Toggle("Dark Mode") に .accessibilityLabel が追加されています。 対処： 表示テキストがあるコントロールには .accessibilityLabel を追加しないでください。自動ラベルが上書きされ、画面上の表示と一致しなくなる可能性があります。ラベルを追加するのは、アイコンのみの要素やテキストのない要素に限ります。

プロジェクトのターゲットより新しい OS を必要とする API

症状： 可用性チェックなしで、プラットフォームのバージョンに依存する API（iOS/macOS/tvOS/watchOS/visionOS）を使用しています。 対処： サポートする各ターゲット OS に対して #available で条件分岐し、必要に応じて古い代替 API を使用してください。よくある置き換え：

• AccessibilityNotification.Announcement("…").post() → UIAccessibility.post(notification: .announcement, argument: "…")
• performAccessibilityAudit() → XCTest の手動アサーション
• ViewThatFits（iOS 16 以降） → @Environment(\.dynamicTypeSize) を使った手動のレイアウト切り替え
• コードを複数のプラットフォームで共有する場合は、複数プラットフォームの条件分岐を優先してください： if #available(iOS 17, macOS 14, tvOS 17, watchOS 10, visionOS 1, *) { ... }

アクセシビリティの概要がない

症状： コード生成後に「Accessibility applied」／「Test on device」の概要ブロックがありません。 対処： コード生成と修正タスク（ワークフローモード 1 と 2）の後には、必ずアクセシビリティの概要を追加してください。アクセシビリティのパターンが追加されていない場合（表示テキストのあるネイティブコントロールのみの場合）に限り、省略できます。

推測したラベルに [VERIFY] コメントがない

症状： SF Symbol 名やメソッド名から導出した .accessibilityLabel に // [VERIFY] コメントがありません。 対処： 推測したラベル（ユーザーが指定していないラベル）には、必ず // [VERIFY] confirm label matches intent を付けてください。square.and.arrow.up のような SF Symbol 名は、ユーザーが聞きたい内容と一致しないことがよくあります。

参考資料

• references/voiceover-swiftui.md — SwiftUI のアクセシビリティ修飾子、特性、アクション、ローター、通知
• references/voiceover-uikit.md — UIAccessibility プロトコル、カスタム要素、コンテナー、通知
• references/voice-control.md — 入力ラベル、「番号／名前を表示」、音声でアクセスできる代替手段
• references/motor-input.md — スイッチコントロール、フルキーボードアクセス、AssistiveTouch、tvOS のフォーカス
• references/dynamic-type.md — Dynamic Type、@ScaledMetric、ラージコンテンツビューアー、適応型レイアウト
• references/display-settings.md — 視差効果を減らす、コントラスト、ダークモード、カラー、透明度、反転
• references/semantic-structure.md — グループ化、読み上げ順、フォーカス管理、ローター、モーダルフォーカス
• references/media-accessibility.md — 字幕、音声解説、音声合成、グラフ
• references/testing-auditing.md — Accessibility Inspector、Xcode Canvas Variants、XCTest、performAccessibilityAudit()、手動テスト
• references/nutrition-labels.md — 9 つすべての栄養ラベルと合格／不合格基準
• references/wcag-mapping.md — WCAG 2.2 レベル A／AA の達成基準と SwiftUI/UIKit/AppKit API の対応
• references/assistive-access.md — Assistive Access（iOS 17 以降）、設計原則、テスト
• references/platform-specifics.md — macOS、watchOS、tvOS、visionOS 固有の情報
• examples/before-after-swiftui.md — SwiftUI の変換前／変換後
• examples/before-after-uikit.md — UIKit の変換前／変換後
• examples/before-after-appkit.md — AppKit（macOS）の変換前／変換後
• resources/audit-template.swift — アクセシビリティ監査を自動化するための、そのまま使える XCUITest ファイル（iOS 17 以降）
• resources/qa-checklist.md — 手動テスト用の単独 QA チェックリスト（テスターに渡してください）