@spectrabrain/eds 0.0.4 → 0.1.0

package/consumer/scan-classes.mjs

@@ -0,0 +1,70 @@
+import { relativeTo } from "./paths.mjs";
+
+// Tailwind utilities that take a color. A class such as hover:bg-eds-bg-brand-primary/80 is one token here.
+const colorUtility = "(?:text|bg|border|ring|outline|fill|stroke|decoration|divide|from|to|via|accent|caret|shadow|placeholder|inset-ring)";
+const variantPrefix = "(?:[a-z0-9-]+:)*";
+const boundaryBefore = "(?<![\\w-])";
+const boundaryAfter = "(?![\\w-])";
+const opacity = "(?:/[0-9]{1,3})?";
+
+const edsColorClass = new RegExp(boundaryBefore + variantPrefix + colorUtility + "-eds-([a-z0-9-]+)" + opacity + boundaryAfter, "g");
+const edsTypographyClass = new RegExp(boundaryBefore + variantPrefix + "eds-typography-([a-z0-9-]+)" + boundaryAfter, "g");
+const rawColorClass = new RegExp(
+  boundaryBefore + variantPrefix + colorUtility +
+    "-(?:(?:slate|gray|zinc|neutral|stone|red|orange|amber|yellow|lime|green|emerald|teal|cyan|sky|blue|indigo|violet|purple|fuchsia|pink|rose)-[0-9]{2,3}|white|black|\\[(?:#|rgba?\\(|hsla?\\(|oklch\\(|oklab\\(|color\\()[^\\]]*\\])" +
+    opacity + boundaryAfter,
+  "g",
+);
+
+// The public class names are derived exactly like eds sync derives the Tailwind aliases from tokens.json.
+export function publicClassNames(manifest) {
+  const colors = new Set();
+  const typography = new Set();
+  for (const name of Object.keys(manifest.tokens ?? {})) {
+    if (name.startsWith("color-")) {
+      colors.add("eds-" + name.slice("color-".length));
+      continue;
+    }
+    const match = name.match(/^typography-(.+)-(?:fontFamily|fontWeight|fontSize|lineHeight|letterSpacing)$/);
+    if (match) {
+      typography.add(match[1]);
+    }
+  }
+  return { colors, typography };
+}
+
+// files: [{ path, contents }] as readSources() lists them (the generated eds-tokens.css is not among them).
+// unknown: eds-* classes that no public token backs (always a mistake, Tailwind silently drops them).
+// raw: Tailwind palette, white/black and arbitrary color classes that bypass the EDS tokens (informational).
+export function scanClassNames({ consumerRoot, manifest, files }) {
+  const { colors, typography } = publicClassNames(manifest);
+  const unknown = [];
+  const raw = [];
+  for (const file of files) {
+    const relativePath = relativeTo(consumerRoot, file.path);
+    file.contents.split(/\r?\n/).forEach((line, index) => {
+      const location = relativePath + ":" + (index + 1);
+      for (const match of line.matchAll(edsColorClass)) {
+        // "bg-eds-bg-" + name is composed at runtime; the scan cannot judge it.
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!colors.has("eds-" + match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(edsTypographyClass)) {
+        if (match[1].endsWith("-")) {
+          continue;
+        }
+        if (!typography.has(match[1])) {
+          unknown.push({ location, className: match[0] });
+        }
+      }
+      for (const match of line.matchAll(rawColorClass)) {
+        raw.push({ location, className: match[0] });
+      }
+    });
+  }
+  return { unknown, raw };
+}

package/consumer/sync.mjs

@@ -0,0 +1,133 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  consumerConfigField,
+  findTailwindRoot,
+  planCssRootImports,
+  planLegacyJsImportCleanup,
+  readSources,
+  tailwindRootConfigKey,
+  tailwindRootEnvironmentVariable,
+} from "./css-root.mjs";
+import { planTailwind } from "./generate-tailwind.mjs";
+import { createExitError, detectPackageManager, generatedCssRelativePath, normalizeEol, resolvePackage, toPosix } from "./paths.mjs";
+import { writeConsumerPackageJson } from "./register-scripts.mjs";
+import { planAgentContext, planClaudeImport, planGeminiImport } from "./update-agent-context.mjs";
+
+export const syncTargets = new Set(["tailwind", "agents"]);
+export const noTailwindNote =
+  "No Tailwind root CSS found (no @import \"tailwindcss\"); skipped " + toPosix(generatedCssRelativePath) +
+  " and the CSS imports. Set " + tailwindRootEnvironmentVariable + "=<file> once to wire Tailwind; sync records it in package.json " +
+  consumerConfigField + "." + tailwindRootConfigKey + ".";
+
+export function collectPlans({ consumerRoot, env = process.env }) {
+  const pkg = resolvePackage(consumerRoot);
+  const packageManager = detectPackageManager(consumerRoot, env);
+  const sources = readSources(consumerRoot);
+  const root = findTailwindRoot(consumerRoot, env, sources, packageManager);
+  // No Tailwind root: the Tailwind wiring is skipped entirely (no generated CSS, no root edits).
+  const tailwind = root === null ? null : planTailwind({ consumerRoot, pkg });
+  const cssRoot = root === null ? null : planCssRootImports({ consumerRoot, root, sources });
+  const legacyImports = root === null ? [] : planLegacyJsImportCleanup({ consumerRoot });
+  const errors = [];
+  let agents = null;
+  try {
+    agents = planAgentContext({ consumerRoot, pkg, packageManager });
+  } catch (error) {
+    errors.push(error);
+  }
+  const claude = planClaudeImport({ consumerRoot });
+  const gemini = planGeminiImport({ consumerRoot });
+  return { consumerRoot, pkg, packageManager, sources, root, tailwind, cssRoot, legacyImports, agents, claude, gemini, errors };
+}
+
+export function planSync({ consumerRoot, env = process.env, only = null }) {
+  if (only !== null && !syncTargets.has(only)) {
+    throw createExitError("Unknown --only target: " + only + " (use tailwind or agents).", 2);
+  }
+  const plans = collectPlans({ consumerRoot, env });
+  if (plans.errors.length > 0) {
+    throw plans.errors[0];
+  }
+
+  const writes = [];
+  if ((only === null || only === "tailwind") && plans.root !== null) {
+    writes.push(plans.tailwind, plans.cssRoot, ...plans.legacyImports);
+  }
+  if (only === null || only === "agents") {
+    writes.push(plans.agents);
+    if (plans.claude) {
+      writes.push(plans.claude);
+    }
+    if (plans.gemini) {
+      writes.push(plans.gemini);
+    }
+  }
+  // Like doctor, an EOL-only difference (an autocrlf checkout of the LF generated CSS) is already synced.
+  return { ...plans, only, writes: writes.filter((write) => normalizeEol(write.before) !== normalizeEol(write.after)) };
+}
+
+// EDS_TAILWIND_ROOT is a one-time choice: sync records it as package.json "eds": { "tailwindRoot" } so
+// doctor and the pretypecheck/prebuild hooks resolve the same root without the environment variable.
+function persistTailwindRoot(plan, { dryRun, log }) {
+  if (plan.root?.source !== "env" || plan.only === "agents") {
+    return false;
+  }
+  const packagePath = path.join(plan.consumerRoot, "package.json");
+  const source = fs.readFileSync(packagePath, "utf8");
+  const consumerPackage = JSON.parse(source);
+  const existing = consumerPackage[consumerConfigField];
+  if (existing !== undefined && (typeof existing !== "object" || existing === null || Array.isArray(existing))) {
+    log("[EDS] package.json " + consumerConfigField + " is not an object; " + tailwindRootEnvironmentVariable + " was not recorded there.");
+    return false;
+  }
+  const value = plan.root.relativePath;
+  const label = consumerConfigField + "." + tailwindRootConfigKey + " = " + JSON.stringify(value);
+  if (existing?.[tailwindRootConfigKey] === value) {
+    return false;
+  }
+  if (dryRun) {
+    log("[EDS] would write " + label + " to package.json");
+    return false;
+  }
+  consumerPackage[consumerConfigField] = { ...(existing ?? {}), [tailwindRootConfigKey]: value };
+  writeConsumerPackageJson(packagePath, source, consumerPackage);
+  log("[EDS] wrote " + label + " to package.json; doctor, sync and the hooks now use this Tailwind root without " + tailwindRootEnvironmentVariable + ".");
+  return true;
+}
+
+export function applySync(plan, { dryRun = false, log = console.log } = {}) {
+  const version = "@spectrabrain/eds@" + plan.pkg.version;
+  if (plan.root === null && plan.only !== "agents") {
+    log("[EDS] " + noTailwindNote);
+  } else if (plan.root?.warning) {
+    log("[EDS] " + plan.root.warning);
+  }
+  persistTailwindRoot(plan, { dryRun, log });
+  if (plan.writes.length === 0) {
+    log("[EDS] Already synced with " + version + ".");
+    return [];
+  }
+  for (const write of plan.writes) {
+    if (dryRun) {
+      log("[EDS] would write " + write.relativePath);
+      continue;
+    }
+    fs.mkdirSync(path.dirname(write.path), { recursive: true });
+    fs.writeFileSync(write.path, write.after);
+    log("[EDS] wrote " + write.relativePath);
+  }
+  if (!dryRun) {
+    log(
+      "[EDS] Synced with " + version + ". Review the diff (AGENTS.md, CSS imports, " + toPosix(generatedCssRelativePath) +
+        ") before committing; the AGENTS.md block lists the rules.",
+    );
+  }
+  return plan.writes.map((write) => write.relativePath);
+}
+
+export function runSync({ consumerRoot, env = process.env, only = null, dryRun = false, log = console.log }) {
+  const plan = planSync({ consumerRoot, env, only });
+  applySync(plan, { dryRun, log });
+  return 0;
+}

package/consumer/update-agent-context.mjs

@@ -0,0 +1,87 @@
+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";
+
+export const claudeBeginMarker = "<!-- EDS:CLAUDE:BEGIN -->";
+export const claudeEndMarker = "<!-- EDS:CLAUDE:END -->";
+export const claudeImportLine = "@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;
+
+export function planAgentContext({ consumerRoot, pkg, packageManager = null }) {
+  const filePath = path.join(consumerRoot, "AGENTS.md");
+  const before = readTextIfExists(filePath);
+  // The block is rendered with the target file's dominant line ending; a new file uses LF.
+  const eol = before === null ? "\n" : detectEol(before);
+  const block = withEol(renderBlock(readTemplateBlock(pkg.packageRoot), pkg.version, packageManager), eol);
+  const located = before === null ? null : locateBlock(before);
+  return {
+    label: "agents",
+    path: filePath,
+    relativePath: relativeTo(consumerRoot, filePath),
+    before,
+    after: applyBlock(before, block, eol),
+    block,
+    existingBlock: located?.block ?? null,
+    existingVersion: located ? readBlockVersion(located.block) : null,
+  };
+}
+
+function hasImport(contents, beginMarker, endMarker) {
+  const visible = maskFencedBlocks(contents);
+  if (visible.includes(beginMarker) && visible.includes(endMarker)) {
+    return true;
+  }
+  return importPattern.test(visible);
+}
+
+// Returns null when the file does not exist, or when it and AGENTS.md are the same file (a symlink in either
+// direction): the managed block already lives in that file and an import would point at itself.
+function planImportFile({ consumerRoot, fileName, label, beginMarker, endMarker, importLine }) {
+  const filePath = path.join(consumerRoot, fileName);
+  const before = readTextIfExists(filePath);
+  if (before === null) {
+    return null;
+  }
+  const realPath = realpathOrNull(filePath);
+  const agentsRealPath = realpathOrNull(path.join(consumerRoot, "AGENTS.md"));
+  if (realPath !== null && realPath === agentsRealPath) {
+    return null;
+  }
+  const eol = detectEol(before);
+  const block = [beginMarker, importLine, endMarker].join(eol);
+  const trimmed = before.replace(/\s*$/, "");
+  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 };
+}
+
+// Claude Code reads CLAUDE.md; the import makes it follow the AGENTS.md managed block.
+export function planClaudeImport({ consumerRoot }) {
+  return planImportFile({
+    consumerRoot,
+    fileName: "CLAUDE.md",
+    label: "claude",
+    beginMarker: claudeBeginMarker,
+    endMarker: claudeEndMarker,
+    importLine: claudeImportLine,
+  });
+}
+
+// Gemini CLI reads GEMINI.md by default and AGENTS.md only with a context.fileName setting, so it gets the same import.
+export function planGeminiImport({ consumerRoot }) {
+  return planImportFile({
+    consumerRoot,
+    fileName: "GEMINI.md",
+    label: "gemini",
+    beginMarker: geminiBeginMarker,
+    endMarker: geminiEndMarker,
+    importLine: geminiImportLine,
+  });
+}

package/consumer-postinstall.mjs

@@ -0,0 +1,59 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { registerConsumerScripts } from "./consumer/register-scripts.mjs";
+
+const packageRoot = path.dirname(fileURLToPath(import.meta.url));
+const consumerRoot = process.env.INIT_CWD;
+
+if (!consumerRoot || path.resolve(consumerRoot) === packageRoot) {
+  process.exit(0);
+}
+
+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.");
+  process.exit(0);
+}
+
+function realpathOrNull(filePath) {
+  try {
+    return fs.realpathSync(filePath);
+  } catch {
+    return null;
+  }
+}
+
+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.");
+  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.");
+  process.exit(0);
+}
+
+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.");
+  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.");
+  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);
+} 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.");
+}

package/dist/base.css

@@ -0,0 +1,4 @@
+/* This file is generated by scripts/build-tokens.ts. Do not edit directly. */
+:where(html) {
+  font-family: var(--eds-typography-body1-fontFamily);
+}

package/dist/components/Button/README.md

@@ -2,7 +2,7 @@
 
 이 문서는 `Button` 디렉토리의 기준 문서입니다. `Button`의 개요·사용 맥락·공개 API·접근성 계약을 기록합니다. Button을 사용하기 전에는 이 문서를 먼저 확인합니다.
 
-패키지 설치와 공개 경로는 루트 [README.md](../../../README.md)를, 소비처 AI의 공통 규칙은 루트 [AI.md](../../../AI.md)를 참고합니다. 루트 `AI.md`에는 컴포넌트별 정책을 중복해서 기록하지 않습니다.
+패키지 설치와 공개 경로는 루트 [README.md](../../../README.md)를, 소비처 AI의 필수 규칙은 루트 [QUICKSTART.md](../../../QUICKSTART.md)를, 공개 범위와 금지 사례는 루트 [AI.md](../../../AI.md)를 참고합니다. 루트 문서에는 컴포넌트별 정책을 중복해서 기록하지 않습니다.
 
 ## 개요
 
@@ -10,6 +10,21 @@
 
 탐색 목적의 링크는 `neutral/link` 조합으로 표현하고, 상태 변경·폼 제출·명령 실행은 native `<button>`으로 표현합니다. `Button`은 현재 React 웹과 light theme만 지원합니다.
 
+화면에서 반복되는 행동 맥락은 다음처럼 선택합니다.
+
+| 행동 맥락 | 우선 검토할 조합 | 설명 |
+| --- | --- | --- |
+| 생성·저장·관리·확인처럼 화면의 핵심 행동 | `brand/solid` | 사용자가 완료해야 할 대표 행동을 강조합니다. 한 화면에 하나를 권장합니다. |
+| 검색·조회·일반적인 주요 실행 | `neutral/solid` | 브랜드 핵심 행동보다 낮은 주목도로 주요 액션을 표현합니다. |
+| 취소·닫기·수정 같은 보조 작업 | `neutral/outline` | 주 행동과 시각적 위계를 분리합니다. |
+| 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동 | `neutral/weak` | CTA를 보조하면서 반복 가능한 행동을 표현합니다. 되돌리기 어려운 초기화는 `critical/weak`입니다. |
+| 되돌리기 어려운 삭제·초기화 | `critical/weak` | 위험을 분명히 전달하고 가능하면 확인 절차와 함께 사용합니다. |
+| 비동기 저장·확인 처리 | 선택한 조합과 `loading` | 중복 실행을 막고 라벨·아이콘 공간과 accessible name을 유지합니다. |
+
+기존 화면에서 다른 조합을 사용하고 있더라도 새 코드에서는 행동의 의미에 맞는 위계를 먼저 검토합니다. 보조 행동은 한 조합으로 고정합니다. 취소·닫기·수정은 `neutral/outline`, 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동은 `neutral/weak`입니다. `neutral/link`는 페이지나 콘텐츠로 이동하는 탐색에만 사용합니다.
+
+표 행 조작이나 pagination처럼 공간이 좁은 곳에서는 `iconOnly`를 사용할 수 있습니다. 아이콘만으로 의미가 충분한지 확인하고, 필요한 경우 비어 있지 않은 `aria-label`을 지정합니다. 아이콘은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때만 사용합니다.
+
 ## 사용 맥락
 
 ### Size
@@ -53,8 +68,8 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 | `brand/solid` | 서비스의 핵심 행동에 사용합니다. 한 화면에 하나를 권장합니다. |
 | `brand/outline` | `brand/solid`보다 낮은 위계의 브랜드 보조 행동에 사용합니다. `neutral/outline`과 조합할 수 있으며 같은 액션 그룹에서 `brand/solid`와 함께 사용하지 않는 것을 권장합니다. |
 | `neutral/solid` | `brand/solid` 다음 위계의 일반적인 주요 CTA에 사용합니다. 한 화면에 하나를 권장합니다. |
-| `neutral/weak` | CTA를 제외한 일반적인 보조 행동에 사용하며, CTA와 함께 제공할 때 보조 위계를 표현합니다. |
-| `neutral/outline` | 시각적 부담을 낮춘 대안이나 보조 행동에 사용합니다. `neutral/solid`과 같은 액션 그룹에서 함께 사용하지 않으며, `brand/outline`과 조합할 수 있습니다. |
+| `neutral/weak` | 초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동에 사용합니다. 취소·닫기·수정은 `neutral/outline`을 사용합니다. |
+| `neutral/outline` | 취소·닫기·수정처럼 주 행동과 위계를 분리하는 보조 행동에 사용합니다. `neutral/solid`과 같은 액션 그룹에서 함께 사용하지 않으며, `brand/outline`과 조합할 수 있습니다. |
 | `neutral/ghost` | 툴바·헤더·옵션 메뉴처럼 주변 UI와의 간섭을 줄여야 하는 보조 행동에 사용합니다. |
 | `neutral/link` | 다른 페이지·콘텐츠로 이동하거나 관련 정보를 확인하는 탐색성 행동에 사용합니다. 상태 변경이나 일반 CTA에는 사용하지 않습니다. `href`가 필요하며 `<a>`로 렌더링합니다. |
 | `critical/weak` | 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다. 위험을 분명히 전달하며 가능하면 확인 대화상자나 Alert Dialog와 함께 사용합니다. |
@@ -98,9 +113,9 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 | --- | --- |
 | `children` | `ReactNode` label입니다. 렌더링 가능한 내용이 하나 이상 필요하며 `startIcon`·`endIcon`과 조합할 수 있습니다. |
 | `icon` | icon-only용 단일 custom `ReactElement`입니다. children이나 start/end icon과 함께 사용하지 않습니다. |
-| `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. |
+| `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. 승인된 아이콘 목록의 이름만 허용합니다. |
 | `startIcon` / `endIcon` | label 앞·뒤의 단일 custom `ReactElement` 슬롯입니다. |
-| `startIconName` / `endIconName` | label 앞·뒤의 `ButtonIconName` lucide 이름 슬롯입니다. |
+| `startIconName` / `endIconName` | label 앞·뒤의 `ButtonIconName` lucide 이름 슬롯입니다. 승인된 아이콘 목록의 이름만 허용합니다. |
 | `aria-label` | 선택적인 `string`입니다. icon-only의 accessible name을 제공할 때 지정하며, 필수로 강제하지 않습니다. |
 | `disabled` | `boolean`입니다. native button은 `disabled`, link는 href 제거·`aria-disabled="true"`·`tabIndex={-1}`를 적용합니다. |
 | `loading` | `boolean`입니다. label·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단합니다. `aria-busy="true"`를 적용합니다. |
@@ -114,6 +129,10 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 
 `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`입니다.

package/dist/components/Button/spec.json

@@ -1,6 +1,6 @@
 {
   "specVersion": 1,
-  "packageVersion": "0.0.4",
+  "packageVersion": "0.1.0",
   "name": "Button",
   "purpose": "사용자가 즉시 실행할 수 있는 행동과 탐색을 표현하는 인터랙티브 요소입니다.",
   "usageContexts": [
@@ -9,6 +9,14 @@
     "brand는 화면에서 가장 중요한 행동을 강조할 때 사용합니다.",
     "neutral은 일반적인 액션과 탐색에 사용합니다.",
     "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다.",
+    "생성·저장·관리·확인처럼 화면의 핵심 행동에는 brand/solid를 먼저 검토합니다.",
+    "검색·조회·일반적인 주요 실행에는 neutral/solid를 먼저 검토합니다.",
+    "취소·닫기·수정 같은 보조 작업에는 neutral/outline을 사용합니다.",
+    "초기화·갱신·되돌리기처럼 부담이 낮은 반복 행동에는 neutral/weak를 사용합니다.",
+    "되돌리기 어려운 삭제·초기화는 critical/weak와 확인 절차를 먼저 검토합니다.",
+    "비동기 저장·확인에는 loading을 사용해 중복 실행을 막고 라벨 공간을 유지합니다.",
+    "표 행 조작·pagination처럼 공간이 좁은 곳의 icon-only는 accessible name을 확인합니다.",
+    "icon은 생성·수정·삭제·외부 이동·다운로드처럼 행동의 목적이나 방향을 보조할 때 사용합니다.",
     "icon-only의 접근성 이름을 제공하려면 aria-label을 지정합니다. aria-label은 필수로 강제하지 않습니다."
   ],
   "unsupportedContexts": [
@@ -157,6 +165,55 @@
       "iconBoth": "children과 앞·뒤 아이콘을 모두 제공합니다.",
       "iconOnly": "children 없이 icon 또는 iconName을 제공합니다. 접근성 이름이 필요하면 aria-label을 지정합니다."
     },
+    "iconNames": [
+      "ArrowLeft",
+      "ArrowRight",
+      "Check",
+      "ChevronDown",
+      "ChevronLeft",
+      "ChevronRight",
+      "ChevronUp",
+      "ChevronsUpDown",
+      "Circle",
+      "CircleAlert",
+      "CircleCheckBig",
+      "CirclePause",
+      "CirclePlay",
+      "CircleQuestionMark",
+      "ClockAlert",
+      "Copy",
+      "Eye",
+      "EyeOff",
+      "FaceNeutral",
+      "FileDown",
+      "FilePenLine",
+      "FileX",
+      "FolderClock",
+      "Fullscreen",
+      "ImageOff",
+      "ImagePlus",
+      "Info",
+      "Key",
+      "Languages",
+      "Layers2",
+      "List",
+      "LoaderCircle",
+      "LockOpen",
+      "Mail",
+      "Megaphone",
+      "Minimize",
+      "Minus",
+      "Moon",
+      "Paperclip",
+      "Plus",
+      "RotateCw",
+      "Search",
+      "Sun",
+      "ThumbsUp",
+      "Trash",
+      "VectorSquare",
+      "X"
+    ],
     "typeExports": [
       "ButtonProps",
       "ButtonComponent",

package/dist/components.css

@@ -245,9 +245,7 @@
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  flex: 0 0 auto;
   appearance: none;
-  margin: 0;
   border: 0;
   font: inherit;
   white-space: nowrap;