tailwind-shadcn

Files (9)

• SKILL.md
• evals.json · evals/
• cli-shadcn-solid.md · references/
• cli.md · references/
• cva.md · references/
• formatting.md · references/
• primitives-solid.md · references/
• responsive.md · references/
• theming.md · references/

SKILL.md (first lines)

# Tailwind + shadcn/ui

Apply these patterns whether you're building new UI from scratch or refactoring existing code — the rules are the same either way.

## Detect framework first

This skill serves two ecosystems. Before doing anything, read `package.json` to detect which one you're in:

- **`react` / `react-dom` present → React mode.** Primitive layer is **Base UI**; the CLI is the official **`npx shadcn@latest`**. Gather project context by running:
  ```json
  npx shadcn@latest info --json
  ```
  Key fields: `tailwindVersion` (v4 uses `@theme inline`; v3 uses `tailwind.config.js`), `tailwindCssFile` (always edit this file for CSS variables — never create a new one), `aliases` (use the actual alias prefix for imports, never hardcode), `base` (the primitive layer).
- **`solid-js` present → Solid mode.** Primitive layer is **Kobalte** (Zaidan components); the CLI is **`npx shadcn-solid@latest`** (much thinner — no `info`/`search`/`docs`). Gather project context by reading `ui.config.json` + `package.json`. See [references/cli-shadcn-solid.md](./references/cli-shadcn-solid.md) and [references/primitives-solid.md](./references/primitives-solid.md).

## Framework mode

| Concern               | React mode                                                         | Solid mode                                                                                         |
| --------------------- | ------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------- |
| Primitive layer       | Base UI — see "Primitive layer APIs" below                         | Kobalte (Zaidan) — see [references/primitives-solid.md](./references/primitives-solid.md)          |
| CLI                   | `npx shadcn@latest` — see [references/cli.md](./references/cli.md) | `npx shadcn-solid@latest` — see [references/cli-shadcn-solid.md](./references/cli-shadcn-solid.md) |
| JSX class attribute   | `className`                                                        | `class`                                                                                            |
| Component composition | `asChild` + `Slot`                                                 | `<Dynamic>` / Kobalte polymorphic `as`                                                             |
| Lists                 | `.map(... key={})`                                                 | `<For each>` / `<Index>`                                                                           |

**Normalization note (Solid mode):** the styling discipline below and the shared references (`theming.md`, `responsive.md`, `cva.md`) use React (`className`) syntax in their examples. In Solid mode, **read every `className` as `class`**, read `.map(...)`+`key` as `<For each>`, and ignore React-only constructs (`React.*` types, `asChild`, `Slot`). See [references/primitives-solid.md](./references/primitives-solid.md) for the Solid equivalents. The Tailwind/token discipline itself is identical in both modes.

---

## Principles

1. **Reusability first — exhaust existing options before writing any inline/custom component.** Work down this ladder in order:
   1. **Search what the project already has.** Scan the UI components directory (`resolvedPaths.ui` in React mode; the components dir in Solid mode) for an existing component that fits.
   2. **Extend what exists.** If an existing component nearly fits and it makes semantic sense, reuse it. Add a new `cva` variant **only when the styling will be reused in more than one place** — for a one-off, prefer composition or a `className` override. Don't reach for a variant by default; overusing `cva` adds complexity. See [references/cva.md](./references/cva.md).
   3. **Bring in an available component.** Check the registry before writing custom UI — `npx shadcn@latest search` (React); browse the shadcn-solid catalog (Solid, no `search`). Check community registries too.
   4. **Only then write custom code**, and consult the component docs first (`npx shadcn@latest docs <component>` in React mode) for the recommended reusable pattern.
2. **Compose, don't reinvent.** Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. **Use built-in variants before custom styles.** `variant="outline"`, `size="sm"`, etc.
4. **Use semantic colors.** `bg-primary`, `text-muted-foreground` — never raw values like `bg-blue-500`.

---

## Critical Rules

These rules are always enforced.

### Colors

- **Never** use raw Tailwind palette values (`text-blue-500`, `bg-emerald-600`) in application code.
- **Never** hardcode hex/rgb/oklch values inline in className strings.
- **Use semantic tokens** for all color decisions: `bg-primary`, `text-destructive`, `border-border`.
- For status indicators with no matching token, use `Badge` variants first. If a reusable semantic token is needed (e.g. `--success`), add it to the theme.

### Spacing & layout

- **No `space-x-*` or `space-y-*`.** Use `flex` + `gap-*` instead. `space-y-4` → `flex flex-col gap-4`.
- **`size-*` when width = height.** `size-10` not `w-10 h-10`.
- **`truncate`** not `overflow-hidden text-ellipsis whitespace-nowrap`.

### Component styling

- **`className` is for layout, not overrides.** Acceptable: `max-w-md mx-auto mt-4`. Not acceptable: `bg-blue-100 text-blue-900 font-bold`.
- **Built-in variants first.** Exhaust `variant="outline"`, `variant="destructive"`, `size="sm"` before adding new ones.
- **Add a new variant sparingly** — only when a styling pattern repeats (used in more than one place) and no built-in fits. Edit the component source using `cva`. Not every component needs variants; a one-off doesn't warrant one. See [references/cva.md](./references/cva.md).

### Class merging

- **`cn()` for all conditional or merged classes.** No `${isActive ? 'bg-primary' : 'bg-muted'}` in className.
- **No manual `z-index`** on overlay components (Dialog, Sheet, Popover, Tooltip, Drawer). They manage their own stacking.
- **No manual `dark:` overrides.** Semantic tokens handle theme switching via CSS variables.

---

## CSS Architecture

### Variables at `:root`

All color tokens are CSS custom properties on `:root` in the global CSS file (`tailwindCssFile` from project context). Never scatter variable definitions across component files.

```css
:root {
  --background: oklch(1 0 0);
  --foreground: oklch(0.145 0 0);
  --primary: oklch(0.205 0 0);
  --primary-foreground: oklch(0.985 0 0);
  --muted: oklch(0.97 0 0);
  --muted-foreground: oklch(0.556 0 0);
  /* ... see references/theming.md for the full token set */
}
```

**OKLCH:** `oklch(lightness chroma hue)` — perceptually uniform, so equal chroma values look equally saturated across hues. Prefer it over HSL.

### Map variables to Tailwind

With **Tailwind v4**, register every CSS variable via `@theme inline`:

```css
@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --color-primary: var(--primary);
  --color-primary-foreground: var(--primary-foreground);
  /* ... see references/theming.md for the full mapping */
  --radius-sm: calc(var(--radius) - 4px);
  --radius-md: calc(var(--radius) - 2px);
  --radius-lg: var(--radius);
  --radius-xl: calc(var(--radius) + 4px);
}
```

### Apply base styles

```css
@layer base {
  * {
    @apply border-border;
  }
  body {

From O-Marsters-1997/my-claude-code, MIT.

More from O-Marsters-1997/my-claude-code