품질 기준
공용 자산이 충족해야 하는 조건이다. 작업자의 기억이나 반복적인 핸드오프에 의존하지 않고 검증 가능한 기준으로 유지한다.
상태
자산의 성격에 따라 필요한 상태를 확인한다.
default
hover
pressed
focus
selected
disabled
loading
error
empty
long content
모든 컴포넌트에 모든 상태를 강제로 만들지는 않는다. 실제 의미가 있는 상태만 정의하되 누락 여부는 명시적으로 검토한다. 일반적으로 있을 법하지만 현재 구현이나 정책에 없는 상태는 만들지 않고 해당 컴포넌트 문서에 현재 정의 없음으로 기록한다. 상태 조합에서 색상이나 우선순위 판단이 필요한 경우 임의로 선택하지 않는다.
접근성
- keyboard navigation
- visible focus
- accessible name
- label과 error 연결
- 필요한 경우
aria-live - 색상만으로 상태를 전달하지 않음
- 일반 텍스트 4.5:1, 큰 텍스트와 필수 UI 3:1 대비를 기본 목표로 함
낭독기에 알릴 자리는 처음부터 문서에 둔다. aria-live·role="status" 를 가진 요소를 알릴 내용과 함께 끼워 넣으면 낭독기가 그 영역을 등록하기 전에 글이 들어와 읽히지 않는 일이 생긴다. 알림 자리는 빈 채로 첫 그림부터 문서에 두고 글만 바꾼다. 「찾는 중입니다」 처럼 조건이 맞을 때만 뜨는 문구도 요소를 감추지 않고 글을 비운다. 상권 서비스에서 지도 알림·검색 결과 수·재기 안내 셋이 모두 이 꼴로 바뀌었다.
짙은 유채색 배경 위의 글자는 WCAG 2.x 수치만으로 판단하지 않는다. 2.x 대비는 상대 휘도만 계산해 색조와 채도를 보지 않으므로, 짙은 유채색에 white 글자를 얹은 경우를 실제 가독성보다 낮게 평가한다. 그런 자리에서는 WCAG 2.x와 APCA 두 값을 함께 재고, 글자 극성은 색조가 아니라 배경 밝기로 정한다. 수치 근거는 badge.md의 「색」에 있다.
반응형과 테마
- Mobile, Tablet, Desktop 검증
- Light/Dark 검증
- overflow와 긴 콘텐츠 검증
중단점은 Tailwind 기본값을 그대로 쓴다. sm 640, md 768, lg 1024, xl 1280, 2xl 1536이며 저장소는 이 값을 재정의하지 않는다.
앱 화면의 최소 폭은 280px다. 그보다 좁아지면 화면을 다시 짜지 않고 가로로 스크롤한다.
모든 서비스에서 글자는 단어 중간에서 줄이 바뀌지 않는다. word-break: keep-all을 기준으로 삼아 어절 단위로만 줄을 넘긴다. 한 어절이 남은 폭보다 길 때만 그 어절 안에서 끊는다. 단어가 잘리면 읽는 사람이 앞 조각을 다시 붙여 읽게 되고, 좁은 폭일수록 그 일이 자주 일어난다.
관리자 웹은 lg까지만 대응한다. 최소 폭이 1024px이고 그보다 좁아지면 화면을 다시 짜지 않고 가로로 스크롤한다. 관리자는 PC에서만 쓰는 화면이므로 태블릿과 모바일 구간을 설계하지 않는다. 앱 화면은 이 규칙을 따르지 않으며 모바일 뷰가 기준이다.
인쇄
종이는 Light/Dark 와 나란히 놓인 또 하나의 매체다. 인쇄를 지원하는 화면은 아래를 지키고, 지원하지 않는 화면은 브라우저 기본 그대로 둔다. 값은 상권 서비스에서 헤드리스 Chrome 으로 재어 확인한 것이다.
그림자는 인쇄에서 뺀다. 종이에는 빛이 없어 shadow-* 가 층을 말하지 못하고 회색 얼룩으로만 남는다. 지도·목록 위에 얹히는 상자처럼 그림자로 층을 가르는 자리는 print:shadow-none 으로 덮고 테두리만 남긴다.
인쇄의 중단점은 종이 폭이 아니라 기본 쪽 크기로 걸린다. @page 에 이름을 붙여 크기를 바꿔도 매체 질의는 그 크기를 보지 않는다. 그래서 화면에서 넓은 폭이던 배치가 인쇄에서 max-lg: 쪽으로 걸릴 수 있다. 인쇄 배치는 lg: 와 max-lg: 어느 쪽이 걸려도 같은 모양이 되도록 print: 로 덮는다.
잠깐 뜨는 것은 인쇄하지 않는다. 알림 한 줄, 열려 있던 popup, 도구 막대와 확대·축소 단추처럼 누르는 자리는 종이에서 뜻이 없다. 접혀 있던 내용은 거꾸로 펼쳐서 싣는다 — 종이에는 펼칠 방법이 없다.
코드
- TypeScript와 lint 통과
- 정식 자산에서 raw primitive color 0개
- 정식 자산에서 shadcn visual token 0개
- 기존 ooee 컴포넌트 재사용
- 의미 없는 wrapper와 불필요한 abstraction 최소화