@bigtablet/design-system 3.11.0 → 3.13.0

package/dist/index.js

@@ -243,6 +243,7 @@ function useAnchoredPosition({
   }, [open, placement, gap, padding, anchorRef, floatingRef]);
   return state;
 }
+var SKIP_AUTOFOCUS_ATTR = "data-focus-trap-skip-autofocus";
 var FOCUSABLE_SELECTORS = [
   "a[href]",
   "button:not([disabled])",
@@ -263,8 +264,9 @@ function useFocusTrap(containerRef, isActive) {
     };
     let wasTabIndexAdded = false;
     const focusableElements = getFocusableElements();
-    if (focusableElements.length > 0) {
-      focusableElements[0].focus();
+    const initialTarget = Array.from(focusableElements).find((el) => !el.hasAttribute(SKIP_AUTOFOCUS_ATTR)) ?? focusableElements[0];
+    if (initialTarget) {
+      initialTarget.focus();
     } else {
       container.setAttribute("tabindex", "-1");
       wasTabIndexAdded = true;
@@ -542,15 +544,28 @@ var EmptyState = ({
   description,
   action,
   size = "md",
+  fillHeight,
   className,
   ...props
 }) => {
-  return /* @__PURE__ */ jsxs("div", { className: cn("empty_state", `empty_state_size_${size}`, className), ...props, children: [
-    illustration && /* @__PURE__ */ jsx("div", { className: "empty_state_illustration", "aria-hidden": "true", children: illustration }),
-    title && /* @__PURE__ */ jsx("h3", { className: "empty_state_title", children: title }),
-    description && /* @__PURE__ */ jsx("p", { className: "empty_state_description", children: description }),
-    action && /* @__PURE__ */ jsx("div", { className: "empty_state_action", children: action })
-  ] });
+  return /* @__PURE__ */ jsxs(
+    "div",
+    {
+      className: cn(
+        "empty_state",
+        `empty_state_size_${size}`,
+        fillHeight && "empty_state_fill_height",
+        className
+      ),
+      ...props,
+      children: [
+        illustration && /* @__PURE__ */ jsx("div", { className: "empty_state_illustration", "aria-hidden": "true", children: illustration }),
+        title && /* @__PURE__ */ jsx("h3", { className: "empty_state_title", children: title }),
+        description && /* @__PURE__ */ jsx("p", { className: "empty_state_description", children: description }),
+        action && /* @__PURE__ */ jsx("div", { className: "empty_state_action", children: action })
+      ]
+    }
+  );
 };
 var DEFAULT_ICON_SIZE = {
   page: 48,
@@ -667,11 +682,12 @@ var BottomNavSpacer = ({ className, ...props }) => {
 var Breadcrumb = ({
   items,
   separator,
+  navLabel = "\uD604\uC7AC \uC704\uCE58",
   className,
   ...props
 }) => {
   const sep = separator ?? /* @__PURE__ */ jsx(ChevronRight, { size: iconSize.xs, "aria-hidden": "true" });
-  return /* @__PURE__ */ jsx("nav", { "aria-label": "Breadcrumb", className: cn("breadcrumb", className), ...props, children: /* @__PURE__ */ jsx("ol", { className: "breadcrumb_list", children: items.map((item, idx) => {
+  return /* @__PURE__ */ jsx("nav", { "aria-label": navLabel, className: cn("breadcrumb", className), ...props, children: /* @__PURE__ */ jsx("ol", { className: "breadcrumb_list", children: items.map((item, idx) => {
     const isLast = idx === items.length - 1;
     return (
       // biome-ignore lint/suspicious/noArrayIndexKey: breadcrumb items have stable order
@@ -1419,7 +1435,7 @@ var Popover = ({
               ref: popoverRef,
               role: "dialog",
               tabIndex: -1,
-              "aria-label": ariaLabelledby ? ariaLabel : ariaLabel ?? "Dialog",
+              "aria-label": ariaLabel,
               "aria-labelledby": ariaLabelledby,
               style,
               className: cn("popover", className),
@@ -2433,6 +2449,29 @@ var MediaCard = ({
     ] })
   ] });
 };
+var Prose = ({ size = "md", className, children, ref, ...props }) => {
+  const rootRef = React16.useRef(null);
+  React16.useImperativeHandle(ref, () => rootRef.current, []);
+  useSafeLayoutEffect(() => {
+    const root = rootRef.current;
+    if (!root) return;
+    const targets = Array.from(root.querySelectorAll("pre, table"));
+    const sync = () => {
+      for (const el of targets) {
+        if (el.scrollWidth > el.clientWidth) el.setAttribute("tabindex", "0");
+        else el.removeAttribute("tabindex");
+      }
+    };
+    sync();
+    if (typeof ResizeObserver === "undefined") return;
+    const observer = new ResizeObserver(sync);
+    observer.observe(root);
+    for (const el of targets) observer.observe(el);
+    return () => observer.disconnect();
+  }, [children]);
+  return /* @__PURE__ */ jsx("div", { ref: rootRef, className: cn("prose", `prose_size_${size}`, className), ...props, children });
+};
+Prose.displayName = "Prose";
 var Skeleton = ({
   variant = "text",
   width,
@@ -2873,7 +2912,7 @@ var LinearProgress = ({
     }
   );
 };
-var Spinner = ({ size = 24, ariaLabel = "Loading" }) => {
+var Spinner = ({ size = 24, ariaLabel = "\uB85C\uB529 \uC911" }) => {
   return /* @__PURE__ */ jsx(
     "span",
     {
@@ -2951,7 +2990,8 @@ var ToastItemComponent = ({ item, onRemove, closeAriaLabel }) => {
 var ToastProvider = ({
   children,
   maxCount = 5,
-  closeAriaLabel = "Close"
+  closeAriaLabel = "\uB2EB\uAE30",
+  regionLabel = "\uC54C\uB9BC"
 }) => {
   const [toasts, setToasts] = React16.useState([]);
   const isMounted = useIsMounted();
@@ -2977,7 +3017,7 @@ var ToastProvider = ({
           role: "region",
           "aria-live": "polite",
           "aria-atomic": "false",
-          "aria-label": "Notifications",
+          "aria-label": regionLabel,
           children: toasts.map((item) => /* @__PURE__ */ jsx(
             ToastItemComponent,
             {
@@ -3018,7 +3058,7 @@ var TopLoading = ({
   color,
   height = 3,
   isLoading = true,
-  ariaLabel = "Page loading"
+  ariaLabel = "\uD398\uC774\uC9C0 \uB85C\uB529 \uC911"
 }) => {
   if (!isLoading) return null;
   const isIndeterminate = progress === void 0;
@@ -3050,7 +3090,7 @@ var Dropdown = (props) => {
   const {
     id,
     label,
-    placeholder = "Select\u2026",
+    placeholder = "\uC120\uD0DD\u2026",
     options,
     disabled,
     size = "md",
@@ -3399,11 +3439,11 @@ var DatePicker = ({
   disabled,
   fullWidth = true,
   width,
-  yearLabel = "Year",
-  monthLabel = "Month",
-  dayLabel = "Day",
-  minDateSrFormat = "Minimum date: {date}",
-  selectableRangeUntilTodaySrText = "Selectable up to today"
+  yearLabel = "\uB144",
+  monthLabel = "\uC6D4",
+  dayLabel = "\uC77C",
+  minDateSrFormat = "\uCD5C\uC18C \uB0A0\uC9DC: {date}",
+  selectableRangeUntilTodaySrText = "\uC624\uB298\uAE4C\uC9C0 \uC120\uD0DD \uAC00\uB2A5"
 }) => {
   const groupId = React16.useId();
   const constraintId = React16.useId();
@@ -3582,7 +3622,7 @@ var DatePicker = ({
   ] });
 };
 var FileInput = ({
-  label = "Choose file",
+  label = "\uD30C\uC77C \uC120\uD0DD",
   onFiles,
   supportingText,
   preview = false,
@@ -4413,7 +4453,7 @@ var Textarea = ({
 };
 Textarea.displayName = "Textarea";
 var ClearIcon = () => /* @__PURE__ */ jsx(X, { size: iconSize.lg, "aria-hidden": "true" });
-var DEFAULT_PASSWORD_TOGGLE_LABELS = { show: "Show password", hide: "Hide password" };
+var DEFAULT_PASSWORD_TOGGLE_LABELS = { show: "\uBE44\uBC00\uBC88\uD638 \uD45C\uC2DC", hide: "\uBE44\uBC00\uBC88\uD638 \uC228\uAE30\uAE30" };
 var TextField = ({
   id,
   label,
@@ -4421,6 +4461,7 @@ var TextField = ({
   supportingText,
   error,
   success,
+  identifier,
   leadingIcon,
   trailingIcon,
   leadingAction,
@@ -4428,6 +4469,7 @@ var TextField = ({
   showPasswordToggle,
   passwordToggleLabels,
   clearable,
+  clearLabel = "\uC9C0\uC6B0\uAE30",
   type,
   fullWidth,
   size = "md",
@@ -4507,7 +4549,7 @@ var TextField = ({
       type: "button",
       className: "text_field_clear",
       onClick: handleClear,
-      "aria-label": "Clear",
+      "aria-label": clearLabel,
       disabled: props.disabled,
       children: /* @__PURE__ */ jsx(ClearIcon, {})
     }
@@ -4529,7 +4571,7 @@ var TextField = ({
             {
               id: inputId,
               ref,
-              className: "text_field_input",
+              className: cn("text_field_input", identifier && "text_field_input_identifier"),
               "aria-invalid": isError,
               "aria-describedby": helperId,
               "aria-label": !showLabel ? label : void 0,
@@ -4661,14 +4703,15 @@ var Pagination = ({
   totalPages,
   onPageChange,
   onChange,
-  prevLabel = "Previous page",
-  nextLabel = "Next page"
+  prevLabel = "\uC774\uC804 \uD398\uC774\uC9C0",
+  nextLabel = "\uB2E4\uC74C \uD398\uC774\uC9C0",
+  navLabel = "\uD398\uC774\uC9C0 \uC774\uB3D9"
 }) => {
   const emit = onPageChange ?? onChange;
   const prevDisabled = page <= 1;
   const nextDisabled = page >= totalPages;
   const items = React16.useMemo(() => getPaginationItems(page, totalPages), [page, totalPages]);
-  return /* @__PURE__ */ jsxs("nav", { className: "pagination", "aria-label": "Pagination", children: [
+  return /* @__PURE__ */ jsxs("nav", { className: "pagination", "aria-label": navLabel, children: [
     /* @__PURE__ */ jsx(
       "button",
       {
@@ -4725,25 +4768,38 @@ var Drawer = ({
   title,
   footer,
   closeOnOverlay = true,
+  dismissible,
   showCloseIcon = true,
   closeLabel = "\uB2EB\uAE30",
   ariaLabel,
+  onExited,
   children,
   className,
   ...props
 }) => {
+  const lastContentRef = React16.useRef({ children, title, footer });
+  if (open) lastContentRef.current = { children, title, footer };
+  const content = open ? { children, title, footer } : lastContentRef.current;
+  const overlayDismissible = dismissible ?? closeOnOverlay;
+  const escapeDismissible = dismissible ?? true;
   const panelRef = React16.useRef(null);
+  const pressedOverlayRef = React16.useRef(false);
   const titleId = React16.useId();
   const [shouldRender, setShouldRender] = React16.useState(open);
   const reduced = useReducedMotion();
   const isMounted = useIsMounted();
   useFocusTrap(panelRef, open && isMounted);
-  useOverlayEscape(open && isMounted, () => onClose?.());
+  useOverlayEscape(open && isMounted, () => {
+    if (escapeDismissible) onClose?.();
+  });
   if (open && !shouldRender) setShouldRender(true);
   const overlayStyle = useSpringPresence({
     visible: open,
     from: "translateY(0px)",
-    onExitComplete: () => setShouldRender(false)
+    onExitComplete: () => {
+      setShouldRender(false);
+      onExited?.();
+    }
   });
   const slideFrom = SLIDE_FROM[placement];
   const slideRest = placement === "bottom" ? "translateY(0%)" : "translateX(0%)";
@@ -4760,7 +4816,7 @@ var Drawer = ({
   }, [open]);
   if (!open && !shouldRender) return null;
   if (typeof document === "undefined" || !isMounted) return null;
-  const hasTitle = !!title;
+  const hasTitle = !!content.title;
   const sizeValue = typeof size === "number" ? `${size}px` : size;
   const panelSizeStyle = placement === "bottom" ? { height: sizeValue } : { width: sizeValue };
   return createPortal(
@@ -4772,8 +4828,16 @@ var Drawer = ({
         role: "dialog",
         "aria-modal": "true",
         "aria-labelledby": hasTitle && !ariaLabel ? titleId : void 0,
-        "aria-label": !hasTitle ? ariaLabel ?? "Dialog" : ariaLabel,
-        onClick: () => closeOnOverlay && onClose?.(),
+        "aria-label": ariaLabel,
+        onPointerDown: (e) => {
+          pressedOverlayRef.current = e.target === e.currentTarget;
+        },
+        onClick: (e) => {
+          if (!overlayDismissible) return;
+          if (e.target !== e.currentTarget) return;
+          if (!pressedOverlayRef.current) return;
+          onClose?.();
+        },
         children: /* @__PURE__ */ jsxs(
           animated.div,
           {
@@ -4781,8 +4845,6 @@ var Drawer = ({
             ...props,
             className: cn("drawer_panel", className),
             style: { ...props.style, ...panelStyle, ...panelSizeStyle },
-            role: "document",
-            onClick: (e) => e.stopPropagation(),
             onKeyDown: (e) => {
               if (e.key !== "Escape") e.stopPropagation();
             },
@@ -4797,9 +4859,12 @@ var Drawer = ({
                   children: /* @__PURE__ */ jsx(X, { size: iconSize.md, "aria-hidden": "true" })
                 }
               ),
-              title && /* @__PURE__ */ jsx("div", { className: "drawer_header", children: /* @__PURE__ */ jsx("h2", { id: titleId, className: "drawer_title", children: title }) }),
-              children && /* @__PURE__ */ jsx("div", { className: "drawer_body", children }),
-              footer && /* @__PURE__ */ jsx("div", { className: "drawer_footer", children: footer })
+              content.title && /* @__PURE__ */ jsx("div", { className: "drawer_header", children: /* @__PURE__ */ jsx("h2", { id: titleId, className: "drawer_title", children: content.title }) }),
+              content.children && // 본문이 스크롤 컨테이너라 키보드로도 스크롤할 수 있어야 한다(axe
+              // `scrollable-region-focusable`). 다만 초기 포커스 대상에서는 제외한다 - 안쪽에
+              // 첫 입력이 있는데 빈 wrapper 에 포커스가 놓이면 열자마자 어디에 있는지 알 수 없다.
+              /* @__PURE__ */ jsx("div", { className: "drawer_body", tabIndex: 0, "data-focus-trap-skip-autofocus": "", children: content.children }),
+              content.footer && /* @__PURE__ */ jsx("div", { className: "drawer_footer", children: content.footer })
             ]
           }
         )
@@ -4813,6 +4878,7 @@ var Modal = ({
   open,
   onClose,
   closeOnOverlay = true,
+  dismissible,
   width = 480,
   title,
   description,
@@ -4823,14 +4889,23 @@ var Modal = ({
   children,
   className,
   ariaLabel,
+  onExited,
   ...props
 }) => {
+  const lastContentRef = React16.useRef({ children, title, description, footer });
+  if (open) lastContentRef.current = { children, title, description, footer };
+  const content = open ? { children, title, description, footer } : lastContentRef.current;
+  const overlayDismissible = dismissible ?? closeOnOverlay;
+  const escapeDismissible = dismissible ?? true;
   const panelRef = React16.useRef(null);
+  const pressedOverlayRef = React16.useRef(false);
   const titleId = React16.useId();
   const [shouldRender, setShouldRender] = React16.useState(open);
   const isMounted = useIsMounted();
   useFocusTrap(panelRef, open && isMounted);
-  useOverlayEscape(open && isMounted, () => onClose?.());
+  useOverlayEscape(open && isMounted, () => {
+    if (escapeDismissible) onClose?.();
+  });
   if (open && !shouldRender) setShouldRender(true);
   const reduced = useReducedMotion();
   const overlayStyle = useSpring({
@@ -4838,7 +4913,9 @@ var Modal = ({
     immediate: reduced,
     config: { tension: 280, friction: 28, clamp: !open },
     onRest: (result) => {
-      if (!open && result.finished) setShouldRender(false);
+      if (open || !result.finished) return;
+      setShouldRender(false);
+      onExited?.();
     }
   });
   const panelStyle = useSpring({
@@ -4854,7 +4931,7 @@ var Modal = ({
   }, [open]);
   if (!open && !shouldRender) return null;
   if (typeof document === "undefined" || !isMounted) return null;
-  const hasTitle = !!title;
+  const hasTitle = !!content.title;
   return createPortal(
     /* @__PURE__ */ jsx(
       animated.div,
@@ -4864,8 +4941,16 @@ var Modal = ({
         role: "dialog",
         "aria-modal": "true",
         "aria-labelledby": hasTitle && !ariaLabel ? titleId : void 0,
-        "aria-label": !hasTitle ? ariaLabel ?? "Dialog" : ariaLabel,
-        onClick: () => closeOnOverlay && onClose?.(),
+        "aria-label": ariaLabel,
+        onPointerDown: (e) => {
+          pressedOverlayRef.current = e.target === e.currentTarget;
+        },
+        onClick: (e) => {
+          if (!overlayDismissible) return;
+          if (e.target !== e.currentTarget) return;
+          if (!pressedOverlayRef.current) return;
+          onClose?.();
+        },
         children: /* @__PURE__ */ jsxs(
           animated.div,
           {
@@ -4873,26 +4958,21 @@ var Modal = ({
             ...props,
             className: cn("modal_panel", className),
             style: { ...props.style, ...panelStyle, width },
-            role: "document",
-            onClick: (e) => e.stopPropagation(),
             onKeyDown: (e) => {
               if (e.key !== "Escape") e.stopPropagation();
             },
             children: [
-              showCloseIcon && onClose && /* @__PURE__ */ jsx(
-                "button",
-                {
-                  type: "button",
-                  className: "modal_close",
-                  onClick: onClose,
-                  "aria-label": closeLabel,
-                  children: /* @__PURE__ */ jsx(X, { size: iconSize.md, "aria-hidden": "true" })
-                }
-              ),
-              title && /* @__PURE__ */ jsx("h2", { id: titleId, className: "modal_title", children: title }),
-              description && /* @__PURE__ */ jsx("div", { className: "modal_description", children: description }),
-              children && /* @__PURE__ */ jsx("div", { className: "modal_body", children }),
-              footer && /* @__PURE__ */ jsx("div", { className: cn("modal_footer", `modal_footer_${footerAlign}`), children: footer })
+              showCloseIcon && onClose && /* @__PURE__ */ jsx("button", { type: "button", className: "modal_close", onClick: onClose, "aria-label": closeLabel, children: /* @__PURE__ */ jsx(X, { size: iconSize.md, "aria-hidden": "true" }) }),
+              content.title && /* @__PURE__ */ jsx("h2", { id: titleId, className: "modal_title", children: content.title }),
+              content.description && /* @__PURE__ */ jsx("div", { className: "modal_description", children: content.description }),
+              content.children && // 본문이 스크롤 컨테이너라 키보드로도 스크롤할 수 있어야 한다(axe
+              // `scrollable-region-focusable`). 넘치는지 여부를 측정해 조건부로 주는 방법도 있지만
+              // ResizeObserver 를 들일 만큼의 이득이 없고, 포커스 트랩 안에서 탭 정지 하나가
+              // 늘어나는 정도의 비용이다.
+              // 다만 초기 포커스 대상에서는 제외한다 - 안쪽에 첫 입력이 있는데 빈 wrapper 에
+              // 포커스가 놓이면 열자마자 어디에 있는지 알 수 없다.
+              /* @__PURE__ */ jsx("div", { className: "modal_body", tabIndex: 0, "data-focus-trap-skip-autofocus": "", children: content.children }),
+              content.footer && /* @__PURE__ */ jsx("div", { className: cn("modal_footer", `modal_footer_${footerAlign}`), children: content.footer })
             ]
           }
         )
@@ -5078,4 +5158,4 @@ var Stack = ({
   );
 };
 
-export { Accordion, AlertProvider, Avatar, Badge, BottomNav, BottomNavItem, BottomNavSpacer, Breadcrumb, Button, Card, Checkbox, Chip, Container, DatePicker, Divider, Drawer, Dropdown, EmptyState, ErrorState, FileInput, Grid, Hero, Icon, IconButton, ImageCropper, LinearProgress, ListItem, MediaCard, Menu, Modal, NavBar, NavLink, OtpInput, Pagination, Popover, Radio, RadioGroup, Section, Sidebar, SidebarItem, SidebarSection, Skeleton, Spinner, Stack, Tab, TabList, TabPanel, Table, Tabs, TextField, Textarea, ThemeProvider, ToastProvider, Toggle, Tooltip, TopLoading, 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 };
+export { Accordion, AlertProvider, Avatar, Badge, BottomNav, BottomNavItem, BottomNavSpacer, Breadcrumb, Button, Card, Checkbox, Chip, Container, DatePicker, Divider, Drawer, Dropdown, EmptyState, ErrorState, FileInput, Grid, Hero, Icon, IconButton, ImageCropper, LinearProgress, ListItem, MediaCard, Menu, Modal, NavBar, NavLink, OtpInput, Pagination, Popover, Prose, Radio, RadioGroup, Section, Sidebar, SidebarItem, SidebarSection, Skeleton, Spinner, Stack, Tab, TabList, TabPanel, Table, Tabs, TextField, Textarea, ThemeProvider, ToastProvider, Toggle, Tooltip, TopLoading, 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 };

package/dist/styles/a11y/_index.scss

@@ -12,7 +12,9 @@ $focus_ring_success: var(--bt-focus-ring-success);
 // WCAG 2.1 SC 2.5.5 권장 최소: 44×44
 
 $tap_min_size:           44px;  // a11y 최소 권장
-$tap_target_dense:       32px;  // 데스크탑 인라인 폼, 컴팩트 UI
+$tap_target_dense:       32px;  // 데스크탑 인라인 폼, 컴팩트 UI. 인터랙티브 컨트롤의 하한이다
+                                //   - 터치 입력이 있는 화면에서는 responsive_height 로 승급할 것
+                                //   - 예외: 마우스 전용 내부 도구(admin 등)는 28px 까지 허용
 $tap_target_compact:     40px;  // 데스크탑 기본
 $tap_target_comfortable: 48px;  // 모바일/터치 기본 (44 초과)
 $tap_target_spacious:    56px;  // 강조 CTA, 풀스크린 액션
@@ -44,3 +46,48 @@ $tap_target_spacious:    56px;  // 강조 CTA, 풀스크린 액션
     }
   }
 }
+
+// ── Visually hidden ───────────────────────────────────────────────────────
+// 시각적으로 숨기되 보조기기에는 남긴다. 라이브 리전, 아이콘 버튼의 텍스트 라벨,
+// 스크린리더 전용 표 헤더 등. `display: none` · `visibility: hidden` 은 접근성 트리에서도
+// 빠지므로 대신 쓸 수 없다.
+//
+// `clip: rect()` 는 CSS Masking 에서 deprecated 지만 구형 폴백으로 함께 둔다. `clip-path`
+// 단독은 일부 조합에서 요소가 잘리지 않는다.
+@mixin visually_hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+// 조건부로 숨기는 자리(브레이크포인트·상태에 따라 다시 보여야 하는 라벨 등)에서 위를 되돌린다.
+// 짝을 손으로 쓰면 한쪽에 속성을 추가할 때 다른 쪽을 빠뜨린다 - `clip-path` 를 되돌리지 않아
+// 라벨이 계속 잘려 있던 것이 실제로 있었던 실수다.
+@mixin visually_hidden_reset {
+  position: static;
+  width: auto;
+  height: auto;
+  padding: 0;
+  margin: 0;
+  overflow: visible;
+  clip: auto;
+  clip-path: none;
+  white-space: normal;
+}
+
+// 포커스를 받으면 드러난다. 스킵 링크("본문으로 건너뛰기") 패턴 - 평소엔 안 보이지만
+// 키보드 사용자가 Tab 을 누르면 나타나야 한다.
+@mixin visually_hidden_focusable {
+  @include visually_hidden;
+
+  &:focus-visible {
+    @include visually_hidden_reset;
+  }
+}

package/dist/styles/border-width/_index.scss

@@ -1,3 +1,6 @@
+@use "sass:list";
+@use "../colors" as colors;
+
 // ── Base border-width ────────────────────────────────────────────────────────
 
 $border_width_0: 0px;
@@ -10,3 +13,29 @@ $border_width_none:      $border_width_0;
 $border_width_standard:  $border_width_1;
 $border_width_thick:     $border_width_2;
 $border_width_indicator: $border_width_2;
+
+// ── Hairline mixin ───────────────────────────────────────────────────────────
+//
+// 1px 경계선용 단축. `border: $border_width_standard solid $color_border_default` 는
+// `border: 1px solid #E5E5E5` 보다 길어서, 실측상 소비 앱 SCSS 에 `1px` 하드코딩이
+// 232 건 남아 있었다. 짧게 쓸 수 있어야 실제로 토큰을 쓴다.
+//
+// @example
+// ```scss
+// .card   { @include token.hairline; }              // 사방
+// .header { @include token.hairline(bottom); }      // 한 면
+// .active { @include token.hairline(left, token.$color_border_hover); }
+// ```
+
+
+@mixin hairline($side: all, $color: colors.$color_border_default) {
+  @if $side == all {
+    border: $border_width_standard solid $color;
+  } @else if list.index(top right bottom left, $side) {
+    border-#{$side}: $border_width_standard solid $color;
+  } @else {
+    // 검증이 없으면 `hairline(letf)` 같은 오타가 컴파일을 통과해 `border-letf` 라는
+    // 무효 속성을 조용히 만든다. 소비 앱에 권장하는 공개 API 라 여기서 끊는다.
+    @error "token.hairline: $side 는 all · top · right · bottom · left 중 하나여야 합니다 (받은 값: #{$side})";
+  }
+}

package/dist/styles/typography/_index.scss

@@ -145,8 +145,37 @@ $letter_spacing_tight:  0.32px;
   white-space: nowrap;
 }
 
+// 한글 줄바꿈. `word-break: break-word` 는 어절 중간에서 끊어 "안녕하세 / 요" 를 만든다.
+// 표준값이 아니고, 명세상 `word-break: normal` + `overflow-wrap: anywhere` 와 같게 동작한다.
+// keep-all 이 어절을 지키고, 끊을 수 없는 긴 영문·URL 만 overflow-wrap 이 처리한다.
+// 텍스트를 줄바꿈하는 모든 컴포넌트는 이 믹스인을 쓴다 (Button·Toast·Tooltip).
+//
+// `break-word` 가 아니라 `anywhere` 를 쓴다. 눈에 보이는 줄바꿈 지점은 둘이 완전히 같지만
+// (120·60px 폭에서 한글·혼합 문자열 실측 결과 동일), min-content 폭이 다르다 —
+// break-word 는 최장 단어(122px), anywhere 는 한 글자(13px). flex item 의 기본
+// min-width: auto 는 min-content 아래로 줄지 못하므로 break-word 면 좁은 컨테이너를 넘친다
+// (실측: 120px 컨테이너에서 98px 초과). anywhere 는 min-width: 0 없이도 넘치지 않고,
+// 텍스트가 inline-flex 의 직접 자식인 vanilla `.bt-button` 처럼 익명 flex item 이라
+// min-width 를 줄 선택자조차 없는 경우까지 함께 해결한다.
+@mixin wrap_keep_all {
+  overflow-wrap: anywhere;
+  word-break: keep-all;
+}
+
 // ── Numeric (v3.1) ────────────────────────────────────────────────────────
 // 매출/지표 표시할 때 숫자 자릿수 정렬.
 
 @mixin tabular_nums  { font-variant-numeric: tabular-nums; }
 @mixin slashed_zero  { font-variant-numeric: slashed-zero; }
+
+// ── Legibility ────────────────────────────────────────────────────────────
+// Pretendard 기본 글자꼴은 l · I · 1 이 거의 같고 0 과 O 도 헷갈린다. 사용자가 한 글자씩
+// 옮겨 적는 값(아이디·인증코드·시리얼·사업자번호)에서 오탈자를 만든다.
+// cv05 = l 에 꼬리, cv08 = I 에 세리프. Pretendard 가 아닌 폴백 폰트는 두 feature 를
+// 그냥 무시하므로 안전하다.
+// 주의: slashed-zero 를 포함하므로 tabular_nums / slashed_zero 와 같은 선택자에서
+// 겹쳐 쓰면 안 된다 - 셋 다 font-variant-numeric 이라 뒤에 온 것만 남는다.
+@mixin legible_identifiers {
+  font-feature-settings: "cv05" 1, "cv08" 1;
+  font-variant-numeric: slashed-zero;
+}