psd2json

PSD를 파싱한 내부 객체가 아니라, React에서 바로 배치하고 렌더링할 수 있는 스타일 데이터로 변환하는 방법을 실험했습니다.

Why I built it

PSD를 읽는 것과 브라우저에서 같은 의미로 다시 그리는 것은 다른 문제였습니다. 중첩 레이어, transform이 적용된 텍스트 좌표, Photoshop의 자간·행간과 효과를 웹의 좌표와 CSS로 다시 해석해야 했습니다.

psd2json은 PSD 전체 구조를 노출하는 대신 텍스트와 이미지 레이어를 value + React.CSSProperties 형태로 정규화하는 작은 출력 계약을 목표로 만든 TypeScript 라이브러리입니다.

How it works

ag-psd로 레이어 트리를 읽고 그룹을 재귀적으로 평탄화한 뒤, 텍스트와 이미지 레이어를 각각 변환합니다. text bounds와 transform matrix로 위치와 크기를 계산하고, tracking·leading·정렬·색상과 기본 스타일을 CSS 속성으로 옮깁니다.

opacity, blend mode, shadow, glow, stroke, gradient와 bevel도 브라우저에서 표현 가능한 값으로 변환합니다. 브라우저에서는 DOM canvas를 사용하고, Node.js에서는 initializePsd2JsonForNode로 외부 canvas 구현을 주입합니다.

Key decisions

• 숨김 레이어는 기본적으로 제외하고 includeHidden 옵션으로만 포함했습니다.
• 입력 buffer의 크기와 PSD signature를 먼저 검사하고, 문서 오류는 구조화된 PsdConversionError 코드로 반환했습니다.
• 지원하지 않거나 실패한 개별 레이어는 격리해 나머지 변환 결과를 유지했습니다.
• v1.1에서 percentage 옵션을 제거하고 위치와 크기를 px로 통일해 출력 좌표계를 단순화했습니다.
• 변환기, 오류 처리, 통합 흐름과 실제 PSD 파일을 자동 테스트로 확인했습니다.

Limits and learnings

이 라이브러리는 Photoshop의 모든 레이어와 합성 효과를 완전히 재현하지 않습니다. 지원 범위 안의 속성을 CSS에 근사해 옮기므로 원본과의 시각적 일치 정도는 문서 구성에 따라 달라질 수 있습니다.

작업의 핵심은 파일 파싱보다 의미 변환이었습니다. 공개 속성을 늘리는 것보다 소비자가 다시 해석하지 않아도 되는 출력 계약, 문서 전체 오류와 레이어별 부분 실패를 구분하는 정책이 변환 라이브러리의 사용성을 더 크게 좌우했습니다.