@conscience-technology/ctds 0.3.3 → 0.4.0

package/assets/components/Sidebar/Sidebar.module.css

@@ -73,9 +73,9 @@
      Body 안쪽 콘텐츠 래퍼(nav/섹션 리스트 등)에 깐다. */
   /* padding-top·padding-bottom도 두지 않음 — Header 아래 숨돌림, Footer 위
      마지막 항목 숨돌림 모두 소비처가 안쪽 래퍼의 padding-block으로 공급. */
-  /* mask-image 금지 — Body 안에 "고정 상단 블록(railTop 등 primary CTA + 검색)"을
-     꽂는 소비처가 많아서 fade가 걸리면 그 블록 상단이 흐려져 "밝은 입체 바"
-     착시를 만듦(특히 primary solid 버튼에서 심함). */
+  /* mask-image 기본 off. 켜고 싶으면 Sidebar.Body의 `fade` prop 사용.
+     top fade는 Body 안에 "고정 상단 블록(primary CTA + 검색)"을 꽂는 소비처에선
+     그 블록 상단이 흐려져 "밝은 입체 바" 착시를 만들므로 주의. */
 }
 
 /* Body 자식이 flex column에서 수축돼 header가 뭉개지는 걸 방지.
@@ -84,15 +84,92 @@
   flex: 0 0 auto;
 }
 
+/* fade mask opt-in — Body에 `fade="top|bottom|both"` prop을 주면 켜짐.
+   페이드 크기는 `--sidebar-body-fade-size` 토큰(기본 --space-3). 소비처가 늘릴 수 있음.
+   주의: top fade는 Body 안에 고정 상단 블록(primary CTA 등)이 없을 때만 안전.
+   있으면 그 블록 상단이 깎여 "흰 입체 바" 착시가 생김. */
+.body[data-fade] {
+  --sidebar-body-fade-size: var(--space-3);
+}
+
+/* mask-image의 #000은 색이 아니라 "완전 불투명" alpha marker — lint-hardcoded ignore. */
+.body[data-fade="top"] {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 100% /* lint-hardcoded: ignore */
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 100% /* lint-hardcoded: ignore */
+  );
+}
+
+.body[data-fade="bottom"] {
+  mask-image: linear-gradient(
+    to bottom,
+    #000 0, /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    #000 0, /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+}
+
+.body[data-fade="both"] {
+  mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+  -webkit-mask-image: linear-gradient(
+    to bottom,
+    transparent 0,
+    #000 var(--sidebar-body-fade-size), /* lint-hardcoded: ignore */
+    #000 calc(100% - var(--sidebar-body-fade-size)), /* lint-hardcoded: ignore */
+    transparent 100%
+  );
+}
+
 /* Brand preset ─────────────────────────────────────────
    Header 안에 꽂히는 preset. symbol은 항상, wordmark는 expanded일 때만 렌더.
    상한선 토큰으로 max-height 강제 — 사용처가 그 안에서 자유롭게 크기 지정.
-   좌우/상하 padding은 소비처가 공급. */
+   Header 자체 좌우/상하 padding은 소비처가 공급(래퍼 축).
+   Brand 안쪽 좌우 padding은 벤더가 공급 — MenuItem이 자체 padding-inline을
+   가지므로 Brand symbol이 아래 MenuItem 아이콘과 같은 X축에 서려면
+   Brand도 동일한 inner padding을 가져야 함(아니면 symbol이 라벨 영역과 anti-flush).
+   width: 100% + collapsed 중앙 정렬: Brand가 Header 폭을 전부 받아야 collapsed일 때
+   justify-content: center가 "Header 가로 중앙"으로 유효해짐. */
 .brand {
   display: flex;
   align-items: center;
   gap: var(--space-2);
   min-height: var(--control-h-md);
+  /* MenuItem이 자체 padding-inline(space-2)을 가지므로 Brand symbol이 아래
+     라벨들의 아이콘과 같은 X축에 서려면 Brand도 동일한 inner padding을 가져야 함.
+     Header 안에 Brand + 다른 자식이 공존하는 소비처가 있으므로 width는 건드리지
+     않고 inner padding만 공급. */
+  padding-inline: var(--space-2);
+  box-sizing: border-box;
+}
+
+/* collapsed일 땐 wordmark가 사라져 symbol 하나만 남으므로 Header 폭을 전부 받아
+   가로 중앙 정렬. 안 그러면 Brand가 symbol 폭에만 머물러 Header 좌측에 붙음.
+   inner padding도 제거 — collapsed Header는 자체적으로 좁고 symbol 1개만 있어
+   추가 안쪽 여백이 필요 없음. */
+.root[data-collapsed] .brand {
+  width: 100%;
+  justify-content: center;
+  padding-inline: 0;
 }
 
 .brandSymbol {

package/assets/components/Sidebar/Sidebar.tsx

@@ -75,8 +75,16 @@ function SidebarHeader({ children, className, ...rest }: HTMLAttributes<HTMLDivE
    Header와 Footer 사이의 세로 스크롤 영역.
    여러 개를 두면 각각 독립적인 스크롤 트랙이 됨.
    ResizeObserver로 scrollHeight > clientHeight 감지 → Footer가 자동으로
-   상단 hairline을 켬. 메뉴가 적으면 선 없음, 많으면 자연스럽게 분리선 등장. */
-function SidebarBody({ children, className, ...rest }: HTMLAttributes<HTMLDivElement>) {
+   상단 hairline을 켬. 메뉴가 적으면 선 없음, 많으면 자연스럽게 분리선 등장.
+
+   fade: 스크롤 트랙 상/하단 소프트 fade mask. "top" | "bottom" | "both" | "none".
+   기본 "none" — 켤 때만 켠다(소비처가 Body 안에 고정 상단 블록을 두면 top fade가
+   그 블록을 깎아 "흰 입체 바" 착시를 만드므로 opt-in). */
+export interface SidebarBodyProps extends HTMLAttributes<HTMLDivElement> {
+  fade?: "top" | "bottom" | "both" | "none";
+}
+
+function SidebarBody({ children, className, fade = "none", ...rest }: SidebarBodyProps) {
   const ref = useRef<HTMLDivElement>(null);
   const { setBodyOverflow } = useSidebar();
 
@@ -100,6 +108,7 @@ function SidebarBody({ children, className, ...rest }: HTMLAttributes<HTMLDivEle
     <div
       ref={ref}
       data-sidebar-slot="body"
+      data-fade={fade !== "none" ? fade : undefined}
       className={[styles.body, className ?? ""].filter(Boolean).join(" ")}
       {...rest}
     >
@@ -272,6 +281,9 @@ const SidebarItem = forwardRef<HTMLDivElement, SidebarItemProps>(function Sideba
   const leadingActions: MenuItemAction[] = icon ? [icon] : [];
   const trailingActions: MenuItemAction[] = trailing ? [trailing] : [];
 
+  /* ellipsis 시 Tooltip, collapsed 시 항상 Tooltip은 MenuItem이 자체 처리.
+     children을 넘기면 복잡 ReactNode라 Tooltip이 안 뜰 수 있으므로, 평문 라벨만 있을 땐
+     label 문자열을 그대로 children으로 흘려 MenuItem이 안전하게 Tooltip 콘텐츠를 결정하게 함. */
   return (
     <MenuItem
       ref={ref}
@@ -280,13 +292,13 @@ const SidebarItem = forwardRef<HTMLDivElement, SidebarItemProps>(function Sideba
       disabled={disabled}
       asChild={asChild}
       collapsed={collapsed}
+      truncateTooltip
       leadingActions={leadingActions}
       trailingActions={trailingActions}
       shortcut={shortcut}
       hasSubmenu={hasSubmenu}
       onClick={onClick}
       aria-label={collapsed ? label : undefined}
-      title={collapsed ? label : undefined}
     >
       {children ?? label}
     </MenuItem>

package/assets/components/SplitButton/SplitButton.module.css

@@ -94,9 +94,9 @@
 .sm .menu { padding-inline: var(--space-1_5); }
 
 .md { --split-h: var(--control-h-md); --btn-icon-size: var(--space-4); }
-.md .part { font-size: var(--text-sm); gap: var(--space-1); }
-.md .main { padding-inline: var(--space-2); }
-.md .menu { padding-inline: var(--space-1_5); }
+.md .part { font-size: var(--text-sm); gap: var(--space-1_5); }
+.md .main { padding-inline: var(--space-3); }
+.md .menu { padding-inline: var(--space-2); }
 
 .lg { --split-h: var(--control-h-lg); --btn-icon-size: var(--space-4); }
 .lg .part { font-size: var(--text-sm); gap: var(--space-1_5); }

package/assets/components/Stepper/Stepper.module.css

@@ -1,42 +1,78 @@
 /* Stepper — 다단계 진행 표시 컴포넌트
-   구성: root(container) > item(button) > marker(dot|number) + body(title + hint)
-   축 반응:
-   ─ Density → --space-scale, --font-scale (여백·라벨 크기)
-   ─ Shape   → focus ring radius (marker는 항상 full)
-   ─ Motion  → 상태 전환 duration/easing (transition-colors)
+   구성: root(container) > item(button) > marker + body(title + hint)
+
+   축 (data-* attr):
+   ─ data-orientation      : vertical | horizontal
+   ─ data-marker           : dot | number
+   ─ data-variant          : md | sm
+   ─ data-tone             : primary | neutral
+   ─ data-density          : comfortable | spacious
+   ─ data-hint-placement   : below | inline
+   ─ data-line-style       : dashed | dotted | solid
 
    로컬 색 변수 (root에서 오버라이드 가능):
-   ─ --stepper-fg         : 활성/진행중 스텝 텍스트
+   ─ --stepper-fg         : 활성 스텝 텍스트
    ─ --stepper-fg-muted   : 완료 스텝 텍스트
    ─ --stepper-fg-subtle  : 미도달 스텝 텍스트 · hint
-   ─ --stepper-line       : 스텝 사이 dashed 트리 라인
-   ─ --stepper-dot-idle   : 미도달 dot border
-   ─ --stepper-marker-fg  : done marker 안쪽 텍스트/아이콘 색 (배경 위)
+   ─ --stepper-line       : 스텝 사이 연결선 색
+   ─ --stepper-dot-idle   : 미도달 marker border
+   ─ --stepper-marker     : active/done 공통 강조색 (기본 Primary)
+   ─ --stepper-marker-fg  : done marker 안쪽 글자/아이콘 색
+   ─ --stepper-marker-soft: upcoming·neutral·active 등 soft fill 색
 */
 
 .root {
   --stepper-fg: var(--fg);
   --stepper-fg-muted: var(--fg-muted);
   --stepper-fg-subtle: var(--fg-subtle);
-  --stepper-line: var(--border);
-  --stepper-dot-idle: var(--border);
+  --stepper-line: var(--border-strong);
+  --stepper-dot-idle: var(--border-strong);
+  --stepper-marker: var(--primary);
   --stepper-marker-fg: var(--bg);
+  --stepper-marker-soft: color-mix(in oklab, var(--fg) 8%, transparent);
 
   --stepper-marker-size: var(--space-5);
   --stepper-marker-gap: var(--space-4);
   --stepper-item-gap: var(--space-6);
+  --stepper-title-lh: var(--lh-sm);  /* marker 수직 보정 기준 */
+  --stepper-line-gap: var(--space-1); /* marker ↔ 선 간격 */
 
   display: flex;
   min-width: 0;
   min-height: 0;
 }
 
-/* Orientation ─────────────────────────────────────────── */
+/* ─ Orientation ────────────────────────────────────── */
 
 .vertical { flex-direction: column; }
-.horizontal { flex-direction: row; align-items: flex-start; }
+.horizontal {
+  flex-direction: row;
+  align-items: flex-start;
+  --stepper-line-gap: var(--space-2);
+}
+
+/* ─ Variant: md (기본, 큰 marker 24px) vs sm (작은 dot 10px) ─ */
+
+.root[data-variant="md"] {
+  --stepper-marker-size: var(--space-6);  /* 24px — 01 Stripe */
+  --stepper-marker-gap: var(--space-4);
+  --stepper-item-gap: var(--space-6);
+  --stepper-title-lh: var(--lh-base);
+}
+.root[data-variant="sm"] {
+  --stepper-marker-size: var(--space-2_5); /* 10px — 02 헤이딜러 */
+  --stepper-marker-gap: var(--space-3);
+  --stepper-item-gap: var(--space-10);     /* 작은 marker는 호흡 넓게 */
+  --stepper-title-lh: var(--lh-sm);
+}
+
+/* ─ Tone: neutral이면 done·marker 색이 모노톤 ──────── */
+
+.root[data-tone="neutral"] {
+  --stepper-marker: var(--fg);
+}
 
-/* Item ─────────────────────────────────────────────────── */
+/* ─ Item ───────────────────────────────────────────── */
 
 .item {
   appearance: none;
@@ -61,7 +97,7 @@
   box-shadow: var(--ring-shadow);
 }
 
-/* Vertical item: 2-column grid, 아래로 dashed line */
+/* Vertical item: 2-column grid */
 .vertical .item {
   display: grid;
   grid-template-columns: var(--stepper-marker-size) 1fr;
@@ -70,23 +106,8 @@
   padding-bottom: var(--stepper-item-gap);
 }
 .vertical .item:last-child { padding-bottom: 0; }
-.vertical .item:not(:last-child)::before {
-  content: "";
-  position: absolute;
-  left: calc(var(--stepper-marker-size) / 2 - var(--hairline) / 2);
-  top: var(--stepper-marker-size);
-  bottom: 0;
-  width: var(--hairline);
-  background-image: linear-gradient(
-    to bottom,
-    var(--stepper-line) 50%,
-    transparent 50%
-  );
-  background-size: var(--hairline) var(--space-1_5);
-  background-repeat: repeat-y;
-}
 
-/* Horizontal item: marker 위, body 아래로 쌓임, 옆으로 dashed line */
+/* Horizontal item: marker 위, body 아래 */
 .horizontal .item {
   display: grid;
   grid-template-rows: var(--stepper-marker-size) 1fr;
@@ -100,24 +121,61 @@
   flex: 0 0 auto;
   padding-right: 0;
 }
+
+/* ─ Connecting line (vertical: 기본 dashed) ─ */
+
+.vertical .item:not(:last-child)::before {
+  content: "";
+  position: absolute;
+  left: calc(var(--stepper-marker-size) / 2 - var(--hairline) / 2);
+  /* marker가 margin-top만큼 아래로 밀렸고, 선은 marker 바닥에서
+     --stepper-line-gap 만큼 떨어진 지점부터 시작, 아래쪽도 같은 간격 띄움 */
+  top: calc(
+    (var(--stepper-title-lh) - var(--stepper-marker-size)) / 2 +
+      var(--stepper-marker-size) + var(--stepper-line-gap)
+  );
+  bottom: var(--stepper-line-gap);
+  width: var(--hairline);
+  background-image: linear-gradient(
+    to bottom,
+    var(--stepper-line) 65%,
+    transparent 35%
+  );
+  background-size: var(--hairline) var(--space-1_5);
+  background-repeat: repeat-y;
+}
+
 .horizontal .item:not(:last-child)::before {
   content: "";
   position: absolute;
   top: calc(var(--stepper-marker-size) / 2 - var(--hairline) / 2);
-  left: var(--stepper-marker-size);
-  right: 0;
+  left: calc(var(--stepper-marker-size) + var(--stepper-line-gap));
+  right: var(--stepper-line-gap);
   height: var(--hairline);
   background-image: linear-gradient(
     to right,
-    var(--stepper-line) 50%,
-    transparent 50%
+    var(--stepper-line) 65%,
+    transparent 35%
   );
   background-size: var(--space-1_5) var(--hairline);
   background-repeat: repeat-x;
-  margin-inline: var(--space-2);
 }
 
-/* Marker ───────────────────────────────────────────────── */
+/* line-style: solid (01 — 매끈한 1px) — selector 주의:
+   .vertical/.horizontal과 data-line-style attr가 같은 root element에 붙어 있으므로
+   descendant가 아닌 compound selector로 작성. */
+.vertical[data-line-style="solid"] .item:not(:last-child)::before {
+  background: var(--stepper-line);
+  background-image: none;
+  background-size: auto;
+}
+.horizontal[data-line-style="solid"] .item:not(:last-child)::before {
+  background: var(--stepper-line);
+  background-image: none;
+  background-size: auto;
+}
+
+/* ─ Marker ────────────────────────────────────────── */
 
 .marker {
   width: var(--stepper-marker-size);
@@ -131,34 +189,98 @@
   flex-shrink: 0;
   transition: var(--transition-colors);
   font-size: var(--text-xs);
-  font-weight: var(--font-weight-semibold);
+  font-weight: var(--font-weight-medium);
   line-height: 1;
-  color: inherit;
+  color: var(--stepper-fg-subtle);
+  font-variant-numeric: tabular-nums;
+  position: relative;
+  /* vertical일 때 marker가 title 첫 줄 중앙선에 맞도록 아래로 밀기.
+     --stepper-title-lh는 variant별로 공급되는 title line-height. */
+  margin-top: calc(
+    (var(--stepper-title-lh) - var(--stepper-marker-size)) / 2
+  );
+}
+/* horizontal에서는 marker가 body 위에 위치하므로 보정 off */
+.horizontal .marker {
+  margin-top: 0;
+}
+
+/* ── variant=md (기본) marker scaling ──
+   24px marker 안의 숫자/check도 균형 잡힌 사이즈. */
+.root[data-variant="md"] .marker {
+  font-size: var(--text-xs);
+}
+
+/* ── variant=sm marker는 solid dot (border 없음, soft fill) ── */
+.root[data-variant="sm"] .marker {
+  border: none;
+  background: var(--stepper-dot-idle);
+}
+
+/* ── Upcoming (md variant): soft bg + muted 숫자 (01 Stripe) ── */
+.root[data-variant="md"] .item[data-state="upcoming"] .marker {
+  background: var(--stepper-marker-soft);
+  border-color: transparent;
+}
+
+/* ── Done marker ── */
+/* md + primary tone (기본): Primary fill */
+.item[data-state="done"] .marker {
+  border-color: transparent;
+  background: var(--stepper-marker);
+  color: var(--stepper-marker-fg);
+}
+/* md + neutral tone (01 Stripe): soft gray fill + muted check */
+.root[data-tone="neutral"] .item[data-state="done"] .marker {
+  background: var(--stepper-marker-soft);
+  color: var(--stepper-fg-muted);
+}
+/* sm variant done: 색만 marker 색, dot 크기 그대로 */
+.root[data-variant="sm"] .item[data-state="done"] .marker {
+  background: var(--stepper-dot-idle);
+  color: transparent;
+}
+.root[data-variant="sm"][data-tone="primary"]
+  .item[data-state="done"]
+  .marker {
+  background: var(--stepper-marker);
 }
 
-/* Active marker: 굵은 링 */
+/* ── Active marker ──
+   marker 자체가 큰 soft Primary 동그라미 + 중앙에 작은 Primary dot. */
 .item[data-state="active"] .marker {
-  border-color: var(--stepper-fg);
-  border-width: calc(var(--hairline) * 2);
-  color: var(--stepper-fg);
+  background: color-mix(in oklab, var(--stepper-marker) 18%, transparent);
+  border-color: transparent;
+  color: var(--stepper-marker);
+}
+/* sm variant active: marker 자체는 solid Primary dot + 바깥에 soft Primary halo.
+   작은 dot(10px)이라 안쪽 split 대신 외곽 halo로 "지금 여기" 신호를 줌. */
+.root[data-variant="sm"] .item[data-state="active"] .marker {
+  background: var(--stepper-marker);
+  color: var(--stepper-marker-fg);
+  box-shadow: 0 0 0 var(--space-1)
+    color-mix(in oklab, var(--stepper-marker) 22%, transparent);
 }
 
-/* dot marker의 active: 안쪽 작은 점 */
+/* ─ markerInnerDot: active marker 중앙 작은 Primary dot ─ */
 .markerInnerDot {
   width: var(--space-1_5);
   height: var(--space-1_5);
   border-radius: var(--radius-full);
-  background: var(--stepper-fg);
+  background: var(--stepper-marker);
+  flex-shrink: 0;
 }
-
-/* Done marker: 배경 채움, 안에 check (dot) 또는 숫자 유지 (number) */
-.item[data-state="done"] .marker {
-  border-color: transparent;
-  background: var(--stepper-fg);
-  color: var(--stepper-marker-fg);
+/* md (24px marker)에서는 inner dot도 조금 더 크게 */
+.root[data-variant="md"] .markerInnerDot {
+  width: var(--space-2);
+  height: var(--space-2);
+}
+/* sm variant는 marker 자체가 10px dot이라 inner dot 숨김 */
+.root[data-variant="sm"] .markerInnerDot {
+  display: none;
 }
 
-/* Body ─────────────────────────────────────────────────── */
+/* ─ Body ─────────────────────────────────────────── */
 
 .body {
   display: flex;
@@ -168,15 +290,37 @@
   padding-right: var(--space-2);
 }
 
+/* hintPlacement=inline (02): title | hint 가로 배치 */
+.root[data-hint-placement="inline"] .body {
+  flex-direction: row;
+  align-items: baseline;
+  gap: var(--space-2);
+  flex-wrap: wrap;
+}
+
 .title {
   font-size: var(--text-sm);
+  font-weight: var(--font-weight-medium);
+  line-height: var(--lh-sm);
+}
+/* md variant는 title 조금 더 큼 (01 Stripe 톤) */
+.root[data-variant="md"] .title {
+  font-size: var(--text-base);
+  line-height: var(--lh-base);
+}
+.item[data-state="active"] .title {
   font-weight: var(--font-weight-semibold);
 }
+
 .hint {
   font-size: var(--text-xs);
   color: var(--stepper-fg-subtle);
   line-height: var(--lh-xs);
 }
+.root[data-variant="md"] .hint {
+  font-size: var(--text-sm);
+  line-height: var(--lh-sm);
+}
 .item[data-state="active"] .hint {
   color: var(--stepper-fg-muted);
 }

package/assets/components/Stepper/Stepper.tsx

@@ -18,15 +18,23 @@ import styles from "./Stepper.module.css";
 
 type Orientation = "vertical" | "horizontal";
 type Marker = "dot" | "number";
+type Variant = "md" | "sm";
+type Tone = "primary" | "neutral";
+type HintPlacement = "below" | "inline";
+type LineStyle = "dashed" | "solid";
 type ItemState = "upcoming" | "active" | "done";
 
 type StepperContextValue = {
   orientation: Orientation;
   marker: Marker;
+  variant: Variant;
+  tone: Tone;
+  hintPlacement: HintPlacement;
   activeIndex: number;
   onStepClick?: (index: number) => void;
 };
 
+
 const StepperContext = createContext<StepperContextValue | null>(null);
 
 function useStepperContext(): StepperContextValue {
@@ -46,6 +54,22 @@ export type StepperProps = Omit<HTMLAttributes<HTMLDivElement>, "onSelect"> & {
   orientation?: Orientation;
   /** marker 종류. dot(기본) | number. */
   marker?: Marker;
+  /**
+   * marker 사이즈.
+   * - `md` : 24px 동그라미 marker (기본, 01 Stripe 류)
+   * - `sm` : 10px 작은 solid dot (02 헤이딜러 류, title 중심)
+   */
+  variant?: Variant;
+  /**
+   * 색 톤.
+   * - `primary` : done/active 모두 Primary (기본)
+   * - `neutral` : done은 모노톤, active만 Primary 혹은 fg-strong
+   */
+  tone?: Tone;
+  /** hint 배치. below(기본) | inline(title 옆). */
+  hintPlacement?: HintPlacement;
+  /** 스텝 사이 연결선 스타일. dashed(기본) | solid. */
+  lineStyle?: LineStyle;
   /** 스텝 클릭 시. 자식 Item에 onClick이 있으면 그쪽이 우선. */
   onStepClick?: (index: number) => void;
   children: ReactNode;
@@ -57,6 +81,10 @@ const StepperRoot = forwardRef<HTMLDivElement, StepperProps>(
       activeIndex,
       orientation = "vertical",
       marker = "dot",
+      variant = "md",
+      tone = "primary",
+      hintPlacement = "below",
+      lineStyle = "dashed",
       onStepClick,
       className,
       children,
@@ -65,11 +93,26 @@ const StepperRoot = forwardRef<HTMLDivElement, StepperProps>(
     ref,
   ) => {
     const ctxValue = useMemo<StepperContextValue>(
-      () => ({ orientation, marker, activeIndex, onStepClick }),
-      [orientation, marker, activeIndex, onStepClick],
+      () => ({
+        orientation,
+        marker,
+        variant,
+        tone,
+        hintPlacement,
+        activeIndex,
+        onStepClick,
+      }),
+      [
+        orientation,
+        marker,
+        variant,
+        tone,
+        hintPlacement,
+        activeIndex,
+        onStepClick,
+      ],
     );
 
-    // 자식 Item에 index를 자동 주입
     const items = Children.toArray(children).filter(isValidElement);
     const injected = items.map((child, i) =>
       cloneElement(child as ReactElement<StepperItemProps>, {
@@ -91,6 +134,10 @@ const StepperRoot = forwardRef<HTMLDivElement, StepperProps>(
             .join(" ")}
           data-orientation={orientation}
           data-marker={marker}
+          data-variant={variant}
+          data-tone={tone}
+          data-hint-placement={hintPlacement}
+          data-line-style={lineStyle}
           {...rest}
         >
           {injected}
@@ -107,11 +154,9 @@ export type StepperItemProps = Omit<
   ButtonHTMLAttributes<HTMLButtonElement>,
   "title"
 > & {
-  /** Stepper가 자동 주입. 수동 override 가능. */
   index?: number;
   title: ReactNode;
   hint?: ReactNode;
-  /** 명시적 상태 지정. 미지정이면 activeIndex 기준으로 자동 결정. */
   state?: ItemState;
 };
 
@@ -130,7 +175,7 @@ const StepperItem = forwardRef<HTMLButtonElement, StepperItemProps>(
     },
     ref,
   ) => {
-    const { orientation, marker, activeIndex, onStepClick } =
+    const { orientation, marker, variant, activeIndex, onStepClick } =
       useStepperContext();
 
     const idx = index ?? 0;
@@ -138,6 +183,22 @@ const StepperItem = forwardRef<HTMLButtonElement, StepperItemProps>(
       stateProp ??
       (idx === activeIndex ? "active" : idx < activeIndex ? "done" : "upcoming");
 
+    // marker 내부 렌더링 규칙:
+    // ─ sm variant   : 내부 글자/dot 없음 (marker 자체가 작은 solid dot)
+    // ─ done         : check 아이콘
+    // ─ number marker: 숫자 (active여도 숫자 유지)
+    // ─ dot + active : 작은 Primary dot
+    const markerContent =
+      variant === "sm"
+        ? null
+        : state === "done"
+          ? <Icon name="check" size={10} />
+          : marker === "number"
+            ? idx + 1
+            : state === "active"
+              ? <span className={styles.markerInnerDot} />
+              : null;
+
     return (
       <button
         ref={ref}
@@ -155,13 +216,7 @@ const StepperItem = forwardRef<HTMLButtonElement, StepperItemProps>(
         {...rest}
       >
         <span className={styles.marker} aria-hidden>
-          {state === "done" ? (
-            <Icon name="check" size={12} />
-          ) : marker === "number" ? (
-            idx + 1
-          ) : state === "active" ? (
-            <span className={styles.markerInnerDot} />
-          ) : null}
+          {markerContent}
         </span>
         <span className={styles.body}>
           <span className={styles.title}>{title}</span>