@x-plat/design-system 0.5.45 → 0.5.47

package/dist/components/Swiper/index.cjs

@@ -66,6 +66,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -93,6 +94,8 @@ var Swiper = (props) => {
   const startXRef = import_react.default.useRef(0);
   const startTimeRef = import_react.default.useRef(0);
   const autoplayTimerRef = import_react.default.useRef(null);
+  const resumeTimeoutRef = import_react.default.useRef(null);
+  const [paused, setPaused] = import_react.default.useState(false);
   import_react.default.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -192,15 +195,36 @@ var Swiper = (props) => {
     slideTo
   }));
   import_react.default.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  import_react.default.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -208,7 +232,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -238,6 +262,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/dist/components/Swiper/index.d.cts

@@ -25,6 +25,8 @@ interface SwiperProps {
     showProgress?: boolean;
     /** 오토플레이 딜레이 (ms) */
     autoplayDelay?: number;
+    /** 사용자 인터랙션(드래그/탭) 후 autoplay 가 재개되기까지 대기 시간 (ms). 0 이면 즉시 재개. 기본 0 */
+    pauseOnInteraction?: number;
     /** 슬라이드 전환 속도 (ms) */
     speed?: number;
     /** 한 번에 이동할 슬라이드 수 (기본: 1) */

package/dist/components/Swiper/index.d.ts

@@ -25,6 +25,8 @@ interface SwiperProps {
     showProgress?: boolean;
     /** 오토플레이 딜레이 (ms) */
     autoplayDelay?: number;
+    /** 사용자 인터랙션(드래그/탭) 후 autoplay 가 재개되기까지 대기 시간 (ms). 0 이면 즉시 재개. 기본 0 */
+    pauseOnInteraction?: number;
     /** 슬라이드 전환 속도 (ms) */
     speed?: number;
     /** 한 번에 이동할 슬라이드 수 (기본: 1) */

package/dist/components/Swiper/index.js

@@ -30,6 +30,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -57,6 +58,8 @@ var Swiper = (props) => {
   const startXRef = React.useRef(0);
   const startTimeRef = React.useRef(0);
   const autoplayTimerRef = React.useRef(null);
+  const resumeTimeoutRef = React.useRef(null);
+  const [paused, setPaused] = React.useState(false);
   React.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -156,15 +159,36 @@ var Swiper = (props) => {
     slideTo
   }));
   React.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  React.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -172,7 +196,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -202,6 +226,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/dist/components/index.cjs

@@ -4712,6 +4712,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -4739,6 +4740,8 @@ var Swiper = (props) => {
   const startXRef = import_react31.default.useRef(0);
   const startTimeRef = import_react31.default.useRef(0);
   const autoplayTimerRef = import_react31.default.useRef(null);
+  const resumeTimeoutRef = import_react31.default.useRef(null);
+  const [paused, setPaused] = import_react31.default.useState(false);
   import_react31.default.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -4838,15 +4841,36 @@ var Swiper = (props) => {
     slideTo
   }));
   import_react31.default.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  import_react31.default.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -4854,7 +4878,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -4884,6 +4908,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/dist/components/index.js

@@ -4622,6 +4622,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -4649,6 +4650,8 @@ var Swiper = (props) => {
   const startXRef = React30.useRef(0);
   const startTimeRef = React30.useRef(0);
   const autoplayTimerRef = React30.useRef(null);
+  const resumeTimeoutRef = React30.useRef(null);
+  const [paused, setPaused] = React30.useState(false);
   React30.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -4748,15 +4751,36 @@ var Swiper = (props) => {
     slideTo
   }));
   React30.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  React30.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -4764,7 +4788,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -4794,6 +4818,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/dist/index.cjs

@@ -9124,6 +9124,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -9151,6 +9152,8 @@ var Swiper = (props) => {
   const startXRef = import_react31.default.useRef(0);
   const startTimeRef = import_react31.default.useRef(0);
   const autoplayTimerRef = import_react31.default.useRef(null);
+  const resumeTimeoutRef = import_react31.default.useRef(null);
+  const [paused, setPaused] = import_react31.default.useState(false);
   import_react31.default.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -9250,15 +9253,36 @@ var Swiper = (props) => {
     slideTo
   }));
   import_react31.default.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  import_react31.default.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -9266,7 +9290,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -9296,6 +9320,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/dist/index.js

@@ -8725,6 +8725,7 @@ var Swiper = (props) => {
     spaceBetween = 16,
     showProgress = false,
     autoplayDelay = 3e3,
+    pauseOnInteraction = 0,
     speed = 300,
     slideBy = 1,
     index: indexProp,
@@ -8752,6 +8753,8 @@ var Swiper = (props) => {
   const startXRef = React30.useRef(0);
   const startTimeRef = React30.useRef(0);
   const autoplayTimerRef = React30.useRef(null);
+  const resumeTimeoutRef = React30.useRef(null);
+  const [paused, setPaused] = React30.useState(false);
   React30.useEffect(() => {
     const el = containerRef.current;
     if (!el) return;
@@ -8851,15 +8854,36 @@ var Swiper = (props) => {
     slideTo
   }));
   React30.useEffect(() => {
-    if (!auto || !canSlide) return;
+    if (!auto || !canSlide || paused) return;
     autoplayTimerRef.current = setInterval(slideNext, autoplayDelay);
     return () => {
       if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
     };
-  }, [auto, autoplayDelay, slideNext, canSlide]);
-  const pauseAutoplay = () => {
-    if (autoplayTimerRef.current) clearInterval(autoplayTimerRef.current);
+  }, [auto, autoplayDelay, slideNext, canSlide, paused]);
+  const pauseForInteraction = () => {
+    setPaused(true);
+    if (resumeTimeoutRef.current) {
+      clearTimeout(resumeTimeoutRef.current);
+      resumeTimeoutRef.current = null;
+    }
+  };
+  const scheduleAutoplayResume = () => {
+    if (!auto) return;
+    if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    if (pauseOnInteraction <= 0) {
+      setPaused(false);
+      return;
+    }
+    resumeTimeoutRef.current = setTimeout(() => {
+      setPaused(false);
+      resumeTimeoutRef.current = null;
+    }, pauseOnInteraction);
   };
+  React30.useEffect(() => {
+    return () => {
+      if (resumeTimeoutRef.current) clearTimeout(resumeTimeoutRef.current);
+    };
+  }, []);
   const getClientX = (e) => {
     if ("touches" in e) return e.touches[0]?.clientX ?? 0;
     return e.clientX;
@@ -8867,7 +8891,7 @@ var Swiper = (props) => {
   const handleDragStart = (e) => {
     if (!canSlide) return;
     if ("button" in e && e.button !== 0) return;
-    pauseAutoplay();
+    pauseForInteraction();
     setIsDragging(true);
     setAnimated(false);
     startXRef.current = getClientX(e);
@@ -8897,6 +8921,7 @@ var Swiper = (props) => {
         setAnimated(true);
       }
       setDragOffset(0);
+      scheduleAutoplayResume();
     };
     window.addEventListener("mousemove", handleMove);
     window.addEventListener("mouseup", handleEnd);

package/guidelines/AGENT_PROMPT.md

@@ -21,6 +21,7 @@
 2. 컴포넌트는 `width: 100%` 로 부모를 채우므로 **반드시 GridItem 또는 wrapper 로 감싸서 너비를 제어**.
 3. **CSS 로 DS 컴포넌트를 오버라이드하지 않는다**.
 4. 색상·간격·타이포는 **semantic 토큰만** 사용. primitive / brand 직접 참조 금지.
+5. **모든 visible 그룹은 명시적 spacing 필수**. wrapper 의 `padding` / `gap` / 간격을 spacing 토큰으로 지정. 매직 넘버(`16px`, `1rem` 등) 금지.
 
 ---
 
@@ -158,6 +159,270 @@ import { FullGrid, FullScreen, GapGrid, GridItem } from "@x-plat/design-system/l
 
 ---
 
+## 공간(Spacing) 처리 — **누락 금지**
+
+DS 컴포넌트는 자체적으로 spacing 을 가지지 않는다(`width: 100%` 만). **wrapper 가 모든 spacing 을 책임진다.** 누락하면 콘텐츠가 붙어버린다.
+
+### 어디에 적용하는가
+
+| 상황 | 처리 |
+|---|---|
+| 컴포넌트들 사이 세로 간격 | wrapper 에 `display: flex; flex-direction: column; gap: var(--spacing-space-N);` |
+| 컴포넌트들 사이 가로 간격 | wrapper 에 `display: flex; gap: var(--spacing-space-N);` 또는 `FullGrid gap` |
+| 컨테이너 내부 padding | wrapper 에 `padding: var(--spacing-space-N);` |
+| 카드/모달 등 박스 내부 | `padding: var(--spacing-space-4);` 가 일반적 |
+| 섹션과 섹션 사이 | `margin-top: var(--spacing-space-6);` 또는 부모 gap |
+
+### 사용 가능한 spacing 토큰 (semantic 만)
+
+```
+--spacing-space-{none|1|2|3|4|5|6|7|8|9|10|11|12|13|14|15|16}
+--spacing-radius-{none|sm|md|lg|xl|full}
+--spacing-stroke-{none|xs|sm|md|lg|xl|2xl}
+--spacing-control-height-{xs|sm|md|lg}
+```
+
+space-1 = 4px, space-2 = 8px, space-3 = 12px, space-4 = 16px, space-5 = 20px, space-6 = 24px, ...
+
+### 자주 누락되는 케이스 — 반드시 적용
+
+DS 컴포넌트는 자체 외부 margin 없음. 부모가 gap 안 주면 모두 붙어버린다. 아래 케이스에서 절대 빼먹지 말 것.
+
+#### 1. 섹션 내 카드 목록 (자주 누락 #1)
+
+```tsx
+// ❌ 카드들이 다닥다닥 붙어버림
+<section>
+  <Card>...</Card>
+  <Card>...</Card>
+  <Card>...</Card>
+</section>
+
+// ✅ 부모에 gap 필수
+<section style={{
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--spacing-space-4)",   // 카드 간 16px
+}}>
+  <Card>...</Card>
+  <Card>...</Card>
+  <Card>...</Card>
+</section>
+
+// ✅ 카드 그리드형 — FullGrid 사용 시 gap prop
+<FullGrid gap={16}>
+  <GridItem column={{ default: 4 }}><Card>...</Card></GridItem>
+  <GridItem column={{ default: 4 }}><Card>...</Card></GridItem>
+  <GridItem column={{ default: 4 }}><Card>...</Card></GridItem>
+</FullGrid>
+```
+
+#### 2. 폼 요소 사이 간격 (자주 누락 #2)
+
+```tsx
+// ❌ Input 들이 붙고 라벨/도움말도 빽빽
+<form>
+  <Input label="이름" />
+  <Input label="이메일" />
+  <Select options={...} />
+  <Button type="primary">제출</Button>
+</form>
+
+// ✅ form 전체 세로 gap + 버튼 가로 정렬
+<form style={{
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--spacing-space-4)",   // 폼 필드 간 16px
+}}>
+  <Input label="이름" />
+  <Input label="이메일" />
+  <Select options={...} />
+  <div style={{
+    display: "flex",
+    gap: "var(--spacing-space-2)",          // 버튼 간 8px
+    justifyContent: "flex-end",
+    marginTop: "var(--spacing-space-2)",    // 폼 필드와 추가 8px (선택)
+  }}>
+    <Button type="default">취소</Button>
+    <Button type="primary">제출</Button>
+  </div>
+</form>
+```
+
+#### 3. 페이지 섹션 사이 간격
+
+```tsx
+// ❌ 섹션들이 붙어버림
+<main>
+  <section><h2>섹션 A</h2>...</section>
+  <section><h2>섹션 B</h2>...</section>
+</main>
+
+// ✅ 페이지 padding + 섹션 간 gap
+<main style={{
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--spacing-space-8)",   // 섹션 간 32px
+  padding: "var(--spacing-space-6)", // 페이지 padding 24px
+}}>
+  <section>...</section>
+  <section>...</section>
+</main>
+```
+
+#### 4. 카드 내부 콘텐츠
+
+```tsx
+// Card 컴포넌트 children 직접 배치 시
+<Card>
+  <div style={{
+    padding: "var(--spacing-space-4)",          // 카드 내부 padding 16px
+    display: "flex",
+    flexDirection: "column",
+    gap: "var(--spacing-space-3)",               // 콘텐츠 간 12px
+  }}>
+    <h3>제목</h3>
+    <p>본문</p>
+    <Button type="primary">액션</Button>
+  </div>
+</Card>
+```
+
+#### 5. 가로 액션 버튼 그룹
+
+```tsx
+<div style={{
+  display: "flex",
+  gap: "var(--spacing-space-2)",   // 버튼 간 8px
+}}>
+  <Button type="default">취소</Button>
+  <Button type="primary">저장</Button>
+</div>
+```
+
+### 폼 요소 구조 — 중첩 금지
+
+**Input / TextArea / Select 안에 다른 컴포넌트를 넣지 않는다.** 레이아웃이 깨진다. 폼 요소는 항상 **형제(sibling)** 로 배치한다.
+
+#### ❌ 금지 — 폼 요소 중첩
+
+```tsx
+// Input 안에 Button → 잘못
+<Input>
+  <Button>검색</Button>
+</Input>
+
+// TextArea 안에 Button → 잘못
+<TextArea>
+  <Button>전송</Button>
+</TextArea>
+
+// Select 안에 Input → 잘못
+<Select>
+  <Input placeholder="검색" />
+</Select>
+
+// form 안에 form → 절대 금지
+<form>
+  <form>...</form>
+</form>
+```
+
+#### ✅ 올바른 패턴
+
+**Pattern 1: "입력 + 전송 버튼" 합성** → `ChatInput` 컴포넌트 사용
+```tsx
+import { ChatInput } from "@x-plat/design-system/components";
+
+<ChatInput
+  placeholder="메시지 입력"
+  onSubmit={(value) => handleSend(value)}
+/>
+```
+
+**Pattern 2: Input 우측 아이콘/소형 액션** → Input 의 `suffix` 슬롯 사용
+```tsx
+<Input
+  placeholder="검색"
+  suffix={<Icon name="search" />}
+/>
+```
+> `suffix` 는 작은 아이콘/버튼 1개용. 일반 `<Button>` 컴포넌트 넣지 말 것 (사이즈 충돌).
+
+**Pattern 3: 폼 요소 + 액션 버튼** → 형제 배치, wrapper 에서 gap
+```tsx
+<div style={{ display: "flex", gap: "var(--spacing-space-2)" }}>
+  <Input placeholder="이메일" />
+  <Button type="primary">확인</Button>
+</div>
+```
+
+**Pattern 4: 폼 요소들 묶음** → 모두 형제, 부모에서 gap
+```tsx
+<form style={{
+  display: "flex",
+  flexDirection: "column",
+  gap: "var(--spacing-space-4)",
+}}>
+  <Input label="이름" />
+  <TextArea label="자기소개" />
+  <Select label="국가" options={...} />
+  <Button type="primary">제출</Button>
+</form>
+```
+
+#### 폼 요소별 children/슬롯 정책
+
+| 컴포넌트 | children 받음? | 슬롯 |
+|---|---|---|
+| `Input` | ❌ | `suffix` (아이콘 1개) |
+| `TextArea` | ❌ | 없음 |
+| `Select` | ❌ | `options` prop 사용 (children 아님) |
+| `CheckBox` / `Radio` / `Switch` | ❌ | `label` prop |
+| `DatePicker` / `Calendar` | ❌ | controlled value/onChange |
+| `Button` | ✅ | 텍스트/아이콘만 |
+| `ChatInput` | ❌ | 입력+버튼 합성 컴포넌트 |
+
+> "입력 안에 무언가를 넣고 싶다" 는 욕구가 들면 → **다른 형태의 합성 컴포넌트가 있는지 먼저 확인**. 없으면 **wrapper + 형제** 패턴 사용.
+
+### 케이스별 권장 spacing 값
+
+| 케이스 | 권장 값 |
+|---|---|
+| 폼 필드 간 (vertical) | `space-4` (16px) |
+| 카드 목록 간 (vertical) | `space-3 ~ space-4` (12-16px) |
+| 그리드형 카드 (gap) | `space-4` (16px) |
+| 액션 버튼 간 (horizontal) | `space-2` (8px) |
+| 섹션 간 | `space-6 ~ space-8` (24-32px) |
+| 카드/박스 내부 padding | `space-4 ~ space-5` (16-20px) |
+| 라벨 - 입력 (Input 내부 자동 처리됨) | DS 컴포넌트가 처리 |
+| 페이지 padding | `space-6` (24px) |
+
+### ❌ 금지 패턴
+
+```tsx
+// 매직 넘버 (토큰 안 씀)
+<div style={{ padding: 16, gap: 8 }}>...</div>
+
+// 컴포넌트 사이 spacing 없음 (요소들이 붙어버림)
+<div>
+  <Button>A</Button>
+  <Button>B</Button>
+</div>
+
+// primitive 직접 참조 (semantic 만 허용)
+<div style={{ padding: "var(--spacing-size-4)" }}>...</div>
+```
+
+### 체크리스트 (코드 작성 후 확인)
+
+- [ ] 모든 wrapper `<div>` 에 명시적 `gap` 또는 `padding` 이 있는가
+- [ ] spacing 값이 모두 `var(--spacing-space-*)` 등 토큰인가 (숫자 리터럴 금지)
+- [ ] 카드/박스 컴포넌트 내부에 적절한 padding 이 있는가
+- [ ] 섹션 사이에 가시적인 간격이 있는가
+
+---
+
 ## 컴포넌트 사용 패턴
 
 ### ✅ 올바른 사용

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.5.45",
+  "version": "0.5.47",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",