@exxatdesignux/ui 0.5.10 → 0.5.12

package/{template/app/(app)/library/layout.tsx → template-vite/src/pages/library/_layout.tsx}

@@ -1,7 +1,5 @@
-"use client"
-
 import * as React from "react"
-import { usePathname } from "next/navigation"
+import { Outlet, useLocation } from "react-router-dom"
 
 import { useSecondaryPanel } from "@/components/sidebar"
 import {
@@ -14,36 +12,36 @@ import {
 const LIBRARY_FOCUSED_FLOW_PATHS: readonly string[] = ["/library/new"]
 
 function isLibraryFocusedFlow(pathname: string): boolean {
-  return LIBRARY_FOCUSED_FLOW_PATHS.some(p => pathname === p || pathname.startsWith(`${p}/`))
+  return LIBRARY_FOCUSED_FLOW_PATHS.some(
+    p => pathname === p || pathname.startsWith(`${p}/`),
+  )
 }
 
 /**
  * Keeps the nested secondary panel open across library navigations.
- * **Question hub** (`/library`), **Search** (`/find`, `/list`), and
- * focused authoring routes (`/new`) stay full-width — no secondary rail.
+ * Hub root, dedicated search surfaces, and focused authoring stay full-width.
+ *
+ * Mirrors the Next `app/(app)/library/layout.tsx` 1:1 — only the
+ * `usePathname` import comes from `react-router-dom` instead of
+ * `next/navigation`, and `<Outlet />` replaces the `children` prop.
  */
-export default function LibraryLayout({ children }: { children: React.ReactNode }) {
-  const pathname = usePathname()
+export function LibraryLayout() {
+  const { pathname } = useLocation()
   const { openPanel, closePanel, activePanel } = useSecondaryPanel()
   const closePanelRef = React.useRef(closePanel)
   const openPanelRef = React.useRef(openPanel)
-  // "Latest ref" pattern — keep callbacks current without re-running the
-  // route effect below on every render. `useEffect` (no deps) updates the
-  // refs after each render; React's `refs` rule disallows direct ref writes
-  // during render so the assignment lives here instead.
+
   React.useEffect(() => {
     closePanelRef.current = closePanel
     openPanelRef.current = openPanel
   })
 
-  /** Leaving `/library/*` entirely — close nested panel without forcing primary sidebar open (⌘B / cookie). */
   React.useEffect(() => {
     return () => {
       closePanelRef.current({ mainSidebar: "leave" })
     }
   }, [])
 
-  /** Only react to route changes — refs carry latest open/close. */
   React.useEffect(() => {
     const isDiscoveryHubRoot =
       pathname === LIBRARY_ENTRY_PATH || pathname === `${LIBRARY_ENTRY_PATH}/`
@@ -51,7 +49,11 @@ export default function LibraryLayout({ children }: { children: React.ReactNode
     const isDedicatedSearchSurface =
       pathname === LIBRARY_HUB_FIND_PATH || pathname === LIBRARY_LIST_PATH
 
-    if (isDiscoveryHubRoot || isDedicatedSearchSurface || isLibraryFocusedFlow(pathname)) {
+    if (
+      isDiscoveryHubRoot ||
+      isDedicatedSearchSurface ||
+      isLibraryFocusedFlow(pathname)
+    ) {
       closePanelRef.current({ mainSidebar: "leave" })
       return undefined
     }
@@ -62,5 +64,5 @@ export default function LibraryLayout({ children }: { children: React.ReactNode
     return undefined
   }, [pathname, activePanel])
 
-  return children
+  return <Outlet />
 }

package/{template/app/(app)/library/all/page.tsx → template-vite/src/pages/library/all.tsx}

@@ -2,7 +2,7 @@ import { Suspense } from "react"
 
 import { LibraryClient } from "@/components/library-client"
 
-export default function LibraryLibraryPage() {
+export default function LibraryAllPage() {
   return (
     <Suspense fallback={null}>
       <LibraryClient />

package/{template/app/(app)/library/new/page.tsx → template-vite/src/pages/library/new.tsx}

@@ -1,14 +1,4 @@
-/**
- * `/library/new` — focused authoring page for a new question.
- *
- * The composer (`NewLibraryItemForm`) owns the `NewFocusTemplate` (form-inspector
- * variant) underneath. This route file is intentionally thin so the same composer
- * can be mounted from other entry points (deep-link, command palette).
- *
- * Folder pre-selection: callers may pass `?folderId=<id>` so users dropped into
- * the composer from a folder-scoped library land with that folder pre-selected
- * in the metadata rail.
- */
+import { useSearchParams } from "react-router-dom"
 
 import { NewLibraryItemForm } from "@/components/new-library-item-form"
 import {
@@ -18,15 +8,19 @@ import {
 import { generateDraftQuestionId } from "@/lib/library-authoring"
 import { newQuestionBackNav } from "@/lib/library-nav"
 
-interface NewQuestionPageProps {
-  searchParams: Promise<{ folderId?: string }>
-}
-
-export default async function NewQuestionPage({ searchParams }: NewQuestionPageProps) {
-  const params = await searchParams
+/**
+ * `/library/new` — focused authoring page for a new question.
+ *
+ * Reads `?folderId=<id>` from the URL via `useSearchParams` (RR DOM
+ * v7 — same shape as the Next equivalent). The Next variant used the
+ * Next 15 async server-component `searchParams: Promise<...>` API; in
+ * the Vite SPA we read params synchronously on every render.
+ */
+export default function NewQuestionPage() {
+  const [searchParams] = useSearchParams()
   const folders: LibraryFolder[] = DEFAULT_LIBRARY_FOLDERS
 
-  const requested = typeof params.folderId === "string" ? params.folderId : undefined
+  const requested = searchParams.get("folderId") ?? undefined
   const matched = requested ? folders.find(f => f.id === requested) : undefined
   const defaultFolderId = matched?.id
 

package/template-vite/src/routes.tsx

@@ -0,0 +1,72 @@
+import { Suspense, lazy } from "react"
+import { Navigate, type RouteObject } from "react-router-dom"
+
+import { LoadingFallback } from "./pages/_loading"
+import { RouteError } from "./pages/_error"
+import { LibraryLayout } from "./pages/library/_layout"
+
+/**
+ * Route table — mirrors the Next `app/(app)/...` filesystem routes 1:1.
+ *
+ * Lazy-load each leaf so the initial bundle is small (mirrors what
+ * `next/dynamic` did on the Next side). `<Suspense>` shows the same
+ * skeleton fallback the Next loading.tsx files used.
+ *
+ * Every route is wrapped by `App` in main.tsx (sidebar, providers,
+ * command menu). Library routes get an extra `LibraryLayout` shell
+ * that drives the secondary panel — same as the Next library/layout.tsx.
+ */
+
+const lazyPage = (loader: () => Promise<{ default: React.ComponentType }>) => {
+  const Lazy = lazy(loader)
+  return (
+    <Suspense fallback={<LoadingFallback />}>
+      <Lazy />
+    </Suspense>
+  )
+}
+
+export const routes: RouteObject[] = [
+  { index: true, element: <Navigate to="/dashboard" replace /> },
+  {
+    path: "dashboard",
+    element: lazyPage(() => import("./pages/dashboard")),
+    errorElement: <RouteError />,
+  },
+  {
+    path: "library",
+    element: <LibraryLayout />,
+    errorElement: <RouteError />,
+    children: [
+      { index: true, element: lazyPage(() => import("./pages/library/index")) },
+      { path: "all", element: lazyPage(() => import("./pages/library/all")) },
+      { path: "find", element: lazyPage(() => import("./pages/library/find")) },
+      { path: "list", element: lazyPage(() => import("./pages/library/list")) },
+      { path: "new", element: lazyPage(() => import("./pages/library/new")) },
+    ],
+  },
+  {
+    path: "columns",
+    element: lazyPage(() => import("./pages/columns")),
+    errorElement: <RouteError />,
+  },
+  {
+    path: "tokens-themes",
+    element: lazyPage(() => import("./pages/tokens-themes")),
+    errorElement: <RouteError />,
+  },
+  {
+    path: "settings",
+    element: lazyPage(() => import("./pages/settings")),
+    errorElement: <RouteError />,
+  },
+  {
+    path: "help",
+    element: lazyPage(() => import("./pages/help")),
+    errorElement: <RouteError />,
+  },
+  {
+    path: "*",
+    element: lazyPage(() => import("./pages/_not-found")),
+  },
+]

package/{template/app → template-vite/src/styles}/globals.css

@@ -16,5 +16,9 @@
 
 @import "@exxatdesignux/ui/globals.css";
 
-/* Ensure Tailwind scans the shared UI package for utility classes (repo-relative — stable with pnpm + Turbopack). */
-@source "../node_modules/@exxatdesignux/ui/src";
+/* Ensure Tailwind scans the shared UI package for utility classes (repo-relative — stable with pnpm + Vite). */
+@source "../../node_modules/@exxatdesignux/ui/src";
+
+/* Designer template lives at src/styles/globals.css (one level deeper than
+   Next's app/globals.css), so @source needs an extra `..` to reach the
+   consumer's node_modules from this file's location. */

package/{template → template-vite}/tsconfig.json

@@ -14,23 +14,14 @@
     "allowImportingTsExtensions": true,
     "jsx": "react-jsx",
     "incremental": true,
-    "assumeChangesOnlyAffectDirectDependencies": true,
-    "plugins": [
-      {
-        "name": "next"
-      }
-    ],
+    "useDefineForClassFields": true,
+    "verbatimModuleSyntax": false,
+    "types": ["vite/client", "node"],
     "baseUrl": ".",
     "paths": {
       "@/*": ["./*"]
     }
   },
-  "include": [
-    "next-env.d.ts",
-    "**/*.ts",
-    "**/*.tsx",
-    ".next/types/**/*.ts",
-    ".next/dev/types/**/*.ts"
-  ],
-  "exclude": ["node_modules"]
+  "include": ["**/*.ts", "**/*.tsx"],
+  "exclude": ["node_modules", "dist"]
 }

package/template-vite/vite.config.ts

@@ -0,0 +1,52 @@
+import { defineConfig } from "vite"
+import react from "@vitejs/plugin-react"
+import tailwindcss from "@tailwindcss/vite"
+import path from "node:path"
+
+/**
+ * Vite config — lightweight designer stack for the Exxat DS template.
+ *
+ * Why Vite over Next.js for designers:
+ *  - Cold start ~300–500 ms vs 8–12 s with Next + Turbopack
+ *  - Resident memory ~250–400 MB vs 1.4–4 GB with Next dev server
+ *  - HMR is instant; no server-component reload
+ *  - Lower barrier for designer prototyping
+ *
+ * The DS itself (`@exxatdesignux/ui`) and the local components/, hooks/,
+ * lib/, contexts/ folders are framework-agnostic React — they work
+ * identically here as they do under Next in the legacy `template/`.
+ *
+ * Engineers porting designer prototypes to a Next-target production app
+ * follow the checklist in `consumer-extras/templates/handoff.md` —
+ * mostly mechanical swaps for `Link`, `useNavigate`, `useLocation`.
+ */
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss(),
+  ],
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "."),
+    },
+  },
+  css: {
+    /**
+     * Tailwind v4 + `@tailwindcss/vite` does not require postcss. We
+     * explicitly opt out of postcss config discovery so Vite does not
+     * walk up the workspace tree and pick up the parent
+     * `packages/ui/postcss.config.mjs`, which in this monorepo pins a
+     * native lightningcss binary that may be missing per-platform.
+     */
+    postcss: { plugins: [] },
+    transformer: "postcss",
+  },
+  server: {
+    port: 3000,
+    strictPort: false,
+  },
+  build: {
+    outDir: "dist",
+    sourcemap: true,
+  },
+})

package/consumer-extras/cursor-rules/exxat-dashboard-view-charts.mdc

@@ -1,53 +0,0 @@
----
-description: Data view dashboard — centralized charts, storage, keyboard parity with gallery, edit layout, coach marks
-alwaysApply: true
----
-
-# Exxat DS — Data view dashboard (list hubs)
-
-**Authoritative detail:** **`apps/web/AGENTS.md` §4.3** and **`exxat-dashboard-view-charts`** (this rule).
-
-## Two dashboard surfaces (do not fork chart engines)
-
-| Surface | Entry | Shared building blocks |
-|--------|--------|-------------------------|
-| **Full-page dashboard** | `app/(app)/dashboard/page.tsx` | `DashboardTabs`, `ChartsOverview` / gallery demos in `charts-overview.tsx` |
-| **Data tab** on Placements / Team / Compliance | `PlacementsTable`, `TeamTable`, `ComplianceTable` → `*DashboardChartsSection` | `ChartFigure`, `ChartCard`, `useChartVariant()`, `data-view-dashboard-charts*.tsx` |
-
-**MUST NOT** duplicate “another” chart system for Data view — extend **`charts-overview`** patterns and **`lib/chart-keyboard-selection`**.
-
-## MUST — accessibility & data
-
-1. **`ChartFigure`** + **`ChartDataTable`** (`sr-only`) for every chart on the Data dashboard — same as **`charts-overview.tsx`**.
-2. **`ChartCard`** wraps chart content; **`KeyMetrics`** **`variant="card"`** for the **`key-metrics`** tile; KPI count **1–4** persisted in layout.
-
-## MUST — keyboard selection (parity with `/dashboard` gallery)
-
-- Import **`CHART_KBD_ACTIVE_BAR`** and **`CHART_KBD_ACTIVE_PIE_SHAPE`** from **`@/lib/chart-keyboard-selection`**.
-- **Bar** series: **`activeBar={CHART_KBD_ACTIVE_BAR}`** + **`activeIndex={activeIndex ?? undefined}`** (and **`Cell`** only for per-bar **fill**, not opacity-only selection).
-- **Pie / donut:** **`activeShape={CHART_KBD_ACTIVE_PIE_SHAPE}`** + **`activeIndex`** + slice **`stroke`** / **`strokeWidth`** consistent with gallery donuts.
-- **MUST NOT** use **`fillOpacity` dimming alone** on **`Cell`** as the sole “selected” state for keyboard exploration.
-
-## MUST — customisation UX
-
-- **Edit layout** control: **`aria-label="Edit dashboard layout"`** (toolbar pen-ruler). Coach marks may target **`[aria-label='Edit dashboard layout']`**.
-- On-canvas: drag reorder, remove, width (half / full), chart type, add/remove cards, reset. **No** separate Sheet for layout.
-- While **`layoutEditMode`**: hide **`DataTableToolbar`** (search / filters / Properties row); **Done** / **Cancel** on canvas.
-
-## MUST — persistence (centralized)
-
-- **One bundle:** **`lib/data-view-dashboard-storage.ts`** — key **`exxat-ds:data-view-dashboards:v1`**, scopes **`placements` | `team` | `compliance`**.
-- Placements helpers: **`loadDashboardLayout`** / **`saveDashboardLayout`** in **`data-view-dashboard-charts.tsx`** (wrap storage API).
-- **MUST NOT** introduce parallel **`localStorage`** keys for the same **`DashboardLayout`** shape without updating the storage module.
-
-## SHOULD — coach marks
-
-- Register **customize dashboard** flows in **`lib/coach-mark-registry.ts`**; shared copy in **`lib/dashboard-customize-coach-mark.ts`**.
-- Use **`useCoachMark`** **`enabled`** / **`dependsOnDismissedFlowId`** when a tour only applies on **dashboard** view or after another flow (**`COACH_MARK_FLOW_COMPLETED_EVENT`**).
-
-## Reference files
-
-- `components/data-view-dashboard-charts.tsx` (Placements)
-- `components/data-view-dashboard-charts-team.tsx`, `data-view-dashboard-charts-compliance.tsx`
-- `components/placements-table.tsx` — dashboard tab body wires `PlacementsDashboardChartsSection` + layout-edit toolbar inline (no separate `DashboardShell` component)
-- `lib/chart-keyboard-selection.ts`, `lib/data-view-dashboard-storage.ts`, `lib/dashboard-customize-coach-mark.ts`

package/template/.agents/skills/shadcn/SKILL.md

@@ -1,242 +0,0 @@
----
-name: shadcn
-description: Manages shadcn components and projects — adding, searching, fixing, debugging, styling, and composing UI. Provides project context, component docs, and usage examples. Applies when working with shadcn/ui, component registries, presets, --preset codes, or any project with a components.json file. Also triggers for "shadcn init", "create an app with --preset", or "switch to --preset".
-user-invocable: false
-allowed-tools: Bash(npx shadcn@latest *), Bash(pnpm dlx shadcn@latest *), Bash(bunx --bun shadcn@latest *)
----
-
-# 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.
-
-> **IMPORTANT:** Run all CLI commands using the project's package runner: `npx shadcn@latest`, `pnpm dlx shadcn@latest`, or `bunx --bun shadcn@latest` — based on the project's `packageManager`. Examples below use `npx shadcn@latest` but substitute the correct runner for the project.
-
-## Current Project Context
-
-```json
-!`npx shadcn@latest info --json`
-```
-
-The JSON above contains the project config and installed components. Use `npx shadcn@latest docs <component>` to get documentation and example URLs for any component.
-
-## Principles
-
-1. **Use existing components first.** Use `npx shadcn@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](./rules/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](./rules/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](./rules/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 `npx shadcn@latest info`. → [base-vs-radix.md](./rules/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](./rules/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](./rules/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 `npx shadcn@latest 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.
-
-```tsx
-// 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
-
-| Need                       | Use                                                                                                 |
-| -------------------------- | --------------------------------------------------------------------------------------------------- |
-| Button/action              | `Button` with appropriate variant                                                                   |
-| Form inputs                | `Input`, `Select`, `Combobox`, `Switch`, `Checkbox`, `RadioGroup`, `Textarea`, `InputOTP`, `Slider` |
-| Toggle between 2–5 options | `ToggleGroup` + `ToggleGroupItem`                                                                   |
-| Data display               | `Table`, `Card`, `Badge`, `Avatar`                                                                  |
-| Navigation                 | `Sidebar`, `NavigationMenu`, `Breadcrumb`, `Tabs`, `Pagination`                                     |
-| Overlays                   | `Dialog` (modal), `Sheet` (side panel), `Drawer` (bottom sheet), `AlertDialog` (confirmation)       |
-| Feedback                   | `sonner` (toast), `Alert`, `Progress`, `Skeleton`, `Spinner`                                        |
-| Command palette            | `Command` inside `Dialog`                                                                           |
-| Charts                     | `Chart` (wraps Recharts)                                                                            |
-| Layout                     | `Card`, `Separator`, `Resizable`, `ScrollArea`, `Accordion`, `Collapsible`                          |
-| Empty states               | `Empty`                                                                                             |
-| Menus                      | `DropdownMenu`, `ContextMenu`, `Menubar`                                                            |
-| Tooltips/info              | `Tooltip`, `HoverCard`, `Popover`                                                                   |
-
-## Key Fields
-
-The injected 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`** → use this for any non-shadcn dependency installs (e.g. `pnpm add date-fns` vs `npm install date-fns`).
-
-See [cli.md — `info` command](./cli.md) for the full field reference.
-
-## Component Docs, Examples, and Usage
-
-Run `npx shadcn@latest docs <component>` to get the URLs for a component's documentation, examples, and API reference. Fetch these URLs to get the actual content.
-
-```bash
-npx shadcn@latest docs button dialog select
-```
-
-**When creating, fixing, debugging, or using a component, always run `npx shadcn@latest docs` and fetch the URLs first.** This ensures you're working with the correct API and usage patterns rather than guessing.
-
-## Workflow
-
-1. **Get project context** — already injected above. Run `npx shadcn@latest info` again if you need to refresh.
-2. **Check installed components first** — before running `add`, always check the `components` list from project context or list the `resolvedPaths.ui` directory. Don't import components that haven't been added, and don't re-add ones already installed.
-3. **Find components** — `npx shadcn@latest search`.
-4. **Get docs and examples** — run `npx shadcn@latest docs <component>` to get URLs, then fetch them. Use `npx shadcn@latest view` to browse registry items you haven't installed. To preview changes to installed components, use `npx shadcn@latest add --diff`.
-5. **Install or update** — `npx shadcn@latest add`. When updating existing components, use `--dry-run` and `--diff` to preview changes first (see [Updating Components](#updating-components) below).
-6. **Fix imports in third-party components** — After adding components from community registries (e.g. `@bundui`, `@magicui`), check the added non-UI files for hardcoded import paths like `@/components/ui/...`. These won't match the project's actual aliases. Use `npx shadcn@latest info` to get the correct `ui` alias (e.g. `@workspace/ui/components`) and rewrite the imports accordingly. The CLI rewrites imports for its own UI files, but third-party registry components may use default paths that don't match the project.
-7. **Review added components** — After adding a component or block from any registry, **always read the added files and verify they are correct**. Check for missing sub-components (e.g. `SelectItem` without `SelectGroup`), missing imports, incorrect composition, or violations of the [Critical Rules](#critical-rules). Also replace any icon imports with the project's `iconLibrary` from the project context (e.g. if the registry item uses `lucide-react` but the project uses `hugeicons`, swap the imports and icon names accordingly). Fix all issues before moving on.
-8. **Registry must be explicit** — When the user asks to add a block or component, **do not guess the registry**. If no registry is specified (e.g. user says "add a login block" without specifying `@shadcn`, `@tailark`, etc.), ask which registry to use. Never default to a registry on behalf of the user.
-9. **Switching presets** — Ask the user first: **reinstall**, **merge**, or **skip**?
-   - **Reinstall**: `npx shadcn@latest init --preset <code> --force --reinstall`. Overwrites all components.
-   - **Merge**: `npx shadcn@latest init --preset <code> --force --no-reinstall`, then run `npx shadcn@latest info` to list installed components, then for each installed component use `--dry-run` and `--diff` to [smart merge](#updating-components) it individually.
-   - **Skip**: `npx shadcn@latest init --preset <code> --force --no-reinstall`. Only updates config and CSS, leaves components as-is.
-   - **Important**: Always run preset commands inside the user's project directory. The CLI automatically preserves the current base (`base` vs `radix`) from `components.json`. If you must use a scratch/temp directory (e.g. for `--dry-run` comparisons), pass `--base <current-base>` explicitly — preset codes do not encode the base.
-
-## Updating Components
-
-When the user asks to update a component from upstream while keeping their local changes, use `--dry-run` and `--diff` to intelligently merge. **NEVER fetch raw files from GitHub manually — always use the CLI.**
-
-1. Run `npx shadcn@latest add <component> --dry-run` to see all files that would be affected.
-2. For each file, run `npx shadcn@latest add <component> --diff <file>` to see what changed upstream vs local.
-3. Decide per file based on the diff:
-   - No local changes → safe to overwrite.
-   - Has local changes → read the local file, analyze the diff, and apply upstream updates while preserving local modifications.
-   - User says "just update everything" → use `--overwrite`, but confirm first.
-4. **Never use `--overwrite` without the user's explicit approval.**
-
-## Quick Reference
-
-```bash
-# Create a new project.
-npx shadcn@latest init --name my-app --preset base-nova
-npx shadcn@latest init --name my-app --preset a2r6bw --template vite
-
-# Create a monorepo project.
-npx shadcn@latest init --name my-app --preset base-nova --monorepo
-npx shadcn@latest init --name my-app --preset base-nova --template next --monorepo
-
-# Initialize existing project.
-npx shadcn@latest init --preset base-nova
-npx shadcn@latest init --defaults  # shortcut: --template=next --preset=base-nova
-
-# Add components.
-npx shadcn@latest add button card dialog
-npx shadcn@latest add @magicui/shimmer-button
-npx shadcn@latest add --all
-
-# Preview changes before adding/updating.
-npx shadcn@latest add button --dry-run
-npx shadcn@latest add button --diff button.tsx
-npx shadcn@latest add @acme/form --view button.tsx
-
-# Search registries.
-npx shadcn@latest search @shadcn -q "sidebar"
-npx shadcn@latest search @tailark -q "stats"
-
-# Get component docs and example URLs.
-npx shadcn@latest docs button dialog select
-
-# View registry item details (for items not yet installed).
-npx shadcn@latest view @shadcn/button
-```
-
-**Named presets:** `base-nova`, `radix-nova`
-**Templates:** `next`, `vite`, `start`, `react-router`, `astro` (all support `--monorepo`) and `laravel` (not supported for monorepo)
-**Preset codes:** Base62 strings starting with `a` (e.g. `a2r6bw`), from [ui.shadcn.com](https://ui.shadcn.com).
-
-## Detailed References
-
-- [rules/forms.md](./rules/forms.md) — FieldGroup, Field, InputGroup, ToggleGroup, FieldSet, validation states
-- [rules/composition.md](./rules/composition.md) — Groups, overlays, Card, Tabs, Avatar, Alert, Empty, Toast, Separator, Skeleton, Badge, Button loading
-- [rules/icons.md](./rules/icons.md) — data-icon, icon sizing, passing icons as objects
-- [rules/styling.md](./rules/styling.md) — Semantic colors, variants, className, spacing, size, truncate, dark mode, cn(), z-index
-- [rules/base-vs-radix.md](./rules/base-vs-radix.md) — asChild vs render, Select, ToggleGroup, Slider, Accordion
-- [cli.md](./cli.md) — Commands, flags, presets, templates
-- [customization.md](./customization.md) — Theming, CSS variables, extending components

package/template/.agents/skills/shadcn/agents/openai.yml

@@ -1,5 +0,0 @@
-interface:
-  display_name: "shadcn/ui"
-  short_description: "Manages shadcn/ui components — adding, searching, fixing, debugging, styling, and composing UI."
-  icon_small: "./assets/shadcn-small.png"
-  icon_large: "./assets/shadcn.png"