@machinemetrics/mm-react-components 1.5.0-0 → 1.5.0

package/CHANGELOG.md

@@ -5,6 +5,46 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-08-28
+
+### Added
+
+- **`components` skill for AI coding assistants:** the package now ships a
+  canonical skill (`dist/cursor-skill/components/`) that steers agents to
+  current mm-react-components guidance, installable into Cursor, VS Code
+  Copilot, Claude Code, and Gemini CLI via `npx mm-install-skill` (and
+  `mm-init`). Replaces the outdated `mm-carbide` skill: a managed legacy
+  install triggers a migration warning; user files are never deleted, and
+  locally modified managed files are backed up to non-colliding `.bak` names.
+- **Authoring gates in `npm run verify`:** `check:theme-parity` (light/dark
+  rule and token parity in `carbide.css`; theme-invariant rules skipped
+  automatically; exemptions recorded and announced) and
+  `check:component-artifacts` (the eight-artifacts checklist per component,
+  resolving `data-slot`s through imports and matching real export names).
+  Baselines grandfather pre-existing gaps so only new drift fails.
+- **`scripts/scaffold-component.cjs`:** generates the eight-artifact skeleton
+  for a new component; refuses on collisions; `--dry-run` previews.
+- **`npm run verify:component`:** scoped iteration gate (changed-component
+  detection, scoped lint, incremental type-check, both checkers, only your
+  visual spec) — seconds per loop instead of the full verify.
+- **Previews and both-theme visual coverage** for `SearchInput`,
+  `SimplePagination`, and `SpinnerCarbide`; `date-range-picker` spec renamed
+  to match conventions.
+- **`agent-docs/component-mapping-reference.md`:** mapping rows for 25
+  previously undocumented components.
+- Repo-local `add-component` authoring skill documenting the eight-artifact
+  contract for library contributors.
+
+### Changed
+
+- Shipped agent docs converged on the `components` skill contract (no shadcn
+  fallback recommendations or palette-class guidance).
+
+### Security
+
+- Dependency audit fixes: 0 known vulnerabilities remaining (undici, vite,
+  postcss/nanoid, brace-expansion, and @babel/core chains bumped).
+
 ## [1.4.0] - 2026-06-17
 
 ### Added
@@ -96,37 +136,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 - Preview app: `CodePreview` route remains hash-only for tests; sidebar exclusions updated. Preview build trims `esbuild.keepNames` where snippet naming no longer requires it.
 
-## [Unreleased]
-
-### Changed
-
-- **TicketDetails:** Two-column **narrative + metadata** layout: header includes ticket id, title, and **status / priority / due** (keys `status`, `priority`, `dueDate`, `due`); main column is **description** then **Activity** with **All / Comments / Updates** tabs; right rail is **Details** (people), **Dates**, and **Custom fields** with optional **Show more** and sticky positioning on large viewports. Optional `onBack` and `onAddCustomField`. `data-slot` hooks for Carbide theming.
-- **`partitionDetailFields`:** Now returns `headerFields`, `mainColumnFields`, `sidebarPeopleFields`, `sidebarDateFields`, `sidebarCustomFields`, and composed `sidebarFields` (people → dates → custom). `assignee` key maps to the people rail. **Breaking for consumers** that assumed `status` / `priority` / `dueDate` lived only in `sidebarFields` or that `otherMainFields` rendered in the main column — those fields are repositioned in the default `TicketDetails` shell (see `PartitionDetailFieldsResult`).
-
-### Added
-
-- **`TicketSystemEvent`** and optional `TicketDetails` prop **`systemEvents`** for the Updates timeline and All-tab merge.
-- **`TicketFieldControl`:** optional **`layout="inline"`** for compact header controls; **`date`** fields use the Carbide **`DatePicker`** (not native `<input type="date">`).
-- **`DatePicker`:** optional **`triggerClassName`** for trigger button styling; optional **`aria-invalid`** / **`aria-describedby`** on the trigger; **controlled `month`** resets when the popover opens so the calendar shows the **selected date’s month** (or `defaultMonth` / today when empty).
-- **`TicketForm`:** **`date`** fields use **`DatePicker`** (not native `<input type="date">`).
-- **`parseTicketDateString`** / **`formatTicketDateString`** exported from the tickets module for host apps.
-- **`TicketFieldType` `updatedDate`:** Read-only timestamp for “last updated” (and similar). Renders as styled text in **`TicketForm`** and **`TicketDetails`** — never an `<input>`. Use **`formatTicketTimestampDisplay`** for custom UIs; value is typically ISO or `YYYY-MM-DD` on the ticket payload.
-- **`TicketDetailsLabels`:** strings for activity tabs, sidebar section titles, back button, show more/less, add field, and comment body label.
-
-## [1.3.0] - 2026-03-19
-
-### Changed
-
-- **TicketDetails** (formerly `TicketDetailSheet`): Renders **detail content only** (no outer `Sheet`), same presentation-only model as `TicketForm`. No `open` / `onClose` / `onOpen`; the host controls visibility and chrome (e.g. `Sheet` + `SheetContent` with its own close). Renamed exports: `TicketDetails`, `TicketDetailsProps`, `TicketDetailsLabels`, `defaultTicketDetailsLabels`, `mergeTicketDetailsLabels`. Removed `closeAriaLabel` from detail labels (library no longer renders a close control).
-- **Tickets module file names:** Renamed to PascalCase under `src/components/ui/tickets/` (`TicketTypes.ts`, `TicketLabels.ts`, `UserFieldValue.ts`, `TicketUserSelect.tsx`, `TicketDates.ts`, `TicketDetailLayout.ts`) for consistency with other feature folders.
-
-### Added
-
-- **Ticket pattern components:** `TicketForm`, `TicketDetails`, `TicketFieldControl`, and `UserDisplay` for schema-driven ticket create/edit and detail UI. Host apps inject `userSelectComponent` and own persistence (`onSubmit`, `onCancel`, `onValuesChange`, `onPostComment`). Optional `labels` props override default copy.
-- **Ticket utilities and types:** Exported `Ticket`, `TicketFieldDefinition`, `Comment`, and helpers (`fieldKeyToHeader`, `getMergedDetailFields`, `partitionDetailFields`, `formatCreationDate`, `formatRelativeTime`, user-field JSON helpers).
-- **Docs:** `src/components/ui/tickets/README.md`, `agent-docs/tickets-pattern.md`, and agent-documentation-reference table entry.
-- **Kanban:** Compound `KanbanBoard`, `KanbanColumn`, `KanbanCard`, and `KanbanCardOverlay` with `@dnd-kit` drag-and-drop. Helpers `dataToKanbanItems`, `normalizeToKanbanColumn`, and `computeMoveFromDragEnd` map table-shaped data to board items and derive moves from drag-end events. Column chrome uses `SheetBanner`; README, preview, Playwright visual tests, and agent-documentation-reference updates.
-
 ---
 
 ## [1.2.3] - 2026-03-23

package/README.md

@@ -186,33 +186,6 @@ document.documentElement.classList.add('carbide');
 - You want to minimize bundle size
 - You're using our components with your own Tailwind config
 
-#### 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.
-
-```tsx
-// index.tsx
-import { ThemeRoot } from '@machinemetrics/mm-react-components';
-
-<ThemeRoot>
-  <App />
-</ThemeRoot>
-```
-
-```tsx
-// 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
 
 ```tsx

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

@@ -54,16 +54,14 @@ This directory contains comprehensive documentation and tools for AI agents work
 
 ### Layout & Navigation
 
-| Component               | Exports                                                                                                                                                                                                                       | Description                                                                 |
-| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- |
-| **ResizablePanelGroup** | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`                                                                                                                                                                    | Split layouts with drag-to-resize; use for workspaces, dashboards, IDE-like UIs |
-| **Sidebar**             | `Sidebar`, `SidebarProvider`, `SidebarInset`, `SidebarHeader`, `SidebarContent`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarTrigger`, etc.                                                                   | Navigation panel; collapsible to icons; use for app nav, not generic content |
-| **Card**                | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`                                                                                                                                            | Discrete content blocks (summary, form section, metric); **not** for structural layout or panels (no built-in scroll) |
-| **ScrollArea**          | `ScrollArea`, `ScrollBar`                                                                                                                                                                                                      | Scrollable region; **must have constrained height** (e.g. `h-[300px]`, `max-h-[50vh]`, or `flex-1 min-h-0` in flex layout) or it won’t scroll |
-| **Separator**           | `Separator`                                                                                                                                                                                                                    | Visual divider                                                             |
-| **Tabs**                | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`                                                                                                                                                                               | Tabbed interface                                                           |
-| **Breadcrumb**          | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis`                                                                                               | Navigation breadcrumbs                                                     |
-| **PageHeader**          | `PageHeader` (+ types)                                                                                                                                                                                                        | Application page header with actions/tabs                                  |
+| Component      | Exports                                                                                                                           | Description                                                                                                                                   |
+| -------------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Card**       | `Card`, `CardHeader`, `CardTitle`, `CardDescription`, `CardContent`, `CardFooter`                                                 | Content container with sections (no built-in scroll)                                                                                          |
+| **ScrollArea** | `ScrollArea`, `ScrollBar`                                                                                                         | Scrollable region; **must have constrained height** (e.g. `h-[300px]`, `max-h-[50vh]`, or `flex-1 min-h-0` in flex layout) or it won’t scroll |
+| **Separator**  | `Separator`                                                                                                                       | Visual divider                                                                                                                                |
+| **Tabs**       | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`                                                                                  | Tabbed interface                                                                                                                              |
+| **Breadcrumb** | `Breadcrumb`, `BreadcrumbList`, `BreadcrumbItem`, `BreadcrumbLink`, `BreadcrumbPage`, `BreadcrumbSeparator`, `BreadcrumbEllipsis` | Navigation breadcrumbs                                                                                                                        |
+| **PageHeader** | `PageHeader` (+ types)                                                                                                            | Application page header with actions/tabs                                                                                                     |
 
 ### Overlays & Modals
 
@@ -98,20 +96,18 @@ This directory contains comprehensive documentation and tools for AI agents work
 
 ### Advanced Components
 
-| Component           | Exports                                                                                                                                                                                                                                | Description                                                                                                                                                          |
-| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Component           | Exports                                                                                                                                                                                                                                | Description                                                                              |
+| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | **DataTable**       | `DataTable`, `DataTablePagination`, `ResponsiveTable`, `TABLE_TOKENS`, column creators, `useTableController`, `UseTableControllerReturn`, toolbar, CSV export (+ types); optional **`controller`** prop to share state with `FileGrid` | Full-featured data table with sorting, filtering, pagination (client-side & server-side) |
 | **Thumbnail**       | `Thumbnail` (+ types)                                                                                                                                                                                                                  | Bordered thumbnail shell with optional footer (`data-slot` for Carbide)                  |
-| **FileIcon**        | `FileIcon`, `FileIconGlyph`, `inferFileIconKind`, `getExtensionFromFileName`, `formatFileIconExtensionLabel` (+ types)                                                                                                                | File glyph + label from extension inference or overrides                                 |
+| **FileIcon**        | `FileIcon`, `FileIconGlyph`, `inferFileIconKind`, `getExtensionFromFileName`, `formatFileIconExtensionLabel` (+ types)                                                                                                                 | File glyph + label from extension inference or overrides                                 |
 | **FileThumbnail**   | `FileThumbnail` (+ types); `FileThumbnailBadgeConfig`                                                                                                                                                                                  | Button wrapping `Thumbnail` + `FileIcon` and optional badge                              |
 | **FileGrid**        | `FileGrid` (+ types)                                                                                                                                                                                                                   | Icon grid bound to a TanStack `Table` (same `controller` as `DataTable`)                 |
 | **HeroMetricCard**  | `HeroMetricCard`, `HeroMetricCardItem` (+ types)                                                                                                                                                                                       | Metrics dashboard card with trends                                                       |
 | **Calendar**        | `Calendar`                                                                                                                                                                                                                             | Date picker calendar                                                                     |
 | **DatePicker**      | `DatePicker`                                                                                                                                                                                                                           | Single date selection with label and placeholder                                         |
-| **DateRangePicker** | `DateRangePicker`, `DATE_RANGE_PRESETS`, `findMatchingPreset`, `PRESET_IDS`, `resolvePresets` (+ types); full variant: `presetIds`, `presetLabels` | Date range selection; `variant="full"` for presets sidebar + dual-month calendar |
+| **DateRangePicker** | `DateRangePicker`                                                                                                                                                                                                                      | Date range selection                                                                     |
 | **Dropzone**        | `Dropzone`, `DropzoneContent`, `DropzoneEmptyState`                                                                                                                                                                                    | File upload drag-drop                                                                    |
-| **Kanban**          | `KanbanBoard`, `KanbanColumn`, `KanbanCard`, `KanbanCardOverlay`, `normalizeToKanbanColumn`, `dataToKanbanItems` (+ types)                                                                                                             | Drag-and-drop Kanban board; compound API; same columns/data as DataTable                  |
-| **Tickets**         | `TicketForm`, `TicketDetails`, `TicketFieldControl`, `UserDisplay`, field helpers (`formatTicketTimestampDisplay`, …), `TicketSystemEvent`, `PartitionDetailFieldsResult` (+ `TicketUserSelectComponent`)                             | Schema-driven ticket form and detail UI; **`data-slot`** on form/details/field wrapper (see tickets README); optional `systemEvents` / `onBack` / `onAddCustomField` |
 | **Chart**           | `ChartContainer`, `ChartTooltip`, `ChartTooltipContent`, `ChartLegend`, `ChartLegendContent`, `ChartStyle` (+ `ChartConfig` type)                                                                                                      | Recharts integration                                                                     |
 
 ### Interactive Elements
@@ -130,36 +126,12 @@ This directory contains comprehensive documentation and tools for AI agents work
 | `cn`            | Class name utility for merging Tailwind classes                                                                                                                                |
 | **Theme Utils** | `activateCarbideTheme`, `deactivateCarbideTheme`, `toggleCarbideTheme`, `isCarbideThemeActive`, `activateDarkMode`, `deactivateDarkMode`, `toggleDarkMode`, `isDarkModeActive` |
 
-### Total: 46+ Components
+### Total: 44+ Components
 
 All components follow shadcn/ui patterns with Carbide theme integration for industrial/manufacturing contexts.
 
 ## Component Usage Guides
 
-### Table + Kanban from same columns and data
-
-Use the same column definitions and data for both DataTable and Kanban:
-
-- **Columns**: Pass table column objects directly to `KanbanColumn` via `column={col}` (accepts `{ id, title? }` or `{ id, header? }`).
-- **Items**: `const items = dataToKanbanItems(data, { columnIdKey: 'status', titleKey: 'name' });` then filter by column when rendering cards.
-- **Compound API**: `<KanbanBoard onMove={...}><KanbanColumn column={col}>…<KanbanCard item={item}>…</KanbanCard>…</KanbanColumn></KanbanBoard>`. Card content is children of `KanbanCard`. Optional `renderDragPreview(item)` for custom drag overlay.
-
-### Ticket form and detail sheet
-
-Schema-driven ticket UI (`TicketForm`, `TicketDetails`, `TicketFieldControl`) — inject a user picker (`TicketUserSelectComponent`), pass `onSubmit` / `onCancel`, and wire `onValuesChange` + `comments` / `onPostComment` / optional `systemEvents`. `TicketDetails` has no open/close API; mount it wherever needed (header metadata, Activity tabs, sticky sidebar). See **[tickets-pattern.md](./tickets-pattern.md)**.
-### Layout and panel-like UI: don’t use Card for every section
-
-Use the right component for the job instead of wrapping everything in Card:
-
-| Need | Use | Notes |
-|------|-----|--------|
-| **Split workspace / dashboard / IDE-like layout** | **ResizablePanelGroup** | Horizontal or vertical split; drag-to-resize; keyboard accessible. Best for admin panels, SaaS tools, file-explorer style UIs. On mobile, use CSS to stack panels vertically. |
-| **Navigation panel (app nav, links, structural sidebar)** | **Sidebar** | Composable, themeable, collapsible to icons. Use for application layout with nav links and groups, not for arbitrary “panel” content. |
-| **Temporary or slide-out panel (settings, details, filters)** | **Sheet** | Slides in from any side (left, right, top, bottom). Use for settings, notifications, detail views, form overlays. See Overlays & Modals table. |
-| **Discrete content block (summary box, metric, form section)** | **Card** | Card is for **content** with sections (header, body, footer), not for structural layout. Do not use Card as the main wrapper for full-page sections, side panels, or workspace areas. |
-
-**Best practice for full app layout:** Combine Sidebar for navigation and ResizablePanelGroup (or a main content area) for the main workspace. Use Sheet for overlay panels; use Card only for distinct content blocks within a panel or page.
-
 ### Scrolling content: Card vs ScrollArea
 
 **There is no "Panel" component.** For a panel-like or card-like region where content may be longer than the visible area, use **ScrollArea** around the scrollable content. **Card** is a structural container (border, padding, sections) and does not add scrolling.
@@ -262,71 +234,6 @@ The `DataTable` component supports both client-side and server-side pagination.
 4. The component automatically handles edge cases (empty data, partial last page, etc.)
 5. See component README at `src/components/ui/data-table/README.md` for detailed examples
 
-### DateRangePicker: date ranges, presets, and helpers
-
-Use **`DateRangePicker`** when the user needs a **start/end date range** (filters, reports, scheduling). Use **`DatePicker`** for a **single date**. Both are in `@machinemetrics/mm-react-components`.
-
-**Imports (typical):**
-
-```tsx
-import {
-  DateRangePicker,
-  PRESET_IDS,
-  // Optional — programmatic preset matching / same subset as the picker:
-  DATE_RANGE_PRESETS,
-  findMatchingPreset,
-  resolvePresets,
-} from '@machinemetrics/mm-react-components';
-```
-
-**Value shape:** Controlled with `value` and `onValueChange`. Type is `[string | null, string | null] | null | undefined` — dates are **`yyyy-MM-dd`** strings (ISO date only), e.g. `['2026-03-01', '2026-03-15']`. `allowSingleDate` allows one-day selections.
-
-**Variants:**
-
-| Variant | Prop | What you get |
-| ------- | ---- | -------------- |
-| **Simple** (default) | omit or `variant="simple"` | Single-calendar popover; Clear / Cancel / Apply (Clear reverts draft to last committed `value` without closing). |
-| **Full** | `variant="full"` | Presets sidebar, dual-month calendar, company start time + optional custom hours, footer with summary and same Clear/Cancel/Apply behavior. |
-
-**Full variant — presets:** The sidebar lists built-in quick ranges (Today, Yesterday, Last 7/30/90 days, week/month/year rollups, week/month/quarter/year-to-date, Custom). Full list and behavior: **`src/components/ui/date-range-picker/README.md`** in the repo (or browse package source after install).
-
-**Customizing presets (full variant only):**
-
-- **`presetIds`** — Pass a **subset and order** of presets using **`PRESET_IDS`** constants (not raw strings in app code, so IDs stay typed and consistent):
-
-  ```tsx
-  presetIds={[
-    PRESET_IDS.TODAY,
-    PRESET_IDS.LAST_7_DAYS,
-    PRESET_IDS.MONTH_TO_DATE,
-    PRESET_IDS.CUSTOM,
-  ]}
-  ```
-
-  Omit `presetIds` for all defaults. Use `presetIds={[]}` to hide every preset row.
-
-- **`presetLabels`** — Override labels (i18n or wording), keyed by **`PresetId`** / `PRESET_IDS`:
-
-  ```tsx
-  presetLabels={{ [PRESET_IDS.MONTH_TO_DATE]: 'This month' }}
-  ```
-
-**Programmatic use (outside the picker):**
-
-- **`DATE_RANGE_PRESETS`** — Array of preset definitions (`id`, label, `getRange()`).
-- **`resolvePresets(presetIds?)`** — Resolves which preset objects to use (same logic as the full picker). Pass the **same `presetIds` array** as the picker so “which preset is active” matches the UI.
-- **`findMatchingPreset(start, end, now, presets?)`** — Given two dates and an optional resolved preset list, returns which **preset id** matches the range (or `undefined`).
-
-Use these when syncing URL/query params, highlighting an active filter, or validating that a range matches a named preset.
-
-**Related:** `Calendar` for bare calendars; `DatePicker` for single date with label. Carbide styles apply with the usual **`carbide`** wrapper and library **`/styles`** import.
-
-**Important notes for AI agents:**
-
-1. Prefer **`PRESET_IDS.*`** in source code for `presetIds` / `presetLabels` keys — do not hardcode string literals like `'month-to-date'` unless you are sure of the id contract.
-2. Full variant may need horizontal space (dual months); avoid squeezing inside tiny columns without testing.
-3. Detailed props table and Copy/paste examples: package **README** at `src/components/ui/date-range-picker/README.md`.
-
 ## Directory Structure
 
 ```

package/agent-docs/ai-agent-guide.md

@@ -37,8 +37,8 @@ The migration configuration is located at `scripts/chakra-to-shadcn-migrator/cha
 
 | Chakra Component | Replacement                                                              | Notes                              |
 | ---------------- | ------------------------------------------------------------------------ | ---------------------------------- |
-| `Box`            | `<div>`                                                                  | Add appropriate Tailwind classes   |
-| `Flex`           | `<div className="flex">`                                                 | Add flex-related Tailwind classes  |
+| `Box`            | `<div>`                                                                  | Layout utilities only; appearance via semantic tokens/variants, never palette classes |
+| `Flex`           | `<div className="flex">`                                                 | Layout utilities only; appearance via semantic tokens/variants, never palette classes |
 | `VStack`         | `<div className="flex flex-col gap-4">`                                  | Adjust spacing as needed           |
 | `HStack`         | `<div className="flex flex-row gap-4">`                                  | Adjust spacing as needed           |
 | `Stack`          | `<div className="flex flex-col gap-4">`                                  | Adjust direction/spacing as needed |
@@ -57,10 +57,10 @@ The migration configuration is located at `scripts/chakra-to-shadcn-migrator/cha
 
 | Chakra Component | Replacement             | Notes                                         |
 | ---------------- | ----------------------- | --------------------------------------------- |
-| `Field`          | `<div>` wrapper         | Use shadcn/ui form components for inputs      |
-| `NumberInput`    | `<input type="number">` | Add Tailwind classes, or use shadcn/ui Input  |
-| `Slider`         | `<input type="range">`  | Add Tailwind classes, or use shadcn/ui Slider |
-| `NativeSelect`   | `<select>`              | Add Tailwind classes, or use shadcn/ui Select |
+| `Field`          | `Field` form composition | `Field`, `FieldLabel`, `FieldDescription`, `FieldError` from `@machinemetrics/mm-react-components` |
+| `NumberInput`    | `Input` (`type="number"`) | `Input` from `@machinemetrics/mm-react-components`, not a raw `<input>` |
+| `Slider`         | `Slider` / `LabeledSlider` | `Slider`/`LabeledSlider` from `@machinemetrics/mm-react-components`, not a raw `<input type="range">` |
+| `NativeSelect`   | `Select` family          | `Select`, `SelectTrigger`, `SelectContent`, `SelectItem` from `@machinemetrics/mm-react-components` |
 
 ### UI Components (Direct Mappings Available)
 
@@ -186,8 +186,6 @@ The migration configuration is located at `scripts/chakra-to-shadcn-migrator/cha
 
 ### Card Components
 
-Use Card for **discrete content blocks** (summary, metric, form section), not for panel or layout structure. For panel-like UI use **ResizablePanelGroup**, **Sidebar**, or **Sheet** (see agent-documentation-reference.md).
-
 ```tsx
 // Chakra UI
 <Card>
@@ -282,7 +280,7 @@ import { Button, Input, Dialog } from '@machinemetrics/mm-react-components';
 </Box>
 
 // After
-<div className="p-4 bg-gray-100">
+<div className="p-4 bg-muted">
   <div className="flex flex-col gap-4">
     <div className="flex flex-col gap-4">
       <div className="flex flex-row gap-2">
@@ -305,10 +303,10 @@ import { Button, Input, Dialog } from '@machinemetrics/mm-react-components';
 </Text>
 
 // After
-<h2 className="text-lg font-semibold text-blue-500">
+<h2 className="text-lg font-semibold text-primary">
   Title
 </h2>
-<p className="text-sm text-gray-600">
+<p className="text-sm text-muted-foreground">
   Description
 </p>
 ```
@@ -400,8 +398,8 @@ import { Plus, Trash2 } from 'lucide-react'
 // Chakra UI colors
 <Box bg="blue.500" color="white">
 
-// Tailwind CSS colors
-<div className="bg-blue-500 text-white">
+// Semantic theme tokens (never palette classes like bg-blue-500)
+<div className="bg-primary text-primary-foreground">
 ```
 
 ### 3. Responsive Design
@@ -455,7 +453,7 @@ import '@machinemetrics/mm-react-components/themes/carbide';
 
 **Error**: Layout components like `Box`, `Flex` not found
 
-**Solution**: Replace with generic HTML elements and Tailwind classes
+**Solution**: Replace with generic HTML elements and layout-only Tailwind utilities (appearance still comes from semantic tokens/variants, never palette classes)
 
 ```tsx
 // Instead of <Box>, use <div>
@@ -515,7 +513,7 @@ If you have custom components built on Chakra UI:
 
 1. Identify the base Chakra component used
 2. Replace with equivalent MachineMetrics component
-3. Update styling to use Tailwind classes
+3. Update layout with Tailwind layout utilities; update appearance via semantic tokens/variants, never palette classes
 4. Test functionality thoroughly
 
 ### Complex Layout Migrations

package/agent-docs/ai-agent-init-guide.md

@@ -129,7 +129,7 @@ function MyComponent() {
 }
 ```
 
-**Done!** Components are ready to use. (This example uses Card for a single content block; for panel layouts or split UIs use ResizablePanelGroup, Sidebar, or Sheet—see agent-documentation-reference.md.)
+**Done!** Components are ready to use.
 
 ## Project Structure After Setup (zero-config)
 

package/agent-docs/chakra-migration-readme.md

@@ -82,9 +82,10 @@ These components can be automatically migrated:
 
 ### Manual Replacements Required
 
-These components need manual conversion to HTML + Tailwind:
+These components need manual conversion to HTML + Tailwind layout utilities. Appearance
+(color) always comes from semantic tokens/variants, never hardcoded palette classes:
 
-- `Box` → `<div>` with Tailwind classes
+- `Box` → `<div>` with layout-only Tailwind utilities
 - `Flex` → `<div className="flex">` with flex classes
 - `VStack` → `<div className="flex flex-col gap-4">`
 - `HStack` → `<div className="flex flex-row gap-4">`
@@ -92,8 +93,8 @@ These components need manual conversion to HTML + Tailwind:
 - `Container` → `<div className="container mx-auto px-4">`
 - `Center` → `<div className="flex items-center justify-center">`
 - `SimpleGrid` → `<div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4">`
-- `Heading` → `<h1>`, `<h2>`, etc. with Tailwind typography
-- `Text` → `<p>`, `<span>`, etc. with Tailwind typography
+- `Heading` → `<h1>`, `<h2>`, etc. with Tailwind typography sizing; color via semantic tokens
+- `Text` → `<p>`, `<span>`, etc. with Tailwind typography sizing; color via semantic tokens
 
 ## Migration Process
 
@@ -154,7 +155,7 @@ import { AddIcon } from '@chakra-ui/icons';
 // After
 import { Button, Input, Dialog } from '@machinemetrics/mm-react-components';
 import { Plus } from 'lucide-react';
-// Layout components become generic HTML elements with Tailwind classes
+// Layout components become generic HTML elements with layout-only Tailwind utilities
 ```
 
 ### Step 4: Convert Components
@@ -202,7 +203,7 @@ node scripts/chakra-to-shadcn-migrator/chakra-to-shadcn.js --apply --verbose
 
 1. **Missing Dependencies**: Install all required packages
 2. **Theme Not Applied**: Ensure Carbide theme is imported and applied
-3. **Layout Components**: Replace with HTML + Tailwind classes
+3. **Layout Components**: Replace with HTML + layout-only Tailwind utilities
 4. **Icons Not Working**: Update to Lucide React icons
 5. **Form Components**: Use new Form component structure
 

package/agent-docs/chakra-migration-troubleshooting.md

@@ -86,7 +86,7 @@ function App() {
 
 #### Issue: Custom colors not working
 
-**Cause**: Using Chakra color tokens instead of Tailwind classes.
+**Cause**: Using Chakra color tokens instead of the library's semantic theme tokens.
 
 **Solution**:
 
@@ -94,8 +94,8 @@ function App() {
 // Before (Chakra)
 <Box bg="blue.500" color="white">
 
-// After (Tailwind)
-<div className="bg-blue-500 text-white">
+// After (semantic tokens — never palette classes like bg-blue-500)
+<div className="bg-primary text-primary-foreground">
 ```
 
 ### 3. Layout Component Issues
@@ -112,8 +112,8 @@ function App() {
   Content
 </Box>
 
-// After
-<div className="p-4 bg-gray-100">
+// After (layout utility + semantic token)
+<div className="p-4 bg-muted">
   Content
 </div>
 ```
@@ -369,7 +369,7 @@ const [isOpen, setIsOpen] = useState(false)
 
 #### Issue: Colors not working
 
-**Cause**: Chakra color tokens not converted to Tailwind.
+**Cause**: Chakra color tokens not converted to semantic theme tokens.
 
 **Solution**:
 
@@ -377,8 +377,8 @@ const [isOpen, setIsOpen] = useState(false)
 // Before (Chakra)
 <Box bg="blue.500" color="white">
 
-// After (Tailwind)
-<div className="bg-blue-500 text-white">
+// After (semantic tokens — never palette classes like bg-blue-500)
+<div className="bg-primary text-primary-foreground">
 ```
 
 #### Issue: Responsive design not working

package/agent-docs/component-mapping-reference.md

@@ -41,7 +41,7 @@ This reference provides detailed mappings between Chakra UI components and Machi
 
 | Chakra UI    | Replacement | Tailwind Classes                                       | Notes                            |
 | ------------ | ----------- | ------------------------------------------------------ | -------------------------------- |
-| `Box`        | `<div>`     | Custom classes                                         | Add appropriate Tailwind classes |
+| `Box`        | `<div>`     | Layout utilities only (e.g. `p-4`, `flex`)             | Appearance via semantic tokens/variants, never palette classes |
 | `Flex`       | `<div>`     | `flex`                                                 | Add flex-related classes         |
 | `VStack`     | `<div>`     | `flex flex-col gap-4`                                  | Adjust spacing as needed         |
 | `HStack`     | `<div>`     | `flex flex-row gap-4`                                  | Adjust spacing as needed         |
@@ -54,8 +54,8 @@ This reference provides detailed mappings between Chakra UI components and Machi
 
 | Chakra UI | Replacement           | Tailwind Classes                 | Notes             |
 | --------- | --------------------- | -------------------------------- | ----------------- |
-| `Heading` | `<h1>`, `<h2>`, etc.  | `font-semibold`, `text-lg`, etc. | Use semantic HTML |
-| `Text`    | `<p>`, `<span>`, etc. | Custom classes                   | Use semantic HTML |
+| `Heading` | `<h1>`, `<h2>`, etc.  | Size/weight utilities (`text-lg`, `font-semibold`); color only via semantic tokens (`text-foreground`) | Use semantic HTML |
+| `Text`    | `<p>`, `<span>`, etc. | Semantic tokens for color (`text-muted-foreground`), never palette classes | Use semantic HTML |
 
 ### Modal/Dialog Components
 
@@ -82,7 +82,7 @@ This reference provides detailed mappings between Chakra UI components and Machi
 | Chakra UI | MachineMetrics | Import                                | Notes              |
 | --------- | -------------- | ------------------------------------- | ------------------ |
 | `Table`   | `Table`        | `@machinemetrics/mm-react-components` | Direct replacement |
-| `Card`    | `Card`         | `@machinemetrics/mm-react-components` | Use for discrete content blocks; for panel/split layout use ResizablePanelGroup, Sidebar, or Sheet (see agent-documentation-reference.md). |
+| `Card`    | `Card`         | `@machinemetrics/mm-react-components` | New component      |
 | `Avatar`  | `Avatar`       | `@machinemetrics/mm-react-components` | New component      |
 | `Tooltip` | `Tooltip`      | `@machinemetrics/mm-react-components` | Direct replacement |
 | `Popover` | `Popover`      | `@machinemetrics/mm-react-components` | Direct replacement |
@@ -93,7 +93,7 @@ This reference provides detailed mappings between Chakra UI components and Machi
 | --------- | -------------- | ------------------------------------- | -------------------- |
 | `Alert`   | `Alert`        | `@machinemetrics/mm-react-components` | New component        |
 | `Toast`   | `Toaster`      | `@machinemetrics/mm-react-components` | New component        |
-| `Spinner` | Custom         | Tailwind classes                      | Use Tailwind spinner |
+| `Spinner` | `Spinner`      | `@machinemetrics/mm-react-components` | New component        |
 
 ### Overlay Components
 
@@ -120,6 +120,38 @@ This reference provides detailed mappings between Chakra UI components and Machi
 | `Dropzone`        | `Dropzone`                             | `@machinemetrics/mm-react-components` | New component |
 | `SearchInput`     | `SearchInput`                          | `@machinemetrics/mm-react-components` | New component |
 
+### Additional Components
+
+Components without a one-to-one Chakra UI ancestor (or replacing composed Chakra patterns). Same import (`@machinemetrics/mm-react-components`) unless noted.
+
+| Chakra UI / pattern      | MachineMetrics                                                        | When to use                                                                                       |
+| ------------------------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `AspectRatio`            | `AspectRatio`                                                          | Constrain media (images, video, maps) to a fixed width/height ratio                               |
+| `ButtonGroup`            | `ButtonGroup`, `ButtonGroupSeparator`, `ButtonGroupText`               | Group related buttons into one segmented control with merged borders                              |
+| Custom carousel          | `Carousel`, `CarouselContent`, `CarouselItem`, `CarouselPrevious`, `CarouselNext` | Horizontally scrollable slides with previous/next controls (Embla-based)                |
+| —                        | `CodePreview`                                                          | Preview-app demo shell only — renders a component beside copyable code in this repo's preview app; not exported from the package, never use in apps |
+| Searchable `Select`      | `Combobox`                                                             | Single-select with type-to-filter search over a moderate option list                              |
+| Command palette          | `Command`, `CommandDialog`, `CommandInput`, `CommandList`, `CommandGroup`, `CommandItem`, `CommandEmpty` | Filterable command palette or searchable list, inline or in a dialog          |
+| Right-click `Menu`       | `ContextMenu`                                                          | Context (right-click) menus with items, submenus, checkbox/radio items                            |
+| Single date input        | `DatePicker`                                                           | Pick a single date from a popover calendar (pair of `DateRangePicker`)                            |
+| Empty state pattern      | `Empty`, `EmptyHeader`, `EmptyMedia`, `EmptyTitle`, `EmptyDescription`, `EmptyContent` | Empty-state placeholder with icon, title, description, and actions              |
+| `Stat` / stat group      | `HeroMetricCard`, `HeroMetricCardItem`                                 | Headline strip of 1–6 key metrics with optional trends, action or filter modes                    |
+| Hover `Popover`          | `HoverCard`, `HoverCardTrigger`, `HoverCardContent`                    | Rich preview shown on hover (non-modal, pointer-only)                                             |
+| `InputGroup` / addons    | `InputGroup`, `InputGroupAddon`, `InputGroupButton`, `InputGroupInput`, `InputGroupText`, `InputGroupTextarea` | Input with leading/trailing icons, text addons, or buttons   |
+| `PinInput`               | `InputOTP`, `InputOTPGroup`, `InputOTPSlot`, `InputOTPSeparator`       | One-time-code / PIN entry with per-character slots                                                |
+| `Kbd`                    | `Kbd`, `KbdGroup`                                                      | Render keyboard shortcuts and key combinations                                                    |
+| Menu bar pattern         | `Menubar`, `MenubarMenu`, `MenubarTrigger`, `MenubarContent`, `MenubarItem`, `MenubarSub` | Horizontal application menu bar with nested dropdown menus                     |
+| Top-level nav pattern    | `NavigationMenu`, `NavigationMenuList`, `NavigationMenuItem`, `NavigationMenuTrigger`, `NavigationMenuContent`, `NavigationMenuLink` | Site/app top navigation with dropdown panels                |
+| Page number pagination   | `Pagination`, `PaginationContent`, `PaginationItem`, `PaginationLink`, `PaginationPrevious`, `PaginationNext`, `PaginationEllipsis` | Full pagination with numbered page links and ellipsis        |
+| Split panes              | `ResizablePanelGroup`, `ResizablePanel`, `ResizableHandle`             | User-resizable side-by-side or stacked panels with drag handles                                   |
+| Custom scrollbars        | `ScrollArea`, `ScrollBar`                                              | Scroll container with themed, cross-browser-consistent scrollbars                                 |
+| Banner / callout strip   | `SheetBanner`                                                          | Shared/company context banner strip at the top of a sheet or panel (`variant="shared" \| "company"`) |
+| App shell nav            | `Sidebar`, `SidebarProvider`, `SidebarMenu`, `SidebarMenuItem`, `SidebarMenuButton`, `SidebarTrigger`, `useSidebar` | Collapsible application sidebar shell with grouped navigation |
+| Prev/next pager          | `SimplePagination`                                                     | Compact "Page X of Y" pager with previous/next buttons — prefer over `Pagination` when page links are unnecessary |
+| `Spinner`                | `SpinnerCarbide`                                                       | Carbide-styled loading spinner (inherits `currentColor`; size via `size-*` utility classes)       |
+| Grouped `Toggle`s        | `ToggleGroup`, `ToggleGroupItem`                                       | Single- or multi-select groups of toggle buttons (view switchers, formatting bars)                |
+| Large-list `Select`      | `VirtualizedCombobox` (+ `useLazyComboboxOptions`)                     | Combobox over large or lazily fetched option lists (virtualized rendering, async paging)          |
+
 ## Compound Component Mappings
 
 ### Modal/Dialog Structure
@@ -216,8 +248,6 @@ This reference provides detailed mappings between Chakra UI components and Machi
 
 ### Card Structure
 
-Use Card for **discrete content blocks** (e.g. summary box, metric card, form section). Do not use Card for structural layout or panel-like UI—prefer **ResizablePanelGroup** (split workspaces), **Sidebar** (nav panels), or **Sheet** (slide-out panels). See agent-documentation-reference.md “Layout and panel-like UI.”
-
 ```tsx
 // Chakra UI Structure
 <Card>
@@ -346,9 +376,13 @@ Use Card for **discrete content blocks** (e.g. summary box, metric card, form se
 
 | Chakra UI                | Tailwind CSS      | Notes            |
 | ------------------------ | ----------------- | ---------------- |
-| `bg="blue.500"`          | `bg-blue-500`     | Background color |
-| `color="white"`          | `text-white`      | Text color       |
-| `borderColor="gray.300"` | `border-gray-300` | Border color     |
+| `bg="blue.500"`          | `bg-primary`             | Map by role, not hue — semantic tokens only |
+| `color="white"`          | `text-primary-foreground` | Pairs with `bg-primary`                     |
+| `borderColor="gray.300"` | `border-border`          | Semantic border token                       |
+
+Never translate Chakra colors to Tailwind palette classes (`bg-blue-500`, `text-white`,
+`border-gray-300`); those hardcode appearance and break theming. Pick the semantic token
+that matches the color's role.
 
 ### Layout
 
@@ -419,7 +453,7 @@ import { Plus } from 'lucide-react';
 </Box>
 
 // After
-<div className="p-4 bg-gray-100">
+<div className="p-4 bg-muted">
   <div className="flex flex-col gap-4">
     <div className="flex flex-col gap-4">
       Content
@@ -452,7 +486,7 @@ import { Plus } from 'lucide-react';
 2. **Layout Issues**: Replace layout components with HTML + Tailwind
 3. **Icon Issues**: Update icon imports to Lucide React
 4. **Prop Issues**: Update prop names according to mapping table
-5. **Styling Issues**: Convert Chakra props to Tailwind classes
+5. **Styling Issues**: Convert Chakra layout props to Tailwind layout utilities; convert color/appearance props to semantic tokens and component variants — never hardcoded palette classes
 
 ### Validation Steps