버튼과 툴팁을 코드로 묶어

KRDS CP-383 — 활성화 버튼과 컨테이너 영역을 aria-labelledby 속성으로 연결하고 있다.

0. 들어가며 — 버튼과 툴팁 내용을 잇는 끈

이번 503편은 (툴팁) 활성화 버튼과 컨테이너 영역을 aria-labelledby 속성으로 연결하라는 규칙입니다.

툴팁 버튼과 그 툴팁 내용(컨테이너)이 — 프로그래밍적으로 연결돼야, 스크린 리더가 버튼과 툴팁을 함께 인식하죠. CP-383은 aria-labelledby(또는 관련 aria)로 둘을 연결하라고 규정합니다. CP-382(이름)의 구체적 연결 방법을 다루는 규칙이죠. 이번 편을 풀어냅니다.

1. 원문 — aria-labelledby로 버튼-컨테이너 연결

CP-383 (컴포넌트 > 툴팁) “활성화 버튼과 컨테이너 영역을 aria-labelledby 속성으로 연결하고 있다.”

툴팁 활성화 버튼과 툴팁 콘텐츠 컨테이너를, aria-labelledby 속성으로 프로그래밍적으로 연결하라는 뜻입니다.

정리: 툴팁 버튼과 툴팁 컨테이너를 aria-labelledby로 연결하라. 이게 CP-383입니다.

2. 왜 aria-labelledby 연결인가

툴팁은 활성화 버튼(아이콘 버튼)과 그 툴팁 내용(컨테이너 영역)이 짝을 이룹니다. 버튼에 호버/포커스하면 툴팁 컨테이너가 뜨죠. 이 둘을 스크린 리더가 하나의 관계로 인식하려면, 프로그래밍적 연결이 필요합니다. 시각 적으론 버튼 옆에 툴팁이 떠 연결이 보이지만 스크린 리더엔 그 시각 관계가 안 전달되니까요. CP-383은 그 연결을 aria-labelledby로 규정합니다.

연결이 없을 때의 문제:

버튼과 툴팁 분리 인식 — 버튼과 툴팁 컨테이너가 — 코드상 연결 안 돼 있으면, 스크린 리더는 둘을 별개 요소로 읽습니다. 버튼은 ‘버튼’(이름 없으면), 툴팁 텍스트는 떠도 그게 그 버튼의 것인지 모르죠. 관계가 끊깁니다.

이름 누락 — 버튼에 접근가능한 이름이 없으면(CP-382) — 툴팁 컨테이너의 텍스트가 그 버튼의 이름이 돼야 하는데, 연결이 없으면 그 역할을 못 하죠.

그래서 CP-383은 — 버튼과 컨테이너를 aria-labelledby로 연결하라고 합니다:

aria-labelledby 활성화 버튼에 aria-labelledby="tooltip-id"를 주고, 툴팁 컨테이너에 그 id를 부여합니다. 그러면 스크린 리더가 버튼을 읽을 때, 연결된 툴팁 컨테이너의 텍스트를 버튼의 이름으로 읽죠. ‘검색’(툴팁 내용) + ‘버튼’(역할)을 함께요. 툴팁 텍스트가 버튼의 접근가능한 이름이 되는 겁니다.

<button aria-labelledby="tip1"><svg>...(검색 아이콘)</svg></button> <span role="tooltip" id="tip1">검색</span>

aria-labelledby vs aria-describedby. 미묘하지만 중요한 구분:

aria-labelledby — 연결된 요소를 이름(label) 으로 씀. 그게 그 컨트롤의 ’무엇인가’를 정함. 아이콘 단독 버튼처럼 — 버튼에 이름이 없고 툴팁이 그 이름 역할을 할 때 적합하죠(CP-376의 레이블 툴팁). CP-383이 명시한 방식입니다.

aria-describedby — 연결된 요소를 설명(description) 으로 씀. 버튼에 이미 이름이 있고, 툴팁이 부가 설명일 때(CP-378의 설명 툴팁) 적합하죠.

CP-383은 aria-labelledby를 명시합니다. 즉 아이콘 단독 버튼(이름 없음)의 툴팁을 그 버튼의 이름으로 연결 하는 경우죠(CP-376의 핵심 용도와 맞물림). 만약 버튼에 이미 이름이 있고 툴팁이 부가 설명이면 aria-describedby가 맞고요. 용도에 따라 적절히 씁니다.

role=“tooltip”. 툴팁 컨테이너에 — role="tooltip"을 주면 스크린 리더가 그게 툴팁임을 인식하죠. aria- labelledby/aria-describedby 연결과 role="tooltip"을 함께 쓰면 — 표준적인 툴팁 접근성이 완성됩니다.

CP-382와의 관계. CP-382는 ’버튼에 고유 이름 제공’이라는 결과, CP-383은 그 이름을 ’컨테이너를 aria-labelledby로 연결’하는 구체적 방법 중 하나죠. 즉 툴팁 텍스트를 직접 입력하는 대신(aria-label) 툴팁 컨테이너를 참조(aria-labelledby)하면, 시각 툴팁과 접근가능한 이름이 한 소스(컨테이너 텍스트)에서 나와 일치하고 유지보수가 쉽습니다.

이 규칙은 툴팁의 ’버튼-내용 연결’을 담당합니다 — 버튼과 컨테이너를 aria-labelledby로 묶어(383), 스크린 리더가 버튼과 툴팁을 한 관계로 인식하게 하죠. 툴팁의 프로그래밍적 접근성 핵심입니다.

정리하면 — 툴팁 버튼과 컨테이너가 코드상 연결 안 되면 스크린 리더가 둘을 별개로 인식하므로, aria-labelledby(이름 용도) 또는 aria-describedby(설명 용도)로 버튼과 툴팁 컨테이너를 연결하고 role=“tooltip”을 부여해야 합니다.

3. 점검 / 개선

무엇을 점검하나

연결 존재 — 버튼이 aria-labelledby(또는 describedby)로 툴팁 컨테이너와 연결됐는가.

용도 맞춤 — 이름 용도면 labelledby, 설명 용도면 describedby로 적절히 썼는가.

role=“tooltip” — 툴팁 컨테이너에 role=“tooltip”이 있는가.

개선 방향

아이콘 단독 버튼(이름 없음) 툴팁은 aria-labelledby로 컨테이너 연결(이름).

부가 설명 툴팁은 aria-describedby. 컨테이너에 role="tooltip".

4. 누가 담당하나 / 우리 사이트에 해당될까?

역할	책임
퍼블리셔/개발	aria-labelledby/describedby·role 구현
QA/접근성	스크린 리더 버튼-툴팁 연결 검증

기관 유형	CP-383 적용
중앙행정기관(대표·운영) / 공공기관 / 지자체	✅ 필수 (툴팁 사용 시)

웹접근성 의무 대상이며 툴팁을 쓰는 사이트에 해당됩니다.

5. 30초 자가진단 + FAQ

✅ 30초 자가진단

□ 버튼이 aria-labelledby(또는 describedby)로 툴팁 컨테이너와 연결됐나요?

□ 이름 용도면 labelledby, 설명 용도면 describedby로 적절히 썼나요?

□ 툴팁 컨테이너에 role=“tooltip”이 있나요?

❓ FAQ

Q1. aria-labelledby와 aria-describedby 차이가 뭔가요? labelledby는 연결 요소를 이름으로(무엇인가), describedby는 설명으로(부가 안내) 씁니다. 아이콘 단독 버튼 이름은 labelledby죠. Q2. 왜 컨테이너를 참조하나요? 시각 툴팁과 접근가능한 이름이 한 소스(컨테이너 텍스트)에서 나와 일치하고 유지 보수가 쉽습니다. Q3. role=“tooltip”도 필요한가요? 네. 스크린 리더가 그게 툴팁임을 인식합니다. aria 연결과 함께 쓰면 표준적인 툴팁 접근성이 되죠.

6. 마무리

CP-383의 메시지:

버튼과 툴팁을 코드로 묶어 — 활성화 버튼과 컨테이너를 aria-labelledby로 연결하라.

버튼과 컨테이너가 코드상 연결 안 되면 스크린 리더가 둘을 별개로 인식합니다. aria-labelledby(이름)/describedby(설명) 로 연결하고 role=“tooltip”을 부여하는 게 핵심이죠. 다음 편은 툴팁 콘텐츠의 DOM 순서입니다.

다음 편 예고 ▶ 「504. (CP-384) 스크린 리더 사용자가 도움말 팝오버 콘텐츠에 논리적인 순서로 접근할 수 있도록 관련 있는 활성화 버튼 다음 요소로 제공하고 있다.」

ViewCheck는 툴팁 버튼-컨테이너의 aria 연결을 진단합니다.

📚 참고 출처

KRDS 컴포넌트 — 툴팁(Tooltip) 가이드 — https://www.krds.go.kr/html/site/component/component_37.html

WAI-ARIA APG — Tooltip Pattern — https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/

KRDS #ViewCheck #공공웹사이트 #전자정부 #디지털정부 #웹접근성 #디자인시스템 #UIUX #UI컴포넌트 #웹표준

KRDS,ViewCheck,공공웹사이트,전자정부,디지털정부,웹접근성,디자인시스템,UIUX,UI컴포넌트,웹표준