@sudoke/kernel 0.6.2 → 0.6.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,24 +1,33 @@
1
- # 서피스 개발 가이드 — UI 패턴 규칙(관리형 화면 공통·골격·표)
1
+ # Surface development guide — UI pattern rules (admin screens · skeleton · tables)
2
2
 
3
- 관리자 CRUD·목록 화면(기능 관리, 고객 관리 등)의 페이지 골격과 표에 적용할 규칙.
4
- 도메인 특성은 없다 — 새 앱의 서피스도 이 기준 그대로 시작한다.
3
+ Rules for the page skeleton and tables of admin CRUD·list screens (function management, client
4
+ management, …). Nothing here is domain-specific — a new app's surfaces start from this same bar.
5
5
 
6
- ## 0. 계약 — 이 4줄은 예외 없음
6
+ ## 0. Contract — these 4 lines have no exceptions
7
7
 
8
- 1. **UI 컴포넌트는 반드시 `@/components/ui/*`에서 import한다.** 로우 `<button>` `<select>` `<table>`·직접 만든 모달 `<div>`를 쓰지 않는다.
9
- 2. **필요한 컴포넌트가 ui/에 없으면 직접 짜지 않는다** — `npx shadcn@latest add <이름>`으로 추가한다. (컨트롤이 아닌 커스텀 위젯(매트릭스 셀 등)은 직접 만들어도 되되, 색·타이포는 시맨틱 토큰만 — R13·R12. 로우 요소가 꼭 필요하면 그 줄에 `/* check:ui-allow: 이유 */` 표식을 남긴다.)
10
- 3. **모양·크기·간격은 shadcn 공식 문서가 기준** — 이 가이드는 수치를 정하지 않는다. 필요한 컴포넌트가 ui/에 없으면 `npx shadcn@latest add <이름>`으로 추가한다.
11
- 4. **기획자가 지정한 화면은 화면 구성서 한 장에서 시작한다**(ui-request-guide.md) — 구성서 없는 화면은 서피스 재량으로 만든다.
8
+ 1. **UI components are imported from `@/components/ui/*` only.** No raw `<button>` `<select>`
9
+ `<table>`, no hand-rolled modal `<div>`s.
10
+ 2. **A missing component is never hand-built** — add it with `npx shadcn@latest add <name>`.
11
+ (Custom non-control widgets (matrix cells etc.) may be hand-built — with semantic tokens only for
12
+ color·type — R13·R12. When a raw element is truly required, mark the line with
13
+ `/* check:ui-allow: reason */`.)
14
+ 3. **Looks·sizes·spacing follow the official shadcn docs** — this guide sets no numbers. A missing
15
+ component is added with `npx shadcn@latest add <name>`.
16
+ 4. **A screen the planner specified starts from a one-page screen spec** (the planner's form) —
17
+ screens without a spec are the surface's discretion.
12
18
 
13
- **검증**: `npm run check:ui` — 이 계약의 기계적 검사다. 커밋 전에 통과해야 한다(아래 "커밋 전 점검"과 같은 기준). 스크립트는 공유 패키지 **`@sudoke/dev-checks`**의 `check-ui.mjs`(`components/ui/` 밖의 `surface/main/src`를 검사) — 복사·npm 등록 세팅은 도메인 개발 가이드 §5-9를 따른다.
19
+ **Check**: `npm run check:ui` — the mechanical check of this contract. It must pass before you
20
+ commit (the same bar as "before you commit" below). The script lives in the shared package
21
+ **`@sudoke/dev-checks`** (`check-ui.mjs` — it scans `surface/main/src` outside `components/ui/`) —
22
+ copying·npm wiring follows domain guide §5-9.
14
23
 
15
- ## DO / DON'T — 컨트롤은 표준 컴포넌트로
24
+ ## DO / DON'T — controls are standard components
16
25
 
17
26
  ```tsx
18
- ❌ <button className="h-6 px-2 text-xs">저장</button>
19
- ✅ <Button size="sm">저장</Button>
27
+ ❌ <button className="h-6 px-2 text-xs">Save</button>
28
+ ✅ <Button size="sm">Save</Button>
20
29
 
21
- ❌ <button className="p-1 text-muted-foreground"><ChevronRight /></button> (아이콘 토글)
30
+ ❌ <button className="p-1 text-muted-foreground"><ChevronRight /></button> (an icon toggle)
22
31
  ✅ <Button variant="ghost" size="icon"><ChevronRight /></Button>
23
32
 
24
33
  ❌ <select className="border rounded px-2">…</select>
@@ -27,139 +36,187 @@
27
36
  ❌ <table className="w-full"><thead>…</thead></table>
28
37
  ✅ <Table><TableHeader><TableRow><TableHead>…</TableHead></TableRow></TableHeader>…</Table>
29
38
 
30
- ❌ <div className="fixed inset-0 z-50 bg-black/50">…직접 만든 모달…</div>
39
+ ❌ <div className="fixed inset-0 z-50 bg-black/50">…a hand-rolled modal…</div>
31
40
  ✅ <Dialog open={open} onOpenChange={setOpen}><DialogContent>…</DialogContent></Dialog>
32
41
 
33
- ❌ ui/에 없는 컴포넌트(토스트·팝오버·탭)를 div로 직접 조립
42
+ ❌ hand-assembling a missing component (toast·popover·tabs) out of divs
34
43
  ✅ npx shadcn@latest add popover → import { Popover } from '@/components/ui/popover'
35
44
  ```
36
45
 
37
- ### 스타일 DO / DON'T
46
+ ### Style DO / DON'T
38
47
 
39
48
  ```tsx
40
- ❌ <Button size="sm" className="h-6 w-14">…</Button> (임의 h-* — data-size가 이기지만 쓰지 않는다)
41
- ✅ <Button size="sm">…</Button> (크기는 shadcn size 변형만)
49
+ ❌ <Button size="sm" className="h-6 w-14">…</Button> (an arbitrary h-* — data-size wins, so don't write it)
50
+ ✅ <Button size="sm">…</Button> (sizes come from the shadcn size variants only)
42
51
 
43
- ❌ <span className="text-red-600">삭제됨</span> · className="bg-[#ff4d5e]"
44
- ✅ <span className="text-destructive">삭제됨</span> (색은 시맨틱 토큰만)
52
+ ❌ <span className="text-red-600">Deleted</span> · className="bg-[#ff4d5e]"
53
+ ✅ <span className="text-destructive">Deleted</span> (colors are semantic tokens only)
45
54
 
46
- ❌ <span className="text-13">…</span> (커스텀 폰트 토큰 — twMerge가 색으로 오인)
47
- ✅ <span className="text-sm">…</span> (shadcn 표준 토큰)
55
+ ❌ <span className="text-13">…</span> (a custom font token — twMerge mistakes it for a color)
56
+ ✅ <span className="text-sm">…</span> (standard shadcn tokens)
48
57
 
49
- ❌ <div style="margin-top: 8px"> (정적 스타일)
50
- ✅ <div className="mt-2"> (클래스로)
58
+ ❌ <div style="margin-top: 8px"> (a static style)
59
+ ✅ <div className="mt-2"> (through classes)
51
60
  ```
52
61
 
53
- ## 규칙
54
-
55
- ### R1. 생성 폼은 항상 노출하지 않는다 — 툴바 버튼 + 다이얼로그
56
- - 항상 보이는 입력 폼 카드는 본문(표)과 경쟁하고, 안 쓸 때는 공간 낭비다.
57
- - 규칙: 화면 상단 툴바에 `[+ 추가]` 버튼 → 클릭 시 다이얼로그. 필드 3개 이하의 짧은 생성은 다이얼로그가 적합하다.
58
- - 다이얼로그 필드 순서는 표 컬럼 순서와 일치(예: 코드→이름), 첫 필드에 포커스(autoFocus).
59
-
60
- ### R2. 행 편집은 인라인 대신 다이얼로그 — 단, 한 번에 끝나는 조작은 예외
61
- - 표 칸 안에서 input으로 바뀌는 인라인 편집은 행 높이가 변하고 주변 컨텐츠가 밀리며, 여러 필드가 되면 감당 안 된다.
62
- - 규칙: 필드 1개짜리라도 **다이얼로그(또는 팝오버)**로. 토글(활성/비활성)·셀렉트 선택처럼 클릭 한 번에 끝나는 것만 즉시 실행.
63
-
64
- ### R3. 행 작업은 1~2개만 노출, 나머지는 케밥(⋯) 메뉴로
65
- - 행마다 버튼 4개가 늘어서면 스캔이 어렵고 표가 버튼 목록처럼 보인다.
66
- - 규칙: 자주 쓰는 작업 최대 2개만 버튼 노출, 나머지는 행 끝 `⋯` 오버플로 메뉴. 파괴적 작업(삭제)은 메뉴 안에서 destructive 스타일.
67
-
68
- ### R4. 드문 기능은 2차 화면으로 — 점진적 공개
69
- - 거의 안 쓰는 기능이 항상 자리를 차지하면 학습성과 밀도가 나빠진다.
70
- - 규칙: 복원·병합 되돌리기 같은 저빈도 작업은 전용 2차 화면(이력 페이지)이나 아코디언으로 이동. 장부(이벤트 로그) 기반 작업은 이력 화면의 해당 이벤트 행에 버튼을 붙이는 게 가장 자연스럽다.
71
-
72
- ### R5. 다이얼로그 접근성 최소한
73
- - 규칙: Esc로 닫기, 닫기 버튼 표시, 포커스 트랩 + 닫힐 때 트리거로 포커스 복귀, 다이얼로그 안에 다이얼로그 금지. (shadcn Dialog는 기본 제공 — 직접 만들지 않는 한 지켜진다.)
74
-
75
- ### R6. 파괴적 작업은 경고 → 확인 2단계 (이미 게이트가 담당)
76
- - 게이트의 경고=거절 → force 재시도 패턴이 곧 이 규칙의 구현이다.
77
- - 규칙: UI는 확인 다이얼로그에 결과를 명시(무엇이 지워지고 무엇이 보존되는지). 되돌림 경로를 함께 안내.
78
-
79
- ### R7. 표는 shadcn 표준 — 밀도·크기 수치는 정하지 않는다
80
- - 표·셀·컨트롤의 크기와 폰트는 **shadcn 표준을 그대로** 쓴다 — 이 가이드는 픽셀 규격을 정하지 않는다.
81
- - **기존 로우 `<table>` 페이지는 그 페이지를 건드릴 때 `ui/Table`로 이전한다**(`check:ui`가 부채로 알려준다). 새 코드는 무조건 `ui/Table`.
82
-
83
- ### R8. 저정보 컬럼·배지는 없애고 인라인 단서로
84
- - 들여쓰기나 모양만으로 알 수 있는 정보를 컬럼으로 늘리면 밀도만 높아지고 본문(상태·액션)과 경쟁한다.
85
- - 규칙: 계층 깊이(L1/L2…)처럼 구조로 알 수 있는 것은 컬럼 없이 들여쓰기로. 상태(활성/비활성)도 전용 컬럼 대신 이름 톤(비활성=muted)+툴팁으로.
86
- - 긴 원본 데이터(이벤트 payload 등)는 컬럼에 한국어 한 줄 요약, 원본은 행 툴팁으로.
87
-
88
- ### R9. 비활성·과거 상태는 뷰 토글로 — 점진적 공개 (뷰 버전)
89
- - 관리 목록의 비활성 항목은 가끔만 필요하다(재활성화·확인). 상시 노출은 본문 스캔을 방해한다.
90
- - 규칙: 툴바에 `[비활성 숨기기/표시]` 토글(기본 표시). 숨길 때는 해당 항목과 **하위 전체**를 함께 감춘다(고아 방지).
91
-
92
- ### R10. 페이지 골격 — 제목 행 / 툴바 / 표 / 페이지네이션
93
- - 골격 순서: 제목 행 → 툴바 → 표 → 페이지네이션.
94
- - 제목 행은 제목·설명 한 줄만 담는다(동작 버튼은 툴바로).
95
- - 툴바: **필터는 왼쪽**, 주요 동작(`+ 등록`)은 **오른쪽**. 필터가 없으면 툴바 전체를 오른쪽 정렬.
96
- - 힌트 문구는 툴바 아래 보조 캡션(muted 톤)으로. 본문 중간 레이블은 섹션이 2개 이상일 때만 단다.
97
- - 시각 표기는 연도 포함 풀 날짜.
98
-
99
- ### R11. 간격은 구조로
100
- - 간격 수치는 정하지 않는다 — shadcn 컴포넌트 기본값과 Tailwind 유틸리티 리듬을 그대로 쓴다.
101
- - `space-y` 레이아웃에서 개별 요소에 마진을 추가하면 리듬이 무너진다 — 간격을 바꾸려면 래퍼 구조로.
102
- - 다이얼로그 폼 간격은 shadcn 공식 폼 관례를 그대로 따른다.
103
-
104
- ### R12. 크기·타이포는 shadcn 계층
105
- - 컨트롤 크기는 shadcn 표준 **size 변형**만 쓴다 — `className`의 임의 `h-*` 금지 (data-size 클래스가 일반 `h-*`를 이긴다 — tailwind-merge가 못 지움).
106
- - **한 줄에 나란히 놓이는 컨트롤은 같은 size 변형** — default끼리는 Button·Input·Select가 같은 높이로 맞는다. 섞으면 줄이 어긋난다(sm는 그 줄 전부가 sm일 때만).
107
- - 폰트는 shadcn 표준 토큰만 쓴다 — 커스텀 `text-*` 토큰은 twMerge가 글자 색으로 오인해 색 변형에서 지워진다.
108
-
109
- ### R13. 색은 shadcn 시맨틱 토큰만
110
- - 팔레트 직접 참조 금지 — 시맨틱 토큰만 쓴다.
111
-
112
- ### R14. 반복되는 값은 조용한 텍스트 — 칩은 마커에만
113
- - 대부분의 행이 같은 값인 컬럼(예: 국내 25행 중 24행 국내)은 muted 텍스트로. 전부 칩(배지)으로 감싸면 정보 없는 노이즈만 늘어난다.
114
- - 칩은 소속 관계(자회사) 같은 **구조 마커**나 눈에 띄어야 할 소수 대상에만 단다.
115
- - 특정 값(예: 해외)을 눈에 띄게 하려면 전체 칩이 아니라 그 값만 강조한다(저빈도 표시).
116
- - 셀 안에 같은 라벨 반복 금지 — 숫자·색 + 범례 한 줄로 담는다(전체 현황 매트릭스 셀 "2 · 1 · 5" 사례).
117
-
118
- ### R15. 컴포넌트 기반은 shadcn/ui — 공식 사이트가 기준
119
- - 버튼·다이얼로그·표·드롭다운 등 컨트롤은 shadcn/ui 공식 컴포넌트를 그대로 쓴다(자체 제작 금지). 모양·변형·a11y는 공식 문서가 기준.
120
- - ui 컴포넌트 목록(기준 서피스 것: badge·button·card·dialog·dropdown-menu·input·label·scroll-area·select·separator·sheet·sonner·table·textarea). **목록에 없는 컨트롤이 필요하면 `npx shadcn@latest add <이름>`으로 추가한다**(직접 조립 금지) — 새 앱은 자기가 add한 목록에 같은 규칙을 적용한다.
121
- - 테마는 shadcn create 페이지(Get Code → Theme 탭)에서 추출한 토큰 세트를 쓴다(R13 시맨틱 토큰과 연결).
122
- - 필요한 크기가 shadcn 기본 변형에 없으면 임의 `className` 말고 shadcn 관례대로 **size 변형을 추가**한다(R12).
123
-
124
- ### R16. 화면 뼈대는 공식 Blocks에서 — 직접 조립하지 않는다
125
- - 사이드바·대시보드·로그인 같은 화면 뼈대는 shadcn 공식 Blocks(sidebar·dashboard 등)에서 선택해 그대로 시작한다 — 메뉴 구조·간격·반응형 동작이 공식 예제 값으로 고정된다(컴포넌트에 R15가 있듯 레이아웃의 같은 원칙).
126
- - Blocks에 없는 구조만 최소로 직접 짠다 — 그때도 R10 골격·R11 간격·R12·R13 토큰 원칙 안에서.
127
-
128
- ### R17. 앱은 역할별 배정표를 가진다 — 화면마다 새로 정하지 않는다
129
- - 앱 시작 시 역할별 타이포·간격 배정표(화면 제목·설명·섹션 제목·본문·페이지 수직 리듬 등 — **표준 토큰만으로**)을 한 번 정해 문서화하고, 모든 화면이 그 표를 따른다.
130
- - 허용된 토큰만 쓰더라도 화면마다 제각각이 될 수 있다 — 일관성은 "같은 역할엔 같은 토큰"에서 나온다. 배정은 표준값 중 무엇을 쓸지 찍어두는 것이지 새 값을 발명하는 게 아니다.
131
-
132
- ### R18. 화면 문구는 사용자의 언어로 — 내부 참조를 노출하지 않는다
133
- - 화면에 보이는 모든 문구(제목 아래 설명·버튼·라벨·상태·빈 상태·오류·확인 문구)는 그 화면을 쓰는 사용자의 언어로 쓴다.
134
- - 금지: 요청서 행 코드(A1·B2 같은 코드), 내부 메커니즘(장부·게이트·커맨드·이벤트·투영·위임 토큰·멱등·row_hash), 개발 프로세스 어휘("화면 구성서에서 확정"·"요청서로 등록" 같은 것). 구성서·요청서의 문장은 설계 문서이지 화면 원문이 아니다 — 서피스를 쓸 때 사용자 관점으로 다시 쓴다.
135
- - 판단 기준: 그 문구가 "이 기능으로 무엇을 할 수 있는지"를 사용자에게 말하는가, "이 시스템이 어떻게 지어졌는지"를 개발자에게 말하는가 — 후자면 지우거나 바꾼다.
136
- - 예외: 사용자가 보기를 요청한 개발 로드맵 안내(예: "이 기능은 ③단계 통계 화면에서 만들어집니다")는 노출 자체가 목적이다 — 단계·기능명까지만 쓰고 내부 구조 언급은 같은 규칙을 따른다.
137
-
138
- ## 커밋 전 점검 — `npm run check:ui`와 같은 기준
62
+ ## Rules
63
+
64
+ ### R1. Creation forms are never always-visible — toolbar button + dialog
65
+ - An always-visible form card competes with the body (the table) and wastes space when unused.
66
+ - Rule: a `[+ Add]` button in the top toolbar → a dialog on click. Short creations with three fields
67
+ or fewer fit a dialog.
68
+ - The dialog's field order matches the table column order (e.g. code→name); the first field takes
69
+ focus (autoFocus).
70
+
71
+ ### R2. Row edits are dialogs, not inline — one-shot manipulations excepted
72
+ - In-place inputs inside table cells change the row height, push surrounding content, and fall apart
73
+ with multiple fields.
74
+ - Rule: even a single-field edit goes through a **dialog (or popover)**. Only one-click manipulations
75
+ (an active/inactive toggle, a select choice) execute immediately.
76
+
77
+ ### R3. Expose 1~2 row actions — the rest goes into the kebab (⋯) menu
78
+ - Four buttons per row make scanning hard and the table look like a button list.
79
+ - Rule: expose at most the two most-used actions as buttons; the rest goes into the row-end `⋯`
80
+ overflow menu. Destructive actions (delete) take the destructive style inside the menu.
81
+
82
+ ### R4. Rare features move to secondary screens — progressive disclosure
83
+ - A rarely used feature occupying permanent space hurts learnability and density.
84
+ - Rule: low-frequency actions (restore, undo-merge) move to a dedicated secondary screen (the history
85
+ page) or an accordion. Ledger (event-log) based actions fit most naturally as a button on the
86
+ corresponding event row of the history screen.
87
+
88
+ ### R5. Dialog accessibility minimum
89
+ - Rule: close on Esc, a visible close button, focus trap + focus restored to the trigger on close,
90
+ no dialog inside a dialog. (shadcn Dialog provides these by default — holding as long as you never
91
+ hand-roll one.)
92
+
93
+ ### R6. Destructive work warns → confirms, two steps (the gate already owns this)
94
+ - The gate's warning=refusal → force retry pattern IS this rule's implementation.
95
+ - Rule: the UI's confirmation dialog states the outcome explicitly (what gets erased, what is
96
+ preserved), with the recovery path shown alongside.
97
+
98
+ ### R7. Tables are shadcn standard — no density·size numbers here
99
+ - Table·cell·control sizes and fonts follow **the shadcn standard as-is** — this guide sets no pixel
100
+ specs.
101
+ - **Pages still on raw `<table>` migrate to `ui/Table` when you touch that page** (`check:ui` flags
102
+ the debt). New code is always `ui/Table`.
103
+
104
+ ### R8. Low-information columns·badges become inline cues
105
+ - Columns that repeat what indentation or shape already tells you raise density and compete with the
106
+ body (state·actions).
107
+ - Rule: things structure already shows (hierarchy depth L1/L2…) get no column — indentation only.
108
+ State (active/inactive) also drops its dedicated column in favor of the name's tone
109
+ (inactive=muted) + a tooltip.
110
+ - Long raw data (event payloads etc.) becomes a one-line summary in the app's language in the
111
+ column, with the original in a row tooltip.
112
+
113
+ ### R9. Inactive·past states go behind a view toggle — progressive disclosure (view edition)
114
+ - Inactive items in management lists are needed only occasionally (reactivation·inspection).
115
+ Permanent display disturbs scanning the body.
116
+ - Rule: a `[Hide inactive / Show]` toggle in the toolbar (visible by default). Hiding removes the
117
+ items AND their **whole subtree** (no orphans).
118
+
119
+ ### R10. Page skeleton — title row / toolbar / table / pagination
120
+ - Skeleton order: title row → toolbar → table → pagination.
121
+ - The title row holds the title·a one-line description only (action buttons go to the toolbar).
122
+ - Toolbar: **filters left**, the primary action (`+ Add`) **right**. With no filters, the whole
123
+ toolbar right-aligns.
124
+ - Hint copy goes as a muted caption under the toolbar. Mid-body labels appear only with two or more
125
+ sections.
126
+ - Time notations are full dates including the year.
127
+
128
+ ### R11. Spacing comes from structure
129
+ - No spacing numbers — use shadcn component defaults and the Tailwind utility rhythm as-is.
130
+ - Adding margins to individual elements inside a `space-y` layout breaks the rhythm — change spacing
131
+ through the wrapper structure.
132
+ - Dialog form spacing follows the official shadcn form conventions as-is.
133
+
134
+ ### R12. Sizes·typography follow the shadcn scale
135
+ - Control sizes come from the shadcn standard **size variants** only — no arbitrary `h-*` in
136
+ `className` (the data-size class beats a plain `h-*` — tailwind-merge cannot remove it).
137
+ - **Controls side by side on one line share the same size variant** — at default, Button·Input·
138
+ Select align in height. Mixing variants skews the line (sm only when the whole line is sm).
139
+ - Fonts use standard shadcn tokens only — a custom `text-*` token gets mistaken for a color by
140
+ twMerge and is dropped in color variants.
141
+
142
+ ### R13. Colors are shadcn semantic tokens only
143
+ - Never reference the palette directly — semantic tokens only.
144
+
145
+ ### R14. Repeated values are quiet text — chips are for markers only
146
+ - A column where most rows share one value (e.g. 24 of 25 rows domestic) renders as muted text.
147
+ Wrapping everything in chips only adds information-free noise.
148
+ - Chips mark **structural markers** (a subsidiary) or the few targets that must stand out.
149
+ - To make a specific value (e.g. overseas) stand out, highlight that value alone — not the whole
150
+ column of chips (low-frequency emphasis).
151
+ - No repeated identical labels inside a cell — numbers·colors + a one-line legend (the "2 · 1 · 5"
152
+ matrix cell case).
153
+
154
+ ### R15. The component base is shadcn/ui — the official site is the reference
155
+ - Controls (buttons·dialogs·tables·dropdowns…) use the official shadcn/ui components as-is (no
156
+ in-house builds). Looks·variants·a11y follow the official docs.
157
+ - The ui component list (of the reference surface): badge·button·card·dialog·dropdown-menu·input·
158
+ label·scroll-area·select·separator·sheet·sonner·table·textarea. **A control missing from the list
159
+ is added with `npx shadcn@latest add <name>`** (never hand-assembled) — a new app applies the same
160
+ rule to its own list of added components.
161
+ - The theme is the token set extracted from the shadcn create page (Get Code → Theme tab) (tied to
162
+ R13's semantic tokens).
163
+ - When a size you need is absent from the shadcn default variants, add a **size variant** the shadcn
164
+ way — not an arbitrary `className` (R12).
165
+
166
+ ### R16. Screen shells come from the official Blocks — never hand-assembled
167
+ - Screen shells (sidebar·dashboard·login) start as-is from the official shadcn Blocks (sidebar·
168
+ dashboard, …) — menu structure·spacing·responsive behavior lock to the official example values
169
+ (as R15 is for components, the same principle for layouts).
170
+ - Only a structure absent from Blocks is built by hand, minimally — still inside R10's skeleton·
171
+ R11's spacing·R12·R13's token principles.
172
+
173
+ ### R17. An app has one per-role assignment table — not per-screen decisions
174
+ - At app start, define and document once a per-role typography·spacing assignment table (screen
175
+ title·description·section title·body·page vertical rhythm, … — **standard tokens only**) that
176
+ every screen follows.
177
+ - Even allowed tokens drift when every screen decides anew — consistency comes from "same role, same
178
+ token". The assignment picks which standard value to use; it never invents new ones.
179
+
180
+ ### R18. Screen copy is in the user's language — internal references stay hidden
181
+ - Every visible string (descriptions under titles·buttons·labels·states·empty states·errors·
182
+ confirmations) is written in the language of the people using that screen.
183
+ - Forbidden: request-row codes (A1·B2), internal mechanism vocabulary (ledger·gate·command·event·
184
+ projection·delegation token·idempotency·row_hash), development-process wording ("confirmed in the
185
+ screen spec"·"registered via request"). Sentences from the spec·request forms are design documents,
186
+ not screen copy — rewrite from the user's perspective when surfacing.
187
+ - The test: does the string tell the USER what this feature does, or tell a DEVELOPER how the system
188
+ is built — if the latter, remove or rewrite it.
189
+ - Exception: a development-roadmap notice the user asked to see (e.g. "this feature arrives in the
190
+ stage-③ statistics screen") — exposure is the point; stage·feature names only, with internal
191
+ structure mentions following the same rule.
192
+
193
+ ## Before you commit — the same bar as `npm run check:ui`
139
194
 
140
195
  ```bash
141
- npm run check:ui # 아래 목록이 기계적으로 검사된다 (위반 시 실패)
196
+ npm run check:ui # the list below is checked mechanically (violations fail)
142
197
  ```
143
198
 
144
- - [ ] 로우 `<button>`·`<select>` — components/ui 밖 0건
145
- - [ ] 로우 `<table>` — 새 코드 0건(기존 페이지는 건드릴 때 ui/Table로 이전, R7)
146
- - [ ] `style="` 문자열·정적 style 객체 0건 — style은 계산값(트리 들여쓰기)만
147
- - [ ] 임의 색(`bg-[#…]` 등) 0건 — shadcn 시맨틱 토큰만
148
- - [ ] `text-13` 같은 커스텀 폰트 토큰 0건 — shadcn 표준 토큰만
149
- - [ ] 새 컨트롤은 shadcn add로 추가했는가 — ui/에 없다고 직접 조립하지 않았는가 (커스텀 위젯 예외에는 `check:ui-allow: 이유` 표식)
150
- - [ ] 페이지는 골격 스니펫 순서(제목행→툴바→표→페이지네이션)인가
151
- - [ ] 크기는 shadcn size 변형 — 임의 className(h-*) 아님
199
+ - [ ] raw `<button>`·`<select>` — zero occurrences outside components/ui
200
+ - [ ] raw `<table>` — zero in new code (existing pages migrate to ui/Table when touched, R7)
201
+ - [ ] zero `style="` strings·static style objects — computed values (tree indentation) only
202
+ - [ ] zero arbitrary colors (`bg-[#…]` etc.) — shadcn semantic tokens only
203
+ - [ ] zero custom font tokens like `text-13` — standard shadcn tokens only
204
+ - [ ] new controls added via shadcn add — nothing hand-assembled for missing-from-ui (custom-widget
205
+ exceptions carry the `check:ui-allow: reason` marker)
206
+ - [ ] pages follow the skeleton order (title row→toolbar→table→pagination)
207
+ - [ ] sizes come from shadcn size variants — no arbitrary className (h-*)
152
208
 
153
- ## URL 명명 규칙
209
+ ## URL naming rules
154
210
 
155
- - **단수 = 대상을 선택해 보는 뷰** (`/function`, `/client`), **복수 = 목록·관리** (`/notes`, `/functions`, `/clients`) — 노트 뷰는 노트 목록 그 자체라 복수다.
211
+ - **Singular = a view selecting one target** (`/function`, `/client`); **plural = a list·management**
212
+ (`/notes`, `/functions`, `/clients`) — the notes view IS the list itself, hence plural.
156
213
 
157
- ## 부록 — 규칙의 근거
214
+ ## Appendix — the grounds for the rules
158
215
 
159
- - R1: [NN/g Modal & Nonmodal Dialogs](https://www.nngroup.com/articles/modal-nonmodal-dialog) (짧은 단일 작업에 모달 적합), [Atlassian Modal Dialog](https://atlassian.design/components/modal-dialog)
160
- - R2: [SaaS UX Patterns](https://www.saasui.design/blog/saas-modal-dialog-ux-patterns), [UX 사례 연구](https://rakibulism.medium.com/choosing-modals-over-inline-actions-a-ux-case-study-on-table-complexity-2552ee168b5c)
161
- - R3: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table), [Carbon Menu Buttons](https://www.carbondesignsystem.com/building-blocks/core/components/menu-buttons), [Ant Design 권장](https://github.com/ant-design/ant-design/issues/25799) (행당 노출 액션 ≤2), [NN/g Contextual Menus](https://www.nngroup.com/articles/contextual-menus-guidelines)
216
+ - R1: [NN/g Modal & Nonmodal Dialogs](https://www.nngroup.com/articles/modal-nonmodal-dialog) (modals fit short single tasks), [Atlassian Modal Dialog](https://atlassian.design/components/modal-dialog)
217
+ - R2: [SaaS UX Patterns](https://www.saasui.design/blog/saas-modal-dialog-ux-patterns), [a UX case study](https://rakibulism.medium.com/choosing-modals-over-inline-actions-a-ux-case-study-on-table-complexity-2552ee168b5c)
218
+ - R3: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table), [Carbon Menu Buttons](https://www.carbondesignsystem.com/building-blocks/core/components/menu-buttons), [Ant Design recommendation](https://github.com/ant-design/ant-design/issues/25799) (≤2 exposed actions per row), [NN/g Contextual Menus](https://www.nngroup.com/articles/contextual-menus-guidelines)
162
219
  - R4·R9: [NN/g Progressive Disclosure](https://www.nngroup.com/articles/progressive-disclosure)
163
- - R5: [WAI-ARIA Dialog Modal 패턴](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal), [A11y Collective](https://www.a11y-collective.com/blog/modal-vs-dialog)
164
- - R7: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table) (compact 밀도), [Ant Design Table](https://ant.design/components/table) (size small/middle)
220
+ - R5: [WAI-ARIA Dialog Modal pattern](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal), [A11y Collective](https://www.a11y-collective.com/blog/modal-vs-dialog)
221
+ - R7: [Carbon Data Table](https://www.carbondesignsystem.com/building-blocks/core/components/data-table) (compact density), [Ant Design Table](https://ant.design/components/table) (size small/middle)
165
222
  - R8: [NN/g How Users Read on the Web](https://www.nngroup.com/articles/how-users-read-on-the-web/)
@@ -1,92 +1,107 @@
1
- # 되돌리기(undo) 대상 선정 가이드
1
+ # Undo scope guide
2
2
 
3
- 도메인을 만들거나 고치는 에이전트가 "어떤 이벤트를 커널 공통 되돌리기로 지원할 것인가"를 정할 때 쓰는 기준이다.
4
- 커널 0.6.1 기준이며, 커널 쪽 계약은 [packages/kernel/README.md](../README.md)의 Undo 절을 따른다.
3
+ The criterion an agent creating or editing a domain uses to decide "which event types do we open to
4
+ the kernel-common undo?" Written against kernel 0.6.1; the kernel-side contract follows the Undo
5
+ section of [packages/kernel/README.md](../README.md).
5
6
 
6
- ## 원칙
7
+ ## Principle
7
8
 
8
- **실수했을 때 손으로 되돌리기 어려운 것만 지원한다.** 나머지는 `unavailable`로 두고 사유에 대안을 적는다.
9
- 전부 지원하려고 하지 않는다. 지원하는 이벤트마다 핸들러·테스트·이벤트 형식 관리가 따라오기 때문이다.
9
+ **Open only what is hard to restore by hand after a mistake.** Everything else stays `unavailable`,
10
+ with an alternative written into the reason. Do not try to support everything — every supported event
11
+ type brings its handler, its tests and its event-format management with it.
10
12
 
11
- 커널은 모든 이벤트 타입에 정책 선언을 요구한다. 이 요구는 "전부 지원하라"가 아니라
12
- "지원 여부를 타입마다 결정하라"는 뜻이다.
13
+ The kernel requires an undo policy declaration for every event type. The requirement is not "support
14
+ everything" — it is "decide, per type, whether you support it".
13
15
 
14
- ## 판단 순서
16
+ ## Decision order
15
17
 
16
- 이벤트 타입마다 위에서부터 차례로 묻고, 처음 걸리는 곳에서 결정한다.
18
+ For each event type, ask top to bottom and decide at the first hit.
17
19
 
18
- | 순서 | 질문 | 걸리면 |
20
+ | # | Question | On a hit |
19
21
  |---|---|---|
20
- | 1 | 비밀·권한·외부 효과인가? | 지원하지 않는다 |
21
- | 2 | 업무상 "상태"가 아니라 "기록"인가? | 지원하지 않는다 |
22
- | 3 | 같은 커맨드를 다시 실행하면 원래대로 돌아가는가? | 지원하지 않는다 |
23
- | 4 | 한 번의 실행이 여러 행을 바꾸거나 없애는가? | **지원 대상** |
24
- | 5 | 지원 대상인데 이벤트에 이전 상태가 없는가? | 이벤트를 먼저 고치고, 그 뒤에 지원한다 |
25
-
26
- 각 질문의 뜻은 다음과 같다.
27
-
28
- 1. **비밀·권한·외부 효과.** 비밀번호, 역할, 위임 발급·회수, 계정 삭제, 메일 발송 같은 것이다.
29
- 되돌리기가 보안 결정을 뒤집거나, 이미 밖으로 나간 것을 되돌린 척하게 된다.
30
- 2. **기록.** 결정·승인·제안처럼 "그때 그렇게 했다"는 사실 자체가 의미인 것이다.
31
- 지우지 않고 새 기록으로 덮는다.
32
- 3. **다시 실행하면 되는 것.** 이름 변경, 활성 전환, 순서 변경, 설정값 변경처럼 값 하나를 바꾸는 것이다.
33
- 미지원 사유에 "같은 커맨드로 이전 값을 넣으세요"라고 안내하면 충분하다.
34
- 4. **여러 행이 함께 바뀌는 것.** 삭제, 병합, 일괄 변경, 하위 항목까지 딸려 가는 이동이다.
35
- 손으로 되돌리려면 무엇이 어떻게 바뀌었는지 기억해야 하는 작업이다.
36
- 5. **이전 상태가 없는 이벤트.** 되돌리기의 품질은 원본 이벤트가 담은 정보가 결정한다.
37
- 정보가 부족한 채로 열면 "복원"이 아니라 "비슷하게 다시 만들기"가 된다.
38
-
39
- ## 우선순위
40
-
41
- 지원 대상이 여럿이면 이 순서로 연다.
42
-
43
- - **실수했을 때 피해가 큰 것 먼저.** 데이터가 사라지는 것, 구조가 바뀌는 것, 값이 바뀌는 것 순이다.
44
- - **에이전트가 실행할 수 있는 것 먼저.** 위임 범위에 들어가는 커맨드는 실수 가능성이 높고, 되돌리기가 안전망이 된다.
45
- - **자주 쓰는 것 먼저.** 드물게 쓰는 커맨드는 뒤로 미룬다.
46
-
47
- ## 열기 전에 갖출 것
48
-
49
- 지원으로 바꾸는 이벤트마다 아래를 모두 확인한다. 하나라도 안 되면 아직 열 때가 아니다.
50
-
51
- - 원본 이벤트에 원상복구에 필요한 값이 모두 들어 있다.
52
- - 보상 커맨드가 "가장 최근 것"이 아니라 정확한 건을 가리키는 식별자를 받는다.
53
- - 되돌리면 잃는 것(그 사이에 생긴 변경 등)을 `losses`로 말할 수 있다.
54
- - 되돌릴 수 없는 조건(부모가 사라짐, 이름 충돌, 이미 직접 복원됨)을 `blockers`로 말할 수 있다.
55
- - 한 번의 커맨드 실행이 쓰는 모든 이벤트 타입이 같은 핸들러를 가리킨다
56
- (다르면 커널이 `undo.operation_mixed_policies`로 막는다).
57
-
58
- ## 열지 않는 편이 나은 신호
59
-
60
- - **되돌리기의 되돌리기가 필요해 보인다.** 복원을 다시 되돌리는 것은 "다시 삭제"와 같다. 일반 커맨드로 충분하다.
61
- - **핸들러가 보상 커맨드보다 복잡해진다.** 계획을 세우는 코드가 실제 복원 코드보다 길면 모델이 그 도메인과 맞지 않는 것이다.
62
- - **미리보기의 `changes`가 "전부 다시 만든다" 한 줄뿐이다.** 사용자가 판단할 정보가 없으므로 재실행 안내가 맞다.
63
-
64
- ## 도메인이 할 일
65
-
66
- 지원하는 이벤트마다 다음을 한다.
67
-
68
- - **핸들러는 보상 커맨드를 정적으로 선언한다**(`compensationCommand`). 계획의 `command`는 선언과 같아야 한다.
69
- - **핸들러는 세 가지만 답한다.** 무엇이 바뀌는가(`changes`), 무엇을 잃는가(`losses`), 왜 안 되는가(`blockers`).
70
- - **`changes`의 `field`에는 필드 이름만 쓴다.** 안내 문장을 넣지 않는다. 원상복구가 아닌 부분은 `losses`로 알린다.
71
- - **화면에 보일 값이 아니라 계획이 의존하는 상태는 `dependsOn`에 토큰으로 넣는다.**
72
- 투영기나 커맨드의 계산을 핸들러에서 다시 구현하지 않는다.
73
- - **직접 복원된 건을 핸들러가 막는다.** 보상 커맨드를 직접 호출한 이력은 커널이 모른다.
74
- 커널의 보상 1회 가드는 undo 경로로 실행된 것만 안다.
75
- - **원본 읽기 규칙은 장부 조회와 판정 함수 하나를 공유한다.** 장부에서 보이는 기록이면 되돌리기 정보도 보인다.
76
- `registerUndoReadGate`로 한 번 등록한다.
77
- - **보상 커맨드를 조립에서 제거하지 않는다.** 제거하면 그 커맨드로 수행된 과거 되돌리기의 재전송이
78
- 본인에게도 거절된다.
79
-
80
- 미지원으로 두는 이벤트는 사유를 구체적으로 적는다. "지원하지 않습니다" 대신
81
- "이름은 같은 커맨드로 다시 바꾸세요"처럼 다음 행동을 알려 준다. 에이전트가 이 문장을 읽고 움직인다.
82
-
83
- ## 서피스가 할 일
84
-
85
- - **되돌릴 수 있는지를 화면이 추측하지 않는다.** 이벤트 목록을 훑어 "이미 되돌렸는지"를 계산하는 코드를 두지 않고 커널에 묻는다.
86
- - **흐름은 세 단계로 고정한다.** 상태 조회로 버튼을 정하고, 미리보기로 확인 창을 채우고, 미리보기의 `planHash`로 실행한다.
87
- - **확인 창은 하나로 만든다.** 미리보기 형식이 모든 이벤트에 공통이므로 이벤트 타입별 전용 창을 만들지 않는다.
88
- - **버튼이 보여도 미리보기에서 막힐 수 있다.** 상태 조회는 도메인 차단 조건을 계산하지 않는다.
89
- `blocked`·`unavailable`·`denied`·`already_undone`의 사유를 보여 주는 화면이 반드시 있어야 한다.
90
- - **`undo.plan_changed`를 받으면 미리보기를 다시 불러 확인을 다시 받는다.**
91
- - **손실이 있으면(`warning`) 사용자가 확인한 뒤에만 `acceptLosses: true`를 보낸다.**
92
- - **상태 조회는 한 번에 100건까지다.** 넘기면 입력 거절이 되므로 나눠서 조회한다.
22
+ | 1 | Is it a secret, a right, or an external effect? | Do not support |
23
+ | 2 | Is it a record rather than a state? | Do not support |
24
+ | 3 | Would re-running the same command restore the original? | Do not support |
25
+ | 4 | Does one execution change or remove multiple rows? | **Support candidate** |
26
+ | 5 | Support candidate, but the event carries no prior state? | Fix the event first, then support it |
27
+
28
+ What each question means:
29
+
30
+ 1. **Secrets, rights, external effects.** Passwords, roles, delegation issue·revoke, account
31
+ deletion, outgoing mail. Undoing these would flip a security decision, or pretend something
32
+ already outside came back.
33
+ 2. **Records.** Decisions, approvals, proposals — things whose meaning is the fact itself, "this
34
+ happened then". You do not erase them; you overlay new records.
35
+ 3. **Re-runnable work.** Renames, active toggles, reordering, settings changes — one-value changes.
36
+ An unsupported reason like "set the previous value with the same command" is enough.
37
+ 4. **Multi-row work.** Deletes, merges, bulk changes, moves that take descendants along. Restoring
38
+ by hand requires remembering exactly what changed — that is what undo is for.
39
+ 5. **Events without prior state.** Undo quality is decided by the information the original event
40
+ carries. Opening it with insufficient data makes the "restore" a rough remake.
41
+
42
+ ## Priority
43
+
44
+ When several candidates remain, open them in this order:
45
+
46
+ - **Largest blast radius first.** Data loss, then structure changes, then value changes.
47
+ - **Agent-runnable first.** Commands inside delegation scopes are the most mistake-prone; undo is
48
+ their safety net.
49
+ - **Frequently used first.** Rarely-run commands wait.
50
+
51
+ ## Before opening — the checklist
52
+
53
+ For every event type you switch to supported, all of these must hold. If any one fails, it is not
54
+ time yet.
55
+
56
+ - The original event carries every value the restoration needs.
57
+ - The compensation command takes an identifier that points at the exact record, not "the latest one".
58
+ - What undo loses (changes made in between, etc.) can be stated in `losses`.
59
+ - Conditions that make undo impossible (parent gone, name conflict, already restored by hand) can be
60
+ stated in `blockers`.
61
+ - Every event type one command execution writes points at the same handler (otherwise the kernel
62
+ refuses with `undo.operation_mixed_policies`).
63
+
64
+ ## Signals you should NOT open it
65
+
66
+ - **You feel a need for undo-of-undo.** Reverting a restoration is "delete it again" — an ordinary
67
+ command does that.
68
+ - **The handler outgrows the compensation.** When the planning code is longer than the actual
69
+ restore code, the model does not fit this domain.
70
+ - **The preview's `changes` is a single line of "recreate everything".** The user gets nothing to
71
+ judge — guide to a re-run instead.
72
+
73
+ ## What the domain does
74
+
75
+ For every supported event type:
76
+
77
+ - **The handler declares its compensation command statically** (`compensationCommand`). The plan's
78
+ `command` must equal the declaration.
79
+ - **The handler answers exactly three things.** What changes (`changes`), what is lost (`losses`),
80
+ why not (`blockers`).
81
+ - **`changes.field` carries field names only** — no explanation sentences. Parts that do not restore
82
+ to the original belong in `losses`.
83
+ - **State the plan depends on — not values shown on screen — goes into `dependsOn` as tokens.**
84
+ Do not re-implement the projector or the command's computation inside the handler.
85
+ - **The handler blocks records already restored by hand.** The kernel does not know about a
86
+ compensation command invoked directly; its one-compensation guard only knows the undo path.
87
+ - **Origin-read rules share one judgment function with ledger reads.** What the ledger shows is what
88
+ undo may show. Register it once with `registerUndoReadGate`.
89
+ - **Never remove a compensation command from the assembly.** Removing it refuses the redelivery of
90
+ past undos performed through it — even for the actor who ran them.
91
+
92
+ For unsupported event types, write a concrete reason. Not "not supported" but "rename back with the
93
+ same command" — the next action spelled out. An agent reads this sentence and acts on it.
94
+
95
+ ## What the surface does
96
+
97
+ - **The screen never guesses undoability.** No code scanning the event list to compute "already
98
+ undone" — ask the kernel.
99
+ - **The flow is fixed at three steps.** Status decides the button, preview fills the confirmation
100
+ dialog, and the preview's `planHash` executes.
101
+ - **One confirmation dialog for all events.** The preview shape is common to every event type —
102
+ build no per-event-type dialogs.
103
+ - **A visible button can still be refused at preview.** Status does not compute domain blockers —
104
+ there must be a screen that shows the reasons for `blocked`·`unavailable`·`denied`·`already_undone`.
105
+ - **On `undo.plan_changed`, reload the preview and take the confirmation again.**
106
+ - **With losses (`warning`), send `acceptLosses: true` only after the user confirmed them.**
107
+ - **A status query carries at most 100 seqs.** More is an input refusal — page the query.