mmtaee/ocserv-dashboard/shadcn-vue

shadcn-vue

A framework for building ui, components and design systems. Components are added as source code to the user's project via the CLI.

IMPORTANT: Run all CLI commands using the project's package runner: npx shadcn-vue@latest, pnpm dlx shadcn-vue@latest, or bunx --bun shadcn-vue@latest — based on the project's packageManager. Examples below use npx shadcn-vue@latest but substitute the correct runner for the project.

Current Project Context

!`npx shadcn-vue@latest info --json`

The JSON above contains the project config and installed components. Use npx shadcn-vue@latest docs <component> to get documentation and example URLs for any component.

Principles

1. Use existing components first. Use npx shadcn-vue@latest search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. Dashboard = Sidebar + Card + Chart + Table.
3. Use built-in variants before custom styles. variant="outline", size="sm", etc.
4. Use semantic colors. bg-primary, text-muted-foreground — never raw values like bg-blue-500.

Critical Rules

These rules are always enforced. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• `class` for layout, not styling. Never override component colors or typography.
• No `space-x-*` or `space-y-*`. Use flex with gap-*. For vertical stacks, flex flex-col gap-*.
• Use `size-*` when width and height are equal. size-10 not w-10 h-10.
• Use `truncate` shorthand. Not overflow-hidden text-ellipsis whitespace-nowrap.
• No manual `dark:` color overrides. Use semantic tokens (bg-background, text-muted-foreground).
• Use `cn()` for conditional classes. Don't write manual template literal ternaries.
• No manual `z-index` on overlay components. Dialog, Sheet, Popover, etc. handle their own stacking.

Forms & Inputs → forms.md

• Forms use `FieldGroup` + `Field`. Never use raw div with space-y-* or grid gap-* for form layout.
• `InputGroup` uses `InputGroupInput`/`InputGroupTextarea`. Never raw Input/Textarea inside InputGroup.
• Buttons inside inputs use `InputGroup` + `InputGroupAddon`.
• Option sets (2–7 choices) use `ToggleGroup`. Don't loop Button with manual active state.
• `FieldSet` + `FieldLegend` for grouping related checkboxes/radios. Don't use a div with a heading.
• Field validation uses `data-invalid` + `aria-invalid`. data-invalid on Field, aria-invalid on the control. For disabled: data-disabled on Field, disabled on the control.

Component Structure → composition.md

• Items always inside their Group. SelectItem → SelectGroup. DropdownMenuItem → DropdownMenuGroup. CommandItem → CommandGroup.
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use class="sr-only" if visually hidden.
• Use full Card composition. CardHeader/CardTitle/CardDescription/CardContent/CardFooter. Don't dump everything in CardContent.
• Button has no `isPending`/`isLoading`. Compose with Spinner + data-icon + disabled.
• `TabsTrigger` must be inside `TabsList`. Never render triggers directly in Tabs.
• `Avatar` always needs `AvatarFallback`. For when the image fails to load.

Use Components, Not Custom Markup → composition.md

• Use existing components before custom markup. Check if a component exists before writing a styled div.
• Callouts use `Alert`. Don't build custom styled divs.
• Empty states use `Empty`. Don't build custom empty state markup.
• Toast via `vue-sonner`. Use toast() from vue-sonner.
• Use `Separator` instead of <hr> or <div class="border-t">.
• Use `Skeleton` for loading placeholders. No custom animate-pulse divs.
• Use `Badge` instead of custom styled spans.

Icons → icons.md

• Icons in `Button` use `data-icon`. data-icon="inline-start" or data-icon="inline-end" on the icon.
• No sizing classes on icons inside components. Components handle icon sizing via CSS. No size-4 or w-4 h-4.
• Pass icons as objects, not string keys. :icon="CheckIcon", not a string lookup.

CLI

• Apply preset codes directly with the CLI. Use npx shadcn-vue@latest apply <code> for existing projects, or npx shadcn-vue@latest init --preset <code> when initializing.

Key Patterns

These are the most common patterns that differentiate correct shadcn-vue code. For edge cases, see the linked rule files above.

<!-- Form layout: FieldGroup + Field, not div + Label. -->
<FieldGroup>
  <Field>
    <FieldLabel for="email">Email</FieldLabel>
    <input id="email" />
  </Field>
</FieldGroup>
 
<!-- Validation: data-invalid on Field, aria-invalid on the control. -->
<Field data-invalid>
  <FieldLabel>Email</FieldLabel>
  <input aria-invalid />
  <FieldDescription>Invalid email.</FieldDescription>
</Field>
 
<!-- Icons in buttons: data-icon, no sizing classes. -->
<button>
  <SearchIcon data-icon="inline-start" />
  Search
</button>
 
<!-- Spacing: gap-*, not space-y-*. -->
<div class="flex flex-col gap-4">
  <!-- correct -->
  <div class="space-y-4">
    <!-- wrong -->
 
    <!-- Equal dimensions: size-*, not w-* h-*. -->
    <Avatar class="size-10">
      <!-- correct -->
      <Avatar class="w-10 h-10">
        <!-- wrong -->
 
        <!-- Status colors: Badge variants or semantic tokens, not raw colors. -->
        <Badge variant="secondary">+20.1%</Badge>
        <!-- correct -->
        <span class="text-emerald-600">+20.1%</span>
        <!-- wrong --></Avatar
      ></Avatar
    >
  </div>
</div>

Component Selection

Key Fields

The injected project context contains these key fields:

• `aliases` → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• `tailwindVersion` → "v4" uses @theme inline blocks; "v3" uses tailwind.config.js.
• `tailwindCssFile` → the global CSS file where custom CSS variables are defined. Always edit this file, never create a new one.
• `style` → component visual treatment (e.g. nova, vega).
• `base` → primitive library (reka). Affects component APIs and available props.
• `iconLibrary` → determines icon imports. Use @lucide/vue for lucide, @tabler/icons-vue for tabler, etc. Never assume @lucide/vue.
• `resolvedPaths` → exact file-system destinations for components, utils, hooks, etc.
• `framework` → routing and file conventions (e.g. Nuxt vs Vite SPA).
• `packageManager` → use this for any non-shadcn-vue dependency installs (e.g. pnpm add date-fns vs npm install date-fns).

See cli.md — `info` command for the full field reference.

Component Docs, Examples, and Usage

Run npx shadcn-vue@latest docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

npx shadcn-vue@latest docs button dialog select

When creating, fixing, debugging, or using a component, always run `npx shadcn-vue@latest docs` and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow