1장 하나의 정본과 채택
여러 제품이 같은 규칙을 쓰려면 규칙을 정하는 곳은 한 곳이어야 합니다. Leysys는 디자인 규칙을
leysys-design한 곳에서 정하고, 각 제품은 게시된 결과를 자기 일정에 맞춰 채택합니다.
왜 필요한가
여러 제품이 같은 버튼과 표와 색을 씁니다. 저장소마다 자기 복사본을 직접 고치면 복사본은 조금씩 달라집니다. 이 현상을 어긋남(drift)이라고 부릅니다. 한때 Leysys는 복사본을 두고 같은 작업 안에서 모든 저장소를 똑같이 맞추는 방식으로 배포했습니다. 이 방식을 지키는 수단은 사람과 에이전트의 규율뿐이었습니다.
2026-07-10 KST에 실제 사고가 있었습니다. 한 제품 저장소가 「디자인 시스템이 참고 자료로만 있으면 AI가 규칙을 어긴다」는 타당한 문제의식으로 자체 규약 문서를 만들었습니다. 그런데 그 문서는 스스로를 정본이라고 선언했고, 디자인 시스템에 없는 클래스를 정식 이름으로 적었고, 제품 전용 토큰을 새로 만들었습니다. 어긋남을 막으려던 문서가 어긋남의 첫 사례가 되었습니다. 규약 문서는 디자인 정본으로 옮겨졌고, 쓸 만한 절차 아이디어는 정본이 받아들였으며, 정본에 없는 클래스와 토큰은 폐기되었습니다. 같은 날 CSS와 토큰을 버전 패키지로 배포하기로 결정했습니다.
원칙
정본은 한 곳입니다
정본(SSOT, single source of truth)은 어떤 규칙이나 값을 정하는 단 한 곳입니다. 다른 곳은 정본을 가져다 쓰고, 바꾸고 싶으면 정본을 먼저 고칩니다. 디자인 token·component·pattern과 접근 UX의 정본은 leysys-design 저장소입니다. 회사 공통 정의와 표준은 Leysys Docs가, 제품별 적용은 각 제품의 Docs가 소유합니다.
배포는 두 갈래입니다
| 산출물 | 배포 방식 | 제품이 하는 일 |
|---|---|---|
| CSS·token | 버전 패키지 @leysys/eds·@leysys/mds·@leysys/print-ds·@leysys/markdown-ds | 게시된 정확한 버전을 manifest에 고정하고 lockfile을 커밋합니다 |
| Vue registry wrapper·pattern | 복사본 | 필요한 item을 의존하는 item까지 통째로 복사하고, 이후 직접 소유합니다 |
| 문서 페이지·샘플 | 패키지로 게시하지 않음 | 채택 의무가 없습니다 |
CSS와 token을 버전 있는 산출물로 배포하면, 모든 저장소를 맞추는 규율이 패키지 의존성 해석으로 바뀌고 어느 버전을 쓰는지 lockfile에 남습니다. 디자인 시스템(DS) 하나가 패키지 하나입니다. EDS와 MDS를 다른 패키지로 나누었기 때문에, EDS만 설치한 관리 콘솔 저장소에는 MDS 클래스가 처음부터 없습니다. 한 페이지에 두 DS를 섞지 않는다는 규칙이 의존성 수준에서 지켜집니다. 네 패키지는 같은 버전 번호로 함께 올라가며, 이 책은 3.1.3을 기준으로 합니다. 제품은 ^나 ~ 없이 정확한 버전(exact version)만 씁니다.
registry는 제품이 복사해 쓰는 Vue 컴포넌트와 패턴의 모음입니다. 이 코드는 shadcn/ui처럼 제품이 가져가 소유하고 고칠 수 있어야 하므로 복사본으로 둡니다. 복사는 파일을 골라서 하지 않고, 한 item이 의존하는 item을 모두 포함한 묶음(dependency closure)으로 합니다. 패키지 버전을 올렸다고 wrapper도 바뀐 것으로 보지 않습니다.
채택은 각 저장소가 소유합니다
디자인 시스템 릴리스가 책임지는 범위는 셋입니다.
- 디자인 정본의 관련 계약과 release gate를 통과합니다.
- 같은 후보 패키지로 대표 소비처를 검증합니다. 현재 EDS 2곳, MDS·Print DS·Markdown DS 각 1곳, 모두 5곳입니다.
- SemVer 버전, 변경 기록, migration 안내를 제공합니다.
그 밖의 제품은 게시된 버전과 필요한 registry item을 자기 일정과 PR과 CI로 채택합니다. 디자인 변경이 다른 저장소를 고칠 권한을 자동으로 만들지 않습니다. 예전에는 모든 소비처의 버전을 올려야 릴리스가 끝났습니다. 그러자 컴포넌트 하나를 바꿔도 여러 저장소의 설치·빌드·PR·CI가 따라왔습니다. 이 비용은 품질의 근거가 아니라 독립된 제품 일정을 한데 묶은 운영 결합이었습니다.
채택 PR에는 출처를 남깁니다. 디자인 PR과 병합 SHA, 패키지 버전, 복사한 item, migration 조치, 현재 증명된 범위, 의도적 편차, 실제 화면(route)과 CI 결과입니다.
결함은 정본에서 먼저 고칩니다
여러 제품에 다시 나타날 결함은 제품 쪽 override나 !important로 덮지 않습니다. 정본에서 진단하고 고친 뒤 각 제품이 새 버전을 채택합니다. 제품 고유의 업무 합성과 데이터 계약은 제품이 소유합니다.
편차는 알림이고, 차단은 실제 고장에만 합니다
정본은 기본 구현 방향이자 검토 근거입니다. 그러나 정본과 다른 이름·간격·조합·패턴은 위치와 근거와 규칙 ID가 붙은 내부 알림(alert)으로만 보고합니다. 그것만으로 commit·PR·merge·release를 막지 않습니다. 의도적인 응용과 실험과 제품별 예외는 사전 승인 없이 허용합니다. 자동 차단은 실제로 고장 난 경우에만 합니다.
- 검사 도구의 실행·parse·schema 실패
- compile·type 오류, 순환하거나 풀리지 않는 의존성
- 패키지와 생성 산출물의 무결성 실패
- 실행으로 재현된 runtime·접근성·보안 실패
- release 출처 확인과 게시의 실패
반대로 검사 도구가 고장 났는데 continue-on-error 같은 설정으로 통과시키지도 않습니다. 선호를 이유로 막지 않고, 고장을 숨기지도 않습니다.
실제 예
같은 역할은 같은 패턴, 다른 기능은 다르게
2026-09-23 KST 결정은 일관성의 기준을 화면 모양이 아니라 정보와 행동의 의미로 정했습니다. 같은 대상과 역할에는 같은 용어, 정보의 상대 순서, 탐색·편집·저장·취소 패턴을 씁니다. 기능·권한·업무 대상·청구 귀속이 다르면 그 차이에 맞게 구성합니다.
예를 들어 일반 정보와 사업자 증빙이 모두 있는 상세 화면은 「일반 → 증빙 → 계정」 순서를 씁니다. 증빙이 없는 LeyVote 멤버(유권자)는 「일반 → 계정 → 활동」을 유지합니다. 순서를 맞추려고 빈 증빙 탭이나 가짜 필드를 만들지 않고, 업무 의미가 다른 항목을 겉모습 때문에 합치지 않습니다.
결함은 정본에서, 채택은 각자
2장에서 다루는 Hero 사진 결함은 이 경계를 그대로 따랐습니다. 결함을 보고한 제품은 사진을 감싸는 방식으로 임시 우회했습니다. 정본은 원인을 고쳐 3.1.1로 게시했고, 새 버전으로 올리고 우회를 걷어 내는 일은 각 제품 저장소의 별도 PR로 남겼습니다.
경계와 예외
- 정본을 따른다는 말이 모든 제품이 같은 버전을 쓴다는 뜻은 아닙니다. 각 제품은 자기 시점에 게시된 버전을 고릅니다.
- 알림만 한다는 말이 정본을 무시해도 된다는 뜻은 아닙니다. 편차는 기록되고, 공개 API나 사용자 동작이 바뀌면 의도와 migration 근거를 남깁니다.
- 같은 정책을 적용했다는 사실을 모든 저장소의 같은 구현이나 같은 배포 상태로 넓혀 말하지 않습니다. 진행 중인 전체 작업이 끝났다고 추정하지 않고, 증명되지 않은 기능을 증명된 것처럼 적지 않습니다.
- 파일을 글자 하나까지 똑같이 복사하는 일은 그 산출물의 소유권 계약이 요구할 때만 합니다. 모든 제품 UI의 목표가 아닙니다.
- CDS(공통 참고 체계)는 CSS도 코드도 없는 참고 문서라 패키지가 없습니다. 네 디자인 시스템의 관계는 6장, 배포와 채택의 절차는 24장에서 다룹니다.
정리
- 디자인 규칙의 정본은
leysys-design한 곳입니다. - CSS·token은 버전 패키지로, wrapper·pattern은 제품이 소유하는 복사본으로 배포합니다.
- 디자인 릴리스는 대표 소비처 5곳의 검증까지 책임지고, 나머지 채택은 각 저장소가 소유합니다.
- 재사용 결함은 정본에서 먼저 고칩니다. 정본과의 편차는 알림이고, 차단은 실제 고장에만 합니다.
- 일관성은 같은 화면이 아니라 같은 의미에 같은 패턴을 쓰는 것입니다.
정본
leysys-designdocs/decisions/NPM-PACKAGE-DISTRIBUTION-PROPOSAL-2026-07-10.md— CSS·token 버전 패키지 배포와 1 DS = 1 패키지leysys-designdocs/decisions/EDS-PRODUCT-CONVENTION-SSOT-RELOCATION-2026-07-10.md— 제품 저장소에서 태어난 규약을 정본으로 옮긴 결정leysys-designdocs/decisions/CONSUMER-UPDATE-OWNERSHIP-2026-08-02.md— 대표 소비처 gate와 채택 소유권leysys-designdocs/decisions/SSOT-POLICY-ADVISORY-ENFORCEMENT-2026-08-17.md— 편차 알림과 기술 차단의 경계leysys-designdocs/decisions/CROSS-PROJECT-CONSISTENCY-2026-09-23.md— 프로젝트 간 일관성의 기준leysys-designdocs/process/SSOT-CONSUMER-ADOPTION-STANDARD.md— 소비처 채택 절차와 PR 기록 항목- 문서 소유권과 아키텍처 경계 — 주제별 정본의 위치