ドキュメントサイドバーにカスタムアイコンを追加

2026年02月05日 07:04 JST shoelace-style/webawesome

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

WebAwesomeのドキュメントサイドバーに、セクション見出しを視覚的に識別しやすくするカスタムアイコンが追加されました。この変更により、ユーザーは目的のセクションをより直感的に見つけられるようになります。

背景

ドキュメントサイドバーのセクション見出しは、テキストのみで構成されていました。セクション数が増えるにつれ、視覚的な手がかりが不足し、ユーザーが目的のセクションを素早く識別することが困難になっていました。#2019 では、各セクションに意味を持つアイコンを追加することで、この問題に対処しています。

PRに添付されたBefore/Afterの比較画像からも、アイコン追加によるサイドバーの視覚的改善が確認できます。

技術的な変更

packages/webawesome/docs/_includes/sidebar.njk テンプレートファイルで、セクション見出しの構造が変更されました。各 <h2> 要素に wa-cluster クラスと wa-icon コンポーネントが追加されています。

変更前:

<h2>Getting Started</h2>

変更後:

<h2 class="wa-cluster wa-gap-xs">
  <wa-icon name="rocket-launch" variant="regular" aria-hidden="true"></wa-icon>
  Getting Started
</h2>

アイコンの選択は各セクションの内容を反映しています：

Getting Started: rocket-launch（開始・起動）
Resources: book-spine（資料・文献）
Using AI with Web Awesome: sparkles（AI・革新性）
Frameworks: grid-2 → puzzle（パズル・統合）
Components: grid-2 → trowel-bricks（構築・組み立て）
Style Utilities: grid-2 → brush（スタイリング）
Patterns: grid-2 → block-brick（パターン・構造）
Theming: palette（テーマ・色）
Terms & Policies: scale-unbalanced-flip（規約・法的文書）

既存の汎用的な grid-2 アイコンは、より具体的な意味を持つアイコンに置き換えられました。

CSSの調整

packages/webawesome/docs/assets/styles/docs.css では、アイコンを含む見出しの視覚的配置を調整するルールが追加されました。

/* visually align icon with child list's border-start */
h2:has(wa-icon) {
  position: relative;
  inset-inline-start: calc(var(--wa-space-xs) * -1);
}

このルールは :has() 疑似クラスを使用して、アイコンを含む見出しのみを対象としています。負の inset-inline-start により、見出しを左側にシフトし、子リストの border-start と視覚的に揃えています。

同時に、サイドバーのリンクスタイルに関する冗長なCSSルールが簡略化されました：

変更前:

#sidebar {
  h2 {
    color: var(--wa-color-text-quiet);

    a {
      color: var(--wa-color-text-normal);
      text-decoration: none;

      wa-icon {
        font-size: var(--wa-font-size-s);
        font-weight: var(--wa-font-weight-action);
      }

      &:hover {
        text-decoration: underline;
      }
    }
  }
}

変更後:

#sidebar {
  h2 a {
    --wa-color-text-link: var(--wa-color-text-normal);
  }
}

カスタムプロパティを使用することで、スタイル定義が大幅に簡潔になりました。

設計判断

実験的な要素には de-emphasize クラスが適用されています。"Agent Skills"リンクのFlaskアイコンが該当します：

<wa-icon name="flask" aria-hidden="true" class="icon-shrink de-emphasize"></wa-icon>

このクラスにより、実験的機能であることを視覚的に控えめに示しながら、ユーザーの注意を引きすぎないようにしています。

また、すべてのアイコンに aria-hidden="true" 属性が設定されています。これは、アイコンが純粋に装飾的な役割であり、スクリーンリーダーユーザーに追加情報を提供しないことを示します。セクション名のテキストのみで十分な情報が伝わるため、アクセシビリティの観点から適切な判断です。

アイコンの配置には wa-cluster と wa-gap-xs クラスが使用されており、WebAwesome独自のレイアウトシステムに一貫性を保っています。

まとめ

本PRは、セマンティックなアイコンの追加と最小限のCSS調整により、ドキュメントサイドバーの視認性を向上させました。:has() 疑似クラスを活用した位置調整とカスタムプロパティによるスタイル簡略化は、モダンなCSS機能を効果的に活用した実装例といえます。アクセシビリティへの配慮も維持されており、視覚的改善と技術的品質の両立が実現されています。