From 8f13bdab52c2e72b0847f0dcc502801d8c52c699 Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 15:27:22 +0900
Subject: [PATCH 1/8] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20Refactor:=20=ED=8F=BC?=
 =?UTF-8?q?=20=EC=BB=A8=ED=8A=B8=EB=A1=A4=20=EA=B3=B5=ED=86=B5=20=EA=B8=B0?=
 =?UTF-8?q?=EB=B0=98=20=EB=B6=84=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Input과 TextArea가 라벨, 오류 상태, 필드 스타일을 공유할 수 있도록
FormControl 기반을 분리했습니다. Input.Control은 역할이 드러나는
Input.FieldGroup으로 정리했습니다.
---
 .../ui/form-control/FormControl.types.ts      | 22 +++++++
 .../ui/form-control/FormControlContext.ts     | 39 +++++++++++++
 .../form-control/FormControlErrorMessage.tsx  | 57 +++++++++++++++++++
 .../ui/form-control/FormControlLabel.tsx      | 53 +++++++++++++++++
 .../ui/form-control/formControlStyles.ts      |  9 +++
 src/shared/ui/input/Input.stories.tsx         |  6 +-
 src/shared/ui/input/Input.tsx                 | 21 +++----
 src/shared/ui/input/Input.types.ts            | 14 +----
 src/shared/ui/input/InputContext.ts           | 17 ------
 src/shared/ui/input/InputErrorMessage.tsx     | 19 +------
 src/shared/ui/input/InputField.tsx            | 18 +++---
 .../{InputControl.tsx => InputFieldGroup.tsx} | 10 ++--
 src/shared/ui/input/InputLabel.tsx            | 20 +------
 13 files changed, 216 insertions(+), 89 deletions(-)
 create mode 100644 src/shared/ui/form-control/FormControl.types.ts
 create mode 100644 src/shared/ui/form-control/FormControlContext.ts
 create mode 100644 src/shared/ui/form-control/FormControlErrorMessage.tsx
 create mode 100644 src/shared/ui/form-control/FormControlLabel.tsx
 create mode 100644 src/shared/ui/form-control/formControlStyles.ts
 delete mode 100644 src/shared/ui/input/InputContext.ts
 rename src/shared/ui/input/{InputControl.tsx => InputFieldGroup.tsx} (78%)

diff --git a/src/shared/ui/form-control/FormControl.types.ts b/src/shared/ui/form-control/FormControl.types.ts
new file mode 100644
index 0000000..829f587
--- /dev/null
+++ b/src/shared/ui/form-control/FormControl.types.ts
@@ -0,0 +1,22 @@
+import type { ComponentPropsWithoutRef, ReactNode } from 'react';
+
+/** Input과 TextArea Root가 Label, Field, ErrorMessage에 제공하는 공통 상태입니다. */
+interface FormControlContextValue {
+  disabled: boolean;
+  errorMessageId: string;
+  fieldId: string;
+  invalid: boolean;
+  required: boolean;
+}
+
+/** Root의 fieldId와 required 상태를 상속하는 공통 Label props입니다. */
+interface FormControlLabelProps extends Omit<ComponentPropsWithoutRef<'label'>, 'htmlFor'> {
+  children: ReactNode;
+}
+
+/** Root의 invalid 상태와 errorMessageId를 상속하는 공통 오류 문구 props입니다. */
+interface FormControlErrorMessageProps extends Omit<ComponentPropsWithoutRef<'p'>, 'id'> {
+  children?: ReactNode;
+}
+
+export type { FormControlContextValue, FormControlErrorMessageProps, FormControlLabelProps };
diff --git a/src/shared/ui/form-control/FormControlContext.ts b/src/shared/ui/form-control/FormControlContext.ts
new file mode 100644
index 0000000..0da6c0d
--- /dev/null
+++ b/src/shared/ui/form-control/FormControlContext.ts
@@ -0,0 +1,39 @@
+import { createContext, use } from 'react';
+
+import type { FormControlContextValue } from './FormControl.types';
+
+const FormControlContext = createContext<FormControlContextValue | null>(null);
+
+/**
+ * ## useFormControlContext
+ *
+ * @description
+ * Input과 TextArea의 compound 하위 컴포넌트가 Root의 id 및 폼 상태를 읽는 내부 훅입니다.
+ * Label, Field, ErrorMessage가 동일한 접근성 연결 정보와 상태를 사용하도록 합니다.
+ *
+ * ### 주의할 점
+ *
+ * 반드시 `FormControlContext`를 제공하는 Input 또는 TextArea Root 내부에서 사용해야 합니다.
+ * 일반 화면 컴포넌트에서는 이 훅을 직접 사용하지 않고 `Input.*` 또는 `TextArea.*` API를
+ * 통해 FormControl 기반 컴포넌트를 조합합니다.
+ *
+ * @example
+ * ```tsx
+ * function CustomField() {
+ *   const { disabled, fieldId } = useFormControlContext();
+ *
+ *   return <input disabled={disabled} id={fieldId} />;
+ * }
+ * ```
+ */
+export function useFormControlContext() {
+  const context = use(FormControlContext);
+
+  if (!context) {
+    throw new Error('Form control compound components must be used within a form control root.');
+  }
+
+  return context;
+}
+
+export { FormControlContext };
diff --git a/src/shared/ui/form-control/FormControlErrorMessage.tsx b/src/shared/ui/form-control/FormControlErrorMessage.tsx
new file mode 100644
index 0000000..34236db
--- /dev/null
+++ b/src/shared/ui/form-control/FormControlErrorMessage.tsx
@@ -0,0 +1,57 @@
+import { cn } from '@/shared/styles/utils/cn';
+
+import { useFormControlContext } from './FormControlContext';
+
+import type { FormControlErrorMessageProps } from './FormControl.types';
+
+/**
+ * ## FormControlErrorMessage
+ *
+ * @description
+ * Input과 TextArea가 공유하는 유효성 오류 문구 기반 컴포넌트입니다. Root의 `invalid`가
+ * true이고 오류 문구가 있을 때만 렌더링하여 정상 상태에서 불필요한 빈 영역을 만들지 않습니다.
+ *
+ * ### 주의할 점
+ *
+ * 이 컴포넌트는 FormControl의 내부 기반이므로 직접 사용하기보다 `Input.ErrorMessage` 또는
+ * `TextArea.ErrorMessage`를 사용합니다. 오류 여부는 사용하는 폼에서 Root의 `invalid`로 전달합니다.
+ *
+ * ### 접근성
+ *
+ * Root가 생성한 `errorMessageId`를 사용하며 `role="alert"`로 오류를 알립니다. 실제 Field는
+ * 동일한 id를 `aria-describedby`와 `aria-errormessage`에 사용해 오류 문구와 연결합니다.
+ *
+ * @param children - 유효성 검증 실패 원인과 해결 방법을 설명하는 문구
+ * @param className - 공통 오류 문구 스타일을 확장하는 클래스 이름
+ *
+ * @example
+ * ```tsx
+ * <TextArea invalid>
+ *   <TextArea.Label>자기소개서 내용</TextArea.Label>
+ *   <TextArea.Field />
+ *   <TextArea.ErrorMessage>내용을 입력해 주세요.</TextArea.ErrorMessage>
+ * </TextArea>
+ * ```
+ */
+export function FormControlErrorMessage({
+  children,
+  className,
+  ...props
+}: FormControlErrorMessageProps) {
+  const { errorMessageId, invalid } = useFormControlContext();
+
+  if (!invalid || !children) {
+    return null;
+  }
+
+  return (
+    <p
+      {...props}
+      className={cn('mt-2 mb-0 body-14 text-error-500', className)}
+      id={errorMessageId}
+      role="alert"
+    >
+      {children}
+    </p>
+  );
+}
diff --git a/src/shared/ui/form-control/FormControlLabel.tsx b/src/shared/ui/form-control/FormControlLabel.tsx
new file mode 100644
index 0000000..c2561c9
--- /dev/null
+++ b/src/shared/ui/form-control/FormControlLabel.tsx
@@ -0,0 +1,53 @@
+import { cn } from '@/shared/styles/utils/cn';
+
+import { useFormControlContext } from './FormControlContext';
+
+import type { FormControlLabelProps } from './FormControl.types';
+
+/**
+ * ## FormControlLabel
+ *
+ * @description
+ * Input과 TextArea가 공유하는 Label 기반 컴포넌트입니다. Root가 제공하는 `fieldId`를
+ * `htmlFor`에 적용하고 `required` 상태에 따라 시각적인 필수 표시를 추가합니다.
+ *
+ * ### 주의할 점
+ *
+ * 이 컴포넌트는 FormControl의 내부 기반이므로 직접 사용하기보다 `Input.Label` 또는
+ * `TextArea.Label`을 사용합니다. `htmlFor`는 Root에서 관리하므로 외부에서 전달하지 않습니다.
+ *
+ * ### 접근성
+ *
+ * 필수 표시 `*`는 장식 요소이므로 스크린 리더에서 제외합니다. 실제 필수 상태는 Root와
+ * 연결된 Field의 네이티브 `required` 및 `aria-required` 속성으로 전달합니다.
+ *
+ * @param children - 입력 요소의 목적을 설명하는 Label 문구
+ * @param className - 공통 Label 스타일을 확장하는 클래스 이름
+ *
+ * @example
+ * ```tsx
+ * <Input required>
+ *   <Input.Label>회사명</Input.Label>
+ *   <Input.Field />
+ * </Input>
+ * ```
+ */
+export function FormControlLabel({ children, className, ...props }: FormControlLabelProps) {
+  const { fieldId, required } = useFormControlContext();
+
+  return (
+    <label
+      {...props}
+      className={cn('mb-6 w-fit body-18 font-semibold text-white', className)}
+      htmlFor={fieldId}
+    >
+      {children}
+      {required ? (
+        <span aria-hidden="true" className="text-primary-500">
+          {' '}
+          *
+        </span>
+      ) : null}
+    </label>
+  );
+}
diff --git a/src/shared/ui/form-control/formControlStyles.ts b/src/shared/ui/form-control/formControlStyles.ts
new file mode 100644
index 0000000..9c69979
--- /dev/null
+++ b/src/shared/ui/form-control/formControlStyles.ts
@@ -0,0 +1,9 @@
+/** Input과 TextArea Field가 공유하는 크기, 배경, 테두리, 글자 스타일입니다. */
+const fieldBaseClassName =
+  'min-w-0 w-full rounded-lg border border-transparent bg-gray-600 px-5 body-16 text-white outline-none';
+
+/** Input과 TextArea Field가 공유하는 focus, invalid, disabled 상태 스타일입니다. */
+const fieldInteractionClassName =
+  'transition-[border-color,box-shadow,background-color,color] duration-150 placeholder:text-gray-200 focus-visible:border-primary-500 focus-visible:shadow-[0_0_12px_2px] focus-visible:shadow-primary-500/25 data-[invalid=true]:border-error-500 data-[invalid=true]:focus-visible:shadow-error-500/25 disabled:cursor-not-allowed disabled:bg-gray-700 disabled:text-gray-300 disabled:placeholder:text-gray-500';
+
+export { fieldBaseClassName, fieldInteractionClassName };
diff --git a/src/shared/ui/input/Input.stories.tsx b/src/shared/ui/input/Input.stories.tsx
index 3d76620..cf7b528 100644
--- a/src/shared/ui/input/Input.stories.tsx
+++ b/src/shared/ui/input/Input.stories.tsx
@@ -189,7 +189,7 @@ const meta = {
     docs: {
       description: {
         component:
-          'Label, Field, ErrorMessage를 조합하는 Compound Input입니다. 버튼은 Input.Control 안에서 함께 구성하며, 폼 상태는 FormField를 통해 React Hook Form과 연결합니다.',
+          'Label, Field, ErrorMessage를 조합하는 Compound Input입니다. 버튼은 Input.FieldGroup 안에서 함께 구성하며, 폼 상태는 FormField를 통해 React Hook Form과 연결합니다.',
       },
     },
   },
@@ -251,12 +251,12 @@ export const WithButton: Story = {
   render: () => (
     <Input>
       <Input.Label>제한 글자 수</Input.Label>
-      <Input.Control>
+      <Input.FieldGroup>
         <Input.Field min={0} placeholder="1000" type="number" />
         <Button size="sm" type="button">
           적용
         </Button>
-      </Input.Control>
+      </Input.FieldGroup>
     </Input>
   ),
 };
diff --git a/src/shared/ui/input/Input.tsx b/src/shared/ui/input/Input.tsx
index 0f5f1c8..ae821be 100644
--- a/src/shared/ui/input/Input.tsx
+++ b/src/shared/ui/input/Input.tsx
@@ -3,14 +3,15 @@
 import { useId } from 'react';
 
 import { cn } from '@/shared/styles/utils/cn';
+import type { FormControlContextValue } from '@/shared/ui/form-control/FormControl.types';
+import { FormControlContext } from '@/shared/ui/form-control/FormControlContext';
 
-import { InputContext } from './InputContext';
-import { InputControl } from './InputControl';
 import { InputErrorMessage } from './InputErrorMessage';
 import { InputField } from './InputField';
+import { InputFieldGroup } from './InputFieldGroup';
 import { InputLabel } from './InputLabel';
 
-import type { InputContextValue, InputProps } from './Input.types';
+import type { InputProps } from './Input.types';
 
 /**
  * ## Input
@@ -23,7 +24,7 @@ import type { InputContextValue, InputProps } from './Input.types';
  *
  * `required`, `disabled`, `invalid` 상태를 하위 컴포넌트에 Context로 전달합니다.
  * `id`를 생략하면 고유한 Field id를 생성하며 Label과 보조 문구의 접근성 연결에도 사용합니다.
- * Field 내부 오른쪽에 버튼이 필요하면 `Input.Control` 안에서 함께 구성합니다.
+ * Field 내부 오른쪽에 버튼이 필요하면 `Input.FieldGroup` 안에서 함께 구성합니다.
  *
  * ### 접근성
  *
@@ -59,10 +60,10 @@ import type { InputContextValue, InputProps } from './Input.types';
  * ```tsx
  * <Input id="character-limit">
  *   <Input.Label>제한 글자 수</Input.Label>
- *   <Input.Control>
+ *   <Input.FieldGroup>
  *     <Input.Field type="number" min={0} placeholder="1000" />
  *     <Button size="sm" type="button">적용</Button>
- *   </Input.Control>
+ *   </Input.FieldGroup>
  *   <Input.ErrorMessage>0 이상의 글자 수를 입력해 주세요.</Input.ErrorMessage>
  * </Input>
  * ```
@@ -88,7 +89,7 @@ function InputRoot({
 }: InputProps) {
   const generatedId = useId();
   const fieldId = id ?? `input-${generatedId}`;
-  const contextValue: InputContextValue = {
+  const contextValue: FormControlContextValue = {
     disabled,
     errorMessageId: `${fieldId}-error-message`,
     fieldId,
@@ -97,7 +98,7 @@ function InputRoot({
   };
 
   return (
-    <InputContext value={contextValue}>
+    <FormControlContext value={contextValue}>
       <div
         {...props}
         className={cn('flex w-full flex-col', className)}
@@ -107,14 +108,14 @@ function InputRoot({
       >
         {children}
       </div>
-    </InputContext>
+    </FormControlContext>
   );
 }
 
 const Input = Object.assign(InputRoot, {
-  Control: InputControl,
   ErrorMessage: InputErrorMessage,
   Field: InputField,
+  FieldGroup: InputFieldGroup,
   Label: InputLabel,
 });
 
diff --git a/src/shared/ui/input/Input.types.ts b/src/shared/ui/input/Input.types.ts
index 2703a60..bd3b69a 100644
--- a/src/shared/ui/input/Input.types.ts
+++ b/src/shared/ui/input/Input.types.ts
@@ -28,7 +28,7 @@ interface InputLabelProps extends Omit<ComponentPropsWithoutRef<'label'>, 'htmlF
 }
 
 /** Field와 Button 같은 부가 동작을 나란히 합성하는 레이아웃 컨테이너입니다. */
-interface InputControlProps extends ComponentPropsWithoutRef<'div'> {
+interface InputFieldGroupProps extends ComponentPropsWithoutRef<'div'> {
   children: ReactNode;
 }
 
@@ -50,20 +50,10 @@ interface InputErrorMessageProps extends Omit<ComponentPropsWithoutRef<'p'>, 'id
   children?: ReactNode;
 }
 
-/** Compound 하위 컴포넌트가 Root에서 전달받는 내부 계약입니다. */
-interface InputContextValue {
-  disabled: boolean;
-  errorMessageId: string;
-  fieldId: string;
-  invalid: boolean;
-  required: boolean;
-}
-
 export type {
-  InputContextValue,
-  InputControlProps,
   InputErrorMessageProps,
   InputFieldProps,
+  InputFieldGroupProps,
   InputLabelProps,
   InputProps,
   InputType,
diff --git a/src/shared/ui/input/InputContext.ts b/src/shared/ui/input/InputContext.ts
deleted file mode 100644
index 4ae0744..0000000
--- a/src/shared/ui/input/InputContext.ts
+++ /dev/null
@@ -1,17 +0,0 @@
-import { createContext, use } from 'react';
-
-import type { InputContextValue } from './Input.types';
-
-const InputContext = createContext<InputContextValue | null>(null);
-
-export function useInputContext() {
-  const context = use(InputContext);
-
-  if (!context) {
-    throw new Error('Input compound components must be used within <Input>.');
-  }
-
-  return context;
-}
-
-export { InputContext };
diff --git a/src/shared/ui/input/InputErrorMessage.tsx b/src/shared/ui/input/InputErrorMessage.tsx
index 05b7fa0..ed27d68 100644
--- a/src/shared/ui/input/InputErrorMessage.tsx
+++ b/src/shared/ui/input/InputErrorMessage.tsx
@@ -1,6 +1,4 @@
-import { cn } from '@/shared/styles/utils/cn';
-
-import { useInputContext } from './InputContext';
+import { FormControlErrorMessage } from '@/shared/ui/form-control/FormControlErrorMessage';
 
 import type { InputErrorMessageProps } from './Input.types';
 
@@ -25,20 +23,9 @@ import type { InputErrorMessageProps } from './Input.types';
  * ```
  */
 export function InputErrorMessage({ children, className, ...props }: InputErrorMessageProps) {
-  const { errorMessageId, invalid } = useInputContext();
-
-  if (!invalid || !children) {
-    return null;
-  }
-
   return (
-    <p
-      {...props}
-      className={cn('mt-2 mb-0 body-14 text-error-500', className)}
-      id={errorMessageId}
-      role="alert"
-    >
+    <FormControlErrorMessage {...props} className={className}>
       {children}
-    </p>
+    </FormControlErrorMessage>
   );
 }
diff --git a/src/shared/ui/input/InputField.tsx b/src/shared/ui/input/InputField.tsx
index b0405a9..ac5ca4e 100644
--- a/src/shared/ui/input/InputField.tsx
+++ b/src/shared/ui/input/InputField.tsx
@@ -1,6 +1,9 @@
 import { cn } from '@/shared/styles/utils/cn';
-
-import { useInputContext } from './InputContext';
+import { useFormControlContext } from '@/shared/ui/form-control/FormControlContext';
+import {
+  fieldBaseClassName,
+  fieldInteractionClassName,
+} from '@/shared/ui/form-control/formControlStyles';
 
 import type { InputFieldProps } from './Input.types';
 
@@ -31,7 +34,7 @@ import type { InputFieldProps } from './Input.types';
  * ```
  */
 export function InputField({ className, ref, type = 'text', ...props }: InputFieldProps) {
-  const { disabled, errorMessageId, fieldId, invalid, required } = useInputContext();
+  const { disabled, errorMessageId, fieldId, invalid, required } = useFormControlContext();
 
   return (
     <input
@@ -41,14 +44,11 @@ export function InputField({ className, ref, type = 'text', ...props }: InputFie
       aria-invalid={invalid || undefined}
       aria-required={required || undefined}
       className={cn(
-        'h-16.75 min-w-0 w-full rounded-lg border border-transparent bg-gray-600 px-5 body-16 text-white outline-none',
-        'transition-[border-color,box-shadow,background-color,color] duration-150',
-        'placeholder:text-gray-200',
+        'h-16.75',
+        fieldBaseClassName,
+        fieldInteractionClassName,
         'autofill:[-webkit-text-fill-color:var(--color-white)] autofill:caret-white',
         'autofill:[transition:background-color_9999s_ease-out_0s]',
-        'focus-visible:border-primary-500 focus-visible:shadow-[0_0_12px_2px] focus-visible:shadow-primary-500/25',
-        'data-[invalid=true]:border-error-500 data-[invalid=true]:focus-visible:shadow-error-500/25',
-        'disabled:cursor-not-allowed disabled:bg-gray-700 disabled:text-gray-300 disabled:placeholder:text-gray-500',
         className
       )}
       data-invalid={invalid || undefined}
diff --git a/src/shared/ui/input/InputControl.tsx b/src/shared/ui/input/InputFieldGroup.tsx
similarity index 78%
rename from src/shared/ui/input/InputControl.tsx
rename to src/shared/ui/input/InputFieldGroup.tsx
index 5397909..d6914ff 100644
--- a/src/shared/ui/input/InputControl.tsx
+++ b/src/shared/ui/input/InputFieldGroup.tsx
@@ -1,9 +1,9 @@
 import { cn } from '@/shared/styles/utils/cn';
 
-import type { InputControlProps } from './Input.types';
+import type { InputFieldGroupProps } from './Input.types';
 
 /**
- * ## Input.Control
+ * ## Input.FieldGroup
  *
  * @description
  * Button을 `Input.Field` 내부 오른쪽에 배치할 때 사용하는 선택적 레이아웃 컴포넌트입니다.
@@ -14,13 +14,13 @@ import type { InputControlProps } from './Input.types';
  *
  * @example
  * ```tsx
- * <Input.Control>
+ * <Input.FieldGroup>
  *   <Input.Field type="number" />
  *   <Button size="sm">적용</Button>
- * </Input.Control>
+ * </Input.FieldGroup>
  * ```
  */
-export function InputControl({ children, className, ...props }: InputControlProps) {
+export function InputFieldGroup({ children, className, ...props }: InputFieldGroupProps) {
   return (
     <div
       {...props}
diff --git a/src/shared/ui/input/InputLabel.tsx b/src/shared/ui/input/InputLabel.tsx
index 93afc41..0b531a4 100644
--- a/src/shared/ui/input/InputLabel.tsx
+++ b/src/shared/ui/input/InputLabel.tsx
@@ -1,6 +1,4 @@
-import { cn } from '@/shared/styles/utils/cn';
-
-import { useInputContext } from './InputContext';
+import { FormControlLabel } from '@/shared/ui/form-control/FormControlLabel';
 
 import type { InputLabelProps } from './Input.types';
 
@@ -25,21 +23,9 @@ import type { InputLabelProps } from './Input.types';
  * ```
  */
 export function InputLabel({ children, className, ...props }: InputLabelProps) {
-  const { fieldId, required } = useInputContext();
-
   return (
-    <label
-      {...props}
-      className={cn('mb-6 w-fit body-18 font-semibold text-white', className)}
-      htmlFor={fieldId}
-    >
+    <FormControlLabel {...props} className={className}>
       {children}
-      {required ? (
-        <span aria-hidden="true" className="text-primary-500">
-          {' '}
-          *
-        </span>
-      ) : null}
-    </label>
+    </FormControlLabel>
   );
 }

From dfed5c74cde7bb93fe17ec4fc2def26797f319cf Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 15:29:17 +0900
Subject: [PATCH 2/8] =?UTF-8?q?=E2=9C=A8=20Feat:=20TextArea=20=EA=B3=B5?=
 =?UTF-8?q?=ED=86=B5=20=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20=EC=B6=94?=
 =?UTF-8?q?=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

긴 텍스트 입력에서 라벨, 오류, 비활성 상태와 글자 수 표시를
일관되게 사용할 수 있는 Compound TextArea를 추가했습니다.
권장 길이와 최대 길이를 타입으로 구분하고 최대 입력을 보장합니다.
---
 src/shared/ui/textarea/TextArea.stories.tsx   | 193 ++++++++++++++++++
 src/shared/ui/textarea/TextArea.tsx           |  86 ++++++++
 src/shared/ui/textarea/TextArea.types.ts      |  40 ++++
 .../ui/textarea/TextAreaErrorMessage.tsx      |  11 +
 src/shared/ui/textarea/TextAreaField.tsx      | 126 ++++++++++++
 src/shared/ui/textarea/TextAreaLabel.tsx      |  11 +
 src/shared/ui/textarea/index.ts               |   1 +
 7 files changed, 468 insertions(+)
 create mode 100644 src/shared/ui/textarea/TextArea.stories.tsx
 create mode 100644 src/shared/ui/textarea/TextArea.tsx
 create mode 100644 src/shared/ui/textarea/TextArea.types.ts
 create mode 100644 src/shared/ui/textarea/TextAreaErrorMessage.tsx
 create mode 100644 src/shared/ui/textarea/TextAreaField.tsx
 create mode 100644 src/shared/ui/textarea/TextAreaLabel.tsx
 create mode 100644 src/shared/ui/textarea/index.ts

diff --git a/src/shared/ui/textarea/TextArea.stories.tsx b/src/shared/ui/textarea/TextArea.stories.tsx
new file mode 100644
index 0000000..e8b4aa5
--- /dev/null
+++ b/src/shared/ui/textarea/TextArea.stories.tsx
@@ -0,0 +1,193 @@
+import { useState } from 'react';
+
+import { useForm } from 'react-hook-form';
+
+import { Button } from '@/shared/ui/button';
+import { FormField } from '@/shared/ui/form-field';
+
+import { TextArea } from './index';
+
+import type { Meta, StoryObj } from '@storybook/nextjs';
+
+interface TextAreaPlaygroundProps {
+  defaultValue: string;
+  disabled: boolean;
+  errorMessage: string;
+  invalid: boolean;
+  label: string;
+  length: number;
+  lengthType: 'max' | 'recommended';
+  placeholder: string;
+  required: boolean;
+  showCount: boolean;
+}
+
+interface ExampleFormValues {
+  answer: string;
+}
+
+function TextAreaPlayground({
+  defaultValue,
+  disabled,
+  errorMessage,
+  invalid,
+  label,
+  length,
+  lengthType,
+  placeholder,
+  required,
+  showCount,
+}: TextAreaPlaygroundProps) {
+  const lengthProps = lengthType === 'max' ? { maxLength: length } : { recommendedLength: length };
+
+  return (
+    <TextArea disabled={disabled} invalid={invalid} required={required}>
+      <TextArea.Label>{label}</TextArea.Label>
+      <TextArea.Field
+        defaultValue={defaultValue || undefined}
+        key={defaultValue}
+        placeholder={placeholder}
+        showCount={showCount}
+        {...lengthProps}
+      />
+      <TextArea.ErrorMessage>{errorMessage}</TextArea.ErrorMessage>
+    </TextArea>
+  );
+}
+
+function ReactHookFormExample() {
+  const [submittedValue, setSubmittedValue] = useState('');
+  const { control, handleSubmit } = useForm<ExampleFormValues>({
+    defaultValues: {
+      answer: '',
+    },
+    mode: 'onBlur',
+  });
+
+  return (
+    <form
+      className="flex w-full flex-col gap-8"
+      noValidate
+      onSubmit={handleSubmit(({ answer }) => setSubmittedValue(answer))}
+    >
+      <FormField
+        control={control}
+        name="answer"
+        render={({ errorMessage, field, invalid }) => (
+          <TextArea invalid={invalid} required>
+            <TextArea.Label>자기소개서 내용</TextArea.Label>
+            <TextArea.Field
+              placeholder="자기소개서 내용을 입력해 주세요."
+              recommendedLength={1000}
+              showCount
+              {...field}
+            />
+            <TextArea.ErrorMessage>{errorMessage}</TextArea.ErrorMessage>
+          </TextArea>
+        )}
+        rules={{ required: '자기소개서 내용을 입력해 주세요.' }}
+      />
+
+      <Button className="self-end" type="submit">
+        저장하기
+      </Button>
+
+      {submittedValue ? (
+        <p className="m-0 body-14 text-gray-50">제출된 글자 수: {submittedValue.length}자</p>
+      ) : null}
+    </form>
+  );
+}
+
+const meta = {
+  title: 'Shared/TextArea',
+  component: TextAreaPlayground,
+  args: {
+    defaultValue: '',
+    disabled: false,
+    errorMessage: '자기소개서 내용을 입력해 주세요.',
+    invalid: false,
+    label: '자기소개서 내용',
+    length: 1000,
+    lengthType: 'recommended',
+    placeholder: '자기소개서 내용을 입력해 주세요.',
+    required: false,
+    showCount: true,
+  },
+  argTypes: {
+    defaultValue: { control: 'text' },
+    disabled: { control: 'boolean' },
+    errorMessage: { control: 'text' },
+    invalid: { control: 'boolean' },
+    label: { control: 'text' },
+    length: { control: 'number' },
+    lengthType: {
+      control: 'inline-radio',
+      options: ['recommended', 'max'],
+    },
+    placeholder: { control: 'text' },
+    required: { control: 'boolean' },
+    showCount: { control: 'boolean' },
+  },
+  decorators: [
+    (Story) => (
+      <div className="w-200 max-w-[calc(100vw-2rem)] bg-gray-800 p-3">
+        <Story />
+      </div>
+    ),
+  ],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          '긴 텍스트 입력을 위한 Compound TextArea입니다. recommendedLength는 안내 기준이고 maxLength는 실제 입력 제한입니다.',
+      },
+    },
+  },
+} satisfies Meta<typeof TextAreaPlayground>;
+
+export default meta;
+
+type Story = StoryObj<typeof meta>;
+
+export const Default: Story = {};
+
+export const WithoutCount: Story = {
+  args: {
+    showCount: false,
+  },
+};
+
+export const RecommendedLengthExceeded: Story = {
+  args: {
+    defaultValue: '권장 길이를 초과한 자기소개서 내용입니다.',
+    length: 10,
+    lengthType: 'recommended',
+  },
+};
+
+export const MaxLengthReached: Story = {
+  args: {
+    defaultValue: '최대길이',
+    length: 5,
+    lengthType: 'max',
+  },
+};
+
+export const WithError: Story = {
+  args: {
+    invalid: true,
+    required: true,
+  },
+};
+
+export const Disabled: Story = {
+  args: {
+    defaultValue: '수정할 수 없는 자기소개서 내용입니다.',
+    disabled: true,
+  },
+};
+
+export const ReactHookForm: Story = {
+  render: () => <ReactHookFormExample />,
+};
diff --git a/src/shared/ui/textarea/TextArea.tsx b/src/shared/ui/textarea/TextArea.tsx
new file mode 100644
index 0000000..ca1b952
--- /dev/null
+++ b/src/shared/ui/textarea/TextArea.tsx
@@ -0,0 +1,86 @@
+'use client';
+
+import { useId } from 'react';
+
+import { cn } from '@/shared/styles/utils/cn';
+import type { FormControlContextValue } from '@/shared/ui/form-control/FormControl.types';
+import { FormControlContext } from '@/shared/ui/form-control/FormControlContext';
+
+import { TextAreaErrorMessage } from './TextAreaErrorMessage';
+import { TextAreaField } from './TextAreaField';
+import { TextAreaLabel } from './TextAreaLabel';
+
+import type { TextAreaProps } from './TextArea.types';
+
+/**
+ * ## TextArea
+ *
+ * @description
+ * Label, Field, ErrorMessage를 조합해 긴 텍스트를 입력받는 공통 Compound TextArea입니다.
+ * 자기소개서 답변, 우대사항처럼 여러 줄 입력이 필요한 폼에서 사용합니다.
+ *
+ * ### 주요 내용
+ *
+ * `required`, `disabled`, `invalid` 상태를 하위 컴포넌트에 전달합니다. `id`를 생략하면
+ * 고유한 Field id를 생성하며 Label, 글자 수 안내, 오류 문구의 접근성 연결에 사용합니다.
+ *
+ * ### 접근성
+ *
+ * 입력 목적을 제공하는 `TextArea.Label`을 함께 사용합니다. 유효성 오류가 있으면
+ * `invalid`를 전달하고 `TextArea.ErrorMessage`에 해결 가능한 오류 문구를 제공합니다.
+ *
+ * @example
+ * ```tsx
+ * <TextArea id="cover-letter-answer" invalid={invalid} required>
+ *   <TextArea.Label>자기소개서 내용</TextArea.Label>
+ *   <TextArea.Field
+ *     recommendedLength={1000}
+ *     showCount
+ *     {...field}
+ *   />
+ *   <TextArea.ErrorMessage>{errorMessage}</TextArea.ErrorMessage>
+ * </TextArea>
+ * ```
+ */
+function TextAreaRoot({
+  children,
+  className,
+  containerId,
+  disabled = false,
+  id,
+  invalid = false,
+  required = false,
+  ...props
+}: TextAreaProps) {
+  const generatedId = useId();
+  const fieldId = id ?? `text-area-${generatedId}`;
+  const contextValue: FormControlContextValue = {
+    disabled,
+    errorMessageId: `${fieldId}-error-message`,
+    fieldId,
+    invalid,
+    required,
+  };
+
+  return (
+    <FormControlContext value={contextValue}>
+      <div
+        {...props}
+        className={cn('flex w-full flex-col', className)}
+        data-disabled={disabled || undefined}
+        data-invalid={invalid || undefined}
+        id={containerId}
+      >
+        {children}
+      </div>
+    </FormControlContext>
+  );
+}
+
+const TextArea = Object.assign(TextAreaRoot, {
+  ErrorMessage: TextAreaErrorMessage,
+  Field: TextAreaField,
+  Label: TextAreaLabel,
+});
+
+export { TextArea };
diff --git a/src/shared/ui/textarea/TextArea.types.ts b/src/shared/ui/textarea/TextArea.types.ts
new file mode 100644
index 0000000..baf426d
--- /dev/null
+++ b/src/shared/ui/textarea/TextArea.types.ts
@@ -0,0 +1,40 @@
+import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from 'react';
+
+interface TextAreaProps extends Omit<ComponentPropsWithoutRef<'div'>, 'id'> {
+  children: ReactNode;
+  containerId?: string;
+  disabled?: boolean;
+  id?: string;
+  invalid?: boolean;
+  required?: boolean;
+}
+
+interface TextAreaFieldBaseProps extends Omit<
+  ComponentPropsWithRef<'textarea'>,
+  | 'aria-describedby'
+  | 'aria-errormessage'
+  | 'aria-invalid'
+  | 'disabled'
+  | 'id'
+  | 'maxLength'
+  | 'required'
+> {
+  showCount?: boolean;
+}
+
+type TextAreaFieldProps = TextAreaFieldBaseProps &
+  (
+    | { maxLength: number; recommendedLength?: never }
+    | { maxLength?: never; recommendedLength: number }
+    | { maxLength?: undefined; recommendedLength?: undefined }
+  );
+
+type TextAreaLabelProps = Omit<ComponentPropsWithoutRef<'label'>, 'htmlFor'> & {
+  children: ReactNode;
+};
+
+type TextAreaErrorMessageProps = Omit<ComponentPropsWithoutRef<'p'>, 'id'> & {
+  children?: ReactNode;
+};
+
+export type { TextAreaErrorMessageProps, TextAreaFieldProps, TextAreaLabelProps, TextAreaProps };
diff --git a/src/shared/ui/textarea/TextAreaErrorMessage.tsx b/src/shared/ui/textarea/TextAreaErrorMessage.tsx
new file mode 100644
index 0000000..7e442b3
--- /dev/null
+++ b/src/shared/ui/textarea/TextAreaErrorMessage.tsx
@@ -0,0 +1,11 @@
+import { FormControlErrorMessage } from '@/shared/ui/form-control/FormControlErrorMessage';
+
+import type { TextAreaErrorMessageProps } from './TextArea.types';
+
+export function TextAreaErrorMessage({ children, className, ...props }: TextAreaErrorMessageProps) {
+  return (
+    <FormControlErrorMessage {...props} className={className}>
+      {children}
+    </FormControlErrorMessage>
+  );
+}
diff --git a/src/shared/ui/textarea/TextAreaField.tsx b/src/shared/ui/textarea/TextAreaField.tsx
new file mode 100644
index 0000000..dfbf7dc
--- /dev/null
+++ b/src/shared/ui/textarea/TextAreaField.tsx
@@ -0,0 +1,126 @@
+import { useState } from 'react';
+
+import { cn } from '@/shared/styles/utils/cn';
+import { useFormControlContext } from '@/shared/ui/form-control/FormControlContext';
+import {
+  fieldBaseClassName,
+  fieldInteractionClassName,
+} from '@/shared/ui/form-control/formControlStyles';
+
+import type { TextAreaFieldProps } from './TextArea.types';
+
+const getValueLength = (value: TextAreaFieldProps['value']) => String(value ?? '').length;
+
+/**
+ * ## TextArea.Field
+ *
+ * @description
+ * 실제 HTML `textarea`를 렌더링하고 선택적으로 현재 글자 수를 표시합니다. 네이티브
+ * `maxLength`는 입력을 제한하며 `recommendedLength`는 입력을 막지 않는 권장 기준입니다.
+ *
+ * ### 주요 내용
+ *
+ * controlled 값은 렌더링 중 길이를 계산하고 uncontrolled 값은 입력 이벤트에서 길이를
+ * 갱신합니다. React Hook Form의 `field` 객체와 React 19의 일반 `ref` prop을 지원합니다.
+ *
+ * @param recommendedLength - 입력을 제한하지 않는 권장 글자 수
+ * @param showCount - 현재 글자 수와 기준 글자 수 표시 여부
+ * @param maxLength - 브라우저가 강제하는 최대 입력 글자 수
+ */
+export function TextAreaField({
+  className,
+  defaultValue,
+  maxLength,
+  onChange,
+  recommendedLength,
+  ref,
+  showCount = false,
+  value,
+  ...props
+}: TextAreaFieldProps) {
+  const { disabled, errorMessageId, fieldId, invalid, required } = useFormControlContext();
+  const [uncontrolledLength, setUncontrolledLength] = useState(() => getValueLength(defaultValue));
+  const isControlled = value !== undefined;
+  const currentLength = isControlled ? getValueLength(value) : uncontrolledLength;
+  const countId = `${fieldId}-character-count`;
+  const describedBy = [showCount ? countId : undefined, invalid ? errorMessageId : undefined]
+    .filter(Boolean)
+    .join(' ');
+  const hasReachedMaxLength = maxLength !== undefined && currentLength >= maxLength;
+  const hasExceededRecommendedLength =
+    recommendedLength !== undefined && currentLength > recommendedLength;
+  const countLimit = recommendedLength ?? maxLength;
+  const hasExceededCountLimit = countLimit !== undefined && currentLength > countLimit;
+  const isNearCountLimit =
+    countLimit !== undefined && currentLength >= countLimit * 0.9 && !hasExceededCountLimit;
+
+  const handleChange: NonNullable<TextAreaFieldProps['onChange']> = (event) => {
+    const inputValue = event.currentTarget.value;
+    const nextValue =
+      maxLength !== undefined && inputValue.length > maxLength
+        ? inputValue.slice(0, maxLength)
+        : inputValue;
+
+    if (inputValue !== nextValue) {
+      event.currentTarget.value = nextValue;
+    }
+
+    if (!isControlled) {
+      setUncontrolledLength(nextValue.length);
+    }
+
+    onChange?.(event);
+  };
+
+  return (
+    <div className="relative w-full">
+      <textarea
+        {...props}
+        aria-describedby={describedBy || undefined}
+        aria-errormessage={invalid ? errorMessageId : undefined}
+        aria-invalid={invalid || undefined}
+        aria-required={required || undefined}
+        className={cn(
+          'block min-h-48 resize-y py-5',
+          showCount ? 'pb-12' : undefined,
+          fieldBaseClassName,
+          fieldInteractionClassName,
+          className
+        )}
+        data-invalid={invalid || undefined}
+        defaultValue={defaultValue}
+        disabled={disabled}
+        id={fieldId}
+        maxLength={maxLength}
+        onChange={handleChange}
+        ref={ref}
+        required={required}
+        value={value}
+      />
+
+      {showCount ? (
+        <p
+          className={cn(
+            'pointer-events-none absolute right-5 bottom-4 m-0 body-14 text-gray-200',
+            disabled ? 'text-gray-500' : undefined
+          )}
+          data-max-length-reached={hasReachedMaxLength || undefined}
+          data-recommended-length-exceeded={hasExceededRecommendedLength || undefined}
+          id={countId}
+        >
+          <span
+            className={cn(
+              'text-primary-500',
+              isNearCountLimit ? 'text-yellow-500' : undefined,
+              hasExceededCountLimit ? 'text-error-500' : undefined,
+              disabled ? 'text-gray-500' : undefined
+            )}
+          >
+            {currentLength}
+          </span>
+          {countLimit !== undefined ? `/${countLimit}자` : '자'}
+        </p>
+      ) : null}
+    </div>
+  );
+}
diff --git a/src/shared/ui/textarea/TextAreaLabel.tsx b/src/shared/ui/textarea/TextAreaLabel.tsx
new file mode 100644
index 0000000..0b99323
--- /dev/null
+++ b/src/shared/ui/textarea/TextAreaLabel.tsx
@@ -0,0 +1,11 @@
+import { FormControlLabel } from '@/shared/ui/form-control/FormControlLabel';
+
+import type { TextAreaLabelProps } from './TextArea.types';
+
+export function TextAreaLabel({ children, className, ...props }: TextAreaLabelProps) {
+  return (
+    <FormControlLabel {...props} className={className}>
+      {children}
+    </FormControlLabel>
+  );
+}
diff --git a/src/shared/ui/textarea/index.ts b/src/shared/ui/textarea/index.ts
new file mode 100644
index 0000000..fdf76b3
--- /dev/null
+++ b/src/shared/ui/textarea/index.ts
@@ -0,0 +1 @@
+export { TextArea } from './TextArea';

From 43465b8581153be16f085779719fde3b537a262d Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 16:18:32 +0900
Subject: [PATCH 3/8] =?UTF-8?q?=F0=9F=8E=A8=20Style:=20TextArea=20?=
 =?UTF-8?q?=EB=86=92=EC=9D=B4=20=EC=82=AC=EC=9D=B4=EC=A6=88=20=EC=88=98?=
 =?UTF-8?q?=EC=A0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

---
 src/shared/ui/textarea/TextAreaField.tsx | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/shared/ui/textarea/TextAreaField.tsx b/src/shared/ui/textarea/TextAreaField.tsx
index dfbf7dc..1c73cc8 100644
--- a/src/shared/ui/textarea/TextAreaField.tsx
+++ b/src/shared/ui/textarea/TextAreaField.tsx
@@ -81,7 +81,7 @@ export function TextAreaField({
         aria-invalid={invalid || undefined}
         aria-required={required || undefined}
         className={cn(
-          'block min-h-48 resize-y py-5',
+          'block min-h-81.75 resize-y py-5',
           showCount ? 'pb-12' : undefined,
           fieldBaseClassName,
           fieldInteractionClassName,

From 33646f54ac50193f90db3c2751485b6c1b94d6fb Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 22:09:29 +0900
Subject: [PATCH 4/8] =?UTF-8?q?=F0=9F=8E=A8=20Style:=20TextArea=20?=
 =?UTF-8?q?=EC=8A=A4=ED=81=AC=EB=A1=A4=20=EC=98=81=EC=97=AD=20=EC=8A=A4?=
 =?UTF-8?q?=ED=83=80=EC=9D=BC=20=EA=B0=9C=EC=84=A0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TextArea의 스크롤바와 크기 조절 아이콘을 디자인 토큰에 맞게
정리했습니다. 하단 카운터에 배경 영역을 제공해 긴 입력 내용과
겹치지 않도록 개선했습니다.
---
 src/shared/styles/base/scroll.css        | 44 ++++++++++++++++++++++++
 src/shared/styles/globals.css            |  1 +
 src/shared/ui/textarea/TextAreaField.tsx |  6 ++--
 3 files changed, 48 insertions(+), 3 deletions(-)
 create mode 100644 src/shared/styles/base/scroll.css

diff --git a/src/shared/styles/base/scroll.css b/src/shared/styles/base/scroll.css
new file mode 100644
index 0000000..828d383
--- /dev/null
+++ b/src/shared/styles/base/scroll.css
@@ -0,0 +1,44 @@
+.textarea-scrollbar {
+  scrollbar-color: var(--color-gray-300) transparent;
+  scrollbar-width: thin;
+}
+
+.textarea-scrollbar::-webkit-scrollbar {
+  width: 10px;
+}
+
+.textarea-scrollbar::-webkit-scrollbar-track {
+  margin-block: 8px;
+  background: transparent;
+}
+
+.textarea-scrollbar::-webkit-scrollbar-thumb {
+  border: 3px solid transparent;
+  border-radius: 9999px;
+  background-color: var(--color-gray-300);
+  background-clip: content-box;
+}
+
+.textarea-scrollbar::-webkit-scrollbar-thumb:hover {
+  background-color: var(--color-gray-200);
+}
+
+.textarea-scrollbar::-webkit-scrollbar-corner {
+  background: transparent;
+}
+
+.textarea-scrollbar::-webkit-resizer {
+  background-color: transparent;
+  background-image: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='12' height='12' viewBox='0 0 12 12'%3E%3Cpath d='M5 11L11 5M1 11L11 1' fill='none' stroke='%23a6a6a6' stroke-linecap='round' stroke-width='1.5'/%3E%3C/svg%3E");
+  background-position: right bottom;
+  background-repeat: no-repeat;
+  background-size: 12px 12px;
+}
+
+.textarea-scrollbar:disabled {
+  scrollbar-color: var(--color-gray-500) transparent;
+}
+
+.textarea-scrollbar:disabled::-webkit-scrollbar-thumb {
+  background-color: var(--color-gray-500);
+}
diff --git a/src/shared/styles/globals.css b/src/shared/styles/globals.css
index d443122..84a1f97 100644
--- a/src/shared/styles/globals.css
+++ b/src/shared/styles/globals.css
@@ -1,6 +1,7 @@
 @import 'tailwindcss';
 @import './base/fonts.css';
 @import './base/colors.css';
+@import './base/scroll.css';
 
 button {
   cursor: pointer;
diff --git a/src/shared/ui/textarea/TextAreaField.tsx b/src/shared/ui/textarea/TextAreaField.tsx
index 1c73cc8..0aa8a51 100644
--- a/src/shared/ui/textarea/TextAreaField.tsx
+++ b/src/shared/ui/textarea/TextAreaField.tsx
@@ -81,7 +81,7 @@ export function TextAreaField({
         aria-invalid={invalid || undefined}
         aria-required={required || undefined}
         className={cn(
-          'block min-h-81.75 resize-y py-5',
+          'textarea-scrollbar block min-h-81.75 resize-y py-5',
           showCount ? 'pb-12' : undefined,
           fieldBaseClassName,
           fieldInteractionClassName,
@@ -101,8 +101,8 @@ export function TextAreaField({
       {showCount ? (
         <p
           className={cn(
-            'pointer-events-none absolute right-5 bottom-4 m-0 body-14 text-gray-200',
-            disabled ? 'text-gray-500' : undefined
+            'pointer-events-none absolute right-4 bottom-px left-px z-10 m-0 flex h-8 items-center justify-end rounded-bl-lg bg-gray-600 px-4 body-14 text-gray-200',
+            disabled ? 'bg-gray-700 text-gray-500' : undefined
           )}
           data-max-length-reached={hasReachedMaxLength || undefined}
           data-recommended-length-exceeded={hasExceededRecommendedLength || undefined}

From d1fb59ae497cc0a1387313c2ceb73d2551eb03df Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 22:23:25 +0900
Subject: [PATCH 5/8] =?UTF-8?q?=F0=9F=93=9D=20Docs:=20=ED=8F=BC=20?=
 =?UTF-8?q?=EC=BB=B4=ED=8F=AC=EB=84=8C=ED=8A=B8=20=ED=83=80=EC=9E=85=20?=
 =?UTF-8?q?=EC=A3=BC=EC=84=9D=20=EB=B3=B4=EA=B0=95?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

FormField의 React Hook Form 상태와 TextArea의 길이 기준 타입을
명확히 이해할 수 있도록 역할과 사용 조건을 문서화했습니다.
---
 src/shared/ui/form-field/FormField.types.ts | 17 +++++++++++
 src/shared/ui/textarea/TextArea.types.ts    | 34 +++++++++++++++++----
 2 files changed, 45 insertions(+), 6 deletions(-)

diff --git a/src/shared/ui/form-field/FormField.types.ts b/src/shared/ui/form-field/FormField.types.ts
index a8c3165..9a79148 100644
--- a/src/shared/ui/form-field/FormField.types.ts
+++ b/src/shared/ui/form-field/FormField.types.ts
@@ -9,17 +9,34 @@ import type {
   UseFormStateReturn,
 } from 'react-hook-form';
 
+/**
+ * FormField의 render 함수에 전달하는 React Hook Form 상태입니다.
+ *
+ * Controller의 원본 상태를 유지하면서 공통 UI가 바로 사용할 수 있도록 `invalid`와
+ * `errorMessage`를 편의 값으로 제공합니다.
+ */
 interface FormFieldRenderProps<
   TFieldValues extends FieldValues,
   TName extends FieldPath<TFieldValues>,
 > {
+  /** 현재 Field의 validation 오류 메시지입니다. */
   errorMessage?: string;
+  /** 실제 입력 요소에 전달할 name, value, 이벤트 핸들러, ref입니다. */
   field: ControllerRenderProps<TFieldValues, TName>;
+  /** touched, dirty, invalid 등 현재 Field 단위 상태입니다. */
   fieldState: ControllerFieldState;
+  /** submit, validating 등 폼 전체 상태입니다. */
   formState: UseFormStateReturn<TFieldValues>;
+  /** 현재 Field에 validation 오류가 있는지 나타내는 편의 값입니다. */
   invalid: boolean;
 }
 
+/**
+ * React Hook Form의 Controller props를 사용하는 공통 FormField adapter 타입입니다.
+ *
+ * Controller의 기본 `render` 대신 공통 UI에 필요한 편의 값이 포함된
+ * `FormFieldRenderProps`를 전달하는 render 함수를 사용합니다.
+ */
 type FormFieldProps<TFieldValues extends FieldValues, TName extends FieldPath<TFieldValues>> = Omit<
   ControllerProps<TFieldValues, TName>,
   'render'
diff --git a/src/shared/ui/textarea/TextArea.types.ts b/src/shared/ui/textarea/TextArea.types.ts
index baf426d..dd857d5 100644
--- a/src/shared/ui/textarea/TextArea.types.ts
+++ b/src/shared/ui/textarea/TextArea.types.ts
@@ -1,5 +1,11 @@
 import type { ComponentPropsWithoutRef, ComponentPropsWithRef, ReactNode } from 'react';
 
+/**
+ * Compound TextArea 전체에서 공유하는 상태입니다.
+ *
+ * `id`는 실제 textarea에 적용되며 Label, 글자 수, ErrorMessage의 접근성 연결에
+ * 사용됩니다. DOM wrapper에 별도 id가 필요하면 `containerId`를 사용합니다.
+ */
 interface TextAreaProps extends Omit<ComponentPropsWithoutRef<'div'>, 'id'> {
   children: ReactNode;
   containerId?: string;
@@ -9,6 +15,12 @@ interface TextAreaProps extends Omit<ComponentPropsWithoutRef<'div'>, 'id'> {
   required?: boolean;
 }
 
+/**
+ * 실제 textarea가 지원하는 공통 props입니다.
+ *
+ * 접근성 및 공통 상태는 Root에서 관리합니다. React Hook Form의 `name`, `value`,
+ * `onChange`, `onBlur`, `ref`를 포함한 나머지 네이티브 textarea props를 전달할 수 있습니다.
+ */
 interface TextAreaFieldBaseProps extends Omit<
   ComponentPropsWithRef<'textarea'>,
   | 'aria-describedby'
@@ -19,20 +31,30 @@ interface TextAreaFieldBaseProps extends Omit<
   | 'maxLength'
   | 'required'
 > {
+  /** 현재 글자 수와 선택한 길이 기준의 표시 여부입니다. */
   showCount?: boolean;
 }
 
-type TextAreaFieldProps = TextAreaFieldBaseProps &
-  (
-    | { maxLength: number; recommendedLength?: never }
-    | { maxLength?: never; recommendedLength: number }
-    | { maxLength?: undefined; recommendedLength?: undefined }
-  );
+/**
+ * TextArea의 글자 수 기준입니다.
+ *
+ * `maxLength`는 입력을 실제로 제한하고 `recommendedLength`는 초과 입력을 허용합니다.
+ * 두 기준은 동작이 다르므로 동시에 전달할 수 없습니다.
+ */
+type TextAreaLengthProps =
+  | { maxLength: number; recommendedLength?: never }
+  | { maxLength?: never; recommendedLength: number }
+  | { maxLength?: undefined; recommendedLength?: undefined };
 
+/** 실제 textarea 요소의 네이티브 props와 글자 수 기준을 결합한 Field props입니다. */
+type TextAreaFieldProps = TextAreaFieldBaseProps & TextAreaLengthProps;
+
+/** Label은 Root가 제공하는 id와 required 상태를 상속합니다. */
 type TextAreaLabelProps = Omit<ComponentPropsWithoutRef<'label'>, 'htmlFor'> & {
   children: ReactNode;
 };
 
+/** Root가 invalid일 때 유효성 검증 오류를 표시하는 문구입니다. */
 type TextAreaErrorMessageProps = Omit<ComponentPropsWithoutRef<'p'>, 'id'> & {
   children?: ReactNode;
 };

From 84577bfba39b0f7624ab93151faa41752fca1e1f Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 23:38:18 +0900
Subject: [PATCH 6/8] =?UTF-8?q?=F0=9F=90=9B=20Fix:=20=EC=98=A4=EB=A5=98=20?=
 =?UTF-8?q?=EB=A9=94=EC=8B=9C=EC=A7=80=20ARIA=20=EC=B0=B8=EC=A1=B0=20?=
 =?UTF-8?q?=EB=8F=99=EA=B8=B0=ED=99=94?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

실제 ErrorMessage 노드가 렌더링된 경우에만 필드가 오류 id를
참조하도록 등록 상태를 추가했습니다. Context와 상태를 관리하는
Provider도 분리해 각 파일의 책임을 명확히 했습니다.
---
 .../ui/form-control/FormControl.types.ts      | 22 ++++++++++--
 .../form-control/FormControlErrorMessage.tsx  | 19 +++++++---
 .../ui/form-control/FormControlProvider.tsx   | 35 +++++++++++++++++++
 src/shared/ui/input/Input.tsx                 | 10 +++---
 src/shared/ui/input/InputField.tsx            |  8 +++--
 src/shared/ui/textarea/TextArea.tsx           | 10 +++---
 src/shared/ui/textarea/TextAreaField.tsx      | 10 ++++--
 7 files changed, 92 insertions(+), 22 deletions(-)
 create mode 100644 src/shared/ui/form-control/FormControlProvider.tsx

diff --git a/src/shared/ui/form-control/FormControl.types.ts b/src/shared/ui/form-control/FormControl.types.ts
index 829f587..542a27c 100644
--- a/src/shared/ui/form-control/FormControl.types.ts
+++ b/src/shared/ui/form-control/FormControl.types.ts
@@ -1,7 +1,7 @@
 import type { ComponentPropsWithoutRef, ReactNode } from 'react';
 
 /** Input과 TextArea Root가 Label, Field, ErrorMessage에 제공하는 공통 상태입니다. */
-interface FormControlContextValue {
+interface FormControlState {
   disabled: boolean;
   errorMessageId: string;
   fieldId: string;
@@ -9,6 +9,18 @@ interface FormControlContextValue {
   required: boolean;
 }
 
+/** FormControl 하위 컴포넌트가 공유하는 상태와 ErrorMessage 등록 동작입니다. */
+interface FormControlContextValue extends FormControlState {
+  hasErrorMessage: boolean;
+  registerErrorMessage: () => () => void;
+}
+
+/** ErrorMessage 등록 상태를 관리하는 내부 Provider props입니다. */
+interface FormControlProviderProps {
+  children: ReactNode;
+  value: FormControlState;
+}
+
 /** Root의 fieldId와 required 상태를 상속하는 공통 Label props입니다. */
 interface FormControlLabelProps extends Omit<ComponentPropsWithoutRef<'label'>, 'htmlFor'> {
   children: ReactNode;
@@ -19,4 +31,10 @@ interface FormControlErrorMessageProps extends Omit<ComponentPropsWithoutRef<'p'
   children?: ReactNode;
 }
 
-export type { FormControlContextValue, FormControlErrorMessageProps, FormControlLabelProps };
+export type {
+  FormControlContextValue,
+  FormControlErrorMessageProps,
+  FormControlLabelProps,
+  FormControlProviderProps,
+  FormControlState,
+};
diff --git a/src/shared/ui/form-control/FormControlErrorMessage.tsx b/src/shared/ui/form-control/FormControlErrorMessage.tsx
index 34236db..135f2ee 100644
--- a/src/shared/ui/form-control/FormControlErrorMessage.tsx
+++ b/src/shared/ui/form-control/FormControlErrorMessage.tsx
@@ -1,3 +1,5 @@
+import { useEffect } from 'react';
+
 import { cn } from '@/shared/styles/utils/cn';
 
 import { useFormControlContext } from './FormControlContext';
@@ -18,8 +20,8 @@ import type { FormControlErrorMessageProps } from './FormControl.types';
  *
  * ### 접근성
  *
- * Root가 생성한 `errorMessageId`를 사용하며 `role="alert"`로 오류를 알립니다. 실제 Field는
- * 동일한 id를 `aria-describedby`와 `aria-errormessage`에 사용해 오류 문구와 연결합니다.
+ * Root가 생성한 `errorMessageId`를 사용하며 `role="alert"`로 오류를 알립니다. 메시지 노드가
+ * 실제 렌더링된 동안에만 Field가 동일한 id를 ARIA 속성으로 참조하도록 Context에 등록합니다.
  *
  * @param children - 유효성 검증 실패 원인과 해결 방법을 설명하는 문구
  * @param className - 공통 오류 문구 스타일을 확장하는 클래스 이름
@@ -38,9 +40,18 @@ export function FormControlErrorMessage({
   className,
   ...props
 }: FormControlErrorMessageProps) {
-  const { errorMessageId, invalid } = useFormControlContext();
+  const { errorMessageId, invalid, registerErrorMessage } = useFormControlContext();
+  const hasMessage = Boolean(children);
+
+  useEffect(() => {
+    if (!invalid || !hasMessage) {
+      return;
+    }
+
+    return registerErrorMessage();
+  }, [hasMessage, invalid, registerErrorMessage]);
 
-  if (!invalid || !children) {
+  if (!invalid || !hasMessage) {
     return null;
   }
 
diff --git a/src/shared/ui/form-control/FormControlProvider.tsx b/src/shared/ui/form-control/FormControlProvider.tsx
new file mode 100644
index 0000000..9f20447
--- /dev/null
+++ b/src/shared/ui/form-control/FormControlProvider.tsx
@@ -0,0 +1,35 @@
+import { useCallback, useState } from 'react';
+
+import { FormControlContext } from './FormControlContext';
+
+import type { FormControlContextValue, FormControlProviderProps } from './FormControl.types';
+
+/**
+ * ## FormControlProvider
+ *
+ * @description
+ * Input과 TextArea Root의 공통 상태를 제공하고 실제 렌더링된 ErrorMessage의 수를 관리합니다.
+ * Field는 등록된 오류 메시지가 있을 때만 해당 id를 ARIA 속성으로 참조합니다.
+ *
+ * @param children - FormControl Context를 사용하는 compound 하위 컴포넌트
+ * @param value - Root가 제공하는 id, required, disabled, invalid 상태
+ */
+export function FormControlProvider({ children, value }: FormControlProviderProps) {
+  const [errorMessageCount, setErrorMessageCount] = useState(0);
+
+  const registerErrorMessage = useCallback(() => {
+    setErrorMessageCount((currentCount) => currentCount + 1);
+
+    return () => {
+      setErrorMessageCount((currentCount) => Math.max(0, currentCount - 1));
+    };
+  }, []);
+
+  const contextValue: FormControlContextValue = {
+    ...value,
+    hasErrorMessage: errorMessageCount > 0,
+    registerErrorMessage,
+  };
+
+  return <FormControlContext value={contextValue}>{children}</FormControlContext>;
+}
diff --git a/src/shared/ui/input/Input.tsx b/src/shared/ui/input/Input.tsx
index ae821be..95c3032 100644
--- a/src/shared/ui/input/Input.tsx
+++ b/src/shared/ui/input/Input.tsx
@@ -3,8 +3,8 @@
 import { useId } from 'react';
 
 import { cn } from '@/shared/styles/utils/cn';
-import type { FormControlContextValue } from '@/shared/ui/form-control/FormControl.types';
-import { FormControlContext } from '@/shared/ui/form-control/FormControlContext';
+import type { FormControlState } from '@/shared/ui/form-control/FormControl.types';
+import { FormControlProvider } from '@/shared/ui/form-control/FormControlProvider';
 
 import { InputErrorMessage } from './InputErrorMessage';
 import { InputField } from './InputField';
@@ -89,7 +89,7 @@ function InputRoot({
 }: InputProps) {
   const generatedId = useId();
   const fieldId = id ?? `input-${generatedId}`;
-  const contextValue: FormControlContextValue = {
+  const contextValue: FormControlState = {
     disabled,
     errorMessageId: `${fieldId}-error-message`,
     fieldId,
@@ -98,7 +98,7 @@ function InputRoot({
   };
 
   return (
-    <FormControlContext value={contextValue}>
+    <FormControlProvider value={contextValue}>
       <div
         {...props}
         className={cn('flex w-full flex-col', className)}
@@ -108,7 +108,7 @@ function InputRoot({
       >
         {children}
       </div>
-    </FormControlContext>
+    </FormControlProvider>
   );
 }
 
diff --git a/src/shared/ui/input/InputField.tsx b/src/shared/ui/input/InputField.tsx
index ac5ca4e..c9a9d50 100644
--- a/src/shared/ui/input/InputField.tsx
+++ b/src/shared/ui/input/InputField.tsx
@@ -34,13 +34,15 @@ import type { InputFieldProps } from './Input.types';
  * ```
  */
 export function InputField({ className, ref, type = 'text', ...props }: InputFieldProps) {
-  const { disabled, errorMessageId, fieldId, invalid, required } = useFormControlContext();
+  const { disabled, errorMessageId, fieldId, hasErrorMessage, invalid, required } =
+    useFormControlContext();
+  const describedBy = invalid && hasErrorMessage ? errorMessageId : undefined;
 
   return (
     <input
       {...props}
-      aria-describedby={invalid ? errorMessageId : undefined}
-      aria-errormessage={invalid ? errorMessageId : undefined}
+      aria-describedby={describedBy}
+      aria-errormessage={describedBy}
       aria-invalid={invalid || undefined}
       aria-required={required || undefined}
       className={cn(
diff --git a/src/shared/ui/textarea/TextArea.tsx b/src/shared/ui/textarea/TextArea.tsx
index ca1b952..c793f88 100644
--- a/src/shared/ui/textarea/TextArea.tsx
+++ b/src/shared/ui/textarea/TextArea.tsx
@@ -3,8 +3,8 @@
 import { useId } from 'react';
 
 import { cn } from '@/shared/styles/utils/cn';
-import type { FormControlContextValue } from '@/shared/ui/form-control/FormControl.types';
-import { FormControlContext } from '@/shared/ui/form-control/FormControlContext';
+import type { FormControlState } from '@/shared/ui/form-control/FormControl.types';
+import { FormControlProvider } from '@/shared/ui/form-control/FormControlProvider';
 
 import { TextAreaErrorMessage } from './TextAreaErrorMessage';
 import { TextAreaField } from './TextAreaField';
@@ -54,7 +54,7 @@ function TextAreaRoot({
 }: TextAreaProps) {
   const generatedId = useId();
   const fieldId = id ?? `text-area-${generatedId}`;
-  const contextValue: FormControlContextValue = {
+  const contextValue: FormControlState = {
     disabled,
     errorMessageId: `${fieldId}-error-message`,
     fieldId,
@@ -63,7 +63,7 @@ function TextAreaRoot({
   };
 
   return (
-    <FormControlContext value={contextValue}>
+    <FormControlProvider value={contextValue}>
       <div
         {...props}
         className={cn('flex w-full flex-col', className)}
@@ -73,7 +73,7 @@ function TextAreaRoot({
       >
         {children}
       </div>
-    </FormControlContext>
+    </FormControlProvider>
   );
 }
 
diff --git a/src/shared/ui/textarea/TextAreaField.tsx b/src/shared/ui/textarea/TextAreaField.tsx
index 0aa8a51..c95e52b 100644
--- a/src/shared/ui/textarea/TextAreaField.tsx
+++ b/src/shared/ui/textarea/TextAreaField.tsx
@@ -38,12 +38,16 @@ export function TextAreaField({
   value,
   ...props
 }: TextAreaFieldProps) {
-  const { disabled, errorMessageId, fieldId, invalid, required } = useFormControlContext();
+  const { disabled, errorMessageId, fieldId, hasErrorMessage, invalid, required } =
+    useFormControlContext();
   const [uncontrolledLength, setUncontrolledLength] = useState(() => getValueLength(defaultValue));
   const isControlled = value !== undefined;
   const currentLength = isControlled ? getValueLength(value) : uncontrolledLength;
   const countId = `${fieldId}-character-count`;
-  const describedBy = [showCount ? countId : undefined, invalid ? errorMessageId : undefined]
+  const describedBy = [
+    showCount ? countId : undefined,
+    invalid && hasErrorMessage ? errorMessageId : undefined,
+  ]
     .filter(Boolean)
     .join(' ');
   const hasReachedMaxLength = maxLength !== undefined && currentLength >= maxLength;
@@ -77,7 +81,7 @@ export function TextAreaField({
       <textarea
         {...props}
         aria-describedby={describedBy || undefined}
-        aria-errormessage={invalid ? errorMessageId : undefined}
+        aria-errormessage={invalid && hasErrorMessage ? errorMessageId : undefined}
         aria-invalid={invalid || undefined}
         aria-required={required || undefined}
         className={cn(

From 657ef2557082089357ebf5500b7d9eebd3cf84dd Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 23:45:37 +0900
Subject: [PATCH 7/8] =?UTF-8?q?=F0=9F=90=9B=20Fix:=20=ED=8F=BC=20=ED=95=84?=
 =?UTF-8?q?=EB=93=9C=20ARIA=20=EC=97=AD=ED=95=A0=20=EB=B6=84=EB=A6=AC?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

보조 설명은 aria-describedby로, 오류 메시지는 aria-errormessage로
연결하도록 역할을 분리했습니다. Input에는 불필요한 설명 참조를
제거하고 TextArea는 글자 수 안내만 설명으로 유지했습니다.
---
 .../ui/form-control/FormControlErrorMessage.tsx      |  2 +-
 src/shared/ui/input/Input.types.ts                   |  2 +-
 src/shared/ui/input/InputField.tsx                   |  9 ++++-----
 src/shared/ui/textarea/TextAreaField.tsx             | 12 ++++--------
 4 files changed, 10 insertions(+), 15 deletions(-)

diff --git a/src/shared/ui/form-control/FormControlErrorMessage.tsx b/src/shared/ui/form-control/FormControlErrorMessage.tsx
index 135f2ee..58f4914 100644
--- a/src/shared/ui/form-control/FormControlErrorMessage.tsx
+++ b/src/shared/ui/form-control/FormControlErrorMessage.tsx
@@ -21,7 +21,7 @@ import type { FormControlErrorMessageProps } from './FormControl.types';
  * ### 접근성
  *
  * Root가 생성한 `errorMessageId`를 사용하며 `role="alert"`로 오류를 알립니다. 메시지 노드가
- * 실제 렌더링된 동안에만 Field가 동일한 id를 ARIA 속성으로 참조하도록 Context에 등록합니다.
+ * 실제 렌더링된 동안에만 Field가 동일한 id를 `aria-errormessage`로 참조하도록 등록합니다.
  *
  * @param children - 유효성 검증 실패 원인과 해결 방법을 설명하는 문구
  * @param className - 공통 오류 문구 스타일을 확장하는 클래스 이름
diff --git a/src/shared/ui/input/Input.types.ts b/src/shared/ui/input/Input.types.ts
index bd3b69a..8c0264a 100644
--- a/src/shared/ui/input/Input.types.ts
+++ b/src/shared/ui/input/Input.types.ts
@@ -40,7 +40,7 @@ interface InputFieldGroupProps extends ComponentPropsWithoutRef<'div'> {
  */
 interface InputFieldProps extends Omit<
   ComponentPropsWithRef<'input'>,
-  'aria-describedby' | 'aria-invalid' | 'disabled' | 'id' | 'readOnly' | 'required' | 'type'
+  'aria-errormessage' | 'aria-invalid' | 'disabled' | 'id' | 'readOnly' | 'required' | 'type'
 > {
   type?: InputType;
 }
diff --git a/src/shared/ui/input/InputField.tsx b/src/shared/ui/input/InputField.tsx
index c9a9d50..6d50b54 100644
--- a/src/shared/ui/input/InputField.tsx
+++ b/src/shared/ui/input/InputField.tsx
@@ -21,8 +21,8 @@ import type { InputFieldProps } from './Input.types';
  *
  * ### 접근성
  *
- * Root 상태에 따라 `required`, `aria-invalid`, `aria-describedby`, `aria-errormessage`를
- * 설정합니다. 접근성 이름은 함께 구성한 `Input.Label`에서 제공받습니다.
+ * Root 상태에 따라 `required`, `aria-invalid`, `aria-errormessage`를 설정합니다.
+ * 접근성 이름은 함께 구성한 `Input.Label`에서 제공받습니다.
  *
  * @param type - 지원하는 입력 타입. 기본값은 `text`
  * @param ref - Field DOM 요소에 접근하거나 폼 라이브러리와 연결하는 ref
@@ -36,13 +36,12 @@ import type { InputFieldProps } from './Input.types';
 export function InputField({ className, ref, type = 'text', ...props }: InputFieldProps) {
   const { disabled, errorMessageId, fieldId, hasErrorMessage, invalid, required } =
     useFormControlContext();
-  const describedBy = invalid && hasErrorMessage ? errorMessageId : undefined;
+  const ariaErrorMessageId = invalid && hasErrorMessage ? errorMessageId : undefined;
 
   return (
     <input
       {...props}
-      aria-describedby={describedBy}
-      aria-errormessage={describedBy}
+      aria-errormessage={ariaErrorMessageId}
       aria-invalid={invalid || undefined}
       aria-required={required || undefined}
       className={cn(
diff --git a/src/shared/ui/textarea/TextAreaField.tsx b/src/shared/ui/textarea/TextAreaField.tsx
index c95e52b..d502cf7 100644
--- a/src/shared/ui/textarea/TextAreaField.tsx
+++ b/src/shared/ui/textarea/TextAreaField.tsx
@@ -44,12 +44,8 @@ export function TextAreaField({
   const isControlled = value !== undefined;
   const currentLength = isControlled ? getValueLength(value) : uncontrolledLength;
   const countId = `${fieldId}-character-count`;
-  const describedBy = [
-    showCount ? countId : undefined,
-    invalid && hasErrorMessage ? errorMessageId : undefined,
-  ]
-    .filter(Boolean)
-    .join(' ');
+  const describedBy = showCount ? countId : undefined;
+  const ariaErrorMessageId = invalid && hasErrorMessage ? errorMessageId : undefined;
   const hasReachedMaxLength = maxLength !== undefined && currentLength >= maxLength;
   const hasExceededRecommendedLength =
     recommendedLength !== undefined && currentLength > recommendedLength;
@@ -80,8 +76,8 @@ export function TextAreaField({
     <div className="relative w-full">
       <textarea
         {...props}
-        aria-describedby={describedBy || undefined}
-        aria-errormessage={invalid && hasErrorMessage ? errorMessageId : undefined}
+        aria-describedby={describedBy}
+        aria-errormessage={ariaErrorMessageId}
         aria-invalid={invalid || undefined}
         aria-required={required || undefined}
         className={cn(

From 9b3440739353be916b7615c0272f48b847c22956 Mon Sep 17 00:00:00 2001
From: Leeseojeong <sjung0314@gmail.com>
Date: Mon, 22 Jun 2026 23:55:47 +0900
Subject: [PATCH 8/8] =?UTF-8?q?=F0=9F=90=9B=20Fix:=20TextArea=20Field=20ch?=
 =?UTF-8?q?ildren=20=EC=A0=9C=ED=95=9C?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

TextArea.Field가 네이티브 textarea의 children을 상속하지 않도록
제외해 value와 defaultValue 기반 입력 계약을 보장했습니다.
---
 src/shared/ui/textarea/TextArea.types.ts | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/shared/ui/textarea/TextArea.types.ts b/src/shared/ui/textarea/TextArea.types.ts
index dd857d5..573b12e 100644
--- a/src/shared/ui/textarea/TextArea.types.ts
+++ b/src/shared/ui/textarea/TextArea.types.ts
@@ -26,6 +26,7 @@ interface TextAreaFieldBaseProps extends Omit<
   | 'aria-describedby'
   | 'aria-errormessage'
   | 'aria-invalid'
+  | 'children'
   | 'disabled'
   | 'id'
   | 'maxLength'