@sreedev/my3dui 0.1.9 → 0.2.2

package/README.md

@@ -41,6 +41,22 @@ yarn add @sreedev/my3dui react react-dom
 pnpm add @sreedev/my3dui react react-dom
 ```
 
+### Import styles (required for theming)
+
+Import the library's built CSS once in your app (e.g. in `main.tsx` or `_app.tsx`) so design tokens and Tailwind utilities apply:
+
+```tsx
+import "@sreedev/my3dui/styles.css";
+```
+
+Or from the package path:
+
+```tsx
+import "@sreedev/my3dui/styles.css";  // or "./node_modules/@sreedev/my3dui/dist/styles.css"
+```
+
+The CSS includes Tailwind base/components/utilities and all theme token definitions (`:root`, `.dark`, `.neon`, `.glass`, `.corporate`, `.vibrant`). You do **not** need to install Tailwind in your app to use My3DUI components; the built CSS is self-contained. For custom utilities or content beyond the library, you can still add your own Tailwind config and extend the theme.
+
 ### Optional Dependencies
 
 For 3D component support, install the following packages:
@@ -65,18 +81,58 @@ All components are exported from the main entry. Use tree-shaking for optimal bu
 
 **Effects:** `Particles`, `Bloom`, `Reflection`, `Fog`, `ShadowSystem`, `GlowEffect`, `WaveEffect`, `NoiseField`
 
+**Theme:** `ThemeProvider`, `useTheme`, `useThemeOptional`, `ThemeName`
+
+## Multi-theme system
+
+My3DUI ships with six themes controlled by a class on `document.documentElement`. Use `ThemeProvider` to switch themes and persist the choice.
+
+**Themes:** `light` (default), `dark`, `neon`, `glass`, `corporate`, `vibrant`
+
+```tsx
+import { ThemeProvider, useTheme } from "@sreedev/my3dui";
+import "@sreedev/my3dui/styles.css";
+
+function App() {
+  return (
+    <ThemeProvider defaultTheme="light" storageKey="my3dui-theme">
+      <Demo />
+    </ThemeProvider>
+  );
+}
+
+function Demo() {
+  const { theme, setTheme } = useTheme();
+  return (
+    <select value={theme} onChange={(e) => setTheme(e.target.value)}>
+      <option value="light">Light</option>
+      <option value="dark">Dark</option>
+      <option value="neon">Neon</option>
+      <option value="glass">Glass</option>
+      <option value="corporate">Corporate</option>
+      <option value="vibrant">Vibrant</option>
+    </select>
+  );
+}
+```
+
+All components use CSS variables for colors, so they automatically adapt to the active theme. No extra Tailwind setup is required in the consumer app when using the built CSS.
+
 ## Design system
 
 ### Design tokens
 
-The library uses a consistent token system (see `lib/tokens.ts`):
+The library uses two layers of tokens:
+
+**1. CSS variables (in `styles.css`)** — Drive theming; values are RGB triplets so Tailwind can apply opacity:
+
+- **Colors:** `--color-primary`, `--color-primary-foreground`, `--color-secondary`, `--color-accent`, `--color-danger`, `--color-success`, `--color-warning`, `--color-background`, `--color-foreground`, `--color-surface`, `--color-border`, `--color-text-primary`, `--color-text-secondary`, `--color-ring`, `--color-muted`, `--color-muted-foreground`
+- **Shadows:** `--shadow-soft`, `--shadow-glow`
+- **Radius:** `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl`, `--radius-2xl`, `--radius-full`
 
-- **Spacing:** Scale 0–24 (1 unit = 0.25rem). Use for `gap`, `padding`, `margin` in layouts.
-- **Radius:** `none`, `sm`, `md`, `lg`, `xl`, `2xl`, `3xl`, `full`.
-- **Z-index:** `dropdown`, `sticky`, `overlay`, `modal`, `popover`, `toast`, `tooltip`.
-- **Container sizes:** `sm` (48rem), `md` (64rem), `lg` (80rem), `xl` (87.5rem), `full`.
+Each theme (`:root`, `.dark`, `.neon`, `.glass`, `.corporate`, `.vibrant`) sets these variables.
 
-Components that accept numeric `gap` or `padding` (e.g. `Stack`, `Grid`, `Container`) use this spacing scale.
+**2. JS tokens (in `lib/tokens.ts`)** — Spacing scale, z-index scale, duration, breakpoints for layout and animation. Used by layout components and shared utilities.
 
 ### Variants (CVA)