@spectrabrain/eds 0.0.2 → 0.0.3

package/AI.md

@@ -29,14 +29,15 @@ const color = cssVar(token); // var(--eds-color-fg-brand)
 
 ## 컴포넌트 문서 읽기
 
-컴포넌트를 사용하거나 구현하기 전에 해당 컴포넌트 디렉토리의 `README.md`를 먼저 읽습니다. 이 문서에 컴포넌트의 개요, 사용 맥락, 공개 API, 접근성 계약, 금지 사례를 기록합니다.
+컴포넌트를 사용하기 전에 해당 컴포넌트의 README와 공개 manifest를 먼저 읽습니다. 문서에는 컴포넌트의 개요, 사용 맥락, 공개 API, 접근성 계약, 금지 사례를 기록합니다.
 
-현재 제공하는 컴포넌트 문서는 다음 위치에 있습니다.
+현재 `Button` 문서는 다음 경로에서 확인합니다.
 
-| 컴포넌트 | 문서 위치 |
-| --- | --- |
-| `Button` | `src/components/Button/README.md` |
+| 환경 | 개요·API 문서 | 기계 판독 manifest |
+| --- | --- | --- |
+| 저장소 작업 | `src/components/Button/README.md` | `dist/components/Button/spec.json` |
+| npm 설치 후 | `dist/components/Button/README.md` | `dist/components/Button/spec.json` |
 
-컴포넌트별 문서에 없는 props·variant·상태·사용 맥락은 추측해서 추가하지 않습니다.
+패키지의 전체 AI 문서 읽기 순서는 [llms.txt](llms.txt)에서 확인합니다. 컴포넌트별 문서에 없는 props·variant·상태·사용 맥락은 추측해서 추가하지 않습니다.
 
 제공되는 EDS 컴포넌트를 유사한 자체 구현보다 우선 사용합니다. typed prop으로 제공하지 않은 색상·상태·variant를 `className`이나 inline style로 우회하지 않으며, native semantics·accessible name·keyboard interaction을 임의로 변경하지 않습니다.

package/README.md

@@ -33,7 +33,7 @@ export function SaveButton() {
 }
 ~~~
 
-아이콘만 사용하는 경우 `icon`과 비어 있지 않은 `aria-label`을 함께 제공합니다. `style`과 component token override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 `AI.md`를 확인합니다.
+아이콘만 사용하는 경우 `icon`과 비어 있지 않은 `aria-label`을 함께 제공합니다. `style`과 임의 스타일 override는 지원하지 않습니다. 전체 contract와 접근성 규칙은 설치된 버전의 `AI.md`를 확인합니다.
 
 lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconName`으로 지정합니다. `ButtonIconName`이 TypeScript 자동완성을 제공하며, 같은 슬롯에 custom ReactElement와 이름을 함께 지정하지 않습니다. 이름으로 지정한 아이콘은 `lucide-react`의 기본 시각 설정을 사용하고 Button이 아이콘 영역 크기를 조정합니다.
 
@@ -77,7 +77,7 @@ lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconNa
 | `aria-*` / `data-*` | native 속성으로 전달할 수 있습니다. |
 | `ref` | native button은 `HTMLButtonElement`, link는 `HTMLAnchorElement`를 전달합니다. |
 
-`style`과 component token override API는 제공하지 않습니다. lucide 이름과 custom `ReactElement`는 같은 슬롯에 함께 지정하지 않습니다. 이름으로 지정한 lucide 아이콘은 `lucide-react` 기본 시각 설정을 사용하며, Button은 아이콘 영역 크기만 조정합니다.
+`style`과 임의 스타일 override API는 제공하지 않습니다. lucide 이름과 custom `ReactElement`는 같은 슬롯에 함께 지정하지 않습니다. 이름으로 지정한 lucide 아이콘은 `lucide-react` 기본 시각 설정을 사용하며, Button은 아이콘 영역 크기만 조정합니다.
 
 슬롯 조합에 따라 layout은 다음처럼 추론합니다.
 
@@ -89,7 +89,7 @@ lucide 아이콘은 PascalCase 이름을 `iconName`, `startIconName`, `endIconNa
 | children과 앞·뒤 아이콘을 모두 지정합니다. | `iconBoth` |
 | children 없이 `icon` 또는 `iconName`만 지정합니다. | `iconOnly` |
 
-잘못된 슬롯 조합, 빈 label·accessible name·icon은 모든 환경에서 오류로 처리합니다. Button의 개요와 사용 맥락은 저장소의 [Button 컴포넌트 문서](src/components/Button/README.md)를 기준으로 합니다.
+잘못된 슬롯 조합, 빈 label·accessible name·icon은 모든 환경에서 오류로 처리합니다. Button의 개요와 사용 맥락은 설치된 패키지의 `llms.txt`에서 안내하는 Button 문서를 기준으로 합니다.
 
 ## 토큰 사용
 
@@ -133,13 +133,16 @@ 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/components/Button/README.md` | Button 개요·사용 맥락·공개 API 문서입니다. |
+| `@spectrabrain/eds/components/Button/spec.json` | Button 공개 API와 접근성 계약을 위한 manifest입니다. |
+| `@spectrabrain/eds/llms.txt` | AI 문서 읽기 순서입니다. |
 | `@spectrabrain/eds/package.json` | 패키지 메타데이터입니다. |
 
 표에 명시한 경로만 지원합니다. 설치된 패키지 버전의 API를 기준으로 사용합니다.
 
 ## 소비자 가이드
 
-AI와 자동화 도구를 위한 규칙은 [AI.md](AI.md)에서 확인합니다. React 컴포넌트가 추가되면 해당 컴포넌트의 공식 API와 사용 규칙을 먼저 확인합니다.
+AI와 자동화 도구를 위한 규칙은 [AI.md](AI.md)와 [llms.txt](llms.txt)에서 확인합니다. React 컴포넌트를 사용하기 전에는 해당 컴포넌트의 공식 API와 사용 규칙을 먼저 확인합니다.
 
 ## 라이선스
 

package/dist/components/Button/README.md

@@ -0,0 +1,143 @@
+# Button — 개요, 사용 맥락, 공개 API
+
+이 문서는 `Button` 디렉토리의 기준 문서입니다. `Button`의 개요·사용 맥락·공개 API·접근성 계약을 기록합니다. Button을 사용하기 전에는 이 문서를 먼저 확인합니다.
+
+패키지 설치와 공개 경로는 루트 [README.md](../../../README.md)를, 소비처 AI의 공통 규칙은 루트 [AI.md](../../../AI.md)를 참고합니다. 루트 `AI.md`에는 컴포넌트별 정책을 중복해서 기록하지 않습니다.
+
+## 개요
+
+`Button`은 사용자가 즉시 실행할 수 있는 행동을 표현하는 인터랙티브 요소입니다. `Size`, `Layout`, `Role`, `Variant`, `State`로 버튼의 크기·구조·의미·위계·상태를 정의합니다.
+
+탐색 목적의 링크는 `neutral/link` 조합으로 표현하고, 상태 변경·폼 제출·명령 실행은 native `<button>`으로 표현합니다. `Button`은 현재 React 웹과 light theme만 지원합니다.
+
+## 사용 맥락
+
+### Size
+
+사용 가능한 크기는 `xs`, `sm`, `md`입니다. 사용할 공간과 행동의 중요도를 함께 고려합니다.
+
+| size | 사용 맥락 |
+| --- | --- |
+| `xs` | 조밀한 영역이나 보조 UI에 사용합니다. 작은 크기가 행동의 중요도를 대신 표현하지는 않습니다. |
+| `sm` | 일반적인 화면 액션에 사용합니다. |
+| `md` | 공간이 충분하거나 중요한 행동을 명확히 강조해야 할 때 사용합니다. |
+
+### Layout
+
+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` | CTA를 제외한 일반적인 보조 행동에 사용하며, CTA와 함께 제공할 때 보조 위계를 표현합니다. |
+| `neutral/outline` | 시각적 부담을 낮춘 대안이나 보조 행동에 사용합니다. `neutral/solid`과 같은 액션 그룹에서 함께 사용하지 않으며, `brand/outline`과 조합할 수 있습니다. |
+| `neutral/ghost` | 툴바·헤더·옵션 메뉴처럼 주변 UI와의 간섭을 줄여야 하는 보조 행동에 사용합니다. |
+| `neutral/link` | 다른 페이지·콘텐츠로 이동하거나 관련 정보를 확인하는 탐색성 행동에 사용합니다. 상태 변경이나 일반 CTA에는 사용하지 않습니다. `href`가 필요하며 `<a>`로 렌더링합니다. |
+| `critical/weak` | 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다. 위험을 분명히 전달하며 가능하면 확인 대화상자나 Alert Dialog와 함께 사용합니다. |
+
+지원하지 않는 Role·Variant 조합을 `className`, inline style, 임의 CSS로 우회하지 않습니다.
+
+### State
+
+| state | 의미 |
+| --- | --- |
+| enabled | 사용자가 실행할 수 있는 기본 상태입니다. |
+| hover | 포인터가 버튼 위에 있을 때의 상태이며 CSS `:hover`로 처리합니다. |
+| loading | 동작을 처리하는 중인 상태입니다. 라벨·아이콘 공간을 유지한 progress circle을 표시하고 상호작용을 차단합니다. |
+| disabled | 사용자가 실행할 수 없는 상태입니다. |
+
+`active`, `pressed`, `visited` 등 문서에 없는 상태는 추가하지 않습니다.
+
+## 공개 API contract
+
+다음 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 조합은 다음과 같습니다.
+
+| role | variant |
+| --- | --- |
+| `brand` | `solid`, `outline` |
+| `neutral` | `solid`, `weak`, `outline`, `ghost`, `link` |
+| `critical` | `weak` |
+
+### API reference
+
+| prop | 타입·규칙 |
+| --- | --- |
+| `children` | `ReactNode` label입니다. 렌더링 가능한 내용이 하나 이상 필요하며 `startIcon`·`endIcon`과 조합할 수 있습니다. |
+| `icon` | icon-only용 단일 custom `ReactElement`입니다. children이나 start/end icon과 함께 사용하지 않습니다. |
+| `iconName` | icon-only용 `ButtonIconName` lucide 이름입니다. |
+| `startIcon` / `endIcon` | label 앞·뒤의 단일 custom `ReactElement` 슬롯입니다. |
+| `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"`를 적용합니다. |
+| `className` | `string`이며 배치·컨테이너 보정에만 허용합니다. |
+| `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와 같은 슬롯에 함께 지정할 수 없습니다.
+
+이름으로 지정한 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`만 있으면 `iconOnly`이며 비어 있지 않은 `aria-label`이 필수입니다.
+
+빈 label·icon과 잘못된 슬롯 조합은 모든 환경에서 오류로 처리합니다. 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 시각을 우선합니다.
+
+## 접근성·상호작용
+
+- 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의 이름은 Button의 `aria-label`로 제공합니다.
+- loading progress circle은 `800ms linear infinite` 회전하며 `prefers-reduced-motion: reduce`에서는 정지합니다.
+
+## 문서와 검증
+
+Button의 공개 API와 사용 맥락은 이 문서와 설치된 패키지의 공개 `spec.json`을 함께 기준으로 사용합니다. 공개 Props·variant·상태를 변경할 때는 디자인 시스템 담당자의 검토와 적절한 버전 변경이 필요합니다.

package/dist/components/Button/spec.json

@@ -0,0 +1,299 @@
+{
+  "specVersion": 1,
+  "packageVersion": "0.0.3",
+  "name": "Button",
+  "purpose": "사용자가 즉시 실행할 수 있는 행동과 탐색을 표현하는 인터랙티브 요소입니다.",
+  "usageContexts": [
+    "상태 변경·폼 제출·명령 실행에는 native button branch를 사용합니다.",
+    "다른 페이지나 콘텐츠로 이동하는 탐색에는 neutral/link branch를 사용합니다.",
+    "brand는 화면에서 가장 중요한 행동을 강조할 때 사용합니다.",
+    "neutral은 일반적인 액션과 탐색에 사용합니다.",
+    "critical은 삭제·초기화처럼 되돌리기 어려운 행동에 사용합니다."
+  ],
+  "unsupportedContexts": [
+    "문서에 없는 role·variant·상태를 className이나 inline style로 우회하지 않습니다.",
+    "상태 변경이나 일반 CTA를 neutral/link로 표현하지 않습니다.",
+    "icon-only에서는 accessible name 없이 아이콘만 사용하지 않습니다."
+  ],
+  "api": {
+    "props": [
+      {
+        "name": "size",
+        "type": "ButtonSize",
+        "required": true,
+        "description": "버튼 크기입니다."
+      },
+      {
+        "name": "role",
+        "type": "ButtonRole",
+        "required": true,
+        "description": "시각적 역할입니다."
+      },
+      {
+        "name": "variant",
+        "type": "ButtonVariant",
+        "required": true,
+        "description": "role에 종속된 시각적 위계입니다."
+      },
+      {
+        "name": "type",
+        "type": "NativeButtonType",
+        "required": true,
+        "branch": "native button",
+        "description": "native button의 동작 유형입니다."
+      },
+      {
+        "name": "href",
+        "type": "string",
+        "required": true,
+        "branch": "neutral/link",
+        "description": "탐색 대상 주소입니다."
+      },
+      {
+        "name": "children",
+        "type": "ReactNode",
+        "required": false,
+        "description": "text label입니다."
+      },
+      {
+        "name": "icon",
+        "type": "ReactElement",
+        "required": false,
+        "description": "icon-only용 custom 아이콘입니다."
+      },
+      {
+        "name": "iconName",
+        "type": "ButtonIconName",
+        "required": false,
+        "description": "icon-only용 lucide 아이콘 이름입니다."
+      },
+      {
+        "name": "startIcon",
+        "type": "ReactElement",
+        "required": false,
+        "description": "label 앞의 custom 아이콘입니다."
+      },
+      {
+        "name": "startIconName",
+        "type": "ButtonIconName",
+        "required": false,
+        "description": "label 앞의 lucide 아이콘 이름입니다."
+      },
+      {
+        "name": "endIcon",
+        "type": "ReactElement",
+        "required": false,
+        "description": "label 뒤의 custom 아이콘입니다."
+      },
+      {
+        "name": "endIconName",
+        "type": "ButtonIconName",
+        "required": false,
+        "description": "label 뒤의 lucide 아이콘 이름입니다."
+      },
+      {
+        "name": "aria-label",
+        "type": "string",
+        "required": false,
+        "description": "accessible name입니다. icon-only에서는 필수입니다."
+      },
+      {
+        "name": "disabled",
+        "type": "boolean",
+        "required": false,
+        "description": "사용할 수 없는 상태입니다."
+      },
+      {
+        "name": "loading",
+        "type": "boolean",
+        "required": false,
+        "description": "처리 중 상태입니다."
+      },
+      {
+        "name": "className",
+        "type": "string",
+        "required": false,
+        "description": "배치·컨테이너 보정용 class입니다."
+      },
+      {
+        "name": "ref",
+        "type": "Ref<HTMLButtonElement | HTMLAnchorElement>",
+        "required": false,
+        "description": "native element ref입니다."
+      }
+    ],
+    "sizes": [
+      "xs",
+      "sm",
+      "md"
+    ],
+    "roleVariants": {
+      "brand": [
+        "solid",
+        "outline"
+      ],
+      "neutral": [
+        "solid",
+        "weak",
+        "outline",
+        "ghost",
+        "link"
+      ],
+      "critical": [
+        "weak"
+      ]
+    },
+    "states": [
+      "enabled",
+      "hover",
+      "disabled",
+      "loading",
+      "focus-visible"
+    ],
+    "slots": {
+      "textOnly": "children만 제공합니다.",
+      "iconFirst": "children과 startIcon 또는 startIconName을 제공합니다.",
+      "iconLast": "children과 endIcon 또는 endIconName을 제공합니다.",
+      "iconBoth": "children과 앞·뒤 아이콘을 모두 제공합니다.",
+      "iconOnly": "children 없이 icon 또는 iconName을 제공하고 비어 있지 않은 aria-label을 지정합니다."
+    },
+    "typeExports": [
+      "ButtonProps",
+      "ButtonComponent",
+      "ButtonIconName",
+      "ButtonLayout",
+      "ButtonRole",
+      "ButtonSize",
+      "ButtonVariant",
+      "NativeButtonType"
+    ]
+  },
+  "accessibility": {
+    "nativeButtonType": "native button branch에서는 type을 필수로 지정합니다.",
+    "linkHref": "neutral/link branch에서는 href를 필수로 지정합니다.",
+    "iconOnlyName": "icon-only layout에서는 비어 있지 않은 aria-label을 필수로 지정합니다.",
+    "disabledLink": "비활성 link는 href를 제거하고 aria-disabled와 tabIndex를 적용합니다.",
+    "loading": "loading 중에는 aria-busy를 적용하고 상호작용을 차단합니다.",
+    "focusVisible": "keyboard focus에는 승인된 focus ring을 표시합니다."
+  },
+  "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",
+      "reason": "공개 스타일 override를 제공하지 않습니다."
+    }
+  ]
+}

package/dist/components.css

@@ -309,22 +309,29 @@
 
 .eds-button__progressCircle {
   position: absolute;
-  inset: 0;
+  top: 50%;
+  left: 50%;
   display: none;
   align-items: center;
   justify-content: center;
+  transform: translate(-50%, -50%);
   pointer-events: none;
 }
 
 .eds-button__button[data-loading="true"] .eds-button__progressCircle {
   display: inline-flex;
-  animation: eds-button__eds-button-progress-spin 800ms linear infinite;
-  transform-origin: center;
-  will-change: transform;
 }
 
 .eds-button__progressCircle > svg {
   display: block;
+  width: 100%;
+  height: 100%;
+  transform-origin: center;
+}
+
+.eds-button__button[data-loading="true"] .eds-button__progressCircle > svg {
+  animation: eds-button__eds-button-progress-spin 800ms linear infinite;
+  will-change: transform;
 }
 
 .eds-button__progressTrack,
@@ -332,12 +339,12 @@
   stroke-width: var(--eds-button-size-xs-progressCircle-thickness);
 }
 
-.eds-button__button[data-size="xs"] .eds-button__progressCircle > svg {
+.eds-button__button[data-size="xs"] .eds-button__progressCircle {
   width: var(--eds-button-size-xs-progressCircle-size);
   height: var(--eds-button-size-xs-progressCircle-size);
 }
 
-.eds-button__button[data-size="sm"] .eds-button__progressCircle > svg {
+.eds-button__button[data-size="sm"] .eds-button__progressCircle {
   width: var(--eds-button-size-sm-progressCircle-size);
   height: var(--eds-button-size-sm-progressCircle-size);
 }
@@ -347,7 +354,7 @@
   stroke-width: var(--eds-button-size-sm-progressCircle-thickness);
 }
 
-.eds-button__button[data-size="md"] .eds-button__progressCircle > svg {
+.eds-button__button[data-size="md"] .eds-button__progressCircle {
   width: var(--eds-button-size-md-progressCircle-size);
   height: var(--eds-button-size-md-progressCircle-size);
 }
@@ -364,7 +371,7 @@
 }
 
 @media (prefers-reduced-motion: reduce) {
-  .eds-button__progressCircle {
+  .eds-button__progressCircle > svg {
     animation: none;
     will-change: auto;
   }

package/llms.txt

@@ -0,0 +1,11 @@
+# EVA Design System AI 문서 인덱스
+
+이 패키지는 React 웹용 EVA 디자인 시스템입니다. 다음 순서로 문서를 읽습니다.
+
+1. [AI 사용 규칙](./AI.md)을 읽고 공개 범위와 금지 사례를 확인합니다.
+2. [Button 개요·사용 맥락·API](./dist/components/Button/README.md)를 읽은 뒤 컴포넌트를 사용합니다.
+3. [Button 공개 manifest](./dist/components/Button/spec.json)에서 허용 조합과 접근성 계약을 확인합니다.
+4. [semantic token manifest](./dist/tokens.json)에서 사용 가능한 token 이름을 확인합니다.
+5. [npm 소비자 안내](./README.md)에서 설치와 CSS 진입점을 확인합니다.
+
+문서에 없는 API나 시각 상태를 추측하지 않습니다. 구현보다 문서와 TypeScript contract를 우선합니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrabrain/eds",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "description": "EVA services' shared React design system",
   "author": "SpectraBrain",
   "license": "UNLICENSED",
@@ -8,75 +8,48 @@
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
   "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "import": {
-        "types": "./dist/index.d.mts",
-        "default": "./dist/index.mjs"
-      },
-      "require": {
-        "types": "./dist/index.d.ts",
-        "default": "./dist/index.js"
-      },
-      "default": "./dist/index.js"
-    },
-    "./tokens": {
-      "import": {
-        "types": "./dist/tokens.d.mts",
-        "default": "./dist/tokens.mjs"
-      },
-      "require": {
-        "types": "./dist/tokens.d.ts",
-        "default": "./dist/tokens.js"
-      },
-      "default": "./dist/tokens.js"
-    },
-    "./tokens.css": "./dist/tokens.css",
-    "./styles.css": "./dist/styles.css",
-    "./fonts.css": "./dist/fonts.css",
-    "./tokens.json": "./dist/tokens.json",
-    "./package.json": "./package.json"
-  },
   "files": [
     "dist",
     "README.md",
     "AI.md",
+    "llms.txt",
     "NOTICE"
   ],
-  "engines": {
-    "node": ">=18"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": [
-    "./dist/tokens.css",
-    "./dist/styles.css",
-    "./dist/fonts.css"
-  ],
-  "peerDependencies": {
-    "react": ">=18.2 <20"
-  },
   "scripts": {
     "tokens:generate": "tsx scripts/build-tokens.ts",
     "components:generate": "tsx scripts/build-components.ts",
+    "component-manifest:generate": "tsx scripts/build-component-manifest.ts",
     "tokens:validate": "tsx scripts/build-tokens.ts --validate",
     "tokens:connectivity": "tsx scripts/check-token-connectivity.ts",
     "tokens:connectivity:strict": "npm run tokens:connectivity -- --strict",
-    "typecheck": "npm run tokens:generate && npm run components:generate && tsc --noEmit",
     "library:build": "tsup",
     "fonts:build": "tsx scripts/build-font-assets.ts",
-    "tokens:build": "npm run typecheck && npm run library:build && npm run fonts:build && npm run public-boundary:check",
+    "tokens:build": "npm run typecheck && npm run library:build && npm run component-manifest:generate && npm run fonts:build && npm run public-boundary:check",
     "public-boundary:check": "tsx scripts/check-public-boundary.ts",
-    "storybook": "npm run tokens:generate && npm run components:generate && npm run fonts:build && storybook dev -p 6006",
+    "storybook": "npm run tokens:generate && npm run components:generate && npm run component-manifest:generate && npm run fonts:build && node scripts/storybook-dev.mjs",
     "storybook:build": "npm run tokens:build && storybook build",
-    "storybook:test": "npm run tokens:generate && npm run components:generate && npm run fonts:build && vitest --config vitest.storybook.config.ts run",
+    "storybook:test": "npm run tokens:generate && npm run components:generate && npm run component-manifest:generate && npm run fonts:build && vitest --config vitest.storybook.config.ts run",
+    "typecheck": "npm run tokens:generate && npm run components:generate && npm run component-manifest:generate && tsc --noEmit",
     "build": "npm run tokens:build",
     "package:check": "node scripts/check-package-exports.mjs",
     "prepack": "npm run tokens:build",
     "test:unit": "vitest run",
     "test": "npm run tokens:build && npm run test:unit"
   },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": [
+    "./dist/tokens.css",
+    "./dist/styles.css",
+    "./dist/fonts.css"
+  ],
+  "peerDependencies": {
+    "react": ">=18.2 <20"
+  },
   "devDependencies": {
     "@changesets/cli": "^2.29.7",
     "@storybook/addon-a11y": "^10.6.0",
@@ -105,5 +78,37 @@
   },
   "dependencies": {
     "lucide-react": "1.45.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "default": "./dist/index.js"
+    },
+    "./tokens": {
+      "import": {
+        "types": "./dist/tokens.d.mts",
+        "default": "./dist/tokens.mjs"
+      },
+      "require": {
+        "types": "./dist/tokens.d.ts",
+        "default": "./dist/tokens.js"
+      },
+      "default": "./dist/tokens.js"
+    },
+    "./tokens.css": "./dist/tokens.css",
+    "./styles.css": "./dist/styles.css",
+    "./fonts.css": "./dist/fonts.css",
+    "./tokens.json": "./dist/tokens.json",
+    "./components/Button/README.md": "./dist/components/Button/README.md",
+    "./components/Button/spec.json": "./dist/components/Button/spec.json",
+    "./llms.txt": "./llms.txt",
+    "./package.json": "./package.json"
   }
 }