AI にドキュメントサイトのトップを作らせてみた — 骨格は通る、でも"中身"が無い（やってみた #23）

⁠やってみたシリーズ⁠: 自作のデザインシステム @gunjo/ui（群青）を、群青のことを一度も見たことのない AI に、実際の画面で組ませていく連載。今回は ⁠ドキュメントサイトのトップ（docs home）⁠。

条件はいつも通り（出荷している npm パッケージ＋docs サイトだけ。ソース非公開）。お題は、上部ナビ＋検索（⌘K）、左サイドバー（グループ分けされたナビ・モバイルではドロワー）、パンくず、本文（h1＋クイックスタートの CodeBlock＋囲み＋特徴リスト）、右の「On this page」目次、前へ/次へ、フッター。

@gunjo/ui は、そもそも ⁠gunjo.jp 自体が docs サイト⁠です。だから「予備知識ゼロの AI が docs のトップを組めるか」は、自分たちの製品で自分たちを試す最高のテスト——組めなければ一番痛い。

結果 — 3.5/5（骨格は強い、でも中身の層が空）

⁠外枠は全部あります⁠: Breadcrumb（正しい aria-current）・CodeBlock（本物）・DocumentPager（前へ/次へ専用）・CommandPalette（⌘K）・Sheet（モバイルのドロワー）・Header/Footer・ダークモード。検証も全部緑（tsc 0・build 0・console 0・h1 1個・見出しレベルの飛ばし0・サイドバーは本物の <nav aria-current>・375px でのはみ出し0）。

低いのは——⁠docs ページの本体（長文の文章＋目次）を表すコンポーネントが一つも無い⁠から。そして⁠またコンポーネント内部の実バグを掘り当てました⁠。

また「出尽くし」が破れた — 今回の実バグ

⁠① CardTitle が <h3> を固定で埋め込み（アクセシビリティ）。⁠ ページの <h1> の隣に Card を置くと <h3> が入って ⁠見出しが 1→3 に飛ぶ⁠（WCAG 違反）。→ as prop を追加（既存を壊さず・既定は h3）して、使う側がレベルを選べるように #116。

⁠② PageAside が、h1 より前に余計な <h3> を出す（アクセシビリティ）。⁠ モバイルの「On this page」の開閉を Accordion で組んでいて、Radix のヘッダーが <h3> を生成 → ページの h1 より前に見出しが入ってしまう。→ 標準の <details>/<summary>（summary は見出しではない）に置き換え #117。

⁠③ DocsTemplate がモバイルで壊れる。⁠ 既定で grid-cols-[200px_…] ＝ 375px でもサイドバーが 200px 固定で潰れる。→ モバイルは1カラム（サイドバーはドロワーに任せる）、lg/xl で多カラムに #118。#66/#111 と同じ、テンプレの役割まわりの種類です。

⁠①〜③ を全部ソース＋ドリフト検査で今回反映。⁠ ＋並行で ⁠Img の 256×256 固定⁠（#113・固定寸法の一族）も .pen を「親幅いっぱい」に変えて反映（ドリフト検査のガードが width===256 で黙って効かなくなっていたのも修復）。

学び — 「骨格」と「中身」は別物

新しいアクセシビリティ・バグ2件は、結局⁠同じ根⁠を指しています: ⁠typography/Heading のコンポーネントが無い⁠（#110）。CardTitle も PageAside も「見出しを手で組む」から階層が崩れる。＋⁠目次（TableOfContents）のコンポーネントも無い⁠（#120）——目次・スクロールに追従する見出しハイライト・見出しの id を全部手組み。

外枠（Header/Sidebar/Breadcrumb/Pager/CodeBlock）→ 揃っている・強い
中身（Heading/Prose/TableOfContents）           → 無い。docs の本体はこっち

⁠ブログ(#21)・ランディング(#22)・docs(#23) と、3画面連続で「typography の不在」が最大の欠落でした。⁠ コンポーネントの外枠は自前で使っても通るのに、⁠「長文＋見出し階層＋目次」という中身の層⁠を、デザインシステムが持っていない。次に閉じるべき軸は、ここで確定的です。

（#116/#117 は、typography が根の症状を "その場ですぐ直せる形" で潰しました。根本の Heading/Prose/目次は設計に関わる話＝beta ゲートで対応。）

次回予告（やってみた #24）

• ⁠価格比較 / エラー画面 / 管理ダッシュボード⁠ ほか。中身の層と組み立てを引き続き突きます。

試す

• ⁠gunjo.jp⁠ ／ npm @gunjo/ui ／ ⁠GitHub⁠
• 前回まで: #1〜#22
• まとめ記事: 群青（@gunjo/ui） ／ なぜ要るのか: AI 時代のデザインシステム論
• ⁠GunjoUI by UIXHERO⁠

まだ alpha。骨格は通る、次は"中身"（typography 層）。3画面連続で同じ根を指しています。