External Developer Guide

Use this guide when building an app with the MiHCM Design System from outside the core repo.

What You Get

Prerequisites

• Node.js 22 or newer.
• pnpm 10 or newer.
• No package registry token is required for MiHCM packages.

Install Access

Read the registry access guide first. The short version: install from npm directly.

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

Package Install

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

Optional packages:

pnpm add @mihcm/ai-ui
pnpm add -D @mihcm/cli

Fast Setup With CLI

pnpm dlx @mihcm/cli init --target next
pnpm dlx @mihcm/cli doctor

init writes safe starter files when they do not already exist. doctor checks for common setup failures: package registry overrides, CSS import, TypeScript config, and Tailwind/PostCSS setup.

Next.js App Router

pnpm add next react react-dom
pnpm add -D typescript @types/react @types/node tailwindcss @tailwindcss/postcss
pnpm add @mihcm/ui @mihcm/theme @mihcm/tokens @mihcm/icons

/* app/globals.css */
@import "@mihcm/theme/globals.css";

// app/page.tsx
import { Button } from '@mihcm/ui/Button';
import { Text } from '@mihcm/ui/Text';
 
export default function Page() {
  return (
    <main className="min-h-screen bg-background p-8 text-foreground">
      <Text size="3xl" weight="bold">MiHCM app</Text>
      <Button className="mt-4">Continue</Button>
    </main>
  );
}

Vite React

pnpm add react react-dom
pnpm add -D vite @vitejs/plugin-react typescript tailwindcss @tailwindcss/vite
pnpm add @mihcm/ui @mihcm/theme @mihcm/tokens @mihcm/icons

/* src/index.css */
@import "@mihcm/theme/globals.css";

Expo

Expo support uses universal primitives where native variants exist. Some web-only components are documented as web-only.

pnpm add expo react react-native
pnpm add nativewind react-native-reanimated react-native-safe-area-context
pnpm add @mihcm/ui @mihcm/theme @mihcm/tokens @mihcm/icons

NativeWind v5 is still pre-release. Follow ADR-013 before assuming Tailwind 4 parity on native.

Agent tooling

Agent setup lives in Agent tooling. Use that page for hosted MCP registration, .skill downloads, Claude Code, Codex, Cursor, VS Code setup, verification steps, and security rules.

For external projects, install the public npm packages first. Then ask the agent to verify setup with mihcm_get_agent_setup, mihcm_search_components, and mihcm_list_tokens before changing UI.

Import Rules

Prefer subpath imports:

import { Button } from '@mihcm/ui/Button';
import { SearchField } from '@mihcm/ui/SearchField';

Avoid broad root imports in app code unless you have measured the bundle impact:

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

Verification

Run these in every consuming app:

pnpm exec tsc --noEmit
pnpm audit --audit-level=high
pnpm dlx @mihcm/cli doctor

Visual verification:

• Button has brand-blue default background.
• Text uses MiHCM type tokens.
• Dark mode does not produce dark text on dark surfaces.
• Focus rings are visible.

Common Failures

Support Boundary

Supported:

• package install and usage;
• documented component APIs;
• MCP metadata lookups;
• AI-UI descriptor validation;
• starter apps and CLI setup.

Not supported:

• arbitrary internal source access through hosted MCP;
• mutation/deploy/publish actions from remote MCP;
• unvalidated model-rendered UI;
• package publish tokens inside app source.