@x-plat/design-system 0.7.2 → 0.8.0

package/guidelines/AGENT_PROMPT.md

@@ -594,9 +594,9 @@ CSS 변수 `--semantic-{category}-{role}` 사용.
 | 카테고리 | 컴포넌트 |
 |---|---|
 | 입력 | `Button`, `Input`, `PasswordInput`, `TextArea`, `Select`, `CheckBox`, `Radio`, `Switch`, `DatePicker`, `Calendar` |
-| 표시 | `Table`, `Card`, `Tag`, `Chip`, `Avatar`, `NotificationBadge`, `Skeleton`, `Spinner`, `Divider`, `EmptyState`, `Progress` |
+| 표시 | `Table`, `Box`, `Tag`, `Chip`, `Avatar`, `NotificationBadge`, `Skeleton`, `Spinner`, `Divider`, `EmptyState`, `Progress` |
 | 오버레이 | `Modal`, `Drawer`, `PopOver`, `Tooltip`, `Alert`, `Toast` (`ToastProvider` 필요) |
-| 네비 | `Tab`, `CardTab`, `Breadcrumb`, `Pagination`, `Steps`, `Dropdown` |
+| 네비 | `Tab`, `CardTab`, `Breadcrumb`, `Pagination`, `Steps`, `Dropdown`, `Link`, `LinkButton` |
 | 미디어 | `Video`, `FileUpload`, `ImageSelector`, `Swiper` |
 | 기타 | `Accordion`, `Chart`, `HtmlTypeWriter` |
 

package/guidelines/Guidelines.md

@@ -60,12 +60,13 @@ React 기반 디자인 시스템 라이브러리이다. Figma Make Kit과 1:1
    - [DatePicker](./components/datepicker.md) - Calendar, DatePicker 4종
    - [Accordion](./components/accordion.md)
    - [Avatar](./components/avatar.md)
-   - [Card](./components/card.md)
+   - [Card → Box](./components/card.md)
    - [Chart](./components/chart.md)
    - [데이터 표시](./components/data-display.md) - Divider, EmptyState, Skeleton, Spinner
    - [Dropdown](./components/dropdown.md)
    - [파일 & 미디어](./components/file-media.md) - FileUpload, ImageSelector, Video
    - [Swiper](./components/swiper.md)
+   - [Link](./components/link.md)
    - [HtmlTypeWriter](./components/html-typewriter.md)
 4. **컴포지션**
    - [Grid](./composition/grid.md) - Grid 시스템, 위젯 패턴

package/guidelines/components/button.md

@@ -1,5 +1,59 @@
 # Button
 
+<!-- props:Button -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children * | `ReactNode` | - |  |
+| type | `"primary" \| "secondary" \| "danger" \| "ghost"` | `"primary"` |  |
+| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
+
+`*` = 필수
+<!-- /props:Button -->
+
+## 버튼 / 링크버튼 / 링크
+
+셋은 의미가 다르다. 생김새가 아니라 **무슨 일이 일어나는지**로 고른다.
+
+| 컴포넌트 | 렌더 | 쓰는 곳 |
+|---|---|---|
+| `Button` | `<button>` | 누르면 **무언가 일어난다** — 저장, 삭제, 모달 열기 |
+| `LinkButton` | `<a>` | **이동한다.** 버튼처럼 보여야 하는 자리 |
+| `Link` | `<a>` | **이동한다.** 본문 속 텍스트 링크 |
+
+```tsx
+<Button onClick={save}>저장</Button>
+<LinkButton href="/terms">약관 보기</LinkButton>
+<p>자세한 내용은 <Link href="/terms">약관</Link>을 확인하세요.</p>
+```
+
+이동하는 자리를 `<button>` 으로 만들면 **우클릭 메뉴·새 탭으로 열기·링크 미리보기가
+전부 막힌다.** 반대로 동작하는 자리를 `<a href="#">` 으로 만들면 주소가 바뀌고
+뒤로가기가 깨진다.
+
+`LinkButton` 은 `Button` 의 스타일시트를 그대로 쓴다. `type`·`size` 값도 같다.
+`width: 100%` 가 들어 있으니 내용만큼만 차지해야 하면 감싸는 요소에
+`width: fit-content` 를 준다.
+
+<!-- props:LinkButton -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children * | `ReactNode` | - |  |
+| href * | `string` | - |  |
+| type | `"primary" \| "secondary" \| "danger" \| "ghost"` | `"primary"` |  |
+| size | `"sm" \| "md" \| "lg"` | `"md"` |  |
+
+`*` = 필수
+표준 HTML 속성(`onClick`, `aria-*` 등 280개)도 그대로 전달된다.
+<!-- /props:LinkButton -->
+
+### 클래스를 직접 빌리지 말 것
+
+`<a className="lib-xplat-button primary md">` 는 동작하지만 클래스 이름이 바뀌면
+컴파일·런타임 에러 없이 **스타일만 조용히 빠진다.** `LinkButton` 을 쓴다.
+
+라우터 링크(`NextLink` 등)를 버튼처럼 보이게 해야 하는 경우는 아직 지원하지 않는다.
+필요해지면 알려달라.
+
 ## Type
 
 | type | 용도 |

package/guidelines/components/card.md

@@ -1,28 +1,24 @@
-# Card
+# Card → Box
 
-콘텐츠를 카드 형태로 감싸는 컨테이너이다.
+**`Card` 라는 컴포넌트는 없다.** 이 역할은 `Box` 가 한다.
 
 ```tsx
-import { Card } from "@x-plat/design-system";
-```
+import { Box } from "@x-plat/design-system";
 
-## Props
+<Box title="매출 현황">
+  <p>이번 달 매출: 1,200만원</p>
+</Box>
+```
 
+<!-- props:Box -->
 | Prop | 타입 | 기본값 | 설명 |
 |------|------|--------|------|
-| children `*` | `ReactNode` | — | 카드 본문 |
-| title | `string` | — | 카드 상단 제목 |
-
----
+| children * | `ReactNode` | - |  |
+| title | `ReactNode` | - |  |
+| variant | `"outlined" \| "elevated" \| "flat"` | - |  |
+| padding | `"none" \| "sm" \| "md" \| "lg"` | - |  |
 
-## 사용 예시
+`*` = 필수
+<!-- /props:Box -->
 
-```tsx
-<Card title="매출 현황">
-  <p>이번 달 매출: 1,200만원</p>
-</Card>
-
-<Card>
-  <p>제목 없는 카드</p>
-</Card>
-```
+`variant` 로 테두리/그림자 방식을, `padding` 으로 안쪽 여백을 정한다.

package/guidelines/components/link.md

@@ -0,0 +1,35 @@
+# Link
+
+본문 속 텍스트 링크. 크기·굵기는 **주변 텍스트를 그대로 물려받는다.**
+색과 밑줄만 정의한다.
+
+```tsx
+<p>자세한 내용은 <Link href="/terms">약관</Link>을 확인하세요.</p>
+<Link href="https://x.com" target="_blank">외부 문서</Link>
+```
+
+<!-- props:Link -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children * | `ReactNode` | - |  |
+| href * | `string` | - |  |
+| underline | `"always" \| "hover" \| "none"` | `"always"` | 밑줄 표시 방식. 기본은 `"always"`. 본문 속 링크는 색만으로 구분하면 색각 이상이 있는 사용자가 놓친다. 주변 텍스트와 확실히 구분되는 자리(내비게이션·목록 등)에서만 `"hover"` 나 `"none"` 으로 내린다. |
+
+`*` = 필수
+표준 HTML 속성(`onClick`, `aria-*` 등 281개)도 그대로 전달된다.
+<!-- /props:Link -->
+
+## underline
+
+기본값은 `"always"` 다. 본문 속 링크를 **색만으로 구분하면 색각 이상이 있는 사용자가
+놓친다.** 주변 텍스트와 확실히 구분되는 자리(내비게이션·목록 등)에서만 내린다.
+
+```tsx
+<Link href="/a">본문 링크</Link>                      {/* 항상 밑줄 */}
+<Link href="/a" underline="hover">목록 항목</Link>     {/* 호버 시에만 */}
+<Link href="/a" underline="none">내비게이션</Link>     {/* 없음 */}
+```
+
+- `target="_blank"` 면 `rel="noopener noreferrer"` 가 자동으로 붙는다.
+- 버튼처럼 보여야 하는 링크는 `LinkButton`, 누르면 무언가 일어나는 자리는 `Button` 이다.
+  [button.md](./button.md) 참고.

package/guidelines/components/overlay.md

@@ -52,7 +52,8 @@
 
 ## Tooltip
 
-부가 정보를 표시한다. **description이 필수이다.** children이 트리거이다.
+부가 정보를 표시한다. `children` 이 트리거다.
+`title` 과 `description` 중 **하나 이상**이 있어야 뜬다 (둘 다 없으면 children 만 렌더된다).
 
 ```tsx
 <Tooltip description="도움말 텍스트">
@@ -60,6 +61,34 @@
 </Tooltip>
 ```
 
+<!-- props:Tooltip -->
+| Prop | 타입 | 기본값 | 설명 |
+|------|------|--------|------|
+| children * | `ReactNode` | - |  |
+| title | `ReactNode` | - |  |
+| description | `ReactNode` | - |  |
+| type | `"dark" \| "light"` | `"dark"` |  |
+| follow | `boolean` | `false` | 커서를 따라다닌다. 기본값은 `false` — 트리거 요소 기준으로 고정된다 (PopOver/Dropdown/Select 와 같은 방식). 넓은 영역 안에서 **가리키는 지점**이 의미를 가질 때만 켠다. 버튼이나 아이콘처럼 대상이 작은 경우는 고정이 읽기 편하다. |
+| disabled | `boolean` | `false` |  |
+
+`*` = 필수
+<!-- /props:Tooltip -->
+
+### 위치 방식
+
+기본은 **트리거 요소 기준 고정**이다 (PopOver/Dropdown/Select 와 같은 방식).
+`follow` 를 주면 커서를 따라다닌다.
+
+```tsx
+<Tooltip description="..." follow>
+  <div className="wide-area">넓은 영역</div>
+</Tooltip>
+```
+
+넓은 영역 안에서 **가리키는 지점**이 의미를 가질 때만 `follow` 를 켠다.
+버튼·아이콘처럼 대상이 작으면 고정이 읽기 편하다.
+키보드 포커스로 뜰 때는 커서가 없으므로 `follow` 여부와 무관하게 트리거 기준으로 뜬다.
+
 ---
 
 ## 의사결정

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@x-plat/design-system",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "XPLAT UI Design System",
   "author": "XPLAT WOONG",
   "main": "dist/index.cjs",