Skip to content

Commit c3fed38

Browse files
eriicafeseriicafes
committed
Build CLI and Studio UI mvp
1 parent 1e3b21d commit c3fed38

127 files changed

Lines changed: 13754 additions & 5724 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

‎.agents/skills/shadcn/SKILL.md‎

Lines changed: 267 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/shadcn/agents/openai.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,5 @@
1+
interface:
2+
display_name: "shadcn/ui"
3+
short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
4+
icon_small: "./assets/shadcn-small.png"
5+
icon_large: "./assets/shadcn.png"

‎.agents/skills/shadcn/assets/shadcn-small.png‎

1.02 KB
Loading

‎.agents/skills/shadcn/assets/shadcn.png‎

3.76 KB
Loading

‎.agents/skills/shadcn/cli.md‎

Lines changed: 290 additions & 0 deletions
Large diffs are not rendered by default.

‎.agents/skills/shadcn/customization.md‎

Lines changed: 209 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,209 @@
1+
# Customization & Theming
2+
3+
Components reference semantic CSS variable tokens. Change the variables to change every component.
4+
5+
## Contents
6+
7+
- How it works (CSS variables → Tailwind utilities → components)
8+
- Color variables and OKLCH format
9+
- Dark mode setup
10+
- Changing the theme (presets, CSS variables)
11+
- Adding custom colors (Tailwind v3 and v4)
12+
- Border radius
13+
- Customizing components (variants, className, wrappers)
14+
- Checking for updates
15+
16+
---
17+
18+
## How It Works
19+
20+
1. CSS variables defined in `:root` (light) and `.dark` (dark mode).
21+
2. Tailwind maps them to utilities: `bg-primary`, `text-muted-foreground`, etc.
22+
3. Components use these utilities — changing a variable changes all components that reference it.
23+
24+
---
25+
26+
## Color Variables
27+
28+
Every color follows the `name` / `name-foreground` convention. The base variable is for backgrounds, `-foreground` is for text/icons on that background.
29+
30+
| Variable | Purpose |
31+
| -------------------------------------------- | -------------------------------- |
32+
| `--background` / `--foreground` | Page background and default text |
33+
| `--card` / `--card-foreground` | Card surfaces |
34+
| `--primary` / `--primary-foreground` | Primary buttons and actions |
35+
| `--secondary` / `--secondary-foreground` | Secondary actions |
36+
| `--muted` / `--muted-foreground` | Muted/disabled states |
37+
| `--accent` / `--accent-foreground` | Hover and accent states |
38+
| `--destructive` / `--destructive-foreground` | Error and destructive actions |
39+
| `--border` | Default border color |
40+
| `--input` | Form input borders |
41+
| `--ring` | Focus ring color |
42+
| `--chart-1` through `--chart-5` | Chart/data visualization |
43+
| `--sidebar-*` | Sidebar-specific colors |
44+
| `--surface` / `--surface-foreground` | Secondary surface |
45+
46+
Colors use OKLCH: `--primary: oklch(0.205 0 0)` where values are lightness (0–1), chroma (0 = gray), and hue (0–360).
47+
48+
---
49+
50+
## Dark Mode
51+
52+
Class-based toggle via `.dark` on the root element. In Next.js, use `next-themes`:
53+
54+
```tsx
55+
import { ThemeProvider } from "next-themes"
56+
57+
<ThemeProvider attribute="class" defaultTheme="system" enableSystem>
58+
{children}
59+
</ThemeProvider>
60+
```
61+
62+
---
63+
64+
## Changing the Theme
65+
66+
```bash
67+
# Apply a preset code from ui.shadcn.com.
68+
npx shadcn@latest apply --preset a2r6bw
69+
70+
# Positional shorthand also works.
71+
npx shadcn@latest apply a2r6bw
72+
73+
# Switch to a named preset and overwrite existing components.
74+
npx shadcn@latest apply --preset nova
75+
76+
# Preserve existing components instead.
77+
npx shadcn@latest init --preset nova --force --no-reinstall
78+
79+
# Use a custom theme URL.
80+
npx shadcn@latest apply --preset "https://ui.shadcn.com/init?base=radix&style=nova&theme=blue&..."
81+
```
82+
83+
Or edit CSS variables directly in `globals.css`.
84+
85+
---
86+
87+
## Adding Custom Colors
88+
89+
Add variables to the file at `tailwindCssFile` from `npx shadcn@latest info` (typically `globals.css`). Never create a new CSS file for this.
90+
91+
```css
92+
/* 1. Define in the global CSS file. */
93+
:root {
94+
--warning: oklch(0.84 0.16 84);
95+
--warning-foreground: oklch(0.28 0.07 46);
96+
}
97+
.dark {
98+
--warning: oklch(0.41 0.11 46);
99+
--warning-foreground: oklch(0.99 0.02 95);
100+
}
101+
```
102+
103+
```css
104+
/* 2a. Register with Tailwind v4 (@theme inline). */
105+
@theme inline {
106+
--color-warning: var(--warning);
107+
--color-warning-foreground: var(--warning-foreground);
108+
}
109+
```
110+
111+
When `tailwindVersion` is `"v3"` (check via `npx shadcn@latest info`), register in `tailwind.config.js` instead:
112+
113+
```js
114+
// 2b. Register with Tailwind v3 (tailwind.config.js).
115+
module.exports = {
116+
theme: {
117+
extend: {
118+
colors: {
119+
warning: "oklch(var(--warning) / <alpha-value>)",
120+
"warning-foreground":
121+
"oklch(var(--warning-foreground) / <alpha-value>)",
122+
},
123+
},
124+
},
125+
}
126+
```
127+
128+
```tsx
129+
// 3. Use in components.
130+
<div className="bg-warning text-warning-foreground">Warning</div>
131+
```
132+
133+
---
134+
135+
## Border Radius
136+
137+
`--radius` controls border radius globally. Components derive values from it (`rounded-lg` = `var(--radius)`, `rounded-md` = `calc(var(--radius) - 2px)`).
138+
139+
---
140+
141+
## Customizing Components
142+
143+
See also: [rules/styling.md](./rules/styling.md) for Incorrect/Correct examples.
144+
145+
Prefer these approaches in order:
146+
147+
### 1. Built-in variants
148+
149+
```tsx
150+
<Button variant="outline" size="sm">
151+
Click
152+
</Button>
153+
```
154+
155+
### 2. Tailwind classes via `className`
156+
157+
```tsx
158+
<Card className="mx-auto max-w-md">...</Card>
159+
```
160+
161+
### 3. Add a new variant
162+
163+
Edit the component source to add a variant via `cva`:
164+
165+
```tsx
166+
// components/ui/button.tsx
167+
warning: "bg-warning text-warning-foreground hover:bg-warning/90",
168+
```
169+
170+
### 4. Wrapper components
171+
172+
Compose shadcn/ui primitives into higher-level components:
173+
174+
```tsx
175+
export function ConfirmDialog({ title, description, onConfirm, children }) {
176+
return (
177+
<AlertDialog>
178+
<AlertDialogTrigger asChild>{children}</AlertDialogTrigger>
179+
<AlertDialogContent>
180+
<AlertDialogHeader>
181+
<AlertDialogTitle>{title}</AlertDialogTitle>
182+
<AlertDialogDescription>{description}</AlertDialogDescription>
183+
</AlertDialogHeader>
184+
<AlertDialogFooter>
185+
<AlertDialogCancel>Cancel</AlertDialogCancel>
186+
<AlertDialogAction onClick={onConfirm}>Confirm</AlertDialogAction>
187+
</AlertDialogFooter>
188+
</AlertDialogContent>
189+
</AlertDialog>
190+
)
191+
}
192+
```
193+
194+
---
195+
196+
## Checking for Updates
197+
198+
```bash
199+
npx shadcn@latest add button --diff
200+
```
201+
202+
To preview exactly what would change before updating, use `--dry-run` and `--diff`:
203+
204+
```bash
205+
npx shadcn@latest add button --dry-run # see all affected files
206+
npx shadcn@latest add button --diff button.tsx # see the diff for a specific file
207+
```
208+
209+
See [Updating Components in SKILL.md](./SKILL.md#updating-components) for the full smart merge workflow.

‎.agents/skills/shadcn/evals/evals.json‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,47 @@
1+
{
2+
"skill_name": "shadcn",
3+
"evals": [
4+
{
5+
"id": 1,
6+
"prompt": "I'm building a Next.js app with shadcn/ui (base-nova preset, lucide icons). Create a settings form component with fields for: full name, email address, and notification preferences (email, SMS, push notifications as toggle options). Add validation states for required fields.",
7+
"expected_output": "A React component using FieldGroup, Field, ToggleGroup, data-invalid/aria-invalid validation, gap-* spacing, and semantic colors.",
8+
"files": [],
9+
"expectations": [
10+
"Uses FieldGroup and Field components for form layout instead of raw div with space-y",
11+
"Uses Switch for independent on/off notification toggles (not looping Button with manual active state)",
12+
"Uses data-invalid on Field and aria-invalid on the input control for validation states",
13+
"Uses gap-* (e.g. gap-4, gap-6) instead of space-y-* or space-x-* for spacing",
14+
"Uses semantic color tokens (e.g. bg-background, text-muted-foreground, text-destructive) instead of raw colors like bg-red-500",
15+
"No manual dark: color overrides"
16+
]
17+
},
18+
{
19+
"id": 2,
20+
"prompt": "Create a dialog component for editing a user profile. It should have the user's avatar at the top, input fields for name and bio, and Save/Cancel buttons with appropriate icons. Using shadcn/ui with radix-nova preset and tabler icons.",
21+
"expected_output": "A React component with DialogTitle, Avatar+AvatarFallback, data-icon on icon buttons, no icon sizing classes, tabler icon imports.",
22+
"files": [],
23+
"expectations": [
24+
"Includes DialogTitle for accessibility (visible or with sr-only class)",
25+
"Avatar component includes AvatarFallback",
26+
"Icons on buttons use the data-icon attribute (data-icon=\"inline-start\" or data-icon=\"inline-end\")",
27+
"No sizing classes on icons inside components (no size-4, w-4, h-4, etc.)",
28+
"Uses tabler icons (@tabler/icons-react) instead of lucide-react",
29+
"Uses asChild for custom triggers (radix preset)"
30+
]
31+
},
32+
{
33+
"id": 3,
34+
"prompt": "Create a dashboard component that shows 4 stat cards in a grid. Each card has a title, large number, percentage change badge, and a loading skeleton state. Using shadcn/ui with base-nova preset and lucide icons.",
35+
"expected_output": "A React component with full Card composition, Skeleton for loading, Badge for changes, semantic colors, gap-* spacing.",
36+
"files": [],
37+
"expectations": [
38+
"Uses full Card composition with CardHeader, CardTitle, CardContent (not dumping everything into CardContent)",
39+
"Uses Skeleton component for loading placeholders instead of custom animate-pulse divs",
40+
"Uses Badge component for percentage change instead of custom styled spans",
41+
"Uses semantic color tokens instead of raw color values like bg-green-500 or text-red-600",
42+
"Uses gap-* instead of space-y-* or space-x-* for spacing",
43+
"Uses size-* when width and height are equal instead of separate w-* h-*"
44+
]
45+
}
46+
]
47+
}

‎.agents/skills/shadcn/mcp.md‎

Lines changed: 105 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,105 @@
1+
# shadcn MCP Server
2+
3+
The CLI includes an MCP server that lets AI assistants search, browse, view, and install items from registries.
4+
5+
---
6+
7+
## Setup
8+
9+
```bash
10+
shadcn mcp # start the MCP server (stdio)
11+
shadcn mcp init # write config for your editor
12+
```
13+
14+
Editor config files:
15+
16+
| Editor | Config file |
17+
| ----------- | ------------------------------- |
18+
| Claude Code | `.mcp.json` |
19+
| Cursor | `.cursor/mcp.json` |
20+
| VS Code | `.vscode/mcp.json` |
21+
| OpenCode | `opencode.json` |
22+
| Codex | `~/.codex/config.toml` (manual) |
23+
24+
---
25+
26+
## Tools
27+
28+
> **Tip:** MCP tools handle registry operations (search, view, install). For project configuration (aliases, framework, Tailwind version), use `npx shadcn@latest info` — there is no MCP equivalent.
29+
30+
### `shadcn:get_project_registries`
31+
32+
Returns registry names from `components.json`. Errors if no `components.json` exists.
33+
34+
**Input:** none
35+
36+
### `shadcn:list_items_in_registries`
37+
38+
Lists all items from one or more registries. Registries can be configured
39+
namespaces such as `@acme`, public GitHub sources such as `owner/repo`, or
40+
registry catalog URLs. Omit `registries` to list from every registry configured
41+
in `components.json`.
42+
43+
**Input:** `registries` (string[], optional — omit for all configured), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
44+
45+
### `shadcn:search_items_in_registries`
46+
47+
Fuzzy search across registries. Registries can be configured namespaces, public
48+
GitHub sources, or registry catalog URLs. Omit `registries` to search every
49+
registry configured in `components.json` — e.g. "find me a hero" across all
50+
configured registries.
51+
52+
**Input:** `registries` (string[], optional — omit for all configured), `query` (string), `types` (string[], optional — e.g. `["ui", "block"]`), `limit` (number, optional, defaults to 100), `offset` (number, optional)
53+
54+
### `shadcn:view_items_in_registries`
55+
56+
View item details including full file contents.
57+
58+
**Input:** `items` (string[]) — e.g.
59+
`["@shadcn/button", "@shadcn/card", "owner/repo/item"]`
60+
61+
### `shadcn:get_item_examples_from_registries`
62+
63+
Find usage examples and demos with source code. Omit `registries` to search
64+
every registry configured in `components.json`.
65+
66+
**Input:** `registries` (string[], optional — omit for all configured), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
67+
68+
### `shadcn:get_add_command_for_items`
69+
70+
Returns the CLI install command.
71+
72+
**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
73+
74+
### `shadcn:get_audit_checklist`
75+
76+
Returns a checklist for verifying components (imports, deps, lint, TypeScript).
77+
78+
**Input:** none
79+
80+
---
81+
82+
## Configuring Registries
83+
84+
Namespaced and authenticated registries are set in `components.json`. The
85+
`@shadcn` registry is always built-in. Public GitHub registries can also be used
86+
directly as `owner/repo` registry sources when the repository has a root
87+
`registry.json`; they do not need `components.json` configuration.
88+
89+
```json
90+
{
91+
"registries": {
92+
"@acme": "https://acme.com/r/{name}.json",
93+
"@private": {
94+
"url": "https://private.com/r/{name}.json",
95+
"headers": { "Authorization": "Bearer ${MY_TOKEN}" }
96+
}
97+
}
98+
}
99+
```
100+
101+
- Names must start with `@`.
102+
- URLs must contain `{name}`.
103+
- `${VAR}` references are resolved from environment variables.
104+
105+
Community registry index: `https://ui.shadcn.com/r/registries.json`

0 commit comments

Comments
 (0)