@dynamic-labs-sdk/droplet

动态实验室反应组件库. 由Radix UI原始人,Tailwind CSS v4所建造,以及一个以OKLCH为主的设计令牌系统. 有35+组件的飞船,动画图标,暗模式等,还有活生生的故事书.

安装

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

同伴依赖性 : react >= 18, (中文(简体) ), react-dom >= 18, (中文(简体) ), tailwindcss >= 4下一个>= 14)是可选的.

设置

Dropplet ship Tailwind CSS v4 通用类被烤入所编译的输出. 你必须 (1) 在您的应用程序中配置 Tailwind v4 , (2) 导入设计符号样式表, (3) 告诉 Tailwind 扫描 droplet 的 dist/ 因此,它的工具类会排入您的样式表.

1. 安装和配置 Tailwind v4

如果你还没有泰尔温德V4,跟着 尾风 v4 安装导线编辑 @tailwindcss/vite 插件是 Vite/ Next 的最简单路径 :

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

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

2. 导入设计符号样式表

从您的应用根导入一次 。 这提供了全色,阴影,半径,和打字符系统,是所有组件正确渲染的要求.

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

3. 在 Tailwind 上添加水滴 @source 路径

Tailwind v4 默认只扫描了消耗性项目,所以它会错过Ltplet编译的JS内部的公用类. 添加一个 @source 对您的应用程序主样式表的指示 :

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

调整相对路径以匹配样式表的住址。 没有这个步骤,组件将变成无样式.

使用量

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>
);

构成部分

UI 初级

薄薄的包装 Radix 用户界面 原始人有完全的代号风格.

项目模式

由原始人所组成的更高级组件,为仪表板和设置UI所设计.

动画图标

自定义带有弹簧物理的 SVG 图标 动议。所有图标接受标准的 SVG 道具加一个 className。 。 。 .

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

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

公用事业和胡克

他们

Droplet)的主题为一层CSS自定义属性. Tailwind 公用事业类通过它们解决(bg-brand-default → var(--brand-default)),每个组件都从同一个 vars 读取——这样你就可以完全重塑由 在您的样式表中重新定义 vars。没有 Tailwind 配置变化,没有重建,没有叉子.

快速启动: 改变品牌颜色

/* 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';

就是这样。 按钮,链接,焦点环,文本选取要闻,侧边栏-都切换到新品牌.

连带命令事项

您的主题样式表 必须在之后装入 @dynamic-labs-sdk/droplet/styles/globals.css,或相同的选择者(:root, (中文(简体) ), .dark)在 Ddroplet 的样式表中,会胜出,而您的操作会默默无所作为. 狦 @import 在单个 CSS 文件中,将 put ditchlet 导入 第一个数字 :

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

什么主题

里面的东西 设计符号 下面的表格——颜色,阴影,弧度. 最常用的东西 :

对于语义颜色( 成功/ 危险/ 警告/ 进程) , 覆盖匹配 --<state>-default, (中文(简体) ), --<state>-light, (中文(简体) ), --text-<state> 三个.

将一个主题限定为应用程序的一部分

如果你只想要在树下丢出它们(例如,一个营销站点重用一个组件),就把超接放在包装类上,而不是 :root数字 :

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

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

颜色空间

滴盘用途 罢 整个 如果你的设计系统是六分之一/四分之一 oklch.com (英语) 或者说 oklch.fyi (英语) 将转换。 你没有 有过 将 OKLCH 用于您的覆盖 oklch(), (中文(简体) ), hex, (中文(简体) ), rgb(),以及 hsl() 所有的操作都很好,但是在OKLCH里,当你调谐时,你就会有 感知的统一的光度坡道.

设计符号

所有符號都由 CSS 自定义属性所定义 globals.css由 Tailwind 工具类直接绘制图 bg-brand-default 决定: var(--brand-default)。 。 。 .

颜色组

阴影系统

--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 */

半径比例

黑暗模式

应用 .dark 类改为 <html> 以激活深色调色板。 所有符号在下方重新定义 .dark 与 OKLCH 相匹配的值——品牌色调被保留,只有光度变化.

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

故事书

交互式组件文档,包含活的代号参考,暗模式切换,以及对每个故事的11y审计.

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

# From packages/droplet
pnpm storybook

运行在 http://localhost:4402 (英语)。 。 。 .

发展

# 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

技术堆栈