@1aboveio/app-dev-skills 0.0.0-stage → 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +29 -2
- package/package.json +33 -4
- package/skills/airflow/LICENSE +3 -0
- package/skills/airflow/SKILL.md +199 -0
- package/skills/airflow/release-check.mjs +93 -0
- package/skills/android-foundation/LICENSE +3 -0
- package/skills/android-foundation/SKILL.md +192 -0
- package/skills/android-foundation/assets/android-ci-job.yml +217 -0
- package/skills/android-foundation/references/ci.md +87 -0
- package/skills/android-foundation/references/gotchas.md +221 -0
- package/skills/android-foundation/references/setup.md +164 -0
- package/skills/android-foundation/release-check.mjs +93 -0
- package/skills/android-foundation/scripts/device-run.sh +176 -0
- package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
- package/skills/app-debug/LICENSE +3 -0
- package/skills/app-debug/SKILL.md +110 -0
- package/skills/app-debug/references/common-errors.md +128 -0
- package/skills/app-debug/release-check.mjs +93 -0
- package/skills/better-auth/LICENSE +3 -0
- package/skills/better-auth/SKILL.md +598 -0
- package/skills/better-auth/references/feishu-api.md +270 -0
- package/skills/better-auth/release-check.mjs +93 -0
- package/skills/ios-foundation/LICENSE +3 -0
- package/skills/ios-foundation/SKILL.md +184 -0
- package/skills/ios-foundation/references/setup.md +243 -0
- package/skills/ios-foundation/release-check.mjs +93 -0
- package/skills/monorepo/LICENSE +3 -0
- package/skills/monorepo/SKILL.md +462 -0
- package/skills/monorepo/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/LICENSE +3 -0
- package/skills/nextjs-fullstack/SKILL.md +211 -0
- package/skills/nextjs-fullstack/conventions.md +318 -0
- package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
- package/skills/nextjs-fullstack/nextjs16.md +287 -0
- package/skills/nextjs-fullstack/release-check.mjs +93 -0
- package/skills/nextjs-fullstack/server-actions.md +409 -0
- package/skills/prisma-setup/LICENSE +3 -0
- package/skills/prisma-setup/SKILL.md +181 -0
- package/skills/prisma-setup/nextjs.md +258 -0
- package/skills/prisma-setup/release-check.mjs +93 -0
- package/skills/prisma-setup/turborepo.md +301 -0
- package/skills/pyspark/LICENSE +3 -0
- package/skills/pyspark/SKILL.md +127 -0
- package/skills/pyspark/assets/templates/etl.py +748 -0
- package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
- package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
- package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
- package/skills/pyspark/references/etl-contract.md +129 -0
- package/skills/pyspark/references/production-validation.md +131 -0
- package/skills/pyspark/references/reconciliation.md +38 -0
- package/skills/pyspark/references/transformation-design.md +190 -0
- package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
- package/skills/pyspark/release-check.mjs +93 -0
- package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
- package/skills/python-backend/LICENSE +3 -0
- package/skills/python-backend/SKILL.md +325 -0
- package/skills/python-backend/assets/uv-install.sh +48 -0
- package/skills/python-backend/references/uv-installs.md +83 -0
- package/skills/python-backend/release-check.mjs +93 -0
- package/skills/shadcn/LICENSE +3 -0
- package/skills/shadcn/SKILL.md +120 -0
- package/skills/shadcn/assets/shadcn-small.png +0 -0
- package/skills/shadcn/assets/shadcn.png +0 -0
- package/skills/shadcn/cli.md +411 -0
- package/skills/shadcn/customization.md +224 -0
- package/skills/shadcn/mcp.md +101 -0
- package/skills/shadcn/release-check.mjs +93 -0
- package/skills/shadcn/rules/base-vs-radix.md +323 -0
- package/skills/shadcn/rules/component-selection.md +67 -0
- package/skills/shadcn/rules/composition.md +195 -0
- package/skills/shadcn/rules/data-table.md +201 -0
- package/skills/shadcn/rules/forms.md +255 -0
- package/skills/shadcn/rules/icons.md +103 -0
- package/skills/shadcn/rules/styling.md +167 -0
- package/skills/zod-v4/LICENSE +3 -0
- package/skills/zod-v4/SKILL.md +286 -0
- package/skills/zod-v4/release-check.mjs +93 -0
|
@@ -0,0 +1,101 @@
|
|
|
1
|
+
# shadcn MCP Server
|
|
2
|
+
|
|
3
|
+
The CLI includes an MCP server that lets AI assistants search, browse, view, and install components 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 (prompts)
|
|
12
|
+
shadcn mcp init --client claude # claude | cursor | vscode | codex | opencode
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
Editor config files:
|
|
16
|
+
|
|
17
|
+
| Editor | Config file |
|
|
18
|
+
|--------|------------|
|
|
19
|
+
| Claude Code | `.mcp.json` |
|
|
20
|
+
| Cursor | `.cursor/mcp.json` |
|
|
21
|
+
| VS Code | `.vscode/mcp.json` |
|
|
22
|
+
| OpenCode | `opencode.json` |
|
|
23
|
+
| Codex | `~/.codex/config.toml` (manual) |
|
|
24
|
+
|
|
25
|
+
---
|
|
26
|
+
|
|
27
|
+
## Tools
|
|
28
|
+
|
|
29
|
+
> **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.
|
|
30
|
+
|
|
31
|
+
### `shadcn:get_project_registries`
|
|
32
|
+
|
|
33
|
+
Returns registry names from `components.json`. Errors if no `components.json` exists.
|
|
34
|
+
|
|
35
|
+
**Input:** none
|
|
36
|
+
|
|
37
|
+
### `shadcn:list_items_in_registries`
|
|
38
|
+
|
|
39
|
+
Lists all items from one or more registries.
|
|
40
|
+
|
|
41
|
+
**Input:** `registries` (string[]), `types` (string[], optional — e.g. `ui`, `block`, `hook`), `limit` (number, optional), `offset` (number, optional)
|
|
42
|
+
|
|
43
|
+
### `shadcn:search_items_in_registries`
|
|
44
|
+
|
|
45
|
+
Fuzzy search across registries.
|
|
46
|
+
|
|
47
|
+
**Input:** `registries` (string[]), `query` (string), `types` (string[], optional), `limit` (number, optional), `offset` (number, optional)
|
|
48
|
+
|
|
49
|
+
### `shadcn:view_items_in_registries`
|
|
50
|
+
|
|
51
|
+
View item details including full file contents.
|
|
52
|
+
|
|
53
|
+
**Input:** `items` (string[]) — e.g. `["@shadcn/button", "@shadcn/card"]`
|
|
54
|
+
|
|
55
|
+
### `shadcn:get_item_examples_from_registries`
|
|
56
|
+
|
|
57
|
+
Find usage examples and demos with source code.
|
|
58
|
+
|
|
59
|
+
**Input:** `registries` (string[]), `query` (string) — e.g. `"accordion-demo"`, `"button example"`
|
|
60
|
+
|
|
61
|
+
### `shadcn:get_add_command_for_items`
|
|
62
|
+
|
|
63
|
+
Returns the CLI install command.
|
|
64
|
+
|
|
65
|
+
**Input:** `items` (string[]) — e.g. `["@shadcn/button"]`
|
|
66
|
+
|
|
67
|
+
### `shadcn:get_audit_checklist`
|
|
68
|
+
|
|
69
|
+
Returns a checklist for verifying components (imports, deps, lint, TypeScript).
|
|
70
|
+
|
|
71
|
+
**Input:** none
|
|
72
|
+
|
|
73
|
+
---
|
|
74
|
+
|
|
75
|
+
## Configuring Registries
|
|
76
|
+
|
|
77
|
+
Registries are set in `components.json`. The `@shadcn` registry is always built-in, as `https://ui.shadcn.com/r/styles/{style}/{name}.json`.
|
|
78
|
+
|
|
79
|
+
Prefer `npx shadcn@latest registry add @acme` (or `@acme=https://acme.com/r/{name}.json`) over hand-editing this object.
|
|
80
|
+
|
|
81
|
+
```json
|
|
82
|
+
{
|
|
83
|
+
"registries": {
|
|
84
|
+
"@acme": "https://acme.com/r/{name}.json",
|
|
85
|
+
"@private": {
|
|
86
|
+
"url": "https://private.com/r/{name}.json",
|
|
87
|
+
"params": { "version": "2" },
|
|
88
|
+
"headers": { "Authorization": "Bearer ${MY_TOKEN}" }
|
|
89
|
+
}
|
|
90
|
+
}
|
|
91
|
+
}
|
|
92
|
+
```
|
|
93
|
+
|
|
94
|
+
- Names must start with `@`.
|
|
95
|
+
- URLs must contain `{name}`. `{style}` is also substituted, from `components.json`'s `style` (the full `<base>-<preset>`, e.g. `radix-nova`) — only use it if the registry really is style-segmented, or resolution will 404.
|
|
96
|
+
- Object form supports `url` (required), `params` (query string), and `headers`.
|
|
97
|
+
- `${VAR}` references are resolved from environment variables.
|
|
98
|
+
|
|
99
|
+
Community registry index: `https://ui.shadcn.com/r/registries.json`. Verify a template from that index actually resolves before trusting it — some entries publish a `{style}` URL whose items don't exist per-style.
|
|
100
|
+
|
|
101
|
+
Validate a registry you author with `npx shadcn@latest registry validate`.
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
import { spawnSync } from 'node:child_process';
|
|
3
|
+
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
|
4
|
+
import { homedir } from 'node:os';
|
|
5
|
+
import { dirname, join } from 'node:path';
|
|
6
|
+
import { fileURLToPath } from 'node:url';
|
|
7
|
+
|
|
8
|
+
const DAY_MS = 24 * 60 * 60 * 1000;
|
|
9
|
+
const WEEK_MS = 7 * DAY_MS;
|
|
10
|
+
const here = dirname(fileURLToPath(import.meta.url));
|
|
11
|
+
|
|
12
|
+
function readJson(path, fallback = {}) {
|
|
13
|
+
try { return JSON.parse(readFileSync(path, 'utf8')); } catch { return fallback; }
|
|
14
|
+
}
|
|
15
|
+
|
|
16
|
+
function frontmatterValue(text, key) {
|
|
17
|
+
const frontmatter = /^---\n([\s\S]*?)\n---/.exec(text)?.[1] ?? '';
|
|
18
|
+
const match = new RegExp('^' + key + ':\\s*([^\\n]+)$', 'm').exec(frontmatter);
|
|
19
|
+
return match?.[1].trim().replace(/^['"]|['"]$/g, '') ?? null;
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
function repositoryOf(source) {
|
|
23
|
+
const value = String(source ?? '').trim();
|
|
24
|
+
const match = /^(?:git@github\.com:|https:\/\/github\.com\/)?([A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+?)(?:\.git)?$/.exec(value);
|
|
25
|
+
return match?.[1] ?? null;
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
function stableVersion(value) {
|
|
29
|
+
const match = /^v?(\d+)\.(\d+)\.(\d+)$/.exec(String(value ?? '').trim());
|
|
30
|
+
return match ? match.slice(1).map(Number) : null;
|
|
31
|
+
}
|
|
32
|
+
|
|
33
|
+
function newer(left, right) {
|
|
34
|
+
for (let index = 0; index < 3; index += 1) {
|
|
35
|
+
if (left[index] !== right[index]) return left[index] > right[index];
|
|
36
|
+
}
|
|
37
|
+
return false;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
function writeCache(path, value) {
|
|
41
|
+
try {
|
|
42
|
+
mkdirSync(dirname(path), { recursive: true });
|
|
43
|
+
writeFileSync(path, JSON.stringify(value));
|
|
44
|
+
} catch { /* A read-only cache must not block skill use. */ }
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
function main(now = Date.now()) {
|
|
48
|
+
if (process.env.ONEABOVEIO_NO_UPDATE_CHECK) return;
|
|
49
|
+
const skill = readFileSync(join(here, 'SKILL.md'), 'utf8');
|
|
50
|
+
const name = frontmatterValue(skill, 'name');
|
|
51
|
+
const localVersion = stableVersion(frontmatterValue(skill, 'release-version'));
|
|
52
|
+
if (!name || !localVersion) return;
|
|
53
|
+
|
|
54
|
+
const lock = readJson(join(process.env.HOME || homedir(), '.agents', '.skill-lock.json'));
|
|
55
|
+
const entry = lock.skills?.[name];
|
|
56
|
+
const repository = repositoryOf(entry?.sourceUrl || entry?.source);
|
|
57
|
+
if (!repository) return;
|
|
58
|
+
|
|
59
|
+
const cacheRoot = process.env.XDG_CACHE_HOME || join(process.env.HOME || homedir(), '.cache');
|
|
60
|
+
const cachePath = join(cacheRoot, '1aboveio-skills', 'release-check.json');
|
|
61
|
+
const all = readJson(cachePath);
|
|
62
|
+
const cache = all[repository] && typeof all[repository] === 'object' ? all[repository] : {};
|
|
63
|
+
|
|
64
|
+
if (!cache.lastCheck || now - cache.lastCheck >= DAY_MS) {
|
|
65
|
+
const result = spawnSync('gh', ['api', 'repos/' + repository + '/releases/latest', '--jq', '.tag_name'], {
|
|
66
|
+
encoding: 'utf8',
|
|
67
|
+
stdio: ['ignore', 'pipe', 'ignore'],
|
|
68
|
+
timeout: 1500,
|
|
69
|
+
});
|
|
70
|
+
cache.lastCheck = now;
|
|
71
|
+
if (result.status === 0 && stableVersion(result.stdout)) cache.latestTag = result.stdout.trim();
|
|
72
|
+
else delete cache.latestTag;
|
|
73
|
+
all[repository] = cache;
|
|
74
|
+
writeCache(cachePath, all);
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const latestVersion = stableVersion(cache.latestTag);
|
|
78
|
+
if (!latestVersion || !newer(latestVersion, localVersion)) return;
|
|
79
|
+
if (cache.notifiedTag === cache.latestTag && cache.notifiedAt && now - cache.notifiedAt < WEEK_MS) return;
|
|
80
|
+
|
|
81
|
+
cache.notifiedTag = cache.latestTag;
|
|
82
|
+
cache.notifiedAt = now;
|
|
83
|
+
all[repository] = cache;
|
|
84
|
+
writeCache(cachePath, all);
|
|
85
|
+
const command = `npx skills@1.5.23 add '${repository}#${cache.latestTag}' --global --agent universal claude-code --skill ${name} --yes`;
|
|
86
|
+
process.stdout.write(
|
|
87
|
+
`UPDATE_AVAILABLE: A newer 1AboveIO skills release (${cache.latestTag}) is available; this skill is `
|
|
88
|
+
+ `v${localVersion.join('.')}. Ask once whether to refresh ${name}. On approval run \`${command}\`. `
|
|
89
|
+
+ 'The refreshed instructions apply next session. Either way, continue the current task and do not ask again this session.\n',
|
|
90
|
+
);
|
|
91
|
+
}
|
|
92
|
+
|
|
93
|
+
try { main(); } catch { /* Update checks are advisory and always fail silent. */ }
|
|
@@ -0,0 +1,323 @@
|
|
|
1
|
+
# Base vs Radix
|
|
2
|
+
|
|
3
|
+
API differences between `base` (Base UI) and `radix` (Radix UI). Check `config.base` from `npx shadcn@latest info`.
|
|
4
|
+
|
|
5
|
+
## Contents
|
|
6
|
+
|
|
7
|
+
- A third base: aria
|
|
8
|
+
- Composition: asChild vs render
|
|
9
|
+
- Button / trigger as non-button element
|
|
10
|
+
- Select (items prop, placeholder, positioning, multiple, object values)
|
|
11
|
+
- ToggleGroup (type vs multiple)
|
|
12
|
+
- Slider (scalar vs array)
|
|
13
|
+
- Accordion (type and defaultValue)
|
|
14
|
+
|
|
15
|
+
---
|
|
16
|
+
|
|
17
|
+
## A third base: `aria`
|
|
18
|
+
|
|
19
|
+
`config.base` can also be **`aria`** — components built on Adobe's [React Aria](https://react-aria.adobe.com). It's selected at init with `npx shadcn@latest init --base aria` and stored in `components.json` as `style: "aria-<preset>"`.
|
|
20
|
+
|
|
21
|
+
The rules below are documented for `base` and `radix` only and **do not describe the aria API**. When a project's base is `aria`, don't extrapolate from either column — pull the real API first:
|
|
22
|
+
|
|
23
|
+
```bash
|
|
24
|
+
npx shadcn@latest docs button select --base aria
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
Docs resolve to `https://ui.shadcn.com/docs/components/aria/<component>`, with an `api` link into the React Aria reference.
|
|
28
|
+
|
|
29
|
+
One aria-specific trap worth carrying: **don't use `<Button>` for links.** React Aria's `Button` always applies `role="button"`, which overrides the link semantics of an `<a>`. Use the `buttonVariants` helper on a plain `<a>` instead.
|
|
30
|
+
|
|
31
|
+
---
|
|
32
|
+
|
|
33
|
+
## Composition: asChild (radix) vs render (base)
|
|
34
|
+
|
|
35
|
+
Radix uses `asChild` to replace the default element. Base uses `render`. Don't wrap triggers in extra elements.
|
|
36
|
+
|
|
37
|
+
**Incorrect:**
|
|
38
|
+
|
|
39
|
+
```tsx
|
|
40
|
+
<DialogTrigger>
|
|
41
|
+
<div>
|
|
42
|
+
<Button>Open</Button>
|
|
43
|
+
</div>
|
|
44
|
+
</DialogTrigger>
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
**Correct (radix):**
|
|
48
|
+
|
|
49
|
+
```tsx
|
|
50
|
+
<DialogTrigger asChild>
|
|
51
|
+
<Button>Open</Button>
|
|
52
|
+
</DialogTrigger>
|
|
53
|
+
```
|
|
54
|
+
|
|
55
|
+
**Correct (base):**
|
|
56
|
+
|
|
57
|
+
```tsx
|
|
58
|
+
<DialogTrigger render={<Button />}>Open</DialogTrigger>
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
This applies to all trigger and close components: `DialogTrigger`, `SheetTrigger`, `AlertDialogTrigger`, `DropdownMenuTrigger`, `PopoverTrigger`, `TooltipTrigger`, `CollapsibleTrigger`, `DialogClose`, `SheetClose`, `NavigationMenuLink`, `BreadcrumbLink`, `SidebarMenuButton`, `Badge`, `Item`.
|
|
62
|
+
|
|
63
|
+
---
|
|
64
|
+
|
|
65
|
+
## Button / trigger as non-button element (base only)
|
|
66
|
+
|
|
67
|
+
When `render` changes an element to a non-button (`<a>`, `<span>`), add `nativeButton={false}`.
|
|
68
|
+
|
|
69
|
+
**Incorrect (base):** missing `nativeButton={false}`.
|
|
70
|
+
|
|
71
|
+
```tsx
|
|
72
|
+
<Button render={<a href="/docs" />}>Read the docs</Button>
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**Correct (base):**
|
|
76
|
+
|
|
77
|
+
```tsx
|
|
78
|
+
<Button render={<a href="/docs" />} nativeButton={false}>
|
|
79
|
+
Read the docs
|
|
80
|
+
</Button>
|
|
81
|
+
```
|
|
82
|
+
|
|
83
|
+
**Correct (radix):**
|
|
84
|
+
|
|
85
|
+
```tsx
|
|
86
|
+
<Button asChild>
|
|
87
|
+
<a href="/docs">Read the docs</a>
|
|
88
|
+
</Button>
|
|
89
|
+
```
|
|
90
|
+
|
|
91
|
+
Same for triggers whose `render` is not a `Button`:
|
|
92
|
+
|
|
93
|
+
```tsx
|
|
94
|
+
// base.
|
|
95
|
+
<PopoverTrigger render={<InputGroupAddon />} nativeButton={false}>
|
|
96
|
+
Pick date
|
|
97
|
+
</PopoverTrigger>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
---
|
|
101
|
+
|
|
102
|
+
## Select
|
|
103
|
+
|
|
104
|
+
**items prop (base only).** Base requires an `items` prop on the root. Radix uses inline JSX only.
|
|
105
|
+
|
|
106
|
+
**Incorrect (base):**
|
|
107
|
+
|
|
108
|
+
```tsx
|
|
109
|
+
<Select>
|
|
110
|
+
<SelectTrigger><SelectValue placeholder="Select a fruit" /></SelectTrigger>
|
|
111
|
+
</Select>
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
**Correct (base):**
|
|
115
|
+
|
|
116
|
+
```tsx
|
|
117
|
+
const items = [
|
|
118
|
+
{ label: "Select a fruit", value: null },
|
|
119
|
+
{ label: "Apple", value: "apple" },
|
|
120
|
+
{ label: "Banana", value: "banana" },
|
|
121
|
+
]
|
|
122
|
+
|
|
123
|
+
<Select items={items}>
|
|
124
|
+
<SelectTrigger>
|
|
125
|
+
<SelectValue />
|
|
126
|
+
</SelectTrigger>
|
|
127
|
+
<SelectContent>
|
|
128
|
+
<SelectGroup>
|
|
129
|
+
{items.map((item) => (
|
|
130
|
+
<SelectItem key={item.value} value={item.value}>{item.label}</SelectItem>
|
|
131
|
+
))}
|
|
132
|
+
</SelectGroup>
|
|
133
|
+
</SelectContent>
|
|
134
|
+
</Select>
|
|
135
|
+
```
|
|
136
|
+
|
|
137
|
+
**Correct (radix):**
|
|
138
|
+
|
|
139
|
+
```tsx
|
|
140
|
+
<Select>
|
|
141
|
+
<SelectTrigger>
|
|
142
|
+
<SelectValue placeholder="Select a fruit" />
|
|
143
|
+
</SelectTrigger>
|
|
144
|
+
<SelectContent>
|
|
145
|
+
<SelectGroup>
|
|
146
|
+
<SelectItem value="apple">Apple</SelectItem>
|
|
147
|
+
<SelectItem value="banana">Banana</SelectItem>
|
|
148
|
+
</SelectGroup>
|
|
149
|
+
</SelectContent>
|
|
150
|
+
</Select>
|
|
151
|
+
```
|
|
152
|
+
|
|
153
|
+
**Placeholder.** Base uses a `{ value: null }` item in the items array. Radix uses `<SelectValue placeholder="...">`.
|
|
154
|
+
|
|
155
|
+
**Content positioning.** Base uses `alignItemWithTrigger`. Radix uses `position`.
|
|
156
|
+
|
|
157
|
+
```tsx
|
|
158
|
+
// base.
|
|
159
|
+
<SelectContent alignItemWithTrigger={false} side="bottom">
|
|
160
|
+
|
|
161
|
+
// radix.
|
|
162
|
+
<SelectContent position="popper">
|
|
163
|
+
```
|
|
164
|
+
|
|
165
|
+
---
|
|
166
|
+
|
|
167
|
+
## Select — multiple selection and object values (base only)
|
|
168
|
+
|
|
169
|
+
Base supports `multiple`, render-function children on `SelectValue`, and object values with `itemToStringValue`. Radix is single-select with string values only.
|
|
170
|
+
|
|
171
|
+
**Correct (base — multiple selection):**
|
|
172
|
+
|
|
173
|
+
```tsx
|
|
174
|
+
<Select items={items} multiple defaultValue={[]}>
|
|
175
|
+
<SelectTrigger>
|
|
176
|
+
<SelectValue>
|
|
177
|
+
{(value: string[]) => value.length === 0 ? "Select fruits" : `${value.length} selected`}
|
|
178
|
+
</SelectValue>
|
|
179
|
+
</SelectTrigger>
|
|
180
|
+
...
|
|
181
|
+
</Select>
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
**Correct (base — object values):**
|
|
185
|
+
|
|
186
|
+
```tsx
|
|
187
|
+
<Select defaultValue={plans[0]} itemToStringValue={(plan) => plan.name}>
|
|
188
|
+
<SelectTrigger>
|
|
189
|
+
<SelectValue>{(value) => value.name}</SelectValue>
|
|
190
|
+
</SelectTrigger>
|
|
191
|
+
...
|
|
192
|
+
</Select>
|
|
193
|
+
```
|
|
194
|
+
|
|
195
|
+
---
|
|
196
|
+
|
|
197
|
+
## ToggleGroup
|
|
198
|
+
|
|
199
|
+
Base uses a `multiple` boolean prop. Radix uses `type="single"` or `type="multiple"`.
|
|
200
|
+
|
|
201
|
+
**Incorrect (base):**
|
|
202
|
+
|
|
203
|
+
```tsx
|
|
204
|
+
<ToggleGroup type="single" defaultValue="daily">
|
|
205
|
+
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
|
|
206
|
+
</ToggleGroup>
|
|
207
|
+
```
|
|
208
|
+
|
|
209
|
+
**Correct (base):**
|
|
210
|
+
|
|
211
|
+
```tsx
|
|
212
|
+
// Single (no prop needed), defaultValue is always an array.
|
|
213
|
+
<ToggleGroup defaultValue={["daily"]} spacing={2}>
|
|
214
|
+
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
|
|
215
|
+
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
|
|
216
|
+
</ToggleGroup>
|
|
217
|
+
|
|
218
|
+
// Multi-selection.
|
|
219
|
+
<ToggleGroup multiple>
|
|
220
|
+
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
|
|
221
|
+
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
|
|
222
|
+
</ToggleGroup>
|
|
223
|
+
```
|
|
224
|
+
|
|
225
|
+
**Correct (radix):**
|
|
226
|
+
|
|
227
|
+
```tsx
|
|
228
|
+
// Single, defaultValue is a string.
|
|
229
|
+
<ToggleGroup type="single" defaultValue="daily" spacing={2}>
|
|
230
|
+
<ToggleGroupItem value="daily">Daily</ToggleGroupItem>
|
|
231
|
+
<ToggleGroupItem value="weekly">Weekly</ToggleGroupItem>
|
|
232
|
+
</ToggleGroup>
|
|
233
|
+
|
|
234
|
+
// Multi-selection.
|
|
235
|
+
<ToggleGroup type="multiple">
|
|
236
|
+
<ToggleGroupItem value="bold">Bold</ToggleGroupItem>
|
|
237
|
+
<ToggleGroupItem value="italic">Italic</ToggleGroupItem>
|
|
238
|
+
</ToggleGroup>
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
**Controlled single value:**
|
|
242
|
+
|
|
243
|
+
```tsx
|
|
244
|
+
// base — wrap/unwrap arrays.
|
|
245
|
+
const [value, setValue] = React.useState("normal")
|
|
246
|
+
<ToggleGroup value={[value]} onValueChange={(v) => setValue(v[0])}>
|
|
247
|
+
|
|
248
|
+
// radix — plain string.
|
|
249
|
+
const [value, setValue] = React.useState("normal")
|
|
250
|
+
<ToggleGroup type="single" value={value} onValueChange={setValue}>
|
|
251
|
+
```
|
|
252
|
+
|
|
253
|
+
---
|
|
254
|
+
|
|
255
|
+
## Slider
|
|
256
|
+
|
|
257
|
+
Base accepts a plain number for a single thumb. Radix always requires an array.
|
|
258
|
+
|
|
259
|
+
**Incorrect (base):**
|
|
260
|
+
|
|
261
|
+
```tsx
|
|
262
|
+
<Slider defaultValue={[50]} max={100} step={1} />
|
|
263
|
+
```
|
|
264
|
+
|
|
265
|
+
**Correct (base):**
|
|
266
|
+
|
|
267
|
+
```tsx
|
|
268
|
+
<Slider defaultValue={50} max={100} step={1} />
|
|
269
|
+
```
|
|
270
|
+
|
|
271
|
+
**Correct (radix):**
|
|
272
|
+
|
|
273
|
+
```tsx
|
|
274
|
+
<Slider defaultValue={[50]} max={100} step={1} />
|
|
275
|
+
```
|
|
276
|
+
|
|
277
|
+
Both use arrays for range sliders. Controlled `onValueChange` in base may need a cast:
|
|
278
|
+
|
|
279
|
+
```tsx
|
|
280
|
+
// base.
|
|
281
|
+
const [value, setValue] = React.useState([0.3, 0.7])
|
|
282
|
+
<Slider value={value} onValueChange={(v) => setValue(v as number[])} />
|
|
283
|
+
|
|
284
|
+
// radix.
|
|
285
|
+
const [value, setValue] = React.useState([0.3, 0.7])
|
|
286
|
+
<Slider value={value} onValueChange={setValue} />
|
|
287
|
+
```
|
|
288
|
+
|
|
289
|
+
---
|
|
290
|
+
|
|
291
|
+
## Accordion
|
|
292
|
+
|
|
293
|
+
Radix requires `type="single"` or `type="multiple"` and supports `collapsible`. `defaultValue` is a string. Base uses no `type` prop, uses `multiple` boolean, and `defaultValue` is always an array.
|
|
294
|
+
|
|
295
|
+
**Incorrect (base):**
|
|
296
|
+
|
|
297
|
+
```tsx
|
|
298
|
+
<Accordion type="single" collapsible defaultValue="item-1">
|
|
299
|
+
<AccordionItem value="item-1">...</AccordionItem>
|
|
300
|
+
</Accordion>
|
|
301
|
+
```
|
|
302
|
+
|
|
303
|
+
**Correct (base):**
|
|
304
|
+
|
|
305
|
+
```tsx
|
|
306
|
+
<Accordion defaultValue={["item-1"]}>
|
|
307
|
+
<AccordionItem value="item-1">...</AccordionItem>
|
|
308
|
+
</Accordion>
|
|
309
|
+
|
|
310
|
+
// Multi-select.
|
|
311
|
+
<Accordion multiple defaultValue={["item-1", "item-2"]}>
|
|
312
|
+
<AccordionItem value="item-1">...</AccordionItem>
|
|
313
|
+
<AccordionItem value="item-2">...</AccordionItem>
|
|
314
|
+
</Accordion>
|
|
315
|
+
```
|
|
316
|
+
|
|
317
|
+
**Correct (radix):**
|
|
318
|
+
|
|
319
|
+
```tsx
|
|
320
|
+
<Accordion type="single" collapsible defaultValue="item-1">
|
|
321
|
+
<AccordionItem value="item-1">...</AccordionItem>
|
|
322
|
+
</Accordion>
|
|
323
|
+
```
|
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# Component Selection
|
|
2
|
+
|
|
3
|
+
Reach for an existing component before writing markup. Almost every "just a styled `div`" in a shadcn codebase is a component someone didn't know existed — and the hand-rolled version misses the states (focus, disabled, invalid, dark mode) that the real one already handles.
|
|
4
|
+
|
|
5
|
+
| Need | Use |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| Button/action | `Button` — variants: `default`, `outline`, `secondary`, `ghost`, `destructive`, `link` |
|
|
8
|
+
| Related buttons in a row | `ButtonGroup` (+ `ButtonGroupSeparator`, `ButtonGroupText`) |
|
|
9
|
+
| Form layout | `Field` family — see [forms.md](./forms.md) for the full export list |
|
|
10
|
+
| Form inputs | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
|
|
11
|
+
| Input with affix/button | `InputGroup` + `InputGroupInput` + `InputGroupAddon` / `InputGroupButton` / `InputGroupText` |
|
|
12
|
+
| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem` |
|
|
13
|
+
| List rows (not a table) | `Item` family — `ItemGroup`, `Item`, `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemActions` |
|
|
14
|
+
| Data display | `Table`, `Card`, `Badge`, `Avatar` — static/read-only only |
|
|
15
|
+
| Portal list/index page | **DiceUI DataTable** — the default there, not a bare `Table`. See [data-table.md](./data-table.md) |
|
|
16
|
+
| Navigation | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination` |
|
|
17
|
+
| Overlays | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation) |
|
|
18
|
+
| Feedback | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner` |
|
|
19
|
+
| Command palette | `Command` inside `Dialog` |
|
|
20
|
+
| Charts | `Chart` (wraps Recharts) |
|
|
21
|
+
| Layout | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible` |
|
|
22
|
+
| Empty states | `Empty` (+ `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent`) |
|
|
23
|
+
| Menus | `DropdownMenu`, `ContextMenu`, `Menubar` |
|
|
24
|
+
| Tooltips/info | `Tooltip`, `HoverCard`, `Popover` |
|
|
25
|
+
|
|
26
|
+
Not sure whether something exists? `npx shadcn@latest search @shadcn -q "<thing>"` answers it in one call — cheaper than building the wrong thing and cheaper than guessing.
|
|
27
|
+
|
|
28
|
+
## Key patterns
|
|
29
|
+
|
|
30
|
+
The handful of shapes that most often separate correct shadcn code from plausible-looking code. Edge cases live in the rule files linked from [SKILL.md](../SKILL.md#critical-rules).
|
|
31
|
+
|
|
32
|
+
```tsx
|
|
33
|
+
// Form layout: FieldGroup + Field, not div + Label.
|
|
34
|
+
<FieldGroup>
|
|
35
|
+
<Field>
|
|
36
|
+
<FieldLabel htmlFor="email">Email</FieldLabel>
|
|
37
|
+
<Input id="email" />
|
|
38
|
+
</Field>
|
|
39
|
+
</FieldGroup>
|
|
40
|
+
|
|
41
|
+
// Validation: data-invalid on Field, aria-invalid on the control, error in FieldError.
|
|
42
|
+
// FieldError carries role="alert"; FieldDescription is muted helper text and announces nothing.
|
|
43
|
+
<Field data-invalid={!!error}>
|
|
44
|
+
<FieldLabel htmlFor="email">Email</FieldLabel>
|
|
45
|
+
<Input id="email" aria-invalid={!!error} />
|
|
46
|
+
<FieldError>Enter a valid email address.</FieldError>
|
|
47
|
+
</Field>
|
|
48
|
+
|
|
49
|
+
// Icons in buttons: data-icon, no sizing classes — the component sizes its own icons.
|
|
50
|
+
<Button>
|
|
51
|
+
<SearchIcon data-icon="inline-start" />
|
|
52
|
+
Search
|
|
53
|
+
</Button>
|
|
54
|
+
|
|
55
|
+
// Spacing: gap-*, not space-y-*.
|
|
56
|
+
<div className="flex flex-col gap-4"> // correct
|
|
57
|
+
<div className="space-y-4"> // wrong
|
|
58
|
+
|
|
59
|
+
// Equal dimensions: size-*, not w-* h-*.
|
|
60
|
+
<Avatar className="size-10"> // correct
|
|
61
|
+
<Avatar className="w-10 h-10"> // wrong
|
|
62
|
+
|
|
63
|
+
// Status colors: Badge variants or semantic tokens, not raw colors.
|
|
64
|
+
// Badge has no `success` variant — an invalid one falls back silently.
|
|
65
|
+
<Badge variant="secondary">+20.1%</Badge> // correct
|
|
66
|
+
<span className="text-emerald-600">+20.1%</span> // wrong
|
|
67
|
+
```
|