@spectrabrain/eds 0.3.0 → 0.3.1
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.
- package/AI.md +3 -3
- package/AI_CONTEXT.json +7 -8
- package/CHANGELOG.md +34 -16
- package/CONSUMER_AGENT.md +65 -55
- package/FRONTEND_CONVENTIONS.md +27 -32
- package/QUICKSTART.md +19 -28
- package/README.md +11 -9
- package/TAILWIND_V4.md +4 -2
- package/TOKEN_CONTEXT.md +7 -7
- package/consumer/align/templates/package.scripts.json +0 -1
- package/consumer/align/templates/src/app/main.tsx +9 -19
- package/consumer/align/templates/vite.config.rolldown.ts +1 -1
- package/consumer/align-analysis.mjs +1712 -299
- package/consumer/align-plan.mjs +647 -139
- package/consumer/align-rules.mjs +59 -23
- package/consumer/align.mjs +639 -103
- package/consumer/cli.mjs +7 -7
- package/dist/components/Button/README.md +1 -1
- package/dist/components/Button/spec.json +2 -2
- package/dist/components.css +1 -1
- package/llms.txt +6 -8
- package/package.json +1 -1
- package/consumer/align/templates/env.mock +0 -1
- package/consumer/align/templates/src/mocks/browser.ts +0 -5
- package/consumer/align/templates/src/mocks/handlers.ts +0 -4
package/AI.md
CHANGED
|
@@ -1,17 +1,17 @@
|
|
|
1
1
|
# EVA Design System — 공개 범위와 사용 경계
|
|
2
2
|
|
|
3
|
-
요청이 EDS 공개 범위 밖의 기능(dark theme,
|
|
3
|
+
요청이 EDS 공개 범위 밖의 기능(dark theme, 생성 CSS에 없는 EDS token alias, 목록에 없는 컴포넌트)을 요구할 때 읽습니다. 일반 Tailwind utility는 소비처 설정에 따라 사용할 수 있습니다. 규칙과 명령은 [QUICKSTART.md](QUICKSTART.md), setup은 [CONSUMER_AGENT.md](CONSUMER_AGENT.md)에 있습니다.
|
|
4
4
|
|
|
5
5
|
## 공개 범위
|
|
6
6
|
|
|
7
7
|
- light theme, `AI_CONTEXT.json`의 `components`에 있는 컴포넌트(현재 `Button`), 공개 semantic color·typography·spacing·radius token과 token runtime API(`@spectrabrain/eds/tokens`)를 제공합니다.
|
|
8
|
-
- 패키지는 Tailwind preset·plugin
|
|
8
|
+
- 패키지는 Tailwind preset·plugin을 export하지 않습니다. `eds sync`는 공개 semantic token alias를 `src/styles/eds-tokens.css`에 추가합니다. 일반 Tailwind utility는 소비처 설정에 따라 함께 쓸 수 있습니다.
|
|
9
9
|
- dark theme과 목록 밖 컴포넌트는 지원 범위 밖입니다. EDS component가 없거나 필요한 prop·variant·state·slot contract가 맞지 않으면 소비처에서 로컬 UI를 구현하고, 공개 token으로 색상·typography·spacing·radius를 지정합니다.
|
|
10
10
|
- CSS 진입점 구성은 `CONSUMER_AGENT.md` 「font 정책」을 따릅니다.
|
|
11
11
|
|
|
12
12
|
## 사용 경계
|
|
13
13
|
|
|
14
|
-
- 문서·`spec.json`·`tokens.json`에 있는 API·prop·variant·token·export 경로만 씁니다. component
|
|
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
16
|
- 이름으로 지정하는 아이콘은 allowlist(`spec.json`의 `api.iconNames`)만 받고, 목록 밖 아이콘은 ReactElement 슬롯으로 전달합니다. 버전 선언과 보고 방법은 `dist/components/Button/README.md` 「Layout과 아이콘」에 있습니다.
|
|
17
17
|
|
package/AI_CONTEXT.json
CHANGED
|
@@ -3,9 +3,7 @@
|
|
|
3
3
|
"package": "@spectrabrain/eds",
|
|
4
4
|
"purpose": "consumer-ai-routing",
|
|
5
5
|
"pathConvention": "readOrder[].file is relative to the package root returned by require.resolve(\"@spectrabrain/eds/package.json\"); readOrder[].specifier is the export subpath for require.resolve or import; {name} expands to each entry of components. Rules and commands live in QUICKSTART.md, setup and CLI behavior in CONSUMER_AGENT.md.",
|
|
6
|
-
"components": [
|
|
7
|
-
"Button"
|
|
8
|
-
],
|
|
6
|
+
"components": ["Button"],
|
|
9
7
|
"readOrder": [
|
|
10
8
|
{
|
|
11
9
|
"file": "QUICKSTART.md",
|
|
@@ -18,14 +16,14 @@
|
|
|
18
16
|
"specifier": "@spectrabrain/eds/CONSUMER_AGENT.md",
|
|
19
17
|
"kind": "setup-contract",
|
|
20
18
|
"required": false,
|
|
21
|
-
"when": "First setup: the consumer AGENTS.md has no <!-- EDS:BEGIN --> block; eds
|
|
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)"
|
|
22
20
|
},
|
|
23
21
|
{
|
|
24
22
|
"file": "AI.md",
|
|
25
23
|
"specifier": "@spectrabrain/eds/AI.md",
|
|
26
24
|
"kind": "scope-and-boundaries",
|
|
27
25
|
"required": false,
|
|
28
|
-
"when": "The request needs dark theme,
|
|
26
|
+
"when": "The request needs dark theme, an EDS Tailwind plugin, an EDS token utility alias missing from the generated CSS, or a component not listed in components"
|
|
29
27
|
},
|
|
30
28
|
{
|
|
31
29
|
"file": "TOKEN_CONTEXT.md",
|
|
@@ -53,14 +51,14 @@
|
|
|
53
51
|
"specifier": "@spectrabrain/eds/tokens.json",
|
|
54
52
|
"kind": "token-manifest",
|
|
55
53
|
"required": false,
|
|
56
|
-
"when": "A tool or script needs the machine-readable token manifest and public name-to-CSS-variable mapping, or an agent checks a CSS variable name for var() without Tailwind; class names
|
|
54
|
+
"when": "A tool or script needs the machine-readable token manifest and public name-to-CSS-variable mapping, or an agent checks a CSS variable name for var() without Tailwind; for a synced Tailwind CSS v4 root, generated class names are in the consumer's src/styles/eds-tokens.css"
|
|
57
55
|
},
|
|
58
56
|
{
|
|
59
57
|
"file": "dist/components/{name}/README.md",
|
|
60
58
|
"specifier": "@spectrabrain/eds/components/{name}/README.md",
|
|
61
59
|
"kind": "component-guide",
|
|
62
60
|
"required": false,
|
|
63
|
-
"when": "
|
|
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."
|
|
64
62
|
},
|
|
65
63
|
{
|
|
66
64
|
"file": "dist/components/{name}/spec.json",
|
|
@@ -80,11 +78,12 @@
|
|
|
80
78
|
"precedence": [
|
|
81
79
|
"user-requirements",
|
|
82
80
|
"accessibility-security-and-framework-constraints",
|
|
81
|
+
"consumer-product-requirements",
|
|
83
82
|
"eds-component-preference",
|
|
84
83
|
"consumer-repository-rules",
|
|
85
84
|
"eds-json-manifest-and-typescript-contract",
|
|
86
85
|
"eds-usage-guides",
|
|
87
86
|
"examples"
|
|
88
87
|
],
|
|
89
|
-
"precedenceNote": "
|
|
88
|
+
"precedenceNote": "Follow QUICKSTART.md: the user's explicit request, accessibility, security, and framework constraints, then documented consumer product requirements. Satisfy them before preferring an EDS component. A consumer repository rule has that priority only when it states one of those requirements; style conventions apply after component choice. Once selected, JSON manifests and TypeScript contracts define the public API, which repository style rules cannot expand."
|
|
90
89
|
}
|
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,25 @@
|
|
|
1
1
|
# @spectrabrain/eds
|
|
2
2
|
|
|
3
|
+
## 0.3.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 4d6c64e: 소비처 조치: 진행 중인 `.eds/align/PLAN.md`가 있으면 `CONSUMER_AGENT.md` 「프로토타입 정렬」에 따라 다시 생성합니다.
|
|
8
|
+
|
|
9
|
+
`eds align`은 mock 설정이나 파일 이동을 추가하지 않고 기존 test·mock·다국어 파일과 설정을 보존합니다.
|
|
10
|
+
|
|
11
|
+
- 96dfdcf: 소비처 조치: `package.json`의 Vite 범위를 Vite 5.2.0 이상 단일 major로 좁힌 뒤 `npx @spectrabrain/eds align`을 실행합니다. 예를 들어 Vite 5는 `^5.2.0`, Vite 8은 `^8.0.0`으로 선언합니다. 완료 확인: 범위 오류 없이 `.eds/align/PLAN.md`가 생성됩니다.
|
|
12
|
+
|
|
13
|
+
`eds align`은 선언된 Vite 범위가 지원되는 단일 major를 보장하지 않거나 설치된 major와 일치하지 않으면 계획 생성을 중단합니다.
|
|
14
|
+
|
|
15
|
+
- b573101: 소비처 조치: 없습니다.
|
|
16
|
+
|
|
17
|
+
Button loading progress가 `prefers-reduced-motion: reduce` 설정에서 회전하지 않도록 수정합니다.
|
|
18
|
+
|
|
19
|
+
- 3a1f859: 소비처 조치: 없습니다.
|
|
20
|
+
|
|
21
|
+
소비처 AI 문서의 기준과 읽기 경로를 간결하게 정리합니다. 설치 동작, 공개 API와 token 값은 바뀌지 않습니다.
|
|
22
|
+
|
|
3
23
|
## 0.3.0
|
|
4
24
|
|
|
5
25
|
### Minor Changes
|
|
@@ -24,11 +44,9 @@
|
|
|
24
44
|
|
|
25
45
|
### Patch Changes
|
|
26
46
|
|
|
27
|
-
- 소비처 조치: 업데이트 뒤 `npm run sync:eds`를 실행해 spacing·radius Tailwind alias를
|
|
28
|
-
|
|
29
|
-
공개 semantic token에 현재 spacing·radius scale 전체를 추가했습니다. `spacing-0.5`처럼 소수점이 있는 public 이름은 TypeScript 자동완성과 `tokens.json`의 CSS variable mapping을 유지하며, CSS reference에서만 점을 escape합니다. Tailwind에서는 `p-eds-spacing-0-5`, `rounded-eds-radius-1` 같은 CSS-safe alias를 생성합니다. EDS component가 없거나 contract가 맞지 않는 화면은 소비처 로컬 UI로 구현하고 공개 token을 사용하도록 AI 문서와 검사를 맞췄습니다.
|
|
47
|
+
- 소비처 조치: 업데이트 뒤 `npm run sync:eds`를 실행해 spacing·radius Tailwind alias를 생성합니다.
|
|
30
48
|
|
|
31
|
-
|
|
49
|
+
공개 semantic token에 spacing·radius scale을 추가했습니다. `spacing-0.5`처럼 소수점이 있는 이름은 유지하며, CSS 참조에서 점을 escape하고 Tailwind에는 `p-eds-spacing-0-5`·`rounded-eds-radius-1` alias를 생성합니다.
|
|
32
50
|
|
|
33
51
|
## 0.1.1
|
|
34
52
|
|
|
@@ -36,7 +54,7 @@
|
|
|
36
54
|
|
|
37
55
|
- 190c1d1: 소비처 조치: 업데이트 뒤 sync가 `note:` 줄을 출력하면 그 안내대로 지시 파일을 만들거나 루트 지시 파일에 안내 문장을 넣습니다.
|
|
38
56
|
|
|
39
|
-
sync와 doctor는 managed block이 에이전트에게 전달되지 않을 수 있는 경우(Claude Code·Gemini CLI 지시 파일 없음, `CLAUDE.local.md`만 있음, `AGENTS.override.md`, block이 Codex 기본 32 KiB 밖, monorepo 하위 package)를 exit code에 영향이 없는 `note:`로 알립니다. sync는 `CLAUDE.md` 없이 `.claude/CLAUDE.md`만 있으면 그 파일에 `@../AGENTS.md` import를 넣습니다. managed block은 UI
|
|
57
|
+
sync와 doctor는 managed block이 에이전트에게 전달되지 않을 수 있는 경우(Claude Code·Gemini CLI 지시 파일 없음, `CLAUDE.local.md`만 있음, `AGENTS.override.md`, block이 Codex 기본 32 KiB 밖, monorepo 하위 package)를 exit code에 영향이 없는 `note:`로 알립니다. sync는 `CLAUDE.md` 없이 `.claude/CLAUDE.md`만 있으면 그 파일에 `@../AGENTS.md` import를 넣습니다. managed block은 UI 작업 전에 `QUICKSTART.md`를 읽게 하고, 완료 기준을 `[EDS] synced with` 줄로 바꿉니다.
|
|
40
58
|
|
|
41
59
|
- 4ba9fb9: 소비처 조치: `grep -rn -- '--eds-button-' src`로 내부 변수 참조를 찾습니다. 참조가 있으면 색은 `--eds-color-*`, 글자는 `--eds-typography-*`로 바꾸고, 높이·간격·모서리는 Button의 `size` prop으로 맞춥니다. 참조가 없으면 할 일이 없습니다.
|
|
42
60
|
|
|
@@ -64,9 +82,9 @@
|
|
|
64
82
|
|
|
65
83
|
- 8a58208: 소비처 조치: 없습니다.
|
|
66
84
|
|
|
67
|
-
managed block과 소비처 AI 문서를 다시
|
|
85
|
+
managed block과 소비처 AI 문서를 다시 써 사용자 요청 우선순위, token 사용, Button 선택 기준을 안내합니다. 공개 API·token 값·CLI 명령·exit code는 바뀌지 않습니다.
|
|
68
86
|
|
|
69
|
-
- 2163c44: 소비처 조치: `AI_CONTEXT.json`을 코드로 읽는 도구가 있다면 `schemaVersion` 2에 맞춥니다. `
|
|
87
|
+
- 2163c44: 소비처 조치: `AI_CONTEXT.json`을 코드로 읽는 도구가 있다면 `schemaVersion` 2에 맞춥니다. `readOrder`는 package root 경로, export subpath, 문서 유형과 읽기 조건을 제공합니다. UI 작업 규칙과 기본 명령은 `QUICKSTART.md`, setup·CLI 세부사항은 `CONSUMER_AGENT.md`를 따릅니다.
|
|
70
88
|
|
|
71
89
|
`QUICKSTART.md`는 「규칙」, 「완료 기준」, 「명령」, 「더 읽을 문서」로 다시 나누고, EDS 컴포넌트의 `className`은 바깥 배치(margin·정렬·grid 위치)에만 쓴다고 명시합니다. `eds doctor`의 마지막 안내는 `QUICKSTART.md` 「완료 기준」을 가리킵니다. `llms.txt`·`AI.md`·`README.md`는 라우팅을 `AI_CONTEXT.json`의 `when` 조건과 맞추고, `TOKEN_CONTEXT.md`는 `cssVar()` 예시를, Button README는 직접 import하는 `lucide-react` 버전을 찾는 위치를 담습니다.
|
|
72
90
|
|
|
@@ -76,7 +94,7 @@
|
|
|
76
94
|
|
|
77
95
|
- efe0076: 소비처 조치: 없습니다. 사용자가 프로토타입 정렬을 요청할 때만 실행하며 `init`·`sync`·`doctor` 동작은 바뀌지 않습니다.
|
|
78
96
|
|
|
79
|
-
`eds align`과 `eds align --check`, 새 공개 문서 `FRONTEND_CONVENTIONS.md`를 추가했습니다.
|
|
97
|
+
`eds align`과 `eds align --check`, 새 공개 문서 `FRONTEND_CONVENTIONS.md`를 추가했습니다. `align`은 소스를 바꾸지 않고 `.eds/align/`에 계획과 템플릿을 만들며, `--check`는 컨벤션과 `.eds/align/state.json`이 있을 때 기준 commit 이후 보호 경로의 변경을 점검합니다. 사용법·exit code는 `CONSUMER_AGENT.md` 「프로토타입 정렬」, 규칙은 `FRONTEND_CONVENTIONS.md`에 있습니다.
|
|
80
98
|
|
|
81
99
|
- ec3d964: 소비처 조치: Tailwind CSS v3 저장소(CSS가 `@tailwind` 지시어를 씀)에서 `EDS_TAILWIND_ROOT`나 `package.json` `eds.tailwindRoot`가 v3 CSS 파일을 가리키면 이제 `eds sync`·`eds doctor`가 exit 2로 멈춥니다. 그 설정을 지우고, 앱 진입점에서 `@spectrabrain/eds/styles.css`를 import한 뒤 `var(--eds-*)`·`cssVar()`로 token을 씁니다. Tailwind CSS v4로 올리는 것은 사용자에게 확인한 뒤 진행합니다.
|
|
82
100
|
|
|
@@ -95,20 +113,20 @@
|
|
|
95
113
|
### Minor Changes
|
|
96
114
|
|
|
97
115
|
- 5104561: `eds doctor`가 소비처 소스의 `eds-*` class 이름을 검사합니다. `tokens.json`에서 sync와 같은 규칙으로 공개 class 이름을 도출해 JS·TS·CSS·HTML 파일을 훑고, 공개 token이 없는 `eds-*` class를 `unknown: <파일:줄> <class>` 항목으로 보고해 exit 1로 끝냅니다. Tailwind는 정의되지 않은 class를 조용히 버리므로 typecheck가 잡지 못하던 오타를 여기서 잡습니다. `eds doctor --scan`은 Tailwind 기본 팔레트, `white`·`black`, 임의 색 class를 `raw:` 줄로 나열하며 exit code는 바꾸지 않습니다. Tailwind root가 없는 저장소에서는 두 검사를 건너뜁니다.
|
|
98
|
-
- bee9af6: `CHANGELOG.md`를 배포물에 포함하고 `@spectrabrain/eds/CHANGELOG.md`로 export합니다.
|
|
116
|
+
- bee9af6: `CHANGELOG.md`를 배포물에 포함하고 `@spectrabrain/eds/CHANGELOG.md`로 export합니다. EDS 버전이 바뀌면 소비처 AI가 변경 기록을 읽도록 `AI_CONTEXT.json`과 관련 안내를 갱신합니다.
|
|
99
117
|
- b09c8d6: `eds sync`가 `GEMINI.md`가 있으면 `<!-- EDS:GEMINI:BEGIN -->`·`<!-- EDS:GEMINI:END -->` 사이에 `@./AGENTS.md` import 한 줄을 추가하고, `eds doctor`가 누락을 `missing:`으로 보고합니다. Gemini CLI가 기본으로 `GEMINI.md`만 읽기 때문이며, `CLAUDE.md`와 같은 규칙(파일이 없으면 만들지 않음, symlink와 fenced 예시 무시)을 따릅니다. Codex·Cursor·Copilot·Windsurf는 `AGENTS.md`를 직접 읽습니다.
|
|
100
118
|
- 4dce7ce: `@spectrabrain/eds/AI.md` export를 추가합니다. `AI_CONTEXT.json`의 `readOrder`에서 `specifier`가 `null`이던 유일한 항목이 `@spectrabrain/eds/AI.md`가 되어, 모든 공개 문서를 `require.resolve`나 `import.meta.resolve`로 같은 방식으로 찾을 수 있습니다. `README.md` 공개 경로 표에 같은 행을 추가했으며 읽기 순서와 조건은 바뀌지 않습니다.
|
|
101
119
|
- 9b2116e: `@spectrabrain/eds/base.css` export를 추가합니다. `:where(html)`에 `--eds-typography-body1-fontFamily`를 `font-family`로 적용하는 규칙 하나만 담고 있으며, `:where()` 선택자라 specificity가 0이므로 cascade layer 밖에 있는 소비처의 `html`·`body` font 규칙이 우선합니다. 소비처가 `@layer` 안에 둔 `html` 규칙보다는 `base.css`가 우선합니다. `@spectrabrain/eds/styles.css`는 이제 `fonts.css`, `tokens.css`, `base.css`, `components.css` 순서로 불러오며, `tokens.css`와 `components.css`만 따로 import하는 소비처는 필요할 때 `base.css`를 함께 import합니다.
|
|
102
120
|
|
|
103
121
|
`@spectrabrain/eds/tokens` runtime과 타입 선언을 가볍게 만듭니다. `tokens`와 `tokenNames`를 만드는 `Object.freeze` 호출에 `/* @__PURE__ */` 표시를 붙이고 `cssVar()`가 token map 대신 `tokenNames`로 이름을 검증하도록 바꿔, `cssVar()`만 사용하는 앱에서는 번들러가 token map을 제거할 수 있습니다. `SemanticTokenCssVariable`과 `SemanticTokenCssReference`는 `SemanticTokenName`에서 파생하는 template literal type으로 선언해 `tokens.d.ts` 크기를 줄였습니다. token 이름 목록, 자동완성, `cssVar()` 반환값과 오류 메시지는 바뀌지 않습니다.
|
|
104
122
|
|
|
105
|
-
- cb5d1b5: `eds init`이
|
|
106
|
-
- cb5d1b5: `eds doctor`가 EDS
|
|
107
|
-
- 507e821: **breaking**: `ButtonIconName
|
|
123
|
+
- cb5d1b5: `eds init`이 npm·pnpm·Yarn·Bun별 postinstall 승인과 실행 명령을 안내하고, npm 12의 `allowScripts`, `--no-allow-scripts`, `--print-ci`를 지원합니다. Tailwind root가 없으면 CSS 배선을 건너뛰고, 후보가 여러 개면 명시적 경로를 요구합니다.
|
|
124
|
+
- cb5d1b5: `eds doctor`가 EDS font import를 검사하고, Tailwind root가 있으면 `eds sync`가 `fonts.css` import와 Tailwind 기본 sans 글꼴 alias를 추가합니다. CDN·`<link>`·별도 `@font-face`로 Pretendard를 불러오면 참고 메시지만 출력합니다.
|
|
125
|
+
- 507e821: **breaking**: `ButtonIconName`은 EVA에서 쓰는 canonical lucide-react 47개만 허용합니다. 목록 밖 이름은 typecheck와 render에서 오류가 되므로 `icon={<X />}`처럼 ReactElement 슬롯을 씁니다. 목록은 `spec.json`의 `api.iconNames`에서 확인합니다.
|
|
108
126
|
|
|
109
127
|
아이콘 registry의 lazy 로드 chunk(`dist/button-icons.js`, `dist/button-icons.mjs`)를 제거하고 아이콘을 동기적으로 렌더링합니다. SSR에서도 아이콘 SVG를 바로 렌더링하며, `ButtonIconName`은 type-only export로 유지됩니다. 목록 밖 아이콘은 `icon`·`startIcon`·`endIcon`에 ReactElement로 전달합니다.
|
|
110
128
|
|
|
111
|
-
- 4fdcd43: 소비처 AI의 필수
|
|
129
|
+
- 4fdcd43: 소비처 AI의 필수 문서를 `QUICKSTART.md` 하나로 줄이고, 조건별 문서는 `AI_CONTEXT.json`에서 안내합니다. 문서와 managed block의 경로·font 정책을 바로잡았으므로 기존 소비처는 `npm run sync:eds`를 한 번 실행합니다.
|
|
112
130
|
- 2ad76e2: 소비처 AI가 공개 token·Button·Tailwind CSS v4 사용 규칙을 먼저 읽고 적용할 수 있도록 `AI_CONTEXT.json`, `CONSUMER_AGENT.md`, `TOKEN_CONTEXT.md`를 제공하고, 소비처 setup을 `eds` CLI(`npx @spectrabrain/eds init`, `eds sync`, `eds doctor`)로 배포합니다. npm 10·11의 postinstall은 소비처 `package.json`에 `sync:eds`·`eds:doctor`와 `pretypecheck`·`prebuild` hook만 등록하며, `npm run sync:eds`는 `src/styles/eds-tokens.css` 생성, Tailwind root CSS의 `@spectrabrain/eds/styles.css`·`eds-tokens.css` import, `AGENTS.md` managed block과 `EDS:VERSION` 줄, 기존 `CLAUDE.md`의 `@AGENTS.md` import를 원자적으로 갱신합니다. Tailwind root는 `EDS_TAILWIND_ROOT`로 지정할 수 있고, `npm run eds:doctor`는 읽기 전용으로 미동기·버전 불일치를 보고합니다. Markdown code block을 추출해 실행하던 이전 runner export와 소비처 소유 script 옵션, `EDS_ENTRYPOINT`는 제거합니다.
|
|
113
131
|
- 8724189: `@spectrabrain/eds/components.css` export를 추가합니다. Button CSS만 포함하며 font는 포함하지 않으므로 개별 구성에서는 `@spectrabrain/eds/tokens.css`·`@spectrabrain/eds/fonts.css`와 함께 import합니다.
|
|
114
132
|
|
|
@@ -117,9 +135,9 @@
|
|
|
117
135
|
- c5672e8: `dist/index.d.ts`의 Button props와 `ButtonIconName`에 JSDoc을 추가합니다. role·variant의 의미, `loading` 계약, branch별 `type`·`href` 필수 조건, allowlist 밖 아이콘의 ReactElement 탈출구, 기계 판독 계약(`spec.json`)의 위치를 편집기 hover와 선언 파일에서 바로 볼 수 있습니다. 타입과 동작은 바뀌지 않습니다.
|
|
118
136
|
- 2edce7b: Button README와 `AI.md`에 슬롯 아이콘을 `lucide-react`에서 직접 import할 때 소비처 `package.json`에 EDS와 같은 `1.45.0`을 선언해야 한다는 점과 stroke 기본값 `2`를 기록합니다.
|
|
119
137
|
- 15f463c: 소비처 `package.json`에 `sync:eds`·`eds:doctor`가 다른 명령으로 이미 있어도 설치가 실패하지 않습니다. `postinstall`과 `eds init`은 그 script를 그대로 두고 안내만 출력하며, `eds sync`·`eds doctor`를 포함한 명령(예: `EDS_DOCTOR=warn eds doctor`)은 등록된 것으로 봅니다. `pretypecheck`·`prebuild`에 이미 `eds doctor`를 포함한 명령이 있으면 다시 안내하지 않습니다. `eds doctor`는 `sync:eds`와 `eds:doctor`를 모두 점검해 미등록이면 `scripts: <이름> is not registered`, 다른 명령이면 `scripts: <이름> runs "<명령>" instead of "<EDS 명령>"` 항목으로 보고하고, `sync:eds`가 `eds sync`를 실행하지 않는 상태에서는 마지막 안내를 `Run npx eds sync to fix.`로 바꿉니다.
|
|
120
|
-
- cb5d1b5: 소비처 CLI의
|
|
121
|
-
- 4fdcd43: 소비처 AI 문서의
|
|
122
|
-
- dda103c:
|
|
138
|
+
- cb5d1b5: 소비처 CLI의 sync·doctor 안내와 Tailwind root 감지를 보강합니다. doctor는 실패 원인과 복구 절차를, sync는 검토할 변경 파일을 안내합니다. Tailwind root는 환경 변수·`package.json`·자동 검출 순으로 결정하며 분할 import를 인식합니다. workspace와 pnpm 설치에서 필요한 수동 `init` 절차도 안내합니다.
|
|
139
|
+
- 4fdcd43: 소비처 AI 문서의 package root 경로, 조건별 읽기 순서와 Button 사용 기준을 공개 contract에 맞춥니다. 기존 소비처는 `npm run sync:eds`로 managed block을 갱신합니다. 취소·닫기·수정은 `neutral/outline`, 부담이 낮은 반복 행동은 `neutral/weak`로 안내합니다. `typesVersions`를 추가해 `moduleResolution: node`에서도 token API 타입을 찾습니다.
|
|
140
|
+
- dda103c: 배포된 `llms.txt`의 문서 읽기 순서와 package root 기준 경로를 `AI_CONTEXT.json`에 맞춥니다.
|
|
123
141
|
- 3922273: Button이 `icon`, `iconName`, `startIcon`, `startIconName`, `endIcon`, `endIconName` 슬롯 prop을 native `<button>`·`<a>` 속성으로 전달하던 문제를 수정합니다. React의 알 수 없는 prop 경고와 DOM의 불필요한 속성이 사라지며 공개 API는 바뀌지 않습니다.
|
|
124
142
|
- ef16f71: `Button` 루트 CSS에서 구현 reset 두 줄(`margin: 0`, `flex: 0 0 auto`)을 제거합니다. 공개 token 값과 컴포넌트 계약은 바뀌지 않으며, 버튼의 margin과 flex 동작은 이제 소비처 레이아웃의 기본값을 따릅니다. 줄어드는 flex 컨테이너에서 버튼 폭이 줄면 부모 레이아웃에서 조정합니다.
|
|
125
143
|
|
package/CONSUMER_AGENT.md
CHANGED
|
@@ -4,15 +4,18 @@
|
|
|
4
4
|
|
|
5
5
|
## 소비처 `AGENTS.md` managed block
|
|
6
6
|
|
|
7
|
-
`npm run sync:eds
|
|
7
|
+
`npm run sync:eds`는 sync를 실행한 package 디렉터리(`package.json`이 있는 곳)의 `AGENTS.md`에 managed block을 관리합니다.
|
|
8
|
+
|
|
9
|
+
- 파일이 없으면 만들고, block이 없으면 끝에 추가하며, 있으면 같은 위치에서 갱신합니다. marker 밖의 내용은 보존합니다.
|
|
10
|
+
- BEGIN marker 바로 뒤에 설치 버전(`<!-- EDS:VERSION x.y.z -->`)을 기록하고 `npm run ` 접두를 감지한 runner(`pnpm `, `yarn `, `bun run `)로 바꿉니다.
|
|
11
|
+
- marker가 중복되거나 한쪽만 있으면 파일을 쓰지 않고 실패합니다.
|
|
8
12
|
|
|
9
13
|
```md
|
|
10
14
|
<!-- EDS:BEGIN -->
|
|
15
|
+
|
|
11
16
|
## EVA Design System 사용 규칙
|
|
12
17
|
|
|
13
|
-
-
|
|
14
|
-
- 사용자의 명시적 요청이 이 block보다 우선하며, 요청 범위의 코드부터 적용합니다. 같은 역할의 EDS 컴포넌트(현재 `Button`)가 있으면 자체 구현이나 소비처 규칙이 지정한 로컬 컴포넌트보다 EDS를 먼저 선택하고, 소비처 규칙이 접근성·보안·제품 요구를 이유로 명시한 경우에만 그것을 우선합니다.
|
|
15
|
-
- `AI_CONTEXT.json.components` → component README → `spec.json` → TypeScript contract 순으로 존재 여부를 확인합니다. 필요한 contract가 맞으면 EDS component를 쓰고, 목록에 없거나 맞지 않으면 소비처 로컬 UI를 구현합니다. 색상·typography·spacing·radius는 raw 값 대신 공개 token으로 지정하며, Tailwind에서는 `text-eds-fg-*`·`bg-eds-bg-*`·`border-eds-stroke-*`·`eds-typography-*`·`p-eds-spacing-0-5`·`rounded-eds-radius-1`, 그 밖에서는 `var(--eds-color-*)`·`cssVar("spacing-0.5")` 같은 API를 씁니다.
|
|
18
|
+
- UI 작업 전에 EDS package root(`require.resolve("@spectrabrain/eds/package.json")`의 디렉터리, 보통 `node_modules/@spectrabrain/eds`)의 `QUICKSTART.md`를 읽고 규칙과 완료 기준을 따릅니다. 조건별 문서는 `AI_CONTEXT.json`의 `readOrder`를 따릅니다.
|
|
16
19
|
- UI 작업을 끝내기 전에 이 `AGENTS.md`가 있는 디렉터리에서 `npm run eds:doctor`를 실행해 `[EDS] synced with` 줄을 확인합니다. 이 줄이 없으면 `QUICKSTART.md` 「완료 기준」의 순서로 고칩니다.
|
|
17
20
|
- UI 작업의 완료 보고에 변경 파일, 사용한 EDS component·token, typecheck·build·doctor 결과를 적습니다.
|
|
18
21
|
- 이 block은 `npm run sync:eds`가 다시 씁니다. 소비처 규칙은 block 밖에 적습니다.
|
|
@@ -21,50 +24,56 @@
|
|
|
21
24
|
|
|
22
25
|
block은 postinstall이 아니라 `npm run sync:eds`가 넣으며, 소비처 담당자가 저장소의 기존 규칙과 함께 diff를 검토합니다. EDS를 업데이트할 때도 block 안쪽과 버전 줄만 바뀝니다.
|
|
23
26
|
|
|
24
|
-
block이
|
|
27
|
+
block이 전달되는 지시 파일은 도구마다 다릅니다.
|
|
28
|
+
|
|
29
|
+
- Codex는 git 루트부터 작업 디렉터리까지의 `AGENTS.md`를 읽습니다. 기본 32 KiB를 넘는 뒷부분은 잘리며, 같은 디렉터리에 `AGENTS.override.md`가 있으면 그 파일만 읽습니다.
|
|
30
|
+
- Claude Code는 `CLAUDE.md`·`.claude/CLAUDE.md`·`CLAUDE.local.md`가 있으면 `AGENTS.md` 대신 해당 지시 파일을 읽습니다. sync는 `CLAUDE.md`(없으면 `.claude/CLAUDE.md`)에 import를 넣습니다.
|
|
31
|
+
- Gemini CLI는 기본 설정에서 `GEMINI.md`를 읽습니다.
|
|
32
|
+
|
|
33
|
+
sync와 doctor는 Claude·Gemini 지시 파일이 없거나, `CLAUDE.local.md`만 있거나, `AGENTS.override.md`가 있거나, block이 32 KiB 밖에 있거나, monorepo 하위 package에서 실행해 지시가 전달되지 않을 수 있으면 `note:`를 출력합니다. exit code에는 영향이 없으며 루트 지시 파일에 넣을 문장도 함께 안내합니다.
|
|
25
34
|
|
|
26
35
|
## 첫 setup 절차
|
|
27
36
|
|
|
28
37
|
소비처 `AGENTS.md`에 EDS managed block이 없으면 UI 작업보다 먼저 이 절차를 진행합니다. `@spectrabrain/eds`를 dependencies에 선언할 앱 package 디렉터리(그 앱의 `package.json`이 있는 곳)에서 패키지를 설치하고 `init`으로 script 등록과 첫 sync를 실행합니다. `init`은 postinstall 실행 여부와 관계없이 동작하며, 현재 `package.json`이 `@spectrabrain/eds`를 선언하지 않으면 아무것도 쓰지 않고 exit 2로 끝납니다.
|
|
29
38
|
|
|
30
|
-
| 패키지 매니저
|
|
31
|
-
|
|
|
32
|
-
| npm
|
|
33
|
-
| pnpm
|
|
34
|
-
| yarn berry(`.yarnrc.yml`이 있거나 `yarn.lock`이 `__metadata:`로 시작) | `yarn add @spectrabrain/eds && yarn eds init`
|
|
35
|
-
| yarn classic
|
|
36
|
-
| bun
|
|
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의 기본 신뢰 목록을 대체하므로 사용자가 결정할 항목으로 완료 보고에 적습니다. |
|
|
37
46
|
|
|
38
|
-
yarn berry의 기본 Plug'n'Play 설치에는 `node_modules/@spectrabrain/eds`가 없으며 지원 여부는
|
|
47
|
+
yarn berry의 기본 Plug'n'Play 설치에는 `node_modules/@spectrabrain/eds`가 없으며 지원 여부는 아직 확인되지 않았습니다. sync와 doctor는 `.pnp.cjs`를 발견하면 `note:`로 알리며, 이때 `nodeLinker`를 바꾸기 전에 저장소 담당자에게 확인합니다.
|
|
39
48
|
|
|
40
49
|
EDS CLI는 가장 가까운 lockfile(현재 디렉터리부터 git 루트까지)로 패키지 매니저를 판별하고, lockfile이 없을 때만 실행한 runner를 따릅니다. `npx`와 `bunx`에는 항상 `@spectrabrain/eds`를 적습니다. npm registry의 `eds`는 EDS와 무관한 패키지라서, 로컬 bin이 없는 위치에서 `npx eds`를 실행하면 그 패키지가 설치되어 실행됩니다.
|
|
41
50
|
|
|
42
|
-
|
|
51
|
+
기본 등록 대상은 다음 script입니다.
|
|
43
52
|
|
|
44
53
|
```json
|
|
45
54
|
{
|
|
46
55
|
"scripts": {
|
|
47
56
|
"sync:eds": "eds sync",
|
|
48
|
-
"eds:doctor": "eds doctor"
|
|
49
|
-
"pretypecheck": "eds doctor",
|
|
50
|
-
"prebuild": "eds doctor"
|
|
57
|
+
"eds:doctor": "eds doctor"
|
|
51
58
|
}
|
|
52
59
|
}
|
|
53
60
|
```
|
|
54
61
|
|
|
55
62
|
- `sync:eds`·`eds:doctor`가 없으면 등록합니다. 같은 이름의 script가 `eds sync`·`eds doctor`를 포함하면(예: `EDS_DOCTOR=warn eds doctor`) 그대로 두고, 다른 명령이면 덮어쓰지 않고 안내만 출력하며 `eds doctor`가 `scripts:` 항목으로 보고합니다. 이전 EDS 버전이 등록한 알려진 명령은 새 명령으로 바꿉니다.
|
|
56
|
-
-
|
|
63
|
+
- 소비처에 `typecheck`·`build` script가 있으면 대응하는 `pretypecheck`·`prebuild` hook이 없는 경우에만 `eds doctor`를 등록합니다. 이미 다른 pre-hook이 있으면 그대로 두고, 출력된 명령대로 기존 hook 앞에 `eds doctor && `를 붙입니다.
|
|
57
64
|
- npm 10·11과, `init`이 `allowScripts`를 기록한 npm 12 이상에서는 EDS의 `postinstall`이 설치 중에 같은 script를 등록하고 다른 파일은 쓰지 않습니다. 소비처 `package.json`에 `workspaces`가 있으면 등록하지 않고 앱 package 안에서 `init`을 실행하도록 안내하며, pnpm 설치에서는 pnpm이 설치 중의 `package.json` 편집을 버리므로 `pnpm exec eds init`을 안내합니다.
|
|
58
65
|
- `--no-sync`는 script만 등록하고(npm 12 이상은 `allowScripts`도 기록) sync는 실행하지 않습니다(`npx @spectrabrain/eds init --no-sync`).
|
|
59
|
-
- `init --print-ci github` 또는 `--print-ci gitlab`(예: `npx @spectrabrain/eds init --print-ci github`)은 이 저장소의 패키지 매니저로 install과 `eds doctor`를 실행하는 CI job snippet을
|
|
66
|
+
- `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에는 이 경로가 포함되지 않습니다.
|
|
60
67
|
|
|
61
|
-
|
|
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 밖 기존 내용을 고쳐야 할 때는 쓰기 전에 사용자에게 확인합니다.
|
|
62
69
|
|
|
63
70
|
## Tailwind root 결정
|
|
64
71
|
|
|
65
72
|
`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`, 점(`.`)으로 시작하는 디렉터리는 제외합니다.
|
|
66
73
|
|
|
67
|
-
- 후보가 2개 이상이면 아무 파일도 쓰지 않고 exit 2로 끝납니다.
|
|
74
|
+
- 후보가 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
|
+
- `EDS_TAILWIND_ROOT`나 저장된 경로가 없는 파일을 가리키면 exit 2입니다.
|
|
68
77
|
- 후보가 없고 지정도 없으면 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합니다.
|
|
69
78
|
- 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 업그레이드는 사용자에게 확인한 뒤 진행합니다.
|
|
70
79
|
|
|
@@ -93,52 +102,53 @@ EDS text style은 font family `Pretendard`를 참조하며, 이 family는 `@spec
|
|
|
93
102
|
|
|
94
103
|
## `eds:doctor` 점검
|
|
95
104
|
|
|
96
|
-
`npm run eds:doctor`는 파일을 쓰지 않고 sync 상태,
|
|
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`가 같은 역할을 합니다.
|
|
97
106
|
|
|
98
|
-
| exit | 의미
|
|
99
|
-
|
|
|
100
|
-
| 0
|
|
101
|
-
| 1
|
|
102
|
-
| 2
|
|
107
|
+
| exit | 의미 |
|
|
108
|
+
| ---- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
109
|
+
| 0 | `[EDS] synced with` 줄이 나오면 동기화된 상태입니다. `--warn`·`EDS_DOCTOR`로 얻은 exit 0에는 이 줄이 없으며 완료가 아닙니다. |
|
|
110
|
+
| 1 | 고칠 항목이 있습니다. 항목마다 `[EDS] <종류>: …` 줄과 조치를 출력합니다. script 등록이나 sync가 필요할 때만 `init`·sync 명령을 안내하고, 마지막에 doctor 재실행을 안내합니다. |
|
|
111
|
+
| 2 | 판정할 수 없는 상태입니다. `@spectrabrain/eds`를 찾을 수 없거나(소비처 `package.json`이 깨진 경우 포함), EDS `package.json`을 읽을 수 없거나, 옵션이 잘못되었거나, Tailwind root 후보가 2개 이상이거나, `EDS_TAILWIND_ROOT`·`eds.tailwindRoot`가 없는 파일이나 Tailwind CSS v3 파일을 가리키거나 `eds.tailwindRoot`가 빈 값·문자열이 아닌 값인 경우입니다. 출력 메시지가 올바른 형식을 안내합니다. |
|
|
103
112
|
|
|
104
113
|
각 `[EDS]` 줄 끝의 조치를 따릅니다. 고치는 순서는 `scripts:` → sync → 나머지이며, 항목별 조치는 다음과 같습니다.
|
|
105
114
|
|
|
106
|
-
| 항목
|
|
107
|
-
|
|
|
108
|
-
| `missing:`·`stale:`·`legacy:`(생성 CSS, root CSS import, `AGENTS.md` block, `CLAUDE.md`·`GEMINI.md` import) | `npm run sync:eds`로
|
|
109
|
-
| `missing:` EDS font import(Tailwind root가 없는 저장소)
|
|
110
|
-
| `scripts:`
|
|
111
|
-
| `unknown: <파일:줄> <class>`
|
|
112
|
-
| `invalid:`
|
|
115
|
+
| 항목 | 조치 |
|
|
116
|
+
| ----------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
117
|
+
| `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
|
+
| `missing:` EDS font import(Tailwind root가 없는 저장소) | 앱 진입점에서 `@spectrabrain/eds/styles.css`를 import합니다. 이 경우 sync는 CSS를 고치지 않습니다. |
|
|
119
|
+
| `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
|
+
| `invalid:` | `AGENTS.md`의 EDS marker가 중복되거나 한쪽만 있습니다. sync는 이 상태를 고치지 않습니다. 출력에 적힌 줄에서 BEGIN 한 줄과 그 뒤의 END 한 줄만 남기고 나머지 marker 줄을 지운 뒤 sync를 다시 실행합니다. |
|
|
113
122
|
|
|
114
123
|
`npm run eds:doctor -- --warn`과 `EDS_DOCTOR=warn`은 같은 출력에 warn mode 경고를 더하고 exit 0으로 끝나며, `EDS_DOCTOR=off`는 출력 없이 exit 0으로 끝납니다. 이 설정은 hook을 잠시 풀어야 할 때 사용자가 쓰는 것이며, 이 상태의 exit 0은 완료가 아닙니다.
|
|
115
124
|
|
|
116
|
-
`npm run eds:doctor -- --scan`은 Tailwind 기본 팔레트(`text-red-500`), `white`·`black`, 임의 색(`bg-[#…]`) class를 `raw: <파일:줄> <class>` 줄로 나열합니다. 정보 제공용이라 exit code를 바꾸지 않습니다. `unknown:`과 `raw:` 검사는 Tailwind root가 있는 저장소에서 Tailwind class만 봅니다. CSS·inline style의 `var(--eds-*)` 참조는 검사하지 않습니다.
|
|
125
|
+
`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-*)` 참조는 검사하지 않습니다.
|
|
117
126
|
|
|
118
127
|
## 프로토타입 정렬
|
|
119
128
|
|
|
120
|
-
사용자가
|
|
129
|
+
사용자가 Vite + React 프로토타입을 EVA 프론트엔드 구조로 정리하라고 요청하면, 코드 이동 전에 `npx @spectrabrain/eds align`(pnpm은 `pnpm exec eds align`, yarn은 `yarn eds align`, Bun은 `bunx @spectrabrain/eds align`)을 실행하고 `.eds/align/PLAN.md`를 따릅니다. 이 명령은 소스 파일을 바꾸지 않고 계획과 템플릿을 생성합니다. 규칙은 `FRONTEND_CONVENTIONS.md`에 있습니다.
|
|
121
130
|
|
|
122
131
|
- EDS가 설치된 frontend package에서 실행하며 git commit이 하나 이상 있어야 합니다. git 저장소나 commit이 없으면 저장소 생성과 첫 commit은 사용자에게 요청합니다. 현재 디렉터리가 React package가 아니면 하위 package를 찾고, 후보가 여럿이면 `--frontend <dir>`로 지정합니다. 그 경우 `PLAN.md`의 명령은 모두 frontend package 디렉터리에서 실행합니다. `--dry-run`은 쓸 파일만 출력합니다.
|
|
123
|
-
- frontend package의 `.eds/align/`에 `PLAN.md`(단계와 완료 기준), `NOTES.md`(작업 기록), `state.json`(기준 commit
|
|
124
|
-
- 다시 실행하면 기준 commit과 `NOTES.md`를 유지하고 `PLAN.md
|
|
125
|
-
- 보호 경로는 backend 디렉터리(`server`, `backend`, `api`, `supabase` 등), backend 옆의 `shared`, backend·배포 설정 파일, frontend package 밖의
|
|
126
|
-
|
|
127
|
-
`npx @spectrabrain/eds align --check
|
|
128
|
-
|
|
129
|
-
| exit | 의미
|
|
130
|
-
|
|
|
131
|
-
| 0
|
|
132
|
-
| 1
|
|
133
|
-
| 2
|
|
134
|
-
|
|
135
|
-
| 종류
|
|
136
|
-
|
|
|
137
|
-
| `protected:`·`outside:`
|
|
138
|
-
| `
|
|
139
|
-
| `
|
|
140
|
-
| `
|
|
141
|
-
| `
|
|
132
|
+
- frontend package의 `.eds/align/`에 `PLAN.md`(단계와 완료 기준), `NOTES.md`(작업 기록), `state.json`(기준 commit, 보호·보존 경로와 tsconfig 설정), `templates/`(이 저장소의 경로로 채운 설정·소스 템플릿)를 씁니다. 디렉터리 안의 `.gitignore`가 디렉터리 전체를 제외하므로 commit에 들어가지 않습니다.
|
|
133
|
+
- 다시 실행하면 기준 commit과 `NOTES.md`를 유지하고 `PLAN.md`·`state.json`·`templates/`를 갱신합니다. 처음부터 다시 하려면 `.eds/align/`을 지운 뒤 실행합니다.
|
|
134
|
+
- 보호 경로는 backend 디렉터리(`server`, `backend`, `api`, `supabase` 등), backend 옆의 `shared`, backend·배포 설정 파일, frontend package 밖의 파일입니다. monorepo 저장소 루트 lockfile은 제외합니다. backend를 실행하는 script와 backend 코드가 쓰는 의존성도 기록합니다. 실행 시점에 이미 있던 uncommitted 변경은 기준으로 기록합니다.
|
|
135
|
+
|
|
136
|
+
`npx @spectrabrain/eds align --check`(pnpm은 `pnpm exec eds align --check`, yarn은 `yarn eds align --check`, Bun은 `bunx @spectrabrain/eds align --check`)는 파일을 쓰지 않고 점검합니다. `.eds/align/state.json`이 있으면 보호·보존 경로, tsconfig 파일 삭제와 각 파일의 기준선 항목 누락을 확인합니다. 보존 기준과 `preservedPaths` 설정 방법은 `FRONTEND_CONVENTIONS.md`를 따릅니다. state가 없으면 보호 기준 없이 컨벤션만 점검합니다. 오류는 `[EDS] <종류>: …`, 경고는 `[EDS] warning <종류>: …` 줄로 출력하며, 경고는 exit code를 바꾸지 않습니다.
|
|
137
|
+
|
|
138
|
+
| exit | 의미 |
|
|
139
|
+
| ---- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
140
|
+
| 0 | 오류가 없습니다. 출력의 `Also required` 명령이 모두 exit 0이어야 끝납니다. 경고는 고치거나 이유를 기록합니다(`.eds/align/`이 있으면 `NOTES.md`, 없으면 작업 보고). |
|
|
141
|
+
| 1 | 고칠 오류가 있습니다. |
|
|
142
|
+
| 2 | 판정할 수 없습니다(Vite + React 앱이 아님, frontend package를 정할 수 없음, 기준 commit이나 `state.json`을 읽을 수 없음, Vite가 지원 범위를 벗어나거나 선언 범위의 상한을 확인할 수 없음, Vite 8 React Compiler에 필요한 Node 버전 미달 등). 출력 메시지가 원인과 조치를 알려 주므로 그대로 따릅니다. |
|
|
143
|
+
|
|
144
|
+
| 종류 | 의미 |
|
|
145
|
+
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
146
|
+
| `protected:`·`outside:` | 기준 commit 이후 보호 경로나 frontend package 밖의 파일이 바뀌었습니다. monorepo 저장소 루트 lockfile은 제외합니다. |
|
|
147
|
+
| `preserved:` | 기준선에 있던 보존 파일이 수정·삭제되었거나 tsconfig의 기준 항목이 빠졌습니다. 해당 파일과 항목을 기준 상태로 복구합니다. 새 리소스 파일 추가는 오류가 아닙니다. |
|
|
148
|
+
| `backend-script:`·`backend-dependency:` | backend를 실행하는 script가 바뀌었거나 backend 코드가 쓰는 의존성이 지워졌습니다. |
|
|
149
|
+
| `structure:`·`language:`·`import:` | FSD 계층, TypeScript 전환, import 방향 규칙을 어겼습니다. slice 이름·segment 위치와 widget 간 import는 경고입니다. |
|
|
150
|
+
| `dependency:`·`config:`·`script:` | 교체 대상 package가 남았거나, 표준 설정이 없거나 tsconfig를 읽을 수 없거나, 필요한 script가 없거나, lint 도구가 템플릿보다 오래되었습니다. `lucide-react` 선언 버전이 EDS와 다르면 경고입니다. |
|
|
151
|
+
| `pattern:`·`agents:` | 항상 경고입니다. `pattern:`은 `shared/api/` 밖의 직접 `fetch()`·axios 호출과 `widgets`·`features`·`entities`·`shared` 계층 TSX 파일의 default export를 알립니다. `agents:`는 `AGENTS.md`가 `FRONTEND_CONVENTIONS.md`를 가리키지 않는 상태를 알립니다(PLAN 8단계에서 해소). |
|
|
142
152
|
|
|
143
153
|
## 버전 업데이트
|
|
144
154
|
|