투명도

진행 중 (Opacity tokens — work in progress)

• 5단위 21단계 (0~100) 토큰 정의 + Tailwind opacity-N utility와 DS 토큰 직접 매핑 완료.
• Tailwind 기본 opacity scale에 없던 opacity-35, opacity-45, opacity-55, opacity-65, opacity-85 도 5단위 풀세트로 사용 가능.
• 단, 시맨틱 토큰은 미정의 (예: --ds-opacity-disabled, --ds-opacity-overlay). 현재는 숫자 기반 primitive 토큰만 사용.
• 자세한 진행 현황은 목표 & 로드맵 참고.

규칙 (강제) · 코딩 에이전트용 — 사람은 접힌 채로 두어도 됩니다

투명도(opacity) 강제 규칙. 상세·토큰표·미리보기는 아래 본문.

• 사용 우선순위: ① Tailwind 유틸(opacity-50·opacity-75) → ② DS 토큰 var(--ds-opacity-N)(특수 CSS·SVG·canvas) → ③ alpha tint 토큰(색 위 반투명 overlay가 필요할 때: --ds-glass-08·--ds-selection-tint-12·--ds-hover-tint-16 등) → ④ 하드코딩 금지(opacity: 0.5, rgba(0,0,0,0.5) ← 쓰지 말 것).
• 스케일 = 5단위 21단계(0~100). Tailwind 기본에 없던 35 · 45 · 55 · 65 · 85도 풀세트로 사용 가능(21개 전부 --ds-opacity-*에 직접 매핑됨).
• 자동 반영: opacity-N 유틸 → var(--opacity-N) → var(--ds-opacity-N). DS 토큰 값만 바꾸면 모든 유틸에 자동 반영되므로 유틸을 우회하지 말 것.
• 단일 요소 페이드 vs 색 위 overlay 구분: 요소 전체를 흐리게 = opacity-*. 색 위에 얹는 반투명 층 = alpha tint 토큰(--ds-glass-*/--ds-*-tint-*/--ds-dim-*) 우선.
• 시맨틱 토큰은 아직 없음(--ds-opacity-disabled·--ds-opacity-overlay 미정의) — 임의로 만들지 말고 숫자 primitive를 쓸 것.

단일 출처

packages/static/styles/design-system.css

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

규칙

1. Scale = 5 단위 (0 → 100)

:root {
  --ds-opacity-0:   0;
  --ds-opacity-5:   0.05;
  --ds-opacity-10:  0.1;
  /* ... */
  --ds-opacity-95:  0.95;
  --ds-opacity-100: 1;
}

토큰 이름	값	토큰 이름	값
--ds-opacity-0	0	--ds-opacity-55	0.55
--ds-opacity-5	0.05	--ds-opacity-60	0.60
--ds-opacity-10	0.10	--ds-opacity-65	0.65
--ds-opacity-15	0.15	--ds-opacity-70	0.70
--ds-opacity-20	0.20	--ds-opacity-75	0.75
--ds-opacity-25	0.25	--ds-opacity-80	0.80
--ds-opacity-30	0.30	--ds-opacity-85	0.85
--ds-opacity-35	0.35	--ds-opacity-90	0.90
--ds-opacity-40	0.40	--ds-opacity-95	0.95
--ds-opacity-45	0.45	--ds-opacity-100	1.00
--ds-opacity-50	0.50

2. Tailwind utility ↔ DS 토큰 직접 매핑

@theme {
  --opacity-0:   var(--ds-opacity-0);
  --opacity-5:   var(--ds-opacity-5);
  /* ... 21개 모두 매핑 */
  --opacity-100: var(--ds-opacity-100);
}

이렇게 매핑되면 Tailwind opacity-N utility는 다음과 같이 동작합니다.

opacity-50 → opacity: var(--opacity-50) → opacity: var(--ds-opacity-50) → opacity: 0.5

디자이너가 --ds-opacity-* 값을 바꾸면 모든 opacity-N utility가 자동 반영됩니다.

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

<!-- 방식 A: Tailwind utility (권장) -->
<div class="opacity-50">…</div>

<!-- 방식 B: DS 토큰 직접 참조 -->
<div style="opacity: var(--ds-opacity-50)">…</div>

시각 미리보기

오렌지 단색에 각 opacity 단계 적용 (배경은 흰색).

0

5

10

15

20

25

30

35

40

45

50

55

60

65

70

75

80

85

90

95

100

사용 우선순위

1. Tailwind utility (1순위, 가장 일반적)
   • opacity-50, opacity-75 …
   • 자동으로 --ds-opacity-* 토큰 참조 → 토큰 변경 시 자동 반영
2. DS 토큰 직접 참조 (특수 CSS·SVG·canvas 등)
   • style="opacity: var(--ds-opacity-50)"
3. alpha tint 토큰 (반투명 색이 필요한 경우)
   • var(--ds-glass-08), var(--ds-selection-tint-12), var(--ds-hover-tint-16) 등
   • 색 위에 layered overlay가 필요한 경우 우선 사용
4. 하드코딩 금지
   • style="opacity: 0.5", rgba(0,0,0,0.5) ← 사용하지 마세요

피그마 연동

• Figma Variables 패널에서 opacity/0, opacity/5, … opacity/100 변수로 노출 (21개)
• 자동 동기화 명령: node scripts/gen-figma-tokens.mjs && node scripts/gen-figma-native.mjs && node scripts/build-figma-plugin.mjs

검토 필요 사항

• 🟡 시맨틱 토큰 미정의: --ds-opacity-disabled (보통 0.4~0.5), --ds-opacity-overlay (보통 0.5~0.6), --ds-opacity-hover-tint (보통 0.04~0.08) 같은 의미 기반 토큰이 없습니다.
• 🟡 Alpha tint 체계와의 관계: --ds-glass-*, --ds-selection-tint-*, --ds-hover-tint-*, --ds-dim-*은 별도 체계로 운영 중. 두 체계의 사용 경계 가이드 필요.
• 🔴 사용 가이드라인 미정: "disabled 상태는 opacity-40, modal overlay는 opacity-50" 같은 상태·컴포넌트별 권장값 표 부재.
• 🟢 분할 정밀도: 5단위 21단계는 충분 — 추가 세분화는 현재 불필요.

목표 & 로드맵

항목	현재	목표
Primitive 토큰 (5단위)	✅ 21단계 정의 완료	유지
Tailwind utility ↔ DS 토큰 매핑	✅ 21개 모두 직접 매핑 완료	유지
Figma Variables 동기화	✅ 21개 opacity 변수	유지
시맨틱 토큰 (의미 기반)	🔴 미정의	--ds-opacity-disabled, --ds-opacity-overlay 등 5~8개 정의
Alpha tint와의 사용 경계 가이드	🔴 미작성	"단일 요소 페이드 vs 색 위 overlay" 사용 시점 문서화
상태별 사용 가이드	🔴 미작성	disabled / hover / overlay / read-only 상태별 권장 opacity 표

변경 이력

날짜	내용
2026-05-28	@theme에 --opacity-N: var(--ds-opacity-N) 21개 매핑 추가. Tailwind opacity-N utility가 DS 토큰을 직접 참조
이전	--ds-opacity-0 ~ 100 21개 정의됨 — 단, Tailwind utility와 단절 상태였음