refactor: Tailwind CSS 마이그레이션 및 색상 토큰 재구성 (v0.2.1)

CHANGELOG.md

@@ -7,6 +7,25 @@
 
 ## [Unreleased]
 
+## [0.2.1] - 2025-01-18
+
+### Changed
+
+- CSS 파일 구조 개선
+  - `src/styles/tailwind.css`를 관심사별로 분리
+  - `tokens/`: CSS 변수 정의 (colors, typography, shadows)
+  - `theme/`: Tailwind 테마 설정 (colors, typography)
+  - `utilities/`: 커스텀 유틸리티 클래스 (typography)
+- 색상 토큰 재구성
+  - `:root`에 실제 색상 이름으로 CSS 변수 정의 (`--color-orange-*`, `--color-green-*`, `--color-red-*`)
+  - `@theme`에서 시멘틱 색상으로 매핑 (`primary` → Orange, `secondary` → Green, `tertiary` → Red)
+  - 실제 색상(`bg-orange-500`)과 시멘틱 색상(`bg-primary-500`) 모두 사용 가능
+  - CSS 변수(`var(--color-orange-500)`, `var(--color-primary-500)`) 직접 사용 가능
+- README 업데이트
+  - 색상 사용 방법 명확화 (실제 색상 vs 시멘틱 색상)
+  - Tailwind 테마 커스터마이징 가이드 개선
+  - CSS 변수 사용 예시 추가
+
 ## [0.2.0] - 2025-01-14
 
 ### Added
@@ -176,7 +195,8 @@
 - Storybook 설정
 - Vitest 테스트 설정
 
-[Unreleased]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.2.0...HEAD
+[Unreleased]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.2.1...HEAD
+[0.2.1]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.1.6...v0.2.0
 [0.1.6]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.1.5...v0.1.6
 [0.1.5]: https://github.com/Team-NumberOne/daepiro-design-system/compare/v0.1.4...v0.1.5

README.md

@@ -143,14 +143,60 @@ import { Icon, Icons } from "@team-numberone/daepiro-design-system";
 
 ### Colors
 
+#### JavaScript/TypeScript에서 사용
+
 ```tsx
 import { colors } from "@team-numberone/daepiro-design-system";
 
-colors.O[500]; // Orange 500
-colors.Gre[300]; // Green 300
-colors.G[900]; // Gray 900
+// 실제 색상 팔레트 (디자인 토큰)
+colors.O[500];   // Orange 500 - #FF6929
+colors.Gre[300]; // Green 300 - #6ACF98
+colors.R[500];   // Red 500 - #FA2C1F
+colors.G[900];   // Gray 900 - #222530
+```
+
+**CSS 변수로 사용:**
+
+```css
+/* 실제 색상 이름 */
+background-color: var(--color-orange-500);
+color: var(--color-green-300);
+
+/* 시멘틱 색상 이름 */
+background-color: var(--color-primary-500);  /* Orange */
+color: var(--color-secondary-300);           /* Green */
+```
+
+#### Tailwind CSS 유틸리티 클래스로 바로 사용
+
+`@theme`에 정의된 색상은 Tailwind 유틸리티 클래스로 바로 사용할 수 있습니다:
+
+```tsx
+// 실제 색상 이름으로 사용
+<div className="bg-orange-500 text-white">Orange 배경</div>
+<div className="bg-green-500 text-white">Green 배경</div>
+<div className="bg-red-500 text-white">Red 배경</div>
+
+// 시멘틱 색상 이름으로 사용 (Orange → Primary, Green → Secondary, Red → Tertiary)
+<div className="bg-primary-500 text-white">Primary(Orange) 배경</div>
+<div className="bg-secondary-500 text-white">Secondary(Green) 배경</div>
+<div className="bg-tertiary-500 text-white">Tertiary(Red) 배경</div>
+
+// Gray 색상
+<div className="bg-gray-50 text-gray-900">Gray 배경</div>
+<div className="bg-gray-75">Gray-75 배경</div>
+<div className="text-gray-600">Gray 텍스트</div>
+
+// 모든 색상 스케일 사용 가능 (50-900)
+<div className="bg-primary-100 hover:bg-primary-200">호버 효과</div>
+<div className="bg-orange-100 hover:bg-orange-200">Orange 호버 효과</div>
 ```
 
+**색상 매핑:**
+- `orange-*` = `primary-*` (Orange → Primary)
+- `green-*` = `secondary-*` (Green → Secondary)
+- `red-*` = `tertiary-*` (Red → Tertiary)
+
 ### Typography
 
 ```tsx
@@ -175,12 +221,67 @@ shadows.large;
 
 이 디자인 시스템은 Tailwind CSS v4를 사용하며, `@theme` 문법을 통해 테마를 커스터마이징할 수 있습니다.
 
+#### 기본 사용법
+
+```tsx
+// 색상 사용
+<div className="bg-primary-500 text-white p-4 rounded-lg">
+  Primary 배경
+</div>
+
+// 타이포그래피 사용
+<h1 className="text-h1">제목 1</h1>
+<p className="text-body-1">본문 텍스트</p>
+```
+
+#### 테마 오버라이드 (사용처에서)
+
+디자인 시스템의 색상을 커스터마이징할 수 있습니다. 예를 들어, Primary 색상을 그린(Secondary)으로 변경:
+
 ```css
-/* 사용처에서 Tailwind 테마 오버라이드 */
+/* globals.css */
+@import "@team-numberone/daepiro-design-system/dist/index.css";
 @import "tailwindcss";
 
+/* Primary 색상을 Green으로 오버라이드 */
+@theme {
+  --color-primary-50: var(--color-green-50);
+  --color-primary-100: var(--color-green-100);
+  --color-primary-200: var(--color-green-200);
+  --color-primary-300: var(--color-green-300);
+  --color-primary-400: var(--color-green-400);
+  --color-primary-500: var(--color-green-500);
+  --color-primary-600: var(--color-green-600);
+  --color-primary-700: var(--color-green-700);
+  --color-primary-800: var(--color-green-800);
+  --color-primary-900: var(--color-green-900);
+}
+
+/* 디자인 시스템 컴포넌트의 CSS 변수도 오버라이드 */
+:root {
+  --color-primary-50: var(--color-green-50);
+  --color-primary-100: var(--color-green-100);
+  --color-primary-200: var(--color-green-200);
+  --color-primary-300: var(--color-green-300);
+  --color-primary-400: var(--color-green-400);
+  --color-primary-500: var(--color-green-500);
+  --color-primary-600: var(--color-green-600);
+  --color-primary-700: var(--color-green-700);
+  --color-primary-800: var(--color-green-800);
+  --color-primary-900: var(--color-green-900);
+}
+```
+
+이렇게 하면:
+- 사용처의 `bg-primary-500` 클래스가 Green 색상으로 적용됩니다
+- 디자인 시스템의 Button 컴포넌트도 Green 색상을 사용합니다
+- 디자인 시스템이 제공하는 `--color-green-*`, `--color-orange-*`, `--color-red-*` CSS 변수를 참조할 수 있습니다
+
+#### 커스텀 색상 정의
+
+```css
 @theme {
-  /* 색상 커스터마이징 */
+  /* 완전히 새로운 색상 정의 */
   --color-primary-500: #ff0000;
   --color-gray-900: #1a1a1a;
 
@@ -189,14 +290,6 @@ shadows.large;
 }
 ```
 
-또는 Tailwind 유틸리티 클래스를 직접 사용할 수 있습니다:
-
-```tsx
-<div className="bg-primary-500 text-white p-4 rounded-lg">
-  커스텀 스타일
-</div>
-```
-
 ## 🛠️ 개발
 
 ### 사전 요구사항

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@team-numberone/daepiro-design-system",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "대피로 디자인 시스템 - React 컴포넌트 라이브러리",
   "private": false,
   "packageManager": "[email protected]",

src/styles/tailwind.css

@@ -1,63 +1,13 @@
 @import "tailwindcss";
 
-@theme {
-  /* Colors - Primary (Orange) */
-  --color-primary-50: #fff0ea;
-  --color-primary-100: #ffd1bd;
-  --color-primary-200: #ffba9d;
-  --color-primary-300: #ff9b70;
-  --color-primary-400: #ff8754;
-  --color-primary-500: #ff6929;
-  --color-primary-600: #e86025;
-  --color-primary-700: #b54b1d;
-  --color-primary-800: #8c3a17;
-  --color-primary-900: #6b2c11;
+/* Import Design Tokens (CSS Variables in :root) */
+@import "./tokens/colors.css";
+@import "./tokens/typography.css";
+@import "./tokens/shadows.css";
 
-  /* Colors - Secondary (Green) */
-  --color-secondary-50: #e9f8f0;
-  --color-secondary-100: #bae9d0;
-  --color-secondary-200: #98deb9;
-  --color-secondary-300: #6acf98;
-  --color-secondary-400: #4dc585;
-  --color-secondary-500: #20b766;
-  --color-secondary-600: #1da75d;
-  --color-secondary-700: #178248;
-  --color-secondary-800: #126538;
-  --color-secondary-900: #0d4d2b;
+/* Import Tailwind Theme Configuration */
+@import "./theme/colors.css";
+@import "./theme/typography.css";
 
-  /* Colors - Tertiary (Red) */
-  --color-tertiary-50: #ffeae9;
-  --color-tertiary-100: #fdbeba;
-  --color-tertiary-200: #fd9e98;
-  --color-tertiary-300: #fc7269;
-  --color-tertiary-400: #fb564c;
-  --color-tertiary-500: #fa2c1f;
-  --color-tertiary-600: #e4281c;
-  --color-tertiary-700: #b21f16;
-  --color-tertiary-800: #8a1811;
-  --color-tertiary-900: #69120d;
-
-  /* Colors - Gray */
-  --color-gray-50: #f5f5f7;
-  --color-gray-75: #e4e5ea;
-  --color-gray-100: #c9ccd4;
-  --color-gray-200: #afb3bf;
-  --color-gray-300: #8b90a1;
-  --color-gray-400: #757a8f;
-  --color-gray-500: #525973;
-  --color-gray-600: #4b5169;
-  --color-gray-700: #3a3f52;
-  --color-gray-800: #2d313f;
-  --color-gray-900: #222530;
-
-  /* Typography */
-  --font-family-sans: Pretendard, -apple-system, BlinkMacSystemFont, system-ui,
-    sans-serif;
-
-  /* Shadows */
-  --shadow-floating: 2px 2px 4px 0 rgba(0, 0, 0, 0.1), 0 0 4px 0
-    rgba(0, 0, 0, 0.15);
-  --shadow-btn-pressed: 0 0 1px 0 rgba(34, 37, 48, 0.15), 1px 1px 2px 0
-    rgba(34, 37, 48, 0.15);
-  --shadow-dimmed: 0 0 8px 0 rgba(0, 0, 0, 0.1), 0 0 20px 0 rgba(0, 0, 0, 0.1);
-}
+/* Import Custom Utilities */
+@import "./utilities/typography.css";

src/styles/theme/colors.css

@@ -0,0 +1,87 @@
+/* Tailwind Theme - Colors */
+@theme {
+  /* Colors - Orange (for Tailwind utilities: bg-orange-500, text-orange-500, etc.) */
+  --color-orange-50: var(--color-orange-50);
+  --color-orange-100: var(--color-orange-100);
+  --color-orange-200: var(--color-orange-200);
+  --color-orange-300: var(--color-orange-300);
+  --color-orange-400: var(--color-orange-400);
+  --color-orange-500: var(--color-orange-500);
+  --color-orange-600: var(--color-orange-600);
+  --color-orange-700: var(--color-orange-700);
+  --color-orange-800: var(--color-orange-800);
+  --color-orange-900: var(--color-orange-900);
+
+  /* Colors - Green (for Tailwind utilities: bg-green-500, text-green-500, etc.) */
+  --color-green-50: var(--color-green-50);
+  --color-green-100: var(--color-green-100);
+  --color-green-200: var(--color-green-200);
+  --color-green-300: var(--color-green-300);
+  --color-green-400: var(--color-green-400);
+  --color-green-500: var(--color-green-500);
+  --color-green-600: var(--color-green-600);
+  --color-green-700: var(--color-green-700);
+  --color-green-800: var(--color-green-800);
+  --color-green-900: var(--color-green-900);
+
+  /* Colors - Red (for Tailwind utilities: bg-red-500, text-red-500, etc.) */
+  --color-red-50: var(--color-red-50);
+  --color-red-100: var(--color-red-100);
+  --color-red-200: var(--color-red-200);
+  --color-red-300: var(--color-red-300);
+  --color-red-400: var(--color-red-400);
+  --color-red-500: var(--color-red-500);
+  --color-red-600: var(--color-red-600);
+  --color-red-700: var(--color-red-700);
+  --color-red-800: var(--color-red-800);
+  --color-red-900: var(--color-red-900);
+
+  /* Colors - Gray (for Tailwind utilities: bg-gray-500, text-gray-500, etc.) */
+  --color-gray-50: var(--color-gray-50);
+  --color-gray-75: var(--color-gray-75);
+  --color-gray-100: var(--color-gray-100);
+  --color-gray-200: var(--color-gray-200);
+  --color-gray-300: var(--color-gray-300);
+  --color-gray-400: var(--color-gray-400);
+  --color-gray-500: var(--color-gray-500);
+  --color-gray-600: var(--color-gray-600);
+  --color-gray-700: var(--color-gray-700);
+  --color-gray-800: var(--color-gray-800);
+  --color-gray-900: var(--color-gray-900);
+
+  /* Semantic Colors - Primary (maps to Orange) */
+  --color-primary-50: var(--color-orange-50);
+  --color-primary-100: var(--color-orange-100);
+  --color-primary-200: var(--color-orange-200);
+  --color-primary-300: var(--color-orange-300);
+  --color-primary-400: var(--color-orange-400);
+  --color-primary-500: var(--color-orange-500);
+  --color-primary-600: var(--color-orange-600);
+  --color-primary-700: var(--color-orange-700);
+  --color-primary-800: var(--color-orange-800);
+  --color-primary-900: var(--color-orange-900);
+
+  /* Semantic Colors - Secondary (maps to Green) */
+  --color-secondary-50: var(--color-green-50);
+  --color-secondary-100: var(--color-green-100);
+  --color-secondary-200: var(--color-green-200);
+  --color-secondary-300: var(--color-green-300);
+  --color-secondary-400: var(--color-green-400);
+  --color-secondary-500: var(--color-green-500);
+  --color-secondary-600: var(--color-green-600);
+  --color-secondary-700: var(--color-green-700);
+  --color-secondary-800: var(--color-green-800);
+  --color-secondary-900: var(--color-green-900);
+
+  /* Semantic Colors - Tertiary (maps to Red) */
+  --color-tertiary-50: var(--color-red-50);
+  --color-tertiary-100: var(--color-red-100);
+  --color-tertiary-200: var(--color-red-200);
+  --color-tertiary-300: var(--color-red-300);
+  --color-tertiary-400: var(--color-red-400);
+  --color-tertiary-500: var(--color-red-500);
+  --color-tertiary-600: var(--color-red-600);
+  --color-tertiary-700: var(--color-red-700);
+  --color-tertiary-800: var(--color-red-800);
+  --color-tertiary-900: var(--color-red-900);
+}