WIZ Design System

한눈에#

assist·filter·input·suggestion 4변형의 상호작용 칩 체계(M3)입니다 — 변형마다 인터랙션 종류가 다릅니다.

디자인

assist·filter·input·suggestion
판별 합집합 타입
2 크기(md·sm)
sm 44px 히트

단순 라벨/제거 칩은 Tag — Chip은 액션·토글·제거·제안의 상호작용 체계입니다

사용 시점#

칩에 상호작용(액션·토글·제거·제안)이 있으면 Chip — 단순 라벨이나 단일 선택 필터 줄은 다른 컴포넌트입니다.

권장 — 이렇게 쓰세요

지양 — 이러지 마세요

쓴다 — assist/suggestion 액션·filter 토글·input 제거처럼 상호작용이 있는 M3 칩

Tag

대신 Tag — 클릭 없이 보여주기만 하는 단순 라벨·제거 칩일 때

BadgeToggle

대신 BadgeToggle — '전체' 포함 단일 선택 필터 줄일 때

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

Chip를 직접 조작해 보세요

속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.

빌더 열기

플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.

해부#

알약 위에 토큰 실측을 핀으로 얹습니다 — 값이 바뀌면 핀도 함께 움직입니다(드리프트 0).

md · variant assist — 실물 렌더 위에 토큰 실측을 핀으로 표기

padding-inline: 12pxspace-3
padding-block: 4pxspace-1
gap: 4pxspace-1
radius: fullradius-full
border: 1pxborder
font: 14 / 500body-2

알약은 radius.full로 콘텐츠 높이에 맞춰 둥글어집니다. sm 인터랙티브 칩은 시각 높이가 ~28px로 줄지만 ::after가 블록축 히트 영역을 44px까지 확장해 터치 타깃을 보장합니다(IconButton §5 미러).

변형#

variant가 인터랙션 종류를 가릅니다 — 색은 이름이 아니라 실제 스와치로 확인하세요.

assist

bg: surface
fg: text
border: border

suggestion

bg: transparent
fg: text
border: border

filter · 선택

bg: primary-subtle
fg: primary-text

primary-subtle 채움 + 체크

디자인

input · 제거

bg: surface
fg: text
border: border

assist / suggestion: <button> + onClick. 작은 액션 버튼처럼 동작합니다(suggestion은 더 가벼운 아웃라인 — 투명 배경).
filter: aria-pressed 토글 — 제어 selected 또는 비제어 defaultSelected + onChange(boolean), 선택 시 선행 체크 + primary 채움.
input: 라벨 + 제거 <button>(aria-label, 기본 ‘제거’) + onRemove. 칩 자체는 비-버튼입니다.

크기#

size로 2단 — md(기본)·sm. 두 크기 모두 알약 형태를 공유합니다. sm은 패딩·폰트가 줄어 시각 높이가 ~28px가 되지만, 인터랙티브 칩은 ::after가 블록축 히트 영역을 44px로 확장해 터치 타깃을 유지합니다(md는 시각 높이로 이미 충분).

md · sm — 공유 베이스라인에서 패딩·폰트차 비교

sizepadding-inlinefontsm 히트 확장md12px (space-3)14px (body-2)—sm8px (space-2)12px (caption)44px (::after)

상태#

filter는 비제어(defaultSelected)와 제어(selected)를 모두 지원합니다 — defaultSelected로 시작하면 컴포넌트가 선택 상태를 소유하고, selected를 주면 그 값이 진실의 원천이라 클릭은 onChange로만 통지합니다(소비자가 selected를 갱신해야 반영). disabled는 4변형 모두에서 상호작용을 차단합니다. Hover/Focus/Disabled는 CSS 의사클래스로 표현됩니다.

sm 인터랙티브 칩(assist·suggestion·filter 버튼, input 제거 버튼)은 시각 크기를 유지하면서 ::after로 히트 영역을 ≥44px까지 확장합니다(터치 타깃).

단일선택 칩 그룹#

여러 칩 중 정확히 하나를 고르는 컨테이너가 필요하면 ChipGroup을 씁니다. 개별 알약을 가로로 늘어놓고, 좁은 폭에선 줄바꿈 없이 가로 스크롤합니다(WDS 필터 칩 패턴). 옵션 수가 가변이거나 라벨이 길어 SegmentedButton(연결형, 짧은 라벨 2~5개 고정)이 한 줄에 안 들어가는 단일 선택에 적합합니다. radiogroup 시맨틱(role=radiogroup·radio, roving tabindex, ←/→ 순환 선택)은 SegmentedButton과 동일합니다.

선택: standard · 좁은 폭에서 줄바꿈 없이 가로 스크롤 · ←/→로 이동

쓸 때	컴포넌트
단일 선택 · 가변/긴 라벨 · 좁은 폭(스크롤)	ChipGroup
단일 선택 · 짧은 라벨 2~5개 · 고정	SegmentedButton
다중 토글(여러 개 on/off)	Chip `variant="filter"`

Props#

Prop	타입	기본값	설명
`variant`	`'assist' \| 'suggestion' \| 'filter' \| 'input'`	—	인터랙션 종류 — assist·suggestion·filter·input.
`children`	`ReactNode`	—	라벨 콘텐츠
`onClick`	`(() => void) \| (() => void)`	—	assist·suggestion 액션 콜백.
`ref`	`Ref<HTMLButtonElement> \| Ref<HTMLSpanElement>`	—	루트 <button>으로 전달되는 ref (React 19 ref-as-prop) 루트 <span>으로 전달되는 ref (React 19 ref-as-prop)
`leadingIcon`	`ReactNode`	—	라벨 앞 선행 아이콘
`disabled`	`boolean`	—	비활성화 시 모든 상호작용 차단
`size`	`'sm' \| 'md'`	—	칩 크기 — md(기본) \| sm
`className`	`string`	—	소비자 className(루트에 병합)
`selected`	`boolean`	—	제어 선택 상태 — 제공하면 제어 모드(내부 상태 무시, 전환은 onChange로만 통지)
`defaultSelected`	`boolean`	—	초기 선택 상태(비제어, selected 미제공 시)
`onChange`	`(selected: boolean) => void`	—	선택 상태 변경 콜백
`onRemove`	`() => void`	—	제거 버튼 클릭 시 호출
`removeLabel`	`string`	—	제거 버튼 aria-label (기본 '제거')

variant별로 허용되는 prop이 타입(판별 합집합)으로 강제됩니다 — 예: filter에 onRemove를 넘기면 컴파일 오류입니다.

접근성#

변형	계약
assist / suggestion	`<button>` — 네이티브 클릭·키보드(Space/Enter)
filter	`<button aria-pressed>` 토글 — 선택 상태를 보조기술에 보고, 선행 체크는 장식(`aria-hidden`)
input	칩은 비-버튼, 제거 `<button>`이 `aria-label`(기본 ‘제거’)을 가지는 단일 액션
공통	`:focus-visible` 2px primary 아웃라인 · `disabled` 차단 · 등장 전환은 `prefers-reduced-motion` 존중

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).

속성	토큰
칩	`color.surface` · `color.border`(hover `surface-hover`) · `radius.full`
filter 선택	`color.primary-subtle` 배경 · `color.primary-text` · 체크
눌림(`:active`)	`color.surface-pressed` — 액션 칩·제거 버튼 (filter 선택은 유지)
크기	`control.height-md` / 축소 · `font.size-body-2`
sm 히트 영역	액션 칩 `space.3`(12px) 블록축 확장 · input 제거 버튼 `space.3` → ≥44px 터치
포커스	`color.focus-ring` 2px 아웃라인
모션	`duration.fast` + `ease.standard`