starwind-ui

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Starwind UI

Astro components and design-system primitives installed as source code into the user's project via the Starwind CLI. Starwind UI is designed for Astro v6 and Tailwind CSS v4.

IMPORTANT: Run CLI commands from the user's project root using the project's package runner:
npx starwind@latest
,
pnpx starwind@latest
/
pnpm dlx starwind@latest
, or
yarn dlx starwind@latest
, based on
package.json
, lockfiles,
starwind.config.json
, or user instruction.

Examples below use

npx starwind@latest

, but substitute the correct runner for the project.

Astro组件与设计系统基础元素通过Starwind CLI以源代码形式安装到用户项目中。Starwind UI专为Astro v6和Tailwind CSS v4设计。

重要提示： 请从用户项目根目录使用项目的包运行器执行CLI命令：根据
package.json
、锁文件、
starwind.config.json
或用户指令，选择
npx starwind@latest
、
pnpx starwind@latest
/
pnpm dlx starwind@latest
或
yarn dlx starwind@latest
。

以下示例使用

npx starwind@latest

，请根据项目替换为正确的运行器。

Current Project Context

当前项目上下文

Build project context from local files before editing:

```
package.json
```
, lockfiles, and
```
packageManager
```
-> package runner and dependency commands.
```
astro.config.*
```
-> Astro project shape and Tailwind/Vite setup.
```
starwind.config.json
```
->
```
starwind.css
```
,
```
componentDir
```
, base color, and installed component list.
Active Starwind CSS file -> global tokens,
```
@theme inline
```
,
```
:root
```
,
```
.dark
```
, and sidebar tokens.
Installed component directory, commonly
```
src/components/starwind
```
-> available imports and local source.
Local component
```
index.ts
```
exports -> final authority for component part names when docs and local code differ.

在编辑前从本地文件构建项目上下文：

```
package.json
```
、锁文件与
```
packageManager
```
-> 包运行器和依赖命令。
```
astro.config.*
```
-> Astro项目结构与Tailwind/Vite配置。
```
starwind.config.json
```
->
```
starwind.css
```
、
```
componentDir
```
、基础颜色及已安装组件列表。
活跃的Starwind CSS文件 -> 全局令牌、
```
@theme inline
```
、
```
:root
```
、
```
.dark
```
及侧边栏令牌。
已安装组件目录（通常为
```
src/components/starwind
```
） -> 可用的导入项与本地源代码。
本地组件
```
index.ts
```
导出内容 -> 当文档与本地代码存在差异时，以此作为组件部件名称的最终依据。

Principles

原则

Use existing components first. Check Starwind docs, MCP, search, local components, or registry metadata before writing custom UI.
Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Table + feedback primitives. Searchable select = Select + SelectSearch.
Use built-in variants before custom styles.
```
variant="outline"
```
,
```
size="sm"
```
,
```
size="icon"
```
, etc.
Use semantic colors and tokens.
```
bg-primary
```
,
```
text-muted-foreground
```
,
```
border-border
```
,
```
bg-card
```
; avoid raw palette utilities when a semantic token exists.
Astro syntax first. Use
```
class
```
,
```
for
```
, browser scripts, and
```
.astro
```
component imports unless the local project intentionally uses a framework island.

优先使用现有组件。在编写自定义UI前，先查阅Starwind文档、MCP、搜索结果、本地组件或注册表元数据。
组合复用，而非重复造轮子。设置页面 = 标签页（Tabs）+ 卡片（Card）+ 表单控件；仪表盘 = 侧边栏（Sidebar）+ 卡片（Card）+ 表格（Table）+ 反馈基础元素；可搜索选择器 = 选择器（Select）+ 选择器搜索（SelectSearch）。
优先使用内置变体而非自定义样式。例如
```
variant="outline"
```
、
```
size="sm"
```
、
```
size="icon"
```
等。
使用语义化颜色与令牌。例如
```
bg-primary
```
、
```
text-muted-foreground
```
、
```
border-border
```
、
```
bg-card
```
；当存在语义化令牌时，避免使用原始调色板工具类。
优先使用Astro语法。使用
```
class
```
、
```
for
```
、浏览器脚本及
```
.astro
```
组件导入，除非本地项目特意使用框架孤岛（island）。

Critical Rules

核心规则

These rules are always enforced. Each links to a focused reference file.

这些规则始终强制执行，每条规则均链接至对应的参考文件。

Styling & Tailwind -> styling.md

样式与Tailwind -> styling.md

class
is for layout and scoped exceptions. Do not override component colors or typography with long utility strings when variants or tokens exist.
No
space-x-*
or
space-y-*
in new code. Use
```
flex
```
or
```
grid
```
with
```
gap-*
```
.
Use
size-*
when width and height are equal.
```
size-10
```
, not
```
w-10 h-10
```
.

Use
truncate
shorthand. Do not spell out

overflow-hidden text-ellipsis whitespace-nowrap

No manual
dark:
color overrides for global themes. Change
```
:root
```
and
```
.dark
```
variables in the active Starwind CSS file.

class
用于布局与作用域例外情况。当存在变体或令牌时，请勿使用冗长的工具类字符串覆盖组件颜色或排版。
新代码中禁止使用
space-x-*
或
space-y-*
。使用
```
flex
```
或
```
grid
```
搭配
```
gap-*
```
。
当宽高相等时使用
size-*
。例如
```
size-10
```
，而非
```
w-10 h-10
```
。

使用
truncate
简写。请勿完整写出

overflow-hidden text-ellipsis whitespace-nowrap

。

全局主题禁止手动添加
dark:
颜色覆盖。在活跃的Starwind CSS文件中修改
```
:root
```
与
```
.dark
```
变量。

Forms & Inputs -> forms.md

表单与输入框 -> forms.md

Astro forms use semantic markup, Label, controls, and ARIA. Starwind does not use shadcn's React
```
FieldGroup
```
/
```
Field
```
API.
Use
for
, not
htmlFor
. Match
```
Label for
```
to the control
```
id
```
.
Preserve
name
on controls that submit.

InputGroup
uses
InputGroupInput
or
InputGroupTextarea
. Never put raw

Input

Textarea

inside

InputGroup

Buttons inside inputs use
InputGroupAddon
and
InputGroupButton
.
Validation pairs
aria-invalid
with
aria-describedby
. Do not rely on color alone.

Astro表单使用语义化标记、Label、控件及ARIA。Starwind不使用shadcn的React
```
FieldGroup
```
/
```
Field
```
API。
使用
for
而非
htmlFor
。将
```
Label for
```
与控件的
```
id
```
匹配。
保留提交控件的
name
属性。

InputGroup
需搭配
InputGroupInput
或
InputGroupTextarea
。切勿在

InputGroup

中直接放置原生

Input

或

Textarea

。

输入框内的按钮需使用
InputGroupAddon
与
InputGroupButton
。
验证需将
aria-invalid
与
aria-describedby
配对使用。切勿仅依赖颜色提示。

Component Structure -> composition.md

组件结构 -> composition.md

Items stay inside groups.

SelectItem

SelectGroup

Item

ItemGroup

InputOtpSlot

InputOtpGroup

Kbd

KbdGroup

Use
asChild
only when the Starwind component documents it. Common triggers support it, but verify from current docs or local exports.
Dialog, Sheet, and AlertDialog need titles. Use
```
DialogTitle
```
,
```
SheetTitle
```
, or
```
AlertDialogTitle
```
;
```
class="sr-only"
```
is fine when visually hidden.

Use full Card composition.

CardHeader

CardTitle

CardDescription

CardContent

CardFooter

, and

CardAction

when relevant.

Button has no
isPending
/
isLoading
. Compose loading with

Spinner

disabled

, and

aria-busy

TabsTrigger
belongs inside
TabsList
.
Avatar
always needs
AvatarFallback
.

子项需置于对应组内。例如

SelectItem

SelectGroup

、

Item

ItemGroup

、

InputOtpSlot

InputOtpGroup

、

Kbd

KbdGroup

。

仅当Starwind组件文档明确说明时使用
asChild
。常见触发器支持该属性，但需从当前文档或本地导出内容中确认。
Dialog、Sheet与AlertDialog必须包含标题。使用
```
DialogTitle
```
、
```
SheetTitle
```
或
```
AlertDialogTitle
```
；若需视觉隐藏，可添加
```
class="sr-only"
```
。
完整使用Card组合结构。相关场景下需使用
```
CardHeader
```
、
```
CardTitle
```
、
```
CardDescription
```
、
```
CardContent
```
、
```
CardFooter
```
及
```
CardAction
```
。
Button无
isPending
/
isLoading
属性。通过
```
Spinner
```
、
```
disabled
```
与
```
aria-busy
```
组合实现加载状态。
TabsTrigger
必须置于
TabsList
内。
Avatar
必须搭配
AvatarFallback
。

Use Components, Not Custom Markup -> composition.md

使用组件而非自定义标记 -> composition.md

Use existing components before custom markup.
Callouts use
Alert
.
Toast uses Starwind
toast
+ one
Toaster
, not a custom toast stack.
Use
Separator
instead of raw
hr
or border-only dividers.
Use
Skeleton
for loading placeholders.
Use
Spinner
for active progress.
Use
Badge
for status labels.
Combobox is the Select pattern. Install
```
select
```
, then use
```
SelectSearch
```
; do not run
```
starwind add combobox
```
.

优先使用现有组件而非自定义标记。
提示框使用
Alert
。
Toast使用Starwind
toast
+ 单个
Toaster
，而非自定义Toast栈。
使用
Separator
替代原生
hr
或仅含边框的分隔器。
使用
Skeleton
作为加载占位符。
使用
Spinner
表示活跃进度。
使用
Badge
作为状态标签。
Combobox属于Select模式。安装
```
select
```
后使用
```
SelectSearch
```
；请勿执行
```
starwind add combobox
```
。

Icons -> icons.md

图标 -> icons.md

Prefer the project's existing icon system. Do not assume Tabler just because Starwind examples often use
```
@tabler/icons
```
.
Do not import React icon packages in plain Astro components unless the project uses a React island for that component.
Icon-only buttons need an accessible name. Use
```
aria-label
```
or visible text.
Let components size common SVG children unless a specific documented override is needed.

优先使用项目现有图标系统。请勿因Starwind示例常使用
```
@tabler/icons
```
就默认使用Tabler图标。
纯Astro组件中禁止导入React图标包，除非项目为该组件使用React孤岛。
仅含图标的按钮需添加可访问名称。使用
```
aria-label
```
或可见文本。
除非需要特定的文档化覆盖，否则让组件自动调整常用SVG子元素的尺寸。

Customization -> customization.md

自定义配置 -> customization.md

Theme globally through CSS variables first.
Edit the active Starwind CSS file from
starwind.config.json
; do not create a second theme file.
Preserve
@theme inline
,
:root
,
.dark
, sidebar tokens, keyframes, and component-specific variables.
Starwind dark mode is class-based through
.dark
. Do not switch to a data-theme system unless the app already bridges that model.
For shadcn-style theme migration, merge semantic values into Starwind tokens. See shadcn-migration.md.

优先通过CSS变量进行全局主题配置。
编辑
starwind.config.json
中指定的活跃Starwind CSS文件；请勿创建第二个主题文件。
保留
@theme inline
、
:root
、
.dark
、侧边栏令牌、关键帧及组件专属变量。
Starwind暗黑模式基于
.dark
类实现。除非应用已适配该模型，否则请勿切换至data-theme系统。
针对shadcn风格主题迁移，需将语义化值合并到Starwind令牌中。详见shadcn-migration.md。

CLI -> cli.md

Only use documented Starwind commands and flags.
Do not invent shadcn CLI features such as
```
info
```
,
```
view
```
,
```
apply
```
, presets, templates,
```
--dry-run
```
,
```
--diff
```
,
```
--overwrite
```
, or
```
--cwd
```
.
update
overwrites local component changes. Only update when the user asks or accepts overwrite risk.
After
add
, read the added files and fix alias drift, icon-library drift, missing imports, and rule violations.

仅使用文档化的Starwind命令与标志。
请勿自创shadcn CLI功能，例如
```
info
```
、
```
view
```
、
```
apply
```
、预设、模板、
```
--dry-run
```
、
```
--diff
```
、
```
--overwrite
```
或
```
--cwd
```
。
update
会覆盖本地组件修改。仅当用户要求或接受覆盖风险时执行更新。
执行
add
后需读取新增文件，修复别名偏移、图标库偏移、缺失导入及规则违反问题。

Key Patterns

关键模式

These are common patterns that differentiate correct Starwind UI code.

astro

---
import { Button } from "@/components/starwind/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/starwind/card";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import { Spinner } from "@/components/starwind/spinner";
---

<!-- Astro syntax: class + for, not className + htmlFor -->
<div class="grid gap-2">
  <Label for="email">Email</Label>
  <Input id="email" name="email" type="email" aria-invalid="false" />
</div>

<!-- Loading button: compose with Spinner, not isLoading/isPending -->
<Button disabled aria-busy="true">
  <Spinner />
  Saving...
</Button>

<!-- Card composition: header/content parts, not one generic bordered div -->
<Card>
  <CardHeader>
    <CardTitle>Workspace</CardTitle>
  </CardHeader>
  <CardContent>Project settings</CardContent>
</Card>

以下是区分正确Starwind UI代码的常见模式。

astro

---
import { Button } from "@/components/starwind/button";
import { Card, CardContent, CardHeader, CardTitle } from "@/components/starwind/card";
import { Input } from "@/components/starwind/input";
import { Label } from "@/components/starwind/label";
import { Spinner } from "@/components/starwind/spinner";
---

<!-- Astro语法：使用class + for，而非className + htmlFor -->
<div class="grid gap-2">
  <Label for="email">邮箱</Label>
  <Input id="email" name="email" type="email" aria-invalid="false" />
</div>

<!-- 加载按钮：搭配Spinner实现，而非isLoading/isPending属性 -->
<Button disabled aria-busy="true">
  <Spinner />
  保存中...
</Button>

<!-- Card组合结构：使用头部/内容部件，而非单一通用边框容器 -->
<Card>
  <CardHeader>
    <CardTitle>工作区</CardTitle>
  </CardHeader>
  <CardContent>项目设置</CardContent>
</Card>

Component Selection

组件选择

Need	Use
Button/action	`button` with documented variants and sizes
Form inputs	`input` , `textarea` , `label` , `select` , `native-select` , `checkbox` , `radio-group` , `switch` , `slider` , `input-otp` , `input-group`
Searchable select / combobox	`select` with `SelectSearch`
Option toggle	`toggle` ; use documented group/patterns if the local project has one
Data display	`table` , `card` , `badge` , `avatar` , `item` , `kbd`
Navigation	`sidebar` , `breadcrumb` , `tabs` , `pagination` , `scroll-area`
Overlays	`dialog` , `sheet` , `alert-dialog` , `popover` , `hover-card` , `tooltip`
Menus	`dropdown` , `context-menu`
Feedback	`toast` , `alert` , `progress` , `skeleton` , `spinner`
Media	`image` , `video` , `aspect-ratio` , `carousel`
Layout/disclosure	`card` , `separator` , `accordion` , `collapsible`
Theme toggle	`theme-toggle`

需求	使用组件
按钮/操作	`button` 搭配文档化的变体与尺寸
表单输入框	`input` 、 `textarea` 、 `label` 、 `select` 、 `native-select` 、 `checkbox` 、 `radio-group` 、 `switch` 、 `slider` 、 `input-otp` 、 `input-group`
可搜索选择器/Combobox	`select` 搭配 `SelectSearch`
选项切换器	`toggle` ；若本地项目有相关组/模式，请使用文档化的实现
数据展示	`table` 、 `card` 、 `badge` 、 `avatar` 、 `item` 、 `kbd`
导航	`sidebar` 、 `breadcrumb` 、 `tabs` 、 `pagination` 、 `scroll-area`
浮层	`dialog` 、 `sheet` 、 `alert-dialog` 、 `popover` 、 `hover-card` 、 `tooltip`
菜单	`dropdown` 、 `context-menu`
反馈	`toast` 、 `alert` 、 `progress` 、 `skeleton` 、 `spinner`
媒体	`image` 、 `video` 、 `aspect-ratio` 、 `carousel`
布局/折叠面板	`card` 、 `separator` 、 `accordion` 、 `collapsible`
主题切换器	`theme-toggle`

Key Fields

关键字段

starwind.config.json
-> source of
```
starwind.css
```
,
```
componentDir
```
, base color, and installed component list.
starwind.css
-> active Starwind CSS file for theme variables. Always edit this file for global theme work.
componentDir
-> component install root. The Starwind subdirectory is commonly
```
src/components/starwind
```
.
components
-> installed component names when present in config.
packageManager
/ lockfiles -> use this for the Starwind runner and dependency installs.
astro.config.*
-> confirms Astro/Vite/Tailwind setup.
Local
index.ts
exports -> exact import names for installed component parts.
Icon imports in nearby files -> preferred icon package and import style.

starwind.config.json
->
```
starwind.css
```
、
```
componentDir
```
、基础颜色及已安装组件列表的来源。
starwind.css
-> 用于主题变量的活跃Starwind CSS文件。全局主题修改需始终编辑此文件。
componentDir
-> 组件安装根目录。Starwind子目录通常为
```
src/components/starwind
```
。
components
-> 配置中存在的已安装组件名称。
packageManager
/ 锁文件 -> 用于Starwind运行器与依赖安装。
astro.config.*
-> 确认Astro/Vite/Tailwind配置。
本地
index.ts
导出内容 -> 已安装组件部件的准确导入名称。
附近文件中的图标导入 -> 首选图标包与导入风格。

Component Docs, Examples, And Usage

组件文档、示例与用法

Use the freshest Starwind context available:

bash

npx starwind@latest docs button dialog select --json

Then fetch and read the returned docs or Markdown URLs before implementing. When tools are available, prefer Starwind MCP

starwind_docs

for live docs and

starwind_add

for install command generation. Local project source remains the final authority for already-installed components.

When creating, fixing, debugging, or using a component, always read the relevant docs or local component source first. Do not guess props, events, or composition from memory.

使用最新的Starwind上下文：

bash

npx starwind@latest docs button dialog select --json

在实现前获取并阅读返回的文档或Markdown链接。当工具可用时，优先使用Starwind MCP的

starwind_docs

获取实时文档，使用

starwind_add

生成安装命令。本地项目源代码始终是已安装组件的最终权威依据。

在创建、修复、调试或使用组件时，务必先阅读相关文档或本地组件源代码。请勿凭记忆猜测属性、事件或组合方式。

Workflow

工作流程

Get project context -> read
```
package.json
```
, lockfiles, Astro config,
```
starwind.config.json
```
, active Starwind CSS, installed component directory, and local exports.
Check installed components first -> do not import components that have not been added, and do not re-add ones already installed unless the user asked to update.
Find components -> use Starwind MCP,
```
npx starwind@latest search
```
, docs,
```
llms.txt
```
,
```
llms-full.txt
```
,
```
ai-manifest.json
```
, or installed registry metadata.
Get docs and examples -> use Starwind MCP or
```
npx starwind@latest docs <component> --json
```
, then fetch the docs content.
Install missing components -> use
```
npx starwind@latest add <component>
```
with the correct package runner and documented flags.
Review added files -> read new component/block files before wiring them in. Fix import aliases, icon imports, missing subcomponents, Astro syntax, and Critical Rules violations.
Compose before editing internals -> use documented props, variants,
```
class
```
, semantic tokens, and wrappers before changing installed component source.
Keep changes scoped -> preserve project patterns and avoid unrelated refactors.

获取项目上下文 -> 读取
```
package.json
```
、锁文件、Astro配置、
```
starwind.config.json
```
、活跃Starwind CSS文件、已安装组件目录及本地导出内容。
优先检查已安装组件 -> 请勿导入未添加的组件，除非用户要求更新，否则请勿重新添加已安装的组件。
查找组件 -> 使用Starwind MCP、
```
npx starwind@latest search
```
、文档、
```
llms.txt
```
、
```
llms-full.txt
```
、
```
ai-manifest.json
```
或已安装的注册表元数据。
获取文档与示例 -> 使用Starwind MCP或
```
npx starwind@latest docs <component> --json
```
，然后获取文档内容。
安装缺失组件 -> 使用
```
npx starwind@latest add <component>
```
搭配正确的包运行器与文档化标志。
审核新增文件 -> 在接入前阅读新组件/区块文件。修复导入别名、图标导入、缺失子组件、Astro语法及核心规则违反问题。
先组合再编辑内部 -> 在修改已安装组件源代码前，优先使用文档化的属性、变体、
```
class
```
、语义化令牌及包装器。
保持变更范围可控 -> 保留项目模式，避免无关重构。

Updating Components

更新组件

Starwind components are local source files after installation.

CAUTION:
npx starwind@latest update
overwrites local component changes.

When the user asks to update a component while preserving local changes:

Read the local component files and where they are imported.
Read current docs or source for the target component.
Decide whether to manually merge the needed upstream changes or ask approval to run
```
update
```
.
Use
```
npx starwind@latest update <component>
```
only when the user asks for it or accepts overwrite risk.
Use
```
update --all
```
only when the user explicitly wants every installed component updated.

Starwind组件安装后为本地源文件。

注意：
npx starwind@latest update
会覆盖本地组件修改。

当用户要求更新组件同时保留本地修改时：

读取本地组件文件及其导入位置。
读取目标组件的当前文档或源代码。
决定是手动合并所需的上游变更，还是请求用户批准执行
```
update
```
。
仅当用户要求或接受覆盖风险时，使用
```
npx starwind@latest update <component>
```
。
仅当用户明确要求更新所有已安装组件时，使用
```
update --all
```
。

Quick Reference

快速参考

bash

undefined

bash

undefined

Initialize Starwind UI

初始化Starwind UI

npx starwind@latest init npx starwind@latest init --defaults npx starwind@latest init --pro

Add components

添加组件

npx starwind@latest add button card dialog npx starwind@latest add select npx starwind@latest add theme-toggle

Add all components

添加所有组件

npx starwind@latest add --all

Search components and Pro blocks

搜索组件与Pro区块

npx starwind@latest search select npx starwind@latest search hero --json npx starwind@latest search pricing --plan free --category pricing --limit 10 --json

Get docs references

获取文档参考

npx starwind@latest docs button dialog select --json

Configure Starwind Pro in an existing project

在现有项目中配置Starwind Pro

npx starwind@latest setup npx starwind@latest setup --yes

Update or remove components

更新或移除组件

npx starwind@latest update button npx starwind@latest remove button

undefined

npx starwind@latest update button npx starwind@latest remove button

undefined

Detailed References

详细参考

rules/forms.md -> labels, controls, InputGroup, Select, validation
rules/composition.md -> groups, overlays, Card, Tabs, Avatar, Toast, Separator, Skeleton, Spinner, Badge, Button loading
rules/icons.md -> Astro icon imports, icon buttons, icon-library drift
rules/styling.md -> semantic colors, variants, class, spacing, size, truncate, dark mode, z-index
cli.md -> Starwind commands, flags, Pro setup, and missing shadcn CLI features
customization.md -> theming, CSS variables, dark mode, extending components
shadcn-migration.md -> mapping shadcn-style theme tokens to Starwind
mcp.md -> MCP and AI docs source priority

Load only the references needed for the current task.

rules/forms.md -> 标签、控件、InputGroup、Select、验证
rules/composition.md -> 组、浮层、Card、Tabs、Avatar、Toast、Separator、Skeleton、Spinner、Badge、按钮加载状态
rules/icons.md -> Astro图标导入、图标按钮、图标库偏移
rules/styling.md -> 语义化颜色、变体、class、间距、尺寸、截断、暗黑模式、z-index
cli.md -> Starwind命令、标志、Pro配置、缺失的shadcn CLI功能
customization.md -> 主题配置、CSS变量、暗黑模式、组件扩展
shadcn-migration.md -> shadcn风格主题令牌到Starwind的映射
mcp.md -> MCP与AI文档源优先级

仅加载当前任务所需的参考内容。