---
name: mihcm-design-system
description: >
  Use this skill when building, reviewing, or refactoring frontend work that must
  use the MiHCM Design System packages, hosted MCP tools, semantic Tailwind
  token classes, and Zod-validated AI-UI descriptors. Trigger for MiHCM UI,
  component selection, token policy, MCP validation, or MiHCM-only implementation
  rules in React, Next.js, Vite, or Expo projects.
metadata:
  short-description: Use MiHCM components, tokens, MCP, and AI-UI safely
---

# MiHCM Design System Skill

## Use When

- Building product UI with `@mihcm/ui`, `@mihcm/theme`, `@mihcm/tokens`, or `@mihcm/icons`.
- Reviewing JSX/TSX for MiHCM-only component and token compliance.
- Validating AI-generated UI descriptors before render.
- Choosing between existing primitives, compositions, patterns, and new component work.

## Required Context

- Hosted MCP endpoint: `https://designsystem.mihcm.com/mcp`
- Docs: `/agent-tooling`, `/components`, `/tokens`, `/ai-ui`, `/developing/mihcm-only-nextjs`
- Downloads: `/downloads/skills/mihcm-skill-pack.json`

Register MCP before implementation:

```bash
claude mcp add --transport http mihcm https://designsystem.mihcm.com/mcp
```

Other clients can use the same HTTP endpoint. If bearer auth is enabled, store the token in the client secret store or an environment variable. Never commit secrets.

## Workflow

1. Search before inventing:
   - call `mihcm_search_components`;
   - call `mihcm_search_patterns` for page or workflow-level UI;
   - compose existing primitives before proposing a new primitive.
2. Use the package surface:
   - import primitives from `@mihcm/ui/<Component>`;
   - import icons from `@mihcm/icons`;
   - use subpath imports for tree-shaking.
3. Use the approved library-backed primitives:
   - forms use TanStack Form through `@mihcm/ui/Form`; do not introduce React Hook Form or `@hookform/resolvers`;
   - tables use `DataTable` with TanStack Table and optional TanStack Virtual props for large client-side row sets;
   - date, date-time, time-only, and date-range UI uses `Calendar` / `DatePicker`, both backed by `@daypicker/react` v10; do not add `react-datepicker` or a second date picker package;
   - command/search menus use `Command` / `Combobox` / `Select` before adding custom listbox logic;
   - charts and compact analytics use `Chart`, `SparkChart`, `BarList`, `CategoryBar`, `ProgressCircle`, and `Tracker` before inventing a new visualization;
   - drag-and-drop uses `SortableList` or `Dropzone`; rich text uses `RichTextEditor`.
4. Use semantic Tailwind and MiHCM token classes:
   - allowed examples: `bg-background`, `text-foreground`, `border-border`, `ring-ring`, `bg-primary`, `text-muted-foreground`;
   - apply the 60/30/10 colour hierarchy: `bg-ratio-60` / `bg-dominant` for dominant neutral surfaces, `bg-ratio-30` / `bg-supporting` / `bg-primary` for supporting brand-blue structure and primary actions, and `bg-ratio-10` / `bg-emphasis` / `bg-accent` only for restrained orange emphasis;
   - standard Tailwind utilities are allowed for layout, spacing, responsive behavior, typography, and state selectors.
5. Block hardcoded visual values:
   - no raw hex/rgb/hsl colours;
   - no arbitrary bracket utilities for visual values;
   - no inline style objects for design values;
   - no CSS modules, styled-components, local shadows, or local primitive forks.
6. Keep server/client boundaries explicit:
   - Server Components may render static MiHCM trees with serializable props;
   - event handlers, hooks, charts, tables, portals, and async UI state need a Client Component wrapper;
   - call `mihcm_check_client_server_boundary` for uncertain snippets.
7. Validate AI-UI descriptors:
   - call `mihcm_validate_descriptor`;
   - render only through `@mihcm/ai-ui`;
   - never allow model-supplied import paths or raw HTML.
8. Review semantics and accessibility:
   - call `mihcm_review_semantics_accessibility` on representative JSX/TSX;
   - fix every error before final output;
   - headings must be real `h1`..`h6` elements or `Text as="h1"`..`Text as="h6"`;
   - paragraphs must use `p` or `Text as="p"`;
   - navigation must use `Link`; side effects must use `Button`;
   - form fields must have visible labels or accessible names plus helper/error linkage;
   - images need `alt`; icon-only controls need `aria-label` / `accessibilityLabel`;
   - keyboard focus, dark-mode contrast, reduced motion, and 44px touch targets are required.
9. Review final JSX:
   - call `mihcm_review_frontend_snippet`;
   - fix blocked imports, hardcoded values, local primitive forks, and boundary errors.
10. Preserve semantic HTML:
   - headings use `Text as="h1"`..`Text as="h6"` or literal `h1`..`h6`;
   - paragraphs use `Text as="p"` or literal `p`;
   - navigation uses `Link`, not a button;
   - side effects use `Button`, defaulting to `type="button"` unless submit/reset is intentional;
   - form fields use semantic inputs/labels with visible labels or accessible names and `aria-describedby` for helper/error text.

## Security Boundary

The hosted MCP is read-only and source-disabled. Do not ask it for private source, mutation actions, package publishing, deploys, GitHub writes, shell execution, or arbitrary file reads.

Consumer projects that need enforcement must run `mihcm-design-system-check` in pre-commit or CI. MCP guidance is advisory unless wired into checks.

## Verification

Before final output:

- MCP component or pattern lookup was used when selecting UI.
- The selected implementation uses the approved underlying library path when one exists: TanStack Form, TanStack Table/Virtual, DayPicker v10, cmdk, d3/Recharts, dnd-kit, Motion, or react-dropzone.
- `mihcm_review_semantics_accessibility` passed for representative JSX/TSX.
- Representative JSX passed `mihcm_review_frontend_snippet`.
- AI-UI descriptors passed Zod validation when present.
- Local project typecheck/build/test ran where available.
- No secrets, prompts, tokens, or private repo paths were added to skill files or config.

## Output

When proposing or delivering UI, include:

- MiHCM components used;
- token classes used;
- MCP checks performed;
- accessibility and client/server caveats;
- validation commands or checks that passed.