참고 구현 — 한 사내 도구의 v2 시안에서 가져온 원칙

이 문서는 이 스킬의 규칙 여럿이 나온 참고 구현(한 사내 도구의 v2 시안)에서 무엇을 원칙으로 가져왔고 무엇을 가져오지 않았는지 적습니다. 가져온 것은 구조 · 위계 · 순서 · 판정 기준이고, 색 · 크기 같은 값은 하나도 가져오지 않았습니다. 시안의 파일 주소 · 노드 · 제품 이름은 이 문서에 두지 않습니다. 같은 시안을 열어 봐야 하는 작업이면 요청이 인자로 넘기거나 제품 저장소의 문서를 봅니다. 규칙 자체의 정본은 각 문서(layout.md · patterns.md · copy.md · figma-file.md · token-usage.md)이고, 이 문서는 그 규칙이 어디서 왔는지와 반면교사를 남깁니다. 시안이 한 도메인의 도구였으므로 예시는 교육 · 병원 · 커머스 · 사내 도구로 옮겨 적었습니다.

• 다크로만 그렸습니다. 라이트 화면이 없었습니다.
• CoUI 변수 연결이 없었습니다. 색은 모두 원시 값이고, 텍스트 스타일 · 효과 스타일도 쓰지 않았습니다.
• 부품은 CoUI 인스턴스가 아니라 파일 안의 시안 키트였습니다. 키트 자체가 CoUI 리디자인 후보였습니다.

그래서 이 시안에서는 관계만 가져옵니다. 어느 것이 먼저 오는지, 무엇이 무엇보다 크고 진한지, 무엇을 몇 개 두는지입니다. 값은 CoUI 토큰으로 다시 고릅니다(token-usage.md · layout.md).

• 순서가 곧 읽는 법입니다. 표지 → 개요 → 부품 → 공통 원본 → 역할 페이지들 → 보관. 이 스킬은 같은 순서를 cc-blueprint 페이지 이름(000 overview-개요 · 900 components · 010 common-공통 · 100 … · _archive)으로 옮겼습니다.
• 시안은 묶음 사이에 구분선 페이지를 두었습니다. 이 이름은 cc-blueprint 검사 예외 목록에 없어 구조 검사에 걸립니다. 쓰지 않고 순서만으로 묶음이 보이게 합니다.
• 공통 페이지 맨 위에 「이 페이지가 무엇인지」 설명을 두었습니다. 이 스킬은 모든 역할 페이지 맨 위에 「이 페이지는」 한 줄을 둡니다.
• 부품 페이지의 도메인 컴포넌트마다 「왜 CoUI 에 넣지 않는지 · 안쪽은 어떤 CoUI 재료로 조립했는지」 두 줄이 있었습니다. 그대로 가져왔습니다(patterns.md 8절 5번).
• 부품 페이지에 「CoUI 지금 ↔ 시안」을 나란히 두고 「구조 유지 · 바뀌는 점」을 적은 비교가 있었습니다. CoUI 후보를 올릴 때 같은 형식을 쓰면 판정이 빨라집니다.

Overview 에서 가져온 것

• 문서마다 「제목 + 한 줄 설명」 머리를 두고 세로로 쌓았습니다.
• 열린 질문을 「아직 몰라요」로 비우지 않고 지금 시안이 가정한 값을 함께 적었습니다.
• 화면 지도의 칸을 네 가지로 구분했습니다 — 이 역할 전용 「코드」 · 공통 원본 인스턴스 「↗ 코드」 · 셸만 바꾼 사본 「= 코드」 · 없음 「—」. 역할별 차이가 한눈에 보입니다.
• 역할 카드에 「한도 · 할 수 있는 것 · 끝나면 어떻게 되는지 · 결제 주체」 네 줄을 두었습니다. 이 스킬은 결제 주체를 권한표의 열로 올렸습니다.
• 역할마다 색을 정해 문서 카드 · 칩 · 상단 바 역할 칩까지 같은 색을 썼습니다. 이 스킬은 「역할 색은 기본으로 두지 않고, 정하면 문서와 화면에서 같게, 상태색과 겹치지 않게」로 가져왔습니다(patterns.md 7절).

Overview 의 반면교사

• 결제 주체가 역할 카드 문장에만 있고 권한표에는 없었습니다.
• 「○ 보기만」 기호가 범례에만 있고 표에서 한 번도 쓰이지 않았습니다. 정말 보기만 하는 기능이 없는지 확인하지 않은 흔적입니다.
• 화면 지도 표의 머리 행과 합계 행이 잘려 보였습니다.

• 상단 바: 왼쪽에 맥락(작업 공간 전환 · 지금 경로), 가운데 전체 검색, 오른쪽에 지금 역할 칩 + 아바타.
• 사이드바: 첫 묶음은 이름표 없이 주요 메뉴, 그 아래 묶음에만 이름표. 맨 아래 한 자리는 플랜 · 사용량 카드.
• 고객이 쓸 수 없는 기능은 메뉴에서 숨기고, 그 기능이 필요한 화면 안에 잠긴 카드와 업그레이드 자리 하나를 두었습니다.
• 메뉴 이름이 기능이 늘면서 함께 자랐습니다(커머스로 옮기면 「주문」 → 「주문과 배송」). 역할마다 메뉴 이름을 새로 짓지 않습니다.

도메인으로 옮기면

반면교사

• 「권한 없음」 화면이 없었습니다. 메뉴에서 숨기는 것으로 대신했기 때문입니다. 직접 주소 · 공유 링크로 들어오는 경우가 비어 있습니다. 이 스킬은 NoPermission 상태를 따로 요구합니다(patterns.md 6 · 7절).
• 한 화면에 업그레이드 버튼이 둘이었습니다 — 사이드바 플랜 카드의 고대비 버튼과 본문 알림 안 버튼. 이 스킬은 사이드바 카드를 조용한 정보 자리로 두고 버튼을 빼거나 ghost 로 내립니다.
• 오프라인일 때 상단 바 역할 칩 자리를 상태 칩이 차지해 지금 역할이 보이지 않았습니다. 지금 역할은 늘 보여야 합니다.

수치에서 배운 것

• 같은 자리의 여백이 화면마다 두 가지로 섞였고, 4의 배수가 아닌 값이 많았습니다. 원칙은 「같은 자리는 같은 값」이고, 값은 CoUI 간격 사다리에서 가장 가까운 것으로 옮깁니다(layout.md 6절).
• 모서리 위계(칩 < 버튼 < 알림 < 패널 < 대화상자)는 지켜졌습니다. CoUI 에서도 대화상자(modal 20)가 카드(surface 16)보다 한 칸 커서 이 위계가 부품 기본값으로 성립합니다(layout.md 7절).
• 본문 글자 크기가 세 가지 섞여 실제로는 다섯 단계를 넘었습니다. 이 스킬은 네 단계로 묶습니다(layout.md 9절).

• 시안에는 판정 기준이 없어서 행동 결과(「되돌렸어요」 「저장했어요」)도 페이지 안 알림으로 그렸습니다. 페이지 안 알림이 열여섯 화면, 떠 있는 알림이 두 화면이었습니다. 이 스킬은 「결과가 화면에 기록으로 남아야 하면 Alert, 잠깐 알리고 사라져도 되면 Toast」로 판정합니다.
• 페이지 안 알림의 자리 네 가지(셸 전체면 페이지 머리 위 · 이 페이지면 머리 아래 · 한 행동의 결과면 그 흐름 안 · 대화상자 안)를 그대로 가져왔습니다(patterns.md 1절).
• 시안은 두 알림을 같은 계열의 표면으로 그렸습니다 — 패널 면 위 상태색의 아주 옅은 톤, 한쪽 모서리에서 번지는 사선 그라디언트, 상태색 옅은 테두리, 상태색 원 아이콘, 제목만 상태색, 패널보다 한 단계 작은 모서리. 그리고 이것을 도메인 컴포넌트로 다시 만들었습니다.
• 이 스킬은 그 표면을 가져오지 않습니다. CoUI Alert · Toast 를 그대로 쓰고, 표면은 「CoUI 후보」로만 기록합니다(patterns.md 1절). CoUI 에 있는 부품을 제품에서 다시 만들면 cc-blueprint L0 이고, 모든 서비스에 쓰려는 생김새라 판정 질문으로 봐도 도메인이 아니라 CoUI 몫이기 때문입니다.
• 떠 있는 알림에 행동이 셋까지 있었습니다. CoUI Toast 는 행동 칸이 하나라 이 스킬은 하나 + 닫기로 두고, 셋은 CoUI 후보입니다.
• 알림 안에 주 버튼을 두지 않은 것은 그대로 가져왔습니다. 시안의 「반투명 보조 버튼」은 CoUI 에서 Alert 면 outline · ghost sm, Toast 면 ghost 입니다(patterns.md 1절).

• 시안의 버튼은 넷이었습니다 — 가장 높은 대비의 주 버튼, 패널보다 한 단계 밝은 면의 보조, 면 없는 버튼, 옅은 오류 면 + 오류 글자의 위험 버튼. CoUI 로 옮기면 primary · outline · ghost(글자만 있는 이동은 Link) · destructive 입니다(token-usage.md 6절).
• 「주 버튼은 흰색」은 다크로만 그린 결과일 뿐입니다. 원칙은 「주 버튼은 화면에서 가장 높은 대비」입니다.
• 페이지 머리는 보조 + 주, 주가 맨 오른쪽. 패널 안 행의 행동은 보조 sm.
• 대화상자 버튼 배치가 세 가지 섞여 있었습니다. 이 스킬은 하나로 정했습니다(patterns.md 5절).

반면교사

• 상세 머리에 버튼 셋(최대 둘을 넘음).
• 대시보드 머리의 「새로 만들기」와 행 안 「승인」이 둘 다 주 버튼.
• 빈 상태 버튼과 페이지 머리 버튼이 같은 「새로 만들기」를 주 버튼으로 두 번.

• 해요체, 짧게, 버튼은 동사로 끝 — 그대로 가져왔습니다.
• 가장 큰 수확은 실패 문구의 「그대로인 것」입니다. 병원 「예약은 그대로 잡혀 있어요」, 커머스 「장바구니는 그대로 있어요」, 사내 도구 「이전 버전이 그대로 돌아가요」처럼 사용자가 먼저 걱정하는 것을 답합니다.

반면교사

• 명사로 끝난 버튼이 섞였습니다(「공유」 「해지」 「영수증」 「변경」). copy.md 5절에서 동사로 정리합니다.
• 관리자 화면에만 합니다체가 섞였습니다. copy.md 2절은 모든 화면을 해요체로 둡니다.
• 고객 결제 실패 화면에 오류 코드가 그대로 보였습니다(copy.md 10절).
• 캡션의 화면 글자 인용에 「」 와 ‘ ’ 가 섞였습니다. copy.md 8절은 「」 하나입니다.
• 숫자와 단위를 띄어 썼습니다. copy.md 7절은 붙여 씁니다(「1,284명」).

• 역할 페이지의 줄 묶음 번호를 모든 역할에서 같게 두고, 그 역할에 없는 묶음은 뺐습니다. 같은 번호끼리 보면 역할별 차이가 보입니다(figma-file.md 4절).
• 화면 이름을 「역할 접두 · 원래 코드 제목」으로 짓고, 코드는 코드 쪽 점검 문서의 것을 그대로 썼습니다. 이 스킬은 이 문자열을 cc-blueprint 계약 위의 섹션 이름으로 옮겼고, 프레임 이름은 cc-blueprint 의 플랫폼-상태(Web-Default 등) 그대로입니다(figma-file.md 2 · 3절).
• 캡션은 프레임 위 두 줄이었고, 시안은 캡션을 프레임으로 감쌌습니다. 이 스킬은 프레임 이름 검사에 걸리지 않게 TEXT 하나로 둡니다.
• 한 줄 다섯 장, 같은 간격. 시안은 데스크톱 앱 창 크기 프레임을 썼지만 이 스킬은 cc-blueprint 의 플랫폼 크기를 씁니다.
• 공통 판정: 상단 바 · 사이드바까지 모든 역할에서 픽셀이 같으면 공통, 하나라도 다르면 역할 페이지. 대화상자만 같으면 대화상자만 공통. 셸만 다른 사본의 캡션은 원본을 가리켰습니다(「수강생의 S-04 와 같은 흐름 · 강사 사이드바」 꼴).

새 화면을 비슷한 화면 복제로 시작할 때 남기 쉬운 것들입니다. figma-file.md 6절의 스크린샷 확인 표가 여기서 나왔습니다.

• 목록이 빈 상태인데 맥락 줄에 복제 원본의 개수가 그대로 남았습니다.
• 체험이 끝난 화면인데 사이드바 카드에 「남은 일수」가 그대로였습니다.
• 경로는 한 메뉴인데 페이지 제목은 다른 메뉴였습니다.
• 표지의 판 번호가 옛것이었습니다.
• 제품 화면 안에 「결정 필요」 같은 저작 메모 칩이 남았습니다.
• 결제 수단 카드 하나에 장식 그라디언트가 있었습니다.
• 오프라인 상태 칩이 역할 칩 자리를 차지했습니다.

• 값 — 다크 전용 색 값 전부(바탕 · 패널 · 행 · 글자 · 상태색 · 상태 칩 면), 알림 표면의 투명도 · 그라디언트 수치, 그림자 수치, 여백 · 모서리 · 글자 크기 숫자. 모두 CoUI 토큰으로 다시 고릅니다.
• 「주 버튼은 흰색」 — 다크의 결과일 뿐입니다(7절).
• 그 도구 전용 화면 · 부품 — 코드 편집기 · 터미널 · 에이전트 대화처럼 개발 도구에만 있는 화면과 부품, 데스크톱 창 장식.
• 그 서비스만의 결정 — 「관리자는 플랜 없음 · 결제 화면 없음」, 관리자 역할을 나누지 않음, 고객 대신 결제하지 않음, 체험 기간 · 개수 한도 · 수정 횟수 · 오프라인 유예 기간 숫자, 로그인 방식, 배포 환경 수와 운영 배포 재확인, 만들기 흐름의 구체 단계 이름.
• 역할 이름과 역할 색 배정 — 서비스마다 다시 정합니다.
• 화면 코드 체계 — 원칙은 「코드 쪽 문서와 같은 코드를 쓴다」 하나입니다.
• 메뉴 · 묶음의 구체 단어 — 「주요 / 운영 / 관리」는 이 스킬의 기본 묶음이고, 그 안의 메뉴 이름은 서비스의 말로 짓습니다(copy.md 9절).
• 시안 키트 컴포넌트 자체 — 새 서비스는 CoUI 인스턴스를 씁니다.

• 이 문서와 같은 형식을 씁니다 — 「원칙 · 본 것 · 이 스킬의 자리」 표, 반면교사, 가져오지 않는 것.
• 지금 더해진 참고 구현: reference-impl-app.md — 한 손님용 앱 시안(손님 앱 + 운영 콘솔). 손님용 앱 기본 예시(mood.md 1-1 · layout.md 10절)가 거기서 나왔습니다.
• 파일 주소 · 노드 · 제품 이름은 적지 않습니다. 이 저장소의 plugins/ 는 공개되므로 제품 정보는 제품 저장소 문서에 둡니다.
• 값은 가져오지 않습니다. 관계와 판정 기준만 가져오고, 규칙이 바뀌면 해당 문서(layout.md 등)를 고친 뒤 여기에는 출처만 남깁니다.
• 참고 구현이 이 스킬과 다르게 했고 그쪽이 낫다고 판단되면, 그 판단은 figma-file.md 8절의 세 관점으로 적고 이 스킬을 고칩니다. 참고 구현이 그렇게 했다는 것 하나로는 근거가 되지 않습니다.