Colors

KRDS 색상 시스템을 Tailwind CSS로 사용하는 방법

빠른 요약

krds- 접두사를 사용하여 Tailwind 기본 색상과 KRDS 색상을 구분합니다.

Tailwind 기본 색상

예: bg-gray-50

KRDS 색상 (krds- 접두사)

예: bg-krds-gray-50

개요

HANUI는 KRDS(대한민국 디자인 시스템) 색상 시스템을 Tailwind CSS에서 사용할 수 있도록 통합했습니다. Tailwind의 기본 색상(gray, red, blue 등)과 충돌을 피하기 위해 krds- 접두사를 붙인 별도 네임스페이스를 사용합니다.

핵심: krds- 접두사를 사용하면 Tailwind 기본 색상과 KRDS 색상이 공존할 수 있습니다. 필요에 따라 둘 다 사용할 수 있습니다.

KRDS 색상 시스템 통합

Tailwind의 기본 색상(gray, red, blue 등)과 충돌을 피하기 위해 krds- 접두사를 붙인 별도 네임스페이스를 사용합니다.

왜 krds- 접두사를 사용하나요?

Tailwind CSS는 기본적으로 gray, red, blue 등의 색상을 제공합니다. KRDS 색상도 같은 이름을 사용하면 충돌이 발생합니다. 예를 들어:

Tailwind 기본 색상

gray-50, gray-100, gray-200...

예: bg-gray-50

KRDS 색상 (krds- 접두사)

krds-gray-50, krds-primary-60...

예: bg-krds-gray-50

핵심: krds- 접두사를 사용하면 Tailwind 기본 색상과 KRDS 색상이 공존할 수 있습니다. 필요에 따라 둘 다 사용할 수 있습니다.

구현 방법

@hanui/react/variables.css에서 KRDS 색상을 CSS 변수로 정의하고,tailwind.config.ts에서 krds- 접두사를 붙여 Tailwind 유틸리티로 사용할 수 있도록 매핑합니다.

1. variables.css - CSS 변수 정의

2. tailwind.config.ts - krds- 접두사로 매핑

사용 방법

krds- 접두사를 붙인 클래스명을 사용합니다.

KRDS 색상 사용 예시

주의:

  • 숫자 스케일도 자동 전환됨: bg-krds-gray-5, text-krds-gray-10 같은 숫자 스케일도 CSS 변수를 통해 자동 전환됩니다. variables.css의 .dark에서 변수 값을 재정의하므로 dark: 접두사가 필요 없습니다.
  • text-white 사용: text-white는 순수 흰색(#ffffff) CSS 변수를 사용합니다. 다크 모드에서도 항상 흰색이므로, 배경이 모드에 따라 변한다면 KRDS 색상 변수(text-krds-white 등)를 사용하세요. 순수 흰색이 필요한 경우에만 사용하세요.

참고: Tailwind 기본 색상(gray-50, red-500 등)도 그대로 사용할 수 있습니다. KRDS 색상은 krds- 접두사가 붙은 것만 사용하면 됩니다.

색상 (Colors)

KRDS 색상 시스템은 접근성을 최우선으로 하며, WCAG 2.1 AA 기준을 준수합니다.

Base Colors (기본 색상)

흰색과 검은색은 모드에 따라 자동으로 반전됩니다. 순수 흰색/검은색이 필요한 경우에는 white와 black을 사용하세요.

bg-krds-white

기본 모드: 흰색, 다크 모드: 검은색 (자동 반전)

bg-krds-black

기본 모드: 검은색, 다크 모드: 흰색 (자동 반전)

차이점:

  • krds-white/krds-black: 모드에 따라 자동 반전 (권장)
  • white/black: 모드 무관, 항상 동일 (순수 색상이 필요한 경우)

Primary Colors

bg-krds-primary-50

Primary - 주요 상호작용

hover:bg-krds-primary-60

Primary Hover

Gray Scale

Gray는 Surface(배경/표면)로 0, 5, 10 세 가지를 사용합니다.

bg-krds-white

Surface 0 - 기본 배경

bg-krds-gray-5

Surface 5 - 보조 배경

bg-krds-gray-10

Surface 10 - 강조 배경

bg-krds-gray-20

구분선, 테두리

bg-krds-gray-40

비활성화

bg-krds-gray-50

비활성화

text-krds-gray-70

보조 텍스트

text-krds-gray-90

본문 텍스트

text-krds-gray-95

굵은 텍스트

System Colors

Danger - 오류, 삭제icon-krds-danger-50 (다크: 20) / text-krds-danger-60 (다크: 20) /
bg-krds-danger-5 (다크: 95) / border-krds-danger-10 (다크: 90)
Warning - 경고, 주의icon-krds-warning-50 (다크: 20) / text-krds-warning-60 (다크: 20) /
bg-krds-warning-5 (다크: 95) / border-krds-warning-10 (다크: 90)
Success - 완료, 성공icon-krds-success-50 (다크: 20) / text-krds-success-60 (다크: 20) /
bg-krds-success-5 (다크: 95) / border-krds-success-10 (다크: 90)
Info - 정보, 안내icon-krds-information-50 (다크: 20) / text-krds-information-60 (다크: 20) /
bg-krds-information-5 (다크: 95) / border-krds-information-10 (다크: 90)

의미 기반 색상 (Semantic Color Tokens)

기본 모드와 다크 모드에서 text, base, surface의 기준이 다릅니다. 예를 들어 Primary 색상의 경우:

기본 모드

  • base = 50
  • text = 60
  • surface = 5

다크 모드

  • base = 50
  • text = 20
  • surface = 95

이를 해결하기 위해 Semantic 변수를 사용하여 모드에 따라 자동으로 올바른 색상이 적용되도록 설정했습니다.

1. variables.css - Semantic 변수 정의

2. tailwind.config.ts - Semantic 이름 매핑

Semantic 변수 vs 숫자 스케일

둘 다 자동 전환되지만, 사용 목적이 다릅니다. 언제 무엇을 사용해야 할까요?

Semantic 변수 (권장)

bg-krds-primary-surface, text-krds-primary-text

  • 의미 기반 이름(surface, text, base)
  • CSS 변수를 통해 자동 전환됨
  • 모드에 따라 적절한 숫자 값 자동 선택
  • 라이트 모드: surface=5, 다크 모드: surface=95

숫자 스케일

bg-krds-gray-5, text-krds-gray-90

  • 구체적인 색상 값(5, 90 등)을 직접 지정
  • CSS 변수를 통해 자동 전환됨
  • 항상 같은 숫자(5)를 참조
  • 라이트 모드: 밝은 색, 다크 모드: 어두운 색

언제 무엇을 사용하나요?

  • Semantic 변수 권장: 일반적인 UI 컴포넌트(버튼, 카드, 알림 등)에서 의미에 맞는 색상을 사용할 때
  • 숫자 스케일 사용: 특정 색상 값이 필요한 경우(예: 디자인 시스템에서 정확히 5번 색상을 지정해야 할 때)

사용 가능한 Semantic 변수

다음 컬러들이 Semantic 변수를 지원합니다:

Primary

  • text-krds-primary-text
  • bg-krds-primary-surface
  • bg-krds-primary-base

Secondary

  • text-krds-secondary-text
  • bg-krds-secondary-surface
  • bg-krds-secondary-base

Accent (강조)

  • text-krds-accent-text
  • bg-krds-accent-surface
  • bg-krds-accent-base

Danger (위험/에러)

  • text-krds-danger-text
  • bg-krds-danger-surface
  • border-krds-danger-border

다크 모드

HANUI는 CSS 변수를 활용하여 다크 모드를 자동으로 지원합니다. html요소에 dark클래스를 추가하면 모든 KRDS 색상이 자동으로 전환됩니다.

작동 원리

CSS 변수는 상위 요소의 값을 상속받습니다. variables.css에서 :root와 .dark에서 같은 변수명을 사용하지만 다른 값을 할당하여, 모드에 따라 자동으로 색상이 변경되도록 구현했습니다.

1. variables.css - CSS 변수 정의

2. tailwind.config.ts - CSS 변수 참조

3. 실제 사용 - 자동 전환

자동 전환 예시

모든 KRDS 색상(숫자 스케일, semantic 변수, `krds-white`/`krds-black` 모두)은 CSS 변수를 통해 자동 전환됩니다.

숫자 스케일 - 자동 전환

Semantic 변수 - 자동 전환

Base Colors - 자동 반전

다크 모드 활성화 방법

html요소에 dark 클래스를 추가하면 됩니다.

주의사항

text-white 사용: text-white는 순수 흰색(#ffffff) CSS 변수를 사용하지만, 모드에 따라 값이 변하지 않으므로 항상 흰색입니다. 배경이 모드에 따라 변한다면 KRDS 색상 변수(text-krds-gray-10 등)를 사용하세요. 순수 흰색이 필요한 경우(로고, 아이콘 등)에만 사용하세요.

핵심: 모든 KRDS 색상(숫자 스케일, semantic 변수, `krds-white`/`krds-black` 모두)은 CSS 변수를 통해 자동 전환되므로, dark: 접두사가 필요 없습니다. html 요소에 dark 클래스만 추가하면 됩니다.

모범 사례

의미 있는 색상 사용

System Colors를 올바른 의미로 사용하세요.

참고 자료

KRDS 색상 시스템

색상 팔레트, 접근성 기준

(새 창 열림)