`/`` 기본 리셋은 브라우저 기본값을 정리해 Tailwind 유틸리티(`border`, `rounded-lg` 등)가 의도대로 작동합니다.\n- 카드/배너처럼 DS 시각 정체성이 중요한 surface는 `bt-ds-*` semantic class로 border/radius/background를 한 번 더 보장합니다. 소비 앱에서는 `.border`, `.rounded` 같은 Tailwind utility 이름을 전역 helper class로 재정의하지 마세요.\n\n권장 설정:\n\n```js\n// tailwind.config.js\nmodule.exports = {\n presets: [require(\"boottent-design/tailwind-preset\")],\n content: [\n \"./src/**/*.{ts,tsx}\",\n \"./node_modules/boottent-design/dist/**/*.{js,cjs,mjs}\",\n ],\n corePlugins: {\n preflight: false, // antd 등과 충돌 회피\n },\n};\n```\n\n권장 import 순서 (앱 엔트리):\n\n```tsx\nimport \"antd/dist/antd.css\"; // 또는 antd less\nimport \"./globals.css\"; // 앱의 글로벌 스타일\nimport \"boottent-design/foundation.css\"; // DS는 마지막에 둬 변수/리셋이 우선\n```\n\n이 구성에서 소비자는 추가 조치 없이 DS 컴포넌트가 Storybook과 동일한 외형으로 렌더되는 것을 기대할 수 있습니다.\n\n### 성능 권장 import\n\n소비자 앱 빌드 시간을 줄이려면 배럴 import보다 deep import를 권장합니다.\n\n- 권장: `import { Button } from \"boottent-design/ui/button\"`\n- 비권장(대량 사용 시 빌드 시간 증가 가능): `import { Button } from \"boottent-design/ui\"`\n\n`boottent-design/ui`는 기존 호환성을 위해 유지되지만, 성능 관점에서는 `ui/*` 경로 사용을 권장합니다.\n\n```tsx\nimport { Button } from \"boottent-design/ui\";\n\nexport function Sample() {\n return ;\n}\n```\n\n### 모듈 import 경로\n\n- `boottent-design/ui`\n- `boottent-design/ui/*`\n- `boottent-design/tokens`\n- `boottent-design/components`\n- `boottent-design/components/*`\n- `boottent-design/foundation.css`\n- `boottent-design/tailwind-preset`\n\n### 참고\n\n- Tailwind를 직접 운영하는 소비자 앱은 `styles.css` 대신 `foundation.css + tailwind-preset` 조합을 권장합니다.\n- `foundation.css`는 self-sufficient합니다. 즉, 토큰(CSS 변수, Pretendard, 커스텀 유틸리티)뿐 아니라 **스코프된 Tailwind preflight 리셋**까지 포함하고 있어 `preflight: false` 환경에서도 DS 컴포넌트가 정상 렌더됩니다. 단 Tailwind 유틸리티 클래스 자체(예: `text-semibold14`, `bg-grey-100`)는 소비자 앱의 Tailwind 빌드에서 생성되므로 `tailwind-preset`과 `content` 설정은 여전히 필요합니다.\n- `styles.css`는 Tailwind 미사용 소비자를 위한 올인원 엔트리로 계속 유지됩니다.\n\n## 제작 및 배포\n\n- 김동성 (Boottent Frontend-Developer)\n- kody@boottent.com\n\n### 로컬 동시 개발 (watch + install)\n\n`boottent-design` 수정 사항을 npm 배포 없이 `boottent-frontend`에 반영하는 로컬 플로우입니다.\n\n1. `boottent-frontend`에서 로컬 의존성으로 전환\n\n```sh\ncd ../boottent-frontend\nyarn design:use-local\n```\n\n2. `boottent-design`에서 watch + install 동기화 실행\n\n```sh\ncd ../boottent-design\nyarn local:watch\n```\n\n내부 동작:\n- `build:lib:watch` + `build:styles:watch` 실행\n- `dist` 변경 감지 시 `../boottent-frontend`에서 `yarn install` 자동 실행\n\n3. `boottent-frontend` 개발 서버 실행\n\n```sh\ncd ../boottent-frontend\nyarn dev\n```\n\n4. 레지스트리 버전으로 복귀\n\n```sh\ncd ../boottent-frontend\nyarn design:use-registry\n```\n\n### Storybook/Chromatic 운영\n\n`boottent-design`은 Storybook 산출물을 Git에 커밋하지 않습니다.\n\n- `build-storybook` 산출물 경로: `.cache/storybook-static`\n- Git 비추적: `storybook-static`, `.cache`, `tsconfig.tsbuildinfo`\n- 목적: 빌드할 때마다 생성되는 해시 파일 변경 노이즈 제거\n\n로컬 확인:\n\n```sh\nyarn storybook\n```\n\n정적 빌드 확인:\n\n```sh\nyarn build-storybook\n```\n\nChromatic 업로드(변경분만):\n\n```sh\nCHROMATIC_PROJECT_TOKEN= yarn chromatic\n```\n\nCI는 `.github/workflows/chromatic.yml`에서 `onlyChanged: true`로 동작합니다.\n\n배포용 `yarn build`는 마지막에 `check:runtime-safety`를 실행해 `react-spinners` 같은 금지 런타임 코드가 `dist`에 다시 섞이지 않았는지 검증합니다.\n\n### npm 토큰 관리\n\nnpm 인증 토큰은 레포 파일에 커밋하지 않고 환경변수로만 주입합니다.\n\n- 로컬: `export NPM_AUTH_TOKEN=`\n- GitHub Actions: npm 인증이 필요한 워크플로가 생기면 Repository Secret `NPM_AUTH_TOKEN` 추가\n- Yarn 설정: `.yarnrc.yml`에서 `npmAuthToken: \"${NPM_AUTH_TOKEN:-}\"` 사용\n\n기존에 파일에 들어가 있던 토큰은 즉시 폐기(rotate/revoke) 후 새 토큰으로 교체해야 합니다.\n\n## 문서\n\n### 레포 문서 (직접 작성)\n\n| 문서 | 설명 |\n|------|------|\n| [docs/PRD.md](docs/PRD.md) | 이 라이브러리의 존재 이유, 이해관계자, 목표, 성공 지표 |\n| [docs/Architecture.md](docs/Architecture.md) | 레이어 구조, 빌드 시스템, CSS 모드 2종, CI/CD 파이프라인 |\n| [docs/CONTRIBUTING.md](docs/CONTRIBUTING.md) | 컴포넌트 추가 절차, 브랜치 전략, 버전 bump, npm publish |\n| [docs/COMPONENT-GUIDELINES.md](docs/COMPONENT-GUIDELINES.md) | 컴포넌트 설계 원칙, presentational 철학, props 패턴, anti-pattern |\n| [docs/DESIGN-TOKENS.md](docs/DESIGN-TOKENS.md) | 색상 팔레트, 타이포 스케일, camps/ads 토큰 전체 레퍼런스 |\n| [docs/STORYBOOK.md](docs/STORYBOOK.md) | 스토리 작성 가이드, JSDoc 자동 문서화, Chromatic 회귀 테스트 |\n| [docs/SSOT-INTEGRATION.md](docs/SSOT-INTEGRATION.md) | 소비 레포(frontend/partner)가 DS 문서를 SSOT로 동기화하는 절차 |\n\n### 자동 생성 문서 (SSOT, 허브 & 스포크)\n\n소스(JSDoc·토큰·컴포넌트·결정 매트릭스)에서 **기계 생성**된다. 큰 문서를 통째로 읽지 않고 **필요한 스포크만** 열어보도록 허브 1개 + 작은 스포크 다수로 구성된다. 직접 수정하지 말 것 — 소스를 고치고 `yarn docs:gen`으로 재생성한다.\n\n흐름: **추적 소스 → 빌드 시 dist로 스탬프 → 소비처가 dist 스탬프본을 sync**\n\n- `docs/design-system/**` — **git 추적·커밋**되는 클린 소스(GitHub에서 바로 열람). 출력은 **결정적**(버전·날짜 없음)이라 버전 bump·재생성에도 소스 내용이 같으면 diff가 없다.\n- `dist/design-system/**` — `yarn build`(`stamp:design-docs`)가 위를 복사하면서 **버전 + 빌드 날짜를 주입**한 배포본. `files: [\"dist\", \"bin\"]`로 npm 배포되는 정본.\n\n| 문서 | 경로(추적 소스) | 설명 |\n|------|------|------|\n| 허브 | `docs/design-system/design-system.md` | 원칙(DS-first) · 네비게이션 가이드 · 인벤토리(링크) · import 맵 |\n| 결정 가이드 | `docs/design-system/when-to-use.md` | 어떤 상황에 어떤 컴포넌트를 쓰는가 |\n| 사용법 | `docs/design-system/usage.md` | 설치 · CSS 배포 모드 · presentational 소비 규칙 |\n| 토큰 | `docs/design-system/tokens.md` | 색상 · 타이포 · 기타 토큰 |\n| 소비 레포 셋업 가이드 | `docs/design-system/consumer-setup.md` | 소비 레포가 이 문서 체계를 자기 레포에 세팅하는 방법(자동 동기화 포함) |\n| UI 스포크 | `docs/design-system/ui/.md` | UI 프리미티브당 1파일 |\n| 조합형 스포크 | `docs/design-system/components/.md` | 조합형 컴포넌트당 1파일 |\n\n**문서 sync 도구** (이 레포에서):\n- `yarn docs:gen` — 추적 문서 재생성 · `yarn docs:check` — 소스와 sync 검사(deep-entry·토큰·결정 매트릭스·freshness).\n- `/ds-docs-check` (slash) — 읽기전용 sync 리포트 · `/ds-docs-sync` (slash) — 재생성 + 누락 JSDoc·결정 엔트리 초안 작성.\n- `/ds-release` (slash) — DS 변경사항 publish(버전 bump·빌드·docs 재생성·커밋·push·npm publish) + 소비 레포(boottent-frontend/boottent-partner/boottent-partner-frontend) 업그레이드 대상 확인 후 반영까지 자동화.\n- husky `pre-commit`이 커밋 시 문서를 자동 재생성·stage 한다.\n\n**소비 레포는 별도 명령 없이 자동으로 동기화된다.** `boottent-design` 패키지 자체가 `postinstall` 훅을 갖고 있어서, `yarn add boottent-design` / `yarn install` / `yarn upgrade boottent-design`을 실행하는 즉시 소비 레포의 `docs/ds/`가 최신 dist 스탬프본으로 채워지고, `docs/design.md`가 없으면 시작 템플릿이 생긴다(이미 있으면 절대 덮어쓰지 않음). 이 훅은 실패해도 설치 자체를 막지 않는다. 자세한 안내는 npm에도 함께 배포되는 [docs/design-system/consumer-setup.md](docs/design-system/consumer-setup.md)(설치 후 `node_modules/boottent-design/dist/design-system/consumer-setup.md`에서 바로 열람 가능)를 보라.\n\n동봉된 `boottent-design-docs` CLI는 수동 재실행이나, 소비 레포 자신의 package.json에 `docs:ds`/`postinstall` 스크립트를 명시적으로 남기고 싶을 때 쓴다:\n\n```sh\n# 소비 레포(boottent-frontend 등)에서 — package.json에 스크립트도 남기고 싶을 때\nyarn boottent-design-docs init --postinstall # docs/ds/ 초기화 + docs/design.md scaffold + install/update 자동 sync 스크립트 추가\n\n# boottent-design이 아직 설치 전이면\nyarn dlx -p boottent-design boottent-design-docs init --postinstall\n\n# npm 사용 소비처\nnpx -p boottent-design boottent-design-docs init --postinstall\n\n# 수동 동기화만 필요할 때\nboottent-design-docs sync # docs/ds/ 로 미러 복사 + docs/design.md scaffold(없을 때만)\nboottent-design-docs sync --out docs/design # 미러 경로 변경\nboottent-design-docs sync --design-doc docs/design-guide.md # design.md 자리에 다른 문서가 이미 있을 때 경로 변경\nboottent-design-docs sync --no-scaffold # design.md 자동 생성 비활성화\n```\n\n소비처는 자체 `docs/design.md`(허브로 연결, 앱 전용 확장 기록)를 소유하고, `docs/ds/`는 sync가 덮어쓰는 SSOT 미러다.\n자세한 연동/업그레이드 루프는 [docs/SSOT-INTEGRATION.md](docs/SSOT-INTEGRATION.md)를 참조하세요.\n","readmeFilename":"README.md","homepage":"https://github.com/boottent-team/boottent-design#readme","bugs":{"url":"https://github.com/boottent-team/boottent-design/issues"}}