@machinemetrics/mm-react-components

🤖 FOR AI AGENTS: This library has extensive AI agent documentation for setup. For Carbide theme colors and CSS variables, read the shipped themes/carbide CSS first; agent-docs/style-color-reference.md is a short overview. 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: built on Radix primitives with keyboard and screen-reader support
• 🚀 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!

• Lovable (Custom Knowledge): Add agent-docs/lovable.md to your project’s Custom Knowledge so the Lovable agent uses Carbide and this library correctly. (Lovable cannot use skills; this doc is the equivalent.)
• New Project Setup: agent-docs/ai-agent-init-guide.md
• Full Documentation Index: agent-docs/agent-documentation-reference.md
• Carbide color & CSS variable overview: agent-docs/style-color-reference.md (full detail in shipped themes/carbide)

Automated Tools:

• ✅ Init script: npx -p @machinemetrics/mm-react-components mm-init
• ✅ Class checker (1.6.4+): ./node_modules/.bin/mm-carbide-check-classes verifies your Tailwind classes against the shipped stylesheet (run from your project root; the bin name is not a registry package, so don't invoke it via bare npx)
• ✅ Zero-config setup option (no build tools needed!)

Quick Start

🚀 Automated Setup (Recommended)

The fastest way to get started (from your React project root):

npx -p @machinemetrics/mm-react-components mm-init

This will automatically:

• ✅ Install the component library
• ✅ Add pre-compiled CSS import to your index.css
• ✅ Create example components
• ✅ Point you at the Carbide plugin for AI skills

📋 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. 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 (208 KB, 31 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

3. Use Components

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

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

📚 Documentation

For AI Agents:

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

For Developers:

• Getting Started Guide - Complete setup guide

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 — 31 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 (advanced — read the caveat)

Import just the Carbide theme variables and component overrides:

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

⚠️ The theme export does not carry the utility CSS our components need. Since 1.6.3 the shipped stylesheet contains exactly the utilities the library's own components use, and your own Tailwind build only scans your sources — it will not emit utilities for classnames inside this package's components, which then render unstyled. Unless you configure Tailwind to scan this package (or know you don't render affected components), import /styles. It is safe alongside an app's own Tailwind build.

Embedded apps: ThemeRoot and useHostTheme

For apps hosted inside the MachineMetrics shell (or any host that passes a light/dark value), wrap the tree once and sync the host value—no next-themes setup boilerplate.

ThemeRoot wraps your React tree (e.g. inside #root). It does not replace <html> in index.html; it still toggles light / dark on document.documentElement. Keep class="carbide" on <html> and import Carbide CSS as usual.

// index.tsx
import { ThemeRoot } from '@machinemetrics/mm-react-components';

<ThemeRoot>
  <App />
</ThemeRoot>

// App.tsx — pass the host color mode (example: mm-react-tools)
import { useHostTheme } from '@machinemetrics/mm-react-components';
import { useMMAppParams } from '@machinemetrics/mm-react-tools';

useHostTheme(useMMAppParams().colorMode);

If you need useTheme() elsewhere (e.g. markdown styling), import it from @machinemetrics/mm-react-components so it uses the same context as ThemeRoot—not from the next-themes package directly.

Optional: pass any ThemeProvider prop to ThemeRoot to override defaults (e.g. storageKey for standalone persistence).

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

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

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: default, secondary, outline, ghost, link, destructive
<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

Components style themselves from the shipped, precompiled stylesheet — consumers need no Tailwind build. One import gets everything (reset, OKLCH color system, Carbide theme, component styles, dark mode, animations):

/* In CSS */
@import '@machinemetrics/mm-react-components/styles';

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

When writing your own Tailwind-style classes against the shipped stylesheet, verify them with ./node_modules/.bin/mm-carbide-check-classes — the stylesheet carries exactly what the library's components use, so a utility you invent may not exist in it.

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.2+ or 19
• Node.js 20.6 or higher

Browser Support

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

Contributing

See AGENTS.md for the working conventions this repo enforces.

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.