모서리

진행 중 (Radius tokens — work in progress)

• primitive 토큰은 2배수 progression (2 → 512px + full, 12만 예외). Tailwind rounded-N utility는 @theme의 --radius-N을 직접 참조합니다.
• 컴포넌트용 의미 토큰(--ds-radius-sm/md/lg, --ds-radius-label-sm/md)이 :root에 별도로 존재 — input·select·chip·label 등에서 사용.
• 전역 버튼 radius를 4px !important로 강제하는 규칙이 남아 있습니다(트랩 참고) — !important 제거는 정리 예정이나, 버튼 모서리 변경은 ds-r-* 축으로 이미 가능합니다.
• 자세한 진행 현황은 목표 & 로드맵 참고.

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

모서리(radius) 강제 규칙. 상세·토큰표는 아래 본문.

• 사용 우선순위: ① Tailwind 유틸(rounded-8·rounded-12·rounded-16·rounded-full, 일반 마크업) → ② 컴포넌트 의미 토큰 var(--ds-radius-*)(컴포넌트 CSS 작성 시) → ③ 하드코딩 금지(border-radius: 8px). 버튼은 예외 — 전역 강제 때문에 유틸이 안 먹으니 ds-r-* 축을 쓸 것(아래 트랩 ①).
• primitive 스케일(@theme → rounded-N, radius의 단일 출처): 2 · 4 · 8 · 12 · 16 · 32 · 64 · 128 · 256 · 512 · full. 기본은 2배수 progression이고 12만 예외(버튼 모서리 축 ds-r-12용, 2026-07-13 채택). 실제로 자주 쓰는 건 4 · 8 · 12 · 16 · full(32 이상은 대형 카드/장식).
• 컴포넌트 의미 토큰(:root): --ds-radius-label-sm 2px(작은 라벨) · --ds-radius-label-md 4px(라벨/태그) · --ds-radius-sm 6px(input·select·작은 버튼) · --ds-radius-md 8px(카드·컨테이너) · --ds-radius-lg 10px(모달·큰 패널).
• 6px·10px는 primitive 스케일에 없음 → 반드시 --ds-radius-sm/--ds-radius-lg로 참조(임의 rounded-[6px] 금지).
• ⚠️ 트랩 ① 전역 버튼 radius = 4px !important: design-system.css의 blanket 규칙 3개(button:not(…) · button[class*="border"] · button[class*="bg-"])가 모든 <button>의 radius를 4px로 강제합니다. 버튼에 Tailwind rounded-*를 줘도 덮어써집니다. 제외 명단: .ds-tab-item · .ds-sub-tab__item · .ds-menu__item · .icon-btn · .ds-btn--icon · .ds-btn--circle · .org-tree__action-btn · .ds-page-header__avatar.
• 버튼 모서리를 바꾸려면 ds-r-* 축을 쓸 것(2026-07-13 신설): ds-r-8 · ds-r-12 · ds-r-16 · ds-r-999 (+ 상속을 되돌리는 ds-r-4). 위 강제 규칙들이 값을 var(--ds-btn-radius, 4px)로 읽으므로, 이 클래스는 변수만 세팅해 !important 없이 이깁니다. !important로 맞불 놓거나 <div role="button">으로 우회하지 마세요 — 축에 없는 값(0 radius 등)이 꼭 필요할 때만 엘리먼트 교체를 고려합니다. 상세: Buttons → 모서리.
• ⚠️ 트랩 ② .rounded/.rounded-lg 유틸 오버라이드(버튼 강제와 별개 규칙): 이 두 Tailwind 유틸 클래스는 각각 --ds-radius-sm(6px)·--ds-radius-lg(10px)로 !important 덮어써집니다.
• 위 강제 규칙들의 정리(특이도 기반 전환·!important 제거)는 별도 브랜치 예정.
• radius 정의는 @theme 스케일 한 곳뿐입니다. tokens.css에 남아 있던 사용처 0건의 --radius-6/10/12는 제거했습니다(2026-07-13). 6px·10px가 필요하면 의미 토큰 --ds-radius-sm/--ds-radius-lg를 쓰세요.

단일 출처

packages/static/styles/design-system.css

primitive --radius-*는 @theme 블록에 정의되고, 생성 스크립트(scripts/gen-figma-tokens.mjs)로 packages/static/tokens.figma.json(radius/* borderRadius 변수)에 전파됩니다.

Figma 파생 파일은 현재 --radius-12를 반영하지 않았습니다

전파는 자동이 아니라 스크립트 실행 시점에 일어나는데, 생성기가 돌면 VariableID를 순차 재할당해 기존 Figma 변수 매핑이 통째로 밀립니다(그래서 2026-07-13 토큰 추가 시 재생성을 보류). 코드·docs는 12px가 정상 반영돼 있고, Figma에만 아직 없습니다. 재생성은 Figma 플러그인 담당자와 함께 진행하세요(같은 이유로 tint-light-40도 미반영 상태입니다).

1. Primitive 스케일 (@theme → Tailwind rounded-*)

radius의 단일 출처는 이 스케일 하나입니다. @theme에 정의되어 있어 Tailwind rounded-N utility가 자동 생성됩니다. 기본은 2배수 progression이고, 12px만 예외로 들어 있습니다 — 버튼 모서리 축(ds-r-12)의 8↔16 중간 단계라 2026-07-13에 정식 채택했습니다(이전의 "신설 취소" 결정을 뒤집음).

Token	값	Tailwind utility	미리보기
--radius-2	2px	rounded-2
--radius-4	4px	rounded-4
--radius-8	8px	rounded-8
--radius-12	12px	rounded-12
--radius-16	16px	rounded-16
--radius-32	32px	rounded-32
--radius-64	64px	rounded-64
--radius-128	128px	rounded-128	—
--radius-256	256px	rounded-256	—
--radius-512	512px	rounded-512	—
--radius-full	9999px	rounded-full

→ 실제 UI에서 자주 쓰이는 단계는 4 · 8 · 12 · 16 · full입니다. 32 이상은 대형 카드/장식용.

2. 컴포넌트 의미 토큰 (:root, --ds-radius-*)

폼 컨트롤·칩·라벨 등 컴포넌트가 직접 참조하는 의미 토큰입니다. primitive 스케일과 별개로 6px·10px 같은 중간값을 포함합니다.

Token	값	사용처	미리보기
--ds-radius-label-sm	2px	작은 라벨/뱃지
--ds-radius-label-md	4px	라벨/태그
--ds-radius-sm	6px	input · select · 작은 버튼
--ds-radius-md	8px	카드 · 컨테이너
--ds-radius-lg	10px	모달 · 큰 패널

두 체계의 관계

--ds-radius-md(8px) = --radius-8로 값이 같지만, 컴포넌트 의미 토큰은 "이 컴포넌트의 모서리"라는 의도를 담습니다. 컴포넌트 CSS에서는 --ds-radius-*, 일반 마크업에서는 Tailwind rounded-*를 사용하세요. 6px·10px는 primitive 스케일에 없으므로 반드시 --ds-radius-sm/lg로 참조합니다.

사용 우선순위

1. Tailwind utility (1순위, 일반 마크업) — rounded-8, rounded-12, rounded-16, rounded-full
2. 컴포넌트 의미 토큰 (컴포넌트 CSS 작성 시) — border-radius: var(--ds-radius-sm)
3. 하드코딩 금지 — border-radius: 8px ← 토큰 변경에 안 따라감

버튼만 예외입니다. 전역 강제 규칙 때문에 버튼에는 rounded-* 유틸이 먹지 않습니다 — 모서리 축 ds-r-*를 쓰세요.

트랩 — !important 강제 규칙 2종

design-system.css에는 !important로 radius를 덮어쓰는 규칙이 두 갈래 있습니다. 서로 다른 규칙이니 혼동하지 마세요.

① 전역 버튼 radius = 4px 강제

모든 <button>의 radius를 4px로 !important 강제하는 blanket 규칙 3개가 design-system.css에 있습니다. (셀렉터 문자열로 검색하세요.)

셀렉터	유래
button:not([class*="bg-"]):not(.ds-tab-item):not(.ds-sub-tab__item)…	기본 강제 (아래 제외 명단 포함)
button[class*="border"]:not(.ds-tab-item)	Figma button/line
button[class*="bg-"]:not([class*="border"])	Figma button/solid

• Tailwind rounded-*를 버튼에 직접 줘도 덮어쓰입니다.
• 강제 제외 명단: .ds-tab-item · .ds-sub-tab__item(자체 radius 3단계 보유) · .ds-menu__item · .icon-btn · .ds-btn--icon · .ds-btn--circle(원형) · .org-tree__action-btn · .ds-page-header__avatar.

버튼 모서리를 바꾸는 정식 경로 — ds-r-* 축 (2026-07-13 신설)

세 규칙 모두 값을 var(--ds-btn-radius, 4px) 로 읽습니다. 그래서 --ds-btn-radius 변수만 세팅하는 클래스는 !important 없이도 강제를 이깁니다(굵기 축 ds-fw-* 와 같은 구조).

클래스	모서리	참조 토큰
(없음)	4px	기본값
ds-r-4	4px (되돌리기용)	--radius-4
ds-r-8	8px	--radius-8
ds-r-12	12px	--radius-12
ds-r-16	16px	--radius-16
ds-r-999	알약(pill)	--radius-full

• 변수는 상속되므로 버튼을 감싼 컨테이너에 얹으면 내부 버튼에 일괄 적용됩니다. 이때 대상은 DS 버튼만이 아니라 위 강제 규칙에 걸리는 모든 <button>(날 유틸로 만든 레거시 버튼 포함)입니다 — 툴바·카드에 얹으면 주변 버튼까지 바뀌므로, 기본은 버튼 엘리먼트에 직접 얹고 컨테이너 적용은 내부 버튼을 확인한 뒤에만 하세요(특정 버튼만 되돌리려면 ds-r-4). 변수를 읽지 않는 버튼 외 요소는 영향이 없습니다.
• !important로 맞불 놓지 마세요. 축에 없는 값(0 radius 등)이 꼭 필요할 때만 <div role="button">으로 엘리먼트를 바꿔 button 셀렉터를 피하세요.
• 전체 조합 미리보기: Buttons → 버튼 탐색기의 모서리 컨트롤.

② .rounded / .rounded-lg 유틸 오버라이드 (버튼 강제와 별개)

design-system.css의 "Strong pass: override commonly used utility classes" 주석 블록에 있습니다.

유틸 클래스	덮어쓰는 값
.rounded	--ds-radius-sm (6px) !important
.rounded-lg	--ds-radius-lg (10px) !important

이 두 규칙 모두 정리(특이도 기반 전환 → !important 제거)는 별도 브랜치 예정입니다.

검토 필요 사항

• 🟡 두 체계 단일화: primitive --radius-*(@theme)와 컴포넌트 --ds-radius-*(:root)가 공존. 값이 겹치는 8px(--radius-8 = --ds-radius-md)은 의도된 별칭이나, 사용 경계 가이드 필요.
• ✅ 드리프트 해소(2026-07-13): design-system.css가 @import하는 tokens.css가 2·4·6·8·10·12·16 스케일을 따로 갖고 있어 위 표와 어긋났습니다. 사용처 0건이던 --radius-6/10/12를 제거해 radius 정의를 @theme 한 곳으로 모았습니다. (tokens.css에는 --gradient-* 4종·--transition-fast/normal 등 사용처 0건 잔재가 더 있습니다 — radius 밖이라 이번엔 손대지 않음.)
• 🟡 !important 강제 제거: 전역 버튼 radius 강제는 특이도 기반으로 전환해 !important 의존을 없애야 함. (2026-07-13 부분 완화 — 세 규칙이 var(--ds-btn-radius, 4px)를 읽어 ds-r-* 축으로 override 가능. !important 자체는 아직 남아 있음.)
• 🔴 컴포넌트별 radius 가이드 미정: "버튼 6px, 카드 8px, 모달 10px" 같은 권장표 부재.
• ✅ 버튼 기본 모서리 = 4px 유지 확정(2026-07-13): ds-r-* 축으로 8/12/16/999를 실제로 비교한 뒤 내린 결정입니다. 다른 모서리가 필요한 버튼만 축 클래스를 얹으세요 — 기본값 변경 제안은 다시 열지 않습니다.
• ✅ SubTab radius = 8px 현황 유지 확정(2026-07-13): --radius-12 신설로 "토큰이 없어서 8px" 라는 제약은 사라졌지만, 12px로 올리는 것은 시각 변경이라 현행 8px를 유지하기로 했습니다(sub-tab).

목표 & 로드맵

항목	현재	목표
Primitive 스케일 (2배수)	✅ 정의 완료 (@theme)	유지
Tailwind rounded-* 연결	✅ --radius-N 자동 생성	유지
컴포넌트 의미 토큰	✅ --ds-radius-* 5종	사용 경계 가이드 작성
전역 버튼 radius !important	🟡 강제 중 (단 ds-r-* 축으로 override 가능)	특이도 기반으로 전환·!important 제거
버튼 모서리 축	✅ ds-r-8/12/16/999	기본 4px 유지 확정(2026-07-13)
컴포넌트별 권장 radius 표	🔴 미작성	버튼/카드/모달/칩별 작성

변경 이력

날짜	내용
2026-07-13	버튼 모서리 축 ds-r-* 신설 — 강제 규칙 3개가 var(--ds-btn-radius, 4px)를 읽도록 바꿔 !important 없이 8/12/16/999 override 가능(기본 4px 유지). 트랩 ①의 <div role="button"> 우회 안내를 정식 축 안내로 교체
2026-07-13	--radius-12 정식 채택 + radius 단일 출처화 — 이전의 "신설 취소" 결정을 뒤집어 @theme 스케일에 12px 추가(rounded-12 유틸 생성). tokens.css의 사용처 0건 --radius-6/10/12를 제거해 radius 정의를 @theme 한 곳으로 정리
2026-06-18	모서리 문서 신규 작성 — primitive --radius-2~512/full + 컴포넌트 --ds-radius-* 토큰표·미리보기, 전역 버튼 radius 강제 트랩 명시