Antigravity Agent
32 lines
4.3 KiB
Markdown
32 lines
4.3 KiB
Markdown
# [[React Design Tokens]]
|
|
|
|
## 📌[[ brief]] Summary
|
|
React 프로젝트에서 디자인 토큰([[Design Tokens]])은 색상, 타이포그래피, 간격, 그림자 등 인터페이스의 핵심 시각적 속성을 중앙 집중화하여 관리하는 원천 데이터([[Single Source of Truth]])입니다. 하드코딩된 값을 배제하고 JSON이나 YAML과 같은 기계 판독 가능한 형식으로 저장되며, [[Style Dictionary]] 등의 도구를 통해 CSS 변수나 테마 객체로 변환되어 React 컴포넌트에 적용됩니다. 이를 통해 디자인의 일관성을 유지하고, 라이트/다크 모드와 같은 동적 테마([[Dynamic Theming]]) 구현 및 확장 가능한 프론트엔드 UI 시스템 구축을 가능하게 합니다.
|
|
|
|
## 📖 Core Content
|
|
* **디자인 토큰의 정의와 목적**
|
|
* 디자인 토큰은 애플리케이션의 시각적 DNA를 구성하는 원자적 데이터 포인트입니다.
|
|
* 개발자는 고정된 값(예: `#4A00FF`)을 직접 하드코딩하는 대신 `primary`와 같은 재사용 가능한 토큰을 정의하여 사용합니다. 값이 변경될 때 모든 컴포넌트가 자동으로 업데이트되므로 유지보수성이 크게 향상되며 디자이너와 개발자 간의 공통 언어 역할을 합니다 [1-3].
|
|
|
|
* **토큰의 3단계 계층 구조 (Token Hierarchy)**
|
|
* 확장 가능한 시스템을 구축하기 위해 토큰은 3가지 계층으로 나뉘어 관리됩니다 [4-10].
|
|
* **기본 토큰 (Primitive/[[Reference]] Tokens):** `#3366FF` 또는 `16px`과 같은 원시적이고 맥락이 없는 기본 값을 의미합니다.
|
|
* **시맨틱 토큰 (Semantic/Alias Tokens):** 기본 토큰을 참조하며, `color.primary`나 `button.background`처럼 토큰의 목적과 의도를 나타냅니다. 테마(라이트/다크 모드) 전환 시 컴포넌트 코드를 수정할 필요 없이 시맨틱 토큰이 가리키는 기본 값만 교체하여 테마를 구현합니다.
|
|
* **컴포넌트 토큰 (Component Tokens):** `button.background.primary`와 같이 특정 컴포넌트나 변형(variant)에 국한된 토큰으로, 시맨틱 토큰을 참조해야 합니다.
|
|
|
|
* **React 애플리케이션에서의 구현 (Implementation Pipeline)**
|
|
* **디자인 도구 통합:** [[Figma]]의 Tokens Studio와 같은 플러그인을 사용하여 디자이너가 설정한 시각적 결정들을 JSON 데이터 구조로 추출합니다 [11-14].
|
|
* **토큰 변환:** Style Dictionary 또는 Knapsack과 같은 변환 도구를 사용하여 JSON/YAML 형태의 토큰을 React에서 사용할 수 있는 CSS 변수(Custom Properties) 또는 JS 객체 포맷으로 자동 변환합니다 [15-17].
|
|
* **React 통합:** 생성된 CSS 변수를 `index.css`와 같은 최상위 스타일에 정의한 뒤, React 컴포넌트 내부에서 인라인 스타일, [[CSS Modules]], [[styled-components]], 또는 [[Tailwind CSS]]와 결합하여 사용합니다 [15, 18, 19].
|
|
|
|
* **최신 트렌드: [[Tailwind CSS v4]]의 CSS-First 접근**
|
|
* 2025/2026년 기준, Tailwind CSS v4는 자바스크립트 설정 파일(`tailwind.config.js`) 대신 CSS `@theme` 디렉티브를 사용하여 디자인 토큰을 선언합니다 [20-22].
|
|
* 이 접근법은 디자인 토큰을 네이티브 CSS 변수로 직접 노출시키며, Tailwind는 이 변수들을 바탕으로 유틸리티 클래스(예: `--color-primary-500` 선언 시 `bg-primary-500` 자동 생성)를 생성하여 런타임 오버헤드 없이 빠른 성능을 제공합니다 [21, 23].
|
|
|
|
## 🔗 Knowledge Connections
|
|
- **Related Topics:** [[Tailwind CSS]], [[styled-components]], [[Dynamic Theming]], [[Atomic Design]], [[CSS-in-JS]]
|
|
- **Projects/Contexts:** [[Style Dictionary]], [[Figma Tokens Studio]], [[React Server Components]]
|
|
- **Contradictions/Notes:** 소스 [15]와 [19]은 디자인 토큰을 기반으로 생성된 CSS 변수를 styled-components와 같은 런타임 [[CSS-in-JS]] 라이브러리에 묶어서 사용하는 방식을 설명하지만, 소스 [24-27]와 [28-30]은 [[React Server Components]](RSC) 환경에서는 런타임 CSS-in-JS의 성능 및 호환성 문제로 인해 Tailwind CSS나 CSS Modules처럼 빌드 타임에 정적 CSS를 생성하는 방식(Zero-runtime)으로 전환하는 것을 강력히 권장합니다.
|
|
|
|
---
|
|
*Last updated: 2026-04-26* |