@machinemetrics/mm-react-components 0.2.0 → 0.2.3-1

package/dist/docs/TAILWIND_SETUP.md

@@ -0,0 +1,339 @@
+# Tailwind CSS Setup for MM React Components
+
+This guide shows how to configure Tailwind CSS in your consuming application to get the same styling as the component preview interface.
+
+## Quick Setup
+
+### 1. Install Dependencies
+
+```bash
+npm install @machinemetrics/mm-react-components tailwindcss postcss autoprefixer
+```
+
+### 2. Copy Tailwind Configuration
+
+Copy the `tailwind.config.export.js` file to your project and rename it to `tailwind.config.js`:
+
+```bash
+cp node_modules/@machinemetrics/mm-react-components/tailwind.config.export.js tailwind.config.js
+```
+
+### 3. Import Theme CSS
+
+**Option A: Complete All-in-One (Recommended)**
+
+```css
+/* Import everything in one go - includes Tailwind reset, base theme, and Carbide theme */
+@import '@machinemetrics/mm-react-components/themes/complete';
+```
+
+**Option B: Manual Setup**
+
+```css
+/* Import base theme */
+@import '@machinemetrics/mm-react-components/themes/base';
+
+/* Import Carbide theme (optional) */
+@import '@machinemetrics/mm-react-components/themes/carbide';
+```
+
+### 4. Configure PostCSS
+
+Create or update your `postcss.config.js`:
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+## Complete Setup Example
+
+### package.json
+
+```json
+{
+  "dependencies": {
+    "@machinemetrics/mm-react-components": "^0.2.1",
+    "tailwindcss": "^3.4.17",
+    "postcss": "^8.4.35",
+    "autoprefixer": "^10.4.17"
+  }
+}
+```
+
+### tailwind.config.js
+
+```javascript
+/** @type {import('tailwindcss').Config} */
+export default {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@machinemetrics/mm-react-components/dist/**/*.{js,ts,jsx,tsx}',
+  ],
+  theme: {
+    extend: {
+      colors: {
+        background: 'var(--background)',
+        foreground: 'var(--foreground)',
+        card: 'var(--card)',
+        'card-foreground': 'var(--card-foreground)',
+        popover: 'var(--popover)',
+        'popover-foreground': 'var(--popover-foreground)',
+        primary: 'var(--primary)',
+        'primary-foreground': 'var(--primary-foreground)',
+        secondary: 'var(--secondary)',
+        'secondary-foreground': 'var(--secondary-foreground)',
+        muted: 'var(--muted)',
+        'muted-foreground': 'var(--muted-foreground)',
+        accent: 'var(--accent)',
+        'accent-foreground': 'var(--accent-foreground)',
+        destructive: 'var(--destructive)',
+        'destructive-foreground': 'var(--destructive-foreground)',
+        border: 'var(--border)',
+        input: 'var(--input)',
+        'bg-input': 'var(--bg-input)',
+        'border-input': 'var(--border-input)',
+        ring: 'var(--ring)',
+        // Chart colors for data visualization
+        'chart-1': 'var(--chart-1)',
+        'chart-2': 'var(--chart-2)',
+        'chart-3': 'var(--chart-3)',
+        'chart-4': 'var(--chart-4)',
+        'chart-5': 'var(--chart-5)',
+        // Sidebar colors
+        sidebar: 'var(--sidebar)',
+        'sidebar-foreground': 'var(--sidebar-foreground)',
+        'sidebar-primary': 'var(--sidebar-primary)',
+        'sidebar-primary-foreground': 'var(--sidebar-primary-foreground)',
+        'sidebar-accent': 'var(--sidebar-accent)',
+        'sidebar-accent-foreground': 'var(--sidebar-accent-foreground)',
+        'sidebar-border': 'var(--sidebar-border)',
+        'sidebar-ring': 'var(--sidebar-ring)',
+      },
+      borderRadius: {
+        sm: 'var(--radius-sm)',
+        md: 'var(--radius-md)',
+        lg: 'var(--radius-lg)',
+        xl: 'var(--radius-xl)',
+      },
+      fontFamily: {
+        sans: [
+          'Noto Sans',
+          'Inter',
+          'ui-sans-serif',
+          'system-ui',
+          '-apple-system',
+          'BlinkMacSystemFont',
+          'Segoe UI',
+          'Roboto',
+          'Helvetica Neue',
+          'Arial',
+          'sans-serif',
+          'Apple Color Emoji',
+          'Segoe UI Emoji',
+          'Segoe UI Symbol',
+          'Noto Color Emoji',
+        ],
+        mono: [
+          'Inconsolata',
+          'ui-monospace',
+          'SFMono-Regular',
+          'Menlo',
+          'Monaco',
+          'Consolas',
+          'Liberation Mono',
+          'Courier New',
+          'monospace',
+        ],
+      },
+      fontWeight: {
+        normal: '400',
+        medium: '500',
+        semibold: '600',
+        bold: 'var(--font-weight-bold)',
+      },
+      spacing: {
+        sidebar: '16rem', // 256px for sidebar width
+      },
+      animation: {
+        'fade-in': 'fadeIn 0.2s ease-in-out',
+        'slide-in': 'slideIn 0.3s ease-out',
+      },
+      keyframes: {
+        fadeIn: {
+          '0%': { opacity: '0' },
+          '100%': { opacity: '1' },
+        },
+        slideIn: {
+          '0%': { transform: 'translateX(-10px)', opacity: '0' },
+          '100%': { transform: 'translateX(0)', opacity: '1' },
+        },
+      },
+    },
+  },
+  plugins: [
+    function ({ addUtilities, theme }) {
+      const newUtilities = {
+        '.preview-sidebar': {
+          width: '16rem',
+          minHeight: '100vh',
+          backgroundColor: 'var(--muted)',
+          borderRight: '1px solid var(--border)',
+          padding: '1rem',
+        },
+        '.preview-main': {
+          flex: '1',
+          minWidth: '0',
+          padding: '2rem',
+        },
+        '.preview-card': {
+          backgroundColor: 'var(--card)',
+          border: '1px solid var(--border)',
+          borderRadius: 'var(--radius-lg)',
+          padding: '1.5rem',
+        },
+        '.preview-nav-item': {
+          width: '100%',
+          textAlign: 'left',
+          padding: '0.75rem',
+          borderRadius: '0.375rem',
+          fontSize: '0.875rem',
+          fontWeight: '500',
+          transition: 'colors 0.2s ease-in-out',
+          '&:hover': {
+            backgroundColor: 'var(--muted)',
+            color: 'var(--foreground)',
+          },
+          '&.active': {
+            backgroundColor: 'var(--primary)',
+            color: 'var(--primary-foreground)',
+          },
+        },
+      };
+      addUtilities(newUtilities);
+    },
+  ],
+};
+```
+
+### src/index.css
+
+```css
+@import '@machinemetrics/mm-react-components/themes/base';
+@import '@machinemetrics/mm-react-components/themes/carbide';
+@import 'tailwindcss';
+```
+
+### postcss.config.js
+
+```javascript
+export default {
+  plugins: {
+    tailwindcss: {},
+    autoprefixer: {},
+  },
+};
+```
+
+## Component Preview Interface
+
+To recreate the component preview interface from the library, use these utility classes:
+
+```tsx
+// Main layout container
+<div className="min-h-screen bg-background flex">
+  {/* Left Navigation Sidebar */}
+  <div className="preview-sidebar">
+    <h1 className="text-xl font-bold text-foreground mb-6">MM Components</h1>
+
+    {/* Theme Toggles */}
+    <div className="mb-6 space-y-3">
+      {/* Add your theme toggle components here */}
+    </div>
+
+    {/* Component Navigation */}
+    <nav className="space-y-2">
+      <button className="preview-nav-item active">Button</button>
+      <button className="preview-nav-item">Input</button>
+      {/* Add more component navigation items */}
+    </nav>
+  </div>
+
+  {/* Main Preview Pane */}
+  <div className="preview-main">
+    <div>
+      <div className="mb-6">
+        <h2 className="text-2xl font-semibold text-foreground capitalize">
+          Component Name
+        </h2>
+        <p className="text-muted-foreground mt-1">
+          Preview and test the component
+        </p>
+      </div>
+      <div className="preview-card">{/* Your component preview content */}</div>
+    </div>
+  </div>
+</div>
+```
+
+## Theme Customization
+
+### Using Base Theme Only
+
+```css
+@import '@machinemetrics/mm-react-components/themes/base';
+```
+
+### Using Carbide Theme
+
+```css
+@import '@machinemetrics/mm-react-components/themes/base';
+@import '@machinemetrics/mm-react-components/themes/carbide';
+```
+
+### Custom Theme Overrides
+
+You can override theme variables in your CSS:
+
+```css
+:root {
+  --primary: #your-custom-color;
+  --background: #your-custom-background;
+  /* Override other variables as needed */
+}
+```
+
+## Available Utility Classes
+
+The exported configuration includes these custom utility classes:
+
+- `.preview-sidebar` - Sidebar styling
+- `.preview-main` - Main content area styling
+- `.preview-card` - Component preview card styling
+- `.preview-nav-item` - Navigation item styling
+
+## Color System
+
+The configuration includes a comprehensive color system:
+
+- **Semantic Colors**: `background`, `foreground`, `primary`, `secondary`, etc.
+- **Chart Colors**: `chart-1` through `chart-5` for data visualization
+- **Sidebar Colors**: Complete sidebar color system
+- **Input Colors**: Specialized input styling colors
+
+## Typography
+
+- **Sans Font**: Noto Sans (primary), Inter, system fonts
+- **Mono Font**: Inconsolata (primary), system monospace fonts
+- **Font Weights**: Normal (400), Medium (500), Semibold (600), Bold (700)
+
+## Animation
+
+- **Fade In**: `animate-fade-in`
+- **Slide In**: `animate-slide-in`
+
+This configuration ensures your consuming application will have the same professional styling as the component preview interface.