| name | shadcn-ui |
| description | Use this skill for any UI work in numpad — shadcn components, theming, shell layout, feature UI, settings dialogs, inspector panels, or Windows 11-like desktop productivity styling. |
shadcn-ui skill
Use this skill when the task involves: feature UI with shadcn primitives, app shell improvements, settings/dialog/sheet UI, theming, CSS variables, or Tailwind styling in this project.
Project-specific setup facts — read before touching any UI
shadcn is already installed. Do not re-install.
| Fact | Value |
|---|
| Framework | React 18 + Vite |
| Tailwind | v4 — config is in vite.config.ts, not tailwind.config.js |
| Global CSS | src/shared/ui/global.css |
| shadcn component path | src/shared/ui/components/<name>.tsx |
| Import alias | @/shared/ui/components/<name> |
| Icon library | lucide-react |
| Font sans | var(--app-font-sans) → "Noto Sans" |
| Font mono | var(--app-font-mono) → "Noto Sans Mono" |
components.json | Root of repo — tailwind.config is blank (Tailwind v4) |
Always read project-ui-reference.md first — it contains the installed component list, all custom CSS variables, and the shell class system. This is the most important companion file.
Core rules
- Use project vars, never raw hex — the project has ~80
--workspace-* and --editor-* CSS variables; use them. See project-ui-reference.md.
- Use installed components — check the installed list in
project-ui-reference.md before adding a new component via CLI.
- Preserve editor identity — the CodeMirror surface has its own visual system. Improve shell around it; do not restyle it.
- Component-hooks model — see
component-hooks-model.md for how to wire stateful UI to the Zustand workspace store.
- Calm productivity UI — see
component-preferences.md and windows-11-ui-guidelines.md for visual direction.
- Minimal diff — replace/improve existing UI patterns; do not create parallel custom systems.
Implementation steps
If adding a new feature panel or tab
- Read
project-ui-reference.md → installed components + CSS vars.
- Read
component-hooks-model.md → store integration pattern.
- Read
component-preferences.md → which primitives fit the use case.
- Implement using installed components + project CSS vars.
- Wire store state via granular selectors — not by destructuring the full store.
If restyling or improving existing UI
- Read
project-ui-reference.md → understand existing shell classes before adding new ones.
- Read
windows-11-ui-guidelines.md → visual direction.
- Prefer editing existing classes over adding new ones.
- Prefer semantic token classes (
bg-muted, text-muted-foreground) over project-specific vars in Tailwind utilities.
If fixing broken styles or imports
- Wrong styles → check
components.json, check src/shared/ui/global.css CSS var definitions.
- Broken imports → check
tsconfig.app.json alias (@ → ./src), check actual file path under src/shared/ui/components/.
- Token not applying → check if
@theme inline block in global.css maps the var to a Tailwind color.
Companion files — use in order
| File | When to read |
|---|
project-ui-reference.md | Always first — installed components, CSS vars, shell classes |
component-hooks-model.md | When adding stateful UI, dialogs with store state, new panels |
component-preferences.md | When choosing which shadcn primitive fits the use case |
windows-11-ui-guidelines.md | When improving shell, panels, or overall visual polish on Windows |
macos-ui-guidelines.md | When building/fixing UI that runs on macOS — popup safe zone, menu bar, window constraints |
migration-checklist.md | When replacing prototype UI or doing a broader shell refactor |
Validation
npm run typecheck && npm run build && npm run lint
Also verify: no broken import aliases, no duplicate component files, dark/light theme behavior correct, keyboard/focus behavior intact for dialogs/sheets/dropdowns.
