@spectrabrain/eds 0.3.1 → 0.6.0

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.
Files changed (35) hide show
  1. package/AI.md +4 -4
  2. package/AI_CONTEXT.json +4 -4
  3. package/CHANGELOG.md +28 -0
  4. package/CONSUMER_AGENT.md +27 -26
  5. package/FRONTEND_CONVENTIONS.md +2 -2
  6. package/QUICKSTART.md +5 -5
  7. package/README.md +9 -10
  8. package/TAILWIND_V4.md +4 -6
  9. package/TOKEN_CONTEXT.md +2 -18
  10. package/consumer/align-plan.mjs +4 -10
  11. package/consumer/align.mjs +5 -3
  12. package/consumer/cli.mjs +6 -6
  13. package/consumer/css-root.mjs +1 -1
  14. package/consumer/generate-tailwind.mjs +0 -30
  15. package/consumer/init.mjs +10 -11
  16. package/consumer/managed-block.mjs +9 -3
  17. package/consumer/register-scripts.mjs +39 -37
  18. package/consumer/scan-classes.mjs +9 -19
  19. package/consumer/sync.mjs +24 -11
  20. package/consumer/update-agent-context.mjs +2 -2
  21. package/consumer-postinstall.mjs +73 -15
  22. package/dist/components/Button/README.md +2 -4
  23. package/dist/components/Button/spec.json +6208 -5
  24. package/dist/index.d.mts +6289 -5
  25. package/dist/index.d.ts +6289 -5
  26. package/dist/index.js +6284 -381
  27. package/dist/index.mjs +6285 -382
  28. package/dist/tokens.css +0 -30
  29. package/dist/tokens.d.mts +1 -1
  30. package/dist/tokens.d.ts +1 -1
  31. package/dist/tokens.js +0 -300
  32. package/dist/tokens.json +0 -360
  33. package/dist/tokens.mjs +0 -300
  34. package/llms.txt +2 -2
  35. package/package.json +3 -2
package/AI.md CHANGED
@@ -4,16 +4,16 @@
4
4
 
5
5
  ## 공개 범위
6
6
 
7
- - light theme, `AI_CONTEXT.json`의 `components`에 있는 컴포넌트(현재 `Button`), 공개 semantic color·typography·spacing·radius token과 token runtime API(`@spectrabrain/eds/tokens`)를 제공합니다.
8
- - 패키지는 Tailwind preset·plugin을 export하지 않습니다. `eds sync`는 공개 semantic token alias를 `src/styles/eds-tokens.css`에 추가합니다. 일반 Tailwind utility는 소비처 설정에 따라 함께 쓸 수 있습니다.
9
- - dark theme과 목록 밖 컴포넌트는 지원 범위 밖입니다. EDS component가 없거나 필요한 prop·variant·state·slot contract가 맞지 않으면 소비처에서 로컬 UI를 구현하고, 공개 token으로 색상·typography·spacing·radius를 지정합니다.
7
+ - light theme, `AI_CONTEXT.json`의 `components`에 있는 컴포넌트(현재 `Button`), 공개 semantic color·typography token과 token runtime API(`@spectrabrain/eds/tokens`)를 제공합니다.
8
+ - 패키지는 Tailwind preset·plugin을 export하지 않습니다. `eds sync`는 공개 semantic token alias를 `src/styles/eds-tokens.css`에 추가합니다. spacing·radius token은 제공하지 않으며, 해당 값에는 Tailwind CSS v4 기본 utility를 권장합니다(`TOKEN_CONTEXT.md`).
9
+ - dark theme과 목록 밖 컴포넌트는 지원 범위 밖입니다. EDS component가 없거나 필요한 prop·variant·state·slot contract가 맞지 않으면 소비처에서 로컬 UI를 구현하고, 색상·typography에는 공개 token을 사용합니다.
10
10
  - CSS 진입점 구성은 `CONSUMER_AGENT.md` 「font 정책」을 따릅니다.
11
11
 
12
12
  ## 사용 경계
13
13
 
14
14
  - 문서·`spec.json`·`tokens.json`에 있는 API·prop·variant·token·export 경로만 씁니다. component 여부와 사용 계약은 `AI_CONTEXT.json.components`, component README, TypeScript contract로 확인합니다. 아이콘 이름 확인이나 기계 판독 계약이 필요할 때만 `spec.json`을 읽습니다. contract가 맞지 않으면 `QUICKSTART.md`의 컴포넌트 선택 기준에 따라 소비처 로컬 UI로 분기합니다.
15
15
  - EDS 컴포넌트의 native element·accessible name·keyboard 동작은 그대로 둡니다. icon-only Button에는 비어 있지 않은 `aria-label`(또는 `aria-labelledby`)을 지정합니다.
16
- - 이름으로 지정하는 아이콘은 allowlist(`spec.json`의 `api.iconNames`)만 받고, 목록 밖 아이콘은 ReactElement 슬롯으로 전달합니다. 버전 선언과 보고 방법은 `dist/components/Button/README.md` 「Layout과 아이콘」에 있습니다.
16
+ - Button 이름 슬롯은 `ButtonIconName`이 제공하는 `lucide-react` 아이콘 이름과 alias를 받습니다. custom 아이콘은 ReactElement 슬롯을 사용합니다. 전체 계약은 `dist/components/Button/README.md` 「Layout과 아이콘」에 있습니다.
17
17
 
18
18
  ## 문서와 manifest
19
19
 
package/AI_CONTEXT.json CHANGED
@@ -16,7 +16,7 @@
16
16
  "specifier": "@spectrabrain/eds/CONSUMER_AGENT.md",
17
17
  "kind": "setup-contract",
18
18
  "required": false,
19
- "when": "First setup: the consumer AGENTS.md has no <!-- EDS:BEGIN --> block; eds doctor exits 1 or 2, eds sync exits 2, or sync recovery is unclear; EDS was upgraded; the user asks to reorganize a prototype into the EVA frontend structure (eds align)"
19
+ "when": "First setup: the consumer AGENTS.md has no <!-- EDS:BEGIN --> block; eds doctor exits 1 or 2, eds sync exits 2, or sync recovery is unclear; the EDS version marker is missing or the installed version differs from it; the user asks to reorganize a prototype into the EVA frontend structure (eds align)"
20
20
  },
21
21
  {
22
22
  "file": "AI.md",
@@ -30,7 +30,7 @@
30
30
  "specifier": "@spectrabrain/eds/TOKEN_CONTEXT.md",
31
31
  "kind": "token-selection",
32
32
  "required": false,
33
- "when": "A color, typography, spacing or radius token is written or changed outside EDS component props, including CSS variables or cssVar() without Tailwind"
33
+ "when": "Choose an EDS color or typography token, or spacing/radius utilities outside an EDS component"
34
34
  },
35
35
  {
36
36
  "file": "TAILWIND_V4.md",
@@ -58,7 +58,7 @@
58
58
  "specifier": "@spectrabrain/eds/components/{name}/README.md",
59
59
  "kind": "component-guide",
60
60
  "required": false,
61
- "when": "A requested UI may fit an EDS component; read its usage context and selection guidance before deciding. If selected, follow its props and accessibility contract; check icons outside the allowlist as needed."
61
+ "when": "A requested UI may fit an EDS component; read its usage context and selection guidance before deciding. If selected, follow its props and accessibility contract."
62
62
  },
63
63
  {
64
64
  "file": "dist/components/{name}/spec.json",
@@ -72,7 +72,7 @@
72
72
  "specifier": "@spectrabrain/eds/CHANGELOG.md",
73
73
  "kind": "changelog",
74
74
  "required": false,
75
- "when": "EDS was upgraded: the installed version is higher than the AGENTS.md EDS:VERSION line"
75
+ "when": "EDS was upgraded, or the AGENTS.md EDS:VERSION marker is missing: read all applicable consumer actions through the installed version"
76
76
  }
77
77
  ],
78
78
  "precedence": [
package/CHANGELOG.md CHANGED
@@ -1,5 +1,33 @@
1
1
  # @spectrabrain/eds
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 458fbde: 소비처 조치: 없습니다.
8
+
9
+ Button 이름 슬롯의 자동완성 응답을 개선하면서 설치된 `lucide-react`의 전체 icon component 이름과 alias 지원을 유지합니다.
10
+
11
+ ## 0.5.0
12
+
13
+ ### Minor Changes
14
+
15
+ - 5da0d43: 소비처 조치: `npm install @spectrabrain/eds`로 업데이트합니다. 허용된 postinstall이 첫 sync를 준비하며, EDS 버전 marker가 없거나 설치 버전과 다르면 에이전트가 적용할 changelog 조치를 읽고 UI 작업 시작에 `sync:eds`를 실행합니다. 최종 검증 뒤 커밋 직전에 `eds:doctor`를 실행해 `[EDS] synced with` 줄을 확인합니다.
16
+
17
+ Doctor는 `typecheck`·`build`에서 자동 실행하지 않습니다. `init`·sync·postinstall은 이전 EDS가 등록한 Doctor lifecycle hook과 typecheck·build 명령의 Doctor 접두를 정리합니다.
18
+
19
+ ## 0.4.0
20
+
21
+ ### Minor Changes
22
+
23
+ - 863888b: 소비처 조치: 없습니다.
24
+
25
+ Button 이름 슬롯에서 설치된 `lucide-react`의 모든 아이콘 component 이름과 alias를 사용할 수 있습니다. custom 아이콘의 ReactElement 슬롯은 그대로 지원합니다.
26
+
27
+ - 0a3ed23: 소비처 조치: `p-eds-spacing-*`·`rounded-eds-radius-*`와 spacing·radius용 `cssVar()` 호출을 `p-4`·`rounded-lg` 같은 Tailwind CSS v4 기본 utility로 바꿉니다. Tailwind CSS를 쓰지 않는 화면은 기존 CSS 규칙을 따릅니다.
28
+
29
+ Breaking change: 소비처용 semantic spacing·radius token, CSS 변수, Tailwind 별칭과 TypeScript 이름을 제거합니다.
30
+
3
31
  ## 0.3.1
4
32
 
5
33
  ### Patch Changes
package/CONSUMER_AGENT.md CHANGED
@@ -7,7 +7,7 @@
7
7
  `npm run sync:eds`는 sync를 실행한 package 디렉터리(`package.json`이 있는 곳)의 `AGENTS.md`에 managed block을 관리합니다.
8
8
 
9
9
  - 파일이 없으면 만들고, block이 없으면 끝에 추가하며, 있으면 같은 위치에서 갱신합니다. marker 밖의 내용은 보존합니다.
10
- - BEGIN marker 바로 뒤에 설치 버전(`<!-- EDS:VERSION x.y.z -->`)을 기록하고 `npm run ` 접두를 감지한 runner(`pnpm `, `yarn `, `bun run `)로 바꿉니다.
10
+ - BEGIN marker 바로 뒤에 설치 버전(`<!-- EDS:VERSION x.y.z -->`)을 기록하고, 해당 package에서 실행 가능한 sync·doctor 명령을 기록합니다. script가 아직 없거나 소비처 소유 script와 충돌하면 CLI 명령을 씁니다.
11
11
  - marker가 중복되거나 한쪽만 있으면 파일을 쓰지 않고 실패합니다.
12
12
 
13
13
  ```md
@@ -16,13 +16,14 @@
16
16
  ## EVA Design System 사용 규칙
17
17
 
18
18
  - UI 작업 전에 EDS package root(`require.resolve("@spectrabrain/eds/package.json")`의 디렉터리, 보통 `node_modules/@spectrabrain/eds`)의 `QUICKSTART.md`를 읽고 규칙과 완료 기준을 따릅니다. 조건별 문서는 `AI_CONTEXT.json`의 `readOrder`를 따릅니다.
19
- - UI 작업을 끝내기 전에 이 `AGENTS.md`가 있는 디렉터리에서 `npm run eds:doctor`를 실행해 `[EDS] synced with` 줄을 확인합니다. 이 줄이 없으면 `QUICKSTART.md` 「완료 기준」의 순서로 고칩니다.
20
- - UI 작업의 완료 보고에 변경 파일, 사용한 EDS component·token, typecheck·build·doctor 결과를 적습니다.
19
+ - 첫 편집 전에 이 `AGENTS.md`가 있는 디렉터리에서 `npm run sync:eds`를 한 번 실행합니다. sync는 설치 버전과 managed block·생성 파일을 비교해 필요한 파일만 갱신하며, 차이가 없으면 `Already synced`를 출력합니다. 설치 버전이 marker보다 높으면 먼저 해당 버전의 `CHANGELOG.md` 소비처 조치를 읽고 적용합니다. 작업 중 EDS를 설치하거나 업데이트하면 변경 내역을 읽고 다시 실행합니다. typecheck·build 앞에는 실행하지 않습니다.
20
+ - 검증이 끝난 뒤 커밋 직전에 `npm run eds:doctor`를 실행해 `[EDS] synced with` 줄을 확인합니다. 기존 pre-commit hook이 이미 같은 점검을 실행하면 그 결과를 확인하고, 그렇지 않으면 에이전트가 직접 실행합니다. EDS는 typecheck·build lifecycle hook을 등록하지 않습니다.
21
+ - UI 작업의 완료 보고에 변경 파일, 사용한 EDS component·token, typecheck·build 결과와 커밋 전 doctor 결과를 적습니다.
21
22
  - 이 block은 `npm run sync:eds`가 다시 씁니다. 소비처 규칙은 block 밖에 적습니다.
22
23
  <!-- EDS:END -->
23
24
  ```
24
25
 
25
- block은 postinstall이 아니라 `npm run sync:eds`가 넣으며, 소비처 담당자가 저장소의 기존 규칙과 함께 diff를 검토합니다. EDS를 업데이트할 때도 block 안쪽과 버전 줄만 바뀝니다.
26
+ 첫 설치 postinstall은 직접 설치된 앱에서 scripts와 첫 sync를 수행해 block을 만들 수 있습니다. EDS 버전이 기존 marker와 다르거나 기존 block에 marker가 없으면 postinstall이 block과 파일을 갱신하지 않습니다. 에이전트가 marker가 없을 때는 설치 버전까지의 적용 가능한 changelog 조치를, 버전이 다를 때는 이전 marker 이후의 조치를 읽은 뒤 다음 UI 작업 시작에 sync합니다. 소비처 담당자는 생성된 변경을 저장소의 기존 규칙과 함께 검토합니다.
26
27
 
27
28
  block이 전달되는 지시 파일은 도구마다 다릅니다.
28
29
 
@@ -34,15 +35,15 @@ sync와 doctor는 Claude·Gemini 지시 파일이 없거나, `CLAUDE.local.md`
34
35
 
35
36
  ## 첫 setup 절차
36
37
 
37
- 소비처 `AGENTS.md`에 EDS managed block이 없으면 UI 작업보다 먼저 이 절차를 진행합니다. `@spectrabrain/eds`를 dependencies에 선언할 앱 package 디렉터리(그 앱의 `package.json`이 있는 곳)에서 패키지를 설치하고 `init`으로 script 등록과 첫 sync를 실행합니다. `init`은 postinstall 실행 여부와 관계없이 동작하며, 현재 `package.json`이 `@spectrabrain/eds`를 선언하지 않으면 아무것도 쓰지 않고 exit 2로 끝납니다.
38
+ 소비처 담당자는 앱 package에 EDS를 설치하면 됩니다. 직접 앱에서 dependency lifecycle script가 허용되면 postinstall이 scripts와 첫 sync를 준비합니다. pnpm postinstall은 `package.json` script를 수정하지 않으며, 첫 UI 작업 sync가 이를 등록합니다. workspace root나 lifecycle script가 실행되지 않은 경우에는 에이전트가 EDS dependency를 선언한 앱 package에서 `init`을 실행합니다(`npx @spectrabrain/eds init`, `pnpm exec eds init`, `yarn eds init`, `bunx @spectrabrain/eds init`). 이때도 소비처 담당자가 `sync:eds`를 직접 실행할 필요는 없습니다. `init`은 현재 `package.json`이 `@spectrabrain/eds`를 선언하지 않으면 아무것도 쓰지 않고 exit 2로 끝납니다.
38
39
 
39
- | 패키지 매니저 | 실행할 명령 | `init`의 추가 동작 |
40
- | --------------------------------------------------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
41
- | npm | `npm install @spectrabrain/eds && npx @spectrabrain/eds init` | npm 12 이상이면 `allowScripts["@spectrabrain/eds"]: true`(이름만, 버전 pin 없음)를 키가 없을 때만 기록합니다. `--no-allow-scripts`로 건너뜁니다. |
42
- | pnpm | `pnpm add @spectrabrain/eds && pnpm exec eds init` | 추가 설정이 필요 없습니다. 설치 중 postinstall은 `init` 안내만 출력합니다. |
43
- | yarn berry(`.yarnrc.yml`이 있거나 `yarn.lock`이 `__metadata:`로 시작) | `yarn add @spectrabrain/eds && yarn eds init` | yarn berry는 `pre`·`post` hook을 실행하지 않으므로 `typecheck`·`build` script 앞에 `eds doctor && `를 붙이라고 안내하며, 그 script를 직접 고치지는 않습니다. `enableScripts`·`dependenciesMeta` 승인은 선택 사항이며 사용자가 결정할 항목으로 완료 보고에 적습니다. |
44
- | yarn classic | `yarn add @spectrabrain/eds && yarn eds init` | 추가 안내가 없습니다. |
45
- | bun | `bun add @spectrabrain/eds && bunx @spectrabrain/eds init` | `trustedDependencies` 승인은 선택 사항이며, bun의 기본 신뢰 목록을 대체하므로 사용자가 결정할 항목으로 완료 보고에 적습니다. |
40
+ | 패키지 매니저 | 소비처가 실행하는 설치 명령 | 설치 후 자동 동작과 에이전트 초기화 |
41
+ | --------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
42
+ | npm | `npm install @spectrabrain/eds` | 허용된 postinstall이 scripts와 첫 sync를 준비합니다. npm 12 이상은 `allowScripts["@spectrabrain/eds"]: true`(이름만, 버전 pin 없음)가 필요할 수 있으며, `init`이 이 설정을 기록합니다. `--no-allow-scripts`로 건너뜁니다. |
43
+ | pnpm | `pnpm add @spectrabrain/eds` | 허용된 postinstall은 소비처 파일을 sync하지만 script 등록은 보류합니다. 첫 UI 작업의 `pnpm exec eds sync`가 scripts를 등록합니다. |
44
+ | yarn berry(`.yarnrc.yml`이 있거나 `yarn.lock`이 `__metadata:`로 시작) | `yarn add @spectrabrain/eds` | dependency script가 허용된 경우 postinstall이 동작합니다. `enableScripts`·`dependenciesMeta` 승인은 사용자가 결정합니다. 실행되지 않으면 에이전트가 `yarn eds init`을 사용합니다. |
45
+ | yarn classic | `yarn add @spectrabrain/eds` | dependency script가 허용된 경우 postinstall이 동작합니다. 실행되지 않으면 에이전트가 `yarn eds init`을 사용합니다. |
46
+ | bun | `bun add @spectrabrain/eds` | dependency script가 허용된 경우 postinstall이 동작합니다. 실행되지 않으면 에이전트가 `bunx @spectrabrain/eds init`을 사용합니다. `trustedDependencies` 승인은 사용자가 결정합니다. |
46
47
 
47
48
  yarn berry의 기본 Plug'n'Play 설치에는 `node_modules/@spectrabrain/eds`가 없으며 지원 여부는 아직 확인되지 않았습니다. sync와 doctor는 `.pnp.cjs`를 발견하면 `note:`로 알리며, 이때 `nodeLinker`를 바꾸기 전에 저장소 담당자에게 확인합니다.
48
49
 
@@ -59,36 +60,36 @@ EDS CLI는 가장 가까운 lockfile(현재 디렉터리부터 git 루트까지)
59
60
  }
60
61
  ```
61
62
 
62
- - `sync:eds`·`eds:doctor`가 없으면 등록합니다. 같은 이름의 script가 `eds sync`·`eds doctor`를 포함하면(예: `EDS_DOCTOR=warn eds doctor`) 그대로 두고, 다른 명령이면 덮어쓰지 않고 안내만 출력하며 `eds doctor`가 `scripts:` 항목으로 보고합니다. 이전 EDS 버전이 등록한 알려진 명령은 새 명령으로 바꿉니다.
63
- - 소비처에 `typecheck`·`build` script가 있으면 대응하는 `pretypecheck`·`prebuild` hook이 없는 경우에만 `eds doctor`를 등록합니다. 이미 다른 pre-hook이 있으면 그대로 두고, 출력된 명령대로 기존 hook 앞에 `eds doctor && `를 붙입니다.
64
- - npm 10·11과, `init`이 `allowScripts`를 기록한 npm 12 이상에서는 EDS의 `postinstall`이 설치 중에 같은 script를 등록하고 다른 파일은 쓰지 않습니다. 소비처 `package.json`에 `workspaces`가 있으면 등록하지 않고 앱 package 안에서 `init`을 실행하도록 안내하며, pnpm 설치에서는 pnpm이 설치 중의 `package.json` 편집을 버리므로 `pnpm exec eds init`을 안내합니다.
63
+ - `sync:eds`·`eds:doctor`가 없으면 `init`·sync·postinstall이 등록합니다. 같은 이름의 script가 `eds sync`·`eds doctor`를 포함하면(예: `EDS_DOCTOR=warn eds doctor`) 그대로 두고, 다른 명령이면 덮어쓰지 않고 안내만 출력하며 `eds doctor`가 `scripts:` 항목으로 보고합니다. 이전 EDS 버전이 등록한 알려진 명령은 새 명령으로 바꿉니다.
64
+ - `init`·sync·postinstall은 Doctor를 typecheck·build lifecycle에 등록하지 않습니다. 이전 EDS가 만든 `pretypecheck`·`prebuild: "eds doctor"`를 제거하고, typecheck·build 또는 해당 pre-hook이 `eds doctor && <기존 명령>`으로 시작하면 Doctor 접두만 제거해 기존 명령을 보존합니다.
65
+ - postinstall은 직접 설치된 앱에서 `sync:eds`·`eds:doctor`를 등록하고 첫 설치 sync로 managed block·생성 CSS·Tailwind import를 준비합니다. 기존 marker와 설치 버전이 다르거나 기존 block에 marker가 없으면 changelog 조치를 보존하기 위해 파일 sync를 미루고 script 정리만 합니다. 소비처 `package.json`에 `workspaces`가 있으면 루트가 앱인지 단정할 수 없어 건너뜁니다. pnpm은 lifecycle 중 `package.json` 편집을 버리므로 파일만 sync하고, 첫 UI 작업의 `pnpm exec eds sync`에서 scripts를 등록합니다.
65
66
  - `--no-sync`는 script만 등록하고(npm 12 이상은 `allowScripts`도 기록) sync는 실행하지 않습니다(`npx @spectrabrain/eds init --no-sync`).
66
67
  - `init --print-ci github` 또는 `--print-ci gitlab`(예: `npx @spectrabrain/eds init --print-ci github`)은 이 저장소의 패키지 매니저로 install과 `eds doctor`를 실행하는 CI job snippet을 출력합니다. 저장소 루트가 EDS package이면 그대로 붙입니다. workspace package에서는 GitHub Actions의 `working-directory`를 지정하거나 GitLab의 install·doctor 명령 앞에 `cd <앱 package 경로> &&`를 붙입니다. 출력 snippet에는 이 경로가 포함되지 않습니다.
67
68
 
68
- 설치와 sync는 `npm run eds:doctor`가 `[EDS] synced with` 줄을 출력하면 확인됩니다. `pretypecheck`·`prebuild` hook은 `init` 또는 `postinstall`이 등록하며, doctor는 hook 자체를 검사하지 않습니다. 기존 hook을 건너뛰었다는 안내가 나오면 `eds doctor && `를 기존 명령 앞에 붙입니다. 담당자가 첫 sync 전에 `CLAUDE.md`·`AGENTS.md`에 넣은 EDS 안내 줄(`README.md` 「설치」)이 남아 있으면 block과 겹치므로 지웁니다. 같은 이름의 다른 script를 바꾸거나 marker 밖 기존 내용을 고쳐야 할 때는 쓰기 전에 사용자에게 확인합니다.
69
+ 에이전트는 첫 편집 전에 한 번 sync하고, 이후 UI 작업 시작과 EDS 설치·업데이트 뒤에도 sync합니다. marker와 생성물이 최신이면 sync는 `Already synced`로 끝납니다. typecheck·build는 Doctor를 실행하지 않습니다. Doctor는 최종 검증 뒤 커밋 직전에 실행하며, 기존 pre-commit hook이 같은 점검을 이미 실행하면 그 결과를 확인하고 그렇지 않으면 에이전트가 직접 실행합니다. 새 hook manager는 설치하지 않습니다. 담당자가 첫 sync 전에 `CLAUDE.md`·`AGENTS.md`에 넣은 EDS 안내 줄(`README.md` 「설치」)이 남아 있으면 block과 겹치므로 지웁니다. 같은 이름의 다른 script를 바꾸거나 marker 밖 기존 내용을 고쳐야 할 때는 쓰기 전에 사용자에게 확인합니다.
69
70
 
70
71
  ## Tailwind root 결정
71
72
 
72
73
  `eds sync`와 `eds doctor`는 환경 변수 `EDS_TAILWIND_ROOT`, 소비처 `package.json`의 `eds.tailwindRoot`, 자동 검출 순서로 Tailwind root CSS를 정합니다. 자동 검출은 `@import "tailwindcss"`(`tailwindcss/theme.css`·`tailwindcss/utilities.css`, `@import url("tailwindcss")` 포함)가 있는 CSS 파일 하나를 root로 쓰며, 주석 안의 import와 `node_modules`·`dist`·`build`·`coverage`·`storybook-static`, 점(`.`)으로 시작하는 디렉터리는 제외합니다.
73
74
 
74
75
  - 후보가 2개 이상이면 아무 파일도 쓰지 않고 exit 2로 끝납니다. 사용자에게 root를 확인하고, 후보마다 앱 진입점(예: `src/main.tsx`)이 그 파일을 import하는지 찾아 함께 알립니다.
75
- - 확인한 root는 `EDS_TAILWIND_ROOT=<root CSS 경로> npm run sync:eds`로 한 번 지정합니다(예: `EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds`). sync는 이 경로를 소비처 `package.json`의 `"eds": { "tailwindRoot": "…" }`에 저장하므로 이후 doctor·sync·hook은 환경 변수 없이 같은 root를 씁니다.
76
+ - 확인한 root는 `EDS_TAILWIND_ROOT=<root CSS 경로> npm run sync:eds`로 한 번 지정합니다(예: `EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds`). sync는 이 경로를 소비처 `package.json`의 `"eds": { "tailwindRoot": "…" }`에 저장하므로 이후 doctor·sync가 환경 변수 없이 같은 root를 씁니다.
76
77
  - `EDS_TAILWIND_ROOT`나 저장된 경로가 없는 파일을 가리키면 exit 2입니다.
77
78
  - 후보가 없고 지정도 없으면 Tailwind를 쓰지 않는 저장소로 보고 Tailwind 배선을 건너뜁니다. 이때 sync는 `AGENTS.md` managed block과, 파일이 있을 때 `CLAUDE.md`·`GEMINI.md`의 import만 갱신합니다. doctor는 Tailwind 항목 대신 `note:` 한 줄을 출력하고 EDS font import는 계속 점검합니다. Tailwind를 쓰지 않는 저장소는 앱 진입점(예: `src/main.tsx`)에서 `@spectrabrain/eds/styles.css`를 import합니다.
78
79
  - CSS가 `@tailwind` 지시어를 쓰는 Tailwind CSS v3 저장소도 후보가 없는 것으로 보고, sync와 doctor가 `Tailwind CSS v3 detected` note를 출력합니다. 이 저장소에서는 `EDS_TAILWIND_ROOT`를 지정하지 않고(v3 파일을 가리키면 exit 2) 앱 진입점의 `styles.css` import와 `var(--eds-*)`·`cssVar()`를 쓰며, Tailwind CSS v4 업그레이드는 사용자에게 확인한 뒤 진행합니다.
79
80
 
80
81
  ## sync가 쓰는 파일
81
82
 
82
- sync는 모든 변경을 먼저 계산하고, 계산 중 하나라도 실패하면 어떤 파일도 바꾸지 않습니다. 쓰는 내용은 다음과 같습니다.
83
+ 전체 sync는 `sync:eds`·`eds:doctor` script가 빠졌으면 등록하고, 이전 EDS Doctor lifecycle hook과 typecheck·build 접두를 정리합니다. 소비처가 덧붙인 접미 명령은 보존합니다. `--only` sync는 지정한 대상만 동기화하며 script 등록과 Doctor 정리는 하지 않습니다. 파일 변경은 모두 먼저 계산하고, 계산 중 하나라도 실패하면 어떤 파일도 바꾸지 않습니다. 쓰는 파일은 다음과 같습니다.
83
84
 
84
- 1. `src/styles/eds-tokens.css`를 생성하고, Tailwind root의 마지막 Tailwind import 바로 다음 줄에 `@import "@spectrabrain/eds/styles.css";`와 생성 CSS의 상대 경로 `@import`를 추가합니다. 이미 있는 import는 다시 추가하지 않습니다. 생성 CSS의 `@theme inline`에는 공개 color·spacing·radius alias와 `--font-sans: var(--eds-typography-body1-fontFamily);`가 들어갑니다. root CSS 예시는 `TAILWIND_V4.md`에 있습니다.
85
+ 1. `src/styles/eds-tokens.css`를 생성하고, Tailwind root의 마지막 Tailwind import 바로 다음 줄에 `@import "@spectrabrain/eds/styles.css";`와 생성 CSS의 상대 경로 `@import`를 추가합니다. 이미 있는 import는 다시 추가하지 않습니다. 생성 CSS의 `@theme inline`에는 공개 color alias와 `--font-sans: var(--eds-typography-body1-fontFamily);`가 들어갑니다. Typography utility도 함께 생성됩니다. root CSS 예시는 `TAILWIND_V4.md`에 있습니다.
85
86
  2. `src/` 아래 JS·TS 파일에서 `eds-tokens.css`를 import하는 줄을 제거합니다. Tailwind는 JS에서 import한 CSS를 compile하지 않기 때문입니다.
86
87
  3. `AGENTS.md` managed block을 넣거나 갱신합니다.
87
88
  4. `CLAUDE.md`가 있으면 `@AGENTS.md`, `CLAUDE.md` 없이 `.claude/CLAUDE.md`가 있으면 `@../AGENTS.md`, `GEMINI.md`가 있으면 `@./AGENTS.md` import를 `<!-- EDS:CLAUDE:BEGIN/END -->`·`<!-- EDS:GEMINI:BEGIN/END -->` marker로 감싸 파일 끝에 한 번 추가합니다. sync는 이 marker로 import를 찾으므로 marker와 import를 함께 유지합니다. 파일이 없으면 만들지 않고, `AGENTS.md`와 같은 파일(symlink)이면 추가하지 않습니다.
88
89
 
89
90
  `@spectrabrain/eds/styles.css`는 CSS나 JS·TS 소스가 이미 import하고 있으면 다시 추가하지 않습니다. `tokens.css`·`components.css`·`fonts.css`가 모두 import되어 있어도 같으며, `tokens.css`와 `components.css`만 있고 `fonts.css`가 없으면 root에 `@import "@spectrabrain/eds/fonts.css";`를 추가합니다.
90
91
 
91
- `npm run sync:eds -- --only tailwind`와 `npm run sync:eds -- --only agents`는 해당 부분만 쓰고, `--dry-run`은 쓸 경로만 출력합니다. 두 옵션을 써도 Tailwind root 판정과 marker 검사는 모두 수행하므로, root 후보가 2개 이상이면 `--only agents`도 exit 2로 끝납니다. 파일을 쓴 sync는 쓴 파일을 `[EDS] wrote <경로>` 줄로 나열한 뒤 그 파일을 변경에 포함하고 doctor를 실행하라는 줄로 끝나고, 바꿀 것이 없으면 `Already synced`로 끝납니다.
92
+ `npm run sync:eds -- --only tailwind`와 `npm run sync:eds -- --only agents`는 해당 부분만 동기화하며 script 등록과 Doctor 정리는 하지 않습니다. `--dry-run`은 변경할 `package.json` script와 파일 경로를 출력하고 파일은 쓰지 않습니다. 두 옵션을 써도 Tailwind root 판정과 marker 검사는 모두 수행하므로, root 후보가 2개 이상이면 `--only agents`도 exit 2로 끝납니다. 파일을 쓴 sync는 쓴 파일을 `[EDS] wrote <경로>` 줄로 나열한 뒤 커밋 전에 doctor를 실행하라는 줄로 끝나고, 바꿀 것이 없으면 `Already synced`로 끝납니다.
92
93
 
93
94
  ## font 정책
94
95
 
@@ -100,9 +101,9 @@ EDS text style은 font family `Pretendard`를 참조하며, 이 family는 `@spec
100
101
 
101
102
  `eds doctor`는 `@spectrabrain/eds/styles.css`와 `@spectrabrain/eds/fonts.css`가 CSS·JS·TS 어디에서도 import되지 않으면 `missing:`으로 보고합니다. HTML·CSS에서 EDS import 밖에 `Pretendard`를 언급하는 줄이 있으면 `note:`를 출력하며, 이 줄은 exit code에 영향을 주지 않습니다.
102
103
 
103
- ## `eds:doctor` 점검
104
+ ## 커밋 전 `eds:doctor` 점검
104
105
 
105
- `npm run eds:doctor`는 파일을 쓰지 않고 sync 상태, `sync:eds`·`eds:doctor` 등록, EDS font import를 점검합니다. Tailwind CSS v4 root가 있으면 소스의 `eds-*` class 이름도 확인합니다. doctor는 `pretypecheck`·`prebuild` hook을 검사하지 않습니다. `init` 또는 `postinstall`이 등록한 hook은 typecheck·build 전에 같은 점검을 실행합니다. yarn berry는 이 hook을 실행하지 않으므로 `typecheck`·`build` 앞에 붙인 `eds doctor`가 같은 역할을 합니다.
106
+ `npm run eds:doctor`는 파일을 쓰지 않고 sync 상태, `sync:eds`·`eds:doctor` 등록, EDS font import를 점검합니다. Tailwind CSS v4 root가 있으면 소스의 `eds-*` class 이름도 확인합니다. typecheck·build 명령에는 연결하지 않으며, 에이전트가 최종 검증을 마친 뒤 커밋 직전에 실행합니다. 기존 pre-commit hook이 Doctor를 실행하면 그 결과를 확인하고, 그렇지 않으면 에이전트가 직접 한 번 실행합니다. `init`·postinstall은 Git hook manager를 설치하거나 만들지 않습니다. `init --print-ci`가 출력하는 CI job은 별도 안전망입니다.
106
107
 
107
108
  | exit | 의미 |
108
109
  | ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -117,10 +118,10 @@ EDS text style은 font family `Pretendard`를 참조하며, 이 family는 `@spec
117
118
  | `missing:`·`stale:`·`legacy:`(생성 CSS, root CSS import, `AGENTS.md` block, `CLAUDE.md`·`GEMINI.md` import) | `npm run sync:eds`로 고칩니다. `sync:eds`가 등록되지 않았으면 `eds doctor`가 출력한 `init` 명령을 실행합니다. 이 명령이 script를 등록하고 sync합니다. |
118
119
  | `missing:` EDS font import(Tailwind root가 없는 저장소) | 앱 진입점에서 `@spectrabrain/eds/styles.css`를 import합니다. 이 경우 sync는 CSS를 고치지 않습니다. |
119
120
  | `scripts:` | 등록되지 않았으면 「첫 setup 절차」의 `init`으로 등록합니다(init이 sync까지 실행합니다). 같은 이름의 다른 script이면 init이 덮어쓰지 않으므로, 그 script가 `eds sync`·`eds doctor`를 실행하도록 고치거나 이름을 바꾼 뒤 init을 실행합니다. |
120
- | `unknown: <파일:줄> <class>` | 공개 token이 없는 `eds-*` class입니다. Tailwind는 이런 class를 조용히 버리므로 `src/styles/eds-tokens.css`에 있는 class로 고칩니다. class 이름은 color token이 `<utility>-eds-<이름>`, `typography-<style>-*`가 `eds-typography-<style>`, spacing·radius가 `p-eds-spacing-0-5`·`rounded-eds-radius-1`처럼 되는 규칙으로 만들어집니다. |
121
+ | `unknown: <파일:줄> <class>` | 공개 token이 없는 `eds-*` class입니다. Tailwind는 이런 class를 조용히 버리므로 `src/styles/eds-tokens.css`에 있는 class로 고칩니다. EDS class는 color token의 `<utility>-eds-<이름>`과 typography utility `eds-typography-<style>`입니다. padding·margin·gap·radius에는 Tailwind CSS v4 기본 utility를 씁니다. |
121
122
  | `invalid:` | `AGENTS.md`의 EDS marker가 중복되거나 한쪽만 있습니다. sync는 이 상태를 고치지 않습니다. 출력에 적힌 줄에서 BEGIN 한 줄과 그 뒤의 END 한 줄만 남기고 나머지 marker 줄을 지운 뒤 sync를 다시 실행합니다. |
122
123
 
123
- `npm run eds:doctor -- --warn`과 `EDS_DOCTOR=warn`은 같은 출력에 warn mode 경고를 더하고 exit 0으로 끝나며, `EDS_DOCTOR=off`는 출력 없이 exit 0으로 끝납니다. 이 설정은 hook을 잠시 풀어야 할 때 사용자가 쓰는 것이며, 이 상태의 exit 0은 완료가 아닙니다.
124
+ `npm run eds:doctor -- --warn`과 `EDS_DOCTOR=warn`은 같은 출력에 warn mode 경고를 더하고 exit 0으로 끝나며, `EDS_DOCTOR=off`는 출력 없이 exit 0으로 끝납니다. 이 설정은 로컬 진단에만 사용하며, 이 상태의 exit 0은 완료가 아닙니다.
124
125
 
125
126
  `npm run eds:doctor -- --scan`은 Tailwind 기본 팔레트(`text-red-500`), `white`·`black`, 임의 색(`bg-[#…]`) class를 `raw: <파일:줄> <class>` 줄로 나열합니다. 정보 제공용이라 exit code를 바꾸지 않습니다. `unknown:`과 `raw:` 검사는 Tailwind CSS v4 root가 있는 저장소에서 Tailwind class만 봅니다. CSS·inline style의 `var(--eds-*)` 참조는 검사하지 않습니다.
126
127
 
@@ -156,7 +157,7 @@ EDS 버전을 올렸으면 다음 순서로 진행합니다.
156
157
 
157
158
  1. sync 전에 `AGENTS.md`의 `<!-- EDS:VERSION x.y.z -->` 줄에서 이전 버전을 확인합니다. 이미 sync했다면 `git diff AGENTS.md`의 삭제된 버전 줄에서 확인합니다.
158
159
  2. package root의 `CHANGELOG.md`(`@spectrabrain/eds/CHANGELOG.md`)에서 이전 버전보다 높은 절만 읽고, 각 항목이 요구하는 소비처 조치를 모두 적용합니다. 새 항목은 `소비처 조치:`로 시작합니다.
159
- 3. `npm run sync:eds`로 Tailwind root의 import, 공개 token alias, managed block과 버전 줄을 갱신하고, `npm run eds:doctor`가 `[EDS] synced with` 줄을 출력하는지 확인합니다.
160
+ 3. `npm run sync:eds`로 Tailwind root의 import, 공개 token alias, managed block과 버전 줄을 갱신합니다.
160
161
  4. 제거되거나 이름이 바뀐 token은 `CHANGELOG.md`에서 이름을 확인하고, Tailwind class는 doctor의 `unknown:` 항목에서, `cssVar()` 호출은 typecheck 오류에서, CSS·inline style의 `var(--eds-<이름>)`은 `tokens.json`의 `cssVariable` mapping과 대조해 고칩니다. dotted public name은 CSS reference에서만 점을 escape합니다. 새로 쓸 수 있는 class는 `src/styles/eds-tokens.css`의 diff에서 확인합니다.
161
162
 
162
- 생성 CSS의 header나 `AGENTS.md`의 버전 줄이 설치된 버전과 다르면 doctor가 `stale:`로 보고하므로, sync를 빠뜨린 업데이트는 `pretypecheck`·`prebuild` hook(yarn berry는 `typecheck`·`build` 앞의 `eds doctor`)에서 드러납니다. 작업 보고에는 올린 EDS 버전, 적용한 소비처 조치, 바뀐 파일, 새로 쓸 수 있는 class, 제거되거나 이름이 바뀐 공개 token, 검증 결과를 남깁니다.
163
+ 생성 CSS의 header나 `AGENTS.md`의 버전 줄이 설치된 버전과 다르면 sync가 해당 파일을 갱신합니다. 에이전트는 UI 작업을 시작할 때 한 번 sync를 실행하고, `Already synced`이면 추가 파일 변경 없이 진행합니다. sync를 빠뜨린 업데이트는 커밋 전 doctor가 `stale:`로 보고합니다. typecheck·build와 다른 최종 검증을 마친 뒤 doctor를 마지막으로 실행하고, 작업 보고에는 올린 EDS 버전, 적용한 소비처 조치, 바뀐 파일, 새로 쓸 수 있는 class, 제거되거나 이름이 바뀐 공개 token, 검증 결과를 남깁니다.
package/FRONTEND_CONVENTIONS.md CHANGED
@@ -25,7 +25,7 @@ EVA 서비스의 Vite + React 프론트엔드 규칙입니다. `eds align`은
25
25
  | client-state | `zustand` 5 | `redux`, `@reduxjs/toolkit`, `jotai`, `recoil`, `mobx` | `entities/<domain>/stores`에 둡니다. 저장이 필요하면 `persist`와 `partialize`를 씁니다. |
26
26
  | form | `useState` 또는 Context + `useReducer` | `react-hook-form`, `formik` | 단순한 form은 `useState`, 여러 단계 form은 feature의 `lib/<Name>FormContext.tsx`에 Context + `useReducer`를 둡니다. |
27
27
  | validation | TypeScript 타입과 검증 함수 | `zod`, `yup`, `valibot` | 검증 함수는 화면에 표시할 오류 문구를 돌려줍니다. backend 코드가 import하는 validation 라이브러리는 패키지를 유지하고, 프론트엔드 코드만 검증 함수로 옮깁니다. |
28
- | styling | Tailwind CSS 4 + EDS token | `styled-components`, `@emotion/*`, `sass`, CSS Modules | 스타일은 `className`으로 쓰고 전역 CSS는 `app/styles/index.css` 하나에 둡니다. |
28
+ | styling | Tailwind CSS 4 + EDS color·typography token | `styled-components`, `@emotion/*`, `sass`, CSS Modules | spacing·radius에는 Tailwind CSS v4 기본 utility를 씁니다. 스타일은 `className`으로 쓰고 전역 CSS는 `app/styles/index.css` 하나에 둡니다. |
29
29
  | ui-kit | EDS `Button` + shadcn/ui(Radix) | `@mui/material`, `@chakra-ui/react`, `antd`, `@mantine/core` | 버튼은 EDS `Button`, 그 밖의 UI 요소는 `shared/ui`의 shadcn/ui 컴포넌트를 씁니다. |
30
30
  | icon | `lucide-react` | `react-icons`, `@heroicons/react`, `@fortawesome/*` | EDS `Button`의 아이콘은 `dist/components/Button/README.md` 「Layout과 아이콘」의 슬롯 규칙을 따릅니다. `lucide-react`는 EDS package root `package.json`의 `dependencies["lucide-react"]`와 같은 버전으로 선언합니다. |
31
31
  | toast | `sonner` | `react-toastify`, `react-hot-toast` | `app/App.tsx`에 `<Toaster position="top-right" richColors />`를 한 번 둡니다. |
@@ -244,4 +244,4 @@ export function ConfirmDeleteAccountButton({
244
244
 
245
245
  ## 점검
246
246
 
247
- - 프론트엔드 코드를 바꾼 작업은 완료 전에 `format:check`·`lint`·`typecheck`·`build` script와 `npx @spectrabrain/eds align --check`가 모두 exit 0이고, `eds:doctor`가 `[EDS] synced with` 줄을 출력해야 합니다. `npm run`·`npx`는 저장소의 패키지 매니저 형식(예: `pnpm exec eds align --check`)으로 바꿔 실행합니다. `--check`의 출력 종류와 exit code는 `CONSUMER_AGENT.md` 「프로토타입 정렬」에 있습니다.
247
+ - 프론트엔드 코드를 바꾼 작업은 `format:check`·`lint`·`typecheck`·`build` script와 `npx @spectrabrain/eds align --check`가 모두 exit 0이어야 합니다. Doctor는 이 명령에 연결하지 않고 최종 검증 뒤 커밋 직전에 실행해 `[EDS] synced with` 줄을 확인합니다. `npm run`·`npx`는 저장소의 패키지 매니저 형식(예: `pnpm exec eds align --check`)으로 바꿔 실행합니다. `--check`의 출력 종류와 exit code는 `CONSUMER_AGENT.md` 「프로토타입 정렬」에 있습니다.
package/QUICKSTART.md CHANGED
@@ -12,7 +12,7 @@
12
12
 
13
13
  1. 사용자의 명시적 요청에 따르고 접근성·보안·framework 제약을 지킵니다. 그 안에서 문서화된 소비처 제품 요구를 우선합니다. 이를 충족하는 같은 역할의 EDS component(현재 `Button`)가 있고 공개 contract도 맞으면 쓰고, 아니면 소비처 로컬 UI를 씁니다.
14
14
  2. `AI_CONTEXT.json.components`의 후보를 확인하고, 요청에 맞는지 판단하기 전에 component `README.md`의 사용 맥락·선택 기준을 읽습니다. 필요한 prop·variant·state·slot이 README와 TypeScript contract에 모두 맞아야 합니다. 후보가 없거나 맞지 않으면 로컬 UI를 쓰고, `spec.json`은 아이콘 이름이나 기계 판독 계약 확인에만 씁니다.
15
- 3. 색상·typography·spacing·radius는 공개 token으로 지정합니다. EDS와 sync한 Tailwind CSS v4 root에서는 `text-eds-fg-*`·`bg-eds-bg-*`·`border-eds-stroke-*`·`p-eds-spacing-0-5`·`rounded-eds-radius-1` 등 EDS class를 쓰고, 그 밖에는 `var(--eds-color-*)`·`var(--eds-typography-*)` 또는 `cssVar("spacing-0.5")`를 씁니다.
15
+ 3. 색상·typography는 EDS token을 씁니다. sync한 Tailwind v4 root에서는 `text-eds-fg-*`·`bg-eds-bg-*`·`border-eds-stroke-*`·`eds-typography-*`, 그 밖에는 `var(--eds-color-*)`·`var(--eds-typography-*)` 또는 `cssVar()`를 씁니다. padding·margin·gap·radius에는 Tailwind v4 기본(`p-4`·`m-2`·`gap-3`·`rounded-lg`)을 권장합니다. EDS spacing·radius token은 없으며, Tailwind v4가 없으면 소비처 CSS 규칙을 따릅니다. `TOKEN_CONTEXT.md`를 따릅니다.
16
16
  4. raw 색상·typography 값, 비공개 CSS variable, 패키지 비공개 경로는 쓰지 않습니다. EDS component의 `className`은 바깥 배치에만 씁니다.
17
17
  5. Tailwind를 쓰는 저장소에서는 EDS 밖 요소도 `className`으로 쓰고, `index.css` 같은 전역 CSS에 컴포넌트별 규칙을 추가하지 않습니다.
18
18
 
@@ -20,13 +20,13 @@
20
20
 
21
21
  ## 완료 기준
22
22
 
23
- 1. `npm run eds:doctor`가 `[EDS] synced with`를 출력해야 합니다. 실패하면 각 줄의 조치(`unknown:` 포함)를 따라 `scripts:` → sync → 나머지 순서로 고칩니다. 자세한 절차는 `CONSUMER_AGENT.md`의 doctor 표를 따릅니다.
24
- 2. 있는 `typecheck`·`build` script는 exit 0이어야 합니다. 없는 script는 추가하지 말고 기존 검증 명령을 씁니다. EDS와 sync한 Tailwind CSS v4 root가 있을 때는 `npm run eds:doctor -- --scan`의 `raw:`에 바꾼 파일이 없어야 합니다.
25
- 3. 완료 보고에 변경 파일, EDS component·token, typecheck·build·doctor 결과를 적습니다. script가 없으면 그렇게 밝힙니다.
23
+ 1. 있는 `typecheck`·`build` script는 exit 0이어야 합니다. Tailwind CSS v4에서는 `eds:doctor -- --scan`의 `raw:`에 바꾼 파일이 없어야 합니다.
24
+ 2. 최종 검증 뒤 커밋 직전에 `npm run eds:doctor`를 실행해 `[EDS] synced with`를 확인합니다. 실패하면 `CONSUMER_AGENT.md` Doctor 표(`unknown:` 포함)의 조치를 따릅니다.
25
+ 3. 완료 보고에 변경 파일, EDS component·token, typecheck·build 결과와 doctor 결과를 적습니다. script가 없으면 그렇게 밝힙니다.
26
26
 
27
27
  ## 명령
28
28
 
29
- `npm run eds:doctor`는 읽기 전용 점검입니다. `npm run sync:eds`는 `AGENTS.md` managed block을 갱신하며, Tailwind CSS v4 root가 있으면 생성 CSS와 token alias도 갱신합니다. `npx @spectrabrain/eds init`은 기본 script 등록을 시도합니다. `typecheck`·`build` script가 있고 대응 hook이 없으면 `eds doctor` hook을 추가하며, 첫 sync도 실행합니다. runner는 소비처 형식으로 바꿉니다(`pnpm`·`yarn`·`bun run`, init은 `pnpm exec eds init`·`yarn eds init`·`bunx @spectrabrain/eds init`).
29
+ 직접 앱 설치의 허용된 postinstall은 첫 sync를 준비합니다. 에이전트는 UI 작업 시작에 `npm run sync:eds`를 한 번 실행합니다. marker가 없으면 설치 버전까지, 있으면 marker 이후의 `CHANGELOG.md` 소비처 조치를 적용한 뒤 sync합니다. 최신이면 `Already synced`로 끝납니다. 매 typecheck·build 전에는 실행하지 않습니다. Doctor는 읽기 전용이며 최종 검증 뒤 커밋 직전에만 실행합니다. postinstall이 생략되었거나 workspace root에서 설치했다면 소비 앱에서 패키지 매니저에 맞는 `init`을 실행합니다(`npx @spectrabrain/eds init`, `pnpm exec eds init`, `yarn eds init`, `bunx @spectrabrain/eds init`).
30
30
 
31
31
  ## 더 읽을 문서
32
32
 
package/README.md CHANGED
@@ -8,14 +8,15 @@ EVA 서비스의 일관된 UI/UX를 위한 React 웹 디자인 시스템입니
8
8
 
9
9
  ~~~sh
10
10
  npm install @spectrabrain/eds
11
- npx @spectrabrain/eds init
12
11
  ~~~
13
12
 
14
- `init`은 소비처 `package.json`에 `sync:eds`·`eds:doctor` 기본 script 등록을 시도합니다. `typecheck`·`build` script가 있으면 대응하는 doctor hook도 기존 hook이 없을 때만 등록한 뒤 첫 sync를 실행합니다. EDS를 업데이트한 뒤 `npm run sync:eds`로 `AGENTS.md` managed block을 갱신하고, Tailwind CSS v4 root가 있으면 CSS import·token alias도 갱신합니다. `npm run eds:doctor`로 동기화 상태를 확인합니다. pnpm·yarn·bun의 명령은 [CONSUMER_AGENT.md](CONSUMER_AGENT.md) 「첫 setup 절차」를 따릅니다. `npx`에는 항상 `@spectrabrain/eds`를 적습니다. npm의 unscoped `eds`는 다른 패키지입니다.
13
+ 허용된 postinstall은 직접 설치된 앱에서 첫 sync를 준비합니다. pnpm은 설치 중 `package.json` 변경을 보존하지 않으므로 script 등록은 첫 UI 작업의 sync로 미룹니다. EDS를 업데이트했을 때 설치 버전과 `AGENTS.md` marker가 다르거나 기존 block에 marker가 없으면 postinstall은 block을 보존해 AI 에이전트가 changelog 조치를 먼저 읽고 다음 UI 작업 시작에 sync하게 합니다. postinstall이 실행되지 않거나 dependency가 workspace root에 hoist된 경우에는 에이전트가 소비 앱에서 `init`으로 setup합니다. 소비처 사용자는 별도로 `sync:eds`를 실행하지 않습니다.
14
+
15
+ AI 에이전트는 UI 작업 시작에 한 번 `sync:eds`를 실행해 설치 버전과 managed block·생성 파일을 맞춥니다. 최신이면 파일을 쓰지 않습니다. Doctor는 typecheck·build에 연결하지 않고, 최종 검증 뒤 커밋 직전에 실행합니다. package manager별 fallback은 [CONSUMER_AGENT.md](CONSUMER_AGENT.md) 「첫 setup 절차」를 따릅니다. `npx`에는 항상 `@spectrabrain/eds`를 적습니다. npm의 unscoped `eds`는 다른 패키지입니다.
15
16
 
16
17
  소비처 AI와 자동화 도구는 UI 작업 전에 [QUICKSTART.md](QUICKSTART.md)를 읽습니다. 나머지 문서는 [AI_CONTEXT.json](AI_CONTEXT.json)의 조건에 해당할 때만 읽습니다.
17
18
 
18
- 첫 sync 전에 AI가 `QUICKSTART.md`를 읽게 하려면 사용하는 도구가 읽는 루트 지시 파일에 다음 한 줄을 임시로 넣습니다(Codex는 `AGENTS.md`, Claude Code는 `CLAUDE.md`, Gemini CLI는 `GEMINI.md`). sync가 managed block을 추가하면 임시 줄을 지웁니다. pnpm·yarn·bun에서는 `npm run`을 해당 runner로 바꿉니다.
19
+ postinstall이 실행되지 않은 저장소에서 에이전트가 EDS 지시를 읽지 못하면, 사용하는 도구의 루트 지시 파일에 아래 한 줄을 임시로 넣습니다(Codex는 `AGENTS.md`, Claude Code는 `CLAUDE.md`, Gemini CLI는 `GEMINI.md`). 에이전트가 `init`으로 managed block을 추가하면 임시 줄을 지웁니다.
19
20
 
20
21
  > package.json에 `@spectrabrain/eds`가 있으면 UI 작업 전에 EDS package root의 `QUICKSTART.md`를 읽고 규칙과 완료 기준을 따릅니다. package root는 `require.resolve("@spectrabrain/eds/package.json")`로 찾습니다.
21
22
 
@@ -24,11 +25,11 @@ npx @spectrabrain/eds init
24
25
  ## 현재 제공 범위
25
26
 
26
27
  - foreground, background, stroke 역할의 semantic color token을 제공합니다.
27
- - 소비처 로컬 UI에서도 사용할 수 있는 spacing·radius semantic scale을 제공합니다. public 이름의 소수점은 유지하며 Tailwind CSS v4에서는 CSS-safe alias를 제공합니다.
28
+ - 소비처 padding·margin·gap·radius token은 제공하지 않습니다. Tailwind CSS v4를 쓰는 앱에는 기본 utility(예: `p-4`, `rounded-lg`) 사용을 권장합니다.
28
29
  - Display, Heading, Title, Body, Caption semantic text style을 제공합니다. 각 style은 font family, weight, size, line height, letter spacing token으로 구성합니다.
29
30
  - `styles.css`에서 사용할 수 있는 Pretendard Variable v1.3.9 webfont를 제공합니다.
30
31
  - 자동완성을 지원하는 TypeScript token API와 CSS custom property를 제공합니다.
31
- - React `Button` 컴포넌트를 제공합니다. 이름으로 지정하는 lucide 아이콘은 승인된 allowlist로 제한합니다.
32
+ - React `Button` 컴포넌트를 제공합니다. 이름 슬롯은 설치된 `lucide-react`의 모든 아이콘 이름과 alias를 지원합니다.
32
33
  - 소비처 setup용 `eds` CLI(`npx @spectrabrain/eds init`, `npm run sync:eds`, `npm run eds:doctor`)를 제공합니다.
33
34
  - Vite + React 프로토타입을 EVA 프론트엔드 컨벤션에 맞추는 일회성 명령 `npx @spectrabrain/eds align`과 컨벤션 문서를 제공합니다.
34
35
 
@@ -49,7 +50,7 @@ export function SaveButton() {
49
50
  }
50
51
  ~~~
51
52
 
52
- 허용 role·variant 조합, `neutral/link`의 `href` 필수 조건, 이름 아이콘 allowlist와 ReactElement 슬롯, 접근성·loading 동작은 설치된 버전의 `@spectrabrain/eds/components/Button/README.md`와 `@spectrabrain/eds/components/Button/spec.json`(package root의 `dist/components/Button/`)이 기준입니다.
53
+ 허용 role·variant 조합, `neutral/link`의 `href` 필수 조건, 이름 아이콘과 ReactElement 슬롯, 접근성·loading 동작은 설치된 버전의 `@spectrabrain/eds/components/Button/README.md`와 `@spectrabrain/eds/components/Button/spec.json`(package root의 `dist/components/Button/`)이 기준입니다.
53
54
 
54
55
  ## 토큰 사용
55
56
 
@@ -63,8 +64,6 @@ const token: SemanticTokenName = "color-fg-brand-contrast";
63
64
  const color = cssVar(token); // var(--eds-color-fg-brand-contrast)
64
65
  ~~~
65
66
 
66
- `spacing-0.5`처럼 소수점이 있는 public 이름은 `cssVar("spacing-0.5")`로 전달합니다. 반환되는 CSS reference는 `var(--eds-spacing-0\.5)`처럼 점을 escape합니다. Tailwind CSS v4에서는 `p-eds-spacing-0-5`, `rounded-eds-radius-1` 같은 CSS-safe alias를 사용합니다.
67
-
68
67
  TypeScript의 `moduleResolution`이 `node`(node10), `node16` 또는 `bundler`인 소비처에서도 `@spectrabrain/eds/tokens`의 타입을 사용할 수 있습니다.
69
68
 
70
69
  역할에 맞는 exact token이 없을 때 가까운 공개 token을 고르는 순서는 [TOKEN_CONTEXT.md](TOKEN_CONTEXT.md)에 있습니다. 그래도 없으면 임의 색상값을 만들지 않고 디자인 시스템 담당자에게 요청합니다.
@@ -73,7 +72,7 @@ TypeScript의 `moduleResolution`이 `node`(node10), `node16` 또는 `bundler`인
73
72
 
74
73
  ## Tailwind CSS v4에서 token 사용
75
74
 
76
- EDS는 Tailwind preset·plugin을 제공하지 않습니다. Tailwind CSS v4 저장소에서는 `npm run sync:eds`가 `tokens.json`에서 `src/styles/eds-tokens.css`를 생성해 `@import "tailwindcss"`가 있는 Tailwind root CSS에 연결합니다. 이 파일에서 `text-eds-fg-*`, `bg-eds-bg-*`, `border-eds-stroke-*`, `eds-typography-*`, `p-eds-spacing-0-5`, `rounded-eds-radius-1` class를 사용할 수 있습니다. 일반 Tailwind utility는 소비처 설정에 따라 함께 쓸 수 있습니다. 생성된 `@theme inline`에는 `--font-sans: var(--eds-typography-body1-fontFamily);`도 들어가므로 Tailwind의 기본 sans font가 Pretendard가 됩니다. 설정 방법은 [Tailwind CSS v4 token 설정 가이드](./TAILWIND_V4.md)를 확인합니다.
75
+ EDS는 Tailwind preset·plugin을 제공하지 않습니다. Tailwind CSS v4 저장소에서는 `npm run sync:eds`가 `tokens.json`에서 `src/styles/eds-tokens.css`를 생성해 `@import "tailwindcss"`가 있는 Tailwind root CSS에 연결합니다. 이 파일에서 `text-eds-fg-*`, `bg-eds-bg-*`, `border-eds-stroke-*`, `eds-typography-*` class를 사용할 수 있습니다. padding·margin·gap·radius에는 Tailwind CSS v4 기본 utility를 씁니다. 생성된 `@theme inline`에는 `--font-sans: var(--eds-typography-body1-fontFamily);`도 들어가므로 Tailwind의 기본 sans font가 Pretendard가 됩니다. 설정 방법은 [Tailwind CSS v4 token 설정 가이드](./TAILWIND_V4.md)를 확인합니다.
77
76
 
78
77
  ## Text style 사용
79
78
 
@@ -115,7 +114,7 @@ EDS는 Tailwind preset·plugin을 제공하지 않습니다. Tailwind CSS v4 저
115
114
  | `@spectrabrain/eds/TOKEN_CONTEXT.md` | semantic token의 역할과 화면 맥락입니다. |
116
115
  | `@spectrabrain/eds/TAILWIND_V4.md` | Tailwind CSS v4에서 공개 token을 연결하는 설치 가이드입니다. |
117
116
  | `@spectrabrain/eds/FRONTEND_CONVENTIONS.md` | EVA 프론트엔드의 구조·라이브러리·코드 패턴·개발 규칙입니다. `eds align`의 기준입니다. |
118
- | `eds` CLI (`npx @spectrabrain/eds init`) | 소비처 setup CLI입니다. `init`은 기본 script 등록을 시도하고 첫 동기화를 실행합니다. `npm run sync:eds`는 동기화합니다. `npm run eds:doctor`는 동기화 상태와 font import를 읽기 전용 점검하고, Tailwind CSS v4 root가 있으면 `eds-*` class 이름도 확인합니다. `npx @spectrabrain/eds align`은 프로토타입 정렬 계획과 점검을 실행합니다. 모듈로 import하지 않습니다. |
117
+ | `eds` CLI (`npx @spectrabrain/eds init`) | 소비처 setup CLI입니다. `init`은 기본 script를 등록하고 첫 동기화를 실행합니다. 에이전트는 UI 작업 전에 `sync:eds`를 한 번 실행합니다. `eds:doctor`는 커밋 직전에 동기화 상태와 font import를 읽기 전용 점검하고, Tailwind CSS v4 root가 있으면 `eds-*` class 이름도 확인합니다. `npx @spectrabrain/eds align`은 프로토타입 정렬 계획과 점검을 실행합니다. 모듈로 import하지 않습니다. |
119
118
  | `@spectrabrain/eds/components/Button/README.md` | Button 개요·사용 맥락·공개 API 문서입니다. |
120
119
  | `@spectrabrain/eds/components/Button/spec.json` | Button 공개 API와 접근성 계약을 위한 manifest입니다. |
121
120
  | `@spectrabrain/eds/llms.txt` | AI 문서 읽기 순서입니다. |
package/TAILWIND_V4.md CHANGED
@@ -10,7 +10,7 @@ CSS 진입점은 `@spectrabrain/eds/styles.css` 하나를 권장합니다. 개
10
10
 
11
11
  1. 「adapter 선택」 표에서 저장소에 맞는 행 하나를 골라 설치하고 연결합니다.
12
12
  2. 기존 앱 전역 CSS를 Tailwind root로 씁니다. 전체 import 구성은 `@import "tailwindcss";`를, 분할 구성은 `@import "tailwindcss/theme.css";`와 `@import "tailwindcss/utilities.css";`를 같은 파일에 둡니다.
13
- 3. `npm run sync:eds`를 실행합니다. script가 없으면 `npx @spectrabrain/eds init`을 실행합니다(패키지 매니저별 명령은 `CONSUMER_AGENT.md` 「첫 setup 절차」). init을 2단계보다 먼저 실행했다면 2단계 뒤에 sync를 다시 실행합니다.
13
+ 3. 직접 앱 설치에서 허용된 postinstall이 첫 sync를 하지 않았다면 AI 에이전트가 `npm run sync:eds`를 실행합니다. script가 없으면 `CONSUMER_AGENT.md` 「첫 setup 절차」의 `init` 명령(예: `npx @spectrabrain/eds init`)을 사용합니다. EDS 업데이트 뒤에는 changelog 조치를 적용하고 UI 작업 시작에 한 번 sync합니다.
14
14
  4. 「완료 기준」을 확인합니다.
15
15
 
16
16
  CSS가 `@tailwind` 지시어를 쓰는 Tailwind CSS v3 저장소는 이 절차 대신 `CONSUMER_AGENT.md` 「Tailwind root 결정」을 따릅니다.
@@ -66,8 +66,6 @@ sync는 설치된 package의 공개 `@spectrabrain/eds/tokens.json`에서 token
66
66
  /* Generated from @spectrabrain/eds@<version>. Do not edit manually. */
67
67
  @theme inline {
68
68
  --color-eds-fg-brand: var(--eds-color-fg-brand);
69
- --spacing-eds-spacing-0-5: var(--eds-spacing-0\.5);
70
- --radius-eds-radius-1: var(--eds-radius-1);
71
69
  --font-sans: var(--eds-typography-body1-fontFamily);
72
70
  }
73
71
 
@@ -81,10 +79,10 @@ sync는 설치된 package의 공개 `@spectrabrain/eds/tokens.json`에서 token
81
79
  ```
82
80
 
83
81
  - `--font-sans`는 `@theme inline`의 마지막 줄이며 Tailwind의 기본 sans font를 EDS body1 font family로 바꿉니다.
84
- - 공개 spacing·radius token은 Tailwind CSS-safe alias로 연결합니다. `spacing-0.5`는 `p-eds-spacing-0-5`, `radius-1`은 `rounded-eds-radius-1`처럼 사용합니다. alias의 점은 `-`로 바뀌며, 생성 CSS의 `var(--eds-spacing-0\.5)`에서만 점을 escape합니다.
82
+ - padding·margin·gap·radius에는 Tailwind CSS v4 기본 utility를 씁니다. 예: `p-4`, `m-2`, `gap-3`, `rounded-lg`. EDS token 별칭은 색상과 typography에만 생성합니다. 선택 기준은 `TOKEN_CONTEXT.md`를 따릅니다.
85
83
  - `@theme`의 EDS alias는 sync가 생성한 `var(--eds-*)` 참조만 두고, EDS를 업데이트할 때마다 `npm run sync:eds`로 다시 생성합니다.
86
84
  - `eds-tokens.css`는 `@theme`·`@utility`를 담으므로 Tailwind root CSS에서만 import합니다. `@spectrabrain/eds/styles.css`와 `eds-tokens.css`는 각각 한 곳에서만 import합니다.
87
- - `src/styles/eds-tokens.css`는 생성물이지만 저장소에 commit합니다. install은 이 파일을 만들지 않으므로, 파일이 없으면 Tailwind root의 `@import`가 깨지고, `pretypecheck`·`prebuild` hook(yarn berry는 `typecheck`·`build` 앞의 `eds doctor`)과 `--print-ci` CI job의 `eds doctor`가 `missing:`으로 실패합니다.
85
+ - `src/styles/eds-tokens.css`는 생성물이지만 저장소에 commit합니다. 설치 postinstall이나 에이전트의 UI 작업 시작 sync가 파일을 만듭니다. 커밋 전 doctor나 `--print-ci` CI job은 파일이 없으면 `missing:`으로 실패합니다. Doctor는 typecheck·build에는 연결되지 않습니다.
88
86
 
89
87
  ## Tailwind root 지정
90
88
 
@@ -96,7 +94,7 @@ EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds
96
94
 
97
95
  ## 완료 기준
98
96
 
99
- 1. `npm run eds:doctor`가 `[EDS] synced with` 줄을 출력하고, 출력에 `No Tailwind root CSS found`·`Tailwind CSS v3 detected` note가 없습니다.
97
+ 1. 커밋 직전 `npm run eds:doctor`가 `[EDS] synced with` 줄을 출력하고, 출력에 `No Tailwind root CSS found`·`Tailwind CSS v3 detected` note가 없습니다.
100
98
  2. Vite 저장소는 `vite.config.*`의 `plugins`에 `@tailwindcss/vite`의 `tailwindcss()`가 있고, 그 밖의 저장소는 PostCSS 설정에 `@tailwindcss/postcss`가 있습니다. doctor는 이 연결을 점검하지 않습니다.
101
99
  3. `@spectrabrain/eds/styles.css`는 Tailwind root CSS나 앱 진입점 가운데 한 곳에서만 import됩니다.
102
100
 
package/TOKEN_CONTEXT.md CHANGED
@@ -90,25 +90,9 @@ import { cssVar } from "@spectrabrain/eds/tokens";
90
90
 
91
91
  ## Spacing과 radius
92
92
 
93
- 소비처 로컬 UI와 EDS component 밖의 배치에는 공개 spacing·radius token을 씁니다. 현재 scale 전체를 공개하며, 이름의 소수점은 유지합니다.
94
-
95
- - spacing: `spacing-none`, `spacing-0.5`, `spacing-1`, `spacing-1.5`, `spacing-2`, `spacing-2.5`, `spacing-3`, `spacing-3.5`, `spacing-4`, `spacing-4.5`, `spacing-5`, `spacing-6`, `spacing-7`, `spacing-7.5`, `spacing-8`, `spacing-9`, `spacing-10`, `spacing-11`, `spacing-12`
96
- - radius: `radius-none`, `radius-1`, `radius-2`, `radius-3`, `radius-4`, `radius-5`, `radius-6`, `radius-7`, `radius-8`, `radius-9`, `radius-10`
97
-
98
- EDS와 sync한 Tailwind CSS v4 root가 있는 저장소에서는 CSS-safe alias를 사용합니다. `spacing-0.5`는 `p-eds-spacing-0-5`, `radius-1`은 `rounded-eds-radius-1`처럼 씁니다. `0.5`·`1.5`·`2.5`·`3.5`·`4.5`·`7.5`의 점은 alias에서 `-`로 바뀝니다.
99
-
100
- Tailwind CSS v4 alias를 사용하지 않는 저장소에서는 `@spectrabrain/eds/tokens`의 `SemanticTokenName` 자동완성과 `cssVar()`를 사용합니다. public 이름은 `spacing-0.5`로 전달하고, CSS reference에서만 점이 escape됩니다.
101
-
102
- ```tsx
103
- import { cssVar } from "@spectrabrain/eds/tokens";
104
-
105
- <div style={{ padding: cssVar("spacing-0.5"), borderRadius: cssVar("radius-1") }}>…</div>;
106
- // var(--eds-spacing-0\.5), var(--eds-radius-1)
107
- ```
108
-
109
- 직접 CSS를 쓸 때도 `tokens.json`의 `tokens.<name>.$extensions.eds.cssVariable` mapping을 따릅니다. CSS custom property 선언과 `var()` reference에서만 `.`을 escape하며, public token 이름은 바꾸지 않습니다.
93
+ padding, margin, gap, radius에는 Tailwind CSS v4 기본 utility를 권장합니다(예: `p-4`, `m-2`, `gap-3`, `rounded-lg`). EDS는 spacing·radius token과 utility를 제공하지 않습니다. Tailwind CSS v4를 쓰지 않는 소비처는 기존 CSS 규칙을 따릅니다.
110
94
 
111
95
  ## 확인 목록
112
96
 
113
- - 새로 쓴 CSS variable이 `tokens.json`의 `cssVariable` mapping과 일치하는지 확인합니다. dotted public name은 `var(--eds-spacing-0\.5)`처럼 CSS reference에서만 escape합니다. `eds doctor`는 Tailwind CSS v4 root가 있을 때만 `eds-*` class를 검사하고, typecheck는 `cssVar()` 인자를 검사합니다.
97
+ - 공개 CSS variable은 설치된 `tokens.json`의 `cssVariable` mapping을 따릅니다. `eds doctor`는 Tailwind CSS v4 root가 있을 때만 `eds-*` class를 검사하고, typecheck는 `cssVar()` 인자를 검사합니다.
114
98
  - typography는 preset 하나(`eds-typography-*` class 또는 같은 preset의 변수 다섯 개)로 지정합니다.
package/consumer/align-plan.mjs CHANGED
@@ -643,8 +643,6 @@ export function renderPlan({
643
643
  ]),
644
644
  "",
645
645
  "완료 기준: " +
646
- code(commands.run("eds:doctor")) +
647
- "가 `[EDS] synced with` 줄을 출력하고 " +
648
646
  code(commands.run("build")) +
649
647
  "가 exit 0이며, Vite가 " +
650
648
  minimumVersions.vite +
@@ -692,7 +690,7 @@ export function renderPlan({
692
690
  " - `components.json`: `aliases`와 `tailwind.css`만 템플릿 값으로 바꾸고 `style`·`baseColor`는 유지합니다.",
693
691
  " - `package.json` scripts: `package.scripts.json`에서 없는 script만 추가하고, 추가한 뒤 " +
694
692
  code(commands.eds("init --no-sync")) +
695
- "로 `pretypecheck`·`prebuild` hook을 등록합니다. backend를 실행하는 script는 바꾸지 않습니다.",
693
+ "로 `sync:eds`·`eds:doctor`를 등록합니다. typecheck·build script에는 Doctor를 넣지 않습니다. backend를 실행하는 script는 바꾸지 않습니다.",
696
694
  " - 이전 lint·format 설정(`.eslintrc*`, `biome.json`, 중복 Prettier 설정)은 규칙을 옮긴 뒤 정리합니다" +
697
695
  (replacedCategories.has("lint-format") ? "(패키지 제거는 4단계)." : ".") +
698
696
  " 테스트·mock·다국어 파일과 설정은 그대로 둡니다. 기준선에 있던 항목을 바꾸지 않고 적용할 수 없으면 멈추고 사용자에게 확인합니다.",
@@ -714,11 +712,8 @@ export function renderPlan({
714
712
  ]
715
713
  .map(code)
716
714
  .join("·") +
717
- "가 exit 0입니다. 기존 `build.outDir`·`base`·`server.proxy`가 병합 전과 같고, " +
718
- (packageManager.berry
719
- ? "`typecheck` script가 `eds doctor && `로 시작하며"
720
- : "`package.json`의 `pretypecheck`가 `eds doctor`를 실행하며") +
721
- ", 「기준선」에 typecheck·lint 결과가 있습니다.",
715
+ "가 exit 0입니다. 기존 `build.outDir`·`base`·`server.proxy`가 병합 전과 같고, typecheck·build script에는 Doctor를 연결하지 않습니다. " +
716
+ "「기준선」에 typecheck·lint 결과가 있습니다.",
722
717
  "",
723
718
  "### 4. 라이브러리 정렬",
724
719
  "",
@@ -846,12 +841,11 @@ export function renderPlan({
846
841
  commands.run("lint"),
847
842
  commands.run("typecheck"),
848
843
  commands.run("build"),
849
- commands.run("eds:doctor"),
850
844
  alignCheck,
851
845
  ]
852
846
  .map(code)
853
847
  .join(", ") +
854
- "을 실행해 모두 exit 0이고 " +
848
+ "을 실행해 모두 exit 0인지 확인합니다. Doctor는 커밋 직전에 마지막으로 실행해 " +
855
849
  code(commands.run("eds:doctor")) +
856
850
  "가 `[EDS] synced with` 줄을 출력하는지 확인합니다.",
857
851
  backendImportsViteConfig && backendStartScript !== null
package/consumer/align.mjs CHANGED
@@ -375,7 +375,7 @@ function conventionsPathFrom(packageDirectory, gitRoot, packageRoot) {
375
375
  }
376
376
 
377
377
  function verificationCommands(commands) {
378
- return ["format:check", "lint", "typecheck", "build", "eds:doctor"]
378
+ return ["format:check", "lint", "typecheck", "build"]
379
379
  .map((script) => commands.run(script))
380
380
  .join(", ");
381
381
  }
@@ -899,10 +899,12 @@ function runCheck({
899
899
  log(
900
900
  "[EDS] Also required: " +
901
901
  verificationCommands(commands) +
902
- " (each must exit 0, and eds:doctor must print [EDS] synced with)" +
902
+ " (each must exit 0). Before committing, run " +
903
+ commands.run("eds:doctor") +
904
+ " and confirm [EDS] synced with" +
903
905
  (state === null
904
906
  ? "."
905
- : ", then step 8 of " +
907
+ : ". Then complete step 8 of " +
906
908
  shown(alignDirectory + "/" + planFileName) +
907
909
  ".")
908
910
  );
package/consumer/cli.mjs CHANGED
@@ -8,9 +8,9 @@ const usage = [
8
8
  "Usage: eds <command> [options]",
9
9
  "",
10
10
  "Commands:",
11
- " init Add sync:eds and eds:doctor when missing; add pretypecheck/prebuild when target scripts exist",
12
- " and hooks are missing; write allowScripts on npm 12+, then sync in the package declaring @spectrabrain/eds",
13
- " sync Generate src/styles/eds-tokens.css, wire the Tailwind root CSS and update AGENTS.md",
11
+ " init Add sync:eds and eds:doctor when missing; remove obsolete Doctor lifecycle commands;",
12
+ " write allowScripts on npm 12+, then sync in the package declaring @spectrabrain/eds",
13
+ " sync Ensure EDS scripts, remove old Doctor lifecycle commands, wire Tailwind CSS and update AGENTS.md",
14
14
  " and the @AGENTS.md import in CLAUDE.md (or .claude/CLAUDE.md) and GEMINI.md when they exist",
15
15
  " (without a Tailwind root only those change); notes say when an agent may not load the block",
16
16
  " doctor Check sync status and the EDS font import; with a Tailwind CSS v4 root, also check that each eds-*",
@@ -20,8 +20,8 @@ const usage = [
20
20
  "",
21
21
  "Options:",
22
22
  " --only tailwind|agents sync: apply only that part",
23
- " --dry-run Print the files sync, init or align would write without writing them",
24
- " --no-sync init: register scripts only",
23
+ " --dry-run Print files and package scripts sync, init or align would change without writing them",
24
+ " --no-sync init: skip file sync but still register and migrate scripts",
25
25
  " --no-allow-scripts init: do not write allowScripts to package.json on npm 12+",
26
26
  " --print-ci github|gitlab init: print a CI job that runs eds doctor with this repository's package manager",
27
27
  " --warn doctor: report findings but exit 0 (same as EDS_DOCTOR=warn)",
@@ -33,7 +33,7 @@ const usage = [
33
33
  "",
34
34
  "Environment:",
35
35
  " EDS_TAILWIND_ROOT=src/index.css Tailwind root CSS when it cannot be detected (needed once: sync records",
36
- " it in package.json \"eds\": { \"tailwindRoot\" }, which doctor and the hooks reuse)",
36
+ " it in package.json \"eds\": { \"tailwindRoot\" }, which sync and doctor reuse)",
37
37
  " EDS_DOCTOR=warn|off Downgrade or silence doctor failures",
38
38
  ].join("\n");
39
39