LLM Wikiは、LLMが特定分野の資料を探して利用する方法をまとめたWikiです。質問に応じて何を先に読むべきかを案内し、資料同士の内容が異なる場合にどの出典を優先するかを知らせます。
まだ確認できていない内容も別途残します。作業中に新たに確認した内容は再びWikiに反映するため、次の作業はすでに整理された基準と残された質問から始められます。
LLM Wikiの必要性
文書が一か所に大量に集まっているからといって、すぐに知識になるわけではありません。必要な資料がどこにあるのか、どの内容が最新なのか、異なる記録が衝突したときに何に従うべきなのかが分からなければ、LLMは大量の文書を読んでも見当違いの答えを出す可能性があります。
図書館が本を積み上げただけの倉庫と異なる理由は、分類と目録があるからです。VUI LLM Wikiも同じ方法で資料を整理します。作業の種類に応じて読む文書を絞り込み、各資料の場所と優先順位を知らせます。
答えを見つけられなかった場合も記録します。暫定的に処理した内容と、まだ確認が必要な質問を残しておけば、LLMは空白を推測で埋めず、次の作業ではその地点から再検討できます。
VUI LLM Wikiの制作背景
私には、長期的にVUI Design Systemを作る仕事が与えられました。問題は、私がビジュアルデザインを体系的に 訓練されて いなかったことでした。画面を見てすぐに「VUIらしい」あるいは「VUIらしくない」と判断するのは困難でした。
個人的な感覚だけでは、長く維持できるDesign Systemを作るのは難しいと考えました。そこで、VUIデザインを判断するときに何を確認すべきか、同じ問題に再び出会ったときにその判断をどのように 再現するかを 整理することから始める必要がありました。
VUI LLM Wikiの構成原理
VUIを判断するための資料は、Figmaデザイン、VUIソースコードとテーマ、生成トークンとコンポーネント仕様、StorybookとQA記録 など 複数の場所にありました。 Wikiはこれらの資料をコピーせず、質問に合った資料へ進む道筋と優先順位を整理します。
1. 基準資料
Figmaはデザイナーが意図した外観を示します。packages/vui-uiとpackages/vui-themeには現在動作しているコードがあり、生成トークンとコンポーネント仕様には使用できる名前と機能が整理されています。StorybookとFigma Syncレポート、QA記録は、実装結果を比較するときに使用します。
2. 判断基準
資料同士が異なる場合は、authority.mdに整理された順序に従います。新しいデザインを移行するときはFigmaを目標とし、現在の動作を説明するときはソースコードとテーマを確認します。コンポーネント、トークン、画面パターンはそれぞれの一覧に分け、まだ確定していない内容はgap-index.mdに別途記録します。
3. 読む順序
wiki.mdは作業に合った開始地点を知らせます。そ の次に、関連するコンポーネントカードやトークン文書、画面パターンだけを読みます。DESIGN.mdは、頻繁に繰り返す作業に必要な文書をさらに絞り込んだ読書リストであり、判断が必要なときはリンクをたどって元の資料に戻ります。
ディレクトリ構造
docs/designでは、この原則を4つの文書 グループに分けます。wiki.mdが作業に合った文書へ案内するため、ファイル名をすべて覚える必要はありません。
入口とルール docs/design/wiki.md, authority.md, validation.md
wiki.mdは作業別の開始地点を案内します。authority.mdは資料が異なる場合に何に従うかを定め、validation.mdはWikiを更新した後に確認する項目をまとめています。
一覧 docs/design/profiles/company/*-index.md
コンポーネント、トークン、画面パターン、未確定項目をそれぞれ分けた一覧です。現在の質問に関連する文書だけを選べるようにします。
詳細文書 components/*.card.md, patterns/*.md, tokens/*.md
コンポーネントごとの使用方法、画面を構成する方法、トークンの使用原則を、必要な単位で説明します。
作業別の読書リスト DESIGN.md, exports/*.DESIGN.md
CRUD一覧画面やFormのように、繰り返し行う作業に必要な文書だけを集めています。LLMはWiki全体を読まず、ここから始め、判断が必要な場合は元の資料を確認します。
Figma Syncの活用と更新
デザイナーが承認したFigmaデザインをVUIコンポーネントとStorybookに移行する作業をFigma Syncと呼びます。画面だけを似せて作る作業ではありません。コンポーネントの状態を既存APIに接続し、VUIトークンとStorybook専用の装飾を区別する必要があります。
私はFigma Syncを始める際、Wikiで該当するコンポーネントカードとトークン文書を先に確認しました。作業中に新たに確認した内容は関連文書に反映し、まだ答えがない部分は未確定項目（gap）として残しました。作業が終わるたびに、Wikiも併せて更新しました。
Tooltipの検証事例
Tooltipの初期画面は、一見すると完成しているように見えました。しかし、矢印の方向と位置がFigmaと異なっており、Storybookの説明用点線フレームも結果画面に含まれていました。
画面だけを見て修正していたら、矢印のサイズと位置を任意の数値に合わせていたかもしれません。Wikiに従い、Figmaの方向定義、既存のVuiTooltip API、Storybook装飾の範囲、使用できるトークンを順番に確認しました。
図1。修正前のTooltip。Storybookの装飾と方向別の矢印の問題が一つの画面に混在している状態。
図2。修正後のTooltip。既存のVuiTooltipのdirectionを使用し、Storybook専用の装飾を分離した状態。
確認の結果、方向は既存の VuiTooltip の direction で対応できました。Storybook 専用の装飾は実装から分離しました。一方、矢印の形状には確認済みのトークンがなかったため、任意にルールを作らず、未確定項目として残しました。
MenuItem の状態区分の事例
MenuItem では disabled と disabled + selected を同じ状態として扱っていたことが問題でした。初期実装では disabled 状態全体に selected の背景色を適用しており、選択されていない項目にもグレーの背景が残っていました。
私は Wiki で VuiMenuItem カードと Figma の状態別画面、VUI の text と action token を併せて確認しました。Figma では disabled 項目の背景が透明で、disabled + selected にのみ selected の背景が残っていました。そこで、disabled のテキストには text.disabled を適用しつつ背景は透明にし、selected 状態が同時に存在する場合にのみ action.selected を適用しました。
図 3. 修正前の MenuItem。選択されていない disabled 項目にも selected の背景が適用されている状態。
図 4. 修正後の MenuItem。disabled は透明にし、disabled + selected にのみ selected の背景を適用した状態。
Kanban デザインの作成事例
前回の Sprint では、短時間で実際に使用できる Kanban テンプレートが必要でした。VUI LLM Wiki が既存コンポーネントの修正に役立つだけでなく、新しい画面を設計する際にも使えるのかを確認するよい機会でした。
まず Wiki で CRUD/List 画面と Dialog のフローを確認しました。ボードと lane、カード、登録・編集・削除の操作は既存の VUI コンポーネントで構成し、状態の色とカードの表面には semantic token を使用しました。初めて作る Kanban でしたが、ほかの VUI 画面と調和する形をすばやく作ることができました。
図 5. VUI LLM Wiki のパターン、コンポーネント、トークンのパスに沿って生成した Kanban backlog 画面。
VUI LLM Wiki が完成すれば、担当する LLM が変わっても同じ設計基準を見つけられるようになるでしょう。新しいコンポーネントや画面も毎回ゼロから推測するのではなく、すでに整理された判断を出発点として、VUI らしい方向へ拡張できるようになります。
Joseph