@spectrabrain/eds 0.1.0 → 0.1.1

package/dist/index.d.mts

@@ -6,7 +6,7 @@ type ButtonIconName = "ArrowLeft" | "ArrowRight" | "Check" | "ChevronDown" | "Ch
 
 /** 버튼 크기입니다. */
 type ButtonSize = "xs" | "sm" | "md";
-/** 행동의 의미입니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
+/** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
 type ButtonRole = "brand" | "neutral" | "critical";
 /** 시각 위계입니다. role마다 허용 조합이 다르며 ButtonProps가 조합을 강제합니다. link는 neutral 탐색 전용입니다. */
 type ButtonVariant = "solid" | "weak" | "outline" | "ghost" | "link";
@@ -14,27 +14,32 @@ type ButtonVariant = "solid" | "weak" | "outline" | "ghost" | "link";
 type ButtonLayout = "textOnly" | "iconFirst" | "iconLast" | "iconBoth" | "iconOnly";
 /** native button branch의 type입니다. 폼 제출은 "submit", 그 밖의 행동은 "button"입니다. */
 type NativeButtonType = "button" | "submit" | "reset";
-/**
- * 허용되는 role·variant 조합입니다. 화면의 핵심 행동(저장·생성·확인)은 brand/solid, 일반 주요 행동(검색·조회)은 neutral/solid,
- * 취소·닫기·수정은 neutral/outline, 부담이 낮은 반복 행동(초기화·갱신)은 neutral/weak, 되돌리기 어려운 삭제·초기화는 critical/weak입니다.
- */
+/** 허용되는 role·variant 조합입니다. 행동별 선택은 QUICKSTART.md의 Button 조합표를 따릅니다. */
 type ButtonVisualProps = {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "brand";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "solid" | "outline";
 } | {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "neutral";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "solid" | "weak" | "outline" | "ghost";
 } | {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "critical";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "weak";
 };
 /** neutral/link 조합입니다. 페이지나 콘텐츠로 이동하는 탐색에만 사용하며 상태 변경이나 일반 CTA에는 쓰지 않습니다. */
 type LinkVisualProps = {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "neutral";
+    /** 페이지·콘텐츠 이동 전용 variant이며 href가 필수입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "link";
 };
 type ReactIconSlot = {
-    /** label 앞의 custom ReactElement 슬롯입니다. startIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추고 stroke 두께는 lucide 기본값 2에 맞춥니다. */
+    /** label 앞의 custom ReactElement 슬롯입니다. startIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추며, 이름으로 지정한 아이콘과 같아 보이려면 lucide 기본 stroke를 그대로 둡니다. */
     readonly startIcon?: ReactElement;
     readonly startIconName?: never;
 } | {
@@ -43,7 +48,7 @@ type ReactIconSlot = {
     readonly startIconName?: ButtonIconName;
 };
 type ReactEndIconSlot = {
-    /** label 뒤의 custom ReactElement 슬롯입니다. endIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추고 stroke 두께는 lucide 기본값 2에 맞춥니다. */
+    /** label 뒤의 custom ReactElement 슬롯입니다. endIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추며, 이름으로 지정한 아이콘과 같아 보이려면 lucide 기본 stroke를 그대로 둡니다. */
     readonly endIcon?: ReactElement;
     readonly endIconName?: never;
 } | {
@@ -52,11 +57,11 @@ type ReactEndIconSlot = {
     readonly endIconName?: ButtonIconName;
 };
 type TextSlotProps = {
-    /** 버튼 label입니다. icon-only 버튼은 children 대신 icon 또는 iconName을 지정합니다. */
+    /** 버튼 label이며 한 줄로 표시합니다. 렌더링할 내용이 없으면(빈 문자열·공백·null) render 오류이므로, icon-only는 children 대신 icon 또는 iconName을 씁니다. */
     readonly children: ReactNode;
     readonly icon?: never;
     readonly iconName?: never;
-    /** 선택적 accessible name입니다. 지정하면 비어 있지 않아야 합니다. */
+    /** 선택적 accessible name입니다. 공백뿐인 문자열은 render 오류이므로, 값이 없을 수 있으면 `""`로 대체하지 말고 prop을 생략합니다. */
     readonly "aria-label"?: string;
 } & ReactIconSlot & ReactEndIconSlot;
 type IconOnlySlotProps = {
@@ -65,7 +70,7 @@ type IconOnlySlotProps = {
     readonly startIconName?: never;
     readonly endIcon?: never;
     readonly endIconName?: never;
-    /** icon-only 버튼의 accessible name입니다. 접근성 이름을 제공할 때 비어 있지 않은 값을 지정합니다. */
+    /** icon-only 버튼의 accessible name입니다. 아이콘은 aria-hidden이므로 항상 비어 있지 않은 값(또는 aria-labelledby)을 지정합니다. 공백뿐인 문자열은 render 오류입니다. */
     readonly "aria-label"?: string;
 } & ({
     /** icon-only용 custom ReactElement입니다. children·start/end 슬롯과 함께 쓰지 않습니다. */
@@ -85,7 +90,7 @@ type SharedProps = {
     readonly disabled?: boolean;
     /** 비동기 처리 중 상태입니다. aria-busy를 적용하고 상호작용을 막으며 label·아이콘 공간과 accessible name을 유지합니다. "저장 중…" 같은 별도 문구 대신 사용합니다. */
     readonly loading?: boolean;
-    /** 배치·컨테이너 보정에만 사용합니다. 문서에 없는 색·상태·variant를 className으로 우회하지 않습니다. */
+    /** 바깥 배치(margin·정렬·grid 위치)에만 사용합니다. 문서에 없는 색·상태·variant를 className으로 우회하지 않습니다. */
     readonly className?: string;
     /** 지원하지 않습니다. 공개 스타일 override를 제공하지 않습니다. */
     readonly style?: never;
@@ -95,15 +100,12 @@ type NativeButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children
     readonly type: NativeButtonType;
 };
 type NativeLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "className" | "href" | "role" | "style" | "type" | "aria-label" | "aria-busy"> & {
-    /** 이동할 주소입니다. neutral/link branch에서 필수이며, 상태 변경이나 일반 CTA를 link로 표현하지 않습니다. */
+    /** 이동할 주소입니다. neutral/link branch에서 필수이며, 상태 변경이나 일반 CTA를 link로 표현하지 않습니다. 공백뿐인 주소는 render 오류이므로 주소가 없을 수 있으면 Button을 렌더링하지 않거나 native button branch를 씁니다. */
     readonly href: string;
 };
 type NativeButtonBranchProps = SharedProps & NativeButtonProps & ButtonVisualProps & SlotProps;
 type LinkBranchProps = SharedProps & NativeLinkProps & LinkVisualProps & SlotProps;
-/**
- * Button의 공개 props입니다. native button branch(type 필수)와 neutral/link branch(href 필수)의 union입니다.
- * 허용 조합과 접근성 계약의 기계 판독 원천은 @spectrabrain/eds/components/Button/spec.json입니다.
- */
+/** Button의 공개 props입니다. native button branch(type 필수)와 neutral/link branch(href 필수)의 union입니다. */
 type ButtonProps = NativeButtonBranchProps | LinkBranchProps;
 /** Button의 호출 시그니처입니다. ref는 branch에 따라 HTMLButtonElement 또는 HTMLAnchorElement입니다. */
 interface ButtonComponent {
@@ -118,8 +120,8 @@ interface ButtonComponent {
     }): ReactElement | null;
 }
 /**
- * EDS Button입니다. EDS에 같은 역할의 컴포넌트가 있으면 자체 구현보다 먼저 사용합니다.
- * 사용 맥락과 role·variant 선택 기준은 @spectrabrain/eds/components/Button/README.md, 기계 판독 계약은 spec.json을 참고합니다.
+ * EDS Button입니다. role·variant를 고를 때 package root의 dist/components/Button/README.md를,
+ * 허용 조합·아이콘 이름·접근성 동작을 확인할 때 dist/components/Button/spec.json을 읽습니다.
  */
 declare const Button: ButtonComponent;
 

package/dist/index.d.ts

@@ -6,7 +6,7 @@ type ButtonIconName = "ArrowLeft" | "ArrowRight" | "Check" | "ChevronDown" | "Ch
 
 /** 버튼 크기입니다. */
 type ButtonSize = "xs" | "sm" | "md";
-/** 행동의 의미입니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
+/** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
 type ButtonRole = "brand" | "neutral" | "critical";
 /** 시각 위계입니다. role마다 허용 조합이 다르며 ButtonProps가 조합을 강제합니다. link는 neutral 탐색 전용입니다. */
 type ButtonVariant = "solid" | "weak" | "outline" | "ghost" | "link";
@@ -14,27 +14,32 @@ type ButtonVariant = "solid" | "weak" | "outline" | "ghost" | "link";
 type ButtonLayout = "textOnly" | "iconFirst" | "iconLast" | "iconBoth" | "iconOnly";
 /** native button branch의 type입니다. 폼 제출은 "submit", 그 밖의 행동은 "button"입니다. */
 type NativeButtonType = "button" | "submit" | "reset";
-/**
- * 허용되는 role·variant 조합입니다. 화면의 핵심 행동(저장·생성·확인)은 brand/solid, 일반 주요 행동(검색·조회)은 neutral/solid,
- * 취소·닫기·수정은 neutral/outline, 부담이 낮은 반복 행동(초기화·갱신)은 neutral/weak, 되돌리기 어려운 삭제·초기화는 critical/weak입니다.
- */
+/** 허용되는 role·variant 조합입니다. 행동별 선택은 QUICKSTART.md의 Button 조합표를 따릅니다. */
 type ButtonVisualProps = {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "brand";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "solid" | "outline";
 } | {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "neutral";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "solid" | "weak" | "outline" | "ghost";
 } | {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "critical";
+    /** role 안의 시각 위계입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "weak";
 };
 /** neutral/link 조합입니다. 페이지나 콘텐츠로 이동하는 탐색에만 사용하며 상태 변경이나 일반 CTA에는 쓰지 않습니다. */
 type LinkVisualProps = {
+    /** 행동의 의미를 나타내는 시각 prop입니다. ARIA role이 아니며 DOM에 전달되지 않습니다. brand는 화면의 핵심 행동, neutral은 일반·보조 행동, critical은 되돌리기 어려운 행동입니다. */
     readonly role: "neutral";
+    /** 페이지·콘텐츠 이동 전용 variant이며 href가 필수입니다. 행동별 조합은 QUICKSTART.md의 Button 조합표를 따릅니다. */
     readonly variant: "link";
 };
 type ReactIconSlot = {
-    /** label 앞의 custom ReactElement 슬롯입니다. startIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추고 stroke 두께는 lucide 기본값 2에 맞춥니다. */
+    /** label 앞의 custom ReactElement 슬롯입니다. startIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추며, 이름으로 지정한 아이콘과 같아 보이려면 lucide 기본 stroke를 그대로 둡니다. */
     readonly startIcon?: ReactElement;
     readonly startIconName?: never;
 } | {
@@ -43,7 +48,7 @@ type ReactIconSlot = {
     readonly startIconName?: ButtonIconName;
 };
 type ReactEndIconSlot = {
-    /** label 뒤의 custom ReactElement 슬롯입니다. endIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추고 stroke 두께는 lucide 기본값 2에 맞춥니다. */
+    /** label 뒤의 custom ReactElement 슬롯입니다. endIconName과 함께 쓰지 않습니다. 크기는 Button이 맞추며, 이름으로 지정한 아이콘과 같아 보이려면 lucide 기본 stroke를 그대로 둡니다. */
     readonly endIcon?: ReactElement;
     readonly endIconName?: never;
 } | {
@@ -52,11 +57,11 @@ type ReactEndIconSlot = {
     readonly endIconName?: ButtonIconName;
 };
 type TextSlotProps = {
-    /** 버튼 label입니다. icon-only 버튼은 children 대신 icon 또는 iconName을 지정합니다. */
+    /** 버튼 label이며 한 줄로 표시합니다. 렌더링할 내용이 없으면(빈 문자열·공백·null) render 오류이므로, icon-only는 children 대신 icon 또는 iconName을 씁니다. */
     readonly children: ReactNode;
     readonly icon?: never;
     readonly iconName?: never;
-    /** 선택적 accessible name입니다. 지정하면 비어 있지 않아야 합니다. */
+    /** 선택적 accessible name입니다. 공백뿐인 문자열은 render 오류이므로, 값이 없을 수 있으면 `""`로 대체하지 말고 prop을 생략합니다. */
     readonly "aria-label"?: string;
 } & ReactIconSlot & ReactEndIconSlot;
 type IconOnlySlotProps = {
@@ -65,7 +70,7 @@ type IconOnlySlotProps = {
     readonly startIconName?: never;
     readonly endIcon?: never;
     readonly endIconName?: never;
-    /** icon-only 버튼의 accessible name입니다. 접근성 이름을 제공할 때 비어 있지 않은 값을 지정합니다. */
+    /** icon-only 버튼의 accessible name입니다. 아이콘은 aria-hidden이므로 항상 비어 있지 않은 값(또는 aria-labelledby)을 지정합니다. 공백뿐인 문자열은 render 오류입니다. */
     readonly "aria-label"?: string;
 } & ({
     /** icon-only용 custom ReactElement입니다. children·start/end 슬롯과 함께 쓰지 않습니다. */
@@ -85,7 +90,7 @@ type SharedProps = {
     readonly disabled?: boolean;
     /** 비동기 처리 중 상태입니다. aria-busy를 적용하고 상호작용을 막으며 label·아이콘 공간과 accessible name을 유지합니다. "저장 중…" 같은 별도 문구 대신 사용합니다. */
     readonly loading?: boolean;
-    /** 배치·컨테이너 보정에만 사용합니다. 문서에 없는 색·상태·variant를 className으로 우회하지 않습니다. */
+    /** 바깥 배치(margin·정렬·grid 위치)에만 사용합니다. 문서에 없는 색·상태·variant를 className으로 우회하지 않습니다. */
     readonly className?: string;
     /** 지원하지 않습니다. 공개 스타일 override를 제공하지 않습니다. */
     readonly style?: never;
@@ -95,15 +100,12 @@ type NativeButtonProps = Omit<ButtonHTMLAttributes<HTMLButtonElement>, "children
     readonly type: NativeButtonType;
 };
 type NativeLinkProps = Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "children" | "className" | "href" | "role" | "style" | "type" | "aria-label" | "aria-busy"> & {
-    /** 이동할 주소입니다. neutral/link branch에서 필수이며, 상태 변경이나 일반 CTA를 link로 표현하지 않습니다. */
+    /** 이동할 주소입니다. neutral/link branch에서 필수이며, 상태 변경이나 일반 CTA를 link로 표현하지 않습니다. 공백뿐인 주소는 render 오류이므로 주소가 없을 수 있으면 Button을 렌더링하지 않거나 native button branch를 씁니다. */
     readonly href: string;
 };
 type NativeButtonBranchProps = SharedProps & NativeButtonProps & ButtonVisualProps & SlotProps;
 type LinkBranchProps = SharedProps & NativeLinkProps & LinkVisualProps & SlotProps;
-/**
- * Button의 공개 props입니다. native button branch(type 필수)와 neutral/link branch(href 필수)의 union입니다.
- * 허용 조합과 접근성 계약의 기계 판독 원천은 @spectrabrain/eds/components/Button/spec.json입니다.
- */
+/** Button의 공개 props입니다. native button branch(type 필수)와 neutral/link branch(href 필수)의 union입니다. */
 type ButtonProps = NativeButtonBranchProps | LinkBranchProps;
 /** Button의 호출 시그니처입니다. ref는 branch에 따라 HTMLButtonElement 또는 HTMLAnchorElement입니다. */
 interface ButtonComponent {
@@ -118,8 +120,8 @@ interface ButtonComponent {
     }): ReactElement | null;
 }
 /**
- * EDS Button입니다. EDS에 같은 역할의 컴포넌트가 있으면 자체 구현보다 먼저 사용합니다.
- * 사용 맥락과 role·variant 선택 기준은 @spectrabrain/eds/components/Button/README.md, 기계 판독 계약은 spec.json을 참고합니다.
+ * EDS Button입니다. role·variant를 고를 때 package root의 dist/components/Button/README.md를,
+ * 허용 조합·아이콘 이름·접근성 동작을 확인할 때 dist/components/Button/spec.json을 읽습니다.
  */
 declare const Button: ButtonComponent;
 

package/dist/tokens.d.mts

@@ -5,12 +5,15 @@ type SemanticTokenCssReference = `var(${SemanticTokenCssVariable})`;
 interface SemanticToken {
     readonly name: SemanticTokenName;
     readonly type: SemanticTokenType;
+    /** 빌드 시 해석된 참고용 값입니다. 스타일에는 cssVariable 또는 cssVar()를 씁니다. */
     readonly value: unknown;
     readonly cssVariable: string;
 }
 type SemanticTokenMap = Readonly<Record<SemanticTokenName, SemanticToken>>;
+/** 공개 token manifest입니다. 이름 목록은 tokenNames, CSS 참조는 cssVar()입니다. */
 declare const tokens: SemanticTokenMap;
 declare const tokenNames: readonly SemanticTokenName[];
+/** 공개 token 이름을 var(--eds-…) 참조로 바꿉니다. 이름은 SemanticTokenName 리터럴로 전달하며, tokenNames에 없는 문자열은 런타임 오류입니다. */
 declare function cssVar(name: SemanticTokenName): SemanticTokenCssReference;
 
 export { type SemanticToken, type SemanticTokenCssReference, type SemanticTokenCssVariable, type SemanticTokenMap, type SemanticTokenName, type SemanticTokenType, cssVar, tokenNames, tokens };

package/dist/tokens.d.ts

@@ -5,12 +5,15 @@ type SemanticTokenCssReference = `var(${SemanticTokenCssVariable})`;
 interface SemanticToken {
     readonly name: SemanticTokenName;
     readonly type: SemanticTokenType;
+    /** 빌드 시 해석된 참고용 값입니다. 스타일에는 cssVariable 또는 cssVar()를 씁니다. */
     readonly value: unknown;
     readonly cssVariable: string;
 }
 type SemanticTokenMap = Readonly<Record<SemanticTokenName, SemanticToken>>;
+/** 공개 token manifest입니다. 이름 목록은 tokenNames, CSS 참조는 cssVar()입니다. */
 declare const tokens: SemanticTokenMap;
 declare const tokenNames: readonly SemanticTokenName[];
+/** 공개 token 이름을 var(--eds-…) 참조로 바꿉니다. 이름은 SemanticTokenName 리터럴로 전달하며, tokenNames에 없는 문자열은 런타임 오류입니다. */
 declare function cssVar(name: SemanticTokenName): SemanticTokenCssReference;
 
 export { type SemanticToken, type SemanticTokenCssReference, type SemanticTokenCssVariable, type SemanticTokenMap, type SemanticTokenName, type SemanticTokenType, cssVar, tokenNames, tokens };

package/llms.txt

@@ -1,19 +1,25 @@
-# EVA Design System AI 문서 인덱스
+# EVA Design System (@spectrabrain/eds)
 
-이 패키지는 React 웹용 EVA 디자인 시스템입니다. 소비처 AI는 `require.resolve("@spectrabrain/eds/package.json")`로 설치된 package root를 찾은 뒤 다음 순서로 문서를 읽습니다. 아래 경로는 모두 package root 기준 파일 경로입니다. 필수 읽기는 1번 하나이며 나머지는 조건에 해당할 때만 읽습니다. 읽기 순서와 조건의 기계용 원천은 `AI_CONTEXT.json`의 `readOrder`이며, 이 문서와 다르면 `AI_CONTEXT.json`을 따릅니다.
+> React 웹용 EVA 디자인 시스템 패키지입니다. 소비처 AI는 package root(`require.resolve("@spectrabrain/eds/package.json")`의 디렉터리)의 `QUICKSTART.md` 하나를 먼저 읽고, 나머지는 아래 조건에 해당할 때만 읽습니다. 같은 목록의 기계용 원천은 `AI_CONTEXT.json`의 `readOrder`입니다.
 
-1. `QUICKSTART.md`: 규칙, 명령, 더 읽을 문서의 조건입니다. 필수입니다.
-2. `CONSUMER_AGENT.md`: setup·sync·doctor를 다룰 때 managed block, 패키지 매니저별 `init`, font 정책, 보고 형식을 확인합니다.
-3. `AI.md`: 공개 범위와 금지 사례를 확인할 때 읽습니다.
-4. `TOKEN_CONTEXT.md`: token을 직접 고를 때 semantic color·typography의 역할을 확인합니다.
-5. `TAILWIND_V4.md`: Tailwind CSS v4에서 token을 사용할 때 읽습니다.
-6. `dist/tokens.json`: token, CSS variable, Tailwind alias를 고를 때 설치된 버전의 공개 token 이름을 확인합니다.
-7. `dist/components/Button/README.md`: Button을 사용할 때 개요·사용 맥락·API를 읽습니다.
-8. `dist/components/Button/spec.json`: Button API나 접근성 동작을 구현할 때 허용 조합, 접근성 계약, `api.iconNames` 아이콘 목록을 확인합니다.
-9. `CHANGELOG.md`: EDS 버전을 올린 뒤 바뀐 내용을 확인할 때 읽습니다.
+EDS 내부 소스로 동작을 추론하지 않고 공개 문서와 TypeScript contract를 기준으로 합니다. 링크는 모두 package root 기준 경로입니다.
 
-설치 방법과 CSS 진입점은 `README.md`에서 확인합니다. `dist/` 아래 파일은 `@spectrabrain/eds/tokens.json`, `@spectrabrain/eds/components/Button/spec.json`처럼 `dist/`를 뗀 export 경로로도 읽을 수 있습니다.
+## 필수
 
-npm 10·11에서는 EDS `postinstall`이 소비처 `package.json`에 `sync:eds`·`eds:doctor` script를 등록하고, 그 밖의 환경에서는 `npx @spectrabrain/eds init`이 같은 script를 등록합니다. 설치·업데이트 후 소비처는 `npm run sync:eds`를 명시적으로 실행해 Tailwind root CSS import, Tailwind alias, `AGENTS.md` managed block을 갱신하며, `npm run eds:doctor`로 동기화 상태를 점검합니다. EDS text style은 `@spectrabrain/eds/fonts.css`가 선언하는 font family를 참조하므로 `styles.css` 또는 `fonts.css` import를 생략하지 않습니다.
+- [QUICKSTART.md](./QUICKSTART.md): UI 작업 규칙, 완료 기준과 doctor 실패 시 복구 순서, 명령(`npm run sync:eds`, `npm run eds:doctor`), 조건부 문서 목록입니다.
 
-문서에 없는 API나 시각 상태를 추측하지 않습니다. 구현보다 공개 문서와 TypeScript contract를 우선합니다.
+## 조건부
+
+- [CONSUMER_AGENT.md](./CONSUMER_AGENT.md): 소비처 `AGENTS.md`에 `<!-- EDS:BEGIN -->` block이 없거나, sync·doctor가 exit 2이거나 sync 뒤에도 doctor가 exit 1이거나, EDS 버전을 올렸거나, 사용자가 프로토타입을 EVA 구조로 정리하라고 요청했을 때(`eds align`) 읽습니다.
+- [TOKEN_CONTEXT.md](./TOKEN_CONTEXT.md): EDS 컴포넌트 prop 밖에서 색상·typography token을 지정하거나 바꿀 때 읽습니다. Tailwind 없이 CSS variable이나 `cssVar()`로 쓰는 경우도 포함합니다.
+- [TAILWIND_V4.md](./TAILWIND_V4.md): Tailwind CSS v4 adapter나 root CSS 배선을 설정하거나 고칠 때 읽습니다.
+- [AI.md](./AI.md): 요청이 dark theme, 생성된 class 밖의 Tailwind utility, `AI_CONTEXT.json` `components`에 없는 컴포넌트를 요구할 때 읽습니다.
+- [FRONTEND_CONVENTIONS.md](./FRONTEND_CONVENTIONS.md): `.eds/align/PLAN.md`가 있거나(`eds align` 진행 중), 소비처 `AGENTS.md`가 구조·라이브러리·코드 패턴 변경에 이 문서를 가리킬 때 읽습니다.
+- [dist/components/Button/README.md](./dist/components/Button/README.md): Button을 쓸 때 사용 맥락, role·variant 선택, prop, 접근성, 목록 밖 아이콘 규칙을 읽습니다.
+- [dist/components/Button/spec.json](./dist/components/Button/spec.json): `api.iconNames`의 아이콘 이름을 확인하거나 도구가 기계용 계약을 읽을 때 씁니다.
+- [dist/tokens.json](./dist/tokens.json): 도구·스크립트가 기계용 token manifest를 읽거나, Tailwind 없이 쓸 `var(--eds-*)` 이름을 확인할 때 씁니다. class 이름은 `src/styles/eds-tokens.css`에 있습니다.
+- [CHANGELOG.md](./CHANGELOG.md): EDS 버전을 올렸을 때(설치된 버전이 `AGENTS.md`의 `EDS:VERSION` 줄보다 높을 때) 읽습니다.
+
+## Optional
+
+- [README.md](./README.md): 사람을 위한 설치 안내와 공개 경로 표입니다.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@spectrabrain/eds",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "EVA services' shared React design system",
   "author": "SpectraBrain",
   "license": "UNLICENSED",
@@ -25,6 +25,7 @@
     "llms.txt",
     "TAILWIND_V4.md",
     "QUICKSTART.md",
+    "FRONTEND_CONVENTIONS.md",
     "CHANGELOG.md",
     "consumer-postinstall.mjs",
     "consumer",
@@ -140,6 +141,7 @@
     "./llms.txt": "./llms.txt",
     "./TAILWIND_V4.md": "./TAILWIND_V4.md",
     "./QUICKSTART.md": "./QUICKSTART.md",
+    "./FRONTEND_CONVENTIONS.md": "./FRONTEND_CONVENTIONS.md",
     "./package.json": "./package.json"
   }
 }