shadcn-ui

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

1. Use project vars, never raw hex — the project has ~80 --workspace-* and --editor-* CSS variables; use them. See project-ui-reference.md.
2. Use installed components — check the installed list in project-ui-reference.md before adding a new component via CLI.
3. Preserve editor identity — the CodeMirror surface has its own visual system. Improve shell around it; do not restyle it.
4. Component-hooks model — see component-hooks-model.md for how to wire stateful UI to the Zustand workspace store.
5. Calm productivity UI — see component-preferences.md and windows-11-ui-guidelines.md for visual direction.
6. Minimal diff — replace/improve existing UI patterns; do not create parallel custom systems.

Implementation steps

If adding a new feature panel or tab

1. Read project-ui-reference.md → installed components + CSS vars.
2. Read component-hooks-model.md → store integration pattern.
3. Read component-preferences.md → which primitives fit the use case.
4. Implement using installed components + project CSS vars.
5. Wire store state via granular selectors — not by destructuring the full store.

If restyling or improving existing UI

1. Read project-ui-reference.md → understand existing shell classes before adding new ones.
2. Read windows-11-ui-guidelines.md → visual direction.
3. Prefer editing existing classes over adding new ones.
4. 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.