보닥 플래너
KB라이프
10:00

디자인 시스템

Semantic Sync 토큰 (Figma 1:1 + shadcn 표준 호환)

색상

Atomic 팔레트(전체 스케일) → Semantic 토큰(컴포넌트 실사용) 2단계 구조. 파란 숫자 = Semantic 연결 스텝.

전체 팔레트

컴포넌트에서 직접 사용 금지 — 시맨틱 토큰을 통해서만 참조

Cool Neutral

클릭하면 CSS 변수명 복사 (예: --cool-neutral-500) · 파란 숫자 = 시맨틱 토큰 연결

Blue

클릭하면 CSS 변수명 복사 (예: --blue-500) · 파란 숫자 = 시맨틱 토큰 연결

Violet

클릭하면 CSS 변수명 복사 (예: --violet-500) · 파란 숫자 = 시맨틱 토큰 연결

Red

클릭하면 CSS 변수명 복사 (예: --red-500) · 파란 숫자 = 시맨틱 토큰 연결

Green

클릭하면 CSS 변수명 복사 (예: --green-500) · 파란 숫자 = 시맨틱 토큰 연결

Amber

클릭하면 CSS 변수명 복사 (예: --amber-500) · 파란 숫자 = 시맨틱 토큰 연결

시맨틱 토큰

클릭하면 Tailwind 클래스명 복사
bg-primary
--primary·#3182f6·메인 액션 버튼 · 강조 배경

↑ 컬럼 구조 예시 (실제 토큰 카드 구조와 동일) · 토큰 카드 클릭 시 클래스명 복사

Background

Fill

Text

Brand

Border

Alpha (overlay · divider)

Status

타이포그래피

font-size

Tailwind: font-size-10 ~ font-size-36
미리보기클래스px용도
Aa
font-size-10
10px레이블, 배지 텍스트
Aa
font-size-12
12px툴바, 보조 정보
Aa
font-size-13
13px테이블 셀, 필터 값
Aa
font-size-14
14px버튼 기본, 본문
Aa
font-size-16
16px카드 제목, 중요 텍스트
Aa
font-size-18
18px섹션 제목
Aa
font-size-20
20px카드 타이틀 (h5)
Aa
font-size-22
22px모달 제목 (h4)
Aa
font-size-24
24px페이지 소제목 (h3)
Aa
font-size-28
28px페이지 타이틀 (h2)
Aa
font-size-34
34px대형 타이틀
Aa
font-size-36
36px히어로 텍스트 (h1)

font-weight

Tailwind: font-weight-normal / font-weight-medium / font-weight-semibold
미리보기클래스값용도
보닥 플래너 Bonydak
font-weight-normal
400본문, 보조 텍스트, placeholder
보닥 플래너 Bonydak
font-weight-medium
500버튼 라벨, 필터 값, 테이블 헤더
보닥 플래너 Bonydak
font-weight-semibold
600타이틀, 강조, KPI 수치 — 이 프로젝트 주력 굵기

font_letter_spacing

Tailwind: font_letter_spacing-0 / font_letter_spacing-050 / font_letter_spacing-100
미리보기클래스값용도
보닥 플래너 Bonydak
font_letter_spacing-0
0shadcn 기본 — 이 프로젝트에서 거의 미사용
보닥 플래너 Bonydak
font_letter_spacing-050
-0.5pxcomposite 토큰 기본값 — 대부분의 UI 텍스트
보닥 플래너 Bonydak
font_letter_spacing-100
-1px긴 본문 가독성용

line-height

Tailwind: line-height-120 ~ line-height-160
미리보기클래스값용도
보닥 플래너
Bonydak Planner
line-height-120
1.2제목류 — 헤딩, 강조 숫자
보닥 플래너
Bonydak Planner
line-height-130
1.3서브타이틀
보닥 플래너
Bonydak Planner
line-height-140
1.4버튼, 배지, 짧은 레이블
보닥 플래너
Bonydak Planner
line-height-160
1.6본문 — composite 토큰 기본 행간

Semantic 타이포 토큰

font-size / line-height / font-weight / letter-spacing 하나로 묶인 Semantic 클래스 — text-h* / text-body* / text-caption
text-h3-bold

24px / semibold / lh 36px / ls -0.5px

재배정 타입 설정 — 상담 관리

text-h4

22px / semibold / lh 32px / ls -0.5px

배정 완료 DB

text-h5-bold

20px / semibold / lh 30px / ls -0.5px

설계사 검색

text-body3-bold

14px / semibold / lh 22px / ls -0.5px

이민혁 · 010-1111-1111 · 2026.01.01

text-body3-medium

14px / medium / lh 22px / ls -0.5px

이민혁 · 010-1111-1111 · 2026.01.01

text-body3-normal

14px / regular / lh 22px / ls -0.5px

이민혁 · 010-1111-1111 · 2026.01.01

text-body4-bold

13px / semibold / lh 20px / ls -0.5px

정상 · 계약 예정 · 상담 종료

text-body4-medium

13px / medium / lh 18px / ls -0.5px

정상 · 계약 예정 · 상담 종료

text-body4-normal

13px / regular / lh 18px / ls -0.5px

정상 · 계약 예정 · 상담 종료

text-body5-bold

12px / semibold / lh 20px / ls -0.5px

담당 설계사 · 상태

text-body5-medium

12px / medium / lh 16px / ls -0.5px

담당 설계사 · 상태

text-body5-normal

12px / regular / lh 16px / ls -0.5px

담당 설계사 · 상태

text-caption

10px / regular / lh 16px / ls -0.5px

레이블 · 구분

라운드

토큰 시각화

rounded-sm

2px

rounded

4px

rounded-md

6px

rounded-lg

8px

rounded-full

pill

사용 계층 규칙

레벨클래스설명
카드 · 컨테이너rounded-lg8px — 가장 많이 사용
버튼 (default/sm)rounded-lg8px
필터 컨트롤 · 작은 버튼rounded-md6px — h-8/h-6 컨트롤
체크박스 · 미세 라운드rounded-sm2px
pill · 원형 (avatar/dot)rounded-full9999px
❌ 금지rounded-xl12px+ 라운드 사용 금지

Border

보더 굵기

border-border05

0.5px

특수 케이스 — 얇은 구분이 필요한 경우

border

1px

기본값 — Tailwind 표준 (border-border10 동일)

보더 색상

border-subtle / border-border / border-primary
border-subtle
#e5e8eb

카드·컨테이너 기본 보더 (cool-neutral-200)

border-border
#d1d6db

shadcn 호환 보더 (cool-neutral-300)

border-primary
#3182f6

선택·포커스 상태

Shadow

그림자 스케일

shadow-xs

필터 컨트롤 · 소형 팝업

shadow-sm

카드 팝업 · select

shadow-md

모달 · 사이드바

shadow-lg

대형 팝오버

shadow-xl

드래그 중 카드

스페이싱

토큰 스케일

Tailwind 네이티브 4px 그리드. 1 = 4px / 2 = 8px / 4 = 16px / 6 = 24px ...

4px

1

8px

2

12px

3

16px

4

20px

5

24px

6

32px

8

40px

10

60px

15

사용 패턴

Tailwind 네이티브 4px 그리드 — prefix(p / m / gap / px / pt 등)는 상황에 따라 자유 조합
pxTailwind 키사용 패턴
41아이콘 ↔ 텍스트 인라인 간격
82타이트한 인라인 gap
123배지 padding · BusinessTree ↔ 본문 gap
164카드 간 gap · 필터 ↔ 테이블 mb
205카드 내부 세로 패딩 (py)
246페이지·카드 수평 패딩 (px)
328섹션 간 gap
4010페이지 타이틀 상단 패딩 (pt)
6015콘텐츠 하단 패딩 (pb-15)

토큰 선택 가이드

어떤 색·간격·라운드를 쓸지 헷갈릴 때. 위에서부터 질문에 답하면 정답이 나오도록 설계.

색상 — 무엇을 표현하나?

컴포넌트에서 색을 결정할 때 따라가는 흐름
1.

브랜드 액션인가? (저장/확인/메인 CTA) → bg-primary / text-primary

2.

상태 표현인가? → 성공 tint-success · 경고 tint-warning · 오류 tint-danger · 정보 tint-blue · 중립 tint-muted

3.

면적이 큰 배경인가? (페이지·카드·모달) → bg-canvas-* (primary=흰 / tertiary=페이지 / quaternary=섹션)

4.

작은 컴포넌트 배경인가? (배지·필 / 컨트롤 hover) → bg-fill-* (subtle=hover / strong=강조)

5.

텍스트인가? → text-content-* (primary 진함 → assistive 옅음 → disabled 회색). 진함과 옅음 사이가 모호하면 한 단계 진한 쪽 선택.

6.

오버레이/구분선인가? → 행 hover bg-alpha-black-02 / 셀 보더 border-divider-subtle

간격 / 라운드 / 굵기

px 단위로 선택하지 말고 의미로 선택

간격 (gap / padding)

  • 아이콘↔텍스트 → gap-s4 (4px)
  • 인라인 → gap-s8 (8px)
  • 카드↔카드 → gap-s16 (16px)
  • 섹션 간 → gap-s32 (32px)

라운드

  • 카드·컨테이너 → rounded-lg (8px)
  • 필터·버튼(sm/xs) → rounded-md (6px)
  • 체크박스 → rounded-sm (2px)
  • pill·avatar → rounded-full

굵기 (font-weight)

  • 본문 → font-normal (400)
  • 레이블 → font-medium (500)
  • 제목·강조 → font-semibold (600)
  • font-bold 사용 금지

네이밍 규칙

토큰 이름은 의미로 읽힌다. Prefix가 카테고리, Suffix가 위계.

Prefix — 무엇을 다루는 토큰인가

Prefix예시의미
bg-canvas-*bg-canvas-primary면적 큰 배경 (페이지·카드·모달)
bg-fill-*bg-fill-subtle작은 컴포넌트 배경 (배지·hover)
bg-primary-*bg-primary-subtle브랜드 강조 배경
bg-{color}-tintbg-green-tint상태 색 tint 배경
bg-alpha-*bg-alpha-black-02투명 오버레이 (반투명 hover/딤)
text-content-*text-content-primary일반 텍스트 색 (위계별)
text-inverse-*text-inverse-primary반전 텍스트 (브랜드 위 흰글자)
text-{color}-tinttext-green-tint상태 색 tint 텍스트 (배지 안)
border-*border-subtle보더 색·굵기
border-divider-*border-divider-subtle셀·구분선 (alpha 기반)

Suffix — 위계와 상태

위계 (진함 → 옅음)

primary → secondary → tertiary → quaternary → assistive → disabled

진할수록 강조, 옅을수록 보조

상태

-hover · -pressed · -subtle · -strong · -inverse

interaction과 강조도 표현

❌ 금지 패턴

이런 패턴은 사용 금지 — 빌드 통과해도 디자인 시스템 위반
  • bg-blue-500 같은 raw atomic 토큰 직접 사용 — 반드시 semantic을 거쳐서 (예: bg-primary)
  • dark:bg-canvas-primary — 다크모드 미지원. 모든 dark: prefix 금지
  • rounded-xl 이상 — Vega 스타일 상한선. 카드는 rounded-lg(8px)까지
  • font-bold — atomic font-weight-bold로만 허용. 일반은 font-semibold
  • bg-primary/10 같은 alpha modifier — semantic 토큰엔 금지. bg-primary-subtle 같은 named 토큰 사용
  • gap-0.5, gap-1.5 같은 half-step 간격 — 4px 그리드 벗어남. s-token 사용

Tailwind 매핑표

Figma 토큰 ↔ shadcn 표준 ↔ 우리 Tailwind 클래스. 한눈에 보고 골라 쓰는 치트시트.

Background

Tailwind 클래스CSS 변수Figma 토큰언제 쓰나
bg-canvas-primary--bg-primarybg_primary카드·모달 흰 배경
bg-canvas-secondary--bg-secondarybg_secondary오프화이트 영역 (드물게)
bg-canvas-secondary--bg-tertiarybg_tertiary페이지 기본 배경 (모든 페이지)
bg-canvas-quaternary--bg-subtlebg_subtle섹션 구분·테이블 짝수행
bg-primary--primary(shadcn 표준)메인 액션 버튼 (브랜드 블루)
bg-primary-subtle--primary-subtle(파생)사이드바·트리 선택 배경
bg-fill-subtle--fill-subtle(파생)테이블 헤더·작은 컴포넌트 hover

Text · Border

Tailwind 클래스CSS 변수Figma 토큰언제 쓰나
text-content-primary--text-primarytext_primary제목·강조 (#191F28)
text-content-secondary--text-secondarytext_secondary본문 (cool-neutral-900)
text-content-tertiary--text-tertiarytext_tertiary서브 텍스트 (cool-neutral-700)
text-content-assistive--text-assistivetext_assistiveplaceholder·힌트 (#8B95A1)
text-primary--primary(shadcn 표준)링크·브랜드 텍스트
text-inverse-primary--common-100text_inverse_primary브랜드 버튼 위 흰 글자
border-subtle--border-subtleborder_subtle카드 보더 (cool-neutral-200)
border-border--borderborder_primaryshadcn 표준 보더
border-divider-subtle--divider-subtle(파생)테이블 셀 행 라인 (alpha-blue 4%)

브랜드 커스터마이징

B2B 다중 테넌트 — --primary 한 줄만 바꾸면 모든 컴포넌트 자동 추종. 한 build로 여러 브랜드 지원.

1단계 — globals.css에 브랜드별 오버라이드 추가

/* :root 블록 끝부분에 추가 */
[data-brand="green"] {
  --primary: var(--green-500);     /* #03b26c */
}
[data-brand="orange"] {
  --primary: oklch(0.65 0.20 45);  /* 임의 hex/oklch도 가능 */
}

2단계 — html 또는 페이지 wrapper에 data-brand 적용

정적 (테넌트 단위)

// app/layout.tsx
<html lang="ko" data-brand={tenant.brand}>
  {/* "default" | "green" | "orange" */}
</html>

동적 (런타임 변경)

useEffect(() => {
  document.documentElement
    .dataset.brand = currentTenant.brand
}, [currentTenant])

자동 추종 컴포넌트 — 코드 수정 불필요

--primary 변경 시 다음이 모두 자동 추종 (CSS 변수 추상화):

Button (variant=primary)
Badge (variant=default)
사이드바 selected/ring
링크 (text-primary)
체크박스/라디오 ON
focus ring
필터 검색 버튼
캘린더 선택 날짜
테이블 selected 행

예외 — 브랜드와 무관한 토큰

reference에서 정적 색이라 브랜드와 무관
  • bg-blue-tint, text-blue-tint — info 배지용 파랑 (브랜드가 그린이어도 info=파랑)
  • bg-success, bg-warning, bg-destructive — 시맨틱 상태색

카드

기본 카드

카드 타이틀

bg-canvas-primary · rounded-lg · border-subtle

내부 구분선: mx-6 h-px bg-divider-subtle — 좌우 mx-6 인셋 필수

KPI 타일 카드

전체

100명

승인대기

50명

정상

10명

일시제한

10명

수직 구분선: absolute h-12 w-px bg-divider-normal

버튼

변형 × 크기 매트릭스

variant
xs
h-6 · 11px
sm
h-8
default
h-9
설명
primary메인 액션 — 저장 / 재배정 / 확인
secondary보조 액션 — 필터 검색 (서브틀 브랜드)
outline약한 강조 — 취소 / 보조 옵션
ghost투명 — 페이지네이션 / 아이콘 트리거
neutral중립 액션 — 작업 영역 토글
destructive위험 액션 — 삭제 / 회수

아이콘 + 텍스트 조합

아이콘은 버튼 텍스트 앞에 배치. data-[icon=inline-start] 자동 좌측 패딩 조정.

아이콘 버튼 사이즈

icon

36px

shadcn 마이그레이션

variantbg / bordertexthover
primarybg-primarytext-inverse-primarybg-primary-hover
secondarybg-primary-subtletext-primarybg-primary-subtle-hover
outlineborder-bordertext-content-primarybg-canvas-quaternary
ghost—text-content-primarybg-canvas-quaternary
neutralbg-canvas-quaternarytext-content-primarybg-fill-hover
destructivebg-destructive-subtletext-destructivebg-destructive-subtle-hover
focus → border-ring ring-ring-glowdisabled → opacity-50 pointer-events-none
shadcn 기본 (설치 직후)이 프로젝트 (적용 후)변경 이유
bg-canvas-primary text-inverse-primarybg-primary text-inverse-primaryprimary SWAP — primary는 흰 배경이므로 brand action = accent
hover:bg-primary (shadcn 서브틀 hover)hover:bg-canvas-quaternary / hover:bg-mutedaccent↔muted SWAP — shadcn accent는 우리 시스템에서 brand blue
data-[state=checked]:bg-canvas-primarydata-[state=checked]:bg-primaryCheckbox ON 상태 — primary SWAP 동일 적용

필터

SearchFilter 라이브 데모

개별 컨트롤 패턴

Select — h-9 border-subtle bg-fill-filter

Input — variant='filter'

필터 초기화 (변경 시 노출)

컨트롤 공통: bg-fill-filter border-subtle shadow-none rounded-md h-9 · 초기화는 아이콘 버튼 금지 (텍스트 언더라인 버튼)

Input / Select 마이그레이션

Input

shadcn 기본 (설치 직후)이 프로젝트 (적용 후)변경 이유
border-input (1px, border-border)variant="filter" → border-subtle필터용 연한 보더
bg-transparentvariant="filter" → bg-fill-filter페이지 bg-canvas-secondary 위 대비
text-content-assistive (placeholder)placeholder:text-content-assistiveassistive = 우리 시스템 placeholder 토큰

Select

shadcn 기본 (설치 직후)이 프로젝트 (적용 후)변경 이유
bg-primary (shadcn 서브틀 hover)hover:bg-blue-tint + border-info + text-primarybrand 컬러 명시적 hover — named atomic 참조 (alpha modifier 금지)
bg-popover border-border (Content)border-subtle className 추가필터용 보더를 subtle로 오버라이드
bg-background (Trigger 기본)bg-fill-filter className 추가필터용 흰 배경 명시

필터 위치 패턴

패턴 A — 카드 헤더 내부

카드 타이틀

테이블

/ (홈) · /pending

패턴 B — 별도 카드 (mb-4)

테이블

/completed · /db/* · /management/*

테이블

No.이름휴대폰번호소속가입일상태
1이민혁010-1111-1111본사 > 사업단 1 > 지점 12026.01.01정상
2이민혁010-1111-1111본사 > 사업단 1 > 지점 12026.01.01정상
3이민혁010-1111-1111본사 > 사업단 1 > 지점 12026.01.01정상
속성값비고
TableHead 높이h-10 (40px)개별 파일 오버라이드 금지
TableCell 높이h-[44px]터치 타겟 최소값
TableCell 패딩px-3 py-2.5
No. 컬럼text-center헤더+셀 동일
나머지 컬럼text-left기본
숫자/날짜/전화num-celltabular-nums + tracking
행 hoverhover:bg-alpha-black-02alpha 2% — 매우 미세, 텍스트 안 진해짐
선택 행data-[state=selected]:bg-blue-tintblue-50
선택 행 hoverdata-[state=selected]:hover:bg-primary-subtle-hoverblue-75 — 선택+hover 시 한 단계 진하게

배지

태그 배지 — 상태·분류 (tint 스타일)

진행중대기상담 거절진행 예정계약 완료 / 종료
tint-successgreen-50 bg / green-450 text — 활성 진행 (db-status: 진행중)
tint-warningamber-50 bg / amber-700 text — 주의·대기 (현재 사용처 없음)
tint-dangerred-50 bg / red-600 text — 명확한 부정 (completed: 상담 거절)
tint-blueblue-50 bg / blue-700 text — 정보·신규 (db-status: 진행 예정)
tint-mutedbg-canvas-quaternary / text-content-quaternary — 비활성·종결 (completed: 계약 완료, db-status: 종료)

pill-* variants 제거 — tint-* (= tag) 스타일로 통일. 칸반 태그도 tint-* 사용.

기본 변형 (shadcn 표준)

default (bg-primary)secondarydestructiveoutlineghostlink

shadcn 마이그레이션

shadcn 기본 (설치 직후)이 프로젝트 (적용 후)변경 이유
bg-canvas-primary text-inverse-primary (default variant)bg-primary text-inverse-primaryprimary SWAP — brand badge = accent
—tint-* variants 추가종결/분류용 배경 fill (badge-tint-* 전용 토큰)
—bg-badge-tint-success-bg / text-badge-tint-success-fg시맨틱 배지 색상 — globals.css에 전용 변수로 분리
bg-primary text-inverse-primary (shadcn secondary)bg-canvas-secondary text-secondary-foregroundshadcn secondary = 우리 accent와 다른 값

페이지네이션

총 143건

아무 번호나 눌러 7슬롯 고정 확인

컴포넌트사용법
PageNumbers<PageNumbers totalPages={n} currentPage={p} onPageChange={setPage} />
PageSizeSelect<PageSizeSelect value={pageSize} onValueChange={(v) => { setPageSize(v); setCurrentPage(1) }} />

차트 팔레트

chart-1

blue-500 · 주지표

chart-2

2순위

chart-3

3순위

chart-4

4순위

chart-5

보조지표

chart-1 = blue-500 (#3182f6) · chart-2~5 = violet-500/550/600/650 · Area 차트 3선: chart-1 / chart-3 / chart-5 순서

레이아웃 패턴

패턴 1 — BusinessTree + 필터[별도] + 테이블

/completed · /db/assigned · /db/unassigned · /management/* · /organization/*

Tree

필터 (mb-4)

테이블

<div className="flex gap-3 px-6 pb-15 items-start">
  <BusinessTree />
  <div className="flex-1 min-w-0">
    <div className="mb-4"><XxxFilter /></div>
    <XxxTable />
  </div>
</div>

패턴 2 — BusinessTree + 카드들

/ (홈) · /pending

Tree

카드 1 (KPI/필터 내장)

카드 2

<div className="flex gap-3 px-6 pb-15 items-start">
  <BusinessTree />
  <div className="flex-1 min-w-0 flex flex-col gap-4">
    {/* 카드들 */}
  </div>
</div>

패턴 3 — BusinessTree 없음 (전체 너비)

/db/status · 설정 페이지 (/settings/*)

테이블 또는 설정 카드 (전체 너비)

<div className="px-6 pb-15">
  <XxxTable />
</div>

현재 상태

이 시스템에 어떤 접근성 보호가 들어있고, 무엇이 빠져있는지 솔직하게.

✓

자동 적용

shadcn / Radix 기본 — 의도하지 않아도 따라옴

  • • focus-visible ring (Button·Input·Select·Checkbox 등 26개)
  • • Modal·Dropdown focus trap
  • • Pagination·Breadcrumb·Sidebar 내부 ARIA
  • • Calendar·Combobox 키보드 네비
  • • Tab·Enter·Esc 표준 키보드 동작
✓

Baseline 적용

2026-05 — 커스텀 컴포넌트에 수동 추가

  • • 아이콘 버튼 aria-label (5곳)
  • • 폼 컨트롤 aria-label (11곳: Search, Select, Combobox 등)
  • • title 툴팁 + aria-label 병행
!

미적용 (백로그)

의도적으로 보류 — 별도 검토 필요

  • • 커스텀 button·a 태그 focus-visible 표준화
  • • Tree role/aria-expanded (BusinessTree·StructureTree·칸반)
  • • 색 대비 미달 토큰 사용처 교체
  • • 키보드 단축키 / Tab 순서 표준
  • • prefers-reduced-motion 대응

현재 등급: shadcn 기본만 의존하던 단계 → Baseline 단계로 진입. 스크린 리더 사용자에게 모든 인터랙티브 요소가 "이름"을 가짐. 키보드 전용 사용자에겐 일부 커스텀 트리·드래그 인터랙션이 여전히 미지원.

색 대비 매트릭스

WCAG 2.1 contrast ratio. 본문(<18px)은 AA 4.5:1 / AAA 7:1. 큰 글자(≥18px bold 또는 ≥24px)는 AA 3:1. 셀 클릭하면 비율 복사.

전체 매트릭스

text 토큰 × bg 토큰 — 실제 사용 가능한 조합 검증
text \ bg
bg-canvas-primary
bg-canvas-secondary
bg-canvas-tertiary
bg-canvas-quaternary
bg-primary
bg-primary-subtle
Aatext-content-primary
16.56AAA
15.87AAA
15.02AAA
14.25AAA
4.46AA-L
14.74AAA
Aatext-content-secondary
11.00AAA
10.53AAA
9.97AAA
9.46AAA
2.96FAIL
9.79AAA
Aatext-content-tertiary
7.11AAA
6.81AA
6.45AA
6.12AA
1.91FAIL
6.33AA
Aatext-content-quaternary
4.62AA
4.42AA-L
4.19AA-L
3.97AA-L
1.24FAIL
4.11AA-L
Aatext-content-assistive
3.04AA-L
2.91FAIL
2.76FAIL
2.61FAIL
1.22FAIL
2.71FAIL
Aatext-content-disabled
2.01FAIL
1.92FAIL
1.82FAIL
1.73FAIL
1.85FAIL
1.79FAIL
Aatext-primary
3.71AA-L
3.56AA-L
3.37AA-L
3.20AA-L
1.00FAIL
3.31AA-L
Aatext-inverse-primary
1.00FAIL
1.04FAIL
1.10FAIL
1.16FAIL
3.71AA-L
1.12FAIL
AAA≥ 7:1 — 모든 본문 통과
AA≥ 4.5:1 — 본문 통과
AA-L≥ 3:1 — 큰 글자(18px+) 또는 placeholder만
FAIL미달 — disabled 상태에만 허용

주요 발견 — 의식적으로 인지해야 할 조합

AA-L

text-primary on bg-canvas-primary = 3.71:1 — 모든 링크 텍스트가 본문 AA 미달. 14px 본문 링크는 시각적으로 잘 안 보일 수 있음. 링크는 가급적 underline 병행 권장.

AA-L

text-inverse-primary on bg-primary = 3.71:1 — Primary 버튼의 흰 글자도 AA-Large만. 버튼 라벨이 14px+ 이고 font-medium 이상이라 실용상 OK지만 13px 이하 사용 금지.

FAIL

text-content-assistive on bg-canvas-secondary (페이지 배경) = 2.91:1 — 페이지 배경 위에선 placeholder조차 미달. 흰 카드 안 placeholder는 OK (3.04:1 AA-L), 페이지 배경 위 본문은 절대 금지.

AA

text-content-quaternary on bg-canvas-secondary = 4.42:1 — 본문 AA에 살짝 못 미침(4.5 기준 0.08 부족). 흰 카드 위(4.62:1)는 본문 OK. 페이지 배경 위에서는 text-content-tertiary 권장.

적용 패턴

새 컴포넌트·새 페이지 만들 때 따라야 할 규칙.

아이콘 버튼

아이콘만 있고 텍스트 없는 모든 button·a 태그 — 스크린 리더에 '이름'을 줘야 함
Don't스크린 리더가 "버튼"으로만 읽음
<button onClick={openSidebar}>
  <Menu className="h-4 w-4" />
</button>
Do"사이드바 열기"로 안내
<button onClick={openSidebar} aria-label="사이드바 열기">
  <Menu className="h-4 w-4" />
</button>

동적 상태(예: 펼침/접힘)는 라벨에 상태를 포함:aria-label={`${name} ${isOpen ? "접기" : "펼치기"}`}

폼 컨트롤

placeholder는 시각적 힌트일 뿐 — 스크린 리더의 라벨로 인정 안 됨
Don'tplaceholder만 — 라벨 미연결
<Input
  placeholder="고객명 검색"
  value={q}
  onChange={...}
/>
Doaria-label로 명시
<Input
  placeholder="고객명 검색"
  aria-label="고객명 검색"
  value={q}
  onChange={...}
/>

Select·Combobox 트리거(button) 위에 시각적 라벨이 있으면 (예: "지역 · 서울"), aria-label="지역 선택" 추가. 동적 값은 aria-label={`지역 선택, 현재 선택: ${value}`} 처럼 상태 포함.

aria-hidden — 의미 없는 아이콘

스크린 리더가 무시 / 데코 아이콘에 적용
{/* 텍스트 옆 보조 아이콘 — 라벨 중복 방지 */}
<Button>
  <Search aria-hidden="true" />
  검색
</Button>

{/* 구분 점 같은 데코 — 의미 없음 */}
<span aria-hidden="true">·</span>

백로그

현재 미적용 항목 — 추후 별도 작업으로 검토.

항목예상 임팩트시각 변화메모
Focus ring 표준화키보드 사용자Tab 시 +커스텀 button·a 태그에 focus-visible:ring-3 ring-ring-glow 일괄. shadcn 컴포넌트는 이미 적용됨.
Tree role/aria-expanded스크린 리더없음BusinessTree·StructureTree·칸반에 role='tree'/role='treeitem'/aria-expanded. 키보드 화살표 핸들러 동시 작업 필요.
색 대비 미달 사용처 정리저시력 사용자글자 톤 변화text-content-assistive를 본문으로 쓰는 곳을 tertiary로 교체. 디자이너 검토 후 진행.
키보드 단축키파워 유저없음테이블 행 ↑↓ 이동, 칸반 카드 이동, 사이드바 토글 단축키 등.
prefers-reduced-motion전정 민감 사용자모션 비활성transition·animation을 미디어 쿼리로 끄기. globals.css에 한 줄로 추가 가능.
스크린 리더 알림 (aria-live)스크린 리더없음필터 적용 후 결과 건수, 저장 완료 토스트 등 변화 알림.

목표 등급

B2B 업무 툴 — WCAG 2.1 AA 본문 기준이 현실적 목표. 현재 Baseline 단계 → 백로그 6개 중 Focus ring · Tree role · 색 대비 정리 3개 마무리 시 본문 AA 도달. 나머지 3개(키보드 단축키 · reduced-motion · aria-live)는 사용자 피드백 기반으로 우선순위 결정.

shadcn 컴포넌트 현황

설치됨 (사용 중 / 설치 유지)

26개 · CLAUDE.md 기준
button

전체 액션 버튼

badge

상태 배지

table

모든 데이터 테이블

select

필터 드롭다운

checkbox

테이블 멀티선택

input

검색 인풋

pagination

PageNumbers / PageSizeSelect

sidebar

layout.tsx 사이드바

radio-group

설정 3개 파일

popover

날짜 선택, 멀티셀렉트

tabs

대시보드 기간 탭

calendar

날짜 범위 선택

dialog

확인 모달

command

설계사 검색 combobox

collapsible

사이드바 메뉴

avatar

사용자 아이콘

tooltip

아이콘 설명

scroll-area

커스텀 스크롤

breadcrumb

sticky-breadcrumb.tsx

chart

대시보드 차트

sheet

sidebar.tsx 내부

skeleton

sidebar.tsx 내부

separator

sidebar.tsx 내부

textarea

input-group.tsx 내부

input-group

command.tsx 내부

toggle

설치됨 (미사용)

제거됨 (필요 시 재설치)

18개 · npx shadcn@latest add [name] 으로 재추가
accordionalertalert-dialogaspect-ratiobutton-groupcardcarouselcomboboxcontext-menudrawerdropdown-menulabelnavigation-menuresizableslidersonnerswitchtoggle-group

새 컴포넌트 추가 후 필수 작업

npx shadcn@latest add [component]
→bg-canvas-primary → bg-primary (액션 버튼 색상)
→bg-primary → bg-muted (서브틀 hover)
→rounded-xl → rounded-lg
→dark:* 클래스 전부 제거
→data-[state=checked]:bg-canvas-primary → data-[state=checked]:bg-primary