@phsa.tec/design-system-react 0.2.0 → 0.3.0

package/README.md

@@ -1,23 +1,20 @@
-# 🎨 PHSA Design System React
+# PHSA Design System React
 
-A modern, **fully isolated** React component library built with TypeScript, Tailwind CSS, and Radix UI. **No Tailwind installation required** in your project!
+A modern, **fully isolated** React component library built with TypeScript, Tailwind CSS, and Radix UI.
 
-## ✨ Features
+## Features
 
-- 🎯 **Zero Configuration** - Works out of the box, no Tailwind setup needed
-- 🔒 **Fully Isolated** - CSS is completely isolated, won't conflict with your project's styles
-- 🎨 **Customizable** - Easy theme customization via Provider props
-- 📦 **Lightweight** - Only includes the CSS you actually use
-- ♿ **Accessible** - Built with Radix UI primitives
-- 🌙 **Dark Mode** - Built-in dark mode support
+- **Zero Conflicts** - Fully isolated CSS, won't interfere with your project's styles
+- **Customizable** - Via CSS Variables or Tailwind Preset
+- **Accessible** - Built with Radix UI primitives
+- **Dark Mode** - Native dark theme support
+- **TypeScript** - Full type support
 
-## 📚 Documentation
+## Documentation
 
-🌐 **[View Live Documentation](https://henriques4nti4go.github.io/phsa-design-system/)**
+[View Full Documentation](https://henriques4nti4go.github.io/phsa-design-system/)
 
-## 🚀 Quick Start
-
-### 1. Install
+## Installation
 
 ```bash
 npm install @phsa.tec/design-system-react
@@ -27,9 +24,13 @@ yarn add @phsa.tec/design-system-react
 pnpm add @phsa.tec/design-system-react
 ```
 
-### 2. Wrap Your App
+## Basic Usage
 
 ```tsx
+// 1. Import CSS (required)
+import "@phsa.tec/design-system-react/styles.css";
+
+// 2. Import components
 import { DesignSystemProvider, Button, Card } from "@phsa.tec/design-system-react";
 
 function App() {
@@ -43,362 +44,150 @@ function App() {
 }
 ```
 
-**That's it!** The CSS is automatically injected. No configuration needed.
-
-## 🎨 Customization
-
-You can customize **all Tailwind properties** through the `DesignSystemProvider`:
-
-### Complete Theme Customization
-
-```tsx
-import { DesignSystemProvider } from "@phsa.tec/design-system-react";
-
-function App() {
-  return (
-    <DesignSystemProvider
-      theme={{
-        colors: {
-          primary: "#3b82f6",
-          secondary: "#10b981",
-          // ... all color options
-        },
-        spacing: {
-          base: "0.25rem",  // 4px
-          sm: "0.5rem",     // 8px
-          md: "1rem",       // 16px
-          lg: "1.5rem",     // 24px
-          xl: "2rem",       // 32px
-        },
-        typography: {
-          fontFamily: "Inter, sans-serif",
-          fontSize: {
-            sm: "0.875rem",
-            base: "1rem",
-            lg: "1.125rem",
-          },
-        },
-        borderRadius: {
-          sm: "0.25rem",
-          md: "0.5rem",
-          lg: "0.75rem",
-        },
-      }}
-    >
-      {/* Your app */}
-    </DesignSystemProvider>
-  );
-}
-```
-
-### Simple Color Customization (Legacy)
-
-For backward compatibility, you can still use the `colors` prop:
-
-```tsx
-<DesignSystemProvider
-  colors={{
-    primary: "#3b82f6",
-    secondary: "#10b981",
-  }}
->
-  {/* Your app */}
-</DesignSystemProvider>
-```
-
-### Available Theme Properties
+## Customization
 
-#### Colors (`theme.colors`)
+### Option 1: CSS Variables (Recommended)
 
-- `primary`, `primaryForeground`
-- `secondary`, `secondaryForeground`
-- `accent`, `accentForeground`
-- `destructive`, `destructiveForeground`
-- `success`, `successForeground`
-- `warning`
-- `muted`, `mutedForeground`
-- `background`, `foreground`
-- `card`, `cardForeground`
-- `popover`, `popoverForeground`
-- `border`, `input`, `ring`
-- `radius`
+Override CSS variables in your stylesheet:
 
-**Color formats supported:**
-- **Hex**: `"#3b82f6"`
-- **HSL**: `"217 91% 60%"` (without `hsl()` wrapper)
-- **RGB**: Standard RGB values
+```css
+/* globals.css */
+:root {
+  /* Primary colors */
+  --primary: 220 90% 50%;
+  --primary-foreground: 0 0% 100%;
+  --secondary: 210 40% 96%;
+  --secondary-foreground: 222 47% 11%;
 
-#### Spacing (`theme.spacing`)
+  /* Feedback colors */
+  --destructive: 0 84% 60%;
+  --success: 142 76% 36%;
+  --warning: 38 92% 50%;
 
-Customize spacing scale used by padding, margin, gap utilities:
+  /* Neutral colors */
+  --background: 0 0% 100%;
+  --foreground: 222 84% 5%;
+  --muted: 210 40% 96%;
+  --muted-foreground: 215 16% 47%;
+  --border: 214 32% 91%;
 
-```tsx
-theme={{
-  spacing: {
-    base: "0.25rem",  // Base unit (default: 4px)
-    xs: "0.5rem",     // Extra small
-    sm: "0.75rem",    // Small
-    md: "1rem",       // Medium
-    lg: "1.5rem",     // Large
-    xl: "2rem",       // Extra large
-    "2xl": "3rem",    // 2x extra large
-    "3xl": "4rem",    // 3x extra large
-  }
-}}
-```
-
-#### Typography (`theme.typography`)
-
-```tsx
-theme={{
-  typography: {
-    fontFamily: "Inter, sans-serif",
-    fontSize: {
-      xs: "0.75rem",
-      sm: "0.875rem",
-      base: "1rem",
-      lg: "1.125rem",
-      xl: "1.25rem",
-      "2xl": "1.5rem",
-      "3xl": "1.875rem",
-      "4xl": "2.25rem",
-      "5xl": "3rem",
-    },
-    fontWeight: {
-      light: "300",
-      normal: "400",
-      medium: "500",
-      semibold: "600",
-      bold: "700",
-    },
-    lineHeight: {
-      none: "1",
-      tight: "1.25",
-      snug: "1.375",
-      normal: "1.5",
-      relaxed: "1.75",
-      loose: "2",
-    },
-  }
-}}
-```
-
-#### Border Radius (`theme.borderRadius`)
-
-```tsx
-theme={{
-  borderRadius: {
-    none: "0px",
-    sm: "0.25rem",
-    md: "0.5rem",
-    lg: "0.75rem",
-    xl: "1rem",
-    "2xl": "1.5rem",
-    "3xl": "2rem",
-    full: "9999px",
-  }
-}}
-```
-
-#### Box Shadow (`theme.boxShadow`)
-
-```tsx
-theme={{
-  boxShadow: {
-    sm: "0 1px 2px 0 rgb(0 0 0 / 0.05)",
-    md: "0 4px 6px -1px rgb(0 0 0 / 0.1)",
-    lg: "0 10px 15px -3px rgb(0 0 0 / 0.1)",
-    xl: "0 20px 25px -5px rgb(0 0 0 / 0.1)",
-    "2xl": "0 25px 50px -12px rgb(0 0 0 / 0.25)",
-    inner: "inset 0 2px 4px 0 rgb(0 0 0 / 0.05)",
-    none: "none",
-  }
-}}
-```
-
-#### Breakpoints (`theme.breakpoints`)
-
-```tsx
-theme={{
-  breakpoints: {
-    sm: "640px",
-    md: "768px",
-    lg: "1024px",
-    xl: "1280px",
-    "2xl": "1536px",
-  }
-}}
-```
-
-## 🎯 Usage Examples
-
-### Basic Components
-
-```tsx
-import {
-  Button,
-  Input,
-  Card,
-  CardContent,
-  CardHeader,
-  CardTitle,
-  DesignSystemProvider,
-} from "@phsa.tec/design-system-react";
+  /* Other */
+  --radius: 0.5rem;
+  --font-family: "Inter", sans-serif;
+}
 
-function App() {
-  return (
-    <DesignSystemProvider>
-      <Card>
-        <CardHeader>
-          <CardTitle>Hello World</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
-            <Input placeholder="Enter text..." />
-            <Button>Click me</Button>
-          </div>
-        </CardContent>
-      </Card>
-    </DesignSystemProvider>
-  );
+/* Dark mode */
+.dark {
+  --background: 222 84% 5%;
+  --foreground: 210 40% 98%;
+  /* ... other variables */
 }
 ```
 
-### With Custom Theme
+### Option 2: Tailwind Preset (Advanced)
 
-```tsx
-import { DesignSystemProvider, Button } from "@phsa.tec/design-system-react";
+If your project uses Tailwind CSS, you can extend with our preset:
 
-function App() {
-  return (
-    <DesignSystemProvider
-      theme={{
-        colors: {
-          primary: "#8b5cf6",      // Purple
-          secondary: "#06b6d4",    // Cyan
-        },
-        spacing: {
-          md: "1.25rem",           // Custom medium spacing
-          lg: "2rem",              // Custom large spacing
-        },
-        typography: {
-          fontFamily: "Inter, sans-serif",
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require("@phsa.tec/design-system-react/tailwind-preset")],
+  theme: {
+    extend: {
+      // Your customizations
+      colors: {
+        primary: {
+          DEFAULT: "#your-color",
         },
-      }}
-    >
-      <Button variant="default">Primary Button</Button>
-      <Button variant="secondary">Secondary Button</Button>
-    </DesignSystemProvider>
-  );
-}
-```
+      },
+    },
+  },
+};
+```
+
+## Available CSS Variables
+
+### Colors
+
+| Variable | Description |
+|----------|-------------|
+| `--primary` | Primary color |
+| `--primary-foreground` | Text on primary color |
+| `--secondary` | Secondary color |
+| `--secondary-foreground` | Text on secondary color |
+| `--destructive` | Error/danger color |
+| `--success` | Success color |
+| `--warning` | Warning color |
+| `--muted` | Muted color |
+| `--muted-foreground` | Muted text |
+| `--background` | Page background |
+| `--foreground` | Main text |
+| `--border` | Border color |
+| `--input` | Input color |
+| `--ring` | Focus ring color |
 
-### Advanced Customization Example
+### Layout
 
-```tsx
-import { DesignSystemProvider, Card, Button } from "@phsa.tec/design-system-react";
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `--radius` | Base border radius | `0.5rem` |
+| `--font-family` | Font family | `"Roboto"` |
 
-function App() {
-  return (
-    <DesignSystemProvider
-      theme={{
-        colors: {
-          primary: "#6366f1",
-          secondary: "#8b5cf6",
-        },
-        spacing: {
-          base: "0.5rem",    // 8px base (instead of 4px)
-          md: "1.5rem",      // 24px medium
-          lg: "3rem",        // 48px large
-        },
-        typography: {
-          fontFamily: "'Inter', 'Roboto', sans-serif",
-          fontSize: {
-            base: "16px",
-            lg: "18px",
-            xl: "20px",
-          },
-          fontWeight: {
-            normal: "400",
-            semibold: "600",
-            bold: "700",
-          },
-        },
-        borderRadius: {
-          md: "0.75rem",
-          lg: "1rem",
-        },
-        boxShadow: {
-          md: "0 8px 16px -4px rgb(0 0 0 / 0.15)",
-          lg: "0 16px 32px -8px rgb(0 0 0 / 0.2)",
-        },
-      }}
-    >
-      <Card>
-        <Button>Customized Button</Button>
-      </Card>
-    </DesignSystemProvider>
-  );
-}
-```
+### Spacing
+
+| Variable | Description |
+|----------|-------------|
+| `--spacing-xs` | Extra small |
+| `--spacing-sm` | Small |
+| `--spacing-md` | Medium |
+| `--spacing-lg` | Large |
+| `--spacing-xl` | Extra large |
 
-## 🧩 Available Components
+## Available Components
 
 ### Layout
-- **Card** - Container component with header, content, and footer
-- **Sheet** - Slide-over panel
-- **Tabs** - Tab navigation
-- **Separator** - Visual divider
-- **PageLayout** - Full page layout wrapper
+- `Card`, `CardHeader`, `CardContent`, `CardFooter`
+- `Sheet`, `SheetContent`, `SheetHeader`
+- `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`
+- `Separator`
 
 ### Forms
-- **Input** - Text input with validation support
-- **Button** - Button with multiple variants
-- **Select** - Dropdown selection
-- **Checkbox** - Checkbox input
-- **Switch** - Toggle switch
-- **Form** - Form wrapper with React Hook Form integration
+- `Button`
+- `Input`
+- `Select`, `SelectTrigger`, `SelectContent`, `SelectItem`
+- `Checkbox`
+- `Switch`
+- `Label`
 
 ### Data Display
-- **DataTable** - Advanced table with sorting, filtering, pagination
-- **Badge** - Status badge
-- **Avatar** - User avatar
-- **Text** - Typography component
+- `DataTable`
+- `Badge`
+- `Avatar`
 
 ### Feedback
-- **Dialog** - Modal dialog
-- **AlertDialog** - Confirmation dialog
-- **Toast** - Notification toast
-- **Alert** - Alert message
-- **Spinner** - Loading spinner
+- `Dialog`, `DialogContent`, `DialogHeader`
+- `AlertDialog`
+- `Toast`, `Toaster`
+- `Alert`
+- `Spinner`
 
 ### Navigation
-- **DropdownMenu** - Dropdown menu
-- **Breadcrumbs** - Breadcrumb navigation
-- **Command** - Command palette
+- `DropdownMenu`
+- `Command`
+- `Popover`
 
-## 🌙 Dark Mode
+## Dark Mode
 
-The design system supports dark mode automatically. Add the `dark` class to your root element:
-
-```tsx
-// Toggle dark mode
-document.documentElement.classList.toggle('dark');
-```
-
-Or use `next-themes` for React:
-
-```bash
-npm install next-themes
-```
+Add the `dark` class to the root element:
 
 ```tsx
+// With next-themes
 import { ThemeProvider } from "next-themes";
 import { DesignSystemProvider } from "@phsa.tec/design-system-react";
 
 function App() {
   return (
-    <ThemeProvider attribute="class" defaultTheme="system" enableSystem>
+    <ThemeProvider attribute="class" defaultTheme="system">
       <DesignSystemProvider>
         {/* Your app */}
       </DesignSystemProvider>
@@ -407,44 +196,34 @@ function App() {
 }
 ```
 
-## 🔒 Isolation & Compatibility
-
-### ✅ Works With
-
-- ✅ Projects **without** Tailwind CSS
-- ✅ Projects **with** Tailwind CSS (no conflicts!)
-- ✅ Next.js, Vite, Create React App, etc.
-- ✅ Any React framework
-
-### How It Works
+## Compatibility
 
-The design system:
-1. **Compiles CSS at build time** - All Tailwind classes are pre-compiled
-2. **Uses unique class prefixes** - Classes are prefixed with `phsa-` to avoid conflicts
-3. **Scopes CSS with `.ds`** - All styles are scoped to prevent interference
-4. **Auto-injects CSS** - CSS is automatically loaded when you use `DesignSystemProvider`
+- Projects **without** Tailwind CSS
+- Projects **with** Tailwind CSS (no conflicts)
+- Next.js, Vite, Create React App
+- React 18+
 
-## 📦 Package Exports
+## Package Exports
 
 ```typescript
 // Components
 import { Button, Card } from "@phsa.tec/design-system-react";
 
-// Styles (if you need manual import)
-import "@phsa.tec/design-system-react/styles";
-// or
-import styles from "@phsa.tec/design-system-react/styles";
-```
+// CSS (required)
+import "@phsa.tec/design-system-react/styles.css";
 
-## 🛠️ Development
+// Tailwind Preset (optional)
+// In tailwind.config.js:
+// presets: [require("@phsa.tec/design-system-react/tailwind-preset")]
+```
 
-For local development and contributing:
+## Development
 
 ```bash
 # Install dependencies
 yarn install
 
-# Run Storybook
+# Storybook
 yarn storybook
 
 # Build library
@@ -453,24 +232,14 @@ yarn build:lib
 # Watch mode
 yarn build:lib:watch
 
-# Run tests
+# Tests
 yarn test
 ```
 
-## 📄 License
-
-MIT License - see [LICENSE](LICENSE) file for details.
-
-## 🤝 Contributing
-
-Contributions are welcome! Please read our contributing guidelines before submitting PRs.
-
-## 📞 Support
+## License
 
-- **Documentation**: [View Live Docs](https://henriques4nti4go.github.io/phsa-design-system/)
-- **Issues**: [GitHub Issues](https://github.com/henriques4nti4go/phsa-design-system/issues)
-- **Package**: [npm](https://www.npmjs.com/package/@phsa.tec/design-system-react)
+MIT
 
 ---
 
-Built with ❤️ by the PHSA team
+Built by the PHSA team