밀당 DS

시작하기

시작하기

패키지 설치부터 스타일 연결, 첫 컴포넌트 사용까지의 안내

@mildang/design-system은 밀당의 신규 디자인시스템입니다. 미리 컴파일된 스타일시트 하나와 컴포넌트만 가져오면 되고, 프로젝트에 Panda CSS를 따로 설정할 필요가 없습니다.

React 18 이상을 전제로 합니다. Next.js를 쓴다면 프로젝트에 정확히 next@16.2.10이 설치돼 있어야 합니다. (이 버전에 맞춰 빌드·검증해 발행합니다.)

1. 설치하기

@mildang 스코프 패키지는 npmjs가 아니라 GitHub Packages 레지스트리로 발행됩니다. 사내 비공개 패키지라 GitHub mildang org 멤버 자격이 있어야 설치할 수 있고, 인증 토큰도 필요합니다. 멤버가 아니라면 org 관리자에게 초대를 요청하세요. (mildang-frontend 루트 .npmrc와 같은 설정입니다.)

  1. 토큰 발급

    GitHub 개인 액세스 토큰(PAT)을 read:packages 권한으로 발급합니다.

    토큰 발급 방법
    1. Personal access tokens에서 Generate new token (classic) 버튼을 클릭하세요.
    2. read:packages 하나만 체크해 생성하세요. (값은 한 번만 표시됩니다)
    3. 생성된 토큰에서 Configure SSO → mildang → Authorize 순서로 클릭하세요.
    4. 토큰은 저장소에 커밋하지 말고 환경변수로 주입하세요.

  2. .npmrc 등록

    프로젝트 루트의 .npmrc에 스코프별 레지스트리 주소와 토큰을 등록하세요.

    ini

    # .npmrc
@mildang:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
always-auth=false

  3. 패키지 설치

    sh

    npm install @mildang/design-system

    react, react-dom(18 이상)은 이 패키지에 포함되지 않으니 프로젝트에 미리 설치돼 있어야 합니다. Next.js 프로젝트면 next@16.2.10도 마찬가지입니다.


    설치 문제 해결

    401·403 오류는 대부분 인증 문제입니다.

    • .npmrc에 @mildang:registry 줄이 있는지, 주소 오타가 없는지 확인하세요.
    • 토큰에 read:packages 권한이 있는지, 만료되지 않았는지 확인하세요.
    • 조직이 SSO를 쓰면 토큰을 해당 조직에 authorize 했는지 확인하세요.

    위 항목으로도 해결되지 않으면 GitHub의 npm 레지스트리 인증 가이드를 참고하세요.

2. 스타일 연결하기

프로젝트 진입점에서 스타일시트를 한 번만 import 하세요. 이 한 줄에 토큰·리셋·모든 컴포넌트 스타일이 모두 들어 있습니다.

tsx

// app/layout.tsx (또는 프로젝트 최상단 엔트리)
import '@mildang/design-system/styles.css';

3. 컴포넌트 사용하기

컴포넌트는 서브패스로 가져옵니다. 루트(@mildang/design-system) import는 없습니다.

tsx

import { Button } from '@mildang/design-system/Button';
import { Text } from '@mildang/design-system/Text';

export function SavePanel({ onSave }: { onSave: () => void }) {
  return (
    <div>
      <Text variant="title-lg">변경 사항 저장</Text>
      <Button onClick={onSave}>저장</Button>
    </div>
  );
}

사용 가능한 컴포넌트 전체 목록과 사용법은 컴포넌트 페이지에서 확인하세요.

4. 테마 설정하기 (선택)

styles.css만 넣으면 밀당 라이트 테마가 기본값으로 적용됩니다. 별도의 프로바이더나 설정은 필요 없습니다. 다크 모드로 바꿀 때만 루트 엘리먼트에 dark 클래스를 추가합니다.

tsx

// app/layout.tsx (루트 엘리먼트에 dark 클래스 추가)
<body className="dark">

브랜드 분기와 새 테마 추가는 멀티 프로덕트 테마 문서를 참고하세요.

5. 다음 단계