@spectrabrain/eds 0.0.4 → 0.1.0

package/AI.md

@@ -1,47 +1,70 @@
 # EVA Design System — 소비처 AI 가이드
 
-이 문서는 `@spectrabrain/eds`를 사용하는 제품 저장소의 AI와 자동화 도구를 위한 공개 안내입니다. 설치된 패키지 버전의 API를 최종 기준으로 사용합니다.
+이 문서는 `@spectrabrain/eds`를 사용하는 제품 저장소의 AI와 자동화 도구를 위한 공개 안내입니다. 설치된 패키지 버전의 API와 문서를 최종 기준으로 사용합니다. 필수 읽기는 package root의 [QUICKSTART.md](QUICKSTART.md) 하나이며, 이 문서는 공개 범위와 금지 사례를 확인할 때 읽습니다.
+
+## 시작 순서
+
+설치 직후에는 `require.resolve("@spectrabrain/eds/package.json")`로 찾은 package root의 [QUICKSTART.md](QUICKSTART.md)를 읽습니다. 소비처의 로컬 `AI.md`와 구분하기 위해 package 문서는 항상 이 경로에서 읽습니다. 그다음 [AI_CONTEXT.json](AI_CONTEXT.json)의 `readOrder` 조건에 해당하는 문서만 추가로 읽습니다. `readOrder`의 `file`은 package root 상대 경로이고 `specifier`는 `require.resolve`에 쓰는 export subpath이며, `dist/` 아래 문서는 두 방식 모두로 읽을 수 있습니다. setup·sync·doctor는 [CONSUMER_AGENT.md](CONSUMER_AGENT.md), token 선택은 [TOKEN_CONTEXT.md](TOKEN_CONTEXT.md), Tailwind CSS v4는 [TAILWIND_V4.md](TAILWIND_V4.md), 전체 목록은 [llms.txt](llms.txt)입니다. token 이름·component prop은 JSON manifest를, 선택 이유와 사용 맥락은 Markdown을 기준으로 합니다.
+
+소비처 `AGENTS.md`의 managed block은 `npm run sync:eds`가 삽입하므로, block이 없거나 `npm run eds:doctor`가 실패하면 UI 작업 전에 sync를 먼저 실행합니다.
+
+문서에 없는 API, prop, variant, 상태, token, deep import는 추측하지 않습니다. 사용자의 제품 요구사항과 접근성·보안 규칙이 언제나 우선합니다.
 
 ## 현재 공개 범위
 
 - React 웹용 semantic color·typography token과 token runtime API를 제공합니다.
 - `Button` React 컴포넌트를 제공합니다.
-- `@spectrabrain/eds/styles.css`, `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/fonts.css`를 제공합니다.
-- `styles.css`는 Pretendard Variable font, semantic CSS custom property, Button CSS를 함께 불러옵니다. `fonts.css`는 font만 불러옵니다.
+- `@spectrabrain/eds/styles.css`, `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/components.css`, `@spectrabrain/eds/fonts.css`, `@spectrabrain/eds/base.css`를 제공합니다.
+- `styles.css`는 `fonts.css`, `tokens.css`, `base.css`, `components.css`를 순서대로 불러옵니다. `components.css`는 Button CSS만, `fonts.css`는 Pretendard Variable font만, `base.css`는 `:where(html)`의 body1 font family 한 규칙만 불러옵니다.
+- EDS text style은 `fonts.css`가 선언하는 font family `Pretendard`를 참조합니다. 개별 파일로 구성할 때는 `tokens.css`, `components.css`, `fonts.css`를 함께 import하고 `base.css`는 선택합니다. 다른 출처의 Pretendard로 EDS `fonts.css`를 대체하는 구성은 지원하지 않습니다.
+- `TOKEN_CONTEXT.md`는 공개 token의 역할과 화면 맥락을 설명합니다.
 
-문서에 없는 API, variant, loading 동작은 추측해서 구현하지 않습니다. 공개되지 않은 토큰 원본을 직접 import하지 않습니다. dark theme를 지원하지 않으며, EDS가 Tailwind utility API를 직접 제공하지도 않습니다. 소비처에서 semantic token을 Tailwind CSS v4 className으로 연결해야 하면 [TAILWIND_V4.md](TAILWIND_V4.md)를 먼저 읽습니다.
+공개되지 않은 token 원본·raw 값·임의 CSS variable은 직접 사용하지 않습니다. dark theme를 추가하지 않으며 EDS가 Tailwind utility API를 직접 제공한다고 가정하지 않습니다.
 
-## 토큰 사용
+## token 사용
 
-~~~ts
+```ts
 import "@spectrabrain/eds/styles.css";
 import { cssVar, type SemanticTokenName } from "@spectrabrain/eds/tokens";
 
 const token: SemanticTokenName = "color-fg-brand";
 const color = cssVar(token); // var(--eds-color-fg-brand)
-~~~
+```
 
 - 색상에는 `SemanticTokenName`, `cssVar()`, 또는 `--eds-*` CSS variable만 사용합니다.
 - text style은 같은 style의 `fontFamily`, `fontWeight`, `fontSize`, `lineHeight`, `letterSpacing` token을 함께 적용합니다.
-- `styles.css`를 import하면 font와 token CSS를 함께 불러옵니다. `tokens.css`만 사용하는 경우 text style에 `fonts.css`를 추가합니다.
-- 문서에 없는 deep import, raw 색상값, 임의 CSS variable은 사용하지 않습니다.
-- 역할에 맞는 semantic token이 없으면 임의 값을 만들지 말고 디자인 시스템 담당자에게 요청합니다.
+- `styles.css`를 import하면 font, token CSS, `html` 기본 font family, Button CSS를 함께 불러옵니다. `tokens.css`를 개별로 사용하는 경우에도 `fonts.css`를 함께 import합니다.
+- 역할에 맞는 exact token이 없으면 `fg/bg/stroke` 역할, 상태, 행동 의미, `neutral` 순서로 가까운 공개 token을 선택합니다. raw 값을 새로 만들지 않습니다.
+
+## Tailwind CSS v4
 
-## Tailwind CSS v4 token 설정
+Tailwind CSS v4에서 token을 `className`으로 사용하려면 [TAILWIND_V4.md](TAILWIND_V4.md)를 읽습니다. 설치된 `eds sync`가 공개 `tokens.json`에서 `src/styles/eds-tokens.css`를 생성하고 `@import "tailwindcss"`가 있는 Tailwind root CSS에 연결합니다. 생성된 `@theme inline`에는 color alias와 함께 `--font-sans: var(--eds-typography-body1-fontFamily);`가 들어가므로 Tailwind의 기본 sans font도 Pretendard가 됩니다. 소비처는 별도 generator script를 소유하지 않습니다.
 
-소비처가 컴포넌트가 아닌 token만 Tailwind CSS v4 utility로 사용하려는 경우 [TAILWIND_V4.md](TAILWIND_V4.md)의 설치·alias·typography preset 설정을 따릅니다. 이 가이드는 공개 semantic CSS variable만 Tailwind theme alias와 custom utility로 연결하며, 내부 token 원본이나 raw 값을 소비처에 복사하지 않습니다.
+npm 10·11에서는 EDS `postinstall`이 소비처 `package.json`에 `sync:eds`·`eds:doctor` script를 등록하고, 의존성의 install script가 실행되지 않는 환경에서는 `npx @spectrabrain/eds init`이 같은 script를 등록한 뒤 패키지 매니저별 승인 절차를 기록하거나 안내합니다. 설치·업데이트 후에는 `npm run sync:eds`로 Tailwind root CSS import, Tailwind alias, `AGENTS.md` managed block을 함께 갱신하고 `npm run eds:doctor`로 상태를 점검합니다. Tailwind를 사용하지 않는 저장소에서는 sync가 Tailwind 배선을 건너뛰고 `AGENTS.md`만 갱신합니다.
 
-## 컴포넌트 문서 읽기
+권장 className은 다음과 같습니다.
 
-컴포넌트를 사용하기 전에 해당 컴포넌트의 README와 공개 manifest를 먼저 읽습니다. 문서에는 컴포넌트의 개요, 사용 맥락, 공개 API, 접근성 계약, 금지 사례를 기록합니다.
+- `text-eds-fg-*`
+- `bg-eds-bg-*`
+- `border-eds-stroke-*`
+- `eds-typography-*`
 
-현재 `Button` 문서는 다음 경로에서 확인합니다.
+새 컴포넌트별 스타일을 `index.css`에 추가하지 않고 Tailwind `className`을 우선 사용합니다. 기존 CSS Modules와 전역 규칙은 일괄 변환하지 않습니다.
+
+## 컴포넌트 문서
+
+컴포넌트를 사용하기 전에 해당 README와 공개 manifest를 먼저 읽습니다. 문서에는 개요, 사용 맥락, 공개 API, 접근성 계약, 금지 사례가 기록되어 있습니다.
+
+현재 `Button` 문서는 다음 경로에서 확인합니다. npm 설치 후에는 package root 상대 경로로 파일을 읽거나 export subpath로 resolve합니다.
 
 | 환경 | 개요·API 문서 | 기계 판독 manifest |
 | --- | --- | --- |
 | 저장소 작업 | `src/components/Button/README.md` | `dist/components/Button/spec.json` |
-| npm 설치 후 | `dist/components/Button/README.md` | `dist/components/Button/spec.json` |
+| npm 설치 후(package root 상대 경로) | `dist/components/Button/README.md` | `dist/components/Button/spec.json` |
+| npm 설치 후(export subpath) | `@spectrabrain/eds/components/Button/README.md` | `@spectrabrain/eds/components/Button/spec.json` |
+
+제공되는 EDS 컴포넌트를 유사한 자체 구현보다 우선 사용합니다. 소비처 저장소 규칙이 특정 컴포넌트를 지정하더라도 EDS에 같은 역할의 컴포넌트가 있으면 EDS를 먼저 선택하고, 소비처 규칙이 접근성·보안·제품 요구사항인 경우에만 그것을 우선합니다. typed prop으로 제공하지 않은 색상·상태·variant를 `className`이나 inline style로 우회하지 않으며, native semantics·accessible name·keyboard interaction을 임의로 변경하지 않습니다.
 
-패키지의 전체 AI 문서 읽기 순서는 [llms.txt](llms.txt)에서 확인합니다. 컴포넌트별 문서에 없는 props·variant·상태·사용 맥락은 추측해서 추가하지 않습니다.
+`iconName`·`startIconName`·`endIconName`에는 승인된 allowlist의 lucide 이름만 사용합니다. `ButtonIconName`이 이 목록과 같은 union이며 `spec.json`의 `api.iconNames`에서 확인합니다. allowlist 밖 아이콘은 `icon`/`startIcon`/`endIcon`에 ReactElement로 전달합니다. `lucide-react`에서 직접 import하는 경우 소비처 `package.json`에 EDS와 같은 `1.45.0`으로 선언하고 stroke 두께는 기본값 `2`로 둡니다. 같은 아이콘이 두 화면 이상에서 반복되면 allowlist PR을 엽니다.
 
-제공되는 EDS 컴포넌트를 유사한 자체 구현보다 우선 사용합니다. typed prop으로 제공하지 않은 색상·상태·variant를 `className`이나 inline style로 우회하지 않으며, native semantics·accessible name·keyboard interaction을 임의로 변경하지 않습니다.
+세부적인 소비처 setup과 버전 업데이트 절차는 [CONSUMER_AGENT.md](CONSUMER_AGENT.md), token 선택 맥락은 [TOKEN_CONTEXT.md](TOKEN_CONTEXT.md)를 기준으로 합니다.

package/AI_CONTEXT.json

@@ -0,0 +1,159 @@
+{
+  "schemaVersion": 1,
+  "package": "@spectrabrain/eds",
+  "purpose": "consumer-ai-routing",
+  "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, or null when the file is not exported; path equals file for compatibility.",
+  "components": [
+    "Button"
+  ],
+  "readOrder": [
+    {
+      "path": "QUICKSTART.md",
+      "file": "QUICKSTART.md",
+      "specifier": "@spectrabrain/eds/QUICKSTART.md",
+      "kind": "quickstart",
+      "required": true
+    },
+    {
+      "path": "CONSUMER_AGENT.md",
+      "file": "CONSUMER_AGENT.md",
+      "specifier": "@spectrabrain/eds/CONSUMER_AGENT.md",
+      "kind": "instructions",
+      "required": false,
+      "when": "setup, sync, or doctor is involved"
+    },
+    {
+      "path": "AI.md",
+      "file": "AI.md",
+      "specifier": "@spectrabrain/eds/AI.md",
+      "kind": "public-contract",
+      "required": false,
+      "when": "The public scope or a forbidden usage must be confirmed"
+    },
+    {
+      "path": "TOKEN_CONTEXT.md",
+      "file": "TOKEN_CONTEXT.md",
+      "specifier": "@spectrabrain/eds/TOKEN_CONTEXT.md",
+      "kind": "usage-context",
+      "required": false,
+      "when": "A token is selected directly or no exact token matches"
+    },
+    {
+      "path": "TAILWIND_V4.md",
+      "file": "TAILWIND_V4.md",
+      "specifier": "@spectrabrain/eds/TAILWIND_V4.md",
+      "kind": "tailwind-setup",
+      "required": false,
+      "when": "Tailwind CSS v4 is used"
+    },
+    {
+      "path": "dist/tokens.json",
+      "file": "dist/tokens.json",
+      "specifier": "@spectrabrain/eds/tokens.json",
+      "kind": "token-manifest",
+      "required": false,
+      "when": "A token, CSS variable, or Tailwind alias is selected"
+    },
+    {
+      "path": "dist/components/{name}/README.md",
+      "file": "dist/components/{name}/README.md",
+      "specifier": "@spectrabrain/eds/components/{name}/README.md",
+      "kind": "component-context",
+      "required": false,
+      "when": "An EDS component is selected"
+    },
+    {
+      "path": "dist/components/{name}/spec.json",
+      "file": "dist/components/{name}/spec.json",
+      "specifier": "@spectrabrain/eds/components/{name}/spec.json",
+      "kind": "component-contract",
+      "required": false,
+      "when": "An EDS component API or accessibility behavior is implemented"
+    },
+    {
+      "path": "CHANGELOG.md",
+      "file": "CHANGELOG.md",
+      "specifier": "@spectrabrain/eds/CHANGELOG.md",
+      "kind": "changelog",
+      "required": false,
+      "when": "The installed EDS version changed since the last sync (eds doctor reports stale) and the update must be summarized"
+    }
+  ],
+  "precedence": [
+    "user-requirements",
+    "consumer-repository-rules",
+    "eds-managed-block-component-preference",
+    "accessibility-security-and-framework-constraints",
+    "eds-public-contract",
+    "eds-usage-context",
+    "examples"
+  ],
+  "precedenceNote": "eds sync injects the EDS managed block into the consumer AGENTS.md, so the block is itself a consumer repository rule. When a consumer rule names a specific local component and EDS ships a component with the same role, choose the EDS component first. The consumer rule wins only when it is an accessibility, security, or product requirement; those count as user-requirements for this tie-break.",
+  "setup": {
+    "install": "npm install @spectrabrain/eds",
+    "init": "npx @spectrabrain/eds init",
+    "sync": "npm run sync:eds",
+    "doctor": "npm run eds:doctor",
+    "doctorWarn": "npm run eds:doctor -- --warn",
+    "doctorScan": "npm run eds:doctor -- --scan",
+    "doctorEnv": "EDS_DOCTOR=warn|off",
+    "printCi": "npx eds init --print-ci gitlab|github",
+    "tailwindRootOverride": "EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds",
+    "tailwindRootConfig": "package.json eds.tailwindRoot (written by sync after EDS_TAILWIND_ROOT; resolution order: EDS_TAILWIND_ROOT, eds.tailwindRoot, auto-detect)",
+    "postinstall": "register-consumer-scripts-only",
+    "postinstallRequires": "npm 10 or 11 with lifecycle scripts enabled",
+    "legacyScriptMigration": "known-eds-commands-only",
+    "fontPolicy": "eds-fonts-required",
+    "syncOrder": [
+      "generate-public-tailwind-token-aliases",
+      "add-missing-eds-css-root-imports",
+      "update-agents-managed-block",
+      "add-claude-agents-import",
+      "add-gemini-agents-import"
+    ],
+    "syncEffects": [
+      "generate-public-tailwind-token-aliases",
+      "add-missing-eds-css-root-imports",
+      "remove-legacy-eds-tokens-js-imports",
+      "update-agents-managed-block",
+      "add-claude-agents-import",
+      "add-gemini-agents-import"
+    ]
+  },
+  "selection": {
+    "component": "prefer-eds-public-component",
+    "colorClassPatterns": [
+      "text-eds-fg-*",
+      "bg-eds-bg-*",
+      "border-eds-stroke-*"
+    ],
+    "typographyClassPattern": "eds-typography-*",
+    "tokenSource": "dist/tokens.json",
+    "componentSource": "dist/components/{name}/spec.json",
+    "iconNameSource": "dist/components/Button/spec.json#api.iconNames",
+    "nearestTokenOrder": [
+      "same-fg-bg-stroke-role",
+      "same-state",
+      "same-action-meaning",
+      "neutral"
+    ],
+    "fallbackRecordRequired": false
+  },
+  "implementation": {
+    "stylePreference": "tailwind-className",
+    "avoid": [
+      "raw-color",
+      "raw-typography",
+      "arbitrary-css-variable",
+      "private-deep-import",
+      "local-reimplementation-of-an-eds-component",
+      "component-rules-added-to-index.css"
+    ]
+  },
+  "completionReport": [
+    "changed-files",
+    "selected-eds-components",
+    "selected-eds-tokens",
+    "verification-results"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,58 @@
+# @spectrabrain/eds
+
+## 0.1.0
+
+### Minor Changes
+
+- 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가 없는 저장소에서는 두 검사를 건너뜁니다.
+- bee9af6: `CHANGELOG.md`를 배포물에 포함하고 `@spectrabrain/eds/CHANGELOG.md`로 export합니다. `AI_CONTEXT.json`의 `readOrder`에 EDS 버전이 바뀐 경우의 항목을 추가하고 `QUICKSTART.md`·`llms.txt`·`CONSUMER_AGENT.md`의 버전 업데이트 절에서 안내합니다. CHANGELOG도 공개 경계 검사 대상이 되어 내부 token 계층 이름을 적은 0.0.x 항목 두 개의 표현을 고쳤습니다.
+- 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`를 직접 읽습니다.
+- 4dce7ce: `@spectrabrain/eds/AI.md` export를 추가합니다. `AI_CONTEXT.json`의 `readOrder`에서 `specifier`가 `null`이던 유일한 항목이 `@spectrabrain/eds/AI.md`가 되어, 모든 공개 문서를 `require.resolve`나 `import.meta.resolve`로 같은 방식으로 찾을 수 있습니다. `README.md` 공개 경로 표에 같은 행을 추가했으며 읽기 순서와 조건은 바뀌지 않습니다.
+- 9b2116e: `@spectrabrain/eds/base.css` export를 추가합니다. `:where(html)`에 `--eds-typography-body1-fontFamily`를 `font-family`로 적용하는 규칙 하나만 담고 있으며, `:where()` 선택자라 specificity가 0이므로 소비처의 `html`·`body` font 규칙이 항상 우선합니다. `@spectrabrain/eds/styles.css`는 이제 `fonts.css`, `tokens.css`, `base.css`, `components.css` 순서로 불러오며, `tokens.css`와 `components.css`만 따로 import하는 소비처는 필요할 때 `base.css`를 함께 import합니다.
+
+  `@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()` 반환값과 오류 메시지는 바뀌지 않습니다.
+- cb5d1b5: `eds init`이 `npm_config_user_agent`와 lockfile로 패키지 매니저를 판별해 setup을 그 환경에 맞춥니다. npm 12 이상에서는 소비처 `package.json`에 `allowScripts["@spectrabrain/eds"] = true`를 기록해 이후 설치·업그레이드에서 postinstall이 자동 실행되게 하며, `--no-allow-scripts`로 건너뛸 수 있습니다. pnpm(`pnpm approve-builds` 또는 `pnpm.onlyBuiltDependencies`), bun(`trustedDependencies`, 기본 신뢰 목록 대체 경고), Yarn 2+(`enableScripts`·`dependenciesMeta`, pre/post hook 미실행 안내)에는 정확한 승인 절차를 출력합니다. `AGENTS.md` managed block과 CLI 안내문의 `npm run ` 접두사는 판별된 runner(`pnpm `, `yarn `, `bun run `)로 렌더링되고 `eds doctor`도 같은 렌더링과 비교합니다. `eds doctor --warn`은 `EDS_DOCTOR=warn`과 같고, `eds init --print-ci github|gitlab`은 `npx eds doctor`를 실행하는 CI job snippet만 출력합니다. Tailwind root가 없고 `EDS_TAILWIND_ROOT`도 없으면 `eds sync`는 `src/styles/eds-tokens.css` 생성과 CSS import 편집을 건너뛰고 안내만 출력하며, `eds doctor`는 Tailwind 관련 항목을 보고하지 않습니다. Tailwind root가 둘 이상이면 이전처럼 exit 2입니다.
+- cb5d1b5: `eds doctor`가 EDS 글꼴 import를 점검합니다. CSS·JS·TS 어디에서도 `@spectrabrain/eds/styles.css` 또는 `@spectrabrain/eds/fonts.css`를 import하지 않으면 `missing:` 항목으로 보고합니다. EDS text style은 `fonts.css`가 선언하는 family `Pretendard`를 참조하므로 opt-out 구성은 `tokens.css` + `components.css` + `fonts.css`입니다. Tailwind root가 있으면 `eds sync`가 빠진 `fonts.css` import를 root CSS에 추가합니다. `index.html`이나 CSS가 CDN·`<link>`·별도 `@font-face`로 Pretendard를 참조하면 exit code에 영향을 주지 않는 `note:` 줄을 출력합니다. 생성되는 `src/styles/eds-tokens.css`의 `@theme inline` block 마지막 줄에 `--font-sans: var(--eds-typography-body1-fontFamily);`가 추가되어 Tailwind 기본 sans 글꼴이 EDS body 글꼴을 따릅니다. 기존 소비처는 `npm run sync:eds`를 한 번 실행하면 갱신됩니다.
+- 507e821: `ButtonIconName`을 승인된 lucide 아이콘 목록으로 좁힙니다. `iconName`·`startIconName`·`endIconName`은 EVA 화면에서 실제로 사용하는 47개의 canonical lucide-react 이름만 허용하며, 목록에 없는 이름은 TypeScript 오류와 render 오류로 처리합니다. 승인된 목록은 공개 `spec.json`의 `api.iconNames`에서 확인할 수 있습니다.
+
+  아이콘 registry의 lazy 로드 chunk(`dist/button-icons.js`, `dist/button-icons.mjs`)를 제거하고 아이콘을 동기적으로 렌더링합니다. SSR에서도 아이콘 SVG를 바로 렌더링하며, `ButtonIconName`은 type-only export로 유지됩니다. 목록 밖 아이콘은 `icon`·`startIcon`·`endIcon`에 ReactElement로 전달합니다.
+- 4fdcd43: 소비처 AI의 필수 읽기를 4 KB 이하의 `QUICKSTART.md` 하나로 줄이고 `./QUICKSTART.md` export를 추가합니다. package root 찾기, EDS 컴포넌트 우선·Button role/variant 대응·`eds-*` class·raw 값 금지·`className` 배치·doctor/sync·완료 보고 규칙, 명령, 조건부로 읽을 문서만 담습니다. `AI_CONTEXT.json`의 `readOrder`는 `QUICKSTART.md`를 유일한 필수 문서로 두고 `CONSUMER_AGENT.md`(setup·sync·doctor), `AI.md`, `TOKEN_CONTEXT.md`를 `when` 조건부로 내리며, `setup`에 `doctorWarn`, `printCi`, `fontPolicy`를 추가합니다. `AGENTS.md` managed block의 첫 두 항목은 `QUICKSTART.md`를 먼저 읽고 `eds doctor`가 실패하면 `sync:eds`를 실행하도록 바뀌므로 기존 소비처는 `npm run sync:eds`를 한 번 실행합니다. 공개 문서는 앱이 이미 Pretendard를 불러오는 경우의 이전 opt-out 문구를 제거하고 EDS `fonts.css`를 필수로 안내하며, `node scripts/check-consumer-guidance.mjs`가 `QUICKSTART.md`의 크기와 핵심 패턴, 제거된 문구의 부재를 단언합니다.
+- 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`는 제거합니다.
+- 8724189: `@spectrabrain/eds/components.css` export를 추가합니다. Button CSS만 포함하며 font는 포함하지 않으므로 개별 구성에서는 `@spectrabrain/eds/tokens.css`·`@spectrabrain/eds/fonts.css`와 함께 import합니다.
+
+### Patch Changes
+
+- c5672e8: `dist/index.d.ts`의 Button props와 `ButtonIconName`에 JSDoc을 추가합니다. role·variant의 의미, `loading` 계약, branch별 `type`·`href` 필수 조건, allowlist 밖 아이콘의 ReactElement 탈출구, 기계 판독 계약(`spec.json`)의 위치를 편집기 hover와 선언 파일에서 바로 볼 수 있습니다. 타입과 동작은 바뀌지 않습니다.
+- 2edce7b: Button README와 `AI.md`에 슬롯 아이콘을 `lucide-react`에서 직접 import할 때 소비처 `package.json`에 EDS와 같은 `1.45.0`을 선언해야 한다는 점과 stroke 기본값 `2`를 기록합니다.
+- 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.`로 바꿉니다.
+- cb5d1b5: 소비처 CLI의 안내와 판별을 보강합니다. `eds doctor`가 exit 1로 끝날 때 `Run ... sync:eds to fix.` 다음 줄에서 `AGENTS.md` managed block과 package root의 `QUICKSTART.md`를 UI 작업 전에 읽도록 안내하고, `eds sync` 완료 줄은 검토할 diff(`AGENTS.md`, CSS import, `src/styles/eds-tokens.css`)와 규칙이 있는 위치를 함께 알립니다. `EDS_TAILWIND_ROOT`로 sync에 성공하면 소비처 `package.json`에 `"eds": { "tailwindRoot": "<경로>" }`를 기록하며, `eds sync`와 `eds doctor`는 환경 변수, `package.json` `eds.tailwindRoot`, 자동 검출 순서로 Tailwind root를 정하므로 hook에서 환경 변수를 반복 지정할 필요가 없습니다. 기록된 경로가 존재하지 않으면 exit 2로 안내합니다. Tailwind root 검출은 `@import "tailwindcss/theme.css"`·`"tailwindcss/utilities.css"`와 `@import url("tailwindcss")` 형태도 인식하고, `/* */` 주석 안의 import는 root나 EDS import로 세지 않습니다. `AGENTS.md`의 fenced code block 안에 있는 marker는 예시로 보고 무시하며, marker가 불균형하면 개수와 첫 줄 번호를 출력합니다. `CLAUDE.md`와 `AGENTS.md`가 같은 파일(symlink)이면 `@AGENTS.md` import를 추가하지 않고, `@./AGENTS.md` 표기도 기존 import로 인식합니다. managed block, `CLAUDE.md` import, CSS import는 대상 파일의 줄바꿈(CRLF/LF)을 따라 쓰고, doctor와 sync는 줄바꿈만 다른 파일을 stale이나 쓸 대상으로 보지 않습니다. `postinstall`은 소비처 `package.json`에 `workspaces`가 있으면 script를 등록하지 않고 앱 package 안에서 `npx eds init`을 실행하도록 안내하며, pnpm으로 설치할 때는 pnpm이 설치 중의 `package.json` 편집을 버린다는 점과 `pnpm exec eds init` 실행을 안내합니다.
+- 4fdcd43: 소비처 AI 문서의 라우팅과 판정 규칙을 정리합니다. `AI_CONTEXT.json`의 `readOrder` 항목마다 package root 상대 경로 `file`과 export subpath `specifier`를 함께 기록하고(`path`는 `file`과 같은 값으로 유지), 최상위 `components` 배열과 `pathConvention`, `setup.doctorEnv`를 추가합니다. `QUICKSTART.md`·`AI.md`·`CONSUMER_AGENT.md`·`README.md`·`TOKEN_CONTEXT.md`의 Button 문서와 token manifest 경로를 실제 파일 위치인 `dist/components/Button/`·`dist/tokens.json`으로 고칩니다. managed block과 `QUICKSTART.md`에 컴포넌트 선택 tie-break 한 문장을 추가하고 `AI_CONTEXT.json` precedence에 `eds-managed-block-component-preference`를 넣습니다. 기존 소비처는 `npm run sync:eds`를 한 번 실행하면 block이 갱신됩니다. 취소·닫기·수정은 `neutral/outline`, 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동은 `neutral/weak`로 Button 안내를 하나로 맞춥니다. `typesVersions`를 추가해 `moduleResolution: node` 소비처에서도 `@spectrabrain/eds/tokens` 타입이 해석됩니다. `README.md`의 Button contract 참조는 `components/Button/README.md`·`spec.json`을 직접 가리키고, `TAILWIND_V4.md`의 script 충돌 서술을 `CONSUMER_AGENT.md`와 같게 맞춥니다.
+- dda103c: 손으로만 유지되던 공개 계약 목록을 저장소 검사가 대조합니다. `npm run build`의 public boundary 검사는 `README.md` 공개 경로 표의 `@spectrabrain/eds/...` 경로 집합이 `package.json` exports와 정확히 일치하는지 확인하고, `npm run component-manifest:generate`는 Button context metadata의 `props`·`unsupportedProps` 이름 집합이 `Button.tsx`가 선언한 prop 이름과 같은지 확인하며, 어긋나면 빠진 이름과 남는 이름을 출력하고 실패합니다. CI verify workflow는 `npx changeset status --since=origin/main`을 경고 전용 단계로 실행합니다. 배포 파일에서는 `llms.txt`만 바뀌어 읽기 순서가 `AI_CONTEXT.json`의 `readOrder`와 같아지고 `dist/tokens.json`, `dist/components/Button/README.md`, `dist/components/Button/spec.json`을 package root 기준 파일 경로로 안내합니다.
+- 3922273: Button이 `icon`, `iconName`, `startIcon`, `startIconName`, `endIcon`, `endIconName` 슬롯 prop을 native `<button>`·`<a>` 속성으로 전달하던 문제를 수정합니다. React의 알 수 없는 prop 경고와 DOM의 불필요한 속성이 사라지며 공개 API는 바뀌지 않습니다.
+- ef16f71: `Button` 루트 CSS에서 구현 reset 두 줄(`margin: 0`, `flex: 0 0 auto`)을 제거합니다. 공개 token 값과 컴포넌트 계약은 바뀌지 않으며, 버튼의 margin과 flex 동작은 이제 소비처 레이아웃의 기본값을 따릅니다.
+
+## 0.0.4
+
+### Patch Changes
+
+- af25629: 소비처 AI가 공개 semantic token을 Tailwind CSS v4 alias와 typography utility로 연결할 수 있도록 설치 가이드와 package export를 추가합니다.
+- 5957adf: Button icon-only layout에서 `aria-label`을 선택 사항으로 변경하고, 관련 공개 문서와 타입 계약을 갱신합니다.
+- bb1e81f: 최신 Figma export 기준으로 semantic color 매핑과 내부 grey scale 원본을 동기화하고, `heading4` typography preset을 추가합니다.
+
+## 0.0.3
+
+### Patch Changes
+
+- 31a5151: 소비처 AI가 Button의 사용 맥락과 접근성 계약을 확인할 수 있도록 공개 component 문서, `spec.json`, `llms.txt`를 제공합니다.
+- 67b9ae5: Button loading progress를 버튼 크기 안에 중앙 배치하고, 회전으로 부모 영역이 확장되지 않도록 수정합니다.
+
+## 0.0.2
+
+### Patch Changes
+
+- 6081959: React `Button` 컴포넌트와 허용된 role·variant·size·loading·icon slot contract를 추가합니다. lucide PascalCase 이름과 `ButtonIconName` 자동완성도 제공합니다.
+  Button label typography는 `xs=body3`, `sm·md=title3` semantic preset을 사용합니다. Semantic typography의 `fontWeight-semibold=550` 변경도 포함합니다.
+
+  custom icon slot을 기존 `ReactNode`에서 `ReactElement`로 제한한 변경은 이후 stable release에서 breaking 후보로 검토합니다. 이번 changeset은 `0.0.2` patch 릴리스 준비용으로 기록합니다.
+
+- 86c9c64: 최신 Color 기준에 맞춰 내부 색상 원본과 `color-stroke-brand-weak` semantic token을 갱신합니다. 이번 `0.0.2` patch 릴리스에 포함합니다.

package/CONSUMER_AGENT.md

@@ -0,0 +1,230 @@
+# EVA Design System 소비처 AI 계약
+
+이 문서는 `@spectrabrain/eds`를 설치한 React 웹 저장소의 AI 코딩 에이전트와 자동화 도구를 위한 실행 계약입니다. 설치된 패키지 버전의 공개 문서와 TypeScript contract를 최종 기준으로 사용합니다. 필수 읽기는 package root의 `QUICKSTART.md` 하나이며, 이 문서는 setup·sync·doctor를 다룰 때 읽습니다.
+
+## 설치 직후 읽는 순서
+
+문서 이름이 소비처의 로컬 문서와 충돌할 수 있으므로 `require.resolve("@spectrabrain/eds/package.json")`로 설치된 package root를 먼저 찾고, 그 경로에서 읽습니다. 일반적인 설치에서는 `node_modules/@spectrabrain/eds`가 package root입니다. `AI_CONTEXT.json`은 읽기 경로와 기계용 canonical manifest를 찾는 라우팅 파일이며, 자연어 규칙은 Markdown 문서를 기준으로 합니다. `readOrder`의 `file`은 package root 상대 경로이고 `specifier`는 `require.resolve`에 쓰는 export subpath입니다. `dist/` 아래 파일은 `dist/components/Button/spec.json`처럼 `file` 경로로 읽거나 `@spectrabrain/eds/components/Button/spec.json`처럼 `specifier`로 resolve합니다.
+
+1. package root의 `QUICKSTART.md`를 읽습니다. 필수이며 4 KB 이하입니다.
+2. `AI_CONTEXT.json`의 `readOrder`에서 아래 문서의 조건을 확인하고 해당하는 문서만 읽습니다.
+3. setup·sync·doctor를 다룰 때 이 문서를 읽습니다.
+4. 공개 범위와 금지 사례를 확인할 때 `AI.md`를 읽습니다.
+5. token을 직접 고를 때 `TOKEN_CONTEXT.md`를 읽습니다.
+6. Tailwind CSS v4를 다룰 때 `TAILWIND_V4.md`를 읽습니다.
+7. 컴포넌트를 사용할 때는 package root의 `dist/components/<Component>/README.md`와 `dist/components/<Component>/spec.json`을 읽습니다. 현재 컴포넌트 이름은 `AI_CONTEXT.json`의 `components` 배열에 있습니다.
+8. `llms.txt` 인덱스로 공개 문서가 더 있는지 확인합니다.
+
+문서에 없는 prop·variant·상태·token·deep import는 추측하지 않습니다.
+
+`npm install`만 끝난 저장소에는 setup이 아직 적용되지 않았을 수 있습니다. 소비처 `AGENTS.md`에 아래 managed block이 없거나 `npm run eds:doctor`가 실패하면 UI 작업보다 먼저 `npm run sync:eds`를 실행합니다.
+
+## 소비처 `AGENTS.md` managed block
+
+`npm run sync:eds`가 소비처 저장소의 루트 `AGENTS.md`에 아래 block을 삽입하고 갱신합니다. 파일이 없으면 만들고, 기존 파일의 marker 밖 내용은 보존합니다. sync는 BEGIN marker 바로 다음 줄에 설치된 버전을 나타내는 `<!-- EDS:VERSION x.y.z -->` 줄을 추가하므로 아래 템플릿에는 버전 줄이 없습니다. marker가 중복되거나 한 쪽만 있으면 아무 파일도 쓰지 않고 실패합니다.
+
+템플릿의 `npm run ` 접두는 sync가 감지한 패키지 매니저의 runner(`pnpm `, `yarn `, `bun run `)로 바꿔 씁니다. 그래서 소비처 `AGENTS.md`의 block에는 그 저장소에서 실제로 동작하는 명령이 들어가며, `eds doctor`도 같은 runner로 렌더링한 block과 비교합니다. 이 문서의 나머지 명령도 같은 방식으로 바꿔 읽습니다.
+
+```md
+<!-- EDS:BEGIN -->
+## EVA Design System 사용 규칙
+
+- EDS package root는 `require.resolve("@spectrabrain/eds/package.json")` 또는 `node_modules/@spectrabrain/eds`입니다. UI 작업 전에 그 경로의 `QUICKSTART.md`를 읽고, 추가 문서는 `AI_CONTEXT.json`의 조건에 해당할 때만 읽습니다.
+- 이 block이 없거나 `npm run eds:doctor`가 실패하면 UI 작업보다 먼저 `npm run sync:eds`를 실행합니다.
+- 제공되는 EDS 컴포넌트를 유사한 자체 구현보다 우선 사용합니다. 새 코드와 수정 중인 코드에서는 `Button`을 먼저 검토합니다. 소비처 저장소 규칙이 특정 컴포넌트를 지정하더라도 EDS에 같은 역할의 컴포넌트가 있으면 EDS를 먼저 선택하고, 소비처 규칙이 접근성·보안·제품 요구사항인 경우에만 그것을 우선합니다.
+- 색상은 `text-eds-fg-*`, `bg-eds-bg-*`, `border-eds-stroke-*`를 사용합니다. typography는 `eds-typography-*`를 사용합니다.
+- raw 색상·typography 값, 임의 CSS variable, 패키지 비공개 경로를 만들거나 복사하지 않습니다.
+- 정확한 공개 token이 없으면 `fg/bg/stroke` 역할, 상태, 행동 의미, `neutral` 순서로 가까운 공개 token을 선택합니다.
+- 새 UI 스타일은 Tailwind `className`을 우선 작성합니다. `index.css`에 컴포넌트별 규칙을 추가하지 않습니다.
+- EDS에 없는 컴포넌트를 구현할 때도 공개 semantic color·typography와 소비처 Tailwind 기본 spacing·radius를 사용합니다.
+- 작업 결과에 변경 파일, 최종 사용한 EDS component·token, typecheck·test·build 결과를 기록합니다.
+<!-- EDS:END -->
+```
+
+이 block은 EDS package의 `postinstall`이 삽입하지 않습니다. `npm run sync:eds`가 삽입·갱신하며, 소비처 담당자가 저장소의 기존 규칙과 함께 diff를 검토합니다. 다음 EDS 버전으로 업데이트할 때도 block 안쪽과 버전 줄만 바뀌고 block 밖의 저장소 규칙은 보존됩니다.
+
+## 첫 setup 절차
+
+기본 패키지를 설치하고 동기화합니다.
+
+```sh
+npm install @spectrabrain/eds
+npm run sync:eds
+```
+
+설치와 최초 동기화를 한 번에 실행하려면 `npm install @spectrabrain/eds && npm run sync:eds`를 사용합니다.
+
+npm 10·11에서는 EDS package의 `postinstall`이 소비처 `package.json`에만 다음 script를 등록합니다. 다른 파일은 만들거나 바꾸지 않습니다.
+
+```json
+{
+  "scripts": {
+    "sync:eds": "eds sync",
+    "eds:doctor": "eds doctor",
+    "pretypecheck": "eds doctor",
+    "prebuild": "eds doctor"
+  }
+}
+```
+
+- `sync:eds`와 `eds:doctor`는 항상 등록합니다. 같은 이름의 script가 `eds sync`·`eds doctor`를 포함한 명령(예: `EDS_DOCTOR=warn eds doctor`)이면 호환으로 보고 그대로 둡니다. 다른 명령이면 덮어쓰지 않고 안내만 출력하며 설치는 실패하지 않습니다. 이 경우 `eds doctor`가 `scripts:` 항목으로 보고합니다. 이전 EDS 버전이 등록한 알려진 `sync:eds` 명령은 `eds sync`로 바꾸고, 이전 runner를 가리키던 `update:eds-agent-context`·`generate:eds-tailwind`는 제거합니다. 소비처가 직접 작성한 명령은 그대로 둡니다.
+- `pretypecheck`·`prebuild`는 소비처에 `typecheck`·`build` script가 있고 같은 이름의 pre-hook이 없을 때만 등록합니다. 이미 다른 pre-hook이 있으면 그대로 두고 안내만 출력합니다. `predev`에는 연결하지 않습니다.
+- 소비처 `package.json`에 `workspaces`가 있으면 그 디렉터리는 앱이 아니라 workspace root이므로 script를 등록하지 않고, `@spectrabrain/eds`에 의존하는 앱 package 안에서 `npx eds init`을 실행하도록 안내만 출력합니다. pnpm으로 설치할 때는 pnpm이 설치 중에 이루어진 `package.json` 편집을 버리므로 postinstall은 등록하지 않고 `pnpm exec eds init` 실행을 안내합니다.
+
+### 의존성 install script를 실행하지 않는 환경
+
+npm 12, pnpm 10, yarn berry, bun은 기본 설정에서 의존성의 install script를 실행하지 않으므로 postinstall 등록이 일어나지 않으며, `npm install --ignore-scripts`를 사용하는 환경도 같습니다. 이 경우 설치 뒤 다음 명령으로 같은 script를 등록하고 첫 동기화까지 실행합니다. 설치가 끝난 저장소에서는 `npx eds init`도 같은 CLI를 실행합니다.
+
+```sh
+npx @spectrabrain/eds init
+```
+
+`init`은 `npm_config_user_agent`(없으면 lockfile 이름)로 패키지 매니저를 판별하고, 등록하는 script 값은 어느 환경에서도 위 JSON과 같습니다. 패키지 매니저별 추가 동작은 다음과 같습니다.
+
+| 패키지 매니저 | `init`의 추가 동작 |
+| --- | --- |
+| npm 12 이상 | 소비처 `package.json`에 `allowScripts["@spectrabrain/eds"]: true`(이름만, 버전 pin 없음)를 키가 없을 때만 기록하고 기록한 내용을 출력합니다. 이후 설치·업그레이드에서 postinstall이 자동 실행됩니다. `--no-allow-scripts`로 이 기록을 건너뜁니다. |
+| pnpm | 파일을 쓰지 않고 `pnpm approve-builds` 또는 `pnpm.onlyBuiltDependencies` 설정 snippet을 출력합니다. |
+| bun | `trustedDependencies` 설정 안내를 출력합니다. 이 필드를 설정하면 bun의 기본 신뢰 목록이 대체되므로 함께 경고합니다. |
+| yarn berry | `enableScripts`·`dependenciesMeta` 설정 안내를 출력합니다. yarn berry는 `pre`·`post` hook을 실행하지 않으므로 `typecheck`·`build` script 앞에 `eds doctor && `를 직접 붙이라는 안내도 출력하며, `init`이 그 script를 수정하지는 않습니다. |
+
+`npm exec -- @spectrabrain/eds init --no-sync`는 script만 등록하고 `npm run sync:eds` 실행을 안내합니다. `init`에 옵션을 넘길 때는 npm이 옵션을 자기 설정으로 해석하지 않도록 `npm exec --` 뒤에 적습니다. `init`은 현재 디렉터리에 `package.json`과 설치된 `@spectrabrain/eds`가 있어야 하며, 없으면 안내와 함께 실패합니다.
+
+`npx eds init --print-ci gitlab` 또는 `--print-ci github`는 CI에서 `npx eds doctor`를 실행하는 job snippet을 출력합니다. 파일은 쓰지 않으며 소비처가 CI 설정에 직접 붙입니다.
+
+## Tailwind root와 sync 적용 순서
+
+`eds sync`와 `eds doctor`는 환경 변수 `EDS_TAILWIND_ROOT`, 소비처 `package.json`의 `eds.tailwindRoot`, 자동 검출 순서로 Tailwind root를 정합니다. 자동 검출은 `@import "tailwindcss"`가 있는 소비처 CSS 파일 하나를 root로 사용하며, `@import "tailwindcss/theme.css"`·`@import "tailwindcss/utilities.css"`와 `@import url("tailwindcss")` 형태도 인식하고 `/* */` 주석 안의 import는 세지 않습니다. `node_modules`, `dist`, `build`, `.git`, `storybook-static`, `coverage`와 생성 파일은 후보에서 제외합니다. 후보가 2개 이상이면 후보 목록을 출력하고 아무 파일도 쓰지 않은 채 실패하므로, 다음처럼 root를 한 번 지정합니다.
+
+```sh
+EDS_TAILWIND_ROOT=src/app/styles/index.css npm run sync:eds
+```
+
+`EDS_TAILWIND_ROOT`로 sync에 성공하면 sync가 소비처 `package.json`에 `"eds": { "tailwindRoot": "src/app/styles/index.css" }`를 기록하므로, 이후 `eds doctor`, `eds sync`, `pretypecheck`·`prebuild` hook은 환경 변수 없이 같은 root를 사용합니다. `--dry-run`은 기록할 내용만 출력합니다. `EDS_TAILWIND_ROOT`나 `eds.tailwindRoot`가 존재하지 않는 파일을 가리키면 exit 2로 실패하고 경로를 고치거나 키를 제거하라고 안내합니다.
+
+후보가 0개이고 `EDS_TAILWIND_ROOT`와 `eds.tailwindRoot`도 없으면 Tailwind를 사용하지 않는 저장소로 보고 Tailwind 배선을 건너뜁니다. `src/styles/eds-tokens.css`를 만들지 않고 CSS root도 고치지 않으며 안내 한 줄만 출력합니다. 이 상태에서 `eds doctor`는 Tailwind 관련 항목을 보고하지 않습니다.
+
+sync는 모든 변경을 먼저 계산한 뒤 다음 순서로 씁니다. 계산 중 실패하면 어떤 파일도 바꾸지 않습니다.
+
+1. `src/styles/eds-tokens.css`를 생성하고, Tailwind root의 마지막 Tailwind import(`@import "tailwindcss";` 또는 `tailwindcss/theme.css`·`tailwindcss/utilities.css`) 바로 다음 줄에 `@import "@spectrabrain/eds/styles.css";`와 생성 CSS의 상대 경로 `@import`를 추가합니다. 주석 처리된 import는 이미 있는 import로 세지 않습니다. 같은 파일이 이미 import되어 있으면 다시 추가하지 않습니다.
+2. `src/` 아래 JS·TS 파일에서 `eds-tokens.css`를 import하는 줄을 제거합니다. Tailwind는 JS에서 import한 CSS를 compile하지 않기 때문입니다. `@spectrabrain/eds/styles.css`의 기존 JS import는 유지합니다.
+3. `AGENTS.md` managed block을 삽입하거나 갱신합니다. fenced code block(```` ``` ````·`~~~`) 안의 marker는 예시로 보고 무시하며, 그 밖의 marker가 불균형하면 개수와 첫 marker의 줄 번호를 출력하고 실패합니다.
+4. `CLAUDE.md`가 있을 때만 `@AGENTS.md` import 줄을 한 번 추가합니다. 파일이 없으면 만들지 않으며, `@./AGENTS.md` 줄이 이미 있거나 `CLAUDE.md`가 `AGENTS.md`와 같은 파일(symlink)이면 추가하지 않습니다.
+5. `GEMINI.md`가 있을 때만 `@./AGENTS.md` import 줄을 같은 규칙으로 한 번 추가합니다. Gemini CLI가 기본으로 읽는 파일이 `GEMINI.md`이기 때문이며, Codex·Cursor·Copilot·Windsurf는 `AGENTS.md`를 직접 읽습니다.
+
+managed block, `CLAUDE.md`·`GEMINI.md` import, CSS import는 대상 파일의 줄바꿈(CRLF·LF)을 따라 쓰고, 생성 CSS는 LF로 씁니다.
+
+`src/index.css`가 root이면 결과는 다음과 같습니다.
+
+```css
+@import "tailwindcss";
+@import "@spectrabrain/eds/styles.css";
+@import "./styles/eds-tokens.css";
+```
+
+`src/app/styles/index.css`가 root이면 생성 CSS의 위치를 기준으로 상대 경로가 달라집니다.
+
+```css
+@import "tailwindcss";
+@import "@spectrabrain/eds/styles.css";
+@import "../../styles/eds-tokens.css";
+```
+
+생성 CSS의 `@theme inline`에는 공개 color alias와 함께 `--font-sans: var(--eds-typography-body1-fontFamily);` 한 줄이 들어가므로 Tailwind의 기본 sans font가 Pretendard가 됩니다.
+
+`@spectrabrain/eds/styles.css`는 어떤 CSS나 JS·TS 소스가 이미 import하고 있으면 추가하지 않습니다. `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/components.css`, `@spectrabrain/eds/fonts.css`가 모두 import되어 있는 경우도 같습니다. `tokens.css`와 `components.css`만 import되어 있고 `fonts.css`가 없으면 sync가 Tailwind root에 `@import "@spectrabrain/eds/fonts.css";`를 추가합니다.
+
+`npm run sync:eds -- --only tailwind`와 `npm run sync:eds -- --only agents`는 해당 부분만 적용하고, `--dry-run`은 파일을 쓰지 않고 `would write <경로>`만 출력합니다. 두 옵션 모두 검증은 전체를 수행합니다. 파일을 쓴 sync는 `[EDS] Synced with @spectrabrain/eds@<version>. Review the diff (AGENTS.md, CSS imports, src/styles/eds-tokens.css) before committing; the AGENTS.md block lists the rules.`로 끝나므로 diff를 검토한 뒤 커밋하고, 바꿀 것이 없으면 `[EDS] Already synced with @spectrabrain/eds@<version>.`을 출력합니다.
+
+기존 전역 CSS와 Tailwind 설정은 보존합니다. 새 컴포넌트의 고유한 표현은 전역 stylesheet보다 Tailwind `className`을 우선 사용합니다.
+
+## font 정책
+
+EDS text style은 font family `Pretendard`를 참조하며, 이 family는 `@spectrabrain/eds/fonts.css`가 선언합니다. 따라서 EDS의 `fonts.css`는 생략할 수 없습니다.
+
+- 기본 구성은 `@spectrabrain/eds/styles.css` 하나입니다. `fonts.css`, `tokens.css`, `base.css`, `components.css`를 순서대로 불러옵니다.
+- 개별 파일로 구성할 때는 `@spectrabrain/eds/tokens.css`, `@spectrabrain/eds/components.css`, `@spectrabrain/eds/fonts.css`를 함께 import합니다. `@spectrabrain/eds/base.css`는 `:where(html)`에 body1 font family를 지정하는 선택 파일이며, 소비처가 `html`의 `font-family`를 직접 관리한다면 생략할 수 있습니다.
+- 소비처가 CDN·`<link>`·자체 `@font-face`로 Pretendard를 따로 불러오는 구성은 EDS `fonts.css`를 대체하지 못합니다. 다른 family 이름으로 선언된 Pretendard는 EDS text style이 참조하지 않기 때문입니다. 이 경우에도 EDS `fonts.css`를 유지하고, 중복 선언은 소비처가 정리합니다.
+
+`eds doctor`는 `@spectrabrain/eds/styles.css`와 `@spectrabrain/eds/fonts.css`가 CSS·JS·TS 어디에서도 import되지 않으면 `missing:`으로 보고합니다. `index.html`이나 CSS에서 다른 출처의 Pretendard를 함께 참조하고 있으면 `note:` 한 줄을 출력하며, 이 줄은 exit code에 영향을 주지 않습니다.
+
+## `eds:doctor` 점검
+
+`npm run eds:doctor`는 아무 파일도 쓰지 않고 `npm run sync:eds`가 무언가를 바꿀지 판정합니다. postinstall 또는 `init`이 등록한 `pretypecheck`·`prebuild` hook이 같은 점검을 typecheck·build 전에 실행합니다.
+
+- exit 0은 동기화된 상태입니다. `[EDS] synced with @spectrabrain/eds@<version>: ...` 한 줄을 출력합니다.
+- exit 1은 고칠 항목이 있는 상태입니다. `sync:eds`·`eds:doctor` script 미등록이나 다른 명령으로의 등록, `src/styles/eds-tokens.css` 누락·구버전, root CSS import 누락, JS에 남은 `eds-tokens.css` import, 소스의 `eds-*` class 중 공개 token이 없는 이름(`unknown: <파일:줄> <class>`), EDS font import 누락, `AGENTS.md` block 누락·불량·구버전, `CLAUDE.md`의 `@AGENTS.md` 줄 누락, `GEMINI.md`의 `@./AGENTS.md` 줄 누락을 `[EDS] <종류>: ...` 줄로 출력한 뒤 `[EDS] Run npm run sync:eds to fix.`와 `[EDS] Then read the AGENTS.md managed block and QUICKSTART.md in the package root before UI work.` 두 줄로 끝납니다. `sync:eds`가 `eds sync`를 실행하지 않는 상태면 첫 줄은 `[EDS] Run npx eds sync to fix.`가 됩니다. 안내한 명령을 실행한 뒤 두 문서를 읽습니다. 줄바꿈(CRLF·LF) 차이만 있는 파일은 stale로 보지 않습니다.
+- exit 2는 판정할 수 없는 상태입니다. `@spectrabrain/eds`가 설치되지 않았거나, 소비처 `package.json`을 읽을 수 없거나, Tailwind root 후보가 2개 이상이거나, `EDS_TAILWIND_ROOT` 또는 `package.json`의 `eds.tailwindRoot`가 존재하지 않는 파일을 가리키는 경우입니다. 설치 상태, `EDS_TAILWIND_ROOT`, `eds.tailwindRoot`를 확인합니다.
+
+`npm run eds:doctor -- --warn`은 같은 출력에 exit 0으로 끝나며 `EDS_DOCTOR=warn`과 같습니다. `EDS_DOCTOR=off`는 출력 없이 exit 0으로 끝납니다. hook 때문에 typecheck·build가 막히면 원인을 고치는 것을 우선하고 `--warn`은 임시로만 사용합니다.
+
+`npm run eds:doctor -- --scan`은 여기에 더해 Tailwind 기본 팔레트(`text-red-500`), `white`·`black`, 임의 색(`bg-[#…]`) class를 `raw: <파일:줄> <class>` 줄로 나열합니다. 정보 제공용이라 exit code를 바꾸지 않으며, 새 코드에 raw 색이 남지 않았는지 검토할 때 사용합니다. `unknown:`과 `raw:` 검사는 Tailwind root가 있는 저장소에서만 실행합니다.
+
+## 소비처 온보딩
+
+소비처 저장소의 `CLAUDE.md` 또는 `AGENTS.md` 상단에 다음 한 줄을 담당자가 직접 넣습니다. 이 줄은 `npm install`만 끝난 상태에서도 AI가 설치된 계약을 먼저 읽고 sync를 실행하게 합니다.
+
+> package.json에 `@spectrabrain/eds`가 있으면 UI 작업 전에 `node_modules/@spectrabrain/eds/QUICKSTART.md`를 먼저 읽고, `npm run eds:doctor`가 실패하면 `npm run sync:eds`를 먼저 실행합니다.
+
+`CLAUDE.md`가 있는 저장소에서는 `npm run sync:eds`가 파일 끝에 `<!-- EDS:CLAUDE:BEGIN -->`와 `<!-- EDS:CLAUDE:END -->` 사이의 `@AGENTS.md` 한 줄을 한 번만 추가해 Claude Code가 `AGENTS.md`의 managed block을 함께 읽게 합니다. `CLAUDE.md`가 없으면 만들지 않고, `@./AGENTS.md`가 이미 있거나 `CLAUDE.md`가 `AGENTS.md`의 symlink이면 추가하지 않습니다. `GEMINI.md`가 있으면 같은 방식으로 `<!-- EDS:GEMINI:BEGIN -->`와 `<!-- EDS:GEMINI:END -->` 사이에 `@./AGENTS.md`를 추가해 Gemini CLI도 block을 읽게 합니다. Codex·Cursor·Copilot·Windsurf는 `AGENTS.md`를 직접 읽으므로 추가 파일이 필요 없습니다.
+
+## AI 작업 프로토콜
+
+각 UI 작업은 다음 순서로 수행합니다.
+
+1. 요청 범위와 소비처의 `AGENTS.md`, 테스트·보안·접근성 규칙을 확인합니다.
+2. `QUICKSTART.md`를 읽고, `AI_CONTEXT.json`의 조건에 따라 필요한 Markdown 문서와 JSON manifest만 추가로 읽습니다.
+3. 화면의 행동·정보 위계를 먼저 정하고, 해당 역할의 EDS component와 semantic token을 선택합니다.
+4. 선택한 공개 contract로 표현할 수 있는지 확인한 뒤 Tailwind `className` 중심으로 구현합니다.
+5. 새 token·prop·variant·상태를 발명하지 않고, exact token이 없을 때만 `AI_CONTEXT.json`의 nearest-token 순서를 적용합니다.
+6. 변경 후 관련 typecheck·test·build와 `npm run eds:doctor` 결과를 확인합니다.
+7. 완료 보고에 변경 파일, 최종 component·token, 실행한 검증을 남깁니다.
+
+문서 설명과 JSON manifest가 충돌하면 공개 token 이름·component prop·접근성 동작은 JSON manifest와 TypeScript contract를 우선합니다. 사용자의 요구사항, 소비처 저장소 규칙, 접근성·보안 제약은 EDS 권고보다 항상 우선합니다. 다만 위 managed block은 sync가 소비처 `AGENTS.md`에 넣는 소비처 규칙의 일부이므로, 컴포넌트 선택은 block의 tie-break 문장을 따릅니다. 소비처 규칙이 특정 컴포넌트를 지정하더라도 EDS에 같은 역할의 컴포넌트가 있으면 EDS를 먼저 선택하고, 그 규칙이 접근성·보안·제품 요구사항일 때만 소비처 규칙을 우선합니다.
+
+다음 상황에서는 임의 구현을 계속하지 않고 범위를 멈춰 확인합니다.
+
+- 공개 manifest에 없는 prop·variant·상태를 요구받은 경우
+- 의미 역할에 맞는 공개 token이 없고 가까운 역할도 선택할 수 없는 경우
+- Tailwind root 후보가 2개 이상인데 `EDS_TAILWIND_ROOT`도 `package.json`의 `eds.tailwindRoot`도 없는 경우
+- 기존 소비처 규칙과 EDS setup이 충돌해 파일을 안전하게 보존할 수 없는 경우
+
+## 작업 우선순위
+
+1. 사용자의 명시적인 요구사항과 제품의 접근성·보안·기능 규칙을 지킵니다.
+2. 현재 저장소의 `AGENTS.md`, `README.md`, 테스트와 기존 컴포넌트 계약을 확인합니다. 로컬 컴포넌트를 지정한 규칙과 EDS 컴포넌트가 겹치면 managed block의 tie-break를 따릅니다.
+3. 설치된 EDS의 공개 문서와 TypeScript contract를 확인합니다.
+4. 기능이 일치하는 EDS component와 semantic token을 우선 선택합니다.
+5. EDS에 없는 기능만 소비처에서 구현하고, 구현에도 공개 token과 Tailwind className을 사용합니다.
+
+기존 레거시 구현을 한 번에 교체하지 않습니다. 수정 범위에 포함된 코드와 새 코드부터 계약을 적용합니다. 기존 local Button wrapper는 EDS `Button` contract로 표현할 수 없는 기능이 있을 때만 유지합니다.
+
+## token 선택 규칙
+
+- 색상 역할은 `fg`, `bg`, `stroke`를 먼저 결정합니다.
+- 그다음 행동 의미와 상태(`brand`, `neutral`, `critical`, `informative`, `positive`, `warning`, `disabled`, `hover`, `focus`)를 맞춥니다.
+- exact token이 없으면 `fg/bg/stroke` 역할, 상태(`primary`, `weak`, `disabled`, `hover`, `focus`), 행동 의미, `neutral` 순서로 가까운 공개 token을 선택합니다.
+- token 이름과 CSS variable은 `@spectrabrain/eds/tokens.json`과 `@spectrabrain/eds/tokens`의 공개 목록만 사용합니다.
+
+text style은 font family, font weight, font size, line height, letter spacing을 한 preset으로 적용합니다. 하나의 속성만 임의로 바꿔 기존 의미를 해석하지 않습니다.
+
+## 컴포넌트 규칙
+
+컴포넌트를 구현하기 전에 해당 README와 `spec.json`의 API·사용 맥락·접근성 계약을 읽습니다. 문서에 없는 prop이나 상태를 `className`, inline style, 임의 CSS로 우회하지 않습니다.
+
+`Button`은 행동의 의미와 위계를 기준으로 선택합니다. `brand/solid`는 핵심 행동, `neutral/solid`는 일반 주요 행동, `neutral/outline`은 취소·닫기·수정 같은 보조 작업, `neutral/weak`는 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동에 사용합니다. 되돌리기 어려운 삭제·초기화는 `critical/weak`를 먼저 검토합니다. `neutral/link`는 탐색에만 사용합니다.
+
+icon-only 버튼은 accessible name을 확인하고, 비동기 처리 중인 버튼은 공개 `loading` contract를 사용합니다. Button 내부 시각 스타일을 `className`으로 덮어쓰지 않습니다. 이름으로 지정하는 lucide 아이콘은 `spec.json`의 `api.iconNames` 목록만 사용하며, 목록 밖 아이콘은 `icon`·`startIcon`·`endIcon`에 ReactElement로 전달합니다.
+
+## 버전 업데이트
+
+EDS 버전을 업데이트한 뒤 다음 명령을 실행해 Tailwind root의 import, 공개 token alias, managed block과 버전 줄을 함께 갱신하고 결과를 점검합니다.
+
+```sh
+npm run sync:eds
+npm run eds:doctor
+```
+
+`eds:doctor`는 생성 CSS의 header와 `AGENTS.md`의 버전 줄이 설치된 버전과 다르면 `stale:`로 보고하고 exit 1로 끝나므로, sync를 빠뜨린 업데이트는 `pretypecheck`·`prebuild` hook에서 드러납니다. 생성 파일의 변경을 검토하고 소비처의 typecheck·lint·test·build를 실행합니다. `sync:eds`는 소비처 CI에서 명시적으로 실행할 수 있으며, EDS package의 `postinstall`은 이를 자동 실행하지 않습니다.
+
+바뀐 내용은 package root의 `CHANGELOG.md`(`@spectrabrain/eds/CHANGELOG.md`)에서 확인합니다. 작업 보고에는 업데이트된 EDS 버전, 생성 파일, 새로 사용할 수 있는 class, 제거되거나 이름이 바뀐 공개 token, 검증 결과를 남깁니다.