初始化项目版本
This commit is contained in:
Axhub Make
248
.agents/skills/shadcn-ui/README.md
Normal file
248
.agents/skills/shadcn-ui/README.md
Normal file
@@ -0,0 +1,248 @@
|
||||
# shadcn/ui Integration Skill
|
||||
|
||||
## Install
|
||||
|
||||
```bash
|
||||
npx skills add google-labs-code/stitch-skills --skill shadcn-ui --global
|
||||
```
|
||||
|
||||
## What It Does
|
||||
|
||||
This skill provides expert guidance for integrating shadcn/ui components into your React applications. It helps you discover, install, customize, and optimize shadcn/ui components while following best practices.
|
||||
|
||||
## Example Prompts
|
||||
|
||||
```text
|
||||
Help me set up shadcn/ui in my Next.js project
|
||||
|
||||
Add a data table component with sorting and filtering to my app
|
||||
|
||||
Show me how to customize the button component with a new variant
|
||||
|
||||
Create a login form using shadcn/ui components with validation
|
||||
|
||||
Build a dashboard layout with sidebar navigation using shadcn/ui blocks
|
||||
```
|
||||
|
||||
## What is shadcn/ui?
|
||||
|
||||
shadcn/ui is a collection of beautifully designed, accessible, and customizable components built with:
|
||||
- **Radix UI or Base UI**: Unstyled, accessible component primitives
|
||||
- **Tailwind CSS**: Utility-first styling framework
|
||||
- **TypeScript**: Full type safety
|
||||
|
||||
**Key Difference**: Unlike traditional component libraries, shadcn/ui copies components directly into your project. This gives you:
|
||||
- Full control over the code
|
||||
- No version lock-in
|
||||
- Complete customization freedom
|
||||
- Zero runtime overhead
|
||||
|
||||
## Skill Structure
|
||||
|
||||
```text
|
||||
skills/shadcn-ui/
|
||||
├── SKILL.md — Core instructions & workflow
|
||||
├── README.md — This file
|
||||
├── examples/ — Example implementations
|
||||
│ ├── form-pattern.tsx — Form with validation
|
||||
│ ├── data-table.tsx — Advanced table with sorting
|
||||
│ └── auth-layout.tsx — Authentication flow
|
||||
├── resources/ — Reference documentation
|
||||
│ ├── setup-guide.md — Project initialization
|
||||
│ ├── component-catalog.md — Component reference
|
||||
│ ├── customization-guide.md — Theming patterns
|
||||
│ └── migration-guide.md — Migration from other libraries
|
||||
└── scripts/ — Utility scripts
|
||||
└── verify-setup.sh — Validate project configuration
|
||||
```
|
||||
|
||||
## How It Works
|
||||
|
||||
When activated, the agent follows this workflow:
|
||||
|
||||
### 1. **Discovery & Planning**
|
||||
- Lists available components using shadcn MCP tools
|
||||
- Identifies required dependencies
|
||||
- Plans component composition strategy
|
||||
|
||||
### 2. **Setup & Configuration**
|
||||
- Verifies or initializes `components.json`
|
||||
- Checks Tailwind CSS configuration
|
||||
- Validates import aliases and paths
|
||||
|
||||
### 3. **Component Integration**
|
||||
- Retrieves component source code
|
||||
- Installs via CLI or manual integration
|
||||
- Handles dependency installation
|
||||
|
||||
### 4. **Customization**
|
||||
- Applies theme customization
|
||||
- Creates component variants
|
||||
- Extends components with custom logic
|
||||
|
||||
### 5. **Quality Assurance**
|
||||
- Validates TypeScript types
|
||||
- Checks accessibility compliance
|
||||
- Verifies responsive behavior
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Your project should have:
|
||||
- **React 18+**
|
||||
- **Tailwind CSS 3.0+**
|
||||
- **TypeScript** (recommended)
|
||||
- **Node.js 18+**
|
||||
|
||||
## Quick Start
|
||||
|
||||
### For New Projects
|
||||
|
||||
```bash
|
||||
# Create Next.js project with shadcn/ui
|
||||
npx create-next-app@latest my-app
|
||||
cd my-app
|
||||
npx shadcn@latest init
|
||||
|
||||
# Add components
|
||||
npx shadcn@latest add button
|
||||
npx shadcn@latest add card
|
||||
```
|
||||
|
||||
### For Existing Projects
|
||||
|
||||
```bash
|
||||
# Initialize shadcn/ui
|
||||
npx shadcn@latest init
|
||||
|
||||
# Configure when prompted:
|
||||
# - Choose style (default/new-york)
|
||||
# - Select base color
|
||||
# - Configure CSS variables
|
||||
# - Set import aliases
|
||||
|
||||
# Add your first component
|
||||
npx shadcn@latest add button
|
||||
```
|
||||
|
||||
## Available Components
|
||||
|
||||
shadcn/ui provides 50+ components including:
|
||||
|
||||
**Layout**: Accordion, Card, Separator, Tabs, Collapsible
|
||||
**Forms**: Button, Input, Label, Checkbox, Radio Group, Select, Textarea
|
||||
**Data Display**: Table, Badge, Avatar, Progress, Skeleton
|
||||
**Overlays**: Dialog, Sheet, Popover, Tooltip, Dropdown Menu
|
||||
**Navigation**: Navigation Menu, Tabs, Breadcrumb, Pagination
|
||||
**Feedback**: Alert, Alert Dialog, Toast, Command
|
||||
|
||||
Plus complete **Blocks** like:
|
||||
- Authentication forms
|
||||
- Dashboard layouts
|
||||
- Calendar interfaces
|
||||
- Sidebar navigation
|
||||
- E-commerce components
|
||||
|
||||
## Customization Approach
|
||||
|
||||
### Theme-Level Customization
|
||||
Modify CSS variables in `globals.css`:
|
||||
```css
|
||||
:root {
|
||||
--primary: 221.2 83.2% 53.3%;
|
||||
--secondary: 210 40% 96.1%;
|
||||
/* ... */
|
||||
}
|
||||
```
|
||||
|
||||
### Component-Level Customization
|
||||
Components use `class-variance-authority` for variants:
|
||||
```typescript
|
||||
const buttonVariants = cva(
|
||||
"base-classes",
|
||||
{
|
||||
variants: {
|
||||
variant: { default: "...", destructive: "..." },
|
||||
size: { default: "...", sm: "..." },
|
||||
}
|
||||
}
|
||||
)
|
||||
```
|
||||
|
||||
### Composition
|
||||
Create higher-level components:
|
||||
```typescript
|
||||
// Compose existing components
|
||||
export function FeatureCard({ title, description, icon }) {
|
||||
return (
|
||||
<Card>
|
||||
<CardHeader>
|
||||
{icon}
|
||||
<CardTitle>{title}</CardTitle>
|
||||
</CardHeader>
|
||||
<CardContent>
|
||||
<p>{description}</p>
|
||||
</CardContent>
|
||||
</Card>
|
||||
)
|
||||
}
|
||||
```
|
||||
|
||||
## Integration with MCP Tools
|
||||
|
||||
This skill leverages shadcn MCP server capabilities:
|
||||
|
||||
- `list_components` - Browse component catalog
|
||||
- `get_component` - Retrieve component source
|
||||
- `get_component_metadata` - View props and dependencies
|
||||
- `get_component_demo` - See usage examples
|
||||
- `list_blocks` - Browse UI blocks
|
||||
- `get_block` - Retrieve block source with all files
|
||||
- `search_items_in_registries` - Find components in custom registries
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Keep `ui/` pure**: Don't modify components in `components/ui/` directly
|
||||
2. **Compose, don't fork**: Create wrapper components instead of editing originals
|
||||
3. **Use the CLI**: Let `shadcn add` handle dependencies and updates
|
||||
4. **Maintain consistency**: Use the `cn()` utility for all class merging
|
||||
5. **Respect accessibility**: Preserve ARIA attributes and keyboard handlers
|
||||
6. **Test responsiveness**: shadcn components are responsive by default—keep it that way
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### "Module not found" errors
|
||||
Check your `tsconfig.json` includes path aliases:
|
||||
```json
|
||||
{
|
||||
"compilerOptions": {
|
||||
"paths": {
|
||||
"@/*": ["./src/*"]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Styles not applying
|
||||
- Import `globals.css` in your root layout
|
||||
- Verify Tailwind config includes component paths
|
||||
- Check CSS variable definitions match component expectations
|
||||
|
||||
### TypeScript errors
|
||||
- Ensure all Radix UI peer dependencies are installed
|
||||
- Run `npm install` after adding components via CLI
|
||||
- Check that React types are up to date
|
||||
|
||||
## Further Reading
|
||||
|
||||
- [Official Documentation](https://ui.shadcn.com)
|
||||
- [Component Source](https://github.com/shadcn-ui/ui)
|
||||
- [Radix UI Docs](https://www.radix-ui.com)
|
||||
- [Tailwind CSS Docs](https://tailwindcss.com)
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions to improve this skill are welcome! See the root [CONTRIBUTING.md](../../../../CONTRIBUTING.md) for guidelines.
|
||||
|
||||
## License
|
||||
|
||||
See [LICENSE](../../../../LICENSE) in the repository root.
|
||||
Reference in New Issue
Block a user