@spectrabrain/eds 0.1.0 → 0.1.1

package/consumer/update-agent-context.mjs

@@ -1,17 +1,21 @@
+import fs from "node:fs";
 import path from "node:path";
 import { applyBlock, locateBlock, maskFencedBlocks, readBlockVersion, readTemplateBlock, renderBlock } from "./managed-block.mjs";
-import { detectEol, readTextIfExists, realpathOrNull, relativeTo, withEol } from "./paths.mjs";
+import { detectEol, findGitRoot, readTextIfExists, realpathOrNull, relativeTo, toPosix, withEol } from "./paths.mjs";
 
 export const claudeBeginMarker = "<!-- EDS:CLAUDE:BEGIN -->";
 export const claudeEndMarker = "<!-- EDS:CLAUDE:END -->";
 export const claudeImportLine = "@AGENTS.md";
+export const claudeNestedImportLine = "@../AGENTS.md";
 export const geminiBeginMarker = "<!-- EDS:GEMINI:BEGIN -->";
 export const geminiEndMarker = "<!-- EDS:GEMINI:END -->";
 // Gemini CLI documents its import syntax with an explicit relative path.
 export const geminiImportLine = "@./AGENTS.md";
 
-// Claude Code and Gemini CLI accept `@AGENTS.md` and `@./AGENTS.md` as the same import and ignore fenced code blocks.
-const importPattern = /^[ \t]*@(?:\.\/)?AGENTS\.md[ \t]*$/m;
+// Claude Code and Gemini CLI accept `@AGENTS.md`, `@./AGENTS.md` and (from .claude/) `@../AGENTS.md` and ignore fenced
+// code blocks.
+const importPattern = /^[ \t]*@(?:\.\.?\/)?AGENTS\.md[ \t]*$/m;
+const endMarkerText = "<!-- EDS:END -->";
 
 export function planAgentContext({ consumerRoot, pkg, packageManager = null }) {
   const filePath = path.join(consumerRoot, "AGENTS.md");
@@ -59,18 +63,20 @@ function planImportFile({ consumerRoot, fileName, label, beginMarker, endMarker,
   const after = hasImport(before, beginMarker, endMarker)
     ? before
     : (trimmed ? trimmed + eol + eol + block + eol : block + eol);
-  return { label, path: filePath, relativePath: relativeTo(consumerRoot, filePath), before, after };
+  return { label, path: filePath, relativePath: relativeTo(consumerRoot, filePath), importLine, before, after };
 }
 
-// Claude Code reads CLAUDE.md; the import makes it follow the AGENTS.md managed block.
+// Claude Code reads CLAUDE.md or .claude/CLAUDE.md instead of AGENTS.md when either exists, so the import goes into
+// whichever the consumer has (CLAUDE.md first). Imports resolve relative to the importing file.
 export function planClaudeImport({ consumerRoot }) {
+  const nested = !fs.existsSync(path.join(consumerRoot, "CLAUDE.md")) && fs.existsSync(path.join(consumerRoot, ".claude", "CLAUDE.md"));
   return planImportFile({
     consumerRoot,
-    fileName: "CLAUDE.md",
+    fileName: nested ? path.join(".claude", "CLAUDE.md") : "CLAUDE.md",
     label: "claude",
     beginMarker: claudeBeginMarker,
     endMarker: claudeEndMarker,
-    importLine: claudeImportLine,
+    importLine: nested ? claudeNestedImportLine : claudeImportLine,
   });
 }
 
@@ -85,3 +91,53 @@ export function planGeminiImport({ consumerRoot }) {
     importLine: geminiImportLine,
   });
 }
+
+const codexBudgetBytes = 32 * 1024;
+
+// Where the block may not reach an agent even though AGENTS.md is synced. Notes never change an exit code.
+export function planDeliveryNotes({ consumerRoot, agents, packageManager = null }) {
+  const notes = [];
+  if (packageManager?.pnp) {
+    notes.push(
+      "Yarn Plug'n'Play detected: the EDS docs the AGENTS.md block points to are not in node_modules/@spectrabrain/eds, " +
+        "and EDS support for Plug'n'Play is undecided. Ask the repository owner before changing nodeLinker.",
+    );
+  }
+  const exists = (relativePath) => fs.existsSync(path.join(consumerRoot, relativePath));
+  const hasClaude = exists("CLAUDE.md") || exists(path.join(".claude", "CLAUDE.md"));
+  if (!hasClaude && exists("CLAUDE.local.md")) {
+    notes.push("CLAUDE.local.md exists but CLAUDE.md does not, so Claude Code reads CLAUDE.local.md instead of AGENTS.md; add a CLAUDE.md and run sync again (sync adds the import).");
+  } else {
+    // Claude Code is named whenever it has no file. Gemini CLI only rides along then: a repository that set up
+    // CLAUDE.md and no GEMINI.md most likely does not use Gemini, and a note on every run would be noise.
+    const missing = hasClaude ? [] : ["Claude Code (CLAUDE.md)", ...(exists("GEMINI.md") ? [] : ["Gemini CLI (GEMINI.md)"])];
+    if (missing.length > 0) {
+      notes.push(
+        "no instruction file for " + missing.join(" or ") + " here, so " + (missing.length > 1 ? "they" : "it") +
+          " may not load the EDS block in AGENTS.md (Codex reads AGENTS.md). If the team uses " + (missing.length > 1 ? "them" : "it") +
+          ", create that file and run sync again; sync adds the import.",
+      );
+    }
+  }
+  if (exists("AGENTS.override.md")) {
+    notes.push("AGENTS.override.md exists; Codex reads it instead of AGENTS.md, so copy or import the EDS block there.");
+  }
+  const endIndex = agents?.after?.indexOf(endMarkerText) ?? -1;
+  if (endIndex >= 0 && Buffer.byteLength(agents.after.slice(0, endIndex), "utf8") > codexBudgetBytes) {
+    notes.push("the EDS block in AGENTS.md ends after the first 32 KiB, where Codex truncates by default; move the block toward the top (sync keeps it where it is).");
+  }
+  const gitRoot = findGitRoot(consumerRoot);
+  const packageRelative = gitRoot === null ? "" : toPosix(path.relative(gitRoot, consumerRoot));
+  if (packageRelative !== "") {
+    const pointer = packageRelative + "/AGENTS.md";
+    const rootMentions = ["AGENTS.md", "CLAUDE.md"].some((fileName) => (readTextIfExists(path.join(gitRoot, fileName)) ?? "").includes(pointer));
+    if (!rootMentions) {
+      notes.push(
+        "this package is " + packageRelative + " inside the repository; agents started at the repository root do not load " + pointer +
+          " by default. Add to the root AGENTS.md or CLAUDE.md: \"Before working in " + packageRelative + ", read " + pointer +
+          " and run its commands from " + packageRelative + ".\"",
+      );
+    }
+  }
+  return notes;
+}

package/consumer-postinstall.mjs

@@ -12,7 +12,7 @@ if (!consumerRoot || path.resolve(consumerRoot) === packageRoot) {
 
 const consumerPackagePath = path.join(consumerRoot, "package.json");
 if (!fs.existsSync(consumerPackagePath)) {
-  console.log("[EVA Design System] Consumer package.json was not found; run the documented setup manually.");
+  console.log("[EDS] Consumer package.json was not found; run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
   process.exit(0);
 }
 
@@ -26,13 +26,13 @@ function realpathOrNull(filePath) {
 
 const installedPath = realpathOrNull(path.join(consumerRoot, "node_modules", "@spectrabrain", "eds"));
 if (installedPath === null || installedPath !== realpathOrNull(packageRoot)) {
-  console.log("[EVA Design System] Skipping consumer setup: this install is not the consumer's node_modules/@spectrabrain/eds. Run npx @spectrabrain/eds init from the consumer root if needed.");
+  console.log("[EDS] Skipping consumer setup: this install is not the consumer's node_modules/@spectrabrain/eds. Run npx @spectrabrain/eds init in the package that depends on @spectrabrain/eds.");
   process.exit(0);
 }
 
 // pnpm rewrites the consumer package.json after dependency lifecycle scripts, so edits made here are lost.
 if (String(process.env.npm_config_user_agent ?? "").startsWith("pnpm/")) {
-  console.log("[EVA Design System] pnpm discards package.json edits made during install; run pnpm exec eds init to register the EDS scripts.");
+  console.log("[EDS] pnpm discards package.json edits made during install; run pnpm exec eds init to register the EDS scripts.");
   process.exit(0);
 }
 
@@ -40,20 +40,21 @@ let consumerPackage;
 try {
   consumerPackage = JSON.parse(fs.readFileSync(consumerPackagePath, "utf8"));
 } catch (error) {
-  console.log("[EVA Design System] Consumer package.json could not be parsed (" + error.message + "); run npx @spectrabrain/eds init after fixing it.");
+  console.log("[EDS] Consumer package.json could not be parsed (" + error.message + "); run npx @spectrabrain/eds init after fixing it.");
   process.exit(0);
 }
 
 // A workspaces root hoists the package but is not the app that uses it: registering the scripts and hooks
 // there would make the root build look for src/styles/eds-tokens.css and AGENTS.md in the wrong place.
 if (consumerPackage.workspaces !== undefined) {
-  console.log("[EVA Design System] Skipping consumer setup: package.json declares workspaces. Run npx eds init inside the app package that depends on @spectrabrain/eds.");
+  console.log("[EDS] Skipping consumer setup: package.json declares workspaces. Run npx @spectrabrain/eds init inside the app package that depends on @spectrabrain/eds.");
   process.exit(0);
 }
 
 // The install must never fail because of this setup step; anything unexpected is reported and left to eds doctor.
 try {
-  registerConsumerScripts(consumerRoot);
+  const result = registerConsumerScripts(consumerRoot);
+  console.log("[EDS] Run " + result.syncRunCommand + " to finish setup.");
 } catch (error) {
-  console.log("[EVA Design System] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + "). Run npx eds init to register the EDS scripts.");
+  console.log("[EDS] Consumer setup was skipped (" + (error instanceof Error ? error.message : String(error)) + "). Run npx @spectrabrain/eds init to register the EDS scripts.");
 }

package/dist/components/Button/README.md

@@ -1,31 +1,47 @@
-# Button — 개요, 사용 맥락, 공개 API
+# Button
 
-이 문서는 `Button` 디렉토리의 기준 문서입니다. `Button`의 개요·사용 맥락·공개 API·접근성 계약을 기록합니다. Button을 사용하기 전에는 이 문서를 먼저 확인합니다.
-
-패키지 설치와 공개 경로는 루트 [README.md](../../../README.md)를, 소비처 AI의 필수 규칙은 루트 [QUICKSTART.md](../../../QUICKSTART.md)를, 공개 범위와 금지 사례는 루트 [AI.md](../../../AI.md)를 참고합니다. 루트 문서에는 컴포넌트별 정책을 중복해서 기록하지 않습니다.
+`Button`의 사용 맥락·공개 API·접근성 계약입니다. 소비처 AI의 필수 규칙은 루트 [QUICKSTART.md](../../../QUICKSTART.md)에 있습니다.
 
 ## 개요
 
 `Button`은 사용자가 즉시 실행할 수 있는 행동을 표현하는 인터랙티브 요소입니다. `Size`, `Layout`, `Role`, `Variant`, `State`로 버튼의 크기·구조·의미·위계·상태를 정의합니다.
 
-탐색 목적의 링크는 `neutral/link` 조합으로 표현하고, 상태 변경·폼 제출·명령 실행은 native `<button>`으로 표현합니다. `Button`은 현재 React 웹과 light theme만 지원합니다.
+탐색 목적의 링크는 `neutral/link` 조합으로 표현하고, 상태 변경·폼 제출·명령 실행은 native `<button>`으로 표현합니다.
+
+```tsx
+<Button size="sm" role="brand" variant="solid" type="submit" loading={isSaving}>저장</Button>
+<Button size="sm" role="neutral" variant="outline" type="button" onClick={onCancel}>취소</Button>
+<Button size="sm" role="neutral" variant="link" href="/docs" endIconName="ArrowRight">자세히 보기</Button>
+<Button size="xs" role="neutral" variant="ghost" type="button" iconName="Trash" aria-label="행 삭제" />
+```
+
+loading 중에도 라벨은 그대로 둡니다. icon-only는 `aria-label`을 타입으로 강제하지 않으므로 마지막 예시처럼 직접 지정합니다.
+
+## 사용 맥락
+
+### Role과 Variant
 
-화면에서 반복되는 행동 맥락은 다음처럼 선택합니다.
+`role`은 색상 취향이 아니라 버튼이 수행하는 행동의 의미입니다. `brand`는 브랜드와 관련되거나 화면에서 가장 중요한 행동, `neutral`은 `brand`보다 낮은 주목도가 필요한 일반적인 액션과 탐색, `critical`은 삭제·초기화처럼 되돌리기 어려운 위험한 행동입니다. `role`은 시각적 prop이며 DOM의 ARIA `role` 속성으로 전달하지 않고, ARIA role을 따로 지정하는 방법은 없습니다. `variant`는 같은 role 안의 시각적 위계입니다.
 
-| 행동 맥락 | 우선 검토할 조합 | 설명 |
+| 행동 | 조합 | 설명 |
 | --- | --- | --- |
 | 생성·저장·관리·확인처럼 화면의 핵심 행동 | `brand/solid` | 사용자가 완료해야 할 대표 행동을 강조합니다. 한 화면에 하나를 권장합니다. |
-| 검색·조회·일반적인 주요 실행 | `neutral/solid` | 브랜드 핵심 행동보다 낮은 주목도로 주요 액션을 표현합니다. |
+| `brand/solid`보다 낮은 위계의 브랜드 보조 행동 | `brand/outline` | 브랜드 맥락의 보조 행동입니다. |
+| 검색·조회·일반적인 주요 실행 | `neutral/solid` | `brand/solid` 다음 위계의 주요 CTA입니다. 한 화면에 하나를 권장합니다. |
 | 취소·닫기·수정 같은 보조 작업 | `neutral/outline` | 주 행동과 시각적 위계를 분리합니다. |
-| 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동 | `neutral/weak` | CTA를 보조하면서 반복 가능한 행동을 표현합니다. 되돌리기 어려운 초기화는 `critical/weak`입니다. |
-| 되돌리기 어려운 삭제·초기화 | `critical/weak` | 위험을 분명히 전달하고 가능하면 확인 절차와 함께 사용합니다. |
-| 비동기 저장·확인 처리 | 선택한 조합과 `loading` | 중복 실행을 막고 라벨·아이콘 공간과 accessible name을 유지합니다. |
+| 초기화·갱신처럼 부담이 낮은 반복 행동 | `neutral/weak` | CTA를 보조하면서 반복 가능한 행동을 표현합니다. 되돌리기 어려운 초기화는 `critical/weak`입니다. |
+| 툴바·헤더·옵션 메뉴처럼 주변 UI와의 간섭을 줄여야 하는 보조 행동 | `neutral/ghost` | 배경 없이 보조 행동을 표현합니다. |
+| 다른 페이지·콘텐츠로 이동하거나 관련 정보를 확인 | `neutral/link` | 탐색에만 사용하며 상태 변경이나 일반 CTA에는 쓰지 않습니다. `href`가 필요하며 `<a>`로 렌더링합니다. |
+| 되돌리기 어려운 삭제·초기화 | `critical/weak` | 위험을 분명히 전달합니다. 가능하면 소비처의 확인 대화상자(WAI-ARIA `alertdialog` 패턴)로 한 번 더 확인받습니다. |
 
-기존 화면에서 다른 조합을 사용하고 있더라도 새 코드에서는 행동의 의미에 맞는 위계를 먼저 검토합니다. 보조 행동은 한 조합으로 고정합니다. 취소·닫기·수정은 `neutral/outline`, 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동은 `neutral/weak`입니다. `neutral/link`는 페이지나 콘텐츠로 이동하는 탐색에만 사용합니다.
+새 코드는 기존 화면의 조합을 따르지 않고 위 표의 행동 기준으로 조합을 고릅니다. 비동기 처리 중에는 선택한 조합에 `loading`을 지정합니다. 툴바·헤더 안의 보조 행동이 `neutral/outline`과 `neutral/ghost`에 모두 해당할 때의 우선순위는 `미결`입니다.
 
-표 행 조작이나 pagination처럼 공간이 좁은 곳에서는 `iconOnly`를 사용할 수 있습니다. 아이콘만으로 의미가 충분한지 확인하고, 필요한 경우 비어 있지 않은 `aria-label`을 지정합니다. 아이콘은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때만 사용합니다.
+같은 액션 그룹(함께 놓이는 버튼 묶음)의 조합은 다음을 따릅니다.
 
-## 사용 맥락
+- `brand/outline`은 같은 액션 그룹에서 `brand/solid`와 함께 쓰지 않는 것을 권장합니다.
+- `neutral/outline`은 `neutral/solid`와 같은 액션 그룹에 두지 않습니다.
+- `brand/outline`과 `neutral/outline`은 함께 둘 수 있습니다.
+- `neutral/solid` 옆에 두는 취소 버튼의 조합은 `미결`입니다.
 
 ### Size
 
@@ -37,67 +53,36 @@
 | `sm` | 일반적인 화면 액션에 사용합니다. |
 | `md` | 공간이 충분하거나 중요한 행동을 명확히 강조해야 할 때 사용합니다. |
 
-### Layout
+### Layout과 아이콘
 
-Layout은 라벨과 아이콘의 조합으로 결정합니다. 아이콘은 행동의 목적이나 방향을 보조할 때만 사용합니다.
+Layout은 prop으로 지정하지 않고 슬롯 조합에서 추론합니다. 아이콘은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때만 사용하고, 표 행 조작이나 pagination처럼 공간이 좁은 곳에서는 `iconOnly`를 사용할 수 있습니다.
 
-| layout | 구성 | 사용 맥락 |
+| layout | 슬롯 조합 | 사용 맥락 |
 | --- | --- | --- |
-| `textOnly` | 라벨만 제공합니다. | 아이콘 없이도 행동을 명확히 전달할 수 있을 때 사용합니다. |
-| `iconFirst` | 라벨 앞에 아이콘을 둡니다. | 아이콘이 행동의 목적을 보조할 때 사용합니다. |
-| `iconLast` | 라벨 뒤에 아이콘을 둡니다. | 이동 방향이나 다음 단계를 나타낼 때 사용합니다. |
-| `iconBoth` | 라벨 양쪽에 아이콘을 둡니다. | 양쪽 아이콘이 모두 의미를 더하는 명확한 경우에만 사용합니다. |
-| `iconOnly` | 아이콘만 제공합니다. | 아이콘만으로 행동의 의미가 충분히 명확할 때 사용하며, 접근성 이름을 제공하려면 `aria-label`을 지정합니다. |
-
-### Role
-
-Role은 색상 취향이 아니라 버튼이 수행하는 행동의 의미를 정의합니다. `role`은 시각적 prop이며 DOM의 ARIA `role` 속성으로 전달하지 않습니다.
-
-| role | 사용 맥락 |
-| --- | --- |
-| `brand` | 브랜드와 관련되거나 화면에서 가장 중요한 행동을 강조할 때 사용합니다. |
-| `neutral` | 일반적인 액션과 탐색에 사용합니다. `brand`보다 낮은 주목도가 필요할 때 선택합니다. |
-| `critical` | 삭제·초기화처럼 오류나 되돌리기 어려운 위험한 행동을 나타낼 때 사용합니다. 가능하면 확인 절차와 함께 사용합니다. |
-
-### Variant
-
-Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
-
-| role / variant | 사용 맥락 |
-| --- | --- |
-| `brand/solid` | 서비스의 핵심 행동에 사용합니다. 한 화면에 하나를 권장합니다. |
-| `brand/outline` | `brand/solid`보다 낮은 위계의 브랜드 보조 행동에 사용합니다. `neutral/outline`과 조합할 수 있으며 같은 액션 그룹에서 `brand/solid`와 함께 사용하지 않는 것을 권장합니다. |
-| `neutral/solid` | `brand/solid` 다음 위계의 일반적인 주요 CTA에 사용합니다. 한 화면에 하나를 권장합니다. |
-| `neutral/weak` | 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동에 사용합니다. 취소·닫기·수정은 `neutral/outline`을 사용합니다. |
-| `neutral/outline` | 취소·닫기·수정처럼 주 행동과 위계를 분리하는 보조 행동에 사용합니다. `neutral/solid`과 같은 액션 그룹에서 함께 사용하지 않으며, `brand/outline`과 조합할 수 있습니다. |
-| `neutral/ghost` | 툴바·헤더·옵션 메뉴처럼 주변 UI와의 간섭을 줄여야 하는 보조 행동에 사용합니다. |
-| `neutral/link` | 다른 페이지·콘텐츠로 이동하거나 관련 정보를 확인하는 탐색성 행동에 사용합니다. 상태 변경이나 일반 CTA에는 사용하지 않습니다. `href`가 필요하며 `<a>`로 렌더링합니다. |
-| `critical/weak` | 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다. 위험을 분명히 전달하며 가능하면 확인 대화상자나 Alert Dialog와 함께 사용합니다. |
+| `textOnly` | `children`만 지정합니다. | |
+| `iconFirst` | `children`과 `startIcon` 또는 `startIconName`을 지정합니다. | 아이콘이 행동의 목적을 보조할 때 사용합니다. |
+| `iconLast` | `children`과 `endIcon` 또는 `endIconName`을 지정합니다. | 이동 방향이나 다음 단계를 나타낼 때 사용합니다. |
+| `iconBoth` | `children`과 앞·뒤 아이콘을 모두 지정합니다. | 양쪽 아이콘이 모두 의미를 더하는 명확한 경우에만 사용합니다. |
+| `iconOnly` | `children` 없이 `icon` 또는 `iconName`과 `aria-label`을 지정합니다. | |
 
-지원하지 않는 Role·Variant 조합을 `className`, inline style, 임의 CSS로 우회하지 않습니다.
+- 이름 슬롯(`iconName`·`startIconName`·`endIconName`)은 승인된 아이콘 목록의 lucide PascalCase 전체 이름만 받습니다. `ButtonIconName`이 이 목록과 같은 union이라 목록에 없는 이름은 TypeScript 오류이고, 런타임에 전달되면 render 오류입니다. 전체 목록은 설치된 패키지 `spec.json`의 `api.iconNames`에 있습니다.
+- 목록은 `lucide-react`의 canonical 이름만 포함하며 `AlertCircle`처럼 deprecated된 alias는 허용하지 않습니다.
+- 목록 밖 아이콘은 `icon`, `startIcon`, `endIcon`에 `ReactElement`로 전달하며, 같은 슬롯에 이름과 custom element를 함께 지정하지 않습니다. `lucide-react`에서 직접 import할 때는 EDS package root `package.json`의 `dependencies["lucide-react"]`와 같은 exact 버전을 소비처 `package.json`에 선언합니다. pnpm처럼 엄격한 node_modules에서는 선언 없이 resolve되지 않고, 버전이 다르면 아이콘 코드가 두 벌 번들됩니다. custom lucide 아이콘은 lucide 기본 stroke를 그대로 써서 이름으로 지정한 아이콘과 맞춥니다.
+- 목록 밖 아이콘을 `ReactElement`로 썼다면 완료 보고에 아이콘 이름과 사용 파일을 allowlist 추가 후보로 적습니다.
 
 ### State
 
-| state | 의미 |
-| --- | --- |
-| enabled | 사용자가 실행할 수 있는 기본 상태입니다. |
-| hover | 포인터가 버튼 위에 있을 때의 상태이며 CSS `:hover`로 처리합니다. |
-| loading | 동작을 처리하는 중인 상태입니다. 라벨·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단합니다. |
-| disabled | 사용자가 실행할 수 없는 상태입니다. |
-
-`active`, `pressed`, `visited` 등 문서에 없는 상태는 추가하지 않습니다.
+상태는 `loading`과 `disabled`만 prop으로 지정합니다. hover와 focus-visible은 컴포넌트가 처리하며, `active`, `pressed`, `visited` 상태는 제공하지 않습니다. `loading`은 라벨·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단합니다.
 
 ## 공개 API contract
 
-다음 props는 필수입니다.
+모든 Button에 다음 props가 필수입니다.
 
 | prop | 허용 값 | 설명 |
 | --- | --- | --- |
 | `size` | `xs`, `sm`, `md` | 버튼 크기입니다. |
 | `role` | `brand`, `neutral`, `critical` | 시각적 역할이며 DOM ARIA `role`로 전달하지 않습니다. |
 | `variant` | role별 아래 표 | 역할에 종속된 표현입니다. |
-| `type` | `button`, `submit`, `reset` | native button branch에서 필수입니다. |
-| `href` | `string` | `neutral/link` branch에서 필수이며 `<a>`로 렌더링합니다. |
 
 허용하는 role·variant 조합은 다음과 같습니다.
 
@@ -107,56 +92,42 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 | `neutral` | `solid`, `weak`, `outline`, `ghost`, `link` |
 | `critical` | `weak` |
 
+조합에 따라 branch가 정해집니다.
+
+- `role="neutral"`·`variant="link"`이면 link branch입니다. 비어 있지 않은 `href`가 필수이고 `<a>`로 렌더링하며 `type`은 받지 않습니다.
+- 그 밖의 조합은 native button branch입니다. `type`(`button`, `submit`, `reset`)이 필수이고 기본값이 없으며 `href`는 받지 않습니다. 폼 제출은 `submit`, 그 밖의 행동은 `button`입니다.
+
 ### API reference
 
 | prop | 타입·규칙 |
 | --- | --- |
-| `children` | `ReactNode` label입니다. 렌더링 가능한 내용이 하나 이상 필요하며 `startIcon`·`endIcon`과 조합할 수 있습니다. |
-| `icon` | icon-only용 단일 custom `ReactElement`입니다. children이나 start/end icon과 함께 사용하지 않습니다. |
-| `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. 승인된 아이콘 목록의 이름만 허용합니다. |
+| `children` | `ReactNode` label입니다. 렌더링 가능한 내용이 하나 이상 필요하며 한 줄로 표시합니다. `startIcon`·`endIcon`과 조합할 수 있습니다. |
+| `icon` | icon-only용 단일 custom `ReactElement`입니다. children이나 start/end 아이콘과 함께 사용하지 않습니다. |
+| `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. |
 | `startIcon` / `endIcon` | label 앞·뒤의 단일 custom `ReactElement` 슬롯입니다. |
-| `startIconName` / `endIconName` | label 앞·뒤의 `ButtonIconName` lucide 이름 슬롯입니다. 승인된 아이콘 목록의 이름만 허용합니다. |
-| `aria-label` | 선택적인 `string`입니다. icon-only의 accessible name을 제공할 때 지정하며, 필수로 강제하지 않습니다. |
+| `startIconName` / `endIconName` | label 앞·뒤의 `ButtonIconName` lucide 이름 슬롯입니다. |
+| `aria-label` | 선택적인 `string`이며, 지정하면 비어 있지 않아야 합니다. icon-only에서는 항상 지정합니다. |
 | `disabled` | `boolean`입니다. native button은 `disabled`, link는 href 제거·`aria-disabled="true"`·`tabIndex={-1}`를 적용합니다. |
-| `loading` | `boolean`입니다. label·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단합니다. `aria-busy="true"`를 적용합니다. |
-| `className` | `string`이며 배치·컨테이너 보정에만 허용합니다. |
+| `loading` | `boolean`입니다. label·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단하며 `aria-busy="true"`를 적용합니다. |
+| `className` | `string`입니다. 허용 범위는 `QUICKSTART.md` 규칙 5를 따릅니다. |
+| `style` | 지원하지 않습니다(`never`). 스타일 override는 공개 API가 아닙니다. |
 | `aria-*` / `data-*` | 각 branch의 native HTML 속성으로 전달할 수 있습니다. |
 | `ref` | branch에 따라 `HTMLButtonElement` 또는 `HTMLAnchorElement`를 전달합니다. |
 
-`style`과 임의 스타일 override는 공개하지 않습니다. 이름으로 지정한 lucide 아이콘은 `lucide-react` 기본 시각 설정을 사용하며 Button은 아이콘 영역 크기만 조정합니다. 공개 소비처의 role·variant 선택과 사용 맥락도 이 문서를 기준으로 합니다.
-
-`variant="link"`는 `role="neutral"`에서만 사용할 수 있으며 `href`가 필수입니다. 이 조합은 `<a>`로 렌더링합니다. native button에는 기본값을 제공하지 않습니다.
-
-`startIcon`, `endIcon`, `icon`은 단일 `ReactElement` 슬롯입니다. lucide 아이콘은 `startIconName`, `endIconName`, `iconName`으로 PascalCase 전체 이름을 지정합니다. 이름 prop은 `ButtonIconName` 자동완성을 제공하며 custom ReactElement와 같은 슬롯에 함께 지정할 수 없습니다.
-
-`ButtonIconName`은 EVA 화면에서 실제로 사용하는 lucide 아이콘을 모은 승인된 아이콘 목록입니다. 목록은 `lucide-react`의 canonical 이름만 포함하며 `AlertCircle`처럼 deprecated된 alias는 허용하지 않습니다. 승인된 이름 전체는 설치된 패키지의 공개 `spec.json`의 `api.iconNames`와 내부 Storybook 아이콘 카탈로그에서 확인합니다. 이름으로 지정한 아이콘은 동기적으로 렌더링하며 SSR에서도 SVG를 바로 출력합니다. 목록에 없는 이름은 TypeScript 오류로 막고, 런타임에 전달되면 render 오류로 처리합니다.
-
-승인된 아이콘 목록 밖의 아이콘이 필요하면 `icon`, `startIcon`, `endIcon`에 `ReactElement`로 전달합니다. 같은 아이콘이 두 화면 이상에서 반복되면 승인된 아이콘 목록에 추가하는 PR을 엽니다. 슬롯 아이콘을 `lucide-react`에서 직접 import할 때는 소비처 `package.json`에 `lucide-react`를 EDS와 같은 `1.45.0`으로 선언합니다. pnpm처럼 엄격한 node_modules에서는 선언 없이 resolve되지 않고, 버전이 다르면 아이콘 코드가 두 벌 번들됩니다. 슬롯 아이콘의 크기는 Button이 맞추므로 stroke 두께만 lucide 기본값 `2`로 두면 이름으로 지정한 아이콘과 같아 보입니다.
-
-이름으로 지정한 lucide 아이콘은 `lucide-react`의 기본 시각 설정을 사용합니다. Button은 아이콘 영역의 크기만 조정하며, `color`, `size`, `strokeWidth`, `strokeLinecap`, `strokeLinejoin`을 소비처 prop으로 노출하거나 덮어쓰지 않습니다. `aria-hidden`과 `focusable`은 Button 접근성 contract에 따라 내부에서 설정합니다.
-
-- children만 있으면 `textOnly`입니다.
-- children과 `startIcon`이 있으면 `iconFirst`입니다.
-- children과 `endIcon`이 있으면 `iconLast`입니다.
-- children과 두 아이콘이 있으면 `iconBoth`입니다.
-- children 없이 `icon` 또는 `iconName`만 있으면 `iconOnly`입니다. 접근성 이름이 필요하면 비어 있지 않은 `aria-label`을 지정합니다.
-
-빈 label·icon, 제공된 빈 `aria-label`과 잘못된 슬롯 조합은 모든 환경에서 오류로 처리합니다. label은 한 줄을 유지합니다.
-
-`className`, native `aria-*`, `data-*`, `forwardRef`를 지원합니다. `style`과 임의 스타일 override는 공개하지 않습니다.
-
-`loading`은 선택 prop입니다. 라벨과 아이콘의 공간·접근성 이름을 유지하면서 내부 2색 SVG progress circle을 표시합니다. 라벨과 아이콘은 시각적으로만 숨겨지며, native button은 `disabled`, link는 href 제거·`aria-disabled="true"`·`tabIndex={-1}`로 상호작용을 차단합니다. loading 중에는 `aria-busy="true"`를 적용하며 `disabled`와 함께 지정하면 loading 시각을 우선합니다.
+다음 입력은 타입을 통과해도 render 중 `Error`를 던지며, error boundary가 없으면 그 화면 트리가 unmount됩니다: 빈 `children`·`href`·지정된 `aria-label`(공백만 있는 문자열 포함), 한 슬롯에 이름과 element를 함께 지정, `icon`과 `children`·start/end 아이콘을 함께 지정, 목록 밖 아이콘 이름, 표에 없는 role·variant 조합. 데이터나 번역에서 받은 값이 비어 있을 수 있으면 `""`로 채우지 말고 Button을 렌더링하지 않거나 prop을 생략합니다.
 
 ## 접근성·상호작용
 
+- 아이콘은 시각 장식으로 `aria-hidden="true"` 처리합니다. 그래서 icon-only Button에는 항상 비어 있지 않은 `aria-label` 또는 `aria-labelledby`를 지정합니다. 타입이 이를 요구하지 않아 빠뜨려도 typecheck가 통과합니다.
 - native button은 `disabled` 속성을 사용합니다.
 - disabled link는 `href`를 제거하고 `aria-disabled="true"`, `tabIndex={-1}`를 적용하며 클릭을 막습니다. href가 제거된 앵커는 의도적으로 link role을 노출하지 않습니다.
-- hover는 CSS `:hover`로 처리합니다.
-- 승인된 시각 상태는 enabled, hover, disabled, loading이며 focus-visible은 별도 focus ring 상태로 제공합니다. active·pressed·visited 상태는 지원하지 않습니다.
-- focus-visible ring은 `color-stroke-focusRing` semantic token과 2px outline·offset 구조값을 사용합니다.
-- 아이콘은 시각 장식으로 `aria-hidden="true"` 처리하며, icon-only의 accessible name을 제공할 때 Button의 `aria-label`을 사용합니다. `aria-label`은 필수로 강제하지 않습니다.
-- loading progress circle은 `800ms linear infinite` 회전하며 `prefers-reduced-motion: reduce`에서는 정지합니다.
+- `loading`은 라벨과 아이콘을 시각적으로만 숨기고 accessible name을 유지합니다. native button은 `disabled`, link는 href 제거·`aria-disabled="true"`·`tabIndex={-1}`로 상호작용을 차단하며 `aria-busy="true"`를 적용합니다. `disabled`와 함께 지정하면 loading 시각을 우선합니다.
+- loading 중 native button은 `disabled`가 되어 탭 순서에서 빠지므로 포커스를 잃을 수 있습니다. loading이 끝나면 포커스를 원래 Button이나 결과를 보여 주는 요소로 옮기고, 완료·실패 결과는 Button 밖의 `role="status"`(실패는 `role="alert"`) 영역으로 알립니다. 진행 중 문구는 live region에 넣지 않습니다.
+- loading progress circle은 회전하며 `prefers-reduced-motion: reduce`에서는 정지합니다.
+- `neutral/link`는 일반 `<a href>`를 렌더링하며 client router와 연결하지 않으므로 이동하면 문서 전체를 다시 불러옵니다. router의 `<Link>`로 감싸지 않습니다(`<a>`가 중첩됩니다). 내부 route 이동도 `href`만 지정하고, 새로고침이 문제가 되는 화면이면 완료 보고에 적습니다. SPA router 연동 방식은 `미결`입니다.
 
 ## 문서와 검증
 
-Button의 공개 API와 사용 맥락은 이 문서와 설치된 패키지의 공개 `spec.json`을 함께 기준으로 사용합니다. 공개 Props·variant·상태를 변경할 때는 디자인 시스템 담당자의 검토와 적절한 버전 변경이 필요합니다.
+Button의 사용 기준은 이 문서이며, 같은 폴더의 `spec.json`은 같은 계약을 도구가 읽는 형식으로 담습니다(이름으로 쓰는 아이콘 목록은 `api.iconNames`). 필요한 prop·variant·상태가 없으면 우회하지 말고 멈춰 사용자에게 확인합니다.
+
+기존 코드를 한 번에 교체하지 않고 요청 범위에서 새로 쓰거나 고치는 코드부터 EDS `Button`을 적용합니다. 저장소에 있던 로컬 Button wrapper는 EDS `Button` contract로 표현할 수 없는 기능이 있을 때만 유지합니다.

package/dist/components/Button/spec.json

@@ -1,6 +1,6 @@
 {
   "specVersion": 1,
-  "packageVersion": "0.1.0",
+  "packageVersion": "0.1.1",
   "name": "Button",
   "purpose": "사용자가 즉시 실행할 수 있는 행동과 탐색을 표현하는 인터랙티브 요소입니다.",
   "usageContexts": [
@@ -8,20 +8,19 @@
     "다른 페이지나 콘텐츠로 이동하는 탐색에는 neutral/link branch를 사용합니다.",
     "brand는 화면에서 가장 중요한 행동을 강조할 때 사용합니다.",
     "neutral은 일반적인 액션과 탐색에 사용합니다.",
-    "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다.",
-    "생성·저장·관리·확인처럼 화면의 핵심 행동에는 brand/solid를 먼저 검토합니다.",
-    "검색·조회·일반적인 주요 실행에는 neutral/solid를 먼저 검토합니다.",
+    "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 critical/weak로 사용하며, 가능하면 확인 절차를 함께 둡니다.",
+    "생성·저장·관리·확인처럼 화면의 핵심 행동에는 brand/solid를 사용합니다.",
+    "검색·조회·일반적인 주요 실행에는 neutral/solid를 사용합니다.",
     "취소·닫기·수정 같은 보조 작업에는 neutral/outline을 사용합니다.",
-    "초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동에는 neutral/weak를 사용합니다.",
-    "되돌리기 어려운 삭제·초기화는 critical/weak와 확인 절차를 먼저 검토합니다.",
+    "초기화·갱신처럼 부담이 낮은 반복 행동에는 neutral/weak를 사용합니다.",
     "비동기 저장·확인에는 loading을 사용해 중복 실행을 막고 라벨 공간을 유지합니다.",
-    "표 행 조작·pagination처럼 공간이 좁은 곳의 icon-only는 accessible name을 확인합니다.",
-    "icon은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때 사용합니다.",
-    "icon-only의 접근성 이름을 제공하려면 aria-label을 지정합니다. aria-label은 필수로 강제하지 않습니다."
+    "표 행 조작·pagination처럼 공간이 좁은 곳에는 icon-only를 쓸 수 있습니다(accessible name은 accessibility.iconOnlyName).",
+    "icon은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때 사용합니다."
   ],
   "unsupportedContexts": [
     "문서에 없는 role·variant·상태를 className이나 inline style로 우회하지 않습니다.",
-    "상태 변경이나 일반 CTA를 neutral/link로 표현하지 않습니다."
+    "상태 변경이나 일반 CTA를 neutral/link로 표현하지 않습니다.",
+    "neutral/outline을 neutral/solid와 같은 액션 그룹에 두지 않습니다(neutral/solid 옆 취소 버튼의 조합은 미결)."
   ],
   "api": {
     "props": [
@@ -35,7 +34,7 @@
         "name": "role",
         "type": "ButtonRole",
         "required": true,
-        "description": "시각적 역할입니다."
+        "description": "행동의 의미(brand·neutral·critical)를 나타내는 시각적 역할입니다. DOM의 ARIA role로 전달되지 않으며 ARIA role은 지정할 수 없습니다."
       },
       {
         "name": "variant",
@@ -48,20 +47,20 @@
         "type": "NativeButtonType",
         "required": true,
         "branch": "native button",
-        "description": "native button의 동작 유형입니다."
+        "description": "native button의 동작 유형입니다. 폼 제출은 submit, 그 밖의 행동은 button을 지정하며 기본값은 없습니다."
       },
       {
         "name": "href",
         "type": "string",
         "required": true,
         "branch": "neutral/link",
-        "description": "탐색 대상 주소입니다."
+        "description": "탐색 대상 주소입니다. 빈 문자열이나 공백만 있는 값은 render 오류입니다."
       },
       {
         "name": "children",
         "type": "ReactNode",
         "required": false,
-        "description": "text label입니다."
+        "description": "text label입니다. iconOnly를 뺀 모든 slot에서 필수이며, 렌더링할 내용이 없으면(빈 문자열·공백·null) render 오류입니다. slot 조합은 slots를 따릅니다."
       },
       {
         "name": "icon",
@@ -103,7 +102,7 @@
         "name": "aria-label",
         "type": "string",
         "required": false,
-        "description": "accessible name입니다. icon-only의 접근성 이름을 제공할 때 사용합니다."
+        "description": "accessible name입니다. 지정하면 비어 있지 않아야 하며, 빈 문자열이나 공백은 render 오류입니다. icon-only에서는 accessibility.iconOnlyName을 따릅니다."
       },
       {
         "name": "disabled",
@@ -115,13 +114,13 @@
         "name": "loading",
         "type": "boolean",
         "required": false,
-        "description": "처리 중 상태입니다."
+        "description": "비동기 처리 중 상태입니다. aria-busy를 적용하고 상호작용을 막으며 label·아이콘 공간과 accessible name을 유지합니다."
       },
       {
         "name": "className",
         "type": "string",
         "required": false,
-        "description": "배치·컨테이너 보정용 class입니다."
+        "description": "바깥 배치(margin·정렬·grid 위치)용 class입니다."
       },
       {
         "name": "ref",
@@ -163,7 +162,7 @@
       "iconFirst": "children과 startIcon 또는 startIconName을 제공합니다.",
       "iconLast": "children과 endIcon 또는 endIconName을 제공합니다.",
       "iconBoth": "children과 앞·뒤 아이콘을 모두 제공합니다.",
-      "iconOnly": "children 없이 icon 또는 iconName을 제공합니다. 접근성 이름이 필요하면 aria-label을 지정합니다."
+      "iconOnly": "children 없이 icon 또는 iconName을 제공합니다. 이름은 accessibility.iconOnlyName을 따릅니다."
     },
     "iconNames": [
       "ArrowLeft",
@@ -226,127 +225,9 @@
     ]
   },
   "accessibility": {
-    "nativeButtonType": "native button branch에서는 type을 필수로 지정합니다.",
-    "linkHref": "neutral/link branch에서는 href를 필수로 지정합니다.",
-    "iconOnlyName": "icon-only layout에서는 접근성 이름을 제공할 때 비어 있지 않은 aria-label을 지정합니다. aria-label은 필수가 아닙니다.",
-    "disabledLink": "비활성 link는 href를 제거하고 aria-disabled와 tabIndex를 적용합니다.",
-    "loading": "loading 중에는 aria-busy를 적용하고 상호작용을 차단합니다.",
-    "focusVisible": "keyboard focus에는 승인된 focus ring을 표시합니다."
+    "iconOnlyName": "icon-only의 아이콘은 aria-hidden이므로 항상 비어 있지 않은 aria-label 또는 aria-labelledby로 이름을 지정합니다. 타입이 이를 요구하지 않아 빠뜨려도 typecheck가 통과하며, 빈 aria-label은 render 오류입니다.",
+    "loading": "loading 중에도 label·아이콘 공간과 accessible name을 유지합니다. native button은 disabled가 되어 포커스를 잃을 수 있으므로, 끝나면 포커스를 원래 Button이나 결과 요소로 옮기고 결과는 Button 밖의 status·alert 영역으로 알립니다."
   },
-  "semanticTokens": [
-    {
-      "name": "color-bg-brand-primary",
-      "usage": "brand solid의 기본 배경입니다."
-    },
-    {
-      "name": "color-bg-brand-primary-hover",
-      "usage": "brand solid의 hover 배경입니다."
-    },
-    {
-      "name": "color-bg-critical-weak",
-      "usage": "critical weak의 기본 배경입니다."
-    },
-    {
-      "name": "color-bg-critical-weak-hover",
-      "usage": "critical weak의 hover 배경입니다."
-    },
-    {
-      "name": "color-bg-disabled",
-      "usage": "비활성 배경입니다."
-    },
-    {
-      "name": "color-bg-neutral-inverted",
-      "usage": "neutral solid의 기본 배경입니다."
-    },
-    {
-      "name": "color-bg-neutral-inverted-hover",
-      "usage": "neutral solid의 hover 배경입니다."
-    },
-    {
-      "name": "color-bg-neutral-weak",
-      "usage": "neutral weak의 기본 배경입니다."
-    },
-    {
-      "name": "color-bg-neutral-weak-hover",
-      "usage": "neutral weak의 hover 배경입니다."
-    },
-    {
-      "name": "color-bg-transparent",
-      "usage": "outline·ghost·link의 투명 배경입니다."
-    },
-    {
-      "name": "color-bg-transparent-hover",
-      "usage": "outline·ghost·link의 hover 배경입니다."
-    },
-    {
-      "name": "color-fg-brand",
-      "usage": "brand outline의 전경입니다."
-    },
-    {
-      "name": "color-fg-critical",
-      "usage": "critical weak의 전경입니다."
-    },
-    {
-      "name": "color-fg-disabled",
-      "usage": "비활성 전경입니다."
-    },
-    {
-      "name": "color-fg-neutral",
-      "usage": "neutral outline·ghost·link의 전경입니다."
-    },
-    {
-      "name": "color-fg-neutral-inverted",
-      "usage": "solid variant의 대비 전경입니다."
-    },
-    {
-      "name": "color-stroke-focusRing",
-      "usage": "focus-visible ring의 전경입니다."
-    },
-    {
-      "name": "color-stroke-neutral-secondary",
-      "usage": "neutral outline의 경계선입니다."
-    },
-    {
-      "name": "typography-body3-fontFamily",
-      "usage": "xs label의 글꼴입니다."
-    },
-    {
-      "name": "typography-body3-fontSize",
-      "usage": "xs label의 글꼴 크기입니다."
-    },
-    {
-      "name": "typography-body3-fontWeight",
-      "usage": "xs label의 글꼴 두께입니다."
-    },
-    {
-      "name": "typography-body3-letterSpacing",
-      "usage": "xs label의 자간입니다."
-    },
-    {
-      "name": "typography-body3-lineHeight",
-      "usage": "xs label의 행간입니다."
-    },
-    {
-      "name": "typography-title3-fontFamily",
-      "usage": "sm·md label의 글꼴입니다."
-    },
-    {
-      "name": "typography-title3-fontSize",
-      "usage": "sm·md label의 글꼴 크기입니다."
-    },
-    {
-      "name": "typography-title3-fontWeight",
-      "usage": "sm·md label의 글꼴 두께입니다."
-    },
-    {
-      "name": "typography-title3-letterSpacing",
-      "usage": "sm·md label의 자간입니다."
-    },
-    {
-      "name": "typography-title3-lineHeight",
-      "usage": "sm·md label의 행간입니다."
-    }
-  ],
   "unsupportedProps": [
     {
       "name": "style",