初始化项目版本

2026-07-29 16:04:39 +08:00
commit 4305a1082b
2629 changed files with 760590 additions and 0 deletions
--- a/.agents/skills/shadcn-ui/resources/setup-guide.md
+++ b/.agents/skills/shadcn-ui/resources/setup-guide.md
@@ -0,0 +1,412 @@
+# shadcn/ui Setup Guide
+
+This guide walks you through setting up shadcn/ui in both new and existing projects.
+
+## Prerequisites
+
+Before you begin, ensure you have:
+- **Node.js 18+** installed
+- **React 18+** in your project
+- **Tailwind CSS 3.0+** configured
+- A package manager: npm, yarn, pnpm, or bun
+
+## Quick Start (New Project)
+
+### Option 1: npx shadcn create (Recommended)
+
+The easiest way to start a new project with shadcn/ui is using the `create` command, which allows you to customize everything (framework, library, style, font, etc.).
+
+```bash
+npx shadcn@latest create
+```
+
+This interactive command will guide you through:
+1.  **Project Name**: Directory for your app.
+2.  **Visual Style**: Choose from Vega, Nova, Maia, Lyra, Mira, or Classic.
+3.  **Base Color**: Select your primary theme color.
+4.  **Framework**: Next.js, Vite, Laravel, etc.
+5.  **Component Library**: Choose **Radix UI** or **Base UI**.
+6.  **RTL Support**: Enable Right-to-Left support if needed.
+
+### Option 2: Classic Manual Setup (Next.js)
+
+```bash
+# Create a new Next.js project
+npx create-next-app@latest my-app
+cd my-app
+
+# Initialize shadcn/ui
+npx shadcn@latest init
+
+# Add your first component
+npx shadcn@latest add button
+```
+
+### Option 3: Classic Manual Setup (Vite + React)
+
+```bash
+# Create a new Vite project
+npm create vite@latest my-app -- --template react-ts
+cd my-app
+npm install
+
+# Install Tailwind CSS
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+
+# Initialize shadcn/ui
+npx shadcn@latest init
+
+# Add your first component
+npx shadcn@latest add button
+```
+
+## Existing Project Setup
+
+### Step 1: Ensure Tailwind CSS is Installed
+
+If Tailwind is not installed:
+
+```bash
+npm install -D tailwindcss postcss autoprefixer
+npx tailwindcss init -p
+```
+
+Configure `tailwind.config.js`:
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    "./index.html",
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
+```
+
+### Step 2: Initialize shadcn/ui
+
+Run the initialization command:
+
+```bash
+npx shadcn@latest init
+```
+
+You'll be asked to configure:
+
+1. **Style**: Choose between `default`, `new-york`, or one of the new styles (Vega, Nova, etc.)
+   - `default`: Clean and minimal design
+   - `new-york`: More refined with subtle details
+
+2. **Base Color**: Choose your primary color palette
+   - slate, gray, zinc, neutral, or stone
+
+3. **CSS Variables**: Recommend `yes` for easier theming
+
+4. **TypeScript**: Recommend `yes` for type safety
+
+5. **Import Alias**: Default is `@/components` (recommended)
+
+6. **React Server Components**: Choose based on your framework
+   - `yes` for Next.js 13+ with app directory
+   - `no` for Vite, CRA, or Next.js pages directory
+
+7. **RTL Support**: Answer `yes` if you need Right-to-Left layout support (this will use logical properties like `ms-4` instead of `ml-4`).
+
+## Advanced Features
+
+### Visual Styles
+shadcn/ui now offers multiple visual styles beyond the defaults:
+- **Vega**: The classic shadcn/ui look.
+- **Nova**: Reduced padding/margins, compact.
+- **Maia**: Soft, rounded, generous spacing.
+- **Lyra**: Boxy, sharp, mono font friendly.
+- **Mira**: Dense, compact.
+
+### Base UI Support
+You can now choose between **Radix UI** and **Base UI** as the underlying primitive library. They share the same component API/abstraction, so your usage remains consistent.
+
+
+### Step 3: Verify Configuration
+
+The init command creates/updates several files:
+
+**components.json** (root of project):
+```json
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "default",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "tailwind.config.js",
+    "css": "src/index.css",
+    "baseColor": "slate",
+    "cssVariables": true
+  },
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib"
+  }
+}
+```
+
+**src/lib/utils.ts**:
+```typescript
+import { clsx, type ClassValue } from "clsx"
+import { twMerge } from "tailwind-merge"
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs))
+}
+```
+
+**Updated tailwind.config.js**:
+```javascript
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  darkMode: ["class"],
+  content: [
+    './pages/**/*.{ts,tsx}',
+    './components/**/*.{ts,tsx}',
+    './app/**/*.{ts,tsx}',
+    './src/**/*.{ts,tsx}',
+  ],
+  theme: {
+    container: {
+      center: true,
+      padding: "2rem",
+      screens: {
+        "2xl": "1400px",
+      },
+    },
+    extend: {
+      colors: {
+        border: "hsl(var(--border))",
+        input: "hsl(var(--input))",
+        ring: "hsl(var(--ring))",
+        background: "hsl(var(--background))",
+        foreground: "hsl(var(--foreground))",
+        primary: {
+          DEFAULT: "hsl(var(--primary))",
+          foreground: "hsl(var(--primary-foreground))",
+        },
+        // ... more colors
+      },
+      borderRadius: {
+        lg: "var(--radius)",
+        md: "calc(var(--radius) - 2px)",
+        sm: "calc(var(--radius) - 4px)",
+      },
+      keyframes: {
+        "accordion-down": {
+          from: { height: 0 },
+          to: { height: "var(--radix-accordion-content-height)" },
+        },
+        "accordion-up": {
+          from: { height: "var(--radix-accordion-content-height)" },
+          to: { height: 0 },
+        },
+      },
+      animation: {
+        "accordion-down": "accordion-down 0.2s ease-out",
+        "accordion-up": "accordion-up 0.2s ease-out",
+      },
+    },
+  },
+  plugins: [require("tailwindcss-animate")],
+}
+```
+
+**Updated globals.css** (or equivalent):
+```css
+@tailwind base;
+@tailwind components;
+@tailwind utilities;
+
+@layer base {
+  :root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --card: 0 0% 100%;
+    --card-foreground: 222.2 84% 4.9%;
+    --popover: 0 0% 100%;
+    --popover-foreground: 222.2 84% 4.9%;
+    --primary: 221.2 83.2% 53.3%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 221.2 83.2% 53.3%;
+    --radius: 0.5rem;
+  }
+
+  .dark {
+    --background: 222.2 84% 4.9%;
+    --foreground: 210 40% 98%;
+    /* ... dark mode variables */
+  }
+}
+
+@layer base {
+  * {
+    @apply border-border;
+  }
+  body {
+    @apply bg-background text-foreground;
+  }
+}
+```
+
+### Step 4: Configure Path Aliases
+
+Ensure your `tsconfig.json` includes path aliases:
+
+```json
+{
+  "compilerOptions": {
+    "baseUrl": ".",
+    "paths": {
+      "@/*": ["./src/*"]
+    }
+  }
+}
+```
+
+For Vite, also update `vite.config.ts`:
+
+```typescript
+import path from "path"
+import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react"
+
+export default defineConfig({
+  plugins: [react()],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
+  },
+})
+```
+
+### Step 5: Add Components
+
+Now you can add components:
+
+```bash
+# Add individual components
+npx shadcn@latest add button
+npx shadcn@latest add card
+npx shadcn@latest add dialog
+
+# Add multiple components at once
+npx shadcn@latest add button card dialog input label
+```
+
+Components will be added to `src/components/ui/` by default.
+
+## Framework-Specific Considerations
+
+### Next.js App Router
+
+- Set `rsc: true` in `components.json`
+- Add `"use client"` to stateful components
+- Import components work from server components by default
+
+### Next.js Pages Router
+
+- Set `rsc: false` in `components.json`
+- All components are client-side by default
+
+### Vite
+
+- Ensure path aliases are configured in `vite.config.ts`
+- Import `globals.css` in your main entry point (`main.tsx`)
+
+### Create React App
+
+- Use `craco` or `react-app-rewired` for path alias support
+- Or use relative imports instead of aliases
+
+## Verification Steps
+
+1. **Check file structure**:
+   ```
+   src/
+   ├── components/
+   │   └── ui/
+   ├── lib/
+   │   └── utils.ts
+   └── index.css (or globals.css)
+   ```
+
+2. **Test a simple component**:
+   ```tsx
+   import { Button } from "@/components/ui/button"
+   
+   export default function App() {
+     return <Button>Click me</Button>
+   }
+   ```
+
+3. **Verify Tailwind is working**:
+   - Component should render with proper styling
+   - Check browser dev tools for applied classes
+
+4. **Test dark mode** (if using CSS variables):
+   ```tsx
+   <html className="dark">
+   ```
+
+## Troubleshooting
+
+### "Cannot find module '@/components/ui/button'"
+
+**Solution**: Check path alias configuration in `tsconfig.json` and framework config.
+
+### Styles not applying
+
+**Solution**: 
+- Ensure `globals.css` is imported in your app entry point
+- Verify Tailwind config `content` paths include your files
+- Check CSS variables are defined in `globals.css`
+
+### TypeScript errors in components
+
+**Solution**:
+- Run `npm install` to ensure all dependencies are installed
+- Check that `@types/react` is installed
+- Restart TypeScript server in your editor
+
+### Components look broken
+
+**Solution**:
+- Verify `tailwindcss-animate` is installed: `npm install tailwindcss-animate`
+- Check that CSS variables are properly defined
+- Ensure you're not overriding component styles globally
+
+## Next Steps
+
+1. Browse the [component catalog](./component-catalog.md)
+2. Read the [customization guide](./customization-guide.md)
+3. Check out example implementations in `/examples`
+4. Join the [shadcn/ui Discord](https://discord.com/invite/vNvTqVaWm6)
+
+## Additional Resources
+
+- [Official Documentation](https://ui.shadcn.com)
+- [Component Examples](https://ui.shadcn.com/examples)
+- [GitHub Repository](https://github.com/shadcn-ui/ui)
+- [Tailwind CSS Docs](https://tailwindcss.com/docs)