@dynamic-labs-sdk/droplet 0.27.2 → 0.27.3

package/README.md

@@ -1,38 +1,30 @@
 # `@dynamic-labs-sdk/droplet`
 
-Dynamic Labs' internal 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.
+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
 
-This package is internal to the `dynamic-js-sdk` monorepo. Add it as a workspace dependency:
-
-```json
-{
-  "dependencies": {
-    "@dynamic-labs-sdk/droplet": "workspace:*"
-  }
-}
+```bash
+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
 
-Import the design tokens stylesheet **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.
+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.
 
-```ts
-import '@dynamic-labs-sdk/droplet/styles/globals.css';
-```
+### 1. Install and configure Tailwind v4
 
-If you're consuming from a source workspace (not the built `dist/`), use the relative path instead:
-
-```ts
-import '../../packages/droplet/src/styles/globals.css';
-```
-
-Your bundler must support Tailwind CSS v4 via the `@tailwindcss/vite` plugin:
+If you don't already have Tailwind v4, follow [the Tailwind v4 install guide](https://tailwindcss.com/docs/installation). The `@tailwindcss/vite` plugin is the simplest path for Vite/Next:
 
 ```ts
 // vite.config.ts
@@ -44,6 +36,26 @@ export default defineConfig({
 });
 ```
 
+### 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.
+
+```ts
+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:
+
+```css
+/* 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
@@ -194,6 +206,90 @@ import {
 
 ---
 
+## 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
+
+```css
+/* 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);
+}
+```
+
+```ts
+// 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**:
+
+```css
+@import '@dynamic-labs-sdk/droplet/styles/globals.css';
+@import './your-theme.css';
+```
+
+### What's themeable
+
+Anything in the [Design tokens](#design-tokens) table below — colors, shadows, radii. The most common things to override:
+
+| What you want to change                                       | Tokens                                                                                              |
+| ------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
+| Brand color (buttons, focus rings, links, selection)          | `--brand-default`, `--brand-hover`, `--brand-accented`, `--brand-light`, `--ring`, `--action`       |
+| Surfaces (page bg, cards, sidebar)                            | `--background`, `--card`, `--bg-bottom`, `--bg-default`, `--sidebar`                                |
+| Text colors                                                   | `--foreground`, `--muted-foreground`, `--text-link`                                                 |
+| Radius scale                                                  | `--radius-sm` through `--radius-4xl`                                                                |
+| Selection highlight                                           | `--selection-bg`                                                                                    |
+| Solid button top-highlight                                    | `--button-highlight`                                                                                |
+| Checkbox / radio hover fills                                  | `--checkbox-hover-fill`, `--radio-hover-fill`                                                       |
+
+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`:
+
+```css
+.my-theme {
+  --brand-default: oklch(0.67 0.21 30);
+  /* ... */
+}
+```
+
+```tsx
+<div className="my-theme">
+  <Button>Themed</Button>
+</div>
+```
+
+### Color space
+
+Droplet uses [OKLCH](https://oklch.com/) throughout. If your design system is in hex/rgb, tools like [oklch.com](https://oklch.com) or [oklch.fyi](https://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)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dynamic-labs-sdk/droplet",
-  "version": "0.27.2",
+  "version": "0.27.3",
   "type": "module",
   "main": "./dist/index.cjs",
   "module": "./dist/index.esm.js",
@@ -23,6 +23,9 @@
     "dist",
     "src/styles"
   ],
+  "sideEffects": [
+    "**/*.css"
+  ],
   "dependencies": {
     "@hugeicons/core-free-icons": "4.1.1",
     "@hugeicons/react": "1.1.6",
@@ -76,7 +79,13 @@
   "peerDependencies": {
     "next": ">=14",
     "react": ">=18",
-    "react-dom": ">=18"
+    "react-dom": ">=18",
+    "tailwindcss": ">=4"
+  },
+  "peerDependenciesMeta": {
+    "next": {
+      "optional": true
+    }
   },
   "scripts": {
     "build": "rm -rf dist && tsdown && pnpm exec tsc --emitDeclarationOnly -p ./tsconfig.lib.json",

package/src/styles/globals.css

@@ -227,6 +227,12 @@
   --shadow-field-hover: 0 0 0 1px oklch(0.278 0.03 256.85 / 0.18), 0px 0px 1px 0px oklch(0.278 0.03 256.85 / 0.10);
   --shadow-elevated: 0 0 0 1px oklch(0.278 0.03 256.85 / 0.10), 0px 5px 15px 0px oklch(0.278 0.03 256.85 / 0.08), 0px 15px 35px -5px oklch(0.278 0.03 256.85 / 0.20);
   --shadow-card-content: 0px 0px 2px 0px oklch(0.278 0.03 256.85 / 0.08), 0px 1px 2px 0px oklch(0.278 0.03 256.85 / 0.06);
+
+  /* ——— Component-specific overlays (themeable) ——— */
+  --selection-bg: oklch(0.574 0.207 257.4 / 0.15);
+  --checkbox-hover-fill: oklch(0.278 0.03 256.85 / 0.08);
+  --radio-hover-fill: oklch(0.278 0.03 256.85 / 0.12);
+  --button-highlight: oklch(1 0 0);
 }
 
 /* ═══════════════════════════════════════════════════════════
@@ -354,6 +360,12 @@
   --shadow-field-hover: 0 0 0 1px oklch(1 0 0 / 0.18), 0px 0px 1px 0px oklch(0 0 0 / 0.10);
   --shadow-elevated: 0 0 0 1px oklch(1 0 0 / 0.06), 0px 5px 15px 0px oklch(0 0 0 / 0.25), 0px 15px 35px -5px oklch(0 0 0 / 0.45);
   --shadow-card-content: 0px 0px 2px 0px oklch(0 0 0 / 0.08), 0px 1px 2px 0px oklch(0 0 0 / 0.06);
+
+  /* ——— Component-specific overlays (themeable) ——— */
+  --selection-bg: oklch(0.510 0.205 257 / 0.18);
+  --checkbox-hover-fill: oklch(1 0 0 / 0.10);
+  --radio-hover-fill: oklch(1 0 0 / 0.15);
+  --button-highlight: oklch(1 0 0);
 }
 
 @layer base {
@@ -384,7 +396,7 @@
   }
   /* Branded text selection */
   ::selection {
-    background-color: oklch(0.574 0.207 257.4 / 0.15);
+    background-color: var(--selection-bg);
     color: inherit;
   }
   /* Slashed zero + tabular nums for monospace contexts */
@@ -448,16 +460,12 @@
   position: absolute;
   inset: 2px;
   border-radius: 2px;
-  background: oklch(0.278 0.03 256.85 / 0.08);
+  background: var(--checkbox-hover-fill);
   opacity: 0;
   transition: opacity 150ms ease-out;
   pointer-events: none;
 }
 
-.dark [data-slot='checkbox'][data-state='unchecked']::before {
-  background: oklch(1 0 0 / 0.10);
-}
-
 [data-slot='checkbox'][data-state='unchecked']:not(:disabled):hover::before {
   opacity: 1;
 }
@@ -477,16 +485,12 @@
   top: 50%;
   left: 50%;
   transform: translate(-50%, -50%);
-  background: oklch(0.278 0.03 256.85 / 0.12);
+  background: var(--radio-hover-fill);
   opacity: 0;
   transition: opacity 150ms ease-out;
   pointer-events: none;
 }
 
-.dark [data-slot='radio-group-item'][data-state='unchecked']::before {
-  background: oklch(1 0 0 / 0.15);
-}
-
 [data-slot='radio-group-item'][data-state='unchecked']:not(:disabled):hover::before {
   opacity: 1;
 }
@@ -524,7 +528,7 @@
   position: absolute;
   inset: 0;
   border-radius: inherit;
-  background: linear-gradient(180deg, oklch(1 0 0 / 1), oklch(1 0 0 / 0));
+  background: linear-gradient(180deg, var(--button-highlight), transparent);
   opacity: 0.1;
   transition: opacity 0.5s;
   pointer-events: none;