@ncds/ui-admin-mcp 1.0.0-alpha.2 → 1.0.0-alpha.20

package/bin/definitions/js-api.json

@@ -0,0 +1,352 @@
+{
+  "Modal": {
+    "className": "Modal",
+    "constructor": "new window.ncua.Modal(options?)",
+    "constructorParams": {
+      "size": "'sm' | 'md' | 'lg' (default: 'md')",
+      "closeOnBackdropClick": "boolean (default: false)",
+      "closeOnEsc": "boolean (default: true)",
+      "onClose": "() => void"
+    },
+    "methods": ["open()", "close()", "destroy()", "setContent(html: string | HTMLElement)", "isModalOpen()"],
+    "example": "const modal = new window.ncua.Modal({ size: 'sm', onClose: () => {} });\nmodal.setContent('<p>Content</p>');\nmodal.open();",
+    "cdnDefaults": {
+      "size": "md",
+      "closeOnBackdropClick": false,
+      "closeOnEsc": true
+    }
+  },
+  "SelectBox": {
+    "className": "SelectBox",
+    "cdnPattern": "A",
+    "constructor": "new window.ncua.SelectBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, text: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.size": "'xs' | 'sm' | 'md'",
+      "config.multiple": "boolean",
+      "config.disabled": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "getSelectedCount()"],
+    "example": "const select = new window.ncua.SelectBox(document.getElementById('my-select'), {\n  options: [{ id: '1', text: 'Option 1' }],\n  onChange: (value) => console.log(value)\n});",
+    "cdnDefaults": {
+      "size": "md",
+      "placeholder": "선택하세요",
+      "disabled": false,
+      "multiple": false
+    }
+  },
+  "ComboBox": {
+    "className": "ComboBox",
+    "cdnPattern": "A",
+    "constructor": "new window.ncua.ComboBox(element, config?)",
+    "constructorParams": {
+      "element": "HTMLElement — target container",
+      "config.options": "Array<{ id: string, label: string, disabled?: boolean }>",
+      "config.placeholder": "string (default: '검색하고 선택하세요')",
+      "config.value": "string | number",
+      "config.onChange": "(value) => void",
+      "config.onSearch": "(searchValue: string) => void",
+      "config.size": "'xs' | 'sm'",
+      "config.multiple": "boolean"
+    },
+    "methods": ["getValues()", "setValues(options[])", "clearInput()", "getSelectedCount()"],
+    "example": "const combo = new window.ncua.ComboBox(document.getElementById('my-combo'), {\n  options: [{ id: '1', label: 'React' }],\n  onSearch: (q) => console.log(q)\n});",
+    "cdnDefaults": {
+      "size": "md",
+      "placeholder": "검색하고 선택하세요",
+      "disabled": false,
+      "multiple": false,
+      "showFooterButtons": false
+    }
+  },
+  "DatePicker": {
+    "className": "DatePicker",
+    "cdnPattern": "A",
+    "constructor": "new window.ncua.DatePicker(wrapper, options)",
+    "constructorParams": {
+      "wrapper": "HTMLElement — container element",
+      "options.size": "'xs' | 'sm'",
+      "options.datePickerOptions": "Array<{ element: string, attrName?: string, placeholder?: string, options: FlatpickrOptions }>",
+      "options.buttons": "Array<{ text: string, period: number, unit: 'days'|'weeks'|'months'|'years', isCurrent: boolean }>",
+      "options.onValidationError": "(error: ValidationError) => void",
+      "options.autoComplete": "'on' | 'off'"
+    },
+    "methods": ["getDates()", "setDate(dates: string[])", "setMultipleDates(dates: string[])"],
+    "example": "const dp = new window.ncua.DatePicker(document.getElementById('my-dp'), {\n  size: 'xs',\n  datePickerOptions: [{ element: 'date-input', placeholder: 'Select date', options: { dateFormat: 'Y-m-d' } }]\n});",
+    "cdnDefaults": {
+      "size": "xs",
+      "datePickerOptions": [
+        {
+          "options": {
+            "mode": "single",
+            "static": true,
+            "dateFormat": "Y-m-d",
+            "clickOpens": true,
+            "allowInvalidPreload": true,
+            "locale": "ko"
+          }
+        }
+      ]
+    }
+  },
+  "Slider": {
+    "className": "Slider",
+    "cdnPattern": "A",
+    "constructor": "new window.ncua.Slider(element, options)",
+    "constructorParams": {
+      "element": "HTMLElement — container",
+      "options.min": "number (default: 0)",
+      "options.max": "number (default: 100)",
+      "options.step": "number (default: 1)",
+      "options.value": "number | [number, number]",
+      "options.onChange": "(value) => void",
+      "options.disabled": "boolean",
+      "options.labelPosition": "'bottom' | 'top-floating'"
+    },
+    "methods": ["getValue()", "setValue(value)", "enable()", "disable()", "destroy()"],
+    "example": "const slider = new window.ncua.Slider(document.getElementById('my-slider'), {\n  min: 0, max: 100, value: 50,\n  onChange: (v) => console.log(v)\n});",
+    "cdnDefaults": {
+      "min": 0,
+      "max": 100,
+      "step": 1,
+      "labelPosition": "top-floating",
+      "disabled": false,
+      "value": 0
+    }
+  },
+  "HorizontalTab": {
+    "className": "Tab",
+    "constructor": "new window.ncua.Tab(swiperEl)",
+    "constructorParams": {
+      "swiperEl": "HTMLElement — `.swiper` 클래스를 가진 element 자체. render_to_html 응답의 `.ncua-horizontal-tab` 내부에 있는 `.swiper` 를 선택해 전달해야 한다. wrapper element 를 넘기면 내부 Swiper 라이브러리가 부모 element 의 스타일을 계산하지 못해 초기화에 실패한다."
+    },
+    "methods": ["destroy()"],
+    "example": "const tab = new window.ncua.Tab(document.querySelector('#my-tab .swiper'));"
+  },
+  "Tooltip": {
+    "className": "Tooltip",
+    "cdnPattern": "C",
+    "constructor": "window.ncua.Tooltip.createShort(title, content?, options?)",
+    "constructorParams": {
+      "title": "string",
+      "content": "string (HTML supported)",
+      "options.position": "'top' | 'bottom' | 'left' | 'right' | 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right' | 'auto' (default: 'auto')",
+      "options.type": "'long' | 'short'",
+      "options.tooltipType": "'white' | 'black'",
+      "options.iconType": "'stroke' | 'fill'",
+      "options.size": "'sm' | 'md'",
+      "options.hideArrow": "boolean",
+      "options.zIndex": "number",
+      "options.useShadowDOM": "boolean",
+      "options.className": "string"
+    },
+    "methods": ["getElement()", "showTooltip()", "hideTooltip()", "destroy()"],
+    "example": "const tip = window.ncua.Tooltip.createShort('Help', 'Tooltip content');\ndocument.getElementById('container').appendChild(tip.getElement());",
+    "cdnDefaults": {
+      "type": "short",
+      "tooltipType": "white",
+      "iconType": "stroke",
+      "position": "auto",
+      "size": "sm",
+      "hideArrow": false
+    }
+  },
+  "Notification": {
+    "className": "Notification",
+    "cdnPattern": "C",
+    "constructor": "window.ncua.Notification.success(title, supportingText?, options?)",
+    "cdnDefaults": {
+      "type": "floating",
+      "color": "neutral",
+      "autoClose": 0
+    },
+    "constructorParams": {
+      "title": "string",
+      "supportingText": "string",
+      "options.autoClose": "number (ms, 0 = no auto-close)",
+      "options.type": "'floating' | 'message' | 'full-width'",
+      "options.color": "'neutral' | 'success' | 'error' | 'warning' | 'info'",
+      "options.actions": "Array<NotificationAction>",
+      "options.onClose": "() => void",
+      "options.className": "string",
+      "options.supportTextLink": "string — full-width 전용 supportingText 링크 URL",
+      "options.onHidePermanently": "() => void — full-width/message 다시보지 않기 핸들러"
+    },
+    "methods": ["show(parent?)", "remove()", "destroy()"],
+    "staticMethods": ["success()", "error()", "warning()", "info()", "neutral()"],
+    "example": "window.ncua.Notification.success('Saved', 'Changes saved successfully');"
+  },
+  "ProgressBar": {
+    "className": "ProgressBar",
+    "cdnPattern": "C",
+    "constructor": "new window.ncua.ProgressBar(options?)",
+    "constructorParams": {
+      "options.value": "number (0-100)",
+      "options.label": "'right' | 'bottom' | 'top-float' | 'bottom-float'",
+      "options.segments": "ProgressSegment[] — 멀티 세그먼트 진행률",
+      "options.showZeroLabel": "boolean — 0% 라벨 표시 여부",
+      "options.valueToPercent": "boolean — value 를 % 환산 표시"
+    },
+    "methods": ["getElement()", "updateOptions(newOptions)", "toHTML()"],
+    "example": "const bar = new window.ncua.ProgressBar({ value: 65, label: 'right' });\ndocument.getElementById('container').appendChild(bar.getElement());",
+    "cdnDefaults": {
+      "label": "right",
+      "showZeroLabel": false,
+      "valueToPercent": true
+    }
+  },
+  "Tag": {
+    "className": "Tag",
+    "cdnPattern": "C",
+    "constructor": "new window.ncua.Tag(options)",
+    "constructorParams": {
+      "options.text": "string",
+      "options.size": "'sm' | 'md' (default: 'sm')",
+      "options.close": "boolean — show close button",
+      "options.onButtonClick": "(event: MouseEvent) => void — close handler",
+      "options.count": "string — 카운트 표시",
+      "options.icon": "SideSlotType — 좌측 아이콘 슬롯",
+      "options.maxLength": "number — 최대 텍스트 길이 (default: 20)"
+    },
+    "methods": ["getElement()", "setText(text)", "setCount(count)", "destroy()"],
+    "example": "const tag = new window.ncua.Tag({ text: 'Label', close: true, onButtonClick: () => tag.destroy() });\ndocument.getElementById('container').appendChild(tag.getElement());",
+    "cdnDefaults": {
+      "size": "sm",
+      "maxLength": 20
+    }
+  },
+  "FileInput": {
+    "className": "FileInput",
+    "cdnPattern": "B",
+    "constructor": "new window.ncua.FileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void",
+      "options.onFail": "(invalidFiles: File[]) => void",
+      "options.disabled": "boolean",
+      "options.size": "'xs' | 'sm'",
+      "options.accept": "string — e.g. '.jpg,.png' or 'image/*'",
+      "options.multiple": "boolean",
+      "options.maxFileCount": "number",
+      "options.maxFileSize": "number — bytes",
+      "options.buttonLabel": "string",
+      "options.label": "string",
+      "options.hintItems": "string[]",
+      "options.isRequired": "boolean",
+      "options.showHelpIcon": "boolean",
+      "options.hintText": "string",
+      "options.validation": "boolean",
+      "options.destructive": "boolean",
+      "options.className": "string"
+    },
+    "methods": ["getElement()", "setDisabled(boolean)", "destroy()"],
+    "example": "const fi = new window.ncua.FileInput({\n  container: 'file-container',\n  onChange: (files) => console.log(files)\n});",
+    "cdnDefaults": {
+      "buttonLabel": "파일 찾기",
+      "multiple": false,
+      "size": "xs"
+    }
+  },
+  "ImageFileInput": {
+    "className": "ImageFileInput",
+    "cdnPattern": "B",
+    "constructor": "new window.ncua.ImageFileInput(options)",
+    "constructorParams": {
+      "options.container": "HTMLElement | string — auto-append target",
+      "options.onChange": "(files: File[]) => void — controlled mode",
+      "options.onFileSelect": "(files: File[]) => void — uncontrolled mode",
+      "options.onFail": "(files: InvalidFile[]) => void",
+      "options.value": "File[] — initial files (controlled mode)",
+      "options.disabled": "boolean",
+      "options.size": "'xs' | 'sm'",
+      "options.accept": "string — e.g. '.jpg,.png' or 'image/*'",
+      "options.multiple": "boolean",
+      "options.maxFileCount": "number",
+      "options.maxFileSize": "number — bytes",
+      "options.buttonLabel": "string",
+      "options.imagePreviewTooltipLabel": "string",
+      "options.label": "string",
+      "options.hintItems": "string[]",
+      "options.isRequired": "boolean",
+      "options.showHelpIcon": "boolean",
+      "options.hintText": "string",
+      "options.validation": "boolean",
+      "options.destructive": "boolean",
+      "options.fileInputName": "string — name attr (PHP form 제출용)",
+      "options.className": "string"
+    },
+    "cdnDefaults": {
+      "buttonLabel": "파일 찾기",
+      "imagePreviewTooltipLabel": "이미지 업로드",
+      "multiple": false,
+      "size": "sm"
+    },
+    "methods": ["getElement()", "getFiles()", "clearFiles()", "setDisabled(boolean)", "destroy()"],
+    "example": "const img = new window.ncua.ImageFileInput({\n  container: 'image-container',\n  maxFileCount: 5,\n  onChange: (files) => console.log(files)\n});"
+  },
+  "FeaturedIcon": {
+    "className": "FeaturedIcon",
+    "constructor": "new window.ncua.FeaturedIcon(options)",
+    "constructorParams": {
+      "options.svgString": "string — SVG content",
+      "options.theme": "'light-circle' | 'dark-circle' | 'outline-circle' | 'square-outline'",
+      "options.color": "'neutral' | 'error' | 'warning' | 'success'",
+      "options.size": "'sm' | 'md' | 'lg' | 'xl'",
+      "options.className": "string"
+    },
+    "methods": ["getElement()", "updateColor(color)", "updateSize(size)", "destroy()"],
+    "example": "const icon = new window.ncua.FeaturedIcon({ svgString: '<svg>...</svg>', color: 'success', size: 'md' });\ndocument.getElementById('container').appendChild(icon.getElement());",
+    "cdnDefaults": {
+      "theme": "light-circle",
+      "color": "neutral",
+      "size": "sm"
+    }
+  },
+  "Table": {
+    "className": "Table",
+    "constructor": "new window.ncua.Table(options)",
+    "constructorParams": {
+      "options.columns": "TableColumn[] — { key: string; label: string; width?: string; sortable?: boolean; align?: 'left'|'center'|'right'; render?: (value, row, index) => string | HTMLElement }",
+      "options.data": "Record<string, unknown>[] — row data",
+      "options.type": "'horizontal' | 'vertical' (default: 'horizontal')",
+      "options.hoverable": "boolean (default: true) — horizontal type 한정",
+      "options.selectable": "boolean (default: false)",
+      "options.fixedHeader": "boolean (default: false)",
+      "options.maxHeight": "string — fixedHeader 와 함께 사용 (예: '320px')",
+      "options.emptyText": "string (default: '등록된 게시물이 없습니다.')",
+      "options.onSort": "(key: string, direction: 'asc' | 'desc' | 'none') => void",
+      "options.onSelect": "(selectedIndices: number[]) => void"
+    },
+    "methods": ["getElement()", "setData(data: Record<string, unknown>[])", "getSelectedIndices()", "destroy()"],
+    "example": "const table = new window.ncua.Table({\n  columns: [{ key: 'name', label: '이름', sortable: true }],\n  data: [{ name: 'Alice' }, { name: 'Bob' }],\n  selectable: true,\n  onSelect: (indices) => console.log(indices),\n});\ndocument.getElementById('container').appendChild(table.getElement());",
+    "cdnDefaults": {
+      "type": "horizontal",
+      "hoverable": true,
+      "selectable": false,
+      "fixedHeader": false
+    }
+  },
+  "Dropdown": {
+    "className": "Dropdown",
+    "constructor": "new window.ncua.Dropdown(host, options)",
+    "constructorParams": {
+      "host": "HTMLElement — Dropdown 이 부착될 컨테이너 (필수, 첫 번째 인자)",
+      "options.trigger": "{ type: 'icon'|'avatar'|'button'|'custom', text?: string, iconHtml?: string, avatar?: string, html?: string } — 트리거 형태",
+      "options.groups": "DropdownGroup[] — 메뉴 항목 그룹 (각 그룹은 items: DropdownItem[], sortable?: boolean)",
+      "options.header": "{ type?: 'avatar', title?: string, subtitle?: string, avatar?: string } — 메뉴 상단 헤더 (옵션)",
+      "options.align": "'left' | 'right' — 메뉴 정렬 (default: 'left')",
+      "options.variant": "'action' | 'config' — 액션 메뉴 vs 설정 메뉴 (default: 'action')",
+      "options.closeOnClickItem": "boolean (default: true) — action variant 한정",
+      "options.closeOnClickOutside": "boolean (default: true)",
+      "options.className": "string — 추가 클래스",
+      "options.applyButtonText": "string — config variant 의 적용 버튼 텍스트 (default: '설정 완료')",
+      "options.onApply": "(items: DropdownItem[]) => void — config variant 적용 시 콜백"
+    },
+    "methods": ["toggle()", "open()", "close()", "closeAndRestoreFocus()", "destroy()"],
+    "example": "const dropdown = new window.ncua.Dropdown(document.getElementById('my-host'), {\n  trigger: { type: 'button', text: '메뉴' },\n  groups: [{\n    items: [\n      { id: 'edit', text: '수정', onClick: () => console.log('edit') },\n      { id: 'delete', text: '삭제', type: 'danger', onClick: () => console.log('delete') },\n    ],\n  }],\n});"
+  }
+}

package/bin/definitions/rules.json

@@ -3,7 +3,8 @@
     "You MUST generate component HTML using the render_to_html tool. Never write HTML/CSS manually.",
     "Use the HTML returned by render_to_html as-is. Do NOT modify class names, structure, or attributes.",
     "Use search_component to find the right component by Korean/English keywords before building any UI.",
-    "Use list_components to browse available components by category and choose the appropriate one."
+    "Use list_components to browse available components by category and choose the appropriate one.",
+    "When building a page with multiple components, use render_to_html_batch to render them all in one call instead of calling render_to_html repeatedly."
   ],
   "componentSelection": [
     "For password fields, you MUST use password-input. The input component is for plain text only.",
@@ -34,14 +35,44 @@
   "forbidden": [
     "Do NOT override ncua-* classes with custom CSS. Control appearance through component props only.",
     "Do NOT define CSS variables (--ncua-*) yourself. They are already included in the CDN CSS.",
-    "Do NOT write SVG icons manually. Use search_icon to find icons from the icon library."
+    "Do NOT write SVG icons manually. Use search_icon to find icons from the icon library.",
+    "⚠️ P22 — DO NOT write fallback / override CSS for ncua-* classes claiming 'CDN 미제공' or 'CDN gap'. The NCDS CDN CSS provides ALL base styles for every component in the catalog (page-title / switch / tooltip / table / data-grid / modal / notification / etc). If you think a class is missing, you are wrong — call render_to_html('<component-name>', props) FIRST to see the actual output. Patterns FORBIDDEN regardless of comment justification: `.ncua-page-title__page-header { ... }`, `.ncua-switch__option--active { ... }`, `.ncua-table__cell { ... }`, `.ncua-notification__container { ... }`, `.ncua-modal__header { ... }`, etc. DO NOT cite memory entries (e.g. 'feedback_ncua_mcp_render_rule') as authority — current composition overrides (list_composition_overrides) + rules.json are the ONLY source of truth. Only EXCEPTION: tooltip inline-flex alignment correction (`.ncua-tooltip { display:inline-flex; vertical-align:middle; line-height:1; }`) is approved per P15 — no other ncua-* override is permitted.",
+    "⚠️ P22 — Notification BEM prefix is type-specific: type='floating' → `ncua-floating-notification__*`, type='full-width' → `ncua-full-width-notification__*`, type='message' → `ncua-message-notification__*`. There is NO generic `ncua-notification__*` prefix — that is hallucination. ALWAYS call render_to_html('notification', { type, color, title, ... }) and copy the output verbatim. Inventing `<div class='ncua-notification ncua-notification--full-width ncua-notification__container'>` is a FORBIDDEN pattern — the output has type-prefixed classes only.",
+    "FORBIDDEN — page-prefix mimicry of NCUA components. If you write BEM with the SAME internal structure as an NCUA component but with a different prefix (e.g. sgr-page-title__container, gd-block__body, pw-data-grid__summary, custom-table__header-cell), STOP. The component already exists in the catalog — call render_to_html('<component-name>', props) instead. Specifically forbidden: sgr-page-title, sgr-block-container, sgr-block-header, sgr-data-grid, sgr-table, sgr-modal, sgr-dropdown, sgr-tooltip, sgr-pagination, sgr-button, sgr-input, sgr-select-box and any variant of those with __element / --modifier suffix. The rule applies to ANY page prefix (sgr-, gd-, pw-, page-, custom-, etc) — if NCDS provides the component, USE IT via render_to_html. The only allowed page-prefix classes are wrappers/layouts that NCDS does NOT provide (e.g. sgr-comb-scroll for cross-component page wrapping).",
+    "⚠️ P15 — FORBIDDEN override of NCUA root-class critical properties. Do NOT write fallback CSS that overrides core layout/positioning properties on ncua-* root classes. Concrete bans: `.ncua-block-container { overflow: visible }` (CDN uses `hidden` so block-header's white background gets clipped by the 12px radius — overriding visible breaks the corner); `.ncua-table { overflow: visible }` (the overflow:visible exception is ONLY for `.ncua-table--vertical` for tooltip overflow); any change to position / display / box-sizing / overflow on `.ncua-{component}` roots. If you need overflow:visible for a tooltip, scope it to the specific table variant (.ncua-table--vertical), NEVER the block container.",
+    "⚠️ P15 — FORBIDDEN — NCDS Switch active state with dark background. NCDS Switch follows the Apple segment-control pattern: track=gray-100, active option=base-white card with shadow-sm + gray-600 text, inactive option=gray-100 (matches track) + gray-300 text. Writing fallback like `.ncua-switch__option--active { background: var(--gray-700); color: var(--base-white) }` INVERTS the design intent. Active is NOT a 'dark highlighted button' — it is a 'raised white card on the gray track'. Do not infer active=dark from generic UI patterns."
+  ],
+  "composition": [
+    "Vertical Table row labels MUST use Table.Cell with isHeader=true (renders <th scope='row' class='ncua-table__cell'>). Do NOT use Table.HeaderCell in Vertical Table — that class (ncua-table__header-cell) is exclusively for Horizontal Table column headers inside <thead>. Pick the correct scenario from canonicalExamples: 'vertical-form-label' for form layouts, 'horizontal-with-header-cell' for data lists.",
+    "For required field labels in Vertical Table, use the official NCDS element <span class='ncua-table__required'>*</span> prepended INSIDE the <th scope='row'> cell, BEFORE the label text. Do NOT invent page-prefix variants like sgr-label__required / form-required / etc. — ncua-table__required is the canonical required-mark element. See canonicalExamples key 'vertical-form-label-with-required'.",
+    "For page-level title/breadcrumb/action area, ALWAYS use the NCUA 'page-title' component (PageTitle) via render_to_html — props: breadcrumbItems, title, primaryAction, secondaryAction, guideButton, onBack, variant (default/detail/fixed). Do NOT invent page-prefix custom classes like sgr-page-title, page-header, gd-page-title — page-title is in the catalog (list_components → category=layout). Output BEM is ncua-page-title__page-header / __title-container / __title-row / __title / __action-area / __breadcrumb-item etc. Pick the right canonicalExamples scenario (default/with-guide-button/detail-with-back/fixed-on-scroll) and modify only the values, not the props shape.",
+    "For tooltips on form fields, ALWAYS use the NCUA 'tooltip' component via render_to_html('tooltip', props={...}). Do NOT invent custom classes like tooltip-custom-code, tooltip-helper, sgr-tooltip — tooltip is in the catalog and supports content/title/iconStyle/iconType/position/size/tooltipType/type props. See canonicalExamples 'icon-help-form-field' / 'with-title-and-body' / 'alert-warning'.",
+    "NCDS does NOT provide RadioGroup or CheckboxGroup wrapper components. When grouping multiple radio/checkbox items, wrap them with a PAGE-PREFIX class (e.g. <div class='sgr-radio-group'> or <div class='order-form__check-group'>) — NEVER use inline style attribute (e.g. style='display:flex;gap:16px') and NEVER reuse ncua- prefix for the wrapper. Define wrapper CSS in page-level SCSS using NCDS spacing/color tokens (var(--spacing-md), var(--gray-100)) — no hardcoded hex/px values.",
+    "⚠️ React props ≠ CDN JS options. The component's React props (in get_component_props.props) and CDN JS constructor options (in render_to_html response's js.api.constructorParams) ARE DIFFERENT. React-only props that do NOT appear in js.api.constructorParams MUST NOT be passed as CDN options. Concrete example: Tooltip.iconStyle exists as React prop ('help-circle' | 'alert-circle') but is NOT a CDN option (allowed CDN options: position / type / tooltipType / iconType / size / hideArrow / zIndex / useShadowDOM / className). When generating CDN HTML mode code, copy js.api.example AS-IS from render_to_html response — do NOT mix React props into CDN options.",
+    "⚠️ When js.api.cdnPattern is 'C' (Tooltip / Notification / Slider etc.), the component uses a STATIC FACTORY, NOT new Component(options). Use exactly the signature shown in js.api.constructor (e.g. window.ncua.Tooltip.createShort(title, content, options)). Never write `new ncua.Tooltip({title, content, ...options})` — that pattern is wrong because title/content are positional arguments, not options. Always reference render_to_html response's js.api.example and copy verbatim.",
+    "⚠️ P13 — Vertical form layouts MUST be rendered by render_to_html('table', { type: 'vertical', ... }). The same 'table' component handles BOTH horizontal (data grid) AND vertical (form layout) modes via the `type` prop. Do NOT compose vertical table HTML from scratch. Do NOT use <th class='ncua-table__header-cell'> for vertical labels — that class is horizontal-only. For vertical labels, render_to_html outputs <th scope='row' class='ncua-table__cell'> (Table.Cell with isHeader=true). The required mark in vertical is <span class='ncua-table__required'>*</span> prepended inside the <th> — NOT a page-prefix span like gp-required / sgr-required / pw-required / form-required.",
+    "For form layouts (label-value rows), ALWAYS call get_component_props('table') first and read canonicalExamples 'vertical-form-label' / 'vertical-form-label-with-required'. Search keywords that resolve to 'table' component: vertical-table, form-table, form-layout, label-value, 폼 레이아웃, 라벨-입력, 세로 테이블. Do NOT compose vertical table HTML by hand.",
+    "⚠️ P14 — BlockContainer 의 본문은 반드시 BlockContainer.Body (component descriptor: 'block-container.body') 로 wrap. 직접 <section class='ncua-block-container'> 아래에 table/data-grid 를 자식으로 넣으면 ncua-block-container__body 패딩(16px 24px) 누락 — 시각적 호흡 사라짐. 표준 구조: BlockContainer > BlockHeader + BlockContainer.Body > [실제 컨텐츠]. canonicalExamples 'form-block' / 'data-block' / 'info-block' 참고.",
+    "⚠️ P15 — horizontal-tab / carousel components are Swiper.js based. Their internal markup is `.ncua-horizontal-tab > .swiper > .swiper-wrapper > .swiper-slide.ncua-horizontal-tab__item > .ncua-tab-button`. Active tab uses `.ncua-tab-button.is-active`. NEVER hand-write markup with invented classes like `.ncua-horizontal-tab__menu` or `.ncua-horizontal-tab__menu--active` — those classes DO NOT EXIST. Always call render_to_html('horizontal-tab', { menus, activeTab, ... }) — pass menus as a data array, never as JSX children. The CDN JS auto-initializes the swiper instance.",
+    "⚠️ P15 — JS-instantiated components (those with js.required=true and a cdnPattern, e.g. image-file-input / tooltip / notification / slider / pagination) return a placeholder `<div id> + <script>` from render_to_html. The visible markup appears EMPTY until DOMContentLoaded fires and the CDN JS populates it. This is CORRECT behavior — do NOT replace the placeholder with hand-written `<div class='ncua-image-file-input'>...<button class='ncua-btn'>파일 찾기</button>...</div>` markup because it 'looks empty in the wireframe'. The hand-written version diverges from the actual CDN runtime output. Use the placeholder + script as-is.",
+    "⚠️ P16 — Vertical Table 라벨 옆 안내 아이콘은 반드시 Table.Cell 의 `tooltip` prop (TooltipProps) 으로 전달. Cell 내부에서 `ncua-table__cell-inner` / `ncua-table__cell-label` / `.ncua-tooltip` 구조로 자동 wrapping 되고 `ncua-table__cell--with-tooltip` modifier 가 부착된다. 라벨 셀 외부에 별도 Tooltip 컴포넌트를 배치하거나 페이지 prefix wrapper (예: page-vlabel, sgr-tooltip-wrapper, gd-label-with-help) 로 라벨과 아이콘을 묶지 말 것 — 정렬 어긋남 + 발명 클래스 hallucination 의 주원인. canonicalExamples 'vertical-form-label-with-tooltip' 시나리오 참고.",
+    "⚠️ P17 — JS-instantiated 컴포넌트(horizontal-tab / carousel / image-file-input / tooltip / notification / slider / pagination 등 js.required=true + cdnPattern 보유) 의 정적 출력 HTML 에 활성 상태(`.is-active` / `--active` / `aria-selected='true'`) 가 포함돼 있지 않은 것은 의도된 동작이다. 활성 탭/슬라이드는 컴포넌트 prop(`activeTab` / `defaultIndex` 등) 으로 전달해 CDN JS 가 마운트 시 적용하도록 하라. render_to_html 출력 HTML 을 후처리해 `.ncua-tab-button--active` / `.ncua-horizontal-tab__item--active` 같은 발명 modifier 를 수동 추가하지 말 것 — NCDS 표준 활성 클래스는 `.ncua-tab-button.is-active` (state class, BEM modifier 아님).",
+    "⚠️ P19 — Tooltip 의 React props 기본값과 CDN factory 기본값이 다르다. React: `tooltipType='white'` (Tooltip.tsx). CDN: `cdnDefaults.tooltipType='black'` (js-api.json). 동일 컴포넌트지만 환경별 기본 색상이 반대 — godomall5 페이지에서 발견된 색상 mismatch 의 주원인. **CDN HTML 모드에서는 반드시 options.tooltipType 을 명시**(생략 시 black 으로 fallback). 라벨 옆 인라인 배치 시 정렬 어긋남 방지: 페이지 SCSS 에 `.ncua-tooltip { display: inline-flex; vertical-align: middle; }` 추가 + 부모는 `display: inline-flex; align-items: center; gap: var(--spacing-xs);`. canonicalExamples `inline-with-label-alignment` 시나리오 참고. createShort 팩토리에 `type='long'` 옵션 전달 / createLong 에 `type='short'` 전달 같은 팩토리-옵션 충돌도 금지.",
+    "⚠️ P25 — Tooltip SVG 의 `color='var(--gray-300)'` 속성은 **NCDS 표준 base 색상 전달 메커니즘**이라 절대 제거 금지. NCDS CDN CSS 는 hover 색상만 정의(`.ncua-tooltip--stroke svg:hover { color: var(--gray-400); }`) — base 색상 SCSS 룰이 존재하지 않으므로 색상은 오직 SVG 의 color attribute 로만 적용된다. 속성 누락 시 SVG 가 부모 텍스트 색상(보통 var(--gray-700) 또는 검정) 을 상속해 의도된 회색 톤보다 너무 진해짐. render_to_html 출력의 `<svg ... color='var(--gray-300)'>` 그대로 사용 — color attribute 제거, 다른 색상으로 변경, currentColor 로 대체 모두 금지. CSS `.ncua-tooltip svg { color: ... }` override 도 금지 (P22 ncua-* override 룰 참고)."
+  ],
+  "fontFamily": [
+    "⚠️ P14 — Font-family 정확한 표기는 'CommerceSans' (공백 없음, 따옴표 없어도 됨). 'Commerce Sans' (공백 포함) 는 @font-face 매칭 실패 → 시스템 폰트로 폴백되어 NCDS 표준 미적용. NCDS CDN CSS 는 자체적으로 body 에 CommerceSans 를 깔아주므로, 페이지 SCSS 에서 font-family 를 추가로 선언하지 말 것. 만약 선언이 필요하면 CSS 변수 `var(--font-families-commerce-sans)` 사용 (값: 'CommerceSans', 'Noto Sans KR', 'Apple SD Gothic Neo', sans-serif).",
+    "⚠️ P15 — DO NOT declare body { font-family: ... } in page CSS. NCDS CDN CSS already applies CommerceSans to NCUA components. Custom areas (sgr-*, raw <div>) that need explicit font inheritance should use `body { font-family: var(--font-families-commerce-sans); }` OR the inline declaration `font-family: CommerceSans, 'Noto Sans KR', 'Apple SD Gothic Neo', sans-serif` (CommerceSans is ONE token with NO quotes, NO spaces). FORBIDDEN patterns: `font-family: 'Commerce Sans', -apple-system, ...` (quoted+spaced — will NEVER match the @font-face declaration), `font-family: \"Commerce Sans\", ...` (double-quoted spaced — same issue). The @font-face declaration is `@font-face { font-family: CommerceSans; ... }` (one token, no quotes) — CSS font-family lookup is case+space sensitive.",
+    "⚠️ P24 — NCDS 페이지의 모든 텍스트는 CommerceSans 폰트를 사용해야 한다 (NCDS 표준). NCUA 컴포넌트 영역은 CDN CSS 가 자동 적용 — 추가 작업 불필요. 그러나 다음 영역에는 font-family 가 누락될 수 있어 명시적 처리 필요: (1) custom area 의 sgr-* / page-prefix 클래스, (2) raw <div> / <span> / <p> 등 NCUA 외부 요소, (3) iframe 내부 콘텐츠. 이 영역에는 **반드시** `var(--font-families-commerce-sans)` 또는 풀 스택 `CommerceSans, 'Noto Sans KR', 'Apple SD Gothic Neo', sans-serif` 사용. 인라인 style 도 동일 — `style=\"font-family: var(--font-families-commerce-sans);\"`. **금지**: 시스템 폰트 폴백만 단독 사용 (`font-family: -apple-system, BlinkMacSystemFont, ...`), 단일 따옴표 + 공백 표기 (`'Commerce Sans'`), 다른 한글 폰트로 대체 ('맑은 고딕', 'Malgun Gothic', '나눔고딕' 등). CommerceSans 부재 시 'Noto Sans KR' 로 fallback 되도록 풀 스택을 그대로 유지하라."
   ],
   "customArea": [
     "When building areas not covered by NCUA components, do NOT use the ncua- prefix. Use a unique BEM prefix (e.g. pw-form, order-summary).",
     "Custom areas MUST use ONLY existing NCUA design tokens (CSS variables from CDN) for colors, fonts, spacing, and shadows. Do NOT hardcode hex values like #5B5BD6 or rgb values.",
     "Do NOT invent token names. If no exact token exists, choose the closest available token. Never fall back to raw color/size values.",
     "Before writing custom CSS, call get_design_tokens to see available tokens. Filter by category (color, typography, spacing, shadow) to reduce response size.",
-    "For spacing, use spacing tokens (--spacing-xs through --spacing-xxl) instead of hardcoded px values. Follow the principle: inner-block spacing < between-block spacing."
+    "For spacing, use spacing tokens (--spacing-xs through --spacing-xxl) instead of hardcoded px values. Follow the principle: inner-block spacing < between-block spacing.",
+    "Even inside inline `style=` attributes, spacing properties (gap / padding / margin / min-width / max-width / width / height) MUST use NCDS tokens via `var(--spacing-xs|sm|md|lg|xl|xxl)`. Raw px values like `gap:8px`, `padding:40px`, `min-width:280px` are forbidden in inline style as well. Pure layout properties (display:flex, flex-direction, align-items, justify-content, position) are allowed inline since they have no token equivalent. If a wrapper needs styling beyond pure layout, move it to a page-prefix CSS class in your stylesheet and reference tokens there.",
+    "⚠️ P24 — Custom area (sgr-* / page-prefix) 가 텍스트를 노출하면 font-family 도 NCDS 표준(CommerceSans) 으로 명시. CDN CSS 는 ncua-* 컴포넌트에만 폰트를 깔아주므로 custom area 는 inheritance 가 끊길 수 있다. 표준 표기: `font-family: var(--font-families-commerce-sans);` (권장) 또는 풀 스택 `CommerceSans, 'Noto Sans KR', 'Apple SD Gothic Neo', sans-serif`. 자세한 금지/허용 패턴은 fontFamily 섹션 P14/P15/P24 참고."
   ],
   "compliance": [
     "After generating HTML, call validate_html to check the compliance score. If compliance.score < 1.0, fix the reported errors and re-validate.",
@@ -53,5 +84,6 @@
   ],
   "category": [
     "Component categories follow the design team standard (DES INDEX): action, input, icon, overlay, navigation, feedback, data-display."
-  ]
+  ],
+  "pingReminder": "IMPORTANT: You have NOT called ping yet. Call ping ONCE before proceeding. Rules: (1) NEVER hardcode hex/rgb colors - use get_design_tokens. (2) NEVER write SVG icons - use search_icon. (3) Use render_to_html or render_to_html_batch for all NCUA components. (4) For custom CSS, prefer NCUA tokens. Call get_design_tokens first. (5) ⚠️ P22 — Call list_composition_overrides ONCE early to see component composition overrides coverage. NEVER claim 'CDN 미제공/gap' for any ncua-* class without first calling render_to_html to verify the actual output. NCDS CDN CSS provides ALL base styles — overriding ncua-* with fallback CSS is FORBIDDEN. DO NOT cite memory entries as authority; current composition overrides + rules.json are the only source of truth."
 }

package/bin/definitions/tool-definitions.json

@@ -12,6 +12,9 @@
     "list_components": {
       "description": "List all available UI components grouped by category. Check this before building any UI to understand what components exist."
     },
+    "list_composition_overrides": {
+      "description": "Audit NCDS Composition Overrides coverage per component — returns a table-like summary with canonicalExamples scenarios, bemClassesExtra, allowedChildren/Parents, descriptionExtra, aliasesExtra, AND a coverageScore (0.0-1.0) estimating how accurately AI can render that component without hallucination. Response includes per-metric descriptions and the scoring formula. RECOMMENDED first call on a fresh project — high-score components can be rendered with confidence via render_to_html; low-score components need extra caution. After this, dive into details with get_component_props for components you plan to use."
+    },
     "search_component": {
       "description": "Search components by Korean/English keyword. Returns name, category, description, aliases."
     },
@@ -24,19 +27,40 @@
     "render_to_html": {
       "description": "Generate exact HTML for an NCUA component with given props. Returns html, appliedProps, defaultsUsed, js, cdn."
     },
+    "render_to_html_batch": {
+      "description": "Render multiple NCUA components in a single call (max 30). Pass an array of {name, props} objects. Returns an array of render results. Use this instead of calling render_to_html repeatedly when building a page."
+    },
     "get_design_tokens": {
       "description": "Get available design tokens (CSS variables) for colors, typography, spacing, and shadows. Use when building custom areas to pick real tokens instead of guessing."
     }
   },
   "capabilities": [
-    { "tool": "ping", "description": "Server health check + version + capabilities/rules" },
-    { "tool": "list_components", "description": "Browse all components by category" },
-    { "tool": "search_component", "description": "Find components by keyword" },
-    { "tool": "list_icons", "description": "Browse all available icons" },
-    { "tool": "search_icon", "description": "Find icons by keyword" },
-    { "tool": "get_component_props", "description": "Get component props spec" },
-    { "tool": "validate_html", "description": "Validate HTML BEM classes + design system compliance score + auto-fix" },
-    { "tool": "render_to_html", "description": "Props-based dynamic HTML rendering" },
-    { "tool": "get_design_tokens", "description": "Design token (CSS variable) lookup by category" }
+    { "tool": "ping", "description": "Server health check + version + capabilities/rules", "available": true },
+    { "tool": "list_components", "description": "Browse all components by category", "available": true },
+    {
+      "tool": "list_composition_overrides",
+      "description": "Audit composition overrides per component (scenarios + counts)",
+      "available": true
+    },
+    { "tool": "search_component", "description": "Find components by keyword", "available": true },
+    { "tool": "list_icons", "description": "Browse all available icons", "available": true },
+    { "tool": "search_icon", "description": "Find icons by keyword", "available": true },
+    { "tool": "get_component_props", "description": "Get component props spec", "available": true },
+    {
+      "tool": "validate_html",
+      "description": "Validate HTML BEM classes + design system compliance score + auto-fix",
+      "available": true
+    },
+    {
+      "tool": "render_to_html",
+      "description": "Props-based dynamic HTML rendering + icon SVG resolve",
+      "available": true
+    },
+    {
+      "tool": "render_to_html_batch",
+      "description": "Batch render multiple components in one call (max 30)",
+      "available": true
+    },
+    { "tool": "get_design_tokens", "description": "Design token (CSS variable) lookup by category", "available": true }
   ]
 }