@nurihaus/web-design-system 3.0.0 → 3.0.3

package/README.md

@@ -1,9 +1,11 @@
-# design-system-lab
+# @nurihaus/web-design-system
 
-## 설치와 사용 (3.x)
+## 설치와 사용 (4.x)
+
+`radix-ui` 는 peerDependency 다. 함께 설치한다.
 
 ```bash
-npm i @nurihaus/web-design-system
+npm i @nurihaus/web-design-system radix-ui
 ```
 
 CSS 는 JS 에 들어 있지 않다. 앱에서 한 번 가져온다.
@@ -12,10 +14,58 @@ CSS 는 JS 에 들어 있지 않다. 앱에서 한 번 가져온다.
 // 토큰만 (CSS Modules 로 직접 화면을 짤 때). 가져와도 화면이 바뀌지 않는다.
 import '@nurihaus/web-design-system/tokens.css';
 
-// 토큰 + 글꼴 + 리셋 + 컴포넌트 스타일 (디자인 시스템 컴포넌트를 쓸 때)
+// 토큰 + 글꼴 스택 + 리셋 + 컴포넌트 스타일 (디자인 시스템 컴포넌트를 쓸 때)
 import '@nurihaus/web-design-system/styles.css';
 ```
 
+글꼴 파일은 앱이 불러온다. 디자인 시스템은 글꼴을 내려받지 않는다. `styles.css` 의 `.nuri-theme` 는 앱이 Pretendard 를 불러왔으면 Pretendard 를 먼저 쓰고, 없으면 시스템 글꼴로 넘어간다. 스택은 `font-family` 이름 `Pretendard` 로 찾는다. 앱이 다른 이름으로 불러오면(예: 이름을 해시로 바꾸는 도구) `.nuri-theme` 의 `font-family` 를 앱에서 덮어쓴다.
+
+`.nuri-theme` 글꼴 스택도 필요 없으면 나눠서 가져온다. 컴포넌트 글자는 앱의 글꼴을 물려받는다.
+
+```ts
+import '@nurihaus/web-design-system/tokens.css';
+import '@nurihaus/web-design-system/reset.css';       // 필요할 때만
+import '@nurihaus/web-design-system/components.css';  // 유틸리티 + 컴포넌트. 글꼴 스택 없음
+```
+
+## 컴포넌트별 import
+
+컴포넌트 경로로 가져온다. 루트(`@nurihaus/web-design-system`)는 radix primitive 를 전부 참조해, 앱 번들러가 쓰지 않는 primitive 를 걷어내지 못한다. Tooltip 하나만 쓰는 Next 15 페이지의 first-load JS 를 쟀다: 루트 import 149 kB, 컴포넌트 경로 122 kB, radix Tooltip 만 직접 쓴 페이지 119 kB, 빈 페이지 102 kB (3.0.1 루트 import 는 140 kB).
+
+```ts
+import Tooltip, { TooltipProvider } from '@nurihaus/web-design-system/tooltip';
+import CollapsibleMenu from '@nurihaus/web-design-system/collapsible-menu';
+import { Spinner } from '@nurihaus/web-design-system/loading'; // loading 은 이름 있는 export 3개
+```
+
+경로는 파일 이름이다: `avatar`, `cta-button`, `option-badge`, `icon-text-badge`, `icon-text-option-badge`, `data-table`, `text-field`, `radio`, `check-box`, `drop-down`, `collapsible-menu`, `text`, `tooltip`, `tabs`, `modal-with-double-button`, `loading`. `loading` 밖에는 default export 다. 루트와 컴포넌트 경로를 섞어 쓰면 같은 코드가 두 번 들어가므로 한 방식으로 통일한다. `TooltipProvider` 는 어디서 가져와도 모든 경로의 툴팁에 닿는다.
+
+## 이 변경으로 올리기
+
+1. `radix-ui` 를 설치한다. 이전 배포본은 번들에 넣어 배포했고 이제는 앱의 것을 쓴다.
+
+   ```bash
+   npm i radix-ui
+   ```
+
+2. 글꼴을 앱이 불러온다. 이전 `styles.css` 는 jsDelivr(Pretendard) · Google Fonts(Roboto, Material Icons) CSS 를 `@import` 했다. 이제는 아무것도 불러오지 않는다. Pretendard 를 앱에서 불러오지 않으면 시스템 글꼴로 보인다. Material Icons 글꼴에 기대던 화면이 있으면 앱에서 직접 불러온다.
+
+3. 루트 import 를 컴포넌트별 import 로 바꾼다. 루트 import 는 그대로 동작하지만 이전 배포본보다 first-load JS 가 크다 (위 측정).
+
+배경은 `docs/decisions/0002-fonts-out-radix-peer-per-component-entries.md`.
+
+## 크기 이름 바꾸기
+
+크기 이름은 모든 컴포넌트가 `xs · s · m · l · xl` 하나를 쓴다. 숫자는 `styles/token/size.css` 에 있다. 높이는 바뀌지 않는다. button `r` 만 없어졌다.
+
+| 컴포넌트 | 바꿀 것 |
+| --- | --- |
+| CTAButton | `size="r"` → `size="m"` (48px → 50px) |
+| DropDown, TextField, CollapsibleMenu | `m` → `s`, `l` → `m` |
+| OptionBadge, IconTextBadge, IconTextOptionBadge | `l` → `xl`, `m` → `l`, `r` → `m`, `sm` → `xs` (`s` 는 그대로) |
+
+찾아 바꾸기는 표에 적힌 순서대로 한다. 순서를 바꾸면 이미 바꾼 이름이 한 번 더 바뀐다(DropDown 에서 `l` → `m` 을 먼저 하면 그 `m` 이 다시 `s` 가 된다). 크기 prop 타입은 `import type { Size } from '@nurihaus/web-design-system'`. 배경은 `docs/decisions/0003-shared-size-scale-and-numeric-tokens.md`.
+
 ```css
 /* CSS Modules 에서 */
 .card {
@@ -39,6 +89,23 @@ JS 토큰이 필요하면.
 import { primitive, semanticApp } from '@nurihaus/web-design-system/tokens';
 ```
 
+## 색 prop 바꾸기
+
+색 prop 은 Text 의 `color` 하나만 남았다. 뱃지는 `variant` 로 색을 고르고, 로딩 링은 CSS `color` 를 따른다. TypeScript 가 지운 prop 을 막는다.
+
+| 컴포넌트 | 이전 | 지금 |
+| --- | --- | --- |
+| OptionBadge, IconTextBadge, IconTextOptionBadge | 색 prop 없음 (검정 글자 · 흰 배경) | `variant="neutral"` (기본값이라 생략) |
+| | `color="purple-900" backgroundColor="purple-50"` | `variant="primary"` |
+| | `color="accent-red-700" backgroundColor="accent-red-50"` | `variant="danger"` |
+| | `borderColor="grey-scale-300"` | `variant="outlined"` |
+| | 그 밖의 `color` · `backgroundColor` · `borderColor` | 가까운 `variant` 를 고르거나 `className` 으로 덮는다 |
+| Spinner | `color="purple-900"` | `style={{ color: 'var(--color-purple-900)' }}` 또는 `color` 를 주는 `className` |
+| InlineLoading | `indicatorColor="purple-900"` | Spinner 와 같다 |
+| OverlayLoading | `spinnerColor="purple-900"` | `className="my-overlay"` 를 주고 `.my-overlay .base-spinner { color: var(--color-purple-900); }` |
+
+뱃지의 variant 규칙은 `.option.variant-primary` 처럼 클래스 두 개(0-2-0)다. `className` 으로 색을 덮을 때는 선택자를 그보다 구체적으로 쓰거나 `style` 을 쓴다. 로딩의 기본 색은 우선순위 0 이라 어떤 `className` 이든 이긴다. 감싸는 요소의 `color` 는 물려받지 않는다. 배경은 `docs/decisions/0004-badge-variants-and-loading-currentcolor.md`.
+
 ## 토큰 고치기
 
 원본은 `tokens/figma.json` 하나다. Tokens Studio 가 그 파일을 갱신하면 생성만 다시 돌린다.
@@ -47,4 +114,36 @@ import { primitive, semanticApp } from '@nurihaus/web-design-system/tokens';
 npm run tokens   # figma.json → tokens/generated/{tokens.css, *.ts}
 ```
 
-`tokens/generated/` 와 `styles/token/*.css` 를 손으로 고치지 않는다. 배경은 `docs/decisions/0001-tokens-in-ds-and-separate-css.md`.
+`tokens/generated/` 를 손으로 고치지 않는다. 배경은 `docs/decisions/0001-tokens-in-ds-and-separate-css.md`.
+
+새 서비스가 다른 의미 토큰 값(버튼 색 등)을 써야 하면 `tokens/figma.json` 에 `semantic_{이름}` 세트를 추가하고 `npm run tokens` 를 돌린다. `<html data-ds-theme="{이름}">` 로 고르는 테마가 생긴다. 자세한 규칙은 `docs/tokens.md`.
+
+## AI 설명서
+
+배포물의 `dist/ai/` 에 쓰는 쪽 AI 가 읽는 설명서가 들어 있다.
+
+| 파일 | 내용 | 원본 |
+| --- | --- | --- |
+| `dist/ai/components.md` | 공통 규칙, 공개 컴포넌트마다 import · 사용법 · 예시 · props 표, 아직 없는 컴포넌트 목록 | 공통 규칙은 `components/common.md`, props 표는 타입, 사용법은 각 폴더 `usage.md`, 없는 목록은 `components/not-yet.md` |
+| `dist/ai/tokens.md` | CSS 변수 전체와 테마별 의미 토큰, 크기·레이어·모션 토큰 | `tokens/figma.json`, `styles/token/size.css` |
+
+쓰는 쪽에서는 `node_modules/@nurihaus/web-design-system/dist/ai/` 경로로 읽는다. `usage.md` 섹션이 없거나 예시가 타입 검사에 실패하면 `npm run build` 가 멈춘다.
+
+## 배포
+
+`main` 으로 가는 PR 마다 CI 가 돈다. `yarn lint` · `yarn typecheck` · `yarn test` · `yarn build` · `yarn build-storybook` 중 하나라도 실패하면 빨간불이다. Node 버전은 `.nvmrc`(20), 패키지 매니저는 Yarn 3 하나다(`corepack enable` 후 `yarn`).
+
+배포는 GitHub 에서 한다. Actions 탭 → Release → Run workflow → `patch` · `minor` · `major` 중 하나를 고른다. 워크플로우는 아래 순서로 돈다.
+
+1. 다음 버전 태그가 이미 origin 에 있으면 멈춘다. 반대로 지금 버전이 태그만 있고 npm 에 없으면(이전 배포가 publish 에서 실패) 버전을 올리지 않고 그 버전을 그대로 올린다.
+2. CI 와 같은 검사(lint · typecheck · test · build)를 돌린다.
+3. `npm version` 으로 버전 커밋(`3.1.0`)과 태그(`v3.1.0`)를 만들어 `main` 에 푸시한다.
+4. npm 에 올리고 GitHub Release 를 만든다(변경 내역은 PR 에서 자동 생성).
+
+검사가 실패하면 버전이 오르지 않고, 푸시가 막히면 npm 에 올리지 않는다. publish 에서 실패했으면 원인을 고치고 버튼을 다시 누르면 같은 버전이 올라간다.
+
+처음 한 번 준비할 것:
+
+- npmjs.com 의 `@nurihaus/web-design-system` 패키지 Settings → Trusted Publisher 에 GitHub Actions 를 등록한다. Organization `NURIHAUS-Dev`, Repository `nuri-web-design-system`, Workflow filename `release.yml`. 토큰은 쓰지 않는다.
+- `main` 보호 규칙(ruleset)이 GitHub Actions 의 푸시를 허용해야 한다. 막혀 있으면 3단계에서 멈춘다.
+- 스토리북 배포는 선택이다. Settings → Pages → Source 를 GitHub Actions 로 켜면 `main` 푸시마다 스토리북이 Pages 에 올라간다. 켜지 않으면 Storybook 워크플로우는 건너뛴다.

package/dist/.storybook/story-kit.d.ts

@@ -0,0 +1,18 @@
+import { ReactNode } from 'react';
+interface MatrixProps<T> {
+    items: readonly T[];
+    label?: (value: T) => string;
+    render: (value: T) => ReactNode;
+    direction?: 'row' | 'column';
+    gap?: number;
+}
+/** items 하나마다 라벨과 샘플을 한 칸으로 그린다. 크기·variant 같은 축을 나란히 비교할 때 쓴다. */
+export declare const Matrix: <T>({ items, label, render, direction, gap, }: MatrixProps<T>) => import("react/jsx-runtime").JSX.Element;
+interface FrameProps {
+    dark?: boolean;
+    width?: number | string;
+    children: ReactNode;
+}
+/** 어두운 배경이나 고정 폭, 툴팁이 뜰 여백이 필요한 샘플을 감싼다. width 는 여백을 뺀 안쪽 폭이다. */
+export declare const Frame: ({ dark, width, children }: FrameProps) => import("react/jsx-runtime").JSX.Element;
+export {};