YDS
YBM 서비스 공용 디자인 시스템. Figma 변수/컴포넌트가 정본이고, 이 저장소(yds)는 그걸 코드로 옮긴 배포 패키지와 동기화 도구다.
이 폴더 하나가 GitHub 저장소 하나다(가이드 사이트와 분리된 단독 저장소).
1. 폴더 구조
yds/ ← 저장소 루트 (2026-11-04 저장소 이름 ybm-ds → YDS) = Pages 사이트 루트
├─ README.md ← 이 문서 (DS 전체 안내)
├─ CLAUDE.md Claude 작업 기준 (원칙, 기준 주소, 상시 규칙, 두 PC 싱크). 진행 상황은 적지 않는다
├─ docs/handoff.md 최신 인수인계 1건 (작업 끝에 덮어쓴다, 시작할 때 읽는다)
├─ docs/log.md 지난 작업 기록, 보류, 정리 후보 (필요할 때만 찾아본다)
├─ index.html 컴포넌트 미리보기 (48종, Light/Dark, ?only=43-48로 골라 보기)
├─ components.json 컴포넌트 목록 - CSS 클래스, Figma 노드 ID, 변형 수 (sync가 양쪽과 대조)
├─ sync.mjs ◆ 통합 동기화 (Figma ↔ 로컬 ↔ GitHub ↔ 가이드 사이트)
├─ 동기화.bat 더블클릭 = node sync.mjs deploy (검증 → 커밋 → GitHub 반영)
├─ deploy.config.json 저장소, Pages 주소, 브랜치
├─ dist/ ← 배포 패키지(2026-10-27 ybm-ds/ → dist/). 서비스는 이 폴더를 가리킨다
│ ├─ ybm-ds.css 진입 파일 (이것 하나만 link) - 아래 5개를 cascade layer로 import
│ ├─ tokens.css 토큰 (⚠ 생성물 - 손으로 고치지 않음)
│ ├─ base.css 리셋, Pretendard @font-face, 포커스 링, reduced-motion, .ds-sr-only
│ ├─ icons.css Lucide 아이콘 (data URI + mask) .ds-icon
│ ├─ components.css 컴포넌트 48종 .ds-*
│ ├─ utilities.css .ds-t01~t17, .ds-fw-*, .ds-fg-*, .u-*
│ ├─ ybm-ds.js 공통 인터랙션 (의존성 없음)
│ └─ fonts/ Pretendard woff2 (CSS 가 쓰는 400/500/600/700 4종만)
├─ tokens/ ← 토큰 소스와 파생물
│ ├─ figma-variables.json Figma 변수 전집 스냅샷 = source of truth
│ ├─ build.mjs 스냅샷 → tokens.css + 파생 3종 생성 (Node - Python 불필요)
│ ├─ figma-sync.mjs Figma ↔ 스냅샷 비교/병합 (sync.mjs가 호출)
│ ├─ design-tokens.json (생성물) 중첩 JSON
│ ├─ tokens.js (생성물) JS 객체
│ └─ tailwind.preset.js (생성물) Tailwind preset - 값은 전부 CSS 변수 참조
├─ .claude/skills/ds-sync/ Claude 용 동기화 절차 ("ds 동기화" 라고 요청하면 이 순서대로 실행)
└─ .claude/skills/yds-figma-draw/ Claude 용 Figma 그리기 절차 (템플릿, 문서 프레임을 사이트와 같게 다시 그릴 때)
git에 올리지 않는 것(.gitignore): tokens/.figma-check.js, tokens/.figma-result.json, tokens/figma-variables.backup-*.json
손으로 관리하는 파일 vs 생성물
| 구분 | 파일 |
|---|
| 직접 편집 | base.css icons.css components.css utilities.css ybm-ds.css ybm-ds.js index.html components.json sync.mjs tokens/build.mjs tokens/figma-sync.mjs |
| 생성물 (편집 금지) | dist/tokens.css tokens/design-tokens.json tokens/tokens.js tokens/tailwind.preset.js tokens/.figma-check.js |
| 스냅샷 (sync 로만 갱신) | tokens/figma-variables.json - 단 cssOnly 묶음(글꼴 목록, 모션, z-index, 기준점)은 손으로 고친다 |
2. 사용법
<!-- 배포 주소에서 바로 (가이드 사이트/외부 시안) -->
<link rel="stylesheet" href="https://luvms012-rgb.github.io/yds/dist/ybm-ds.css">
<script src="https://luvms012-rgb.github.io/yds/dist/ybm-ds.js" defer></script>
<!-- 로컬 작업(works 폴더 안) - 상대경로. 가이드 배포 때 위 주소로 자동 치환된다 -->
<link rel="stylesheet" href="../../../../ybm-ds/dist/ybm-ds.css">
<link rel="stylesheet" href="…/{서비스}.css"> <!-- 서비스 전용은 DS 다음에 -->
<html data-theme="dark"> <!-- 다크 모드(선택). 모드는 Light/Dark 두 가지뿐 -->
Cascade Layers
DS 전체가 @layer ds.tokens, ds.base, ds.icons, ds.components, ds.utilities 안에 들어 있다.
레이어 밖에 쓴 서비스 CSS는 선택자 우선순위와 상관없이 항상 DS를 이긴다 → !important/선택자 길이 경쟁 불필요.
커스텀 규칙
- 서비스는 컴포넌트 변수(
--ds-*)만 바꿔서 커스텀한다. 클래스 신설/!important 금지.
예) .signup-dialog { --ds-dialog-width: 360px; }
- 토큰 레이어 중 팔레트는 YBM 전체 공유, 서비스는 시맨틱/컴포넌트 층만 덮어쓴다.
ybm-ds.js가 하는 일 (CSS로 안 되는 것만)
| 기능 | 사용 |
|---|
| Dialog 열기/닫기 | data-ds-open="dialogId" / data-ds-close 속성, 바깥(dim) 클릭 닫기. 네이티브 <dialog>.showModal() |
| Snackbar | DS.snackbar("문구", { tone: "positive"|"critical", action: "확인", onAction, duration }) - 기본 4초 |
| Slider | <input type="range" class="ds-slider"> 채움 길이(--ds-slider-value) 동기화 |
| Checkbox | data-indeterminate → input.indeterminate = true |
| Text Field clear | 값 지우기 (노출/숨김은 CSS) |
3. 동기화 - Figma ↔ 로컬 ↔ GitHub ↔ 가이드 사이트
Figma 변수/컴포넌트
│ ① node sync.mjs figma → tokens/.figma-check.js
│ Claude가 use_figma로 실행(읽기 전용) → 결과를 tokens/.figma-result.json에 저장
▼
② node sync.mjs pull
├─ 변수 변경 → figma-variables.json 병합(백업) → build.mjs로 생성물 4종 재작성
├─ 컴포넌트 대조 → components.json과 다른 노드/변형 수/목록에 없는 세트 보고
├─ 문서 프레임 링크 대조 → 문서 / 코드 링크가 어긋나면 보고 (고치기는 node sync.mjs links)
├─ 검증(아래) → 실패하면 멈춤
├─ git commit → push → GitHub Pages(1~2분 뒤 반영)
└─ 가이드 사이트 재배포(project/_publish/publish.ps1) - 가이드는 DS를 Pages 주소로 참조
| 하고 싶은 일 | 명령 |
|---|
| 전부(Figma → 로컬 → GitHub → 가이드) | Claude에게 "ds 동기화" - ①② 를 이어서 실행한다 |
| 로컬에서 고친 CSS를 올리기 | 동기화.bat 더블클릭 또는 node sync.mjs deploy "메시지" |
| 상태만 보기 | node sync.mjs (검증, 커밋 안 된 변경, 스냅샷 날짜, 사이트 응답) |
| Figma 문서 프레임의 문서 / 코드 링크 다시 걸기 | node sync.mjs links → 만든 tokens/.figma-links.js를 Claude가 use_figma로 실행 |
| 토큰만 다시 빌드 | node sync.mjs build (또는 node tokens/build.mjs <날짜> <폴더>로 다른 곳에 빌드해 diff) |
| 옵션 | --no-push 커밋까지만, --ds-only 가이드 재배포 생략 |
검증 항목 (node sync.mjs verify, deploy/pull이 매번 실행)
- 생성물 4종 = 스냅샷으로 다시 빌드한 결과 (tokens.css를 손으로 고쳤거나 빌드를 빠뜨리면 실패)
ybm-ds.css가 import 하는 파일, base.css의 폰트 파일이 실제로 있는지components.json의 클래스가 components.css에 모두 있는지 (+ 목록에 없는 루트 클래스 경고)
변수 비교 기준: 이름, 타입, 모드별 값(색 hex, 숫자, 별칭 이름), description. 스냅샷이 불완전하면(개수 불일치/모드 누락/별칭 미해결) 빌드가 즉시 실패한다.
컴포넌트 비교 기준: components.json의 노드 ID 존재, 타입, 변형 수, Components 페이지에서 목록에 없는 COMPONENT_SET.
처음 한 번: GitHub에서 저장소 yds(Public, README 없이) 생성 → Settings → Pages → Branch main / root.
push 인증은 PC의 Git Credential Manager(가이드 배포와 같은 GitHub 로그인)를 그대로 쓴다.
This is the beginning of the README. Read the rest at the original. Read the full README ↗
