Component Expandability Roadmap
This roadmap defines how MiHCM components should become more useful without turning the API into unbounded prop sprawl.
The rule is simple: expand through composition first, add props only when repeated product workflows prove the need.
Research baseline
| System | What MiHCM should adopt |
|---|---|
| Radix Primitives | Anatomy-first composition, controlled and uncontrolled state, asChild, accessibility behavior. |
| Chakra recipes | Typed variants, sizes, compound variants, and component defaults. |
| MUI APIs | Practical action props such as loading, icons, full-width, polymorphic roots, and slots. |
| Ant Design | Intent-led guidance for action hierarchy, danger, ghost, text, link, and disabled states. |
| Mantine | Consistent variant/size naming and application-level defaults. |
| Shopify Polaris | Patterns, tokens, components, icons, and product guidance together. |
| shadcn/ui | Primitives plus examples and blocks as the scaling layer. |
Classification
Every enhancement starts here.
| Type | Use when | Output |
|---|---|---|
| Prop expansion | Existing composition cannot express a repeated product need. | Source change, tests, Storybook, docs, changeset. |
| Slot expansion | Consumers need to replace icons, actions, metadata, headers, footers, triggers, or empty states. | Named slot or composable part. |
| Recipe expansion | Existing primitives can already build the workflow. | Docs example, Storybook story, MCP recipe. |
| Metadata expansion | Agents need better guidance or validation. | MCP recipe, AI-UI descriptor, anti-pattern rule. |
| No API change | Existing API is sufficient. | Docs rationale only. |
Shared prop language
| Prop | Meaning |
|---|---|
variant | Structural style such as default, outline, ghost, link, card, minimal. |
tone | Semantic intent such as primary, accent, success, warning, danger, neutral, info. |
size | Control dimensions and touch target. Use sm, md, lg; reserve icon for icon-only actions. |
density | Information density: comfortable, compact, dense. |
orientation | Layout direction: horizontal or vertical. |
loading | Pending action state. Keep existing isLoading where already public. |
invalid | Validation failure state for controls. |
error | Error content for field abstractions. |
required / optional | Form semantics and visible label affordance. |
fullWidth | Root stretches to container width. |
asChild | Web composition where child becomes rendered element. |
leftSection / rightSection | Control adornment slots. |
action / secondaryAction | Command slots for feedback/content surfaces. |
Audit matrix
| Batch | Components | Primary gap |
|---|---|---|
| Form and data | Form, DataTable, Table, CheckboxGrid, TransferList, SearchField, Command | Workflow depth, density, toolbar, empty/error/loading states, bulk actions. |
| Inputs and controls | Button, Input, Textarea, Select, Combobox, RadioGroup, Switch, Slider, Toggle, DatePicker, Calendar, InputOTP | Adornments, validation, helper text, loading, clearable, range/time/date use cases. |
| Navigation and layout | Sidebar, PageShell, TopBar, IconSidebar, NavigationMenu, Breadcrumb, Pagination, Tabs | Complete app shells, responsive behavior, overflow, active state. |
| Overlay and menu | Dialog, AlertDialog, Sheet, Drawer, Popover, HoverCard, DropdownMenu, ContextMenu, Menubar, Tooltip, Toast | Confirmation, settings, destructive action, keyboard examples, async states. |
| Feedback and content | Alert, Banner, EmptyState, Progress, Skeleton, StatusBadge, NotificationBadge, StatCard, SectionHeader, TitleBar | Recovery actions, priority, dismissibility, trend/meta, skeleton sets. |
| Media and structure | Avatar, AvatarGroup, Badge, Tag, Card, Accordion, Collapsible, Carousel, ScrollArea, Resizable, Separator, AspectRatio, Text, Label | Dense team/admin surfaces, truncation, overflow, required/optional labels. |
| Data visualization | Chart | More chart families, accessible summaries, dark-mode-safe palettes, empty/error/loading states. |
Per-component classification
| Component | Classification | Planned expansion |
|---|---|---|
| AccessLevelGroup | Prop + recipe | Permission matrix, disabled reasons, audit trail copy, compact density. |
| Accordion | Recipe | FAQ, settings groups, policy sections, long content, disabled items. |
| Alert | Slot + recipe | Actions, page outage, inline field alert, success save, destructive warning. |
| AlertDialog | Slot + recipe | Destructive confirmation, typed confirmation, async loading, focus return. |
| AspectRatio | Recipe | Media cards, previews, chart placeholders, video fallback. |
| Avatar | Prop + recipe | Shape/status audit, image failure, initials fallback, profile patterns. |
| AvatarGroup | Prop + recipe | Overflow label, profile preview pairing, dense team rows. |
| Badge | Prop + recipe | Counts, status, categories, removable taxonomy. |
| Banner | Slot + recipe | Priority, sticky page banner, persistence, action slot. |
| Breadcrumb | Recipe | Collapsed paths, entity detail trails, mobile overflow. |
| Button | Prop + recipe | Loading position, left/right sections, icon-only tooltip, split-button recipe. |
| Calendar | Recipe | Availability, blocked dates, payroll period, range, timezone examples. |
| Card | Slot + recipe | Clickable, KPI, entity summary, media, nested action, skeleton states. |
| Carousel | Recipe | Content rail, insight rail, keyboard, empty/single/many cases. |
| Chart | Recipe + MCP | Accessible summaries, semantic palettes, sparkline, stacked, dashboard recipes. |
| Checkbox | Prop + recipe | Helper/error pairing, indeterminate group, dense checklist. |
| CheckboxGrid | Prop + recipe | Search, loading, empty, disabled reason, grouped permissions. |
| Collapsible | Recipe | Advanced filters, progressive details, reduced-motion guidance. |
| Combobox | Prop + recipe | Async loading, create option, grouped options, empty state. |
| Command | Slot + recipe | App command palette, grouped results, recent searches, shortcuts. |
| ContextMenu | Recipe | Row menu, file menu, disabled explanations, submenus. |
| DataTable | Prop + slot + recipe | Density, toolbar, bulk actions, row actions, empty/loading states. |
| DatePicker | Recipe | Scheduling, payroll range, time selection, disabled dates. |
| Dialog | Slot + recipe | Form dialog, async save, validation summary, large content. |
| Drawer | Slot + recipe | Entity details, mobile filters, activity timeline, nested forms. |
| DropdownMenu | Recipe | User menu, row actions, settings menu, destructive item, shortcuts. |
| EmptyState | Prop + recipe | No permission, no results, onboarding, error recovery. |
| Form | Prop + recipe | Settings, multi-step, field arrays, async validation, error summary. |
| HoverCard | Recipe | Employee preview, policy preview, accessibility fallback. |
| IconSidebar | Slot + recipe | App rail, badge counts, grouped nav, mobile bottom nav. |
| Input | Prop + recipe | Helper/error, prefix/suffix, clearable, password toggle, character count. |
| InputOTP | Recipe | Verification, resend timer, error recovery, grouped slots. |
| Label | Prop + recipe | Required/optional/description pairings, hidden labels. |
| Menubar | Recipe | Desktop app menu, editor menu, keyboard map. |
| NavigationMenu | Recipe | Mega-menu, role-specific nav, resource center, mobile fallback. |
| NotificationBadge | Prop + recipe | Overflow count, live region, nav/avatar usage. |
| PageShell | Slot + recipe | Admin shell, settings shell, data page, mobile layout. |
| Pagination | Recipe | Cursor/numbered pagination, compact mobile, table integration. |
| Popover | Slot + recipe | Inline help, quick edit, filter popover, focus behavior. |
| Progress | Prop + recipe | Status text, segmented progress, upload/task states. |
| RadioGroup | Prop + recipe | Rich option cards, disabled reasons, plan selection. |
| Resizable | Recipe | Split editor, analytics workspace, constraints, persistence. |
| RichTextEditor | Prop + recipe | Toolbar presets, read-only review, validation, sanitized output. |
| ScrollArea | Recipe | Dense side panels, command results, scroll shadows. |
| SearchField | Prop + recipe | Loading, result count, clearable behavior, filter chips. |
| SectionHeader | Slot + recipe | Metadata, actions, tabs pairing, dense sections. |
| Select | Prop + recipe | Grouped options, helper/error, disabled reasons, long labels. |
| Separator | Recipe | Semantic breaks, menu separators, toolbar separators. |
| Sheet | Slot + recipe | Settings panel, filters, unsaved changes, async save. |
| Sidebar | Slot + recipe | App nav, team switcher, role sections, collapsed tooltips. |
| Skeleton | Prop + recipe | Table/card/form/page skeleton sets, reduced motion. |
| Slider | Prop + recipe | Output label, marks, min/max/step, filter preferences. |
| StatCard | Prop + recipe | Trend, delta, meta, loading, KPI dashboards. |
| StatusBadge | Prop + recipe | Status taxonomy, SLA states, table usage. |
| Switch | Prop + recipe | Setting rows, helper/error, async toggle, disabled reasons. |
| Table | Recipe | Dense, comparison, invoice, audit log, responsive/card variants. |
| Tabs | Prop + recipe | Badges, overflow, vertical tabs, URL-driven sections. |
| Tag | Prop + recipe | Removable filters, selected tags, overflow wrapping. |
| Text | Prop + recipe | Truncation, line clamp, hierarchy, data-heavy typography. |
| Textarea | Prop + recipe | Character count, autosize recipe, helper/error, resize constraints. |
| TitleBar | Slot + recipe | Breadcrumbs/actions/meta, entity title, workflow status. |
| Toast | Slot + recipe | Promise/async toast, undo action, queue behavior. |
| Toggle | Recipe | Toolbar groups, filter chips, formatting controls. |
| Tooltip | Recipe | Icon-only labels, disabled wrappers, keyboard/focus examples. |
| TopBar | Slot + recipe | Global search, tenant switcher, notifications, profile menu. |
| TransferList | Prop + recipe | Loading/empty/disabled reason, grouped transfer, keyboard selection. |
Implementation order
- Form and data.
- Inputs and controls.
- Navigation and layout.
- Overlay and menu.
- Feedback, content, media, and structure.
- Chart and data visualization.
- MCP and AI-UI metadata.
Each batch must update examples, Storybook when visual QA matters, wiki pages, MCP recipes where useful, and changesets when public package APIs change.
Security and accessibility gates
- Do not add props that allow raw colour values or arbitrary style objects.
- Keep semantic tokens as the styling boundary.
- Preserve WCAG 2.1 AA contrast, keyboard operation, focus visibility, and screen reader labels.
- Do not expose source code from hosted MCP recipe tools.
- Do not render AI-generated component descriptors without Zod validation.
- Validate Next.js Server Component examples for serializable props.
Done criteria
A batch is complete when:
- every component has an extension classification;
- new public props have tests, docs, and Storybook coverage where useful;
- examples include basic, complex workflow, and adversarial state;
- light and dark mode are checked;
- native parity is preserved or documented;
- docs and package verification pass;
- high/critical audit findings are zero.
Full runbook: Component expandability roadmap.