Laiteu Design System

Laiteu 프로젝트를 위한 디자인 시스템 패키지입니다.

설치

GitHub에서 설치

# pnpm (권장)
pnpm add https://github.com/sehandev/laiteu-design-system

# npm
npm install https://github.com/sehandev/laiteu-design-system

# yarn
yarn add https://github.com/sehandev/laiteu-design-system

특정 버전 또는 브랜치 설치

# 특정 버전 설치
pnpm add https://github.com/sehandev/laiteu-design-system#v1.0.0

# 특정 브랜치 설치
pnpm add https://github.com/sehandev/laiteu-design-system#main

npm 패키지로 설치 (배포 후)

npm install laiteu-design-system
# 또는
yarn add laiteu-design-system
# 또는
pnpm add laiteu-design-system

개발 환경 세팅

1. 저장소 클론 및 의존성 설치

git clone [email protected]:sehandev/laiteu-design-system.git
cd laiteu-design-system
npm install
# 또는
yarn install

2. 개발 서버 실행

npm run dev
# 또는
yarn dev

3. Storybook 실행

npm run storybook
# 또는
yarn storybook

Storybook은 기본적으로 http://localhost:6006 에서 실행됩니다.

4. 빌드

프로덕션 빌드를 생성합니다:

npm run build
# 또는
yarn build

빌드 결과물은 dist 디렉토리에 생성됩니다.

5. 타입 체크

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

npm run type-check
# 또는
yarn type-check

6. Lint

코드 품질을 검사합니다:

npm run lint
# 또는
yarn lint

사용 방법

1. Peer Dependencies 설치

pnpm add react react-dom framer-motion react-dropzone

2. Tailwind CSS v4 설정

postcss.config.js 생성/수정

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

Tailwind CSS v4 설치

pnpm add -D tailwindcss@^4.0.0 @tailwindcss/postcss

3. CSS 스타일 import

메인 CSS 파일에 추가 (예: src/index.css):

@import 'tailwindcss';

/* Laiteu Design System 스타일 import */
@import 'laiteu-design-system/dist/style.css';

또는 JavaScript/TypeScript 파일에서:

import 'laiteu-design-system/dist/style.css';

4. 컴포넌트 사용

import { Button, Typography, Input } from 'laiteu-design-system';

function App() {
  return (
    <div className="laiteu-ds">
      <Typography variant="h1">환영합니다</Typography>
      <Input placeholder="이름을 입력하세요" />
      <Button variant="primary">제출</Button>
    </div>
  );
}

사용 가능한 컴포넌트

// 버튼
import { Button, IconButton, NavigationIconButton } from 'laiteu-design-system';

// 타이포그래피
import { Typography } from 'laiteu-design-system';

// 폼 컴포넌트
import {
  Input,
  PasswordInput,
  SearchInput,
  FullWidthSearchInput,
  Textarea,
  TagInput,
} from 'laiteu-design-system';

// 드롭다운
import { Dropdown, Select, Combobox } from 'laiteu-design-system';

// 업로드
import { ImageUpload, AvatarInput } from 'laiteu-design-system';

// 다이얼로그
import {
  AlertDialog,
  Dialog,
  DialogTrigger,
  DialogContent,
  DialogTitle,
  DialogDescription,
} from 'laiteu-design-system';

// 기타
import {
  Tag,
  TagList,
  Category,
  CategoryGroup,
  LoadingCircle,
} from 'laiteu-design-system';

// 아이콘
import {
  AlarmIcon,
  AlertTriangleIcon,
  BookmarkIcon,
  BookmarkOutlinedIcon,
  CheckIcon,
  ChevronRightIcon,
  CircleUploadIcon,
  CloseIcon,
  ConfirmIcon,
  DeleteIcon,
  ImageUploadIcon,
  MyPageIcon,
  SearchIcon,
  SelectIcon,
  TrashIcon,
  TrashcanIcon,
  UploadIcon,
  UploadIconActive,
} from 'laiteu-design-system';

아이콘 사용 예시

import { SearchIcon, CloseIcon } from 'laiteu-design-system';

function SearchBar() {
  return (
    <div className="flex items-center gap-2">
      <SearchIcon className="w-5 h-5 text-gray-500" />
      <input type="text" />
      <CloseIcon className="w-5 h-5 cursor-pointer" />
    </div>
  );
}

AlertDialog 사용 예시

import { AlertDialog } from 'laiteu-design-system';
import { useState } from 'react';

function DeleteConfirmExample() {
  const [open, setOpen] = useState(false);

  return (
    <>
      <button onClick={() => setOpen(true)}>파일 삭제</button>
      <AlertDialog
        variant="delete"
        open={open}
        onOpenChange={setOpen}
        description="해당 파일을 삭제하시면 삭제된 파일은 복구할 수 없습니다.
파일을 삭제하시겠습니까?"
        cancelText="취소"
        confirmText="확인"
        showCancel={true}
        onConfirm={() => console.log('삭제 확인')}
        onCancel={() => console.log('취소')}
      />
    </>
  );
}

// 한 개 버튼 (확인만)
function SuccessExample() {
  const [open, setOpen] = useState(false);

  return (
    <AlertDialog
      variant="confirm"
      open={open}
      onOpenChange={setOpen}
      description="작업이 완료되었습니다."
      confirmText="확인"
      showCancel={false}
      onConfirm={() => console.log('확인')}
    />
  );
}

AlertDialog variants:

• delete: 삭제 확인 (빨간색 휴지통 아이콘)
• error: 오류 알림 (빨간색 경고 아이콘)
• confirm: 확인 알림 (초록색 체크 아이콘)

테마 및 스타일링

테마 적용

앱을 laiteu-ds 클래스로 감싸세요:

function App() {
  return <div className="laiteu-ds">{/* 앱 콘텐츠 */}</div>;
}

다크 모드

<div className="laiteu-ds" data-theme="dark">
  {/* 앱 콘텐츠 */}
</div>

커스텀 색상 시스템

디자인 시스템은 CSS 변수를 활용한 커스텀 색상 팔레트를 제공합니다:

/* 색상 변수들 */
--laiteu-foreground:
  전경색 (주요 텍스트) --laiteu-reverse: 반전 색상 --laiteu-background: 기본
    배경색 --laiteu-secondary: 보조 색상 --laiteu-gs-01,
  --laiteu-gs-02: 그레이스케일 색상 --laiteu-bg-02, --laiteu-bg-03,
  --laiteu-bg-04: 배경 레벨 --laiteu-grayscale-01, --laiteu-grayscale-02,
  --laiteu-grayscale-03: 그레이스케일 --laiteu-text-gs: 텍스트 그레이스케일;

상태별 색상

--laiteu-status-search: 검색 상태 색상 --laiteu-status-opening: 진행중 상태 색상
  --laiteu-status-all: 전체 상태 색상 --laiteu-status-default: 기본 상태 색상;

사용 예시

<div className="bg-default text-foreground">
  <Button className="bg-secondary">클릭하세요</Button>
</div>

커스텀 색상 클래스

Tailwind 유틸리티 클래스로 사용 가능:

• foreground - 주요 텍스트 색상
• reverse - 반전 색상 (foreground 반대)
• default - 배경 색상
• secondary - 보조 색상
• gs01, gs02 - 그레이스케일
• bg02, bg03, bg04 - 배경 레벨
• grayscale01, grayscale02, grayscale03 - 그레이스케일 변형
• textgs - 텍스트 그레이스케일
• status-search, status-opening, status-all, status-default - 상태 색상

반응형 브레이크포인트

lg: 1024px   // 데스크탑
xl: 1336px   // 대형 데스크탑
2xl: 1440px  // 초대형 데스크탑

사용 예시:

<div className="w-full lg:w-1/2 xl:w-1/3">반응형 컨테이너</div>

확장된 Spacing

기본 Tailwind spacing에 추가된 값들:

0.5: 0.125rem  (2px)
1.5: 0.375rem  (6px)
2.5: 0.625rem  (10px)
3.5: 0.875rem  (14px)
4.5: 1.125rem  (18px)
5.5: 1.375rem  (22px)
6.5: 1.625rem  (26px)

커스텀 트랜지션

// 트랜지션 지속 시간
duration-180: 180ms
duration-300: 300ms

버전 관리 및 배포

자동 버전 관리

이 프로젝트는 Conventional Commits와 standard-version을 사용하여 자동으로 버전을 관리합니다.

커밋 메시지 규칙

<type>(<scope>): <subject>

# 예시
feat(Button): 새로운 variant 추가
fix(Input): placeholder 색상 수정
docs(README): 설치 가이드 업데이트

타입:

• feat: 새로운 기능
• fix: 버그 수정
• docs: 문서 변경
• style: 코드 스타일 변경 (포맷팅 등)
• refactor: 리팩토링
• perf: 성능 개선
• test: 테스트 추가/수정
• chore: 기타 변경사항

버전 릴리스

수동 릴리스:

# Patch 버전 증가 (1.0.0 -> 1.0.1)
pnpm release

# Minor 버전 증가 (1.0.0 -> 1.1.0)
pnpm release:minor

# Major 버전 증가 (1.0.0 -> 2.0.0)
pnpm release:major

자동 릴리스 (GitHub Actions):

1. main 브랜치에 변경사항을 푸시하면 자동으로 CI가 실행됩니다
2. GitHub Actions > Release & Publish 워크플로우를 수동으로 실행하여 릴리스할 수 있습니다
3. 릴리스 타입(patch/minor/major)을 선택하면 자동으로:
   • 버전이 업데이트되고
   • CHANGELOG.md가 생성되며
   • Git 태그가 생성되고
   • NPM에 배포됩니다

NPM 배포

필수 설정

1. NPM 토큰 설정

   • NPM 계정에서 Access Token 생성
   • GitHub 저장소 Settings > Secrets and variables > Actions
   • NPM_TOKEN secret 추가

2. package.json 확인

   • name: NPM 패키지명이 올바른지 확인
   • version: 현재 버전 확인
   • files: 배포할 파일 목록 확인

수동 배포

# 빌드 및 NPM 배포
pnpm publish:npm

CI/CD 워크플로우

CI (Continuous Integration)

PR 또는 main 브랜치에 푸시할 때마다 자동으로 실행됩니다:

• 의존성 설치
• 타입 체크
• Lint 검사
• 빌드
• Storybook 빌드

자동 릴리스

main 브랜치에 푸시되면 자동으로:

1. 커밋 메시지를 분석하여 버전 업데이트
2. CHANGELOG 생성
3. Git 태그 생성 및 푸시
4. NPM에 자동 배포
5. GitHub Release 생성

수동 릴리스

GitHub Actions 탭에서 "Release & Publish" 워크플로우를 수동으로 실행하여 원하는 릴리스 타입을 선택할 수 있습니다.

CHANGELOG

모든 버전 변경사항은 CHANGELOG.md에 자동으로 기록됩니다. Conventional Commits를 따르면 자동으로 적절한 카테고리로 분류됩니다.

프로젝트 구조

lds/
├── .storybook/          # Storybook 설정
├── src/
│   ├── components/      # 컴포넌트들
│   │   ├── icons/       # SVG 아이콘 컴포넌트
│   │   ├── Button/
│   │   ├── Input/
│   │   └── ...
│   ├── styles/          # 전역 스타일 (Tailwind v4 @theme)
│   ├── utils/           # 유틸리티 함수
│   └── index.ts         # 메인 엔트리 포인트
├── dist/                # 빌드 출력 디렉토리
├── package.json
├── vite.config.ts       # Vite 설정
├── postcss.config.js    # PostCSS 설정
└── tsconfig.json        # TypeScript 설정

기술 스택

• React 18: UI 라이브러리
• TypeScript: 타입 안정성
• Tailwind CSS v4: CSS-first 설정, 향상된 성능
• Vite: 빌드 도구 및 개발 서버
• Storybook 7: 컴포넌트 문서화 및 개발
• Framer Motion: 애니메이션
• Class Variance Authority (CVA): 컴포넌트 variant 관리
• clsx & tailwind-merge: 클래스명 조합 유틸리티

패키지 의존성

핵심 의존성

• class-variance-authority: 컴포넌트 variant 패턴
• clsx: 조건부 클래스명 결합
• framer-motion: 애니메이션 라이브러리
• react-dropzone: 파일 업로드 기능
• tailwind-merge: Tailwind 클래스명 충돌 해결

TypeScript 지원

패키지는 TypeScript 정의를 기본 제공합니다.

import type { ButtonProps } from 'laiteu-design-system';

const CustomButton: React.FC<ButtonProps> = (props) => {
  return <Button {...props} />;
};

빠른 시작 가이드

다른 프로젝트에서 사용하는 전체 예시:

1. 설치

pnpm add https://github.com/sehandev/laiteu-design-system
pnpm add react react-dom framer-motion react-dropzone
pnpm add -D tailwindcss@^4.0.0 @tailwindcss/postcss

2. postcss.config.js

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

3. src/index.css

@import 'tailwindcss';
@import 'laiteu-design-system/dist/style.css';

4. App.tsx

import { Button, Input, Typography } from 'laiteu-design-system';

export default function App() {
  return (
    <div className="laiteu-ds p-8">
      <Typography variant="h1" className="mb-4">
        Laiteu Design System
      </Typography>
      <Input placeholder="이름을 입력하세요" className="mb-4" />
      <Button variant="primary">제출</Button>
    </div>
  );
}

완료! 이제 Laiteu Design System을 사용할 수 있습니다.

문제 해결

"모듈 또는 해당 형식 선언을 찾을 수 없습니다" 오류

이 오류가 발생하면 다음 단계를 시도하세요:

1. node_modules 재설치

# node_modules 및 lock 파일 삭제
rm -rf node_modules pnpm-lock.yaml  # pnpm 사용 시
# 또는
rm -rf node_modules package-lock.json  # npm 사용 시
# 또는
rm -rf node_modules yarn.lock  # yarn 사용 시

# 재설치
pnpm install

2. 패키지 재설치

# 패키지 제거
pnpm remove laiteu-design-system

# 캐시 클리어 후 재설치
pnpm store prune
pnpm add https://github.com/sehandev/laiteu-design-system

3. TypeScript 설정 확인

tsconfig.json에 다음 설정이 있는지 확인:

{
  "compilerOptions": {
    "moduleResolution": "bundler", // 또는 "node"
    "resolveJsonModule": true,
    "esModuleInterop": true
  }
}

4. IDE 재시작

VSCode 등의 IDE를 재시작하면 타입 정의가 인식될 수 있습니다.

# VSCode에서
Cmd/Ctrl + Shift + P -> "TypeScript: Restart TS Server"

5. 임시 타입 정의 (최후의 수단)

위 방법들이 모두 실패하면 프로젝트의 src 폴더에 laiteu-design-system.d.ts 파일 생성:

declare module 'laiteu-design-system' {
  export * from 'laiteu-design-system/dist';
}

declare module 'laiteu-design-system/dist/style.css' {
  const content: string;
  export default content;
}

Tailwind CSS 스타일이 적용되지 않는 경우

1. postcss.config.js 확인

export default {
  plugins: {
    '@tailwindcss/postcss': {},
  },
};

2. CSS import 순서 확인

@import "tailwindcss"가 먼저, 디자인 시스템 스타일이 나중에:

@import 'tailwindcss';
@import 'laiteu-design-system/dist/style.css';

3. Tailwind CSS v4 설치 확인

pnpm list tailwindcss
# tailwindcss 4.x.x 버전이어야 함

필요시:

pnpm add -D tailwindcss@^4.0.0 @tailwindcss/postcss

빌드 오류

PostCSS 관련 오류 발생 시:

# 모든 의존성 재설치
rm -rf node_modules pnpm-lock.yaml
pnpm install