webawesome-design エージェントスキルの追加と <wa-page> ナビゲーショントグル修正

Web Awesome に webawesome‑design エージェントスキルが新規追加され、レイアウト・テーマ・ビジュアル構成のガイドが機械可読ドキュメントとして提供されました。同時に <wa-page> コンポーネントのナビゲーショントグル検出ロジックが修正され、カスタムトグルが期待通りに動作するようになりました。

背景

webawesome エージェントスキルはコンポーネント API のみを対象としており、デザイン指示には応答できませんでした。AI ツールがページ全体のレイアウトやテーマ設定まで支援できるように、webawesome‑design スキルが作成されました。

また、<wa-page> のナビゲーショントグルはスロット名のミスによりカスタムボタンが検出できず、モバイルメニューが開かないバグが報告されていました。この問題は実装上の単一文字列置換で解決可能でした。

結果として、AI ドキュメントの充実と開発者体験の向上という二つの課題が同時に解決されました。

技術的な変更

webawesome‑design エージェントスキルの導入

新規スクリプト packages/webawesome/scripts/design-skill.js が追加され、ビルド時に design-skill/ ディレクトリ全体を dist/skills/webawesome-design/ と dist-cdn/skills/webawesome-design/ にコピーします。コピー後に SKILL.md の front‑matter にパッケージバージョンが自動注入され、スキルとリリースのバージョンが常に一致します。

export async function generateDesignSkill(options = {}) {
  const {
    sourceDir = SOURCE_DIR,
    outDirs = [
      path.join(getDistDir(), 'skills/webawesome-design'),
      path.join(getCdnDir(), 'skills/webawesome-design')
    ],
    // ...
  } = options;
  // コピーとバージョン注入が実装されています
}

Markdown ソースは scripts/design-skill/ 配下に配置され、SKILL.md と多数の references/ ファイル（例: layouts-page.md, theming.md）が手書きで管理されます。これにより AI が「ページレイアウト」や「テーマ設定」などの問い合わせに対し、構造化された情報を取得できます。

`<wa-page>` ナビゲーショントグルバグの修正

packages/webawesome/src/components/page/page.ts では、カスタムトグル検出用のセレクタが誤って toggle‑navigation を参照していました。正しいスロット名 navigation‑toggle に置き換えるだけで、data-toggle-nav を持つ要素が正しく認識されます。

@@
-    const hasCustomToggle = Boolean(this.querySelector(":not([slot='toggle-navigation']) [data-toggle-nav]"));
+    const hasCustomToggle = Boolean(this.querySelector(":not([slot='navigation-toggle']) [data-toggle-nav]"));

この変更は API の追加や既存 CSS の改変を伴わず、既存のカスタムトグル実装はそのまま動作します。

ドキュメントスタイルの改善

packages/webawesome/docs/assets/styles/docs.css では、テーブル内の <code> 要素と依存リストの背景色を透明化し、white-space: nowrap に変更しました。また、パンくずリスト直後の見出し上部余白を 0 にリセットし、ページタイトルとコンテキストの間隔を統一しています。

@@
-  table code,
-  .dependency-list code {
-    background-color: var(--wa-color-neutral-10);
-    white-space: normal;
-  }
+  table code,
+  .dependency-list code {
+    background-color: transparent;
+    white-space: nowrap;
+  }
@@
-  .page-breadcrumbs + h1 {
-    margin-block-start: var(--wa-space-l);
-  }
+  .page-breadcrumbs + h1 {
+    margin-block-start: 0;
+  }

検証スクリプトの追加

packages/webawesome/scripts/verify-skills.js が新規追加され、エージェントスキルの手書きコンテンツがコンポーネントカタログと整合しているか、相対リンクが実在ファイルに解決できるかを CI でチェックします。これにより choosing-components.md のようなドリフトがリリース前に検出されます。

// ...省略された実装例
// 1. <wa-*> タグの存在検証
// 2. (Pro) フラグの正当性検証
// 3. 相対リンク解決検証

設計判断

スキルの分離戦略：webawesome と webawesome‑design を別スキルとして提供することで、AI が「コンポーネント API」か「デザインガイド」かを判別しやすくなります。新たな設定キーを導入せず、単なる Markdown コピーとバージョン注入だけの実装にすることで保守コストを最小限に抑えました。

最小侵入のバグ修正：スロット名置換は唯一のコード変更であり、公開 API や CSS に影響しません。既存利用者はマイグレーション不要で、カスタムトグルが即座に機能します。

バージョン同期と検証：generateDesignSkill がビルド時にバージョンを書き込み、verify-skills.js がコンテンツと実装の整合性を CI で保証します。これによりリリースとスキルの内容が常に一致し、リグレッションが防止されます。

まとめ

本 PR は webawesome‑design エージェントスキルを新規追加し、AI がデザイン指示まで支援できるようにした点と、<wa-page> のナビゲーショントグル検出バグを最小侵入で修正した点が主な成果です。スキル分離と自動検証により保守性と拡張性が確保され、同時にドキュメントの可読性も向上しました。

背景