svelte-frontend

Windmill Svelte 模式

在 frontend/ 中编写 Svelte 代码时，请采用这些 Windmill 专属模式。有关 Svelte 5 的通用语法（runes、snippets、事件处理），请使用 Svelte MCP 服务。

编写任何 UI 之前（必须）

在写下第一行标记之前，先完成以下两项——不要等到之后，也不要只在遇到陌生内容时才做。

1. 找到已有组件。 frontend/src/lib/components/common/index.ts 是设计系统的集中导出文件，共 28 行，请完整阅读。它导出的组件远不止下面记录的三个：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/ 等也都存在，但 必须通过路径导入。Select、文本输入和基于 melt 的基础组件位于 common/ 旁边的 components/select/、components/text_input/、components/meltComponents/ 中。

组件树中有 1,600 多个组件——用 grep 搜索 frontend/src/lib/components，查找你准备 构建的组件；它几乎肯定已经存在。构建新组件是最后的选择，而不是第一步。

2. 阅读你要构建内容的设计指南。 frontend/brand-guidelines.md 是关于外观和 文案的权威指南。无需加载全部 34k 字符——直接跳到相应章节：

构建内容	阅读章节
任何新页面或组件	# Components（核心规则、快速参考）
按钮、CTA	## Buttons——层级很重要，每个视图只能有一个 Accent
颜色、表面、边框	# Color system（快速参考、注意事项）
文本、标签、标题	# 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 元素。下面三个是最常用的示例， 并非完整目录。其他组件请查看集中导出文件并使用 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 已弃用——请使用上面列出的四种值。

文本输入 — <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）
• 使用组件属性前，先阅读其 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 → “验证前端更改”。在 devboxes 上使用 playwright（无头模式）；有显示器时使用 playwright-headed。