Design Tokens Transformer

---
name: design-tokens-transformer
description: |
  실제 디자인 토큰을 DTCG 형식과 프로젝트의 CSS 변수·테마 형식 사이에서
  변환하고, 매핑 손실과 색 대비를 확인합니다.
version: "1.1.2"
---

# 디자인 토큰 변환

사용자의 원본 토큰과 소비 프로젝트를 먼저 확인한다. 원본이 DTCG라면 그 파일을 기준으로 파생 결과를 만든다. CSS만 있으면 역추출할 수 있지만, 값만으로 브랜드 출처나 의도를 복원했다고 주장하지 않는다. 3계층 파일, Tailwind, shadcn, 다크 모드는 해당 프로젝트에서 실제 사용하는 경우에만 만든다.

## 입력 확인

1. 원본 파일을 읽고 파일 경로·버전·토큰 이름·별칭·모드를 기록한다. `DESIGN.md`의 설명만으로 색 값을 새로 만들지 않는다.
2. 대상 프로젝트의 CSS, Tailwind 버전, shadcn 사용 여부와 기존 변수 이름을 확인한다. 이미 있는 변수 체계를 보존한다.
3. `$type`과 `$value`는 [DTCG Format Module 2025.10](https://www.designtokens.org/tr/2025.10/format/)에 맞춰 검증한다. 색은 `colorSpace`·`components`를 가진 객체, dimension은 숫자와 단위의 객체, shadow는 그림자 객체 또는 그 배열, gradient는 색·위치를 가진 스톱 배열이다. CSS의 `#hex`, `linear-gradient(...)`, `box-shadow` 문자열을 그대로 표준 DTCG 값이라고 표기하지 않는다.
4. 기존 파일이 다른 토큰 형식을 쓰면 그 형식을 명시하고 변환 가능한 값과 수동 결정이 필요한 값을 나눈다. `$description`은 선택 사항이며, 값의 출처를 자동 증명하지 않는다. 실제 확인한 출처는 별도 기록한다.

## 변환

- 원본 경로 → 출력 변수 이름의 대응표를 먼저 작성한다. 이름 충돌, 별칭 순환, 미지원 타입은 출력 전에 보고한다.
- DTCG 값에서 CSS 값을 만들 때 색 공간 변환·단위·알파·그라디언트 종류처럼 표현이 달라지는 항목은 변환 기준과 오차를 적는다. CSS에서 역추출할 때 잃은 정보는 `복원 불가`로 표시한다.
- 일반 CSS 소비처에는 필요한 custom property만 만든다. [Tailwind v4의 `@theme`](https://tailwindcss.com/docs/theme)은 유틸리티가 필요한 변수에만 사용하고, 다른 CSS 변수 참조가 필요할 때는 공식 문서의 `@theme inline` 동작을 따른다.
- shadcn을 쓰는 프로젝트에서는 [공식 테마 문서](https://ui.shadcn.com/docs/theming)의 현재 변수 계약과 프로젝트의 `components.json`을 대조한다. 보통 `--primary`와 `--primary-foreground`처럼 배경·전경 쌍을 만들며, Tailwind 매핑은 `--color-primary: var(--primary)` 형태다. `--base-*`나 상태색·차트 다섯 개를 임의의 필수 표준으로 만들지 않는다.
- 다크 모드가 있으면 프로젝트의 실제 선택자와 토큰을 사용한다. 밝기만 기계적으로 올리거나 임의 색상을 생성하지 않는다. 원본에 없는 모드는 미확정 상태로 남긴다.
- 폰트 파일은 라이선스·배포 경로가 확인된 경우에만 넣는다. 파일이 있다는 이유로 셀프 호스팅 코드를 자동 생성하지 않는다.

## 검증

1. JSON 파싱과 타입별 값 구조, 참조 대상과 순환 여부를 확인한다.
2. 생성 CSS를 실제 대상 빌드로 검사한다. 대상 빌드를 실행할 수 없으면 정적 검사만 했다고 적는다.
3. 대응표의 원본 토큰마다 출력 변수와 값을 대조한다. 역변환은 표현 가능한 하위 집합에만 왕복 검사를 하고, 손실 항목은 별도로 열거한다. `PASS`는 실제 비교 결과가 있을 때만 쓴다.
4. 배경·전경 쌍을 실제 모드별로 계산해 대비를 확인한다. 주색 위 글자를 흰색으로 고정하지 않는다.
5. 원본이 금지한 색·글꼴·표현이 있으면 변환 결과와 대조한다. 금지 규칙 자체를 창작하지 않는다.

## 보고

입력 경로와 확인한 형식, 생성한 파일, 변환한 토큰 수, 손실·충돌 목록, 실제 실행한 파서·빌드·대비 검사의 명령과 결과를 적는다. 확인하지 못한 플랫폼과 렌더 결과는 미검증으로 남긴다.