@xfilecom/front-core 0.2.27 → 0.2.29

package/README.md

@@ -1,33 +1,63 @@
 # @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 요약, **복붙 예제 코드** |
+| [docs/SHADCN.md](./docs/SHADCN.md) | [shadcn/ui](https://ui.shadcn.com/) **대응표** — Radix 없이 쓰는 범위·앱 의존 권장 |
+
+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
 
-**Dark mode:** `tokens.css` 끝에 `html.dark` / `data-theme="dark"` 프리셋이 있다. 루트에 클래스 또는 속성만 켜면 동일 변수명으로 전환된다.
+```tsx
+import {
+  Paper,
+  Card,
+  Button,
+  Text,
+  Dialog,
+} from '@xfilecom/front-core';
+```
 
-**토큰:** `--xfc-shadow-xs|sm|md|lg`, `--xfc-accent-soft` 등 계층·글로우용 변수가 있다. `tokenVars`에서 TS로 참조 가능.
+서브패스: `@xfilecom/front-core/atoms`, `@xfilecom/front-core/overlays`.
 
-**배경:** `base.css`의 `body`는 아주 옅은 액센트 그라데이션을 쓴다. 단색만 원하면 앱 CSS에서 `body { background-image: none; }` 로 끈다.
+## 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).