@uniai-fe/uds-primitives 0.3.60 → 0.4.1

package/README.md

@@ -47,6 +47,212 @@ export default function Page() {
 }
 ```
 
+## 제공 도구 목록
+
+- `Alternate.EmptyData`
+- `Alternate.LoadingDefault`
+- `Alternate.LoadingIcon`
+- `Alternate.Text`
+- `AlternateEmptyDataProps`
+- `AlternateLoadingDefaultProps`
+- `AlternateLoadingIconProps`
+- `AlternateTextProps`
+- `Badge`
+- `BadgeProps`
+- `Chip.Default`
+- `Chip.ClickableStyle`
+- `Chip.InputStyle`
+- `Chip.Label`
+- `Chip.List`
+- `ChipProps`
+- `ChipListRootProps`
+- `ChipListItemData`
+- `Calendar.Root`
+- `Calendar.Container`
+- `Calendar.Header`
+- `Calendar.Body`
+- `Calendar.Footer`
+- `Calendar.Core`
+- `Calendar.Icon`
+- `CalendarValue`
+- `CalendarRootProps`
+- `CalendarContainerProps`
+- `CalendarGridProps`
+- `CalendarDatePickerProps`
+- `Carousel.Provider`
+- `Carousel.Container`
+- `Carousel.Control`
+- `Carousel.Track`
+- `Carousel.Button.Base`
+- `Carousel.Button.Prev`
+- `Carousel.Button.Next`
+- `useCarousel`
+- `useCarouselProviderController`
+- `CarouselProviderProps`
+- `CarouselTrackProps`
+- `CarouselContainerProps`
+- `CarouselControlProps`
+- `CarouselPrevButtonProps`
+- `CarouselNextButtonProps`
+- `DrawerRoot`
+- `DrawerTrigger`
+- `DrawerPortal`
+- `DrawerOverlay`
+- `DrawerContent`
+- `DrawerHeader`
+- `DrawerBody`
+- `DrawerFooter`
+- `DrawerTitle`
+- `DrawerDescription`
+- `DrawerClose`
+- `DrawerRootProps`
+- `DrawerTriggerProps`
+- `DrawerContentProps`
+- `useDrawerDrag`
+- `Form.Provider`
+- `Form.Field.Container`
+- `Form.Field.Header`
+- `Form.Field.Body`
+- `Form.Field.Footer`
+- `Form.Field.Template`
+- `FormFieldTemplateProps`
+- `FormFieldContainerProps`
+- `FormFieldHeaderProps`
+- `FormFieldFooterProps`
+- `FormFieldWidth`
+- `FormFieldState`
+- `getFormFieldWidthAttr`
+- `getFormFieldWidthValue`
+- `InfoBox`
+- `InfoBoxIcon`
+- `InfoBoxProps`
+- `InfoBoxState`
+- `BottomNavigation`
+- `BottomNavigationProps`
+- `NavigationItem`
+- `NavigationItemKey`
+- `NavigationHrefItem`
+- `NavigationActionItem`
+- `NavigationSitemapNode`
+- `NavigationSitemapCollection`
+- `NavigationSitemapOptions`
+- `composeNavigationClassName`
+- `isHrefNavigationItem`
+- `Pagination`
+- `PaginationCarousel`
+- `PaginationCount`
+- `PaginationProps`
+- `PaginationCarouselProps`
+- `PaginationCountProps`
+- `PaginationCountSize`
+- `PaginationCarouselPriority`
+- `normalizePaginationState`
+- `createPaginationPages`
+- `composePaginationClassName`
+- `Slot.Base`
+- `Slot.Text`
+- `SlotComponentProps`
+- `SlotTextProps`
+- `TabRoot`
+- `TabList`
+- `TabTrigger`
+- `TabContent`
+- `TabRootProps`
+- `TabListProps`
+- `TabTriggerProps`
+- `TabContentProps`
+- `TabVariant`
+- `TabScale`
+- `TabContext`
+- `useTabContext`
+- `SegmentedControl`
+- `SegmentedControlLabel`
+- `SegmentedControlProps`
+- `SegmentedControlOption`
+- `SegmentedControlValue`
+- `Divider`
+- `DividerProps`
+- `DividerDirection`
+- `scrollbar` (현재 public export 없음)
+- `spinner` (현재 public export 없음)
+- `Table.Root`
+- `Table.Head`
+- `Table.Body`
+- `Table.Foot`
+- `Table.Row`
+- `Table.Th`
+- `Table.Td`
+- `Table.Cell`
+- `Table.Text`
+- `Table.Container`
+- `Table.Colgroup`
+- `Table.Col`
+- `TableColumnData`
+- `TableRootProps`
+- `TableContainerProps`
+- `TableCellProps`
+- `Button.Default`
+- `Button.Text`
+- `Button.Rounded`
+- `Button.Label`
+- `ButtonProps`
+- `TextButtonProps`
+- `RoundButtonProps`
+- `Input.Base`
+- `Input.TextArea`
+- `Input.Text.Password`
+- `Input.Text.Phone`
+- `Input.Text.Email`
+- `Input.Text.Search`
+- `Input.Text.AuthCode`
+- `Input.Date.Template`
+- `Input.Address.Template`
+- `Input.Address.Button`
+- `Input.File.UploadButton`
+- `Input.File.UploadedChip`
+- `Input.File.List.*`
+- `useInputFile`
+- `useInputFileContext`
+- `Select.Default`
+- `Select.Multiple`
+- `Select.Container`
+- `Select.Trigger.Base`
+- `Select.Selected.Base`
+- `Select.Selected.Multiple`
+- `SelectDropdownOption`
+- `SelectMultipleTag`
+- `Dropdown.Root`
+- `Dropdown.Trigger`
+- `Dropdown.Container`
+- `Dropdown.Menu.Item`
+- `Dropdown.Menu.List`
+- `Dropdown.Template`
+- `DropdownTemplateItem`
+- `DropdownTemplateChangePayload`
+- `Radio`
+- `RadioField`
+- `RadioCard`
+- `RadioCardGroup`
+- `RadioProps`
+- `RadioFieldProps`
+- `Checkbox`
+- `CheckboxField`
+- `CheckboxProps`
+- `CheckboxFieldProps`
+- `CheckboxSize`
+- `Tooltip.Root`
+- `Tooltip.Trigger`
+- `Tooltip.Message`
+- `Tooltip.Text`
+- `Tooltip.Template`
+- `TooltipMessageProps`
+- `PopOver.Root`
+- `PopOver.Trigger`
+- `PopOver.Content`
+- `PopOverRootProps`
+- `PopOverTriggerProps`
+- `PopOverContentProps`
+
 ### Link/Anchor로 사용하기
 
 ```tsx
@@ -103,11 +309,11 @@ function Templates() {
 - 템플릿별 클래스를 추가로 노출한다: `.button-template-text`, `.button-template-text-size-*`, `.button-template-round`, `.button-template-round-size-*`.
 - 스토리북 `primitives/Button` Story에서 solid/outlined/텍스트/라운드 4가지 카테고리를 한 번에 확인할 수 있다.
 
-### SlotComponent (폴리모픽 as 래퍼)
+### Slot (폴리모픽 as 래퍼)
 
-- `Button.Default`는 `SlotComponent`를 통해 `as` prop으로 전달된 요소(예: `Link`, `a`, `button`)에 공통 속성/`ref`를 안전하게 전달한다.
+- `Button.Default`는 `Slot.Base`를 통해 `as` prop으로 전달된 요소(예: `Link`, `a`, `button`)에 공통 속성/`ref`를 안전하게 전달한다.
 - `SlotComponentProps<C>`는 React가 허용하는 모든 native props + `data-*` 속성을 그대로 포함하고, `as/children/className`만 재정의한다.
-- 필요 시 `import { SlotComponent } from "@uniai-fe/uds-primitives";`로 직접 사용해 카드/배너 등의 래퍼를 구현할 수 있다.
+- 필요 시 `import { Slot } from "@uniai-fe/uds-primitives";` 후 `Slot.Base`, `Slot.Text`를 직접 사용해 카드/배너 래퍼나 텍스트 슬롯을 구현할 수 있다.
 - 자세한 도입 배경과 API는 `docs/CONTEXT-SLOT.md`에서 확인할 수 있다.
 
 ### 최근 업데이트

package/dist/styles.css

@@ -614,6 +614,8 @@
   --select-secondary-color-text-readonly: var(
   --select-primary-color-text-readonly
   );
+  --select-secondary-color-border-disabled: var(--color-label-disabled);
+  --select-secondary-color-border-readonly: transparent;
   --select-secondary-color-placeholder: var(--color-label-alternative);
   --select-secondary-color-placeholder-disabled: var(--color-label-disabled);
   --select-secondary-color-placeholder-readonly: var(
@@ -623,9 +625,11 @@
   --select-color-surface-secondary-hover: var(--color-surface-static-cool-gray);
   --select-color-surface-secondary-active: var(--color-surface-standard);
   --select-color-surface-secondary-disabled: var(--color-surface-neutral);
+  --select-color-surface-secondary-readonly: transparent;
   --select-icon-color-default: var(--color-cool-gray-75);
   --select-icon-color-focused: var(--color-cool-gray-20);
   --select-icon-color-disabled: var(--color-cool-gray-85);
+  --select-icon-color-readonly: transparent;
   /* Multi select chip */
   --select-multiple-chip-gap: var(--spacing-gap-2);
   --select-multiple-tag-label-gap: var(--spacing-gap-1);
@@ -3872,7 +3876,11 @@ figure.chip {
   --select-flex: 1 1 0%;
 }
 
-.select[data-width=full],
+.select:where([data-width=full]) {
+  --select-width: 100%;
+  --select-flex: 0 0 100%;
+}
+
 .select-block {
   --select-width: 100%;
   --select-flex: 0 0 100%;
@@ -3983,12 +3991,13 @@ figure.chip {
   border-color: var(--select-primary-color-border-disabled);
   background-color: var(--select-primary-color-surface-disabled);
   cursor: default;
-  --select-icon-fill: var(--select-icon-color-disabled);
+  --select-icon-fill: var(--select-icon-color-readonly);
 }
 .select-button:where([data-priority=secondary]):where([data-readonly=true]) {
-  border-color: transparent;
-  background-color: var(--select-color-surface-secondary-disabled);
+  border-color: var(--select-secondary-color-border-readonly);
+  background-color: var(--select-color-surface-secondary-readonly);
   cursor: default;
+  --select-icon-fill: var(--select-icon-color-readonly);
 }
 .select-button:where([data-priority=secondary]):where([data-readonly=true])::after {
   background-color: var(--select-color-border-secondary-disabled);
@@ -3998,7 +4007,7 @@ figure.chip {
   border-color: var(--select-table-border-readonly-color);
   background-color: var(--select-table-surface-readonly-color);
   cursor: not-allowed;
-  --select-icon-fill: var(--select-table-icon-color-disabled);
+  --select-icon-fill: var(--select-table-icon-color-readonly);
 }
 .select-button:where(:not([data-priority=secondary])):where([data-state=disabled]), .select-button:where(:not([data-priority=secondary])):disabled {
   border-color: var(--select-primary-color-border-disabled);
@@ -4007,7 +4016,7 @@ figure.chip {
   --select-icon-fill: var(--select-icon-color-disabled);
 }
 .select-button:where([data-priority=secondary]):where([data-state=disabled]), .select-button:where([data-priority=secondary]):disabled {
-  border-color: transparent;
+  border-color: var(--select-secondary-color-border-disabled);
   background-color: var(--select-color-surface-secondary-disabled);
 }
 .select-button:where([data-priority=secondary]):where([data-state=disabled])::after, .select-button:where([data-priority=secondary]):disabled::after {
@@ -4074,6 +4083,11 @@ figure.chip {
   color: var(--select-secondary-color-text-readonly);
 }
 
+.select-input-label-readonly {
+  width: auto;
+  max-width: 100%;
+}
+
 .select-button:where(:not([data-state=disabled])) .select-value[data-has-value=true] .select-input-label {
   color: var(--select-color-text-value);
   caret-color: var(--select-color-text-value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.3.60",
+  "version": "0.4.1",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -15,7 +15,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.32.0",
+  "packageManager": "pnpm@10.32.1",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"
@@ -85,13 +85,13 @@
     "@radix-ui/react-tooltip": "^1.2.8",
     "@radix-ui/react-visually-hidden": "^1.2.4",
     "clsx": "^2.1.1",
-    "dayjs": "^1.11.19",
+    "dayjs": "^1.11.20",
     "react-daum-postcode": "^4.0.0"
   },
   "devDependencies": {
-    "@mantine/core": "^8.3.16",
-    "@mantine/dates": "^8.3.16",
-    "@mantine/hooks": "^8.3.16",
+    "@mantine/core": "^8.3.18",
+    "@mantine/dates": "^8.3.18",
+    "@mantine/hooks": "^8.3.18",
     "@svgr/webpack": "^8.1.0",
     "@types/node": "^24.10.2",
     "@types/react": "^19.2.14",
@@ -104,7 +104,7 @@
     "eslint": "^9.39.2",
     "prettier": "^3.8.1",
     "react-hook-form": "^7.71.2",
-    "sass": "^1.97.3",
+    "sass": "^1.98.0",
     "typescript": "~5.9.3"
   }
 }

package/src/components/alternate/index.tsx

@@ -1,4 +1,10 @@
 /**
- * alternate 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Alternate; empty/loading fallback 유닛 카테고리 배럴
+ * @desc
+ * - `Alternate.EmptyData`: 빈 데이터 안내 레이아웃이다.
+ * - `Alternate.LoadingDefault`: 로딩 아이콘과 안내 문구를 함께 렌더링한다.
+ * - `Alternate.LoadingIcon`: 단독 스피너 아이콘이다.
+ * - `Alternate.Text`: fallback 문구 스타일 슬롯이다.
  */
 export { default as Alternate } from "./markup";
+export type * from "./types";

package/src/components/alternate/markup/Label.tsx

@@ -1,9 +1,14 @@
 import { Slot } from "../../slot";
+import type { AlternateTextProps } from "../types";
 
-export default function AlternateText({
-  children,
-}: {
-  children: React.ReactNode;
-}) {
+/**
+ * Alternate Text; fallback 문구 슬롯
+ * @component
+ * @param {AlternateTextProps} props
+ * @param {React.ReactNode} props.children 렌더링할 문구 콘텐츠다.
+ * @example
+ * <Alternate.Text>데이터가 없습니다.</Alternate.Text>
+ */
+export default function AlternateText({ children }: AlternateTextProps) {
   return <Slot.Text className="alternate-text">{children}</Slot.Text>;
 }

package/src/components/alternate/markup/empty/Data.tsx

@@ -2,20 +2,23 @@
 
 import { clsx } from "clsx";
 import AlternateText from "../Label";
+import type { AlternateEmptyDataProps } from "../../types";
 
 /**
- * 차트; 데이터 없는 경우 대체 컴포넌트
+ * Alternate EmptyData; 빈 데이터 안내 레이아웃
  * @component
+ * @param {AlternateEmptyDataProps} props
+ * @param {string} [props.className] 루트 className override다.
+ * @param {"vertical" | "horizontal"} [props.direction="vertical"] 아이콘/문구 배치 방향이다.
+ * @param {React.ReactNode} [props.children] 안내 문구 콘텐츠다. 비어 있으면 기본 문구를 사용한다.
+ * @example
+ * <Alternate.EmptyData direction="horizontal">데이터가 없습니다.</Alternate.EmptyData>
  */
 export default function AlternateEmptyData({
   className,
   direction = "vertical",
   children: text,
-}: Partial<{
-  className: string;
-  direction: "vertical" | "horizontal";
-  children: React.ReactNode;
-}>) {
+}: AlternateEmptyDataProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
 

package/src/components/alternate/markup/index.tsx

@@ -3,6 +3,14 @@ import AlternateText from "./Label";
 import AlternateLoadingDefault from "./loading/Default";
 import AlternateLoadingIcon from "./loading/Icon";
 
+/**
+ * Alternate; empty/loading fallback namespace
+ * @desc
+ * - `Alternate.EmptyData`: 빈 데이터 안내 레이아웃이다.
+ * - `Alternate.LoadingDefault`: 로딩 안내 레이아웃이다.
+ * - `Alternate.LoadingIcon`: 단독 스피너 아이콘이다.
+ * - `Alternate.Text`: 안내 문구 슬롯이다.
+ */
 const Alternate = {
   EmptyData: AlternateEmptyData,
   LoadingDefault: AlternateLoadingDefault,

package/src/components/alternate/markup/loading/Default.tsx

@@ -3,25 +3,29 @@
 import { clsx } from "clsx";
 import AlternateLoadingIcon from "./Icon";
 import AlternateText from "../Label";
+import type { AlternateLoadingDefaultProps } from "../../types";
 
 /**
- * 데이터 로딩중 컴포넌트
+ * Alternate LoadingDefault; 로딩 안내 레이아웃
  * @component
+ * @param {AlternateLoadingDefaultProps} props
+ * @param {"vertical" | "horizontal"} [props.direction="vertical"] 아이콘/문구 배치 방향이다.
+ * @param {React.ReactNode} [props.children] 안내 문구 콘텐츠다. 비어 있으면 기본 문구를 사용한다.
+ * @example
+ * <Alternate.LoadingDefault>데이터를 불러오는 중입니다.</Alternate.LoadingDefault>
  */
 export default function AlternateLoadingDefault({
   direction = "vertical",
   children: text,
-}: Partial<{
-  direction: "vertical" | "horizontal";
-  children: React.ReactNode;
-}>) {
+}: AlternateLoadingDefaultProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
 
   return (
     <div className={clsx("alternate loading", directionClass)}>
       <AlternateLoadingIcon direction={direction} />
-      {["string", "undefined"].includes(typeof text) ? (
+      {/* string/number만 Slot.Text로 감싸고, 그 외 ReactNode는 그대로 렌더링한다. */}
+      {["string", "number", "undefined"].includes(typeof text) ? (
         <AlternateText>{text || "데이터를 불러오는 중입니다."}</AlternateText>
       ) : (
         text

package/src/components/alternate/markup/loading/Icon.tsx

@@ -4,14 +4,21 @@ import { clsx } from "clsx";
 import SpinnerSmallIcon from "../../img/spinner-small-24x24.svg";
 import SpinnerMediumIcon from "../../img/spinner-medium-36x36.svg";
 import SpinnerLargeIcon from "../../img/spinner-large-52x52.svg";
+import type { AlternateLoadingIconProps } from "../../types";
 
+/**
+ * Alternate LoadingIcon; 단독 스피너 아이콘
+ * @component
+ * @param {AlternateLoadingIconProps} props
+ * @param {"small" | "medium" | "large"} [props.size="small"] 로딩 아이콘 스케일이다.
+ * @param {"vertical" | "horizontal"} [props.direction] 부모 레이아웃 방향 클래스 동기화용 값이다.
+ * @example
+ * <Alternate.LoadingIcon size="medium" />
+ */
 export default function AlternateLoadingIcon({
   size = "small",
   direction,
-}: {
-  size?: "small" | "medium" | "large";
-  direction?: "vertical" | "horizontal";
-}) {
+}: AlternateLoadingIconProps) {
   const directionClass =
     direction === "horizontal" ? "is-horizontal" : "is-vertical";
   const sizeClass = size ? `is-${size}` : undefined;

package/src/components/alternate/types/index.ts

@@ -1,4 +1,77 @@
+import type { ReactNode } from "react";
+
 /**
- * TODO(alternate): variant/slot 타입 정의를 작성한다.
+ * Alternate Direction; fallback 레이아웃 방향 축
+ * @typedef {"vertical" | "horizontal"} AlternateDirection
  */
-export {};
+export type AlternateDirection = "vertical" | "horizontal";
+
+/**
+ * Alternate Loading Icon Size; 로딩 아이콘 스케일 축
+ * @typedef {"small" | "medium" | "large"} AlternateLoadingIconSize
+ */
+export type AlternateLoadingIconSize = "small" | "medium" | "large";
+
+/**
+ * Alternate Text Props; fallback 문구 슬롯 props
+ * @property {ReactNode} children 렌더링할 문구 콘텐츠다.
+ */
+export interface AlternateTextProps {
+  /**
+   * 렌더링할 문구 콘텐츠다.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Alternate Empty Data Props; 빈 데이터 안내 레이아웃 props
+ * @property {string} [className] 루트 className override다.
+ * @property {"vertical" | "horizontal"} [direction] 아이콘/문구 배치 방향이다.
+ * @property {ReactNode} [children] 안내 문구 콘텐츠다.
+ */
+export interface AlternateEmptyDataProps {
+  /**
+   * 루트 className override다.
+   */
+  className?: string;
+  /**
+   * 아이콘/문구 배치 방향이다.
+   */
+  direction?: AlternateDirection;
+  /**
+   * 안내 문구 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Alternate Loading Default Props; 로딩 안내 레이아웃 props
+ * @property {"vertical" | "horizontal"} [direction] 아이콘/문구 배치 방향이다.
+ * @property {ReactNode} [children] 안내 문구 콘텐츠다.
+ */
+export interface AlternateLoadingDefaultProps {
+  /**
+   * 아이콘/문구 배치 방향이다.
+   */
+  direction?: AlternateDirection;
+  /**
+   * 안내 문구 콘텐츠다.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Alternate Loading Icon Props; 단독 스피너 아이콘 props
+ * @property {"small" | "medium" | "large"} [size] 로딩 아이콘 스케일이다.
+ * @property {"vertical" | "horizontal"} [direction] 부모 레이아웃 방향 클래스 동기화용 값이다.
+ */
+export interface AlternateLoadingIconProps {
+  /**
+   * 로딩 아이콘 스케일이다.
+   */
+  size?: AlternateLoadingIconSize;
+  /**
+   * 부모 레이아웃 방향 클래스 동기화용 값이다.
+   */
+  direction?: AlternateDirection;
+}

package/src/components/badge/index.tsx

@@ -1,5 +1,8 @@
 /**
- * badge 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Badge; status/info label 렌더링 카테고리 배럴
+ * @desc
+ * - `Badge`: size/style/intent/tone 축을 렌더링하는 단일 leaf 컴포넌트다.
+ * - `BadgeProps`: badge public props 계약이다.
  */
 import "./index.scss";
 

package/src/components/badge/markup/Badge.tsx

@@ -4,17 +4,19 @@ import { composeBadgeClassName } from "../utils";
 import { Slot } from "../../slot";
 
 /**
- * Badge 컴포넌트; size/style/intent 축을 data attribute로 노출한다.
+ * Badge; status/info label 렌더링 leaf 컴포넌트
  * @component
  * @param {BadgeProps} props
- * @param {"xsmall" | "small"} [props.size="xsmall"] 토큰 size.
- * @param {"fill" | "outlined" | "dot"} [props.style="fill"] 시각 스타일.
+ * @param {"xsmall" | "small"} [props.size="xsmall"] 토큰 size 축이다.
+ * @param {"fill" | "outlined" | "dot"} [props.style="fill"] 시각 스타일 축이다.
  * @param {"primary" | "secondary" | "tertiary" | "gray" | "green" | "yellow" | "orange" | "red"} [props.intent="primary"]
- *  fill/outlined 스타일에서 사용되는 intent.
- * @param {"primary" | "feedback"} [props.tone="primary"] dot 스타일에 사용되는 tone.
- * @param {React.ReactNode} [props.children] 라벨 텍스트. dot 스타일에서 생략하면 점만 렌더.
- * @param {string} [props.className] figure className.
- * @param {React.CSSProperties} [props.inlineStyle] figure inline style.
+ *  fill/outlined 스타일에서 사용되는 intent 축이다.
+ * @param {"primary" | "feedback"} [props.tone="primary"] dot 스타일 전용 tone 축이다.
+ * @param {React.ReactNode} [props.children] 라벨 텍스트다. dot 스타일에서 생략하면 점만 렌더링한다.
+ * @param {string} [props.className] figure root className override다.
+ * @param {React.CSSProperties} [props.inlineStyle] figure root inline style이다.
+ * @example
+ * <Badge style="fill" intent="primary">승인됨</Badge>
  */
 const Badge = forwardRef<HTMLElementTagNameMap["figure"], BadgeProps>(
   (

package/src/components/badge/types/index.ts

@@ -1,4 +1,4 @@
-import type { ComponentPropsWithoutRef, ReactNode } from "react";
+import type { CSSProperties, ComponentPropsWithoutRef, ReactNode } from "react";
 
 export const BADGE_SIZES = ["xsmall", "small"] as const;
 export const BADGE_STYLES = ["fill", "outlined", "dot"] as const;
@@ -21,6 +21,15 @@ export type BadgeTone = (typeof BADGE_TONES)[number];
 
 type NativeFigureProps = Omit<ComponentPropsWithoutRef<"figure">, "style">;
 
+/**
+ * Badge Props; status/info label badge public props
+ * @property {ReactNode} [children] 표시할 라벨이다. 생략하면 dot만 렌더링한다.
+ * @property {"xsmall" | "small"} [size] Figma size 축이다.
+ * @property {"fill" | "outlined" | "dot"} [style] badge 시각 스타일 축이다.
+ * @property {"primary" | "secondary" | "tertiary" | "gray" | "green" | "yellow" | "orange" | "red"} [intent] fill/outlined 변형의 색상 의도다.
+ * @property {"primary" | "feedback"} [tone] dot 변형 전용 tone 축이다.
+ * @property {CSSProperties} [inlineStyle] 원본 figure 요소에 적용할 inline style이다.
+ */
 export interface BadgeProps extends Omit<NativeFigureProps, "children"> {
   /**
    * 표시할 라벨. 생략하면 dot 스타일만 렌더링된다.
@@ -45,11 +54,26 @@ export interface BadgeProps extends Omit<NativeFigureProps, "children"> {
   /**
    * 원본 figure 요소에 적용할 인라인 스타일.
    */
-  inlineStyle?: ComponentPropsWithoutRef<"figure">["style"];
+  inlineStyle?: CSSProperties;
 }
 
+/**
+ * Badge ClassName Options; badge root className 조합 입력값
+ * @property {"xsmall" | "small"} size badge size 축이다.
+ * @property {"fill" | "outlined" | "dot"} style badge style 축이다.
+ * @property {string} [className] 외부 className override다.
+ */
 export interface BadgeClassNameOptions {
+  /**
+   * badge size 축이다.
+   */
   size: BadgeSize;
+  /**
+   * badge style 축이다.
+   */
   style: BadgeStyle;
+  /**
+   * 외부 className override다.
+   */
   className?: string;
 }

package/src/components/button/index.tsx

@@ -1,5 +1,10 @@
 /**
- * button 카테고리 배럴 placeholder: 실제 구현은 markup/ 하위에 추가한다.
+ * Button; namespace 배럴 export
+ * @desc
+ * - `Button.Default`: fill/priority/size 축 기반 기본 버튼
+ * - `Button.Text`: text action 템플릿
+ * - `Button.Rounded`: round icon action 템플릿
+ * - `Button.Label`: button-label className 고정 래퍼
  */
 import "./index.scss";