starwind-ui

Starwind UI v3

Starwind UI 是一个以 Astro 为先、可移植到不同框架的系统，适用于 Astro 和 React。其常规产品形态是安装到应用中的可编辑样式化源码。对于需要更多控制的项目，基础组件适配器和与框架无关的 Runtime 属于更底层的方案。

使用 starwind@latest。当前要求：Node 22.12+、Tailwind CSS 4、Astro 5+，或 React 和 React DOM 18+。上游仓库中的 Vue 和 Svelte 代码仅用于内部验证，不是面向公众发布的包，也不是 CLI 的目标。

请在项目根目录中使用项目的包运行器执行 CLI 命令。示例使用 npx starwind@latest；如果本地文件表明项目使用其他包管理器，请替换为 pnpm dlx、pnpx 或 yarn dlx。

确认项目上下文

修改代码前，请先查看以下内容：

• package.json、packageManager 和锁文件：框架、包运行器、版本和脚本。
• starwind.config.json：配置生成、主要框架、注册表、组件/Primitive 目标目录、已安装记录、Tailwind CSS 和 Pro 设置。
• 框架配置：astro.config.*、Vite、Next.js、TanStack Start 或 React Router 文件。
• 配置指定的 Starwind CSS 文件：令牌、@theme inline、:root 和 .dark。
• 配置的组件目录及本地 index.ts/index.tsx 导出：已安装源码和准确的公开组成部分。
• 附近的导入和测试：别名、图标系统、语法、状态和事件约定。

Starwind UI v3 仍会生成使用 config-schema.v2.json 架构且带有 version: 2 的配置。产品主版本和配置格式版本并不相同；不要手动“升级”配置编号。

选择合适的层

1. 优先使用样式化组件。 使用 starwind add 获取可直接渲染、可编辑且带有 Starwind 变体和组合方式的源码。
2. 需要自行控制结构时，使用基础组件适配器。 导入 @starwind-ui/astro/<name> 或 @starwind-ui/react/<name>；如果项目必须直接编辑适配器本身，则使用 starwind primitives add 将可编译的适配器源码复制到项目中。
3. 处理原生 DOM 或适配器时，使用 Runtime。 仅在使用纯 HTML、自定义适配器或直接集成控制器时，使用 @starwind-ui/runtime/<name> 或 initStarwind。

如果任务涉及包中的 Primitives、复制到项目中的 Primitive 源码、Runtime 控制器、原生 HTML，或编辑由 Runtime 支持的组件内部内容，请阅读 layers.md。

核心规则

• 在自行设计 UI 前，先检查已安装源码、当前文档、MCP 或注册表元数据。
• 编写相似标记前，先组合现有组件和有文档说明的组成部分。
• 使用内置变体、语义令牌和有文档说明的状态选择器，再考虑自定义内部实现。
• 编辑已安装的组件源码时，保留 data-slot 作为公开组成部分的标识，并保留 data-sw-* 作为 Runtime 发现钩子。
• 遵循文件所用的框架：Astro 使用 class、for、静态初始状态属性和浏览器脚本；React 使用 className、htmlFor、React 事件处理器，以及适用时的受控属性。
• 在假设组成部分、属性、事件或 asChild 的用法前，先查看本地导出和当前组件文档。
• 将样式化源码视为应用自有内容；替换自定义文件前先检查差异。

关键规则

这里再次列出这些防护规则，因为根技能是唯一能保证加载的文件：

• 样式： 优先使用内置变体和语义令牌，再考虑原始调色板工具类或大范围外观覆盖。使用 gap-*、size-* 和 truncate；在当前 Starwind CSS 变量中更改全局浅色／深色颜色。
• 表单： 保留原生的 name、提交、重置、必填、禁用和验证行为。Astro 使用 for；React 使用 htmlFor。将无效状态与对应的错误文本配对。
• 组合： 将项目放在文档指定的组内，为 Dialog／Sheet／Alert Dialog 设置标题，将 TabsTrigger 放在 TabsList 内，并将 AvatarImage 与 AvatarFallback 配对。
• 加载： Button 没有默认的 isLoading 或 isPending 属性。确认已安装的 API 后，再组合使用 Spinner、disabled 和 aria-busy。
• 图标： 复用项目的图标系统，并为每个仅含图标的控件命名。除非本地 Starwind 源码有说明，否则不要照搬 shadcn 的 data-icon 约定。
• 更新： 接受替换前，使用 --dry-run、--diff 或 --view 预览已自定义样式或供应商提供的源码。

关键形状：

<Field name="email">
  <FieldLabel>Email</FieldLabel>
  <FieldControl type="email" required />
  <FieldError match="valueMissing">Enter an email address.</FieldError>
</Field>

<Button disabled aria-busy="true"><Spinner /> Saving...</Button>

<DialogContent>
  <DialogHeader><DialogTitle class="sr-only">Edit profile</DialogTitle></DialogHeader>
  
</DialogContent>

重点规则

• rules/composition.md：组件嵌套、叠加层、Toast、独立 Combobox、Card、Tabs、Avatar 和加载组合。
• rules/forms.md：原生表单参与、Field／Form、标签、默认值、验证和 Input Group。
• rules/styling.md：语义令牌、变体、间距、状态选择器和 Runtime 钩子边界。
• rules/icons.md：符合框架规范的图标导入和无障碍图标按钮。
• customization.md：主题、深色模式初始化、变量和安全的组件自定义。

仅加载与当前任务相匹配的参考资料。

组件选择

需求	从这里开始
操作	button；相关操作使用 button-group
表单结构	form、field、fieldset、label
文本和选项输入	input、textarea、input-group、checkbox、checkbox-group、radio-group、switch、slider、input-otp
固定选项列表	select 或 native-select
可搜索选项	独立的 combobox；V3 没有 SelectSearch
导航	navigation-menu、sidebar、breadcrumb、tabs、pagination
叠加层	dialog、sheet、alert-dialog、popover、dropdown、context-menu、hover-card、tooltip
反馈	toast、alert、progress、skeleton、spinner
数据和内容	table、card、badge、avatar、item、kbd、prose
富输入／媒体	color-picker、dropzone、image、video、carousel
披露和切换	accordion、collapsible、toggle、toggle-group

安装前，请确认配置的框架支持该组件。带样式的 image 组件仅适用于 Astro。

当前文档和命令

如需了解准确的 API，请查阅当前文档或已安装的源码：

npx starwind@latest docs button dialog combobox --json
npx starwind@latest search combobox --json

如果 Starwind MCP 可用，优先使用；然后依次查阅各页面的 Markdown、llms.txt、llms-full.txt 和 ai-manifest.json。有关来源优先级和后备方案，请参阅 mcp.md。

常用的 V3 命令：

npx starwind@latest init --framework astro
npx starwind@latest init --framework react
npx starwind@latest add button dialog combobox
npx starwind@latest update button --dry-run
npx starwind@latest update button --diff
npx starwind@latest primitives add button --framework react
npx starwind@latest primitives list --framework all
npx starwind@latest migrate

仅使用 cli.md 中记录的标志。

工作流程

1. 确认框架、包运行器、当前配置结构、目标位置、已安装记录和本地验证命令。
2. 根据分层结构选择 Styled、Primitive 或 Runtime。
3. 通过已安装的源码和当前文档确认组件及 API。
4. 按照配置指定的确切框架和目标位置安装缺失的源码。
5. 在将新增或替换的文件接入应用之前，逐一阅读。
6. 通过本地导出和框架语法进行组合；保留 Runtime 钩子和原生语义。
7. 运行范围最小且相关的格式检查、类型检查、构建、测试和浏览器检查。

只有在每个导入都能从预期的框架和目标位置解析、生成或编辑的源码符合当前文档所述的约定，并且相关验证均通过或已报告每项未解决的问题时，任务才算完成。

更新和迁移

update 可能会替换本地修改过的 Styled 或供应商提供的 Primitive 源码。请先预览：

npx starwind@latest update button --dry-run
npx starwind@latest update button --diff
npx starwind@latest update button --view

只有在请求范围明确且本地更改可以恢复时，才使用 --all 或 --overwrite。

对于尚未使用 Runtime 的 Astro 项目，请在运行 starwind migrate 前阅读 v3-migration.md。 迁移成功意味着已处理迁移报告、剩余的旧版条目、应用 API 更改和行为检查，而不只是命令已退出。

参考资料

• cli.md：完整的 V3 CLI 功能和所有权注意事项
• layers.md：Styled、Primitive、供应商提供的源码和 Runtime 的边界
• v3-migration.md：从 V2 Astro 迁移到 V3 Runtime 的操作指南
• customization.md：令牌、深色模式和安全自定义
• shadcn-migration.md：仅映射 shadcn 风格的主题令牌
• mcp.md：实时 Starwind 工具和可供 AI 阅读的文档