🎨 ZUM Design System

ZUM Design System을 Sass 기반의 스타일링과 CSS 유틸리티로 제공하는 패키지입니다.

🌟 주요 기능

• 디자인 토큰: 피그마와 연동된 디자인 토큰을 활용하여 일관된 스타일 적용
• Sass Mixin: 재사용 가능한 Mixin을 통해 디자인 토큰 적용
• 유틸리티 클래스: Sass를 사용하지 않는 환경에서도 클래스 사용 가능
• Reset CSS: 프로젝트 스타일 초기화를 위한 Reset CSS 제공

🚀 실행

스토리북을 실행해 작업된 디자인 시스템을 확인할 수 있습니다.

pnpm storybook

📦 설치

pnpm add -D @zuminternet/design-system

🛠️ Sass (권장 방법)

• 디자인 토큰만으로 스타일을 적용하기 위해 Mixin 사용이 권장됩니다.
• Sass를 사용하는 환경에서 아래와 같이 설정할 수 있습니다.

/* Webpack's sass-loader
   See: https://webpack.js.org/loaders/sass-loader/#resolving-import-and-use-at-rules */
@import '~@zuminternet/design-system/src/styles/zds.scss';

/* Sass `pkg:` Importers (Dart Sass 1.71.0 or later)
   See: https://sass-lang.com/blog/announcing-pkg-importers */
@use 'pkg:@zuminternet/design-system/scss';

.container {
  @include radius-999;
}

✨ Pure CSS

Sass를 사용하지 않는 환경에서도 디자인 시스템을 사용할 수 있습니다. 아래는 기본적인 사용 예제입니다.

import '@zuminternet/design-system'

function App() {
  return <div className="radius-999" />
}

🔄 Reset 적용

• 기본적으로 reset 스타일은 포함되지 않습니다.
• 신규 프로젝트 혹은 필요한 프로젝트에서는 아래와 같이 별도로 reset을 포함시킬 수 있습니다.

@import '@zuminternet/design-system/reset';

📊 z-index 적용

• @include z(...) 믹스인을 통해 z-index를 일관성 있게 관리합니다.
• 별도로 z-index 숫자를 직접 작성하지 않고, 계층 구조에 따라 자연스럽게 정렬되어 유지보수성을 높입니다.

⚙️ Z-Index 구조 및 계층 예시

| Layer | Base Z-Index | Level Steps (lowest → highest) | 설명 및 사용 예시 | | ------- | ------------ | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- | | hidden | -6 | -5, -4, -3, -2, -1 | 요소를 시각적으로 숨기거나 탭 순서에서 제외하고 싶을 때 사용. 예: 일시적으로 가려야 하는 툴팁, 미리 렌더링된 오프스크린 UI 등 | | base | 0 | 1, 2, 3, 4, 5 | 가장 일반적인 콘텐츠에 사용. 예: 기본적인 페이지 콘텐츠, 카드, 리스트 등 | | floated | 100 | 101, 102, 103, 104, 105 | 살짝 떠 있는 요소. 예: 드롭다운, 호버 박스, badge 등 | | surface | 200 | 201, 202, 203, 204, 205 | 주요 인터페이스 표면. 예: 고정된 헤더/푸터, 고정된 버튼 등 | | overlay | 300 | 301, 302, 303, 304, 305 | UI의 일부를 덮는 요소. 예: 로딩 스피너, 사이드패널, dim 처리 | | modal | 400 | 401, 402, 403, 404, 405 | 사용자 인터랙션을 차단하고 집중시키는 창. 예: 모달 창, 경고 창 등 | | system | 500 | 501, 502, 503, 504, 505 | 시스템 레벨 인터페이스. 예: 토스트 메시지, 글로벌 알림, 접근성 오버레이 등 |

🧩 Base / Hidden의 위치

• base와 hidden은 주로 플랫한 콘텐츠나 시각적 요소를 제거해야 할 경우에 적합합니다.
• 그러나 이 두 레이어는 보통 floated~system 같은 상위 z-index 계층 내부의 새로운 stacking context 안에서 사용하는 것이 권장됩니다.

  예: 하나의 모달 안에서 특정 요소들의 인덱스를 조정할 때

🎯 사용 예시

@include z(base, normal); // z-index: 3 (relative)
@include z(floated, higher); // z-index: 104 (relative)
@include z(overlay, lowest); // z-index: 301 (relative)

@include z(absolute, surface, normal); // position: absolute; z-index: 203;
@include z(fixed, modal, highest); // position: fixed; z-index: 405;