@xonic0506/sonic-ui 0.1.0 → 0.3.0

package/README.md

@@ -1,65 +1,95 @@
-# @xonic0506/sonic-ui
+<div align="center">
 
-Figma를 원본으로 하는 개인 디자인 시스템이에요. React 컴포넌트는 [Base UI](https://base-ui.com) 위에 만들었고, CSS는 Tailwind v4로 미리 빌드해서 배포해요.
+<img src="./docs/assets/sonic-mascot.webp" alt="Sonic 마스코트" width="240" />
 
-- 디자인 규칙: [DESIGN.md](./DESIGN.md)
-- AI 작업 규칙: [AI-RULES.md](./AI-RULES.md)
-- Figma: [Sonic Design System](https://www.figma.com/design/XifnZsjqJWJqFmAmrM6p3u)
+# Sonic UI
 
-## 설치
+[![npm version](https://img.shields.io/npm/v/@xonic0506/sonic-ui.svg)](https://www.npmjs.com/package/@xonic0506/sonic-ui) ![React](https://img.shields.io/badge/react-18.2%20%7C%2019-61dafb.svg) [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Figma를 원본으로 하는 개인 디자인 시스템이에요.
+
+[Figma](https://www.figma.com/design/XifnZsjqJWJqFmAmrM6p3u) | [디자인 규칙 (DESIGN.md)](./DESIGN.md) | [AI 작업 규칙 (AI-RULES.md)](./AI-RULES.md)
+
+</div>
+
+Sonic UI는 모든 사이드 프로젝트에서 같은 디자인을 쓰기 위해 만들었어요. 디자인 룰을 Figma와 DESIGN.md에 정해 두면, AI가 그 룰로 Figma 디자인을 만들고 이 패키지의 컴포넌트로 코드를 짜요.
+
+```text
+Figma (원본) → DESIGN.md (룰) → @xonic0506/sonic-ui (코드) → 실제 프로젝트
+```
+
+## 특징
+
+- Figma Variables가 그대로 CSS 변수가 돼요. `color/bg/primary`는 `--sn-color-bg-primary`이고, light/dark 테마를 함께 가져요.
+- CSS를 미리 빌드해서 배포해요. 쓰는 쪽 프로젝트는 Tailwind가 있어도 되고 없어도 돼요.
+- 모든 클래스에 `sn:` 접두사를 붙이고 `@layer sonic` 안에 넣어서, 쓰는 쪽 스타일과 부딪히지 않아요.
+- [Base UI](https://base-ui.com) 위에 만들어서 키보드 조작, 포커스 관리, 화면 낭독기 지원이 기본으로 들어 있어요.
+- 모든 파일에 `"use client"`가 붙어 있어서 Next.js 서버 컴포넌트에서도 바로 import할 수 있어요.
+- 쓰는 쪽 AI가 읽을 규칙 문서(DESIGN.md, AI-RULES.md)와 디자인 lint 규칙을 함께 배포해요.
+
+## 컴포넌트
+
+| 분류 | 컴포넌트 |
+| --- | --- |
+| 기본 | Button, Input, Textarea, Text, Card, Avatar, Separator |
+| 폼 | Field, Checkbox, CheckboxGroup, RadioGroup, Switch, Select (단일·다중) |
+| 오버레이 | Dialog, AlertDialog, Menu, Popover, Tooltip |
+| 탐색 | Tabs |
+| 피드백·상태 | Toast, Badge, Progress, Skeleton, EmptyState, ErrorState |
+
+컴포넌트별 props와 스펙은 [DESIGN.md §10](./DESIGN.md#10-컴포넌트-스펙-core)에 있어요.
+
+## 시작하기
+
+### 설치
 
 ```bash
 npm i @xonic0506/sonic-ui
 ```
 
-`react`, `react-dom` 18.2 이상(19 포함)이 필요해요(peerDependencies).
+`react`, `react-dom` 18.2 이상(19 포함)이 필요해요.
 
 ### 글꼴
 
-글꼴은 패키지에 들어 있지 않아요. IBM Plex Sans(400·500·600)와 IBM Plex Mono(400)를 프로젝트에서 불러와요. 없으면 시스템 글꼴로 대체돼요.
+IBM Plex Sans(400, 500, 600)와 IBM Plex Mono(400)를 프로젝트에서 불러와요. 없으면 시스템 글꼴로 대체돼요.
 
 ```html
 <link href="https://fonts.googleapis.com/css2?family=IBM+Plex+Mono&family=IBM+Plex+Sans:wght@400;500;600&display=swap" rel="stylesheet" />
 ```
 
-sonic-ui는 글꼴 이름 `"IBM Plex Sans"`, `"IBM Plex Mono"`를 찾아요. 이름을 바꾸는 방식(예: `next/font`의 기본 설정)으로 불러오면 적용되지 않으니, 위 링크나 `@fontsource/ibm-plex-sans`처럼 원래 이름을 유지하는 방식을 써요.
+> [!NOTE]
+> 글꼴은 패키지에 들어 있지 않아요. sonic-ui는 글꼴 이름 `"IBM Plex Sans"`, `"IBM Plex Mono"`를 찾기 때문에, 이름을 바꾸는 방식(예: `next/font` 기본 설정)으로 불러오면 적용되지 않아요. 위 링크나 `@fontsource/ibm-plex-sans`처럼 원래 이름을 유지하는 방식을 써요.
 
-## 설정
+### CSS 연결
 
-### Tailwind v4 프로젝트 (권장)
+Tailwind v4 프로젝트(권장)에서는 이렇게 연결해요.
 
 ```css
 /* app/globals.css */
 @layer theme, base, sonic, components, utilities;
 @import "tailwindcss";
 @import "@xonic0506/sonic-ui/styles.css";
-@import "@xonic0506/sonic-ui/tailwind.css"; /* 선택: bg-primary, text-muted, rounded-md, text-body … 클래스 */
+@import "@xonic0506/sonic-ui/tailwind.css"; /* 선택: bg-primary, text-muted, rounded-md, text-body 같은 클래스 */
 ```
 
-**layer 순서가 중요해요.** `sonic`은 Tailwind preflight(`base`)보다 뒤, 쓰는 쪽 `components`/`utilities`보다 앞이에요. 그래서 다음이 보장돼요.
-
-- preflight가 버튼 배경, 글자 크기를 지우지 않아요.
-- 쓰는 쪽 `className="bg-red-500"`은 항상 sonic-ui 기본 스타일을 이겨요.
+> [!IMPORTANT]
+> layer 순서를 지켜요. `sonic`이 Tailwind preflight(`base`)보다 뒤에 있어야 버튼 배경과 글자 크기가 지워지지 않고, 쓰는 쪽 `components`/`utilities`보다 앞에 있어야 `className="bg-red-500"` 같은 덮어쓰기가 항상 이겨요.
 
-### Tailwind 없는 프로젝트
+Tailwind가 없는 프로젝트에서는 CSS 파일 하나만 불러와요. 토큰은 `var(--sn-color-bg-primary)`처럼 CSS 변수로 써요.
 
 ```ts
 import '@xonic0506/sonic-ui/styles.css';
 ```
 
-sonic-ui CSS는 전부 `@layer sonic` 안에 있어서, layer에 넣지 않은 쓰는 쪽 CSS가 항상 이겨요. 토큰은 `var(--sn-color-bg-primary)`처럼 CSS 변수로 써요.
+### 앱 루트와 테마
 
-### 앱 최상위 요소
+앱 루트에 `isolation: isolate`를 지정해요. 앱의 z-index가 `body` 아래에 그려지는 Dialog, Toast를 가리지 않게 해 줘요.
 
 ```tsx
 <div style={{ isolation: 'isolate' }}>{/* 앱 */}</div>   // Tailwind: className="isolate"
 ```
 
-앱 루트에 `isolation: isolate`를 지정해요. 앱의 z-index가 Dialog Portal(`body` 아래)을 넘어서지 않게 해 줘요.
-
-### 테마
-
-`<html data-theme="light">` 또는 `data-theme="dark"`로 바꿔요. 속성이 없으면 light예요. Portal로 `body`에 그려지는 Dialog에도 같은 테마가 적용돼요.
+테마는 `<html data-theme="light">` 또는 `data-theme="dark"`로 바꿔요. 속성이 없으면 light이고, `body` 아래에 그려지는 팝업에도 같은 테마가 적용돼요.
 
 ## 사용
 
@@ -86,20 +116,26 @@ import { Button, Card, CardBody, CardHeader, CardTitle, Dialog, DialogClose, Dia
 </Dialog>
 ```
 
-컴포넌트별 props는 [DESIGN.md §10](./DESIGN.md#10-컴포넌트-스펙-core)에 있어요. 모든 파일에 `"use client"`가 붙어 있어서 Next.js 서버 컴포넌트에서도 바로 import할 수 있어요. 하위 컴포넌트는 `CardHeader`처럼 이름 있는 export로 써요.
+하위 컴포넌트는 `Card.Header`가 아니라 `CardHeader`처럼 이름 있는 export로 써요. 서버 컴포넌트에서도 깨지지 않게 하기 위해서예요.
 
-## Claude Code에서 쓰기
+Toast는 앱 최상단(Next.js는 `app/layout.tsx`)을 `<ToastProvider>`로 한 번 감싸고, 클라이언트 컴포넌트에서 띄워요.
 
-프로젝트 CLAUDE.md에 추가해요.
-
-```md
-@node_modules/@xonic0506/sonic-ui/DESIGN.md
-@node_modules/@xonic0506/sonic-ui/AI-RULES.md
+```tsx
+const toast = useToast();
+toast.add({ title: 'API 키를 만들었어요', tone: 'success' });
 ```
 
-## 디자인 lint 규칙 (선택)
+## AI와 함께 쓰기
+
+> [!TIP]
+> Claude Code를 쓰는 프로젝트라면 CLAUDE.md에 아래 두 줄을 추가해요. AI가 디자인 규칙을 읽고 sonic-ui 컴포넌트로 화면을 만들어요.
+>
+> ```md
+> @node_modules/@xonic0506/sonic-ui/DESIGN.md
+> @node_modules/@xonic0506/sonic-ui/AI-RULES.md
+> ```
 
-임의의 값 클래스, Tailwind 기본 팔레트, hex 색을 막는 ESLint flat config 조각을 제공해요. 켜는 것은 쓰는 쪽 설정에서 해요.
+임의의 값 클래스, Tailwind 기본 팔레트, hex 색을 막는 ESLint flat config도 제공해요. 켜는 것은 쓰는 쪽 설정에서 해요.
 
 ```js
 // eslint.config.js
@@ -109,15 +145,28 @@ export default [/* … */, sonicDesign];
 
 ## 지원 브라우저
 
-Tailwind v4 기준과 같아요: Chrome 111+, Edge 111+, Safari 16.4+, Firefox 128+. CSS `@layer`와 `@property`를 쓰기 때문이에요.
+Chrome 111+, Edge 111+, Safari 16.4+, Firefox 128+. CSS `@layer`와 `@property`를 쓰기 때문에 Tailwind v4와 기준이 같아요.
 
 ## 개발
 
 ```bash
-npm run build       # 토큰 생성 → JS(Vite) → 타입 → CSS(@layer sonic)
-npm test            # Vitest
+npm run build           # 토큰 생성 → JS(Vite) → 타입 → CSS(@layer sonic)
+npm test                # Vitest
 npm run typecheck
-npm run playground  # Figma Core 페이지와 비교하는 화면 (build 먼저)
+npm run check:contrast  # 글자와 바탕 대비 4.5:1 검사
+npm run playground      # Figma와 비교하는 화면 (build 먼저)
+```
+
+```text
+.
+├── src/components/   # Core 컴포넌트
+├── src/patterns/     # Pattern 승격 기준 (두 번째 프로젝트에서 복사하게 될 때)
+├── scripts/          # Figma 토큰 추출, CSS 빌드, 대비 검사
+├── lint/             # 디자인 lint 규칙
+├── playground/       # Figma와 비교하는 화면
+├── fixtures/         # 쓰는 쪽 예제 (vite, Next.js)
+└── DESIGN.md         # 디자인 규칙 (패키지에 포함)
 ```
 
-운영 규칙은 [CLAUDE.md](./CLAUDE.md)에 있어요.
+> [!NOTE]
+> 디자인을 바꿀 때는 Figma → DESIGN.md → 토큰 추출 → 코드 순서를 지켜요. 자세한 운영 규칙은 [CLAUDE.md](./CLAUDE.md)에 있어요.

package/dist/components/accordion.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+export interface AccordionProps {
+    /** 여러 항목을 함께 열 수 있음 (기본 false) */
+    multiple?: boolean;
+    /** 열린 항목들의 value */
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    className?: string;
+    children?: React.ReactNode;
+}
+/** 닫힌 내용도 브라우저 페이지 찾기로 찾아 열 수 있어요 (hiddenUntilFound) */
+export declare function Accordion({ onValueChange, className, ...props }: AccordionProps): React.JSX.Element;
+export interface AccordionItemProps {
+    value?: string;
+    disabled?: boolean;
+    className?: string;
+    children?: React.ReactNode;
+}
+export declare function AccordionItem({ className, ...props }: AccordionItemProps): React.JSX.Element;
+export interface AccordionTriggerProps {
+    className?: string;
+    children?: React.ReactNode;
+}
+export declare function AccordionTrigger({ className, children }: AccordionTriggerProps): React.JSX.Element;
+export interface AccordionPanelProps {
+    className?: string;
+    children?: React.ReactNode;
+}
+export declare function AccordionPanel({ className, children }: AccordionPanelProps): React.JSX.Element;

package/dist/components/accordion.js

@@ -0,0 +1,44 @@
+"use client";
+import { cn as e } from "../lib/cn.js";
+import "react";
+import { ChevronDown as t } from "lucide-react";
+import { jsx as n, jsxs as r } from "react/jsx-runtime";
+import { Accordion as i } from "@base-ui/react/accordion";
+//#region src/components/accordion.tsx
+function a({ onValueChange: t, className: r, ...a }) {
+	return /* @__PURE__ */ n(i.Root, {
+		...a,
+		hiddenUntilFound: !0,
+		onValueChange: t && ((e) => t(e)),
+		className: e("sn:flex sn:flex-col sn:font-sans", r)
+	});
+}
+function o({ className: t, ...r }) {
+	return /* @__PURE__ */ n(i.Item, {
+		...r,
+		className: e("sn:border-b sn:border-default sn:data-disabled:opacity-(--sn-opacity-disabled)", t)
+	});
+}
+function s({ className: a, children: o }) {
+	return /* @__PURE__ */ n(i.Header, {
+		className: "sn:m-0",
+		children: /* @__PURE__ */ r(i.Trigger, {
+			className: e("sn:group sn:flex sn:w-full sn:items-center sn:gap-2 sn:rounded-sm sn:border-0 sn:bg-transparent sn:px-0 sn:py-3 sn:text-left sn:font-sans sn:text-body-strong sn:text-default sn:cursor-pointer sn:focus-visible:outline-2 sn:focus-visible:outline-offset-2 sn:focus-visible:outline-focus sn:data-disabled:cursor-not-allowed", a),
+			children: [/* @__PURE__ */ n("span", {
+				className: "sn:min-w-0 sn:flex-1",
+				children: o
+			}), /* @__PURE__ */ n(t, { className: "sn:size-4 sn:shrink-0 sn:text-muted sn:transition-transform sn:duration-(--sn-duration-normal) sn:ease-standard sn:group-data-panel-open:rotate-180 sn:motion-reduce:transition-none" })]
+		})
+	});
+}
+function c({ className: t, children: r }) {
+	return /* @__PURE__ */ n(i.Panel, {
+		className: "sn:h-(--accordion-panel-height) sn:overflow-hidden sn:transition-[height] sn:duration-(--sn-duration-normal) sn:ease-standard sn:data-starting-style:h-0 sn:data-ending-style:h-0 sn:motion-reduce:transition-none",
+		children: /* @__PURE__ */ n("div", {
+			className: e("sn:pb-4 sn:font-sans sn:text-body sn:text-muted", t),
+			children: r
+		})
+	});
+}
+//#endregion
+export { a as Accordion, o as AccordionItem, c as AccordionPanel, s as AccordionTrigger };

package/dist/components/alert-dialog.d.ts

@@ -0,0 +1,16 @@
+import * as React from 'react';
+import { type DialogButtonProps, type DialogPopupProps, type DialogProps } from './dialog';
+/** 되돌릴 수 없는 동작(삭제 등) 확인. Dialog와 같은 모양이고 바깥을 눌러도 닫히지 않아요 */
+export declare function AlertDialog({ onOpenChange, ...props }: DialogProps): React.JSX.Element;
+export declare const AlertDialogTrigger: React.ForwardRefExoticComponent<DialogButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const AlertDialogClose: React.ForwardRefExoticComponent<DialogButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export declare const AlertDialogPopup: React.ForwardRefExoticComponent<DialogPopupProps & React.RefAttributes<HTMLDivElement>>;
+export declare const AlertDialogTitle: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLHeadingElement>, "className"> & {
+    className?: string;
+} & React.RefAttributes<HTMLHeadingElement>>;
+export declare const AlertDialogDescription: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLParagraphElement>, "className"> & {
+    className?: string;
+} & React.RefAttributes<HTMLParagraphElement>>;
+export declare const AlertDialogFooter: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "className"> & {
+    className?: string;
+} & React.RefAttributes<HTMLDivElement>>;

package/dist/components/alert-dialog.js

@@ -0,0 +1,46 @@
+"use client";
+import { cn as e } from "../lib/cn.js";
+import { DialogFooter as t, backdropClass as n, dialogDescriptionClass as r, dialogPopupClass as i, dialogTitleClass as a } from "./dialog.js";
+import * as o from "react";
+import { jsx as s, jsxs as c } from "react/jsx-runtime";
+import { AlertDialog as l } from "@base-ui/react/alert-dialog";
+//#region src/components/alert-dialog.tsx
+function u({ onOpenChange: e, ...t }) {
+	return /* @__PURE__ */ s(l.Root, {
+		...t,
+		onOpenChange: e && ((t) => e(t))
+	});
+}
+var d = o.forwardRef(function(e, t) {
+	return /* @__PURE__ */ s(l.Trigger, {
+		ref: t,
+		...e
+	});
+}), f = o.forwardRef(function(e, t) {
+	return /* @__PURE__ */ s(l.Close, {
+		ref: t,
+		...e
+	});
+}), p = o.forwardRef(function({ className: t, initialFocus: r, finalFocus: a, ...o }, u) {
+	return /* @__PURE__ */ c(l.Portal, { children: [/* @__PURE__ */ s(l.Backdrop, { className: n }), /* @__PURE__ */ s(l.Popup, {
+		ref: u,
+		initialFocus: r,
+		finalFocus: a,
+		className: e(i, t),
+		...o
+	})] });
+}), m = o.forwardRef(function({ className: t, ...n }, r) {
+	return /* @__PURE__ */ s(l.Title, {
+		ref: r,
+		className: e(a, t),
+		...n
+	});
+}), h = o.forwardRef(function({ className: t, ...n }, i) {
+	return /* @__PURE__ */ s(l.Description, {
+		ref: i,
+		className: e(r, t),
+		...n
+	});
+}), g = t;
+//#endregion
+export { u as AlertDialog, f as AlertDialogClose, h as AlertDialogDescription, g as AlertDialogFooter, p as AlertDialogPopup, m as AlertDialogTitle, d as AlertDialogTrigger };

package/dist/components/badge.d.ts

@@ -0,0 +1,8 @@
+import * as React from 'react';
+export interface BadgeProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'className'> {
+    tone?: 'neutral' | 'success' | 'warning' | 'danger';
+    /** 목록·표에서는 subtle, 꼭 눈에 띄어야 하는 한 곳에만 solid */
+    variant?: 'subtle' | 'solid';
+    className?: string;
+}
+export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/components/badge.js

@@ -0,0 +1,77 @@
+"use client";
+import { cn as e } from "../lib/cn.js";
+import * as t from "react";
+import { cva as n } from "class-variance-authority";
+import { jsx as r } from "react/jsx-runtime";
+//#region src/components/badge.tsx
+var i = n("sn:box-border sn:inline-flex sn:h-5 sn:shrink-0 sn:items-center sn:gap-1 sn:whitespace-nowrap sn:rounded-sm sn:px-2 sn:font-sans sn:text-label sn:[&_svg]:size-3 sn:[&_svg]:shrink-0", {
+	variants: {
+		tone: {
+			neutral: "",
+			success: "",
+			warning: "",
+			danger: ""
+		},
+		variant: {
+			subtle: "",
+			solid: ""
+		}
+	},
+	compoundVariants: [
+		{
+			tone: "neutral",
+			variant: "subtle",
+			className: "sn:bg-subtle sn:text-default"
+		},
+		{
+			tone: "neutral",
+			variant: "solid",
+			className: "sn:bg-inverse sn:text-inverse"
+		},
+		{
+			tone: "success",
+			variant: "subtle",
+			className: "sn:bg-success-subtle sn:text-success"
+		},
+		{
+			tone: "success",
+			variant: "solid",
+			className: "sn:bg-success sn:text-on-success"
+		},
+		{
+			tone: "warning",
+			variant: "subtle",
+			className: "sn:bg-warning-subtle sn:text-warning"
+		},
+		{
+			tone: "warning",
+			variant: "solid",
+			className: "sn:bg-warning sn:text-on-warning"
+		},
+		{
+			tone: "danger",
+			variant: "subtle",
+			className: "sn:bg-danger-subtle sn:text-danger"
+		},
+		{
+			tone: "danger",
+			variant: "solid",
+			className: "sn:bg-danger sn:text-on-danger"
+		}
+	],
+	defaultVariants: {
+		tone: "neutral",
+		variant: "subtle"
+	}
+}), a = t.forwardRef(function({ tone: t, variant: n, className: a, ...o }, s) {
+	return /* @__PURE__ */ r("span", {
+		ref: s,
+		className: e(i({
+			tone: t,
+			variant: n
+		}), a),
+		...o
+	});
+});
+//#endregion
+export { a as Badge };

package/dist/components/button.d.ts

@@ -1,9 +1,18 @@
 import * as React from 'react';
-export interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
+interface ButtonBaseProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'className'> {
     variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
-    size?: 'sm' | 'md' | 'lg';
     className?: string;
     /** 다른 요소로 렌더링할 때 (예: render={<a href="/" />}) */
     render?: React.ReactElement;
+    /** 진행 중: 스피너 표시, 클릭 막기, 포커스 유지, aria-busy */
+    loading?: boolean;
 }
+/** 아이콘만 있는 버튼은 읽을 글자가 없어서 aria-label이 필수예요 */
+export type ButtonProps = ButtonBaseProps & ({
+    size?: 'sm' | 'md' | 'lg';
+} | {
+    size: 'icon-sm' | 'icon-md' | 'icon-lg';
+    'aria-label': string;
+});
 export declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export {};

package/dist/components/button.js

@@ -3,9 +3,10 @@ import { cn as e } from "../lib/cn.js";
 import * as t from "react";
 import { Button as n } from "@base-ui/react/button";
 import { cva as r } from "class-variance-authority";
-import { jsx as i } from "react/jsx-runtime";
+import { LoaderCircle as i } from "lucide-react";
+import { Fragment as a, jsx as o, jsxs as s } from "react/jsx-runtime";
 //#region src/components/button.tsx
-var a = r("sn:box-border sn:inline-flex sn:items-center sn:justify-center sn:gap-2 sn:whitespace-nowrap sn:rounded-md sn:border sn:border-transparent sn:font-sans sn:cursor-pointer sn:select-none sn:transition-colors sn:duration-(--sn-duration-fast) sn:ease-standard sn:focus-visible:outline-2 sn:focus-visible:outline-offset-2 sn:focus-visible:outline-focus sn:data-disabled:cursor-not-allowed sn:data-disabled:opacity-(--sn-opacity-disabled)", {
+var c = r("sn:box-border sn:inline-flex sn:items-center sn:justify-center sn:gap-2 sn:whitespace-nowrap sn:rounded-md sn:border sn:border-transparent sn:font-sans sn:cursor-pointer sn:select-none sn:transition-colors sn:duration-(--sn-duration-fast) sn:ease-standard sn:focus-visible:outline-2 sn:focus-visible:outline-offset-2 sn:focus-visible:outline-focus sn:data-disabled:not-data-loading:cursor-not-allowed sn:data-disabled:not-data-loading:opacity-(--sn-opacity-disabled) sn:data-loading:cursor-progress sn:[&_svg]:pointer-events-none sn:[&_svg]:shrink-0", {
 	variants: {
 		variant: {
 			primary: "sn:bg-primary sn:text-on-primary sn:hover:not-data-disabled:bg-primary-hover",
@@ -14,26 +15,35 @@ var a = r("sn:box-border sn:inline-flex sn:items-center sn:justify-center sn:gap
 			danger: "sn:bg-danger sn:text-on-danger"
 		},
 		size: {
-			sm: "sn:h-7 sn:px-2 sn:text-label",
-			md: "sn:h-8 sn:px-3 sn:text-body-strong",
-			lg: "sn:h-10 sn:px-4 sn:text-body-strong"
+			sm: "sn:h-7 sn:px-2 sn:text-label sn:[&_svg]:size-4",
+			md: "sn:h-8 sn:px-3 sn:text-body-strong sn:[&_svg]:size-4",
+			lg: "sn:h-10 sn:px-4 sn:text-body-strong sn:[&_svg]:size-5",
+			"icon-sm": "sn:size-7 sn:p-0 sn:[&_svg]:size-4",
+			"icon-md": "sn:size-8 sn:p-0 sn:[&_svg]:size-4",
+			"icon-lg": "sn:size-10 sn:p-0 sn:[&_svg]:size-5"
 		}
 	},
 	defaultVariants: {
 		variant: "primary",
 		size: "md"
 	}
-}), o = t.forwardRef(function({ variant: t, size: r, className: o, render: s, ...c }, l) {
-	return /* @__PURE__ */ i(n, {
-		ref: l,
-		render: s,
-		nativeButton: !s || s.type === "button",
-		className: e(a({
+}), l = t.forwardRef(function({ variant: t, size: r, className: l, render: u, loading: d, disabled: f, children: p, ...m }, h) {
+	let g = /* @__PURE__ */ o(i, { className: "sn:animate-[sn-spin_var(--sn-duration-loop)_linear_infinite] sn:motion-reduce:animate-none" });
+	return /* @__PURE__ */ o(n, {
+		ref: h,
+		render: u,
+		nativeButton: !u || u.type === "button",
+		disabled: f || d,
+		focusableWhenDisabled: d,
+		"aria-busy": d || void 0,
+		"data-loading": d ? "" : void 0,
+		className: e(c({
 			variant: t,
 			size: r
-		}), o),
-		...c
+		}), l),
+		...m,
+		children: d && r?.startsWith("icon-") ? g : d ? /* @__PURE__ */ s(a, { children: [g, p] }) : p
 	});
 });
 //#endregion
-export { o as Button };
+export { l as Button };

package/dist/components/checkbox.d.ts

@@ -0,0 +1,30 @@
+import * as React from 'react';
+declare const labelClass = "sn:inline-flex sn:items-center sn:gap-2 sn:font-sans sn:text-body sn:text-default sn:cursor-pointer";
+declare const disabledClass = "sn:cursor-not-allowed sn:opacity-(--sn-opacity-disabled)";
+declare const focusClass = "sn:focus-visible:outline-2 sn:focus-visible:outline-offset-2 sn:focus-visible:outline-focus";
+export interface CheckboxProps {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onCheckedChange?: (checked: boolean) => void;
+    /** 일부만 선택된 상태 (그룹의 상위 항목) */
+    indeterminate?: boolean;
+    disabled?: boolean;
+    /** CheckboxGroup 안에서 쓰는 값 */
+    value?: string;
+    name?: string;
+    className?: string;
+    children?: React.ReactNode;
+}
+export declare const Checkbox: React.ForwardRefExoticComponent<CheckboxProps & React.RefAttributes<HTMLElement>>;
+export interface CheckboxGroupProps {
+    /** 그룹 이름 (fieldset legend) */
+    label: React.ReactNode;
+    value?: string[];
+    defaultValue?: string[];
+    onValueChange?: (value: string[]) => void;
+    disabled?: boolean;
+    className?: string;
+    children: React.ReactNode;
+}
+export declare function CheckboxGroup({ label, value, defaultValue, onValueChange, disabled, className, children }: CheckboxGroupProps): React.JSX.Element;
+export { labelClass as choiceLabelClass, disabledClass as choiceDisabledClass, focusClass as choiceFocusClass };

package/dist/components/checkbox.js

@@ -0,0 +1,48 @@
+"use client";
+import { cn as e } from "../lib/cn.js";
+import { boxClass as t } from "./popup-styles.js";
+import * as n from "react";
+import { Check as r, Minus as i } from "lucide-react";
+import { jsx as a, jsxs as o } from "react/jsx-runtime";
+import { Checkbox as s } from "@base-ui/react/checkbox";
+import { CheckboxGroup as c } from "@base-ui/react/checkbox-group";
+import { Fieldset as l } from "@base-ui/react/fieldset";
+//#region src/components/checkbox.tsx
+var u = "sn:inline-flex sn:items-center sn:gap-2 sn:font-sans sn:text-body sn:text-default sn:cursor-pointer", d = "sn:cursor-not-allowed sn:opacity-(--sn-opacity-disabled)", f = "sn:focus-visible:outline-2 sn:focus-visible:outline-offset-2 sn:focus-visible:outline-focus", p = n.forwardRef(function({ checked: n, defaultChecked: c, onCheckedChange: l, indeterminate: d, disabled: p, value: m, name: h, className: g, children: _ }, v) {
+	return /* @__PURE__ */ o("label", {
+		className: e(u, p && "sn:cursor-not-allowed sn:opacity-(--sn-opacity-disabled)", g),
+		children: [/* @__PURE__ */ a(s.Root, {
+			ref: v,
+			checked: n,
+			defaultChecked: c,
+			onCheckedChange: l && ((e) => l(e)),
+			indeterminate: d,
+			disabled: p,
+			value: m,
+			name: h,
+			className: e(t, f, "sn:data-checked:border-transparent sn:data-checked:bg-primary sn:data-indeterminate:border-transparent sn:data-indeterminate:bg-primary"),
+			children: /* @__PURE__ */ a(s.Indicator, {
+				className: "sn:flex",
+				children: a(d ? i : r, {})
+			})
+		}), _]
+	});
+});
+function m({ label: t, value: n, defaultValue: r, onValueChange: i, disabled: s, className: u, children: d }) {
+	return /* @__PURE__ */ o(l.Root, {
+		className: e("sn:m-0 sn:flex sn:min-w-0 sn:flex-col sn:gap-3 sn:border-0 sn:p-0 sn:font-sans", u),
+		children: [/* @__PURE__ */ a(l.Legend, {
+			className: "sn:p-0 sn:text-label sn:text-default",
+			children: t
+		}), /* @__PURE__ */ a(c, {
+			value: n,
+			defaultValue: r,
+			onValueChange: i && ((e) => i(e)),
+			disabled: s,
+			className: "sn:flex sn:flex-col sn:gap-2",
+			children: d
+		})]
+	});
+}
+//#endregion
+export { p as Checkbox, m as CheckboxGroup, d as choiceDisabledClass, f as choiceFocusClass, u as choiceLabelClass };

package/dist/components/dialog.d.ts

@@ -1,4 +1,8 @@
 import * as React from 'react';
+export declare const backdropClass = "sn:fixed sn:inset-0 sn:z-50 sn:bg-overlay sn:transition-opacity sn:duration-(--sn-duration-normal) sn:ease-standard sn:data-starting-style:opacity-0 sn:data-ending-style:opacity-0 sn:motion-reduce:transition-none";
+export declare const dialogPopupClass = "sn:fixed sn:top-1/2 sn:left-1/2 sn:z-50 sn:box-border sn:flex sn:w-110 sn:max-w-[calc(100vw-2*var(--sn-space-4))] sn:-translate-x-1/2 sn:-translate-y-1/2 sn:flex-col sn:gap-4 sn:rounded-lg sn:border sn:border-default sn:bg-surface sn:p-6 sn:font-sans sn:text-body sn:text-default sn:outline-none sn:transition-[opacity,scale] sn:duration-(--sn-duration-normal) sn:ease-standard sn:data-starting-style:scale-98 sn:data-starting-style:opacity-0 sn:data-ending-style:scale-98 sn:data-ending-style:opacity-0 sn:motion-reduce:transition-none";
+export declare const dialogTitleClass = "sn:m-0 sn:text-title sn:text-default";
+export declare const dialogDescriptionClass = "sn:-mt-3 sn:mb-0 sn:text-caption sn:text-muted";
 export interface DialogProps {
     open?: boolean;
     defaultOpen?: boolean;
@@ -15,8 +19,15 @@ export declare const DialogTrigger: React.ForwardRefExoticComponent<DialogButton
 export declare const DialogClose: React.ForwardRefExoticComponent<DialogButtonProps & React.RefAttributes<HTMLButtonElement>>;
 export interface DialogPopupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'className'> {
     className?: string;
+    /** 열릴 때 포커스할 요소 (기본: 팝업 안 첫 포커스 가능 요소) */
+    initialFocus?: React.RefObject<HTMLElement | null>;
+    /** 닫힌 뒤 포커스할 요소 (기본: 트리거나 열기 전 포커스 요소). 코드로 열었을 때 지정해요 */
+    finalFocus?: React.RefObject<HTMLElement | null>;
 }
 export declare const DialogPopup: React.ForwardRefExoticComponent<DialogPopupProps & React.RefAttributes<HTMLDivElement>>;
+export type TextProps<E extends HTMLElement> = Omit<React.HTMLAttributes<E>, 'className'> & {
+    className?: string;
+};
 export declare const DialogTitle: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLHeadingElement>, "className"> & {
     className?: string;
 } & React.RefAttributes<HTMLHeadingElement>>;