@highpixel-co/palda-design-system 0.4.1 → 0.6.0

package/dist/guide/docs/CONSUMER_GUIDE.md

@@ -0,0 +1,131 @@
+# 앱에서 Palda DS 사용하기
+
+패키지 하나에 UI 코드·스타일·타입과 이 설명서, 자산 목록, 앱용 검사 도구가 들어 있다.
+패키지를 빌드할 때 같은 DS 원본에서 함께 생성하므로 다른 DS 저장소를 내려받지 않아도 된다.
+패키지의 `dist/guide/docs/`는 사용 문서, `dist/guide/catalog/`는 자산 목록,
+`dist/harness/metadata.json`은 같은 버전의 export·상태·아이콘 대체표다.
+
+## 처음 한 번 연결
+
+Node.js 22.12 이상, React 19 이상의 웹 앱을 대상으로 한다. 검사기의 TypeScript와 YAML
+의존성은 패키지 설치에 포함되며 브라우저용 UI import에는 들어가지 않는다.
+
+```sh
+pnpm add --save-exact @highpixel-co/palda-design-system
+pnpm exec palda-ds guide
+pnpm exec palda-ds check
+```
+
+npm 프로젝트는 `npm install --save-exact`와 `npm exec -- palda-ds check`를 사용한다.
+과거 비공개 registry 설정이 남아 있다면 프로젝트 `.npmrc`의 `@highpixel-co:registry`를
+`https://registry.npmjs.org/`로 변경한다. 계정 토큰은 필요 없다.
+
+앱 시작점에서 `@highpixel-co/palda-design-system/styles.css`를 한 번 import한다. 자산은
+`/ui`, `/patterns`, `/icons`, `/tokens`의 이름 있는 export로 불러온다.
+`palda-ds check`는 앱 manifest와 잠금 파일이 **실행 중인 패키지의 정확한 버전**과 같은지도
+확인한다. pnpm lockfile v9와 npm lockfile v2/v3을 지원한다. 다른 형식은 구성 오류로 실패한다.
+워크스페이스에서는 앱 디렉터리에서 실행하거나 `--root apps/web`처럼 앱 경로를 지정한다.
+
+## 작업할 때 읽는 순서
+
+- 화면 조립: [디자인 원칙](./DESIGN_PRINCIPLES.md) → [디자인 문법](./DESIGN_GRAMMAR.md)
+- 컴포넌트 선택: [컴포넌트 목록](../catalog/components.yml)과 [패턴 목록](../catalog/patterns.yml)
+- 토큰: [토큰 정책](./TOKEN_POLICY.md)
+- 아이콘: [아이콘 정책](./ICON_POLICY.md)과 [아이콘 목록](../catalog/icons.yml)
+- 키보드·읽기 순서: [접근성](./ACCESSIBILITY.md)
+
+Stable 자산을 먼저 사용한다. Draft 자산은 catalog의 사용 조건과 검토 질문을 확인한다.
+catalog의 `source`·`story`는 DS 원본 저장소의 경로다. 설치된 패키지의 prop 타입은
+`dist/ui.d.ts`와 `dist/patterns.d.ts`에서 확인한다.
+`check`는 Draft import 위치를 보고하지만 모든 Draft를 금지하지 않는다. variant별 사용 조건과
+화면 전체의 적절성은 문서·타입·브라우저 검토로 확인한다. Storybook 검토 환경과 DS 제작 전용
+생성·release 검사는 DS 저장소에 있고, 앱용 CLI를 실행하는 데 필요하지 않다.
+
+## 검사 명령과 경로
+
+```sh
+pnpm exec palda-ds check --root . --json
+pnpm exec palda-ds screens --root .
+pnpm exec palda-ds --version
+```
+
+`check`는 기본 `src/`의 JS·JSX·TS·TSX·MJS·CJS·MTS·CTS를 읽는다. test/spec/stories/gen 파일과
+타입 선언 파일, node_modules·dist·coverage·.git 디렉터리는 제외한다. 파일 개수와 제외 개수,
+예외 적용 개수를 출력한다. symlink 소스와 프로젝트 밖 소스 경로는 지원하지 않는다.
+
+DS 경계를 우회하는 Radix/CVA import, DS로 대체 가능한 Lucide import, 존재하지 않는 DS
+export를 검사한다. 이름을 숨기는 namespace·동적 import/require·export-star는 DS와 Lucide에
+대해 오류로 보고하므로 명시적인 이름으로 바꾼다. 계산식으로 구성한 모듈 경로까지 추적하는
+번들 분석기는 아니다. 앱의 lint·타입 검사도 함께 유지한다.
+
+경로가 다르면 앱에 `palda-ds.config.json`을 한 번 만든다. 경로는 앱 루트 기준이다.
+
+```json
+{
+  "source": ["src"],
+  "screens": ["preview"],
+  "exceptions": []
+}
+```
+
+설정 파일 위치를 바꾸려면 `--config config/palda-ds.json`을 사용한다. 알 수 없는 설정 키,
+누락된 디렉터리, 검사 대상 0개는 실패다. 화면 검사는 별도 명령이므로 앱에 HTML 시안이 없으면
+`check`만 연결한다. HTML 시안을 관리한다면 `screens`도 전체 검사에 연결한다.
+
+`screens`는 지정 디렉터리의 HTML **화면 시안**을 검사한다. 파일 맨 위 주석의 화면 선언 표와
+`palda-app-shell__band--body` 안의 `data-screen-role` 블록을 기존 디자인 문법으로 검사한다.
+셸이 없는 컴포넌트 조각은 화면 통과로 처리하지 않는다. 컴포넌트 시안은 다른 폴더에 보관한다.
+실행 중인 React 화면의 시각적 결과를 자동 촬영하거나 판정하지는 않는다.
+
+## 기존 화면의 예외
+
+기존 위반을 단계적으로 전환할 때만 정확한 파일·규칙·심볼과 이유를 기록한다.
+
+```json
+{
+  "exceptions": [
+    {
+      "file": "src/LegacySearch.tsx",
+      "rule": "icon-import",
+      "symbol": "Search",
+      "reason": "기존 검색 화면을 DS로 전환할 때 제거"
+    }
+  ]
+}
+```
+
+허용 rule은 `primitive-import`, `icon-import`, `opaque-import`다. primitive·opaque의 symbol은
+모듈 이름, icon의 symbol은 가져온 원래 이름이다. 폴더 prefix와 wildcard 예외는 없다.
+예외 설정은 코드 리뷰 대상으로 두고 전환한 파일의 예외를 제거한다.
+
+## AI 작업과 CI 연결
+
+앱의 `AGENTS.md` 또는 `CLAUDE.md`에 다음 진입점을 넣는다.
+
+```text
+UI 작업 전 설치된 DS 패키지의 dist/guide/docs/CONSUMER_GUIDE.md를 읽는다.
+작업 중 검사 시점과 범위는 변경 내용에 따라 판단한다.
+오류 수정 뒤 실패 검사를 다시 실행하고, 제출 전에는 DS 검사를 포함한 전체 검사를 수행한다.
+```
+
+앱의 기존 전체 검사 명령에 `palda-ds check`를 추가한다. 예:
+
+```json
+{
+  "scripts": {
+    "check:ds": "palda-ds check",
+    "verify": "pnpm check:ds && pnpm lint && pnpm typecheck && pnpm test && pnpm build"
+  }
+}
+```
+
+기존 CI에서 의존성 설치 후 `pnpm verify`를 실행하면 작업자나 AI가 바뀌어도 같은 검사로
+확인한다. 프로젝트별 최초 연결은 필요하지만 매 작업마다 연결하지 않는다. 설치 과정에서
+앱 파일이나 GitHub 설정을 자동 변경하지 않는다.
+
+CI 실패 시 병합까지 차단하려면 관리자가 해당 job을 필수 상태 검사로 지정해야 한다. 기존
+자동 동기화·bot PR도 검사 완료를 기다릴 수 있는지 먼저 확인한다. CLI는 검사 결과와 exit
+code를 제공하며 GitHub 권한이나 병합 정책을 대신 설정하지 않는다.
+
+검사 결과는 실행한 곳의 표준 출력으로만 나온다. 앱 소스·사용처 보고서는 DS 패키지나 공개
+저장소에 수집하지 않는다. JSON 결과를 파일로 저장할 때는 소비 프로젝트의 로컬 산출물로 관리한다.

package/dist/guide/docs/CONTENT.md

@@ -0,0 +1,148 @@
+# Content
+
+**제품 문구의 말투와 표기를 정하는 문서다.**
+
+읽는 사람은 스마트스토어를 혼자 운영하는 셀러다. 옆에서 대신 봐 줄 사람이 없고, 화면의 문구가
+곧 안내다. 인상은 [`DESIGN_PRINCIPLES.md`](DESIGN_PRINCIPLES.md) §1·§2를 따른다.
+
+## 말투
+
+**문장은 "요"로 끝난다.** 해요체다. "~습니다"(합쇼체)를 쓰지 않는다.
+
+**친절한 서비스직 말투다.** 매장에서 손님을 맞는 사람의 말이지, 공지문이나 약관의 말이 아니다.
+딱딱하게 알리는 대신 옆에서 알려 주듯 쓴다.
+
+| 이렇게                      | 이렇게 말고                     |
+| --------------------------- | ------------------------------- |
+| 변경한 내용을 저장했어요    | 변경사항이 저장되었습니다       |
+| 연동할 스토어를 골라 주세요 | 스토어를 선택하십시오           |
+| 아직 등록한 상품이 없어요   | 등록된 상품이 존재하지 않습니다 |
+| 잠시만 기다려 주세요        | 처리 중입니다                   |
+
+**높임의 대상은 사람이지 사물이 아니다.** "주문이 있으세요"가 아니라 "주문이 있어요"다.
+
+**명령하지 않는다.** "~하십시오"·"~하세요"보다 "~해 주세요"가 기본이고, 그마저 필요 없는 자리는
+평서문으로 끝낸다.
+
+## 오류와 성공 — 겁주지 않는다
+
+**오류 문구가 무섭지 않아야 한다.** 혼자 쓰는 사람에게 강한 경고는 도움이 아니라 부담이다.
+무슨 일이 있었는지와 지금 무엇을 하면 되는지, 둘만 담는다.
+
+| 하지 않는 것                        | 대신                                            |
+| ----------------------------------- | ----------------------------------------------- |
+| 겁주는 단어 — 경고·실패·오류·불가   | 무슨 일이 있었는지 그대로 ("저장하지 못했어요") |
+| 느낌표                              | 마침표 없는 평서문                              |
+| 사용자를 탓하기 ("잘못 입력했어요") | 조건을 알려 주기 ("숫자만 넣을 수 있어요")      |
+| 되돌릴 수 없다는 말을 앞세우기      | 무엇이 사라지는지 담담하게                      |
+| 원인만 적고 끝내기                  | 다음에 할 일을 한 문장 덧붙이기                 |
+
+**되돌릴 수 없는 일은 숨기지 않는다.** 겁주지 않는 것과 알리지 않는 것은 다르다. "영구적으로
+삭제됩니다!"가 아니라 "삭제하면 다시 불러올 수 없어요"다.
+
+**성공은 짧게.** 한 문장이면 된다. 축하하거나 칭찬하지 않는다.
+
+## 버튼
+
+### 라벨은 고정이다
+
+**버튼의 글자는 어떤 상태에서도 바뀌지 않는다.** 눌렀다고, 값이 정해졌다고, 처리 중이라고 글자가
+바뀌지 않는다.
+
+| 자리                 | 이렇게             | 이렇게 말고             |
+| -------------------- | ------------------ | ----------------------- |
+| 스토어를 고르는 버튼 | `선택하기` 로 고정 | 고른 뒤 `우리집상회` 로 |
+| 저장 중              | `저장하기` 로 고정 | `저장 중...` 으로       |
+| 이미 연동된 스토어   | `연동하기` 로 고정 | `연동됨` 으로           |
+
+버튼은 **누르면 무슨 일이 일어나는지**를 말하는 자리다. 지금 무엇이 골라졌는지, 처리가 어디까지
+갔는지는 버튼 밖에서 말한다 — 고른 값은 버튼 옆이나 아래, 진행 상태는 `ProgressBar`나
+`Toast`다.
+
+**진행 중은 글자가 아니라 `disabled`로 표현한다.** `Button`에 로딩 전용 prop이 없는 것이
+그래서다([`components/src/Button/Button.tsx`](https://github.com/highpixel-co/palda-design-system/blob/ad23980481cd81dcf09a1044504d2295f0e4a0f3/components/src/Button/Button.tsx)).
+
+### "~기"로 끝난다
+
+**버튼 라벨은 동사이고 "~기"로 끝난다.** 명사로 끝내지 않는다.
+
+| 이렇게    | 이렇게 말고 |
+| --------- | ----------- |
+| 저장하기  | 저장        |
+| 다시 하기 | 다시 시도   |
+| 더 보기   | 더보기      |
+| 충전하기  | 충전        |
+
+## 오류·성공·Empty State 문구 구조
+
+**컴포넌트가 칸을 이미 정해 두었다.** 문구는 그 칸에 맞춘다.
+
+| 자리                  | 칸                                      | 무엇을 넣나                                         |
+| --------------------- | --------------------------------------- | --------------------------------------------------- |
+| `EmptyState`          | `title` · `description` · `actionLabel` | 무엇이 없는지 · 왜 비어 있는지나 다음 할 일 · "~기" |
+| `Alert`               | 제목 · 본문 · action                    | 무슨 일인지 · 다음에 할 일 · "~기"                  |
+| `Toast`               | 메시지 한 줄                            | 끝난 일 하나. 설명을 붙이지 않는다                  |
+| `TextField`의 `error` | 한 줄                                   | 무엇이 맞지 않는지와 어떤 값이면 되는지             |
+
+**제목에는 상태를, 설명에는 다음 할 일을 쓴다.** 두 칸에 같은 말을 나눠 쓰지 않는다.
+
+**Empty State는 사과하지 않는다.** "아직 없어요"까지가 사실이고, 그다음은 만들 수 있는 길이다.
+
+## 설명은 언제 붙이나
+
+**기본은 제목만이다.** `Card`·`FormSection`·`ListRow`의 `description`은 비워 둔다. 칸이 있으니
+채우는 것이 화면에 설명이 쌓이는 가장 흔한 이유다.
+
+### 붙일지는 사람이 정한다
+
+**중복인지 아닌지를 매번 따져서 채우지 않는다.** 한 화면의 설명이 위층과 겹치는지, 아래 값과
+겹치는지, 제목을 뒤집어 말한 것인지를 전부 확인하는 일은 화면마다 어렵고 판단도 갈린다.
+
+그래서 절차로 가른다. **시안은 제목만 둔 상태로 만들고, 설명이 필요해 보이는 자리는 묻는다.**
+묻지 않고 채우지 않는다. 붙이기로 정한 자리만 채운다.
+
+### 붙이기로 했다면 — 그 자리에서만 할 수 있는 말
+
+셋 중 하나가 아니면 설명이 아니다.
+
+| 무엇                    | 예                                             |
+| ----------------------- | ---------------------------------------------- |
+| 눈에 안 보이는 사실     | 10분마다 새 주문을 가져와요                    |
+| 제목이 원인일 때의 대처 | 스마트스토어에 다시 로그인하면 이어서 수집해요 |
+| 어디로 가야 하는지      | 위의 자동 수집 스위치를 켜면 다시 시작해요     |
+
+`Chrome · v1.4.2`나 `MacBook Pro · Chrome 129`처럼 **값을 적는 자리는 설명이 아니다.** 위 규칙의
+대상이 아니고 그대로 둔다.
+
+**제목을 다시 말하는 설명은 붙이기로 정한 자리에도 쓰지 않는다.** 뒤집어 말한 것도 다시 말한
+것이다 — "브라우저를 닫아 뒀을 때 / 브라우저가 켜져 있을 때만 움직여요"는 한 문장을 앞뒤로 나눠
+쓴 것이다.
+
+**목록의 행 설명은 전부 붙이거나 전부 뺀다.** 한 행만 설명이 없으면 그 행이 덜 중요해 보인다.
+어느 한 행에서 지울 이유가 생기면 지우는 대신 위 셋 중 하나로 고쳐 쓴다.
+
+## 아직 확정되지 않은 것
+
+**여기 있는 것은 화면에서 마주쳐도 지어내지 않고 멈춘다.**
+
+| 무엇                  | 상태                                                                               |
+| --------------------- | ---------------------------------------------------------------------------------- |
+| 메뉴 라벨             | 지금 코드의 사이드바 항목은 명사다(`배송과정`·`클레임`). 규칙으로 확정된 적은 없다 |
+| 동일 액션의 고정 명칭 | 한 액션에 한 이름을 쓴다는 규칙만 있고, 대조표가 없다. 아래 §제안 참고             |
+| 날짜 표기             | 미확정                                                                             |
+| 금액 표기             | 미확정                                                                             |
+| 수량 표기             | 미확정                                                                             |
+| 대화상자 버튼의 예외  | `취소`·`확인`에도 "~기"를 붙일지 (`취소하기`·`확인하기`)                           |
+
+### 제안 — 고정 명칭 후보
+
+**확정 전이다.** 지금 저장소의 스토리·예시에 실제로 쓰인 라벨을 위 규칙에 맞춰 옮긴 것이다.
+
+| 지금 코드에 있는 것 | 제안      |
+| ------------------- | --------- |
+| 저장                | 저장하기  |
+| 초기화              | 되돌리기  |
+| 다시 시도           | 다시 하기 |
+| 알림 받기           | 알림 받기 |
+| 확인                | 확인하기  |
+| 취소                | 취소하기  |