sonth87/shadcn-design-system

Design System Skill — @sth87/shadcn-design-system

Quick Reference

| | | |---|---| | Package | @sth87/shadcn-design-system | | Internal alias | @dsui/design-system | | React | 18 / 19 | | Styling | Tailwind CSS v4 + CSS custom properties | | Primitives | Radix UI | | Motion | motion/react (Framer Motion v11+) | | Icons | lucide-react | | Table | TanStack Table v8 | | Toasts | Sonner | | URL State | nuqs | | Storybook | https://design-system-sth-kappa.vercel.app/ |

---

Import Policy

Use subpath imports for all new code. Root imports from @sth87/shadcn-design-system are legacy/backward-compatible only and should not be generated by AI agents. Read references/import-policy.md whenever you need the canonical import for a component, hook, text animation, or utility.

1. Installation & Setup

1.1 Install

npm install @sth87/shadcn-design-system
# or
pnpm add @sth87/shadcn-design-system

1.2 Tailwind v4 Configuration

/* In your global CSS (v4 style) */
@source "../../node_modules/@sth87/shadcn-design-system/dist";

// tailwind.config.js (v3 compat)
content: [
  "./src/**/*.{ts,tsx}",
  "./node_modules/@sth87/shadcn-design-system/dist/**/*.{js,mjs}"
]

Tailwind v3 — extend theme with CSS variable mappings:

theme: {
  extend: {
    colors: {
      border: "hsl(var(--border))",
      input: "hsl(var(--input))",
      ring: "hsl(var(--ring))",
      background: "hsl(var(--background))",
      foreground: "hsl(var(--foreground))",
      primary: { DEFAULT: "hsl(var(--primary))", foreground: "hsl(var(--primary-foreground))" },
      secondary: { DEFAULT: "hsl(var(--secondary))", foreground: "hsl(var(--secondary-foreground))" },
      destructive: { DEFAULT: "hsl(var(--destructive))", foreground: "hsl(var(--destructive-foreground))" },
      muted: { DEFAULT: "hsl(var(--muted))", foreground: "hsl(var(--muted-foreground))" },
      accent: { DEFAULT: "hsl(var(--accent))", foreground: "hsl(var(--accent-foreground))" },
    },
    borderRadius: {
      lg: "var(--radius)",
      md: "calc(var(--radius) - 2px)",
      sm: "calc(var(--radius) - 4px)"
    },
  }
}

1.3 Global CSS Imports

Import all three in your root entry (main.tsx, app/layout.tsx, etc.):

import "@sth87/shadcn-design-system/theme.css";     // design tokens (colors, radius, etc.)
import "@sth87/shadcn-design-system/index.css";     // component base styles
import "@sth87/shadcn-design-system/animation.css"; // animation keyframes

1.4 Component Imports

Prefer subpath imports:

import Button from "@sth87/shadcn-design-system/button";
import Dialog from "@sth87/shadcn-design-system/dialog";
import { DataTable } from "@sth87/shadcn-design-system/table";
import { Toaster, toast } from "@sth87/shadcn-design-system/toast";
import { useDataTable } from "@sth87/shadcn-design-system/use-data-table";

Legacy root imports still work for older code, but do not generate new code with them:

import { Button, Dialog, DataTable } from "@sth87/shadcn-design-system";

1.5 Toaster Setup

import { Toaster } from "@sth87/shadcn-design-system/toast";
// Add once at the app root
<Toaster position="top-right" richColors closeButton />

---

2. Reference Files

Load the relevant reference file when you need full props, types, or detailed examples. The index tables in Section 3 link directly to the relevant anchors.

| File | When to read | Contents | |---|---|---| | references/import-policy.md | User imports any component, hook, text animation, or utility | Canonical subpath imports and legacy root import policy | | references/theme-tokens.md | User asks about colors, dark mode, CSS variables, theming, or custom tokens | CSS design tokens, dark mode, theme switching, animation token table | | references/components-a-l.md | User uses any component from Accordion to Label | Accordion → Label — full props + examples for 25 components | | references/components-m-z.md | User uses any component from Marquee to Upload | Marquee → Upload — full props + examples for 26 components | | references/text-animation.md | User asks about text effects or animation components | 13 text animation components with usage examples | | references/utils.md | User calls cn, formatting helpers, or URL state utilities | cn, animationClass, animationEffect, formatDate, dataTableConfig, URL state parsers | | references/hooks.md | User uses any hook from this library | 12 hooks including useDataTable, useDebounceValue, useIntersectionObserver | | references/types.md | User needs TypeScript types or interfaces | All TypeScript types: BasicColor, BasicAnimation, UploadFile, FilterVariant, etc. | | references/data-table-column-options.md | User works on DataTable column visibility, column reorder, draggable column options, pinned columns, or DataTableViewOptions | Implementation rules for TanStack columnOrder, columnPinning, @dnd-kit, customization props, and crash-safe edge cases |

---

3. Component Quick Index

Components A–L → references/components-a-l.md

| Component | Import | Purpose | |---|---|---| | Accordion | Accordion | Collapsible FAQ sections | | Avatar | Avatar | User photo or initials | | Badge | Badge | Status label / tag | | Breadcrumb | Breadcrumb | Navigation trail | | Button | Button, ButtonGroup | Primary action / grouped buttons | | Calendar | Calendar | Full calendar with date/range selection | | Carousel | Carousel, CarouselSlide | Touch slider (Swiper.js) | | Checkbox | Checkbox | Binary toggle with label | | Collapsible | Collapsible | Single expandable section | | Command | Command, CommandDialog | Command palette / spotlight search | | ContextMenu | ContextMenu | Right-click action menu | | Cropper | Cropper | Image crop with zoom/rotation | | DatePicker | DatePicker | Date selection input | | RangePicker | RangePicker | Date range selection | | TimePicker | TimePicker | Time selection wheel | | Dialog | Dialog | Modal overlay | | DropdownMenu | DropdownMenu | Triggered action menu | | Glass | Glass | Frosted glass distortion filter | | ImageViewer | ImageViewer | Lightbox with zoom/pan/rotation | | Input | Input | Text input with label/error/prefix/suffix | | InputOTP | InputOTP | OTP / verification code input | | Interactive3DCard | Interactive3DCard | Mouse-tracked 3D tilt card | | Interactive3DMarquee | Interactive3DMarquee | 3D perspective grid scroller | | InteractiveCursorFollow | InteractiveCursorFollow | Custom cursor tracking | | Label | Label | Form label with required/optional indicator |

Components M–Z → references/components-m-z.md

| Component | Import | Purpose | |---|---|---| | Marquee | Marquee | Auto-scrolling content belt | | Masonry | Masonry | Pinterest-style column layout | | Pagination | Pagination | Page navigation control | | Popover | Popover | Non-modal floating panel | | QrCode | QrCode | QR code generator | | Radio | Radio | Radio group / button-group variant | | Rate | Rate | Star rating input | | Resizable | Resizable | Drag-to-resize split panels | | ScrollArea | ScrollArea | Custom-styled scrollable container | | Select | Select | Dropdown value selector with search | | Separator | Separator | Divider line with optional label | | Sheet | Sheet | Side drawer/panel | | Sidebar | Sidebar + 20 sub-components | Full application sidebar | | Skeleton | Skeleton | Loading placeholder shimmer | | Slider | Slider | Range / value input | | Stepper | Stepper | Multi-step progress indicator | | Switch | Switch | Toggle switch | | DataTable | DataTable, DataTableColumnHeader, etc. | TanStack Table v8 integration | | Tabs | Tabs | Switchable content panels | | Textarea | Textarea | Multi-line text input | | Toast | toast, Toaster | Notification toasts (Sonner) | | Toggle | Toggle | Two-state toggled button | | Tooltip | Tooltip | Hover information popup | | Tour | Tour | Step-by-step feature walkthrough | | TreeSelect | TreeSelect | Hierarchical tree data selector | | Upload | Upload | File uploader with drag & drop preview |

Text Animation → references/text-animation.md

| Import | Effect | |---|---| | BlurText | Word-by-word blur entrance | | RotatingText | Cycling word rotation | | CircularText | Radial character ring | | FlipWords | Vertical flip word list | | GradientText | Animated gradient fill | | RollingText | Slot-machine character roll | | ShimmeringText | Light sheen sweep | | SplittingText | Staggered character entrance | | TextGenerateEffect | Word-by-word generation | | TextHoverEffect | Cursor-following gradient trail | | TextPressure | Variable font weight cursor response | | TypingText | Classic typewriter + cycling | | WritingText | SVG path draw-in animation |

---

4. Quick Recipes

Minimal page with Button + Toast

import "@sth87/shadcn-design-system/theme.css";
import "@sth87/shadcn-design-system/index.css";
import "@sth87/shadcn-design-system/animation.css";
import Button from "@sth87/shadcn-design-system/button";
import { Toaster, toast } from "@sth87/shadcn-design-system/toast";

export default function App() {
  return (
    <>
      <Button color="primary" onClick={() => toast.success("Hello!")}>Click me</Button>
      <Toaster position="top-right" />
    </>
  );
}

DataTable (server-side + URL state)

// Full docs: references/components-m-z.md#441-datatable  &  references/hooks.md#usedatatable
import { useDataTable } from "@sth87/shadcn-design-system/use-data-table";
import { DataTable, DataTableColumnHeader } from "@sth87/shadcn-design-system/table";
import type { ColumnDef } from "@tanstack/react-table";

const columns: ColumnDef<User>[] = [
  { accessorKey: "name", header: ({ column }) => <DataTableColumnHeader column={column} title="Name" /> },
  { accessorKey: "email", header: "Email" },
];

function UsersPage({ data, pageCount, isLoading }) {
  const table = useDataTable({ data, columns, pageCount, enableSorting: true, syncWithUrl: true });
  return <DataTable table={table} pagination sticky loading={isLoading} />;
}

Sidebar layout

// Full example: references/components-m-z.md#436-sidebar
import {
  SidebarProvider,
  Sidebar,
  SidebarContent,
  SidebarMenu,
  SidebarMenuItem,
  SidebarMenuButton,
  SidebarInset,
  SidebarTrigger,
} from "@sth87/shadcn-design-system/sidebar";

export default function Layout({ children }) {
  return (
    <SidebarProvider>
      <Sidebar collapsible="icon">
        <SidebarContent>
          <SidebarMenu>
            {navItems.map((item) => (
              <SidebarMenuItem key={item.href}>
                <SidebarMenuButton asChild tooltip={item.label}>
                  <a href={item.href}><item.icon /><span>{item.label}</span></a>
                </SidebarMenuButton>
              </SidebarMenuItem>
            ))}
          </SidebarMenu>
        </SidebarContent>
      </Sidebar>
      <SidebarInset>
        <header className="flex h-16 px-4 items-center gap-4 border-b">
          <SidebarTrigger />
        </header>
        <main className="p-6">{children}</main>
      </SidebarInset>
    </SidebarProvider>
  );
}

---

5. Integration Checklist

• [ ] npm install @sth87/shadcn-design-system
• [ ] Import theme.css in root entry
• [ ] Import index.css in root entry
• [ ] Import animation.css in root entry
• [ ] Configure Tailwind to scan node_modules/@sth87/shadcn-design-system/dist/
• [ ] Add <Toaster /> to app root
• [ ] Install nuqs + wrap app in <NuqsAdapter> (only if using syncWithUrl with useDataTable)
• [ ] Wrap app in <SidebarProvider> (only if using the Sidebar component)