라벨 · 뱃지 (Labels)
라벨의 색과 크기를 확인하고, 사용 기준과 적용 방법을 찾아보세요.
CSS 기반 · Web / Mobile · 문서 포맷 시범 적용
Interactive playground
ds-label--disabled 로 렌더돼요. <span class="ds-label ds-label--md ds-label--square ds-label--primary">라벨</span>변형(Tint·Solid·Line) · 모양(Square·Round) · 크기(24·20·18px) · 색(12종) · 굵기를 골라, 실제 design-system.css의 .ds-label 규칙으로 렌더된 칩과 같은 조합의 코드를 확인할 수 있습니다.
규칙 (강제) · 코딩 에이전트용
라벨/뱃지 칩의 강제 규칙. 상세·색표·예시는 아래 본문.
- 인라인 색칠 금지.
style="background/color"로 라벨을 칠하지 말 것 — 반드시 색 변형 클래스. 원하는 색이 없으면 인라인이 아니라design-system.css에 명명 변형을 추가. - 조합식:
.ds-label+ 크기(--xs/--sm/--md) + 모양(--square/--round) + 색(--primary등). 채움 강도 축(택1): 기본=soft 틴트(연한 배경 + 진한 글자),--line=테두리(outline),--solid=강조 채움(진한 배경 + 흰 글자).--line과--solid는 배타적으로 쓴다(둘 다 주면--solid가 이김).--solid는 신호가 강한 상태(정상/위험 등)를 또렷하게 보여야 할 때만 — 남용하면 화면이 원색 칩으로 시끄러워진다. - 크기:
--xs18px/10px ·--sm20px/11px ·--md24px/13px. 표 셀·이름 옆 인라인 칩은 기본--sm --square. - 굵기는 크기와 분리된 축: 기본 medium(500), 바꾸려면
.ds-fw-regular/medium/semibold/bold하나를 라벨에 얹는다(버튼과 같은 모디파이어).font-bold같은 Tailwind 유틸로는 안 바뀐다 —.ds-label--*는 레이어 밖 규칙이라 유틸을 이긴다. - 긴 라벨은
--trunc로 말줄임: 폭이 정해진 표 셀에 긴 이름(근무형태 등)을 넣을 땐.ds-label--trunc+ 글자를<span class="ds-label__text">로 감싸고, 전체 텍스트를title(툴팁)에 둔다..ds-label은 inline-flex 라 컨테이너에text-overflow를 줘도 잘리지 않고 옆 칸까지 넘친다. 폭을 늘려 해결하지 말 것. - 위치는 래퍼에:
.ds-label이position: relative를 직접 선언하므로 Tailwindabsolute를 라벨에 직접 주면 무시된다(카운트 배지처럼 겹쳐 놓을 땐 감싼 요소에 위치를 준다). - 의미↔색 고정. 같은 의미는 어디서나 같은 색(예:
admin=--primary,팀장=--blue). - 인접 칩은 색을 겹치지 말 것. 한 셀에 두 칩이 함께 뜨면 서로 다른 색으로 구분(예: admin=
--primary, 팀장=--blue). - 상태 배지(
.ds-status-badge)는 라벨의 secondary 팔레트를 공유 — 활성=green · 휴직=yellow · 퇴직=red · 비활성=gray. 새로 만들어도 이 매핑을 따를 것(딴 톤으로 드리프트 금지). - 접근성: 색만으로 의미 전달 금지 — 라벨 텍스트(
팀장/admin/반려)로 뜻이 드러나게, 아이콘 전용 금지. - 다크 모드(2026-10-19) —
ds-label--gray글자--ds-label-fg-assistive는 다크에서label-alternative(회색 틴트 위 2.4 였음). 늘 어두운 면 위 배지--gray-dark·--light-gray-dark의 글자 · 테두리 · 틴트는 정적 흰 잉크--ds-ink-white-*라 테마와 무관하게 같다 —--ds-glass-*(다크에서 어두워짐)를 쓰지 않는다. 흰 라벨(ds-label--white)은 다크에서 한 단계 뜬 면(bg-elevated, neutral-700)(10-20) — 다크에서도 neutral-25 흰 면이라 공지 상세 「일반」 칩 등이 튀었다. 칩 면만--ds-label-white-bg로 분리했고--ds-label-white는*-dark배지의 흰 잉크로도 쓰여 그대로다. 검정 라벨(ds-label--black)은 다크에서 짙은 채움 + 흰 글자 + 가는 경계(강조 버튼--strong과 같은 규칙, 10-20) — 면이--ds-label-black(= label-normal)이라 다크에서 밝아져 흰 글자가 사라졌었다. 칩 면 · 글자는--ds-label-black-bg·-fg로 따로 두고,--ds-label-black은 다른 곳에서 글자색으로 쓰이므로 그대로다. 상태색 배지(초록 · 노랑 · 빨강 · 파랑)와 파랑 · 보라 라벨의 다크 틴트는 상태색 500 을 neutral-800 에 16% 섞은 값(테두리 40%, 2026-10-20).
이름 옆의 팀장·admin, 상태 칩, 카운트 뱃지처럼 짧은 상태·속성 텍스트를 한 가지 규격(크기·모양·색)으로 표시하는 인라인 칩입니다. .ds-label 골격에 크기 · 모양 · 색 변형을 조합해서 씁니다.
하지 마세요 — 인라인 스타일로 라벨 색을 칠하는 것
style="background:...; color:..."로 라벨 색을 직접 칠하면 디자인 토큰 규칙과 어긋나고, 같은 의미의 칩이 화면마다 미묘하게 달라집니다(드리프트). 아래 색 변형 중 의미에 맞는 클래스를 고르세요. 원하는 색이 없으면 인라인으로 때우지 말고 design-system.css에 명명된 변형을 추가하세요.
사용법
.ds-label + 크기(--xs/--sm/--md) + 모양(--square/--round) + 색(--primary 등)을 조합합니다. 채움 강도는 세 가지 중 하나입니다 — 기본은 soft 틴트(연한 배경 + 진한 글자), --line은 테두리(outline), --solid는 강조 채움(진한 배경 + 흰 글자)입니다. --line과 --solid는 함께 쓰지 않습니다.
<!-- 팀장 라벨 — 이름/사번 옆 역할 칩 (blue) -->
<span class="ds-label ds-label--sm ds-label--square ds-label--blue">팀장</span>
<!-- 시스템 관리자 라벨 (primary) -->
<span class="ds-label ds-label--sm ds-label--square ds-label--primary">admin</span>
<!-- outline 변형 -->
<span class="ds-label ds-label--sm ds-label--round ds-label--line ds-label--gray">대기</span>
<!-- 말줄임 변형 — 폭이 정해진 표 셀의 긴 이름. 전체 텍스트는 title(툴팁)이 진다 -->
<span class="ds-label ds-label--sm ds-label--square ds-label--yellow ds-label--trunc"
data-ds-tip="top" title="08:30-17:30 (재활·언어·약사보조·사회복지)">
<span class="ds-label__text">08:30-17:30 (재활·언어·약사보조·사회복지)</span>
</span>의미색 매핑 규칙
- 같은 의미 = 같은 색.
admin은 어디서나--primary,팀장은 어디서나--blue처럼 의미↔색을 고정합니다. - 인접 칩은 색을 겹치지 마세요. 한 셀에 두 칩이 함께 뜨면(예:
팀장+admin) 서로 다른 색을 써서 구분되게 합니다 — admin=--primary(주황), 팀장=--blue. 둘 다 primary면 시각적으로 붙어 구분이 사라집니다. - 상태(재직/휴직/퇴직 등)는 상태 배지 규칙을 따르되, 새로 만들 땐 위 색 매핑(활성=green, 주의=yellow, 위험=red)에 맞춥니다. 상태 배지(
.ds-status-badge)는 이 라벨의 secondary 팔레트와 동일 색을 공유합니다(활성=--green, 휴직=--yellow, 퇴직=--red, 비활성=--gray값) — 상태 배지가 라벨과 다른 톤으로 드리프트하지 않도록 통일돼 있습니다.
드리프트 히스토리
과거 admin 조직 탭의 팀장 칩은 style="background:var(--color-orange-50); color:var(--color-orange-600)"로 --primary를 인라인으로 흉내 냈습니다(배경은 primary-soft와 동일, 글자만 더 진한 orange-600). 옆의 admin(--primary)과 색이 겹쳐 구분이 약했고, 인라인이라 재사용도 안 됐습니다. → --blue 표준 변형으로 교체하며 인라인을 제거했습니다. 새 라벨을 만들 때 이 패턴을 반복하지 마세요.
접근성
- 색만으로 의미를 전달하지 말고, 라벨 텍스트(
팀장,admin,반려)로 뜻이 드러나게 합니다. - 칩은 장식이 아니라 정보이므로 아이콘 전용으로 만들지 말고 텍스트를 포함합니다.
색 변형
각 색은 세 가지 채움 강도로 쓸 수 있습니다 — 기본(soft 틴트), --line(테두리), --solid(강조 채움). 아래 표는 기본(soft 틴트) 의 배경/글자 토큰입니다. --line은 테두리색만, --solid는 진한 배경 + 흰 글자를 지정합니다(강조 채움 표 참고).
| 변형 | 배경 / 글자 토큰 | 권장 용도 |
|---|---|---|
--primary | --ds-color-primary-soft / --ds-color-primary | 브랜드 강조·주요 속성 (예: admin) |
--green | --ds-secondary-green-bg / --ds-secondary-green | 성공·활성·정상 |
--yellow | --ds-secondary-yellow-bg / --color-yellow-500 | 주의·대기·부분 |
--red | --ds-secondary-red-bg / --ds-color-danger | 위험·반려·오류 |
--blue | --ds-secondary-blue-bg / --ds-secondary-blue | 정보·역할 구분 (예: 팀장) |
--aqua | --ds-secondary-aqua-bg / --ds-secondary-aquablue | 보조 정보 (blue와 구분 필요할 때) |
--black | --ds-label-black / --ds-label-white | 중립 강조(반전) |
--white | --ds-label-white / --ds-label-fg-muted | 밝은 배경 위 중립 |
--gray | rgb(193 193 193 / 60%) / --ds-label-fg-assistive | 보조·비강조 (밝은 배경) |
--light-gray | rgb(193 193 193 / 30%) / --ds-label-black | 아주 약한 보조 (밝은 배경) |
--gray-dark | --ds-glass-18 / --ds-label-white | 보조·비강조 (다크 배경 위) |
--light-gray-dark | --ds-glass-08 / --ds-glass-70 | 아주 약한 보조 (다크 배경 위) |
--disabled | rgb(193 193 193 / 20%) / --ds-label-disable | 비활성 |
강조 채움 (--solid)
기본 색 변형은 soft 틴트(연한 배경)라 신호가 약해 보일 때가 있습니다. --solid를 더하면 진한 배경 + 흰 글자로 또렷해집니다. 의미↔색은 그대로(green=성공, red=위험 …)이고 강도만 올립니다. 글자색은 모두 --ds-label-white입니다.
배경은 각 색군의 500 톤으로 통일합니다(글자는 흰색).
| 변형 | 배경 토큰 |
|---|---|
--solid --primary | --color-orange-500 |
--solid --green | --color-green-500 |
--solid --red | --color-red-500 |
--solid --yellow | --color-yellow-500 |
--solid --blue | --color-blue-500 |
--solid --aqua | --color-aquablue-500 |
--solid --gray | --color-neutral-500 |
--line과--solid는 배타적입니다 — 둘 다 주면--solid가 이깁니다.--black은 그 자체가 진한 채움(black bg + white text)이라 별도--solid가 없습니다.- 남용 주의: 한 화면에 solid 칩이 많으면 원색이 시끄러워집니다. 소트 틴트를 기본으로 두고, 정말 강조가 필요한 상태(정상/위험 등)에만 solid를 씁니다. "데이터 없음/기준 없음" 같은 무데이터·중립 상태는 solid로 올리지 말고 틴트(
--light-gray)로 두세요.
크기
| 크기 | 높이 | 폰트 | 패딩 | 아이콘 |
|---|---|---|---|---|
--xs | 18px | 10px | 2 4 | 14px |
--sm | 20px | 11px | 2 4 | 14px |
--md | 24px | 13px | 4 8 | 16px |
- 모양:
--square는--ds-radius-label-*토큰 라운드,--round는 완전 알약형(999px). - 표 셀·이름 옆 인라인 칩은 대부분
--sm --square를 씁니다.
굵기
굵기는 크기와 분리된 축입니다. 기본은 세 크기 모두 medium(500)이고, 바꾸고 싶으면 .ds-fw-regular / .ds-fw-medium / .ds-fw-semibold / .ds-fw-bold 중 하나를 라벨에 얹습니다 — 버튼이 쓰는 것과 같은 모디파이어입니다(각 크기 변형이 이미 읽고 있는 --ds-label-weight 변수만 세팅하므로 새 !important가 필요 없습니다).
<!-- 미확인 개수 배지 — 숫자를 굵게 -->
<span class="ds-label ds-label--xs ds-label--round ds-label--solid ds-label--red ds-fw-bold">3</span>Tailwind font-bold로는 안 바뀝니다
.ds-label--xs/sm/md의 font-weight는 레이어 밖(unlayered) 규칙이라 @layer utilities에 들어가는 Tailwind 유틸을 특이도와 무관하게 이깁니다. 굵기는 반드시 .ds-fw-*로 바꾸세요. 같은 이유로 위치도 라벨에 직접 주면 안 됩니다 — .ds-label이 position: relative를 직접 선언하므로 absolute가 무시됩니다. 배지처럼 겹쳐 놓을 땐 감싼 요소에 위치를 주세요.
아이콘
라벨은 텍스트 좌/우에 아이콘을 넣을 수 있습니다(버튼과 동일). .ds-label의 직접 자식으로 <svg>를 텍스트 앞(왼쪽) 또는 뒤(오른쪽)에 두면, 크기별 슬롯(위 표: md 16px · sm·xs 14px)에 자동으로 맞춰집니다. 골격이 gap: 4px + 중앙정렬을 제공하므로 별도 클래스는 필요 없습니다. 색은 currentColor를 따르니 <svg>에 fill/stroke를 직접 칠하지 마세요(변형 글자색을 따라갑니다).
<span class="ds-label ds-label--sm ds-label--round ds-label--green">
<svg viewBox="0 0 16 16" ...>…</svg> <!-- 왼쪽 아이콘 -->
정상
</span>