@pantoia/ui 0.4.0 → 0.6.0

package/README.md

@@ -0,0 +1,46 @@
+# Pantoia UI
+
+React 디자인 시스템 패키지. 문서는 `design.pantoia.com`
+
+## 사용
+
+```
+npx @pantoia/ui init          components.json을 만든다
+npx @pantoia/ui add button    components/ui/button/에 소스를 복사한다
+npx @pantoia/ui list          컴포넌트 목록
+npx @pantoia/ui diff          복사한 소스와 배포본의 차이
+```
+
+`init`이 전역 CSS에 아래 줄을 추가한다.
+
+```css
+@import "@pantoia/ui/tailwind.css";
+```
+
+## 개발
+
+호스트에는 Docker만 있으면 된다.
+
+```
+git clone git@github.com:pantoia/pantoia-ui.git
+cd pantoia-ui
+docker compose up -d dev
+```
+
+편집기는 `.devcontainer/devcontainer.json`으로 컨테이너 안에서 연다.
+
+```
+docker compose up -d dev                        실행
+docker compose down                             종료
+docker compose exec dev npm run verify          typecheck, check, lint, test
+docker compose exec dev npm pack                tarball
+```
+
+## 구조
+
+```
+<이름>/               컴포넌트
+cli/                  CLI
+docs/decisions/       결정 기록
+.claude/rules/        일하는 규칙
+```

package/agents/pantoia-ui.md

@@ -0,0 +1,211 @@
+---
+name: pantoia-ui
+description: PANTOIA Design System(@pantoia/ui)으로 화면을 만들거나 고칠 때 쓴다. 컴포넌트 고르기, 토큰과 클래스, 커스텀 값 추가, 컴포넌트 내려받기를 다룬다
+---
+
+# @pantoia/ui
+
+React 디자인 시스템이다. Base UI 위에 스타일을 얹고 Tailwind CSS 4로 토큰을 노출한다.
+사람이 보는 문서는 https://design.pantoia.com 에 있다.
+
+## 설치
+
+```sh
+npx @pantoia/ui init
+```
+
+init은 컴포넌트를 저장할 위치와 전역 CSS 파일을 묻고 `components.json`을 만든다.
+글꼴 패키지 `pretendard`, `@fontsource/jetbrains-mono`는 설치할지 묻는다.
+전역 CSS에는 `@import "tailwindcss";` 바로 아래에 이 줄이 들어간다.
+
+```css
+@import "@pantoia/ui/tailwind.css";
+```
+
+다크 모드는 `.dark` 클래스로 켠다. `html`이나 `body`에 `.dark`를 두면 그 안의 토큰이 모두 바뀐다.
+next-themes를 쓸 때는 `attribute="class"`로 둔다.
+
+## 쓰는 법
+
+컴포넌트는 폴더 이름으로 가져온다.
+
+```tsx
+import { Button } from '@pantoia/ui/button'
+import { Field, FieldLabel, FieldHelp } from '@pantoia/ui/field'
+```
+
+쓰는 방식은 2가지다.
+
+```
+패키지로 쓴다     import해서 쓴다. 버전을 올리면 고친 내용이 따라온다
+복사해서 쓴다     npx @pantoia/ui add로 소스를 가져와 프로젝트 안에서 고친다
+```
+
+기본은 패키지로 쓰는 것이다. 동작이나 마크업을 프로젝트에 맞게 바꿔야 할 때만 복사한다.
+
+제어 속성은 Base UI 규약을 따른다. `value`와 `defaultValue`, `onValueChange`를 짝으로 쓴다.
+컴포넌트마다의 속성과 이벤트는 https://design.pantoia.com 의 각 페이지에 있다.
+
+## 디자인 규칙
+
+### 색
+
+색은 토큰으로 쓴다. 이름은 `<속성>-<역할>-<변형>-<상태>`다.
+
+```
+속성   fg 글자, bg 배경, line 선, shadow 그림자
+역할   neutral, brand, info, success, warning, danger
+변형   solid 기준색, weak 옅은 배경, subtle 더 옅게, strong 더 진하게,
+       muted 약한 글자, placeholder 값 없는 Input의 글자, contrast 그 배경 위의 글자
+상태   hover, disabled, checked, selected
+```
+
+```tsx
+<div className="bg-bg-brand-solid text-fg-brand-solid-contrast">
+```
+
+역할은 뜻으로 고른다. info는 진행 중인 일, success는 끝난 일, warning은 살펴볼 일, danger는 막힌 일이다.
+
+### Surface
+
+경계를 만드는 유틸리티가 4개다.
+
+```
+frame   배경과 선. 페이지 안의 영역
+card    배경과 그림자. 목록의 항목
+float   배경과 선과 그림자. 페이지 위에 뜨는 것
+sheet   배경만. 화면을 덮는 것
+well    bg-bg-well. 파인 면
+```
+
+### 간격, 둥글기, 글자, 그림자
+
+```
+간격     gap-tight 4, gap-stack 16, gap-block 32, gap-section 48, gap-gutter 16
+둥글기   rounded-r2부터 rounded-r24까지 10단계
+글자     text-display, text-title, text-section, text-subsection, text-prose,
+         text-value, text-label, text-caption, text-micro
+크기만   text-t10부터 text-t64까지
+그림자   shadow-s1, shadow-s2, shadow-s3
+전환     transition-state, animate-enter, animate-exit
+층       z-sticky 10, z-overlay 50, z-toast 60
+```
+
+### 쓰지 않는 것
+
+```
+임의 값          bg-[#fff], p-[13px]. 토큰을 쓰거나 토큰을 더한다
+dark: 변형자      토큰이 이미 양쪽 모드를 담는다
+Tailwind 기본 색  bg-blue-500, text-gray-700. 역할 토큰을 쓴다
+px 직접 지정      간격과 둥글기는 토큰으로 쓴다
+```
+
+## 커스텀 값 추가
+
+전역 CSS에 적는다. 값은 라이트와 다크 양쪽에 모두 적는다. `:root`에만 적으면 다크가 따라오지 않는다.
+
+```css
+/* 모드와 무관한 값 */
+@theme {
+  --radius-r18: 18px;
+  --spacing-wide: 64px;
+}
+
+/* 모드마다 다른 값 */
+:root, .light { --pds-bg-brand-solid: #2563eb; }
+.dark { --pds-bg-brand-solid: #3b82f6; }
+
+/* 새 유틸리티 */
+@utility raised { @apply bg-bg-panel shadow-s2; }
+```
+
+색 역할을 더하려면 팔레트 10단계를 양쪽 모드에 적고, 토큰 6개를 만든다.
+
+```
+--pds-bg-<역할>-solid      --pds-bg-<역할>-weak
+--pds-fg-<역할>            --pds-fg-<역할>-contrast
+--pds-line-<역할>          --pds-line-<역할>-weak
+```
+
+토큰을 덮어쓸 때 미치는 범위는 3가지다.
+
+```
+팔레트 단계   그 단계를 참조하는 토큰이 모두 바뀐다
+토큰          그 토큰을 쓰는 곳이 모두 바뀐다
+className     그 한 곳만 바뀐다
+```
+
+## 컴포넌트
+
+`variant`는 tailwind-variants로 만든 스타일 축이다. `-`는 축이 없다는 뜻이다.
+
+| 컴포넌트 | import | 하위 컴포넌트 | variant |
+|---|---|---|---|
+| Accordion | @pantoia/ui/accordion | Accordion, AccordionItem, AccordionTrigger, AccordionContent | - |
+| AlertDialog | @pantoia/ui/alert-dialog | AlertDialog, AlertDialogTrigger, AlertDialogContent, AlertDialogTitle, AlertDialogDescription, AlertDialogHeader, AlertDialogFooter, AlertDialogAction, AlertDialogCancel | - |
+| Badge | @pantoia/ui/badge | Badge | color, shape |
+| Button | @pantoia/ui/button | Button | color, emphasis, size, shape |
+| Callout | @pantoia/ui/callout | Callout | color |
+| Checkbox | @pantoia/ui/checkbox | CheckboxGroup, Checkbox | color |
+| Combobox | @pantoia/ui/combobox | Combobox, ComboboxAnchor, ComboboxInput, ComboboxTrigger, ComboboxCancel, ComboboxContent, ComboboxViewport, ComboboxCollection, ComboboxItem, ComboboxItemText, ComboboxItemDescription, ComboboxGroup, ComboboxEmpty, ComboboxSeparator | surface, size |
+| CommandPalette | @pantoia/ui/command-palette | CommandPalette | - |
+| Dialog | @pantoia/ui/dialog | Dialog, DialogTrigger, DialogClose, DialogContent, DialogTitle, DialogDescription, DialogHeader, DialogFooter | size |
+| Drawer | @pantoia/ui/drawer | Drawer, DrawerTrigger, DrawerClose, DrawerContent, DrawerHeader, DrawerTitle, DrawerDescription | side |
+| DropdownMenu | @pantoia/ui/dropdown-menu | DropdownMenu, DropdownMenuTrigger, DropdownMenuContent, DropdownMenuGroup, DropdownMenuItem, DropdownMenuCheckboxItem, DropdownMenuRadioGroup, DropdownMenuRadioItem, DropdownMenuSeparator, DropdownMenuSub, DropdownMenuSubTrigger, DropdownMenuSubContent | color |
+| Field | @pantoia/ui/field | Field, FieldLabel, FieldHelp, FieldError, FieldPending, FieldSuccess | layout |
+| Input | @pantoia/ui/input | Input | surface, size |
+| Kbd | @pantoia/ui/kbd | Kbd | - |
+| Label | @pantoia/ui/label | Label | - |
+| NumberField | @pantoia/ui/number-field | NumberField | surface, size, readonly |
+| Popover | @pantoia/ui/popover | Popover, PopoverTrigger, PopoverAnchor, PopoverClose, PopoverContent | - |
+| RadioGroup | @pantoia/ui/radio-group | RadioGroup, RadioGroupItem, RadioGroupItemLabel, RadioGroupItemDescription | color |
+| Select | @pantoia/ui/select | Select, SelectGroup, SelectItem, SelectItemText, SelectItemDescription, SelectSeparator | surface, size |
+| Switch | @pantoia/ui/switch | Switch | color |
+| Table | @pantoia/ui/table | Table, TableHeader, TableHeadCell, TableBody, TableRow, TableCell | fixed, mono |
+| Tabs | @pantoia/ui/tabs | Tabs, TabsList, TabsTrigger, TabsContent | - |
+| Textarea | @pantoia/ui/textarea | Textarea | surface, size |
+| Toast | @pantoia/ui/toast | Toast | - |
+| Toggle | @pantoia/ui/toggle | Toggle | surface |
+| Tooltip | @pantoia/ui/tooltip | TooltipProvider, Tooltip, TooltipTrigger, TooltipContent | - |
+
+컴포넌트를 고를 때 헷갈리는 짝은 이렇다.
+
+```
+Dialog와 AlertDialog     내용을 보여 주면 Dialog, 되돌릴 수 없는 일을 한 번 더 물으면 AlertDialog
+Dialog와 Drawer          화면 가운데면 Dialog, 가장자리에서 열리면 Drawer
+Select와 Combobox        목록에서 고르면 Select, 입력해서 찾으면 Combobox
+Checkbox와 Switch        여러 개를 고르면 Checkbox, 설정을 바로 켜고 끄면 Switch
+Toggle과 Switch          도구 모음에서 상태를 누르면 Toggle, 설정이면 Switch
+Badge와 Button           누를 수 없으면 Badge, 누르면 Button
+Tabs와 Accordion         한 번에 하나만 보이면 Tabs, 여러 개를 펴 두면 Accordion
+Tooltip과 Popover        짧은 설명이면 Tooltip, 안에서 조작하면 Popover
+```
+
+Field는 라벨, 도움말, 오류 메시지를 입력 컨트롤에 묶는다. Input, Textarea, NumberField, Select, Combobox와 함께 쓴다.
+
+앱에 한 번만 두는 것이 2개다.
+
+```tsx
+import { Toast, toast } from '@pantoia/ui/toast'
+import { TooltipProvider } from '@pantoia/ui/tooltip'
+
+<TooltipProvider>
+  <App />
+  <Toast />
+</TooltipProvider>
+```
+
+알림은 `toast('저장했어요.')`로 띄운다. `toast.success`, `toast.error`, `toast.warning`, `toast.info`, `toast.dismiss`도 있다.
+
+## 컴포넌트 내려받기
+
+```sh
+npx @pantoia/ui list          추가할 수 있는 컴포넌트를 확인한다
+npx @pantoia/ui add button    소스를 components.json의 위치로 복사한다
+npx @pantoia/ui diff          복사한 파일을 설치된 패키지의 파일과 비교한다
+```
+
+`add`는 함께 필요한 파일까지 복사하고 `components.json`에 버전을 적는다.
+복사한 파일을 고치면 패키지를 올려도 그 파일은 그대로다. `diff`로 달라진 곳을 확인하고 직접 반영한다.
+
+복사한 파일도 위의 디자인 규칙을 따른다. 임의 값과 `dark:` 변형자를 쓰지 않는다.

package/dist/index.js

@@ -6,6 +6,8 @@ import { argv, cwd, exit, platform, stdin, stdout } from 'node:process';
 import { createInterface } from 'node:readline/promises';
 const HERE = join(import.meta.dirname, '..');
 const CONFIG = 'components.json';
+const AGENTS = 'agents/pantoia-ui.md';
+const AGENTS_TARGET = '.claude/agents/pantoia-ui.md';
 const STYLES = '@import "@pantoia/ui/tailwind.css";';
 const TAILWIND = /^@import\s+["']tailwindcss["'][^;]*;\s*$/;
 const IMPORTED = /@import\s+["']@pantoia\/ui\//;
@@ -122,6 +124,20 @@ async function copy(item, base, force) {
     }
     return skipped;
 }
+async function copyAgents() {
+    const source = readFileSync(join(HERE, AGENTS), 'utf8');
+    const target = join(cwd(), AGENTS_TARGET);
+    if (existsSync(target) && readFileSync(target, 'utf8') === source)
+        return version();
+    if (!await confirm(`Claude Code 에이전트 파일 ${AGENTS_TARGET}을 만들까요?`, true))
+        return undefined;
+    if (existsSync(target) && !await confirm(`${AGENTS_TARGET} 파일이 이미 있어요. 덮어쓸까요?`))
+        return undefined;
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, source);
+    console.log(`${AGENTS_TARGET}을 만들었어요.`);
+    return version();
+}
 function detect() {
     return LAYOUTS.find(layout => existsSync(join(cwd(), layout.css))) ?? LAYOUTS[0];
 }
@@ -212,7 +228,8 @@ async function commandInit(args) {
     const { head, tail } = additions(text, fonts);
     const needed = head.length > 0 || tail.length > 0;
     const added = needed && await importStyles(css, head, tail);
-    writeConfig({ path, css, components: {} });
+    const agents = await copyAgents();
+    writeConfig({ path, css, agents, components: {} });
     if (stdin.isTTY)
         console.log('');
     console.log(`${CONFIG}을 만들었어요. 컴포넌트는 ${path}에 저장돼요.`);
@@ -313,23 +330,28 @@ async function commandDiff(args) {
     const names = args.filter(arg => !arg.startsWith('--'));
     const wanted = names.length > 0 ? names : Object.keys(config.components);
     let changed = 0;
+    const show = (shown, mine, theirs) => {
+        if (mine === theirs)
+            return;
+        if (changed === 0)
+            console.log('- 줄은 내 파일, + 줄은 설치된 패키지의 파일이에요.');
+        changed++;
+        console.log(`\n${shown}`);
+        for (const line of difference(mine.split('\n'), theirs.split('\n')))
+            console.log(line);
+    };
     for (const item of wanted.map(find)) {
         for (const file of item.files ?? []) {
-            const target = join(cwd(), config.path, file.target ?? file.path);
+            const shown = join(config.path, file.target ?? file.path);
+            const target = join(cwd(), shown);
             if (!existsSync(target))
                 continue;
-            const mine = readFileSync(target, 'utf8');
-            const theirs = readFileSync(join(HERE, file.path), 'utf8');
-            if (mine === theirs)
-                continue;
-            if (changed === 0)
-                console.log('- 줄은 내 파일, + 줄은 설치된 패키지의 파일이에요.');
-            changed++;
-            console.log(`\n${join(config.path, file.target ?? file.path)}`);
-            for (const line of difference(mine.split('\n'), theirs.split('\n')))
-                console.log(line);
+            show(shown, readFileSync(target, 'utf8'), readFileSync(join(HERE, file.path), 'utf8'));
         }
     }
+    const agents = join(cwd(), AGENTS_TARGET);
+    if (names.length === 0 && config.agents && existsSync(agents))
+        show(AGENTS_TARGET, readFileSync(agents, 'utf8'), readFileSync(join(HERE, AGENTS), 'utf8'));
     if (changed === 0)
         console.log('달라진 파일이 없어요.');
 }

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@pantoia/ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Pantoia Design System",
   "homepage": "https://design.pantoia.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/pantoia/pantoia-design.git",
-    "directory": "packages/registry"
+    "url": "git+https://github.com/pantoia/pantoia-ui.git"
   },
   "license": "MIT",
   "type": "module",
@@ -14,6 +13,7 @@
     "pantoia-ui": "./dist/index.js"
   },
   "files": [
+    "agents/pantoia-ui.md",
     "*/index.tsx",
     "*/index.module.css",
     "dist",
@@ -44,7 +44,13 @@
   },
   "scripts": {
     "prepack": "tsc cli/index.ts --ignoreConfig --outDir dist --target es2022 --module esnext --moduleResolution bundler --skipLibCheck --types node",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.node.json",
+    "check": "tsx scripts/check.ts",
+    "lint": "oxlint --deny-warnings",
+    "test": "vitest run",
+    "verify": "npm run typecheck && npm run check && npm run lint && npm run test",
+    "dev:up": "docker compose up -d dev",
+    "dev:down": "docker compose down"
   },
   "dependencies": {
     "@base-ui/react": "^1.8.0",
@@ -56,12 +62,19 @@
     "tailwindcss": "^4.0.0"
   },
   "devDependencies": {
-    "@pantoia/typescript-config": "*",
+    "@testing-library/dom": "^10.4.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.6",
     "@types/node": "26.4.0",
     "@types/react": "19.2.18",
     "@types/react-dom": "19.2.5",
+    "happy-dom": "^20.12.0",
+    "oxlint": "1.81.0",
     "react": "19.2.8",
     "react-dom": "19.2.8",
-    "typescript": "7.0.2"
+    "tailwindcss": "4.3.3",
+    "tsx": "4.23.12",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.11"
   }
 }