zhongwei/gh-jezweb-claude-skills-skills-tailwind-v4-shadcn
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:25:32 +08:00
commit 6c7fa6696d
14 changed files with 2262 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

12
.claude-plugin/plugin.json Normal file
View File

@@ -0,0 +1,12 @@
{
"name": "tailwind-v4-shadcn",
"description": "Set up Tailwind v4 with shadcn/ui using @theme inline pattern and CSS variable architecture. Four-step mandatory pattern: define CSS variables at root, map to Tailwind utilities, apply base styles, get automatic dark mode. Use when: initializing React projects with Tailwind v4, setting up shadcn/ui dark mode, or fixing colors not working, theme not applying, CSS variables broken, tw-animate-css errors, or migrating from v3.",
"version": "1.0.0",
"author": {
"name": "Jeremy Dawes",
"email": "jeremy@jezweb.net"
},
"skills": [
"./"
]
}

3
README.md Normal file
View File

@@ -0,0 +1,3 @@
# tailwind-v4-shadcn
Set up Tailwind v4 with shadcn/ui using @theme inline pattern and CSS variable architecture. Four-step mandatory pattern: define CSS variables at root, map to Tailwind utilities, apply base styles, get automatic dark mode. Use when: initializing React projects with Tailwind v4, setting up shadcn/ui dark mode, or fixing colors not working, theme not applying, CSS variables broken, tw-animate-css errors, or migrating from v3.

629
SKILL.md Normal file
View File

@@ -0,0 +1,629 @@
---
name: tailwind-v4-shadcn
description: |
Set up Tailwind v4 with shadcn/ui using @theme inline pattern and CSS variable architecture. Four-step mandatory pattern: define CSS variables at root, map to Tailwind utilities, apply base styles, get automatic dark mode.
Use when: initializing React projects with Tailwind v4, setting up shadcn/ui dark mode, or fixing colors not working, theme not applying, CSS variables broken, tw-animate-css errors, or migrating from v3.
license: MIT
---
# Tailwind v4 + shadcn/ui Production Stack
**Production-tested**: WordPress Auditor (https://wordpress-auditor.webfonts.workers.dev)
**Last Updated**: 2025-11-09
**Status**: Production Ready ✅
---
## ⚠️ BEFORE YOU START (READ THIS!)
**CRITICAL FOR AI AGENTS**: If you're Claude Code helping a user set up Tailwind v4:
1. **Explicitly state you're using this skill** at the start of the conversation
2. **Reference patterns from the skill** rather than general knowledge
3. **Prevent known issues** listed in `reference/common-gotchas.md`
4. **Don't guess** - if unsure, check the skill documentation
**USER ACTION REQUIRED**: Tell Claude to check this skill first!
Say: **"I'm setting up Tailwind v4 + shadcn/ui - check the tailwind-v4-shadcn skill first"**
### Why This Matters (Real-World Results)
**Without skill activation:**
- ❌ Setup time: ~5 minutes
- ❌ Errors encountered: 2-3 (tw-animate-css, duplicate @layer base)
- ❌ Manual fixes needed: 2+ commits
- ❌ Token usage: ~65k
- ❌ User confidence: Required debugging
**With skill activation:**
- ✅ Setup time: ~1 minute
- ✅ Errors encountered: 0
- ✅ Manual fixes needed: 0
- ✅ Token usage: ~20k (70% reduction)
- ✅ User confidence: Instant success
### Known Issues This Skill Prevents
1. **tw-animate-css import error** (deprecated in v4)
2. **Duplicate @layer base blocks** (shadcn init adds its own)
3. **Wrong template selection** (vanilla TS vs React)
4. **Missing post-init cleanup** (incompatible CSS rules)
5. **Wrong plugin syntax** (using @import or require() instead of @plugin directive)
All of these are handled automatically when the skill is active.
---
## Quick Start (5 Minutes - Follow This Exact Order)
### 1. Install Dependencies
```bash
pnpm add tailwindcss @tailwindcss/vite
pnpm add -D @types/node
pnpm dlx shadcn@latest init
```
### 2. Configure Vite
```typescript
// vite.config.ts
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'
export default defineConfig({
plugins: [react(), tailwindcss()],
resolve: {
alias: {
'@': path.resolve(__dirname, './src')
}
}
})
```
### 3. Update components.json
```json
{
"tailwind": {
"config": "", // ← CRITICAL: Empty for v4
"css": "src/index.css",
"baseColor": "slate", // Base color palette
"cssVariables": true,
"prefix": "" // No prefix for utility classes
}
}
```
### 4. Delete tailwind.config.ts
```bash
rm tailwind.config.ts # v4 doesn't use this file
```
---
## The Four-Step Architecture (CRITICAL)
This pattern is **mandatory** - skipping steps will break your theme.
### Step 1: Define CSS Variables at Root Level
```css
/* src/index.css */
@import "tailwindcss";
:root {
--background: hsl(0 0% 100%); /* ← hsl() wrapper required */
--foreground: hsl(222.2 84% 4.9%);
--primary: hsl(221.2 83.2% 53.3%);
/* ... all light mode colors */
}
.dark {
--background: hsl(222.2 84% 4.9%);
--foreground: hsl(210 40% 98%);
--primary: hsl(217.2 91.2% 59.8%);
/* ... all dark mode colors */
}
```
**Critical Rules:**
- ✅ Define at root level (NOT inside `@layer base`)
- ✅ Use `hsl()` wrapper on all color values
- ✅ Use `.dark` for dark mode (NOT `.dark { @theme { } }`)
### Step 2: Map Variables to Tailwind Utilities
```css
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-primary: var(--primary);
/* ... map ALL CSS variables */
}
```
**Why This Is Required:**
- Generates utility classes (`bg-background`, `text-primary`)
- Without this, `bg-primary` etc. won't exist
### Step 3: Apply Base Styles
```css
@layer base {
body {
background-color: var(--background); /* NO hsl() here */
color: var(--foreground);
}
}
```
**Critical Rules:**
- ✅ Reference variables directly: `var(--background)`
- ❌ Never double-wrap: `hsl(var(--background))`
### Step 4: Result - Automatic Dark Mode
```tsx
<div className="bg-background text-foreground">
{/* No dark: variants needed - theme switches automatically */}
</div>
```
---
## Dark Mode Setup
### 1. Create ThemeProvider
See `reference/dark-mode.md` for full implementation or use template:
```typescript
// Copy from: templates/theme-provider.tsx
```
### 2. Wrap Your App
```typescript
// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
<App />
</ThemeProvider>
</React.StrictMode>,
)
```
### 3. Add Theme Toggle
```bash
pnpm dlx shadcn@latest add dropdown-menu
```
See `reference/dark-mode.md` for ModeToggle component code.
---
## Critical Rules (MUST FOLLOW)
### ✅ Always Do:
1. **Wrap color values with `hsl()` in `:root` and `.dark`**
```css
--background: hsl(0 0% 100%); /* ✅ Correct */
```
2. **Use `@theme inline` to map all CSS variables**
```css
@theme inline {
--color-background: var(--background);
}
```
3. **Set `"tailwind.config": ""` in components.json**
```json
{ "tailwind": { "config": "" } }
```
4. **Delete `tailwind.config.ts` if it exists**
5. **Use `@tailwindcss/vite` plugin (NOT PostCSS)**
6. **Use `cn()` for conditional classes**
```typescript
import { cn } from "@/lib/utils"
<div className={cn("base", isActive && "active")} />
```
### ❌ Never Do:
1. **Put `:root` or `.dark` inside `@layer base`**
```css
/* WRONG */
@layer base {
:root { --background: hsl(...); }
}
```
2. **Use `.dark { @theme { } }` pattern**
```css
/* WRONG - v4 doesn't support nested @theme */
.dark {
@theme {
--color-primary: hsl(...);
}
}
```
3. **Double-wrap colors**
```css
/* WRONG */
body {
background-color: hsl(var(--background));
}
```
4. **Use `tailwind.config.ts` for theme colors**
```typescript
/* WRONG - v4 ignores this */
export default {
theme: {
extend: {
colors: { primary: 'hsl(var(--primary))' }
}
}
}
```
5. **Use `@apply` directive (deprecated in v4)**
6. **Use `dark:` variants for semantic colors**
```tsx
/* WRONG */
<div className="bg-primary dark:bg-primary-dark" />
/* CORRECT */
<div className="bg-primary" />
```
---
## Semantic Color Tokens
Always use semantic names for colors:
```css
:root {
--destructive: hsl(0 84.2% 60.2%); /* Red - errors, critical */
--success: hsl(142.1 76.2% 36.3%); /* Green - success states */
--warning: hsl(38 92% 50%); /* Yellow - warnings */
--info: hsl(221.2 83.2% 53.3%); /* Blue - info, primary */
}
```
**Usage:**
```tsx
<div className="bg-destructive text-destructive-foreground">Critical</div>
<div className="bg-success text-success-foreground">Success</div>
<div className="bg-warning text-warning-foreground">Warning</div>
<div className="bg-info text-info-foreground">Info</div>
```
---
## Common Issues & Quick Fixes
| Symptom | Cause | Fix |
|---------|-------|-----|
| `bg-primary` doesn't work | Missing `@theme inline` mapping | Add `@theme inline` block |
| Colors all black/white | Double `hsl()` wrapping | Use `var(--color)` not `hsl(var(--color))` |
| Dark mode not switching | Missing ThemeProvider | Wrap app in `<ThemeProvider>` |
| Build fails | `tailwind.config.ts` exists | Delete the file |
| Text invisible | Wrong contrast colors | Check color definitions in `:root`/`.dark` |
See `reference/common-gotchas.md` for complete troubleshooting guide.
---
## File Templates
All templates are available in the `templates/` directory:
- **index.css** - Complete CSS setup with all color variables
- **components.json** - shadcn/ui v4 configuration
- **vite.config.ts** - Vite + Tailwind plugin setup
- **tsconfig.app.json** - TypeScript with path aliases
- **theme-provider.tsx** - Dark mode provider with localStorage
- **utils.ts** - `cn()` utility for class merging
Copy these files to your project and customize as needed.
---
## Complete Setup Checklist
- [ ] Vite + React + TypeScript project created
- [ ] `@tailwindcss/vite` installed (NOT postcss)
- [ ] `vite.config.ts` uses `tailwindcss()` plugin
- [ ] `tsconfig.json` has path aliases configured
- [ ] `components.json` exists with `"config": ""`
- [ ] NO `tailwind.config.ts` file exists
- [ ] `src/index.css` follows v4 pattern:
- [ ] `:root` and `.dark` at root level (not in @layer)
- [ ] Colors wrapped with `hsl()`
- [ ] `@theme inline` maps all variables
- [ ] `@layer base` uses unwrapped variables
- [ ] Theme provider installed and wrapping app
- [ ] Dark mode toggle component created
- [ ] Test theme switching works in browser
---
## Advanced Topics
### Custom Colors
Add new semantic colors:
```css
:root {
--brand: hsl(280 65% 60%);
--brand-foreground: hsl(0 0% 100%);
}
.dark {
--brand: hsl(280 75% 70%);
--brand-foreground: hsl(280 20% 10%);
}
@theme inline {
--color-brand: var(--brand);
--color-brand-foreground: var(--brand-foreground);
}
```
Usage: `<div className="bg-brand text-brand-foreground">Branded</div>`
### Migration from v3
See `reference/migration-guide.md` for complete v3 → v4 migration steps.
### Component Best Practices
1. **Always use semantic tokens**
```tsx
<Button variant="destructive">Delete</Button> /* ✅ */
<Button className="bg-red-600">Delete</Button> /* ❌ */
```
2. **Use `cn()` for conditional styling**
```tsx
import { cn } from "@/lib/utils"
<div className={cn(
"base-class",
isActive && "active-class",
hasError && "error-class"
)} />
```
3. **Compose shadcn/ui components**
```tsx
<Dialog>
<DialogTrigger asChild>
<Button>Open</Button>
</DialogTrigger>
<DialogContent>
<DialogHeader>
<DialogTitle>Title</DialogTitle>
</DialogHeader>
</DialogContent>
</Dialog>
```
---
## Dependencies
### ✅ Install These
```json
{
"dependencies": {
"tailwindcss": "^4.1.17",
"@tailwindcss/vite": "^4.1.17",
"clsx": "^2.1.1",
"tailwind-merge": "^3.3.1",
"@radix-ui/react-*": "latest",
"lucide-react": "^0.553.0",
"react": "^19.2.0",
"react-dom": "^19.2.0"
},
"devDependencies": {
"@types/node": "^24.10.0",
"@vitejs/plugin-react": "^5.1.0",
"vite": "^7.2.2",
"typescript": "~5.9.0",
"tw-animate-css": "^1.4.0"
}
}
```
### Animation Packages (Updated Nov 2025)
shadcn/ui has deprecated `tailwindcss-animate` in favor of `tw-animate-css` for Tailwind v4 compatibility.
**✅ DO Install (v4-compatible)**:
```bash
pnpm add -D tw-animate-css
```
Then add to `src/index.css`:
```css
@import "tailwindcss";
@import "tw-animate-css";
```
**❌ DO NOT Install**:
```bash
npm install tailwindcss-animate # Deprecated - v3 only
```
**Why**: `tw-animate-css` is the official v4-compatible replacement for animations, required by shadcn/ui components.
**Reference**: https://ui.shadcn.com/docs/tailwind-v4
---
## Tailwind v4 Plugins
Tailwind v4 supports official plugins using the `@plugin` directive in CSS.
### Official Plugins (Tailwind Labs)
#### Typography Plugin - Style Markdown/CMS Content
**When to use:** Displaying blog posts, documentation, or any HTML from Markdown/CMS.
**Installation:**
```bash
pnpm add -D @tailwindcss/typography
```
**Configuration (v4 syntax):**
```css
/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
```
**Usage:**
```html
<article class="prose lg:prose-xl dark:prose-invert">
{{ markdown_content }}
</article>
```
**Available classes:**
- `prose` - Base typography styles
- `prose-sm`, `prose-base`, `prose-lg`, `prose-xl`, `prose-2xl` - Size variants
- `dark:prose-invert` - Dark mode styles
---
#### Forms Plugin - Reset Form Element Styles
**When to use:** Building custom forms without shadcn/ui components, or need consistent cross-browser form styling.
**Installation:**
```bash
pnpm add -D @tailwindcss/forms
```
**Configuration (v4 syntax):**
```css
/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/forms";
```
**What it does:**
- Resets browser default form styles
- Makes form elements styleable with Tailwind utilities
- Fixes cross-browser inconsistencies for inputs, selects, checkboxes, radios
**Note:** Less critical for shadcn/ui users (they have pre-styled form components), but still useful for basic forms.
---
### Common Plugin Errors
These errors happen when using v3 syntax in v4 projects:
**❌ WRONG (v3 config file syntax):**
```js
// tailwind.config.js
module.exports = {
plugins: [require('@tailwindcss/typography')]
}
```
**❌ WRONG (@import instead of @plugin):**
```css
@import "@tailwindcss/typography"; /* Doesn't work */
```
**✅ CORRECT (v4 @plugin directive):**
```css
/* src/index.css */
@import "tailwindcss";
@plugin "@tailwindcss/typography";
@plugin "@tailwindcss/forms";
```
---
### Built-in Features (No Plugin Needed)
**Container queries** are built into Tailwind v4 core - no plugin needed:
```tsx
<div className="@container">
<div className="@md:text-lg">
Responds to container width, not viewport
</div>
</div>
```
**❌ Don't install:** `@tailwindcss/container-queries` (deprecated, now core feature)
---
## Reference Documentation
For deeper understanding, see:
- **architecture.md** - Deep dive into the 4-step pattern
- **dark-mode.md** - Complete dark mode implementation
- **common-gotchas.md** - All the ways it can break (and fixes)
- **migration-guide.md** - Migrating hardcoded colors to CSS variables
---
## Official Documentation
- **shadcn/ui Vite Setup**: https://ui.shadcn.com/docs/installation/vite
- **shadcn/ui Tailwind v4 Guide**: https://ui.shadcn.com/docs/tailwind-v4
- **shadcn/ui Dark Mode (Vite)**: https://ui.shadcn.com/docs/dark-mode/vite
- **Tailwind v4 Docs**: https://tailwindcss.com/docs
- **shadcn/ui Theming**: https://ui.shadcn.com/docs/theming
---
## Production Example
This skill is based on the WordPress Auditor project:
- **Live**: https://wordpress-auditor.webfonts.workers.dev
- **Stack**: Vite + React 19 + Tailwind v4 + shadcn/ui + Cloudflare Workers
- **Dark Mode**: Full system/light/dark support
- **Version**: Tailwind v4.1.14 + shadcn/ui latest (Oct 2025)
All patterns in this skill have been validated in production.
---
**Questions? Issues?**
1. Check `reference/common-gotchas.md` first
2. Verify all steps in the 4-step architecture
3. Ensure `components.json` has `"config": ""`
4. Delete `tailwind.config.ts` if it exists
5. Check official docs: https://ui.shadcn.com/docs/tailwind-v4

85
plugin.lock.json Normal file
View File

@@ -0,0 +1,85 @@
{
"$schema": "internal://schemas/plugin.lock.v1.json",
"pluginId": "gh:jezweb/claude-skills:skills/tailwind-v4-shadcn",
"normalized": {
"repo": null,
"ref": "refs/tags/v20251128.0",
"commit": "3a4ea8133386093e3aaeb81830b149674e1a8e83",
"treeHash": "a5dcad101e5c0e16d791c9cb2c005ba605f50d0d86217e272252a3026fd47616",
"generatedAt": "2025-11-28T10:18:58.994843Z",
"toolVersion": "publish_plugins.py@0.2.0"
},
"origin": {
"remote": "git@github.com:zhongweili/42plugin-data.git",
"branch": "master",
"commit": "aa1497ed0949fd50e99e70d6324a29c5b34f9390",
"repoRoot": "/Users/zhongweili/projects/openmind/42plugin-data"
},
"manifest": {
"name": "tailwind-v4-shadcn",
"description": "Set up Tailwind v4 with shadcn/ui using @theme inline pattern and CSS variable architecture. Four-step mandatory pattern: define CSS variables at root, map to Tailwind utilities, apply base styles, get automatic dark mode. Use when: initializing React projects with Tailwind v4, setting up shadcn/ui dark mode, or fixing colors not working, theme not applying, CSS variables broken, tw-animate-css errors, or migrating from v3.",
"version": "1.0.0"
},
"content": {
"files": [
{
"path": "README.md",
"sha256": "d8a327f4da5d3c0bc4fb7d3ff4e45cb9398833619dee5bac7cf6c9be72ccaa30"
},
{
"path": "SKILL.md",
"sha256": "5cdeded8fc9ab0f6634b1c9a2656ba45f4045efef87d3979447129dc97221b65"
},
{
"path": "references/architecture.md",
"sha256": "da2f6f3eeb32717728159c6133c6e9ebe83815ae41371a83a8a38eeff461f344"
},
{
"path": "references/migration-guide.md",
"sha256": "4580c5c918d71e3ac518d236a035bd627a5e99b254bb93f05eed67fc5ae53b42"
},
{
"path": "references/dark-mode.md",
"sha256": "3392626694dcf970bdadd4537b425de5825fc0a2a8725474110f246528c87e34"
},
{
"path": "references/common-gotchas.md",
"sha256": "b42d35ce713ae2f7ff0a77072cbbb70f89428f01b8e0ac77ee325368841fb835"
},
{
"path": ".claude-plugin/plugin.json",
"sha256": "94ab042d7431b148cfd14aaed3b60839c319599f9611cc0adb350283f0062aa8"
},
{
"path": "templates/theme-provider.tsx",
"sha256": "df87540b95499b272216c7b41a5d133bf0a449eb25049128f8a032ccd0e65580"
},
{
"path": "templates/tsconfig.app.json",
"sha256": "8d20a8ea391818bebc7436709dd00e3e5422db9f811868127f1584efe8ff3047"
},
{
"path": "templates/utils.ts",
"sha256": "51bbf14cd1f84f49aab2e0dbee420137015d56b6677bb439e83a908cd292cce1"
},
{
"path": "templates/index.css",
"sha256": "3bb8a7a2daf4a9507f8c27deeb626b0d51166d018f7aa0d1d656dd8f652a527a"
},
{
"path": "templates/components.json",
"sha256": "38d09e0be58f15412e01057114a5d9d4b3582200378441a3c74fd490c37b9a4b"
},
{
"path": "templates/vite.config.ts",
"sha256": "37171894fd3d8b7709d1ea15c4db5f4ba0faa1b58d7c7418d11ce4e30eb5562d"
}
],
"dirSha256": "a5dcad101e5c0e16d791c9cb2c005ba605f50d0d86217e272252a3026fd47616"
},
"security": {
"scannedAt": null,
"scannerVersion": null,
"flags": []
}
}

206
references/architecture.md Normal file
View File

@@ -0,0 +1,206 @@
# Tailwind v4 + shadcn/ui Theming Architecture
## The Four-Step Pattern
Tailwind v4 requires a specific architecture for CSS variable-based theming. This pattern is **mandatory** - skipping or modifying steps will break your theme.
### Step 1: Define CSS Variables at Root Level
```css
:root {
--background: hsl(0 0% 100%);
--foreground: hsl(222.2 84% 4.9%);
/* ... more colors */
}
.dark {
--background: hsl(222.2 84% 4.9%);
--foreground: hsl(210 40% 98%);
/* ... dark mode colors */
}
```
**Critical Rules:**
- ✅ Define at root level (NOT inside `@layer base`)
- ✅ Use `hsl()` wrapper on all color values
- ✅ Use `.dark` for dark mode overrides (NOT `.dark { @theme { } }`)
- ❌ Never put `:root` or `.dark` inside `@layer base`
### Step 2: Map Variables to Tailwind Utilities
```css
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
/* ... map all CSS variables */
}
```
**Why This Is Required:**
- Tailwind v4 doesn't read `tailwind.config.ts` for colors
- `@theme inline` generates utility classes (`bg-background`, `text-foreground`)
- Without this, utilities like `bg-primary` won't exist
### Step 3: Apply Base Styles
```css
@layer base {
body {
background-color: var(--background); /* NO hsl() wrapper here */
color: var(--foreground);
}
}
```
**Critical Rules:**
- ✅ Reference variables directly: `var(--background)`
- ❌ Never double-wrap: `hsl(var(--background))` (already has hsl)
### Step 4: Result - Automatic Dark Mode
With this architecture:
- `<div className="bg-background text-foreground">` works automatically
- No `dark:` variants needed in components
- Theme switches via `.dark` class on `<html>`
- Single source of truth for all colors
---
## Why This Architecture Works
### Color Variable Flow
```
CSS Variable Definition → @theme inline Mapping → Tailwind Utility Class
--background → --color-background → bg-background
(with hsl() wrapper) (references variable) (generated class)
```
### Dark Mode Switching
```
ThemeProvider toggles `.dark` class on <html>
↓
CSS variables update automatically (.dark overrides)
↓
Tailwind utilities reference updated variables
↓
UI updates without re-render
```
---
## Common Mistakes
### ❌ Mistake 1: Variables Inside @layer base
```css
/* WRONG */
@layer base {
:root {
--background: hsl(0 0% 100%);
}
}
```
**Why It Fails:** Tailwind v4 strips CSS outside `@theme`/`@layer`, but `:root` must be at root level to persist.
### ❌ Mistake 2: Using .dark { @theme { } }
```css
/* WRONG */
@theme {
--color-primary: hsl(0 0% 0%);
}
.dark {
@theme {
--color-primary: hsl(0 0% 100%);
}
}
```
**Why It Fails:** Tailwind v4 doesn't support nested `@theme` directives.
### ❌ Mistake 3: Double hsl() Wrapping
```css
/* WRONG */
@layer base {
body {
background-color: hsl(var(--background));
}
}
```
**Why It Fails:** `--background` already contains `hsl()`, results in `hsl(hsl(...))`.
### ❌ Mistake 4: Config-Based Colors
```typescript
// WRONG (tailwind.config.ts)
export default {
theme: {
extend: {
colors: {
primary: 'hsl(var(--primary))'
}
}
}
}
```
**Why It Fails:** Tailwind v4 completely ignores `theme.extend.colors` in config files.
---
## Best Practices
### 1. Semantic Color Names
Use semantic names, not color values:
```css
--primary /* ✅ Semantic */
--blue-500 /* ❌ Not semantic */
```
### 2. Foreground Pairing
Every background color needs a foreground:
```css
--primary: hsl(...);
--primary-foreground: hsl(...);
```
### 3. WCAG Contrast Ratios
Ensure proper contrast:
- Normal text: 4.5:1 minimum
- Large text: 3:1 minimum
- UI components: 3:1 minimum
### 4. Chart Colors
Charts need separate variables (don't use hsl wrapper in components):
```css
:root {
--chart-1: hsl(12 76% 61%);
}
@theme inline {
--color-chart-1: var(--chart-1);
}
```
Use in components:
```tsx
<div style={{ backgroundColor: 'var(--chart-1)' }} />
```
---
## Official Documentation
- shadcn/ui Tailwind v4 Guide: https://ui.shadcn.com/docs/tailwind-v4
- Tailwind v4 Docs: https://tailwindcss.com/docs
- shadcn/ui Theming: https://ui.shadcn.com/docs/theming

469
references/common-gotchas.md Normal file
View File

@@ -0,0 +1,469 @@
# Common Gotchas & Solutions
## Critical Failures (Will Break Your Build)
### 1. `:root` Inside `@layer base`
❌ **WRONG:**
```css
@layer base {
:root {
--background: hsl(0 0% 100%);
}
}
```
✅ **CORRECT:**
```css
:root {
--background: hsl(0 0% 100%);
}
@layer base {
body {
background-color: var(--background);
}
}
```
**Why:** Tailwind v4 strips CSS outside `@theme`/`@layer`, but `:root` must be at root level.
---
### 2. Nested `@theme` Directive
❌ **WRONG:**
```css
@theme {
--color-primary: hsl(0 0% 0%);
}
.dark {
@theme {
--color-primary: hsl(0 0% 100%);
}
}
```
✅ **CORRECT:**
```css
:root {
--primary: hsl(0 0% 0%);
}
.dark {
--primary: hsl(0 0% 100%);
}
@theme inline {
--color-primary: var(--primary);
}
```
**Why:** Tailwind v4 doesn't support `@theme` inside selectors.
---
### 3. Double `hsl()` Wrapping
❌ **WRONG:**
```css
@layer base {
body {
background-color: hsl(var(--background));
}
}
```
✅ **CORRECT:**
```css
@layer base {
body {
background-color: var(--background); /* Already has hsl() */
}
}
```
**Why:** Variables already contain `hsl()`, double-wrapping creates `hsl(hsl(...))`.
---
### 4. Colors in `tailwind.config.ts`
❌ **WRONG:**
```typescript
// tailwind.config.ts
export default {
theme: {
extend: {
colors: {
primary: 'hsl(var(--primary))'
}
}
}
}
```
✅ **CORRECT:**
```typescript
// Delete tailwind.config.ts entirely OR leave it empty
export default {}
// components.json
{
"tailwind": {
"config": "" // ← Empty string
}
}
```
**Why:** Tailwind v4 completely ignores `theme.extend.colors`.
---
### 5. Missing `@theme inline` Mapping
❌ **WRONG:**
```css
:root {
--background: hsl(0 0% 100%);
}
/* No @theme inline block */
```
Result: `bg-background` class doesn't exist
✅ **CORRECT:**
```css
:root {
--background: hsl(0 0% 100%);
}
@theme inline {
--color-background: var(--background);
}
```
**Why:** `@theme inline` generates the utility classes.
---
## Configuration Gotchas
### 6. Wrong components.json Config
❌ **WRONG:**
```json
{
"tailwind": {
"config": "tailwind.config.ts" // ← No!
}
}
```
✅ **CORRECT:**
```json
{
"tailwind": {
"config": "" // ← Empty for v4
}
}
```
---
### 7. Using PostCSS Instead of Vite Plugin
❌ **WRONG:**
```typescript
// vite.config.ts
export default defineConfig({
css: {
postcss: './postcss.config.js' // Old v3 way
}
})
```
✅ **CORRECT:**
```typescript
import tailwindcss from '@tailwindcss/vite'
export default defineConfig({
plugins: [react(), tailwindcss()] // v4 way
})
```
---
### 8. Missing Path Aliases
❌ **WRONG:**
```typescript
// tsconfig.json has no paths
import { Button } from '../../components/ui/button'
```
✅ **CORRECT:**
```json
// tsconfig.app.json
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
}
}
}
```
```typescript
import { Button } from '@/components/ui/button'
```
---
## Color System Gotchas
### 9. Using `dark:` Variants for Semantic Colors
❌ **WRONG:**
```tsx
<div className="bg-primary dark:bg-primary-dark" />
```
✅ **CORRECT:**
```tsx
<div className="bg-primary" />
```
**Why:** With proper CSS variable setup, `bg-primary` automatically responds to theme.
---
### 10. Hardcoded Color Values
❌ **WRONG:**
```tsx
<div className="bg-blue-600 dark:bg-blue-400" />
```
✅ **CORRECT:**
```tsx
<div className="bg-primary" /> {/* Or bg-info, bg-success, etc. */}
```
**Why:** Semantic tokens enable theme switching and reduce repetition.
---
## Component Gotchas
### 11. Missing `cn()` Utility
❌ **WRONG:**
```tsx
<div className={`base ${isActive && 'active'}`} />
```
✅ **CORRECT:**
```tsx
import { cn } from '@/lib/utils'
<div className={cn("base", isActive && "active")} />
```
**Why:** `cn()` properly merges and deduplicates Tailwind classes.
---
### 12. Empty String in Radix Select
❌ **WRONG:**
```tsx
<SelectItem value="">Select an option</SelectItem>
```
✅ **CORRECT:**
```tsx
<SelectItem value="placeholder">Select an option</SelectItem>
```
**Why:** Radix UI Select doesn't allow empty string values.
---
## Installation Gotchas
### 13. Wrong Tailwind Package
❌ **WRONG:**
```bash
npm install tailwindcss@^3.4.0 # v3
```
✅ **CORRECT:**
```bash
npm install tailwindcss@^4.1.0 # v4
npm install @tailwindcss/vite
```
---
### 14. Missing Dependencies
❌ **WRONG:**
```json
{
"dependencies": {
"tailwindcss": "^4.1.0"
// Missing @tailwindcss/vite
}
}
```
✅ **CORRECT:**
```json
{
"dependencies": {
"tailwindcss": "^4.1.0",
"@tailwindcss/vite": "^4.1.0",
"clsx": "^2.1.1",
"tailwind-merge": "^3.3.1"
},
"devDependencies": {
"@types/node": "^24.0.0"
}
}
```
---
### 17. tw-animate-css Import Error (REAL-WORLD ISSUE)
❌ **WRONG:**
```bash
npm install tailwindcss-animate # Deprecated package
```
```css
@import "tw-animate-css"; # Package doesn't exist in v4
```
✅ **CORRECT:**
```bash
# Don't install tailwindcss-animate at all
# Use native CSS animations or @tailwindcss/motion
```
**Why:**
- `tailwindcss-animate` is deprecated in Tailwind v4
- Causes import errors during build
- shadcn/ui docs may still reference it (outdated)
- The skill handles animations differently in v4
**Impact:** Build failure, requires manual CSS file cleanup
---
### 18. Duplicate @layer base After shadcn init (REAL-WORLD ISSUE)
❌ **WRONG:**
```css
/* After running shadcn init, you might have: */
@layer base {
body {
background-color: var(--background);
}
}
@layer base { /* ← Duplicate added by shadcn init */
* {
border-color: hsl(var(--border));
}
}
```
✅ **CORRECT:**
```css
/* Merge into single @layer base block */
@layer base {
* {
border-color: var(--border);
}
body {
background-color: var(--background);
color: var(--foreground);
}
}
```
**Why:**
- `shadcn init` adds its own `@layer base` block
- Results in duplicate layer declarations
- Can cause unexpected CSS priority issues
- Easy to miss during setup
**Prevention:**
- Check `src/index.css` immediately after running `shadcn init`
- Merge any duplicate `@layer base` blocks
- Keep only one base layer section
**Impact:** CSS priority issues, harder to debug styling problems
---
## Testing Gotchas
### 15. Not Testing Both Themes
❌ **WRONG:**
Only testing in light mode
✅ **CORRECT:**
Test in:
- Light mode
- Dark mode
- System mode
- Both initial load and toggle
---
### 16. Not Checking Contrast
❌ **WRONG:**
Colors look good but fail WCAG
✅ **CORRECT:**
- Use browser DevTools Lighthouse
- Check contrast ratios (4.5:1 minimum)
- Test with actual users
---
## Quick Diagnosis
**Symptoms → Likely Cause:**
| Symptom | Likely Cause |
|---------|-------------|
| `bg-primary` doesn't work | Missing `@theme inline` mapping |
| Colors all black/white | Double `hsl()` wrapping |
| Dark mode not switching | Missing ThemeProvider |
| Build fails | `tailwind.config.ts` exists with theme config |
| Text invisible | Wrong contrast colors |
| `@/` imports fail | Missing path aliases in tsconfig |
---
## Prevention Checklist
Before deploying:
- [ ] No `tailwind.config.ts` file (or it's empty)
- [ ] `components.json` has `"config": ""`
- [ ] All colors have `hsl()` wrapper in `:root`
- [ ] `@theme inline` maps all variables
- [ ] `@layer base` doesn't wrap `:root`
- [ ] Theme provider wraps app
- [ ] Tested in both light and dark modes
- [ ] All text has sufficient contrast

239
references/dark-mode.md Normal file
View File

@@ -0,0 +1,239 @@
# Dark Mode Implementation
## Overview
Tailwind v4 + shadcn/ui dark mode requires:
1. `ThemeProvider` component to manage state
2. `.dark` class toggling on `<html>` element
3. localStorage persistence
4. System theme detection
---
## ThemeProvider Component
### Full Implementation
```typescript
// src/components/theme-provider.tsx
import { createContext, useContext, useEffect, useState, ReactNode } from 'react'
type Theme = 'dark' | 'light' | 'system'
type ThemeProviderProps = {
children: ReactNode
defaultTheme?: Theme
storageKey?: string
}
type ThemeProviderState = {
theme: Theme
setTheme: (theme: Theme) => void
}
const initialState: ThemeProviderState = {
theme: 'system',
setTheme: () => null,
}
const ThemeProviderContext = createContext<ThemeProviderState>(initialState)
export function ThemeProvider({
children,
defaultTheme = 'system',
storageKey = 'vite-ui-theme',
...props
}: ThemeProviderProps) {
const [theme, setTheme] = useState<Theme>(() => {
try {
return (localStorage.getItem(storageKey) as Theme) || defaultTheme
} catch (e) {
return defaultTheme
}
})
useEffect(() => {
const root = window.document.documentElement
root.classList.remove('light', 'dark')
if (theme === 'system') {
const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
.matches ? 'dark' : 'light'
root.classList.add(systemTheme)
return
}
root.classList.add(theme)
}, [theme])
const value = {
theme,
setTheme: (theme: Theme) => {
try {
localStorage.setItem(storageKey, theme)
} catch (e) {
console.warn('Storage unavailable')
}
setTheme(theme)
},
}
return (
<ThemeProviderContext.Provider {...props} value={value}>
{children}
</ThemeProviderContext.Provider>
)
}
export const useTheme = () => {
const context = useContext(ThemeProviderContext)
if (context === undefined)
throw new Error('useTheme must be used within a ThemeProvider')
return context
}
```
### Wrap Your App
```typescript
// src/main.tsx
import { ThemeProvider } from '@/components/theme-provider'
ReactDOM.createRoot(document.getElementById('root')!).render(
<React.StrictMode>
<ThemeProvider defaultTheme="dark" storageKey="vite-ui-theme">
<App />
</ThemeProvider>
</React.StrictMode>,
)
```
---
## Theme Toggle Component
### Using shadcn/ui Dropdown Menu
```bash
pnpm dlx shadcn@latest add dropdown-menu
```
```typescript
// src/components/mode-toggle.tsx
import { Moon, Sun } from "lucide-react"
import { Button } from "@/components/ui/button"
import {
DropdownMenu,
DropdownMenuContent,
DropdownMenuItem,
DropdownMenuTrigger,
} from "@/components/ui/dropdown-menu"
import { useTheme } from "@/components/theme-provider"
export function ModeToggle() {
const { setTheme } = useTheme()
return (
<DropdownMenu>
<DropdownMenuTrigger asChild>
<Button variant="outline" size="icon">
<Sun className="h-[1.2rem] w-[1.2rem] rotate-0 scale-100 transition-all dark:-rotate-90 dark:scale-0" />
<Moon className="absolute h-[1.2rem] w-[1.2rem] rotate-90 scale-0 transition-all dark:rotate-0 dark:scale-100" />
<span className="sr-only">Toggle theme</span>
</Button>
</DropdownMenuTrigger>
<DropdownMenuContent align="end">
<DropdownMenuItem onClick={() => setTheme("light")}>
Light
</DropdownMenuItem>
<DropdownMenuItem onClick={() => setTheme("dark")}>
Dark
</DropdownMenuItem>
<DropdownMenuItem onClick={() => setTheme("system")}>
System
</DropdownMenuItem>
</DropdownMenuContent>
</DropdownMenu>
)
}
```
---
## How It Works
### Theme Flow
```
User selects theme → setTheme() called
↓
Save to localStorage
↓
Update state
↓
useEffect triggers
↓
Remove existing classes (.light, .dark)
↓
Add new class to <html>
↓
CSS variables update (.dark overrides :root)
↓
UI updates automatically
```
### System Theme Detection
```typescript
if (theme === 'system') {
const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
.matches ? 'dark' : 'light'
root.classList.add(systemTheme)
}
```
This respects the user's OS preference when "System" is selected.
---
## Common Issues
### Issue: Dark mode not switching
**Cause:** Theme provider not wrapping app
**Fix:** Ensure `<ThemeProvider>` wraps your app in `main.tsx`
### Issue: Theme resets on page refresh
**Cause:** localStorage not working
**Fix:** Check browser privacy settings, add sessionStorage fallback
### Issue: Flash of wrong theme on load
**Cause:** Theme applied after initial render
**Fix:** Add inline script to `index.html` (advanced)
### Issue: Icons not changing
**Cause:** CSS transitions not working
**Fix:** Verify icon classes use `dark:` variants for animations
---
## Testing Checklist
- [ ] Light mode displays correctly
- [ ] Dark mode displays correctly
- [ ] System mode respects OS setting
- [ ] Theme persists after page refresh
- [ ] Toggle component shows current state
- [ ] All text has proper contrast
- [ ] No flash of wrong theme on load
- [ ] Works in incognito mode (graceful fallback)
---
## Official Documentation
- shadcn/ui Dark Mode (Vite): https://ui.shadcn.com/docs/dark-mode/vite
- Tailwind Dark Mode: https://tailwindcss.com/docs/dark-mode

313
references/migration-guide.md Normal file
View File

@@ -0,0 +1,313 @@
# Migration Guide: Hardcoded Colors → CSS Variables
## Overview
This guide helps you migrate from hardcoded Tailwind colors (`bg-blue-600`) to semantic CSS variables (`bg-primary`).
**Benefits:**
- Automatic dark mode support
- Consistent color usage
- Single source of truth
- Easy theme customization
- Better accessibility
---
## Semantic Color Mapping
| Hardcoded Color | CSS Variable | Use Case |
|----------------|--------------|----------|
| `bg-red-*` / `text-red-*` | `bg-destructive` / `text-destructive` | Critical issues, errors, delete actions |
| `bg-green-*` / `text-green-*` | `bg-success` / `text-success` | Success states, positive metrics |
| `bg-yellow-*` / `text-yellow-*` | `bg-warning` / `text-warning` | Warnings, moderate issues |
| `bg-blue-*` / `text-blue-*` | `bg-info` or `bg-primary` | Info boxes, primary actions |
| `bg-gray-*` / `text-gray-*` | `bg-muted` / `text-muted-foreground` | Backgrounds, secondary text |
| `bg-purple-*` | `bg-info` | Remove - use blue instead |
| `bg-orange-*` | `bg-warning` | Remove - use yellow instead |
| `bg-emerald-*` | `bg-success` | Remove - use green instead |
---
## Migration Patterns
### Pattern 1: Solid Backgrounds
❌ **Before:**
```tsx
<div className="bg-blue-50 dark:bg-blue-950/20 text-blue-700 dark:text-blue-300">
```
✅ **After:**
```tsx
<div className="bg-info/10 text-info">
```
**Note:** `/10` creates 10% opacity
---
### Pattern 2: Borders
❌ **Before:**
```tsx
<div className="border-2 border-green-200 dark:border-green-800">
```
✅ **After:**
```tsx
<div className="border-2 border-success/30">
```
---
### Pattern 3: Text Colors
❌ **Before:**
```tsx
<span className="text-red-600 dark:text-red-400">
```
✅ **After:**
```tsx
<span className="text-destructive">
```
---
### Pattern 4: Icons
❌ **Before:**
```tsx
<AlertCircle className="text-yellow-500" />
```
✅ **After:**
```tsx
<AlertCircle className="text-warning" />
```
---
### Pattern 5: Gradients
❌ **Before:**
```tsx
<div className="bg-gradient-to-r from-green-50 to-emerald-50 dark:from-green-950/20 dark:to-emerald-950/20">
```
✅ **After:**
```tsx
<div className="bg-gradient-to-r from-success/10 to-success/20">
```
---
## Step-by-Step Migration
### Step 1: Add Semantic Colors to CSS
```css
/* src/index.css */
:root {
/* Add these if not already present */
--destructive: hsl(0 84.2% 60.2%);
--destructive-foreground: hsl(210 40% 98%);
--success: hsl(142.1 76.2% 36.3%);
--success-foreground: hsl(210 40% 98%);
--warning: hsl(38 92% 50%);
--warning-foreground: hsl(222.2 47.4% 11.2%);
--info: hsl(221.2 83.2% 53.3%);
--info-foreground: hsl(210 40% 98%);
}
.dark {
--destructive: hsl(0 62.8% 30.6%);
--destructive-foreground: hsl(210 40% 98%);
--success: hsl(142.1 70.6% 45.3%);
--success-foreground: hsl(222.2 47.4% 11.2%);
--warning: hsl(38 92% 55%);
--warning-foreground: hsl(222.2 47.4% 11.2%);
--info: hsl(217.2 91.2% 59.8%);
--info-foreground: hsl(222.2 47.4% 11.2%);
}
@theme inline {
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-success: var(--success);
--color-success-foreground: var(--success-foreground);
--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
}
```
### Step 2: Find Hardcoded Colors
```bash
# Search for background colors
grep -r "bg-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/
# Search for text colors
grep -r "text-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/
# Search for border colors
grep -r "border-\(red\|yellow\|blue\|green\|purple\|orange\|pink\|emerald\)-[0-9]" src/
```
### Step 3: Replace Component by Component
Start with high-impact components:
1. Buttons
2. Badges
3. Alert boxes
4. Status indicators
5. Cards
### Step 4: Test Both Themes
After each component:
- [ ] Check light mode appearance
- [ ] Check dark mode appearance
- [ ] Verify text contrast
- [ ] Test hover/active states
---
## Example: Badge Component
❌ **Before:**
```tsx
const severityConfig = {
critical: {
color: 'text-red-500',
bg: 'bg-red-500/10',
border: 'border-red-500/20',
},
warning: {
color: 'text-yellow-500',
bg: 'bg-yellow-500/10',
border: 'border-yellow-500/20',
},
info: {
color: 'text-blue-500',
bg: 'bg-blue-500/10',
border: 'border-blue-500/20',
}
}
```
✅ **After:**
```tsx
const severityConfig = {
critical: {
color: 'text-destructive',
bg: 'bg-destructive/10',
border: 'border-destructive/20',
},
warning: {
color: 'text-warning',
bg: 'bg-warning/10',
border: 'border-warning/20',
},
info: {
color: 'text-info',
bg: 'bg-info/10',
border: 'border-info/20',
}
}
```
---
## Testing Checklist
After migration:
- [ ] All severity levels (critical/warning/info) visually distinct
- [ ] Text has proper contrast in both light and dark modes
- [ ] No hardcoded color classes remain
- [ ] Hover states work correctly
- [ ] Gradients render smoothly
- [ ] Icons are visible and colored correctly
- [ ] Borders are visible
- [ ] No visual regressions
---
## Verification Commands
```bash
# Should return 0 results when migration complete
grep -r "text-red-[0-9]" src/components/
grep -r "bg-blue-[0-9]" src/components/
grep -r "border-green-[0-9]" src/components/
# Verify semantic colors are used
grep -r "bg-destructive" src/components/
grep -r "text-success" src/components/
```
---
## Performance Impact
**Before:** Every component has `dark:` variants
```tsx
<div className="bg-blue-50 dark:bg-blue-950/20 text-blue-700 dark:text-blue-300 border-blue-200 dark:border-blue-800">
```
**After:** Single class, CSS handles switching
```tsx
<div className="bg-info/10 text-info border-info/30">
```
**Result:**
- 60% fewer CSS classes in markup
- Smaller HTML payload
- Faster rendering
- Easier to maintain
---
## Common Pitfalls
### 1. Forgetting to Map in @theme inline
Variables defined in `:root` but not mapped → utilities don't exist
### 2. Wrong Opacity Syntax
❌ `bg-success-10` (doesn't work)
✅ `bg-success/10` (correct)
### 3. Mixing Approaches
Don't mix hardcoded and semantic in same component - choose one approach.
### 4. Not Testing Dark Mode
Always test both themes during migration.
---
## Rollback Plan
If migration causes issues:
1. Keep original components in git history
2. Use feature flags to toggle new theme
3. Test with subset of users first
4. Have monitoring for visual regressions
---
## Further Customization
After migration, you can easily:
- Add new semantic colors
- Create theme variants (high contrast, etc.)
- Support multiple brand themes
- Implement user-selectable color schemes
All by editing CSS variables - no component changes needed!

20
templates/components.json Normal file
View File

@@ -0,0 +1,20 @@
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "default",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "",
"css": "src/index.css",
"baseColor": "slate",
"cssVariables": true,
"prefix": ""
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils",
"ui": "@/components/ui",
"lib": "@/lib",
"hooks": "@/hooks"
}
}

140
templates/index.css Normal file
View File

@@ -0,0 +1,140 @@
@import "tailwindcss";
/*
Tailwind v4 + shadcn/ui Dark Mode Pattern
Based on: https://ui.shadcn.com/docs/tailwind-v4
Key Pattern:
1. Define CSS variables at root level (NOT in @layer base)
2. Use .dark for dark mode overrides (NOT in @theme)
3. Use @theme inline to map variables to Tailwind utilities
4. All color values must use hsl() wrapper
*/
/* Light mode colors - Define at root level */
:root {
--background: hsl(0 0% 100%);
--foreground: hsl(222.2 84% 4.9%);
--card: hsl(0 0% 100%);
--card-foreground: hsl(222.2 84% 4.9%);
--popover: hsl(0 0% 100%);
--popover-foreground: hsl(222.2 84% 4.9%);
--primary: hsl(221.2 83.2% 53.3%);
--primary-foreground: hsl(210 40% 98%);
--secondary: hsl(210 40% 96.1%);
--secondary-foreground: hsl(222.2 47.4% 11.2%);
--muted: hsl(210 40% 96.1%);
--muted-foreground: hsl(215.4 16.3% 46.9%);
--accent: hsl(210 40% 96.1%);
--accent-foreground: hsl(222.2 47.4% 11.2%);
--destructive: hsl(0 84.2% 60.2%);
--destructive-foreground: hsl(210 40% 98%);
--success: hsl(142.1 76.2% 36.3%);
--success-foreground: hsl(210 40% 98%);
--warning: hsl(38 92% 50%);
--warning-foreground: hsl(222.2 47.4% 11.2%);
--info: hsl(221.2 83.2% 53.3%);
--info-foreground: hsl(210 40% 98%);
--border: hsl(214.3 31.8% 91.4%);
--input: hsl(214.3 31.8% 91.4%);
--ring: hsl(221.2 83.2% 53.3%);
--radius: 0.5rem;
/* Chart colors */
--chart-1: hsl(12 76% 61%);
--chart-2: hsl(173 58% 39%);
--chart-3: hsl(197 37% 24%);
--chart-4: hsl(43 74% 66%);
--chart-5: hsl(27 87% 67%);
}
/* Dark mode colors - Plain CSS overrides (NOT in @theme) */
.dark {
--background: hsl(222.2 84% 4.9%);
--foreground: hsl(210 40% 98%);
--card: hsl(222.2 84% 4.9%);
--card-foreground: hsl(210 40% 98%);
--popover: hsl(222.2 84% 4.9%);
--popover-foreground: hsl(210 40% 98%);
--primary: hsl(217.2 91.2% 59.8%);
--primary-foreground: hsl(222.2 47.4% 11.2%);
--secondary: hsl(217.2 32.6% 17.5%);
--secondary-foreground: hsl(210 40% 98%);
--muted: hsl(217.2 32.6% 17.5%);
--muted-foreground: hsl(215 20.2% 65.1%);
--accent: hsl(217.2 32.6% 17.5%);
--accent-foreground: hsl(210 40% 98%);
--destructive: hsl(0 62.8% 30.6%);
--destructive-foreground: hsl(210 40% 98%);
--success: hsl(142.1 70.6% 45.3%);
--success-foreground: hsl(222.2 47.4% 11.2%);
--warning: hsl(38 92% 55%);
--warning-foreground: hsl(222.2 47.4% 11.2%);
--info: hsl(217.2 91.2% 59.8%);
--info-foreground: hsl(222.2 47.4% 11.2%);
--border: hsl(217.2 32.6% 17.5%);
--input: hsl(217.2 32.6% 17.5%);
--ring: hsl(224.3 76.3% 48%);
/* Chart colors for dark mode */
--chart-1: hsl(220 70% 50%);
--chart-2: hsl(160 60% 45%);
--chart-3: hsl(30 80% 55%);
--chart-4: hsl(280 65% 60%);
--chart-5: hsl(340 75% 55%);
}
/* Map CSS variables to Tailwind theme with @theme inline */
@theme inline {
--color-background: var(--background);
--color-foreground: var(--foreground);
--color-card: var(--card);
--color-card-foreground: var(--card-foreground);
--color-popover: var(--popover);
--color-popover-foreground: var(--popover-foreground);
--color-primary: var(--primary);
--color-primary-foreground: var(--primary-foreground);
--color-secondary: var(--secondary);
--color-secondary-foreground: var(--secondary-foreground);
--color-muted: var(--muted);
--color-muted-foreground: var(--muted-foreground);
--color-accent: var(--accent);
--color-accent-foreground: var(--accent-foreground);
--color-destructive: var(--destructive);
--color-destructive-foreground: var(--destructive-foreground);
--color-success: var(--success);
--color-success-foreground: var(--success-foreground);
--color-warning: var(--warning);
--color-warning-foreground: var(--warning-foreground);
--color-info: var(--info);
--color-info-foreground: var(--info-foreground);
--color-border: var(--border);
--color-input: var(--input);
--color-ring: var(--ring);
--color-chart-1: var(--chart-1);
--color-chart-2: var(--chart-2);
--color-chart-3: var(--chart-3);
--color-chart-4: var(--chart-4);
--color-chart-5: var(--chart-5);
/* Border radius tokens */
--radius-sm: calc(var(--radius) - 4px);
--radius-md: calc(var(--radius) - 2px);
--radius-lg: var(--radius);
}
/* Base styles in @layer base */
@layer base {
* {
border-color: var(--border);
}
body {
margin: 0;
background-color: var(--background);
color: var(--foreground);
font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif;
-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
}
}

92
templates/theme-provider.tsx Normal file
View File

@@ -0,0 +1,92 @@
import { createContext, useContext, useEffect, useState, ReactNode } from 'react'
type Theme = 'dark' | 'light' | 'system'
type ThemeProviderProps = {
children: ReactNode
defaultTheme?: Theme
storageKey?: string
}
type ThemeProviderState = {
theme: Theme
setTheme: (theme: Theme) => void
}
const initialState: ThemeProviderState = {
theme: 'system',
setTheme: () => null,
}
const ThemeProviderContext = createContext<ThemeProviderState>(initialState)
export function ThemeProvider({
children,
defaultTheme = 'system',
storageKey = 'vite-ui-theme',
...props
}: ThemeProviderProps) {
const [theme, setTheme] = useState<Theme>(() => {
// Try localStorage first, fall back to sessionStorage, then default
try {
return (localStorage.getItem(storageKey) as Theme) ||
(sessionStorage.getItem(storageKey) as Theme) ||
defaultTheme
} catch (e) {
// Storage unavailable (incognito/privacy mode) - use default
return defaultTheme
}
})
useEffect(() => {
const root = window.document.documentElement
root.classList.remove('light', 'dark')
if (theme === 'system') {
const systemTheme = window.matchMedia('(prefers-color-scheme: dark)')
.matches
? 'dark'
: 'light'
root.classList.add(systemTheme)
return
}
root.classList.add(theme)
}, [theme])
const value = {
theme,
setTheme: (theme: Theme) => {
// Try to persist to localStorage, fall back to sessionStorage
try {
localStorage.setItem(storageKey, theme)
} catch (e) {
// localStorage unavailable (incognito) - use sessionStorage
try {
sessionStorage.setItem(storageKey, theme)
} catch (err) {
// Both unavailable - just update state without persistence
console.warn('Storage unavailable, theme preference will not persist')
}
}
setTheme(theme)
},
}
return (
<ThemeProviderContext.Provider {...props} value={value}>
{children}
</ThemeProviderContext.Provider>
)
}
export const useTheme = () => {
const context = useContext(ThemeProviderContext)
if (context === undefined)
throw new Error('useTheme must be used within a ThemeProvider')
return context
}

31
templates/tsconfig.app.json Normal file
View File

@@ -0,0 +1,31 @@
{
"compilerOptions": {
"tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
"target": "ES2022",
"useDefineForClassFields": true,
"lib": ["ES2022", "DOM", "DOM.Iterable"],
"module": "ESNext",
"skipLibCheck": true,
/* Bundler mode */
"moduleResolution": "bundler",
"allowImportingTsExtensions": true,
"verbatimModuleSyntax": true,
"moduleDetection": "force",
"noEmit": true,
"jsx": "react-jsx",
/* Path aliases */
"baseUrl": ".",
"paths": {
"@/*": ["./src/*"]
},
/* Linting */
"strict": true,
"noUnusedLocals": true,
"noUnusedParameters": true,
"noFallthroughCasesInSwitch": true
},
"include": ["src"]
}

6
templates/utils.ts Normal file
View File

@@ -0,0 +1,6 @@
import { type ClassValue, clsx } from "clsx"
import { twMerge } from "tailwind-merge"
export function cn(...inputs: ClassValue[]) {
return twMerge(clsx(inputs))
}

17
templates/vite.config.ts Normal file
View File

@@ -0,0 +1,17 @@
import { defineConfig } from 'vite'
import react from '@vitejs/plugin-react'
import tailwindcss from '@tailwindcss/vite'
import path from 'path'
// https://vite.dev/config/
export default defineConfig({
plugins: [
react(),
tailwindcss(),
],
resolve: {
alias: {
'@': path.resolve(__dirname, './src')
}
}
})