Mandu UI

Mandu Island 아키텍처에 UI 컴포넌트 라이브러리를 통합하는 가이드입니다.

Agent Workflow Contract

This skill is a Domain addendum. It must not replace mandu-agent-workflow. Use it only after mandu.agent.plan selects UI, design, styling, component, or hydration domains.

Canonical workflow step: plan -> apply -> verify.

Preferred MCP tools:

Step	Tools
plan	mandu.agent.plan, mandu.design.get, mandu.component.list
apply	mandu.agent.apply, mandu.component.add
verify	mandu.agent.verify, mandu.design.check, mandu.lint
repair	mandu.agent.repair

Allowed file edits:

• components/ui/**/*.tsx
• Route-local island/client components named in the plan
• Styling utilities only when they are required by the selected component

Verification command:

mandu agent verify --changed --json --write

Common failures:

• Adding UI libraries before reading the existing design/component inventory
• Mixing server components and island-only UI imports
• Skipping accessibility or design checks for interactive components

Repair path:

mandu agent repair --from .mandu/agent-verify.json --json

핵심 원칙

1. Headless First: Radix UI 기반으로 동작과 스타일 분리
2. Copy-Paste: shadcn/ui 방식으로 소유권 유지
3. Accessibility: WCAG 2.1 AA 수준 준수
4. Island 호환: 클라이언트 컴포넌트로 올바르게 분리

권장 스택

Primitives:  Radix UI (headless, accessible)
Components:  shadcn/ui (copy-paste, customizable)
Icons:       Lucide React
Utilities:   clsx, tailwind-merge, cva

Setup Examples

Use these examples only after mandu.agent.plan selects UI library setup.

shadcn/ui 초기화

bunx shadcn-ui@latest init

✔ Would you like to use TypeScript? yes
✔ Which style would you like to use? Default
✔ Which color would you like to use as base? Slate
✔ Where is your global CSS file? app/globals.css
✔ Do you want to use CSS variables? yes
✔ Where is your tailwind.config located? tailwind.config.ts
✔ Configure import alias for components? @/components
✔ Configure import alias for utils? @/lib/utils

컴포넌트 추가

# 개별 컴포넌트
bunx shadcn-ui@latest add button
bunx shadcn-ui@latest add card
bunx shadcn-ui@latest add dialog

# 여러 컴포넌트
bunx shadcn-ui@latest add button card dialog input

Island에서 사용

// app/user-settings/client.tsx
"use client";

import { Button } from "@/components/ui/button";
import {
  Dialog,
  DialogContent,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog";

export function UserSettingsIsland() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Settings</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>User Settings</DialogTitle>
        </DialogHeader>
        {/* Settings form */}
      </DialogContent>
    </Dialog>
  );
}

폴더 구조

components/
├── ui/                    # shadcn/ui 컴포넌트
│   ├── button.tsx
│   ├── card.tsx
│   ├── dialog.tsx
│   └── ...
└── islands/               # 커스텀 Island 컴포넌트
    ├── user-menu.tsx
    └── ...

규칙 카테고리

Category	Description	Rules
Library	라이브러리 설정	2
Accessibility	접근성 패턴	2
Integration	Island 통합	2

→ 세부 규칙은 rules/ 폴더 참조