用途
@lottiefiles/creator-plugins-ui 是用于 LottieFiles Creator Plugin 的用户界面组件库，适用于构建或修改插件 UI 的场景。该库仅用于插件 UI 代码（src/）中，不用于插件沙箱（plugin sandbox）。
主要能力
库中提供 25 个无障碍组件，构建于 Base UI + Tailwind CSS + CVA 之上。可用组件包括：Button、Input、Label、Select、Slider、NumberInput、DualNumberInput、Checkbox、Toggle、RadioGroup、Tabs、Dialog、Dropdown、Tooltip、SegmentedControl、SearchBar、Toast、Spinner、Separator、Card、Grid、EmptyState、Badge、AIPromptInput、ThemeProvider。
其中 Dialog、Select、Dropdown、Tabs、Card、Tooltip、Toast、RadioGroup 为复合组件，需使用子组件组合方式。关于各组件的 props、变体与 API 细节，可阅读已安装包中的 TypeScript 类型，其中包含 JSDoc 注释、显式联合类型与默认值，路径为 node_modules/@lottiefiles/creator-plugins-ui/dist/components/*/。
使用方式
安装：
npm install @lottiefiles/creator-plugins-ui
在入口文件（src/main.tsx）中于本地样式之前引入样式：
import "@lottiefiles/creator-plugins-ui/styles.css";
组件与主题颜色工具类（bg-primary、text-foreground、border-border 等）只需 styles.css 即可工作，无需 Tailwind 配置。
若需要库之外的额外自定义 Tailwind 类，可配置 Tailwind v4：
npm install --save-dev tailwindcss @tailwindcss/vite
在 vite.config.ts 的 plugins 中加入 tailwindcss()，创建 src/styles.css 并写入 @import "tailwindcss"，使用 @theme {} 定义自定义颜色。不要创建 tailwind.config.js 或 postcss.config.js（v3 模式）。
引入模式示例：
import { Button, Input, Select, Slider, cn } from "@lottiefiles/creator-plugins-ui";
复合组件使用子组件组合，多态渲染使用 render prop（非 asChild，因为该库基于 Base UI 而非 Radix）：
<DialogRoot> <DialogTrigger render={<Button variant="outline" />}>Delete</DialogTrigger> <DialogContent> <DialogHeader> <DialogTitle>Delete Layer?</DialogTitle> <DialogDescription>This cannot be undone.</DialogDescription> </DialogHeader> <DialogFooter> <DialogClose render={<Button variant="outline" />}>Cancel</DialogClose> <Button variant="destructive" onClick={handleDelete}>Delete</Button> </DialogFooter> </DialogContent> </DialogRoot>
主题化
深色模式：在 <html> 上添加 class="dark"，即 document.documentElement.classList.add("dark")。
可通过 ThemeProvider 进行运行时覆盖：
<ThemeProvider tokens={{ "--primary": "hsl(260 80% 55%)" }} themeName="custom"> <App /> </ThemeProvider>
关键 CSS 变量包括：--background、--foreground、--primary、--secondary、--destructive、--muted-foreground、--border、--ring。
cn() 工具函数：应使用库提供的 cn()（而非本地 clsx），它包含针对主题颜色与字体大小的自定义 Tailwind merge 配置：
import { cn } from "@lottiefiles/creator-plugins-ui"; <div className={cn("p-4 text-foreground", isActive && "bg-primary")} />
常见问题与限制
缺少 styles.css 引入会导致组件无样式，需在入口文件引入一次 @lottiefiles/creator-plugins-ui/styles.css。使用 Tailwind v3 配置搭配 v4 是错误的，不要创建 tailwind.config.js 或 postcss.config.js；Tailwind v4 使用 CSS 中的 @import "tailwindcss" + @theme {} 与 Vite 集成用的 @tailwindcss/vite。使用 asChild 而非 render 也会出错，Base UI 使用 render={<a href="/" />}，而非 Radix 的 asChild 加 Slot。Select 的空字符串值："" 被保留表示"未选择"，应使用 "none" 或类似值。NumberInput 仅支持受控模式，需要 value 与 onChange，没有非受控模式。Slider 的值始终是数组，应传 [50] 而非 50，回调也返回数组。Toast 需要 provider，useToast() 在 <ToastProvider> 之外会抛错，需包裹应用根节点。深色模式的 dark 类应放在 <html> 或父级上，而非组件上。cn 引入错误：应使用 @lottiefiles/creator-plugins-ui 中的 cn，而非本地 clsx。
从自定义组件迁移
可将 @stitches/react 样式组件替换为库组件加 Tailwind 类；将 @radix-ui/* 引入替换为库组件；将 asChild 替换为 render prop；将 data-[state=checked] 替换为 data-[checked]、data-[state=open] 替换为 data-[open] 等；将内联颜色替换为 CSS 变量类（text-foreground、bg-primary）；将自定义 cn()/clsx() 替换为库的 cn()。
参考文档
references/setup-guide.md 涵盖安装、Tailwind 配置、从 Stitches/Radix 迁移与故障排查。 references/theming-guide.md 涵盖 CSS 变量、深色模式、ThemeProvider 与自定义颜色。