@machinemetrics/mm-react-components

🤖 FOR AI AGENTS: This library has extensive AI agent documentation for setup and Chakra UI migration. See the agent-docs/ folder for comprehensive guides.

A comprehensive React component library designed specifically for MachineMetrics industrial and manufacturing applications.

Features

• 🏭 Industrial-Focused: Components designed for manufacturing and industrial environments
• 🎨 Modern Design: Built on shadcn/ui with Tailwind CSS for consistent, accessible UI
• 📦 Tree-Shakable: ES modules with full tree-shaking support
• 🔧 TypeScript: Full TypeScript support with comprehensive type definitions
• ♿ Accessible: WCAG 2.1 AA compliant components
• 🚀 Performance: Optimized for real-time data display and monitoring
• 🤖 AI-Agent Ready: Comprehensive AI agent documentation with automated setup and migration tools

Installation

npm install @machinemetrics/mm-react-components

Required Dependencies:

• React 18.2+ or React 19+
• React DOM 18.2+ or React DOM 19+

Optional Dependencies (only if using /themes/carbide):

• Tailwind CSS 4.0+
• PostCSS 8.5+
• Autoprefixer 10+

💡 Note: When using /styles (recommended), no build tools are required! The CSS is fully compiled.

🤖 For AI Agents

This library has comprehensive documentation for AI-assisted development!

• New Project Setup: agent-docs/ai-agent-init-guide.md
• Chakra UI Migration: agent-docs/ai-agent-guide.md
• Component Mappings (83 components): agent-docs/component-mapping-summary.md
• Full Documentation Index: agent-docs/agent-documentation-reference.md

Automated Tools:

• ✅ Init script: npx @machinemetrics/mm-react-components init
• ✅ Migration script: npx @machinemetrics/mm-react-components chakra-to-shadcn
• ✅ 98% automation rate for Chakra UI conversion
• ✅ Zero-config setup option (no build tools needed!)

Quick Start

🚀 Automated Setup (Recommended)

The fastest way to get started:

# Install the package
npm install @machinemetrics/mm-react-components

# Run the automated setup
npx @machinemetrics/mm-react-components/setup

This will automatically:

• ✅ Copy Tailwind configuration
• ✅ Create PostCSS configuration
• ✅ Set up the complete theme
• ✅ Create an example component
• ✅ Generate all necessary files

📋 Manual Setup

If you prefer manual setup:

1. Install the Library

npm install @machinemetrics/mm-react-components

Optional: Only install Tailwind if you want to use /themes/carbide instead of /styles:

npm install -D tailwindcss postcss autoprefixer

2. (Optional) Configure Tailwind CSS

💡 Skip this step if using /styles - Tailwind configuration is not needed!

Only if using /themes/carbide:

cp node_modules/@machinemetrics/mm-react-components/tailwind.config.export.js tailwind.config.js

Note: The exported config is the main config (no preview-only utilities). The preview app in this repo uses a separate tailwind.preview.config.js that imports the main config and adds preview utilities.

3. Import Styles

Import the complete styles including Tailwind CSS, base styles, and Carbide theme:

// In your main entry (e.g., src/main.tsx)
import '@machinemetrics/mm-react-components/styles';
document.documentElement.classList.add('carbide');

What's included in /styles (118 KB, 18 KB gzipped):

• ✅ Tailwind CSS reset and utilities (compiled)
• ✅ Base theme variables (OKLCH color system)
• ✅ Carbide industrial theme
• ✅ All component styles (focus states, rings, borders, etc.)
• ✅ Dark mode support
• ✅ Animations and utilities

4. Use Components

import { Button, Input } from '@machinemetrics/mm-react-components';

function App() {
  return (
    <div>
      <Button variant="primary">Start Monitoring</Button>
      <Input placeholder="Enter machine ID..." />
    </div>
  );
}

📚 Documentation

For AI Agents:

• AI Agent Documentation Hub - Start here!
• Setup Guide for AI Agents
• Chakra Migration for AI Agents

For Developers:

• Getting Started Guide - Complete setup guide
• Tailwind Setup Guide - Detailed configuration
• Chakra Migration Guide - Detailed migration reference
• Component Mapping Summary - All 83 component mappings

Theme System

The component library includes a comprehensive theme system with two main themes:

Base Theme (OKLCH)

• Modern OKLCH color space for better perceptual uniformity
• Professional typography with embedded Noto Sans and Inconsolata fonts (via @fontsource)
• Complete dark mode support
• Chart and sidebar color systems

Carbide Theme (Industrial)

• Manufacturing-appropriate color palette
• MachineMetrics brand colors (green, grey)
• Enhanced component styling for industrial applications
• Complete dark mode support

Import Options

Option 1: Complete Styles (Recommended - 118 KB gzipped)

Import everything including Tailwind utilities, theme, and animations:

import '@machinemetrics/mm-react-components/styles';
document.documentElement.classList.add('carbide');

Includes:

• ✅ All Tailwind utilities (compiled)
• ✅ Carbide theme variables
• ✅ Component styles with focus states
• ✅ Dark mode support
• ✅ Animations

Option 2: Theme Only (41 KB - if you already have Tailwind)

Import just the Carbide theme variables and component overrides:

import '@machinemetrics/mm-react-components/themes/carbide';
document.documentElement.classList.add('carbide');

Use this if:

• You already have Tailwind CSS in your project
• You want to minimize bundle size
• You're using our components with your own Tailwind config

Option 3: Use Theme Utilities

import {
  activateCarbideTheme,
  toggleDarkMode,
  isCarbideThemeActive,
} from '@machinemetrics/mm-react-components';

// Activate Carbide theme
activateCarbideTheme();

// Toggle dark mode
toggleDarkMode();

// Check theme status
const isCarbideActive = isCarbideThemeActive();

Theme Classes

The theme system uses CSS classes for activation:

• Base theme: Active by default
• Carbide theme: Add carbide class to <html> element
• Dark mode: Add dark class to <html> element

<!-- Base theme -->
<html>
  <!-- Carbide theme -->
  <html class="carbide">
    <!-- Carbide theme + dark mode -->
    <html class="carbide dark"></html>
  </html>
</html>

Available Theme Utilities

import {
  // Carbide theme utilities
  activateCarbideTheme,
  deactivateCarbideTheme,
  toggleCarbideTheme,
  isCarbideThemeActive,

  // Dark mode utilities
  activateDarkMode,
  deactivateDarkMode,
  toggleDarkMode,
  isDarkModeActive,
} from '@machinemetrics/mm-react-components';

Components

Button

A versatile button component with multiple variants for different use cases.

import { Button } from '@machinemetrics/mm-react-components';

// Basic usage
<Button>Default</Button>

// Variants
<Button variant="primary">Primary</Button>
<Button variant="secondary">Secondary</Button>
<Button variant="outline">Outline</Button>
<Button variant="destructive">Destructive</Button>

// Sizes
<Button size="sm">Small</Button>
<Button size="lg">Large</Button>

Input

Form input component with built-in validation states.

import { Input } from '@machinemetrics/mm-react-components';

<Input placeholder="Enter value..." />
<Input type="email" placeholder="Email address" />
<Input type="password" placeholder="Password" />

Styling

The component library uses Tailwind CSS with a complete theme system. The easiest way to get started is with the complete theme:

/* Recommended: One import gets everything */
@import '@machinemetrics/mm-react-components/themes/complete';

This includes:

• Tailwind CSS reset and base styles
• OKLCH color system with dark mode support
• Carbide industrial theme
• All component styles and animations

Alternative Import Methods

/* Import complete styles including Carbide theme */
@import '@machinemetrics/mm-react-components/styles';

// Import in JavaScript/TypeScript
import '@machinemetrics/mm-react-components/styles';

TypeScript Support

This library is built with TypeScript and provides full type definitions:

import { Button, type ButtonProps } from '@machinemetrics/mm-react-components';

const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

Requirements

• React 18.0.0 or higher
• Node.js 20.0.0 or higher

Browser Support

• Chrome (latest)
• Firefox (latest)
• Safari (latest)
• Edge (latest)

Contributing

We welcome contributions! Please see our Contributing Guide for details.

License

MIT License - see LICENSE file for details.

Support

For support and questions, please contact the MachineMetrics development team.

Built with ❤️ by the MachineMetrics team for industrial applications.