modu-inning-design-system

v1.0.20

Published

6 months ago

모두의 이닝(MODU INNING)을 위한 디자인 시스템 및 UI 컴포넌트 라이브러리

Downloads

0High
0Medium
0Low

popo0118

modu-inning-design-system

모두의 이닝(MODU INNING)을 위한 디자인 시스템 레포지토리입니다. 공통 UI 컴포넌트, 디자인 토큰, 스타일 가이드를 관리합니다.

Tailwind CSS v4 기반 컴포넌트 킷
Atomic Design 패턴으로 구성된 컴포넌트 구조
Storybook을 통한 컴포넌트 문서화 및 개발 환경
라이트/다크 모드 지원
웹 접근성(A11y) 준수
TypeScript 기반 타입 안정성

기술 스택

React 18 - UI 라이브러리
TypeScript - 타입 안정성
Tailwind CSS v4 - 유틸리티 기반 CSS 프레임워크
Storybook - 컴포넌트 문서화 및 개발 환경
tsup - TypeScript 빌드 도구
ESLint - 코드 품질 관리
Prettier - 코드 포맷팅

시작하기

사전 요구사항

Node.js 18 이상
pnpm 8 이상 (또는 npm/yarn)

# pnpm이 설치되어 있지 않은 경우
npm install -g pnpm

설치

pnpm install

개발 서버 실행

Storybook 실행

컴포넌트 개발 및 문서화를 위한 Storybook:

pnpm dev
# 또는
pnpm storybook

브라우저에서 http://localhost:6006으로 접속합니다.

빌드

컴포넌트 라이브러리 빌드

pnpm build

빌드된 파일은 dist/ 디렉토리에 생성됩니다:

dist/index.js (ESM)
dist/index.cjs (CommonJS)
dist/index.d.ts (타입 정의)
dist/styles/globals.css (CSS 파일)

Storybook 빌드

pnpm build:storybook

빌드된 파일은 storybook-static/ 디렉토리에 생성됩니다.

버전 관리 및 배포

버전 업데이트

# 패치 버전 (1.0.0 → 1.0.1)
pnpm run version:patch

# 마이너 버전 (1.0.0 → 1.1.0)
pnpm run version:minor

# 메이저 버전 (1.0.0 → 2.0.0)
pnpm run version:major

버전 업데이트 시 자동으로:

package.json의 버전이 업데이트됩니다
변경사항이 Git에 스테이징됩니다
버전명이 포함된 커밋 메시지로 자동 커밋됩니다

배포

# 패치 버전으로 빌드 후 배포
pnpm run release:patch

# 마이너 버전으로 빌드 후 배포
pnpm run release:minor

# 메이저 버전으로 빌드 후 배포
pnpm run release:major

타입 체크

TypeScript 타입 검사를 실행합니다:

pnpm type-check

코드 품질 관리

ESLint

코드 린팅을 실행합니다:

pnpm lint

자동으로 수정 가능한 문제를 해결합니다:

pnpm lint:fix

Prettier

코드를 포맷팅합니다:

pnpm format

포맷팅이 필요한지 확인합니다:

pnpm format:check

VSCode 설정

프로젝트에는 VSCode 설정이 포함되어 있어 저장 시 자동으로:

코드 포맷팅 (Prettier)
ESLint 자동 수정
사용하지 않는 import 제거
import 정렬

가 적용됩니다. VSCode를 사용하는 경우 .vscode/extensions.json에 권장 확장 프로그램이 포함되어 있습니다.

컴포넌트 구조

이 디자인 시스템은 Atomic Design 패턴을 따릅니다:

Atoms (원자)

가장 작은 단위의 컴포넌트들:

Alert - 알림 메시지
Badge - 배지/태그
Button - 버튼
Checkbox - 체크박스
Input - 입력 필드
Kbd - 키보드 단축키 표시
Label - 라벨
Progress - 진행 표시줄
Radio - 라디오 버튼
Separator - 구분선
Skeleton - 로딩 스켈레톤
Slider - 슬라이더
Spinner - 로딩 스피너
Switch - 스위치
Textarea - 텍스트 영역
Tooltip - 툴팁

Molecules (분자)

여러 Atoms를 조합한 컴포넌트들:

ButtonGroup - 버튼 그룹
DropdownMenu - 드롭다운 메뉴
InputGroup - 입력 그룹
Popover - 팝오버
RadioGroup - 라디오 그룹
Select - 셀렉트 박스
Tabs - 탭

Organisms (유기체)

복잡한 UI 패턴을 구성하는 컴포넌트들:

Card - 카드
Dialog - 다이얼로그/모달
Form - 폼
Toast - 토스트 알림

프로젝트 구조

modu-inning-design-system/
├── src/                      # 컴포넌트 킷 소스 코드
│   ├── components/          # UI 컴포넌트들 (Atomic Design 패턴)
│   │   ├── Alert/           # Atoms
│   │   ├── Button/          # Atoms
│   │   ├── ButtonGroup/     # Molecules
│   │   ├── Card/            # Organisms
│   │   └── ...
│   ├── styles/              # 전역 스타일 및 디자인 토큰
│   │   └── globals.css      # Tailwind CSS v4 설정 및 디자인 토큰
│   ├── types/               # TypeScript 타입 정의
│   ├── utils/               # 유틸리티 함수
│   └── index.ts             # 컴포넌트 export
├── dist/                     # 빌드 산출물 (배포용)
├── .storybook/               # Storybook 설정
├── scripts/                  # 빌드 및 유틸리티 스크립트
│   └── version-bump.js      # 버전 업데이트 스크립트
├── package.json              # 프로젝트 설정
├── tsconfig.json             # TypeScript 설정
├── tsup.config.ts            # tsup 빌드 설정
├── tailwind.config.ts        # Tailwind CSS 설정
└── postcss.config.mjs         # PostCSS 설정

컴포넌트 개발

새로운 컴포넌트를 추가할 때는 다음 구조를 따르세요:

src/components/ComponentName/
├── ComponentName.tsx           # 컴포넌트 구현
├── ComponentName.stories.tsx  # Storybook 스토리
└── index.ts                    # export 파일

컴포넌트를 추가한 후 src/index.ts에 export를 추가하세요.

Atomic Design 분류

컴포넌트를 추가할 때는 적절한 카테고리로 분류하세요:

Atoms: 단일 책임을 가진 가장 작은 컴포넌트
Molecules: 여러 Atoms를 조합한 컴포넌트
Organisms: 복잡한 UI 패턴을 구성하는 컴포넌트

테마 및 다크 모드

이 디자인 시스템은 라이트 모드를 기본으로 하며, 다크 모드를 지원합니다.

라이트 모드 (기본)

기본적으로 라이트 모드가 적용됩니다.

다크 모드 사용

다크 모드를 적용하려면 HTML 요소에 .dark 클래스를 추가하거나 data-theme="dark" 속성을 설정하세요:

// HTML 요소에 클래스 추가
<html className="dark">
  {/* ... */}
</html>

// 또는 data-theme 속성 사용
<div data-theme="dark">
  {/* ... */}
</div>

설치 및 사용하기

이 디자인 시스템은 npm 패키지로 배포되어 외부 프로젝트에서 설치하여 사용할 수 있습니다.

⚠️ 중요: 이 디자인 시스템은 Tailwind CSS v4를 사용하므로, 사용하는 프로젝트에도 Tailwind CSS v4가 설정되어 있어야 합니다.

1. 패키지 설치

# npm 사용 시
npm install modu-inning-design-system

# pnpm 사용 시
pnpm add modu-inning-design-system

# yarn 사용 시
yarn add modu-inning-design-system

2. CSS 파일 설정

프로젝트의 메인 CSS 파일에 추가 (src/index.css, app/globals.css 등):

/* Tailwind CSS v4 import (반드시 먼저!) */
@import 'tailwindcss';

/* 디자인 시스템 스타일 import */
@import 'modu-inning-design-system/styles';

3. Tailwind Config 설정

프로젝트의 tailwind.config.ts 파일에 패키지 경로를 추가:

import type { Config } from 'tailwindcss'

const config: Config = {
  content: [
    './src/**/*.{js,jsx,ts,tsx}',
    // 디자인 시스템 컴포넌트 경로 포함
    './node_modules/modu-inning-design-system/dist/**/*.{js,jsx,ts,tsx}'
  ]
}

export default config

4. 컴포넌트 사용

import { Button, Input, Card } from 'modu-inning-design-system'

function App() {
  return (
    <div className="p-4 space-y-4">
      <Button variant="primary" onClick={() => alert('클릭!')}>
        Primary Button
      </Button>

      <Button variant="secondary">Secondary Button</Button>

      <Button variant="outline">Outline Button</Button>

      <Input label="이름" placeholder="이름을 입력하세요" />

      <Card title="카드 제목" description="카드 설명">
        카드 내용
      </Card>
    </div>
  )
}

기본 사용 예시

1. CSS 파일 설정 (src/index.css 또는 app/globals.css):

@import 'tailwindcss';
@import 'modu-inning-design-system/styles';

2. 컴포넌트 사용:

import { Button, Input, Card } from 'modu-inning-design-system'

function App() {
  return (
    <div className="p-4 space-y-4">
      <Button variant="primary" onClick={() => alert('클릭!')}>
        Primary Button
      </Button>

      <Button variant="secondary">Secondary Button</Button>

      <Button variant="outline">Outline Button</Button>

      <Input label="이름" placeholder="이름을 입력하세요" />

      <Card title="카드 제목" description="카드 설명">
        카드 내용
      </Card>
    </div>
  )
}

3. 컴포넌트 크기 및 variant 예시:

import { Button, Badge, Alert } from 'modu-inning-design-system'

function Example() {
  return (
    <div className="space-y-4">
      {/* Button 크기 */}
      <div className="flex gap-2">
        <Button size="sm">Small</Button>
        <Button size="md">Medium</Button>
        <Button size="lg">Large</Button>
      </div>

      {/* Badge variant */}
      <div className="flex gap-2">
        <Badge variant="primary">Primary</Badge>
        <Badge variant="success">Success</Badge>
        <Badge variant="danger">Danger</Badge>
      </div>

      {/* Alert */}
      <Alert variant="info" title="정보">
        이것은 정보 알림입니다.
      </Alert>
    </div>
  )
}

스타일만 사용하기

컴포넌트 없이 디자인 토큰과 스타일만 사용하려면:

// CSS 파일에서
@import 'tailwindcss';
@import 'modu-inning-design-system/styles';

이렇게 하면 디자인 시스템의 모든 CSS 변수와 유틸리티 클래스를 사용할 수 있습니다.

웹 접근성 (A11y)

모든 컴포넌트는 웹 접근성 표준을 준수합니다:

ARIA 속성: aria-label, aria-describedby, aria-invalid 등
키보드 네비게이션: Tab, Enter, Escape 등 키 지원
포커스 관리: 명확한 포커스 스타일 및 포커스 트랩
스크린 리더 지원: 적절한 역할(role) 및 레이블 제공

폰트 설정

이 디자인 시스템은 기본적으로 Pretendard 또는 Noto Sans KR 폰트를 사용합니다. 폰트는 패키지에 포함되지 않으므로, 사용하는 프로젝트에서 직접 로드해야 합니다.

방법 1: HTML head에 link 태그 추가 (권장)

Pretendard 사용 시:

<link
  rel="stylesheet"
  as="style"
  crossorigin
  href="https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard.min.css"
/>

Noto Sans KR 사용 시:

<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link
  href="https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;600;700;800&display=swap"
  rel="stylesheet"
/>

방법 2: CSS에서 @import 사용

프로젝트의 전역 CSS 파일에 추가:

/* Pretendard */
@import url('https://cdn.jsdelivr.net/gh/orioncactus/[email protected]/dist/web/static/pretendard.min.css');

/* 또는 Noto Sans KR */
@import url('https://fonts.googleapis.com/css2?family=Noto+Sans+KR:wght@300;400;500;600;700;800&display=swap');

방법 3: 다른 폰트 사용하기

CSS 변수를 오버라이드하여 다른 폰트를 사용할 수 있습니다:

:root {
  --font-family-body: 'Your Font', sans-serif;
}

주의사항

CDN 사용 시: 외부 네트워크 요청이 필요하며, CDN이 다운되면 폰트가 로드되지 않을 수 있습니다.
프라이버시 정책: 일부 환경에서는 외부 CDN 접근이 제한될 수 있습니다.
오프라인 지원: 오프라인 환경이 필요한 경우, 폰트 파일을 프로젝트에 직접 포함시키는 것을 권장합니다.

추가 문서

스타일 설정 가이드 - 스타일 설정 방법
트러블슈팅 - 문제 해결 가이드

라이선스

MIT

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

modu-inning-design-system

기술 스택

시작하기

사전 요구사항

설치

개발 서버 실행

Storybook 실행

빌드

컴포넌트 라이브러리 빌드

Storybook 빌드

버전 관리 및 배포

버전 업데이트

배포

타입 체크

코드 품질 관리

ESLint

Prettier

VSCode 설정

컴포넌트 구조

Atoms (원자)

Molecules (분자)

Organisms (유기체)

프로젝트 구조

컴포넌트 개발

Atomic Design 분류

테마 및 다크 모드

라이트 모드 (기본)

다크 모드 사용

설치 및 사용하기

1. 패키지 설치

2. CSS 파일 설정

3. Tailwind Config 설정

4. 컴포넌트 사용

기본 사용 예시

스타일만 사용하기

웹 접근성 (A11y)

폰트 설정

방법 1: HTML head에 link 태그 추가 (권장)

방법 2: CSS에서 @import 사용

방법 3: 다른 폰트 사용하기

주의사항

추가 문서

라이선스