| name | shadcn-vite-integration |
| description | Use this skill whenever the user wants to set up, configure, or refactor shadcn/ui in a Vite + React + TypeScript project (non-Next.js), including Tailwind, components.json, theming, and component structure. |
shadcn/ui + Vite + React + TypeScript Integration Skill
Purpose
You are a specialized assistant for integrating shadcn/ui into Vite + React + TypeScript
projects (i.e. non-Next.js setups).
Use this skill to:
- Set up shadcn/ui in a Vite + React + TS project from scratch
- Configure Tailwind CSS and PostCSS for shadcn/ui
- Create and maintain
components.json for shadcn/ui
- Generate and organize shadcn components (
components/ui/*, lib/utils)
- Configure theming (colors, radius, typography, dark mode)
- Refactor UI to use shadcn/ui primitives in a Vite app
- Align component structure and imports with shadcn best practices
Do not use this skill for:
- Next.js projects (use the Next.js + shadcn skills instead)
- Non-React frameworks (Vue, Svelte, etc.)
- Projects that do not use Vite or that explicitly use a different UI library only
If CLAUDE.md exists, follow its conventions for directory structure, theming, and any UI rules.
When To Apply This Skill
Trigger this skill when the user asks for any of the following (or similar):
- “Install and configure shadcn/ui in my Vite React app.”
- “Migrate this Vite + React project to use shadcn components.”
- “Set up Tailwind + shadcn in a Vite + TS project.”
- “Create a design system using shadcn/ui for this Vite app.”
- “Fix my shadcn setup in Vite (components.json, tailwind, etc.).”
Avoid applying this skill when:
- The project is clearly a Next.js project (use Next.js-specific shadcn skills).
- The user is asking only for test setup, routing, or backend code.
Project Assumptions
Unless otherwise stated:
-
Project is Vite + React + TypeScript (e.g. created via npm create vite@latest → React + TS).
-
Styling uses Tailwind CSS (or will be configured to do so).
-
Components live under something like:
src/
components/
ui/
lib/
utils.ts
-
The user is okay with introducing Tailwind + shadcn conventions into the project.
High-Level Workflow
When this skill is active, follow this workflow:
-
Detect project type & state
- Confirm it is a Vite + React + TS project.
- Check if Tailwind is already installed.
- Check if
components.json or existing shadcn components are present.
-
Install dependencies
- Ensure the following are added (adjust for npm/yarn/pnpm):
- React/TypeScript deps (usually already there).
- Tailwind CSS, PostCSS, Autoprefixer.
- shadcn-related tooling (CLI, configs) where applicable.
-
Configure Tailwind & PostCSS
- Initialize Tailwind if not present.
- Configure
tailwind.config with proper content globs for Vite + React.
- Ensure
postcss.config is set up to use Tailwind & Autoprefixer.
-
Create and configure components.json
- Create a
components.json file in the project root.
- Configure the paths for:
- base
components directory (e.g. src/components)
ui directory for shadcn components (e.g. src/components/ui)lib directory (e.g. src/lib)
- Set preferred
tailwind config paths and aliases.
-
Generate base components
- Use shadcn tooling/CLI patterns to generate base primitives:
Button, Input, Label, Card, etc.
- Ensure
src/lib/utils.ts is created with a cn helper or equivalent.
- Confirm imports work with the project’s module resolution (e.g. relative paths,
@/* alias if present).
-
Configure theming
- Set up color palette, radius, and other design tokens in Tailwind config and/or shadcn theme tokens.
- Ensure dark mode is configured consistently (e.g.
class strategy with dark class on <html> or <body>).
- Provide examples of how to toggle themes in the Vite app (e.g. with a
ThemeProvider component).
-
Refactor / build components using shadcn
- Convert or design new components (buttons, forms, layouts, modals, etc.) using shadcn primitives.
- Keep a clean separation between:
- Low-level primitives in
components/ui
- Higher-level patterns in
components/* (e.g. components/layout/AppShell.tsx).
-
Integrate into app entry point
- Ensure Tailwind styles are imported in the main entry file (e.g.
src/index.css vs src/main.tsx).
- Wrap the app in theming/context providers as needed (e.g.
ThemeProvider).
-
Document usage
- Add short documentation on how to:
- Generate new shadcn components.
- Use the
Button, Input, etc. in the app.
- Extend/override styles in a consistent way.
Detailed Steps
1. Tailwind Setup for Vite + React + TS
If Tailwind is not set up yet:
-
Install Tailwind + PostCSS + Autoprefixer.
-
Initialize Tailwind config and PostCSS config.
-
Configure Tailwind content globs similar to:
export default {
content: [
"./index.html",
"./src/**/*.{ts,tsx,js,jsx}",
],
theme: {
extend: {},
},
plugins: [],
};
-
Import Tailwind base styles in a global stylesheet, commonly src/index.css or src/styles/globals.css:
@tailwind base;
@tailwind components;
@tailwind utilities;
2. components.json for shadcn/ui
Create components.json in the project root, with something like:
{
"$schema": "https://ui.shadcn.com/schema.json",
"style": "default",
"rsc": false,
"tsx": true,
"tailwind": {
"config": "tailwind.config.ts",
"css": "src/index.css",
"baseColor": "slate",
"cssVariables": true
},
"aliases": {
"components": "@/components",
"utils": "@/lib/utils"
}
}
Adjust paths and aliases (@/) to match the project’s Vite/TS config. If no alias exists, use relative paths (../../components/ui/button).
3. Base Utilities & Structure
Set up a helper file for class merging:
import { clsx } from "clsx";
import { twMerge } from "tailwind-merge";
export function cn(...inputs: any[]) {
return twMerge(clsx(inputs));
}
Structure:
src/
components/
ui/
button.tsx
input.tsx
...
lib/
utils.ts
app/ or main layout files
4. Generating Components (Conceptually)
Since this skill cannot actually run commands, it should:
- Describe CLI usage (e.g.
npx shadcn-ui@latest add button or project-specific variant).
- Then create or modify the resulting files directly in the workspace, following shadcn’s expected patterns.
The generated Button component should:
- Use
cn helper.
- Provide
variant, size, and other props as per shadcn defaults.
- Export from
src/components/ui/button.tsx.
5. Theming & Design Tokens
-
Configure Tailwind theme extension in tailwind.config:
theme: {
extend: {
borderRadius: {
lg: "0.5rem",
md: "0.375rem",
sm: "0.25rem",
},
colors: {
},
},
},
-
If using custom CSS variables, ensure they are defined in :root and .dark classes in the global CSS.
-
Provide a ThemeProvider pattern if the user wants theme switching (e.g. using context + localStorage).
6. Refactoring Existing UI to shadcn
When asked to refactor, this skill should:
- Identify existing components that match common patterns (buttons, inputs, modals, cards).
- Replace them with shadcn-based versions or wrap shadcn primitives.
- Keep props APIs compatible or provide a clear migration path.
- Ensure accessible markup is preserved (roles, aria, label associations).
7. DX and Maintenance
Encourage:
- Consistent use of
components/ui for primitives.
- Consistent usage of
cn for merging class names.
- Avoiding hard-coding colors all over; instead rely on Tailwind tokens and CSS variables.
Examples of Prompts That Should Use This Skill
- “Install and configure shadcn/ui in this Vite + React + TS app.”
- “Set up Tailwind + shadcn for this Vite project and create base button/input components.”
- “Refactor this existing UI to use shadcn components instead of our custom ones.”
- “Fix my broken shadcn setup in Vite; components.json and paths are off.”
- “Create a consistent theme (radius, colors, typography) for this Vite app using shadcn.”
For these kinds of tasks, rely on this skill to provide project-level setup, configuration,
and refactoring guidance for shadcn/ui in a Vite + React + TypeScript environment, while other
skills handle routing, data fetching, or testing.
