@mondrianai/runyourai-design-system 0.0.24 → 0.0.26

package/dist/index.d.mts

@@ -1,6 +1,6 @@
 import * as React$1 from 'react';
 import React__default, { ReactNode } from 'react';
-import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Switch as Switch$1, Tooltip as Tooltip$1, Popover as Popover$1 } from 'radix-ui';
+import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Toggle as Toggle$1, Switch as Switch$1, Tooltip as Tooltip$1, Popover as Popover$1 } from 'radix-ui';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
@@ -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;
 
@@ -717,6 +727,10 @@ interface ProgressProps {
     tooltip?: string;
     className?: string;
 }
+/**
+ * 진행률 바 — Radix Progress 기반(role=progressbar, aria-valuenow/valuemin/valuemax).
+ * warning/danger 임계값 색상, tooltip 지원.
+ */
 declare function Progress({ value, warning, danger, tooltip, className, }: ProgressProps): react_jsx_runtime.JSX.Element;
 
 interface Item<T extends string> {
@@ -727,8 +741,18 @@ interface SegmentedControlProps<T extends string> {
     value: T;
     onChange: (value: T) => void;
     items: readonly Item<T>[];
+    /**
+     * true면 컨테이너를 w-full로 펼치고 각 세그먼트를 균등분할(flex-1)한다.
+     * 기본 false — 콘텐츠 폭(각 세그먼트가 라벨 길이에 맞춰짐).
+     */
+    block?: boolean;
+    className?: string;
 }
-declare function SegmentedControl<T extends string>({ value, onChange, items, }: SegmentedControlProps<T>): react_jsx_runtime.JSX.Element;
+/**
+ * 세그먼트 컨트롤(값/필터 선택) — Tabs `variant="pill"`과 동일 스타일.
+ * 균등분할이 필요하면 `block`. 라벨이 칸보다 길면 말줄임되고, 그 경우에만 hover 시 툴팁으로 전체 표시.
+ */
+declare function SegmentedControl<T extends string>({ value, onChange, items, block, className, }: SegmentedControlProps<T>): react_jsx_runtime.JSX.Element;
 
 interface SearchInputProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'type'> {
     value: string;
@@ -882,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;
@@ -906,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> {
@@ -948,51 +986,71 @@ interface TabsProps<T extends string = string> {
     allTabs: TabItem<T>[];
     current: T;
     onTabChange: (value: T) => void;
-    /**
-     * "pill"      — 회색 배경 컨테이너 + 흰 배경 active (segment control 스타일)
-     * "underline" — 하단 밑줄 active (default)
-     */
-    variant?: 'pill' | 'underline';
     /** 컨테이너를 w-full로 펼치고 각 탭 버튼을 균등 분할(flex-1)합니다 */
     block?: boolean;
-    /** Tailwind height 클래스 (e.g. "h-[36px]"). 지정 시 내부 버튼 패딩도 자동 조정됩니다. */
-    height?: string;
     className?: string;
 }
 /**
- * 디자인 시스템에서는 동일 뷰의 데이터 전환을 위해 ToggleGroup 대신 Tabs를 사용합니다.
- * Tabs의 원래 목적으로도 사용하며, 한 화면에 두 가지의 의미로 Tabs를 사용하지 않습니다.
+ * 하단 밑줄(underline) 탭 — 서로 다른 콘텐츠 영역 전환(진짜 탭).
+ * Radix Tabs 기반: role=tablist/tab, roving tabindex, ←/→ 키보드,
+ * `activationMode="manual"`(화살표는 포커스만, 클릭/Enter/Space로 활성화).
+ *
+ * 세그먼트/값·필터 선택(구 `variant="pill"`)은 SegmentedControl을 사용한다.
+ *
+ * NOTE: 콘텐츠 패널은 사용처가 바깥에서 `current`로 렌더하므로 Tabs.Content(및 aria-controls↔
+ *   aria-labelledby 연결)가 없다. 키보드·역할 a11y는 확보했으나 탭↔패널 연결은 미완.
+ *   구 pill 사용처 이관 및 릴리스 체크리스트: docs/todo/tabs-segmented-control.md
  */
-declare function Tabs<T extends string = string>({ allTabs, current, onTabChange, variant, block, height, className, }: TabsProps<T>): react_jsx_runtime.JSX.Element;
+declare function Tabs<T extends string = string>({ allTabs, current, onTabChange, block, className, }: TabsProps<T>): react_jsx_runtime.JSX.Element;
 
-interface ToggleProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
-    pressed?: boolean;
-    onPressedChange?: (pressed: boolean) => void;
-    size?: 'sm' | 'md' | 'lg';
-}
+/**
+ * 좌우 여백은 아이콘 단독 사용 시 정사각(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";
 };
 declare const toggleBaseClasses = "inline-flex items-center justify-center gap-1.5 font-medium tracking-tight transition-colors select-none";
-declare function Toggle({ pressed, onPressedChange, size, disabled, className, children, ...props }: ToggleProps): react_jsx_runtime.JSX.Element;
+interface ToggleProps extends Omit<React$1.ComponentPropsWithoutRef<typeof Toggle$1.Root>, 'asChild'> {
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * 두 상태(on/off) 토글 버튼 — Radix Toggle 기반(aria-pressed, data-state=on/off, Space/Enter 키보드).
+ * `pressed`/`onPressedChange`로 제어한다.
+ */
+declare function Toggle({ size, className, ...props }: ToggleProps): react_jsx_runtime.JSX.Element;
 
 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';
@@ -1005,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 {
     /** 사용량 (바이트 또는 임의 단위) */
@@ -1256,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;
 
 /**
  * 사용자 메시지 말풍선.

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as React$1 from 'react';
 import React__default, { ReactNode } from 'react';
-import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Switch as Switch$1, Tooltip as Tooltip$1, Popover as Popover$1 } from 'radix-ui';
+import { Accordion as Accordion$1, AlertDialog as AlertDialog$1, Checkbox as Checkbox$1, Collapsible as Collapsible$1, Menubar as Menubar$1, Slider as Slider$1, Toggle as Toggle$1, Switch as Switch$1, Tooltip as Tooltip$1, Popover as Popover$1 } from 'radix-ui';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
@@ -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;
 
@@ -717,6 +727,10 @@ interface ProgressProps {
     tooltip?: string;
     className?: string;
 }
+/**
+ * 진행률 바 — Radix Progress 기반(role=progressbar, aria-valuenow/valuemin/valuemax).
+ * warning/danger 임계값 색상, tooltip 지원.
+ */
 declare function Progress({ value, warning, danger, tooltip, className, }: ProgressProps): react_jsx_runtime.JSX.Element;
 
 interface Item<T extends string> {
@@ -727,8 +741,18 @@ interface SegmentedControlProps<T extends string> {
     value: T;
     onChange: (value: T) => void;
     items: readonly Item<T>[];
+    /**
+     * true면 컨테이너를 w-full로 펼치고 각 세그먼트를 균등분할(flex-1)한다.
+     * 기본 false — 콘텐츠 폭(각 세그먼트가 라벨 길이에 맞춰짐).
+     */
+    block?: boolean;
+    className?: string;
 }
-declare function SegmentedControl<T extends string>({ value, onChange, items, }: SegmentedControlProps<T>): react_jsx_runtime.JSX.Element;
+/**
+ * 세그먼트 컨트롤(값/필터 선택) — Tabs `variant="pill"`과 동일 스타일.
+ * 균등분할이 필요하면 `block`. 라벨이 칸보다 길면 말줄임되고, 그 경우에만 hover 시 툴팁으로 전체 표시.
+ */
+declare function SegmentedControl<T extends string>({ value, onChange, items, block, className, }: SegmentedControlProps<T>): react_jsx_runtime.JSX.Element;
 
 interface SearchInputProps extends Omit<React$1.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'type'> {
     value: string;
@@ -882,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;
@@ -906,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> {
@@ -948,51 +986,71 @@ interface TabsProps<T extends string = string> {
     allTabs: TabItem<T>[];
     current: T;
     onTabChange: (value: T) => void;
-    /**
-     * "pill"      — 회색 배경 컨테이너 + 흰 배경 active (segment control 스타일)
-     * "underline" — 하단 밑줄 active (default)
-     */
-    variant?: 'pill' | 'underline';
     /** 컨테이너를 w-full로 펼치고 각 탭 버튼을 균등 분할(flex-1)합니다 */
     block?: boolean;
-    /** Tailwind height 클래스 (e.g. "h-[36px]"). 지정 시 내부 버튼 패딩도 자동 조정됩니다. */
-    height?: string;
     className?: string;
 }
 /**
- * 디자인 시스템에서는 동일 뷰의 데이터 전환을 위해 ToggleGroup 대신 Tabs를 사용합니다.
- * Tabs의 원래 목적으로도 사용하며, 한 화면에 두 가지의 의미로 Tabs를 사용하지 않습니다.
+ * 하단 밑줄(underline) 탭 — 서로 다른 콘텐츠 영역 전환(진짜 탭).
+ * Radix Tabs 기반: role=tablist/tab, roving tabindex, ←/→ 키보드,
+ * `activationMode="manual"`(화살표는 포커스만, 클릭/Enter/Space로 활성화).
+ *
+ * 세그먼트/값·필터 선택(구 `variant="pill"`)은 SegmentedControl을 사용한다.
+ *
+ * NOTE: 콘텐츠 패널은 사용처가 바깥에서 `current`로 렌더하므로 Tabs.Content(및 aria-controls↔
+ *   aria-labelledby 연결)가 없다. 키보드·역할 a11y는 확보했으나 탭↔패널 연결은 미완.
+ *   구 pill 사용처 이관 및 릴리스 체크리스트: docs/todo/tabs-segmented-control.md
  */
-declare function Tabs<T extends string = string>({ allTabs, current, onTabChange, variant, block, height, className, }: TabsProps<T>): react_jsx_runtime.JSX.Element;
+declare function Tabs<T extends string = string>({ allTabs, current, onTabChange, block, className, }: TabsProps<T>): react_jsx_runtime.JSX.Element;
 
-interface ToggleProps extends Omit<React$1.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
-    pressed?: boolean;
-    onPressedChange?: (pressed: boolean) => void;
-    size?: 'sm' | 'md' | 'lg';
-}
+/**
+ * 좌우 여백은 아이콘 단독 사용 시 정사각(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";
 };
 declare const toggleBaseClasses = "inline-flex items-center justify-center gap-1.5 font-medium tracking-tight transition-colors select-none";
-declare function Toggle({ pressed, onPressedChange, size, disabled, className, children, ...props }: ToggleProps): react_jsx_runtime.JSX.Element;
+interface ToggleProps extends Omit<React$1.ComponentPropsWithoutRef<typeof Toggle$1.Root>, 'asChild'> {
+    size?: 'sm' | 'md' | 'lg';
+}
+/**
+ * 두 상태(on/off) 토글 버튼 — Radix Toggle 기반(aria-pressed, data-state=on/off, Space/Enter 키보드).
+ * `pressed`/`onPressedChange`로 제어한다.
+ */
+declare function Toggle({ size, className, ...props }: ToggleProps): react_jsx_runtime.JSX.Element;
 
 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';
@@ -1005,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 {
     /** 사용량 (바이트 또는 임의 단위) */
@@ -1256,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;
 
 /**
  * 사용자 메시지 말풍선.