【検証】 AIへの「アクセシビリティ指示」でデザインシステムの実装品質はどう変わるか

こんにちは。虎の穴ラボ株式会社のKTです。

最近はClaude Codeを使って個人的に欲しいなと思うWEBアプリを細々と開発しています。

開発しているとき、画面にデザインを適用すると一段とモチベーションが上がりませんか？（私は上がります💪）
私自身はデザインの素養はないのですが、Claude Codeの公式プラグイン「frontend-design」や自作のSkillsを使って試行錯誤しながらデザインを適用しています。

手探りでデザインシステムを作る中でふと思ったのが 「トレンドのデザインとアクセシビリティの両方を考慮したスタイルが一気に適用できたらいいのに」ということでした。
アクセシビリティをどう言語化したら良いのか、どのように指示すればデザインと両立できるのか、コツを掴みたいと思ったのです。

そこで、本記事では Claude Code の Skills機能を使い、Liquid Glass風のデザインシステムを「アクセシビリティ指示なし」と「アクセシビリティ指示あり」の 2 パターンで実装して、実測データをもとに結果を比較してみました。

実験の設計

今回Liquid Glass風を選定した理由は「Liquid Glass風にして」「トレンドのデザインにして」と指示した時に背景と文字色のコントラスト比が低いデザインが生成されがちな印象があったためです。

この問題がアクセシビリティについての指示追加でどれだけ改善するのかを検証します。

サンプルサイト

架空のプロジェクト管理SaaS「Sample Dashboard」を題材に、以下の 3ページを作成しました。

LP（ランディングページ）：Hero セクション、Bento Grid の機能紹介、料金プラン
Login：ログイン / サインアップフォーム、バリデーション
Dashboard：サイドバー、統計カード、タスクテーブル、Bento Grid レイアウト

技術スタックは Next.js（App Router）+ TypeScript + Tailwind CSS + shadcn/ui です。

3パターン比較

パターン	内容
ベースライン	shadcn/ui デフォルトのみ。カスタムスタイルなし
without-a11y	Liquid Glass + Bento Grids のデザインスキルを適用。アクセシビリティの指示なし
with-a11y	同じデザインスキルに、デジタル庁「ウェブアクセシビリティ導入ガイドブック」の要件を追加

アクセシビリティの言語化としてすぐに参考にできそうだったのが「ウェブアクセシビリティ導入ガイドブック」だったため採用しました。また、いずれのパターンでも「frontend-design」スキルは使用していません。

評価基準

Lighthouse アクセシビリティスコア
コントラスト比（Colour Contrast Analyser で実測）
セマンティック HTML の構造（DevTools で確認）
メディアクエリ対応（prefers-reduced-motion, prefers-contrast）
スキルに書いた指示の実装率

Claude Code Skills とは

Claude Code の Skills は、タスク固有の知識や手順をまとめたフォルダで、Claude が必要に応じて動的に読み込む仕組みです。プロジェクトの .claude/skills/ ディレクトリに SKILL.md ファイルを配置すると、Claude Code がタスクに応じて自動的にスキルを参照してくれます。

.claude/skills/
└── design-pattern-with-a11y/
    └── SKILL.md

スキルファイルは YAML フロントマター（名前と説明）と Markdown 本文で構成されています。フロントマターの description が、Claude がスキルを使うかどうかを判断するトリガーになります。

今回は、このスキルファイルに「デザインシステムの CSS 定義」と「アクセシビリティの実装ルール」を記述して Claude Code に渡すことで、デザインとアクセシビリティの両立を試みました。

ベースライン：shadcn/ui デフォルト

まず shadcn/ui のデフォルトコンポーネントだけで 3ページを実装しました。これがデザインスキル適用前の比較基準になります。

Claude Code への指示はこちらです：

@references/baseline-spec.md を読んで、この仕様書通りに3ページを実装してください。

以下のルールを守ってください：
- shadcn/ui のデフォルトテーマのみ使用し、カスタムスタイルは一切加えない
- 必要な shadcn/ui コンポーネントをインストールして使用する
- ダミーデータはハードコードで構いません
- 3ページ: / (LP), /login (ログイン), /dashboard (ダッシュボード)

SaaSダッシュボード風と指示しているため、AI生成ではおなじみのキャッチコピー付きのサンプルサイトが作成できました。

without-a11y：Liquid Glass + Bento Grids

スキルファイル

以下が without-a11y のスキルファイル全文です。Liquid Glass の CSS 変数、Glass マテリアルのバリエーション、Bento Grid レイアウト、タイポグラフィ、コンポーネントスタイル、アニメーションを定義しています。アクセシビリティに関する指示は意図的に含めていません。

※ SKILL.md の全文はリポジトリの skills-master/design-pattern-without-a11y/SKILL.md を参照

github.com

Claude Code への指示

Liquid Glass + Bento Grids デザインスキルを使って、現在の Sample Dashboard の3ページすべてに
デザインを適用してください。

以下のルールを守ってください：
- SKILL.md に定義された CSS 変数、Glass マテリアル、Bento Grid レイアウト、
  タイポグラフィ、コンポーネントスタイル、アニメーションをすべて適用する
- ダークテーマをデフォルトにする（LP はライトモードも可）
- 既存の機能やコンテンツは変更せず、見た目のみ変更する
- shadcn/ui のコンポーネントは引き続き使用するが、スタイルを上書きする

結果

Liquid Glass 風の半透明マテリアルと Bento Grid のレイアウトが適用されて、見た目はかなりモダンな印象になりました。でも、この時点で実はいくつかの問題が潜んでいます（詳細は後述の計測結果で！）。

with-a11y：デジタル庁ガイドライン反映

スキルファイルの差分

with-a11y のスキルファイルは、without-a11y の全内容に加えて、★マーク付きでアクセシビリティ指示を追加したものです。

追加した原則（5 項目）：

Contrast Guaranteed：Glass マテリアル上のテキストでコントラスト比 4.5:1 以上を確保（WCAG 1.4.3）
Not Color Alone：色だけで情報を伝えない。色 + アイコン + テキストの 3 重で区別（WCAG 1.4.1）
Keyboard Navigable：すべてのインタラクティブ要素にフォーカスインジケーターを設定（WCAG 2.1.1, 2.4.7）
Semantic Structure：適切な HTML 要素と ARIA 属性を使用（WCAG 1.3.1, 1.3.2）
Reduced Motion Respected：prefers-reduced-motion: reduce でアニメーション無効化（WCAG 2.3.3）

追加した実装ルール（12 項目）：

 9. コントラスト検証必須（Glass 背景上のテキスト 4.5:1 以上）
10. フォーカスリング必須（Glass 背景に溶け込まない明るい色）
11. 色だけで情報を伝えない（アイコン・テキスト併用）
12. ラベル必須（プレースホルダーをラベル代わりにしない）
13. DOM順序 = 視覚順序（CSS order 禁止）
14. 見出し階層の遵守（h1→h2→h3、レベル飛ばし禁止）
15. ランドマーク設定（header, nav, main, footer + aria-label）
16. スキップリンク設置
17. prefers-reduced-motion 対応
18. prefers-reduced-transparency 対応
19. prefers-contrast: more 対応
20. 最小タッチターゲット 44x44px

CSS の具体的な変更点：

項目	without-a11y	with-a11y	変更理由
テキスト不透明度（primary）	`rgba(255,255,255, 0.90)`	`rgba(255,255,255, 0.95)`	コントラスト確保
テキスト不透明度（secondary）	`rgba(255,255,255, 0.60)`	`rgba(255,255,255, 0.75)`	コントラスト確保
テキスト不透明度（tertiary）	`rgba(255,255,255, 0.40)`	`rgba(255,255,255, 0.60)`	コントラスト確保
Glass 背景不透明度	`rgba(255,255,255, 0.08)`	`rgba(255,255,255, 0.12)`	テキスト可読性
フォーカスリング	未定義	`3px solid oklch(0.80 0.18 240)`	Glass 上での視認性
`prefers-reduced-motion`	未定義	`animation: none`	動作制約対応
`prefers-contrast: more`	未定義	Glass を不透明化 + ボーダー強化	高コントラスト対応
`prefers-reduced-transparency`	未定義	`backdrop-filter: none`	半透明制約対応

※ SKILL.md の全文はリポジトリの skills-master/design-pattern-with-a11y/SKILL.md を参照

github.com

Claude Code への指示

アクセシブルな Liquid Glass + Bento Grids デザインスキルを使って、
現在の Sample Dashboard の3ページすべてにデザインを適用してください。

まず ../references/20251016_introduction_to_web_accessibility.pdf を読んで、
ウェブアクセシビリティの要件を把握した上で、SKILL.md のルールに従って実装してください。

以下のルールを守ってください：
- SKILL.md に定義された CSS 変数、Glass マテリアル、Bento Grid レイアウト、
  タイポグラフィ、コンポーネントスタイル、アニメーションをすべて適用する
- ★マーク付きのアクセシビリティ実装ルール（20項目）を必ずすべて適用する
- ダークテーマをデフォルトにする（LP はライトモードも可）
- 既存の機能やコンテンツは変更せず、見た目のみ変更する
- セマンティック HTML 要件（スキップリンク、aria-label、scope 等）を必ず実装する
- prefers-reduced-motion, prefers-reduced-transparency, prefers-contrast に対応する

結果

見た目は without-a11y とほぼ同じ Liquid Glass デザインを維持しつつ、アクセシビリティが強化されています。パッと見ではほとんど区別がつかないのがポイントです。

【比較検証】Lighthouseスコアとコントラスト比の実測結果

デザイン適用後のサイトの状態を実際に数値で比較してみましょう。

Lighthouse アクセシビリティスコア

ページ	without-a11y	with-a11y
LP	98	96
Login	95	96
Dashboard	93	96

これは意外な結果でした。
without-a11y（アクセシビリティ指示なし）の LP（98）が with-a11y（指示あり）（96）を上回っています！
Lighthouse の自動チェックだけではアクセシビリティの品質を正しく評価できないことがわかります。

デジタル庁のガイドブックにも、まさにこの点が指摘されています。

チェックツールで見つけられる問題は、ウェブアクセシビリティの問題の2割から3割程度です。ウェブアクセシビリティは基本的に「人がチェックする必要がある」と考えましょう。

― 出典：デジタル庁「ウェブアクセシビリティ導入ガイドブック」（DS-671.2、2025年10月16日版）p.13

コントラスト比

Colour Contrast Analyser を使って、画面上のレンダリング結果から直接計測しました。
テキストの文字色と、文字に近い位置の背景色をスポイトツールでそれぞれ拾い、コントラスト比を算出しています。
Liquid Glass風のような半透明背景では DevTools の自動計算が効かないため、この方法で計測しています。

WCAG AA 基準は通常テキストで 4.5:1、大テキスト（24px 以上太字 / 29px 以上通常）で 3:1 です。

LP - Hero テキスト（大テキスト、基準 3:1）：

箇所	without-a11y	with-a11y	判定
「プロジェクト管理を、」	16.2:1	15.8:1	両方 ✅
「もっとシンプルに。」左端	7.5:1	6.5:1	両方 ✅
「もっとシンプルに。」右端	5.7:1	5.8:1	両方 ✅

Hero テキストは大テキストのため基準が緩く、両パターンとも合格です。ただし Liquid Glass の特性上、グラデーション背景の位置によってコントラスト比が大きく変動する点（左端 7.5:1 vs 右端 5.7:1）には注意が必要です。

LP - Glass カード上の本文（通常テキスト、基準 4.5:1）：

箇所	without-a11y	with-a11y	判定
「タスク管理」カード	6.7:1	8.6:1	両方 ✅、with-a11y が +1.9 向上

Glass の不透明度を 0.08 → 0.12 に引き上げた効果が出ています。

Dashboard - バッジテキスト（通常テキスト、基準 4.5:1）：

箇所	without-a11y	with-a11y	判定
ステータス「進行中」	3.8:1 ❌	4.4:1 ❌	改善したが未達（あと 0.1！）
ステータス「レビュー」	5.1:1 ✅	5.7:1 ✅	+0.6 向上
ステータス「完了」	5.1:1 ✅	4.8:1 ✅
ステータス「未着手」	5.6:1 ✅	7.6:1 ✅	+2.0 向上
優先度「高」	3.5:1 ❌	3.3:1 ❌	未改善
優先度「中」	4.9:1 ✅	5.6:1 ✅	+0.7 向上
優先度「低」	5.6:1 ✅	8.1:1 ✅	+2.5 向上

Login - プレースホルダー（通常テキスト、基準 4.5:1）：

箇所	without-a11y	with-a11y	判定
プレースホルダー	3.2:1 ❌	3.5:1 ❌	改善したが未達

with-a11y で「進行中」バッジは 3.8:1 → 4.4:1 と改善しましたが、基準の 4.5:1 にあと 0.1 届きませんでした。
優先度「高」とプレースホルダーは両パターンとも不合格で、これらは人の手で修正すべき箇所です。

コントラスト比以外の差分

ここからがコントラスト比だけでは見えない、本当の差分です。

項目	without-a11y	with-a11y
スキップリンク	❌ なし	✅ あり
フォーカスリング	あり（デフォルト）	✅ あり（水色、視認性高い）
`aria-label`（nav）	❌ なし	✅ あり
`aria-current="page"`	❌ なし	✅ あり
`prefers-reduced-motion`	❌ 変化なし	✅ アニメーション停止
`prefers-contrast: more`	❌ 変化なし	✅ 不透明度上昇（8.4:1→11.3:1）

特に注目してほしいのが prefers-contrast: more の結果です。with-a11y では Glass カードのコントラスト比が 8.4:1 から 11.3:1 に向上しました。without-a11y では何も変化しません。ユーザーが OS の設定でコントラストを上げても、対応していなければ意味がないということですね。

差分箇所の補足

スキルに書いたが実装されなかった項目

ここも正直に報告します。以下の 3 項目は with-a11y のスキルファイルに明記したにもかかわらず、Claude Code が実装してくれませんでした。

項目	SKILL.md の指示	結果
テーブルの `<caption>` / `<th scope="col">`	「caption でテーブルの目的を示す、scope 属性で見出しセルの関連を明示する」	未実装
バッジのアイコン併用	「各バッジにはアイコンも併用し、色だけに依存しない」	未実装
エラー表示のアイコン併用	「エラー状態: 色だけでなくアイコンとテキストで伝える」	未実装

CSS スタイルの指示（Glass の不透明度、フォーカスリング色、メディアクエリ対応）はほぼ忠実に反映された一方で、HTML のセマンティック構造や UI の細かい要素（アイコン併用）は反映率が低い傾向がありました。スキルに書けば全部やってくれるわけではない、というのは重要な学びです。

なぜ反映されなかったのか？

原因の一つとして、SKILL.md のファイルサイズが大きすぎたことが考えられます。今回の with-a11y の SKILL.md は約 890 行ありました。Claude Code の公式ドキュメントでは次のように推奨されています。

Keep SKILL.md under 500 lines. Move detailed reference material to separate files.

― Claude Code Docs: Add supporting files

890 行の中にデザイン定義とアクセシビリティルールが混在していたため、ファイル後半にあった HTML 構造の指示（caption, scope, アイコン併用）が読み飛ばされた可能性があります。CSS の具体値はファイルの前半〜中盤に集中しており、反映率が高かったことと整合します。

対策としては、スキルファイルを以下のように分割する構成が考えられます。

.claude/skills/liquid-glass-a11y/
├── SKILL.md                        # 原則とルール一覧（500行以内）
├── references/
│   ├── glass-materials.md          # Glass CSS 定義
│   ├── bento-grid.md               # Bento Grid レイアウト
│   ├── components.md               # コンポーネントスタイル
│   ├── animations.md               # アニメーション定義
│   └── a11y-html-templates.md      # セマンティック HTML テンプレート
└── scripts/
    └── contrast-check.sh           # コントラスト比チェック用スクリプト

SKILL.md 本体にはデザイン原則、アクセシビリティルール 20 項目、各ファイルの参照指示だけを記述し、CSS やHTML のコードブロックは references/ 配下に移す形です。これなら Claude Code が必要な参照ファイルだけを段階的に読み込む（Progressive Disclosure）ので、指示の抜け漏れが減ることが期待できます。

まとめ：アクセシブルなデザインスキルの作り方

3 つの結論

1. Lighthouse スコアだけではアクセシビリティは測れません。

without-a11y の LP は 98 点で、with-a11y の 96 点を上回りました。
しかし、実際には without-a11y にはコントラスト不合格 4 箇所、メディアクエリ未対応、スキップリンクなし、ARIA 属性なしという問題があります。
自動チェックツールが検出できるのは問題の 2〜3 割だという事実を、今回の実験データで裏付けることができました。

2. スキルにアクセシビリティ指示を入れることで、確実に改善する領域があります。

特に効果が高かったのは以下の項目です。

メディアクエリ対応（prefers-reduced-motion, prefers-contrast）：CSS レベルの指示なので反映率が高いです
フォーカスリングの色指定：具体的な CSS 値を示すと忠実に実装されます
ARIA 属性（aria-label, aria-current）：追加するだけなのでコストが低いです
スキップリンク：HTML テンプレートを示すと確実に実装されます
コントラスト比の底上げ：Glass 不透明度やテキスト不透明度の数値を具体的に指定した効果が出ています

3. スキルだけでは完全にはなりません。人のチェックが不可欠です。

スキルに書いても実装されなかった 3 項目があり、コントラスト不合格も 3 箇所残りました。
今回参考にしたデジタル庁のガイドラインでも「ウェブアクセシビリティは基本的に人がチェックする必要がある」と述べられている通り、こうしたスキルはベースラインの底上げツールであって、現状は最終的な品質を人が担保する必要があります。

スキルファイル設計のコツ

実験を通じてわかった、スキルファイルの書き方のポイントをまとめます。

反映されやすい指示の書き方：

CSS の具体値を示す：rgba(255,255,255, 0.95) のように数値で指定するとそのまま使われます
メディアクエリの完全なコードブロックを示す：@media (prefers-reduced-motion: reduce) { ... } のように書くと効果的です
CSS 変数のコメントに理由を書く：/* ★ 0.08 → 0.12 に引き上げ（コントラスト確保） */ のようにすると、Claude が意図を汲み取りやすくなります

反映されにくい指示と対策：

HTML の構造指示（caption, scope, アイコン併用）→ テンプレートの HTML コードブロックだけでなく、ルールセクションにも明示的に列挙しましょう
「〜すべき」のような抽象的な指示 → 具体的なコードに落とし込む必要があります
大量の指示の末尾にある項目 → 重要な指示ほど先頭に配置するのがおすすめです

再現手順

本記事の実験は以下のリポジトリで再現できます。ぜひ試してみてください！

git clone https://github.com/tkana-dev/sample-dashboard
cd a11y-skill-blog/sample-dashboard
npm install

# ベースライン
git checkout baseline
npm run dev

# Liquid Glass（アクセシビリティ未考慮）
git checkout without-a11y
npm run dev

# Liquid Glass（アクセシビリティ考慮）
git checkout with-a11y
npm run dev

次にやりたいこと

今回の実験では SKILL.md を 1 ファイルに全部詰め込んだ結果、一部の指示が反映されませんでした。
実際にスキルを運用する際は、公式ドキュメントの推奨に従って SKILL.md を 500 行以内に抑え、詳細な定義を references/ に分割した構成にすることで、指示の抜け漏れを防げるかもしれません。
この点は今後の課題として意識しておきたいと思います。