@xfilecom/front-core 0.2.26 → 0.2.28

package/README.md

@@ -1,29 +1,62 @@
 # @xfilecom/front-core
 
-Design tokens (`tokens.css`), atomic layout/CSS (`base.css`), and browser-only React atoms + overlays. **Nest / 서버 의존 없음.**
+Design tokens (`tokens.css`), atomic layout (`base.css`), browser-only React components. **Nest / 서버 의존 없음.**
 
-## CSS import order
+## 문서 (상세)
+
+| 문서 | 내용 |
+|------|------|
+| [docs/DESIGN_SYSTEM.md](./docs/DESIGN_SYSTEM.md) | MUI Paper / react-native-paper 등과 **개념 매핑**, elevation·역할 색 |
+| [docs/COMPONENTS.md](./docs/COMPONENTS.md) | 컴포넌트별 **소스 경로**, props 요약, **복붙 예제 코드** |
+
+npm 패키지에 `docs/`가 포함되므로, 설치 후 `node_modules/@xfilecom/front-core/docs/`에서도 동일 파일을 볼 수 있다.
+
+## CSS 로드 순서
 
 1. `@xfilecom/front-core/tokens.css`
 2. `@xfilecom/front-core/base.css`
-3. (optional) 앱/공유 테마 — 예: `xfc-theme.css`에서 `--xfc-*` 덮어쓰기
+3. (선택) 앱 `xfc-theme.css`에서 `--xfc-*` 덮어쓰기
+4. (선택) 레이아웃 `app.css`
+
+**다크:** `tokens.css` — `html.dark` / `data-theme="dark"`.
+
+**배경:** `body` 기본은 옅은 액센트 그라데이션. 단색만 쓰려면 `body { background-image: none; }`.
+
+## React import
+
+```tsx
+import {
+  Paper,
+  Card,
+  Button,
+  Text,
+  Dialog,
+} from '@xfilecom/front-core';
+```
+
+서브패스: `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
 
-**Dark mode:** `tokens.css` 끝에 `html.dark` / `data-theme="dark"` 프리셋이 있다. 루트에 클래스 또는 속성만 켜면 동일 변수명으로 전환된다.
+## Paper (표면)
 
-## React
+MUI `Paper` / RN `Surface`에 대응하는 얇은 래퍼:
 
-- 루트 export 또는 `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
-- **기본 UI 문자열은 영어** (토스트 닫기 `Dismiss`, ConfirmDialog `OK` / `Cancel`). 한국어 등은 props로 넘긴다.
+```tsx
+<Paper elevation={2} style={{ padding: 'var(--xfc-space-lg)' }}>
+  …
+</Paper>
+<Paper variant="outlined" style={{ padding: 16 }}>…</Paper>
+```
 
-## Accessibility
+## 기본 문자열·a11y
 
-- **Dialog / BottomSheet / ConfirmDialog:** body 스크롤 잠금, Escape, 초기 포커스·복귀, **Tab 포커스 트랩** (`useFocusTrap`).
-- **Toast:** `error`는 `role="alert"`, 그 외 `role="status"`. `ToastList`는 `ToastEntry.dismissible`로 행마다 닫기 버튼 on/off.
+- 기본 UI 문구는 **영어** (토스트 Dismiss, Confirm OK/Cancel). 한국어는 props로 덮어쓴다.
+- Dialog / BottomSheet: 스크롤 잠금, Escape, 포커스 트랩 (`useFocusTrap`).
+- Toast: `error` → `role="alert"`, 그 외 `role="status"`.
 
 ## Version
 
-`XFRAME_FRONT_CORE_VERSION`은 `npm run build` 시 `package.json`의 `version`으로 `src/generatedVersion.ts`가 갱신된다.
+`npm run build` 시 `package.json`의 `version`이 `src/generatedVersion.ts`에 반영된다.
 
-## Form atoms
+## 폼
 
-`Input`, `Textarea`, `Select`, `Checkbox`, `Field` — `Field`는 단일 자식 컨트롤에 `aria-describedby` / `aria-invalid` / `id`를 병합한다. 라벨 `htmlFor`와 컨트롤 `id`를 맞출 것.
+`Input`, `Textarea`, `Select`, `Checkbox`, `Field` — 자세한 예는 [COMPONENTS.md](./docs/COMPONENTS.md).

package/dist/base.css

@@ -23,8 +23,11 @@ body {
   font-size: var(--xfc-text-body);
   line-height: var(--xfc-leading-normal);
   color: var(--xfc-fg);
-  background: var(--xfc-bg);
+  background-color: var(--xfc-bg);
+  background-image: radial-gradient(ellipse 120% 80% at 50% -20%, var(--xfc-accent-soft), transparent 55%);
+  background-attachment: fixed;
   -webkit-font-smoothing: antialiased;
+  text-rendering: optimizeLegibility;
 }
 
 a {
@@ -46,9 +49,10 @@ a:hover {
 
 .xfc-text--title {
   font-size: var(--xfc-text-display);
-  font-weight: 700;
+  font-weight: 800;
   line-height: var(--xfc-leading-tight);
-  letter-spacing: -0.02em;
+  letter-spacing: -0.035em;
+  font-feature-settings: 'ss01' on, 'cv01' on;
 }
 
 .xfc-text--appbar {
@@ -75,6 +79,15 @@ a:hover {
   font-size: var(--xfc-text-body);
 }
 
+/** 본문보다 한 단계 큰 리드 문단 (히어로·카피) */
+.xfc-text--lead {
+  font-size: 1.125rem;
+  font-weight: 500;
+  line-height: 1.6;
+  color: var(--xfc-fg-label);
+  letter-spacing: -0.01em;
+}
+
 .xfc-text--small {
   font-size: var(--xfc-text-small);
 }
@@ -175,51 +188,114 @@ a:hover {
 .xfc-card {
   background: var(--xfc-bg-elevated);
   color: var(--xfc-fg);
-  border: 1px solid var(--xfc-border);
-  border-radius: var(--xfc-radius-md);
+  border: 1px solid color-mix(in srgb, var(--xfc-border) 88%, var(--xfc-fg) 6%);
+  border-radius: var(--xfc-radius-lg);
   box-shadow: var(--xfc-card-shadow);
 }
 
+/** 클릭·링크 카드만 — 정적 패널에는 붙이지 말 것 */
+.xfc-card--interactive {
+  cursor: pointer;
+  transition:
+    box-shadow 0.2s ease,
+    border-color 0.2s ease,
+    transform 0.2s ease;
+}
+
+@media (hover: hover) {
+  .xfc-card--interactive:hover {
+    border-color: color-mix(in srgb, var(--xfc-border-strong) 75%, var(--xfc-accent) 10%);
+    box-shadow: var(--xfc-shadow-md);
+    transform: translateY(-1px);
+  }
+
+  .xfc-card--interactive:active {
+    transform: translateY(0);
+  }
+}
+
 .xfc-card__header {
-  padding: var(--xfc-space-lg) var(--xfc-space-lg) var(--xfc-space-md);
+  padding: var(--xfc-space-xl) var(--xfc-space-xl) var(--xfc-space-md);
   border-bottom: 1px solid var(--xfc-border);
   font-size: var(--xfc-text-section);
   font-weight: 700;
+  letter-spacing: -0.02em;
   color: var(--xfc-fg-strong);
 }
 
 .xfc-card__body {
   min-width: 0;
-  padding: var(--xfc-space-lg);
+  padding: var(--xfc-space-xl);
 }
 
 .xfc-card__footer {
-  padding: 0 var(--xfc-space-lg) var(--xfc-space-lg);
+  padding: 0 var(--xfc-space-xl) var(--xfc-space-xl);
   border-top: 1px solid var(--xfc-border);
   padding-top: var(--xfc-space-md);
 }
 
-/* —— Buttons (피그마: 80×34 primary, radius 5) —— */
+/* —— Paper / Surface (MUI Paper · RN Paper Surface 스타일 elevation) —— */
+
+.xfc-paper {
+  box-sizing: border-box;
+  background: var(--xfc-bg-elevated);
+  color: var(--xfc-fg);
+  border-radius: var(--xfc-radius-md);
+  border: 1px solid transparent;
+  transition:
+    box-shadow 0.2s ease,
+    border-color 0.2s ease;
+}
+
+.xfc-paper--elevation-0 {
+  box-shadow: none;
+  border-color: var(--xfc-border);
+}
+
+.xfc-paper--elevation-1 {
+  box-shadow: var(--xfc-shadow-xs);
+}
+
+.xfc-paper--elevation-2 {
+  box-shadow: var(--xfc-shadow-sm);
+}
+
+.xfc-paper--elevation-3 {
+  box-shadow: var(--xfc-shadow-md);
+}
+
+.xfc-paper--elevation-4 {
+  box-shadow: var(--xfc-shadow-lg);
+}
+
+.xfc-paper--outlined {
+  box-shadow: none;
+  border-color: var(--xfc-border-strong);
+}
+
+/* —— Buttons —— */
 
 .xfc-btn {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  gap: var(--xfc-space-xs);
-  min-height: 34px;
-  padding: 0 var(--xfc-space-lg);
+  gap: var(--xfc-space-sm);
+  min-height: 40px;
+  padding: 0 calc(var(--xfc-space-lg) + 2px);
   font: inherit;
   font-size: var(--xfc-text-body);
-  font-weight: 700;
+  font-weight: 600;
+  letter-spacing: -0.01em;
   line-height: 1;
-  border-radius: var(--xfc-radius-xs);
+  border-radius: var(--xfc-radius-sm);
   border: 1px solid transparent;
   cursor: pointer;
   transition:
-    background 0.15s ease,
-    color 0.15s ease,
-    border-color 0.15s ease,
-    box-shadow 0.15s ease;
+    background 0.18s ease,
+    color 0.18s ease,
+    border-color 0.18s ease,
+    box-shadow 0.18s ease,
+    transform 0.18s ease;
 }
 
 .xfc-btn:focus-visible {
@@ -228,8 +304,10 @@ a:hover {
 }
 
 .xfc-btn:disabled {
-  opacity: 0.5;
+  opacity: 0.48;
   cursor: not-allowed;
+  transform: none;
+  box-shadow: none;
 }
 
 .xfc-btn--loading {
@@ -250,52 +328,75 @@ a:hover {
 .xfc-btn--primary {
   background: var(--xfc-accent);
   color: var(--xfc-accent-fg);
+  box-shadow:
+    var(--xfc-shadow-xs),
+    0 2px 12px color-mix(in srgb, var(--xfc-accent) 32%, transparent);
 }
 
 .xfc-btn--primary:hover:not(:disabled) {
   background: var(--xfc-accent-hover);
+  box-shadow:
+    var(--xfc-shadow-sm),
+    0 4px 20px color-mix(in srgb, var(--xfc-accent) 38%, transparent);
+}
+
+@media (hover: hover) {
+  .xfc-btn--primary:hover:not(:disabled) {
+    transform: translateY(-1px);
+  }
+
+  .xfc-btn--primary:active:not(:disabled) {
+    transform: translateY(0);
+  }
 }
 
 .xfc-btn--secondary {
   background: var(--xfc-bg-elevated);
   color: var(--xfc-fg);
   border-color: var(--xfc-border-strong);
+  box-shadow: var(--xfc-shadow-xs);
 }
 
 .xfc-btn--secondary:hover:not(:disabled) {
-  border-color: var(--xfc-fg-muted);
+  border-color: color-mix(in srgb, var(--xfc-accent) 35%, var(--xfc-border-strong));
+  background: color-mix(in srgb, var(--xfc-bg-muted) 40%, var(--xfc-bg-elevated));
 }
 
 .xfc-btn--outline {
-  background: var(--xfc-bg-elevated);
+  background: transparent;
   color: var(--xfc-accent);
-  border-color: var(--xfc-accent);
+  border-color: color-mix(in srgb, var(--xfc-accent) 45%, var(--xfc-border-strong));
+  box-shadow: none;
 }
 
 .xfc-btn--outline:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--xfc-accent) 6%, transparent);
+  background: var(--xfc-accent-soft);
+  border-color: var(--xfc-accent);
 }
 
 .xfc-btn--muted {
-  background: var(--xfc-bg-disabled);
+  background: color-mix(in srgb, var(--xfc-bg-muted) 65%, var(--xfc-bg-elevated));
   color: var(--xfc-fg-muted);
-  border-color: transparent;
+  border-color: var(--xfc-border);
+  box-shadow: none;
 }
 
 .xfc-btn--muted:hover:not(:disabled) {
-  filter: brightness(0.97);
+  background: var(--xfc-bg-muted);
+  color: var(--xfc-fg-label);
 }
 
 .xfc-btn--ghost {
   background: transparent;
   color: var(--xfc-accent);
+  box-shadow: none;
 }
 
 .xfc-btn--ghost:hover:not(:disabled) {
-  background: color-mix(in srgb, var(--xfc-accent) 8%, transparent);
+  background: var(--xfc-accent-soft);
 }
 
-/* —— Inputs (로그인 필드 48px, border #D4D4D4) —— */
+/* —— Inputs —— */
 
 .xfc-input {
   display: block;
@@ -307,26 +408,32 @@ a:hover {
   color: var(--xfc-fg);
   background: var(--xfc-bg-elevated);
   border: 1px solid var(--xfc-border-strong);
-  border-radius: var(--xfc-radius-xs);
+  border-radius: var(--xfc-radius-sm);
   box-shadow: var(--xfc-input-shadow);
   transition:
-    border-color 0.15s ease,
-    box-shadow 0.15s ease;
+    border-color 0.18s ease,
+    box-shadow 0.18s ease,
+    background-color 0.18s ease;
 }
 
 .xfc-input::placeholder {
   color: var(--xfc-fg-placeholder);
 }
 
+.xfc-input:hover:not(:disabled):not(:focus) {
+  border-color: color-mix(in srgb, var(--xfc-border-strong) 70%, var(--xfc-fg-muted) 30%);
+}
+
 .xfc-input:focus {
   outline: none;
   border-color: var(--xfc-accent);
-  box-shadow: var(--xfc-input-shadow), var(--xfc-focus-ring);
+  box-shadow: var(--xfc-shadow-sm), var(--xfc-focus-ring);
 }
 
 .xfc-input:disabled {
-  opacity: 0.6;
+  opacity: 0.55;
   cursor: not-allowed;
+  background: var(--xfc-bg-muted);
 }
 
 .xfc-input--invalid {
@@ -335,7 +442,7 @@ a:hover {
 
 .xfc-input--invalid:focus {
   border-color: var(--xfc-danger);
-  box-shadow: var(--xfc-input-shadow), 0 0 0 2px color-mix(in srgb, var(--xfc-danger) 25%, transparent);
+  box-shadow: var(--xfc-shadow-xs), 0 0 0 3px color-mix(in srgb, var(--xfc-danger) 22%, transparent);
 }
 
 .xfc-input-description {
@@ -410,31 +517,44 @@ a:hover {
 .xfc-badge {
   display: inline-flex;
   align-items: center;
-  padding: 2px var(--xfc-space-sm);
+  padding: 4px 10px;
   font-size: var(--xfc-text-small);
   font-weight: 600;
-  line-height: 1.3;
-  border-radius: var(--xfc-radius-xs);
+  line-height: 1.25;
+  letter-spacing: 0.01em;
+  border-radius: var(--xfc-radius-full);
+  border: 1px solid transparent;
+  box-shadow: var(--xfc-shadow-xs);
 }
 
 .xfc-badge--neutral {
-  background: var(--xfc-border);
-  color: var(--xfc-fg);
+  background: color-mix(in srgb, var(--xfc-bg-muted) 55%, var(--xfc-bg-elevated));
+  color: var(--xfc-fg-label);
+  border-color: var(--xfc-border);
 }
 
 .xfc-badge--accent {
-  background: color-mix(in srgb, var(--xfc-accent) 18%, transparent);
-  color: var(--xfc-accent-hover);
+  background: color-mix(in srgb, var(--xfc-accent) 16%, var(--xfc-bg-elevated));
+  color: var(--xfc-accent);
+  border-color: color-mix(in srgb, var(--xfc-accent) 28%, transparent);
 }
 
 .xfc-badge--success {
-  background: var(--xfc-success-bg);
+  background: color-mix(in srgb, var(--xfc-success) 12%, var(--xfc-success-bg));
   color: var(--xfc-success);
+  border-color: color-mix(in srgb, var(--xfc-success) 22%, transparent);
+}
+
+.xfc-badge--warn {
+  background: color-mix(in srgb, var(--xfc-warning) 14%, var(--xfc-warning-bg));
+  color: color-mix(in srgb, var(--xfc-warning) 85%, #000);
+  border-color: color-mix(in srgb, var(--xfc-warning) 25%, transparent);
 }
 
 .xfc-badge--danger {
-  background: color-mix(in srgb, var(--xfc-danger) 15%, transparent);
+  background: color-mix(in srgb, var(--xfc-danger) 12%, var(--xfc-bg-elevated));
   color: var(--xfc-danger);
+  border-color: color-mix(in srgb, var(--xfc-danger) 22%, transparent);
 }
 
 span.xfc-badge[aria-disabled='true'] {
@@ -479,17 +599,18 @@ button.xfc-badge[aria-disabled='true'] {
 }
 
 .xfc-loading-overlay-spinner {
-  width: 48px;
-  height: 48px;
-  border: 4px solid color-mix(in srgb, var(--xfc-accent) 22%, transparent);
+  width: 52px;
+  height: 52px;
+  border: 3px solid color-mix(in srgb, var(--xfc-accent) 18%, transparent);
   border-top-color: var(--xfc-accent);
+  border-right-color: color-mix(in srgb, var(--xfc-accent) 45%, transparent);
   border-radius: 50%;
-  animation: xfc-loading-overlay-spin 0.68s linear infinite;
+  animation: xfc-loading-overlay-spin 0.72s linear infinite;
   flex-shrink: 0;
   box-shadow:
-    0 0 0 2px rgba(255, 255, 255, 0.95),
-    0 6px 24px rgba(0, 0, 0, 0.14);
-  filter: drop-shadow(0 2px 6px rgba(0, 0, 0, 0.08));
+    0 0 0 1px rgba(255, 255, 255, 0.5),
+    0 8px 32px color-mix(in srgb, var(--xfc-accent) 22%, transparent),
+    var(--xfc-shadow-md);
 }
 
 .xfc-loading-overlay-title {
@@ -564,32 +685,38 @@ button.xfc-badge[aria-disabled='true'] {
   box-sizing: border-box;
   align-items: flex-start;
   justify-content: flex-start;
-  gap: var(--xfc-space-lg);
-  padding: var(--xfc-space-lg);
+  gap: var(--xfc-space-md);
+  padding: var(--xfc-space-lg) var(--xfc-space-xl);
   border-radius: var(--xfc-toast-radius);
   color: #fff;
   font-family: var(--xfc-font-sans);
   font-size: var(--xfc-text-body);
-  font-weight: 400;
-  line-height: 1.25;
+  font-weight: 500;
+  line-height: 1.35;
+  letter-spacing: -0.01em;
+  border: var(--xfc-toast-border);
   box-shadow: var(--xfc-toast-shadow);
-  transition: opacity 0.2s ease;
+  backdrop-filter: blur(8px);
+  -webkit-backdrop-filter: blur(8px);
+  transition:
+    opacity 0.2s ease,
+    transform 0.2s ease;
 }
 
 .xfc-toast--info {
-  background: var(--xfc-toast-info-bg);
+  background: linear-gradient(155deg, rgba(255, 255, 255, 0.12) 0%, transparent 42%), var(--xfc-toast-info-bg);
 }
 
 .xfc-toast--success {
-  background: var(--xfc-toast-success-bg);
+  background: linear-gradient(155deg, rgba(255, 255, 255, 0.14) 0%, transparent 40%), var(--xfc-toast-success-bg);
 }
 
 .xfc-toast--warn {
-  background: var(--xfc-toast-warn-bg);
+  background: linear-gradient(155deg, rgba(255, 255, 255, 0.12) 0%, transparent 40%), var(--xfc-toast-warn-bg);
 }
 
 .xfc-toast--error {
-  background: var(--xfc-toast-error-bg);
+  background: linear-gradient(155deg, rgba(255, 255, 255, 0.12) 0%, transparent 40%), var(--xfc-toast-error-bg);
 }
 
 .xfc-toast__icon {
@@ -662,11 +789,13 @@ button.xfc-badge[aria-disabled='true'] {
   align-items: center;
   justify-content: space-between;
   gap: var(--xfc-space-sm);
-  padding: var(--xfc-space-md) var(--xfc-space-lg);
-  background: var(--xfc-danger);
+  padding: var(--xfc-space-md) var(--xfc-space-xl);
+  background: linear-gradient(135deg, color-mix(in srgb, var(--xfc-danger) 92%, #fff) 0%, var(--xfc-danger) 100%);
   color: var(--xfc-accent-fg);
-  border-radius: var(--xfc-radius-md);
+  border-radius: var(--xfc-radius-lg);
   font-size: var(--xfc-text-small);
+  font-weight: 600;
+  border: 1px solid color-mix(in srgb, var(--xfc-danger) 55%, #fff);
   box-shadow: var(--xfc-toast-shadow);
 }
 
@@ -744,8 +873,10 @@ button.xfc-badge[aria-disabled='true'] {
   justify-content: center;
   padding: var(--xfc-space-lg);
   box-sizing: border-box;
-  background: color-mix(in srgb, var(--xfc-fg) 42%, transparent);
-  animation: xfc-dialog-backdrop-in 0.18s ease-out;
+  background: color-mix(in srgb, var(--xfc-fg-strong) 48%, transparent);
+  backdrop-filter: blur(10px) saturate(1.05);
+  -webkit-backdrop-filter: blur(10px) saturate(1.05);
+  animation: xfc-dialog-backdrop-in 0.2s ease-out;
 }
 
 .xfc-dialog-backdrop--bottom {
@@ -762,15 +893,13 @@ button.xfc-badge[aria-disabled='true'] {
   overflow: auto;
   box-sizing: border-box;
   padding: var(--xfc-space-xl);
-  border-radius: var(--xfc-radius-md);
+  border-radius: var(--xfc-radius-lg);
   background: var(--xfc-bg-elevated);
   color: var(--xfc-fg);
-  border: 1px solid var(--xfc-border);
-  box-shadow:
-    0 24px 48px color-mix(in srgb, var(--xfc-fg) 12%, transparent),
-    var(--xfc-card-shadow);
+  border: 1px solid color-mix(in srgb, var(--xfc-border) 88%, var(--xfc-accent) 10%);
+  box-shadow: var(--xfc-shadow-lg);
   font-family: var(--xfc-font-sans);
-  animation: xfc-dialog-panel-in 0.22s ease-out;
+  animation: xfc-dialog-panel-in 0.24s cubic-bezier(0.22, 1, 0.36, 1);
 }
 
 .xfc-dialog-panel__title-row {
@@ -916,4 +1045,10 @@ button.xfc-btn.xfc-btn--primary.xfc-confirm-dialog__confirm--danger:hover:not(:d
   .xfc-bottom-sheet-panel {
     animation: none;
   }
+
+  .xfc-btn--primary:hover:not(:disabled),
+  .xfc-card--interactive:hover,
+  .xfc-card--interactive:active {
+    transform: none;
+  }
 }

package/dist/components/atoms/Badge.d.ts

@@ -1,6 +1,6 @@
 import type { HTMLAttributes, MouseEventHandler, ReactNode } from 'react';
 export type BadgeProps = Omit<HTMLAttributes<HTMLSpanElement>, 'onClick'> & {
-    tone?: 'neutral' | 'accent' | 'success' | 'danger';
+    tone?: 'neutral' | 'accent' | 'success' | 'warn' | 'danger';
     children?: ReactNode;
     /** 앞쪽 아이콘·이모지 등 */
     icon?: ReactNode;

package/dist/components/atoms/Card.d.ts

@@ -5,5 +5,7 @@ export type CardProps = HTMLAttributes<HTMLDivElement> & {
     title?: ReactNode;
     /** 하단 푸터 슬롯 */
     footer?: ReactNode;
+    /** true면 호버 시 살짝 떠오르는 인터랙션 (클릭 카드·타일용) */
+    interactive?: boolean;
 };
-export declare function Card({ className, children, title, footer, ...rest }: CardProps): import("react/jsx-runtime").JSX.Element;
+export declare function Card({ className, children, title, footer, interactive, ...rest }: CardProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/Card.js

@@ -2,8 +2,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.Card = Card;
 const jsx_runtime_1 = require("react/jsx-runtime");
-function Card({ className = '', children, title, footer, ...rest }) {
-    const cls = ['xfc-card', className].filter(Boolean).join(' ');
+function Card({ className = '', children, title, footer, interactive, ...rest }) {
+    const cls = ['xfc-card', interactive ? 'xfc-card--interactive' : '', className].filter(Boolean).join(' ');
     const structured = title != null || footer != null;
     return ((0, jsx_runtime_1.jsxs)("div", { className: cls, ...rest, children: [title != null ? (0, jsx_runtime_1.jsx)("div", { className: "xfc-card__header", children: title }) : null, structured ? (0, jsx_runtime_1.jsx)("div", { className: "xfc-card__body", children: children }) : children, footer != null ? (0, jsx_runtime_1.jsx)("div", { className: "xfc-card__footer", children: footer }) : null] }));
 }

package/dist/components/atoms/Paper.d.ts

@@ -0,0 +1,16 @@
+import type { HTMLAttributes, ReactNode } from 'react';
+export type PaperProps = HTMLAttributes<HTMLDivElement> & {
+    children?: ReactNode;
+    /**
+     * Material-style elevation: 0은 평면+보더, 1…4는 섀도 강도 증가.
+     * `variant="outlined"`일 때는 무시되고 보더만 씀.
+     */
+    elevation?: 0 | 1 | 2 | 3 | 4;
+    /** filled = elevation 섀도, outlined = 보더만 */
+    variant?: 'filled' | 'outlined';
+};
+/**
+ * 콘텐츠를 올려놓는 표면 컴포넌트 (MUI `Paper` / RN Paper `Surface`에 가깝게).
+ * 스타일은 `base.css`의 `.xfc-paper*` — 토큰 `--xfc-shadow-*`와 연동.
+ */
+export declare function Paper({ elevation, variant, className, children, ...rest }: PaperProps): import("react/jsx-runtime").JSX.Element;

package/dist/components/atoms/Paper.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Paper = Paper;
+const jsx_runtime_1 = require("react/jsx-runtime");
+/**
+ * 콘텐츠를 올려놓는 표면 컴포넌트 (MUI `Paper` / RN Paper `Surface`에 가깝게).
+ * 스타일은 `base.css`의 `.xfc-paper*` — 토큰 `--xfc-shadow-*`와 연동.
+ */
+function Paper({ elevation = 1, variant = 'filled', className = '', children, ...rest }) {
+    const elevClass = variant === 'outlined' ? 'xfc-paper--outlined' : `xfc-paper--elevation-${elevation}`;
+    const cls = ['xfc-paper', elevClass, className].filter(Boolean).join(' ');
+    return ((0, jsx_runtime_1.jsx)("div", { className: cls, ...rest, children: children }));
+}

package/dist/components/atoms/Text.d.ts

@@ -4,6 +4,7 @@ declare const variantClass: {
     readonly appbar: "xfc-text xfc-text--appbar";
     readonly section: "xfc-text xfc-text--section";
     readonly subtitle: "xfc-text xfc-text--subtitle";
+    readonly lead: "xfc-text xfc-text--lead";
     readonly body: "xfc-text xfc-text--body";
     readonly muted: "xfc-text xfc-text--body xfc-text--muted";
     readonly small: "xfc-text xfc-text--small";

package/dist/components/atoms/Text.js

@@ -7,6 +7,7 @@ const variantClass = {
     appbar: 'xfc-text xfc-text--appbar',
     section: 'xfc-text xfc-text--section',
     subtitle: 'xfc-text xfc-text--subtitle',
+    lead: 'xfc-text xfc-text--lead',
     body: 'xfc-text xfc-text--body',
     muted: 'xfc-text xfc-text--body xfc-text--muted',
     small: 'xfc-text xfc-text--small',

package/dist/components/atoms/index.d.ts

@@ -13,6 +13,7 @@ export { Select, type SelectProps } from './Select';
 export { Textarea, type TextareaProps } from './Textarea';
 export { InlineErrorList, type InlineErrorEntry, type InlineErrorListProps, } from './InlineErrorList';
 export { LoadingOverlay, type LoadingOverlayProps } from './LoadingOverlay';
+export { Paper, type PaperProps } from './Paper';
 export { Stack, type StackProps } from './Stack';
 export { Toast, ToastList, ToastSeverityIcon, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './Toast';
 export { Text, type TextProps, type TextVariant } from './Text';

package/dist/components/atoms/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Text = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Stack = exports.LoadingOverlay = exports.InlineErrorList = exports.Textarea = exports.Select = exports.Input = exports.Field = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.Badge = void 0;
+exports.Text = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Stack = exports.Paper = exports.LoadingOverlay = exports.InlineErrorList = exports.Textarea = exports.Select = exports.Input = exports.Field = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.Badge = void 0;
 /**
  * Atomic UI — design tokens + base.css 의 `.xfc-*` 와 1:1.
  * 패키지 루트는 `components/index.ts` → 여기서 동일 심볼을 재export.
@@ -27,6 +27,8 @@ var InlineErrorList_1 = require("./InlineErrorList");
 Object.defineProperty(exports, "InlineErrorList", { enumerable: true, get: function () { return InlineErrorList_1.InlineErrorList; } });
 var LoadingOverlay_1 = require("./LoadingOverlay");
 Object.defineProperty(exports, "LoadingOverlay", { enumerable: true, get: function () { return LoadingOverlay_1.LoadingOverlay; } });
+var Paper_1 = require("./Paper");
+Object.defineProperty(exports, "Paper", { enumerable: true, get: function () { return Paper_1.Paper; } });
 var Stack_1 = require("./Stack");
 Object.defineProperty(exports, "Stack", { enumerable: true, get: function () { return Stack_1.Stack; } });
 var Toast_1 = require("./Toast");

package/dist/generatedVersion.d.ts

@@ -1,2 +1,2 @@
 /** Auto-generated by scripts/write-version.js — do not edit by hand */
-export declare const XFRAME_FRONT_CORE_VERSION: "0.2.26";
+export declare const XFRAME_FRONT_CORE_VERSION: "0.2.28";

package/dist/generatedVersion.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.XFRAME_FRONT_CORE_VERSION = void 0;
 /** Auto-generated by scripts/write-version.js — do not edit by hand */
-exports.XFRAME_FRONT_CORE_VERSION = "0.2.26";
+exports.XFRAME_FRONT_CORE_VERSION = "0.2.28";

package/dist/index.d.ts

@@ -24,7 +24,12 @@ export declare const tokenVars: {
     readonly colorBorderStrong: "--xfc-border-strong";
     readonly colorAccent: "--xfc-accent";
     readonly colorAccentHover: "--xfc-accent-hover";
+    readonly colorAccentSoft: "--xfc-accent-soft";
     readonly colorDanger: "--xfc-danger";
+    readonly shadowXs: "--xfc-shadow-xs";
+    readonly shadowSm: "--xfc-shadow-sm";
+    readonly shadowMd: "--xfc-shadow-md";
+    readonly shadowLg: "--xfc-shadow-lg";
     readonly radiusXs: "--xfc-radius-xs";
     readonly radiusSm: "--xfc-radius-sm";
     readonly radiusMd: "--xfc-radius-md";
@@ -46,6 +51,6 @@ export declare const tokenVars: {
     readonly toastWarnBg: "--xfc-toast-warn-bg";
     readonly toastErrorBg: "--xfc-toast-error-bg";
 };
-export { Badge, BottomSheet, Box, Button, Card, Checkbox, ConfirmDialog, Dialog, Field, InlineErrorList, Input, LoadingOverlay, Select, Stack, Text, Textarea, Toast, ToastList, ToastSeverityIcon, type BadgeProps, type BottomSheetProps, type BoxProps, type ButtonProps, type CardProps, type CheckboxProps, type ConfirmDialogProps, type DialogProps, type FieldProps, type InlineErrorEntry, type InlineErrorListProps, type InputProps, type LoadingOverlayProps, type SelectProps, type StackProps, type TextProps, type TextVariant, type TextareaProps, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './components';
+export { Badge, BottomSheet, Box, Button, Card, Checkbox, ConfirmDialog, Dialog, Field, InlineErrorList, Input, LoadingOverlay, Paper, Select, Stack, Text, Textarea, Toast, ToastList, ToastSeverityIcon, type BadgeProps, type BottomSheetProps, type BoxProps, type ButtonProps, type CardProps, type CheckboxProps, type ConfirmDialogProps, type DialogProps, type FieldProps, type InlineErrorEntry, type InlineErrorListProps, type InputProps, type LoadingOverlayProps, type PaperProps, type SelectProps, type StackProps, type TextProps, type TextVariant, type TextareaProps, type ToastEntry, type ToastListProps, type ToastProps, type ToastSeverity, type ToastSeverityIconProps, } from './components';
 /** 커스텀 오버레이용 — `Dialog`/`BottomSheet`와 동일한 훅 */
 export { useBodyScrollLock, useEscapeKey, useFocusTrap } from './components';

package/dist/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFocusTrap = exports.useEscapeKey = exports.useBodyScrollLock = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Textarea = exports.Text = exports.Stack = exports.Select = exports.LoadingOverlay = exports.Input = exports.InlineErrorList = exports.Field = exports.Dialog = exports.ConfirmDialog = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.BottomSheet = exports.Badge = exports.tokenVars = exports.XFRAME_FRONT_CORE_VERSION = void 0;
+exports.useFocusTrap = exports.useEscapeKey = exports.useBodyScrollLock = exports.ToastSeverityIcon = exports.ToastList = exports.Toast = exports.Textarea = exports.Text = exports.Stack = exports.Select = exports.Paper = exports.LoadingOverlay = exports.Input = exports.InlineErrorList = exports.Field = exports.Dialog = exports.ConfirmDialog = exports.Checkbox = exports.Card = exports.Button = exports.Box = exports.BottomSheet = exports.Badge = exports.tokenVars = exports.XFRAME_FRONT_CORE_VERSION = void 0;
 /**
  * @xfilecom/front-core — design tokens + atomic React components (browser-only).
  *
@@ -28,7 +28,12 @@ exports.tokenVars = {
     colorBorderStrong: '--xfc-border-strong',
     colorAccent: '--xfc-accent',
     colorAccentHover: '--xfc-accent-hover',
+    colorAccentSoft: '--xfc-accent-soft',
     colorDanger: '--xfc-danger',
+    shadowXs: '--xfc-shadow-xs',
+    shadowSm: '--xfc-shadow-sm',
+    shadowMd: '--xfc-shadow-md',
+    shadowLg: '--xfc-shadow-lg',
     radiusXs: '--xfc-radius-xs',
     radiusSm: '--xfc-radius-sm',
     radiusMd: '--xfc-radius-md',
@@ -63,6 +68,7 @@ Object.defineProperty(exports, "Field", { enumerable: true, get: function () { r
 Object.defineProperty(exports, "InlineErrorList", { enumerable: true, get: function () { return components_1.InlineErrorList; } });
 Object.defineProperty(exports, "Input", { enumerable: true, get: function () { return components_1.Input; } });
 Object.defineProperty(exports, "LoadingOverlay", { enumerable: true, get: function () { return components_1.LoadingOverlay; } });
+Object.defineProperty(exports, "Paper", { enumerable: true, get: function () { return components_1.Paper; } });
 Object.defineProperty(exports, "Select", { enumerable: true, get: function () { return components_1.Select; } });
 Object.defineProperty(exports, "Stack", { enumerable: true, get: function () { return components_1.Stack; } });
 Object.defineProperty(exports, "Text", { enumerable: true, get: function () { return components_1.Text; } });

package/dist/tokens.css

@@ -1,56 +1,70 @@
 /**
- * Design tokens — `xframe/html/html` (business-promotion Figma export) 기준.
- * 참고: main.html, navi_default.html, login_01.html 등 인라인 스타일에서 추출.
+ * Design tokens — 기본 테마 (라이트).
+ * 슬레이트 뉴트럴 + 인디고 액센트, 계층형 섀도·라디우스.
+ *
+ * Material 3 / MUI Paper / react-native-paper 와의 대응(개념):
+ * - 페이지 바탕: `--xfc-bg` ≈ surface / screen background
+ * - 카드·시트: `--xfc-bg-elevated` + `--xfc-shadow-*` ≈ elevated surface
+ * - `<Paper elevation={n}>` → `.xfc-paper--elevation-n` → `--xfc-shadow-xs|sm|md|lg`
+ * 자세한 비교: 패키지 `docs/DESIGN_SYSTEM.md`
  */
 :root {
   /* Surfaces */
-  --xfc-bg: #ffffff;
+  --xfc-bg: #f4f5f8;
   --xfc-bg-elevated: #ffffff;
-  --xfc-bg-muted: #f8f8f8;
-  --xfc-bg-disabled: #eaeaea;
+  --xfc-bg-muted: #e8ebf2;
+  --xfc-bg-disabled: #dce0e8;
 
   /* Text */
-  --xfc-fg: #1c252f;
-  --xfc-fg-strong: #000000;
-  --xfc-fg-label: #1d2125;
-  --xfc-fg-muted: #777777;
-  --xfc-fg-placeholder: #c7c7c7;
-  --xfc-fg-icon: #464c50;
+  --xfc-fg: #1e293b;
+  --xfc-fg-strong: #0f172a;
+  --xfc-fg-label: #334155;
+  --xfc-fg-muted: #64748b;
+  --xfc-fg-placeholder: #94a3b8;
+  --xfc-fg-icon: #475569;
 
   /* Lines */
-  --xfc-border: #ededed;
-  --xfc-border-strong: #d4d4d4;
-  --xfc-border-header: #e9e8e6;
+  --xfc-border: #e2e8f0;
+  --xfc-border-strong: #cbd5e1;
+  --xfc-border-header: #e2e8f0;
 
   /* Brand */
-  --xfc-accent: #2a5bff;
-  --xfc-accent-hover: #2248e6;
+  --xfc-accent: #4f46e5;
+  --xfc-accent-hover: #4338ca;
   --xfc-accent-fg: #ffffff;
+  /** 포커스·글로우용 연한 틴트 */
+  --xfc-accent-soft: color-mix(in srgb, var(--xfc-accent) 14%, transparent);
 
   /* Status */
-  --xfc-danger: #f43b3c;
+  --xfc-danger: #e11d48;
   --xfc-success: #059669;
   --xfc-success-bg: #d1fae5;
   --xfc-warning: #d97706;
   --xfc-warning-bg: #fef3c7;
 
-  /* Toasts (business-promotion client index.css 와 동일 톤) */
-  --xfc-toast-info-bg: #1c252f;
-  --xfc-toast-success-bg: #19af66;
-  --xfc-toast-warn-bg: #e8a317;
-  --xfc-toast-error-bg: #f43b3c;
-  --xfc-toast-shadow: 0 2px 8px rgba(0, 0, 0, 0.15);
-  --xfc-toast-radius: 6px;
-
-  /* Effects */
-  --xfc-input-shadow: 0 7px 64px rgba(0, 0, 0, 0.07);
-  --xfc-card-shadow: 0 1px 2px rgba(28, 37, 47, 0.06);
-
-  /* Radius (px 그대로 — 디자인 5 / 10 / pill) */
-  --xfc-radius-xs: 5px;
-  --xfc-radius-sm: 5px;
-  --xfc-radius-md: 10px;
-  --xfc-radius-lg: 10px;
+  /* Toasts (단색 — 그라데이션·글로우는 base.css 에서 보강) */
+  --xfc-toast-info-bg: #1e293b;
+  --xfc-toast-success-bg: #059669;
+  --xfc-toast-warn-bg: #d97706;
+  --xfc-toast-error-bg: #e11d48;
+  --xfc-toast-shadow: 0 10px 40px rgba(15, 23, 42, 0.18), 0 2px 8px rgba(15, 23, 42, 0.08);
+  --xfc-toast-radius: 12px;
+  --xfc-toast-border: 1px solid rgba(255, 255, 255, 0.14);
+
+  /* Layered shadows */
+  --xfc-shadow-xs: 0 1px 2px rgba(15, 23, 42, 0.05);
+  --xfc-shadow-sm: 0 2px 8px rgba(15, 23, 42, 0.06), 0 1px 2px rgba(15, 23, 42, 0.04);
+  --xfc-shadow-md: 0 8px 24px rgba(15, 23, 42, 0.08), 0 2px 6px rgba(15, 23, 42, 0.04);
+  --xfc-shadow-lg: 0 24px 48px rgba(15, 23, 42, 0.12), 0 8px 16px rgba(15, 23, 42, 0.06);
+
+  --xfc-input-shadow: var(--xfc-shadow-xs);
+  --xfc-card-shadow: var(--xfc-shadow-sm);
+
+  /* Radius */
+  --xfc-radius-xs: 8px;
+  --xfc-radius-sm: 10px;
+  --xfc-radius-md: 14px;
+  --xfc-radius-lg: 18px;
   --xfc-radius-full: 9999px;
 
   /* Space */
@@ -61,7 +75,7 @@
   --xfc-space-xl: 24px;
   --xfc-space-2xl: 32px;
 
-  /* Typography — Pretendard Variable (+ 로고용 Poppins 는 앱에서 별도) */
+  /* Typography */
   --xfc-font-sans: 'Pretendard Variable', Pretendard, -apple-system, BlinkMacSystemFont, system-ui,
     Roboto, 'Noto Sans KR', 'Apple SD Gothic Neo', sans-serif;
   --xfc-font-mono: ui-monospace, 'Cascadia Code', 'SF Mono', Menlo, monospace;
@@ -74,44 +88,44 @@
   --xfc-text-input: 0.9375rem;
 
   --xfc-leading-tight: 1.25;
-  --xfc-leading-normal: 1.5;
+  --xfc-leading-normal: 1.55;
   --xfc-leading-label: 22px;
   --xfc-leading-menu: 50px;
 
   /* Focus */
-  --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 35%, transparent);
+  --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 32%, transparent);
 }
 
 /**
- * Dark theme (opt-in): `<html class="dark">` or `data-theme="dark"` on `:root` / `html`.
- * 동일한 변수 이름만 덮어쓴다 — 앱은 토큰 참조를 바꿀 필요 없음.
+ * Dark theme (opt-in): `<html class="dark">` or `data-theme="dark"`.
  */
 html.dark,
 :root[data-theme='dark'],
 html[data-theme='dark'] {
   color-scheme: dark;
 
-  --xfc-bg: #0f1419;
-  --xfc-bg-elevated: #1a222c;
-  --xfc-bg-muted: #141b22;
-  --xfc-bg-disabled: #2a3440;
+  --xfc-bg: #0c0f14;
+  --xfc-bg-elevated: #151b24;
+  --xfc-bg-muted: #1a222d;
+  --xfc-bg-disabled: #2d3a4a;
 
-  --xfc-fg: #e8eef4;
-  --xfc-fg-strong: #ffffff;
-  --xfc-fg-label: #dce4ec;
-  --xfc-fg-muted: #8b9aab;
-  --xfc-fg-placeholder: #5c6b7a;
+  --xfc-fg: #e2e8f0;
+  --xfc-fg-strong: #f8fafc;
+  --xfc-fg-label: #cbd5e1;
+  --xfc-fg-muted: #94a3b8;
+  --xfc-fg-placeholder: #64748b;
   --xfc-fg-icon: #a8b8c8;
 
-  --xfc-border: #2a3440;
-  --xfc-border-strong: #3d4a5c;
-  --xfc-border-header: #2f3d4d;
+  --xfc-border: #2d3a4a;
+  --xfc-border-strong: #3d4f66;
+  --xfc-border-header: #334155;
 
-  --xfc-accent: #5b8aff;
-  --xfc-accent-hover: #7aa3ff;
-  --xfc-accent-fg: #0f1419;
+  --xfc-accent: #818cf8;
+  --xfc-accent-hover: #a5b4fc;
+  --xfc-accent-fg: #0f172a;
+  --xfc-accent-soft: color-mix(in srgb, var(--xfc-accent) 18%, transparent);
 
-  --xfc-danger: #ff6b6b;
+  --xfc-danger: #fb7185;
   --xfc-success: #34d399;
   --xfc-success-bg: #064e3b;
   --xfc-warning: #fbbf24;
@@ -120,11 +134,17 @@ html[data-theme='dark'] {
   --xfc-toast-info-bg: #1e293b;
   --xfc-toast-success-bg: #047857;
   --xfc-toast-warn-bg: #b45309;
-  --xfc-toast-error-bg: #dc2626;
-  --xfc-toast-shadow: 0 2px 12px rgba(0, 0, 0, 0.45);
+  --xfc-toast-error-bg: #be123c;
+  --xfc-toast-shadow: 0 12px 40px rgba(0, 0, 0, 0.45), 0 4px 12px rgba(0, 0, 0, 0.3);
+  --xfc-toast-border: 1px solid rgba(255, 255, 255, 0.08);
+
+  --xfc-shadow-xs: 0 1px 2px rgba(0, 0, 0, 0.35);
+  --xfc-shadow-sm: 0 4px 16px rgba(0, 0, 0, 0.25), 0 1px 3px rgba(0, 0, 0, 0.2);
+  --xfc-shadow-md: 0 12px 32px rgba(0, 0, 0, 0.35), 0 4px 12px rgba(0, 0, 0, 0.2);
+  --xfc-shadow-lg: 0 28px 56px rgba(0, 0, 0, 0.45), 0 12px 24px rgba(0, 0, 0, 0.25);
 
-  --xfc-input-shadow: 0 4px 24px rgba(0, 0, 0, 0.25);
-  --xfc-card-shadow: 0 1px 3px rgba(0, 0, 0, 0.35);
+  --xfc-input-shadow: var(--xfc-shadow-xs);
+  --xfc-card-shadow: var(--xfc-shadow-sm);
 
-  --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 45%, transparent);
+  --xfc-focus-ring: 0 0 0 3px color-mix(in srgb, var(--xfc-accent) 40%, transparent);
 }

package/docs/COMPONENTS.md

@@ -0,0 +1,111 @@
+# Components reference
+
+소스는 모두 `packages/front-core/src/` 기준. 빌드 산출물은 `dist/`에 동일 구조로 복사된다.
+
+## 레이아웃·표면
+
+| 컴포넌트 | 소스 | 요약 |
+|----------|------|------|
+| `Paper` | [atoms/Paper.tsx](../src/components/atoms/Paper.tsx) | `elevation` 0~4, `variant` filled \| outlined |
+| `Card` | [atoms/Card.tsx](../src/components/atoms/Card.tsx) | `title`, `footer`, `interactive` |
+| `Box` | [atoms/Box.tsx](../src/components/atoms/Box.tsx) | `as`, `padding` |
+| `Stack` | [atoms/Stack.tsx](../src/components/atoms/Stack.tsx) | flex gap·align·justify |
+
+### Paper
+
+```tsx
+import { Paper, Stack, Text } from '@xfilecom/front-core';
+
+<Paper elevation={2} style={{ padding: 'var(--xfc-space-lg)' }}>
+  <Text variant="body">Elevation 2 surface</Text>
+</Paper>
+
+<Paper variant="outlined" style={{ padding: 'var(--xfc-space-md)' }}>
+  Border only
+</Paper>
+```
+
+### Card
+
+```tsx
+import { Card, Button } from '@xfilecom/front-core';
+
+<Card
+  title="제목"
+  footer={<Button variant="primary">확인</Button>}
+>
+  본문
+</Card>
+```
+
+## 타이포
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Text` | [atoms/Text.tsx](../src/components/atoms/Text.tsx) |
+
+`variant`: `title` | `appbar` | `section` | `subtitle` | `lead` | `body` | `muted` | `small` | `label` | `labelBlock` | `accent`
+
+```tsx
+<Text variant="section">섹션 제목</Text>
+<Text variant="lead">리드 문단</Text>
+```
+
+## 액션
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Button` | [atoms/Button.tsx](../src/components/atoms/Button.tsx) |
+| `Badge` | [atoms/Badge.tsx](../src/components/atoms/Badge.tsx) |
+
+`Button` variants: `primary` | `secondary` | `outline` | `muted` | `ghost`  
+`Badge` tone: `neutral` | `accent` | `success` | `warn` | `danger`
+
+## 폼
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Input` | [atoms/Input.tsx](../src/components/atoms/Input.tsx) |
+| `Textarea` | [atoms/Textarea.tsx](../src/components/atoms/Textarea.tsx) |
+| `Select` | [atoms/Select.tsx](../src/components/atoms/Select.tsx) |
+| `Checkbox` | [atoms/Checkbox.tsx](../src/components/atoms/Checkbox.tsx) |
+| `Field` | [atoms/Field.tsx](../src/components/atoms/Field.tsx) |
+
+`Field`는 **단일** 자식에 `id` / `aria-describedby` / `aria-invalid`를 병합한다. `htmlFor`와 자식 `id`를 일치시킨다.
+
+## 피드백
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Toast` / `ToastList` | [atoms/Toast.tsx](../src/components/atoms/Toast.tsx) |
+| `ToastSeverityIcon` | 동일 파일 |
+| `InlineErrorList` | [atoms/InlineErrorList.tsx](../src/components/atoms/InlineErrorList.tsx) |
+| `LoadingOverlay` | [atoms/LoadingOverlay.tsx](../src/components/atoms/LoadingOverlay.tsx) |
+
+`ToastList`의 `ToastEntry`에 `dismissible?: boolean`으로 행마다 닫기 버튼을 제어한다.
+
+## 오버레이
+
+| 컴포넌트 | 소스 |
+|----------|------|
+| `Dialog` | [overlays/Dialog.tsx](../src/components/overlays/Dialog.tsx) |
+| `ConfirmDialog` | [overlays/ConfirmDialog.tsx](../src/components/overlays/ConfirmDialog.tsx) |
+| `BottomSheet` | [overlays/BottomSheet.tsx](../src/components/overlays/BottomSheet.tsx) |
+
+커스텀 모달에 동일한 스크롤 잠금·포커스 트랩을 쓰려면 [overlayHooks.ts](../src/components/overlays/overlayHooks.ts)의 `useFocusTrap`, `useBodyScrollLock`, `useEscapeKey`를 루트에서 import 한다.
+
+## CSS
+
+| 파일 | 용도 |
+|------|------|
+| [tokens.css](../src/tokens.css) | `:root` 변수, 다크 프리셋 |
+| [base.css](../src/base.css) | `.xfc-*` atoms 스타일 |
+
+## TypeScript
+
+`tokenVars`로 CSS 변수 이름을 문자열 상수로 참조할 수 있다. ([index.ts](../src/index.ts))
+
+```ts
+import { tokenVars } from '@xfilecom/front-core';
+document.body.style.setProperty(tokenVars.colorAccent, '#143c38');
+```

package/docs/DESIGN_SYSTEM.md

@@ -0,0 +1,32 @@
+# xframe design system vs Paper-style UI kits
+
+`@xfilecom/front-core`는 **브라우저 전용**이며 React Native(`react-native-paper`)나 MUI(`@mui/material`)와 동일한 패키지는 아니다. 대신 **같은 UX 패턴**(표면·높이·토큰)을 웹 CSS 변수 + 얇은 React atoms로 옮긴다.
+
+## 한눈에 비교
+
+| 개념 | MUI (`Paper`) | react-native-paper (`Surface`) | front-core |
+|------|---------------|---------------------------------|------------|
+| 표면/카드 | `Paper` + `elevation` | `Surface` + `elevation` | [`Paper`](../src/components/atoms/Paper.tsx) `elevation={0…4}` |
+| 구조형 카드 | `Card` | `Card` | [`Card`](../src/components/atoms/Card.tsx) (title/footer 슬롯) |
+| 버튼 | `Button` | `Button` | [`Button`](../src/components/atoms/Button.tsx) variants |
+| 다이얼로그 | `Dialog` | `Portal`+`Dialog` | [`Dialog`](../src/components/overlays/Dialog.tsx) |
+| 스낵바/토스트 | `Snackbar` | `Snackbar` | [`Toast`](../src/components/atoms/Toast.tsx) / [`ToastList`](../src/components/atoms/Toast.tsx) |
+| 테마 | `ThemeProvider` | `PaperProvider` | `:root` / `html.dark` **CSS 변수** + 선택적 `xfc-theme.css` |
+
+## Elevation (높이)
+
+- **MUI**: 그림자 깊이가 elevation 숫자에 대응.
+- **front-core**: `Paper`의 `elevation` 0~4가 `--xfc-shadow-xs` … `--xfc-shadow-lg`에 매핑된다. `variant="outlined"`는 그림자 없이 테두리만 (`outlined` variant).
+
+## 색 (Color roles)
+
+Material 3의 *primary / on-primary / surface* 같은 **역할 이름**은 npm 타입으로 강제하지 않고, `--xfc-accent`, `--xfc-bg-elevated`, `--xfc-fg` 등 **토큰 이름**으로 맞춘다. 다크 모드는 `html.dark` 또는 `data-theme="dark"` 한 번에 같은 변수를 덮어쓴다.
+
+## 언제 MUI / RN Paper를 쓰고 언제 front-core를 쓰나
+
+- **이미 MUI 생태계**를 쓰는 앱 → MUI 유지.
+- **xframe 스캐폴드**, 번들·의존성을 가볍게, Nest와 무관한 **순수 웹 atoms** → `front-core`.
+
+## 다음 문서
+
+- [COMPONENTS.md](./COMPONENTS.md) — 컴포넌트별 props·소스 경로·예제 코드

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xfilecom/front-core",
-  "version": "0.2.26",
+  "version": "0.2.28",
   "description": "Shared design tokens, base CSS, and atomic React components (browser-only; no Nest dependency)",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -21,7 +21,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "docs",
+    "README.md"
   ],
   "scripts": {
     "prepublishOnly": "npm run build",