@abhir9/pd-design-system 0.1.18 → 0.1.20

package/README.md

@@ -9,7 +9,7 @@ This design system follows a **headless-first, adapter-based architecture**:
 - **Props-only API**: Consumers use only props and variants, no className required
 - **Full TypeScript**: Complete autocomplete and type safety
 - **Adapter Layer**: Switch between UI engines (shadcn, Material, etc.) without app changes
-- **Semantic Tokens**: Intent-based design tokens that work across themes
+- **Semantic Tokens**: Design tokens that work across themes
 - **Framework Agnostic**: Design tokens and semantics are framework-agnostic
 
 ## Installation
@@ -21,21 +21,38 @@ npm install @pd-design/system
 ## Quick Start
 
 ```tsx
-import { ThemeProvider, Button, Input } from '@pd-design/system';
-import '@pd-design/system/styles';
+import { PdThemeProvider, Button, Input } from '@pd-design/system';
+import '@pd-design/system/styles.css';
 
 function App() {
   return (
-    <ThemeProvider adapter="shadcn" theme="base" mode="light">
-      <Button variant="primary" intent="danger" size="md">
+    <PdThemeProvider theme="base" mode="light">
+      <Button variant="destructive" size="md">
         Delete
       </Button>
       <Input placeholder="Enter text..." size="md" />
-    </ThemeProvider>
+    </PdThemeProvider>
   );
 }
 ```
 
+### Important: Style Isolation
+
+The design system uses **scoped styling** to prevent style conflicts:
+
+- ✅ **All Tailwind classes are prefixed with `pd-`** - No collision with consumer Tailwind
+- ✅ **All CSS variables are scoped under `.pd-root`** - No token leakage
+- ✅ **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:
+
+```tsx
+<PdThemeProvider theme="base" mode="light">
+  {/* Your design system components */}
+</PdThemeProvider>
+```
+
 ## Configuration
 
 Configure the design system globally:
@@ -51,7 +68,7 @@ setDesignSystemConfig({
 });
 ```
 
-Or use the `ThemeProvider`:
+Or use the `ThemeProvider` (full-featured with context):
 
 ```tsx
 <ThemeProvider adapter="shadcn" theme="base" mode="light">
@@ -59,22 +76,47 @@ Or use the `ThemeProvider`:
 </ThemeProvider>
 ```
 
+### 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.
+
+Both support the same `theme` and `mode` props.
+
 ## Components
 
 ### Button
 
 ```tsx
 <Button
-  variant="primary"    // primary | secondary | ghost | outline
-  intent="danger"      // primary | success | warning | danger | neutral
+  variant="primary"    // primary | secondary | ghost | destructive
   size="md"            // sm | md | lg
+  startIcon="Download" // Icon name (TypeScript autocomplete)
+  endIcon="ArrowRight" // Icon name (TypeScript autocomplete)
   loading={false}
   disabled={false}
+  asChild={false}      // Render as child element
 >
   Click me
 </Button>
 ```
 
+**For form submission buttons:**
+```tsx
+<form onSubmit={handleSubmit}>
+  <Button type="submit">Submit Form</Button>
+  <Button type="reset">Reset</Button>
+</form>
+```
+
+**Button with Icons:**
+```tsx
+<Button startIcon="Download">Download</Button>
+<Button endIcon="ArrowRight">Next</Button>
+<Button startIcon="Trash2" variant="destructive">Delete</Button>
+<Button startIcon="Save">Save</Button>
+```
+
 ### Input
 
 ```tsx
@@ -173,17 +215,62 @@ Or use the `ThemeProvider`:
     onOpenChange={setOpen}
     title="Success"
     description="Action completed"
-    intent="success"
   />
 </ToastProvider>
 ```
 
+## Icons
+
+The design system includes all [Lucide React icons](https://lucide.dev/) with TypeScript autocomplete support.
+
+### Using Icons with Components
+
+Use icon names as strings. TypeScript will autocomplete available icon names:
+
+```tsx
+import { Button } from '@pd-design/system';
+
+<Button startIcon="Download">Download</Button>
+<Button endIcon="ArrowRight">Next</Button>
+<Button startIcon="Trash2" variant="destructive">Delete</Button>
+```
+
+### Using Icons Standalone
+
+Import icons from the `Icons` namespace for standalone use:
+
+```tsx
+import { Icons } from '@pd-design/system';
+
+<Icons.Download className="h-4 w-4" />
+<Icons.Trash2 className="h-5 w-5 text-red-500" />
+<Icons.Heart className="h-6 w-6 fill-red-500" />
+```
+
+### Combining Icons and Components
+
+You can use icons standalone alongside components:
+
+```tsx
+import { Button, Icons } from '@pd-design/system';
+
+<Button startIcon="Download">
+  <Icons.Check className="ml-2 h-4 w-4" />
+  Download Complete
+</Button>
+```
+
+### Available Icons
+
+All Lucide React icons are available. TypeScript provides autocomplete for icon names when using with components. Browse all icons in Storybook or check the [Lucide Icons website](https://lucide.dev/icons/).
+
+**Popular icons:** `Download`, `Upload`, `Trash2`, `Edit`, `Save`, `Search`, `Settings`, `User`, `Mail`, `Bell`, `Heart`, `Star`, `Share`, `Copy`, `Check`, `X`, `Plus`, `Minus`, `ArrowRight`, `ArrowLeft`, `Home`, `Menu`, and 1000+ more.
+
 ## Variant System
 
 All components follow a strict, typed variant system:
 
-- **variant**: `primary` | `secondary` | `ghost` | `outline`
-- **intent**: `primary` | `success` | `warning` | `danger` | `neutral`
+- **variant**: `primary` | `secondary` | `ghost` | `destructive`
 - **size**: `sm` | `md` | `lg`
 - **state**: `loading` | `disabled`
 
@@ -191,25 +278,69 @@ No arbitrary strings or raw class overrides are allowed.
 
 ## Theming
 
-The design system uses CSS variables as the public contract. Themes can be switched without rebuilding:
+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:
 
 ```tsx
-<ThemeProvider theme="base" mode="dark">
-  {/* Dark mode */}
-</ThemeProvider>
+<PdThemeProvider theme="base" mode="dark">
+  {/* Base theme, dark mode */}
+</PdThemeProvider>
+
+<PdThemeProvider theme="brand" mode="light">
+  {/* Brand theme, light mode */}
+</PdThemeProvider>
+
+<PdThemeProvider theme="base" mode="system">
+  {/* Base theme, follows OS preference */}
+</PdThemeProvider>
 ```
 
+### Default Values
+
+- **adapter**: `'shadcn'` (default)
+- **theme**: `'base'` (default)
+- **mode**: `'system'` (default - follows OS preference)
+
 ### Custom Themes
 
-You can extend themes by overriding CSS variables:
+You can override tokens using CSS variables scoped to `.pd-root`:
+
+```tsx
+<PdThemeProvider 
+  theme="base" 
+  mode="light"
+  className="pd-root [--pd-primary:220_80%_50%]"
+>
+  {/* Custom primary color */}
+</PdThemeProvider>
+```
+
+Or via CSS:
 
 ```css
-:root {
-  --pd-intent-primary: #your-color;
-  --pd-intent-primary-hover: #your-hover-color;
+.pd-root {
+  --pd-primary: 220 80% 50%;
+  --pd-primary-foreground: 0 0% 98%;
 }
 ```
 
+### Per-Widget Theming
+
+You can wrap only part of your page with `PdThemeProvider` for widget-level theming:
+
+```tsx
+<div>
+  {/* Consumer styles */}
+  <PdThemeProvider theme="base" mode="dark">
+    {/* Design system widget with dark theme */}
+  </PdThemeProvider>
+</div>
+```
+
 ## Adapter Layer
 
 The adapter layer allows switching UI engines without changing application code:
@@ -234,10 +365,13 @@ npm run storybook
 Storybook includes:
 - All component variants
 - Interactive controls
-- Theme switcher (light/dark)
-- Adapter switcher
+- Theme switcher (base/brand)
+- Mode switcher (light/dark/system)
+- Adapter switcher (shadcn/material)
+- Icons browser with search
 - Accessibility panel
 - Code snippets
+- Live examples
 
 ## Architecture
 
@@ -247,28 +381,138 @@ src/
 ├── theme/           # Theme system & provider
 ├── primitives/      # Headless components
 ├── adapters/        # UI engine adapters
-└── components/      # Public components
+├── components/      # Public components
+└── styles/          # Scoped CSS (tokens.css, base.css)
 ```
 
+### Style Isolation Architecture
+
+The design system implements **4 guardrails** to prevent style conflicts:
+
+1. **Prefix all Tailwind classes** (`pd-`) - Utilities never collide with consumer Tailwind
+2. **Disable Tailwind preflight** - Consumer styles are never reset
+3. **Scope all tokens under `.pd-root`** - Tokens never leak outside the boundary
+4. **Ship compiled CSS** - Consumer doesn't need Tailwind to use components
+
+This ensures the design system works seamlessly with:
+- ✅ Consumer Tailwind projects
+- ✅ Material UI (MUI)
+- ✅ Ant Design
+- ✅ Bootstrap
+- ✅ Plain CSS projects
+- ✅ Any CSS framework or reset
+
 ## TypeScript
 
-Full TypeScript support with autocomplete:
+Full TypeScript support with autocomplete for all props:
 
 ```tsx
 <Button
-  variant="primary"  // ✅ Autocomplete
-  intent="danger"    // ✅ Autocomplete
-  size="md"          // ✅ Autocomplete
+  variant="primary"      // ✅ Autocomplete: primary | secondary | ghost | destructive
+  size="md"              // ✅ Autocomplete: sm | md | lg
+  startIcon="Download"   // ✅ Autocomplete: All Lucide icon names
+  endIcon="ArrowRight"   // ✅ Autocomplete: All Lucide icon names
+/>
+
+<PdThemeProvider
+  theme="base"           // ✅ Autocomplete: base | brand
+  mode="system"          // ✅ Autocomplete: light | dark | system
 />
 ```
 
+All types are exported and available for use:
+
+```tsx
+import type { 
+  Variant, 
+  Size, 
+  ButtonType,
+  ThemeName,
+  ThemeMode,
+  LucideIconName 
+} from '@pd-design/system';
+```
+
+## API Reference
+
+### Exports
+
+```tsx
+// Components
+import { 
+  Button, 
+  ButtonGroup, 
+  PdThemeProvider,
+  Icons 
+} from '@pd-design/system';
+
+// Theme
+import { 
+  ThemeProvider, 
+  useTheme,
+  setDesignSystemConfig,
+  getDesignSystemConfig 
+} from '@pd-design/system';
+
+// Types
+import type { 
+  Variant, 
+  Size, 
+  ButtonType,
+  ThemeName,
+  ThemeMode,
+  AdapterType,
+  LucideIconName 
+} from '@pd-design/system';
+
+// Icons
+import { Icons } from '@pd-design/system';
+// or individual icons
+import { Download, Trash2 } from '@pd-design/system';
+
+// Utilities
+import { 
+  getIcon, 
+  renderIcon, 
+  iconExists, 
+  getAvailableIconNames 
+} from '@pd-design/system';
+
+// Styles (required)
+import '@pd-design/system/styles.css';
+```
+
+### Component Props
+
+All components use consistent prop patterns:
+
+- **variant**: Visual style (`primary`, `secondary`, `ghost`, `destructive`)
+- **size**: Component size (`sm`, `md`, `lg`)
+- **disabled**: Disabled state
+- **loading**: Loading state (where applicable)
+- **startIcon/endIcon**: Icon names with TypeScript autocomplete
+
 ## Accessibility
 
-- Radix UI primitives for ARIA compliance
-- Keyboard navigation support
-- Focus ring standards
-- Screen reader labels
-- Contrast-safe tokens
+- ✅ Radix UI primitives for ARIA compliance
+- ✅ Keyboard navigation support (Tab, Enter, Space, Arrow keys)
+- ✅ Focus ring standards (visible focus indicators)
+- ✅ Screen reader labels (aria-label, aria-describedby)
+- ✅ Contrast-safe tokens (WCAG AA compliant)
+- ✅ Disabled state handling (aria-disabled, pointer-events)
+- ✅ Loading state indicators (aria-busy)
+
+## Browser Support
+
+- Chrome (latest)
+- Firefox (latest)
+- Safari (latest)
+- Edge (latest)
+- Mobile browsers (iOS Safari, Chrome Mobile)
+
+## Contributing
+
+This is an internal design system. For contributions, please follow the architecture guidelines in `ARCHITECTURE.md`.
 
 ## License