@mondrianai/runyourai-design-system 0.0.25 → 0.0.27

package/README.md

@@ -1,56 +1,33 @@
 # @mondrianai/runyourai-design-system
 
-RunYourAI Design System — React component library built on [shadcn/ui](https://ui.shadcn.com/) components, [Radix UI](https://www.radix-ui.com/) primitives, and [Tailwind CSS v4](https://tailwindcss.com/).
+RunYourAI Design System — [shadcn/ui](https://ui.shadcn.com/) · [Radix UI](https://www.radix-ui.com/) · [Tailwind CSS v4](https://tailwindcss.com/) 기반 React 컴포넌트 라이브러리입니다.
 
-## Requirements
+| 항목 | 내용 |
+| --- | --- |
+| 최종 수정 | 2026-08-11 (Seulki Yun) |
 
-- React 18+
-- Next.js 15+
-- Tailwind CSS v4
-
-## Installation
-
-```bash
-npm install @mondrianai/runyourai-design-system
-# or
-yarn add @mondrianai/runyourai-design-system
-```
-
-## Local Development (yalc)
-
-소비 앱에서 로컬 빌드를 테스트할 때는 [yalc](https://github.com/wclr/yalc)를 사용합니다.
-
-```bash
-# 최초 1회: 소비 앱에 yalc 연결
-# (design system 레포에서)
-yalc publish
-# (소비 앱 레포에서)
-yalc add @mondrianai/runyourai-design-system
-
-# 이후 변경사항 반영 시 (design system 레포에서)
-npm run build && yalc push
-# 소비 앱 dev 서버 재시작 필요
-```
+---
 
-> **주의**: `sidebar.tsx`, `button.tsx` 등 컴포넌트 소스를 수정한 경우, 반드시 `npm run build && yalc push` 를 실행해야 소비 앱에 변경사항이 반영됩니다. 소스 파일을 수정해도 소비 앱의 dev server hot-reload만으로는 dist가 갱신되지 않습니다.
+소비 앱은 `main-frontend`(React 18 · antd 5)와 `core-frontend`(Next.js 16 · React 19 · antd 6) 두 곳입니다. 이 레포는 라이브러리이면서 동시에 **쇼케이스 앱**(`src/app/`)을 겸하고 있어, `yarn dev` 로 모든 컴포넌트를 눈으로 확인할 수 있습니다.
 
----
+| 항목 | 값 |
+| --- | --- |
+| Peer deps | React 18+ · Tailwind CSS v4 |
+| 배포 | Bitbucket Pipelines — `v*` 태그 push 시 npm publish |
+| 로컬 연동 | [yalc](https://github.com/wclr/yalc) |
 
-## Setup
+## 소비 앱에 설치하기
 
 ### 1. 패키지 설치
 
 ```bash
-npm install @mondrianai/runyourai-design-system tailwindcss
-npm install --save-dev @tailwindcss/postcss
-# or
 yarn add @mondrianai/runyourai-design-system tailwindcss
 yarn add --dev @tailwindcss/postcss
 ```
 
 ### 2. PostCSS 설정
 
-프로젝트 루트에 `postcss.config.mjs`를 생성합니다.
+프로젝트 루트에 `postcss.config.mjs` 를 만듭니다.
 
 ```js
 // postcss.config.mjs
@@ -65,7 +42,7 @@ export default config;
 
 ### 3. Next.js (Turbopack) 설정
 
-Next.js 15+ / 16의 기본 번들러인 Turbopack은 CSS `@import`에서 `package.json`의 `exports` 서브패스를 해석하지 못합니다. `next.config.ts`에 아래 `resolveAlias`를 추가해야 합니다.
+Next.js 15+ / 16 의 기본 번들러인 Turbopack 은 CSS `@import` 에서 `package.json` 의 `exports` 서브패스를 해석하지 못합니다. `next.config.ts` 에 `resolveAlias` 를 추가합니다.
 
 ```ts
 // next.config.ts
@@ -85,11 +62,11 @@ const nextConfig: NextConfig = {
 export default nextConfig;
 ```
 
-> Turbopack을 사용하지 않는 경우(webpack 기반 커스텀 설정 등)에는 이 단계를 건너뜁니다.
+> Turbopack 을 쓰지 않으면(webpack 기반 커스텀 설정 등) 이 단계는 건너뜁니다.
 
 ### 4. Tailwind CSS 설정
 
-`globals.css`에 아래 내용을 추가합니다. 디자인 토큰, Tailwind 테마, 애니메이션, 다크모드 설정이 모두 적용됩니다.
+`globals.css` 에 아래를 추가하면 디자인 토큰 · Tailwind 테마 · 애니메이션 · 다크모드가 모두 적용됩니다.
 
 ```css
 /* globals.css */
@@ -98,60 +75,53 @@ export default nextConfig;
 @import '@mondrianai/runyourai-design-system/tailwind-theme';
 
 /* globals.css 위치 기준 node_modules 상대 경로 — 프로젝트 구조에 따라 조정하세요
- * globals.css가 app/globals.css 에 있는 경우: ../node_modules/...
- * globals.css가 src/app/globals.css 에 있는 경우: ../../node_modules/...
+ * app/globals.css      → ../node_modules/...
+ * src/app/globals.css  → ../../node_modules/...
  */
 @source "../node_modules/@mondrianai/runyourai-design-system/dist";
 ```
 
-> **`@import` 순서 주의**
->
-> - `url(...)` 형태의 외부 폰트 import가 있다면 `@import 'tailwindcss'` **앞에** 위치시킵니다.
-> - `@mondrianai/runyourai-design-system/styles`, `@mondrianai/runyourai-design-system/tailwind-theme`는 `@import 'tailwindcss'` **뒤에** 위치시킵니다.
-
-> **디자인 토큰 오버라이드 주의**
->
-> `:root`에서 디자인 시스템 CSS 변수를 오버라이드할 때, **컴포넌트 표면색 토큰**(`--background`, `--card`, `--popover` 등)을 페이지 배경색 설정 목적으로 변경하면 안 됩니다. 이 변수들은 `Button` outline, `Card`, `Popover` 등 컴포넌트의 배경색에 직접 사용됩니다.
->
-> **페이지 배경색**은 CSS 토큰 오버라이드 대신 `html`/`body`에 직접 지정하세요.
->
-> ```css
-> /* ❌ 잘못된 예 — Button outline 등 컴포넌트 배경색까지 바뀜 */
-> :root {
->   --background: #fdfdfd;
-> }
->
-> /* ✅ 올바른 예 — 페이지 배경만 변경, 컴포넌트 토큰 무영향 */
-> html, body {
->   background-color: #fdfdfd;
-> }
-> ```
-
-> **기존 CSS 리셋 주의 (Tailwind v4)**
-> 프로젝트에 `* { margin: 0; padding: 0; }` 같은 전역 리셋이 있다면 반드시 `@layer base`로 감싸야 합니다. Tailwind v4에서 레이어 밖의 스타일은 `@layer utilities`보다 우선순위가 높아 `px-*`, `py-*` 등의 유틸리티 클래스가 무효화됩니다.
->
-> ```css
-> @layer base {
->   *,
->   *::before,
->   *::after {
->     box-sizing: border-box;
->   }
->
->   * {
->     margin: 0;
->     padding: 0;
->   }
-> }
-> ```
+**`@import` 순서** — `url(...)` 형태의 외부 폰트 import 는 `@import 'tailwindcss'` **앞에**, 디자인 시스템 두 줄은 **뒤에** 둡니다.
+
+**디자인 토큰 오버라이드** — `:root` 에서 **컴포넌트 표면색 토큰**(`--background` · `--card` · `--popover` 등)을 페이지 배경색 목적으로 바꾸면 안 됩니다. 이 변수들은 `Button` outline · `Card` · `Popover` 의 배경색에 직접 쓰입니다.
+
+```css
+/* ❌ Button outline 등 컴포넌트 배경색까지 바뀜 */
+:root {
+  --background: #fdfdfd;
+}
+
+/* ✅ 페이지 배경만 변경, 컴포넌트 토큰 무영향 */
+html,
+body {
+  background-color: #fdfdfd;
+}
+```
+
+**기존 CSS 리셋** — `* { margin: 0; padding: 0; }` 같은 전역 리셋이 있다면 반드시 `@layer base` 로 감쌉니다. Tailwind v4 에서 레이어 밖 스타일은 `@layer utilities` 보다 우선순위가 높아 `px-*` · `py-*` 가 무효화됩니다.
+
+```css
+@layer base {
+  *,
+  *::before,
+  *::after {
+    box-sizing: border-box;
+  }
+
+  * {
+    margin: 0;
+    padding: 0;
+  }
+}
+```
 
 ### 5. Provider 설정
 
-`Tooltip` 등 Radix UI 기반 컴포넌트가 올바르게 동작하려면 앱 최상단에 `Providers`를 감싸야 합니다.
+`Tooltip` · `toast()` 등 Radix · sonner 기반 컴포넌트가 동작하려면 앱 최상단을 `RyaiDsProvider` 로 감쌉니다.
 
 ```tsx
 // app/layout.tsx
-import { Providers } from '@mondrianai/runyourai-design-system';
+import { RyaiDsProvider } from '@mondrianai/runyourai-design-system';
 
 export default function RootLayout({
   children,
@@ -161,19 +131,21 @@ export default function RootLayout({
   return (
     <html lang='ko'>
       <body>
-        <Providers>{children}</Providers>
+        <RyaiDsProvider>{children}</RyaiDsProvider>
       </body>
     </html>
   );
 }
 ```
 
-## Usage
+> antd 를 함께 쓴다면 **antd `ConfigProvider` 바깥**에 둡니다.
+
+## 사용
 
 ```tsx
 import { Button, Badge, Card } from '@mondrianai/runyourai-design-system';
 
-export default function Page() {
+export function Page() {
   return (
     <Card>
       <Badge text='New' />
@@ -183,78 +155,59 @@ export default function Page() {
 }
 ```
 
-### Utilities
-
 ```tsx
 import { cn } from '@mondrianai/runyourai-design-system/utils';
 
 <div className={cn('base-class', isActive && 'active-class')} />;
 ```
 
-## Components
-
-| Component                             | Description               |
-| ------------------------------------- | ------------------------- |
-| `Accordion`                           | 펼침/접힘 컨텐츠 영역     |
-| `AlertDialog`                         | 확인/취소 모달 다이얼로그 |
-| `Alert`                               | 인라인 알림 메시지        |
-| `Avatar` / `AvatarGroup`              | 유저 아바타 및 그룹       |
-| `Badge`                               | 상태·카테고리 배지        |
-| `Breadcrumb`                          | 페이지 경로 탐색          |
-| `Button`                              | 버튼                      |
-| `Card`                                | 카드 컨테이너             |
-| `Checkbox` / `CheckboxCard`           | 체크박스                  |
-| `ChoiceCardGroup` / `ChoiceCardItem`  | 선택형 카드 그룹          |
-| `Collapsible`                         | 접을 수 있는 컨텐츠       |
-| `Combobox`                            | 검색 가능한 선택 입력     |
-| `Field` / `FieldSection` / `FieldRow` | 폼 필드 레이아웃          |
-| `GroupedSelect`                       | 그룹 구분이 있는 셀렉트   |
-| `Header`                              | 앱 상단 헤더              |
-| `Icon`                                | Lucide 아이콘 래퍼        |
-| `MarkdownMessage`                     | 마크다운 렌더링 메시지    |
-| `Menubar`                             | 메뉴바                    |
-| `MessageFooter`                       | 메시지 하단 액션 영역     |
-| `NumberBadge`                         | 숫자 배지                 |
-| `SegmentedControl`                    | 세그먼트 탭 컨트롤        |
-| `Select`                              | 셀렉트 박스               |
-| `Sheet`                               | 사이드 슬라이드 패널      |
-| `Sidebar`                             | 앱 사이드바               |
-| `Slider`                              | 슬라이더                  |
-| `Stepper`                             | 단계 진행 표시            |
-| `Switch` / `SwitchField`              | 토글 스위치               |
-| `Tooltip` / `TooltipWithIcon`         | 툴팁                      |
-| `UserMessageBubble`                   | 채팅 메시지 말풍선        |
-
-## Icons
-
-### Custom Icons
+아이콘도 같은 진입점에서 가져옵니다. `size-*` · `text-*` 클래스로 크기와 색을 제어합니다.
 
 ```tsx
 import {
-  SparklesIcon,
-  TrashIcon,
-  StarIcon,
+  SparklesIcon, // 커스텀 아이콘
+  ClaudeIcon, // 브랜드 아이콘
+  RyaiLogoIcon, // 로고
 } from '@mondrianai/runyourai-design-system';
 
 <SparklesIcon className='size-4 text-primary' />;
 ```
 
-### Brand Icons
+**제공 컴포넌트 목록**은 여기 적지 않습니다 — 목록은 금방 낡습니다. `src/components/index.ts` 의 export 를 보거나, `yarn dev` 로 쇼케이스 앱을 띄워 확인하세요.
 
-```tsx
-import {
-  ClaudeIcon,
-  OpenAiIcon,
-  GeminiIcon,
-} from '@mondrianai/runyourai-design-system';
+## 로컬 개발
 
-<ClaudeIcon className='size-6' />;
+```bash
+yarn install
+yarn dev           # 쇼케이스 앱 (port 3999)
+yarn build         # 라이브러리 빌드 — tsc --noEmit && tsup
+yarn lint
 ```
 
-### Logo
+소비 앱에서 로컬 빌드를 테스트할 때는 yalc 를 씁니다.
 
-```tsx
-import { RyaiLogoIcon } from '@mondrianai/runyourai-design-system';
+```bash
+# 디자인 시스템 레포에서 (최초 1회)
+yarn build && yalc publish
+# 소비 앱에서 (최초 1회)
+yalc add @mondrianai/runyourai-design-system
 
-<RyaiLogoIcon />;
+# 이후 변경마다 — 디자인 시스템 레포에서
+yarn build && yalc push
 ```
+
+> **소스만 고치면 소비 앱에 반영되지 않습니다.** 소비 앱은 `dist/` 를 보므로 반드시 `yarn build` 를 거쳐야 합니다. 최초 세팅·트러블슈팅은 [개발 사이클](./docs/operations/dev-cycle.md).
+
+## 문서
+
+| 문서 | 내용 |
+| --- | --- |
+| [`AGENTS.md`](./AGENTS.md) | **작업 규칙** — 코드를 만지기 전에 읽습니다. 디자이너·개발자 갈래가 나뉩니다 |
+| [`docs/`](./docs/README.md) | 문서 인덱스 — 디자인 · 아키텍처 · 운영 · 계획 |
+| [Figma 구현](./docs/design/figma-implementation.md) | 시안을 1px 오차 없이 옮기는 기준 |
+| [디자인 토큰](./docs/design/tokens.md) | `variables.json` → CSS 세 파일 동기화 |
+| [컴포넌트 API](./docs/architecture/component-api.md) | 공개 표면 설계 원칙 |
+| [개발 사이클](./docs/operations/dev-cycle.md) | 구현 후 마무리 · yalc 반영 · 트러블슈팅 |
+| [릴리스](./docs/operations/release.md) | 버전 결정 · 태그 · npm 배포 |
+
+디렉터리 구조와 설정 항목은 문서로 옮겨두지 않습니다. `src/` 와 `tsup.config.ts` · `package.json` 을 직접 보세요. 왜 그렇게 되어 있는지는 위 문서에 있습니다.

package/dist/index.d.mts

@@ -114,7 +114,7 @@ declare function BreadcrumbSeparator({ iconName, className, ...props }: React__d
 
 declare const buttonVariants: (props?: ({
     variant?: "link" | "primary" | "secondary" | "outline" | "ghost" | "destructive" | "ghostDestructive" | null | undefined;
-    size?: "rounded" | "default" | "icon" | "pill" | null | undefined;
+    size?: "rounded" | "default" | "sm" | "icon" | "pill" | null | undefined;
 } & class_variance_authority_types.ClassProp) | undefined) => string;
 interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
     /** Radix Slot 패턴 — true 이면 자식 요소에 props를 병합 */
@@ -132,7 +132,12 @@ interface ButtonProps extends React$1.ButtonHTMLAttributes<HTMLButtonElement>, V
      */
     iconEnd?: React$1.ReactNode;
 }
-declare function Button({ className, variant, size, asChild, loading, iconStart, iconEnd, disabled, children, ...props }: ButtonProps): react_jsx_runtime.JSX.Element;
+/**
+ * ref를 받는 이유 — Popover/Tooltip/Drawer/Modal 등 DS 컴포넌트가 트리거를 Radix `asChild`(Slot)로
+ * 렌더하고, Slot은 자식에 ref를 붙인다. peerDependencies가 react>=18이라 React 19의 ref-as-prop에
+ * 기댈 수 없으므로 forwardRef가 필요하다. (React 18에서는 없으면 ref 경고와 함께 위치 계산이 깨진다)
+ */
+declare const Button: React$1.ForwardRefExoticComponent<ButtonProps & React$1.RefAttributes<HTMLButtonElement>>;
 
 declare function Card({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
 declare function CardHeader({ className, ...props }: React$1.ComponentProps<"div">): react_jsx_runtime.JSX.Element;
@@ -534,8 +539,13 @@ interface IconProps extends React$1.SVGProps<SVGSVGElement> {
  * Inline SVG icon component.
  * Uses `stroke="currentColor"` so color is controlled via CSS `text-*` classes.
  * Renders the same paths as lucide-react but without the library dependency.
+ *
+ * ref를 받는 이유 — Tooltip/Popover/Drawer 등이 트리거를 Radix `asChild`(Slot)로 렌더하고,
+ * Slot은 자식에 ref를 붙인다. peerDependencies가 react>=18이라 React 19의 ref-as-prop에
+ * 기댈 수 없으므로 forwardRef가 필요하다. (React 18에서는 ref가 죽어 Popper가 앵커를 잡지
+ * 못하고, 툴팁이 열려도 화면 밖에 머문다)
  */
-declare function Icon({ name, className, strokeWidth, ...props }: IconProps): react_jsx_runtime.JSX.Element | null;
+declare const Icon: React$1.ForwardRefExoticComponent<Omit<IconProps, "ref"> & React$1.RefAttributes<SVGSVGElement>>;
 
 declare function Input({ className, type, ...props }: React$1.ComponentProps<"input">): react_jsx_runtime.JSX.Element;
 
@@ -809,7 +819,7 @@ type SelectProps = SingleSelectProps | MultiSelectProps;
  * - 열린 상태에서 listbox에 포커스가 이동하고 `aria-activedescendant`로 활성 옵션을 연결한다.
  * - 키보드: ↑/↓/Home/End 이동, Enter/Space 선택(다중은 토글), Esc 닫힘, 타입어헤드 점프.
  * - 역할: 컨테이너 `role="listbox"`(+다중 시 `aria-multiselectable`), 옵션 `role="option"`+`aria-selected`.
- * 배경·설계 근거: {@link ../../../docs/todo/select-a11y-keyboard-aria.md}
+ * 배경·설계 근거: {@link ../../../docs/plans/select-a11y-keyboard-aria.md}
  */
 declare function Select(props: SelectProps): react_jsx_runtime.JSX.Element;
 
@@ -896,7 +906,7 @@ declare function SidebarLink({ href, className, style, onClick, children, }: {
     onClick?: () => void;
     children: React$1.ReactNode;
 }): React$1.ReactElement<unknown, string | React$1.JSXElementConstructor<any>>;
-declare function Sidebar({ logo, menus, avatar, utilities, panelTopContent, panelCenterContent, panelBottomContent, className, LinkComponent, isPanelOpen: isPanelOpenProp, onPanelOpenChange, mainMenuIconSize, }: {
+declare function Sidebar({ logo, menus, avatar, utilities, panelTopContent, panelCenterContent, panelBottomContent, className, LinkComponent, isPanelOpen: isPanelOpenProp, onPanelOpenChange, mainMenuIconSize, labels, }: {
     logo: React$1.ReactNode;
     menus: SidebarMainMenuItem[];
     avatar: React$1.ReactNode;
@@ -920,6 +930,20 @@ declare function Sidebar({ logo, menus, avatar, utilities, panelTopContent, pane
      * - `'lg'`: 40px
      */
     mainMenuIconSize?: 'md' | 'lg';
+    /**
+     * 접근성 이름 — 스크린 리더에만 노출되는 문자열이라 화면에는 보이지 않는다.
+     * 미지정 시 한국어 기본값을 쓰므로, 다국어 앱은 번역된 문자열을 넘긴다.
+     */
+    labels?: {
+        /** 사이드바 전체(landmark). 기본값 '사이드바' */
+        sidebar?: string;
+        /** 좌측 서비스 내비게이터. 기본값 '메인 메뉴' */
+        mainMenu?: string;
+        /** 서브 메뉴 패널. 기본값은 활성 메뉴 제목 */
+        panel?: string;
+        /** 패널 닫기 버튼. 기본값 '패널 닫기' */
+        panelClose?: string;
+    };
 }): react_jsx_runtime.JSX.Element;
 
 interface SkeletonProps extends React$1.HTMLAttributes<HTMLDivElement> {
@@ -975,12 +999,16 @@ interface TabsProps<T extends string = string> {
  *
  * NOTE: 콘텐츠 패널은 사용처가 바깥에서 `current`로 렌더하므로 Tabs.Content(및 aria-controls↔
  *   aria-labelledby 연결)가 없다. 키보드·역할 a11y는 확보했으나 탭↔패널 연결은 미완.
- *   구 pill 사용처 이관 및 릴리스 체크리스트: docs/todo/tabs-segmented-control.md
+ *   구 pill 사용처 이관 및 릴리스 체크리스트: docs/plans/tabs-segmented-control.md
  */
 declare function Tabs<T extends string = string>({ allTabs, current, onTabChange, block, className, }: TabsProps<T>): react_jsx_runtime.JSX.Element;
 
+/**
+ * 좌우 여백은 아이콘 단독 사용 시 정사각(min-w)을 유지하도록 좁게 둔다.
+ * 라벨을 함께 두는 그룹(ToggleGroup)은 자체 여백을 쓴다.
+ */
 declare const toggleSizeClasses: {
-    readonly sm: "h-7 min-w-7 px-1.5 text-sm";
+    readonly sm: "h-7 min-w-7 px-1.5 text-xs";
     readonly md: "h-9 min-w-9 px-2 text-sm";
     readonly lg: "h-10 min-w-10 px-2.5 text-base";
 };
@@ -996,19 +1024,33 @@ declare function Toggle({ size, className, ...props }: ToggleProps): react_jsx_r
 
 interface ToggleGroupItemData<T extends string = string> {
     value: T;
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     disabled?: boolean;
 }
 interface ToggleGroupBaseProps<T extends string = string> {
     items: ToggleGroupItemData<T>[];
     /**
-     * outlined — 컨테이너 border + 아이템 사이 divider (default)
-     * noBorder — border 없음, 아이템마다 rounded-md 독립 적용
+     * bordered — 컨테이너 border + 아이템 사이 divider (default)
+     * noBorder — border 없이 붙은 묶음
+     * chip     — 아이템이 독립 알약(rounded-full)으로 떨어지고, 폭이 모자라면 줄바꿈된다
+     */
+    variant?: 'bordered' | 'noBorder' | 'chip';
+    /**
+     * 선택된 항목에 쓸 Button variant. 기본 'outline'(흰 배경 + 테두리).
+     * 선택되지 않은 항목은 'secondary'(연회색 배경)로 고정이라, 선택된 쪽이 배경에서 떠 보인다.
+     * 더 강한 강조가 필요하면 'primary'를 넘긴다.
      */
-    variant?: 'bordered' | 'noBorder';
+    selectedStyle?: ButtonProps['variant'];
     disabled?: boolean;
     size?: 'sm' | 'md' | 'lg';
     className?: string;
+    /**
+     * 그룹(radiogroup/group)의 접근성 이름. 화면에 보이는 제목이 따로 없다면 반드시 지정한다.
+     * 보이는 제목이 있으면 `aria-labelledby`로 그 요소를 가리키는 편이 낫다.
+     */
+    'aria-label'?: string;
+    /** 그룹의 접근성 이름을 다른 요소에서 가져올 때 쓴다(`aria-label`보다 우선). */
+    'aria-labelledby'?: string;
 }
 interface ToggleGroupSingleProps<T extends string = string> extends ToggleGroupBaseProps<T> {
     type?: 'single';
@@ -1021,7 +1063,16 @@ interface ToggleGroupMultipleProps<T extends string = string> extends ToggleGrou
     onValueChange?: (value: T[]) => void;
 }
 type ToggleGroupProps<T extends string = string> = ToggleGroupSingleProps<T> | ToggleGroupMultipleProps<T>;
-declare function ToggleGroup<T extends string = string>({ items, variant, disabled, size, className, ...rest }: ToggleGroupProps<T>): react_jsx_runtime.JSX.Element;
+/**
+ * 여러 항목 중 하나(single) 또는 여럿(multiple)을 고르는 버튼 그룹.
+ * 항목은 DS Button으로 렌더링되므로 색/상태 스타일이 버튼과 일관된다.
+ *
+ * 선택 방식에 따라 역할이 달라진다 (WAI-ARIA APG).
+ * - single   — 상호배타 선택이므로 `radiogroup`/`radio`. 그룹 전체가 탭 스톱 하나이고
+ *              좌우/상하 화살표로 이동하며 이동과 동시에 선택된다.
+ * - multiple — 각각 독립 on/off이므로 `aria-pressed` 토글 버튼 묶음.
+ */
+declare function ToggleGroup<T extends string = string>({ items, variant, selectedStyle, disabled, size, className, 'aria-label': ariaLabel, 'aria-labelledby': ariaLabelledBy, ...rest }: ToggleGroupProps<T>): react_jsx_runtime.JSX.Element;
 
 interface CircleIndicatorProps {
     /** 사용량 (바이트 또는 임의 단위) */
@@ -1272,9 +1323,20 @@ interface TooltipWithIconProps {
     content: string;
     /** 트리거 아이콘 이름 (Lucide). @default "info" */
     iconName?: string;
+    /**
+     * 트리거 버튼의 접근성 이름. 기본값은 `content`다.
+     * 기본값이면 스크린 리더가 이름과 설명으로 같은 문장을 두 번 읽으므로,
+     * 다국어 앱은 '도움말' 같은 짧은 번역 문자열을 넘기는 편이 낫다.
+     */
+    triggerLabel?: string;
+    /** 트리거 버튼에 적용된다(크기·색). 아이콘은 버튼 크기를 채운다. */
     className?: string;
 }
-declare function TooltipWithIcon({ content, iconName, className, }: TooltipWithIconProps): react_jsx_runtime.JSX.Element | null;
+/**
+ * 트리거를 `<button>`으로 두는 이유 — 아이콘(svg)은 `aria-hidden`이고 탭 순서에도 없어
+ * 트리거로 쓰면 키보드·스크린 리더 사용자가 툴팁에 도달할 수 없다.
+ */
+declare function TooltipWithIcon({ content, iconName, triggerLabel, className, }: TooltipWithIconProps): react_jsx_runtime.JSX.Element | null;
 
 /**
  * 사용자 메시지 말풍선.
@@ -1334,6 +1396,15 @@ type ToastOptions = {
     duration?: number;
     /** 표시 위치. 미지정 시 `<Toaster />` 기본값(top-center). */
     position?: ExternalToast['position'];
+    /**
+     * 기본 너비(356px)에서 줄바꿈하지 않고 문구 길이만큼 토스트를 넓힌다.
+     * 목록처럼 길이가 가변적인 문구(예: 지원하지 않는 파일 형식 나열)에 사용한다.
+     *
+     * 무한정 넓어지지는 않는다. `--toast-nowrap-max`(기본 `min(90vw, 720px)`)에서
+     * 멈추고, 그보다 긴 문구는 그 지점부터 다시 줄바꿈한다. 좁은 뷰포트에서
+     * 토스트가 화면 밖으로 나가지 않도록 하는 안전장치다.
+     */
+    nowrap?: boolean;
     /** 토스트 컨테이너에 추가할 클래스 */
     className?: string;
 };
@@ -1381,7 +1452,7 @@ type ToastPromiseMessages<T> = {
  *   error: '실패',
  * });
  */
-declare function promiseToast<T>(promise: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>): string | number;
+declare function promiseToast<T>(promise: Promise<T> | (() => Promise<T>), messages: ToastPromiseMessages<T>, options?: ToastMethodOptions): string | number;
 /**
  * 이미 떠 있는 하나의 토스트를 이후 상태로 갱신하는 핸들.
  * `toast.loading()`이 반환하며, `{ id }`를 옵션으로 넘겨 다시 지정할 필요 없이