---
name: mihcm-frontend-build
description: >
  Use this skill when creating or wiring a Next.js, Vite React, or Expo project
  that consumes MiHCM Design System packages, hosted MCP, theme CSS, Tailwind
  token classes, icons, and optional AI-UI rendering. Trigger for new consumer
  apps, migration to MiHCM-only UI, registry setup, or project bootstrap.
metadata:
  short-description: Set up MiHCM in Next.js, Vite, or Expo apps
---

# MiHCM Frontend Build Skill

## Use When

- Starting a new app that must use MiHCM packages.
- Migrating an existing frontend to MiHCM-only components and tokens.
- Setting up registry access, theme CSS, MCP, CI enforcement, or AI-UI rendering.
- Verifying a consumer app is correctly wired before feature work continues.

## Required Inputs

- Runtime: `next`, `vite`, or `expo`.
- Public npm access for `@mihcm/*` packages.
- Whether AI-UI rendering is required.
- Whether hosted MCP is reachable.
- Whether strict MiHCM-only enforcement is required in CI.

## Required Context

- `/getting-started/registry-access`
- `/getting-started/external-developers`
- `/developing`
- `/developing/mihcm-only-nextjs`
- `/agent-tooling`

## Workflow

1. Confirm package access:
   - use the registry access guide;
   - install from public npm; do not add GitHub Packages registry overrides for MiHCM packages.
2. Register hosted MCP:
   - Claude Code: `claude mcp add --transport http mihcm https://designsystem.mihcm.com/mcp`;
   - Codex: `codex mcp add mihcm --url https://designsystem.mihcm.com/mcp`;
   - Cursor and VS Code: use the documented one-click link or config download from `/agent-tooling`.
3. Install packages:
   - `@mihcm/ui`;
   - `@mihcm/theme`;
   - `@mihcm/tokens`;
   - `@mihcm/icons`;
   - `@mihcm/ai-ui` only when AI-generated descriptors will be rendered.
4. Import theme CSS once:
   - Next.js: app-level global CSS;
   - Vite: app entry CSS;
   - Expo: follow NativeWind and native theme setup documented for the package version.
5. Use MiHCM imports and token classes:
   - import from package subpaths;
   - use standard Tailwind utilities and MiHCM semantic token classes;
   - do not create local UI primitive copies.
6. Use approved implementation libraries through MiHCM components:
   - forms: TanStack Form through `@mihcm/ui/Form`; do not add React Hook Form or `@hookform/resolvers`;
   - dates: `Calendar` / `DatePicker`, backed by `@daypicker/react` v10 and date-fns utilities;
   - large tables: `DataTable` with TanStack Table and optional TanStack Virtual props;
   - command palettes: `Command`, powered by cmdk;
   - analytics: MiHCM chart primitives, including D3-backed spark and tracker patterns;
   - drag/drop and uploads: `SortableList` and `Dropzone`, backed by dnd-kit and react-dropzone;
   - animation: MiHCM motion props backed by Motion primitives, with reduced-motion support.
7. Query MCP before writing UI:
   - `mihcm_search_components`;
   - `mihcm_get_component_examples`;
   - `mihcm_list_tokens`;
   - `mihcm_search_patterns`.
8. Add enforcement when required:
   - add `mihcm-design-system-check app components src` to CI;
   - block non-MiHCM UI imports with lint rules;
   - protect the main branch.
9. Build a verification screen:
   - render `Button`, `Text`, one form field, one icon, and theme colours;
   - check light and dark mode.
10. Run mandatory semantics and accessibility review:
   - call `mihcm_review_semantics_accessibility` on the verification screen and any new UI;
   - headings must be real `h1`..`h6` or `Text as="h1"`..`Text as="h6"`;
   - paragraphs must be `p` or `Text as="p"`;
   - navigation uses `Link`; side effects use `Button`;
   - fields have visible labels or accessible names and helper/error text uses `aria-describedby`;
   - images have `alt`; icon-only actions have `aria-label` / `accessibilityLabel`;
   - keyboard focus, dark-mode contrast, reduced motion, and 44px touch targets are verified.

## Security Boundary

- Do not commit `.npmrc` tokens, MCP bearer tokens, or private registry credentials.
- Do not ask consumers for GitHub package tokens to install MiHCM packages; public npm is the default channel.
- Do not render model descriptors unless `@mihcm/ai-ui` Zod validation passes.
- Do not rely on MCP alone as an enforcement boundary.
- Do not ask hosted MCP for source files or mutation tools.
- Do not add replacement form, calendar, table, command, drag/drop, upload, chart, or motion libraries unless the MiHCM primitive is missing and maintainers approve the gap.

## Verification

- Package install succeeds.
- TypeScript succeeds.
- App build succeeds.
- Representative screen visibly uses MiHCM styling in light and dark mode.
- `mihcm_review_semantics_accessibility` passes for representative JSX.
- `mihcm_review_frontend_snippet` passes for representative JSX.
- CI has `mihcm-design-system-check` when strict enforcement is required.

## Output

Report:

- runtime and package versions;
- MCP install method;
- files changed;
- enforcement added or explicitly deferred;
- verification commands and results;
- remaining platform caveats, especially Expo/native parity.