@uniai-fe/uds-primitives 0.0.16 → 0.0.18

package/README.md

@@ -1,6 +1,6 @@
 # @uniai-fe/uds-primitives
 
-`@uniai-fe/uds-foundation` 토큰 위에 Radix UI 컴포넌트를 얇게 감싼 **기초 UI 컴포넌트 컬렉션**입니다. Next.js 등 React 런타임에서 바로 import해 버튼·입력·네비게이션 등 공통 요소를 일관된 스타일로 사용할 수 있습니다.
+`@uniai-fe/uds-foundation` 토큰 위에 Radix UI 컴포넌트를 얇게 감싼 **기초 UI 컴포넌트 컬렉션**입니다. Next.js 등 React 런타임에서 바로 import해 버튼·입력·네비게이션 등 공통 요소를 일관된 스타일로 사용할 수 있습니다. Templates(`@uniai-fe/uds-templates`) 패키지에서 사용하는 Phone Input/Email Verification Input/OneTimeCode Input 등의 인증 시나리오 컴포넌트도 이곳에서 제공합니다.
 
 ## 설치
 
@@ -192,8 +192,16 @@ src/components/{category}/
 ## 문서
 
 - `CONTEXT.md` 및 `CONTEXT-*.md`: 각 컴포넌트의 상태/진행/디자인 근거
+- `CONTEXT-INPUT.md`: Phone/Email/OneTimeCode 등 인증 입력 시나리오 규칙을 포함하며, templates `CONTEXT-SIGNUP*.md`와 항상 동기화해야 한다.
 - `RADIX-SIZE-GUIDE.md`: primitives 사이즈 체계와 Radix 매핑 규칙
 
+### Signup 인증 입력 컴포넌트
+
+- **PhoneInput**: 기본은 마스킹된 전화번호 입력만 제공한다. `onRequestCode`(optional)를 주입하면 인증요청 버튼이 우측 right 슬롯에 노출된다. Step1 User Info에서는 단순 입력만 필요하므로 optional props를 생략한다.
+- **EmailInput**: 이메일 입력 + 인증요청 버튼 + countdown + OneTimeCode 입력을 하나로 묶는다. `countdownText`, `codeVisible`, `codeLength`, `codeLabel`, `codeHelper`, `codeState`, `onCodeComplete`로 Step2 Verify & Agreement 상태를 제어한다.
+- **AuthCodeInput**: length 지정형 OneTimeCode grid. EmailInput 내부에서 사용하지만 서비스 앱도 직접 import할 수 있다.
+- 변경 시에는 다음 문서를 함께 업데이트한다: `packages/design/primitives/docs/CONTEXT-INPUT.md`, `packages/design/templates/docs/CONTEXT-SIGNUP.md`, `CONTEXT-SIGNUP-FLOW.md`, `packages/design/templates/docs/STORYBOOK.md`, `apps/design-storybook/src/stories/templates/auth/AuthSignup.stories.tsx`.
+
 * **컨벤션**: 모든 컴포넌트/스토리/문서는 slot/prefix/suffix 용어를 사용하지 않고, 레이아웃 기준(`header/body/footer`, 2단 구조는 `upper/lower`)과 `util*` 키워드를 사용한다. 인터랙션 함수는 `on*` 접두사를 사용하고, JSDoc `@param`은 depth 전체를 풀어 쓴다.
 
 필요한 컨텍스트를 확인한 뒤 컴포넌트를 import해 사용하면 됩니다.

package/dist/styles.css

@@ -1663,13 +1663,15 @@
   --theme-checkbox-surface: var(--color-common-100);
   --theme-checkbox-surface-selected: var(--color-primary-default);
   --theme-checkbox-surface-disabled: var(--color-neutral-95);
+  --theme-checkbox-surface-selected-disabled: rgba(26, 106, 255, 0.28);
   --theme-checkbox-label-color: var(--color-label-strong);
   --theme-checkbox-label-disabled: var(--color-label-disabled);
   --theme-checkbox-helper-color: var(--color-label-neutral);
   --theme-checkbox-helper-disabled: var(--color-label-disabled);
-  --theme-checkbox-icon-color: var(--color-common-100);
+  --theme-checkbox-icon-default: transparent;
+  --theme-checkbox-icon-selected: var(--color-common-100);
+  --theme-checkbox-icon-disabled-selected: var(--color-common-100);
   --theme-checkbox-focus-ring: rgba(2, 84, 255, 0.32);
-  --theme-checkbox-disabled-selected-opacity: 0.28;
 }
 
 .checkbox {
@@ -1695,7 +1697,6 @@
   border-radius: var(--theme-checkbox-control-radius-large);
 }
 .checkbox[data-disabled=true] {
-  opacity: 0.6;
   cursor: not-allowed;
 }
 
@@ -1703,49 +1704,64 @@
   box-shadow: 0 0 0 2px var(--theme-checkbox-focus-ring);
 }
 
-.checkbox-indicator {
+.checkbox-surface {
   inline-size: var(--theme-checkbox-indicator-size-medium);
   block-size: var(--theme-checkbox-indicator-size-medium);
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  color: var(--theme-checkbox-icon-color);
   border: var(--theme-checkbox-border-width) solid var(--theme-checkbox-border-color);
   border-radius: var(--theme-checkbox-control-radius-medium);
   background-color: var(--theme-checkbox-surface);
-  transition: background-color 0.15s ease, border-color 0.15s ease, color 0.15s ease, opacity 0.15s ease;
-}
-.checkbox-indicator svg {
-  display: block;
-  inline-size: auto;
-  block-size: auto;
-  max-inline-size: 100%;
-  max-block-size: 100%;
+  transition: background-color 0.15s ease, border-color 0.15s ease;
 }
 
-.checkbox[data-size=large] .checkbox-indicator {
+.checkbox[data-size=large] .checkbox-surface {
   inline-size: var(--theme-checkbox-indicator-size-large);
   block-size: var(--theme-checkbox-indicator-size-large);
   border-radius: var(--theme-checkbox-control-radius-large);
 }
 
-.checkbox[data-state=checked] .checkbox-indicator,
-.checkbox[data-state=indeterminate] .checkbox-indicator {
+.checkbox[data-state=checked] .checkbox-surface,
+.checkbox[data-state=indeterminate] .checkbox-surface {
   background-color: var(--theme-checkbox-surface-selected);
   border-color: var(--theme-checkbox-border-selected);
 }
 
-.checkbox[data-disabled=true] .checkbox-indicator {
+.checkbox[data-disabled=true] .checkbox-surface {
   background-color: var(--theme-checkbox-surface-disabled);
   border-color: var(--theme-checkbox-border-color);
-  opacity: 1;
+}
+
+.checkbox[data-disabled=true][data-state=checked] .checkbox-surface,
+.checkbox[data-disabled=true][data-state=indeterminate] .checkbox-surface {
+  background-color: var(--theme-checkbox-surface-selected-disabled);
+  border-color: var(--theme-checkbox-border-color);
+}
+
+.checkbox-indicator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--theme-checkbox-icon-default);
+  transition: color 0.15s ease;
+}
+.checkbox-indicator svg {
+  display: block;
+  inline-size: auto;
+  block-size: auto;
+  max-inline-size: 100%;
+  max-block-size: 100%;
+}
+
+.checkbox[data-state=checked] .checkbox-indicator,
+.checkbox[data-state=indeterminate] .checkbox-indicator {
+  color: var(--theme-checkbox-icon-selected);
 }
 
 .checkbox[data-disabled=true][data-state=checked] .checkbox-indicator,
 .checkbox[data-disabled=true][data-state=indeterminate] .checkbox-indicator {
-  background-color: var(--theme-checkbox-surface-selected);
-  border-color: var(--theme-checkbox-border-selected);
-  opacity: var(--theme-checkbox-disabled-selected-opacity);
+  color: var(--theme-checkbox-icon-disabled-selected);
 }
 
 .checkbox-field {
@@ -2165,6 +2181,8 @@ figure.chip {
   --theme-input-radius-tertiary: var(--theme-radius-large-2);
   --theme-input-label-color: var(--color-label-standard);
   --theme-input-helper-color: var(--color-label-neutral);
+  --theme-input-helper-success-color: var(--color-success);
+  --theme-input-helper-error-color: var(--color-error);
   --theme-input-helper-disabled-color: var(--color-label-disabled);
   --theme-input-label-accent-color: var(--color-primary-default);
   --theme-input-label-error-color: var(--color-error);
@@ -2248,24 +2266,53 @@ figure.chip {
   padding-block: var(--spacing-padding-4);
   background-color: transparent;
 }
+.input-field[data-priority=secondary][data-state=active], .input-field[data-priority=secondary][data-state=focused] {
+  border-bottom-color: var(--theme-input-border-active);
+  border-bottom-width: var(--theme-input-border-width-emphasis);
+}
+.input-field[data-priority=secondary][data-state=success] {
+  border-bottom-color: var(--theme-input-border-success);
+  border-bottom-width: var(--theme-input-border-width-emphasis);
+}
+.input-field[data-priority=secondary][data-state=error] {
+  border-bottom-color: var(--theme-input-border-error);
+  border-bottom-width: var(--theme-input-border-width-emphasis);
+}
+.input-field[data-priority=secondary][data-state=disabled] {
+  border-bottom-color: var(--theme-input-border-underline-disabled);
+  border-bottom-width: var(--theme-input-border-width-default);
+}
 .input-field[data-priority=tertiary] {
   border-radius: var(--theme-input-radius-tertiary);
   background-color: var(--theme-input-surface);
   min-height: var(--theme-input-height-tertiary);
-  flex-wrap: wrap;
   row-gap: var(--spacing-gap-1);
   column-gap: var(--theme-input-gap);
+  flex-wrap: wrap;
+  align-items: center;
+}
+.input-field[data-priority=tertiary] .input-field__control {
+  display: grid;
+  grid-template-columns: auto minmax(0, 1fr);
+  column-gap: var(--theme-input-gap);
+  row-gap: var(--spacing-gap-1);
+  align-items: center;
+  flex: 1 1 auto;
+  min-width: 0;
 }
 .input-field[data-priority=tertiary] .input-inline-label {
-  flex-basis: 100%;
+  grid-column: 1/-1;
+  margin: 0;
+  align-self: flex-start;
 }
 .input-field[data-priority=tertiary] .input-element {
   min-height: var(--theme-size-medium-2);
   width: auto;
   flex: 1 1 auto;
 }
-.input-field[data-priority=tertiary] .input-element + .input-affix {
-  margin-left: auto;
+.input-field[data-priority=tertiary] .input-field__utilities {
+  align-self: center;
+  margin-left: 0;
 }
 .input-field:not([data-priority=secondary])[data-state=active], .input-field:not([data-priority=secondary])[data-state=focused] {
   border-color: var(--theme-input-border-active);
@@ -2311,6 +2358,25 @@ figure.chip {
   box-shadow: none;
 }
 
+.input-field__control {
+  display: flex;
+  align-items: center;
+  gap: var(--theme-input-gap);
+  flex: 1 1 auto;
+  min-width: 0;
+}
+
+.input-field__utilities {
+  display: flex;
+  align-items: center;
+  gap: var(--spacing-gap-2, 8px);
+  flex-shrink: 0;
+  margin-left: var(--spacing-gap-3, 12px);
+}
+.input-field__utilities .input-affix {
+  margin-left: 0;
+}
+
 .input-inline-label {
   order: -2;
   flex-basis: 100%;
@@ -2340,7 +2406,7 @@ figure.chip {
 }
 
 .input-affix {
-  display: inline-flex;
+  display: flex;
   align-items: center;
   justify-content: center;
   min-width: 20px;
@@ -2414,8 +2480,7 @@ figure.chip {
   background-color: transparent;
 }
 
-.input-password-toggle,
-.input-action-button {
+.input-password-toggle {
   border: none;
   background: transparent;
   color: var(--theme-input-label-accent-color);
@@ -2425,8 +2490,7 @@ figure.chip {
   padding: 0;
   cursor: pointer;
 }
-.input-password-toggle:disabled,
-.input-action-button:disabled {
+.input-password-toggle:disabled {
   color: var(--theme-input-helper-disabled-color);
   cursor: not-allowed;
 }
@@ -2473,16 +2537,47 @@ figure.chip {
   color: var(--theme-input-helper-color);
 }
 
-.email-verification {
+.email-verification,
+.phone-verification {
   display: flex;
   flex-direction: column;
   gap: var(--spacing-gap-4);
 }
 
-.email-verification__countdown {
-  font-size: var(--font-caption-medium-size);
-  line-height: var(--font-caption-medium-line-height);
-  color: var(--theme-input-helper-color);
+.auth-code-input__actions,
+.email-verification__code-actions,
+.phone-verification__code-actions {
+  display: flex;
+  align-items: center;
+  justify-content: flex-end;
+  gap: var(--spacing-gap-3);
+  min-width: 0;
+}
+
+.auth-code-input__countdown,
+.email-verification__countdown,
+.phone-verification__countdown {
+  display: flex;
+  align-items: center;
+  font-weight: 500;
+  font-style: normal;
+  font-size: 13px;
+  line-height: 1em;
+  letter-spacing: -0.0025em;
+  color: var(--color-primary-default);
+  flex-shrink: 0;
+}
+
+.button.input-utility-button {
+  min-height: 32px;
+  padding: var(--spacing-padding-2, 4px) var(--spacing-padding-6, 24px);
+  border-radius: var(--shape-rounded-1, 8px);
+}
+.button.input-utility-button .button-label {
+  font-size: var(--font-body-xxsmall-size);
+  line-height: var(--font-body-xxsmall-line-height);
+  letter-spacing: var(--font-body-xxsmall-letter-spacing);
+  font-weight: var(--font-body-xxsmall-weight);
 }
 
 /* TODO(label): 스타일을 SOT 토큰 값으로 정의한다. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@uniai-fe/uds-primitives",
-  "version": "0.0.16",
+  "version": "0.0.18",
   "description": "UNIAI Design System; Primitives Components Package",
   "type": "module",
   "private": false,
@@ -14,7 +14,7 @@
   "publishConfig": {
     "access": "public"
   },
-  "packageManager": "pnpm@10.26.1",
+  "packageManager": "pnpm@10.26.2",
   "engines": {
     "node": ">=24",
     "pnpm": ">=10"

package/src/components/checkbox/img/check-large.svg

@@ -1,3 +1,3 @@
 <svg width="12" height="8" viewBox="0 0 12 8" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M0.699997 3.52844L4.23553 7.06398L10.5995 0.700012" stroke="white" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
+<path d="M0.699997 3.52844L4.23553 7.06398L10.5995 0.700012" stroke="currentColor" stroke-width="1.4" stroke-linecap="round" stroke-linejoin="round"/>
 </svg>

package/src/components/checkbox/img/check-medium.svg

@@ -1,3 +1,3 @@
 <svg width="10" height="7" viewBox="0 0 10 7" fill="none" xmlns="http://www.w3.org/2000/svg">
-<path d="M0.170857 3.35307C-0.0569492 3.12526 -0.0569492 2.75569 0.170857 2.52788C0.398662 2.30008 0.768239 2.30008 0.996045 2.52788L3.52973 5.06157L8.42044 0.170859C8.64824 -0.0569466 9.01782 -0.056947 9.24562 0.170859C9.47343 0.398665 9.47343 0.768242 9.24562 0.996047L3.94232 6.29935C3.83293 6.40874 3.68444 6.47025 3.52973 6.47025C3.37502 6.47025 3.22653 6.40874 3.11713 6.29935L0.170857 3.35307Z" fill="white"/>
+<path d="M0.170857 3.35307C-0.0569492 3.12526 -0.0569492 2.75569 0.170857 2.52788C0.398662 2.30008 0.768239 2.30008 0.996045 2.52788L3.52973 5.06157L8.42044 0.170859C8.64824 -0.0569466 9.01782 -0.056947 9.24562 0.170859C9.47343 0.398665 9.47343 0.768242 9.24562 0.996047L3.94232 6.29935C3.83293 6.40874 3.68444 6.47025 3.52973 6.47025C3.37502 6.47025 3.22653 6.40874 3.11713 6.29935L0.170857 3.35307Z" fill="currentColor"/>
 </svg>

package/src/components/checkbox/markup/Checkbox.tsx

@@ -6,6 +6,7 @@ import CheckLargeIcon from "../img/check-large.svg";
 import CheckMediumIcon from "../img/check-medium.svg";
 
 const CHECKBOX_CLASSNAME = "checkbox";
+const CHECKBOX_SURFACE_CLASSNAME = "checkbox-surface";
 const CHECKBOX_INDICATOR_CLASSNAME = "checkbox-indicator";
 const CHECKBOX_FIELD_CLASSNAME = "checkbox-field";
 const CHECKBOX_LABEL_WRAPPER_CLASSNAME = "checkbox-label-wrapper";
@@ -46,9 +47,11 @@ export const Checkbox = forwardRef<HTMLButtonElement, CheckboxProps>(
         className={clsx(CHECKBOX_CLASSNAME, className)}
         {...restProps}
       >
-        <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
-          <IndicatorIcon aria-hidden />
-        </CheckboxPrimitive.Indicator>
+        <span className={CHECKBOX_SURFACE_CLASSNAME} aria-hidden="true">
+          <CheckboxPrimitive.Indicator className={CHECKBOX_INDICATOR_CLASSNAME}>
+            <IndicatorIcon aria-hidden />
+          </CheckboxPrimitive.Indicator>
+        </span>
       </CheckboxPrimitive.Root>
     );
   },

package/src/components/checkbox/styles/index.scss

@@ -13,13 +13,15 @@
   --theme-checkbox-surface: var(--color-common-100);
   --theme-checkbox-surface-selected: var(--color-primary-default);
   --theme-checkbox-surface-disabled: var(--color-neutral-95);
+  --theme-checkbox-surface-selected-disabled: rgba(26, 106, 255, 0.28);
   --theme-checkbox-label-color: var(--color-label-strong);
   --theme-checkbox-label-disabled: var(--color-label-disabled);
   --theme-checkbox-helper-color: var(--color-label-neutral);
   --theme-checkbox-helper-disabled: var(--color-label-disabled);
-  --theme-checkbox-icon-color: var(--color-common-100);
+  --theme-checkbox-icon-default: transparent;
+  --theme-checkbox-icon-selected: var(--color-common-100);
+  --theme-checkbox-icon-disabled-selected: var(--color-common-100);
   --theme-checkbox-focus-ring: rgba(2, 84, 255, 0.32);
-  --theme-checkbox-disabled-selected-opacity: 0.28;
 }
 
 .checkbox {
@@ -51,7 +53,6 @@
   }
 
   &[data-disabled="true"] {
-    opacity: 0.6;
     cursor: not-allowed;
   }
 }
@@ -60,58 +61,70 @@
   box-shadow: 0 0 0 2px var(--theme-checkbox-focus-ring);
 }
 
-.checkbox-indicator {
+.checkbox-surface {
   inline-size: var(--theme-checkbox-indicator-size-medium);
   block-size: var(--theme-checkbox-indicator-size-medium);
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  color: var(--theme-checkbox-icon-color);
   border: var(--theme-checkbox-border-width) solid
     var(--theme-checkbox-border-color);
   border-radius: var(--theme-checkbox-control-radius-medium);
   background-color: var(--theme-checkbox-surface);
   transition:
     background-color 0.15s ease,
-    border-color 0.15s ease,
-    color 0.15s ease,
-    opacity 0.15s ease;
-
-  svg {
-    display: block;
-    inline-size: auto;
-    block-size: auto;
-    max-inline-size: 100%;
-    max-block-size: 100%;
-  }
+    border-color 0.15s ease;
 }
 
-.checkbox[data-size="large"] .checkbox-indicator {
+.checkbox[data-size="large"] .checkbox-surface {
   inline-size: var(--theme-checkbox-indicator-size-large);
   block-size: var(--theme-checkbox-indicator-size-large);
   border-radius: var(--theme-checkbox-control-radius-large);
 }
 
 // 인디케이터 영역(16x16 / 20x20)에만 상태 색상을 입혀 Figma 레이아웃과 동일하게 유지한다.
-.checkbox[data-state="checked"] .checkbox-indicator,
-.checkbox[data-state="indeterminate"] .checkbox-indicator {
+.checkbox[data-state="checked"] .checkbox-surface,
+.checkbox[data-state="indeterminate"] .checkbox-surface {
   background-color: var(--theme-checkbox-surface-selected);
   border-color: var(--theme-checkbox-border-selected);
 }
 
-.checkbox[data-disabled="true"] .checkbox-indicator {
+.checkbox[data-disabled="true"] .checkbox-surface {
   background-color: var(--theme-checkbox-surface-disabled);
   border-color: var(--theme-checkbox-border-color);
-  opacity: 1;
+}
+
+.checkbox[data-disabled="true"][data-state="checked"] .checkbox-surface,
+.checkbox[data-disabled="true"][data-state="indeterminate"] .checkbox-surface {
+  background-color: var(--theme-checkbox-surface-selected-disabled);
+  border-color: var(--theme-checkbox-border-color);
+}
+
+.checkbox-indicator {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: var(--theme-checkbox-icon-default);
+  transition: color 0.15s ease;
+
+  svg {
+    display: block;
+    inline-size: auto;
+    block-size: auto;
+    max-inline-size: 100%;
+    max-block-size: 100%;
+  }
+}
+
+.checkbox[data-state="checked"] .checkbox-indicator,
+.checkbox[data-state="indeterminate"] .checkbox-indicator {
+  color: var(--theme-checkbox-icon-selected);
 }
 
 .checkbox[data-disabled="true"][data-state="checked"] .checkbox-indicator,
 .checkbox[data-disabled="true"][data-state="indeterminate"]
   .checkbox-indicator {
-  // Figma 기준 disabled selected 상태는 primary 면을 유지하며 투명도로 구분한다.
-  background-color: var(--theme-checkbox-surface-selected);
-  border-color: var(--theme-checkbox-border-selected);
-  opacity: var(--theme-checkbox-disabled-selected-opacity);
+  color: var(--theme-checkbox-icon-disabled-selected);
 }
 
 .checkbox-field {

package/src/components/input/markup/text/AuthCode.tsx

@@ -0,0 +1,145 @@
+import type { ChangeEvent, ComponentPropsWithoutRef, ReactNode } from "react";
+import { forwardRef, useCallback, useMemo, useState } from "react";
+import { Text } from "./Base";
+import { InputUtilityButton } from "./InputUtilityButton";
+import type { InputUtilityButtonClickHandler } from "./InputUtilityButton";
+import type { InputProps } from "../../types";
+
+const normalizeDigits = (value?: string) => (value ?? "").replace(/\D/g, "");
+const clampLength = (length?: number) => Math.max(4, Math.min(8, length ?? 6));
+
+/**
+ * AuthCodeInput props. 이메일/휴대폰 컴포넌트와 동일한 UX로 인증코드를 입력한다.
+ * @property {string} [value] 제어형 값.
+ * @property {string} [defaultValue] 비제어 초기값.
+ * @property {(value: string) => void} [onValueChange] 값 변경 시 호출.
+ * @property {ComponentPropsWithoutRef<"input">["onChange"]} [onChange] native onChange override.
+ * @property {number} [length=6] 허용 자리수(4~8 사이로 보정).
+ * @property {(code: string) => void} [onComplete] length만큼 입력되면 호출.
+ * @property {string} [placeholder="인증코드 입력"] placeholder 텍스트.
+ * @property {ReactNode} [countdownText] 제한 시간 텍스트.
+ * @property {ReactNode} [countdownActionLabel="시간연장"] 제한 시간 연장 버튼 라벨.
+ * @property {InputUtilityButtonClickHandler} [onCountdownAction] 제한 시간 연장 핸들러.
+ * @property {boolean} [countdownActionDisabled] 제한 시간 연장 버튼 disabled.
+ */
+export interface AuthCodeInputProps extends Omit<
+  InputProps,
+  "type" | "inputMode" | "pattern" | "onChange" | "value" | "defaultValue"
+> {
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  onChange?: ComponentPropsWithoutRef<"input">["onChange"];
+  length?: number;
+  onComplete?: (code: string) => void;
+  placeholder?: string;
+  countdownText?: ReactNode;
+  countdownActionLabel?: ReactNode;
+  onCountdownAction?: InputUtilityButtonClickHandler;
+  countdownActionDisabled?: boolean;
+}
+
+const DEFAULT_PLACEHOLDER = "인증코드 입력";
+const DEFAULT_COUNTDOWN_ACTION_LABEL = "시간연장";
+
+/**
+ * AuthCodeInput — Text Input priority secondary 스타일로 구성된 인증번호 입력.
+ * @component
+ * @param {AuthCodeInputProps} props 인증코드 입력 props
+ */
+const AuthCodeInput = forwardRef<HTMLInputElement, AuthCodeInputProps>(
+  (
+    {
+      value,
+      defaultValue,
+      onValueChange,
+      onChange,
+      length = 6,
+      onComplete,
+      placeholder = DEFAULT_PLACEHOLDER,
+      countdownText,
+      countdownActionLabel = DEFAULT_COUNTDOWN_ACTION_LABEL,
+      onCountdownAction,
+      countdownActionDisabled,
+      priority = "secondary",
+      right,
+      ...restProps
+    },
+    forwardedRef,
+  ) => {
+    const safeLength = clampLength(length);
+    const [innerValue, setInnerValue] = useState(() =>
+      normalizeDigits(defaultValue),
+    );
+    const isControlled = value !== undefined;
+    const resolvedValue = isControlled ? normalizeDigits(value) : innerValue;
+
+    const handleChange = useCallback(
+      (event: ChangeEvent<HTMLInputElement>) => {
+        const digits = normalizeDigits(event.currentTarget.value).slice(
+          0,
+          safeLength,
+        );
+        if (!isControlled) {
+          setInnerValue(digits);
+        }
+        if (event.currentTarget.value !== digits) {
+          event.currentTarget.value = digits;
+        }
+        onValueChange?.(digits);
+        if (digits.length === safeLength) {
+          onComplete?.(digits);
+        }
+        onChange?.(event);
+      },
+      [isControlled, onChange, onComplete, onValueChange, safeLength],
+    );
+
+    const countdownActions = useMemo(() => {
+      if (!countdownText && !onCountdownAction) {
+        return null;
+      }
+
+      return (
+        <div className="auth-code-input__actions">
+          {countdownText ? (
+            <span className="auth-code-input__countdown">{countdownText}</span>
+          ) : null}
+          {onCountdownAction ? (
+            <InputUtilityButton
+              priority="tertiary"
+              onClick={onCountdownAction}
+              disabled={countdownActionDisabled}
+            >
+              {countdownActionLabel}
+            </InputUtilityButton>
+          ) : null}
+        </div>
+      );
+    }, [
+      countdownActionDisabled,
+      countdownActionLabel,
+      countdownText,
+      onCountdownAction,
+    ]);
+
+    return (
+      <Text
+        {...restProps}
+        ref={forwardedRef}
+        priority={priority}
+        type="text"
+        inputMode="numeric"
+        placeholder={placeholder}
+        value={resolvedValue}
+        onChange={handleChange}
+        maxLength={safeLength}
+        right={right ?? countdownActions}
+      />
+    );
+  },
+);
+
+AuthCodeInput.displayName = "AuthCodeInput";
+
+export { AuthCodeInput };