creator-plugins-ui - SKILL.md Agent Skill

name: creator-plugins-ui description: | Use when building or modifying plugin UI with @lottiefiles/creator-plugins-ui. Applies when adding React components in src/, using Button/Select/Slider/Dialog/Toast/NumberInput or other library components, setting up Tailwind CSS theming or dark mode, using the cn() utility, troubleshooting Base UI data attributes or missing styles, or updating the plugin UI theme to match Creator's interface theme.

Creator Plugins UI Library

@lottiefiles/creator-plugins-ui — 25 accessible components built on Base UI + Tailwind CSS + CVA. Used in plugin UI code (src/) only, not the plugin sandbox.

Quick Setup

Full guide: references/setup-guide.md

pnpm add @lottiefiles/creator-plugins-ui

// src/main.tsx — import before local styles
import "@lottiefiles/creator-plugins-ui/styles.css";

Components and theme color utility classes (bg-primary, text-foreground, border-border, etc.) work with just styles.css — no Tailwind configuration needed.

If you need additional custom Tailwind classes beyond what the library provides, set up Tailwind v4:

pnpm add -D tailwindcss @tailwindcss/vite

Add tailwindcss() to vite.config.ts plugins, create src/styles.css with @import "tailwindcss", and use @theme {} for custom colors. Do not create tailwind.config.js or postcss.config.js (v3 patterns). See references/setup-guide.md for full instructions.

Import Pattern

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

Available Components

For props, variants, and API details, read the TypeScript types from the installed package — they include JSDoc comments, explicit union types, and default values:

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

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

Compound components (use sub-component composition): Dialog, Select, Dropdown, Tabs, Card, Tooltip, Toast, RadioGroup

Compound Component Pattern

Compound components (Dialog, Select, Dropdown, Tabs) use sub-component composition. Use render prop for polymorphic rendering (not asChild — this library uses Base UI, not 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>

Theming

Full guide: references/theming-guide.md

Dark mode: add class="dark" to <html> — document.documentElement.classList.add("dark").

Runtime overrides with ThemeProvider:

<ThemeProvider tokens={{ "--primary": "hsl(260 80% 55%)" }} themeName="custom">
  <App />
</ThemeProvider>

Key CSS variables: --background, --foreground, --primary, --secondary, --destructive, --muted-foreground, --border, --ring.

cn() Utility

Use cn() from the library (not a local clsx) — it includes custom Tailwind merge config for theme colors and font sizes:

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

Common Pitfalls

Missing styles.css import — Components render unstyled. Import @lottiefiles/creator-plugins-ui/styles.css once in entry file.
Using Tailwind v3 config with v4 — Do not create tailwind.config.js or postcss.config.js. Tailwind v4 uses @import "tailwindcss" + @theme {} in CSS and @tailwindcss/vite for Vite integration.
Using asChild instead of render — Base UI uses render={<a href="/" />}, not Radix's asChild + Slot.
Select empty string values — "" is reserved for "no selection". Use "none" or similar.
NumberInput is controlled only — Requires value + onChange. No uncontrolled mode.
Slider value is always an array — Pass [50] not 50. Callback returns array too.
Toast requires provider — useToast() throws outside <ToastProvider>. Wrap app root.
Dark mode class placement — dark class goes on <html> or parent, not on the component.
Wrong cn import — Use cn from @lottiefiles/creator-plugins-ui, not a local clsx.

Migration from Custom Components

Full before/after examples: references/setup-guide.md

Replace @stitches/react styled components with library components + Tailwind classes
Replace @radix-ui/* imports with library components
Replace asChild with render prop
Replace data-[state=checked] → data-[checked], data-[state=open] → data-[open], etc.
Replace inline colors with CSS variable classes (text-foreground, bg-primary)
Replace custom cn()/clsx() with library's cn()

Reference Guide

Reference	Contents
`references/setup-guide.md`	Installation, Tailwind config, migration from Stitches/Radix, troubleshooting
`references/theming-guide.md`	CSS variables, dark mode, ThemeProvider, custom colors