@t3q-ui/design-system 0.0.0-stage → 1.56.0

package/package.json

@@ -1,6 +1,214 @@
 {
   "name": "@t3q-ui/design-system",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.56.0",
+  "description": "T3Q Design System - React Components",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "patterns": [
+        "./dist/patterns/index.d.ts"
+      ]
+    }
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./patterns": {
+      "import": {
+        "types": "./dist/patterns/index.d.ts",
+        "default": "./dist/patterns/index.js"
+      },
+      "require": {
+        "types": "./dist/patterns/index.d.cts",
+        "default": "./dist/patterns/index.cjs"
+      }
+    },
+    "./styles.css": "./dist/styles.css",
+    "./fonts.css": "./dist/fonts.css"
+  },
+  "sideEffects": [
+    "*.css"
+  ],
+  "bin": {
+    "t3q-design": "cli/t3q-design.mjs"
+  },
+  "files": [
+    "dist",
+    "cli",
+    "skills",
+    "CHANGELOG.md",
+    "!cli/*.test.mjs"
+  ],
+  "scripts": {
+    "build": "tsup && node scripts/fix-dts.mjs && npm run build:css",
+    "check": "pnpm lint && pnpm typecheck && pnpm build",
+    "build:css": "cp src/styles/fonts.css dist/fonts.css && echo '@source \"./**/*.js\";' > dist/styles.css && cat src/styles/tokens.css >> dist/styles.css && cat src/styles/utilities.css >> dist/styles.css && cat src/components/agGridTable/style.css >> dist/styles.css && cat src/components/parameterTable/parameterTable.css >> dist/styles.css",
+    "build:dev": "vite build --config vite.config.dev.ts",
+    "dev": "vite --config vite.config.dev.ts",
+    "dev:watch": "tsup --watch",
+    "lint": "eslint src/",
+    "test": "vitest run --project unit",
+    "test:audit": "vitest run --project audit",
+    "test:cli": "vitest run --project cli",
+    "test:eval": "vitest run --project eval",
+    "eval:judge": "node scripts/eval/judge.mjs",
+    "test:a11y": "node scripts/audit/tds-a11y.mjs --ci --md docs/audits/tds-a11y.md --json docs/audits/tds-a11y.json",
+    "test:keyboard": "node scripts/audit/tds-keyboard.mjs --ci --md docs/audits/tds-a11y-keyboard.md",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.examples.json",
+    "prepublishOnly": "npm run build && npm run build:css",
+    "prepare": "husky && npm run build",
+    "storybook": "storybook dev -p 6006",
+    "build-storybook": "storybook build && node scripts/mcp/build-skill-reference.mjs",
+    "cz": "cz",
+    "semantic-release": "semantic-release",
+    "audit:tokens": "node scripts/audit/audit-tokens.mjs",
+    "audit:mcp": "node scripts/audit/mcp-docs-check.mjs",
+    "mcp:serve": "node scripts/mcp/serve-static.mjs",
+    "audit:storybook": "node scripts/audit/storybook-export-audit.mjs --md docs/audits/storybook-export-audit.md --json docs/audits/storybook-export-audit.json && node scripts/audit/storybook-ai-readiness.mjs --md docs/audits/storybook-ai-readiness.md --json docs/audits/storybook-ai-readiness.json",
+    "eval": "node scripts/eval/run.mjs",
+    "eval:init": "node scripts/eval/init-sandbox.mjs",
+    "eval:html": "node scripts/eval/html-coverage.mjs",
+    "eval:errors": "node scripts/eval/run.mjs errors"
+  },
+  "peerDependencies": {
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@radix-ui/react-accordion": "^1.2.11",
+    "@radix-ui/react-alert-dialog": "^1.1.15",
+    "@radix-ui/react-checkbox": "^1.1.4",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-dropdown-menu": "^2.1.6",
+    "@radix-ui/react-label": "^2.1.2",
+    "@radix-ui/react-popover": "^1.1.6",
+    "@radix-ui/react-progress": "^1.1.2",
+    "@radix-ui/react-radio-group": "^1.2.3",
+    "@radix-ui/react-select": "^2.1.6",
+    "@radix-ui/react-separator": "^1.1.2",
+    "@radix-ui/react-slider": "^1.2.3",
+    "@radix-ui/react-slot": "^1.1.2",
+    "@radix-ui/react-switch": "^1.1.3",
+    "@radix-ui/react-tabs": "^1.1.3",
+    "@radix-ui/react-toggle-group": "^1.1.0",
+    "@radix-ui/react-tooltip": "^1.1.8",
+    "ag-grid-community": "^33.2.3 || ^36.0.0",
+    "ag-grid-react": "^33.2.3 || ^36.0.0",
+    "react": "^18.0.0",
+    "react-dom": "^18.0.0",
+    "react-hook-form": "^7.0.0",
+    "sonner": "^1.7.4 || ^2",
+    "tailwindcss": "^4.0.0"
+  },
+  "dependencies": {
+    "@tanstack/react-virtual": "^3.10.0",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "cmdk": "^1.0.0",
+    "date-fns": "^3.6.0",
+    "es-toolkit": "^1.0.0",
+    "lucide-react": "^0.468.0",
+    "pretendard": "^1.3.9",
+    "react-day-picker": "^8.10.1",
+    "react-lottie": "^1.2.10",
+    "react-textarea-autosize": "^8.5.3",
+    "tailwind-merge": "^2.6.0"
+  },
+  "devDependencies": {
+    "@chromatic-com/storybook": "^5.4.0",
+    "@commitlint/cli": "^20.4.1",
+    "@commitlint/config-conventional": "^20.4.1",
+    "@dnd-kit/core": "^6.3.1",
+    "@dnd-kit/sortable": "^10.0.0",
+    "@dnd-kit/utilities": "^3.2.2",
+    "@eslint/js": "^9.39.1",
+    "@radix-ui/react-accordion": "^1.2.11",
+    "@radix-ui/react-toggle-group": "^1.1.0",
+    "@semantic-release/gitlab": "^13.3.0",
+    "@storybook/addon-a11y": "^10.6.1",
+    "@storybook/addon-docs": "^10.6.1",
+    "@storybook/addon-mcp": "10.6.1",
+    "@storybook/addon-onboarding": "^10.6.1",
+    "@storybook/addon-vitest": "^10.6.1",
+    "@storybook/mcp": "10.6.1",
+    "@storybook/nextjs-vite": "^10.6.1",
+    "@tailwindcss/postcss": "^4.1.3",
+    "@tailwindcss/vite": "^4.1.18",
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/node": "^22.15.21",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "@types/react-lottie": "^1.2.10",
+    "@typescript-eslint/eslint-plugin": "^8.48.0",
+    "@typescript-eslint/parser": "^8.48.0",
+    "@vitejs/plugin-react": "^5.1.4",
+    "@vitest/browser-playwright": "^4.0.16",
+    "@vitest/coverage-v8": "^4.0.16",
+    "ag-grid-community": "^36.2.0",
+    "ag-grid-react": "^36.2.0",
+    "commitizen": "^4.3.1",
+    "cz-conventional-changelog": "^3.3.0",
+    "eslint": "^8.57.1",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-jsx-a11y": "^6.10.2",
+    "eslint-plugin-prettier": "^5.5.4",
+    "eslint-plugin-react": "^7.37.5",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-simple-import-sort": "^12.1.1",
+    "eslint-plugin-storybook": "^10.6.1",
+    "globals": "^17.0.0",
+    "husky": "^9.1.7",
+    "jsdom": "^28.0.0",
+    "lint-staged": "^15.5.2",
+    "next": "^15.5.6",
+    "playwright": "^1.57.0",
+    "postcss": "^8.5.3",
+    "postcss-cli": "^11.0.0",
+    "prettier": "^3.7.3",
+    "react-hook-form": "^7.71.1",
+    "semantic-release": "^25.0.3",
+    "storybook": "^10.6.1",
+    "tailwindcss": "^4.1.3",
+    "tsup": "^8.3.5",
+    "typescript": "^5.7.3",
+    "typescript-eslint": "^8.51.0",
+    "vite": "^7.3.0",
+    "vitest": "^4.0.16"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/t3q-platform-service/t3q-ui-design-system"
+  },
+  "keywords": [
+    "design-system",
+    "react",
+    "components",
+    "tailwindcss",
+    "t3q"
+  ],
+  "license": "SEE LICENSE IN LICENSE.md",
+  "lint-staged": {
+    "src/**/*.{ts,tsx}": [
+      "eslint --fix",
+      "bash -c 'npm run typecheck'"
+    ]
+  },
+  "config": {
+    "commitizen": {
+      "path": "cz-conventional-changelog"
+    }
+  },
+  "packageManager": "pnpm@10.28.2+sha512.41872f037ad22f7348e3b1debbaf7e867cfd448f2726d9cf74c08f19507c31d2c8e7a11525b983febc2df640b5438dee6023ebb1f84ed43cc2d654d2bc326264"
+}

package/skills/tds/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: tds
+description: '@t3q-ui/design-system(TDS) 로 화면이나 UI 를 만들거나 고칠 때 쓴다. 화면 유형 분류 → Pattern 선택 → Storybook MCP 조회 → 조립 → 검증 순서.'
+license: Proprietary. See LICENSE.md in the @t3q-ui/design-system package
+---
+
+# TDS 로 화면 만들기
+
+규칙 9개는 `AGENTS.md` 의 TDS 블록에 있다(항상 적용). 이 Skill 은 그 규칙을 지키며 **새 화면을 만드는 순서**다.
+
+## 절차
+
+1. **화면 유형을 정한다.** 요청을 List / Detail / Form / Dashboard 중 하나로 분류하고 아래 표로 Pattern 을 고른다.
+2. **Pattern 부터 시작한다.** `@t3q-ui/design-system/patterns` 에서 import 한다. 헤더·본문·상태 표시는 Pattern 이 가진다. 맞는 Pattern 이 없을 때만 PageHeader + Component 로 조립한다.
+3. **조회한다.** MCP `docs-list` 로 ID 를 찾고, `docs-show <id>` 로 props·variant·"언제 쓰나" 를 읽고, 필요하면 `docs-show-story` 로 예시 코드를 본다. MCP 를 부르지 않거나 없으면 이 Skill 의 [reference/components.md](reference/components.md)(같은 내용 — ID·언제 쓰나·props·예시 코드, 패턴이 먼저)를 읽고, 그것도 없으면 `node_modules/@t3q-ui/design-system/dist/index.d.ts`·`dist/patterns/index.d.ts` 를 읽는다. 타입 선언에는 예시 코드가 없다(2026-10-27 홀드아웃 13: d.ts 만 읽은 run 이 MCP 를 부른 run 보다 Pattern·props 를 덜 썼다).
+4. **조립한다.** 데이터 조회·상태 관리는 앱이, 배치·상태 표시는 Pattern 이 맡는다. 빈 상태(`empty`)·로딩(`loading`)·오류(`error` + `onRetry`)를 반드시 넘긴다. 페이지는 앱 레이아웃의 `<main>` 하나 안에 두되 **`<main>` 에 padding·max-width·배경을 주지 않는다**(Pattern 이 헤더 띠와 본문 여백 24px 을 가진다 — `<main className='p-8'>` 로 감싸면 헤더가 가장자리에서 떠 보인다, 2026-10-18 한 줄 판). **요청문의 요소·동작은 빠짐없이**(규칙 9) — Pattern 에 없는 것은 생략하지 말고 슬롯(`filters`·`titleRight`·`detail`·`banner`·`footer`·`note`·`actionsNote`) 안에 Component 로 만든다.
+5. **검증한다.** 타입검사·빌드를 돌린다. 직접 쓴 `<button>`/`<input>`/`<table>`, raw hex, `red-500` 같은 기본 팔레트, `bg-[#…]` 같은 임의값이 없는지 훑는다. 마지막으로 요청문을 체크리스트로 삼아 열·필터·정렬 표시·상세 항목·버튼과 비활성 사유·확인 창·로딩/빈/오류·제출 중 상태를 하나씩 대조한다.
+
+## 예제 — 먼저 열어 본다
+
+- 목록 화면: [examples/list-page.tsx](examples/list-page.tsx) — 검색·필터(상태색 건수 뱃지 세그먼트) → 표(정렬 가능 열은 `sortable: true` 로 아이콘이 보임, 이름 아래 보조 줄은 `secondaryField`) → 행 클릭 상세 패널(`detail` 슬롯, 목록 오른쪽에 나란히, 비활성 사유는 `note`) → 삭제 확인. TDS 저장소에서 타입 검사·렌더 테스트를 통과한 코드다. 새 목록 화면은 이 구조를 복사해 시작하고, 필드·컬럼만 과제에 맞게 바꾼다.
+- 상세 화면: [examples/detail-page.tsx](examples/detail-page.tsx) — 헤더(상태·**메타 `meta` 한 곳**(`MetaGroup columns={3}` + `MetaItem` — ID·버전·소유자·수정일 등 핵심 정보, 탭 위에 항상)·행동 슬롯) → 탭(건수 뱃지) → 본문 전폭 → 삭제 확인. 메타 자리를 두 개로 나누지 않는다(2026-10-30 사용자 결정 — 별도 요약 상자 없음). 오른쪽 패널(`aside`)은 쓰지 않는다(짧은 오른쪽 패널은 첫 화면 아래가 비어 홀드아웃 9~12 연속 감점). 상세 화면에 안내 한 줄(`actionsNote`)은 두지 않는다(본문 위에 떠 보여 4라운드 연속 감점, 2026-10-18 11차) — 비활성 버튼은 비활성으로만, 상태 안내는 `banner`. 오류·없음은 `error`/`notFound` prop. 개요 탭은 요약 패널 + 최근 N행 표.
+- 생성·수정 폼: [examples/form-page.tsx](examples/form-page.tsx) — PageHeader → 섹션 4개 → 누르면 검증(`FormMessage`) → 제출 중 상태(`submitting`, 버튼 잠금·중복 제출 방지) → 취소 확인 → 성공 toast. 선택지 로딩 실패는 폼을 유지한 채 그 섹션 안에 `Alert variant='danger'` 한 줄 + `AlertActions` 다시 시도.
+- 대시보드: [examples/dashboard-page.tsx](examples/dashboard-page.tsx) — 요약 타일(`ratio`·`tone`) → 기간 선택 + SVG 추이 차트 → 표 → `EventList`. 오류·없음은 `error`/`empty` prop.
+- 네 예제 모두 같은 구조다: 데이터는 `fetch*` prop 으로 받고, 상태(로딩·오류·없음)는 패턴 prop 으로 넘기고, 화면 조립만 한다.
+
+## 화면 유형 → Pattern
+
+| 화면             | Pattern                                                              | 언제 쓰나                                                                                                                                                                                                     |
+| ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| 목록             | `ListPage`                                                           | 검색/필터 → 표 → 상세 진입 흐름의 리소스 목록                                                                                                                                                                 |
+| 상세             | `DetailPage`                                                         | 리소스 하나의 상세. 핵심 정보는 헤더 `meta` 한 곳(`MetaGroup columns={3}` + `MetaItem`) → 본문 전폭. `aside` 는 쓰지 않는다. 행동 버튼은 `deleteAction`·`secondaryActions`·`primaryAction` 슬롯 — 패턴이 제목 줄 오른쪽에 [더보기 ⋯][보조 ≤2][주 행동]으로 놓고 삭제는 ⋯ 메뉴 안 |
+| 입력 — 전용 URL  | `FormPage`                                                           | 스크롤이 생기는 긴 폼 — 섹션 3개 이상, 한 화면을 넘김, 또는 여러 단계. 생성·수정 화면의 기본                                                                                                                  |
+| 입력 — 목록 위에 | `FormDrawer`                                                         | 목록 맥락을 유지해야 하고 **Drawer 한 화면 안에 들어가는** 폼(섹션 1~2개). 스크롤이 생기면 FormPage                                                                                                           |
+| 입력 — 짧게      | `FormDialog`                                                         | 이름 변경·태그 추가처럼 필드 1~4개                                                                                                                                                                            |
+| 대시보드         | `DashboardLayout` + `DashboardSection`(`columns`) + `DashboardPanel` | 숫자 타일·차트로 현재 상태를 한눈에                                                                                                                                                                           |
+
+되돌릴 수 없는 작업의 확인만 받을 때는 Pattern 이 아니라 `AlertDialog` 를 쓴다.
+
+**폼을 어디에 두나** — 필드 수와 스크롤로 정한다(Carbon·Shopify·Atlassian 의 관례와 같다, 2026-10-13): 필드 1~4개 → `FormDialog`, 목록 맥락이 필요하고 Drawer 한 화면 안에 들어가면 → `FormDrawer`, 스크롤이 생기거나 섹션이 셋 이상이거나 여러 단계면 → `FormPage`. **긴 폼을 Drawer 나 Dialog 에 넣지 않는다.** 폼 안은 한 열, 라벨은 위, 섹션 제목으로 묶고(FormSection), 저장 버튼은 잠그지 않는다(`submitMode='always'`). **FormPage 에는 검토 패널(`aside`)을 항상 둔다** — 지금까지 입력한 값의 요약과 예상 비용·영향처럼 제출 전에 확인할 것을 보여 준다(예제 form-page.tsx 의 `aside`). 폼 열만 두고 오른쪽을 비우지 않는다.
+
+## 자주 틀리는 것
+
+- Pattern 본문은 이미 `<section>` landmark 다. `<main>` 으로 또 감싸지 않는다. 앱의 `<main>` 에는 `p-8`·`max-w-*`·배경을 주지 않는다 — Pattern 이 헤더 띠(화면 끝까지)와 본문 여백(24px)을 가지므로, 감싸면 헤더가 가장자리에서 32px 떠 보인다(2026-10-18 한 줄 판 run). **사이드바·상단바 같은 앱 셸을 새로 그리지 않는다** — 과제는 페이지 하나이고 Pattern 이 헤더(제목·행동)를 그린다. 셸이 꼭 필요하면 `DashboardLayout` 을 쓰고, `fixed` 사이드바로 Pattern 을 덮지 않는다(2026-10-20 17차: Codex 가 그린 사이드바가 ListPage 제목을 덮어 27점).
+- `ListPage` 의 `onResetFilters` 는 **항상** 넘기고, 필터가 없을 때는 `filtersActive={false}` 로 보이지 않게 한다(자리는 유지). 조건부로 넘기면 빈 결과 화면에서 버튼이 튀어나와 배치가 바뀐다. 버튼은 패턴이 빠른 필터 줄 오른쪽에 그린다 — 검색창 옆에 직접 만들지 않는다.
+- `ListPage` 에 `tableTitle`("실행환경 목록" 같은 표 제목)을 넘기지 않는다 — 헤더 제목과 중복이고 빠른 필터 옆에서 빽빽해 보인다(2026-10-18 10차). 빠른 필터 줄에는 칩과 "필터 초기화"만.
+- **라운드는 한 계열** — 뱃지·태그 4px, 칩·버튼·입력 6px, 표·카드 8px. 컴포넌트 기본값이 이미 그렇다. `rounded-full`·`shape='rounded'`·`rounded='full'` 을 덧씌워 pill 을 만들지 않는다(각진 것 옆의 pill 은 세 라운드 연속 감점, 2026-10-18 10차).
+- 행을 눌러 보는 상세는 `ListPage detail={{ title, description, onClose, children, note, footer }}` 로 **목록 오른쪽에 나란히** 연다(표가 좁아지고 목록은 계속 보인다, 닫기 버튼·Esc). `activeRowId={selected?.id ?? null}` 로 열린 행을 표시하고, 상세 필드는 `MetaList` 안에 `MetaRow` 로 세로로 쌓는다. `Stack` 은 기본 방향이 가로라 MetaRow 를 감싸면 옆으로 늘어서 잘린다. 표를 좁히면 안 될 때만 `<Drawer modal={false}>` 옆 패널(덮는 형태)을 쓴다.
+- **`DetailPage asideTitle` 을 주면 패널 안에 같은 제목을 또 쓰지 않는다** — 패턴이 패널 제목을 그리므로 안쪽 `MetaList`·카드에 "작업 정보" 같은 머리글을 반복하면 제목이 연달아 두 번 보인다(2026-10-27 홀드아웃 12, 심판 2건). 패널 안은 항목(`MetaRow`)부터 시작한다.
+- **"예시 데이터로 구성된 페이지입니다" 같은 개발자 면책문·'샘플 데이터' 뱃지를 화면에 넣지 않는다** — 목 데이터임은 코드 주석에만 적는다. 심판은 이를 제품 문구의 결함으로 읽는다(2026-10-27 홀드아웃 12, 문구 차원 감점).
+- **목록의 검색 입력은 `ColumnFilter` + `ColumnFilterInput`**(스토리와 같은 조합). 필터 칩(`TableFilter*`, 채움형) 옆에 `TextField`(외곽선)를 따로 두면 두 모양이 어긋나 감점(2026-10-26 홀드아웃 11, 심판 4건). 표 셀 정렬은 `TableCell align='right'`(`className='text-right'` 도 같은 효과), 숫자 열은 `type: 'number'`(cellClass 를 더해도 정렬이 유지된다), 금액 아래 사용량 같은 두 줄 셀은 `TwoLineCellRenderer`(직접 flex 로 두 줄을 그리면 위·아래로 벌어진다).
+- 정렬할 수 있는 열은 `sortable: true` 를 **명시**한다 → 정렬 전에도 아이콘이 보이고, 누르면 방향이 바뀐다. 요청문에 "정렬 가능" 이 있으면 반드시.
+- **검토 패널(`aside`)이 있는 폼의 취소·제출 버튼은 패널 바닥** — FormPage 가 그린다(폼 끝에 따로 두지 않는다). 긴 폼 옆에서 패널이 짧게 끝나고 제출이 멀어 두 심판 모두 감점했다(2026-10-20 16차). 요약 패널에는 입력값 요약과 예상 비용·시간만.
+- **표의 진행률 열은 고정 폭 막대 + % 글자 한 줄** — `<Progress value={p} className='w-[120px]' aria-label={`GPU 사용률 ${p}%`} />` 오른쪽에 `tabular-nums` 로 `{p}%`. **막대마다 `aria-label` 로 '무엇 몇 %' 이름을 준다** — 이름 없는 progressbar 는 행마다 axe serious(17차 파이프라인 목록 21건; DS 가 기본 이름 '46%' 를 붙이지만 뜻이 약하다). 분수(816 / 1,200)는 상세나 툴팁으로. 글자 아래 막대를 쌓으면 행마다 막대 폭이 달라져 감점(2026-10-20 홀드아웃 8 Codex 목록).
+- 제출 중 상태는 앱이 `const [submitting, setSubmitting] = useState(false)` 로 갖고 `FormPage submitting={submitting}` 에 넘긴다(`onSubmit` 안에서 try/finally). FormPage 가 버튼을 잠그고 스피너를 보이지만, 상태가 코드에 드러나야 중복 제출 방지가 확인된다.
+- 빈 결과는 패턴이 아이콘·제목·설명·"필터 초기화" 버튼 상자로 그린다. `emptyState` 에는 `{ title: '조건에 맞는 모델이 없습니다', description: '검색어나 필터를 바꿔 보세요.' }` 또는 두 문장 문자열("…없습니다. …해 보세요.")만 넘긴다. 버튼·아이콘·`<div>` 를 직접 만들어 넣지 않는다.
+- 비활성 버튼은 `disabled` 로만 둔다. DetailPage 에는 사유 안내 한 줄(`actionsNote`)을 **쓰지 않는다**(2026-10-18 11차) — 상태 자체의 안내가 필요하면 `banner`(Alert). ListPage 상세 패널의 `detail.note` 는 그대로. `disabled` 를 빼먹고 배너만 두지 않는다.
+- **`banner` 는 오류·경고에만**(실패·중단·권한·삭제 예정). "실험이 진행 중입니다" 같은 상태 안내를 큰 배너로 올리지 않는다 — 상태는 상태 `Badge` 가 보여 준다(2026-10-19 14차, 13차 상세 color·layout 감점).
+- **탭 건수(`badge`)·진행률·"최근 N행" 표의 행 수는 같은 배열에서 계산한다** — 숫자를 따로 지어 쓰면 심사자가 모순으로 본다("실행 18" 탭 vs "15/24 완료"). 시간·기간은 0 단위를 생략한다("0시간 41분" → "41분").
+- **주요 행동 버튼 자리는 패턴이 정한다 — 제목 줄 오른쪽.** ListPage `actions`·DashboardLayout `actions`·DetailPage 슬롯 모두 PageHeader 제목 줄에 놓인다(2026-10-19 14차, Polaris·GitHub Issues·Primer 관례). 필터 줄에는 검색·필터·"필터 초기화"만 둔다. **행동 줄에는 버튼만** — `Tag`·`Badge` 를 버튼 옆에 두면 버튼처럼 보인다("the 'GPU 노드' tag looks like the buttons beside it", 2026-10-21 18차); 태그·종류는 제목 옆 상태 뱃지나 메타 줄에.
+- 목록의 주 식별자 열은 ListPage 가 `onRowClick` 이 있으면 `name` 열을 자동으로 강조한다(굵게, hover 밑줄). 이름 열 field 가 `name` 이 아니면 `primaryField` 로 지정하고, 셀 렌더러로 파란 링크를 직접 만들지 않는다. 표 위 제목·건수는 `tableTitle` 과 `pagination.total` 로 보인다.
+- **상태처럼 선택지가 3~6개인 다중 선택 필터는 `ListPage quickFilter`** 로 표 왼쪽 위에 세그먼트(ToggleGroup)로 둔다 — 드롭다운을 열지 않아도 선택지가 보이고, `count` 로 항목마다 건수를 붙이고 **`countVariant` 에 표의 상태 뱃지와 같은 tone**(`STATUS[s].tone`: `success`·`secondary`·`danger`…)을 준다 — 건수는 상태색 pill 뱃지로 그려져 칩과 표가 같은 색 언어가 된다(예제의 `statusCounts`; "전체" 는 패턴이 primary, 2026-10-18 13차). 드롭다운에 숨기지 않는다. 선택지가 많거나(7개 이상) 검색이 필요한 축만 `TableFilterSingleSelect`/`TableFilterMultiSelect` 로 `filters` 에 두고, 그때는 `title`(예: '프레임워크')을 주면 "프레임워크 · 전체" 처럼 대상이 항상 보인다. placeholder 에 "전체" 만 넣지 않는다. 일반 `Select` 를 필터로 쓰면 placeholder 에 "전체 상태" 처럼 대상 이름을 넣는다. 라벨 없이 "전체" 만 보이는 필터를 만들지 않는다.
+- 표는 `AgGridTable` 로 만든다. `ag-grid-react` 를 직접 쓰지 않는다. 행 클릭과 키보드 Enter 는 같은 행 클릭 핸들러로 들어온다.
+- 주요 행동 버튼(생성·등록)은 `ListPage actions` 에 둔다 — 패턴이 제목 줄 오른쪽에 놓는다(직접 필터 슬롯이나 `titleRight` 에 넣지 않는다). `PageHeader actions` 도 제목 줄 오른쪽(탭이 있어도 같다, 2026-10-19 14차).
+- **유형·방식 선택(소스 유형·공개 범위·입력 방식처럼 선택지 2개 이상에 제목·설명이 붙는 것)은 `RadioSectionGroup` + `RadioSection`(카드형)** 으로 — dl-ui-v3 의 관례(21곳). 배치는 그룹이 개수로 정한다: 1~3개 한 줄, **4개는 2×2, 5개 이상은 세로 쌓기**(카드 안은 제목 · 설명 가로) — `className` 으로 grid 를 직접 짜지 않는다. 설명 없는 짧은 선택(예·아니오)만 `RadioGroup`, 선택지 7개 이상·검색이 필요하면 `Select`. **복수 선택에 제목·설명이 붙으면 `CheckboxSectionGroup` + `CheckboxSection`**(알림 채널), 설명 없는 짧은 옵션만 `Checkbox`. **켜기/끄기 하나의 설정(규칙 사용, 실패 시 알림, 노트북 지원)은 `SwitchSection`**(박스 + 제목·설명 + Switch, dl-ui-v3 ToggleField 관례) — 폼 제출값이어도 Checkbox 로 만들지 않는다. 예제 form-page.tsx 의 스케줄 선택(RadioSectionGroup)과 실패 알림(SwitchSection)이 본보기(`FormLabel id` + 그룹 `aria-labelledby`).
+- 버튼 묶음 사이 간격은 8px. PageHeader·Dialog·Drawer·Form 의 버튼 슬롯이 이미 그렇게 그린다.
+- **상태 표시는 `Badge` 에 아이콘 + 글자** — `<Badge variant='success'><LucideIcon iconComponentName='circle-check' />완료</Badge>`. 아이콘은 Badge 의 자식으로 바로 넣고(Badge 가 16px·글자색으로 맞춘다), 크기는 기본(`size` 를 주지 않는다 — 건수 뱃지와 같은 20px). **별도 상태 컴포넌트·래퍼를 만들지 않는다**(2026-10-30 사용자 결정 — 예전의 상태 전용 래퍼는 크기·여백이 달라 태그인지 뱃지인지 모를 부품이 됐다). 상태값 → `variant`·아이콘 매핑은 상수 한 곳에. **어휘**: 작업·노트북·파이프라인·서버처럼 돌아가는 프로세스의 '실행 중' `primary` + `play`(▶), 활성·사용 중·감시 중·허용·연결됨 같은 켜진 상태 `primary` + `circle-dot`(●) — ▶ 를 켜진 상태에 붙이면 재생 버튼처럼 읽힌다(2026-10-21 18차), 완료·준비됨 `success` + `circle-check`(✓) — 실행 중에 ✓ 를 붙이면 끝난 것으로 읽힌다(2026-10-20 17차), 학습 중·배포 중처럼 끝이 있는 진행 `info` + `loader-circle`(정적 아이콘 — 스피너는 정지 화면에서 점 뭉치로 보인다), 대기 `secondary` + `clock`, 중지·비활성 `secondary` + `circle-pause`, 실패 `danger` + `circle-x`, 경고·알림 발생 `warning` + `triangle-alert`. **한 화면에 같은 variant 의 상태 둘을 두지 않는다** — '준비됨'(`success` ✓)과 '사용 중'(`primary` ●)처럼 상태마다 색이 달라야 한다(2026-10-21 19차 "two different states look the same"). 기본은 연한 색 채움(`appearance` 를 주지 않는다 — 2026-10-18 10차). **lucide 이름은 정식 이름만**(`circle-pause`·`loader-circle`·`triangle-alert`; 옛 alias `pause-circle` 같은 것은 쓰지 않는다). 같은 화면의 상태 뱃지는 **전부 아이콘이 있게** — 섞이면 심사자가 불일치로 본다. 색은 `variant` 로 정하고 `className` 으로 덧씌우지 않는다.
+- **주요 행동 버튼에는 lucide 아이콘**을 글자 앞에 붙인다 — 생성 `plus`, 삭제 `trash-2`, 중지 `square`, 배포 `rocket`, 다시 시도 `refresh-cw`, 내보내기 `download`(`<Button variant='primaryBold'><LucideIcon iconComponentName='plus' /> 생성</Button>`). `LucideIcon` 의 기본 크기는 16px 이고 버튼 안 아이콘은 그 크기로 둔다(`size={20}`·`24` 를 주면 버튼보다 커 보인다). 아이콘 없는 글자 버튼만 늘어놓지 않는다.
+- **숫자 열(개수·크기·비율·시간)은 `type: 'number'`** — AgGridTable 이 셀과 제목을 오른쪽 정렬하고 숫자 폭을 고정한다(셀 렌더러가 있어도 적용). 폭을 안 주면 140 으로 잡는다(ag-grid 기본 200 은 숫자 열이 비어 보인다 — 2026-10-27 홀드아웃 13 layout 지적 "wide empty area"). 숫자를 왼쪽 정렬로 두지 않는다.
+- **상세 패널·오른쪽 정보 열의 필드는 `MetaRow align='start'`** — 값이 라벨 바로 옆에 붙는다. 기본(`end`)은 값을 행 오른쪽 끝에 두어 넓은 패널에서 라벨과 값 사이가 빈다.
+- **진행 막대의 색은 상태와 맞춘다** — 실패한 작업은 `Progress variant='danger'`, 경고는 `warning`, 완료는 `success`. 실패한 작업에 파란 막대를 두지 않는다.
+- **헤더 `meta` 에 쓴 값(ID·버전·소유자·수정일)은 본문 Panel 에 다시 쓰지 않는다** — 같은 값이 두 번 보여도 심사자가 중복으로 본다. 키워드·분류 태그는 `Tag variant='secondary'`(기본 각진 4px) — 상태 뱃지·칩·입력과 같은 라운드 계열. pill(`shape='rounded'`)로 그리지 않는다(2026-10-18 10차).
+- **설명 문장은 PageHeader `description` 한 곳에만.** 같은 문장을 본문 위·카드 안에 다시 쓰지 않고, 본문에 "설명" Panel 을 따로 만들지 않는다(예제 detail-page 와 같이 — 같은 문장이 두 번 보이면 심사자가 중복으로 본다). 본문의 `<p>` 안내문은 사용자가 지금 해야 할 일이 있을 때만. 본문 문단에는 `break-keep wrap-break-word` 를 붙인다(한국어가 단어 중간에서 꺾이지 않게).
+- **상세 개요 탭의 블록(정보·표·목록)은 전부 `Panel` 안에** — 표 블록도 `Panel title='최근 실행' titleRight={<Button variant='primaryLink'>전체 보기</Button>}` 안에 넣고, 제목(`h2`) + 표를 맨몸으로 두지 않는다(이웃이 카드인데 하나만 카드 밖이면 "sits outside a card unlike its neighbors", 2026-10-21 18차 상세 4/6 run). **카드 안의 표는 예제처럼 `Table`(가벼운 표)로** — `AgGridTable`(회색 머리줄·둥근 테두리 상자)은 목록 화면과 전용 탭에만 쓰고 카드 안에 넣지 않는다("bordered table header inside the jobs card while the other cards use plain rows", 2026-10-21 19차). **개요 탭은 요약 패널 + 작은 표** — `Panel '주요 정보'`(MetaList) 아래 `Panel '최근 배포'`(또는 최근 실행·최근 버전) Table **4열·5행까지**(이름·상태·핵심 지표 1·시각) + `titleRight` 에 '전체 보기' 링크(`Button variant='primaryLink'`)로 전용 탭. 열이 더 필요한 표는 전용 탭에서 — 패턴이 `aside` 없는 탭을 **전체 폭**으로 그린다(GitHub PR 식: Conversation 은 2단, Files changed 는 전체 폭). 열 5~7개 표를 2/3 열에 넣으면 이름·날짜가 줄바꿈해 두 심판 모두 감점(2026-10-19 15차). 패널 하나만 두면 오른쪽 열 아래가 비어 "large empty area" 감점(11차).
+- **상세 주 행동은 생산적 행동 하나** — `primaryAction` 은 배포·실행·저장처럼 되돌릴 수 있는 것. 중지·삭제·초기화는 `secondaryActions`(회색) 또는 ⋯ 메뉴(`deleteAction`) — primary 파랑도 빨간 채움도 주지 않는다(5차 빨간 버튼·15차 파란 "실험 중지" 감점).
+- **상태 단어는 한 표에서** — 상태값 → 라벨·tone 매핑 객체 하나를 헤더 뱃지·표·탭이 같이 쓴다("진행 중" vs "실행 중" 처럼 갈리면 감점, 15차). 진행률은 "완료 10 / 전체 12 · 실패 2" 처럼 풀어 쓴다.
+- **아이콘·글자** — 중지는 `circle-stop`(`square` 는 체크박스로 읽힘). 태그·뱃지 글자는 한국어, 영문은 고유명사만("Best run" 같은 장식 영문 감점, 15차).
+- **상세 본문 구역은 `Panel title='…'` 안에 `MetaList`** — 구역마다 상자 하나, 상자 사이 16px. `Separator`·`Card`·맨 `<h2>` 로 나누지 않는다. 옆 패널(`aside`)·목록의 상세 패널(`detail`)·폼의 검토 패널(`aside`)은 패턴이 같은 Panel 로 그리므로 안에 상자를 또 두르지 않는다. 표(`Table`·`AgGridTable`)는 자기 상자가 있으니 Panel 로 감싸지 않는다.
+- **폼 옆 검토·요약 패널은 `FormPage aside={…} asideTitle='검토'`** 로 — 패턴이 폼 열 옆에 세로선으로 구분해 sticky 로 따라오게 그린다(좁으면 폼 아래). FormPage 를 `<div className='flex'>` 로 감싸 옆에 `<aside>` 를 두지 않는다: 헤더가 화면 폭을 다 못 써 구분선이 패널에서 끊기고, 패널이 중간에서 잘린다. Card(그림자)로 만들지도 않는다. FormPage 는 헤더 내용과 본문을 같은 가운데 폭(패널 있으면 1152, 없으면 720)에 가둔다(2026-10-26 22차) — 바깥에서 `max-w`·`mx-auto` 로 또 감싸지 않는다.
+- **날짜·시각 입력은 `DatePicker`·`TimePicker` 로, 폼 칸을 채우게** — 기본 폭이 250·160px 라 두 칸 줄에서 절반이 빈다(2026-10-28 홀드아웃 14, Opus·Gemini "date/time fields leave a lot of unused space"). `DatePicker classNames={{ button: 'w-full' }}`·`TimePicker classNames={{ trigger: 'w-full' }}`(두 부품의 통로 이름이 다르다). `<input type='date'>` 를 직접 쓰지 않는다.
+- **목 데이터는 의미가 맞게, 양도 화면을 채울 만큼** — 태스크·프레임워크·이름·상태가 서로 어울리는 조합(예: `yolo-v8-detector` 는 `object-detection` + `PyTorch`), 날짜는 생성일 ≤ 수정일, 건수는 목록 길이와 일치. **목록은 20행 이상**(페이지 크기 20 이면 두 페이지 분량) — 10~12행이면 표 아래가 비어 심사자가 "빈 공간" 으로 깎는다(한 줄 판 12차 6쌍, 2026-10-18). 심사자는 데이터가 말이 되는지도 본다.
+- **표 열 폭** — 이름 열 `flex: 2, minWidth: 200, maxWidth: 480`, **글자가 들어가는 열은 모두** `flex: 1, minWidth: 120`(소유자·팀·프레임워크·설명 — 하나만 고르지 않는다. 남는 폭이 여러 열로 흩어져야 이름 열만 넓어지지 않는다; 글자 열이 하나뿐이면 2:1 로 나눠도 이름 열이 500px 라 "name column leaves substantial whitespace", 2026-10-20 17차·18차), 숫자·날짜·상태·진행률 열은 `width` 로 — **숫자 열은 `type: 'number'` 만 주고 `flex` 를 주지 않는다**(폭 없으면 140). DS `Table` 의 숫자 열은 `TableHead align='right'` 로 — 폭 140 으로 고정돼 글자 열이 남는 폭을 가진다(표가 `table-fixed` 라 머리글의 `align` 이 열 폭을 정한다). **DS `Table` 의 상태 열은 `TableHead className='w-32'`, 날짜·시각 열은 `className='w-44'` 로 폭을 준다** — 폭 없는 열은 남는 폭을 똑같이 나눠 가져 뱃지 하나뿐인 상태 열이 400px 가 된다(2026-10-30 홀드아웃 17 "large empty gap between the status and GPU columns"). 남는 폭은 이름·글자 열이 나눈다. 글자 열이 하나도 없으면 `maxWidth` 를 뺀다(표 오른쪽이 빈다 — 상한 없는 flex 열이 없으면 AgGridTable 이 flex 열의 `maxWidth` 를 떼어 표를 채운다, 2026-10-28 홀드아웃 14 "row dividers stop around 1330px")(제목 글자가 들어가는 최소 폭은 AgGridTable 이 보정하고 넘치는 셀 글자는 말줄임표로 끝난다). 열은 6~7개 이내로 — **보조 정보(id·이미지·경로·설명)는 열을 늘리지 말고 `ListPage secondaryField='image'` 로 이름 아래 12px 줄에**(dl-ui-v3 목록의 이름 / 설명 셀; 패턴이 행을 56 으로 그린다). 셀마다 `cellStyle`·`width: 110` 같은 좁은 폭을 손으로 맞추지 않는다(2026-10-18 13차). **주 식별자가 짧은 ID·코드(요청 ID·커밋 해시·키)면 이름 열 공식(`flex: 2`) 대신 `width: 200` 으로 고정**하고, 남는 폭은 엔드포인트·모델·설명 같은 글자 열(`flex: 1`)이 나눈다 — ID 열이 남는 폭을 다 받으면 "request ID column is too wide"(2026-10-28 홀드아웃 14, 목록 3/3).
+- **도움말 문구(`FormDescription`)는 규칙·전제·추천값** — "실행 경로에 쓰여 만든 뒤 바꿀 수 없습니다. 영문 소문자·숫자·하이픈 3~40자", "1~32 코어. 전처리는 2~4, 학습은 8 이상을 권합니다". placeholder 와 같은 말("1~64" / "1~64")을 되풀이하지 않고, placeholder 는 "예: 4" 같은 보기 하나. **도움말·선택지 설명은 문장 끝 마침표 없이 통일**한다(두 문장을 이을 때만 가운데 마침표 — "1~32 코어. 전처리는 2~4") — 일부만 마침표가 붙으면 심사자가 copy 불일치로 본다(2026-10-18 13차 폼). 검토·요약 패널의 **빈 값은 "—" 하나**(단위는 값이 있을 때만 — "CPU —코어 · 메모리 —GB" 처럼 이어 붙이지 않고 항목마다 한 행). 예제 form-page.tsx 의 리소스 섹션·검토 패널이 본보기(2026-10-18 13차, 기준선 copy 12쌍 벤치마킹).
+- **글자 수("0 / 500자") 같은 보조 표시는 `FormDescription icon={false}`** — `FormDescription` 은 앞에 정보 아이콘을 그리므로 안내 문장에만 쓴다(2026-10-28 홀드아웃 15, Opus·Gemini "info icon next to a simple character counter").
+- **표 안 진행률 열은 `type: 'number'` 를 주지 않는다** — 오른쪽 정렬이 되면 % 글자 폭에 따라 막대 시작점이 흔들린다. 셀 안에서 `Progress` 는 고정 폭(`w-24`), % 글자도 고정 폭(`w-10 text-right tabular-nums`)으로 나란히 두고, 정지·대기 행도 빈 막대(`value={0}`)를 그린다(2026-10-28 홀드아웃 15, "progress bars have uneven lengths and starting points").
+- **오류·없음 화면은 패턴 prop 으로** — DetailPage `error`/`notFound`, DashboardLayout `error`/`empty`, ListPage `error`/`emptyState`. 패턴이 그림(빈 상태는 `EmptyBoxIllustration` 상자 일러스트, 오류는 경고 아이콘)·제목·설명·"다시 시도" 상자로 그린다. 빨간 `Alert` 줄이나 `<div>` 로 본문을 대체하지 않는다. 패턴 밖(폼의 선택지 목록 등)에서는 `@t3q-ui/design-system/patterns` 의 `ErrorState`·`EmptyState` 를 쓴다.
+- 폼의 선택지 목록(실행환경 등)을 못 불러왔으면 **폼을 지우지 말고** 그 섹션 안에 `Alert variant='danger'`(아이콘 + 한 줄 제목 + 설명 + `AlertActions` 의 링크형 "다시 시도")를 둔다. `ErrorState` 상자는 화면·패널 본문을 통째로 못 불러왔을 때만. 제출 버튼은 기본으로 항상 눌리고 누르면 검증해 틀린 항목마다 `FormMessage` 를 보인다(`submitMode` 기본 `always`).
+- 숫자 입력의 단위(개·GB·코어)는 `TextField elemAfterInput='개'` 로 입력 칸 안에 붙인다. 라벨에 "(GB)" 를 넣거나 옆에 `<span>` 을 두지 않는다.
+- **간격은 세 단계** — 붙어 있는 요소 8, 한 묶음 안 16, 묶음(섹션) 사이 32(폼 섹션 사이 48, 상세 패널 사이는 패턴 기본 24). 패턴이 기본으로 그리니 `gap`·`space-y` 를 덧붙여 평평하게 만들지 않는다. 같은 16 이나 24 가 화면 전체에 반복되면 틀린 것이다(2026-10-17).
+- 상세 패널·정보 열의 값은 14px 기본, 라벨 12px — **행마다 값 크기를 바꾸지 않는다**(8차에 건수·용량 행만 20px 로 키웠더니 심판이 "패널 안 크기가 들쭉날쭉"으로 읽어 감점, 2026-10-18 되돌림).
+- 대시보드 요약 타일의 사용률은 `stats` 항목에 `ratio`(0~1 → 진행 막대)와 `tone`(기준 초과면 `'warning'`)을 준다. 최근 이벤트는 `EventList`(레벨 색 띠 + Badge + 시각).