hamedmp/matrix-os/shadcn

shadcn/ui

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

Matrix integration

Use this pack when the app uses shadcn or the user requests it. Read only the relevant CLI, customization, preset, chart and rule resources. The skill is documentation: it does not execute commands, install an MCP server, grant access, or supply project context automatically.

Generated Matrix products remain Vite/React/TypeScript with manifests and owner Postgres via window.MatrixOS.db. Preserve bridge, sandbox and responsive contracts. Use a coherent app-local style and semantic tokens; platform chrome/auth/billing keeps the shared Matrix brand. Use local/bundled fonts and icons; registry assets or font imports need review for CSP compatibility. Charts and dashboards need a real task and saved data, never decorative sample metrics.

Matrix uses pnpm only. In every example, replace VERSION with the explicitly selected reviewed CLI version that satisfies the project's minimum release age and registry policy; it is not a runnable version literal. Recheck eligible versions before use, inspect current docs and CLI help for that version, and record the exact choice. Never resolve an unreviewed latest tag implicitly. Run pnpm install from the project root after dependencies change and retain its lockfile. See Presets for the dated verification and preservation workflow.

Current project context

Read the existing package manifest, lockfile, components.json, CSS and local UI sources before using tools. If the active run permits CLI access, pnpm dlx shadcn@VERSION info --json can discover actual aliases, primitive base, styles and installed components. No context is injected by this skill. If CLI/network access is absent, report that limitation and inspect local sources; do not claim a fresh upstream check.

Principles

1. Use existing components first. Use pnpm dlx shadcn@VERSION search to check registries before writing custom UI. Check community registries too.
2. Compose, don't reinvent. Settings page = Tabs + Card + form controls. A real data overview may combine Sidebar, Chart and Table; do not add a dashboard or card to every product.
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

Apply these composition rules to compatible installed component APIs. Check the actual primitive base and version before adapting older projects. Each links to a file with Incorrect/Correct code pairs.

Styling & Tailwind → styling.md

• `className` 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.
• Use `asChild` (radix) or `render` (base) for custom triggers. Check base field from pnpm dlx shadcn@VERSION info. → base-vs-radix.md
• Dialog, Sheet, and Drawer always need a Title. DialogTitle, SheetTitle, DrawerTitle required for accessibility. Use className="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 `sonner`. Use toast() from sonner.
• Use `Separator` instead of <hr> or <div className="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

• Never decode or fetch preset codes manually. Pass them directly to pnpm dlx shadcn@VERSION init --preset <code>.

Key Patterns

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

// Form layout: FieldGroup + Field, not div + Label.
<FieldGroup>
  <Field>
    <FieldLabel htmlFor="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 className="flex flex-col gap-4">  // correct
<div className="space-y-4">           // wrong
// Equal dimensions: size-*, not w-* h-*.
<Avatar className="size-10">   // correct
<Avatar className="w-10 h-10"> // wrong
// Status colors: Badge variants or semantic tokens, not raw colors.
<Badge variant="secondary">+20.1%</Badge>    // correct
<span className="text-emerald-600">+20.1%</span> // wrong

Component Selection

Key Fields

The inspected project context contains these key fields:

• `aliases` → use the actual alias prefix for imports (e.g. @/, ~/), never hardcode.
• `isRSC` → when true, components using useState, useEffect, event handlers, or browser APIs need "use client" at the top of the file. Always reference this field when advising on the directive.
• `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 (radix or base). Affects component APIs and available props.
• `iconLibrary` → determines icon imports. Use lucide-react for lucide, @tabler/icons-react for tabler, etc. Never assume lucide-react.
• `resolvedPaths` → exact file-system destinations for components, utils, hooks, etc.
• `framework` → routing and file conventions (e.g. Next.js App Router vs Vite SPA).
• `packageManager` → inspect project context; Matrix installs use pnpm (e.g. pnpm add date-fns).

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

Component Docs, Examples, and Usage

Run pnpm dlx shadcn@VERSION docs <component> to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.

pnpm dlx shadcn@VERSION docs button dialog select

When creating, fixing, debugging, or using a component and permitted tools are available, run `pnpm dlx shadcn@VERSION docs` and fetch the URLs first. This ensures you're working with the correct API and usage patterns rather than guessing.

Workflow