@pylerai/design-system 1.2.3 → 2.0.0

package/README.md

@@ -1,120 +1,51 @@
 # @pylerai/design-system
 
-Pyler Frontend를 위한 디자인 시스템 패키지 (Tailwind CSS + shadcn/ui 기반)
+Pyler Frontend를 위한 디자인 시스템 패키지 (React + TypeScript + Tailwind CSS)
 
-## 📦 패키지 정보
-
-- **패키지명**: `@pylerai/design-system`
-- **버전**: ![npm version](https://img.shields.io/npm/v/@pylerai/design-system)
-- **라이선스**: ISC
-- **레지스트리**: npm (registry.npmjs.org, public)
-- **기술 스택**: React + TypeScript + Tailwind CSS + shadcn/ui + Storybook + Vitest
+📖 **[Storybook](https://pylerai.github.io/design-system/)** — 모든 컴포넌트의 렌더링 결과와 전체 prop 문서는 여기서 확인하세요.
 
-## 🚀 설치 및 사용
+> 이 README는 Storybook이 알려줄 수 없는 것(설치·Tailwind 연동·토큰 사용법·릴리스 절차)만 다룹니다.
+> 컴포넌트별 prop 목록은 Storybook autodocs가 소스에서 자동 생성하므로 여기에 중복해 적지 않습니다 —
+> 같은 내용을 두 곳에 두면 한쪽이 반드시 낡습니다.
 
-### 다른 프로젝트에서 사용하기
+## 📦 패키지 정보
 
-다른 레포지토리에서 이 디자인 시스템을 사용하려면 다음 단계를 따라하세요:
+- **패키지명**: `@pylerai/design-system` ![npm version](https://img.shields.io/npm/v/@pylerai/design-system)
+- **레지스트리**: public npm (`registry.npmjs.org`) — 별도 인증 불필요
+- **라이선스**: ISC
+- **peer 의존성**: React 18 또는 19
 
-#### 1. 패키지 설치
+> [CHANGELOG](./CHANGELOG.md) · [CONTRIBUTING](./CONTRIBUTING.md)
 
-public npm 레지스트리에 배포되어 있으므로 별도 인증 없이 바로 설치할 수 있습니다.
+## 🚀 설치
 
 ```bash
 npm install @pylerai/design-system
 ```
 
-> [CHANGELOG](./CHANGELOG.md) · [CONTRIBUTING](./CONTRIBUTING.md)
+### 1. 스타일 로드
 
-#### 2. Tailwind CSS 설정
+앱 진입점에서 한 번만 로드합니다.
 
-사용할 프로젝트의 `tailwind.config.js` / `tailwind.config.cjs` 파일에 다음을 추가하세요:
-
-```js
-module.exports = {
-  content: [
-    "./src/**/*.{js,jsx,ts,tsx}",
-    "./node_modules/@pylerai/design-system/**/*.{js,ts,jsx,tsx}", // 추가
-  ],
-  // ...
-};
+```typescript
+import "@pylerai/design-system/style.css";
 ```
 
-그리고 CSS 파일에 다음을 추가하세요:
+CSS 파일에서 `@import` 해도 동일합니다.
 
 ```css
 @tailwind base;
 @tailwind components;
 @tailwind utilities;
 
-/* 디자인 시스템 스타일 (컴포넌트 + Pyler 컬러 변수 등) */
 @import "@pylerai/design-system/style.css";
 ```
 
-앱 진입 TS/JS에서 한 번 로드하는 방식도 동일합니다.
-
-```typescript
-import "@pylerai/design-system/style.css";
-```
-
-> 구버전 번들러에서 서브패스가 동작하지 않으면 `@import "@pylerai/design-system/dist/style.css";` 또는 `import "@pylerai/design-system/dist/style.css";` 를 사용하세요.
-
-#### 3. 사용하기
-
-```typescript
-import { Button } from "@pylerai/design-system";
-
-function App() {
-  return (
-    <div className="p-4">
-      <Button>클릭하세요</Button>
-      <Button variant="outline">외곽선</Button>
-      <Button variant="destructive">삭제</Button>
-    </div>
-  );
-}
-```
-
-### 컬러 토큰 (Pyler Light)
-
-Figma Light 모드와 동일한 HEX를 **TypeScript 상수**, **CSS 변수 (`--ds-*`)**, **Tailwind `ds` 팔레트**로 제공합니다. 앱 코드에 HEX를 직접 쓰지 말고 패키지 토큰을 참조하세요.
-
-#### TypeScript에서 HEX·경로 사용
-
-```typescript
-import {
-  PYLER_LIGHT_COLOR_TOKENS,
-  flatPylerLightTokens,
-  getDsCssVar,
-} from "@pylerai/design-system";
-
-// 중첩 객체
-const strong = PYLER_LIGHT_COLOR_TOKENS.text.strong.hex; // "#333333"
-
-// 순회·문서화용 플랫 리스트
-flatPylerLightTokens.forEach(({ path, hex, cssVar }) => {
-  console.log(path, hex, cssVar);
-});
-
-// CSS 변수 이름
-getDsCssVar("text.strong"); // => "--ds-text-strong"
-```
-
-#### CSS 변수
-
-`style.css`를 로드한 뒤 임의 요소에 적용합니다.
-
-```css
-.my-title {
-  color: var(--ds-text-strong);
-  border-color: var(--ds-line-strong);
-  background-color: var(--ds-surface-normal);
-}
-```
+> 구버전 번들러에서 서브패스가 동작하지 않으면 `@pylerai/design-system/dist/style.css`를 사용하세요.
 
-#### Tailwind에서 `ds` 색상
+### 2. Tailwind 연동
 
-1. **프리셋 사용 (권장)** — `theme.extend.colors.ds`가 자동으로 합쳐집니다.
+프리셋을 사용하면 `ds` 컬러 팔레트·타이포그래피 스케일·radius·shadow가 한 번에 합쳐집니다.
 
 ```javascript
 // tailwind.config.cjs
@@ -126,303 +57,225 @@ module.exports = {
   ],
   theme: {
     extend: {
-      /* 기존 앱 전용 확장 */
+      /* 앱 전용 확장 */
     },
   },
 };
 ```
 
-2. **색상 맵만 병합** — 이미 `extend.colors`를 쓰는 경우:
+이미 `extend.colors`를 쓰고 있어 색상 맵만 필요하다면:
 
 ```javascript
 const { dsColors } = require("@pylerai/design-system/pyler-tailwind-colors");
 
 module.exports = {
-  theme: {
-    extend: {
-      colors: {
-        ds: dsColors,
-      },
-    },
-  },
+  theme: { extend: { colors: { ds: dsColors } } },
 };
 ```
 
-유틸 클래스 예: `bg-ds-primary-blue-normal`, `text-ds-text-strong`, `border-ds-line-normal`.
+클래스명을 `bg-ds-${color}`처럼 **동적으로 조합**하면 Tailwind의 content 스캔에 잡히지 않습니다. 그런 경우 앱 config에 safelist를 두세요.
 
-동적으로 `bg-ds-*`만 조합하는 경우 Tailwind가 클래스를 빼버릴 수 있으므로, 소비 앱 `tailwind.config`에 `safelist: [{ pattern: /^bg-ds-/ }]`를 두는 것을 권장합니다.
+```javascript
+safelist: [{ pattern: /^bg-ds-/ }],
+```
 
-스토리북 **Design Tokens → Color Tokens**에서 전체 스와치와 HEX를 확인할 수 있습니다.
+### 3. 사용
 
-## 🎨 컴포넌트
+```tsx
+import { Button, InputField, Toaster, toast } from "@pylerai/design-system";
 
-### Typography
+function App() {
+  return (
+    <div className="flex flex-col gap-4 p-4">
+      <InputField label="이메일" placeholder="you@pyler.tech" require />
+      <Button variant="filled" color="blue" size="lg" onClick={() => toast.success("저장했습니다")}>
+        저장
+      </Button>
+      <Toaster />
+    </div>
+  );
+}
+```
 
-일관된 타이포그래피를 위한 컴포넌트들입니다.
+## 🧩 컴포넌트
 
-#### Headline
+전체 목록입니다. **각 컴포넌트의 prop과 실제 렌더링은 [Storybook](https://pylerai.github.io/design-system/)에서 확인하세요.**
 
-페이지와 섹션의 제목을 위한 컴포넌트입니다.
+| 카테고리 | export |
+|---|---|
+| Action | `Button`, `ButtonIndicator`, `buttonVariants` |
+| Form | `InputField`, `TextField`, `SearchField`, `Dropdown`, `Checkbox`, `Radio`, `Toggle`, `Calendar` |
+| Data display | `Table`, `TableRoot`, `TableHead`, `TableBody`, `TableRow`, `TableHeaderCell`, `TableCell`, `Pagination` |
+| Status | `Badge`, `Tag`, `Chip`, `Tips`, `LoadingBar` |
+| Feedback | `Toaster`, `toast`, `snackbar`, `SnackbarContent` |
+| Overlay | `InformationModal`, `ActionModal`, `ContentModal`, `ModalProvider`, `useModal` |
+| Navigation | `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent` |
+| Typography | `Headline`, `Body`, `Label` (+ `headlineVariants`, `bodyVariants`, `labelVariants`) |
+| Types | `DsSize` (전역 사이즈 스케일) |
+| Tokens | `PYLER_LIGHT_COLOR_TOKENS`, `flatPylerLightTokens`, `PYLER_LIGHT_GROUP_ORDER`, `getDsCssVar`, `formatPylerPathForDisplay`, `PYLER_TYPOGRAPHY_STYLE` |
 
-```typescript
-import { Headline } from '@pylerai/design-system';
-
-// 기본 사용
-<Headline>페이지 제목</Headline>
-
-// Variant
-<Headline variant="h1-20">페이지/섹션 최상위 제목</Headline>
-<Headline variant="h1-20-m">보조 헤드라인</Headline>
-<Headline variant="h1-20-r">큰 본문/설명</Headline>
-<Headline variant="h2-18">섹션 제목</Headline>
-<Headline variant="h2-18-sb">섹션 보조 제목</Headline>
-<Headline variant="h2-18-r">크고 차분한 본문</Headline>
-
-// HTML 태그 지정
-<Headline as="h1">H1 태그로 렌더링</Headline>
-<Headline as="h2">H2 태그로 렌더링</Headline>
-```
+### 알아두면 좋은 것
 
-#### Body
+- **`size`는 전 컴포넌트가 `xs | sm | md | lg | xl` 스케일(`DsSize`)을 씁니다.** 컴포넌트마다 지원 범위는 다릅니다 — `Button`/`LoadingBar` `sm~xl`, `InputField`/`SearchField`/`Dropdown`/`ContentModal` `sm~lg`, `Badge`/`Chip`/`Tips` `sm~md`, `Tag` `xs~md`.
+- **`Checkbox`·`Radio`는 라벨 텍스트를 children으로 받습니다** (`<Checkbox>동의</Checkbox>`). 밖에서 `<label>`로 감싸면 label이 중첩됩니다.
+- **`Checkbox`·`Radio`·`Toggle`의 `onChange`는 네이티브 이벤트가 아니라 값을 직접 넘깁니다** (`(checked: boolean) => void`, Radio는 `(value: string) => void`). `react-hook-form`의 `register()` 스프레드와는 그대로 맞물리지 않으니 `Controller`를 쓰세요.
+- **`Checkbox`·`Radio`·`Toggle`·`Dropdown`은 제어 컴포넌트 전용**입니다(`defaultChecked`/`defaultValue` 미지원). `Tabs`만 제어·비제어를 모두 지원합니다.
+- **아이콘은 아직 export되지 않습니다.** Storybook `Foundation/Icon`에서 목록은 볼 수 있지만 패키지에서 import할 수는 없습니다. `Button`의 `leftIcon`/`rightIcon`에는 앱 쪽 아이콘을 넘겨야 합니다.
 
-본문 텍스트를 위한 컴포넌트입니다.
+## 🎨 디자인 토큰
 
-```typescript
-import { Body } from '@pylerai/design-system';
-
-// 기본 사용
-<Body>본문 텍스트입니다.</Body>
-
-// Variant
-<Body variant="b1-16">강조 본문</Body>
-<Body variant="b1-16-m">일반 본문(기본)</Body>
-<Body variant="b1-16-r">일반 본문(라이트)</Body>
-<Body variant="b2-14">작은 강조 본문</Body>
-<Body variant="b2-14-m">작은 본문/캡션</Body>
-<Body variant="b2-14-r">캡션/헬퍼텍스트</Body>
-<Body variant="b3-13-m">세부설명/테이블 셀</Body>
-<Body variant="b3-13-r">보조설명</Body>
-<Body variant="b4-12-m">메타/상태</Body>
-<Body variant="b4-12-r">아주 작은 본문</Body>
-
-// HTML 태그 지정
-<Body as="p">P 태그로 렌더링</Body>
-<Body as="div">DIV 태그로 렌더링</Body>
-```
+Figma Light 모드와 동일한 값을 **CSS 변수(`--ds-*`)**, **Tailwind `ds` 팔레트**, **TypeScript 상수** 세 가지 형태로 제공합니다. 앱 코드에 HEX를 직접 쓰지 말고 토큰을 참조하세요.
 
-#### Label
+> 세 형태의 값이 어긋나지 않도록 `npm run check:tokens`가 CI에서 정합성을 검사합니다.
 
-폼 요소나 작은 텍스트 라벨을 위한 컴포넌트입니다.
+### 컬러
 
-```typescript
-import { Label } from '@pylerai/design-system';
+Tailwind 유틸리티가 가장 일반적입니다.
+
+```tsx
+<div className="bg-ds-surface-normal border border-ds-line-normal text-ds-text-strong" />
+```
+
+CSS 변수로도 쓸 수 있습니다.
 
-// 기본 사용
-<Label>라벨 텍스트</Label>
+```css
+.my-title {
+  color: var(--ds-text-strong);
+  background-color: var(--ds-surface-normal);
+}
+```
 
-// Variant
-<Label variant="l1-10-sb">라벨/태그</Label>
-<Label variant="l1-10-r">라벨(비강조)</Label>
+TypeScript에서 HEX 값이나 변수명이 필요하면:
 
-// 폼과 함께 사용
-<Label htmlFor="email">이메일 주소</Label>
-<input id="email" type="email" />
+```typescript
+import { PYLER_LIGHT_COLOR_TOKENS, flatPylerLightTokens, getDsCssVar } from "@pylerai/design-system";
+
+PYLER_LIGHT_COLOR_TOKENS.text.strong.hex; // "#333333"
+getDsCssVar("text.strong");               // "--ds-text-strong"
+flatPylerLightTokens.forEach(({ path, hex, cssVar }) => { /* 문서화·순회용 */ });
 ```
 
-### Button
+토큰 그룹: `primitive` · `main` · `background` · `text` · `line` · `surface` · `primary`(blue/red/green × normal/hovered/disabled/muted) · `category` · `icon`.
+전체 스와치와 HEX는 Storybook **Foundation → Color**에서 확인하세요.
+
+### 타이포그래피
+
+| 스케일 | 크기 | 굵기 | Tailwind | 순수 CSS 클래스 |
+|---|---|---|---|---|
+| Title 1 SB | 24px | 600 | `text-title-1-sb` | `.ds-type-title-1-sb` |
+| Title 1 M | 24px | 500 | `text-title-1-m` | `.ds-type-title-1-m` |
+| Title 2 SB | 20px | 600 | `text-title-2-sb` | `.ds-type-title-2-sb` |
+| Body 1 M | 16px | 500 | `text-body-1-m` | `.ds-type-body-1-m` |
+| Body 1 R | 16px | 400 | `text-body-1-r` | `.ds-type-body-1-r` |
+| Body 2 SB | 14px | 600 | `text-body-2-sb` | `.ds-type-body-2-sb` |
+| Body 2 M | 14px | 500 | `text-body-2-m` | `.ds-type-body-2-m` |
+| Body 2 R | 14px | 400 | `text-body-2-r` | `.ds-type-body-2-r` |
+| Body 3 M | 13px | 500 | `text-body-3-m` | `.ds-type-body-3-m` |
+| Body 3 R | 13px | 400 | `text-body-3-r` | `.ds-type-body-3-r` |
+| Body 4 M | 12px | 500 | `text-body-4-m` | `.ds-type-body-4-m` |
+| Body 4 R | 12px | 400 | `text-body-4-r` | `.ds-type-body-4-r` |
+| Label 1 R | 11px | 400 | `text-label-1-r` | `.ds-type-label-1-r` |
+
+폰트는 Pretendard JP(`--ds-font-sans`)를 사용합니다. 앱에서 웹폰트를 별도로 로드해야 합니다.
+
+컴포넌트로 쓸 수도 있습니다. `as`로 태그를, `asChild`로 자식 요소에 스타일만 입힐 수 있습니다.
+
+```tsx
+<Headline variant="title-1-sb" as="h1">페이지 제목</Headline>
+<Body variant="body-2-r">본문</Body>
+<Label variant="label-1-r" htmlFor="email">이메일</Label>
+
+<Headline asChild variant="title-2-sb">
+  <a href="/docs">래퍼 없이 링크에 타이틀 스타일만</a>
+</Headline>
+```
 
-다양한 variant와 size를 지원하는 버튼 컴포넌트입니다.
+Chakra UI·Emotion 등 CSS-in-JS에서는 `PYLER_TYPOGRAPHY_STYLE`을 `textStyle`/`sx`에 그대로 넘기면 됩니다.
 
 ```typescript
-import { Button } from '@pylerai/design-system';
-
-// 기본 사용
-<Button>클릭하세요</Button>
-
-// Variant
-<Button variant="default">기본</Button>
-<Button variant="destructive">삭제</Button>
-<Button variant="outline">외곽선</Button>
-<Button variant="secondary">두 번째</Button>
-<Button variant="ghost">고스트</Button>
-<Button variant="link">링크</Button>
-
-// Size
-<Button size="sm">작은 버튼</Button>
-<Button size="default">기본</Button>
-<Button size="lg">큰 버튼</Button>
-<Button size="icon">🔍</Button>
-
-// 조합
-<Button variant="outline" size="lg">외곽선 큰 버튼</Button>
-```
+import { PYLER_TYPOGRAPHY_STYLE } from "@pylerai/design-system";
 
-## 📏 타이포그래피 스케일
+<Text sx={PYLER_TYPOGRAPHY_STYLE.body2R}>본문</Text>
+```
 
-### 디자인 토큰
+### Radius · Shadow · Dim
 
-| Token | Size(px) | Weight | Tailwind class | 용도 |
-|-------|----------|--------|----------------|------|
-| H1-20B | 20 | 700 | text-h1-20 | 페이지/섹션 최상위 제목 |
-| H1-20M | 20 | 500 | text-h1-20-m | 보조 헤드라인 |
-| H1-20R | 20 | 400 | text-h1-20-r | 큰 본문/설명 |
-| H2-18B | 18 | 700 | text-h2-18 | 섹션 제목 |
-| H2-18SB | 18 | 600 | text-h2-18-sb | 섹션 보조 제목 |
-| H2-18R | 18 | 400 | text-h2-18-r | 크고 차분한 본문 |
-| B1-16B | 16 | 700 | text-b1-16 | 강조 본문 |
-| B1-16M | 16 | 500 | text-b1-16-m | 일반 본문(기본) |
-| B1-16R | 16 | 400 | text-b1-16-r | 일반 본문(라이트) |
-| B2-14B | 14 | 700 | text-b2-14 | 작은 강조 본문 |
-| B2-14M | 14 | 500 | text-b2-14-m | 작은 본문/캡션 |
-| B2-14R | 14 | 400 | text-b2-14-r | 캡션/헬퍼텍스트 |
-| B3-13M | 13 | 500 | text-b3-13-m | 세부설명/테이블 셀 |
-| B3-13R | 13 | 400 | text-b3-13-r | 보조설명 |
-| B4-12M | 12 | 500 | text-b4-12-m | 메타/상태 |
-| B4-12R | 12 | 400 | text-b4-12-r | 아주 작은 본문 |
-| L1-10SB | 10 | 600 | text-l1-10-sb | 라벨/태그 |
-| L1-10R | 10 | 400 | text-l1-10-r | 라벨(비강조) |
+```tsx
+<div className="rounded-ds-md shadow-ds-default" />   // radius: xs(2) ss(4) md(8) lg(12)
+                                                       // shadow: ds-default, ds-modal
+```
 
-### 사용 가이드라인
+Dim은 `var(--ds-dim-default)`로 제공됩니다. Storybook **Foundation → Radius / Shadow / Dim** 참고.
 
-#### ✅ 권장사항
+## ♿ 접근성
 
-- **계층 구조 유지**: H1 → H2 → H3 순서로 헤딩을 사용하고, 각 레벨의 용도를 일관되게 유지하세요.
-- **충분한 대비**: 텍스트와 배경 간 충분한 색상 대비를 확보하여 가독성을 보장하세요.
-- **적절한 라인 높이**: 본문 텍스트는 1.4~1.6의 라인 높이를 사용하여 가독성을 높이세요.
+`@storybook/addon-a11y`(axe)가 모든 스토리에서 실행되며 **위반이 있으면 CI가 실패**합니다(`npm test`).
 
-#### ❌ 주의사항
+키보드 조작 요약:
 
-- **과도한 변형 사용**: 너무 많은 폰트 크기와 굵기를 혼용하면 일관성이 떨어집니다.
-- **너무 작은 텍스트**: 10px 이하의 텍스트는 가독성과 접근성 문제를 일으킬 수 있습니다.
-- **의미 없는 굵기 변경**: 단순히 강조를 위해 굵기를 변경하지 말고, 의미 있는 계층 구조를 사용하세요.
+| 컴포넌트 | 키보드 |
+|---|---|
+| `Modal` | 포커스 트랩, 열 때 포커스 진입 / 닫을 때 복원, `Esc` 닫기, 스크롤 잠금. 모달이 쌓이면 `Esc`는 최상단만 닫습니다 |
+| `Dropdown` | `↑`/`↓`/`Home`/`End` 이동, `Enter`/`Space` 선택, `Esc` 닫기 |
+| `Tabs` | `←`/`→`/`Home`/`End` 이동(선택 동시 적용), `Tab`은 탭 목록을 통과 |
+| `Table` | 정렬 헤더에 포커스 이동 후 `Enter`/`Space`로 정렬, `aria-sort` 노출 |
 
-### 접근성
+라벨이 필요한 컴포넌트:
 
-모든 타이포그래피 컴포넌트는 WCAG 2.1 AA 기준을 준수합니다:
+- `Checkbox`·`Radio`는 자체적으로 `<label>`을 렌더합니다. **밖에서 `<label>`로 감싸지 마세요** — label이 중첩되어 연결이 깨집니다. 텍스트는 children으로 넘기고(`<Checkbox>동의</Checkbox>`), 텍스트가 없으면 `aria-label`을 지정하세요.
+- `Toggle`, 아이콘 전용 `Button`, 라벨 없는 `Dropdown`/`SearchField`에는 `aria-label`이 필요합니다.
 
-- **색상 대비**: 최소 4.5:1의 대비율 유지
-- **헤딩 계층**: 올바른 HTML 헤딩 태그 사용
-- **스크린 리더**: 의미 있는 텍스트와 라벨 제공
-- **키보드 네비게이션**: 포커스 표시 및 키보드 접근성 지원
+> ⚠️ **컬러 대비는 아직 WCAG AA를 충족하지 못합니다.** `--ds-text-normal`(#969696)은 흰 배경에서 2.95:1, `--ds-text-disabled`(#cccccc)는 1.6:1, 흰 글자 + `--ds-primary-blue-normal`(#2c80f5)은 3.8:1로 기준(4.5:1)에 미달합니다. 토큰을 바꾸면 제품 전체 색이 바뀌므로 디자이너 결정이 필요한 사안이며, 그때까지 axe의 `color-contrast` 규칙만 꺼 둔 상태입니다(`.storybook/preview.ts`).
 
 ## 📁 프로젝트 구조
 
 ```
 design-system/
-├── .storybook/
-│   ├── main.cjs                    # Storybook 메인 설정 (CJS — Vite/Storybook 호환)
-│   ├── preview.ts                  # Storybook 미리보기 설정
-│   └── vitest.setup.ts            # Vitest 테스트 설정
-├── .github/
-│   └── workflows/
-│       └── release-package.yml     # GitHub Actions 릴리스 워크플로우
+├── .storybook/                     # Storybook 설정 (main/preview/vitest.setup)
+├── .github/workflows/
+│   ├── pr-checks.yml               # PR 검증 (tokens → lint → tsc → test → build)
+│   └── deploy-github-pages.yml     # Storybook 배포
+├── scripts/
+│   └── check-tokens.cjs            # 토큰 정합성 검사
 ├── src/
-│   ├── components/
-│   │   ├── ui/
-│   │   │   ├── button.tsx         # Button 컴포넌트 구현
-│   │   │   └── button.stories.tsx # Button Storybook 스토리
-│   │   └── Button.tsx              # Button export
-│   ├── stories/                    # Storybook 데모 컴포넌트
-│   │   ├── assets/                # 데모용 이미지/아이콘
-│   │   ├── Button.tsx             # 데모 Button
-│   │   ├── Button.stories.ts      # Button 스토리
-│   │   ├── Header.tsx             # 데모 Header
-│   │   ├── Header.stories.ts      # Header 스토리
-│   │   ├── Page.tsx               # 데모 Page
-│   │   ├── Page.stories.ts        # Page 스토리
-│   │   └── *.css                  # 데모 스타일
+│   ├── components/ui/              # 컴포넌트 + *.stories.tsx (스토리가 곧 테스트)
 │   ├── lib/
-│   │   └── utils.ts               # 유틸리티 함수 (cn, clsx)
-│   ├── index.css                   # Tailwind CSS 스타일
-│   ├── index.css.ts                # CSS 타입 정의
+│   │   ├── icons.tsx               # 내부 아이콘 (아직 미export)
+│   │   └── utils.ts                # cn() — clsx + tailwind-merge
+│   ├── tokens/
+│   │   ├── pyler-light.ts          # 컬러 토큰 (TS)
+│   │   └── typography.ts           # 타이포 토큰 (CSS-in-JS용)
+│   ├── index.css                   # --ds-* CSS 변수 + 타이포 유틸리티 (실제 값)
 │   └── index.tsx                   # 패키지 진입점
-├── components.json                 # shadcn/ui 설정
-├── tailwind.config.cjs            # Tailwind CSS 설정
-├── postcss.config.js              # PostCSS 설정
-├── tsconfig.json                   # TypeScript 설정
-├── tsconfig.node.json              # TypeScript Node 설정
-├── vite.config.ts                  # Vite 설정
-├── vitest.shims.d.ts              # Vitest 타입 정의
-└── package.json                    # 패키지 정보
+├── pyler-tailwind-colors.cjs       # Tailwind ds 컬러 맵
+├── pyler-typography.cjs            # Tailwind 타이포 스케일
+├── tailwind-preset.cjs             # 소비 앱용 프리셋
+└── eslint.config.js
 ```
 
-### 주요 디렉토리 설명
-
-- **`src/components/`**: 실제 디자인 시스템 컴포넌트들이 위치
-
-  - `ui/`: shadcn/ui 기반 컴포넌트 구현
-  - 컴포넌트 export 파일들
-
-- **`src/stories/`**: Storybook 데모 및 예제 컴포넌트들
-
-  - 실제 패키지에는 포함되지 않으며 개발/테스트 용도
-  - Button, Header, Page 등의 데모 컴포넌트
-
-- **`src/lib/`**: 공통 유틸리티 함수
-
-  - `utils.ts`: class-variance-authority, clsx, tailwind-merge를 사용한 `cn` 함수
-
-- **`.storybook/`**: Storybook 설정 파일
-  - Vitest 통합
-  - addons: a11y, docs, onboarding, vitest
-
 ## 🔧 개발
 
-### 로컬 개발
-
 ```bash
-# 의존성 설치
 npm install
-
-# 개발 서버 실행 (테스트용)
-npm run dev
-
-# 빌드
+npm run storybook        # http://localhost:6006
+npm test                 # 스토리의 play 함수를 vitest로 실행
+npm run lint
+npm run check:tokens
 npm run build
-
-# 테스트 실행
-npm test
 ```
 
-### Storybook 개발
-
-컴포넌트를 개발하고 테스트하기 위해 Storybook을 사용할 수 있습니다.
+이 저장소는 **별도 테스트 파일을 두지 않고 Storybook 스토리의 `play` 함수를 테스트로 실행**합니다(`@storybook/addon-vitest`). 스토리를 추가하면 그 자체로 렌더 스모크 테스트가 되고, 핵심 상호작용에는 `play`를 작성합니다.
 
-```bash
-# Storybook 개발 서버 실행
-npm run storybook
-
-# Storybook 빌드
-npm run build-storybook
-```
-
-Storybook은 `http://localhost:6006`에서 실행됩니다.
-
-컴포넌트 스토리는 `src/components/**/*.stories.tsx` 경로에 생성됩니다.
+새 컴포넌트를 추가하는 순서와 PR 절차는 [CONTRIBUTING](./CONTRIBUTING.md)을 참고하세요.
 
 ## 📤 배포
 
-이 프로젝트는 `npm run publish:npm` 실행을 통해 public npm 레지스트리(`registry.npmjs.org`)로 배포됩니다.
-
-### 배포 프로세스
-
-1. **버전 업데이트**: `package.json`의 `version`을 올립니다.
-2. **배포 실행**:
+`main`은 브랜치 보호로 직접 push할 수 없습니다. 버전 릴리스 절차(버전 범프 → CHANGELOG → 태그 → `npm run publish:npm`)는 [CONTRIBUTING](./CONTRIBUTING.md)에 정리돼 있습니다.
 
-```bash
-npm run publish:npm
-```
-
-이 스크립트는 `npm run build`로 패키지를 빌드한 뒤, `npm publish --access public`으로 `@pylerai/design-system`을 public 스코프로 퍼블리시합니다.
-
-> ⚠️ `.github/workflows/release-package.yml`은 GitHub Release가 생성될 때 트리거되어 GitHub Packages(`npm.pkg.github.com`)로도 별도 퍼블리시를 시도하는 워크플로우입니다. 현재 실제 배포는 위 수동 `npm run publish:npm` 경로로만 이루어지고 있어 이 워크플로우와 실제 배포 방식이 어긋나 있습니다. GitHub Release를 생성하면 의도치 않게 GitHub Packages 쪽에도 배포가 실행될 수 있으니 주의하세요 (워크플로우 자체 정리는 별도 후속 작업 — [CONTRIBUTING](./CONTRIBUTING.md) 참고).
+> ⚠️ `.github/workflows/release-package.yml`은 GitHub Release 생성 시 GitHub Packages로 배포하도록 되어 있으나, 실제 배포는 public npm으로 수동 실행하는 방식입니다. 한 번도 실행된 적 없는 워크플로이며 정리 대상입니다. 자세한 경위는 [CONTRIBUTING](./CONTRIBUTING.md#알려진-이슈-release-packageyml-워크플로-범위-외) 참고.
 
 ## 🔗 링크
 
+- **Storybook**: https://pylerai.github.io/design-system/
 - **Repository**: https://github.com/pylerAI/design-system
 - **Issues**: https://github.com/pylerAI/design-system/issues
-- **Homepage**: https://github.com/pylerAI/design-system#readme
-
-## 📄 라이선스
-
-ISC

package/dist/components/ui/badge.d.ts

@@ -1,6 +1,7 @@
+import { DsSize } from '../../lib/size';
 import * as React from "react";
 export type BadgeColor = "normal" | "neutral" | "negative" | "positive";
-export type BadgeSize = "medium" | "small";
+export type BadgeSize = Extract<DsSize, "md" | "sm">;
 export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
     color?: BadgeColor;
     size?: BadgeSize;

package/dist/components/ui/badge.js

@@ -0,0 +1,49 @@
+"use client";
+import { jsx as x } from "react/jsx-runtime";
+import { cn as i } from "../../lib/utils.js";
+import * as l from "react";
+const b = {
+  normal: {
+    border: "border-ds-primary-blue-normal",
+    text: "text-ds-primary-blue-normal"
+  },
+  neutral: {
+    border: "border-ds-line-strong",
+    text: "text-ds-text-strong"
+  },
+  negative: {
+    border: "border-ds-primary-red-normal",
+    text: "text-ds-primary-red-normal"
+  },
+  positive: {
+    border: "border-ds-primary-green-normal",
+    text: "text-ds-primary-green-normal"
+  }
+}, c = {
+  md: { padding: "px-2 pt-[5px] pb-[3px]", text: "text-body-3-m" },
+  sm: { padding: "px-1 pt-[3px] pb-[1px]", text: "text-label-1-r" }
+}, g = l.forwardRef(
+  ({ color: r = "normal", size: e = "md", className: t, children: o, ...d }, a) => {
+    const { border: s, text: n } = b[r], { padding: p, text: m } = c[e];
+    return /* @__PURE__ */ x(
+      "span",
+      {
+        ref: a,
+        className: i(
+          "inline-flex items-center justify-center border rounded-[4px] bg-ds-background-default whitespace-nowrap",
+          s,
+          p,
+          n,
+          m,
+          t
+        ),
+        ...d,
+        children: o
+      }
+    );
+  }
+);
+g.displayName = "Badge";
+export {
+  g as Badge
+};