AI エージェントと使う
AI のコーディングエージェントは、ブラウザーを使わずに svelte-zukan を導入し、カタログファイルを書いて確かめられます。いちばん手早いのは、エージェントスキルを使う方法です。ほかにも svelte-zukan は、テキストで読めるドキュメントと、データとしてのカタログ(ブラウザーでは WebMCP のツールとしても)を用意しています。
スキル
svelte-zukan には 2 つのエージェントスキルが付いています。svelte-zukan の導入と、カタログファイルを書いて説明を付けて確かめるための svelte-zukan と、Storybook や Histoire からカタログを移すための migrate-svelte-zukan です。それぞれの内容とインストール方法はエージェントスキルにまとめています。
テキストで読めるドキュメント
llms.txtにページの一覧が、llms-full.txtに全ページの本文がまとまっています- どのページも Markdown で読めます。
https://oekazuma.github.io/svelte-zukan/quickstart.mdのように、URL の末尾に.mdを付けます
データとしてのカタログ
dev サーバーは /__zukan/catalog.json を返します。build: true で vite build すると、同じデータを index.html の隣の catalog.json に書き出します。中のパスは Vite の root からの相対パスです。カタログを一覧にできないとき(ID の重複)は、dev サーバーはステータス 500 で { "error": "<メッセージ>" } を返します。
| フィールド | 中身 |
|---|---|
title |
title オプション |
components[].id |
カタログ ID |
components[].group |
グループ。groups のキーか、パッケージの name |
components[].name |
カタログファイルの名前から .zukan.svelte を除いたもの |
components[].dir |
ID のうちグループと name の間の部分。なければ '' |
components[].file |
カタログファイル |
components[].component |
Button.zukan.svelte の隣にある Button.svelte。なければ null |
components[].doc |
.md ファイルの Markdown。なければ null |
components[].props |
Props の一覧。名前、型、デフォルト値、必須か、バインド可能か、説明(HTML) |
components[].propsType |
パッケージの Props の型や、一覧で読めない型。ソースに書かれたとおりの文字列をカンマで区切ったもので、なければ null |
components[].sections[] |
セクションごとの title、コード表示と同じ code、プレビューのページのハッシュ preview |
components[].error |
カタログファイルが素の Svelte として読めない、または <Section> の決まりに反しているときに、そのビルドエラーのメッセージが入ります。このとき sections は空です |
uncataloged[] |
探索するディレクトリにある .svelte ファイルのうち、隣にカタログファイルがないもの。トップページと同じファイルは含めません |
tailwind |
Tailwind CSS のエントリーが 1 つも見つからなかったとき(Tailwind が入っていない、または v3 のときも)は null。読み込めたときはエントリーごとのオブジェクトで、中身は下の表のとおりです |
tailwind のオブジェクトには次のフィールドがあります。
| フィールド | 中身 |
|---|---|
file |
エントリー。Vite の root からの相対パス |
version |
Tailwind CSS のバージョン |
prefix |
テーマの prefix。なければ null |
categories[] |
カテゴリーごとのユーティリティクラス。id、title、tokens[](class(prefix つき。ブレークポイントとスペーシングの基準値では null)、cssVariable、value) |
variables |
すべてのテーマ変数とその値。{ "--color-brand-500": "#ff3e00" } の形 |
error |
エントリーを読み込めなかったときに、そのメッセージが入ります。このとき categories と variables は空です |
categories のクラスはテーマが定義しているものなので、エージェントがコンポーネントにスタイルを付けるときは、ここにあるものだけを使います。ダークモードの値、任意の値、バリアントは含みません。
preview はカタログのページのハッシュです。/__zukan/#/preview/ui/Button?section=Primary はそのセクションだけを表示するので、スクリーンショットに向いています。&theme=dark を付けるとダークテーマになります(theme オプションでテーマを固定しているときは無視されます)。これはページの color-scheme を設定するもので、light-dark() はこれに従います。prefers-color-scheme を使うスタイルシートはブラウザーに従うので、ダークのスクリーンショットにはカラースキームのエミュレートも必要です(Playwright では colorScheme: 'dark')。このページはウィンドウいっぱいに広がるので、スマートフォンやタブレットの幅で見るときはウィンドウの幅を変えます。
カタログの WebMCP ツール
WebMCP に対応したブラウザーでは、カタログのページが自分のデータをツールとしても公開します。ブラウザーを操作するエージェントは、画面を読まずにカタログを使えます。
| ツール | 働き |
|---|---|
list_components |
コンポーネントの一覧(ID、名前、グループ、セクション名、説明の最初の行)と、カタログファイルのない .svelte ファイルを返します |
get_component |
1 つのコンポーネントを、catalog.json と同じ形で返します |
open_component |
コンポーネントのページを開きます。セクション、そのプレビューの幅とテーマも指定できます |
check_accessibility |
1 つのセクションを単独で描画し、axe-core が見つけた問題(violations)と、axe-core だけでは判定できなかった項目(review)を返します |
list_tailwind_tokens |
Tailwind CSS のデータがあるときだけ使えます。category を省くと、エントリーごとにカテゴリーとトークンの数を返します。カテゴリーの ID(background-color、padding、font-size など)を渡すとそのトークンを、full-config を渡すとすべてのテーマ変数を { 変数: 値 } の形で、tokens ではなく variables に入れて返します。query は、クラス名・変数名・値のどれかにその文字を含むものだけに絞ります |
WebMCP に対応していないブラウザーではツールは使われず、そのためのコードも読み込みません。