@bigtablet/design-system 3.6.0 → 3.8.0

package/LICENSE

@@ -0,0 +1,53 @@
+# Bigtablet Inc. Open Source License
+
+## Table of Contents / 목차
+- [English Version](#english-version)
+- [한국어 버전](#한국어-버전)
+
+---
+
+## English Version
+
+This license is issued by **Bigtablet Inc.** (hereinafter referred to as the "Copyright Holder") and is intended to provide the source code to developers, researchers, and other users (hereinafter referred to as "Users").  
+Any use that contradicts the purposes stated below is strictly prohibited.
+
+### Terms and Conditions
+
+1. All copyrights for the source code and files opened within this GitHub organization belong to the Copyright Holder.  
+2. All open-source materials are, by default, permitted for **non-commercial use only**.  
+3. Any User who uses, modifies, processes, redistributes, or conducts research with part or all of the open source must clearly indicate the source by referencing the link to the original GitHub repository.  
+4. Commercial use of the open source without explicit or implicit permission from the Copyright Holder is strictly prohibited. For inquiries regarding commercial use, please contact the email address provided in the profile.  
+5. Users are obligated to report any issues, errors, or security vulnerabilities discovered or encountered while using the open source to the Copyright Holder, and are prohibited from exploiting or disclosing them to external parties. 
+6. If unauthorized commercial use is detected, the Copyright Holder reserves the right to take legal action.  
+7. By cloning, forking, or otherwise copying and using a repository containing this open source, the User is deemed to have fully understood and agreed to all the terms of this license.  
+8. This license shall take effect from **September 9, 2025**, and shall have legal force and effect from that date.  
+9. For any additional inquiries, please contact the email address listed in the profile.  
+
+### Disclaimer
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, AND NON-INFRINGEMENT.  
+IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+---
+
+## 한국어 버전
+
+본 라이선스는 **Bigtablet Inc.**(이하 “저작권자”)에서 발행하였으며, 개발자, 연구자 등 (이하 “사용자”)에게 소스코드를 제공하기 위한 목적으로 공개합니다.  
+아래에 기재된 목적에 반하는 사용은 엄격히 금지됩니다.
+
+### 조항
+
+1. 본 GitHub 조직에 공개된 모든 소스코드와 파일에 대한 저작권은 저작권자에게 있습니다.  
+2. 모든 오픈소스는 원칙적으로 **비상업적 목적**으로만 이용할 수 있습니다.  
+3. 모든 사용자는 오픈소스의 일부 또는 전체를 사용, 수정, 가공, 재배포, 연구할 경우 반드시 해당 GitHub 저장소 링크를 통해 출처를 명시해야 합니다.  
+4. 저작권자의 명시적 또는 묵시적 허가 없이 오픈소스를 상업적 목적으로 이용하는 것을 금합니다. 상업적 이용 문의는 프로필에 기재된 이메일로 연락하시기 바랍니다.  
+5. 사용자는 오픈소스를 이용하는 중 발견되거나 발생한 문제, 오류, 보안 취약점을 저작권자에게 보고할 의무가 있으며 이를 악용하거나 외부로 공유하는 것을 금합니다.  
+6. 무단으로 상업적 이용이 적발될 경우 저작권자는 법적 조치를 취할 권리를 가집니다.  
+7. 오픈소스가 포함된 저장소를 clone, fork 또는 기타 방법으로 복제하여 이용하는 경우, 사용자는 본 라이선스의 모든 조항을 충분히 숙지하였으며 이에 동의한 것으로 간주됩니다.  
+8. 본 라이선스는 **2025년 9월 9일**부터 발효되며, 해당 시점부터 법적 효력을 가집니다.  
+9. 기타 문의 사항은 프로필에 기재된 이메일로 연락하시기 바랍니다.  
+
+### 면책 조항
+
+이 소프트웨어는 **“있는 그대로(As-Is)”** 제공되며, 상품성, 특정 목적에의 적합성, 비침해를 포함하되 이에 국한되지 않는 어떠한 형태의 명시적 또는 묵시적 보증도 하지 않습니다.  
+저작권자 또는 기여자는 계약, 불법행위, 기타 어떠한 법적 근거에 의한 것이든 간에, 본 소프트웨어 또는 이를 사용하거나 다른 방식으로 이용함으로 인해 발생하는 모든 청구, 손해, 기타 법적 책임에 대해 책임을 지지 않습니다.

package/README.md

@@ -45,7 +45,7 @@ A complete React + TypeScript design system maintained by Bigtablet for internal
 ## What's inside
 
 - **40+ components** across forms, display, feedback, navigation, overlay, and layout<br />
-- **11 token domains** - colors, typography, spacing, motion, radius, elevation, and more - exposed as SCSS variables and CSS custom properties<br />
+- **13 token domains** - colors, typography, spacing, motion, radius, elevation, and more - exposed as SCSS variables and CSS custom properties (plus a SCSS-only `layout` domain)<br />
 - **Light + dark mode** out of the box. `[data-theme="dark"]` or `prefers-color-scheme`, no theme provider required (but available via `ThemeProvider` for runtime toggling)<br />
 - **Vanilla JS bundle** for non-React backends - Thymeleaf, JSP, PHP, Django<br />
 - **Accessibility tested** with axe-core in CI · keyboard nav · ARIA throughout
@@ -58,7 +58,7 @@ A complete React + TypeScript design system maintained by Bigtablet for internal
 pnpm add @bigtablet/design-system react@^19 react-dom@^19 lucide-react
 ```
 
-Requires React 19 + lucide-react ≥ 0.552. Compatible with Next.js 13+.
+Requires React 19 + lucide-react ≥ 0.552. Next.js is an optional peer dependency at `>=15`.
 
 <details>
 <summary><b>One-line setup</b> - auto-detect package manager + framework</summary>
@@ -102,12 +102,13 @@ showAlert({ title: "Delete?", showCancel: true, onConfirm: ... });
 ## Components
 
 <table>
-<tr><td><b>Forms</b></td><td>Button · IconButton · TextField · Textarea · Checkbox · Radio · Toggle · Dropdown · DatePicker · FileInput · OTPInput</td></tr>
+<tr><td><b>Forms</b></td><td>Button · IconButton · TextField · Textarea · Checkbox · Radio · RadioGroup · Toggle · Dropdown · DatePicker · FileInput · ImageCropper · OtpInput</td></tr>
 <tr><td><b>Display</b></td><td>Card · MediaCard · Hero · Avatar · Badge · Chip · ListItem · Table · Divider · Icon · Accordion</td></tr>
 <tr><td><b>Feedback</b></td><td>Alert · Toast · Spinner · TopLoading · LinearProgress · Skeleton · EmptyState · ErrorState</td></tr>
 <tr><td><b>Navigation</b></td><td>Tabs · Sidebar · BottomNav · NavBar · Breadcrumb · Menu · Pagination</td></tr>
-<tr><td><b>Overlay</b></td><td>Modal · Tooltip</td></tr>
+<tr><td><b>Overlay</b></td><td>Modal · Drawer · Tooltip · Popover</td></tr>
 <tr><td><b>Layout</b></td><td>Container · Section · Stack · Grid</td></tr>
+<tr><td><b>System</b></td><td>ThemeProvider</td></tr>
 </table>
 
 →&nbsp;Full API · [`docs/COMPONENTS.md`](./docs/COMPONENTS.md)
@@ -117,7 +118,7 @@ showAlert({ title: "Delete?", showCancel: true, onConfirm: ... });
 ## Design tokens
 
 ```scss
-@use "src/styles/token" as token;
+@use "@bigtablet/design-system/scss/token" as token;
 
 .card {
   background: token.$color_bg_solid;
@@ -129,16 +130,18 @@ showAlert({ title: "Delete?", showCancel: true, onConfirm: ... });
 ```
 
 ```css
+/* from @bigtablet/design-system/style.css */
 .card {
   background: var(--bt-color-bg-solid);
   color: var(--bt-color-text-heading);
-  padding: var(--bt-spacing-16);
-  border-radius: var(--bt-radius-md);
+  border: 1px solid var(--bt-color-border-default);
   box-shadow: var(--bt-elevation-level1);
 }
 ```
 
-`colors`&nbsp;·&nbsp;`spacing`&nbsp;·&nbsp;`typography`&nbsp;·&nbsp;`radius`&nbsp;·&nbsp;`elevation`&nbsp;·&nbsp;`motion`&nbsp;·&nbsp;`z-index`&nbsp;·&nbsp;`breakpoints`&nbsp;·&nbsp;`border-width`&nbsp;·&nbsp;`opacity`&nbsp;·&nbsp;`a11y`
+> The React entry's `style.css` only emits `--bt-color-*`, `--bt-elevation-*`, `--bt-focus-*`, `--bt-sidebar-*`, and `--bt-bottom-nav-*`. Spacing, radius, and typography are **SCSS-only** on this entry - use `scss/token` for them (`--bt-spacing-*` / `--bt-radius-*` exist only in the [Vanilla bundle](./docs/VANILLA.md)).
+
+`colors`&nbsp;·&nbsp;`spacing`&nbsp;·&nbsp;`typography`&nbsp;·&nbsp;`radius`&nbsp;·&nbsp;`elevation`&nbsp;·&nbsp;`motion`&nbsp;·&nbsp;`z-index`&nbsp;·&nbsp;`breakpoints`&nbsp;·&nbsp;`border-width`&nbsp;·&nbsp;`opacity`&nbsp;·&nbsp;`skeleton`&nbsp;·&nbsp;`icon`&nbsp;·&nbsp;`a11y`&nbsp;·&nbsp;`layout`<sup>SCSS only</sup>
 
 <br />
 
@@ -150,7 +153,7 @@ For server-rendered apps (Thymeleaf, JSP, PHP, Django):
 <link rel="stylesheet" href="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.css">
 <script src="https://unpkg.com/@bigtablet/design-system/dist/vanilla/bigtablet.min.js"></script>
 
-<button class="bt-button bt-button--md bt-button--primary">Primary</button>
+<button class="bt-button bt-button--md bt-button--filled">Filled</button>
 ```
 
 →&nbsp;Full guide · [`docs/VANILLA.md`](./docs/VANILLA.md)

package/dist/index.css

@@ -743,6 +743,11 @@
   align-items: center;
   color: var(--bt-color-text-caption);
 }
+@media (prefers-reduced-motion: reduce) {
+  .breadcrumb_link {
+    transition: none;
+  }
+}
 
 /* src/ui/navigation/menu/style.scss */
 @keyframes skeleton_loading {
@@ -1559,38 +1564,18 @@
   display: inline-flex;
 }
 .popover_position {
-  position: absolute;
   z-index: 1000;
   width: max-content;
 }
-.popover_position.popover_placement_top {
-  bottom: calc(100% + 8px);
-  left: 50%;
-  transform: translateX(-50%);
-}
-.popover_position.popover_placement_bottom {
-  top: calc(100% + 8px);
-  left: 50%;
-  transform: translateX(-50%);
-}
-.popover_position.popover_placement_left {
-  right: calc(100% + 8px);
-  top: 50%;
-  transform: translateY(-50%);
-}
-.popover_position.popover_placement_right {
-  left: calc(100% + 8px);
-  top: 50%;
-  transform: translateY(-50%);
-}
 .popover {
   background: var(--bt-color-bg-solid);
   border: 1px solid var(--bt-color-border-default);
   border-radius: 12px;
   box-shadow: var(--bt-elevation-level2);
   padding: 16px;
-  min-width: 200px;
-  max-width: 320px;
+  box-sizing: border-box;
+  min-width: min(200px, 100%);
+  max-width: min(320px, 100%);
   color: var(--bt-color-text-body);
   font-size: 14px;
   font-weight: 400;
@@ -1632,31 +1617,10 @@
   vertical-align: middle;
 }
 .tooltip_position {
-  position: absolute;
   z-index: 1000;
   display: block;
   width: max-content;
 }
-.tooltip_position.tooltip_placement_top {
-  bottom: calc(100% + 6px);
-  left: 50%;
-  transform: translateX(-50%);
-}
-.tooltip_position.tooltip_placement_bottom {
-  top: calc(100% + 6px);
-  left: 50%;
-  transform: translateX(-50%);
-}
-.tooltip_position.tooltip_placement_left {
-  right: calc(100% + 6px);
-  top: 50%;
-  transform: translateY(-50%);
-}
-.tooltip_position.tooltip_placement_right {
-  left: calc(100% + 6px);
-  top: 50%;
-  transform: translateY(-50%);
-}
 .tooltip {
   display: block;
   background: var(--bt-color-accent-strong);
@@ -2038,6 +2002,14 @@
   width: 18px;
   height: 18px;
 }
+@media (prefers-reduced-motion: reduce) {
+  .chip,
+  .chip::before,
+  .chip_content::before,
+  .chip_icon {
+    transition: none;
+  }
+}
 
 /* src/ui/display/divider/style.scss */
 @keyframes skeleton_loading {
@@ -2611,6 +2583,11 @@
   opacity: 0.38;
   pointer-events: none;
 }
+@media (prefers-reduced-motion: reduce) {
+  .list_item_interactive .list_item_state_layer::before {
+    transition: none;
+  }
+}
 
 /* src/ui/display/media-card/style.scss */
 @keyframes skeleton_loading {
@@ -3588,7 +3565,7 @@
   left: 0;
   height: 3px;
   border-radius: 0 0 0 12px;
-  animation: toast_progress var(--toast-duration, 3000ms) linear forwards;
+  animation: toast_progress var(--toast-duration, 3s) linear forwards;
 }
 .toast_progress_success {
   background: var(--bt-color-status-success);
@@ -4423,6 +4400,11 @@
 .otp_input_supporting_error {
   color: var(--bt-color-status-error-on-surface);
 }
+@media (prefers-reduced-motion: reduce) {
+  .otp_input_box {
+    transition: none;
+  }
+}
 
 /* src/ui/forms/radio-group/style.scss */
 @keyframes skeleton_loading {
@@ -4936,6 +4918,14 @@
 .text_field_disabled .text_field_helper {
   opacity: 0.38;
 }
+@media (prefers-reduced-motion: reduce) {
+  .text_field_label,
+  .text_field_container,
+  .text_field_clear,
+  .text_field_helper {
+    transition: none;
+  }
+}
 
 /* src/ui/forms/toggle/style.scss */
 @keyframes skeleton_loading {
@@ -5274,6 +5264,12 @@
   letter-spacing: 0px;
   color: var(--bt-color-text-caption);
 }
+@media (prefers-reduced-motion: reduce) {
+  .pagination_item,
+  .pagination_page_button {
+    transition: none;
+  }
+}
 
 /* src/ui/overlay/drawer/style.scss */
 @keyframes skeleton_loading {
@@ -5500,6 +5496,11 @@
 .modal_footer_start {
   justify-content: flex-start;
 }
+@media (prefers-reduced-motion: reduce) {
+  .modal_close {
+    transition: none;
+  }
+}
 
 /* src/ui/layout/container/style.scss */
 @keyframes skeleton_loading {

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as React$1 from 'react';
-import { Ref } from 'react';
+import { HTMLAttributes, Ref } from 'react';
 import * as _react_spring_web from '@react-spring/web';
 import { LucideProps, LucideIcon } from 'lucide-react';
 export { LucideIcon, LucideProps } from 'lucide-react';
@@ -368,7 +368,7 @@ interface MenuProps {
  * @example
  * ```tsx
  * <Menu
- *   trigger={<IconButton icon={<MoreIcon />} />}
+ *   trigger={<IconButton icon={<MoreIcon />} aria-label="더보기" />}
  *   items={[
  *     { key: "edit", label: "편집", onSelect: handleEdit },
  *     { key: "del", label: "삭제", onSelect: handleDel, destructive: true },
@@ -395,6 +395,15 @@ interface NavBarLocaleConfig {
     onChange?: (next: string) => void;
     /** 표시 라벨 - 기본은 옵션의 label, 미지정 시 short code 표시 */
     hideLabel?: boolean;
+    /**
+     * locale 트리거 버튼의 접근성 이름 (기본값: 현재 옵션의 label, 없으면 `current` 대문자).
+     * `hideLabel` 이 true 면 버튼 안이 아이콘뿐이라 이 값이 유일한 접근성 이름이 된다.
+     *
+     * ⚠️ `hideLabel` 이 false(기본값)일 때는 이 값이 화면에 보이는 라벨을 덮어쓰므로,
+     * 보이는 라벨 텍스트를 **포함**하는 문자열이어야 한다. 그렇지 않으면 음성 제어 사용자가
+     * 보이는 대로 말해도 버튼이 잡히지 않는다 (WCAG 2.1 SC 2.5.3 Label in Name 위반).
+     */
+    ariaLabel?: string;
 }
 interface NavBarProps extends React$1.HTMLAttributes<HTMLElement> {
     /** 왼쪽 brand/로고 영역 */
@@ -560,7 +569,10 @@ interface PopoverProps {
     trigger: React$1.ReactElement;
     /** 팝오버 내부 콘텐츠 - 임의 ReactNode (폼/설명/액션 조합) */
     content: React$1.ReactNode;
-    /** 위치 (기본값: "bottom") */
+    /**
+     * 선호 위치 (기본값: "bottom"). 뷰포트를 벗어나면 반대편으로 flip 되고 교차축으로 shift 되므로
+     * 실제 위치는 계산 결과를 따른다(Radix `side` + `collisionPadding` 계약). body 로 포탈된다.
+     */
     placement?: PopoverPlacement;
     /** 제어 모드 - 열림 상태 */
     open?: boolean;
@@ -568,7 +580,7 @@ interface PopoverProps {
     defaultOpen?: boolean;
     /** 열림 상태 변경 콜백 */
     onOpenChange?: (open: boolean) => void;
-    /** dialog 의 접근성 라벨 - content 에 제목이 없을 때 권장 */
+    /** 팝오버 접근성 레이블(기본값: "Dialog") - content 에 제목이 없을 때 권장 */
     "aria-label"?: string;
     /** dialog 의 접근성 라벨 요소 id */
     "aria-labelledby"?: string;
@@ -603,7 +615,10 @@ type TooltipPlacement = "top" | "bottom" | "left" | "right";
 interface TooltipProps {
     /** 툴팁 콘텐츠 */
     content: React$1.ReactNode;
-    /** 위치 (기본값: "top") */
+    /**
+     * 선호 위치 (기본값: "top"). 뷰포트를 벗어나면 반대편으로 flip 되고 교차축으로 shift 되므로
+     * 실제 위치는 계산 결과를 따른다(Radix `side` + `collisionPadding` 계약). body 로 포탈된다.
+     */
     placement?: TooltipPlacement;
     /** hover 후 지연 시간 ms (기본 200) */
     delay?: number;
@@ -617,7 +632,7 @@ interface TooltipProps {
  * @example
  * ```tsx
  * <Tooltip content="저장하기">
- *   <IconButton icon={<SaveIcon />} />
+ *   <IconButton icon={<SaveIcon />} aria-label="저장" />
  * </Tooltip>
  * ```
  */
@@ -1488,6 +1503,7 @@ interface SpinnerProps {
  */
 declare const Spinner: ({ size, ariaLabel }: SpinnerProps) => React$1.JSX.Element;
 
+type ToastVariant = "success" | "error" | "warning" | "info" | "default";
 interface ToastProviderProps {
     /** 앱 루트에서 감싸는 자식 요소 */
     children: React$1.ReactNode;
@@ -1775,7 +1791,7 @@ interface ImageCropperHandle {
     /** 배율·위치를 초기 상태(전체가 보이는 zoom=min, 중앙)로 되돌린다. */
     reset: () => void;
 }
-interface ImageCropperProps {
+interface ImageCropperProps extends Omit<HTMLAttributes<HTMLDivElement>, "onError" | "children" | "dangerouslySetInnerHTML"> {
     /** 크롭/리셋을 호출할 imperative 핸들 (React 19 ref-as-prop). */
     ref?: Ref<ImageCropperHandle>;
     /** 크롭할 이미지. `File`/`Blob`(로컬) 또는 이미지 URL 문자열. */
@@ -1801,6 +1817,16 @@ interface ImageCropperProps {
     className?: string;
     /** 뷰포트 접근성 레이블. 기본 "이미지 위치와 배율 조정". */
     label?: string;
+    /** 뷰포트 아래 조작 안내 문구. 기본 "드래그(또는 방향키)로 위치, 휠·슬라이더로 배율을 맞추세요." */
+    hint?: string;
+    /** 축소 버튼 접근성 레이블. 기본 "축소". */
+    zoomOutLabel?: string;
+    /** 배율 슬라이더 접근성 레이블. 기본 "배율". */
+    zoomLabel?: string;
+    /** 확대 버튼 접근성 레이블. 기본 "확대". */
+    zoomInLabel?: string;
+    /** 이동 여유가 없을 때 스크린리더로 알리는 문구. 기본 "이미지가 뷰포트를 딱 채워 이동 여유가 없습니다." */
+    noPanHint?: string;
 }
 /**
  * 업로드 전에 이미지에서 보일 정사각 영역을 정하는 크로퍼. 뷰포트 안에서 **드래그(또는 방향키)**
@@ -1817,7 +1843,7 @@ interface ImageCropperProps {
  * 원격 URL 을 넘기면 `canvas.drawImage` 가 서버의 CORS(`Access-Control-Allow-Origin`)에
  * 의존한다 — 확실히 자르려면 로컬 `File`/`Blob` 을 권장한다.
  */
-declare function ImageCropper({ ref, src, outputSize, outputType, quality, circular, viewportSize, minZoom, maxZoom, onReady, onError, className, label, }: ImageCropperProps): React$1.JSX.Element;
+declare function ImageCropper({ ref, src, outputSize, outputType, quality, circular, viewportSize, minZoom, maxZoom, onReady, onError, className, label, hint, zoomOutLabel, zoomLabel, zoomInLabel, noPanHint, ...rest }: ImageCropperProps): React$1.JSX.Element;
 
 interface OtpInputProps {
     /** OTP 자릿수 (기본값: 6) */
@@ -1874,6 +1900,23 @@ declare const Radio: {
 
 type RadioGroupSize = "sm" | "md" | "lg";
 type RadioGroupOrientation = "vertical" | "horizontal";
+interface RadioGroupContextValue {
+    /** 그룹 라디오들이 공유하는 name (브라우저 그룹핑) */
+    name: string;
+    /** 현재 선택된 value (없으면 미선택) */
+    value: string | undefined;
+    /** 라디오 선택 시 호출 */
+    onChange: (value: string) => void;
+    /** 그룹 사이즈 — 개별 Radio 의 size 미지정 시 적용 */
+    size: RadioGroupSize;
+    /** 그룹 전체 비활성화 */
+    disabled: boolean;
+}
+/**
+ * `Radio` 가 상위 `RadioGroup` 의 컨텍스트를 optional 하게 소비하기 위한 hook.
+ * `RadioGroup` 밖에서 쓰이면 `null` 을 반환 — 이 경우 Radio 는 standalone 으로 동작.
+ */
+declare function useRadioGroupContext(): RadioGroupContextValue | null;
 interface RadioGroupProps extends Omit<React$1.HTMLAttributes<HTMLDivElement>, "onChange"> {
     /** 제어형: 선택된 value */
     value?: string;
@@ -2126,7 +2169,8 @@ declare const Button: (props: ButtonProps) => React$1.JSX.Element;
 
 type IconButtonVariant = "standard" | "filled" | "tonal" | "outlined";
 type IconButtonSize = "sm" | "md";
-interface IconButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement> {
+/** 접근성 이름을 제외한 IconButton 공통 props */
+interface IconButtonBaseProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "aria-labelledby"> {
     /** 아이콘 버튼 스타일 변형 (기본값: "standard") */
     variant?: IconButtonVariant;
     /** 아이콘 버튼 크기 (기본값: "md") */
@@ -2136,9 +2180,40 @@ interface IconButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement
     /** 루트 button 요소 ref (React 19 ref-as-prop) */
     ref?: React$1.Ref<HTMLButtonElement>;
 }
+/** `aria-label` 로 접근성 이름을 직접 지정 */
+interface IconButtonWithAriaLabel extends IconButtonBaseProps {
+    /** 아이콘 버튼의 접근성 이름 (필수) */
+    "aria-label": string;
+    /** 접근성 이름을 제공하는 요소 id (선택) */
+    "aria-labelledby"?: string;
+}
+/** `aria-labelledby` 로 외부 요소를 참조해 접근성 이름을 지정 */
+interface IconButtonWithAriaLabelledBy extends IconButtonBaseProps {
+    /** 아이콘 버튼의 접근성 이름 (선택) */
+    "aria-label"?: string;
+    /** 접근성 이름을 제공하는 요소 id (필수) */
+    "aria-labelledby": string;
+}
+/**
+ * IconButton props - 접근성 이름을 타입 레벨에서 강제하는 union.
+ * `icon` 은 항상 `aria-hidden` 으로 감싸지므로 `aria-label` 또는 `aria-labelledby` 중
+ * 최소 하나를 반드시 지정해야 한다 (WCAG 2.1 SC 4.1.2 Name, Role, Value).
+ *
+ * @remarks **Breaking change (타입 레벨)** - v3.7.0 이하에서는 두 속성 모두 optional 이었다.
+ * 접근성 이름 없이 `<IconButton icon={<X />} />` 로 사용하던 코드는 이제 **타입 에러**가 난다.
+ * 런타임 렌더링은 바뀌지 않았으므로 `aria-label`(또는 `aria-labelledby`)만 추가하면 된다.
+ * ```tsx
+ * // before (타입 에러 - 접근성 이름 없음)
+ * <IconButton icon={<X />} />
+ * // after
+ * <IconButton icon={<X />} aria-label="닫기" />
+ * ```
+ */
+type IconButtonProps = IconButtonWithAriaLabel | IconButtonWithAriaLabelledBy;
 /**
  * 아이콘만 표시하는 버튼을 렌더링한다.
  * Figma DS 기준 4가지 variant(standard/filled/tonal/outlined)와 2가지 size(sm/md)를 지원한다.
+ * 아이콘은 `aria-hidden` 이므로 `aria-label` 또는 `aria-labelledby` 가 타입 레벨에서 필수다.
  * @param props 아이콘 버튼 속성
  * @returns 렌더링된 아이콘 버튼 요소
  */
@@ -2434,4 +2509,4 @@ interface StackProps extends React$1.HTMLAttributes<HTMLDivElement> {
  */
 declare const Stack: ({ direction, gap, align, justify, wrap, as: Tag, ref, className, children, style, ...props }: StackProps) => React$1.JSX.Element;
 
-export { Accordion, type AccordionItem, type AccordionProps, AlertProvider, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, Badge, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BottomNav, BottomNavItem, type BottomNavItemProps, type BottomNavProps, BottomNavSpacer, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Card, type CardFooterAlign, type CardProps, type CardVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipSize, type ChipTone, type ChipType, Container, type ContainerProps, type ContainerSize, type CropImageSize, type CropOffset, type CropRect, DatePicker, type DatePickerProps, Divider, type DividerProps, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, type DropdownOption, type DropdownProps, type DropdownSize, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type ErrorStateVariant, FileInput, type FileInputProps, Grid, type GridCols, type GridGap, type GridProps, Hero, type HeroAction, type HeroAlign, type HeroHeight, type HeroOverlay, type HeroProps, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconProps, ImageCropper, type ImageCropperHandle, type ImageCropperProps, type ImeStrategy, LinearProgress, type LinearProgressProps, ListItem, type ListItemProps, MediaCard, type MediaCardImage, type MediaCardImagePosition, type MediaCardProps, type MediaCardShadow, Menu, type MenuItem, type MenuProps, Modal, type ModalProps, NavBar, type NavBarLayout, type NavBarLocaleConfig, type NavBarLocaleOption, type NavBarProps, type NavBarVariant, NavLink, type NavLinkProps, OtpInput, type OtpInputProps, Pagination, type PaginationProps, Popover, type PopoverPlacement, type PopoverProps, Radio, RadioGroup, type RadioGroupOrientation, type RadioGroupProps, type RadioGroupSize, type RadioProps, type ResolvedTheme, Section, type SectionBg, type SectionProps, type SectionSpacing, Sidebar, SidebarItem, type SidebarItemProps, type SidebarMode, type SidebarProps, SidebarSection, type SidebarSectionProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackDirection, type StackGap, type StackJustify, type StackProps, type StackWrap, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, type TableColumn, type TableProps, type TableSize, type TableSort, type TableSortDirection, Tabs, type TabsProps, type TabsSize, type TabsVariant, TextField, type TextFieldProps, type TextFieldSize, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type ThemeMode, ThemeProvider, type ThemeProviderProps, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipPlacement, type TooltipProps, TopLoading, type TopLoadingProps, a11y, baseBorderWidth, baseColors, baseTypography, borderWidth, breakpoints, cn, colors, elevation, iconSize, motion, opacity, radius, skeleton, spacing, typography, useAlert, useFocusTrap, useReducedMotion, useSpringHover, useSpringPresence, useTheme, useToast, zIndex };
+export { Accordion, type AccordionItem, type AccordionProps, type AlertActionsAlign, type AlertOptions, AlertProvider, type AlertVariant, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, Badge, type BadgeAppearance, type BadgeProps, type BadgeShape, type BadgeSize, type BadgeVariant, BottomNav, BottomNavItem, type BottomNavItemProps, type BottomNavProps, BottomNavSpacer, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonAsAnchor, type ButtonAsButton, type ButtonProps, type ButtonSize, type ButtonVariant, Card, type CardFooterAlign, type CardProps, type CardVariant, Checkbox, type CheckboxProps, Chip, type ChipProps, type ChipSize, type ChipTone, type ChipType, Container, type ContainerProps, type ContainerSize, type CropImageSize, type CropOffset, type CropRect, DatePicker, type DatePickerProps, Divider, type DividerProps, Drawer, type DrawerPlacement, type DrawerProps, Dropdown, type DropdownMultipleProps, type DropdownOption, type DropdownProps, type DropdownSingleProps, type DropdownSize, EmptyState, type EmptyStateProps, ErrorState, type ErrorStateProps, type ErrorStateVariant, FileInput, type FileInputProps, type FileInputVariant, Grid, type GridCols, type GridGap, type GridProps, Hero, type HeroAction, type HeroAlign, type HeroHeight, type HeroOverlay, type HeroProps, Icon, IconButton, type IconButtonProps, type IconButtonSize, type IconButtonVariant, type IconProps, ImageCropper, type ImageCropperHandle, type ImageCropperProps, type ImeStrategy, LinearProgress, type LinearProgressProps, ListItem, type ListItemProps, MediaCard, type MediaCardImage, type MediaCardImagePosition, type MediaCardProps, type MediaCardShadow, Menu, type MenuItem, type MenuProps, Modal, type ModalFooterAlign, type ModalProps, NavBar, type NavBarLayout, type NavBarLocaleConfig, type NavBarLocaleOption, type NavBarProps, type NavBarVariant, NavLink, type NavLinkProps, OtpInput, type OtpInputProps, Pagination, type PaginationProps, Popover, type PopoverPlacement, type PopoverProps, Radio, RadioGroup, type RadioGroupContextValue, type RadioGroupOrientation, type RadioGroupProps, type RadioGroupSize, type RadioProps, type ResolvedTheme, Section, type SectionBg, type SectionProps, type SectionSpacing, Sidebar, SidebarItem, type SidebarItemProps, type SidebarMode, type SidebarProps, SidebarSection, type SidebarSectionProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackDirection, type StackGap, type StackJustify, type StackProps, type StackWrap, Tab, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Table, type TableColumn, type TableProps, type TableSize, type TableSort, type TableSortDirection, Tabs, type TabsProps, type TabsSize, type TabsVariant, TextField, type TextFieldProps, type TextFieldSize, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type ThemeMode, ThemeProvider, type ThemeProviderProps, ToastProvider, type ToastProviderProps, type ToastVariant, Toggle, type ToggleProps, Tooltip, type TooltipPlacement, type TooltipProps, TopLoading, type TopLoadingProps, a11y, baseBorderWidth, baseColors, baseTypography, borderWidth, breakpoints, cn, colors, elevation, iconSize, motion, opacity, radius, skeleton, spacing, typography, useAlert, useFocusTrap, useRadioGroupContext, useReducedMotion, useSpringHover, useSpringPresence, useTheme, useToast, zIndex };