"같다"는 말을 증명하기

"KRDS를 구현했어요"라고 말하는 순간, 당연한 질문이 따라와요. "정말요? 어떻게 믿죠?"

다행히 기준이 있어요. KRDS는 공식 데모 사이트(Storybook이라고 불러요)를 운영해요. 공식 버튼, 공식 달력이 실제로 움직이는 모습을 볼 수 있는 곳이죠. 그러니 증명은 간단해 보였어요. 내가 만든 것과 공식을 비교하면 되니까요.

문제는 "어떻게 비교하느냐"였어요.

기계에게 판정을 맡기려고 했어요

처음 떠올린 건 픽셀 비교였어요. 두 화면을 사진으로 찍어 겹쳐놓고 다른 점을 기계가 찾아내는, 말하자면 틀린그림찾기를 기계에게 시키는 방식이에요.

그런데 벽이 있었어요. 내 문서 사이트와 공식 데모 사이트는 배치도 배율도 여백도 달라요. 같은 버튼이라도 사진 위의 위치가 다르니, 기계는 전부 "다르다"고 답해요. 판정이 무의미했어요.

자동화를 포기해야 하나 싶었을 때, 질문을 바꿨어요. "판정을 자동화할 수 없다면, 판정 준비를 자동화하면 되지 않나?"

기계는 준비하고, 사람이 판정해요

그래서 도구의 역할을 바꿨어요. 기계(Playwright라는 브라우저 자동화 도구)는 내 것과 공식을 각각 찍어 나란히 붙인 비교 사진 수십 장을 만들어요. 팝업이나 달력처럼 열어야 보이는 것들은 기계가 직접 클릭해서 연 다음 찍고요. 판정은 사람 눈이 해요. 색이 같은지, 모서리 곡률이 같은지, 한마디로 "같은 컴포넌트로 보이는지".

기계가 잘하는 건 반복이고, 사람이 잘하는 건 판단이에요. 역할을 이렇게 나누니 검증이 굴러가기 시작했어요.

재미있는 건, 픽셀 비교가 완벽하게 유효한 곳이 따로 있었다는 거예요. 밝은 모드와 어두운 모드의 비교였어요. 이건 같은 화면을 두 번 찍는 거라 위치가 완전히 같거든요. 색을 사전(토큰)에서 가져오지 않고 직접 박아넣은 곳은 모드를 바꿔도 색이 안 변하니, 두 사진의 차이에서 바로 드러나요. 여기서는 판정도 숫자로 해요 — 경험상 진짜 문제는 차이가 5%를 넘고, 글꼴 렌더링 노이즈는 1% 아래였어요.

이 도구들이 장식이 아니라는 건 수정 기록이 증명해요. 나란히 놓기 전에는 "대충 비슷해 보이던" 체크박스 라벨 정렬 같은 것들이, 나란히 놓는 순간 드러나서 공식 구조를 이식해 고쳤어요.

fix(align): KRDS Checkbox·Radio with-description 구조 개편 — KRDS 공식 구조 이식
fix(align): 아이콘+한글텍스트 정렬 nudge 일괄 제거

문서도 거짓말을 못 하게

증명해야 할 게 하나 더 있었어요. 문서예요. 부품은 바뀌었는데 설명서는 옛날 그대로인 것 — 라이브러리에서 신뢰를 제일 크게 깎아먹는 사고예요.

"성실하게 관리하겠다"는 다짐 대신, 불성실하면 부서지는 구조를 만들었어요. 예제 199개와 부품 목록, 한국어 설명이 서로 어긋나면 아예 사이트가 만들어지지(빌드되지) 않아요. 문서가 틀린 채로 세상에 나가는 길 자체를 막은 거예요.

배운 것

증명은 성실함이 아니라 장치에서 나와요. "매번 꼼꼼히 확인할게요"보다 "어긋나면 자동으로 드러나요"가 훨씬 믿을 만한 말이에요. 그리고 자동화의 요령은 기계에게 전부 맡기는 게 아니라, 기계와 사람이 각자 잘하는 일을 나누는 거였어요.

마지막 글은 이 프로젝트의 처음부터 끝까지 기준이 되어준 사람들 이야기예요 — 「마우스 없이 쓰는 사람들」.