@designbasekorea/ui-contracts 0.1.2

package/src/components.ts

@@ -0,0 +1,753 @@
+/**
+ * 컴포넌트별 API 계약.
+ *
+ * 웹(@designbasekorea/ui-wc)과 React Native(@designbasekorea/ui-native)가
+ * 공유하는 컴포넌트의 variant/size/type 값은 전부 여기서 나온다.
+ * 한쪽에만 있는 컴포넌트(db-code-block, db-animation-background 등)는
+ * 여기에 넣지 않는다 — 공유하지 않는 것을 계약에 넣으면 계약이 죽는다.
+ *
+ * 값을 바꾸면 양쪽 구현이 동시에 타입 에러를 낸다. 그게 이 파일의 목적이다.
+ */
+
+import {
+    FEEDBACK_TONES,
+    RADIUS_SCALE,
+    SIZE_SML,
+    SIZE_XS_2XL,
+    SIZE_XS_XL,
+    type FeedbackTone,
+    type RadiusScale,
+    type SizeSML,
+    type SizeXs2Xl,
+    type SizeXsXl,
+} from './primitives.js';
+
+// ─────────────────────────────────────────────────────────────
+// Button
+// ─────────────────────────────────────────────────────────────
+
+export const BUTTON_VARIANTS = [
+    'primary',
+    'secondary',
+    'tertiary',
+    'destructive',
+    'ghost',
+    'accent',
+] as const;
+export type ButtonVariant = (typeof BUTTON_VARIANTS)[number];
+
+/**
+ * 구 이름 → 현 이름. 버튼은 *동작*을 나타내므로 `destructive` 가 맞고,
+ * badge/chip/tooltip 등 *상태* 축은 `danger` 를 그대로 쓴다.
+ *
+ * 이미 배포된 `variant="danger"` 를 깨지 않기 위해 별칭을 남긴다.
+ * `coerceWithAliases` 가 이 표를 거쳐 정본 값으로 접는다.
+ */
+export const BUTTON_VARIANT_ALIASES: Readonly<Record<string, ButtonVariant>> = {
+    danger: 'destructive',
+};
+
+export const BUTTON_SIZES = SIZE_SML;
+export type ButtonSize = SizeSML;
+
+export const BUTTON_RADII = RADIUS_SCALE;
+export type ButtonRadius = RadiusScale;
+
+/** accent variant 에서만 의미가 있다 */
+/**
+ * accent 버튼의 표현 방식.
+ *
+ * `primary` 가 먹색이 되면서 accent 가 브랜드 색을 쓰는 일상적인 버튼이 됐다.
+ * 그래서 기본은 `solid` 이고, 나머지는 의도적으로 고르는 장식이다.
+ * `prism` 은 테마의 프리즘 축(`--db-prism-*`)을 따르므로 프리셋을 바꾸면 함께 바뀐다.
+ */
+export const BUTTON_ACCENT_STYLES = ['solid', 'gradient', 'backlight', 'outline', 'prism'] as const;
+export type ButtonAccentStyle = (typeof BUTTON_ACCENT_STYLES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Input
+// ─────────────────────────────────────────────────────────────
+
+export const INPUT_SIZES = SIZE_SML;
+export type InputSize = SizeSML;
+
+/**
+ * 웹의 <input type> 에 대응한다. RN 에는 type 개념이 없고 keyboardType /
+ * secureTextEntry / autoComplete 조합으로 매핑되므로, RN 구현체는 이 값을
+ * 받아 내부적으로 변환한다. 값 집합 자체는 공유해야 API 가 통일된다.
+ */
+export const INPUT_TYPES = [
+    'text',
+    'email',
+    'password',
+    'url',
+    'search',
+    'tel',
+    'number',
+] as const;
+export type InputType = (typeof INPUT_TYPES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Card
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * 웹 기준으로 확정. RN 에 있던 elevated/outlined/filled 는 제거한다.
+ * (웹 db-card.scss 가 default/flat 만 구현하고 있고, 그림자·테두리 변형은
+ *  현재 hoverable/clickable 같은 별도 modifier 로 처리된다)
+ */
+export const CARD_VARIANTS = ['default', 'flat'] as const;
+export type CardVariant = (typeof CARD_VARIANTS)[number];
+
+export const CARD_SIZES = SIZE_SML;
+export type CardSize = SizeSML;
+
+// ─────────────────────────────────────────────────────────────
+// Badge
+// ─────────────────────────────────────────────────────────────
+
+export const BADGE_VARIANTS = [
+    'primary',
+    'secondary',
+    'info',
+    'success',
+    'warning',
+    'danger',
+] as const;
+export type BadgeVariant = (typeof BADGE_VARIANTS)[number];
+
+export const BADGE_SIZES = SIZE_SML;
+export type BadgeSize = SizeSML;
+
+/**
+ * 표시 형태. 웹은 이 축을 `style` 이라고 불렀지만 `type` 으로 통일한다.
+ * (`style` 은 RN 에서 사실상 예약어이고, 나머지 컴포넌트도 `type` 을 쓴다)
+ */
+export const BADGE_TYPES = ['dot', 'number', 'text', 'outlined'] as const;
+export type BadgeType = (typeof BADGE_TYPES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Avatar
+// ─────────────────────────────────────────────────────────────
+
+export const AVATAR_SIZES = SIZE_XS_2XL;
+export type AvatarSize = SizeXs2Xl;
+
+export const AVATAR_VARIANTS = [
+    'default',
+    'primary',
+    'success',
+    'warning',
+    'danger',
+    'info',
+] as const;
+export type AvatarVariant = (typeof AVATAR_VARIANTS)[number];
+
+export const AVATAR_STATUSES = ['online', 'offline', 'away', 'busy'] as const;
+export type AvatarStatus = (typeof AVATAR_STATUSES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Chip
+// ─────────────────────────────────────────────────────────────
+
+/**
+ * `outlined` 는 여기 없다. 색상 축(variant)과 테두리 축(outlined)이 섞여 있던 것을
+ * 분리했다 — outlined 는 별도 boolean prop 이며, 모든 색상과 조합 가능하다.
+ */
+export const CHIP_VARIANTS = [
+    'default',
+    'primary',
+    'success',
+    'warning',
+    'danger',
+    'info',
+    'neutral',
+] as const;
+export type ChipVariant = (typeof CHIP_VARIANTS)[number];
+
+export const CHIP_SIZES = SIZE_SML;
+export type ChipSize = SizeSML;
+
+// ─────────────────────────────────────────────────────────────
+// Divider
+// ─────────────────────────────────────────────────────────────
+
+export const DIVIDER_COLORS = [
+    'primary',
+    'secondary',
+    'success',
+    'warning',
+    'danger',
+    'muted',
+] as const;
+export type DividerColor = (typeof DIVIDER_COLORS)[number];
+
+export const DIVIDER_ORIENTATIONS = ['horizontal', 'vertical'] as const;
+export type DividerOrientation = (typeof DIVIDER_ORIENTATIONS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Spinner
+// ─────────────────────────────────────────────────────────────
+
+export const SPINNER_SIZES = SIZE_XS_XL;
+export type SpinnerSize = SizeXsXl;
+
+/**
+ * RN 은 ActivityIndicator 가 circular 만 제공하므로 나머지는 직접 그려야 한다.
+ * 미구현 타입은 circular 로 폴백하되, 계약에서 빼지는 않는다.
+ */
+export const SPINNER_TYPES = ['circular', 'dots', 'bars', 'pulse', 'ripple'] as const;
+export type SpinnerType = (typeof SPINNER_TYPES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Toggle / Checkbox / Radio
+// ─────────────────────────────────────────────────────────────
+
+export const TOGGLE_SIZES = SIZE_SML;
+export type ToggleSize = SizeSML;
+
+/** 선택 상태의 시각적 톤. neutral 은 브랜드 컬러 없이 배경 레이어로 선택을 표현한다. */
+export const TOGGLE_VARIANTS = ['default', 'neutral'] as const;
+export type ToggleVariant = (typeof TOGGLE_VARIANTS)[number];
+
+export const CHECKBOX_SIZES = SIZE_SML;
+export type CheckboxSize = SizeSML;
+
+export const RADIO_SIZES = SIZE_SML;
+export type RadioSize = SizeSML;
+
+// ─────────────────────────────────────────────────────────────
+// Alert / Toast
+// ─────────────────────────────────────────────────────────────
+
+/** `error` 아님 — danger 로 통일했다. FEEDBACK_TONES 참고. */
+export const ALERT_VARIANTS = ['default', ...FEEDBACK_TONES] as const;
+export type AlertVariant = 'default' | FeedbackTone;
+
+export const ALERT_SIZES = SIZE_SML;
+export type AlertSize = SizeSML;
+
+/**
+ * 웹은 이 축을 `status` attribute 로 불렀지만 `variant` 로 통일한다.
+ * 나머지 컴포넌트가 전부 variant 를 쓰는데 Toast 만 달랐다.
+ */
+export const TOAST_VARIANTS = ['default', ...FEEDBACK_TONES] as const;
+export type ToastVariant = 'default' | FeedbackTone;
+
+/**
+ * 웹 `toast()` 헬퍼가 이미 배포한 값 그대로다.
+ * RN 은 화면이 좁아 좌/중앙/우 차이가 작지만, 같은 이름을 받아야 코드가 옮겨진다.
+ */
+export const TOAST_POSITIONS = [
+    'top-left',
+    'top-center',
+    'top-right',
+    'bottom-left',
+    'bottom-center',
+    'bottom-right',
+] as const;
+export type ToastPosition = (typeof TOAST_POSITIONS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Modal / BottomSheet
+// ─────────────────────────────────────────────────────────────
+
+export const MODAL_SIZES = ['s', 'm', 'l', 'xl', 'full'] as const;
+export type ModalSize = (typeof MODAL_SIZES)[number];
+
+export const BOTTOM_SHEET_VARIANTS = [
+    'default',
+    'persistent',
+    'temporary',
+    'fullscreen',
+] as const;
+export type BottomSheetVariant = (typeof BOTTOM_SHEET_VARIANTS)[number];
+
+export const BOTTOM_SHEET_ANIMATIONS = ['slide', 'fade', 'scale', 'none'] as const;
+export type BottomSheetAnimation = (typeof BOTTOM_SHEET_ANIMATIONS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Tabs
+// ─────────────────────────────────────────────────────────────
+
+export const TABS_VARIANTS = ['default', 'pills'] as const;
+export type TabsVariant = (typeof TABS_VARIANTS)[number];
+
+export const TABS_SIZES = SIZE_SML;
+export type TabsSize = SizeSML;
+
+export const TABS_ORIENTATIONS = ['horizontal', 'vertical'] as const;
+export type TabsOrientation = (typeof TABS_ORIENTATIONS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Select
+// ─────────────────────────────────────────────────────────────
+
+export const SELECT_SIZES = SIZE_SML;
+export type SelectSize = SizeSML;
+
+/** 드롭다운이 트리거 위/아래 중 어디에 펼쳐지는지 */
+export const SELECT_POSITIONS = ['bottom', 'top'] as const;
+export type SelectPosition = (typeof SELECT_POSITIONS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Navbar / BottomNavigation
+// ─────────────────────────────────────────────────────────────
+
+export const NAVBAR_VARIANTS = ['default', 'transparent'] as const;
+export type NavbarVariant = (typeof NAVBAR_VARIANTS)[number];
+
+export const NAVBAR_SIZES = SIZE_SML;
+export type NavbarSize = SizeSML;
+
+/**
+ * RN 에는 CSS position 개념이 없다. sticky/fixed 는 네이티브에서 동일하게
+ * "스크롤과 무관하게 상단 고정" 으로 해석되고, static 만 스크롤을 따라간다.
+ */
+export const NAVBAR_POSITIONS = ['fixed', 'sticky', 'static'] as const;
+export type NavbarPosition = (typeof NAVBAR_POSITIONS)[number];
+
+export const NAVIGATION_RAIL_SIZES = SIZE_SML;
+export const NAVIGATION_RAIL_LABEL_DISPLAYS = ['tooltip', 'always'] as const;
+export type NavigationRailLabelDisplay = (typeof NAVIGATION_RAIL_LABEL_DISPLAYS)[number];
+
+export const BOTTOM_NAV_SIZES = SIZE_SML;
+export type BottomNavSize = SizeSML;
+
+export const BOTTOM_NAV_BACKGROUNDS = ['default', 'glass', 'transparent'] as const;
+export type BottomNavBackground = (typeof BOTTOM_NAV_BACKGROUNDS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// SearchBar
+// ─────────────────────────────────────────────────────────────
+
+export const SEARCH_BAR_SIZES = SIZE_SML;
+export type SearchBarSize = SizeSML;
+
+export const SEARCH_BAR_RECENT_LAYOUTS = ['vertical', 'horizontal'] as const;
+export type SearchBarRecentLayout = (typeof SEARCH_BAR_RECENT_LAYOUTS)[number];
+
+// ─────────────────────────────────────────────────────────────
+// Skeleton
+// ─────────────────────────────────────────────────────────────
+
+export const SKELETON_VARIANTS = [
+    'text',
+    'circular',
+    'rectangular',
+    'rounded',
+] as const;
+export type SkeletonVariant = (typeof SKELETON_VARIANTS)[number];
+
+export const SKELETON_SIZES = SIZE_XS_XL;
+export type SkeletonSize = SizeXsXl;
+
+// ─────────────────────────────────────────────────────────────
+// ProgressBar
+// ─────────────────────────────────────────────────────────────
+
+export const PROGRESS_BAR_VARIANTS = ['default', 'primary', ...FEEDBACK_TONES] as const;
+export type ProgressBarVariant = 'default' | 'primary' | FeedbackTone;
+
+export const PROGRESS_BAR_SIZES = SIZE_SML;
+export type ProgressBarSize = SizeSML;
+
+export const PROGRESS_BAR_STYLES = ['solid', 'striped', 'animated'] as const;
+export type ProgressBarStyle = (typeof PROGRESS_BAR_STYLES)[number];
+
+// ─────────────────────────────────────────────────────────────
+// 컴포넌트 로컬 enum 이관분
+//
+// 아래 상수들은 원래 각 ui-wc 컴포넌트 파일이 직접 선언하던 것이다.
+// 같은 값을 두 곳에서 선언하면 한쪽에 값이 추가될 때 다른 쪽이 조용히 뒤처지므로
+// 정본을 여기로 옮겼다. ui-native 는 필요한 것부터 이 상수를 채택한다.
+// ─────────────────────────────────────────────────────────────
+
+// db-accordion
+export const ACCORDION_VARIANTS = ['default', 'bordered', 'separated', 'contained'] as const;
+export type AccordionVariant = (typeof ACCORDION_VARIANTS)[number];
+export const ACCORDION_SIZES = SIZE_SML;
+export type AccordionSize = SizeSML;
+
+// db-banner
+export const BANNER_VARIANTS = ['primary', 'secondary', 'tertiary', 'outline', 'image'] as const;
+export type BannerVariant = (typeof BANNER_VARIANTS)[number];
+export const BANNER_SIZES = SIZE_SML;
+export type BannerSize = SizeSML;
+
+// db-breadcrumbs
+export const BREADCRUMBS_VARIANTS = ['default', 'contained', 'underlined'] as const;
+export type BreadcrumbsVariant = (typeof BREADCRUMBS_VARIANTS)[number];
+export const BREADCRUMBS_SIZES = SIZE_SML;
+export type BreadcrumbsSize = SizeSML;
+
+// db-empty-state
+export const EMPTY_STATE_VARIANTS = ['no-data', 'no-results', 'no-access', 'error', 'onboarding'] as const;
+export type EmptyStateVariant = (typeof EMPTY_STATE_VARIANTS)[number];
+export const EMPTY_STATE_SIZES = SIZE_SML;
+export type EmptyStateSize = SizeSML;
+
+// db-logo
+export const LOGO_VARIANTS = ['default', 'original', 'primary', 'secondary', 'light', 'dark', 'white'] as const;
+export type LogoVariant = (typeof LOGO_VARIANTS)[number];
+export const LOGO_SIZES = ['xs', 's', 'm', 'l', 'xl'] as const;
+export type LogoSize = (typeof LOGO_SIZES)[number];
+
+// db-menu-item
+export const MENU_ITEM_VARIANTS = ['default', 'primary', 'success', 'warning', 'danger', 'info'] as const;
+export type MenuItemVariant = (typeof MENU_ITEM_VARIANTS)[number];
+export const MENU_ITEM_SIZES = SIZE_SML;
+export type MenuItemSize = SizeSML;
+
+// db-pagination
+export const PAGINATION_VARIANTS = ['default', 'outlined', 'minimal'] as const;
+export type PaginationVariant = (typeof PAGINATION_VARIANTS)[number];
+export const PAGINATION_SIZES = SIZE_SML;
+export type PaginationSize = SizeSML;
+
+// db-kanban
+export const KANBAN_SIZES = SIZE_SML;
+export type KanbanSize = SizeSML;
+
+// db-activity-heatmap
+export const ACTIVITY_HEATMAP_SIZES = SIZE_SML;
+export type ActivityHeatmapSize = SizeSML;
+
+export const ACTIVITY_HEATMAP_COLOR_SCHEMES = ['green', 'primary'] as const;
+export type ActivityHeatmapColorScheme = (typeof ACTIVITY_HEATMAP_COLOR_SCHEMES)[number];
+
+// db-chat-message
+export const CHAT_MESSAGE_ROLES = ['user', 'assistant', 'system'] as const;
+export type ChatMessageRole = (typeof CHAT_MESSAGE_ROLES)[number];
+
+// db-ai-glow
+export const AI_GLOW_VARIANTS = ['aurora', 'brand'] as const;
+export type AiGlowVariant = (typeof AI_GLOW_VARIANTS)[number];
+
+export const AI_GLOW_STATES = ['thinking', 'working', 'listening'] as const;
+export type AiGlowState = (typeof AI_GLOW_STATES)[number];
+
+export const AI_GLOW_SIZES = SIZE_SML;
+export type AiGlowSize = SizeSML;
+
+// db-chat-orb
+export const CHAT_ORB_SIZES = SIZE_XS_XL;
+export type ChatOrbSize = SizeXsXl;
+
+export const CHAT_ORB_VARIANTS = ['aurora', 'ocean', 'emerald', 'violet', 'mono'] as const;
+export type ChatOrbVariant = (typeof CHAT_ORB_VARIANTS)[number];
+
+export const CHAT_ORB_STATES = ['idle', 'thinking', 'listening'] as const;
+export type ChatOrbState = (typeof CHAT_ORB_STATES)[number];
+
+export const CHAT_ORB_THEMES = ['auto', 'light', 'dark'] as const;
+export type ChatOrbTheme = (typeof CHAT_ORB_THEMES)[number];
+
+// db-chat-welcome
+export const CHAT_WELCOME_ALIGNS = ['center', 'left'] as const;
+export type ChatWelcomeAlign = (typeof CHAT_WELCOME_ALIGNS)[number];
+
+// db-chat-widget
+export const CHAT_WIDGET_VIEWS = ['home', 'messages', 'conversation', 'help', 'article'] as const;
+export type ChatWidgetView = (typeof CHAT_WIDGET_VIEWS)[number];
+
+export const CHAT_WIDGET_POSITIONS = ['bottom-right', 'bottom-left'] as const;
+export type ChatWidgetPosition = (typeof CHAT_WIDGET_POSITIONS)[number];
+
+// db-container
+export const CONTAINER_SIZES = ['s', 'm', 'l', 'xl', 'full'] as const;
+export type ContainerSize = (typeof CONTAINER_SIZES)[number];
+
+export const CONTAINER_PADDINGS = ['none', 's', 'm', 'l', 'xl'] as const;
+export type ContainerPadding = (typeof CONTAINER_PADDINGS)[number];
+
+// db-date-picker
+export const DATE_PICKER_SIZES = SIZE_SML;
+export type DatePickerSize = SizeSML;
+
+export const DATE_PICKER_VARIANTS = ['default', 'outlined', 'filled'] as const;
+export type DatePickerVariant = (typeof DATE_PICKER_VARIANTS)[number];
+
+// db-download-progress
+export const DOWNLOAD_PROGRESS_STATUSES = ['downloading', 'paused', 'error', 'complete'] as const;
+export type DownloadProgressStatus = (typeof DOWNLOAD_PROGRESS_STATUSES)[number];
+
+export const DOWNLOAD_PROGRESS_POSITIONS = ['bottom-right', 'bottom-left', 'bottom-center', 'top-right', 'top-left', 'top-center'] as const;
+export type DownloadProgressPosition = (typeof DOWNLOAD_PROGRESS_POSITIONS)[number];
+
+// db-drawer
+export const DRAWER_POSITIONS = ['left', 'right', 'top', 'bottom'] as const;
+export type DrawerPosition = (typeof DRAWER_POSITIONS)[number];
+
+export const DRAWER_SIZES = ['s', 'm', 'l', 'xl', 'full'] as const;
+export type DrawerSize = (typeof DRAWER_SIZES)[number];
+
+// db-dropdown
+export const DROPDOWN_SIZES = SIZE_SML;
+export type DropdownSize = SizeSML;
+
+export const DROPDOWN_PLACEMENTS = ['bottom-left', 'bottom-right', 'top-left', 'top-right'] as const;
+export type DropdownPlacement = (typeof DROPDOWN_PLACEMENTS)[number];
+
+export const DROPDOWN_TRIGGER_VARIANTS = ['primary', 'secondary', 'tertiary', 'danger', 'ghost'] as const;
+export type DropdownTriggerVariant = (typeof DROPDOWN_TRIGGER_VARIANTS)[number];
+
+// db-dropzone
+export const DROPZONE_SIZES = SIZE_SML;
+export type DropzoneSize = SizeSML;
+
+export const DROPZONE_VARIANTS = ['default', 'outlined', 'filled'] as const;
+export type DropzoneVariant = (typeof DROPZONE_VARIANTS)[number];
+
+// db-email-verify
+export const EMAIL_VERIFY_SIZES = SIZE_SML;
+export type EmailVerifySize = SizeSML;
+
+// db-file-uploader
+export const FILE_UPLOADER_SIZES = SIZE_SML;
+export type FileUploaderSize = SizeSML;
+
+export const FILE_UPLOADER_VARIANTS = ['default', 'outlined', 'filled'] as const;
+export type FileUploaderVariant = (typeof FILE_UPLOADER_VARIANTS)[number];
+
+// db-floating-action-button
+export const FLOATING_ACTION_BUTTON_SIZES = SIZE_SML;
+export type FloatingActionButtonSize = SizeSML;
+
+export const FLOATING_ACTION_BUTTON_VARIANTS = ['primary', 'secondary', 'tertiary'] as const;
+export type FloatingActionButtonVariant = (typeof FLOATING_ACTION_BUTTON_VARIANTS)[number];
+
+// db-footer
+export const FOOTER_VARIANTS = ['default', 'compact', 'minimal'] as const;
+export type FooterVariant = (typeof FOOTER_VARIANTS)[number];
+
+export const FOOTER_SIZES = SIZE_SML;
+export type FooterSize = SizeSML;
+
+// db-indicator
+export const INDICATOR_TYPES = ['dots', 'numbers', 'line', 'dot-line', 'slide', 'fill', 'combined'] as const;
+export type IndicatorType = (typeof INDICATOR_TYPES)[number];
+
+export const INDICATOR_SIZES = SIZE_SML;
+export type IndicatorSize = SizeSML;
+
+export const INDICATOR_DIRECTIONS = ['horizontal', 'vertical'] as const;
+export type IndicatorDirection = (typeof INDICATOR_DIRECTIONS)[number];
+
+// db-lightbox
+export const LIGHTBOX_SIZES = ['s', 'm', 'l', 'xl'] as const;
+export type LightboxSize = (typeof LIGHTBOX_SIZES)[number];
+
+// db-otp-input
+export const OTP_INPUT_SIZES = SIZE_SML;
+export type OtpInputSize = SizeSML;
+
+// db-page-header
+export const PAGE_HEADER_VARIANTS = ['default', 'minimal'] as const;
+export type PageHeaderVariant = (typeof PAGE_HEADER_VARIANTS)[number];
+
+export const PAGE_HEADER_ALIGNS = ['center', 'left'] as const;
+export type PageHeaderAlign = (typeof PAGE_HEADER_ALIGNS)[number];
+
+// db-phone-verify
+export const PHONE_VERIFY_SIZES = SIZE_SML;
+export type PhoneVerifySize = SizeSML;
+
+// db-popover
+export const POPOVER_PLACEMENTS = ['top', 'bottom', 'left', 'right', 'top-start', 'top-end', 'bottom-start', 'bottom-end', 'left-start', 'left-end', 'right-start', 'right-end'] as const;
+export type PopoverPlacement = (typeof POPOVER_PLACEMENTS)[number];
+
+export const POPOVER_SIZES = SIZE_SML;
+export type PopoverSize = SizeSML;
+
+export const POPOVER_VARIANTS = ['default', 'primary', 'success', 'warning', 'danger', 'info'] as const;
+export type PopoverVariant = (typeof POPOVER_VARIANTS)[number];
+
+export const POPOVER_TRIGGERS = ['click', 'hover', 'focus', 'manual'] as const;
+export type PopoverTrigger = (typeof POPOVER_TRIGGERS)[number];
+
+// db-progress
+export const PROGRESS_SIZES = SIZE_SML;
+export type ProgressSize = SizeSML;
+
+export const PROGRESS_VARIANTS = ['default', 'success', 'warning', 'danger'] as const;
+export type ProgressVariant = (typeof PROGRESS_VARIANTS)[number];
+
+export const PROGRESS_CIRCULAR_STYLES = ['default', 'minimal'] as const;
+export type ProgressCircularStyle = (typeof PROGRESS_CIRCULAR_STYLES)[number];
+
+// db-section
+export const SECTION_SIZES = SIZE_SML;
+export type SectionSize = SizeSML;
+
+// db-sidebar
+export const SIDEBAR_SIZES = SIZE_SML;
+export type SidebarSize = SizeSML;
+
+export const SIDEBAR_THEMES = ['default', 'dark', 'light'] as const;
+export type SidebarTheme = (typeof SIDEBAR_THEMES)[number];
+
+export const SIDEBAR_VARIANTS = ['default', 'wrapper'] as const;
+export type SidebarVariant = (typeof SIDEBAR_VARIANTS)[number];
+
+export const SIDEBAR_POSITIONS = ['left', 'right'] as const;
+export type SidebarPosition = (typeof SIDEBAR_POSITIONS)[number];
+
+export const SIDEBAR_PANEL_MODES = ['auto', 'adjacent', 'replace'] as const;
+export type SidebarPanelMode = (typeof SIDEBAR_PANEL_MODES)[number];
+
+export const SIDEBAR_CUSTOM_NAV_SLOTS = ['nav-top', 'nav', 'nav-bottom'] as const;
+export type SidebarCustomNavSlot = (typeof SIDEBAR_CUSTOM_NAV_SLOTS)[number];
+
+// db-stat
+export const STAT_SIZES = SIZE_SML;
+export type StatSize = SizeSML;
+
+export const STAT_VARIANTS = ['default', 'minimal', 'card', 'colored', 'iconBox'] as const;
+export type StatVariant = (typeof STAT_VARIANTS)[number];
+
+export const STAT_LAYOUTS = ['horizontal', 'vertical', 'reverse'] as const;
+export type StatLayout = (typeof STAT_LAYOUTS)[number];
+
+export const STAT_COLORS = ['primary', 'secondary', 'success', 'warning', 'error', 'info', 'custom'] as const;
+export type StatColor = (typeof STAT_COLORS)[number];
+
+// db-table
+export const TABLE_SIZES = SIZE_SML;
+export type TableSize = SizeSML;
+
+export const TABLE_VARIANTS = ['default', 'striped', 'hoverable'] as const;
+export type TableVariant = (typeof TABLE_VARIANTS)[number];
+
+// db-testimonial
+export const TESTIMONIAL_VARIANTS = ['list', 'card', 'logo', 'image', 'text'] as const;
+export type TestimonialVariant = (typeof TESTIMONIAL_VARIANTS)[number];
+
+// db-textarea
+export const TEXTAREA_SIZES = SIZE_SML;
+export type TextareaSize = SizeSML;
+
+// db-time-picker
+export const TIME_PICKER_SIZES = SIZE_SML;
+export type TimePickerSize = SizeSML;
+
+export const TIME_PICKER_FORMATS = ['12h', '24h', '12h-with-seconds', '24h-with-seconds'] as const;
+export type TimePickerFormat = (typeof TIME_PICKER_FORMATS)[number];
+
+/** TimePicker 드롭다운의 기준점. auto는 뷰포트 공간에 맞춰 상·하/좌·우를 계산한다. */
+export const TIME_PICKER_DROPDOWN_POSITIONS = [
+    'auto',
+    'bottom-start',
+    'bottom-end',
+    'top-start',
+    'top-end',
+] as const;
+export type TimePickerDropdownPosition = (typeof TIME_PICKER_DROPDOWN_POSITIONS)[number];
+
+// db-tooltip
+export const TOOLTIP_POSITIONS = ['top', 'bottom', 'left', 'right', 'top-start', 'top-end', 'bottom-start', 'bottom-end', 'left-start', 'left-end', 'right-start', 'right-end'] as const;
+export type TooltipPosition = (typeof TOOLTIP_POSITIONS)[number];
+
+export const TOOLTIP_SIZES = SIZE_SML;
+export type TooltipSize = SizeSML;
+
+export const TOOLTIP_VARIANTS = ['default', 'primary', 'success', 'warning', 'danger', 'info'] as const;
+export type TooltipVariant = (typeof TOOLTIP_VARIANTS)[number];
+
+// db-top-banner
+export const TOP_BANNER_VARIANTS = ['primary', 'white', 'dark'] as const;
+export type TopBannerVariant = (typeof TOP_BANNER_VARIANTS)[number];
+
+// db-two-factor
+export const TWO_FACTOR_SIZES = SIZE_SML;
+export type TwoFactorSize = SizeSML;
+
+// ─────────────────────────────────────────────────────────────
+// ui-wc 전용 컴포넌트 enum
+//
+// 웹 커스텀 엘리먼트도 attribute 를 통해 임의의 문자열을 받기 때문에,
+// 공개 허용값과 런타임 fallback 을 같은 계약으로 유지한다.
+// ─────────────────────────────────────────────────────────────
+
+export const AD_BANNER_VARIANTS = ['primary', 'secondary', 'success', 'warning', 'error'] as const;
+export const AD_BANNER_SIZES = SIZE_SML;
+
+export const ANIMATION_TEXT_SIZES = ['xs', 's', 'm', 'l', 'xl', '2xl', '3xl'] as const;
+export const ANIMATION_TEXT_ALIGNS = ['left', 'center', 'right', 'justify'] as const;
+
+export const APP_BADGE_SIZES = SIZE_SML;
+
+export const AUDIO_PLAYER_VARIANTS = ['default', 'minimal', 'compact', 'full'] as const;
+export const AUDIO_PLAYER_SIZES = ['s', 'm', 'l', 'xl'] as const;
+
+export const CAROUSEL_VARIANTS = ['default', 'cards', 'gallery', 'hero', 'testimonial'] as const;
+export const CAROUSEL_SIZES = ['s', 'm', 'l', 'xl'] as const;
+
+export const COLOR_PICKER_SIZES = SIZE_SML;
+export const COLOR_PICKER_POSITIONS = ['bottom-start', 'bottom-end', 'top-start', 'top-end'] as const;
+
+export const COLOR_SWATCH_SIZES = SIZE_SML;
+
+export const CONFIRM_VARIANTS = ['default', 'info', 'success', 'warning', 'danger'] as const;
+export const CONFIRM_SIZES = SIZE_SML;
+
+export const COUNTDOWN_VARIANTS = ['default', 'compact', 'minimal'] as const;
+export const COUNTDOWN_SIZES = SIZE_SML;
+
+export const GRADIENT_VARIANTS = ['default', 'animated', 'mesh'] as const;
+export const GRADIENT_SIZES = ['s', 'm', 'l', 'xl', 'full'] as const;
+
+export const GRID_BACKGROUND_SIZES = SIZE_SML;
+export const LABEL_SIZES = SIZE_SML;
+
+export const LIST_VARIANTS = ['default', 'minimal', 'bordered', 'card', 'navigation'] as const;
+export const LIST_SIZES = SIZE_SML;
+
+export const MARKDOWN_EDITOR_VARIANTS = ['default', 'filled', 'outlined'] as const;
+export const MARKDOWN_EDITOR_SIZES = SIZE_SML;
+
+export const MARQUEE_VARIANTS = ['default', 'filled', 'outlined'] as const;
+export const MARQUEE_SIZES = SIZE_SML;
+
+export const PROGRESS_STEP_SIZES = SIZE_SML;
+export const RANDOM_GRADIENT_TONES = ['light', 'vivid', 'dark'] as const;
+
+export const RATING_VARIANTS = ['default', 'minimal', 'card', 'inline', 'large'] as const;
+export const RATING_SIZES = SIZE_SML;
+
+export const REORDER_VARIANTS = ['default', 'bordered', 'filled', 'minimal'] as const;
+export const REORDER_SIZES = SIZE_SML;
+
+export const SECTION_ALIGNS = ['left', 'center', 'right'] as const;
+export const SECTION_APP_DOWNLOAD_SIZES = SIZE_SML;
+export const SECTION_CONTACT_SIZES = SIZE_SML;
+export const SECTION_CTA_VARIANTS = ['default', 'dark', 'light', 'gradient', 'tinted'] as const;
+export const SECTION_CTA_SIZES = SIZE_SML;
+export const SECTION_FAQ_SIZES = SIZE_SML;
+export const SECTION_FEATURE_SIZES = SIZE_SML;
+export const SECTION_FEATURE_GRID_SIZES = SIZE_SML;
+export const SECTION_HERO_VARIANTS = ['default', 'showcase', 'split', 'overlay', 'centered'] as const;
+export const SECTION_LOGO_CLOUD_VARIANTS = ['grid', 'inline', 'minimal', 'marquee'] as const;
+export const SECTION_LOGO_CLOUD_SIZES = SIZE_SML;
+export const SECTION_PRICING_SIZES = SIZE_SML;
+export const SECTION_STATS_SIZES = SIZE_SML;
+export const SECTION_TESTIMONIALS_VARIANTS = ['grid', 'list', 'carousel', 'cards'] as const;
+export const SECTION_TESTIMONIALS_SIZES = SIZE_SML;
+
+export const SHARE_VARIANTS = ['button', 'dropdown', 'modal', 'inline'] as const;
+export const SHARE_SIZES = SIZE_SML;
+export const SHARE_POSITIONS = ['top', 'bottom', 'left', 'right'] as const;
+
+export const SIGNATURE_VARIANTS = ['dashed', 'outlined'] as const;
+
+export const TIMELINE_VARIANTS = ['default', 'alternate', 'left', 'right'] as const;
+export const TIMELINE_SIZES = SIZE_SML;
+
+export const TOOLBAR_VARIANTS = ['default', 'filled', 'outlined', 'ghost'] as const;
+export const TOOLBAR_SIZES = SIZE_SML;
+export const TOOLBAR_POSITIONS = ['top', 'bottom', 'left', 'right', 'floating'] as const;
+
+export const VIDEO_PLAYER_VARIANTS = ['default', 'minimal', 'theater'] as const;
+export const VIDEO_PLAYER_SIZES = ['s', 'm', 'l', 'xl'] as const;
+export const YOUTUBE_PLAYER_VARIANTS = ['default', 'minimal', 'theater', 'full'] as const;
+export const YOUTUBE_PLAYER_SIZES = ['s', 'm', 'l', 'xl'] as const;