@dynamic-labs-sdk/droplet

Dynamic Labs' React component library. Built on Radix UI primitives, Tailwind CSS v4, and an OKLCH-based design token system. Ships with 35+ components, animated icons, dark mode, and a live Storybook.

Installation

npm install @dynamic-labs-sdk/droplet
# or
pnpm add @dynamic-labs-sdk/droplet
# or
yarn add @dynamic-labs-sdk/droplet

Peer dependencies: react >= 18, react-dom >= 18, tailwindcss >= 4. Next.js (>= 14) is optional.

Setup

Droplet ships Tailwind CSS v4 utility classes baked into its compiled output. You must (1) have Tailwind v4 configured in your app, (2) import the design tokens stylesheet, and (3) tell Tailwind to scan droplet's dist/ so its utility classes are emitted into your stylesheet.

1. Install and configure Tailwind v4

If you don't already have Tailwind v4, follow the Tailwind v4 install guide. The @tailwindcss/vite plugin is the simplest path for Vite/Next:

// vite.config.ts
import tailwindcss from '@tailwindcss/vite';
import { defineConfig } from 'vite';

export default defineConfig({
  plugins: [tailwindcss()],
});

2. Import the design tokens stylesheet

Import once at your app root. This provides the full color, shadow, radius, and typography token system and is required for all components to render correctly.

import '@dynamic-labs-sdk/droplet/styles/globals.css';

3. Add droplet to Tailwind's @source paths

Tailwind v4 only scans the consuming project by default, so it will miss the utility classes inside droplet's compiled JS. Add an @source directive to your app's main stylesheet:

/* app.css */
@import 'tailwindcss';
@source "../node_modules/@dynamic-labs-sdk/droplet/dist";

Adjust the relative path to match where your stylesheet lives. Without this step, components will render unstyled.

Usage

import {
  Button,
  Card,
  CardContent,
  CardHeader,
  CardTitle,
  Badge,
} from '@dynamic-labs-sdk/droplet';

export const Example = () => (
  <Card>
    <CardHeader>
      <CardTitle>
        My Feature
        <Badge variant="brand">New</Badge>
      </CardTitle>
    </CardHeader>
    <CardContent>
      <Button>Get started</Button>
    </CardContent>
  </Card>
);

Components

UI Primitives

Thin wrappers over Radix UI primitives with full token-based styling.

Project Patterns

Higher-level components composed from primitives, designed for dashboard and settings UIs.

Animated Icons

Custom SVG icons with spring physics via Motion. All icons accept standard SVG props plus a className.

import {
  ChevronDownIcon,
  CopyCheckIcon,
  SettingsIcon,
} from '@dynamic-labs-sdk/droplet';

<SettingsIcon className="size-4 text-muted-foreground" />;

Utilities & Hooks

Theming

Droplet's theme is a layer of CSS custom properties. Tailwind utility classes resolve through them (bg-brand-default → var(--brand-default)), and every component reads from the same vars — so you can fully rebrand by redefining the vars in your own stylesheet. No Tailwind config changes, no rebuild, no fork.

Quick start: change the brand color

/* your-theme.css — imported AFTER @dynamic-labs-sdk/droplet/styles/globals.css */

:root {
  --brand-default: oklch(0.67 0.21 30);  /* your light-mode brand */
  --brand-hover: oklch(0.72 0.19 30);
  --brand-accented: oklch(0.58 0.22 30);
  --brand-light: oklch(0.97 0.03 30);
  --ring: oklch(0.67 0.21 30);
  --action: oklch(0.67 0.21 30);
}

.dark {
  --brand-default: oklch(0.6 0.22 30);   /* your dark-mode brand */
  --brand-hover: oklch(0.68 0.19 30);
  --brand-accented: oklch(0.52 0.23 30);
  --brand-light: oklch(0.27 0.07 30);
  --ring: oklch(0.6 0.22 30);
  --action: oklch(0.6 0.22 30);
}

// in your app entry, AFTER the droplet import
import '@dynamic-labs-sdk/droplet/styles/globals.css';
import './your-theme.css';

That's it. Buttons, links, focus rings, text-selection highlights, sidebars — all switch to the new brand.

Cascade order matters

Your theme stylesheet must load after @dynamic-labs-sdk/droplet/styles/globals.css, or the same selectors (:root, .dark) in droplet's stylesheet will win and your overrides will silently do nothing. If you @import in a single CSS file, put droplet's import first:

@import '@dynamic-labs-sdk/droplet/styles/globals.css';
@import './your-theme.css';

What's themeable

Anything in the Design tokens table below — colors, shadows, radii. The most common things to override:

For semantic colors (success/danger/warning/process), override the matching --<state>-default, --<state>-light, --text-<state> triplet.

Scoping a theme to part of your app

If you only want droplet themed inside a subtree (e.g., a marketing site reusing one component), put the overrides on a wrapper class instead of :root:

.my-theme {
  --brand-default: oklch(0.67 0.21 30);
  /* ... */
}

<div className="my-theme">
  <Button>Themed</Button>
</div>

Color space

Droplet uses OKLCH throughout. If your design system is in hex/rgb, tools like oklch.com or oklch.fyi will convert. You don't have to use OKLCH in your overrides — oklch(), hex, rgb(), and hsl() all interoperate fine — but staying in OKLCH gives you perceptually uniform lightness ramps when you tune hover/accented variants.

Design tokens

All tokens are CSS custom properties defined in globals.css. Tailwind utility classes map directly to them — bg-brand-default resolves to var(--brand-default).

Color groups

Shadow system

--shadow-border       /* 1px outline */
--shadow-card         /* card elevation */
--shadow-button       /* button depth */
--shadow-input        /* form field */
--shadow-input-hover  /* field on hover */
--shadow-elevated     /* popovers / dropdowns */
--shadow-card-content /* content area separator */

Radius scale

Dark mode

Apply the .dark class to <html> to activate the dark palette. All tokens are redefined under .dark with OKLCH-matched values — brand hue is preserved, only lightness shifts.

document.documentElement.classList.toggle('dark', isDark);

Storybook

Interactive component documentation with live token reference, dark mode toggle, and a11y audit on every story.

# From repo root
pnpm --filter @dynamic-labs-sdk/droplet storybook

# From packages/droplet
pnpm storybook

Runs on http://localhost:4402.

Development

# Run tests
pnpm --filter @dynamic-labs-sdk/droplet test

# Watch mode
pnpm --filter @dynamic-labs-sdk/droplet test:watch

# Build (ESM + CJS + .d.ts)
pnpm --filter @dynamic-labs-sdk/droplet build

# Lint
pnpm --filter @dynamic-labs-sdk/droplet lint

Tech stack