@mihcm/ui

Universal MiHCM UI primitives for React, Next.js, and React Native.

This is the primary component package. It ships typed, tokenized primitives with per-component exports so applications can import only what they use.

Current release

Current package version: 0.16.0.

This release rebuilds Toast on top of sonner (themed end-to-end with MiHCM tokens) and lands the MainSidebar polish + whitelabel layer: five interaction variants (drilldown / floating / columns / command / hover), shadcn-style collapsible="icon", mobile hamburger + Sheet pattern, vertical guide lines for arbitrary nesting, and a 14-token colorScheme prop for full whitelabeling. See CHANGELOG.md and the public changelog at https://designsystem.mihcm.com/help/changelog.

Install

pnpm add @mihcm/ui @mihcm/theme @mihcm/tokens

For web apps, also import the theme CSS once at the app root:

import '@mihcm/theme/globals.css';

Usage

Prefer per-component imports for tree-shaking:

import { Button } from '@mihcm/ui/Button';
import { Card, CardContent, CardHeader, CardTitle } from '@mihcm/ui/Card';

export function Example() {
  return (
    <Card>
      <CardHeader>
        <CardTitle>Employee profile</CardTitle>
      </CardHeader>
      <CardContent>
        <Button>Save changes</Button>
      </CardContent>
    </Card>
  );
}

Every primitive accepts className for Tailwind/NativeWind overrides. Use MiHCM semantic tokens and standard Tailwind utilities. Do not hardcode raw colors, inline styles, or local CSS unless a component explicitly documents that escape hatch.

Variant styling uses proven helpers rather than handwritten class maps: class-variance-authority for simple single-root variants, and tailwind-variants when a component needs multiple styled slots or compound variants.

What is included

• Form controls: Input, Textarea, SearchField, Select, Combobox, Checkbox, CheckboxGrid, RadioGroup, Switch, Slider, DatePicker, Calendar, InputOTP.
• Navigation and layout: TopBar, MainSidebar, Sidebar, PageShell, TitleBar, NavigationMenu, Breadcrumb, Pagination, Tabs, Link, ScrollArea, Resizable.
• Overlays: Dialog, AlertDialog, Sheet, Drawer, Popover, Popper, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, Toast.
• Data and visualization: Table, DataTable, Chart, Progress, StatCard, StatusBadge, NotificationBadge, TransferList.
• Content and display: Text, Button, IconButton, Card, Badge, Banner, Alert, Avatar, AvatarGroup, Logo, Skeleton, Separator, AspectRatio, EmptyState, SectionHeader, RichTextEditor, Tag, Toggle, Command, Carousel.

Recent additions and fixes

0.16.0

• Toast rebuilt on top of sonner. Exposes the full upstream feature set (toast.success/error/warning/info/message/loading, toast.promise, toast.custom, action+cancel buttons, swipe-to-dismiss, expand-on-hover, theme switching) with MiHCM tokens mapped through sonner's CSS variables so surface, type tints, and buttons follow the design-system palette in light + dark mode. Legacy <ToastProvider> + <Toast> sub-components remain as deprecated shims.
• MainSidebar ships shadcn-style collapsible toggle (collapsible="icon"), five interaction variants, deep-nesting breadcrumbs (PathBreadcrumb), mobile hamburger pattern via existing Sheet, and a 14-token colorScheme prop (bg, fg, railBg, railFg, panelBg, panelFg, accentBg, accentFg, border, mutedFg, hoverBg, ring, tooltipBg, tooltipFg) that cascades through every nested affordance — including tooltips, badges, breadcrumbs, panel surfaces, and dividers. Outside-click + Esc dismissal unified, columns variant flushSync-resets deep stack on close, focus uses preventScroll.
• Icons + badges in active rows inherit currentColor from the parent button so themed accent surfaces render the right contrast.

0.15.0

• Added a semantic Link primitive for real navigation, with inline, nav, standalone, button-like, muted, foreground, and accent variants.
• Added semantic Text as="h1" | "h2" | "p" | ... rendering so docs, apps, and AI-generated text preserve the actual document outline instead of styling generic spans.
• Made Button default to type="button" while still supporting explicit type="submit" and type="reset" for form actions.
• Added tokenized SectionHeader spacing, surface, border, radius, shadow, and slot class override props for contained section layouts.
• Added larger Logo size presets and brand-aware scaling for approved logo assets.
• Stabilized Sidebar mobile behavior with explicit mobile Sheet state, configurable mobile widths, and side-aware right/left trigger, rail, divider, and inset handling.
• Added Popper and wired Popover to share the same positioning contract.
• Expanded TopBar, MainSidebar, Menubar, HoverCard, Collapsible, DataTable, TransferList, Breadcrumb, Toast, Progress, and Slider customizability.
• Upgraded Calendar to @daypicker/react v10 and documented the full DayPicker passthrough surface.
• Added React Select-powered advanced selects while keeping the native-parity composable Select.
• Normalized form field surfaces across Input, Textarea, SearchField, Select, React Select, Combobox, and DatePicker with reduced shadow-mi-input elevation.
• Added tailwind-variants as an approved dependency for slot-heavy and compound component styling; keep it installed when copied or local primitives import it.
• Fixed DatePicker and Calendar popup UX: compact triggers, icon-only trigger behavior, stable popover placement, dropdown month/year controls, aligned time inputs, and range popovers that stay open unless explicitly configured to close.
• Fixed DatePicker triggerWidth="full" so responsive fields span the grid without stretching the calendar popup.
• Fixed Tracker weighted segment sizing and timeline end caps by applying layout to the direct list item wrapper.
• Removed the experimental editor export and dependency set; use RichTextEditor for rich text.
• Fixed known UX regressions around tabs resizing, Select placeholder/label behavior, tooltip sizing, sheet exit animation, toast duplication, avatar group rings, and right-side sidebar placement.

Client and server compatibility

Components that use browser state, portals, focus management, dates, or event handlers must be rendered from a Client Component in Next.js. Static wrappers and plain display components can be composed from Server Components when they do not receive event handlers.

Practical rule:

'use client';

import { Select } from '@mihcm/ui/Select';

export function ClientFilter() {
  return <Select placeholder="Choose team" />;
}

When in doubt, wrap interactive examples in a small client boundary and keep data loading in the server parent.

Accessibility contract

• Keyboard access and visible focus states are required.
• Touch targets should stay at or above 44px where the component is interactive.
• Components must use semantic roles/attributes from the underlying primitive or native element.
• Use Link for href navigation and Button for actions. In forms, submit/reset buttons must set the explicit type.
• Inputs must have a visible label or an accessible name, and helper/error text must be connected with aria-describedby where applicable.
• Headings must render as headings, either with native h1-h6 tags or Text as="h1" through Text as="h6".
• Color changes must use tokens with WCAG AA contrast.
• Loading, disabled, error, empty, and selected states must remain readable in light and dark mode.

Security contract

• Do not render untrusted HTML through component props.
• Do not pass model-generated component paths or imports into this package.
• Do not put secrets in props, class names, logs, Storybook args, screenshots, or docs examples.
• AI-rendered usage must go through @mihcm/ai-ui Zod schemas first.

Maintainer checklist

When adding or changing a primitive:

1. Update the component source and native parity file when applicable.
2. Add or update Storybook stories and focused regression tests.
3. Update src/apps/docs/content/components/<component>/.
4. Update docs/components/<Component>.md and src/apps/docs/lib/registry.ts.
5. If the component can be AI-rendered, update @mihcm/ai-ui schemas and renderer; otherwise add an explicit coverage decision.
6. Add a changeset before publishing.

Build

cd src
pnpm -F @mihcm/ui build
pnpm -F @mihcm/ui typecheck

Related docs

• docs/components/ contains per-component wiki pages.
• docs/CONVENTIONS.md describes design and implementation rules.
• docs/security-playbook.md contains library and AI-UI security rules.