sellmate-design-system-react 0.1.0

package/README.md

@@ -0,0 +1,65 @@
+# sellmate-design-system-react
+
+Sellmate 디자인 시스템의 React 포팅 (React + TypeScript + Tailwind v4).
+기존 Stencil 디자인 시스템(`@sellmate/design-system`)을 네이티브 React 컴포넌트로 이식합니다.
+
+> ⚠️ **소비 앱은 Tailwind CSS v4가 필요합니다.** (v3에서는 클래스가 purge되어 스타일이 적용되지 않습니다.)
+
+## 설치
+
+```bash
+npm install sellmate-design-system-react
+```
+
+## 사용법 (방식 1 — 권장)
+
+소비 앱의 전역 CSS에 다음을 추가합니다.
+
+```css
+/* app globals.css */
+@import "tailwindcss";
+@import "sellmate-design-system-react/theme.css";
+@source "../node_modules/sellmate-design-system-react/dist";
+```
+
+- `theme.css` — 디자인 토큰(`@theme`). 라이브러리와 앱이 같은 토큰을 공유합니다.
+- `@source` — 라이브러리 `dist`를 Tailwind 스캔 대상에 포함시켜 컴포넌트 클래스가 생성되게 합니다. **경로는 여러분의 CSS 파일 위치 기준 상대경로**이며, `node_modules` 전체가 아니라 반드시 이 패키지 `dist`만 지정하세요.
+
+```tsx
+import { Button } from "sellmate-design-system-react";
+
+export function Example() {
+  return (
+    <Button variant="primary" size="md" onClick={() => alert("clicked")}>
+      확인
+    </Button>
+  );
+}
+```
+
+## 사용법 (방식 2 — 폴백)
+
+Tailwind를 쓰지 않는 앱은 컴파일된 CSS를 직접 import 합니다.
+
+```ts
+import "sellmate-design-system-react/styles.css";
+```
+
+## 개발
+
+```bash
+npm install
+npm run build      # tsup(ESM+CJS+d.ts) + theme/styles CSS 컴파일 → dist/
+npm run dev        # 감시 모드
+npm run typecheck
+```
+
+## 설계 원칙
+
+- **Radix UI(헤드리스) + Tailwind v4 + CVA** — shadcn은 참조만
+- 단순 컴포넌트는 pure React, 복잡/오버레이는 Radix 기반
+- **sd-select**(검색형 콤보박스)만 예외적으로 `@ariakit/react` 사용
+- 폼 컴포넌트는 **form-agnostic** (`forwardRef` + 표준 `value`/`onChange`) — 특정 폼 라이브러리에 의존하지 않음
+- 다크모드 미지원 (단일 라이트 테마)
+
+자세한 계획은 `마이그레이션-플랜.md`, 컴포넌트별 API 매핑은 `Phase0-API매핑.md` 참고.