@abhir9/pd-design-system 0.1.22 → 0.1.23

package/README.md

@@ -2,6 +2,43 @@
 
 Production-grade design system with adapter layer support. Built for teams who need a flexible, type-safe component library that can work with different UI engines without changing application code.
 
+## 🎯 What People Love About PD Design System
+
+- ✅ **3 Lines to Get Started** - No complex setup, just works
+- ✅ **System Mode Built-In** - Automatically follows OS dark/light preference
+- ✅ **Zero-Config Persistence** - Pass `storageKey` prop, localStorage sync is automatic
+- ✅ **Cross-Tab Sync** - Theme changes sync across browser tabs instantly
+- ✅ **Type-Safe** - Full TypeScript with autocomplete for all props
+- ✅ **Accessible** - WCAG 2.1 AA compliant, built on Radix UI
+- ✅ **Style Isolation** - Works with Tailwind, MUI, AntD, Bootstrap, or plain CSS
+- ✅ **50+ Components** - Buttons, Inputs, Modals, Dropdowns, and more
+- ✅ **1000+ Icons** - All Lucide icons with TypeScript autocomplete
+
+## Why PD Design System?
+
+### 🚀 **Incredibly Easy to Use**
+
+```tsx
+// That's it! Just 3 lines of code
+<ThemeProvider storageKey="my-theme">
+  <Button>Click me</Button>
+</ThemeProvider>
+```
+
+No complex setup. No manual theme management. No localStorage code. Everything works automatically.
+
+### ✨ **Key Features**
+
+- **🎯 Zero-Config Theme System** - Pass `storageKey` and everything works
+- **🌓 System Mode Support** - Automatically follows OS dark/light preference
+- **💾 Automatic Persistence** - localStorage sync with one prop
+- **🔄 Cross-Tab Sync** - Theme changes sync across browser tabs
+- **🎨 Semantic Tokens** - Design tokens that adapt to themes automatically
+- **📦 Type-Safe** - Full TypeScript with autocomplete
+- **♿ Accessible** - WCAG 2.1 AA compliant out of the box
+- **🔌 Adapter Layer** - Switch UI engines without changing app code
+- **🎭 Style Isolation** - Works with any CSS framework (Tailwind, MUI, AntD, etc.)
+
 ## Philosophy
 
 This design system follows a **headless-first, adapter-based architecture**:
@@ -11,6 +48,7 @@ This design system follows a **headless-first, adapter-based architecture**:
 - **Adapter Layer**: Switch between UI engines (shadcn, Material, etc.) without app changes
 - **Semantic Tokens**: Design tokens that work across themes
 - **Framework Agnostic**: Design tokens and semantics are framework-agnostic
+- **Zero-Config Theming**: Automatic system detection and localStorage sync
 
 ## Installation
 
@@ -20,22 +58,34 @@ npm install @pd-design/system
 
 ## Quick Start
 
+**Get started in 3 simple steps:**
+
 ```tsx
-import { PdThemeProvider, Button, Input } from '@pd-design/system';
+import { ThemeProvider, Button } from '@pd-design/system';
 import '@pd-design/system/styles.css';
 
 function App() {
   return (
-    <PdThemeProvider theme="base" mode="light">
-      <Button variant="destructive" size="md">
-        Delete
+    <ThemeProvider 
+      adapter="shadcn" 
+      theme="base" 
+      storageKey="my-app-theme"
+    >
+      <Button variant="primary" size="md">
+        Click me
       </Button>
-      <Input placeholder="Enter text..." size="md" />
-    </PdThemeProvider>
+    </ThemeProvider>
   );
 }
 ```
 
+That's it! 🎉 The `ThemeProvider` automatically handles:
+- ✅ **System preference detection** - Follows OS dark/light mode
+- ✅ **localStorage persistence** - Remembers user's theme choice
+- ✅ **Cross-tab sync** - Theme changes sync across browser tabs
+- ✅ **Class management** - Automatically adds `pd-root` and `pd-dark` classes
+- ✅ **CSS variables** - Sets all theme variables automatically
+
 ### Important: Style Isolation
 
 The design system uses **scoped styling** to prevent style conflicts:
@@ -45,17 +95,65 @@ The design system uses **scoped styling** to prevent style conflicts:
 - ✅ **Preflight is disabled** - Consumer styles are never reset
 - ✅ **Works with any consumer setup** - Tailwind, MUI, AntD, Bootstrap, or plain CSS
 
-**Always wrap your components with `PdThemeProvider`** to create the scoped boundary:
+**Always wrap your components with `ThemeProvider`** (or `PdThemeProvider`) to create the scoped boundary:
 
 ```tsx
-<PdThemeProvider theme="base" mode="light">
+<ThemeProvider storageKey="my-theme">
   {/* Your design system components */}
-</PdThemeProvider>
+</ThemeProvider>
+```
+
+The `ThemeProvider` automatically adds the `pd-root` class to your body element, so all tokens are properly scoped.
+
+## Complete Example
+
+Here's a complete example showing how easy it is:
+
+```tsx
+import { ThemeProvider, Button, useTheme } from '@pd-design/system';
+import '@pd-design/system/styles.css';
+
+function App() {
+  return (
+    <ThemeProvider 
+      adapter="shadcn" 
+      theme="base" 
+      storageKey="my-app-theme"  // Enable localStorage persistence
+    >
+      <ThemeToggle />
+      <Button variant="primary">Hello World</Button>
+    </ThemeProvider>
+  );
+}
+
+function ThemeToggle() {
+  const { config, setConfig } = useTheme();
+  
+  return (
+    <button onClick={() => {
+      const nextMode = config.mode === 'dark' ? 'light' : 'dark';
+      setConfig({ mode: nextMode });
+      // ✅ Automatically saved to localStorage
+      // ✅ Syncs across tabs
+      // ✅ Updates theme immediately
+    }}>
+      Switch to {config.mode === 'dark' ? 'Light' : 'Dark'} Mode
+    </button>
+  );
+}
 ```
 
+**What happens automatically:**
+1. ✅ Reads theme from localStorage on mount
+2. ✅ Detects system preference if mode is `'system'`
+3. ✅ Saves theme changes to localStorage
+4. ✅ Syncs changes across browser tabs
+5. ✅ Updates CSS variables and classes
+6. ✅ Manages `pd-root` and `pd-dark` classes
+
 ## Configuration
 
-Configure the design system globally:
+For advanced use cases, you can configure the design system globally:
 
 ```tsx
 import { setDesignSystemConfig } from '@pd-design/system';
@@ -68,18 +166,21 @@ setDesignSystemConfig({
 });
 ```
 
-Or use the `ThemeProvider` (full-featured with context):
+**Note:** When using `ThemeProvider` with `storageKey`, you don't need to call `setDesignSystemConfig` manually - it's handled automatically.
 
-```tsx
-<ThemeProvider adapter="shadcn" theme="base" mode="light">
-  {/* Your app */}
-</ThemeProvider>
-```
+### ThemeProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `adapter` | `'shadcn' \| 'material'` | `'shadcn'` | UI engine adapter |
+| `theme` | `'base' \| 'brand'` | `'base'` | Theme name |
+| `mode` | `'light' \| 'dark' \| 'system'` | `'system'` | Color mode (system follows OS) |
+| `storageKey` | `string?` | `undefined` | localStorage key for persistence (enables sync) |
 
 ### PdThemeProvider vs ThemeProvider
 
-- **`PdThemeProvider`**: Lightweight wrapper that creates the `.pd-root` scoped boundary. Use for simple theming needs.
-- **`ThemeProvider`**: Full-featured provider with React context, system preference detection, and CSS variable management. Use when you need theme context access via `useTheme()` hook.
+- **`PdThemeProvider`**: Lightweight wrapper that creates the `.pd-root` scoped boundary. Use for simple theming needs without context.
+- **`ThemeProvider`**: Full-featured provider with React context, system preference detection, localStorage sync, and CSS variable management. **Recommended for most use cases.**
 
 Both support the same `theme` and `mode` props.
 
@@ -283,20 +384,69 @@ The design system supports **themes** and **modes** as separate concepts:
 - **Theme** (`theme`): The design theme name - `'base'` | `'brand'`
 - **Mode** (`mode`): The color scheme - `'light'` | `'dark'` | `'system'`
 
-The design system uses **scoped CSS variables** under `.pd-root`. Themes and modes can be switched without rebuilding:
+### System Mode 🌓
+
+The `'system'` mode automatically follows your OS dark/light preference:
 
 ```tsx
-<PdThemeProvider theme="base" mode="dark">
-  {/* Base theme, dark mode */}
-</PdThemeProvider>
+<ThemeProvider storageKey="my-theme">
+  {/* 
+    - If OS is dark → uses dark mode
+    - If OS is light → uses light mode
+    - Automatically updates when OS preference changes
+    - Works perfectly with localStorage persistence
+  */}
+</ThemeProvider>
+```
 
-<PdThemeProvider theme="brand" mode="light">
-  {/* Brand theme, light mode */}
-</PdThemeProvider>
+**How it works:**
+- On mount, detects OS preference
+- Listens to OS preference changes in real-time
+- Only applies system changes when mode is `'system'`
+- When user manually selects `'light'` or `'dark'`, system changes are ignored
 
-<PdThemeProvider theme="base" mode="system">
-  {/* Base theme, follows OS preference */}
-</PdThemeProvider>
+### localStorage Persistence 💾
+
+Pass `storageKey` to enable automatic theme persistence:
+
+```tsx
+<ThemeProvider storageKey="my-app-theme">
+  {/* 
+    ✅ Reads saved preference on mount
+    ✅ Saves changes automatically
+    ✅ Syncs across browser tabs
+    ✅ Works with system mode
+  */}
+</ThemeProvider>
+```
+
+**What gets saved:**
+- User's manual selection (`'light'` | `'dark'`)
+- `'system'` preference (so it knows to follow OS)
+
+**Example flow:**
+1. User selects "Dark" → Saved to localStorage
+2. User refreshes page → Reads "Dark" from localStorage
+3. User opens new tab → Reads "Dark" from localStorage (synced)
+4. User changes to "System" → Saved, now follows OS preference
+
+### Theme Examples
+
+```tsx
+// Base theme, dark mode
+<ThemeProvider theme="base" mode="dark" storageKey="my-theme">
+  {/* Your app */}
+</ThemeProvider>
+
+// Brand theme, light mode
+<ThemeProvider theme="brand" mode="light" storageKey="my-theme">
+  {/* Your app */}
+</ThemeProvider>
+
+// Base theme, follows OS preference (recommended)
+<ThemeProvider theme="base" storageKey="my-theme">
+  {/* Default mode is 'system' - follows OS */}
+</ThemeProvider>
 ```
 
 ### Default Values
@@ -304,6 +454,7 @@ The design system uses **scoped CSS variables** under `.pd-root`. Themes and mod
 - **adapter**: `'shadcn'` (default)
 - **theme**: `'base'` (default)
 - **mode**: `'system'` (default - follows OS preference)
+- **storageKey**: `undefined` (no persistence by default, pass a key to enable)
 
 ### Custom Themes
 
@@ -363,15 +514,16 @@ npm run storybook
 ```
 
 Storybook includes:
-- All component variants
-- Interactive controls
-- Theme switcher (base/brand)
-- Mode switcher (light/dark/system)
-- Adapter switcher (shadcn/material)
-- Icons browser with search
-- Accessibility panel
-- Code snippets
-- Live examples
+- ✅ All component variants with live examples
+- ✅ Interactive controls for all props
+- ✅ **Theme switcher** (base/brand) - See components in different themes
+- ✅ **Mode switcher** (light/dark/system) - Test system mode detection
+- ✅ **Adapter switcher** (shadcn/material) - Switch UI engines
+- ✅ **Icons browser** with search - Browse 1000+ Lucide icons
+- ✅ **Accessibility panel** - WCAG compliance checks
+- ✅ **Code snippets** - Copy-paste ready examples
+- ✅ **Design tokens showcase** - See all color primitives and semantic tokens
+- ✅ **Dark mode preview** - See how components look in dark mode
 
 ## Architecture
 
@@ -446,10 +598,10 @@ import {
   Icons 
 } from '@pd-design/system';
 
-// Theme
+// Theme (Recommended: ThemeProvider with storageKey)
 import { 
-  ThemeProvider, 
-  useTheme,
+  ThemeProvider,      // Full-featured provider with localStorage sync
+  useTheme,           // Hook to access/update theme
   setDesignSystemConfig,
   getDesignSystemConfig 
 } from '@pd-design/system';
@@ -502,6 +654,74 @@ All components use consistent prop patterns:
 - ✅ Disabled state handling (aria-disabled, pointer-events)
 - ✅ Loading state indicators (aria-busy)
 
+## Common Use Cases
+
+### Use Case 1: Basic Setup with Persistence
+
+```tsx
+<ThemeProvider storageKey="my-app-theme">
+  <App />
+</ThemeProvider>
+```
+
+**What you get:**
+- ✅ System mode detection (follows OS)
+- ✅ Theme persistence (remembers user choice)
+- ✅ Cross-tab sync
+- ✅ Zero configuration
+
+### Use Case 2: Force Light Mode
+
+```tsx
+<ThemeProvider mode="light">
+  <App />
+</ThemeProvider>
+```
+
+**What you get:**
+- ✅ Always light mode
+- ✅ Ignores system preference
+- ✅ No localStorage (no storageKey)
+
+### Use Case 3: Custom Theme with System Mode
+
+```tsx
+<ThemeProvider 
+  theme="brand" 
+  storageKey="my-brand-theme"
+>
+  <App />
+</ThemeProvider>
+```
+
+**What you get:**
+- ✅ Brand theme
+- ✅ System mode with persistence
+- ✅ User can override system preference
+
+### Use Case 4: Theme Toggle Component
+
+```tsx
+function ThemeToggle() {
+  const { config, setConfig } = useTheme();
+  
+  const toggle = () => {
+    const modes: ThemeMode[] = ['light', 'dark', 'system'];
+    const currentIndex = modes.indexOf(config.mode);
+    const nextIndex = (currentIndex + 1) % modes.length;
+    setConfig({ mode: modes[nextIndex] });
+  };
+  
+  return (
+    <button onClick={toggle}>
+      {config.mode === 'system' && '🌓 System'}
+      {config.mode === 'light' && '☀️ Light'}
+      {config.mode === 'dark' && '🌙 Dark'}
+    </button>
+  );
+}
+```
+
 ## Browser Support
 
 - Chrome (latest)
@@ -510,6 +730,37 @@ All components use consistent prop patterns:
 - Edge (latest)
 - Mobile browsers (iOS Safari, Chrome Mobile)
 
+## Quick Reference
+
+### ThemeProvider Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `adapter` | `'shadcn' \| 'material'` | `'shadcn'` | UI engine adapter |
+| `theme` | `'base' \| 'brand'` | `'base'` | Theme name |
+| `mode` | `'light' \| 'dark' \| 'system'` | `'system'` | Color mode |
+| `storageKey` | `string?` | `undefined` | localStorage key (enables persistence) |
+
+### What Happens When You Pass `storageKey`?
+
+✅ **Automatic localStorage sync** - Reads and writes theme preference  
+✅ **Cross-tab synchronization** - Changes sync across browser tabs  
+✅ **System mode support** - Follows OS preference when mode is `'system'`  
+✅ **Class management** - Automatically adds `pd-root` and `pd-dark` classes  
+✅ **CSS variables** - Sets all theme variables automatically  
+
+### System Mode Behavior
+
+- **`mode="system"`** (default): Follows OS dark/light preference, updates automatically
+- **`mode="light"`**: Always light mode, ignores system preference
+- **`mode="dark"`**: Always dark mode, ignores system preference
+
+When `storageKey` is provided:
+- User's manual selection (`light`/`dark`) is saved
+- `system` preference is also saved
+- On refresh, uses saved preference
+- System changes only apply when mode is `'system'`
+
 ## Contributing
 
 This is an internal design system. For contributions, please follow the architecture guidelines in `ARCHITECTURE.md`.

package/dist/index.css

@@ -616,6 +616,9 @@
   font-family: var(--pd-font-sans, Gist, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
   color: var(--pd-text-body, var(--pd-content-primary));
   background: var(--pd-background-primary);
+  /* Set font-size to 16px to ensure rem-based calculations use standard base */
+  /* This prevents consumer's root font-size (e.g., 10px) from affecting pd-design components */
+  font-size: 16px;
 }
 /* Ensure interactive elements behave correctly even with global resets */
 .pd-root button {
@@ -1147,6 +1150,9 @@
 .pd-overflow-hidden {
   overflow: hidden;
 }
+.pd-overflow-x-auto {
+  overflow-x: auto;
+}
 .pd-truncate {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -1244,6 +1250,9 @@
 .\!pd-bg-\[var\(--pd-background-tertiary\)\] {
   background-color: var(--pd-background-tertiary) !important;
 }
+.pd-bg-\[var\(--pd-background-blue\)\] {
+  background-color: var(--pd-background-blue);
+}
 .pd-bg-\[var\(--pd-background-green\)\] {
   background-color: var(--pd-background-green);
 }

package/dist/styles.css

@@ -625,6 +625,7 @@
   font-family: var(--pd-font-sans, Gist, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif);
   color: var(--pd-text-body, var(--pd-content-primary));
   background: var(--pd-background-primary);
+  font-size: 16px;
 }
 .pd-root button {
   font-family: var(--pd-font-sans, Gist, sans-serif);
@@ -1148,6 +1149,9 @@
 .pd-overflow-hidden {
   overflow: hidden;
 }
+.pd-overflow-x-auto {
+  overflow-x: auto;
+}
 .pd-truncate {
   overflow: hidden;
   text-overflow: ellipsis;
@@ -1245,6 +1249,9 @@
 .\!pd-bg-\[var\(--pd-background-tertiary\)\] {
   background-color: var(--pd-background-tertiary) !important;
 }
+.pd-bg-\[var\(--pd-background-blue\)\] {
+  background-color: var(--pd-background-blue);
+}
 .pd-bg-\[var\(--pd-background-green\)\] {
   background-color: var(--pd-background-green);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abhir9/pd-design-system",
-  "version": "0.1.22",
+  "version": "0.1.23",
   "description": "Production-grade design system with adapter layer support",
   "type": "module",
   "main": "./dist/index.cjs",