hereby Platform

한국어

English

한국어

English

다크 모드

간격 ​

진행 중 (Spacing tokens — work in progress)

  • primitive 토큰은 2px 간격으로 정의 (2~256px, 128단계). Tailwind gap-N / p-N / m-N / space-N utility는 @theme의 --spacing: 4px base에 calc(var(--spacing) * N)을 곱해 계산되며, 결과가 primitive 토큰과 정렬되도록 연결됨. (기본 단위는 §1의 4px, primitive 토큰 간격은 2px — 둘을 혼동하지 말 것.)
  • 단, 시맨틱 토큰은 아직 정의 전 (예: --ds-spacing-card-inset, --ds-spacing-section-gap). 현재는 픽셀 기반 primitive 토큰과 Tailwind utility만 사용.
  • 자세한 진행 현황은 목표 & 로드맵 참고.
규칙 (강제) · 코딩 에이전트용 — 사람은 접힌 채로 두어도 됩니다

간격(spacing) 강제 규칙. 상세·매핑표는 아래 본문.

  • 사용 우선순위: ① Tailwind 유틸(gap-2·p-4·m-6·space-y-3) → ② DS 토큰 직접 참조 var(--ds-spacing-N)(인라인 SVG·canvas 등 유틸을 못 쓰는 특수 CSS만) → ③ 하드코딩 금지(style="padding: 12px" ← 쓰지 말 것. 토큰 변경에 안 따라감).
  • Base unit = 4px (@theme { --spacing: 4px }). Tailwind spacing 유틸은 전부 calc(var(--spacing) * N) — base 한 곳만 바꾸면 전체 일괄 변경.
  • 모든 spacing 값은 2의 배수 (primitive 토큰 step = 2px, 2~256px 128단계). gap-0.5(2px) 같은 0.5 단위까지 표현 가능.
  • ⚠️ 혼동 금지: 기본 단위 4px(Tailwind 계산 base)과 primitive 토큰 간격 2px(토큰 스케일)은 다른 개념.
  • 시맨틱 토큰은 아직 없음(--ds-spacing-card-inset 등 미정의) — 임의로 만들지 말고 primitive 토큰/유틸을 쓸 것.

단일 출처 ​

packages/static/styles/design-system.css

여기서 정의된 값이 packages/static/tokens.figma.json, Figma 플러그인 등으로 자동 전파됩니다.

규칙 ​

1. Base unit = 4px ​

css
@theme {
  --spacing: 4px;
}

Tailwind v4의 모든 spacing utility는 calc(var(--spacing) * N)으로 자동 계산됩니다. base 한 곳만 바꾸면 전체 spacing이 일괄 변경됩니다.

2. Step = 2px (0.5 단위 정렬 가능) ​

표현 방식값비고
Tailwind utility gap-0.5 / p-0.52px0.5 단위
Tailwind utility gap-1 / p-14px1 단위
Tailwind utility gap-1.5 / p-1.56px1.5 단위
Tailwind utility gap-2 / p-28px2 단위
DS 토큰 --ds-spacing-{N}N px (정수)직접 참조용

→ 모든 spacing 값은 2의 배수. gap-N 표기로 0.5 step (2px) 단위까지 표현 가능합니다.

3. 두 가지 호출 방식 — 같은 결과 ​

html
<!-- 방식 A: Tailwind utility (권장, 일반 코드) -->
<div class="gap-2">…</div>           <!-- 8px -->
<div class="p-3">…</div>             <!-- 12px -->

<!-- 방식 B: DS 토큰 직접 참조 (특수 CSS 작성 시) -->
<div style="gap: var(--ds-spacing-8)">…</div>     <!-- 8px -->
<div style="padding: var(--ds-spacing-12)">…</div> <!-- 12px -->

두 방식 모두 결과값은 동일합니다.

시각 미리보기 ​

대표적인 step만 표시합니다. 전체 128단계는 Figma Variables 패널에서 확인하세요.

2px (0.5)
4px (1)
8px (2)
12px (3)
16px (4)
24px (6)
32px (8)
48px (12)
64px (16)
96px (24)
128px (32)

괄호 안 숫자는 Tailwind utility 번호 (gap-N / p-N / m-N).

Tailwind utility 매핑 표 ​

자주 쓰이는 step만 표기. 모든 정수/0.5 step이 자동 지원 (base × N 계산).

Tailwind utility계산결과DS 토큰
gap-0 / p-04 × 00px–
gap-0.5 / p-0.54 × 0.52px--ds-spacing-2
gap-1 / p-14 × 14px--ds-spacing-4
gap-1.5 / p-1.54 × 1.56px--ds-spacing-6
gap-2 / p-24 × 28px--ds-spacing-8
gap-2.5 / p-2.54 × 2.510px--ds-spacing-10
gap-3 / p-34 × 312px--ds-spacing-12
gap-4 / p-44 × 416px--ds-spacing-16
gap-5 / p-54 × 520px--ds-spacing-20
gap-6 / p-64 × 624px--ds-spacing-24
gap-8 / p-84 × 832px--ds-spacing-32
gap-12 / p-124 × 1248px--ds-spacing-48
gap-16 / p-164 × 1664px--ds-spacing-64

사용 우선순위 ​

새 코드를 작성할 때 다음 순서로 선택합니다.

  1. Tailwind utility (1순위, 가장 일반적)
    • gap-2, p-4, m-6, space-y-3 …
    • 자동으로 DS base 토큰 참조 → 일괄 변경에 자동 대응
  2. DS 토큰 직접 참조 (특수 CSS·인라인 스타일이 필요한 경우만)
    • style="padding: var(--ds-spacing-12)"
    • 보통 인라인 SVG/canvas 등 utility class 사용이 어려운 컨텍스트
  3. 하드코딩 금지
    • style="padding: 12px" ← 사용하지 마세요
    • 디자인 토큰 변경 시 안 따라가서 일관성 깨짐

피그마 연동 ​

  • Figma Variables 패널에서 spacing/2, spacing/4, … spacing/256 변수로 노출 (128개)
  • 자동 동기화 명령: node scripts/gen-figma-tokens.mjs && node scripts/gen-figma-native.mjs && node scripts/build-figma-plugin.mjs
  • 토큰을 추가/수정한 후 위 스크립트를 실행해야 Figma 플러그인에 반영됩니다.

검토 필요 사항 ​

  • 🟡 시맨틱 토큰 미정의: --ds-spacing-card-inset, --ds-spacing-section-gap, --ds-spacing-stack-md 같은 의미 기반 토큰이 없습니다. 디자이너·개발자 합의 후 우선 항목부터 정의 필요.
  • 🟡 px vs rem: 현재 --spacing: 4px로 절대 단위 고정. 접근성(브라우저 폰트 확대) vs 시각 일관성 트레이드오프 — 결정 필요.
  • 🟡 App·페이지 레벨 레이아웃 토큰: 화면 외곽 여백(page-padding-x), 그리드 거터(grid-gutter) 등 페이지 레이아웃 전용 토큰 미정의.
  • 🔴 사용 가이드라인 미정: "버튼 내부는 p-2, 카드 내부는 p-4" 같은 컴포넌트별 권장 spacing 가이드 부재.

목표 & 로드맵 ​

항목현재목표
Primitive 토큰 (2px step)✅ 128단계 정의 완료유지
Tailwind utility ↔ DS 토큰 연결✅ @theme --spacing: 4px base 매핑 완료유지
Figma Variables 동기화✅ 128개 spacing 변수유지
시맨틱 토큰 (의미 기반)🔴 미정의--ds-spacing-card-inset 등 핵심 10~15개 정의
컴포넌트별 사용 가이드🔴 미작성버튼/카드/모달/리스트별 권장 spacing 표
레이아웃 토큰 (페이지 단위)🔴 미정의--ds-layout-page-padding-x 등
px vs rem 결정🟡 px 고정디자이너 결정 후 명문화

변경 이력 ​

날짜내용
2026-05-28spacing 토큰 4px step (64개) → 2px step (128개) 확장. @theme에 --spacing: 4px base 추가하여 Tailwind utility와 DS 토큰 연결
이전--ds-spacing-4 ~ 256 (4px step 64개) 초기 정의 — 단, Tailwind utility와 단절 상태였음