@spectrabrain/eds 0.0.3 → 0.0.4

package/AI.md

@@ -9,7 +9,7 @@
 - `@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만 불러옵니다.
 
-문서에 없는 API, variant, loading 동작은 추측해서 구현하지 않습니다. 공개되지 않은 토큰 원본을 직접 import하지 않습니다. dark theme와 Tailwind utility API도 지원하지 않습니다.
+문서에 없는 API, variant, loading 동작은 추측해서 구현하지 않습니다. 공개되지 않은 토큰 원본을 직접 import하지 않습니다. dark theme를 지원하지 않으며, EDS가 Tailwind utility API를 직접 제공하지도 않습니다. 소비처에서 semantic token을 Tailwind CSS v4 className으로 연결해야 하면 [TAILWIND_V4.md](TAILWIND_V4.md)를 먼저 읽습니다.
 
 ## 토큰 사용
 
@@ -27,6 +27,10 @@ const color = cssVar(token); // var(--eds-color-fg-brand)
 - 문서에 없는 deep import, raw 색상값, 임의 CSS variable은 사용하지 않습니다.
 - 역할에 맞는 semantic token이 없으면 임의 값을 만들지 말고 디자인 시스템 담당자에게 요청합니다.
 
+## Tailwind CSS v4 token 설정
+
+소비처가 컴포넌트가 아닌 token만 Tailwind CSS v4 utility로 사용하려는 경우 [TAILWIND_V4.md](TAILWIND_V4.md)의 설치·alias·typography preset 설정을 따릅니다. 이 가이드는 공개 semantic CSS variable만 Tailwind theme alias와 custom utility로 연결하며, 내부 token 원본이나 raw 값을 소비처에 복사하지 않습니다.
+
 ## 컴포넌트 문서 읽기
 
 컴포넌트를 사용하기 전에 해당 컴포넌트의 README와 공개 manifest를 먼저 읽습니다. 문서에는 컴포넌트의 개요, 사용 맥락, 공개 API, 접근성 계약, 금지 사례를 기록합니다.

package/README.md

@@ -33,7 +33,7 @@ export function SaveButton() {
 }
 ~~~
 
-아이콘만 사용하는 경우 `icon`과 비어 있지 않은 `aria-label`을 함께 제공합니다. `style`과 임의 스타일 override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 `AI.md`를 확인합니다.
+아이콘만 사용하는 경우 접근성 이름을 제공하려면 `icon` 또는 `iconName`과 `aria-label`을 함께 지정합니다. `aria-label`은 필수로 강제하지 않습니다. `style`과 임의 스타일 override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 `AI.md`를 확인합니다.
 
 lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconName`으로 지정합니다. `ButtonIconName`이 TypeScript 자동완성을 제공하며, 같은 슬롯에 custom ReactElement와 이름을 함께 지정하지 않습니다. 이름으로 지정한 아이콘은 `lucide-react`의 기본 시각 설정을 사용하고 Button이 아이콘 영역 크기를 조정합니다.
 
@@ -70,7 +70,7 @@ lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconNa
 | `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. |
 | `startIcon` / `endIcon` | label 앞·뒤에 배치할 단일 custom `ReactElement` 슬롯입니다. |
 | `startIconName` / `endIconName` | label 앞·뒤에 배치할 `ButtonIconName` lucide 이름입니다. |
-| `aria-label` | icon-only에서 비어 있지 않은 accessible name으로 필수입니다. text label에서는 필요할 때 지정합니다. |
+| `aria-label` | 선택적인 accessible name입니다. icon-only의 접근성 이름을 제공할 때 지정하며, text label에서도 필요할 때 사용할 수 있습니다. |
 | `disabled` | 실행할 수 없는 상태입니다. native button은 `disabled`, link는 href 제거·`aria-disabled="true"`·`tabIndex={-1}`를 적용합니다. |
 | `loading` | 처리 중 상태입니다. label과 아이콘 공간을 유지하고 progress circle을 표시하며 상호작용을 차단합니다. `aria-busy="true"`를 적용합니다. |
 | `className` | 배치·컨테이너 보정용으로만 사용합니다. |
@@ -89,7 +89,7 @@ lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconNa
 | children과 앞·뒤 아이콘을 모두 지정합니다. | `iconBoth` |
 | children 없이 `icon` 또는 `iconName`만 지정합니다. | `iconOnly` |
 
-잘못된 슬롯 조합, 빈 label·accessible name·icon은 모든 환경에서 오류로 처리합니다. Button의 개요와 사용 맥락은 설치된 패키지의 `llms.txt`에서 안내하는 Button 문서를 기준으로 합니다.
+잘못된 슬롯 조합, 빈 label·icon 또는 제공된 빈 `aria-label`은 모든 환경에서 오류로 처리합니다. Button의 개요와 사용 맥락은 설치된 패키지의 `llms.txt`에서 안내하는 Button 문서를 기준으로 합니다.
 
 ## 토큰 사용
 
@@ -107,6 +107,10 @@ const color = cssVar(token); // var(--eds-color-fg-brand-contrast)
 
 필요한 역할의 token이 없으면 임의 색상값을 추가하지 말고 디자인 시스템 담당자에게 요청합니다.
 
+## Tailwind CSS v4에서 token 사용
+
+EDS는 Tailwind utility API를 패키지에 포함하지 않습니다. Tailwind CSS v4에서 공개 semantic token을 className으로 사용하려면 [Tailwind CSS v4 token 설정 가이드](./TAILWIND_V4.md)를 확인합니다. 가이드는 `@theme inline` color alias와 `@utility` typography preset을 설정하는 방법을 안내합니다.
+
 ## Text style 사용
 
 하나의 text style은 다섯 속성을 함께 적용합니다.
@@ -133,6 +137,7 @@ const color = cssVar(token); // var(--eds-color-fg-brand-contrast)
 | `@spectrabrain/eds/styles.css` | Pretendard font와 semantic CSS custom property를 함께 불러옵니다. |
 | `@spectrabrain/eds/fonts.css` | Pretendard font만 불러옵니다. |
 | `@spectrabrain/eds/tokens.json` | 도구 연동용 semantic token manifest입니다. |
+| `@spectrabrain/eds/TAILWIND_V4.md` | Tailwind CSS v4에서 공개 token을 연결하는 설치 가이드입니다. |
 | `@spectrabrain/eds/components/Button/README.md` | Button 개요·사용 맥락·공개 API 문서입니다. |
 | `@spectrabrain/eds/components/Button/spec.json` | Button 공개 API와 접근성 계약을 위한 manifest입니다. |
 | `@spectrabrain/eds/llms.txt` | AI 문서 읽기 순서입니다. |

package/TAILWIND_V4.md

@@ -0,0 +1,284 @@
+# EVA token을 Tailwind CSS v4에서 사용하는 가이드
+
+이 문서는 소비처가 `@spectrabrain/eds`의 공개 semantic token을 Tailwind CSS v4의 `className`으로 사용하는 방법을 안내합니다. EDS는 Tailwind utility API를 패키지에 포함하지 않으며, 소비처에서 공개 CSS variable을 Tailwind theme alias와 utility로 연결해 사용합니다.
+
+이 가이드는 token만 연결하는 경우를 다룹니다. React 컴포넌트의 구현이나 컴포넌트별 스타일을 변경하지 않습니다.
+
+## 공개 범위
+
+소비처는 다음 공개 경로만 사용합니다.
+
+| 경로 | 용도 |
+| --- | --- |
+| `@spectrabrain/eds/tokens.css` | semantic CSS variable을 불러옵니다. |
+| `@spectrabrain/eds/fonts.css` | Pretendard font를 불러옵니다. 선택 사항입니다. |
+| `@spectrabrain/eds/tokens.json` | 공개 token 이름과 타입을 도구에서 확인합니다. |
+| `@spectrabrain/eds/tokens` | TypeScript token 이름과 `cssVar()`를 사용합니다. |
+
+공개되지 않은 내부 token 원본이나 raw 값을 소비처에 복사하지 않습니다.
+
+## 사전 조건
+
+- React 웹 프로젝트입니다.
+- Tailwind CSS v4를 사용합니다.
+- 프로젝트의 framework와 bundler가 확인되어 있습니다.
+- 전역 CSS 진입점이 하나 지정되어 있습니다.
+
+## 설치
+
+기본 패키지를 설치합니다. Tailwind adapter는 프로젝트의 빌드 방식에 맞는 하나만 선택합니다.
+
+~~~sh
+npm install @spectrabrain/eds
+~~~
+
+Vite 프로젝트는 Tailwind Vite adapter를 추가합니다.
+
+~~~sh
+npm install -D tailwindcss @tailwindcss/vite
+~~~
+
+PostCSS 기반 프로젝트는 PostCSS adapter를 추가합니다.
+
+~~~sh
+npm install -D tailwindcss @tailwindcss/postcss postcss
+~~~
+
+이미 설치된 패키지는 중복 설치하지 않으며 Vite adapter와 PostCSS adapter를 동시에 추가하지 않습니다.
+
+## 설치 시 자동화 정책
+
+EDS는 `npm install`의 `postinstall`에서 소비처의 CSS나 설정 파일을 수정하지 않습니다. 설치 스크립트가 파일을 덮어쓰면 소비처의 기존 Tailwind 설정, CI 정책, package manager 설정과 충돌할 수 있기 때문입니다.
+
+token alias를 EDS 버전과 함께 자동 갱신하려면 소비처 저장소가 다음 작업을 소유하는 명시적인 생성 스크립트를 둡니다.
+
+1. `@spectrabrain/eds/tokens.json`에서 token 이름만 읽습니다.
+2. `color-*` token을 `var(--eds-...)`로 연결하는 `@theme inline` 블록을 생성합니다.
+3. raw `$value`나 비공개 파일 경로는 생성물에 기록하지 않습니다.
+4. `npm run generate:eds-tailwind`처럼 명시적으로 실행하고, 필요할 때만 소비처의 `postinstall` 또는 CI에 연결합니다.
+
+설치 스크립트를 사용하지 않는 환경에서도 동작하도록 생성된 `eds-tokens.css`는 저장소에 두거나 CI에서 재생성합니다. 현재 EDS가 제공하는 자동화 범위는 공개 token manifest와 이 설치 가이드이며, 소비처 파일을 직접 변경하는 CLI는 제공하지 않습니다.
+
+다음은 소비처가 소유할 수 있는 color alias 생성 스크립트 예시입니다. 이 스크립트는 token의 실제 값을 읽지 않고 공개 이름만 읽습니다.
+
+~~~js
+// scripts/generate-eds-tailwind.mjs
+import fs from "node:fs";
+import path from "node:path";
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+const manifestPath = require.resolve("@spectrabrain/eds/tokens.json");
+const manifest = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+const colorNames = Object.keys(manifest.tokens).filter((name) => name.startsWith("color-"));
+const aliases = colorNames
+  .map((name) => `  --color-eds-${name.slice("color-".length)}: var(--eds-${name});`)
+  .join("\n");
+const output = `@theme inline {\n${aliases}\n}\n`;
+const outputPath = path.resolve("src/styles/eds-tokens.css");
+
+fs.mkdirSync(path.dirname(outputPath), { recursive: true });
+fs.writeFileSync(outputPath, output);
+~~~
+
+소비처의 `package.json`에는 기존 script를 덮어쓰지 않는 범위에서 다음 명령을 추가할 수 있습니다.
+
+~~~json
+{
+  "scripts": {
+    "generate:eds-tailwind": "node scripts/generate-eds-tailwind.mjs"
+  }
+}
+~~~
+
+`postinstall`에 연결하려면 소비처의 보안·CI 정책이 허용하는 경우에만 기존 `postinstall` 뒤에 `npm run generate:eds-tailwind`를 추가합니다. 설치 시 script 실행이 차단된 환경도 고려해 생성 파일을 커밋하거나 CI에서 `generate:eds-tailwind`를 먼저 실행합니다.
+
+## Tailwind v4 연결
+
+### Vite
+
+`vite.config.ts`의 기존 plugins를 유지하면서 `tailwindcss()`를 추가합니다.
+
+~~~ts
+import tailwindcss from "@tailwindcss/vite";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  plugins: [tailwindcss()],
+});
+~~~
+
+기존 React plugin 등 다른 plugin은 제거하지 않습니다.
+
+### PostCSS
+
+`postcss.config.mjs`의 기존 설정을 유지하면서 adapter를 추가합니다.
+
+~~~js
+export default {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+~~~
+
+## 전역 CSS 설정
+
+기존 전역 CSS 파일을 사용합니다. 중복 stylesheet를 만들지 않습니다.
+
+~~~css
+@import "tailwindcss";
+@import "@spectrabrain/eds/tokens.css";
+@import "./eds-tokens.css";
+~~~
+
+Pretendard font도 사용하려면 `eds-tokens.css`보다 앞이나 뒤에 다음 import를 추가합니다.
+
+~~~css
+@import "@spectrabrain/eds/fonts.css";
+~~~
+
+`tokens.css`는 token variable만 제공하며 애플리케이션의 font-family를 자동으로 지정하지 않습니다.
+
+## Color token alias
+
+`eds-tokens.css`에 공개 semantic color variable을 Tailwind theme alias로 연결합니다. `@theme inline`을 사용해야 EDS CSS variable 참조가 유지됩니다.
+
+~~~css
+@theme inline {
+  --color-eds-fg-brand: var(--eds-color-fg-brand);
+  --color-eds-fg-neutral: var(--eds-color-fg-neutral);
+  --color-eds-fg-neutral-secondary: var(--eds-color-fg-neutral-secondary);
+  --color-eds-fg-neutral-inverted: var(--eds-color-fg-neutral-inverted);
+
+  --color-eds-bg-brand-primary: var(--eds-color-bg-brand-primary);
+  --color-eds-bg-brand-primary-hover: var(--eds-color-bg-brand-primary-hover);
+  --color-eds-bg-neutral-primary: var(--eds-color-bg-neutral-primary);
+  --color-eds-bg-neutral-primary-hover: var(--eds-color-bg-neutral-primary-hover);
+  --color-eds-bg-neutral-weak: var(--eds-color-bg-neutral-weak);
+  --color-eds-bg-disabled: var(--eds-color-bg-disabled);
+
+  --color-eds-stroke-neutral-secondary: var(--eds-color-stroke-neutral-secondary);
+  --color-eds-stroke-focusRing: var(--eds-color-stroke-focusRing);
+}
+~~~
+
+다음 규칙으로 추가 alias를 작성합니다.
+
+| EDS token | Tailwind alias | 생성되는 utility 예시 |
+| --- | --- | --- |
+| `color-fg-brand` | `--color-eds-fg-brand` | `text-eds-fg-brand` |
+| `color-bg-brand-primary` | `--color-eds-bg-brand-primary` | `bg-eds-bg-brand-primary` |
+| `color-stroke-neutral-secondary` | `--color-eds-stroke-neutral-secondary` | `border-eds-stroke-neutral-secondary` |
+
+사용 예시는 다음과 같습니다.
+
+~~~tsx
+<div className="bg-eds-bg-neutral-primary text-eds-fg-neutral border border-eds-stroke-neutral-secondary">
+  콘텐츠입니다.
+</div>
+~~~
+
+상태별 표현에는 semantic hover token을 사용합니다.
+
+~~~tsx
+<a className="text-eds-fg-brand hover:text-eds-fg-brand-contrast" href="/details">
+  자세히 보기
+</a>
+~~~
+
+## Typography preset utility
+
+EDS typography preset은 font family, weight, size, line height, letter spacing을 함께 적용합니다. Tailwind의 `text-*` theme variable만으로는 다섯 속성을 하나의 preset으로 묶을 수 없으므로 `@utility`를 사용합니다.
+
+~~~css
+@utility eds-typography-title3 {
+  font-family: var(--eds-typography-title3-fontFamily);
+  font-weight: var(--eds-typography-title3-fontWeight);
+  font-size: var(--eds-typography-title3-fontSize);
+  line-height: var(--eds-typography-title3-lineHeight);
+  letter-spacing: var(--eds-typography-title3-letterSpacing);
+}
+~~~
+
+다음 preset을 같은 규칙으로 제공합니다.
+
+~~~text
+display1, display2
+heading1, heading2, heading3, heading4
+title1, title2, title3, title4
+body1, body2, body3, body4
+caption1, caption2, caption3
+~~~
+
+사용 예시는 다음과 같습니다.
+
+~~~tsx
+<h1 className="eds-typography-heading1 text-eds-fg-neutral">
+  제목입니다.
+</h1>
+
+<p className="eds-typography-body2 text-eds-fg-neutral-secondary">
+  본문입니다.
+</p>
+~~~
+
+## Spacing과 radius
+
+현재 공개 semantic token에 없는 spacing·radius 값을 소비처에서 임의로 alias로 만들지 않습니다. 공개 token이 필요한 경우 다음 정보를 디자인 시스템 담당자에게 요청합니다.
+
+- 필요한 token 이름입니다.
+- 사용하려는 UI 목적입니다.
+- 필요한 상태나 variant입니다.
+- 기존 Tailwind scale로 대체할 수 없는 이유입니다.
+
+내부 파일 경로를 참조하거나 raw 값을 복사해 `spacing-eds-*`, `radius-eds-*` utility를 만들지 않습니다.
+
+## TypeScript token 자동완성
+
+CSS가 아닌 CSS-in-JS 또는 inline style에서 token을 선택해야 하면 공개 TypeScript API를 사용합니다.
+
+~~~ts
+import { cssVar, type SemanticTokenName } from "@spectrabrain/eds/tokens";
+
+const token: SemanticTokenName = "color-fg-brand";
+const color = cssVar(token);
+// var(--eds-color-fg-brand)
+~~~
+
+`SemanticTokenName`은 공개 semantic token 이름 자동완성을 제공합니다. token 값 자체를 복사해 스타일에 넣지 않고 `cssVar()` 결과를 사용합니다.
+
+## 권장 파일 구조
+
+~~~text
+src/styles/
+  globals.css
+  eds-tokens.css
+~~~
+
+`globals.css`에서 `tailwindcss`, EDS token CSS, `eds-tokens.css`를 한 번씩 import합니다. alias와 typography utility는 `eds-tokens.css`에서 관리합니다.
+
+token 목록이 많거나 EDS 버전 변경 때 자동 갱신이 필요하면 `@spectrabrain/eds/tokens.json`의 token 이름과 CSS variable 이름만 읽어 alias 파일을 생성할 수 있습니다. 생성 스크립트에는 raw `$value`를 포함하지 않습니다.
+
+## 금지 사항
+
+- EDS 내부 token 원본을 import하거나 복사하지 않습니다.
+- raw hex·px·rem 값을 EDS token 대신 작성하지 않습니다.
+- `@theme`에 EDS token의 resolved 값을 직접 입력하지 않습니다.
+- `@spectrabrain/eds` 패키지 내부의 비공개 경로를 deep import하지 않습니다.
+- Tailwind class로 EDS가 관리하는 UI 스타일을 임의로 덮어쓰지 않습니다.
+- EDS token 이름과 다른 의미의 alias를 만들어 역할을 바꾸지 않습니다.
+
+## AI 설정 완료 조건
+
+소비처 AI는 설정을 마친 뒤 다음을 확인합니다.
+
+1. framework와 Tailwind v4 adapter가 현재 프로젝트에 맞게 연결되어 있습니다.
+2. EDS token CSS가 전역에서 한 번만 import되어 있습니다.
+3. semantic color alias가 `var(--eds-...)`를 참조합니다.
+4. typography preset utility가 모든 공개 preset에 대해 생성되어 있습니다.
+5. 생성 CSS에 raw 값이나 비공개 token 경로가 없습니다.
+6. 예시 `className`이 실제 빌드 결과에 포함됩니다.
+7. 소비처의 typecheck, lint, test, build가 통과합니다.
+
+설정 후 변경 파일, 설치 패키지, 사용할 수 있는 `eds-*` class, 공개되지 않아 추가하지 않은 token, 검증 결과를 요약합니다.

package/dist/components/Button/README.md

@@ -32,7 +32,7 @@ Layout은 라벨과 아이콘의 조합으로 결정합니다. 아이콘은 행
 | `iconFirst` | 라벨 앞에 아이콘을 둡니다. | 아이콘이 행동의 목적을 보조할 때 사용합니다. |
 | `iconLast` | 라벨 뒤에 아이콘을 둡니다. | 이동 방향이나 다음 단계를 나타낼 때 사용합니다. |
 | `iconBoth` | 라벨 양쪽에 아이콘을 둡니다. | 양쪽 아이콘이 모두 의미를 더하는 명확한 경우에만 사용합니다. |
-| `iconOnly` | 아이콘만 제공합니다. | 아이콘만으로 행동의 의미가 충분히 명확할 때 사용하며, 비어 있지 않은 `aria-label`이 필요합니다. |
+| `iconOnly` | 아이콘만 제공합니다. | 아이콘만으로 행동의 의미가 충분히 명확할 때 사용하며, 접근성 이름을 제공하려면 `aria-label`을 지정합니다. |
 
 ### Role
 
@@ -101,7 +101,7 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 | `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. |
 | `startIcon` / `endIcon` | label 앞·뒤의 단일 custom `ReactElement` 슬롯입니다. |
 | `startIconName` / `endIconName` | label 앞·뒤의 `ButtonIconName` lucide 이름 슬롯입니다. |
-| `aria-label` | `string`이며 icon-only에서 비어 있지 않은 accessible name으로 필수입니다. |
+| `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"`를 적용합니다. |
 | `className` | `string`이며 배치·컨테이너 보정에만 허용합니다. |
@@ -120,9 +120,9 @@ Variant는 같은 Role 안에서 시각적 위계를 정의합니다.
 - children과 `startIcon`이 있으면 `iconFirst`입니다.
 - children과 `endIcon`이 있으면 `iconLast`입니다.
 - children과 두 아이콘이 있으면 `iconBoth`입니다.
-- children 없이 `icon`만 있으면 `iconOnly`이며 비어 있지 않은 `aria-label`이 필수입니다.
+- children 없이 `icon` 또는 `iconName`만 있으면 `iconOnly`입니다. 접근성 이름이 필요하면 비어 있지 않은 `aria-label`을 지정합니다.
 
-빈 label·icon과 잘못된 슬롯 조합은 모든 환경에서 오류로 처리합니다. label은 한 줄을 유지합니다.
+빈 label·icon, 제공된 빈 `aria-label`과 잘못된 슬롯 조합은 모든 환경에서 오류로 처리합니다. label은 한 줄을 유지합니다.
 
 `className`, native `aria-*`, `data-*`, `forwardRef`를 지원합니다. `style`과 임의 스타일 override는 공개하지 않습니다.
 
@@ -135,7 +135,7 @@ Variant는 같은 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의 이름은 Button의 `aria-label`로 제공합니다.
+- 아이콘은 시각 장식으로 `aria-hidden="true"` 처리하며, icon-only의 accessible name을 제공할 때 Button의 `aria-label`을 사용합니다. `aria-label`은 필수로 강제하지 않습니다.
 - loading progress circle은 `800ms linear infinite` 회전하며 `prefers-reduced-motion: reduce`에서는 정지합니다.
 
 ## 문서와 검증

package/dist/components/Button/spec.json

@@ -1,6 +1,6 @@
 {
   "specVersion": 1,
-  "packageVersion": "0.0.3",
+  "packageVersion": "0.0.4",
   "name": "Button",
   "purpose": "사용자가 즉시 실행할 수 있는 행동과 탐색을 표현하는 인터랙티브 요소입니다.",
   "usageContexts": [
@@ -8,12 +8,12 @@
     "다른 페이지나 콘텐츠로 이동하는 탐색에는 neutral/link branch를 사용합니다.",
     "brand는 화면에서 가장 중요한 행동을 강조할 때 사용합니다.",
     "neutral은 일반적인 액션과 탐색에 사용합니다.",
-    "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다."
+    "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다.",
+    "icon-only의 접근성 이름을 제공하려면 aria-label을 지정합니다. aria-label은 필수로 강제하지 않습니다."
   ],
   "unsupportedContexts": [
     "문서에 없는 role·variant·상태를 className이나 inline style로 우회하지 않습니다.",
-    "상태 변경이나 일반 CTA를 neutral/link로 표현하지 않습니다.",
-    "icon-only에서는 accessible name 없이 아이콘만 사용하지 않습니다."
+    "상태 변경이나 일반 CTA를 neutral/link로 표현하지 않습니다."
   ],
   "api": {
     "props": [
@@ -95,7 +95,7 @@
         "name": "aria-label",
         "type": "string",
         "required": false,
-        "description": "accessible name입니다. icon-only에서는 필수입니다."
+        "description": "accessible name입니다. icon-only의 접근성 이름을 제공할 때 사용합니다."
       },
       {
         "name": "disabled",
@@ -155,7 +155,7 @@
       "iconFirst": "children과 startIcon 또는 startIconName을 제공합니다.",
       "iconLast": "children과 endIcon 또는 endIconName을 제공합니다.",
       "iconBoth": "children과 앞·뒤 아이콘을 모두 제공합니다.",
-      "iconOnly": "children 없이 icon 또는 iconName을 제공하고 비어 있지 않은 aria-label을 지정합니다."
+      "iconOnly": "children 없이 icon 또는 iconName을 제공합니다. 접근성 이름이 필요하면 aria-label을 지정합니다."
     },
     "typeExports": [
       "ButtonProps",
@@ -171,7 +171,7 @@
   "accessibility": {
     "nativeButtonType": "native button branch에서는 type을 필수로 지정합니다.",
     "linkHref": "neutral/link branch에서는 href를 필수로 지정합니다.",
-    "iconOnlyName": "icon-only layout에서는 비어 있지 않은 aria-label을 필수로 지정합니다.",
+    "iconOnlyName": "icon-only layout에서는 접근성 이름을 제공할 때 비어 있지 않은 aria-label을 지정합니다. aria-label은 필수가 아닙니다.",
     "disabledLink": "비활성 link는 href를 제거하고 aria-disabled와 tabIndex를 적용합니다.",
     "loading": "loading 중에는 aria-busy를 적용하고 상호작용을 차단합니다.",
     "focusVisible": "keyboard focus에는 승인된 focus ring을 표시합니다."

package/dist/index.d.mts

@@ -48,7 +48,7 @@ type IconOnlySlotProps = {
     readonly startIconName?: never;
     readonly endIcon?: never;
     readonly endIconName?: never;
-    readonly "aria-label": string;
+    readonly "aria-label"?: string;
 } & ({
     readonly icon: ReactElement;
     readonly iconName?: never;

package/dist/index.d.ts

@@ -48,7 +48,7 @@ type IconOnlySlotProps = {
     readonly startIconName?: never;
     readonly endIcon?: never;
     readonly endIconName?: never;
-    readonly "aria-label": string;
+    readonly "aria-label"?: string;
 } & ({
     readonly icon: ReactElement;
     readonly iconName?: never;