oklch 시맨틱 토큰으로 상태 배지 API 설계하기

클린맥 스캔 결과 화면처럼 대기, 진행, 완료, 확인 필요 상태가 한곳에 모이면 배지 색도 API 계약의 일부가 돼요. 화면에서 원색을 바로 고르면 같은 상태가 페이지마다 다르게 보이고, 나중에 테마를 바꿀 때 수정 범위가 커져요.

재현용 상태 API를 직접 만들어 보니, DB에는 색 이름이 아니라 상태 코드만 저장하는 편이 관리하기 쉬웠어요. 예를 들어 status, updated_at, version 3개 필드를 두고 상태는 queued, running, passed, review처럼 4개 값으로 제한할 수 있어요. API는 상태 코드와 표시 문구를 반환하고, 프론트엔드는 코드에 맞는 시맨틱 토큰을 선택해요.

상태 전이를 적용해 봤더니, 색상보다 먼저 막아야 할 것은 잘못된 전환이었어요. passed 상태를 다시 running으로 바꾸려면 별도 재실행 요청을 받도록 하고, 현재 버전이 다르면 API가 HTTP 409를 반환하게 할 수 있어요. 이렇게 하면 여러 요청이 겹쳐도 결과 화면이 조용히 덮어써지는 일을 줄일 수 있어요.

응답을 테스트해 보면 배지는 단 1개의 status 문자열만으로 렌더링할 수 있어요. 색상 값은 서버 응답에 넣지 않고 CSS의 --status-success, --status-warning, --status-neutral 같은 토큰으로 분리해요. 각 토큰은 oklch()로 정의하면 밝기와 채도를 독립적으로 조절하기 편해요.

:root {
  --status-success: oklch(0.72 0.14 150);
  --status-warning: oklch(0.78 0.14 85);
  --status-neutral: oklch(0.62 0.02 260);
}

로컬에서 돌려 보니 이 구조는 인증 경계에도 도움이 됐어요. 스캔 결과를 조회하는 API는 사용자별 소유권을 확인하고, 상태 변경 API는 2개 엔드포인트로 분리해 감사 로그를 남기기 쉬워져요. 라이프케어로그의 플랜비(plan-b)처럼 운영 상태가 자주 바뀌는 화면도 같은 방식으로 상태 계약과 색상 표현을 분리해 볼 수 있어요.