@deepnoid-ui

본부 내 프로젝트에서 공통으로 사용하는 TailwindCSS 기반 UI 컴포넌트 라이브러리입니다.

모노레포 구조로 구성되어 있으며, Storybook을 통해 컴포넌트 문서화 및 테스트를 수행합니다.

• Storybook 앱 위치: ./apps/docs

📦 Monorepo 구성

이 모노레포에는 다음 패키지들이 포함되어 있습니다.

• ./packages/eslint-config
  공통 ESLint 규칙 정의

• ./packages/tailwind-config
  Tailwind CSS v4 마이그레이션 적용 (CSS-First 기반 디자인 토큰 및 모듈화된 프리셋 제공)

• ./packages/typescript-config
  공통 TypeScript 설정 정의

• ./packages/ui
  TailwindCSS 기반 UI 컴포넌트 패키지

설치

yarn add @deepnoid/ui

Tailwind CSS v4 설정

@deepnoid/ui는 Tailwind CSS v4의 CSS-First 아키텍처를 도입하여 플러그인(plugin.ts)과 tailwind.config.ts를 완전히 제거했습니다. 설정을 적용하려면 앱의 엔트리 CSS 파일(예: global.css)에 다음과 같이 import 해야 합니다.

/* global.css */
@import "tailwindcss";
@import "@deepnoid/ui/style.css";

/* Deepnoid UI 프리셋/폰트/@source가 포함된 엔트리 CSS를 로드합니다. */
/* (선택) 앱에서 사용하는 소스 경로를 추가 스캔하고 싶다면 @source 를 추가하세요. */
/* @source "./src/**/*.{ts,tsx,js,jsx}"; */

/* 특정 프로젝트 전용 커스텀 색상(테마) 덮어쓰기 */
:root, .light, [data-theme="light"],
.dark, [data-theme="dark"] {
  --color-primary-soft: #EFF8FF;
  /* 동적 CSS 색상 매핑을 위해 --color- 접두사를 사용합니다. */
}

Tailwind CSS v4 아키텍처 및 확장 관리

유지보수와 확장을 쉽게 하기 위해 설정들을 여러 CSS 파일로 분리하여 관리합니다.

packages/tailwind-config/
├── scripts/
│   └── generate-border.ts    # border 유틸리티 자동 생성 스크립트 (build-time)
├── src/
│   ├── preset.css            # 모든 CSS를 하나로 묶는 @import 진입점 (최상위 설정)
│   └── styles/
│       ├── generated/
│       │   └── border.css    # 스크립트 실행으로 자동 생성된 파일
│       ├── tokens/
│       │   ├── theme.css     # 폰트, Radius, Shadow, Spacing 등
│       │   └── colors.css    # 원시(Primitive) 기본 색상 및 시맨틱 매핑
│       ├── utilities/
│       │   └── scrollbar.css # 브라우저 스크롤바 커스텀 유틸리티 (@utility)
│       └── animation.css     # 타이밍, Keyframes, 애니메이션 테마 변수

참고 사항:

• 더 이상 tailwind.config.ts에서 하드코딩으로 컴포넌트나 테마를 생성하지 않습니다.
• 유틸리티 클래스가 반복되는 경우(예: border-t-sm, border-x-md), JS 플러그인을 다시 부활시키지 않고 scripts/ 폴더 내에 TS/JS 코드 생성기(Generator) 를 작성하여 빌드 타임에 정적인 CSS 객체를 뽑아냅니다.

개발 환경

[email protected]
[email protected]
[email protected]

Storybook

• 개발 환경: http://localhost:6006
• ~~테스트 서버: http://172.30.10.148:6006~~

yarn install
yarn build
yarn dev

디자인 시스템

• Design System (Figma)

Publish

1. Storybook

테스트 서버 Storybook 배포 방법:

• ./storybook.Dockerfile 파일 참고
• ./docker-compose.yml 파일 참고

프로젝트 루트 경로에서 아래와 같은 커맨드를 통해 Storybook을 테스트 서버에 배포합니다.

// 서비스에 필요한 컨테이너를 생성하고 실행
  docker compose up

// 실행 중인 컨테이너를 멈추고 생성된 컨테이너나 이미지를 제거
  docker compose down

2. NPM (Node Package Manager)

커맨드 라인을 사용하여 NPM 배포:

yarn build

yarn publish:npm

Gitlab Action을 사용하여 NPM 배포:

release 브랜치에 머지했을 때 배포 파이프라인 실행되도록 스크립트가 작성되어 있습니다.

• ./.gitlab-ci.yml 파일 참고

Claude Code 스킬

@deepnoid/ui 컴포넌트를 AI 에이전트(Claude Code, Cursor 등)와 함께 사용할 때, 스킬을 설치하면 컴포넌트 사용법/규칙/토큰을 자동으로 안내받을 수 있습니다.

# 소비 프로젝트 루트에서
cp -r node_modules/@deepnoid/ui/skills/deepnoid-ui .claude/skills/

설치 후 @deepnoid/ui 관련 질문 시 자동으로 가이드가 활성화됩니다.

스킬 업데이트: yarn upgrade @deepnoid/ui 후 위 cp 명령을 다시 실행

기타

turborepo를 활용하여 프로젝트를 구성했으니 내용 참고해주시기 바랍니다.