creator-plugins-ui

Creator Plugins UI Library

@lottiefiles/creator-plugins-ui — 基于 Base UI + Tailwind CSS + CVA 构建的 25 个无障碍组件。仅用于插件 UI 代码（src/），不用于插件沙盒。

快速设置

完整指南：references/setup-guide.md

npm install @lottiefiles/creator-plugins-ui

// src/main.tsx — import before local styles
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 插件中添加 tailwindcss()，创建 src/styles.css 并加入 @import "tailwindcss"，再使用 @theme {} 设置自定义颜色。不要创建 tailwind.config.js 或 postcss.config.js（v3 的配置方式）。完整说明请参阅 references/setup-guide.md。

导入方式

import { Button, Input, Select, Slider, cn } from "@lottiefiles/creator-plugins-ui";

可用组件

有关属性、变体和 API 的详细信息，请阅读已安装包中的 TypeScript 类型——其中包含 JSDoc 注释、明确的联合类型和默认值：

node_modules/@lottiefiles/creator-plugins-ui/dist/components/*/

组件： 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

复合组件模式

复合组件（Dialog、Select、Dropdown、Tabs）使用子组件组合。使用 render 属性进行多态渲染（不要使用 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>

主题设置

完整指南：references/theming-guide.md

深色模式：为 <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 合并配置：

import { cn } from "@lottiefiles/creator-plugins-ui";
<div className={cn("p-4 text-foreground", isActive && "bg-primary")} />

常见问题

1. 未导入 styles.css — 组件将不会应用样式。在入口文件中导入一次 @lottiefiles/creator-plugins-ui/styles.css。
2. 在 Tailwind v4 中使用 Tailwind v3 配置 — 不要创建 tailwind.config.js 或 postcss.config.js。Tailwind v4 在 CSS 中使用 @import "tailwindcss" + @theme {}，并使用 @tailwindcss/vite 集成 Vite。
3. 使用 asChild 而不是 render — Base UI 使用 render={<a href="/" />}，而不是 Radix 的 asChild + Slot。
4. Select 的空字符串值 — "" 专用于表示“未选择”。请使用 "none" 或类似值。
5. NumberInput 只能受控 — 必须提供 value + onChange。不支持非受控模式。
6. Slider 的值始终是数组 — 传入 [50]，而不是 50。回调也会返回数组。
7. Toast 需要 Provider — 在 <ToastProvider> 外调用 useToast() 会抛出异常。请包装应用根节点。
8. 深色模式类的位置 — dark 类应添加到 <html> 或其父元素上，而不是组件上。
9. cn 导入错误 — 请使用来自 @lottiefiles/creator-plugins-ui 的 cn，而不是本地的 clsx。

从自定义组件迁移

完整的迁移前后示例：references/setup-guide.md

1. 将 @stitches/react 样式化组件替换为库组件 + Tailwind 类
2. 将 @radix-ui/* 导入替换为库组件
3. 将 asChild 替换为 render 属性
4. 将 data-[state=checked] → data-[checked]、data-[state=open] → data-[open] 等
5. 将内联颜色替换为 CSS 变量类（text-foreground、bg-primary）
6. 将自定义 cn()/clsx() 替换为库的 cn()

参考指南

参考资料	内容
references/setup-guide.md	安装、Tailwind 配置、从 Stitches/Radix 迁移、故障排查
references/theming-guide.md	CSS 变量、深色模式、ThemeProvider、自定义颜色