@tydavidson/design-system 1.1.5 → 1.1.7

package/docs/theme-usage.md

@@ -0,0 +1,668 @@
+# Float Design System - Theme System Guide
+
+A comprehensive guide for implementing and using the Float Design System's theme system in your React applications.
+
+## Table of Contents
+
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Components](#core-components)
+- [Theme Variables](#theme-variables)
+- [Advanced Usage](#advanced-usage)
+- [Framework Integration](#framework-integration)
+- [Troubleshooting](#troubleshooting)
+
+## Installation
+
+```bash
+npm install @tydavidson/design-system
+```
+
+## Quick Start
+
+### 1. Import Theme CSS
+
+Import the theme CSS to get access to all theme variables:
+
+```css
+/* In your main CSS file */
+@import '@tydavidson/design-system/themes/theme.css';
+```
+
+Or in your JavaScript/TypeScript:
+
+```typescript
+import '@tydavidson/design-system/themes/theme.css';
+```
+
+### 2. Set up Theme Providers
+
+Wrap your app with the theme providers:
+
+```tsx
+import { ThemeProvider, ThemeContextProvider } from '@tydavidson/design-system';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeContextProvider>
+        {/* Your app content */}
+        <Header />
+        <Main />
+        <Footer />
+      </ThemeContextProvider>
+    </ThemeProvider>
+  );
+}
+```
+
+### 3. Add Theme Toggle
+
+Add the theme toggle component to your app:
+
+```tsx
+import { ThemeToggle } from '@tydavidson/design-system';
+
+function Header() {
+  return (
+    <header className="bg-bg-primary border-b border-border-primary p-4">
+      <div className="flex items-center justify-between">
+        <h1 className="text-text-primary text-xl font-bold">My App</h1>
+        <ThemeToggle variant="icon" size="md" />
+      </div>
+    </header>
+  );
+}
+```
+
+## Core Components
+
+### ThemeToggle
+
+A flexible component for switching between light and dark themes with multiple variants.
+
+```tsx
+import { ThemeToggle } from '@tydavidson/design-system';
+
+// Icon variant (default) - Compact toggle with sun/moon icons
+<ThemeToggle variant="icon" size="md" />
+
+// Button variant - Full button with text
+<ThemeToggle variant="button" size="lg" />
+
+// Switch variant - Toggle switch style
+<ThemeToggle variant="switch" size="sm" />
+```
+
+**Props:**
+- `variant`: `'icon' | 'switch' | 'button'` (default: `'icon'`)
+- `size`: `'sm' | 'md' | 'lg'` (default: `'md'`)
+- `className`: Additional CSS classes
+
+**Examples:**
+
+```tsx
+// In a header
+<div className="flex items-center gap-4">
+  <ThemeToggle variant="icon" size="sm" />
+  <ThemeToggle variant="button" size="md" />
+</div>
+
+// In a sidebar
+<nav className="flex flex-col gap-2">
+  <ThemeToggle variant="switch" size="lg" />
+</nav>
+```
+
+### useTheme Hook
+
+Access theme state and functions in your components:
+
+```tsx
+import { useTheme } from '@tydavidson/design-system';
+
+function ThemeAwareComponent() {
+  const { 
+    theme,           // Current theme setting ('light', 'dark', 'system')
+    setTheme,        // Function to change theme
+    resolvedTheme,   // Actual theme ('light' or 'dark')
+    isDark,          // Boolean for dark mode
+    isClient         // Boolean for client-side rendering
+  } = useTheme();
+  
+  return (
+    <div className="p-4 bg-bg-secondary border border-border-primary rounded-lg">
+      <h3 className="text-text-primary font-semibold mb-2">Theme Information</h3>
+      <div className="space-y-1 text-sm text-text-secondary">
+        <p>Current setting: {theme}</p>
+        <p>Resolved theme: {resolvedTheme}</p>
+        <p>Is dark mode: {isDark ? 'Yes' : 'No'}</p>
+      </div>
+      
+      <div className="flex gap-2 mt-4">
+        <button 
+          onClick={() => setTheme('light')}
+          className="px-3 py-1 bg-bg-primary border border-border-primary rounded text-text-primary hover:bg-bg-tertiary"
+        >
+          Light
+        </button>
+        <button 
+          onClick={() => setTheme('dark')}
+          className="px-3 py-1 bg-bg-primary border border-border-primary rounded text-text-primary hover:bg-bg-tertiary"
+        >
+          Dark
+        </button>
+        <button 
+          onClick={() => setTheme('system')}
+          className="px-3 py-1 bg-bg-primary border border-border-primary rounded text-text-primary hover:bg-bg-tertiary"
+        >
+          System
+        </button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Theme Variables
+
+### CSS Variables
+
+The theme system provides comprehensive CSS custom properties:
+
+```css
+/* Background colors */
+.my-component {
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  border: 1px solid var(--border-primary);
+}
+
+/* Semantic colors */
+.success-message {
+  background-color: var(--bg-success-primary);
+  color: var(--text-success-primary);
+  border-color: var(--border-success);
+}
+
+.error-message {
+  background-color: var(--bg-error-primary);
+  color: var(--text-error-primary);
+  border-color: var(--border-error);
+}
+```
+
+### Tailwind Classes
+
+Use semantic color classes with Tailwind CSS:
+
+```tsx
+// Basic layout
+<div className="bg-bg-primary text-text-primary min-h-screen">
+  <header className="bg-bg-secondary border-b border-border-primary p-4">
+    <h1 className="text-text-primary font-bold">My App</h1>
+  </header>
+  
+  <main className="p-6">
+    <div className="bg-bg-tertiary border border-border-secondary rounded-lg p-4">
+      <p className="text-text-secondary">Content goes here</p>
+    </div>
+  </main>
+</div>
+
+// Semantic components
+<div className="space-y-4">
+  <div className="bg-bg-success-primary text-text-success-primary border border-border-success rounded p-3">
+    Success message
+  </div>
+  
+  <div className="bg-bg-error-primary text-text-error-primary border border-border-error rounded p-3">
+    Error message
+  </div>
+  
+  <div className="bg-bg-warning-primary text-text-warning-primary border border-border-warning rounded p-3">
+    Warning message
+  </div>
+</div>
+```
+
+### Available Color Variables
+
+#### Background Colors
+- `--bg-primary` / `bg-bg-primary` - Main background
+- `--bg-secondary` / `bg-bg-secondary` - Secondary background
+- `--bg-tertiary` / `bg-bg-tertiary` - Tertiary background
+- `--bg-quaternary` / `bg-bg-quaternary` - Quaternary background
+- `--bg-disabled` / `bg-bg-disabled` - Disabled state background
+- `--bg-overlay` / `bg-bg-overlay` - Overlay/modal background
+
+#### Text Colors
+- `--text-primary` / `text-text-primary` - Primary text
+- `--text-secondary` / `text-text-secondary` - Secondary text
+- `--text-tertiary` / `text-text-tertiary` - Tertiary text
+- `--text-disabled` / `text-text-disabled` - Disabled text
+
+#### Border Colors
+- `--border-primary` / `border-border-primary` - Primary borders
+- `--border-secondary` / `border-border-secondary` - Secondary borders
+- `--border-tertiary` / `border-border-tertiary` - Tertiary borders
+- `--border-disabled` / `border-border-disabled` - Disabled borders
+
+#### Brand Colors
+- `--bg-brand-primary` / `bg-bg-brand-primary` - Brand background
+- `--text-brand-primary` / `text-text-brand-primary` - Brand text
+- `--border-brand` / `border-border-brand` - Brand borders
+
+#### Semantic Colors
+- **Error**: `--bg-error-primary`, `--text-error-primary`, `--border-error`
+- **Warning**: `--bg-warning-primary`, `--text-warning-primary`, `--border-warning`
+- **Success**: `--bg-success-primary`, `--text-success-primary`, `--border-success`
+
+## Advanced Usage
+
+### Custom Theme Detection
+
+```tsx
+import { isDarkTheme } from '@tydavidson/design-system';
+
+function ConditionalComponent() {
+  const { theme, systemTheme } = useTheme();
+  const isDark = isDarkTheme(theme, systemTheme);
+  
+  return (
+    <div className={isDark ? 'dark-mode-styles' : 'light-mode-styles'}>
+      {isDark ? 'Dark mode content' : 'Light mode content'}
+    </div>
+  );
+}
+```
+
+### Color Mapping Utilities
+
+```tsx
+import { 
+  mapColorToShadcnVariant, 
+  mapVariantToShadcnVariant,
+  getColorVariantClasses 
+} from '@tydavidson/design-system';
+
+// Map design system colors to shadcn variants
+const variant = mapColorToShadcnVariant('brand'); // returns 'default'
+const errorVariant = mapColorToShadcnVariant('error'); // returns 'destructive'
+
+// Map design system variants to shadcn variants
+const shadcnVariant = mapVariantToShadcnVariant('primary'); // returns 'default'
+const outlineVariant = mapVariantToShadcnVariant('secondary'); // returns 'outline'
+
+// Get Tailwind classes for color/variant combinations
+const primaryClasses = getColorVariantClasses('brand', 'primary');
+// returns: 'bg-brand-600 hover:bg-brand-700 text-white focus-visible:ring-brand-500'
+
+const secondaryClasses = getColorVariantClasses('error', 'secondary');
+// returns: 'border-error-300 text-error-700 hover:bg-error-50 focus-visible:ring-error-500'
+```
+
+### Dynamic Theme Switching
+
+```tsx
+import { useTheme } from '@tydavidson/design-system';
+
+function ThemeSwitcher() {
+  const { theme, setTheme, resolvedTheme } = useTheme();
+  
+  const themes = [
+    { value: 'light', label: 'Light', icon: '☀️' },
+    { value: 'dark', label: 'Dark', icon: '🌙' },
+    { value: 'system', label: 'System', icon: '💻' }
+  ];
+  
+  return (
+    <div className="flex gap-2">
+      {themes.map(({ value, label, icon }) => (
+        <button
+          key={value}
+          onClick={() => setTheme(value)}
+          className={`px-3 py-2 rounded border transition-colors ${
+            theme === value
+              ? 'bg-bg-brand-primary text-text-brand-primary border-border-brand'
+              : 'bg-bg-primary text-text-primary border-border-primary hover:bg-bg-secondary'
+          }`}
+        >
+          <span className="mr-2">{icon}</span>
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}
+```
+
+### Theme-Aware Components
+
+```tsx
+import { useTheme } from '@tydavidson/design-system';
+
+function ThemeAwareCard({ title, children, variant = 'default' }) {
+  const { isDark } = useTheme();
+  
+  const variants = {
+    default: 'bg-bg-primary border-border-primary',
+    elevated: isDark ? 'bg-bg-secondary border-border-secondary shadow-lg' : 'bg-white border-border-primary shadow-md',
+    brand: 'bg-bg-brand-primary border-border-brand',
+    error: 'bg-bg-error-primary border-border-error',
+    success: 'bg-bg-success-primary border-border-success'
+  };
+  
+  return (
+    <div className={`p-6 rounded-lg border ${variants[variant]}`}>
+      <h3 className="text-text-primary font-semibold mb-3">{title}</h3>
+      <div className="text-text-secondary">{children}</div>
+    </div>
+  );
+}
+
+// Usage
+<ThemeAwareCard title="Default Card" variant="default">
+  This is a default card
+</ThemeAwareCard>
+
+<ThemeAwareCard title="Brand Card" variant="brand">
+  This is a brand-themed card
+</ThemeAwareCard>
+```
+
+## Framework Integration
+
+### Next.js App Router
+
+```tsx
+// app/layout.tsx
+import { ThemeProvider, ThemeContextProvider } from '@tydavidson/design-system';
+import '@tydavidson/design-system/themes/theme.css';
+
+export default function RootLayout({
+  children,
+}: {
+  children: React.ReactNode
+}) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <body className="bg-bg-primary text-text-primary">
+        <ThemeProvider>
+          <ThemeContextProvider>
+            {children}
+          </ThemeContextProvider>
+        </ThemeProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js Pages Router
+
+```tsx
+// pages/_app.tsx
+import { ThemeProvider, ThemeContextProvider } from '@tydavidson/design-system';
+import '@tydavidson/design-system/themes/theme.css';
+
+function MyApp({ Component, pageProps }) {
+  return (
+    <ThemeProvider>
+      <ThemeContextProvider>
+        <Component {...pageProps} />
+      </ThemeContextProvider>
+    </ThemeProvider>
+  );
+}
+
+export default MyApp;
+```
+
+### Create React App
+
+```tsx
+// src/App.tsx
+import { ThemeProvider, ThemeContextProvider } from '@tydavidson/design-system';
+import '@tydavidson/design-system/themes/theme.css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeContextProvider>
+        <div className="bg-bg-primary text-text-primary min-h-screen">
+          {/* Your app content */}
+        </div>
+      </ThemeContextProvider>
+    </ThemeProvider>
+  );
+}
+
+export default App;
+```
+
+### Tailwind Configuration
+
+Extend your Tailwind config to use theme variables:
+
+```js
+// tailwind.config.js
+module.exports = {
+  darkMode: ["class"],
+  content: [
+    "./src/**/*.{js,ts,jsx,tsx}",
+  ],
+  theme: {
+    extend: {
+      colors: {
+        // Background colors
+        bg: {
+          primary: 'var(--bg-primary)',
+          secondary: 'var(--bg-secondary)',
+          tertiary: 'var(--bg-tertiary)',
+          quaternary: 'var(--bg-quaternary)',
+          disabled: 'var(--bg-disabled)',
+          overlay: 'var(--bg-overlay)',
+          'brand-primary': 'var(--bg-brand-primary)',
+          'error-primary': 'var(--bg-error-primary)',
+          'warning-primary': 'var(--bg-warning-primary)',
+          'success-primary': 'var(--bg-success-primary)',
+        },
+        // Text colors
+        text: {
+          primary: 'var(--text-primary)',
+          secondary: 'var(--text-secondary)',
+          tertiary: 'var(--text-tertiary)',
+          disabled: 'var(--text-disabled)',
+          'brand-primary': 'var(--text-brand-primary)',
+          'error-primary': 'var(--text-error-primary)',
+          'warning-primary': 'var(--text-warning-primary)',
+          'success-primary': 'var(--text-success-primary)',
+        },
+        // Border colors
+        border: {
+          primary: 'var(--border-primary)',
+          secondary: 'var(--border-secondary)',
+          tertiary: 'var(--border-tertiary)',
+          disabled: 'var(--border-disabled)',
+          brand: 'var(--border-brand)',
+          error: 'var(--border-error)',
+          warning: 'var(--border-warning)',
+          success: 'var(--border-success)',
+        }
+      }
+    }
+  },
+  plugins: [],
+}
+```
+
+## Troubleshooting
+
+### Hydration Mismatch
+
+**Problem**: Server-side rendering doesn't match client-side rendering.
+
+**Solutions**:
+1. Add `suppressHydrationWarning` to the HTML element
+2. Check `isClient` before rendering theme-dependent content
+3. Use the `useTheme` hook properly
+
+```tsx
+function ThemeDependentComponent() {
+  const { isClient, isDark } = useTheme();
+  
+  // Don't render until client-side
+  if (!isClient) return null;
+  
+  return (
+    <div className={isDark ? 'dark-styles' : 'light-styles'}>
+      Theme-dependent content
+    </div>
+  );
+}
+```
+
+### Theme Not Switching
+
+**Problem**: Theme toggle doesn't change the appearance.
+
+**Solutions**:
+1. Verify theme CSS is imported
+2. Check theme providers are wrapping your app
+3. Ensure `next-themes` is properly configured
+4. Confirm Tailwind config includes theme variables
+
+```tsx
+// Debug theme state
+function ThemeDebugger() {
+  const { theme, setTheme, resolvedTheme, isDark, isClient } = useTheme();
+  
+  return (
+    <div className="p-4 bg-bg-secondary border border-border-primary rounded">
+      <h3 className="text-text-primary font-semibold mb-2">Theme Debug</h3>
+      <div className="text-sm text-text-secondary space-y-1">
+        <p>Client: {isClient ? 'Yes' : 'No'}</p>
+        <p>Theme: {theme}</p>
+        <p>Resolved: {resolvedTheme}</p>
+        <p>Is Dark: {isDark ? 'Yes' : 'No'}</p>
+      </div>
+    </div>
+  );
+}
+```
+
+### Styling Issues
+
+**Problem**: Theme styles aren't applying correctly.
+
+**Solutions**:
+1. Verify CSS variables are imported
+2. Check Tailwind configuration includes theme colors
+3. Ensure correct class names are used
+4. Confirm theme providers are in correct order
+
+```css
+/* Test CSS variables are working */
+.theme-test {
+  background-color: var(--bg-primary);
+  color: var(--text-primary);
+  border: 1px solid var(--border-primary);
+}
+```
+
+### Performance Optimization
+
+**Best Practices**:
+1. Use CSS variables for dynamic theming
+2. Avoid inline styles for theme-dependent styles
+3. Use Tailwind classes when possible
+4. Minimize theme-dependent JavaScript
+
+```tsx
+// Good: Use CSS variables and Tailwind
+<div className="bg-bg-primary text-text-primary border border-border-primary">
+  Content
+</div>
+
+// Avoid: Inline styles for theme
+<div style={{ 
+  backgroundColor: isDark ? '#000' : '#fff',
+  color: isDark ? '#fff' : '#000'
+}}>
+  Content
+</div>
+```
+
+## Examples
+
+### Complete App Example
+
+```tsx
+import { ThemeProvider, ThemeContextProvider, ThemeToggle } from '@tydavidson/design-system';
+import '@tydavidson/design-system/themes/theme.css';
+
+function App() {
+  return (
+    <ThemeProvider>
+      <ThemeContextProvider>
+        <div className="min-h-screen bg-bg-primary text-text-primary">
+          <Header />
+          <Main />
+          <Footer />
+        </div>
+      </ThemeContextProvider>
+    </ThemeProvider>
+  );
+}
+
+function Header() {
+  return (
+    <header className="bg-bg-secondary border-b border-border-primary p-4">
+      <div className="max-w-6xl mx-auto flex items-center justify-between">
+        <h1 className="text-xl font-bold text-text-primary">My App</h1>
+        <ThemeToggle variant="icon" size="md" />
+      </div>
+    </header>
+  );
+}
+
+function Main() {
+  return (
+    <main className="max-w-6xl mx-auto p-6">
+      <div className="grid gap-6">
+        <section className="bg-bg-secondary border border-border-primary rounded-lg p-6">
+          <h2 className="text-lg font-semibold text-text-primary mb-4">Welcome</h2>
+          <p className="text-text-secondary">
+            This app uses the Float Design System theme system.
+          </p>
+        </section>
+        
+        <section className="grid grid-cols-1 md:grid-cols-3 gap-4">
+          <div className="bg-bg-success-primary text-text-success-primary border border-border-success rounded-lg p-4">
+            Success Card
+          </div>
+          <div className="bg-bg-error-primary text-text-error-primary border border-border-error rounded-lg p-4">
+            Error Card
+          </div>
+          <div className="bg-bg-warning-primary text-text-warning-primary border border-border-warning rounded-lg p-4">
+            Warning Card
+          </div>
+        </section>
+      </div>
+    </main>
+  );
+}
+
+function Footer() {
+  return (
+    <footer className="bg-bg-secondary border-t border-border-primary p-4 mt-auto">
+      <div className="max-w-6xl mx-auto text-center text-text-secondary">
+        © 2024 My App. Built with Float Design System.
+      </div>
+    </footer>
+  );
+}
+```
+
+This comprehensive guide should help you implement and use the Float Design System theme system effectively in your projects!