npm package: @nudgelabs/design-theme
Description: Shared shadcn/ui theme CSS variables for Tailwind v4
Latest version: 0.2.0

# @nudgelabs/design-theme

A shared shadcn/ui theme package for **Tailwind CSS v4** that provides CSS variables and `@theme inline` configuration for consistent theming across projects.

## What's Included

- **CSS Variables** - Complete shadcn/ui color tokens in OKLCH format for light/dark modes
- **@theme inline** - Pre-configured Tailwind v4 theme mapping
- **Dark Mode Variant** - `@custom-variant dark` for class-based dark mode
- **Base Styles** - Border, background, and cursor defaults

## Installation

```bash
pnpm add @nudgelabs/design-theme tailwindcss@^4.0.0 tw-animate-css
```

## Usage

### Configure globals.css

In your `globals.css`, import Tailwind and the theme:

```css
@import "tailwindcss";
@import "tw-animate-css";
@import "@nudgelabs/design-theme/styles.css";
```

That's it! No `tailwind.config.ts` needed for theming - it's all CSS-based with Tailwind v4.

### Configure PostCSS

```js
// postcss.config.mjs
export default {
  plugins: {
    "@tailwindcss/postcss": {},
  },
};
```

### Enable Dark Mode

The theme uses the `class` strategy. Add the `dark` class to `<html>`:

```tsx
// Using next-themes
import { ThemeProvider } from "next-themes";

<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
  {children}
</ThemeProvider>
```

### Add shadcn/ui Components

```bash
npx shadcn@latest add button card input dialog
```

Components automatically use the theme variables.

## CSS Variables Reference

All colors use the **OKLCH** color format for better perceptual uniformity.

### Colors

| Variable | Description |
|----------|-------------|
| `--background` | Page background |
| `--foreground` | Default text color |
| `--card` / `--card-foreground` | Card colors |
| `--popover` / `--popover-foreground` | Popover colors |
| `--primary` / `--primary-foreground` | Primary brand color |
| `--secondary` / `--secondary-foreground` | Secondary color |
| `--muted` / `--muted-foreground` | Muted/subtle colors |
| `--accent` / `--accent-foreground` | Accent highlights |
| `--destructive` / `--destructive-foreground` | Error/danger states |
| `--border` | Border color |
| `--input` | Input border color |
| `--ring` | Focus ring color |
| `--chart-1..5` | Chart palette |
| `--sidebar-*` | Sidebar-specific colors |

### Other Variables

| Variable | Default |
|----------|---------|
| `--radius` | 0.625rem |

## Customizing

### Override Variables

Add custom values after importing the theme:

```css
@import "tailwindcss";
@import "tw-animate-css";
@import "@nudgelabs/design-theme/styles.css";

:root {
  --primary: oklch(0.6 0.2 250);
  --radius: 0.75rem;
}

.dark {
  --primary: oklch(0.7 0.2 250);
}
```

### Variables Only (No @theme inline)

If you need just the CSS variables without the Tailwind configuration:

```css
@import "tailwindcss";
@import "@nudgelabs/design-theme/theme.css";

/* Add your own @theme inline block */
@theme inline {
  --color-background: var(--background);
  /* ... */
}
```

## Exports

| Export | Description |
|--------|-------------|
| `@nudgelabs/design-theme/styles.css` | Full theme (variables + @theme inline) |
| `@nudgelabs/design-theme/theme.css` | Variables only |

## Key Differences from Tailwind v3

| Tailwind v3 | Tailwind v4 |
|-------------|-------------|
| `tailwind.config.ts` | `@theme inline` in CSS |
| `@tailwind base/components/utilities` | `@import "tailwindcss"` |
| `tailwindcss-animate` | `tw-animate-css` |
| HSL colors | OKLCH colors |
| `darkMode: ["class"]` | `@custom-variant dark` |

## License

MIT