Astro UI パターン & ポータブルコンポーネントライブラリ は何をしますか？
本ガイドは、Astroサイト向けのポータブルでドロップイン可能なUIコンポーネントの標準カタログを定義します。
スタンドアロンの例はポータブルコンポーネントモデルに従います。これは、npm外部依存関係ゼロ、クライアントフレームワークランタイム（React/Vueなし）不要、名前空間付きCSSトークンと組み込みフォールバック、プログレッシブエンハンスメントを特徴とします。フレームワークプロジェクトでは、意味論とインタラクション要件は保持しつつ、選択された契約に従って構成とスタイリングを適応させてください。レンダリングされたプロジェクトでアクセシビリティを検証してください。テンプレート単体ではWCAG準拠を確立しません。
動作契約とフレームワーク構成
以下のインデックスに含まれるコンポーネントについては、その意味論とインタラクション契約（キーボードサポート、フォーカス管理、ネイティブ要素、アクセシブルな名前、状態更新、プログレッシブエンハンスメント）を使用してください。選択されたプロジェクト/フレームワーク契約が、スタイリング、トークン、インポート、コンポーネント構成を決定します。ユーザー指示が優先されます。
例では、以下のスタンドアロンポータブルコンポーネントモデルを使用しています。フレームワーク構成契約のない独立したコンポーネントを追加する場合はこれを使用してください。プロジェクトに確立されたライブラリがある場合は、例のラッパーやクラスを複製する代わりに、そのライブラリの適切なプリミティブを使用して動作を適応させてください。必須の意味論と動作を維持しながら、例のラッパーとクラスを適応させてください。
コンポーネントフレームワーク（Lumosなど）で構築されたプロジェクトの場合は、そのフレームワークの構成とスタイリングを使用してください。そのプリミティブはインポートされても構いません。スタンドアロンのゼロサイトインポートルールと名前空間付きフォールバックトークンは、選択されたフレームワークの契約を上書きしません。
ポータブルコンポーネントモデル
スタンドアロンポータブルコンポーネントには、以下の5つのルールを使用します。選択されたフレームワーク上では、動作要件を維持し、上記の説明に従ってその構成/スタイリング契約に従ってください。
- ゼロ外部/サイトインポート: コンポーネントファイルは、サイトのレイアウト、ボタン、またはサードパーティのクライアントUIライブラリをインポートしてはいけません。唯一の例外は SelfHostedMap で、マップレンダラーとタイルリーダーが必要です。その仕様にはパッケージがリストされており、所有者の承認がある場合にのみインストールされます。
- 名前空間付きCSS変数とフォールバック: コンポーネントのスタイルシート内でホストトークン（
var(--color-brand)など）を直接参照してはいけません。常にvar(--comp-property, <fallback>)と記述してください。 - スコープ付きBEMとCSS論理プロパティ: BEMクラス命名（
.c-theme-toggle、.c-accordion__summary）と論理プロパティ（inline-size、block-size、padding-inline、margin-block）を使用してください。 - 冪等なバニラプログレッシブエンハンスメント: スクリプトはロード時に実行され、Astro View Transitionsがアクティブな場合でもクリーンに再アタッチされる必要があります（
document.addEventListener('astro:after-swap', init)）。 - タッチターゲットとARIA: ボタンとインタラクティブコントロールは、最小
44px（2.75rem）または48px（3rem）のタッチターゲット、適切なARIA状態（aria-expanded、aria-selected、aria-pressed、aria-controls）、およびキーボードフォーカスリングを持たなければなりません。
コンポーネントインデックス
| コンポーネント | 仕様ファイル | 目的 | 主要契約 |
|---|---|---|---|
| 1. ThemeToggle | components/theme-toggle.md | FOUCゼロ、SVGモーフィングによるライト/ダークテーマ切り替え | <head> インラインスクリプト + OKLCHトークンマッピング |
| 2. MobileNavDrawer | components/mobile-nav-drawer.md | アクセシブルなスライドダウンナビゲーションドロワー、アニメーションハンバーガーメニュー | 48pxタッチターゲット、Escapeキーで閉じる、GPUぼかしラグなし |
| 3. SearchBar | components/search-bar.md | クリアボタンとライブアナウンサー付きクライアントサイド検索入力 | rAF デバウンス（最適なINP）、aria-live、カスタムイベントコーディネーター |
| 4. FilterChips | components/filter-chips.md | アクセシブルな押下状態を持つマルチカテゴリピルフィルターバー | role="group"、aria-pressed、カスタムイベントコーディネーター |
| 5. SearchFilterBar | components/search-filter-bar.md | SearchBar と FilterChips を組み合わせた複合パターン | 事前構成済みスタックツールバー、マルチカラムフレックスレイアウト、共有スコープ |
| 6. AccessibleModal | components/accessible-modal.md | ネイティブHTML5 <dialog> を使用したアクセシブルなダイアログオーバーレイ | ネイティブトップレイヤー、背景クリック、Escapeキー、フォーカス復元 |
| 7. AccessibleAccordion | components/accessible-accordion.md | スムーズなCSSグリッド展開を使用したネイティブFAQ/アコーディオン | ネイティブ <details name="...">、JavaScript 0 KB |
| 8. AccessibleTabs | components/accessible-tabs.md | 価格帯やマルチパネルビューのためのWAI-ARIAタブスイッチャー | キーボード矢印ナビゲーション（Left/Right/Home/End） |
| 9. SocialShare | components/social-share.md | Web Share APIを使用したプライバシーファーストのソーシャル共有バー | 100% GDPRセーフ、0トラッカー、静的インテントURL |
| 10. TableOfContents | components/table-of-contents.md | スクロールスパイ付き長文記事目次 | IntersectionObserver 見出し追跡、記事レイアウトと組み合わせ |
| 11. AccessibleCarousel | components/accessible-carousel.md | レビュー、カード、ロゴ用のネイティブCSSスクロールスナップスライダー | ネイティブタッチスワイプ（JavaScript 0 KB）、アクセシブルな前/次のボタン |
| 12. InfiniteTicker | components/infinite-ticker.md | ホバー/フォーカスで一時停止するピュアCSS無限ロゴ/テキストマーキー | WCAG 2.2.2準拠、aria-hidden で隠された重複トラック |
| 13. StatsCounter | components/stats-counter.md | イーズアウトスクロールアニメーション付きHTMLファーストメトリックカウンターバー | 0 CLS、静的HTMLフォールバック、IntersectionObserver |
| 14. AddToCalendar | components/add-to-calendar.md | ビルド時のiCalendarファイルへの「日付を保存」リンク | 同一オリジン静的 .ics + <a download>、有効なRFC 5545、JavaScript 0 KB |
| 15. SelfHostedMap | components/self-hosted-map.md | セルフホストPMTiles抽出物からのリストの場所のマップ。番号付きピンはリストと一致。 | 遅延MapLibre、HTTP 206タイルルート、テキスト代替を伴う aria-hidden マップ、テーマに従う。npmパッケージが必要（所有者の承認） |
| 16. ClickableParent | components/clickable-parent.md | 1つの実際のリンクまたはボタンを介してカード/行全体をクリック可能にする | ::after 拡張ヒットエリア、セカンダリコントロールの引き上げ、コンテナ上のフォーカスリング、JavaScript 0 KB |
| 17. Card | components/card.md | メディア、メタ、本文、セカンダリアクションを備えたコンテンツカード | 見出しファーストDOM、headingLevel プロパティ、コンテナクエリレイアウト、リンク時の ClickableParent 契約 |
カタログ外コンポーネントの決定ゲート（人間による決定ポイント）
プロジェクトの要件またはデザインにより、上記の17のカタログコンポーネントに含まれないインタラクティブUIコンポーネント（例：Before/After画像比較スライダー、日付ピッカー、範囲セレクター、ステップウィザード、カスタムメディアプレーヤー）が必要な場合：
[!IMPORTANT] 一度停止して質問してください: エージェントは、クライアントサイドフレームワークライブラリ（React、Vue、Svelte）を黙ってインストールしたり、未検証のサードパーティnpmパッケージをインポートしたり、一時的なテキストプレースホルダーブロック（例:
<div class="c-placeholder">）を残したりしてはなりません。エージェントは一時停止し、プロジェクトオーナーに3つの明確な選択肢を提示しなければなりません:
- オプションA: カスタムバニラコンポーネント（推奨）: 以下の特注コンポーネントフォールバック契約に準拠した、依存関係ゼロの
.astroコンポーネントを作成します。- オプションB: 静的HTMLベースライン: インタラクティブな拡張を完全に省略し、JavaScript 0 KBで純粋に静的な意味論的レイアウト（例：並べた画像や標準的な積み重ねカード）を実装します。
- オプションC: カタログパターンの適応: 既存のカタログパターンが要件を満たせるか評価します（例：
AccessibleModalを画像ライトボックスに適応、AccessibleTabsをステップパネルビューに適応）。
特注コンポーネントフォールバック契約
プロジェクトオーナーがカタログ外コンポーネントの構築（オプションA）を承認した場合、実装は以下の6つのルールを満たさなければなりません。フレームワーク適応の場合、項目3～4にはそのフレームワークの構成、クラス命名、トークンルールを使用してください。
- セマンティックHTMLファースト: JavaScriptを記述する前に、インターフェースを標準HTML要素にアンカーします（例：スライダーには
<input type="range">、開示には<details>、オーバーレイには<dialog>）。 - ゼロ外部ランタイム依存関係: クライアントフレームワークランタイム（React/Vueなし）およびサードパーティUIウィジェットパッケージはゼロ。ブラウザのインタラクションが本当に必要な場合にのみ、プレーンなバニラTypeScript/JavaScriptを作成します。
- スコープ付きBEMとCSS論理プロパティ: 標準的なBEM命名（
.c-block、.c-block__element）とフロー相対レイアウトプロパティ（inline-size、block-size、padding-block、margin-inline、inset）を使用します。 - 名前空間付きトークンとフォールバック: 16進数値をハードコードしないでください。適切なフォールバックを持つホストセマンティックトークンまたは名前空間付きカスタムプロパティを使用します（
var(--comp-color, var(--color-primary))）。 - JavaScriptなしのプログレッシブエンハンスメント: クライアントJavaScriptが無効になっている場合でも、コンポーネントは読みやすく、アクセス可能で、操作可能でなければなりません。
@media (scripting: none)またはネイティブCSSフォールバックレイアウト（例：並べた表示や積み重ね表示）を使用して、コンテンツが隠されないようにします。 - WCAG 2.2 AA準拠: 最小
44px（2.75rem）のタッチターゲット、高コントラストで可視の:focus-visibleリング、明確なアクセシブルな名前（aria-label、<label>）を維持し、axe-core違反が0であることを確認します。
エージェント向け選択的読み込みガイダンス
ユーザーが上記のコンポーネントのいずれかの実装または編集を依頼した場合、カタログ全体を読まないでください。代わりに、必要な特定のコンポーネントファイルのみを読んでください（例：components/accessible-carousel.md）。
統合検証
ビルド/デプロイされた出力で選択された仕様を検証してください：意味論と名前、キーボード/フォーカスの動作、状態遷移、JavaScriptなしの扱い、繰り返しの初期化、ホストトークンマッピング。スタンドアロンパッケージングルールはスタンドアロンコンポーネントにのみ適用されます。フレームワークはそのプリミティブを再利用します。プロジェクトで設定されたチェック/ビルド/テストを実行し、利用できないチェックやカバレッジのギャップを開示してください。44pxはこのライブラリのターゲットサイズの慣例であり、WCAG AAのしきい値そのものではありません。
ネイティブのセレクトポップアップは、所有者がカスタムコンボボックスのトレードオフを承認しない限り、ブラウザ/OSのUIのままです。