{ "name": "@axe/ui", "version": "v0.22.0", "origin": "https://design.axelabs.ai", "schema": "ComponentDoc (src/lib/docs-schema.ts)", "delivery": { "react": { "root": "@axe/ui", "server": "@axe/ui/server", "format": "ESM JS + TypeScript declarations", "status": "private-unpublished" }, "serverRendered": { "command": "axe-ui-export --config axe-ui.consumer.json", "check": "axe-ui-export --config axe-ui.consumer.json --check", "lock": "axe-ui.lock.json (@axe/ui/consumer-lock@1)" } }, "count": 75, "groups": [ { "key": "layout", "label": "레이아웃" }, { "key": "navigation", "label": "내비게이션" }, { "key": "action", "label": "액션" }, { "key": "input", "label": "입력" }, { "key": "container", "label": "컨테이너" }, { "key": "content", "label": "콘텐츠" }, { "key": "overlay", "label": "오버레이" }, { "key": "feedback", "label": "피드백" }, { "key": "data", "label": "데이터" }, { "key": "chat", "label": "채팅 · AI" }, { "key": "utility", "label": "유틸리티" } ], "components": [ { "name": "Accordion", "slug": "accordion", "group": "container", "summary": "collapsible disclosure 스택(single/multiple).", "description": "Radix Accordion 위에 .axe-accordion__* 스타일을 얹은 접이식 항목 스택이다. type=\"single\"(한 번에 하나) 과 type=\"multiple\"(동시 여러 개) 을 모두 지원하며 FAQ, 설정 그룹, 긴 폼의 섹션 접기 등에 쓴다. 각 트리거는 heading 안 버튼으로 렌더되고 chevron 이 자동으로 붙는다. 부드러운 height 접기는 Radix 가 노출하는 --radix-accordion-content-height 변수를 @keyframes 로 잡아 처리한다(하나의 영역만 접는 경량 패턴은 Collapsible).", "keywords": [ "accordion", "아코디언", "disclosure", "faq", "접기", "collapsible", "single", "multiple", "섹션", "radix" ], "props": [ { "name": "Accordion.type", "type": "\"single\" | \"multiple\"", "required": true, "description": "single = 한 번에 하나만 열림, multiple = 동시 여러 개." }, { "name": "Accordion.collapsible", "type": "boolean", "description": "type=\"single\" 에서 열린 항목을 다시 눌러 전부 닫기 허용." }, { "name": "Accordion.defaultValue", "type": "string | string[]", "description": "uncontrolled 초기 열림 value(single=string, multiple=string[])." }, { "name": "Accordion.value", "type": "string | string[]", "description": "controlled 열림 value." }, { "name": "Accordion.onValueChange", "type": "(value: string | string[]) => void", "description": "열림 value 변경 콜백." }, { "name": "Accordion.…rest", "type": "React.ComponentPropsWithoutRef", "description": "Accordion 은 Radix Root 를 그대로 재노출(axe 클래스 없음) — className 등은 Root 로 직접 전파." }, { "name": "AccordionItem.value", "type": "string", "required": true, "description": "항목 식별 value(열림 상태 매핑 키)." }, { "name": "AccordionItem.…rest", "type": "React.ComponentPropsWithoutRef", "description": "className 은 axe-accordion__item 과 병합, 나머지는 Radix Item 으로 전파." }, { "name": "AccordionTrigger.…rest", "type": "React.ComponentPropsWithoutRef", "description": "children=제목/질문. .axe-accordion__header 안에 렌더되고 chevron 자동. 나머지는 Radix Trigger 로 전파." }, { "name": "AccordionContent.…rest", "type": "React.ComponentPropsWithoutRef", "description": "children 은 .axe-accordion__content-inner 로 감싸 렌더. 나머지는 Radix Content 로 전파." } ], "cssClasses": [ { "className": "axe-accordion__item", "purpose": "각 항목 래퍼 — 하단 border-subtle(마지막 항목 제외).", "stability": "stable" }, { "className": "axe-accordion__header", "purpose": "트리거를 감싸는 heading 래퍼(margin 0, flex).", "stability": "stable" }, { "className": "axe-accordion__trigger", "purpose": "트리거 버튼(전폭, label+chevron, hover/focus 트림).", "stability": "stable" }, { "className": "axe-accordion__trigger-label", "purpose": "트리거 라벨 span(flex:1).", "stability": "stable" }, { "className": "axe-accordion__chevron", "purpose": "chevron SVG — [data-state=open] 시 90deg 회전.", "stability": "stable" }, { "className": "axe-accordion__content", "purpose": "접히는 영역(overflow hidden). data-state open/closed 에 --radix-accordion-content-height 애니메이션.", "stability": "stable" }, { "className": "axe-accordion__content-inner", "purpose": "content 내부 padding 래퍼.", "stability": "stable" } ], "a11y": { "keyboard": [ "↑/↓ — 트리거 간 이동(roving tabindex)", "Home/End — 첫/마지막 트리거로", "Enter/Space — 항목 열기/접기" ], "aria": "각 트리거는 heading(.axe-accordion__header) 안 버튼으로, aria-expanded + aria-controls 를 가지며 컨텐츠는 연결된 region 이다. 화살표 네비/포커스 관리는 Radix 가 제공. chevron 은 aria-hidden 장식.", "notes": "smooth height 는 --radix-accordion-content-height 를 @keyframes from/to 로 잡아 처리하고 prefers-reduced-motion 시 즉시 토글한다. Accordion 루트는 axe 클래스 없이 Radix Root 그대로(레이아웃 중립) — 컨테이너 스타일이 필요하면 className 을 직접 부여한다." }, "examples": [ { "title": "single (FAQ)", "lang": "tsx", "code": "import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from \"@axe/ui\";\n\n\n \n 배포는 어떻게 하나요?\n axe ship <svc> 로 합니다.\n \n \n 롤백은?\n blue/green 전환으로…\n \n" }, { "title": "multiple", "lang": "tsx", "code": "import { Accordion, AccordionItem, AccordionTrigger, AccordionContent } from \"@axe/ui\";\n\n\n A…\n B…\n C…\n" }, { "title": "CSS-only (정적 open 항목)", "lang": "html", "code": "
\n

\n \n

\n
\n
axe ship <svc> 로 합니다.
\n
\n
" } ], "bestPractices": { "do": [ "AccordionItem.value 는 유일하게 — 열림 상태가 이 키로 매핑된다.", "한 번에 하나만 펼치는 게 자연스러우면 type=\"single\" + collapsible." ], "dont": [ "단일 영역 하나만 접는 데 Accordion 을 쓰지 말 것(그건 Collapsible).", "AccordionTrigger 안에 인터랙티브 요소(버튼/링크)를 중첩하지 말 것(포커스 충돌)." ] }, "consumeCss": "정적 open/closed 는 트리거·컨텐츠에 data-state=\"open|closed\" 를 직접 부여하면 .axe-accordion__* 스타일로 재현된다(chevron 회전 포함). 단 부드러운 height 애니메이션은 Radix 가 --radix-accordion-content-height 를 런타임 측정해 주입하므로 CSS-only 로는 즉시 토글만. 화살표 키 네비도 JS(Radix) 몫이다.", "url": "https://design.axelabs.ai/components/accordion" }, { "name": "AgentExecutor", "slug": "agent-executor", "group": "chat", "summary": "Phase 8 AI-first 컴포지트 — 채팅 셸(AgentExecutor) + 점진 테이블(StreamingTable) + 멀티모달 입력(MultiModalChatInput).", "description": "Phase 1-7 primitive(ChatInput / MessageBubble / StreamingMarkdown / ToolCallCard / Spinner / Button) 위에 얹는 high-level 조합 3종을 한 모듈로 export 한다. AgentExecutor 는 controlled 채팅 셸(messages 는 부모 보유, onSubmit 으로 새 사용자 메시지)이며 assistant 메시지는 StreamingMarkdown, 인라인 tool 은 ToolCallCard 로 렌더하고 sticky-bottom 자동 스크롤을 한다. StreamingTable 은 row 를 하나씩 append 하는 제너릭 테이블(진행 bar·pending spinner 행), MultiModalChatInput 은 ChatInput 을 첨부(drag/drop·paste·file picker)로 확장한 입력이다. 셋 다 barrel 최상위에서 직접 export 된다.", "keywords": [ "agent", "에이전트", "agent executor", "chat shell", "streaming table", "multimodal", "멀티모달", "첨부", "attachment", "drag drop", "tool call", "composite", "phase 8" ], "props": [ { "name": "messages", "type": "ChatMessage[]", "required": true, "description": "AgentExecutor: 렌더할 메시지 배열. ChatMessage = { id, role, content, tools?, attachments? }." }, { "name": "onSubmit", "type": "(text: string, attachments?: File[]) => void", "required": true, "description": "AgentExecutor: 사용자 제출 콜백. attachments 는 inputSlot 으로 MultiModalChatInput 을 쓸 때만." }, { "name": "onCancel", "type": "() => void", "description": "AgentExecutor: 주어지면 streaming=true 일 때 streaming-hint 에 '취소' 버튼 노출." }, { "name": "streaming", "type": "boolean", "defaultValue": "false", "description": "AgentExecutor: 마지막 assistant 메시지 끝 cursor + 하단 '응답 생성 중…' hint." }, { "name": "tools", "type": "ToolCallEvent[]", "description": "AgentExecutor: 메시지에 속하지 않는 free-floating tool 카드(보통 message.tools 권장)." }, { "name": "placeholder", "type": "string", "description": "AgentExecutor: 기본 ChatInput 의 placeholder(inputSlot 미사용 시)." }, { "name": "disabled", "type": "boolean", "description": "AgentExecutor: 기본 ChatInput 비활성(보통 streaming 중 true)." }, { "name": "inputRef", "type": "React.Ref", "description": "AgentExecutor: 기본 ChatInput 의 외부 ref(focus/clear)." }, { "name": "inputSlot", "type": "React.ReactNode", "description": "AgentExecutor: 입력 자리에 넣을 커스텀 노드 — 지정 시 기본 ChatInput 대체(예: MultiModalChatInput)." }, { "name": "ref → AgentExecutorHandle", "type": "{ focus(): void; scrollToBottom(): void }", "description": "AgentExecutor: imperative 핸들 — 입력 focus·강제 맨아래 스크롤." }, { "name": "StreamingTable.columns", "type": "StreamingTableColumn[]", "required": true, "description": "StreamingTable: 열 정의. { key, header, render?, align?('left'|'right'|'center'), width? }." }, { "name": "StreamingTable.rows", "type": "R[]", "required": true, "description": "StreamingTable: 현재까지의 행(추가되면 페이드인)." }, { "name": "StreamingTable.getRowKey", "type": "(row: R, idx: number) => string", "required": true, "description": "StreamingTable: 안정적 row key." }, { "name": "StreamingTable.streaming", "type": "boolean", "defaultValue": "false", "description": "StreamingTable: 마지막에 spinner pending 행 노출(다음 행 대기)." }, { "name": "StreamingTable.expectedRowCount", "type": "number", "description": "StreamingTable: 총 행 수를 알면 상단 progress bar(0..100%)." }, { "name": "StreamingTable.emptyLabel", "type": "React.ReactNode", "defaultValue": "\"—\"", "description": "StreamingTable: 행 0 & 비스트리밍 시 placeholder." }, { "name": "MultiModalChatInput.onSubmit", "type": "(text: string, attachments: File[]) => void", "description": "MultiModalChatInput: 텍스트+첨부 제출(ChatInput 과 다른 시그니처 — 그래서 별도 컴포넌트)." }, { "name": "MultiModalChatInput.accept", "type": "string", "description": "MultiModalChatInput: accept 패턴(예 'image/*,application/pdf'). '.pdf'/'image/*'/'application/pdf' 모두 매칭." }, { "name": "MultiModalChatInput.maxFiles", "type": "number", "defaultValue": "5", "description": "MultiModalChatInput: 최대 첨부 개수(초과 시 onReject('count')). " }, { "name": "MultiModalChatInput.maxSizeBytes", "type": "number", "defaultValue": "20 * 1024 * 1024", "description": "MultiModalChatInput: 파일당 최대 크기(초과 시 onReject('size'))." }, { "name": "MultiModalChatInput.onReject", "type": "(reason: \"count\" | \"size\" | \"type\", file: File) => void", "description": "MultiModalChatInput: 거부 콜백(toast 등)." }, { "name": "MultiModalChatInput.toolbarLeft / toolbarRight / hint", "type": "React.ReactNode", "description": "MultiModalChatInput: 툴바 슬롯·힌트(hint 기본 '↵ 보내기 · ⇧↵ 줄바꿈 · 끌어 놓기 / 붙여넣기로 첨부')." }, { "name": "MultiModalChatInput.ref → ChatInputHandle", "type": "{ focus(): void; clear(): void }", "description": "MultiModalChatInput: imperative 핸들(clear 는 텍스트+첨부 모두 비움)." } ], "cssClasses": [ { "className": "axe-agent-executor", "purpose": "AgentExecutor 루트(세로 flex, 높이 100%, 테두리 카드).", "stability": "stable" }, { "className": "axe-agent-executor__scroll", "purpose": "메시지 스크롤 영역(reduced-motion 시 smooth 해제).", "stability": "stable" }, { "className": "axe-agent-executor__empty", "purpose": "messages 0 일 때 '대화를 시작하세요' 빈 상태.", "stability": "stable" }, { "className": "axe-agent-executor__user-content", "purpose": "사용자 메시지 본문(pre-wrap).", "stability": "stable" }, { "className": "axe-agent-executor__tools", "purpose": "메시지 내부 ToolCallCard 목록 래퍼. --free 변형 = free-floating tools.", "stability": "stable" }, { "className": "axe-agent-executor__attachments", "purpose": "사용자 메시지의 첨부 chip 행.", "stability": "stable" }, { "className": "axe-agent-executor__streaming-hint", "purpose": "하단 '응답 생성 중…' 상태 바(Spinner + 선택 취소 버튼).", "stability": "stable" }, { "className": "axe-agent-executor__input", "purpose": "입력 도크(상단 구분선, ChatInput 또는 inputSlot).", "stability": "stable" }, { "className": "axe-chat-input--dragover", "purpose": "MultiModal: drag-over 하이라이트(accent 테두리·ring).", "stability": "stable" }, { "className": "axe-chat-input--disabled", "purpose": "MultiModal: 비활성(opacity·pointer-events none).", "stability": "stable" }, { "className": "axe-chat-input__drop-overlay", "purpose": "MultiModal: '끌어 놓아 첨부' 드롭 오버레이(aria-hidden).", "stability": "stable" }, { "className": "axe-attach-list", "purpose": "첨부 chip 목록(입력 위).", "stability": "stable" }, { "className": "axe-attach-chip", "purpose": "첨부 chip. __thumb(이미지 썸네일)/__icon(비이미지)/__name/__size/__remove 파트. --compact = AgentExecutor 사용자 메시지용 mini.", "stability": "stable" }, { "className": "axe-attach-button", "purpose": "'📎 첨부' 파일 피커 버튼(maxFiles 도달 시 disabled).", "stability": "stable" }, { "className": "axe-attach-file-input", "purpose": "숨긴 (display:none).", "stability": "internal" }, { "className": "axe-streaming-table", "purpose": "StreamingTable 루트(elevated 카드). data-streaming 속성.", "stability": "stable" }, { "className": "axe-streaming-table__progress", "purpose": "상단 progress 트랙. __progress-bar 는 --axe-progress(0..1) scaleX 로 채움.", "stability": "stable" }, { "className": "axe-streaming-table__scroll", "purpose": "가로 스크롤 래퍼(min-width 480px 테이블).", "stability": "stable" }, { "className": "axe-streaming-table__table", "purpose": "테이블 본체().", "stability": "stable" }, { "className": "axe-streaming-table__th", "purpose": "헤더 셀. --right/--center 정렬 변형.", "stability": "stable" }, { "className": "axe-streaming-table__td", "purpose": "데이터 셀(tabular-nums). --right/--center 정렬 변형.", "stability": "stable" }, { "className": "axe-streaming-table__tr--in", "purpose": "새 행 페이드인(axe-stream-row-in, reduced-motion 시 off).", "stability": "internal" }, { "className": "axe-streaming-table__pending", "purpose": "'다음 행 대기 중…' spinner 행(streaming 시).", "stability": "stable" }, { "className": "axe-streaming-table__empty", "purpose": "행 0 & 비스트리밍 시 emptyLabel 셀.", "stability": "stable" } ], "a11y": { "keyboard": [ "AgentExecutor: 기본 ChatInput 은 ↵ 보내기 · ⇧↵ 줄바꿈", "MultiModalChatInput: ↵ 보내기 · ⇧↵ 줄바꿈(IME 조합 중이면 submit 억제) · 붙여넣기/끌어 놓기로 첨부", "MultiModalChatInput: 각 chip 의 제거 버튼(aria-label \"<파일명> 제거\")로 삭제" ], "aria": "AgentExecutor 빈 상태는 aria-live=\"polite\", 하단 streaming-hint 는 role=\"status\" aria-live=\"polite\"(Spinner label=\"Streaming\")로 진행을 고지한다. StreamingTable 은 시맨틱
이고 pending 행이 aria-live=\"polite\" 로 '다음 행 대기 중' 을 알리지만, 상단 progress bar 는 aria-hidden 장식이라 수치 진행은 시각으로만 전달된다. MultiModalChatInput 의 파일 버튼은 aria-label=\"파일 첨부\"(maxFiles 도달 시 disabled), 드롭 오버레이는 aria-hidden 이다.", "notes": "AgentExecutor 의 자동 스크롤은 rAF 후 scrollTop 이동이며 사용자가 바닥에서 32px 이상 위로 스크롤하면 stick 해제된다(read 방해 없음). scroll-behavior 는 prefers-reduced-motion 에서 auto 로, StreamingTable 의 행 페이드인·progress transition 도 reduced-motion 에서 정지된다. MultiModal 의 dragenter/leave 는 중첩 카운팅으로 자식 위 호버 시 깜빡임을 막는다." }, "examples": [ { "title": "AgentExecutor — 기본 채팅 셸", "lang": "tsx", "code": "import { AgentExecutor, type ChatMessage } from \"@axe/ui\";\n\nconst [messages, setMessages] = useState([]);\n\n send(text)}\n/>" }, { "title": "AgentExecutor — 인라인 tool call + 멀티모달 입력", "lang": "tsx", "code": "import { AgentExecutor, MultiModalChatInput, type ChatMessage } from \"@axe/ui\";\n\nconst messages: ChatMessage[] = [\n {\n id: \"a1\",\n role: \"assistant\",\n content: \"장부를 조회했습니다.\",\n tools: [{ id: \"t1\", name: \"query_trial_balance\", status: \"success\", output: \"…\" }],\n },\n];\n\n send(text, files)}\n inputSlot={\n send(text, files)}\n onReject={(reason, f) => toast(`${f.name}: ${reason}`)}\n />\n }\n/>" }, { "title": "StreamingTable — 행 점진 append", "lang": "tsx", "code": "import { StreamingTable } from \"@axe/ui\";\n\n r.id}\n/>" }, { "title": "StreamingTable — CSS-only 정적 (비-React)", "lang": "html", "code": "
\n
\n
\n \n \n \n \n \n \n \n \n \n \n
종목IRR
A사18.4%
\n \n" } ], "bestPractices": { "do": [ "tool call 은 되도록 해당 message.tools 에 넣는다 — free-floating tools prop 은 pre-warm 등 예외용.", "streaming 중에는 disabled 로 기본 ChatInput 을 잠그거나 onCancel 을 제공해 4-state 를 완성한다.", "MultiModalChatInput 은 onSubmit 시그니처(text, files)가 ChatInput 과 다름을 인지하고 호출 측을 맞춘다." ], "dont": [ "messages 를 컴포넌트 내부에서 변형하려 하지 말 것 — controlled(부모 소유)다.", "StreamingTable 의 progress 를 스크린리더 진행 고지로 기대하지 말 것 — bar 는 aria-hidden 시각 전용.", "AgentExecutorHandle(focus/scrollToBottom)과 ChatInputHandle(focus/clear)을 혼동하지 말 것 — 서로 다른 ref." ] }, "consumeCss": "StreamingTable 은 시맨틱 마크업이라 서버 렌더(maud/jinja)로도 그대로 재현 가능하고, progress 는 __progress-bar 에 --axe-progress(0..1)만 주면 된다(구 inline width:% 도 하위호환). AgentExecutor·MultiModalChatInput 은 드래그·붙여넣기·자동 스크롤·첨부 상태가 모두 JS 이므로 CSS-only 로는 정적 셸/입력 스냅샷만 재현된다. 이 모듈 스타일(agent.css)은 아직 components.css 에 통합되지 않아 소비 측에서 명시적으로 import 해야 한다.", "url": "https://design.axelabs.ai/components/agent-executor" }, { "name": "AlertDialog", "slug": "alert-dialog", "group": "overlay", "summary": "되돌릴 수 없는 행동을 확인시키는 경고 모달 (Radix AlertDialog 기반).", "description": "Dialog 와 비주얼은 거의 같지만, 사용자가 Cancel 또는 Action 중 하나를 반드시 명시적으로 선택하게 만드는 확인 전용 모달이다. 닫기 X 가 없고 바깥 클릭으로도 닫히지 않으며(Esc 는 Cancel 과 동치), role=alertdialog 로 보조 기술에 '주의' 모달임을 알린다. AlertDialogAction 은 variant=\"danger\" 로 파괴적 확인(삭제·영구취소)에 맞춘 danger 버튼이 되고, AlertDialogCancel 은 ghost 버튼으로 렌더된다. Confirm 용도라 size 기본값이 sm 이며 full/xl 변형은 없다.", "keywords": [ "alert-dialog", "alertdialog", "확인", "confirm", "삭제", "destructive", "경고", "modal", "radix" ], "props": [ { "name": "open", "type": "boolean", "description": "열림 상태 (controlled). Radix AlertDialog.Root prop." }, { "name": "onOpenChange", "type": "(open: boolean) => void", "description": "열림/닫힘 전환 콜백 (Root)." }, { "name": "defaultOpen", "type": "boolean", "defaultValue": "false", "description": "uncontrolled 초기 열림 상태 (Root)." }, { "name": "size", "type": "\"sm\" | \"md\" | \"lg\"", "defaultValue": "\"sm\"", "description": "AlertDialogContent 의 max-width. sm=440 / md=560 / lg=720. Dialog 와 달리 xl/full 없음." }, { "name": "variant (AlertDialogAction)", "type": "\"primary\" | \"danger\"", "defaultValue": "\"primary\"", "description": "확인 버튼 톤. danger 면 axe-btn--danger 로 파괴적 확인에 맞춘 색을 입힌다." }, { "name": "...rest (AlertDialogContent)", "type": "React.ComponentPropsWithoutRef", "description": "onEscapeKeyDown 등 Radix Content props 를 전파." }, { "name": "...rest (Action/Cancel)", "type": "각 Radix AlertDialog.Action / .Cancel props", "description": "onClick·asChild 등 대응 Radix 파트 props 를 그대로 전파." } ], "cssClasses": [ { "className": "axe-alert-dialog__overlay", "purpose": "화면 전체 흐린 backdrop(z-modal).", "stability": "stable" }, { "className": "axe-alert-dialog__content", "purpose": "중앙 정렬 확인 카드 표면.", "stability": "stable" }, { "className": "axe-alert-dialog__content--sm", "purpose": "max-width 440px 변형(기본).", "stability": "stable" }, { "className": "axe-alert-dialog__content--md", "purpose": "max-width 560px 변형.", "stability": "stable" }, { "className": "axe-alert-dialog__content--lg", "purpose": "max-width 720px 변형.", "stability": "stable" }, { "className": "axe-alert-dialog__header", "purpose": "title+설명 스택(close X 없어 padding-right 0).", "stability": "stable" }, { "className": "axe-alert-dialog__title", "purpose": "제목(display 폰트·semibold).", "stability": "stable" }, { "className": "axe-alert-dialog__description", "purpose": "결과 설명 문단(secondary 톤).", "stability": "stable" }, { "className": "axe-alert-dialog__footer", "purpose": "우정렬 Cancel|Action 라인(상단 구분선).", "stability": "stable" }, { "className": "axe-alert-dialog__action", "purpose": "확인 버튼 보정(min-width·중앙정렬). axe-btn 위에 얹힘.", "stability": "stable" }, { "className": "axe-alert-dialog__cancel", "purpose": "취소 버튼 보정. axe-btn axe-btn--ghost 위에 얹힘.", "stability": "stable" } ], "a11y": { "keyboard": [ "Esc 로 취소(Cancel 과 동치)", "Tab/Shift+Tab 은 콘텐츠 안에서만 순환(포커스 트랩)", "열릴 때 기본 포커스가 Cancel(안전쪽)로 이동" ], "aria": "Radix 가 콘텐츠에 role=alertdialog·aria-modal=true 를 부여하고, AlertDialogTitle 을 aria-labelledby, AlertDialogDescription 을 aria-describedby 로 자동 연결한다. Cancel/Action 은 각각 취소·확정 시맨틱을 가진 버튼이다.", "notes": "Dialog 와 달리 바깥(오버레이) 클릭으로 닫히지 않아 실수 확정을 막는다. 기본 포커스가 Action 이 아닌 Cancel 에 놓여 파괴적 행동을 안전쪽으로 default 한다. data-state 로 진입/퇴장 애니메이션이 갈리며 prefers-reduced-motion 시 제거된다." }, "examples": [ { "title": "파괴적 확인 (삭제)", "lang": "tsx", "code": "import {\n AlertDialog,\n AlertDialogTrigger,\n AlertDialogContent,\n AlertDialogHeader,\n AlertDialogTitle,\n AlertDialogDescription,\n AlertDialogFooter,\n AlertDialogCancel,\n AlertDialogAction,\n Button,\n} from \"@axe/ui\";\n\n\n \n \n \n \n \n 문서 3개 영구 삭제\n \n 이 작업은 되돌릴 수 없습니다.\n \n \n \n 취소\n \n 삭제\n \n \n \n" }, { "title": "CSS-only 정적 표면 (비-React)", "lang": "html", "code": "
\n
\n
\n

문서 3개 영구 삭제

\n

이 작업은 되돌릴 수 없습니다.

\n
\n
\n \n \n
\n
" } ], "bestPractices": { "do": [ "제목·설명에 결과(무엇이·되돌릴 수 없음)를 구체적으로 서술.", "파괴적 확인 버튼은 variant=\"danger\" 로.", "확인이 필요 없는 단순 안내/폼은 Dialog 를 쓸 것." ], "dont": [ "여기에 close X 나 바깥클릭 닫기를 임의로 추가하지 말 것 — 명시적 선택 강제가 목적.", "size=full/xl 을 기대하지 말 것 — confirm 모달은 sm~lg 만." ] }, "consumeCss": "정적 표면은 .axe-alert-dialog__* + .axe-btn 마크업으로 재현 가능하다. 단 role=alertdialog·포커스 트랩·Esc=Cancel·바깥클릭 무시 같은 확인 시맨틱은 Radix 런타임이 만들므로, 실제 확인 흐름은 React 컴포넌트로 소비해야 한다. AlertDialogContent 는 내부에서 오버레이를 항상 함께 렌더하므로 별도 export 인 AlertDialogOverlay 를 기본 구성에서 추가로 둘 필요는 없다(커스텀 조립용).", "url": "https://design.axelabs.ai/components/alert-dialog" }, { "name": "AppShell", "slug": "app-shell", "group": "layout", "summary": "페이지 전체 레이아웃 chrome — 슬롯 골격과 Design/Gate 공용 workspace 표면.", "description": "variant 로 그리드 골격을 고른다: docs = Sidebar | Content | TOC, dashboard = Sidebar | Content, landing = Content. `.axe-workspace-shell`을 함께 쓰면 Design과 Gate가 공유하는 280px rail · 68rem bounded canvas · 30px navigation row 계약이 활성화된다. 본질은 CSS-only — Rust(maud)/Python(jinja) 도 같은 markup으로 같은 chrome을 그릴 수 있고, React wrapper는 슬롯 합성과 semantic role만 얹는 thin 층이다. 1024–1439px에서는 우측 context를 topbar disclosure로 옮기고, ≤1023px에서는 navigation과 context 양쪽을 native disclosure로 노출한다.", "keywords": [ "app shell", "앱셸", "layout", "레이아웃", "chrome", "docs", "dashboard", "landing", "toc", "shell" ], "props": [ { "name": "variant", "type": "\"docs\" | \"dashboard\" | \"landing\"", "defaultValue": "\"docs\"", "description": "그리드 골격 선택. data-shell 속성으로 CSS 가 분기." }, { "name": "topbar", "type": "React.ReactNode", "description": "상단 바 슬롯(보통 )." }, { "name": "sidebar", "type": "React.ReactNode", "description": "좌측 네비 슬롯(보통 ). landing 에서는 무시." }, { "name": "toc", "type": "React.ReactNode", "description": "우측 목차 슬롯(보통 ). variant=\"docs\" 에서만 표시." }, { "name": "footer", "type": "React.ReactNode", "description": "하단 슬롯(보통
\n \n \n {aum.map((r) => (\n \n \n \n \n ))}\n \n
일별 운용자산
{r.date}{r.value}
\n" } ], "bestPractices": { "do": [ "ariaLabel 을 항상 지정한다(미지정 fallback 은 무의미).", "실제 수치가 중요하면 ariaDescribedBy 로 .axe-sr-only 데이터 표를 함께 제공한다.", "각 series.label 을 지정해 색뿐 아니라 이름으로도 계열을 구분한다.", "예측·추정 계열은 dashed 로 실선/점선을 섞어 형태 단서를 준다.", "대시보드 첫 화면 차트는 LazyCharts 변형으로 recharts 청크를 지연 로드한다." ], "dont": [ "onPointClick 에 필수 정보 접근을 의존하지 말 것 — 마우스 전용이라 키보드로 도달 불가.", "6개 이상 계열을 색 지정 없이 두지 말 것 — semantic 팔레트가 5색에서 순환해 색이 겹친다.", "색만으로 계열 의미를 구분하지 말 것(color-blind·흑백 인쇄).", "recharts 무게(~395KB)를 first-paint 번들에 싣지 말 것." ] }, "consumeCss": "본 컴포넌트는 recharts(React) 위에 서 있어 순수 CSS-only 로는 소비할 수 없다 — HTML 마크업만으로 재현 불가. .axe-chart__tooltip* 클래스는 컴포넌트가 렌더하는 tooltip 을 테마가 재스타일하기 위한 계약이다. components.css가 data-display.css와 feedback.css를 모두 import하므로 표준 진입점 하나면 스타일은 완결된다.", "url": "https://design.axelabs.ai/components/chart" }, { "name": "ChatInput", "slug": "chat-input", "group": "input", "summary": "Enter 전송·자동 높이 조절·툴바 슬롯을 갖춘 AI 채팅 입력창.", "description": "uncontrolled \n
\n
\n
↵ 보내기 · ⇧↵ 줄바꿈
\n
\n" } ], "bestPractices": { "do": [ "전송 버튼은 toolbarRight 에 두고, 클릭 시 소비자 쪽에서도 값을 얻고 싶으면 ref 로 관리할 것.", "커스텀 키 처리가 필요하면 onKeyDown 에서 preventDefault 로 내부 Enter-to-send 를 끌 것." ], "dont": [ "controlled value/onChange 를 기대하지 말 것 — uncontrolled 이며 값은 ref 로 읽는다.", "전송 후 수동으로 비우려 하지 말 것 — onSubmit 성공 시 자동으로 비워진다." ] }, "consumeCss": "시각 껍데기(테두리·툴바·힌트·focus-within 링)는 .axe-chat-input__* 마크업만으로 재현되지만, Enter-to-send·autosize·IME 가드·clear() 는 모두 JS 동작이라 CSS-only 로는 재현되지 않는다.", "url": "https://design.axelabs.ai/components/chat-input" }, { "name": "Checkbox", "slug": "checkbox", "group": "input", "summary": "Radix 기반 tri-state 체크박스 (checked / unchecked / indeterminate).", "description": "@radix-ui/react-checkbox 의 Root 를 감싼 얇은 래퍼로, box 와 check/dash 아이콘 CSS 만 담당하고 상태·키보드·포커스는 Radix 가 처리한다. checked 는 boolean 또는 \"indeterminate\" 를 받아 부분선택(전체선택 헤더 등)을 표현한다. Indicator 는 forceMount 로 항상 렌더되고 표시할 아이콘은 data-state 에 따라 CSS 로 분기된다. 커스텀 prop 은 없고 Radix Checkbox.Root 의 props 를 그대로 노출한다.", "keywords": [ "checkbox", "체크박스", "tri-state", "indeterminate", "부분선택", "form", "폼" ], "props": [ { "name": "checked", "type": "boolean | \"indeterminate\"", "description": "controlled 상태. \"indeterminate\" = 부분선택 (aria-checked=\"mixed\")." }, { "name": "defaultChecked", "type": "boolean | \"indeterminate\"", "description": "uncontrolled 초기값." }, { "name": "onCheckedChange", "type": "(checked: boolean | \"indeterminate\") => void", "description": "상태 변경 콜백." }, { "name": "disabled", "type": "boolean", "description": "비활성 — data-disabled → opacity 0.5, 클릭 불가." }, { "name": "required", "type": "boolean", "description": "폼 제출 시 필수." }, { "name": "name", "type": "string", "description": "폼 필드명 — 지정 시 Radix 가 제출용 hidden input 을 렌더." }, { "name": "value", "type": "string", "defaultValue": "\"on\"", "description": "체크 시 폼에 전송되는 값." }, { "name": "...rest", "type": "React.ComponentPropsWithoutRef", "description": "asChild 등 나머지 Radix Checkbox.Root props 전파 (className 은 axe-checkbox 와 병합)." } ], "cssClasses": [ { "className": "axe-checkbox", "purpose": "체크박스 루트 (18px box). data-state=checked/indeterminate 시 accent 배경.", "stability": "stable" }, { "className": "axe-checkbox__indicator", "purpose": "아이콘 컨테이너 (Radix Indicator, forceMount).", "stability": "internal" }, { "className": "axe-checkbox__icon", "purpose": "check/dash SVG 공통 (기본 display:none).", "stability": "internal" }, { "className": "axe-checkbox__icon--check", "purpose": "체크 아이콘 — data-state=checked 에서만 표시.", "stability": "internal" }, { "className": "axe-checkbox__icon--dash", "purpose": "대시(부분선택) 아이콘 — data-state=indeterminate 에서만 표시.", "stability": "internal" } ], "a11y": { "keyboard": [ "Space 로 토글", "Tab 으로 포커스" ], "aria": "Radix 가 role=\"checkbox\" + aria-checked(true/false/\"mixed\") 를 부여. indeterminate → aria-checked=\"mixed\". disabled → aria-disabled + data-disabled.", "notes": "box 자체엔 텍스트가 없으므로 
 로 렌더하고, 헤더에 filename/language 라벨과 Copy 버튼을 둔다(클라이언트 컴포넌트 — clipboard API 사용). 복사 성공 시 버튼 라벨이 1.4초간 ‘Copied’ 로 바뀐다. 헤더는 language·filename·showCopy 중 하나라도 있을 때만 렌더된다. 문법 하이라이팅은 하지 않는다 — 토큰 색이 필요하면 서버 컴포넌트 ServerCodeBlock 을 사용.",
      "keywords": [
        "code block",
        "코드블록",
        "copy",
        "복사",
        "clipboard",
        "pre",
        "snippet"
      ],
      "props": [
        {
          "name": "code",
          "type": "string",
          "required": true,
          "description": "표시·복사할 코드 문자열."
        },
        {
          "name": "language",
          "type": "string",
          "description": "헤더 라벨(filename 없을 때). 하이라이팅에는 쓰이지 않음."
        },
        {
          "name": "showCopy",
          "type": "boolean",
          "defaultValue": "true",
          "description": "Copy 버튼 표시 여부. false 여도 language/filename 있으면 헤더는 렌더."
        },
        {
          "name": "filename",
          "type": "string",
          "description": "헤더 라벨(language 보다 우선)."
        },
        {
          "name": "...rest",
          "type": "React.HTMLAttributes",
          "description": "className 병합 후 나머지 속성은 루트 
 로 전파."
        }
      ],
      "cssClasses": [
        {
          "className": "axe-codeblock",
          "purpose": "블록 루트 
.",
          "stability": "stable"
        },
        {
          "className": "axe-codeblock__header",
          "purpose": "라벨 + copy 버튼 헤더 행.",
          "stability": "stable"
        },
        {
          "className": "axe-codeblock__lang",
          "purpose": "filename/language 라벨.",
          "stability": "stable"
        },
        {
          "className": "axe-codeblock__copy",
          "purpose": "Copy 버튼.",
          "stability": "stable"
        },
        {
          "className": "axe-codeblock__pre",
          "purpose": "코드 본문 
.",
          "stability": "stable"
        }
      ],
      "a11y": {
        "keyboard": [
          "Tab 으로 Copy 버튼 포커스",
          "Enter/Space 로 복사"
        ],
        "aria": "Copy 버튼은 aria-label=\"Copy code\" 를 가진 네이티브 \n  \n  …\n"
        },
        {
          "title": "CSS-only (정적 open)",
          "lang": "html",
          "code": "
\n  \n  
\n    
…본문…
\n  
\n
"
        }
      ],
      "bestPractices": {
        "do": [
          "하나의 영역만 접고 펼 때 쓴다(FAQ 목록 등 다항목은 Accordion).",
          "asChild 로 커스텀 트리거를 쓸 때는 chevron 등 열림 표시를 직접 배치한다."
        ],
        "dont": [
          "여러 Collapsible 을 나열해 accordion 을 흉내내지 말 것(키보드 네비가 없다)."
        ]
      },
      "consumeCss": "정적 open/closed 는 트리거·컨텐츠에 data-state=\"open|closed\" 를 직접 부여하면 .axe-collapsible__* 스타일로 재현된다(chevron 회전 포함). 단 부드러운 height 애니메이션은 Radix 가 --radix-collapsible-content-height 를 런타임 측정해 주입하므로 CSS-only 로는 즉시 토글만 가능.",
      "url": "https://design.axelabs.ai/components/collapsible"
    },
    {
      "name": "Combobox",
      "slug": "combobox",
      "group": "input",
      "summary": "타이핑으로 필터링하는 인라인 자동완성 (input + listbox).",
      "description": "input(role=combobox) 아래에 필터된 listbox 가 떠 있는 WAI-ARIA combobox 패턴. CommandPalette 와 같은 필터·키보드 내비·한국어 IME 가드 로직을 쓰되, modal dialog 대신 Popover anchor 로 인라인 렌더한다. 포커스는 항상 input 에 머물고 aria-activedescendant 로 가상 포커스만 이동하며, 팝업은 portal 로 떠 overflow:hidden 부모에 갇히지 않는다. 옵션이 적고 고정이면 Select 를 검토.",
      "keywords": [
        "combobox",
        "콤보박스",
        "자동완성",
        "autocomplete",
        "검색",
        "typeahead",
        "listbox"
      ],
      "props": [
        {
          "name": "items",
          "type": "ComboboxItem[]",
          "required": true,
          "description": "옵션 목록. 각 항목 = { value, label, keywords? } (keywords 는 label 외 추가 검색 대상)."
        },
        {
          "name": "value",
          "type": "string",
          "description": "선택된 value (controlled)."
        },
        {
          "name": "onValueChange",
          "type": "(value: string) => void",
          "description": "항목 선택 시 콜백."
        },
        {
          "name": "placeholder",
          "type": "string",
          "defaultValue": "\"검색…\"",
          "description": "input placeholder."
        },
        {
          "name": "emptyText",
          "type": "string",
          "defaultValue": "\"결과 없음\"",
          "description": "필터 결과가 0건일 때 표시할 텍스트."
        },
        {
          "name": "disabled",
          "type": "boolean",
          "defaultValue": "false",
          "description": "입력·열림 비활성."
        },
        {
          "name": "className",
          "type": "string",
          "description": "루트 .axe-combobox 에 병합."
        }
      ],
      "cssClasses": [
        {
          "className": "axe-combobox",
          "purpose": "루트 래퍼(Popover anchor).",
          "stability": "stable"
        },
        {
          "className": "axe-combobox__input",
          "purpose": "필터 input(role=combobox) — Select 트리거와 동일 sizing/border/ring 토큰.",
          "stability": "stable"
        },
        {
          "className": "axe-combobox__content",
          "purpose": "포털로 뜨는 팝업 패널.",
          "stability": "stable"
        },
        {
          "className": "axe-combobox__list",
          "purpose": "옵션 스크롤 리스트(role=listbox).",
          "stability": "stable"
        },
        {
          "className": "axe-combobox__item",
          "purpose": "옵션 row(role=option) — aria-selected/hover 시 강조.",
          "stability": "stable"
        },
        {
          "className": "axe-combobox__empty",
          "purpose": "결과 없음 안내 영역.",
          "stability": "stable"
        }
      ],
      "a11y": {
        "keyboard": [
          "↓ 로 열기 / 다음 항목, ↑ 로 이전 항목",
          "Enter 로 활성 항목 선택 (단, 한글 IME 조합 중 Enter 는 글자 확정으로 처리해 선택되지 않음)",
          "Esc 로 닫고 입력 쿼리 초기화"
        ],
        "aria": "input 에 role=combobox·aria-autocomplete=list·aria-expanded·aria-controls(listbox), 열림 시 aria-activedescendant 로 활성 옵션을 가리킴. 리스트=role=listbox, 각 옵션=role=option + aria-selected. 실제 DOM 포커스는 input 에 고정된다.",
        "notes": "Popover open/close auto-focus 를 막아 포커스가 input 밖으로 나가지 않는다. 옵션 클릭은 mousedown 으로 확정(input blur 로 닫히기 전). 활성 옵션은 scrollIntoView 로 항상 시야에 유지. portal 렌더라 overflow:hidden 부모에 갇히지 않음."
      },
      "examples": [
        {
          "title": "기본 (controlled)",
          "lang": "tsx",
          "code": "import { Combobox } from \"@axe/ui\";\n\n"
        }
      ],
      "bestPractices": {
        "do": [
          "라벨 외 별칭·영문 표기로도 찾게 하려면 각 item 에 keywords 를 채울 것.",
          "결과 0건 상황을 emptyText 로 안내."
        ],
        "dont": [
          "옵션이 소수이고 자유 검색이 불필요하면 Combobox 대신 Select 를 쓸 것.",
          "value 를 controlled 로 두면서 onValueChange 를 빼먹지 말 것(선택이 반영되지 않음)."
        ]
      },
      "consumeCss": "필터·키보드 내비·IME 가드가 전부 React 상태 로직이라 CSS-only 로는 동작을 재현할 수 없다(정적 마크업은 껍데기만). 스타일은 .axe-combobox__* 토큰으로 노출되나 실제 소비는 React 컴포넌트를 통한다.",
      "url": "https://design.axelabs.ai/components/combobox"
    },
    {
      "name": "CommandPalette",
      "slug": "command-palette",
      "group": "overlay",
      "summary": "⌘K 스타일 검색·명령 팔레트 오버레이.",
      "description": "document.body portal의 viewport 모달 combobox — 입력한 질의로 items 를 label·keywords·group 기준 부분일치 필터하고, group 별로 묶어 listbox 로 보여준다. open 상태는 소비자가 제어(controlled)하며 선택 시 onSelect + onClose 가 함께 불린다. 포커스 트랩·이전 포커스 복원·aria-activedescendant 로 WAI-ARIA dialog+combobox 패턴을 직접 구현한다. 항목은 CmdItem({ id, label, keywords?, meta?, group? }) 배열로 주입한다.",
      "keywords": [
        "command palette",
        "cmdk",
        "커맨드 팔레트",
        "명령",
        "검색",
        "⌘K",
        "combobox",
        "spotlight",
        "quick open"
      ],
      "props": [
        {
          "name": "open",
          "type": "boolean",
          "required": true,
          "description": "열림 여부. 소비자가 제어(false 면 null 반환 — 언마운트)."
        },
        {
          "name": "onClose",
          "type": "() => void",
          "required": true,
          "description": "닫기 요청 — Esc·backdrop 클릭·항목 선택 후 호출."
        },
        {
          "name": "items",
          "type": "CmdItem[]",
          "required": true,
          "description": "후보 목록. CmdItem = { id, label, keywords?, meta?, group? }."
        },
        {
          "name": "onSelect",
          "type": "(item: CmdItem) => void",
          "required": true,
          "description": "항목 확정 시 호출(뒤이어 onClose 도 실행됨)."
        },
        {
          "name": "placeholder",
          "type": "string",
          "defaultValue": "\"검색…\"",
          "description": "검색 input placeholder."
        },
        {
          "name": "ariaLabel",
          "type": "string",
          "defaultValue": "\"명령 검색\"",
          "description": "dialog의 접근성 이름. 검색 input 이름도 이 값에서 파생."
        },
        {
          "name": "className",
          "type": "string",
          "description": "루트 backdrop(.axe-cmdk-backdrop)에 덧대는 클래스."
        }
      ],
      "cssClasses": [
        {
          "className": "axe-cmdk-backdrop",
          "purpose": "화면 전체 backdrop — 바깥 클릭 시 닫힘.",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk",
          "purpose": "떠 있는 role=dialog 패널(포커스 트랩 컨테이너).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__search-row",
          "purpose": "검색 input + 명시적 닫기 버튼 행.",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__input",
          "purpose": "상단 검색 input(role=combobox).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__close",
          "purpose": "검색 닫기 버튼(Esc 힌트 포함).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__list",
          "purpose": "결과 스크롤 영역(role=listbox).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__group",
          "purpose": "동일 group 항목 묶음 래퍼.",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__group-label",
          "purpose": "group 헤더 라벨(group 있을 때만).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__item",
          "purpose": "항목 행(role=option). 강조는 [aria-selected=\"true\"]·:hover 로.",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__item-meta",
          "purpose": "항목 우측 메타(단축키 등, mono).",
          "stability": "stable"
        },
        {
          "className": "axe-cmdk__empty",
          "purpose": "결과 없음 안내.",
          "stability": "stable"
        }
      ],
      "a11y": {
        "keyboard": [
          "↑/↓ 활성 항목 이동(범위 clamp)",
          "Enter 활성 항목 선택(한글 IME 조합 중 Enter 는 글자 확정으로 무시)",
          "Esc 닫기",
          "Tab/Shift+Tab 팔레트 내부 순환(포커스 트랩 — 밖으로 탈출 금지)"
        ],
        "aria": "패널 = role=dialog + aria-modal=true + aria-label. input = role=combobox + 접근 이름 + aria-expanded=true + aria-autocomplete=list + aria-controls(listbox) + aria-activedescendant(활성 option id). 리스트 = role=listbox, 그룹 = role=group + aria-labelledby, 항목 = role=option + aria-selected.",
        "notes": "document.body portal이라 transformed/backdrop-filter 조상에 fixed modal이 갇히지 않는다. 열릴 때 같은 window의 다른 CommandPalette를 닫아 단일 modal만 유지하고, 최초 opener 포커스를 보존한 채 rAF로 input에 포커스한다. 마지막 palette가 닫힐 때만 body scroll lock을 풀고 최초 opener로 포커스를 복원한다. 방향키/Enter 선택은 input에서만 가로채므로 닫기 버튼의 네이티브 Enter를 침범하지 않는다. 활성 항목은 scrollIntoView(block:nearest)로 시야 유지. ⌘K 전역 단축키는 컴포넌트가 등록하지 않음 — open 토글은 소비자 몫."
      },
      "examples": [
        {
          "title": "기본 (controlled)",
          "lang": "tsx",
          "code": "import { useState } from \"react\";\nimport { CommandPalette, type CmdItem } from \"@axe/ui\";\n\nconst items: CmdItem[] = [\n  { id: \"new\", label: \"새 문서\", group: \"문서\", meta: \"⌘N\" },\n  { id: \"find\", label: \"검색\", keywords: \"find grep\", group: \"문서\", meta: \"⌘F\" },\n  { id: \"theme\", label: \"테마 전환\", group: \"설정\" },\n];\n\nexport function Launcher() {\n  const [open, setOpen] = useState(false);\n  return (\n    <>\n      \n       setOpen(false)}\n        onSelect={(item) => console.log(item.id)}\n      />\n    \n  );\n}"
        },
        {
          "title": "CSS-only (비-React 정적 마크업)",
          "lang": "html",
          "code": "
\n  
\n    
\n    \n      \n    
\n    
\n      
\n        
문서
\n        
\n          새 문서⌘N\n        
\n        
\n          검색⌘F\n        
\n      
\n    
\n  
\n
"
        }
      ],
      "bestPractices": {
        "do": [
          "open/닫기 상태와 ⌘K 단축키는 소비자가 관리(예 useHotkeys)한다.",
          "meta 에 단축키를, group 으로 항목을 의미 단위로 묶는다.",
          "검색 보강이 필요하면 keywords 에 동의어(영/한)를 넣는다."
        ],
        "dont": [
          "긴 목록에 무거운 onSelect 를 두지 말 것 — 선택 직후 onClose 로 닫힌다.",
          "backdrop 을 다른 오버레이 위에 겹치지 말 것(단일 모달 전제)."
        ]
      },
      "consumeCss": "필터·포커스 트랩·활성 이동은 JS 로직 — CSS-only 로는 정적 표시만 재현된다. 항목 강조는 [aria-selected=\"true\"] 속성으로 그려지므로, 비-React 로 쓸 땐 활성 option 에 aria-selected 를 직접 토글해야 한다.",
      "url": "https://design.axelabs.ai/components/command-palette"
    },
    {
      "name": "ContextMenu",
      "slug": "context-menu",
      "group": "overlay",
      "summary": "우클릭(또는 길게 누르기)으로 대상 영역 위에 여는 컨텍스트 액션 메뉴 (Radix ContextMenu 기반).",
      "description": "DropdownMenu 와 **같은** .axe-dropdown-menu__* 표면·항목·indicator·shortcut·separator 를 재사용한다(새 CSS 없음). 차이는 트리거뿐 — DropdownMenu 는 버튼 클릭으로 트리거 아래에, ContextMenu 는 대상 영역 우클릭으로 커서 위치에 뜬다(그래서 sideOffset 개념이 없다). ContextMenu(Root)·ContextMenuTrigger(우클릭 대상)·ContextMenuContent·ContextMenuItem 를 기본으로, Label·Separator·Shortcut·Checkbox/RadioItem·Sub 를 조합한다.",
      "keywords": [
        "context menu",
        "컨텍스트 메뉴",
        "우클릭",
        "right click",
        "long press",
        "액션 메뉴",
        "radix"
      ],
      "props": [
        {
          "name": "open",
          "type": "boolean",
          "description": "열림 상태 (controlled). Radix Root prop."
        },
        {
          "name": "onOpenChange",
          "type": "(open: boolean) => void",
          "description": "열림/닫힘 콜백 (Root)."
        },
        {
          "name": "modal",
          "type": "boolean",
          "defaultValue": "true",
          "description": "true 면 바깥 스크롤/포커스를 잠금 (Root)."
        },
        {
          "name": "withPortal",
          "type": "boolean",
          "defaultValue": "true",
          "description": "ContextMenuContent 를 portal 로 띄울지 — overflow:hidden 부모 탈출."
        },
        {
          "name": "variant",
          "type": "\"default\" | \"danger\"",
          "defaultValue": "\"default\"",
          "description": "ContextMenuItem 톤. danger=파괴적 액션의 텍스트/highlighted bg 를 danger 로."
        },
        {
          "name": "icon",
          "type": "React.ReactNode",
          "description": "ContextMenuItem 좌측 아이콘 슬롯 (선택)."
        },
        {
          "name": "...rest",
          "type": "각 Radix ContextMenu.* props",
          "description": "Trigger(asChild·우클릭 대상)·Content(collisionPadding)·Item(onSelect/disabled)·CheckboxItem/RadioItem 등 각 파트는 대응 Radix 컴포넌트 props 를 그대로 전파. DropdownMenu 와 달리 sideOffset·Arrow 는 없다(커서 위치 표시)."
        }
      ],
      "cssClasses": [
        {
          "className": "axe-dropdown-menu__content",
          "purpose": "커서 위치에 뜨는 메뉴 패널 표면(DropdownMenu 와 공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__sub-content",
          "purpose": "서브메뉴 패널(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__item",
          "purpose": "메뉴 항목 row(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__item--danger",
          "purpose": "danger 변형 항목(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__label",
          "purpose": "그룹 제목(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__separator",
          "purpose": "그룹 구분선(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__shortcut",
          "purpose": "우측 정렬 단축키 힌트 슬롯(공유).",
          "stability": "stable"
        },
        {
          "className": "axe-dropdown-menu__item--checkbox",
          "purpose": "checkbox 항목 layout 변형(자동 적용).",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__item--radio",
          "purpose": "radio 항목 layout 변형(자동 적용).",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__item--sub-trigger",
          "purpose": "서브메뉴 여는 항목 layout(자동 적용).",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__item-indicator",
          "purpose": "체크/도트 표시 슬롯(Radix ItemIndicator).",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__item-icon",
          "purpose": "항목 좌측 아이콘 슬롯 span.",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__item-label",
          "purpose": "항목 가운데 라벨 span.",
          "stability": "internal"
        },
        {
          "className": "axe-dropdown-menu__sub-chevron",
          "purpose": "sub-trigger 우측 chevron 아이콘.",
          "stability": "internal"
        }
      ],
      "a11y": {
        "keyboard": [
          "포커스된 트리거에서 ContextMenu 키(또는 Shift+F10)로 열기",
          "↑/↓ 로 항목 이동, Home/End 로 처음/끝",
          "글자 입력 시 type-ahead 로 해당 항목 점프",
          "→ 로 서브메뉴 열기, ← 로 닫고 상위로",
          "Enter/Space 로 항목 실행, Esc 로 닫기(트리거로 포커스 복원)"
        ],
        "aria": "Radix 가 콘텐츠에 role=menu, 각 항목에 role=menuitem(체크박스=menuitemcheckbox, 라디오=menuitemradio)을 부여. 현재 항목은 data-highlighted, 비활성은 data-disabled. 마우스 우클릭 외에 터치의 길게 누르기(long-press)로도 열린다.",
        "notes": "커서(또는 long-press) 지점에 앵커되어 뜬다. modal 기본(바깥 클릭·스크롤 잠금). 닫힘 시 트리거로 포커스 복원. prefers-reduced-motion 시 애니메이션 제거."
      },
      "examples": [
        {
          "title": "기본 (우클릭 영역)",
          "lang": "tsx",
          "code": "import {\n  ContextMenu,\n  ContextMenuTrigger,\n  ContextMenuContent,\n  ContextMenuLabel,\n  ContextMenuItem,\n  ContextMenuShortcut,\n  ContextMenuSeparator,\n} from \"@axe/ui\";\n\n\n  \n    
우클릭 가능한 영역
\n  \n  \n    액션\n    \n      열기 ⏎\n    \n    복제\n    \n    삭제\n  \n"
        },
        {
          "title": "서브메뉴",
          "lang": "tsx",
          "code": "import {\n  ContextMenu,\n  ContextMenuTrigger,\n  ContextMenuContent,\n  ContextMenuItem,\n  ContextMenuSub,\n  ContextMenuSubTrigger,\n  ContextMenuSubContent,\n} from \"@axe/ui\";\n\n\n  \n    
행
\n  \n  \n    편집\n    \n      이동\n      \n         moveTo(\"inbox\")}>보관함\n         moveTo(\"archive\")}>아카이브\n      \n    \n  \n"
        }
      ],
      "bestPractices": {
        "do": [
          "우클릭 컨텍스트가 있는 표면(행·카드·캔버스)에만 붙인다 — 발견성이 낮으니 보조 경로로.",
          "같은 액션을 툴바/DropdownMenu 등 눈에 보이는 경로로도 제공.",
          "항목 의미는 DropdownMenu 와 동일하게 유지(같은 표면·같은 규칙)."
        ],
        "dont": [
          "유일한 액션 경로로 삼지 말 것 — 우클릭은 터치/키보드 발견성이 낮다.",
          "메뉴에 폼·긴 인터랙티브 컨텐츠를 넣지 말 것."
        ]
      },
      "consumeCss": "열림 트리거(우클릭/long-press)·커서 앵커링·항목 하이라이트가 Radix 런타임에 의존해 CSS-only 로는 재현할 수 없다. 표면 스타일은 DropdownMenu 의 .axe-dropdown-menu__* 를 그대로 공유하므로 별도 CSS 토큰이 없다 — 실제 소비는 React 컴포넌트로.",
      "url": "https://design.axelabs.ai/components/context-menu"
    },
    {
      "name": "DataTable",
      "slug": "data-table",
      "group": "data",
      "summary": "정렬·페이지 슬라이싱·행 클릭을 갖춘 제네릭 데이터 표.",
      "description": "columns 정의(key·header·accessor·render·sortable·align·width)와 rows 배열로 구동되는 SSOT 표. 정렬은 controlled(sortBy+sortDir+onSort)와 uncontrolled(defaultSortBy) 두 모드를 지원하고, accessor 가 있으면 그 값으로, 없으면 row[key] 로 비교한다(숫자·Date·한국어 로케일 자동 판별). page+pageSize 를 주면 자체적으로 slice 만 하며, 페이지 이동 UI 는 Pagination 컴포넌트가 별도로 담당한다. loading 시 skeleton 행, 빈 rows 시 emptyState 를 렌더한다.",
      "keywords": [
        "data table",
        "데이터테이블",
        "표",
        "정렬",
        "sort",
        "pagination",
        "페이지네이션",
        "sortable",
        "sticky header"
      ],
      "props": [
        {
          "name": "columns",
          "type": "DataTableColumn[]",
          "required": true,
          "description": "열 정의 배열. 각 항목: key(정렬/aria 식별자) · header(ReactNode) · accessor?(정렬값 추출, 미지정 시 row[key]) · render?(셀 커스텀, 미지정 시 row[key]) · sortable? · align?(\"left\"|\"right\"|\"center\") · width?(CSS 폭)."
        },
        {
          "name": "rows",
          "type": "Row[]",
          "required": true,
          "description": "표시할 데이터 행. Row 는 제네릭 — 어떤 객체든 가능."
        },
        {
          "name": "getRowKey",
          "type": "(row: Row, index: number) => string",
          "description": "React key 로만 사용(onRowClick 은 row 객체를 직접 받으므로 무관). 미지정 시 배열 index 사용."
        },
        {
          "name": "sortBy",
          "type": "string",
          "description": "controlled 정렬 — 현재 정렬 열의 key. onSort 와 함께 줘야 controlled 로 인식."
        },
        {
          "name": "sortDir",
          "type": "\"asc\" | \"desc\"",
          "description": "controlled 정렬 방향. controlled 인데 미지정이면 \"asc\" 로 취급."
        },
        {
          "name": "onSort",
          "type": "(key: string, dir: SortDir) => void",
          "description": "정렬 헤더 클릭 콜백. sortBy 와 함께 주면 controlled. sortBy 만 주고 이걸 안 주면 controlled 로 인식되지 않아 dev 경고와 함께 sortBy 값이 무시되고, 헤더 클릭 정렬은 내부 state 로 폴백해 계속 동작한다."
        },
        {
          "name": "defaultSortBy",
          "type": "string",
          "description": "uncontrolled 초기 정렬 열. 이후 정렬 state 는 컴포넌트가 보유."
        },
        {
          "name": "defaultSortDir",
          "type": "\"asc\" | \"desc\"",
          "defaultValue": "\"asc\"",
          "description": "uncontrolled 초기 정렬 방향."
        },
        {
          "name": "page",
          "type": "number",
          "description": "1-based 현재 페이지. pageSize 와 함께 있어야 slice 발생."
        },
        {
          "name": "pageSize",
          "type": "number",
          "description": "페이지당 행 수. page 와 함께 주면 (page-1)*pageSize 부터 slice. loading skeleton 행 수의 기본값이기도 함(미지정 시 5)."
        },
        {
          "name": "onPageChange",
          "type": "(page: number) => void",
          "description": "시그니처 대칭을 위해 노출되나 컴포넌트가 내부에서 호출하지 않는다 — 페이지 전환은 짝을 이루는 Pagination 이 발생시키고, 그 값을 부모가 page 로 되돌려 준다."
        },
        {
          "name": "onRowClick",
          "type": "(row: Row) => void",
          "description": "행 클릭 콜백. 지정 시 행에 `--clickable` 클래스와 클릭 핸들러가 붙는다."
        },
        {
          "name": "rowClickable",
          "type": "boolean",
          "defaultValue": "false",
          "description": "onRowClick 이 있을 때 행 전체를 role=button+tabIndex 위젯으로 만들지. 기본 false(table 시맨틱 보존) — 셀 안에 ``/`