svelte-frontend

Windmill の Svelte パターン

frontend/ で Svelte コードを書く際は、Windmill 固有のパターンを適用してください。一般的な Svelte 5 の構文（ルーン、スニペット、イベント処理）については、Svelte MCP サーバーを利用してください。

UI を書き始める前に（必須）

最初のマークアップを書く前に、次の両方を行ってください。後回しにしたり、見慣れないものがあった場合だけ行ったりしてはいけません。

1. 既存のコンポーネントを探します。 frontend/src/lib/components/common/index.ts はデザインシステムのバレルです。28 行すべてを読んでください。以下に記載する 3 つよりも多くのコンポーネントをエクスポートしています。Alert、Badge、Breadcrumb、Drawer／DrawerContent、Menu／MenuItem、 Tabs／Tab／TabContent、Skeleton、FileInput、RadioCard、Section、Kbd、ActionRow、 ClearableInput、CopyButton、SecondsInput、UndoRedo、Url です。

このバレルだけですべてではありません。common/ には 34 個のサブディレクトリがありますが、エクスポートされているのは 23 個だけです。そのため、modal/、popup/、stepper/、tooltip/、checkbox/、table/、contextmenu/、 confirmationModal/、calendarPicker/、fileUpload/、toggleButton-v2/ などは存在しますが、 パスを指定してインポートする必要があります。セレクト、テキスト入力、melt ベースのプリミティブは、common/ の隣にある components/select/、components/text_input/、components/meltComponents/ にあります。

ツリーには 1,600 個を超えるコンポーネントがあります。これから作ろうとしているものを frontend/src/lib/components で grep してください。ほぼ間違いなく既存のものが見つかります。新しいコンポーネントの作成は最終手段であり、最初に行うことではありません。

2. 作成するものに関するガイドラインを読みます。 frontend/brand-guidelines.md は、見た目や表現の基準となる資料です。34,000 文字すべてを読み込む必要はありません。該当するセクションに移動してください。

作成するもの	読むセクション
新しい画面またはコンポーネント	# Components（Core Rules、Quick Reference）
ボタン、CTA	## Buttons — 階層が重要です。1 つのビューにつき Accent は 1 つだけにします
色、サーフェス、境界線	# Color system（Quick Reference、Do's and Don'ts）
テキスト、ラベル、見出し	# Typography — ## Text Casing を確認し、全体を文頭大文字の形式に統一します
余白、グリッド、ページ構成	# Spacing & Layout。フォームについては # Layout → ## Form
影、オーバーレイ、奥行き	# Elevation
アイコン	# Iconography
UI の文言全般	# Voice & Communication、# Tone of Voice

grep -n '^#' frontend/brand-guidelines.md で行の範囲を確認し、その範囲だけを読んでください。

Windmill UI コンポーネント（必須）

Windmill のデザインシステムコンポーネントを必ず使用してください。生の HTML 要素は使用しないでください。以下の 3 つは特によく使うコンポーネントの例であり、カタログのすべてではありません。それ以外のものが必要な場合は、バレルに戻って grep してください。

ボタン — <Button>

<script>
  import { Button } from '$lib/components/common'
  import { ChevronLeft } from 'lucide-svelte'
</script>

<Button variant="default" onclick={handleClick}>Label</Button>
<Button startIcon={{ icon: ChevronLeft }} iconOnly onclick={prev} />

プロパティ：variant?: 'accent' | 'accent-secondary' | 'default' | 'subtle'、unifiedSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg'、startIcon?: { icon: SvelteComponent }、iconOnly?: boolean、disabled?: boolean

<Button> での size の使用は禁止です。spacingSize と extendedSize も含め、これらは従来のサイズ体系（xs3／xs2／xs／…）であり、Button.svelte で @deprecated とマークされています。小さいボタンも含め、すべてのボタンのサイズには unifiedSize を使用してください。2xs と xs は h-5、sm は h-7、md は h-8、lg は h-10 です。既存の size="xs2" の使用箇所は従来のコードであり、踏襲すべき前例ではありません。variant も同様です。contained／border／divider は非推奨なので、上記の 4 つを使用してください。

テキスト入力 — <TextInput>

<script>
  import { TextInput } from '$lib/components/common'
</script>

<TextInput bind:value={val} placeholder="Enter value" />

プロパティ：value?: string | number（バインド可能）、placeholder?: string、disabled?: boolean、error?: string | boolean、size?: 'sm' | 'md' | 'lg'

セレクト — <Select>

<script>
  import Select from '$lib/components/select/Select.svelte'
</script>

<Select items={[{ label: 'Jan', value: 1 }]} bind:value={selected} />

プロパティ：items?: Array<{ label?: string; value: any }>、value（バインド可能）、placeholder?: string、clearable?: boolean、size?: 'sm' | 'md' | 'lg'

アイコン — lucide-svelte

インライン SVG は絶対に書かないでください。lucide-svelte からインポートしてください。

<script>
  import { ChevronLeft, X } from 'lucide-svelte'
</script>
<ChevronLeft size={16} />

フォームコンポーネント

フォームコンポーネント（TextInput、Toggle、Select など）を並べて配置する場合は、統一サイズシステムを使用してください。

スタイリング

• すべてのスタイリングに Tailwind CSS を使用してください。カスタム CSS は使用しないでください
• 色やサーフェスには Windmill のテーマ用クラスを使用してください（frontend/brand-guidelines.md を参照）
• 使用する前に、コンポーネントの props の JSDoc を読んでください

機能テレメトリー

ユーザー向けの新しい UX は feature_usage カウンターの主な発生源です。別途質問するのではなく、計画の中で提案し、まず docs/feature-telemetry.md を読んでください。$lib/utils/featureUsage の logFeatureUsage() は変更の半分にすぎません。(feature, kind) の組み合わせもバックエンドの許可リストに登録する必要があります。登録しないと、すべてのイベントが通知されずに破棄されます。InstanceSettings.svelte の開示文言はカテゴリーレベルのままにしてください。レシピのステップ 3 を参照してください。

Svelte MCP サーバー

Svelte コードを扱う際は、Svelte MCP ツールを使用してください。

1. list-sections：利用可能なドキュメントを確認するため、最初に呼び出してください
2. get-documentation：use_cases に基づいて関連するセクションを取得してください
3. svelte-autofixer：最終確定の前に、すべての Svelte コードに必ず使用してください。問題がなくなるまで繰り返し呼び出してください
4. playground-link：ユーザーの確認後、かつコードをプロジェクトファイルに書き込んでいない場合に限り使用してください

ブラウザーでの検証

Svelte コードを変更した後は、Playwright MCP（mcp__playwright__*）を使用して実行中のフロントエンドを操作し、変更が機能することを確認してください。詳しい手順は frontend/AGENTS.md →「フロントエンドの変更の検証」を参照してください。devbox では playwright（ヘッドレス）を、ディスプレイを利用できる場合は playwright-headed を使用してください。