Skip to content

Using components

Five habits keep Shavin code short, themeable and easy for agents to follow. Each component page lists its exact props.

1. Import from the package root

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

Two subpaths exist for specific cases: @shavin/ui/server for helpers like cn in Server Components, and @shavin/ui/panels for resizable layouts.

2. Choose props, not classes

Appearance comes from typed props. They stay consistent across the app and follow the theme.

<Button>Save</Button>
<Button variant="outline">Cancel</Button>
<Button variant="ghost" size="sm">Skip</Button>
<Button tone="danger">Delete</Button>

3. Lay out with Flex and Grid

Spacing between elements comes from gap on a layout component, not margins on the children. Inside a card, put the content in a column:

<Card padding="lg">
  <Flex direction="column" gap="3">
    <Heading as="h3" size="sm">Storage</Heading>
    <Text size="sm" color="subtle">You have used 4 of 10 GB.</Text>
  </Flex>
</Card>

4. Use tokens when you need a class

When you do write a class, use the semantic tokens. They change with the theme and dark mode; Tailwind palette colours do not.

// Follows the theme
<div className="border border-hairline bg-surface text-fg-subtle" />

// Breaks in dark mode and on rebrand
<div className="border border-gray-200 bg-white text-gray-500" />

Your className merges with the component's own classes, and yours win when they conflict.

5. Pass parts as props

Overlays take their title and trigger as props, so a dialog is one element:

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

export function DeleteProject() {
  return (
    <Dialog title="Delete project?" trigger={<Button tone="danger">Delete</Button>}>
      <Text size="sm" color="subtle">This removes the project for everyone on the team.</Text>
    </Dialog>
  );
}

Next

Configure Theme
Theme
Brand Color
Custom
Gray Family
Appearance
Radius
Scaling
Panel Style
Heading Font
Body Font