@machinemetrics/mm-react-components 1.2.1 → 1.2.3

package/README.md

@@ -1,6 +1,6 @@
 # @machinemetrics/mm-react-components
 
-> **🤖 FOR AI AGENTS:** This library has [extensive AI agent documentation](./agent-docs/agent-documentation-reference.md) for setup and Chakra UI migration. See the [`agent-docs/`](./agent-docs/) folder for comprehensive guides.
+> **🤖 FOR AI AGENTS:** This library has [extensive AI agent documentation](./agent-docs/agent-documentation-reference.md) for setup and Chakra UI migration. For **Carbide theme colors and CSS variables**, read the shipped **`themes/carbide`** CSS first; [agent-docs/style-color-reference.md](./agent-docs/style-color-reference.md) is a short overview. See the [`agent-docs/`](./agent-docs/) folder for comprehensive guides.
 
 A comprehensive React component library designed specifically for MachineMetrics industrial and manufacturing applications.
 
@@ -42,6 +42,7 @@ npm install @machinemetrics/mm-react-components
 - **Chakra UI Migration:** [`agent-docs/ai-agent-guide.md`](./agent-docs/ai-agent-guide.md)
 - **Component Mappings (83 components):** [`agent-docs/component-mapping-summary.md`](./agent-docs/component-mapping-summary.md)
 - **Full Documentation Index:** [`agent-docs/agent-documentation-reference.md`](./agent-docs/agent-documentation-reference.md)
+- **Carbide color & CSS variable overview:** [`agent-docs/style-color-reference.md`](./agent-docs/style-color-reference.md) (full detail in shipped `themes/carbide`)
 
 **Automated Tools:**
 

package/agent-docs/agent-documentation-reference.md

@@ -8,6 +8,8 @@
 >
 > **For Lovable:** Lovable cannot use installable skills. Add [lovable.md](./lovable.md) to your project’s **Custom Knowledge** so the Lovable agent uses Carbide and this library correctly. The package also exports it as `@machinemetrics/mm-react-components/agent-docs/lovable`.
 
+**Carbide colors and CSS variables:** Prefer **`@machinemetrics/mm-react-components/themes/carbide`** (`carbide.css`) as the source of truth. [style-color-reference.md](./style-color-reference.md) is a short overview; the precompiled **`/styles`** export contains only what this library’s build emits—verify class names in that CSS or use **`var(--token)`** from the theme file.
+
 ## Library Foundation
 
 **@machinemetrics/mm-react-components** is a **traditional npm package** built on **[shadcn/ui](https://ui.shadcn.com/)** components (Radix UI + Tailwind CSS) with the Carbide industrial theme.

package/agent-docs/cursor-skill-mm-carbide.md

@@ -65,6 +65,7 @@ The skill triggers when the user asks to create or generate a UI, widget, screen
 
 - **SKILL.md** — Main instructions: components (only library exports, compound components, `cn()`, `data-slot`); **theme and styling** (CSS variables only, variants, layout, `.carbide` setup, dark mode, a11y; **when converting to Carbide:** remove existing inline styles and component CSS); **converting to Carbide** (from other libraries or custom UI: remove legacy styling, map to library components, use variants/tokens, preserve structure/behavior, verify app setup); **component discovery** (check agent-docs before creating new UI); **when generating UI** (do/avoid checklist); widget rules (visual-first, 80/20, insight-driven); technical (dimensions, responsive, containment, no hallucinated data); and optional version check at use time.
 - **reference.md** — **Styling and conventions** (tokens, variants, layout, setup); **component discovery** (agent-docs index); key exports and patterns (PageHeader, DataTable, Form, ChartContainer, etc.); short widget rules summary (when to use charts vs metrics, accessibility).
+- **Package agent-docs:** **`style-color-reference.md`** — short overview; **authoritative** token names/values are in **`themes/carbide`** (`carbide.css`). Precompiled `/styles` is library-scoped CSS, not a full generic utility set.
 
 Full widget and visualization rules are in the skill as **widget-rules.md** (installed with the skill). In this repo, see [cursor-skill/mm-carbide/widget-rules.md](../cursor-skill/mm-carbide/widget-rules.md).
 

package/agent-docs/lovable.md

@@ -24,6 +24,7 @@ Use this document when building UIs with **Lovable** or any tool that uses Custo
 
 ## Theme and styling
 
+- **Authoritative tokens:** Search **`@machinemetrics/mm-react-components/themes/carbide`** (`carbide.css`) for `--` variable names and values. [style-color-reference.md](./style-color-reference.md) is a short overview. Precompiled `/styles` only includes rules from this library’s build—use **`var(--token)`** from the theme CSS when unsure.
 - **CSS variables only.** Never hardcode colors, spacing, radii, or shadows. Use semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--ring`, etc.
 - **When converting a component to Carbide:** Remove existing inline styles (`style={{ ... }}`) and component-level CSS (e.g. `.module.css`, `<style>`, or component-scoped styles). Carbide supplies appearance via theme tokens and component variants; legacy styles conflict with the theme and break consistency.
 - **Variants over one-off styles.** Use component variants and sizes (e.g. Button: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"`). Do not apply brand colors or one-off Tailwind color classes to components.

package/agent-docs/style-color-reference.md

@@ -0,0 +1,85 @@
+# Carbide theme: colors and CSS variables (`@machinemetrics/mm-react-components`)
+
+**Purpose:** Short **overview** for AI agents and developers using **Carbide** with **MachineMetrics React Components**. For **names, values, and where tokens apply**, use the **shipped theme CSS**—this file does not duplicate the full token list.
+
+**Related:** [agent-documentation-reference.md](./agent-documentation-reference.md) (component index), [lovable.md](./lovable.md) (Lovable Custom Knowledge).
+
+---
+
+## Source of truth: `themes/carbide`
+
+**Always start here** for a specific color or variable:
+
+| Resource | Import / path |
+| -------- | ---------------- |
+| **Carbide theme (all `--*` variables, `.carbide` rules, `@theme`)** | `@machinemetrics/mm-react-components/themes/carbide` → `dist/themes/carbide.css` in the package |
+| **This overview** | `@machinemetrics/mm-react-components/agent-docs/style-color-reference` |
+
+Search the **`carbide.css`** file for `--` (e.g. `--indigo-600`, `--tablist-bg`, `--button-secondary-bg`). That file defines:
+
+- **Palette** scales (`--grey-*`, `--red-*`, …) under `.carbide`
+- **Semantic** tokens (`--background`, `--primary`, …) and **component-oriented** tokens (`--tablist-*`, `--code-*`, …)
+- **`@theme inline`** mappings used when the library build emits semantic **utility class names** (see below)
+
+You do **not** need large TypeScript reference modules to look up a single token.
+
+---
+
+## Dev preview data (optional)
+
+For the **dev app Colors preview** only, token groupings, manual semantic rows, and **Style reference** class probes live in **`src/preview/colors-preview-data.ts`**. They are **maintained by hand** alongside `src/themes/carbide.css`—there is no codegen step.
+
+Consumers and agents doing real work should still rely on **`carbide.css`**, not the preview file.
+
+---
+
+## Precompiled `/styles` export
+
+The package exports **`@machinemetrics/mm-react-components/styles`**: **precompiled CSS** from this library’s build. It contains **only** the rules that the library’s sources require—not every possible atomic class name a generic CSS framework might define elsewhere.
+
+**Implications:**
+
+- Do **not** assume a class name exists in that bundle unless it appears in the shipped CSS or your **own** app’s stylesheet.
+- **Prefer** **`var(--token-name)`** from **`themes/carbide`** for one-offs and custom surfaces (see below).
+- Layout and spacing: follow **component examples** and patterns in agent-docs; your app may supply additional CSS as needed.
+
+---
+
+## Semantic colors (`@theme` in `carbide.css`)
+
+The theme file registers semantic colors under `@theme inline` (e.g. `--color-background`, `--color-primary`, …). The library’s components and examples often use **short class names** that resolve through that theme (e.g. surface vs text roles). **Exact** class names available in **your** bundle depend on the **precompiled `/styles`** output—verify in the built CSS or use **`var(--…)`** from `carbide.css` when in doubt.
+
+**Practical rule:** Map **foreground** roles to text-related usage and **surface** roles to backgrounds, using token names from **`carbide.css`** (`--foreground`, `--card`, `--muted-foreground`, …).
+
+---
+
+## Palette as CSS variables
+
+Grey / red / green / indigo / … scales live as **custom properties** in **`themes/carbide`** (e.g. `--grey-500`, `--indigo-600`). **Exact step names** are only guaranteed in that file—search it.
+
+**Typical pattern** in JSX when you need a literal palette step:
+
+```tsx
+<div className="bg-[var(--grey-500)]" />
+<span className="text-[var(--indigo-600)]" />
+```
+
+**Additional semantic variables** (tabs, buttons, code, overlay, …) appear under **`.carbide`** in the same file—e.g. `--tablist-bg`, `--code-fg`. Use **`var(--token-name)`** in `className` arbitrary values or **`style`** when appropriate.
+
+### Card: custom background (light and dark)
+
+The **Card** component usually uses the semantic **card** token. To tint with the **palette**, pass **`className`** with `var(--…)` as in the examples above. For **dark mode**, pair **lighter** palette steps in light contexts with **deeper** steps when the root is dark so text and borders stay readable (see **`carbide.css`** and the dev **Card** preview “Custom background” example).
+
+---
+
+## Carbide-scoped rules (non–`data-slot`)
+
+Some behaviors are implemented as **scoped CSS** under **`.carbide`** in `carbide.css` (e.g. utility overrides). Prefer semantic tokens from the theme file; see comments and selectors in **`carbide.css`**.
+
+---
+
+## Verification and maintenance
+
+**Consumers:** Validate variable names against **`@machinemetrics/mm-react-components/themes/carbide`**. Optional Playwright tests in this repo hit the dev **Colors → Style reference** tab.
+
+**Maintainers:** When **`src/themes/carbide.css`** changes, update **`src/preview/colors-preview-data.ts`** so the Colors preview and Playwright probes stay aligned (sections, token lists, manual semantic rows, and fixed class probes). Update **this overview** when consumer-facing guidance changes.

package/dist/App.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../src/App.tsx"],"names":[],"mappings":"AAqEA,iBAAS,GAAG,4CAgRX;AAED,eAAe,GAAG,CAAC"}
+{"version":3,"file":"App.d.ts","sourceRoot":"","sources":["../src/App.tsx"],"names":[],"mappings":"AAyEA,iBAAS,GAAG,4CAmQX;AAED,eAAe,GAAG,CAAC"}

package/dist/README.md

@@ -1,6 +1,6 @@
 # @machinemetrics/mm-react-components
 
-> **🤖 FOR AI AGENTS:** This library has [extensive AI agent documentation](./agent-docs/agent-documentation-reference.md) for setup and Chakra UI migration. See the [`agent-docs/`](./agent-docs/) folder for comprehensive guides.
+> **🤖 FOR AI AGENTS:** This library has [extensive AI agent documentation](./agent-docs/agent-documentation-reference.md) for setup and Chakra UI migration. For **Carbide theme colors and CSS variables**, read the shipped **`themes/carbide`** CSS first; [agent-docs/style-color-reference.md](./agent-docs/style-color-reference.md) is a short overview. See the [`agent-docs/`](./agent-docs/) folder for comprehensive guides.
 
 A comprehensive React component library designed specifically for MachineMetrics industrial and manufacturing applications.
 
@@ -42,6 +42,7 @@ npm install @machinemetrics/mm-react-components
 - **Chakra UI Migration:** [`agent-docs/ai-agent-guide.md`](./agent-docs/ai-agent-guide.md)
 - **Component Mappings (83 components):** [`agent-docs/component-mapping-summary.md`](./agent-docs/component-mapping-summary.md)
 - **Full Documentation Index:** [`agent-docs/agent-documentation-reference.md`](./agent-docs/agent-documentation-reference.md)
+- **Carbide color & CSS variable overview:** [`agent-docs/style-color-reference.md`](./agent-docs/style-color-reference.md) (full detail in shipped `themes/carbide`)
 
 **Automated Tools:**
 

package/dist/cursor-skill/mm-carbide/SKILL.md

@@ -14,6 +14,7 @@ description: Generate UIs and widgets with Carbide and MachineMetrics React Comp
 
 ## Theme and styling
 
+- **Color/CSS reference:** Search **`themes/carbide`** (`carbide.css`) for `--` tokens. **`agent-docs/style-color-reference.md`** is a short overview only. Precompiled `/styles` contains only rules from this library’s build.
 - **CSS variables only.** Never hardcode colors, spacing, radii, or shadows. Use semantic tokens: `--background`, `--foreground`, `--primary`, `--muted`, `--muted-foreground`, `--destructive`, `--border`, `--ring`, etc.
 - **When converting a component to Carbide:** Remove existing inline styles (`style={{ ... }}`) and component-level CSS (e.g. `.module.css`, `<style>`, or component-scoped styles). Carbide supplies appearance via theme tokens and component variants; legacy styles conflict with the theme and break consistency.
 - **Variants over one-off styles.** Use component variants and sizes (e.g. Button: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"`). Do not apply brand colors or one-off Tailwind color classes to components.

package/dist/cursor-skill/mm-carbide/reference.md

@@ -2,7 +2,8 @@
 
 ## Styling and conventions
 
-- **Colors and tokens:** Use only CSS variables / semantic tokens (e.g. `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`, `text-destructive`). Never use raw Tailwind color classes like `bg-blue-600` or `text-gray-500`.
+- **Authoritative tokens:** **`@machinemetrics/mm-react-components/themes/carbide`** (`carbide.css`) — search for `--` variables and `.carbide` rules. **`agent-docs/style-color-reference.md`** is an overview only. Precompiled `/styles` is scoped to this library’s build; use **`var(--token)`** from `carbide.css` when needed.
+- **Colors and tokens:** Use only CSS variables / semantic tokens (e.g. `bg-background`, `text-foreground`, `text-muted-foreground`, `border-border`, `bg-primary`, `text-destructive`). Never use raw Tailwind color classes like `bg-blue-600` or `text-gray-500`. For palette stops, use arbitrary values: `bg-[var(--grey-500)]`, etc.
 - **Variants and sizes:** Use component props: `variant="default"|"destructive"|"outline"|"secondary"|"ghost"|"link"`, `size="sm"|"md"|"lg"|"icon"` where supported. Same variant names apply across Button, Badge, and other components.
 - **Layout:** Use `flex`, `grid`, and `gap-*` for spacing; avoid ad-hoc margins between siblings.
 - **Converting to Carbide:** Remove existing inline styles and component CSS; map to library components and use variants/tokens. See SKILL.md section “Converting to Carbide.”