boottent-design

목차

• 소개
• 시작하기
• 문서
  • 설치
  • 빠른 사용법 (Tailwind 설정 불필요)
  • Tailwind 앱 권장 사용법
  • 다른 컴포넌트 라이브러리와 공존 (antd, MUI 등)
  • 성능 권장 import
  • 모듈 import 경로
• 제작 및 배포
  • 로컬 동시 개발 (watch + install)
  • Storybook/Chromatic 운영

소개

• 부트텐트의 디자인 시스템 라이브러리입니다.

시작하기

설치

yarn add boottent-design@latest

또는

npm install boottent-design@latest

빠른 사용법 (Tailwind 설정 불필요)

Tailwind를 직접 설치하거나 tailwind.config를 수정하지 않아도 됩니다. 라이브러리에서 미리 빌드된 CSS를 함께 제공하므로, 아래 2단계만 하면 동작합니다.

이 방식은 Tailwind를 쓰지 않는 앱이나 빠른 프로토타이핑에 적합합니다. Tailwind를 직접 운영하는 앱에서는 아래의 Tailwind 앱 권장 사용법을 사용하세요.

1. 앱 엔트리에서 스타일 1회 임포트

import React from "react";
import ReactDOM from "react-dom/client";
import App from "./App";
import "boottent-design/styles.css";

ReactDOM.createRoot(document.getElementById("root") as HTMLElement).render(
  <React.StrictMode>
    <App />
  </React.StrictMode>,
);

2. 필요한 모듈 import 후 바로 사용

import { Button } from "boottent-design/ui/button";

export function Sample() {
  return <Button>확인</Button>;
}

Tailwind 앱 권장 사용법

Tailwind를 직접 운영하는 앱에서는 styles.css 대신 foundation.css와 tailwind-preset을 사용하세요. 이 방식은 유틸 클래스를 앱 CSS에서 한 번만 생성하게 만들어, 디자인시스템 CSS와 앱 CSS 간 우선순위 충돌을 막습니다.

1. 앱 엔트리에서 foundation CSS 1회 임포트

import "boottent-design/foundation.css";
import "./index.css";

2. tailwind.config에서 preset과 content를 추가

const boottentDesignTailwindPreset = require("boottent-design/tailwind-preset");

module.exports = {
  content: ["./src/**/*.{ts,tsx}", "./node_modules/boottent-design/dist/**/*.{js,cjs,mjs}"],
  presets: [boottentDesignTailwindPreset],
};

3. 필요한 모듈 import 후 바로 사용

import { EventCard } from "boottent-design/components";

export function Sample() {
  return <EventCard {...props} />;
}

Note — boottent-design/foundation.css는 자체 스코프된 Tailwind preflight 리셋을 내장하고 있어, 소비자 앱이 tailwind.config.js에서 corePlugins: { preflight: false }로 설정해도 디자인시스템 컴포넌트는 정상 렌더링됩니다. (antd, MUI 등 다른 컴포넌트 라이브러리와 공존하는 환경 대응.)

다른 컴포넌트 라이브러리와 공존 (antd, MUI 등)

antd처럼 자체 글로벌 리셋(<button>, <input> 등)을 가진 컴포넌트 라이브러리는 Tailwind preflight와 충돌할 수 있습니다. 디자인시스템은 이 충돌을 피하면서도 자체 컴포넌트는 Storybook과 동일하게 렌더되도록 설계되어 있습니다.

• foundation.css의 preflight 리셋은 :where()로 래핑되어 specificity 0으로 출력됩니다.
• antd의 .ant-btn 같이 클래스 기반 selector(specificity ≥ 0,1,0)는 그대로 이깁니다 → antd 컴포넌트는 영향 없음.
• DS 컴포넌트가 의존하는 border-style: solid, <button>/<li>/<p> 기본 리셋은 브라우저 기본값을 정리해 Tailwind 유틸리티(border, rounded-lg 등)가 의도대로 작동합니다.
• 카드/배너처럼 DS 시각 정체성이 중요한 surface는 bt-ds-* semantic class로 border/radius/background를 한 번 더 보장합니다. 소비 앱에서는 .border, .rounded 같은 Tailwind utility 이름을 전역 helper class로 재정의하지 마세요.

권장 설정:

// tailwind.config.js
module.exports = {
  presets: [require("boottent-design/tailwind-preset")],
  content: [
    "./src/**/*.{ts,tsx}",
    "./node_modules/boottent-design/dist/**/*.{js,cjs,mjs}",
  ],
  corePlugins: {
    preflight: false, // antd 등과 충돌 회피
  },
};

권장 import 순서 (앱 엔트리):

import "antd/dist/antd.css"; // 또는 antd less
import "./globals.css"; // 앱의 글로벌 스타일
import "boottent-design/foundation.css"; // DS는 마지막에 둬 변수/리셋이 우선

이 구성에서 소비자는 추가 조치 없이 DS 컴포넌트가 Storybook과 동일한 외형으로 렌더되는 것을 기대할 수 있습니다.

성능 권장 import

소비자 앱 빌드 시간을 줄이려면 배럴 import보다 deep import를 권장합니다.

• 권장: import { Button } from "boottent-design/ui/button"
• 비권장(대량 사용 시 빌드 시간 증가 가능): import { Button } from "boottent-design/ui"

boottent-design/ui는 기존 호환성을 위해 유지되지만, 성능 관점에서는 ui/* 경로 사용을 권장합니다.

import { Button } from "boottent-design/ui";

export function Sample() {
  return <Button>확인</Button>;
}

모듈 import 경로

• boottent-design/ui
• boottent-design/ui/*
• boottent-design/tokens
• boottent-design/components
• boottent-design/components/*
• boottent-design/foundation.css
• boottent-design/tailwind-preset

참고

• Tailwind를 직접 운영하는 소비자 앱은 styles.css 대신 foundation.css + tailwind-preset 조합을 권장합니다.
• foundation.css는 self-sufficient합니다. 즉, 토큰(CSS 변수, Pretendard, 커스텀 유틸리티)뿐 아니라 스코프된 Tailwind preflight 리셋까지 포함하고 있어 preflight: false 환경에서도 DS 컴포넌트가 정상 렌더됩니다. 단 Tailwind 유틸리티 클래스 자체(예: text-semibold14, bg-grey-100)는 소비자 앱의 Tailwind 빌드에서 생성되므로 tailwind-preset과 content 설정은 여전히 필요합니다.
• styles.css는 Tailwind 미사용 소비자를 위한 올인원 엔트리로 계속 유지됩니다.

제작 및 배포

• 김동성 (Boottent Frontend-Developer)
• [email protected]

로컬 동시 개발 (watch + install)

boottent-design 수정 사항을 npm 배포 없이 boottent-frontend에 반영하는 로컬 플로우입니다.

1. boottent-frontend에서 로컬 의존성으로 전환

cd ../boottent-frontend
yarn design:use-local

2. boottent-design에서 watch + install 동기화 실행

cd ../boottent-design
yarn local:watch

내부 동작:

• build:lib:watch + build:styles:watch 실행
• dist 변경 감지 시 ../boottent-frontend에서 yarn install 자동 실행

3. boottent-frontend 개발 서버 실행

cd ../boottent-frontend
yarn dev

4. 레지스트리 버전으로 복귀

cd ../boottent-frontend
yarn design:use-registry

Storybook/Chromatic 운영

boottent-design은 Storybook 산출물을 Git에 커밋하지 않습니다.

• build-storybook 산출물 경로: .cache/storybook-static
• Git 비추적: storybook-static, .cache, tsconfig.tsbuildinfo
• 목적: 빌드할 때마다 생성되는 해시 파일 변경 노이즈 제거

로컬 확인:

yarn storybook

정적 빌드 확인:

yarn build-storybook

Chromatic 업로드(변경분만):

CHROMATIC_PROJECT_TOKEN=<your-token> yarn chromatic

CI는 .github/workflows/chromatic.yml에서 onlyChanged: true로 동작합니다.

배포용 yarn build는 마지막에 check:runtime-safety를 실행해 react-spinners 같은 금지 런타임 코드가 dist에 다시 섞이지 않았는지 검증합니다.

npm 토큰 관리

npm 인증 토큰은 레포 파일에 커밋하지 않고 환경변수로만 주입합니다.

• 로컬: export NPM_AUTH_TOKEN=<new-token>
• GitHub Actions: npm 인증이 필요한 워크플로가 생기면 Repository Secret NPM_AUTH_TOKEN 추가
• Yarn 설정: .yarnrc.yml에서 npmAuthToken: "${NPM_AUTH_TOKEN:-}" 사용

기존에 파일에 들어가 있던 토큰은 즉시 폐기(rotate/revoke) 후 새 토큰으로 교체해야 합니다.

문서

레포 문서 (직접 작성)

| 문서 | 설명 | |------|------| | docs/PRD.md | 이 라이브러리의 존재 이유, 이해관계자, 목표, 성공 지표 | | docs/Architecture.md | 레이어 구조, 빌드 시스템, CSS 모드 2종, CI/CD 파이프라인 | | docs/CONTRIBUTING.md | 컴포넌트 추가 절차, 브랜치 전략, 버전 bump, npm publish | | docs/COMPONENT-GUIDELINES.md | 컴포넌트 설계 원칙, presentational 철학, props 패턴, anti-pattern | | docs/DESIGN-TOKENS.md | 색상 팔레트, 타이포 스케일, camps/ads 토큰 전체 레퍼런스 | | docs/STORYBOOK.md | 스토리 작성 가이드, JSDoc 자동 문서화, Chromatic 회귀 테스트 | | docs/SSOT-INTEGRATION.md | 소비 레포(frontend/partner)가 DS 문서를 SSOT로 동기화하는 절차 |

자동 생성 문서 (SSOT, 허브 & 스포크)

소스(JSDoc·토큰·컴포넌트·결정 매트릭스)에서 기계 생성된다. 큰 문서를 통째로 읽지 않고 필요한 스포크만 열어보도록 허브 1개 + 작은 스포크 다수로 구성된다. 직접 수정하지 말 것 — 소스를 고치고 yarn docs:gen으로 재생성한다.

흐름: 추적 소스 → 빌드 시 dist로 스탬프 → 소비처가 dist 스탬프본을 sync

• docs/design-system/** — git 추적·커밋되는 클린 소스(GitHub에서 바로 열람). 출력은 결정적(버전·날짜 없음)이라 버전 bump·재생성에도 소스 내용이 같으면 diff가 없다.
• dist/design-system/** — yarn build(stamp:design-docs)가 위를 복사하면서 버전 + 빌드 날짜를 주입한 배포본. files: ["dist", "bin"]로 npm 배포되는 정본.

| 문서 | 경로(추적 소스) | 설명 | |------|------|------| | 허브 | docs/design-system/design-system.md | 원칙(DS-first) · 네비게이션 가이드 · 인벤토리(링크) · import 맵 | | 결정 가이드 | docs/design-system/when-to-use.md | 어떤 상황에 어떤 컴포넌트를 쓰는가 | | 사용법 | docs/design-system/usage.md | 설치 · CSS 배포 모드 · presentational 소비 규칙 | | 토큰 | docs/design-system/tokens.md | 색상 · 타이포 · 기타 토큰 | | UI 스포크 | docs/design-system/ui/<name>.md | UI 프리미티브당 1파일 | | 조합형 스포크 | docs/design-system/components/<name>.md | 조합형 컴포넌트당 1파일 |

문서 sync 도구 (이 레포에서):

• yarn docs:gen — 추적 문서 재생성 · yarn docs:check — 소스와 sync 검사(deep-entry·토큰·결정 매트릭스·freshness).
• /ds-docs-check (slash) — 읽기전용 sync 리포트 · /ds-docs-sync (slash) — 재생성 + 누락 JSDoc·결정 엔트리 초안 작성.
• husky pre-commit이 커밋 시 문서를 자동 재생성·stage 한다.

소비 레포는 동봉된 boottent-design-docs CLI로 dist 스탬프본을 자기 레포로 동기화한다.

# 소비 레포(boottent-frontend 등)에서
yarn boottent-design-docs init --postinstall    # docs/ds/ 초기화 + docs/design.md scaffold + install/update 자동 sync 설정

# boottent-design이 아직 설치 전이면
yarn dlx -p boottent-design boottent-design-docs init --postinstall

# npm 사용 소비처
npx -p boottent-design boottent-design-docs init --postinstall

# 수동 동기화만 필요할 때
boottent-design-docs sync                       # docs/ds/ 로 미러 복사 + docs/design.md scaffold(없을 때만)
boottent-design-docs sync --out docs/design     # 미러 경로 변경
boottent-design-docs sync --no-scaffold         # design.md 자동 생성 비활성화

소비처는 자체 docs/design.md(허브로 연결, 앱 전용 확장 기록)를 소유하고, docs/ds/는 sync가 덮어쓰는 SSOT 미러다. init --postinstall을 한 번 실행하면 이후 yarn install / yarn upgrade boottent-design 때 최신 DS 문서가 자동으로 다시 동기화된다. 자세한 연동/업그레이드 루프는 docs/SSOT-INTEGRATION.md를 참조하세요.