ドキュメントサイトのLighthouseスコア改善：フォント最適化・アクセシビリティ修正・プロモ改善

2026年05月21日 23:21 JST shoelace-style/webawesome

https://github.com/shoelace-style/webawesome/pull/2420

WebAwesomeのドキュメントサイトを対象に、レンダーブロッキングフォントの解消、Lighthouse a11y監査の3項目クリア、プロモーションダイアログの不要リソース読み込み抑制を一括実施しました。これにより、ページの初期表示速度とアクセシビリティが改善されます。

背景

ドキュメントサイトのLighthouseスコアを引き下げる要因が複数存在していました。フォント読み込み・アクセシビリティ・コントラスト比・不要リソースの事前読み込みという4つの独立した問題が積み重なり、パフォーマンスとアクセシビリティの両スコアを圧迫していた状況です。

cera-typeface.css は287 KBのスタイルシートで、4つの.woff2ファイルをBase64インライン化していました。Base64エンコードはバイナリサイズを約33%増加させ、さらにスタイルシートはレンダーブロッキングリソースであるためブラウザの並列プリロードも妨げ、通常のフォントキャッシュの恩恵も受けられないという三重の問題を抱えていました。

アクセシビリティ面では、アイコンのみで構成されたボタンへのラベル付けが不十分で、Lighthouseのaria-prohibited-attr・button-name・ナビゲーションリンクの識別名に関する監査で失敗していました。またプロモーションダイアログは、ユーザーが一度閉じた後も149 KBのポスター画像を毎回読み込んでいました。

技術的な変更

フォントの分割・サブセット化

CeraフォントをBase64インライン埋め込みから実ファイル配信に移行し、CSSサイズを287 KBから723バイトに削減しました。docs/assets/fonts/配下にcera-round-pro-400.woff2・cera-round-pro-500.woff2・cera-round-pro-700.woff2・cera-round-pro-900.woff2の4ファイルを追加し、cera-typeface.cssの@font-faceブロックはファイル参照に書き換えています。すべての@font-faceにfont-display: swapを適用し、フォント読み込み中もテキストが表示されるようになっています。

グリフはラテン文字・句読点・通貨記号（U+0000-024F,U+2000-206F,U+20A0-20CF）にサブセット化されています。英語のドキュメントサイトでは不要なキリル文字・ギリシャ文字・ベトナム語拡張・CJK文字を除外し、emダッシュ・スマートクォート・省略記号・通貨記号は維持することで、フォントの総バイナリサイズを220 KBから103 KBに削減しています。

head.njkでは、初期表示に使用する400ウェイトのみを<link rel="preload">で優先読み込みするよう変更されました。

変更後（head.njk）:

<link rel="preload" as="font" type="font/woff2" href="/assets/fonts/cera-round-pro-400.woff2" crossorigin>
{% if pageClass == 'home' %}
  <link rel="preload" as="image" type="image/svg+xml" href="/assets/images/bg-wa-pattern-light.svg" media="(prefers-color-scheme: light)">
  <link rel="preload" as="image" type="image/svg+xml" href="/assets/images/bg-wa-pattern-dark.svg" media="(prefers-color-scheme: dark)">
{% endif %}

ホームページ限定でSVG背景画像もプリロードするよう追加されており、400ウェイト以外のフォントはCSSの@font-face定義により実際に使用されたタイミングで遅延読み込みされます。

アクセシビリティの修正

Lighthouseのa11y監査で失敗していた3箇所を修正しました。各修正の対応は以下のとおりです。

Font Awesomeナビリンク（#product-font-awesome）: <a>タグにaria-label="{{ site.siblings.fontAwesome.name }}"を追加。ツールチップのfor=によるアクセシブル名はツールチップのShadow DOMがレンダーされるまで信頼できないため、明示的なラベルで解決しています。
カラースキームセレクター（color-scheme-selector.njk）: アイコンのみの<wa-button>内の<wa-icon>にlabel="Select Color Scheme"を追加。
テーマセレクター（theme-selector.njk）: 同様に<wa-icon name="brush">にlabel="Select Theme"を追加。

<wa-button>のアイコンのみパターンでは、ホスト要素のaria-*属性とツールチップによるラベル付けがaria-prohibited-attr違反を引き起こしていたため、スロット内の<wa-icon>にlabel属性を付与する方式に統一されています。

変更前:

<wa-icon name="sun-bright" variant="regular" class="only-light"></wa-icon>
<wa-icon name="moon-stars" variant="regular" class="only-dark"></wa-icon>

変更後:

<wa-icon name="sun-bright" variant="regular" class="only-light" label="Select Color Scheme"></wa-icon>
<wa-icon name="moon-stars" variant="regular" class="only-dark" label="Select Color Scheme"></wa-icon>

プロモーションダイアログの最適化

プロモーションダイアログのポスター画像を遅延読み込みに変更し、dismissedユーザーへの不要なリソース配信を防止しました。dialog-ba-kickstarter.njkでは2点の変更が行われています。

まず、テンプレートの条件分岐が{% if isBuildAwesomePromoActive %}から{% if isBuildAwesomePromoActive and not isBuildAwesomePromoDismissed %}に変更され、LocalStorageでdismissedと記録されたユーザーにはダイアログHTMLそのものが出力されなくなりました。次に、ポスター画像placeholder-ba-video.png（149 KB）がsrc属性からdata-src属性に変更され、Vimeo iframeと同様にinitDialog()内でのみ実際に読み込まれるようになっています。

変更前:

<img src="/assets/images/placeholder-ba-video.png" alt="" />

変更後:

<img data-src="/assets/images/placeholder-ba-video.png" alt="" />

コントラスト比の修正

utils.css内の.brand-build-awesomeスコープで--wa-color-brand-50がvar(--brand-build-awesome-green)（#00a776）から#198560に変更されました。#00a776の白色テキストに対するコントラスト比は3.09:1でWCAGのAA基準（4.5:1）を下回っていましたが、#198560では4.59:1となり基準を満たしています。バナー・ダイアログCTAのボタン・本文リンクに適用される一方、ロゴ・ナビゲーションは視覚的ブランドカラーを維持するため引き続き--brand-build-awesome-green（#00a776）を使用します。

設計判断

フォント配信の方針として、CDNではなくドキュメントサイト自身のオリジンからの配信が選択されています。CDN配信ではCORS設定やキャッシュコントロールのコントロールが難しくなる一方、自ホスト配信はHTTPキャッシュヘッダーの完全なコントロールを可能にします（1年間のキャッシュ設定は関連PRで実施予定）。Base64インラインからファイル参照への変換により、4ウェイトの並列プリロードが可能になるという副次的な利点もあります。

アクセシビリティの修正方針として、ツールチップのShadow DOM依存を避け、<wa-icon>のlabel属性という確実な手段が採用されています。ツールチップは視覚的な補足情報として維持しつつ、スクリーンリーダー向けのアクセシブル名は独立して提供するという分離が明確です。

ポスター画像の遅延読み込みはdismissedユーザーへの効果が主目的とPR本文で明記されており、Lighthouse測定中は500msの自動オープンが依然として動作するため初回ユーザーへの影響は限定的です。PR本文では「auto-openの遅延またはサーバーサイドでのダイアログHTML出力の制御」が今後の課題として言及されており、今回の変更はその前段階の対処となっています。

まとめ

本PRは、フォント配信戦略の根本的な見直し（Base64インライン→実ファイル）、アイコンボタンのアクセシブル名付与パターンの統一、条件付きリソース読み込みの徹底という3つの独立した改善を組み合わせることで、Lighthouseのパフォーマンス・アクセシビリティ双方のスコアに寄与しています。特にフォントのサブセット化とファイル分割は、287 KBのレンダーブロッキングリソースを723バイトのCSSと103 KBのフォントファイル群に置き換えるという質的な転換であり、ブラウザキャッシュの活用も含めた持続的な改善効果が期待されます。