@machinemetrics/mm-react-components 1.4.2 → 1.5.0

package/dist/cursor-skill/components/component-structure.md

@@ -0,0 +1,33 @@
+# Frontend component structure (universal)
+
+Summary of base vs. customization layer and composition patterns. Adapt to your project (e.g. shadcn/ui, Radix, or an internal design system).
+
+## Rules
+
+| Layer | Rule |
+|-------|------|
+| **Base** (vendor / CLI-installed / design system) | Do not modify. Updated by CLI or upstream; customizations here are lost. |
+| **App / customization** (e.g. `ui/`, `components/app/`) | Customize here only. Re-export from base; override via composition. |
+
+## Composition
+
+Compose base components in the customization layer and preserve their documented public,
+theming, and accessibility contracts. Use the installed package's current guidance for
+implementation mechanics. Re-export unchanged behavior rather than forking it.
+
+## Theming
+
+- Use semantic CSS variables for colors and spacing; support light/dark via variables.
+- Add design-system attributes (e.g. `data-slot`, `data-variant`) when the theme stylesheet targets them.
+- Single compiled CSS entry for the library or app so consumers get one import.
+
+## Adding and updating
+
+- **New behavior:** Use Carbide components as the base when applicable. Compose or
+  customize, and add a primitive only after recording a legitimate gap.
+- **Update base:** Use the project's documented update workflow and verify customizations
+  against the installed public contract.
+- **Troubleshooting:** Check public exports and version-matched package docs before changing
+  a wrapper.
+
+When in doubt: customize in the app layer, not the base.

package/dist/cursor-skill/components/reference.md

@@ -0,0 +1,39 @@
+# Carbide component reference
+
+## Stable conventions
+
+- **Appearance:** Use semantic tokens and current component appearance props. Never copy
+  raw palette colors or assume variants are shared across components.
+- **Layout:** Use `flex` and `grid` for spacing; avoid ad-hoc margins between siblings. Tailwind
+  is an optional peer dependency: use its `gap-*` utilities only when Tailwind is installed in
+  the consuming app, otherwise use plain CSS `gap` on the flex/grid container.
+- **Setup:** Import library styles (e.g. `import '@machinemetrics/mm-react-components/styles'`) and wrap the app (or Carbide root) in `<div className="carbide">` so the theme and fonts apply. For dark mode, apply the compound class instead: `<div className="carbide dark">`.
+
+## Component discovery
+
+**When the package is installed in this project:** Check **agent-docs** at `node_modules/@machinemetrics/mm-react-components/agent-docs/`; use **agent-documentation-reference.md** as the index for existing components and patterns.
+
+**When the package is not installed in this workspace:** agent-docs is not present. Use this reference and [widget-rules.md](widget-rules.md); recommend installing the package in the project (`npx -p @machinemetrics/mm-react-components mm-init`) for the full doc set.
+
+## Select by behavior
+
+Inventory structure, navigation, forms, data display, feedback, and overlays. Search the
+current docs by the required behavior, verify the export, and preserve its documented
+compound children. Do not rely on a static export catalog in this fallback.
+
+## Layout decisions
+
+Distinguish structural layout, navigation, temporary overlays, discrete content, and
+bounded overflow. Search current docs for the primitive whose behavior matches the need.
+Do not assume a content container provides page structure or scrolling.
+
+## Widget rules summary
+
+- **When to use**: Charts/graphs for trends, comparisons, distributions (with insight annotations). Icons/indicators for status, categories, severity. Metrics/numbers for single KPIs with context (vs target, trend). Text only for labels, brief context, annotations.
+- **Insight-driven**: Add comparisons (vs average, vs goal), highlight what matters (color, sizing), show direction/trend (arrows, sparklines), explain significance.
+- **Avoid**: Text-only widgets, generic charts without context, equal visual weight for all data, missing comparison or context.
+- **Chart complexity**: Follow current guidance and reduce density when the insight becomes
+  difficult to read.
+- **Accessibility**: WCAG contrast (4.5:1 text, 3:1 graphics); never rely on color alone: use patterns, shapes, or labels; direct labels on data when possible.
+
+For full widget and visualization rules, see [widget-rules.md](widget-rules.md).

package/dist/cursor-skill/{mm-carbide → components}/widget-rules.md

@@ -1,44 +1,3 @@
-**Insight-Driven Visualizations (NOT generic data dumps)**:
-
-- **Add context**: Show comparisons, benchmarks, goals, or historical context
-- **Highlight what matters**: Use color, annotations, or visual emphasis to draw attention to key findings
-- **Show the "so what"**: Don't just display numbers - show WHY they matter (trends up/down, exceeding goals, anomalies)
-- **Tell a story**: The visualization should answer a question or reveal an insight, not just display data
-- **Actionable insights**: Help users understand what to do with the information
-
-**Examples of insight-driven approaches**:
-
-- ❌ BAD: Simple bar chart showing 5 categories and their values
-- ✅ GOOD: Bar chart with the #1 issue prominently highlighted, showing % vs. average, and including trend indicators or impact metrics
-- ❌ BAD: Line graph showing sales over time
-- ✅ GOOD: Line graph with annotations marking significant events, goal lines, forecasts, or anomalies highlighted
-- ❌ BAD: Pie chart of categories
-- ✅ GOOD: Focused metric card showing the dominant category with a small visual indicator of its proportion and comparative context
-
-**When to use different methods**:
-
-- **Charts/Graphs**: Trends, comparisons, distributions, relationships (ALWAYS with insight annotations, highlighting, or contextual markers)
-- **Icons/Indicators**: Status, categories, quick recognition, severity levels
-- **Metrics/Numbers**: Single key values, KPIs with context (vs. target, vs. last period, trend indicator)
-- **Combination layouts**: Mix large metrics with supporting mini-charts for context
-- **Text**: Labels, brief context, annotations only when necessary
-
-**Required elements for insight**:
-
-- Comparison points (vs. average, vs. goal, vs. previous period)
-- Visual highlighting of what's important (color coding, sizing, positioning)
-- Indicators of direction/trend (arrows, sparklines, change percentages)
-- Context that explains significance (why this matters, what's normal)
-
-**Avoid**:
-
-- Large blocks of text, lengthy descriptions, text-only widgets
-- Generic bar/line charts that just show data without insight or context
-- Equal visual weight for all data points (everything looks equally important)
-- Visualizations that require the user to interpret meaning themselves
-- Missing comparison or context that would make the data actionable
-- If you find yourself creating a chart that could be from Excel's default templates, you're doing it wrong.
-
 # UI Widget Generator Instructions
 
 ## CRITICAL RULES - READ FIRST
@@ -79,12 +38,16 @@
 
 **CRITICAL: You MUST use only the pre-defined themed components provided in the application.**
 
-- **DO NOT** create new components
-- **DO NOT** use custom components
-- **DO NOT** write components from scratch
-- **ONLY** use the existing themed components available in the component library
+- **DO NOT** build a lookalike component from scratch when the library already provides one
+- **DO NOT** use raw HTML controls or a competing component library
+- **ONLY** use the existing themed components available in the component library, or — for a
+  legitimate gap where no library component fits — a wrapper/re-export built through the
+  customization layer, composing existing components and preserving their contracts
 
-When building widgets, you must work exclusively with the components that have been provided to you. All UI elements must be constructed using these pre-existing themed components.
+When building widgets, you must work exclusively with the components that have been provided to
+you, extended only through the sanctioned customization layer for legitimate gaps. All UI
+elements must be constructed using these pre-existing themed components (or their sanctioned
+customization-layer wrappers).
 
 ### Widget Dimensions
 
@@ -260,19 +223,22 @@ Widgets are VISUAL tools. If a user needs to read paragraphs to understand the d
 1. **DO NOT** make up data to complete the widget
 2. **DO NOT** use assumptions or estimates
 3. **DO** clearly indicate what data is available and what is missing
-4. **DO** ask for the specific data needed before proceeding
+4. **DO** ask for the specific data needed before building ONLY when the widget cannot be
+   accurate without it (no accurate, valuable subset of the request can be built from the
+   data provided); otherwise build from what is available instead of asking (see
+   Intelligent Adaptation below)
 
 **Remember**: An incomplete but accurate widget is infinitely better than a complete but inaccurate one. Data integrity is non-negotiable.
 
 ### Intelligent Adaptation
 
-**MANDATORY: Work with available data to create the best possible widget. DO NOT ask follow-up questions about missing data.**
+**MANDATORY: Work with available data to create the best possible widget. Do not ask follow-up questions about missing data when any accurate widget can be built from what was provided; asking is reserved for the single case above, where the missing data is required for correctness.**
 
 While you must never hallucinate or assume data, you MUST intelligently adapt to work with the data that IS available:
 
 - **Assess what's available**: Evaluate the data provided and determine what insights can be accurately derived
 - **Adapt immediately**: If ideal data is unavailable, IMMEDIATELY pivot to showcase the next best data that is relevant and valuable
-- **DO NOT ask for more data**: Do not get stuck requesting additional data - work with what you have
+- **DO NOT get stuck requesting more data**: When an accurate widget is possible, work with what you have
 - **Prioritize value**: Focus on what CAN be displayed that provides genuine insight, rather than what's missing
 - **Be flexible with visualization types**: If the preferred chart type requires unavailable data, choose an alternative visualization that works with available data
 
@@ -283,7 +249,7 @@ While you must never hallucinate or assume data, you MUST intelligently adapt to
 - If comparative data is missing, focus on absolute values or trends that exist
 - If Category A data is unavailable, pivot to Category B data that IS available and relevant
 
-**The goal**: Generate the most valuable, accurate widget possible given the data constraints, without ever compromising on accuracy or fabricating information. Always deliver a widget - never get stuck in data collection mode.
+**The goal**: Generate the most valuable, accurate widget possible given the data constraints, without ever compromising on accuracy or fabricating information. Deliver a widget whenever an accurate one is possible; never get stuck in data collection mode.
 
 ## Widget Creation Process