Design Token System

Atomic CSS는 .atomic.json 파일을 통해 프로젝트 디자인 토큰을 정의할 수 있습니다. 토큰을 설정하면 자동완성에서 프로젝트 토큰이 ★ 마크와 함께 최상위에 표시됩니다.

핵심: .atomic.json에 토큰을 정의하면 자동완성 우선순위가 올라가고, strict 모드로 팀 디자인 시스템을 강제할 수 있습니다.

개요

Design Token System은 프로젝트의 색상, 간격, 폰트 크기, 모서리 둥글기, 폰트 굵기를 중앙에서 관리하고, 자동완성에서 우선 노출시키는 기능입니다.

1.atomic.json 파일에 디자인 토큰을 정의합니다

2자동완성에서 토큰 값이 ★ 마크로 최상위에 표시됩니다

3strict: true 설정 시 토큰 외 값에 경고가 표시됩니다

✓토큰 없이도 기존과 100% 동일하게 동작합니다 (하위 호환)

자동완성 우선 노출

토큰에 정의된 값이 ★ 마크와 함께 자동완성 최상위에 표시됩니다.

100% 하위 호환

토큰을 설정하지 않으면 기존과 완전히 동일하게 동작합니다. 기존 프로젝트에 영향이 없습니다.

Strict 모드

strict: true로 설정하면 토큰 외 값 사용 시 경고를 표시하고, Quick Fix로 가장 가까운 토큰값을 제안합니다.

토큰 설정 (.atomic.json)

프로젝트 루트에 .atomic.json 파일을 생성하고 토큰을 정의합니다.

.atomic.json

{
    "cssDirectoryPath": "/assets/css/common/",
    "tokens": {
        "colors": {
            "primary": "6366F1",
            "secondary": "A855F7",
            "danger": "EF4444",
            "success": "22C55E",
            "warning": "F59E0B",
            "text": "333333",
            "text-light": "999999",
            "bg": "FFFFFF",
            "bg-dark": "18181B",
            "border": "DDDDDD"
        },
        "spacing": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64],
        "fontSize": [12, 14, 16, 18, 20, 24, 32, 40],
        "borderRadius": [4, 8, 12, 16, 50],
        "fontWeight": [400, 500, 600, 700]
    },
    "strict": false
}

참고: cssDirectoryPath는 CSS 변수 자동 스캔 경로이며, tokens와 strict는 디자인 토큰 관련 설정입니다. 모든 필드는 선택사항입니다.

토큰 타입

각 토큰 타입은 특정 CSS 속성 접두사에 매핑됩니다.

colors — 색상 팔레트

c, bg, bc 접두사에 적용됩니다. HEX 6자리 값을 키-값 쌍으로 정의합니다. 자동완성에서 c 입력 시 c6366F1 ★ primary가 최상위에 표시됩니다.

"colors": {
    "primary": "6366F1",
    "secondary": "A855F7",
    "danger": "EF4444",
    "success": "22C55E",
    "warning": "F59E0B",
    "text": "333333",
    "text-light": "999999",
    "bg": "FFFFFF",
    "bg-dark": "18181B",
    "border": "DDDDDD"
}

입력	자동완성 표시	CSS
`c`	`c6366F1 ★ primary`	color: #6366F1
`c`	`cEF4444 ★ danger`	color: #EF4444
`bg`	`bgFFFFFF ★ bg`	background-color: #FFFFFF
`bg`	`bg18181B ★ bg-dark`	background-color: #18181B
`bc`	`bcDDDDDD ★ border`	border-color: #DDDDDD

spacing — 간격 값 (px)

gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr 접두사에 적용됩니다. 20px 미만은 px, 20px 이상은 자동으로 rem 변환됩니다.

"spacing": [4, 8, 12, 16, 20, 24, 32, 40, 48, 64]

토큰 값	생성 클래스	적용 접두사
`4`	`gap4px, p4px, m4px ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`8`	`gap8px, p8px, m8px ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`12`	`gap12px, p12px, m12px ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`16`	`gap16px, p16px, m16px ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`20`	`gap2rem, p2rem, m2rem ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`24`	`gap2-4rem, p2-4rem, m2-4rem ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`32`	`gap3-2rem, p3-2rem, m3-2rem ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr
`64`	`gap6-4rem, p6-4rem, m6-4rem ...`	gap, m, p, mt, mb, ml, mr, pt, pb, pl, pr

fontSize — 폰트 크기 (px)

fs 접두사에 적용됩니다. spacing과 동일한 px→rem 변환 규칙이 적용됩니다.

"fontSize": [12, 14, 16, 18, 20, 24, 32, 40]

토큰 값	생성 클래스
`12`	`fs12px`
`14`	`fs14px`
`16`	`fs16px`
`18`	`fs18px`
`20`	`fs2rem`
`24`	`fs2-4rem`
`32`	`fs3-2rem`
`40`	`fs4rem`

borderRadius — 모서리 둥글기 (px)

br 접두사에 적용됩니다.

"borderRadius": [4, 8, 12, 16, 50]

토큰 값	생성 클래스
`4`	`br4px`
`8`	`br8px`
`12`	`br12px`
`16`	`br16px`
`50`	`br5rem`

fontWeight — 폰트 굵기

fw 접두사에 적용됩니다. 단위 없이 숫자값 그대로 클래스가 생성됩니다.

"fontWeight": [400, 500, 600, 700]

토큰 값	생성 클래스
`400`	`fw400`
`500`	`fw500`
`600`	`fw600`
`700`	`fw700`

Strict 모드

strict 옵션으로 토큰 사용을 자유 모드 또는 팀 모드로 설정할 수 있습니다.

strict: false (기본값) — 자유 모드

토큰이 자동완성 상위에 노출되지만, 다른 값도 자유롭게 사용할 수 있습니다.

✓토큰이 자동완성 상위에 ★ 마크로 노출

✓토큰 외 값도 자유롭게 사용 가능

✓경고 없음

strict: true — 팀 모드

토큰 외 값 사용 시 경고 밑줄이 표시되고, Quick Fix로 가장 가까운 토큰값을 제안합니다.

!토큰 외 값 사용 시 경고 밑줄 표시

!Quick Fix로 가장 가까운 토큰값 제안

!색상은 RGB 거리 기반, 간격/폰트는 가장 가까운 허용 값 기준

Strict 모드 경고 예시

토큰에 없는 값을 사용하면 경고와 함께 Quick Fix가 제안됩니다.

위반 클래스	경고 메시지	Quick Fix
`bgABCDEF`	프로젝트 팔레트에 없는 색상입니다	`bg6366F1 (primary)`
`gap13px`	허용된 간격: 4, 8, 12, 16, 20, 24, 32, 40, 48, 64	`gap12px / gap16px`
`fs15px`	허용된 폰트 크기: 12, 14, 16, 18, 20, 24, 32, 40	`fs14px / fs16px`

CSS 변수와의 시너지

토큰 이름과 CSS 변수를 함께 사용하면 일관된 디자인을 유지할 수 있습니다. bg--primary는 var(--primary), bg6366F1은 #6366F1 — 같은 색상을 변수와 직접값으로 모두 사용할 수 있습니다.

<!-- CSS variable approach -->
<div class="bg--primary c--text">
  Uses var(--primary) and var(--text)
</div>

<!-- Direct token value approach -->
<div class="bg6366F1 c333333">
  Uses #6366F1 and #333333 directly
</div>

<!-- Both reference the same design token "primary: 6366F1" -->
<!-- bg--primary = background-color: var(--primary) -->
<!-- bg6366F1   = background-color: #6366F1          -->

CSS 변수 방식

bg--primary → var(--primary)
런타임에 변수 값을 변경할 수 있어 다크 모드 전환에 유리합니다.

직접값 방식

bg6366F1 → #6366F1
별도의 변수 정의 없이 바로 사용 가능합니다. 토큰으로 자동완성에서 우선 표시됩니다.

CSS 변수 자동완성

프로젝트의 CSS/SCSS 파일에서 :root 변수를 자동 스캔하여 자동완성에 표시합니다.

1cssDirectoryPath에 지정된 경로의 CSS/SCSS 파일을 스캔합니다

2bg-- 입력 시 실제 프로젝트 변수명이 자동완성에 표시됩니다

3변수의 원래 값과 소스 파일도 함께 표시됩니다

/* Your project CSS/SCSS file */
:root {
  --primary: #6366f1;
  --secondary: #a855f7;
  --spacing-sm: 8px;
  --spacing-md: 16px;
  --spacing-lg: 32px;
  --radius: 8px;
}

/* Type "bg--" in HTML class → autocomplete shows: */
/* bg--primary       → background-color: var(--primary)     #6366f1  (from style.css) */
/* bg--secondary     → background-color: var(--secondary)   #a855f7  (from style.css) */

팁: cssDirectoryPath를 설정하면 해당 경로의 CSS/SCSS 파일에서 :root 변수를 자동으로 스캔합니다. 설정하지 않으면 프로젝트 루트 기준으로 기본 경로를 탐색합니다.

팁 & 주의사항

토큰은 선택사항

tokens 필드를 설정하지 않으면 기존 Atomic CSS와 동일하게 동작합니다. 점진적으로 도입할 수 있습니다.

px → rem 자동 변환

20px 미만은 px 단위, 20px 이상은 자동으로 rem 단위로 변환됩니다. (1rem = 10px 기준)

팀 프로젝트에서의 Strict 모드

strict: true를 설정하면 팀 전체가 동일한 디자인 토큰을 사용하도록 강제할 수 있습니다. .atomic.json을 git에 커밋하여 공유하세요.

CSS 변수 스캔 경로

cssDirectoryPath를 설정하면 해당 경로의 CSS/SCSS 파일에서 :root 변수를 자동으로 스캔하여 자동완성에 활용합니다.