svelte-frontend

# Windmill Svelte Patterns Apply these Windmill-specific patterns when writing Svelte code in `frontend/`. For general Svelte 5 syntax (runes, snippets, event handling), use the Svelte MCP server. ## Before writing any UI (MUST) Do both of these before the first line of markup — not after, and not only when something looks unfamiliar. **1. Find the component that already exists.** `frontend/src/lib/components/common/index.ts` is the design-system barrel — 28 lines, read it in full. It exports far more than the three documented below: `Alert`, `Badge`, `Breadcrumb`, `Drawer`/`DrawerContent`, `Menu`/`MenuItem`, `Tabs`/`Tab`/`TabContent`, `Skeleton`, `FileInput`, `RadioCard`, `Section`, `Kbd`, `ActionRow`, `ClearableInput`, `CopyButton`, `SecondsInput`, `UndoRedo`, `Url`. The barrel is not the full picture either: `common/` has 34 subdirectories and only 23 exports, so `modal/`, `popup/`, `stepper/`, `tooltip/`, `checkbox/`, `table/`, `contextmenu/`, `confirmationModal/`, `calendarPicker/`, `fileUpload/`, `toggleButton-v2/` and more exist but must be imported by path. Selects, text inputs and melt-based primitives sit next to `common/` in `components/select/`, `components/text_input/`, `components/meltComponents/`. The tree holds 1,600+ components — grep `frontend/src/lib/components` for the thing you're about to build; it almost certainly exists. Building a new one is the last resort, not the first move. **2. Read the guideline for what you're building.** `frontend/brand-guidelines.md` is the authority on how it should look and read. Don't load all 34k chars — jump to the section: | Building | Section to read | |---|---| | Any new screen or component | `# Components` (Core Rules, Quick Reference) | | Buttons, CTAs | `## Buttons` — hierarchy matters, only one Accent per view | | Colors, surfaces, borders | `# Color system` (Quick Reference, Do's and Don'ts) | | Text, labels, headings | `# Typography` — note `## Text Casing`, sentence case throughout | | Spacing, grids, page structure | `# Spacing & Layout`; `# Layout` → `## Form` for forms | | Shadows, overlays, depth | `# Elevation` | | Icons | `# Iconography` | | Wording of any UI copy | `# Voice & Communication`, `# Tone of Voice` | Get the line range with `grep -n '^#' frontend/brand-guidelines.md`, then read just that span. ## Windmill UI Components (MUST use) Always use Windmill's design-system components. Never use raw HTML elements. The three below are the ones you'll reach for most often — they are examples, not the catalog. For anything else, go back to the barrel and grep. ### Buttons — `<Button>` ```svelte <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} /> ``` Props: `variant?: 'accent' | 'accent-secondary' | 'default' | 'subtle'`, `unifiedSize?: '2xs' | 'xs' | 'sm' | 'md' | 'lg'`, `startIcon?: { icon: SvelteComponent }`, `iconOnly?: boolean`, `disabled?: boolean` **`size` on `<Button>` is banned** — it, `spacingSize` and `extendedSize` are the legacy sizing system (`xs3`/`xs2`/`xs`/…, marked `@deprecated` in `Button.svelte`). Size every button with `unifiedSize`, the small ones included: `2xs` and `xs` are `h-5`, `sm` is `h-7`, `md` is `h-8`, `lg` is `h-10`. Existing `size="xs2"` call sites are legacy, not a precedent to copy. Same for `variant`: `contained`/`border`/`divider` are deprecated — use the four listed above. ### Text inputs — `<TextInput>` ```svelte <script> import { TextInput } from '$lib/components/common' </script> <TextInput bind:value={val} placeholder="Enter value" /> ``` Props: `value?: string | number` (bindable), `placeholder?: string`, `disabled?: boolean`, `error?: string | boolean`, `size?: 'sm' | 'md' | 'lg'` ### Selects — `<Select>` ```svelte <script> import Select from '$lib/components/select/Select.svelte' </script> <Select items={[{ label: 'Jan', value: 1 }]} bind:value={selected} /> ``` Props: `items?: Array<{ label?: string; value: any }>`, `value` (bindable), `placeholder?: string`, `clearable?: boolean`, `size?: 'sm' | 'md' | 'lg'` ### Icons — `lucide-svelte` Never write inline SVGs. Import from `lucide-svelte`: ```svelte <script> import { ChevronLeft, X } from 'lucide-svelte' </script> <ChevronLeft size={16} /> ``` ## Form Components Form components (TextInput, Toggle, Select, etc.) should use the unified size system when placed together. ## Styling - Use Tailwind CSS for all styling — no custom CSS - Use Windmill's theming classes for colors/surfaces (see `frontend/brand-guidelines.md`) - Read component props JSDoc before using them ## Feature Telemetry New user-facing UX is the main source of `feature_usage` counters — propose them in the plan, not as a separate question, and read `docs/feature-telemetry.md` first. `logFeatureUsage()` from `$lib/utils/featureUsage` is only half the change: the `(feature, kind)` pair must also be registered in the backend allowlist or every event is silently discarded. The disclosure copy in `InstanceSettings.svelte` stays at the category level; see the recipe's step 3. ## Svelte MCP Server Use the Svelte MCP tools when working on Svelte code: 1. **list-sections**: Call first to discover available docs 2. **get-documentation**: Fetch relevant sections based on use_cases 3. **svelte-autofixer**: MUST use on all Svelte code before finalizing — keep calling until no issues 4. **playground-link**: Only after user confirms and code was NOT written to project files ## Verifying in the Browser After changing Svelte code, use the **Playwright MCP** (`mcp__playwright__*`) to drive the running frontend and confirm the change works. See frontend/AGENTS.md → "Verifying Frontend Changes" for the full flow. Use `playwright` (headless) on devboxes; `playwright-headed` when a display is available.