dashboard-ui-components

name: dashboard-ui-components description: Use when building new UI in packages/fern-dashboard/, adding interactive elements, or choosing between raw HTML and existing components. Covers shadcn/ui component catalog, import patterns, variants, and design tokens.

Dashboard UI Components

Overview

The Fern dashboard (packages/fern-dashboard/) uses shadcn/ui (new-york style) with Radix primitives, CVA variants, and Tailwind CSS v4. Always check src/components/ui/ before building custom UI.

Component Catalog

Import Patterns

// Always import cn from this path
import { cn } from "@/utils/utils";

// Named exports from individual files (no barrel index.ts)
import { Button } from "@/components/ui/button";
import {
    Dialog, DialogBody, DialogClose, DialogContent, DialogDescription,
    DialogFooter, DialogHeader, DialogTitle, DialogTrigger
} from "@/components/ui/dialog";
import { Input } from "@/components/ui/input";

// Card is the ONLY default export
import Card from "@/components/ui/card";

// Icons from lucide-react
import { Plus, XIcon, ChevronDown } from "lucide-react";

// Type-only React import
import type * as React from "react";

Component Patterns

CVA Variants (Button pattern)

import { cva, type VariantProps } from "class-variance-authority";

const myVariants = cva("base-classes", {
    variants: {
        variant: { default: "...", outline: "..." },
        size: { default: "h-9 px-4", sm: "h-8 px-3" }
    },
    defaultVariants: { variant: "default", size: "default" }
});

// Usage: cn(myVariants({ variant, size, className }))

Compound Components (Dialog, Select, Tabs)

<Dialog>
    <DialogTrigger asChild>
        <Button variant="outline">Open</Button>
    </DialogTrigger>
    <DialogContent>
        <DialogHeader>
            <DialogTitle>Title</DialogTitle>
            <DialogDescription>Description</DialogDescription>
        </DialogHeader>
        <DialogBody>
            {/* content */}
        </DialogBody>
        <DialogFooter>
            <DialogClose asChild><Button variant="outline">Cancel</Button></DialogClose>
            <Button variant="destructive">Delete</Button>
        </DialogFooter>
    </DialogContent>
</Dialog>

Required Directives

• "use client" on all interactive components (button, dialog, select, tooltip, dropdown-menu, tabs, switch, popover)
• data-slot="component-name" on Radix-based wrappers

asChild Pattern

Use asChild to render a different element while keeping component behavior:

<DialogTrigger asChild>
    <Button variant="outline">Click me</Button>
</DialogTrigger>

Loading State (Button)

<Button loading>Saving...</Button>
// Renders children invisible + centered Loader2 spinner
// Automatically sets disabled={true}

Design Tokens

Semantic Colors (use these first)

Color Scale (100-1200)

Available for: gray, green, blue, purple, yellow

bg-gray-100 … bg-gray-1200
text-green-1100  (brand green in light mode)
border-blue-900

• 100-400: Backgrounds, surfaces
• 500-700: Borders, separators
• 800-1000: Icons, secondary elements
• 1100-1200: Text, primary elements

Dark Mode

Class-based: .dark on parent element. All tokens automatically remap. Never hardcode light/dark-specific hex values — use the semantic tokens or color scale.

Decision Flow

Need UI element?
├── Check src/components/ui/ first
│   ├── Component exists → Use it with correct variant
│   └── Component doesn't exist
│       ├── Can shadcn generate it? → npx shadcn add <component>
│       └── Truly custom → Create in src/components/ui/ following patterns above
└── Styling only? → Use semantic tokens, then color scale, never arbitrary hex

Common Mistakes