@1aboveio/app-dev-skills 0.0.0-stage → 0.1.1

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.
Files changed (89) hide show
  1. package/README.md +30 -2
  2. package/package.json +34 -4
  3. package/skills/airflow/LICENSE +3 -0
  4. package/skills/airflow/SKILL.md +199 -0
  5. package/skills/airflow/release-check.mjs +93 -0
  6. package/skills/android-foundation/LICENSE +3 -0
  7. package/skills/android-foundation/SKILL.md +192 -0
  8. package/skills/android-foundation/assets/android-ci-job.yml +217 -0
  9. package/skills/android-foundation/references/ci.md +87 -0
  10. package/skills/android-foundation/references/gotchas.md +221 -0
  11. package/skills/android-foundation/references/setup.md +164 -0
  12. package/skills/android-foundation/release-check.mjs +93 -0
  13. package/skills/android-foundation/scripts/device-run.sh +176 -0
  14. package/skills/android-foundation/scripts/device-run.test.mjs +172 -0
  15. package/skills/app-debug/LICENSE +3 -0
  16. package/skills/app-debug/SKILL.md +110 -0
  17. package/skills/app-debug/references/common-errors.md +128 -0
  18. package/skills/app-debug/release-check.mjs +93 -0
  19. package/skills/better-auth/LICENSE +3 -0
  20. package/skills/better-auth/SKILL.md +598 -0
  21. package/skills/better-auth/references/feishu-api.md +270 -0
  22. package/skills/better-auth/release-check.mjs +93 -0
  23. package/skills/data-catalog/LICENSE +3 -0
  24. package/skills/data-catalog/SKILL.md +207 -0
  25. package/skills/data-catalog/agents/openai.yaml +3 -0
  26. package/skills/data-catalog/references/data-catalog-conventions.md +76 -0
  27. package/skills/data-catalog/references/field-definitions.md +123 -0
  28. package/skills/data-catalog/references/format.md +130 -0
  29. package/skills/data-catalog/release-check.mjs +93 -0
  30. package/skills/data-catalog/scripts/data-catalog.test.mjs +36 -0
  31. package/skills/data-catalog/scripts/data_catalog.py +1435 -0
  32. package/skills/data-catalog/scripts/persist-conventions-core.mjs +117 -0
  33. package/skills/data-catalog/scripts/persist-conventions.mjs +17 -0
  34. package/skills/data-catalog/scripts/test_data_catalog.py +603 -0
  35. package/skills/ios-foundation/LICENSE +3 -0
  36. package/skills/ios-foundation/SKILL.md +184 -0
  37. package/skills/ios-foundation/references/setup.md +243 -0
  38. package/skills/ios-foundation/release-check.mjs +93 -0
  39. package/skills/monorepo/LICENSE +3 -0
  40. package/skills/monorepo/SKILL.md +462 -0
  41. package/skills/monorepo/release-check.mjs +93 -0
  42. package/skills/nextjs-fullstack/LICENSE +3 -0
  43. package/skills/nextjs-fullstack/SKILL.md +211 -0
  44. package/skills/nextjs-fullstack/conventions.md +318 -0
  45. package/skills/nextjs-fullstack/frontend-conventions.md +61 -0
  46. package/skills/nextjs-fullstack/nextjs16.md +287 -0
  47. package/skills/nextjs-fullstack/release-check.mjs +93 -0
  48. package/skills/nextjs-fullstack/server-actions.md +409 -0
  49. package/skills/prisma-setup/LICENSE +3 -0
  50. package/skills/prisma-setup/SKILL.md +181 -0
  51. package/skills/prisma-setup/nextjs.md +258 -0
  52. package/skills/prisma-setup/release-check.mjs +93 -0
  53. package/skills/prisma-setup/turborepo.md +301 -0
  54. package/skills/pyspark/LICENSE +3 -0
  55. package/skills/pyspark/SKILL.md +127 -0
  56. package/skills/pyspark/assets/templates/etl.py +748 -0
  57. package/skills/pyspark/assets/templates/utils/__init__.py +1 -0
  58. package/skills/pyspark/assets/templates/utils/hudi_metadata.py +14 -0
  59. package/skills/pyspark/references/diagnosis-and-profiling.md +169 -0
  60. package/skills/pyspark/references/etl-contract.md +129 -0
  61. package/skills/pyspark/references/production-validation.md +131 -0
  62. package/skills/pyspark/references/reconciliation.md +38 -0
  63. package/skills/pyspark/references/transformation-design.md +190 -0
  64. package/skills/pyspark/references/velocity-feature-calculation.md +193 -0
  65. package/skills/pyspark/release-check.mjs +93 -0
  66. package/skills/pyspark/scripts/spark_eventlog_summary.py +223 -0
  67. package/skills/python-backend/LICENSE +3 -0
  68. package/skills/python-backend/SKILL.md +325 -0
  69. package/skills/python-backend/assets/uv-install.sh +48 -0
  70. package/skills/python-backend/references/uv-installs.md +83 -0
  71. package/skills/python-backend/release-check.mjs +93 -0
  72. package/skills/shadcn/LICENSE +3 -0
  73. package/skills/shadcn/SKILL.md +120 -0
  74. package/skills/shadcn/assets/shadcn-small.png +0 -0
  75. package/skills/shadcn/assets/shadcn.png +0 -0
  76. package/skills/shadcn/cli.md +411 -0
  77. package/skills/shadcn/customization.md +224 -0
  78. package/skills/shadcn/mcp.md +101 -0
  79. package/skills/shadcn/release-check.mjs +93 -0
  80. package/skills/shadcn/rules/base-vs-radix.md +323 -0
  81. package/skills/shadcn/rules/component-selection.md +67 -0
  82. package/skills/shadcn/rules/composition.md +195 -0
  83. package/skills/shadcn/rules/data-table.md +201 -0
  84. package/skills/shadcn/rules/forms.md +255 -0
  85. package/skills/shadcn/rules/icons.md +103 -0
  86. package/skills/shadcn/rules/styling.md +167 -0
  87. package/skills/zod-v4/LICENSE +3 -0
  88. package/skills/zod-v4/SKILL.md +286 -0
  89. 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
+ ```