@uniai-fe/uds-primitives 0.12.5 → 0.12.7

package/src/components/button/styles/round-button.scss

@@ -3,55 +3,28 @@
 // 라운드 버튼 사이즈 토큰을 맵으로 정의해 중복 제거
 $round-size-map: (
   small: (
-    min-height: var(
-        --button-round-height-small,
-        var(--theme-size-small-2, 24px)
-      ),
-    padding-inline: var(
-        --button-round-padding-inline-small,
-        var(--spacing-padding-5, 12px)
-      ),
-    radius: var(--button-round-radius-small, var(--theme-radius-xlarge-2, 16px)),
+    min-height: var(--button-round-height-small),
+    padding-inline: var(--button-round-padding-inline-small),
+    radius: var(--button-round-radius-small),
   ),
   medium: (
-    min-height: var(
-        --button-round-height-medium,
-        var(--theme-size-small-3, 32px)
-      ),
-    padding-inline: var(
-        --button-round-padding-inline-medium,
-        var(--spacing-padding-6, 16px)
-      ),
-    radius: var(
-        --button-round-radius-medium,
-        var(--theme-radius-xlarge-2, 16px)
-      ),
+    min-height: var(--button-round-height-medium),
+    padding-inline: var(--button-round-padding-inline-medium),
+    radius: var(--button-round-radius-medium),
   ),
   large: (
-    min-height: var(
-        --button-round-height-large,
-        var(--theme-size-medium-1, 40px)
-      ),
-    padding-inline: var(
-        --button-round-padding-inline-large,
-        var(--spacing-padding-7, 20px)
-      ),
-    radius: var(--button-round-radius-large, 30px),
+    min-height: var(--button-round-height-large),
+    padding-inline: var(--button-round-padding-inline-large),
+    radius: var(--button-round-radius-large),
   ),
 );
 
 .button {
   &:where(.button-template-round) {
     min-width: auto;
-    padding-block: var(
-      --button-round-padding-block-base,
-      var(--spacing-padding-2, 4px)
-    );
-    padding-inline: var(
-      --button-round-padding-inline-medium,
-      var(--spacing-padding-6, 16px)
-    );
-    gap: var(--spacing-gap-2, 8px);
+    padding-block: var(--button-round-padding-block-base);
+    padding-inline: var(--button-round-padding-inline-medium);
+    gap: var(--spacing-gap-2);
   }
 
   @each $size, $tokens in $round-size-map {

package/src/components/button/styles/text-button.scss

@@ -3,28 +3,16 @@
 // 텍스트 버튼 사이즈 토큰을 맵으로 정의해 가독성을 높인다
 $text-size-map: (
   small: (
-    min-height: var(--button-text-height-small, var(--theme-size-small-1, 20px)),
-    padding-inline: var(
-        --button-text-padding-inline-small,
-        var(--spacing-padding-4, 8px)
-      ),
+    min-height: var(--button-text-height-small),
+    padding-inline: var(--button-text-padding-inline-small),
   ),
   medium: (
-    min-height: var(
-        --button-text-height-medium,
-        var(--theme-size-small-2, 24px)
-      ),
-    padding-inline: var(
-        --button-text-padding-inline-medium,
-        var(--spacing-padding-5, 12px)
-      ),
+    min-height: var(--button-text-height-medium),
+    padding-inline: var(--button-text-padding-inline-medium),
   ),
   large: (
-    min-height: var(--button-text-height-large, var(--theme-size-small-3, 32px)),
-    padding-inline: var(
-        --button-text-padding-inline-large,
-        var(--spacing-padding-5, 12px)
-      ),
+    min-height: var(--button-text-height-large),
+    padding-inline: var(--button-text-padding-inline-large),
   ),
 );
 
@@ -33,20 +21,11 @@ $text-size-map: (
     min-width: auto;
     border-color: transparent;
     background-color: transparent;
-    padding-block: var(
-      --button-text-padding-block-base,
-      var(--spacing-padding-4, 8px)
-    );
-    padding-inline: var(
-      --button-text-padding-inline-small,
-      var(--spacing-padding-4, 8px)
-    );
+    padding-block: var(--button-text-padding-block-base);
+    padding-inline: var(--button-text-padding-inline-small);
     border-width: 0;
-    gap: var(--spacing-gap-1, 4px);
-    border-radius: var(
-      --button-text-radius-base,
-      var(--theme-radius-small, 4px)
-    );
+    gap: var(--spacing-gap-1);
+    border-radius: var(--button-text-radius-base);
   }
 
   @each $size, $tokens in $text-size-map {
@@ -62,45 +41,30 @@ $text-size-map: (
   }
 
   &:where(.button-template-text.button-priority-secondary) {
-    color: var(
-      --button-text-secondary-foreground,
-      var(--color-primary-default)
-    );
+    color: var(--button-text-secondary-foreground);
 
     &:hover:not(:disabled),
     &[data-user-action="hover"]:not(:disabled) {
-      background-color: var(
-        --button-text-secondary-hover-bg,
-        var(--color-bg-alternative-cool-gray, var(--color-cool-gray-95))
-      );
+      background-color: var(--button-text-secondary-hover-bg);
     }
 
     &:active:not(:disabled),
     &[data-user-action="pressed"]:not(:disabled) {
-      background-color: var(
-        --button-text-secondary-pressed-bg,
-        var(--color-secondary-strong, var(--color-blue-90))
-      );
+      background-color: var(--button-text-secondary-pressed-bg);
     }
   }
 
   &:where(.button-template-text.button-priority-tertiary) {
-    color: var(--button-text-tertiary-foreground, var(--color-cool-gray-10));
+    color: var(--button-text-tertiary-foreground);
 
     &:hover:not(:disabled),
     &[data-user-action="hover"]:not(:disabled) {
-      background-color: var(
-        --button-text-tertiary-hover-bg,
-        var(--color-bg-alternative-cool-gray, var(--color-cool-gray-95))
-      );
+      background-color: var(--button-text-tertiary-hover-bg);
     }
 
     &:active:not(:disabled),
     &[data-user-action="pressed"]:not(:disabled) {
-      background-color: var(
-        --button-text-tertiary-pressed-bg,
-        var(--color-surface-strong, var(--color-cool-gray-20))
-      );
+      background-color: var(--button-text-tertiary-pressed-bg);
     }
   }
 }

package/src/components/button/styles/variables.scss

@@ -25,11 +25,11 @@
   /* default button sizing */
   --button-default-width-min-base: var(--theme-size-small-2);
 
-  --button-default-height-small: var(--theme-size-small-3, 32px);
-  --button-default-height-medium: var(--theme-size-medium-1, 40px);
-  --button-default-height-large: var(--theme-size-medium-2, 48px);
-  --button-default-height-xlarge: var(--theme-size-medium-3, 56px);
-  --button-default-height-table: var(--theme-size-small-2, 24px);
+  --button-default-height-small: var(--theme-size-small-3);
+  --button-default-height-medium: var(--theme-size-medium-1);
+  --button-default-height-large: var(--theme-size-medium-2);
+  --button-default-height-xlarge: var(--theme-size-medium-3);
+  --button-default-height-table: var(--theme-size-small-2);
 
   --button-default-radius-small: var(--theme-radius-medium-3);
   --button-default-radius-medium: var(--theme-radius-medium-3);
@@ -38,68 +38,57 @@
   --button-default-radius-table: var(--theme-radius-medium-2);
 
   /* text buttons */
-  --button-text-padding-block-base: var(--spacing-padding-4, 8px);
-  --button-text-padding-inline-small: var(--spacing-padding-4, 8px);
-  --button-text-padding-inline-medium: var(--spacing-padding-5, 12px);
-  --button-text-padding-inline-large: var(--spacing-padding-5, 12px);
-  --button-text-height-small: var(--theme-size-small-1, 20px);
-  --button-text-height-medium: var(--theme-size-small-2, 24px);
-  --button-text-height-large: var(--theme-size-small-3, 32px);
-  --button-text-radius-base: var(--theme-radius-small, 4px);
+  --button-text-padding-block-base: var(--spacing-padding-4);
+  --button-text-padding-inline-small: var(--spacing-padding-4);
+  --button-text-padding-inline-medium: var(--spacing-padding-5);
+  --button-text-padding-inline-large: var(--spacing-padding-5);
+  --button-text-height-small: var(--theme-size-small-1);
+  --button-text-height-medium: var(--theme-size-small-2);
+  --button-text-height-large: var(--theme-size-small-3);
+  --button-text-radius-base: var(--theme-radius-small);
 
   /* round buttons */
-  --button-round-padding-inline-small: var(--spacing-padding-5, 12px);
-  --button-round-padding-inline-medium: var(--spacing-padding-6, 16px);
-  --button-round-padding-inline-large: var(--spacing-padding-7, 20px);
-  --button-round-padding-block-base: var(--spacing-padding-2, 4px);
-  --button-round-height-small: var(--theme-size-small-2, 24px);
-  --button-round-height-medium: var(--theme-size-small-3, 32px);
-  --button-round-height-large: var(--theme-size-medium-1, 40px);
-  --button-round-radius-small: var(--theme-radius-xlarge-2, 16px);
-  --button-round-radius-medium: var(--theme-radius-xlarge-2, 16px);
+  --button-round-padding-inline-small: var(--spacing-padding-5);
+  --button-round-padding-inline-medium: var(--spacing-padding-6);
+  --button-round-padding-inline-large: var(--spacing-padding-7);
+  --button-round-padding-block-base: var(--spacing-padding-2);
+  --button-round-height-small: var(--theme-size-small-2);
+  --button-round-height-medium: var(--theme-size-small-3);
+  --button-round-height-large: var(--theme-size-medium-1);
+  --button-round-radius-small: var(--theme-radius-xlarge);
+  --button-round-radius-medium: var(--theme-radius-xlarge);
   --button-round-radius-large: 30px;
 
   /* typography */
   --button-default-font-weight: 400;
-  --button-default-font-body-medium-family: var(--font-body-medium-family);
   --button-default-font-body-medium-size: var(--font-body-medium-size);
   --button-default-font-body-medium-weight: var(--button-default-font-weight);
-  --button-default-font-body-medium-line-height: var(
-    --font-body-medium-line-height
-  );
+  --button-default-font-body-medium-line-height: 1em;
   --button-default-font-body-medium-letter-spacing: var(
     --font-body-medium-letter-spacing
   );
   --button-default-font-label-medium-size: var(--font-body-xxsmall-size);
   --button-default-font-label-medium-weight: var(--button-default-font-weight);
-  --button-default-font-label-medium-line-height: var(
-    --font-body-xxsmall-line-height
-  );
+  --button-default-font-label-medium-line-height: 1em;
   --button-default-font-label-medium-letter-spacing: var(
     --font-body-xxsmall-letter-spacing
   );
   --button-default-font-label-large-size: var(--font-body-xsmall-size);
   --button-default-font-label-large-weight: var(--button-default-font-weight);
-  --button-default-font-label-large-line-height: var(
-    --font-body-xsmall-line-height
-  );
+  --button-default-font-label-large-line-height: 1em;
   --button-default-font-label-large-letter-spacing: var(
     --font-body-xsmall-letter-spacing
   );
   --button-default-font-body-large-size: var(--font-body-large-size);
   --button-default-font-body-large-weight: var(--button-default-font-weight);
-  --button-default-font-body-large-line-height: var(
-    --font-body-large-line-height
-  );
+  --button-default-font-body-large-line-height: 1em;
   --button-default-font-body-large-letter-spacing: var(
     --font-body-large-letter-spacing
   );
   /* 변경: table 버튼은 caption-large 스케일(12px)을 사용한다. */
   --button-default-font-caption-large-size: var(--font-caption-large-size);
   --button-default-font-caption-large-weight: var(--button-default-font-weight);
-  --button-default-font-caption-large-line-height: var(
-    --font-caption-large-line-height
-  );
+  --button-default-font-caption-large-line-height: 1em;
   --button-default-font-caption-large-letter-spacing: var(
     --font-caption-large-letter-spacing
   );
@@ -107,6 +96,7 @@
   --button-default-neutral-foreground: var(--color-neutral-20);
   --button-default-neutral-disabled-bg: var(--color-surface-standard);
   --button-default-neutral-disabled-foreground: var(--color-label-disabled);
+  --button-default-outline-bg: var(--color-surface-static-white);
 
   --button-default-primary-solid-bg: var(--color-primary-default);
   --button-default-primary-solid-hover-bg: var(--color-blue-50);
@@ -118,7 +108,7 @@
   --button-default-primary-outline-hover-foreground: var(--color-common-100);
   --button-default-primary-overlay-outlined-bg: var(--color-blue-90);
 
-  --button-default-secondary-solid-bg: var(--color-blue-95, #e5eeff);
+  --button-default-secondary-solid-bg: var(--color-blue-95);
   --button-default-secondary-solid-hover-bg: #dbe9ff;
   --button-default-secondary-solid-active-bg: #ccdeff;
   --button-default-secondary-solid-foreground: var(--color-primary-default);
@@ -216,21 +206,9 @@
 
   /* text button colors */
   --button-text-secondary-foreground: var(--color-primary-default);
-  --button-text-secondary-hover-bg: var(
-    --color-bg-alternative-cool-gray,
-    var(--color-cool-gray-95)
-  );
-  --button-text-secondary-pressed-bg: var(
-    --color-secondary-strong,
-    var(--color-blue-90)
-  );
+  --button-text-secondary-hover-bg: var(--color-bg-alternative-cool-gray);
+  --button-text-secondary-pressed-bg: var(--color-secondary-strong);
   --button-text-tertiary-foreground: var(--color-cool-gray-10);
-  --button-text-tertiary-hover-bg: var(
-    --color-bg-alternative-cool-gray,
-    var(--color-cool-gray-95)
-  );
-  --button-text-tertiary-pressed-bg: var(
-    --color-surface-strong,
-    var(--color-cool-gray-20)
-  );
+  --button-text-tertiary-hover-bg: var(--color-bg-alternative-cool-gray);
+  --button-text-tertiary-pressed-bg: var(--color-surface-strong);
 }

package/src/components/button/types/options.ts

@@ -10,22 +10,25 @@ import type {
 
 /**
  * Button Types; scale 구성 객체 타입
- * @property {ButtonFill} fill fill 옵션.
- * @property {ButtonScaleGroup} group scale group 옵션.
- * @property {ButtonSize} size size 옵션.
+ * @property {"solid" | "outlined"} fill fill 옵션.
+ * @property {"solid" | "outlined"} group scale group 옵션.
+ * @property {"xlarge" | "large" | "medium" | "small" | "table"} size size 옵션.
  * @deprecated
  */
-type ButtonScaleConfig = {
+export type ButtonScaleConfig = {
   /**
    * fill 옵션.
+   * "solid" | "outlined"
    */
   fill: ButtonFill;
   /**
    * scale group 옵션.
+   * "solid" | "outlined"
    */
   group: ButtonScaleGroup;
   /**
    * size 옵션.
+   * "xlarge" | "large" | "medium" | "small" | "table"
    */
   size: ButtonSize;
 };

package/src/components/button/types/props.ts

@@ -28,7 +28,7 @@ export type ButtonPriority =
  * @typedef {"solid" | "outlined"} ButtonFill
  * @desc
  * - solid: 배경을 채우는 스타일.
- * - outlined: 배경을 비우고 선만 두르는 스타일.
+ * - outlined: 흰색 기본 면에 테두리를 두르는 스타일.
  */
 export type ButtonFill = "solid" | "outlined";
 
@@ -52,6 +52,7 @@ export type ButtonSize = "xlarge" | "large" | "medium" | "small" | "table";
  * } ButtonScale
  * @deprecated
  * @desc
+ * Base는 전달된 값을 완전히 무시하며 fill/size fallback으로 사용하지 않는다.
  * - solid-xlarge~solid-small: Solid fill + size 조합.
  * - outlined-xlarge~outlined-small: Outline fill + size 조합.
  */
@@ -92,27 +93,27 @@ export type ButtonScaleGroup = ButtonFill;
 /**
  * Button; <button /> native props 타입
  */
-type NativeButtonProps = ComponentPropsWithoutRef<"button">;
+export type NativeButtonProps = ComponentPropsWithoutRef<"button">;
 /**
  * Button; <a /> native props 타입
  */
-type AnchorProps = ComponentPropsWithoutRef<"a">;
+export type AnchorProps = ComponentPropsWithoutRef<"a">;
 
 /**
  * Button; 컴포넌트 공통 props 타입
  */
-type SharedElementProps = Omit<NativeButtonProps, "children"> &
+export type SharedElementProps = Omit<NativeButtonProps, "children"> &
   Omit<AnchorProps, "children">;
 
 /**
  * Button 컴포넌트의 공통 props.
  * @property {ElementType} [as] 렌더링할 요소. 기본값은 button.
  * @property {ReactNode} [children] 주 내용. 문자열이면 자동으로 .button-label로 감싼다.
- * @property {"solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" | "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"} [scale] 레이아웃/spacing 집합. 추후 fill/size 조합으로 대체 예정이다.
- * @property {"solid" | "outlined"} fill 채움 스타일. scale 조합보다 우선한다.
- * @property {"xlarge" | "large" | "medium" | "small" | "table"} size 높이/타이포 스케일. scale 조합보다 우선한다.
+ * @property {"solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" | "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"} [scale] deprecated 호환 입력. Base는 값을 완전히 무시하며 fill/size fallback이 아니다.
+ * @property {"solid" | "outlined"} fill 필수 채움 스타일.
+ * @property {"xlarge" | "large" | "medium" | "small" | "table"} size 필수 높이/타이포 스케일.
  * @property {"primary" | "secondary" | "tertiary" | "green" | "yellow" | "orange" | "teal" | "pink" | "red" | "darkGray" | "lightGray"} priority semantic color priority.
- * @property {"default" | "readonly" | "disabled"} [state] UI 상태. disabled prop과 조합된다.
+ * @property {"default" | "readonly" | "disabled"} [state] UI 상태. 최종 값은 loading → disabled → state 순서로 계산된다.
  * @property {boolean} [block] width:100% 확장 여부.
  * @property {FormFieldWidth} [width] width preset. block보다 우선 적용된다.
  * @property {boolean} [loading] true면 readonly 처리 + aria-busy.
@@ -135,7 +136,7 @@ export interface ButtonProps extends SharedElementProps {
    * @deprecated
    * "solid-xlarge" | "solid-large" | "solid-medium" | "solid-small" |
    * "outlined-xlarge" | "outlined-large" | "outlined-medium" | "outlined-small"
-   * fill/size를 제공하지 않을 때만 fallback으로 사용한다.
+   * Base는 값을 완전히 무시하며 fill/size fallback이 아니다. 필수 fill과 size를 사용한다.
    */
   scale?: ButtonScale;
   /**
@@ -156,7 +157,7 @@ export interface ButtonProps extends SharedElementProps {
   size: ButtonSize;
   /**
    * 컴포넌트 내부 state.
-   * disabled prop과 병합되어 최종 상태를 결정한다.
+   * loading → disabled → state 우선순위로 최종 상태를 결정한다.
    * "default" | "readonly" | "disabled"
    */
   state?: ButtonState;
@@ -188,10 +189,6 @@ export interface ButtonProps extends SharedElementProps {
   "data-user-action"?: ButtonUserAction;
 }
 
-/**
- * 변경 사항: preset 타입 파일을 제거하고 props.ts로 통합한다.
- */
-
 /**
  * Button Types; Text preset size 옵션
  * @typedef {"small" | "medium" | "large"} TextButtonSize

package/src/components/button/utils/index.ts

@@ -1,15 +1,26 @@
 import clsx from "clsx";
-type ButtonClassNameOptions = {
+
+/**
+ * Button utility; className 조합 입력
+ * @property {string} [className] 기본 `button` class와 병합할 추가 className.
+ */
+export type ButtonClassNameOptions = {
+  /**
+   * 기본 `button` class와 병합할 추가 className.
+   */
   className?: string;
 };
 
 const BUTTON_CLASSNAME = "button";
 
 /**
- * 버튼 클래스 조합 helper: scale/fill/priority/size 별 modifier를 한 곳에서 관리한다.
+ * Button utility; 기본 className 조합
+ * @utility
+ * @property {string} [className] 기본 `button` class와 병합할 추가 className.
+ * @desc 기본 `button` class와 전달된 className만 clsx로 병합하며 modifier는 생성하지 않는다.
+ * @return {string} 병합된 className.
  */
 const composeButtonClassName = ({ className }: ButtonClassNameOptions) =>
   clsx(BUTTON_CLASSNAME, className);
 
 export { BUTTON_CLASSNAME, composeButtonClassName };
-export type { ButtonClassNameOptions };

package/src/components/form/markup/Provider.tsx

@@ -1,7 +1,6 @@
 "use client";
 
 import { useEffect } from "react";
-// import { useEffect } from "react";
 import {
   FormProvider as ReactHookFormProvider,
   useForm,
@@ -11,7 +10,13 @@ import {
 } from "react-hook-form";
 
 /**
- * react-hook-form; context provider
+ * Form Component; react-hook-form context provider
+ * @component
+ * @param {object} props Form provider props
+ * @property {React.ReactNode} props.children provider 하위 콘텐츠
+ * @property {UseFormProps<FormDataType>} [props.options] useForm 초기 옵션
+ * @property {(params: UseFormReturn<FormDataType>) => void | undefined} [props.callback] 생성된 form methods 전달 callback
+ * @desc useForm methods를 생성하고 React Hook Form context로 제공하며 callback이 있으면 effect에서 methods를 전달한다.
  */
 export default function FormProvider<FormDataType extends FieldValues>({
   children,
@@ -27,7 +32,6 @@ export default function FormProvider<FormDataType extends FieldValues>({
 
   useEffect(() => {
     if (typeof callback === "undefined") return;
-    // if (typeof callback !== "undefined")
     callback(formMethods);
   }, [callback, formMethods]);
 

package/src/components/form/markup/form-field/Body.tsx

@@ -6,6 +6,7 @@ import clsx from "clsx";
  * @param {object} props
  * @property {string} [className]
  * @property {React.ReactNode} [children]
+ * @desc field control과 주요 콘텐츠를 body 영역에 렌더링한다.
  */
 export default function FormFieldBody({
   className,

package/src/components/form/markup/form-field/Container.tsx

@@ -13,10 +13,12 @@ import {
  * @component
  * @param {FormFieldContainerProps} props
  * @property {React.ElementType} [as] container 태그 지정 (default: <section />)
- * @property {FormFieldWidth} [width] form field 너비 옵션
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] form field 너비 옵션
+ * @property {"default" | "error"} [state] visual state
  * @property {string} [className]
  * @property {React.ReactNode} [children]
  * @property {React.HTMLAttributes<HTMLElement>} [containerProps] container 속성
+ * @desc width를 data attribute와 CSS variable로 변환하고 visual state를 노출하는 field wrapper다.
  */
 const FormFieldContainer = forwardRef<HTMLElement, FormFieldContainerProps>(
   (

package/src/components/form/markup/form-field/Footer.tsx

@@ -7,6 +7,7 @@ import type { FormFieldFooterProps } from "../../types";
  * @param {FormFieldFooterProps} props
  * @property {string} [className]
  * @property {React.ReactNode} [children]
+ * @desc helper 또는 action 콘텐츠와 footer DOM 속성을 렌더링한다.
  */
 export default function FormFieldFooter({
   className,

package/src/components/form/markup/form-field/Header.tsx

@@ -10,11 +10,13 @@ import { Slot } from "../../../slot";
  * @param {FormFieldHeaderProps} props
  * @property {string} [className]
  * @property {string} [label] 필드명
+ * @property {React.ReactNode} [labelJsx] label보다 우선하는 커스텀 label JSX
  * @property {React.ElementType} [labelAs] 필드 태그 지정 (default: <h5 />)
  * @property {string} [labelId] 필드 아이디 지정
  * @property {boolean} [required] 필수 여부
  * @property {React.ReactNode} [children] 추가 헤더 내용
  * @property {React.HTMLAttributes<HTMLElement>} [labelProps] 추가 라벨 속성
+ * @desc labelJsx를 우선 렌더링하고 문자열 label은 Slot.Text로 감싸 필수 표시와 함께 구성한다.
  */
 export default function FormFieldHeader({
   className,

package/src/components/form/markup/form-field/Template.tsx

@@ -17,10 +17,11 @@ import FormFieldContainer from "./Container";
  * @property {React.ReactNode} [footer] 푸터 내용
  * @property {FormFieldHeaderProps} [headerProps] 헤더 속성
  * @property {FormFieldFooterProps} [footerProps] 푸터 속성
- * @property {FormFieldWidth} [width] form field 너비 옵션
- * @property {FormFieldState} [state] visual state
+ * @property {"full" | "fit" | "fill" | "auto" | number | string} [width] form field 너비 옵션
+ * @property {"default" | "error"} [state] visual state
  * @property {React.HTMLAttributes<HTMLElement>} [containerProps] container 속성
  * @property {React.ReactNode} children
+ * @desc Header와 Body를 렌더링하고 footer가 있으면 Footer를 추가해 field layout을 구성한다.
  */
 const FormFieldTemplate = forwardRef<HTMLElement, FormFieldTemplateProps>(
   (

package/src/components/form/markup/form-field/index.tsx

@@ -6,7 +6,7 @@ import FormFieldTemplate from "./Template";
 
 /**
  * Form; form field 컴포넌트
- * @component
+ * @namespace Form.Field
  * @desc
  * - FormField.Container: Form 필드의 컨테이너 컴포넌트
  * - FormField.Header: Form 필드의 헤더 컴포넌트

package/src/components/form/markup/index.tsx

@@ -3,6 +3,7 @@ import { FormField } from "./form-field";
 
 /**
  * Form; provider + field layout namespace
+ * @namespace Form
  * @desc
  * - `Form.Provider`: react-hook-form provider 래퍼다.
  * - `Form.Field.Container`: field 루트 wrapper다.

package/src/components/form/styles/form-field/variables.scss

@@ -2,8 +2,8 @@
   --form-field-width: auto;
   --form-field-flex: 0 0 auto;
 
-  --form-field-gap-x: var(--spacing-gap-5, 12px);
-  --form-field-gap-y: var(--spacing-gap-3, 6px);
+  --form-field-gap-x: var(--spacing-gap-5);
+  --form-field-gap-y: var(--spacing-gap-3);
 
   --form-field-label-font-size: var(--font-label-small-size);
   --form-field-label-font-weight: 400;