@admin-layout/tailwind-design-pro 10.1.1-alpha.9 → 11.2.1-alpha.1

package/README.md

@@ -1,17 +1,17 @@
 # Tailwind Design Pro
 
-A universal tailwind design system for use across all projects.
+A universal tailwind design system with multi-theme support and CSS custom properties for seamless theme switching.
 
 ## Features
 
--   Unified theme system with light and dark mode support
--   Consistent styling across all projects
--   Easy to customize and extend
--   Built-in typography, forms, and aspect ratio support
+-   **Multi-Theme System**: 5 pre-built themes (Default, Airbnb, Slack, GitHub, Spotify)
+-   **CSS Custom Properties**: Theme-aware styling with CSS variables
+-   **Dark/Light Mode**: Automatic theme switching with persistent preferences
+-   **Component Library**: Pre-built UI components with theme integration
+-   **Responsive Design**: Mobile-first approach with consistent breakpoints
+-   **Accessibility**: WCAG compliant color contrasts and focus states
 
-## Usage in Servers
-
-To use this package in your server project, follow these steps:
+## Quick Start
 
 ### 1. Install the package
 
@@ -19,327 +19,453 @@ To use this package in your server project, follow these steps:
 npm install @admin-layout/tailwind-design-pro
 ```
 
-### 2. Use the Universal Tailwind Config
+### 2. Import the CSS
+
+```typescript
+// In your main CSS file or entry point
+import '@admin-layout/tailwind-design-pro/src/styles/index.css';
+```
 
-Create a `tailwind.config.js` or `tailwind.config.ts` file in your server project and import the universal config:
+### 3. Configure Tailwind
 
 ```typescript
-// tailwind.config.ts or tailwind.config.js
+// tailwind.config.ts
 import { themeConfig } from '@admin-layout/tailwind-design-pro';
 
 export default {
-    // Override content paths to include server-specific paths
-    content: [
-        './src/**/{**,.client,.server}/**/*.{js,jsx,ts,tsx}',
-        './app/**/{**,.client,.server}/**/*.{js,jsx,ts,tsx}',
-        '../../packages/**/*.{js,jsx,ts,tsx}',
-        '../../packages-modules/**/*.{js,jsx,ts,tsx}',
-    ],
-
-    // You can add server-specific overrides here if needed
+    content: ['./src/**/*.{js,jsx,ts,tsx}', '../../packages/**/*.{js,jsx,ts,tsx}'],
     theme: {
-        extend: {
-            // Any server-specific extensions would go here
-            ...themeConfig,
-        },
+        extend: themeConfig,
     },
     darkMode: 'class',
-    variants: {
-        typography: ['dark'],
-    },
-    plugins: [typography, forms, aspectRatio],
+    plugins: [],
 };
 ```
 
-# Theme System Documentation
+### 4. Set up Theme Provider
 
-## Overview
+```tsx
+import { ThemeProviderTailwind } from '@admin-layout/tailwind-ui';
 
-The theme system provides a flexible and powerful way to manage the visual appearance of your application. It supports multiple pre-built themes (default, Airbnb, Slack, GitHub, and Spotify) and includes dark mode functionality.
+const App = () => {
+    const settings = {
+        theme: 'default', // 'default', 'airbnb', 'slack', 'github', 'spotify'
+        navTheme: 'light', // 'light' or 'dark'
+        primaryColor: '#000000',
+        fontFamily: 'Inter, sans-serif',
+    };
+
+    return (
+        <ThemeProviderTailwind settings={settings} actor={actor}>
+            <YourApp />
+        </ThemeProviderTailwind>
+    );
+};
+```
 
 ## Available Themes
 
-The system comes with several pre-built themes:
+### 1. Default Theme
 
--   `default`: A neutral theme with standard components
--   `airbnb`: Inspired by Airbnb's design system
--   `slack`: Based on Slack's color scheme and components
--   `github`: Following GitHub's design patterns
--   `spotify`: Matching Spotify's visual identity
+-   Clean, professional design
+-   Neutral color palette
+-   Perfect for business applications
 
-## Theme Structure
+### 2. Airbnb Theme
 
-Each theme follows a consistent structure defined by the `DefaultTheme` interface:
+-   Warm, welcoming colors
+-   Red accent colors
+-   Great for hospitality and travel apps
 
-```typescript
-interface DefaultTheme {
-    name: string;
-    colors: {
-        primary: ColorRamp;
-        secondary: ColorRamp;
-        accent: ColorRamp;
-        success: ColorRamp;
-        warning: ColorRamp;
-        error: ColorRamp;
-        neutral: ColorRamp;
-        background: {
-            light: string;
-            dark: string;
-        };
-        text: {
-            light: {
-                primary: string;
-                secondary: string;
-                tertiary: string;
-            };
-            dark: {
-                primary: string;
-                secondary: string;
-                tertiary: string;
-            };
-        };
-    };
-    borderRadius: {
-        sm: string;
-        DEFAULT: string;
-        md: string;
-        lg: string;
-        xl: string;
-        '2xl': string;
-        full: string;
-    };
-    fontFamily: {
-        sans: string[];
-        serif: string[];
-        mono: string[];
-    };
-    boxShadow: {
-        sm: string;
-        DEFAULT: string;
-        md: string;
-        lg: string;
-        xl: string;
-    };
-    components: {
-        buttons: {
-            primary: ButtonStyle;
-            secondary: ButtonStyle;
-        };
-        cards: {
-            borderRadius: string;
-            padding: string;
-            shadow: string;
-            border: string;
-        };
-        inputs: {
-            borderRadius: string;
-            borderColor: string;
-            focusBorderColor: string;
-            padding: string;
-            fontSize: string;
-            lineHeight: string;
-        };
-    };
-}
+### 3. Slack Theme
+
+-   Purple-based design
+-   Modern, collaborative feel
+-   Ideal for team communication tools
+
+### 4. GitHub Theme
+
+-   Dark, developer-friendly
+-   High contrast design
+-   Perfect for developer tools
+
+### 5. Spotify Theme
+
+-   Green accent colors
+-   Music and entertainment focused
+-   Great for media applications
+
+## Theme-Aware CSS Classes
+
+The design system provides theme-aware CSS classes that automatically adapt to the current theme:
+
+### Background Colors
+
+```css
+.bg-background          /* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+/* Main background */
+.bg-card               /* Card background */
+.bg-popover            /* Popover background */
+.bg-muted              /* Muted background */
+.bg-accent; /* Accent background */
 ```
 
-## Setting Up the Theme Provider
+### Text Colors
+
+```css
+.text-foreground        /* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+/* Primary text */
+.text-muted-foreground  /* Secondary text */
+.text-primary           /* Primary brand color */
+.text-secondary         /* Secondary brand color */
+.text-accent; /* Accent color */
+```
 
-To use the theme system, wrap your application with the `ThemeProviderTailwind` component:
+### Semantic Colors
+
+```css
+.text-success           /* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+/* Success text */
+.text-warning           /* Warning text */
+.text-error             /* Error text */
+.text-info              /* Info text */
+.bg-success             /* Success background */
+.bg-warning             /* Warning background */
+.bg-error               /* Error background */
+.bg-info; /* Info background */
+```
 
-```tsx
-import { ThemeProviderTailwind } from 'packages/tailwind-design-pro/src/components/ThemeProvider';
+### Component Classes
+
+```css
+.themed-button          /* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+/* Theme-aware button */
+.themed-card            /* Theme-aware card */
+.themed-input           /* Theme-aware input */
+.themed-modal           /* Theme-aware modal */
+.themed-dropdown        /* Theme-aware dropdown */
+.themed-sidebar; /* Theme-aware sidebar */
+```
 
-const App = () => {
-    const settings = {
-        theme: 'default', // or 'airbnb', 'slack', 'github', 'spotify'
-        themeType: 'light',
-        primaryColor: '#your-color',
-        fontFamily: 'your-font-family',
-        navTheme: 'light', // or 'dark'
-    };
+### Interactive Classes
+
+```css
+.interactive-hover      /* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+/* Hover effects */
+.focus-themed           /* Focus states */
+.rounded-themed         /* Theme-aware border radius */
+.shadow-themed-sm       /* Theme-aware shadows */
+.shadow-themed-md
+.shadow-themed-lg
+.shadow-themed-xl;
+```
 
-    return <ThemeProviderTailwind settings={settings}>{/* Your app components */}</ThemeProviderTailwind>;
+## Using Theme-Aware Components
+
+### Basic Usage
+
+```tsx
+import { Button, Card, CardContent, CardHeader, CardTitle } from '@admin-layout/tailwind-ui';
+
+const MyComponent = () => {
+    return (
+        <div className="bg-background text-foreground p-6">
+            <Card className="themed-card">
+                <CardHeader>
+                    <CardTitle className="text-foreground">Card Title</CardTitle>
+                </CardHeader>
+                <CardContent>
+                    <p className="text-muted-foreground">Card content</p>
+                    <Button className="themed-button interactive-hover">Click Me</Button>
+                </CardContent>
+            </Card>
+        </div>
+    );
 };
 ```
 
-## Using the useTheme Hook
+### Form Components
 
-The `useTheme` hook provides access to the current theme and theme-related functionality. Here's how to use it:
+```tsx
+const FormExample = () => {
+    return (
+        <form className="space-y-4">
+            <div>
+                <label className="text-foreground font-medium">Email</label>
+                <input type="email" className="w-full themed-input focus-themed" placeholder="Enter your email" />
+            </div>
+            <Button type="submit" className="themed-button">
+                Submit
+            </Button>
+        </form>
+    );
+};
+```
+
+### Theme Switching
 
 ```tsx
-import { useTheme } from 'packages/tailwind-design-pro/src/components/ThemeProvider';
+import { useTheme } from '@admin-layout/tailwind-ui';
 
-const YourComponent = () => {
-    const { themeName, theme, isDarkMode, toggleDarkMode } = useTheme();
+const ThemeSwitcher = () => {
+    const { theme, mode, toggleMode, setTheme, setMode } = useTheme();
 
     return (
-        <div>
-            {/* Access theme colors */}
-            <div style={{ color: theme.colors.primary[500] }}>Primary Color</div>
-
-            {/* Use theme-specific styles */}
-            <button
-                style={{
-                    borderRadius: theme.borderRadius.DEFAULT,
-                    fontFamily: theme.fontFamily.sans.join(', '),
-                }}
+        <div className="space-x-2">
+            <Button
+                onClick={() => setTheme('airbnb')}
+                className={theme === 'airbnb' ? 'themed-button' : 'bg-muted text-foreground'}
             >
-                Themed Button
-            </button>
-
-            {/* Toggle dark mode */}
-            <button onClick={toggleDarkMode}>Toggle {isDarkMode ? 'Light' : 'Dark'} Mode</button>
+                Airbnb
+            </Button>
+            <Button
+                onClick={() => setTheme('slack')}
+                className={theme === 'slack' ? 'themed-button' : 'bg-muted text-foreground'}
+            >
+                Slack
+            </Button>
+            <Button onClick={toggleDarkMode}>{mode === 'dark' ? 'Light' : 'Dark'} Mode</Button>
         </div>
     );
 };
 ```
 
-### Available Properties from useTheme
-
-1. `themeName`: The current theme name ('default', 'airbnb', 'slack', 'github', or 'spotify')
-2. `theme`: The complete theme object containing all styling properties
-3. `isDarkMode`: Boolean indicating if dark mode is active
-4. `toggleDarkMode`: Function to toggle between light and dark modes
+## CSS Custom Properties
+
+The design system uses CSS custom properties for dynamic theming:
+
+### Color Variables
+
+```css
+:root {
+    --background: 0 0% 100%;
+    --foreground: 222.2 84% 4.9%;
+    --primary: 222.2 47.4% 11.2%;
+    --primary-foreground: 210 40% 98%;
+    --secondary: 210 40% 96.1%;
+    --secondary-foreground: 222.2 47.4% 11.2%;
+    --muted: 210 40% 96.1%;
+    --muted-foreground: 215.4 16.3% 46.9%;
+    --accent: 210 40% 96.1%;
+    --accent-foreground: 222.2 47.4% 11.2%;
+    --destructive: 0 84.2% 60.2%;
+    --destructive-foreground: 210 40% 98%;
+    --border: 214.3 31.8% 91.4%;
+    --input: 214.3 31.8% 91.4%;
+    --ring: 222.2 84% 4.9%;
+    --radius: 0.5rem;
+}
+```
 
-## Theme Features
+### Theme-Specific Variables
 
-### 1. Dark Mode Support
+Each theme has its own set of variables:
 
--   Automatically handles dark mode through the `isDarkMode` state
--   Persists dark mode preference in localStorage
--   Applies appropriate dark mode classes to the document
+```css
+[data-theme='airbnb'] {
+    --primary: 0 100% 60%;
+    --background: 0 0% 100%;
+    /* ... other theme-specific variables */
+}
+```
 
-### 2. Dynamic Theme Switching
+## Best Practices
 
--   Themes can be changed dynamically through the settings prop
--   All theme properties are immediately applied when changed
+### 1. Use Theme-Aware Classes
 
-### 3. Component-Specific Styling
+```tsx
+// ✅ Good - Theme-aware
+<div className="bg-background text-foreground">
+    <Button className="themed-button">Click</Button>
+</div>
+
+// ❌ Avoid - Hardcoded colors
+<div className="bg-white text-black">
+    <Button className="bg-blue-500 text-white">Click</Button>
+</div>
+```
 
-Each theme includes specific styling for common components:
+### 2. Leverage Semantic Colors
 
--   Buttons (primary and secondary variants)
--   Cards
--   Input fields
+```tsx
+// ✅ Good - Semantic meaning
+<div className="text-success">Success message</div>
+<div className="text-error">Error message</div>
 
-### 4. Color System
+// ❌ Avoid - Hardcoded colors
+<div className="text-green-500">Success message</div>
+<div className="text-red-500">Error message</div>
+```
 
--   Each theme includes a comprehensive color system with:
-    -   Primary colors
-    -   Secondary colors
-    -   Accent colors
-    -   Semantic colors (success, warning, error)
-    -   Neutral colors
-    -   Background colors
-    -   Text colors
+### 3. Use Interactive Classes
 
-### 5. Typography
+```tsx
+// ✅ Good - Built-in interactions
+<Button className="themed-button interactive-hover">
+    Hover me
+</Button>
+
+// ❌ Avoid - Custom hover states
+<Button className="themed-button hover:scale-105 hover:shadow-lg">
+    Hover me
+</Button>
+```
 
--   Customizable font families for different text styles
--   Consistent typography settings across themes
+### 4. Responsive Design
 
-## Best Practices
+```tsx
+// ✅ Good - Responsive with theme
+<div className="bg-background p-4 md:p-6 lg:p-8">
+    <Card className="themed-card">
+        <CardContent className="p-4 md:p-6">Content</CardContent>
+    </Card>
+</div>
+```
 
-1. **Theme Access**
+## Migration Guide
 
-    ```tsx
-    const { theme } = useTheme();
-    // Use theme properties directly
-    const primaryColor = theme.colors.primary[500];
-    ```
+### From Inline Styles to CSS Classes
 
-2. **Dark Mode Handling**
+**Before:**
 
-    ```tsx
-    const { isDarkMode, toggleDarkMode } = useTheme();
-    // Use isDarkMode to conditionally render styles
-    const backgroundColor = isDarkMode ? theme.colors.background.dark : theme.colors.background.light;
-    ```
+```tsx
+const { theme, isDarkMode } = useTheme();
+const textColor = isDarkMode ? theme.colors.text.dark.primary : theme.colors.text.light.primary;
 
-3. **Component Styling**
+<div style={{ color: textColor, backgroundColor: theme.colors.background.light }}>Content</div>;
+```
 
-    ```tsx
-    const { theme } = useTheme();
-    // Use theme component styles
-    const buttonStyle = {
-        ...theme.components.buttons.primary,
-        // Add custom styles as needed
-    };
-    ```
-
-4. **Responsive Design**
-    ```tsx
-    const { theme } = useTheme();
-    // Use theme's responsive values
-    const cardStyle = {
-        borderRadius: theme.borderRadius.md,
-        boxShadow: theme.boxShadow.DEFAULT,
-    };
-    ```
+**After:**
 
-## Theme Customization
+```tsx
+<div className="bg-background text-foreground">Content</div>
+```
 
-### Creating a Custom Theme
+### From Custom Components to Theme-Aware Components
 
-You can create your own theme by following the `DefaultTheme` interface structure:
+**Before:**
 
-```typescript
-const customTheme: DefaultTheme = {
-    name: 'custom',
-    colors: {
-        // Define your color palette
-    },
-    // Define other theme properties
-};
+```tsx
+<button
+    style={{
+        backgroundColor: theme.components.buttons.primary.background,
+        color: theme.components.buttons.primary.text,
+        borderRadius: theme.components.buttons.primary.borderRadius,
+    }}
+>
+    Button
+</button>
 ```
 
-### Extending Existing Themes
-
-You can extend existing themes by importing them and modifying specific properties:
+**After:**
 
-```typescript
-import { defaultTheme } from './themes/default';
-
-const extendedTheme: DefaultTheme = {
-    ...defaultTheme,
-    name: 'extended',
-    colors: {
-        ...defaultTheme.colors,
-        primary: {
-            // Override primary colors
-        },
-    },
-};
+```tsx
+<Button className="themed-button">Button</Button>
 ```
 
 ## Troubleshooting
 
-### Common Issues
+### Theme Not Applying
 
-1. **Theme Not Applying**
+1. Ensure CSS is imported: `import '@admin-layout/tailwind-design-pro/src/styles/index.css'`
+2. Check that `ThemeProviderTailwind` wraps your app
+3. Verify theme name is valid: `'default'`, `'airbnb'`, `'slack'`, `'github'`, `'spotify'`
 
-    - Ensure the `ThemeProviderTailwind` is properly wrapped around your application
-    - Check if the theme name matches one of the available themes
-    - Verify that the settings prop is correctly configured
+### Dark Mode Not Working
 
-2. **Dark Mode Not Working**
+1. Check `navTheme` setting: `'light'` or `'dark'`
+2. Ensure `darkMode: 'class'` in Tailwind config
+3. Verify CSS custom properties are being applied
 
-    - Check if `navTheme` is properly set in the settings
-    - Verify that the dark mode classes are being applied to the document
-    - Ensure localStorage is accessible in your environment
+### Components Not Styled
 
-3. **Custom Styles Not Taking Effect**
-    - Verify that your custom theme follows the `DefaultTheme` interface
-    - Check if the theme is properly registered in the themes object
-    - Ensure the theme name is correctly referenced in the settings
+1. Use theme-aware classes: `themed-button`, `themed-card`, etc.
+2. Import components from `@admin-layout/tailwind-ui`
+3. Check that CSS custom properties are loaded
 
 ## Contributing
 
 When contributing to the theme system:
 
-1. Follow the existing theme structure
-2. Maintain consistency with other themes
-3. Include both light and dark mode variants
-4. Document any new theme properties or features
-5. Test the theme across different components and scenarios
+1. **Follow the CSS Custom Properties pattern**
+2. **Use semantic color names**
+3. **Test across all themes**
+4. **Ensure accessibility compliance**
+5. **Update documentation for new features**
+
+## Examples
+
+See the demo applications for complete examples:
+
+-   `packages-modules/demo/tailwind-browser` - Tailwind examples
+-   `packages-modules/demo/chakra-browser` - Chakra UI examples