UI Components

Core UI Components (`/components/ui/`)

Standard Shadcn/ui components that provide the design system foundation. These are generated using the Shadcn CLI and follow their conventions.

Files you should NOT modify:

• button.tsx, input.tsx, card.tsx, etc.
• These are the atomic building blocks

When to modify core components:

• Only for critical design system changes that affect your entire app
• When adding company-specific variants (see below)
• Always test thoroughly - these affect the entire application

Custom Components (`/components/`)

Application-specific components that use the core UI components.

Files marked as USER EDITABLE:

• Safe to customize for your product
• Examples: FeatureGate.tsx, Header.tsx, UpgradeButton.tsx

Product Components (`/components/product/`):

• Your custom business logic components
• Completely safe to modify/replace
• Examples: dashboard widgets, forms, specialized UI

Landing Components (`/components/landing/`)

Marketing and landing page components. Replace these with your own branding and messaging.

Component Variants

All Shadcn components use class-variance-authority (CVA) for variants:

import { Button } from "@/components/ui/button";

// Standard variants
<Button variant="default">Default</Button>
<Button variant="outline">Outline</Button>
<Button variant="ghost">Ghost</Button>

// Size variants
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>

Styling Conventions

// ✅ Good - semantic colors
className="text-foreground bg-card border-border"

// ❌ Bad - hardcoded colors
className="text-gray-900 bg-white border-gray-200"

// ✅ Consistent spacing
className="p-4 gap-3"

// ❌ Inconsistent values
className="p-5 gap-2.5"

// ✅ Flexbox patterns
className="flex items-center justify-between"
className="grid grid-cols-2 gap-4"

For Core UI Extensions

# Add a new Shadcn component npx shadcn@latest add [component-name]

For Custom Components

Create in the appropriate directory:

// /components/product/MyComponent.tsx
"use client";

import { cn } from "@/lib/utils";
import { Button } from "@/components/ui/button";

interface MyComponentProps {
  className?: string;
  children: React.ReactNode;
}

export function MyComponent({ className, children }: MyComponentProps) {
  return (
    <div className={cn("rounded-lg border bg-card p-4", className)}>
      {children}
    </div>
  );
}

CSS Variables

The design system uses CSS variables defined in globals.css:

/* Available in all components */
--background
--foreground
--card
--border
--primary
--secondary
/* ... etc */

Dark Mode Classes

Components automatically support dark mode through the dark: prefix:

className="bg-background text-foreground dark:bg-gray-900 dark:text-white"

However, prefer semantic tokens that automatically adapt:

className="bg-background text-foreground"

Theme Toggle

Use the existing ThemeToggle component for user theme switching.

Feature Gates

Wrap premium features with the FeatureGate component:

import { FeatureGate } from "@/components/FeatureGate";

<FeatureGate entitlement="pro_features">
  <PremiumFeature />
</FeatureGate>

Loading States

Use consistent loading patterns:

import { Loader2 } from "lucide-react";

<div className="flex items-center justify-center p-8">
  <Loader2 className="h-8 w-8 animate-spin text-muted-foreground" />
</div>

Form Components

Combine UI components for forms:

import { Input } from "@/components/ui/input";
import { Label } from "@/components/ui/label";
import { Button } from "@/components/ui/button";

<div className="space-y-4">
  <div className="space-y-2">
    <Label htmlFor="email">Email</Label>
    <Input id="email" type="email" />
  </div>
  <Button>Submit</Button>
</div>

✅ Do

• Use semantic color tokens (text-foreground, bg-card)
• Follow component variant patterns
• Test components in both light and dark modes
• Use the cn() utility for conditional classes
• Keep component interfaces clean and typed
• Use Lucide icons for consistency

❌ Don't

• Hardcode colors or spacing values
• Create custom CSS files (use Tailwind classes)
• Modify core UI components without thorough testing
• Mix different icon libraries
• Create components that don't work in dark mode
• Use inline styles instead of Tailwind classes