@opsnow-mcp/opsnow-mcp-common-ui-server 1.0.32 → 1.0.34

package/build/components/examples/opsnow-common-forms-examples-data.js

@@ -1607,6 +1607,57 @@ const handleDownload = useCallback(() => {
         description: '팝업에서 텍스트 콘텐츠를 표시하고 RTF 파일로 다운로드하는 예제입니다. downloadInsightAsRtf 유틸리티를 사용하면 어떤 텍스트든 RTF 문서로 내보낼 수 있습니다. [검색 키워드: RTF 다운로드, 콘텐츠 내보내기, 문서 저장, 텍스트 내보내기, 리포트 다운로드]'
     }
 ];
+export const CurrencySwitcherExamples = [
+    {
+        title: 'basic-currency-switcher',
+        code: `const { OpsnowCommonCurrencySwitcher } = useCommonComponents()
+
+const [currency, setCurrency] = useState('USD')
+const [appliedRate, setAppliedRate] = useState(1)
+
+// BE 환율 API 응답을 그대로 주입 (컴포넌트는 API를 호출하지 않음)
+const rateInfo = {
+  baseDate: '2026-07-08',            // 적용 환율 기준일
+  source: '한국수출입은행',            // 출처 (선택)
+  rates: { USD: 1, KRW: 1450, JPY: 156.58, VND: 25508, AED: 3.67 }, // 기준 통화(USD) 1단위당 환율
+}
+
+// 환율 상세 보기 차트용 월별(또는 일별) 추이 — 과거 → 현재 순, 마지막 값 = 현재 환율
+const history = [
+  { label: '25.07', rate: 1495.3 },
+  { label: '26.06', rate: 1462.1 },
+  { label: '26.07', rate: 1450 },
+]
+
+<OpsnowCommonCurrencySwitcher
+  value={currency}
+  onChange={(code, rate) => {
+    setCurrency(code)
+    setAppliedRate(rate) // 금액 표시 변환은 소비 측에서 rate로 처리
+  }}
+  rateInfo={rateInfo}
+  history={history}
+/>`,
+        description: '통화 전환 드롭다운 + 환율 팝오버 기본 예제입니다. 환율 데이터는 컴포넌트가 조회하지 않으므로 BE 환율 API 응답을 rateInfo/history props로 주입합니다. [검색 키워드: 통화 전환, 환율, 환율 필터, 통화 필터, 통화 변환, currency, exchange rate]'
+    },
+    {
+        title: 'custom-options-no-detail',
+        code: `<OpsnowCommonCurrencySwitcher
+  value={currency}
+  onChange={handleCurrencyChange}
+  rateInfo={rateInfo}
+  currencyOptions={[
+    { code: 'USD', symbol: '$' },
+    { code: 'KRW', symbol: '₩', digits: 0 },
+    { code: 'JPY', symbol: '¥' },
+  ]}
+  baseCurrency="USD"
+  size="small"
+  showDetail={false}
+/>`,
+        description: '팝오버 통화 목록을 커스텀하고 환율 상세 보기 드릴다운 없이 small 크기 트리거로 사용하는 예제입니다.'
+    }
+];
 export const ToggleButtonExamples = [
     {
         title: 'large-toggle-group',

package/build/components/examples/opsnow-common-layout-examples-data.js

@@ -2,18 +2,19 @@
 export const GridLayoutExamples = [
     {
         title: '4열 그리드 레이아웃',
-        description: 'Wrap="nowrap"와 고정 패딩·간격을 적용한 4열 레이아웃 예제입니다.',
+        description: 'Wrap="nowrap"와 간격 토큰(pagePadding·sectionGap·cardPadding·cardGap)을 적용한 4열 레이아웃 예제입니다. 색상 토큰처럼 theme.commonSpacing 을 참조하며 px 하드코딩하지 않습니다.',
         code: `
-<Grid container wrap="nowrap" spacing={0} sx={{ padding: '27px', gap: '27px' }}>
+<Grid container wrap="nowrap" spacing={0} sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}>
   <Grid item xs={12} sm={6} md={3} key={0}>
-    <Box sx={{
+    <Box sx={theme => ({
       border: '1px solid #ddd',
       borderRadius: '12px',
-      padding: 2,
+      padding: theme.commonSpacing.cardPadding,
+      gap: theme.commonSpacing.cardGap,
       display: 'flex',
       flexDirection: 'column',
       boxShadow: '2px 2px 8px 0 #4254663D',
-    }}>
+    })}>
     </Box>
   </Grid>
   <!-- 총 4개 아이템 반복 -->
@@ -25,7 +26,7 @@ export const GridLayoutExamples = [
         title: '2열 그리드 레이아웃',
         description: '2개의 박스를 한 줄에 배치하는 예제입니다.',
         code: `
-<Grid container wrap="nowrap" spacing={0} sx={{ padding: '27px', gap: '27px' }}>
+<Grid container wrap="nowrap" spacing={0} sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}>
   <Grid item xs={12} md={6} key={0}>
     <Box sx={{ /* 동일한 스타일 */ }}>
     </Box>
@@ -41,7 +42,7 @@ export const GridLayoutExamples = [
         title: '3열 그리드 레이아웃',
         description: '3개의 박스를 한 줄에 배치하는 예제입니다.',
         code: `
-<Grid container wrap="nowrap" spacing={0} sx={{ padding: '27px', gap: '27px' }}>
+<Grid container wrap="nowrap" spacing={0} sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}>
   <Grid item xs={12} md={4} key={0}>
     <Box sx={{ /* 동일한 스타일 */ }}>
     </Box>

package/build/components/examples/opsnow-common-select-examples-data.js

@@ -61,19 +61,19 @@ export const SelectExamples = [
         description: 'outlined variant, small 사이즈, label과 placeholder를 함께 사용하는 다중 선택 셀렉트 예제입니다.'
     },
     {
-        title: '필터 여러 개 배치 (간격 규칙: 필터 행 gap 24px, 라벨-필터 gap 8px)',
-        code: `<Stack sx={{ flexDirection: 'row', gap: '24px' }}>
+        title: '필터 여러 개 배치 (간격 규칙: 필터 행 filterGap(24px), 라벨-필터 filterLabelGap(8px))',
+        code: `<Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
   <OpsnowCommonSelect items={vendorItems} size="small" variant="outlined" placeholder="벤더" value={vendor} onChange={e => setVendor(e.target.value)} />
-  <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
+  <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
     <OpsnowCommonTypography variant="e-m8">계정 :</OpsnowCommonTypography>
     <OpsnowCommonSelect items={accountItems} size="small" variant="outlined" placeholder="계정 선택" value={account} onChange={e => setAccount(e.target.value)} />
   </Stack>
-  <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
+  <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
     <OpsnowCommonTypography variant="e-m8">리전 :</OpsnowCommonTypography>
     <OpsnowCommonSelect items={regionItems} size="small" variant="outlined" placeholder="리전 선택" value={region} onChange={e => setRegion(e.target.value)} />
   </Stack>
 </Stack>`,
-        description: '한 화면에 필터를 여러 개 배치할 때의 간격 규칙 예제입니다. 필터 행 컨테이너의 gap은 무조건 24px, 라벨이 있는 필터는 라벨+필터를 gap 8px Stack으로 감싸며, 그 묶음과 앞 필터 사이는 동일하게 24px입니다. 간격은 spacing prop 대신 gap으로 지정합니다.'
+        description: '한 화면에 필터를 여러 개 배치할 때의 간격 규칙 예제입니다. 색상 토큰(theme.palette.commonPalette)과 동일하게 간격도 theme.commonSpacing 토큰을 참조합니다. 필터 행 컨테이너 gap은 theme.commonSpacing.filterGap(24px), 라벨이 있는 필터는 라벨+필터를 theme.commonSpacing.filterLabelGap(8px) Stack으로 감싸며, 그 묶음과 앞 필터 사이는 동일하게 filterGap입니다. px 하드코딩 대신 토큰으로 지정합니다.'
     }
 ];
 // Autocomplete(오토컴플리트) 컴포넌트 예제 데이터
@@ -165,22 +165,22 @@ export const AutocompleteExamples = [
         description: 'dropdownMaxWidth prop으로 확장 최대 너비(px)를 지정하는 예제입니다. 드롭다운이 입력 필드보다 넓게 확장되되 지정한 너비(360px)로 제한되고, 그보다 긴 라벨은 줄바꿈됩니다.'
     },
     {
-        title: 'Autocomplete - 필터 여러 개 배치 (간격 규칙: 필터 행 gap 24px, 라벨-필터 gap 8px)',
-        code: `<Stack sx={{ flexDirection: 'row', gap: '24px' }}>
+        title: 'Autocomplete - 필터 여러 개 배치 (간격 규칙: 필터 행 filterGap(24px), 라벨-필터 filterLabelGap(8px))',
+        code: `<Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
   <OpsnowCommonAutocomplete items={vendorItems} multiple value={vendors} onChange={setVendors} useCheckboxOption useSelectAll label="벤더" />
-  <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
+  <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
     <OpsnowCommonTypography variant="e-m8">계정 :</OpsnowCommonTypography>
     <Box sx={{ minWidth: 200 }}>
       <OpsnowCommonAutocomplete items={accountItems} multiple value={accounts} onChange={setAccounts} useCheckboxOption useSelectAll />
     </Box>
   </Stack>
-  <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
+  <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
     <OpsnowCommonTypography variant="e-m8">서비스 :</OpsnowCommonTypography>
     <Box sx={{ minWidth: 200 }}>
       <OpsnowCommonAutocomplete items={serviceItems} value={service} onChange={setService} />
     </Box>
   </Stack>
 </Stack>`,
-        description: '한 화면에 필터를 여러 개 배치할 때의 간격 규칙 예제입니다. 필터 행 컨테이너의 gap은 무조건 24px, 라벨이 있는 필터는 라벨+필터를 gap 8px Stack으로 감싸며, 그 묶음과 앞 필터 사이는 동일하게 24px입니다. 간격은 spacing prop 대신 gap으로 지정하고, Autocomplete는 Box(minWidth)로 최소 폭을 확보합니다. Select와 Autocomplete를 섞어 배치할 때도 같은 규칙이 적용됩니다.'
+        description: '한 화면에 필터를 여러 개 배치할 때의 간격 규칙 예제입니다. 색상 토큰(theme.palette.commonPalette)과 동일하게 간격도 theme.commonSpacing 토큰을 참조합니다. 필터 행 컨테이너 gap은 theme.commonSpacing.filterGap(24px), 라벨이 있는 필터는 라벨+필터를 theme.commonSpacing.filterLabelGap(8px) Stack으로 감싸며, 그 묶음과 앞 필터 사이는 동일하게 filterGap입니다. px 하드코딩 대신 토큰으로 지정하고, Autocomplete는 Box(minWidth)로 최소 폭을 확보합니다. Select와 Autocomplete를 섞어 배치할 때도 같은 규칙이 적용됩니다.'
     }
 ];

package/build/components/opsnow-common-calendar.js

@@ -65,7 +65,14 @@ export function createCalendarComponent() {
             name: "createCalendar",
             description: `캘린더 컴포넌트 - 날짜 선택 및 이벤트 관리
       **주의사항:**
-      - 선택된 날짜를 표시할 때 selectedDate가 null인 경우 'None'으로 표시됩니다.      
+      - 선택된 날짜를 표시할 때 selectedDate가 null인 경우 'None'으로 표시됩니다.
+      **필터로 배치할 때 간격 규칙 (다른 필터(Select/Autocomplete)와 함께 한 행에 둘 때, Select와 동일, px 하드코딩 금지):**
+      - 필터 행 컨테이너 gap: theme.commonSpacing.filterGap (24px)
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
+      - "기간 : <DatePicker>"처럼 라벨이 붙으면 라벨+DatePicker를 theme.commonSpacing.filterLabelGap (8px) Stack으로 감쌈
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
+      - 색상 토큰(theme.palette.commonPalette)과 동일하게 theme.commonSpacing 참조. 순수 CSS는 var(--opsnow-spacing-filter-gap) / var(--opsnow-spacing-filter-label-gap)
+
       **사용 예시:**
       \`\`\`jsx
       <p>

package/build/components/opsnow-common-examples.js

@@ -1,4 +1,4 @@
-import { ButtonExamples, BadgeExamples, TextareaExamples, SwitchExamples, ChipExamples, TextFieldExamples, AvatarExamples, CheckboxExamples, RadioGroupExamples, CollapseExamples, SliderExamples, LinkExamples, TreeViewExamples, InsightCardExamples, InsightContentExamples, ToggleButtonExamples } from "./examples/opsnow-common-forms-examples-data.js";
+import { ButtonExamples, BadgeExamples, TextareaExamples, SwitchExamples, ChipExamples, TextFieldExamples, AvatarExamples, CheckboxExamples, RadioGroupExamples, CollapseExamples, SliderExamples, LinkExamples, TreeViewExamples, InsightCardExamples, InsightContentExamples, CurrencySwitcherExamples, ToggleButtonExamples } from "./examples/opsnow-common-forms-examples-data.js";
 import { IconExamples, MuiIconExamples } from "./examples/opsnow-common-icons-examples-data.js";
 import { CalendarExamples } from "./examples/opsnow-common-calendar-examples-data.js";
 import { GaugeChartExamples, PieChartExamples, BarChartExamples, LineChartExamples, StackChartExamples, XyMultiChartExamples, HeatmapChartExamples, BubbleChartExamples } from "./examples/opsnow-common-chart-examples-data.js";
@@ -36,6 +36,7 @@ export const EXAMPLES_MAP = {
     TreeView: TreeViewExamples,
     InsightCard: InsightCardExamples,
     InsightContent: InsightContentExamples,
+    CurrencySwitcher: CurrencySwitcherExamples,
     ToggleButtonGroup: ToggleButtonExamples,
     Icon: IconExamples,
     MuiIcon: MuiIconExamples,

package/build/components/opsnow-common-forms.js

@@ -290,6 +290,23 @@ export const InsightContentSchema = z.object({
     emptyMessage: z.string().optional().describe("insightText가 없을 때 표시할 빈 메시지"),
     sx: z.string().optional().describe("MUI sx 스타일 객체(JSX/문자열)"),
 });
+// CurrencySwitcher 컴포넌트 관련 스키마 정의 (통화 전환 드롭다운 + 환율 팝오버, opsnow-common-forms >= 1.0.19)
+export const CurrencySwitcherSchema = z.object({
+    value: z.string().describe("현재 표시 통화 코드 상태 변수명 (controlled, 예: currency)"),
+    onChange: z.string().describe("통화 선택/직접 입력 시 호출되는 핸들러 함수명 — (currency, rate) => void 형태, rate는 기준 통화 1단위당 적용 환율 (예: handleCurrencyChange)"),
+    rateInfo: z.string().optional().describe("기준일 환율 정보 객체 변수명 — { baseDate, source?, rates } 형태로 BE 환율 API 응답을 주입 (없으면 목록에 환율이 '-'로 표시, 예: rateInfo)"),
+    history: z.string().optional().describe("환율 상세 보기 추이 차트 데이터 배열 변수명 — Array<{ label, rate }>, 과거 → 현재 순이며 마지막 값 = 현재 환율 (예: history)"),
+    currencyOptions: z.string().optional().describe("팝오버 통화 목록 배열 변수명 — Array<{ code, symbol, digits? }> (기본: USD/KRW/JPY/VND/AED)"),
+    baseCurrency: z.string().optional().describe("변환 기준 통화 코드 (기본값: 'USD')"),
+    defaultTargetCurrency: z.string().optional().describe("기준 통화 선택 중일 때 상세 보기가 다룰 초기 비교 통화 코드"),
+    customRate: z.string().optional().describe("직접 입력 시뮬레이션 환율 상태 변수명 (number | null, controlled 모드 — 미지정 시 내부 관리)"),
+    onCustomRateChange: z.string().optional().describe("직접 입력 환율 변경 핸들러 함수명 — (rate) => void 형태"),
+    showDetail: z.boolean().optional().describe("환율 상세 보기 드릴다운 노출 여부 (기본값: true)"),
+    renderChart: z.string().optional().describe("추이 차트 교체 슬롯 함수명 — (history, currency) => ReactNode 형태 (기본: 내장 SVG 스파크라인)"),
+    labels: z.string().optional().describe("문구 개별 커스텀 객체 변수명 — Partial<CurrencySwitcherLabels>, i18n(ko/en/ja) 번역 위에 항목별로 덮어씀 ({placeholder} 템플릿 치환 지원)"),
+    size: z.enum(["small", "medium"]).optional().describe("트리거 크기"),
+    disabled: z.boolean().optional().describe("비활성화 여부"),
+});
 // Forms 컴포넌트 함수 - 배열 반환
 export function createFormsComponent() {
     return [
@@ -1004,6 +1021,11 @@ export function createFormsComponent() {
             name: "createInsightCard",
             description: `InsightCard 컴포넌트 - AI 인사이트, 로딩 상태 등 지원
 
+      **간격 규칙 (여러 카드/섹션을 배치할 때, px 하드코딩 금지):**
+      - 카드(섹션 그룹) 사이 간격: theme.commonSpacing.sectionGap (24px)
+      - 카드 내부 요소 간 간격: theme.commonSpacing.cardGap (16px)
+      - 색상 토큰(theme.palette.commonPalette)과 동일하게 theme.commonSpacing 참조. 순수 CSS는 var(--opsnow-spacing-section-gap) / var(--opsnow-spacing-card-gap)
+
       **import:**
       \`\`\`javascript
       import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
@@ -1051,6 +1073,11 @@ export function createFormsComponent() {
             name: "createInsightContent",
             description: `InsightContent 컴포넌트 - 타일 없이 AI 인사이트 콘텐츠만 표시
 
+      **간격 규칙 (콘텐츠를 카드/섹션 안에 조합할 때, px 하드코딩 금지):**
+      - 카드 내부 요소 간 간격: theme.commonSpacing.cardGap (16px)
+      - 섹션(카드 그룹) 사이 간격: theme.commonSpacing.sectionGap (24px)
+      - 색상 토큰(theme.palette.commonPalette)과 동일하게 theme.commonSpacing 참조
+
       **import:**
       \`\`\`javascript
       import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
@@ -1083,6 +1110,72 @@ export function createFormsComponent() {
                     ]
                 };
             }
+        },
+        {
+            name: "createCurrencySwitcher",
+            description: `CurrencySwitcher 컴포넌트 - 통화 전환 드롭다운 + 환율 팝오버, 환율/통화 필터로 사용 (opsnow-common-forms >= 1.0.19)
+
+      트리거에 현재 선택된 통화가 표시되고, 클릭하면 팝오버에서 적용 환율 기준일 안내와
+      통화 목록(클릭 시 즉시 적용)을 제공합니다. "환율 상세 보기" 드릴다운에서 직접 입력
+      시뮬레이션, 현재/최고/최저/변동 스탯, 환율 추이 차트를 확인할 수 있습니다.
+
+      **데이터 주입 규칙 (중요):**
+      - 환율 데이터는 컴포넌트가 조회하지 않습니다 — BE 환율 API 응답을 rateInfo / history props로 주입하세요.
+      - rateInfo: { baseDate: 'YYYY-MM-DD', source?: '출처', rates: { USD: 1, KRW: 1450, ... } } — 기준 통화 1단위당 환율
+      - history: [{ label: '25.07', rate: 1495.3 }, ...] — 과거 → 현재 순, 마지막 값 = 현재 환율
+      - BE API 호출 시 axios 직접 import 금지 — getAxios() 공통 axios 사용
+
+      **동작 규칙:**
+      - 선택/직접 입력 시 onChange(code, rate)가 호출됩니다 — 금액 표시 변환은 소비 프로젝트에서 rate로 처리
+      - 직접 입력 환율은 시뮬레이션 용도이며 저장되지 않습니다
+      - 문구는 i18n 현재 언어(ko/en/ja)를 자동으로 따르고, labels prop으로 항목별 커스텀 가능
+
+      **import:**
+      \`\`\`javascript
+      import { useCommonComponents } from '@opsnow-common/opsnow-finops-common-ui-loader';
+      const { OpsnowCommonCurrencySwitcher } = useCommonComponents();
+      \`\`\``,
+            parameters: CurrencySwitcherSchema,
+            handler: async (args) => {
+                const props = [];
+                if (args.value)
+                    props.push(`value={${args.value}}`);
+                if (args.onChange)
+                    props.push(`onChange={${args.onChange}}`);
+                if (args.rateInfo)
+                    props.push(`rateInfo={${args.rateInfo}}`);
+                if (args.history)
+                    props.push(`history={${args.history}}`);
+                if (args.currencyOptions)
+                    props.push(`currencyOptions={${args.currencyOptions}}`);
+                if (args.baseCurrency)
+                    props.push(`baseCurrency="${args.baseCurrency}"`);
+                if (args.defaultTargetCurrency)
+                    props.push(`defaultTargetCurrency="${args.defaultTargetCurrency}"`);
+                if (args.customRate)
+                    props.push(`customRate={${args.customRate}}`);
+                if (args.onCustomRateChange)
+                    props.push(`onCustomRateChange={${args.onCustomRateChange}}`);
+                if (args.showDetail !== undefined)
+                    props.push(`showDetail={${args.showDetail}}`);
+                if (args.renderChart)
+                    props.push(`renderChart={${args.renderChart}}`);
+                if (args.labels)
+                    props.push(`labels={${args.labels}}`);
+                if (args.size)
+                    props.push(`size="${args.size}"`);
+                if (args.disabled)
+                    props.push(`disabled`);
+                const code = `<OpsnowCommonCurrencySwitcher\n  ${props.join('\n  ')}\n/>`;
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: `\`\`\`jsx\n${code}\n\`\`\``
+                        }
+                    ]
+                };
+            }
         }
     ];
 }

package/build/components/opsnow-common-layout.js

@@ -42,6 +42,13 @@ export function createGridLayoutComponent() {
             name: "createGridLayout",
             description: `Grid 및 Box 기반 레이아웃 생성
 
+        **간격 규칙 (px 하드코딩 금지, 색상 토큰처럼 theme.commonSpacing 참조):**
+        - 페이지/그리드 컨테이너 패딩: theme.commonSpacing.pagePadding (24px)
+        - 섹션(카드 그룹) 사이 간격: theme.commonSpacing.sectionGap (24px) — Grid container의 gap
+        - 카드(Box) 내부 패딩: theme.commonSpacing.cardPadding ('16px 20px')
+        - 카드 내부 요소 간 간격: theme.commonSpacing.cardGap (16px)
+        - 값이 여러 개이므로 sx는 콜백 형태로: sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}
+
         **import:**
         \`\`\`jsx
         import { Box, Grid } from '@mui/material';
@@ -56,20 +63,21 @@ export function createGridLayoutComponent() {
                         .map(([k, v]) => `${k}={${v}}`)
                         .join(" ");
                     return `  <Grid item ${bpProps} key={${i}}>` +
-                        `\n    <Box sx={{` +
+                        `\n    <Box sx={theme => ({` +
                         `\n      border: '1px solid #ddd',` +
                         `\n      borderRadius: '12px',` +
-                        `\n      padding: 2,` +
+                        `\n      padding: theme.commonSpacing.cardPadding,` +
+                        `\n      gap: theme.commonSpacing.cardGap,` +
                         `\n      display: 'flex',` +
                         `\n      flexDirection: 'column',` +
                         `\n      boxShadow: '2px 2px 8px 0 #4254663D',` +
-                        `\n    }}>` +
+                        `\n    })}>` +
                         `\n      ${item}` +
                         `\n    </Box>` +
                         `\n  </Grid>`;
                 }).join("\n");
                 const code = [
-                    `<Grid container wrap="nowrap" spacing={0} sx={{ padding: '27px', gap: '27px' }}>`,
+                    `<Grid container wrap="nowrap" spacing={0} sx={theme => ({ padding: theme.commonSpacing.pagePadding, gap: theme.commonSpacing.sectionGap })}>`,
                     gridItems,
                     `</Grid>`,
                 ].join("\n");

package/build/components/opsnow-common-select.js

@@ -56,12 +56,14 @@ export function createSelectComponent() {
       - value/onChange는 단일/다중 선택에 따라 배열 또는 단일 값
 
       **필터 배치 간격 규칙 (한 화면에 필터 여러 개 배치 시 무조건 적용):**
-      - 필터를 감싸는 행(row) 컨테이너의 gap은 무조건 24px:
-        <Stack sx={{ flexDirection: 'row', gap: '24px' }}>
-      - "계정 : <필터>"처럼 라벨이 붙는 경우 라벨+필터를 gap 8px Stack으로 감쌈:
-        <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
-      - 라벨이 있는 필터도 앞 필터와의 간격은 동일하게 24px (라벨+필터 묶음 전체가 하나의 필터로 취급됨)
-      - 간격은 spacing prop이 아니라 gap으로 지정
+      색상 토큰(theme.palette.commonPalette)과 동일하게, 간격도 시맨틱 토큰 theme.commonSpacing 을 참조합니다 (px 하드코딩 금지).
+      - 필터를 감싸는 행(row) 컨테이너 gap은 theme.commonSpacing.filterGap (= 24px):
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
+      - "계정 : <필터>"처럼 라벨이 붙는 경우 라벨+필터를 theme.commonSpacing.filterLabelGap (= 8px) Stack으로 감쌈:
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
+      - 라벨이 있는 필터도 앞 필터와의 간격은 동일하게 filterGap (라벨+필터 묶음 전체가 하나의 필터로 취급됨)
+      - 간격은 spacing prop이나 px 하드코딩이 아니라 theme.commonSpacing 토큰으로 지정 (theme.commonSpacing. 까지 치면 자동완성)
+      - theme 컨텍스트를 못 쓰는 순수 CSS는 var(--opsnow-spacing-filter-gap) / var(--opsnow-spacing-filter-label-gap) 사용
       - 필터가 많아 화면 폭을 넘칠 수 있으면 행 컨테이너에 flexWrap: 'wrap' 추가 (선택)
 
       **import:**
@@ -109,12 +111,14 @@ export function createSelectComponent() {
       - value/onChange는 단일/다중 선택에 따라 배열 또는 단일 값
 
       **필터 배치 간격 규칙 (한 화면에 필터 여러 개 배치 시 무조건 적용):**
-      - 필터를 감싸는 행(row) 컨테이너의 gap은 무조건 24px:
-        <Stack sx={{ flexDirection: 'row', gap: '24px' }}>
-      - "계정 : <필터>"처럼 라벨이 붙는 경우 라벨+필터를 gap 8px Stack으로 감쌈:
-        <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
-      - 라벨이 있는 필터도 앞 필터와의 간격은 동일하게 24px (라벨+필터 묶음 전체가 하나의 필터로 취급됨)
-      - 간격은 spacing prop이 아니라 gap으로 지정
+      색상 토큰(theme.palette.commonPalette)과 동일하게, 간격도 시맨틱 토큰 theme.commonSpacing 을 참조합니다 (px 하드코딩 금지).
+      - 필터를 감싸는 행(row) 컨테이너 gap은 theme.commonSpacing.filterGap (= 24px):
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
+      - "계정 : <필터>"처럼 라벨이 붙는 경우 라벨+필터를 theme.commonSpacing.filterLabelGap (= 8px) Stack으로 감쌈:
+        <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
+      - 라벨이 있는 필터도 앞 필터와의 간격은 동일하게 filterGap (라벨+필터 묶음 전체가 하나의 필터로 취급됨)
+      - 간격은 spacing prop이나 px 하드코딩이 아니라 theme.commonSpacing 토큰으로 지정 (theme.commonSpacing. 까지 치면 자동완성)
+      - theme 컨텍스트를 못 쓰는 순수 CSS는 var(--opsnow-spacing-filter-gap) / var(--opsnow-spacing-filter-label-gap) 사용
       - 필터가 많아 화면 폭을 넘칠 수 있으면 행 컨테이너에 flexWrap: 'wrap' 추가 (선택)
 
       **import:**

package/build/index.js

@@ -84,28 +84,45 @@ Before implementing OpsnowCommonDataGrid, you MUST use getUIExamples tool with '
 
    Reference example: "Search + Pagination"
 
-**CRITICAL: Filter Layout Spacing Rules (Select/Autocomplete)**
+**CRITICAL: Spacing Tokens (theme.commonSpacing) — DO NOT hardcode px**
 
-When placing multiple filters (Select/Autocomplete) in one row, the gap values are MANDATORY:
+Just like color tokens (theme.palette.commonPalette), all layout spacing uses the semantic token theme.commonSpacing
+(requires @opsnow-common/opsnow-common-style 1.0.11+, type-augmented → autocompletes, light/dark 공통):
 
-   [CORRECT] Row container MUST have gap 24px, label+filter group MUST have gap 8px:
-   <Stack sx={{ flexDirection: 'row', gap: '24px' }}>
+   filterGap      24px        - gap between filters (filter row gap)
+   filterLabelGap 8px         - gap between label and its filter
+   filterRowGap   12px        - marginBottom below a filter row
+   sectionGap     24px        - gap between sections (card groups)
+   cardGap        16px        - gap between elements inside a card
+   cardPadding    '16px 20px' - padding of a filter bar / card container
+   pagePadding    24px        - page content padding
+
+Use theme in sx/styled: sx={theme => ({ gap: theme.commonSpacing.filterGap })} or sx={{ gap: theme => theme.commonSpacing.filterLabelGap }}.
+Pure CSS (no theme context): var(--opsnow-spacing-filter-gap), --opsnow-spacing-filter-label-gap, --opsnow-spacing-section-gap, --opsnow-spacing-card-gap, --opsnow-spacing-card-padding, --opsnow-spacing-page-padding, --opsnow-spacing-filter-row-gap.
+Outside theme context (constants/utils): import { commonSpacing } from '@opsnow-common/opsnow-common-style'; commonSpacing.filterGap // '24px'.
+Found hardcoded px spacing? You MUST replace it: (1) use the token for that purpose → (2) if none fits, use theme.spacing(n) for generic multiples (base 4px → theme.spacing(2) = 8px) → (3) still nothing? DO NOT keep px — ask to add a new token in the style package (one row).
+
+--- Filter layout (Select/Autocomplete/DatePicker/DataGrid search area) ---
+When placing multiple filters in one row, the gap values are MANDATORY:
+
+   [CORRECT] Row container MUST use theme.commonSpacing.filterGap (24px), label+filter group MUST use theme.commonSpacing.filterLabelGap (8px):
+   <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterGap }}>
      <OpsnowCommonSelect ... />
-     <Stack sx={{ flexDirection: 'row', gap: '8px' }}>
+     <Stack sx={{ flexDirection: 'row', gap: theme => theme.commonSpacing.filterLabelGap }}>
        <OpsnowCommonTypography variant="e-m8">계정 :</OpsnowCommonTypography>
        <OpsnowCommonAutocomplete ... />
      </Stack>
    </Stack>
 
-   [FORBIDDEN] DO NOT place filters without gap:
-   <Stack direction="row">        <- gap 누락 금지!
-     <OpsnowCommonSelect ... />
-     <OpsnowCommonSelect ... />
-   </Stack>
+   [FORBIDDEN] DO NOT hardcode px and DO NOT place filters without gap:
+   <Stack direction="row" sx={{ gap: '24px' }}>   <- px 하드코딩 금지, 토큰 사용!
+   <Stack direction="row">                        <- gap 누락 금지!
 
-   - Adjacent filters: 24px gap (gap style, NOT spacing prop)
-   - Label and its filter: 8px gap (wrap label+filter in one Stack)
-   - A labeled group counts as ONE filter — still 24px from the previous filter
+   - Adjacent filters: theme.commonSpacing.filterGap (24px) — token, NOT hardcoded px or spacing prop
+   - Label and its filter: theme.commonSpacing.filterLabelGap (8px) — wrap label+filter in one Stack
+   - A labeled group counts as ONE filter — still filterGap from the previous filter
+   - Pure CSS (no theme context): use var(--opsnow-spacing-filter-gap) / var(--opsnow-spacing-filter-label-gap)
+   - Requires @opsnow-common/opsnow-common-style 1.0.11+ (theme.commonSpacing is type-augmented → autocompletes)
 
 WARNING: Violating these rules will cause the UI to malfunction.`
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opsnow-mcp/opsnow-mcp-common-ui-server",
-  "version": "1.0.32",
+  "version": "1.0.34",
   "type": "module",
   "main": "index.js",
   "bin": {