Developer Integration & Patterns

Component Usage & Consumption

1. Single Import Surface

All components are exported directly from the top-level package. Never use deep subpath imports:

// ✅ Correct: single top-level import
import { Button, Dialog, Select, Card, Text } from "@shavin/ui";

// ❌ Incorrect: deep imports are forbidden
import { Button } from "@shavin/ui/primitives/Button";

2. Component Variants with CVA

Components accept strongly typed variant props backed by class-variance-authority:

import { Button } from "@shavin/ui";

export function Example() {
  return (
    <div className="flex gap-2">
      <Button variant="solid" size="md">Solid Accent</Button>
      <Button variant="outline" size="md">Outline</Button>
      <Button variant="ghost" size="sm">Ghost Link</Button>
    </div>
  );
}

3. Safe Style Merging with cn()

Every component accepts a className prop that merges with internal styles using clsx and tailwind-merge. Your passed classes cleanly override defaults without specificity issues:

import { Card, Text } from "@shavin/ui";

export function CustomCard() {
  return (
    // p-8 cleanly overrides internal default padding
    <Card className="p-8 border-accent/40 bg-surface-hover">
      <Text weight="semibold">Custom Padded Card</Text>
    </Card>
  );
}

4. Compound Component Patterns

Complex interactive primitives (Dialog, Select, Tabs, Accordion, SegmentedControl) expose compound sub-components:

import { Dialog, DialogTrigger, DialogContent, Button } from "@shavin/ui";

export function ModalDemo() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="solid">Open Dialog</Button>
      </DialogTrigger>
      <DialogContent title="Account Settings">
        <p className="text-sm text-fg-muted">Modal body content goes here.</p>
      </DialogContent>
    </Dialog>
  );
}

Want to see all 56 primitives in action? Explore the complete Component Gallery.