디자인 SSOT와 하네스 한눈에 보기

0한눈에

디자인 값(색·간격·서체)은 토큰 파일 한 곳에만 둡니다. 화면 코드는 var()로, 하네스 규칙 문서는 경로로 그 자리를 가리킵니다. 하네스는 값이 아니라 판정 기준과 금지 목록을 갖고, 배포 CI가 새 위반을 막습니다. 그래서 서체를 바꿀 때 고칠 곳은 한 곳입니다.

flowchart TD
  T["토큰 파일 theme.css<br/>:root 의 변수 = 정본"]
  C["화면 코드<br/>var(--변수)로 참조"]
  R["하네스 규칙 문서<br/>정본 경로 + 판정 기준 + 금지 목록"]
  S["화면 계약<br/>시각 값의 주인 선언"]
  G["디자인 검사 lint:design<br/>새 위반만 차단"]
  CI["배포 CI<br/>검사 실패 시 빌드 중단"]
  T -->|값을 가져옴| C
  R -.->|경로로 가리킴| T
  R -->|판정 기준 제공| S
  S -->|"contract: 토큰을 따름"| C
  C --> G --> CI

1디자인 SSOT: 값은 한 곳에

요점 값은 토큰 파일 한 곳에만 두고, 화면과 문서는 모두 그 자리를 가리킵니다.

SSOT는 "같은 값은 한 곳에만 적고, 나머지는 그 자리를 가리킨다"는 원칙입니다. 값이 두 곳에 있으면 한쪽만 고쳐지는 순간 둘이 어긋나고, 어느 쪽이 맞는지 판단할 근거가 사라집니다.

1-1. 정본의 실제 모습

제품 저장소의 토큰 파일이 정본입니다. 기본값은 :root에 모이고, 다크 모드는 .dark가 필요한 값만 덮어씁니다.

/* src/styles/theme.css: 정본 */
:root {
  --primary: #22304a;
  --bis-gap: 12px;
  --foundation-font-family-sans:
      "Pretendard Variable", "Pretendard", -apple-system, sans-serif;
}

/* 화면 쪽: 값을 복사하지 않고 가리킨다 */
.title {
  font-family: var(--foundation-font-family-sans);
}

1-2. 한 줄을 바꾸면 무엇이 따라오나

단, 화면 계약에서 "목업이 시각 값을 정한다"고 선언한 화면은 따라오지 않습니다. 이 선언은 3절에서 설명합니다.

1-3. 디자인 시스템 4층

값은 토큰 층에 있고, 위 층으로 갈수록 업무에 가까운 결정이 쌓입니다. 층마다 기준을 두는 곳이 다릅니다.

권한과 승인 조건 같은 업무 규칙의 정본은 그 업무의 명세에 둡니다. 디자인 시스템은 그것을 화면에 어떻게 표현할지만 연결합니다.

2문서마다 담는 것

요점 문서마다 소유하는 것이 다릅니다. 다른 문서의 것은 옮겨 적지 않고 가리킵니다.

문서마다 소유하는 것이 다릅니다. 한 문서가 다른 문서의 소유물을 옮겨 적기 시작하면 사본이 생깁니다.

flowchart TD
  subgraph OWN["각자 소유"]
    T2["토큰 파일<br/>값"]
    D2["디자인 시스템 문서<br/>구성 · 사용법 · 패턴"]
    H2["하네스 규칙<br/>판정 축 · 금지 목록"]
    L2["검사 스크립트<br/>기계 판정 규칙"]
  end
  D2 -.->|변수 이름만 인용| T2
  H2 -.->|경로로 가리킴| T2
  H2 -.->|경로로 가리킴| D2
  H2 -->|판정 가능한 금지만 옮김| L2

규칙 문서에 서체를 적어야 할 때는 Pretendard처럼 값을 쓰지 말고 --foundation-font-family-sans처럼 변수 이름을 씁니다. 값이 바뀌어도 이름은 그대로라 문서를 고칠 일이 없습니다.

3하네스 규칙은 이렇게 처리합니다

요점 하네스 기준서는 값이 아니라 판정 기준을 가집니다. 시각 값의 주인은 화면마다 선언합니다.

3-1. 기준서는 포인터와 판정 축만 소유합니다

디자인 기준서(하네스 스킬)는 첫머리에 "값의 정본을 복제하지 않고 포인터로 연결한다"고 적어 둡니다. 기준서와 정본이 충돌하면 정본이 이깁니다.

3-2. 지키는 강도는 세 단계입니다

프로토타입 작성 스킬이 강도를 나눕니다. 디자인 시스템이 아직 확정 전이라, 토큰과 맞는지는 막지 않고 참고로만 봅니다.

3-3. 시각 값의 주인을 선언합니다

프로토타입의 <main data-design-status="…">가 "이 화면의 시각 값을 목업이 정하는지, 토큰이 정하는지"를 밝힙니다. 구현자는 착수 전에 이 값부터 읽습니다.

마커가 없는 화면은 판정할 수 없는 것으로 보고, 구현 기준으로 쓰지 않습니다.

flowchart TD
  M["프로토타입 화면"] --> Q{"data-design-status?"}
  Q -->|contract| A["구조만 가져오고<br/>시각은 토큰을 씀"]
  Q -->|normative| B["목업의 간격·색·문구를<br/>그대로 옮김"]
  Q -->|exploratory 계열| C["구현 기준 아님"]
  Q -->|없음| D["판정 불가"]

4강제는 세 층에서

요점 같은 디자인 검사를 작성·수정·배포 세 지점에 걸고, 새로 생긴 위반만 막습니다.

원칙만 적어 두면 사본은 조용히 샙니다. 그래서 같은 디자인 검사를 세 지점에 걸어 둡니다.

flowchart TD
  W["1 작성<br/>하네스 스킬이 정본 경로를 읽음"] -->|권고| X["2 수정 루프<br/>typecheck + lint:design 통과해야 '수정됨'"]
  X -->|차단| Y["3 배포 CI<br/>dev · staging · prod 빌드 명령"]
  Y -->|"lint:design 실패"| Z["빌드 중단"]
  Y -->|통과| OK["배포"]

4-1. 디자인 검사가 보는 것

lint:design은 화면 코드(.ts, .tsx, .css)를 보고, 정본인 theme.css는 검사에서 뺍니다. 규칙은 9개입니다.

4-2. 래칫: 새 위반만 막습니다

기존 위반은 기준선 파일(design-gate-baseline.json)에 파일×규칙별 건수로 고정하고, 건수가 늘어날 때만 실패시킵니다. 위반을 줄이면 기준선을 갱신해 다시 늘지 못하게 합니다. 한 번에 다 고치지 않아도 나빠지지는 않게 만드는 방식입니다.

5더 넓게 보기: 디자인 하네스 흐름

요점 하네스 전체는 여섯 단계로 돌고, 이번 화면을 고치는 일과 다음 기준을 바꾸는 일을 나눕니다. 전체 내용과 실습은 디자인 하네스 가이드 6판에 있습니다.

디자인 시스템이 "어떤 기준을 지킬지"를 담는다면, 하네스는 그 기준을 언제 읽고 어떻게 검사하며 어디로 되돌릴지를 연결합니다. 핵심은 이번 화면을 고치는 일과 다음 작업의 기준을 바꾸는 일을 구분하는 것입니다.

5-1. 여섯 단계와 두 개선 경로

flowchart TD
  I["01 Intent<br/>목적과 범위"] --> R["02 Rules<br/>토큰 · 상태 · 동작 · 업무 계약"]
  R --> G["03 Generate<br/>시안 · 프로토타입 · 코드"]
  G --> E["04 Execute<br/>브라우저에서 실제 조작"]
  E --> V["05 Verify<br/>기준과 대조, 증거 남김"]
  V -->|"A 화면 수정<br/>기준은 맞고 구현이 어긋남"| G
  V --> F["06 Refine<br/>개선 후보 정리"]
  F -->|"B 규칙 개선<br/>후보 → 검토 → 반영"| R

5-2. 골든 셋: 화면과 조건을 함께 묶은 비교 기준

보기 좋은 이미지 한 장으로는 무엇을 지켜야 하는지 설명하기 어렵습니다. 골든 셋은 대표 화면에 조건과 판정 방법을 함께 묶습니다.

5-3. 차이를 발견하면

5-4. 자동화와 사람 게이트

문서와 시안은 자동화가 만들고, 품질과 방향은 게이트와 사람이 지킵니다. 되돌리기 어려운 결정(등록·병합·배포)은 자동화가 준비까지만 합니다.

프로토타입에서 통과한 화면도 제품의 서버 저장·권한·동시 편집 검증을 대신하지 않습니다. 두 완료 상태는 따로 기록합니다.

6용어

7출처

• 디자인 하네스 가이드 6판 (2026-09-20, 확장판): 5절의 단계·골든 셋·차이 처리·디자인 게이트 표를 요약했습니다. 원문의 예시 화면과 수치는 설명용 가상 예시입니다.
• 제품 저장소 dev 브랜치 (2026-09-22 기준): src/styles/theme.css, scripts/lint-design.cjs, 배포 워크플로 3개.
• 문서 저장소 main 브랜치: 디자인 기준서 스킬, 프로토타입 작성 스킬, 프로토타입→React 계약 문서, 문서 정합 CI.
• 4절의 숫자(검사 규칙 9개)는 2026-09-26에 파일을 직접 열어 센 값입니다.