디자인 토큰 기반 UI 아키텍처 (Design Token-Based UI Architecture)

디자인 토큰 (Design tokens)은 데이터로서의 디자인 결정 사항이며, 디자인과 엔지니어링을 위한 단일 진실 공급원 (Single source of truth) 역할을 합니다. 배포 파이프라인 (Deployment pipelines)을 활용하여 플랫폼 전반에 걸친 자동화된 코드 생성을 가능하게 하며, 이를 통해 더 빠른 업데이트와 향상된 디자인 일관성을 제공합니다. 사용 가능한 옵션에서부터 해당 옵션이 어떻게 적용되는지를 포착하는 토큰으로 나아가는 계층 구조로 토큰을 구성하면, 확장성 (Scalability)과 더 나은 개발자 경험 (Developer experience)을 보장할 수 있습니다. 옵션 토큰 (예: 컬러 팔레트)을 비공개로 유지하면 파일 크기를 줄이고 중단 없는 변경 (Non-breaking changes)을 지원할 수 있습니다. 이러한 이점들 덕분에 디자인 토큰은 대규모 프로젝트, 멀티 플랫폼 환경 또는 빈번한 디자인 변경이 발생하는 조직에 특히 적합합니다.

2024년 12월 12일

디자인 토큰 (Design tokens), 또는 "토큰 (tokens)"은 데이터로 표현된 근본적인 디자인 결정 사항입니다. 이는 디자인 시스템 (Design systems)의 기초적인 빌딩 블록 (Building blocks)입니다.

2022년 디자인 토큰 사양 (Design token specification)의 두 번째 에디터 초안 (Editor’s draft)이 발표되고, 도구 제작자들에게 구현 및 피드백 제공을 요청한 이후로 디자인 토큰 도구의 환경은 급격히 발전했습니다. 코드 생성기 (Code generators), 문서화 시스템 (Documentation systems), UI 디자인 소프트웨어와 같은 도구들은 이제 디자인 토큰을 지원할 수 있는 더 나은 역량을 갖추게 되었으며, 이는 현대 UI 아키텍처 (UI architecture)에서 디자인 토큰의 중요성이 커지고 있음을 강조합니다.

이 글에서 저는 디자인 토큰이 무엇인지, 언제 유용한지, 그리고 어떻게 효과적으로 적용할 수 있는지 설명할 것입니다. 우리는 나중에 변경하기 어려운 주요 아키텍처 결정 사항들에 초점을 맞출 것이며, 여기에는 다음 내용이 포함됩니다:

• 확장성 (Scalability), 유지보수성 (Maintainability) 및 개발자 경험 (Developer experience)의 균형을 맞추기 위해 디자인 토큰을 계층 (Layers)으로 구성하는 방법.
• 모든 토큰을 제품 팀에 공개해야 하는지, 아니면 일부 하위 집합 (Subset)만 공개해야 하는지 여부.
• 팀 간의 토큰 배포 프로세스를 자동화하는 방법.

디자인 토큰의 역할 (Role of design tokens)

2017년경, 저는 개발 팀의 규모를 확장하기 위해 마이크로 프론트엔드 아키텍처 (Micro Frontend Architecture)를 사용하는 대규모 프로젝트에 참여했습니다. 이 설정에서 서로 다른 팀들은 사용자 인터페이스 (UI)의 각기 다른 부분들을 담당했으며, 이는 심지어 동일한 페이지 내에 있을 수도 있었습니다. 각 팀은 자신의 마이크로 프론트엔드를 독립적으로 배포할 수 있었습니다.

동일한 마이크로 프론트엔드에 속하지 않은 컴포넌트들이 서로 겹쳐서 표시되는 다양한 경우(예: 콘텐츠 영역 위에 나타나는 다이얼로그 (dialogs) 또는 토스트 (toasts))가 있었습니다. 팀들은 쌓임 순서 (stacking order)를 제어하기 위해 CSS 속성인 z-index를 사용했는데, 종종 문서화되거나 표준화되지 않은 임의의 값인 매직 넘버 (magic numbers)에 의존하곤 했습니다. 이러한 접근 방식은 프로젝트가 성장함에 따라 확장성을 갖추지 못했습니다. 이는 팀 간의 협업이 필요하게 만들어, 해결하는 데 많은 노력이 드는 문제들로 이어졌습니다.

이 문제는 결국 디자인 토큰 (design tokens)을 통해 해결되었으며, 저는 이것이 이 개념을 소개하기에 좋은 사례라고 생각합니다. 해당 토큰 파일은 다음과 유사한 형태였을 것입니다:

{ "z-index": { "$type": "number", "default": { "$value": 1 }, "sticky": { "$value": 100 }, "navigation": { "$value": 200 }, "spinner": { "$value": 300 }, "toast": { "$value": 400 }, "modal": { "$value": 500 } } }

위의 디자인 토큰은 애플리케이션에서 사용할 수 있는 z-index 값의 집합을 나타내며, 이름만으로도 개발자에게 어디에 사용해야 할지에 대한 명확한 아이디어를 제공합니다. 이와 같은 토큰 파일은 디자이너의 워크플로 (workflow)에 통합될 수 있으며, 각 팀이 요구하는 형식으로 코드를 생성하는 데에도 사용될 수 있습니다. 예를 들어, 이 사례의 경우 토큰 파일은 CSS 또는 SCSS 변수를 생성하는 데 사용되었을 것입니다:

css

:root { --z-index-default: 1; --z-index-sticky: 100; --z-index-navigation: 200; --z-index-spinner: 300; --z-index-toast: 400; --z-index-modal: 500; }

scss

$z-index-default: 1; $z-index-sticky: 100; $z-index-navigation: 200; $z-index-spinner: 300; $z-index-toast: 400; $z-index-modal: 500;

디자인 토큰이란 무엇인가요?

Salesforce는 원래 여러 플랫폼에 대한 디자인 업데이트를 간소화하기 위해 디자인 토큰 (Design Tokens)을 도입했습니다.

Design Tokens Community Group은 디자인 토큰을 "다양한 분야 (disciplines), 도구 (tools), 그리고 기술 (technologies) 간에 공유될 수 있도록, 플랫폼에 구애받지 않는 방식으로 디자인 결정을 표현하는 방법론"이라고 설명합니다.

이를 자세히 살펴보겠습니다:

분야 간 협업 (Cross-Disciplinary Collaboration): 디자인 토큰은 디자이너, 개발자, 제품 관리자(Product Manager) 및 기타 분야를 정렬하는 공통 언어 역할을 합니다. 디자인 결정에 대한 단일 진실 공급원 (Single Source of Truth)을 제공함으로써, 제품 수명 주기(Product Life Cycle)에 참여하는 모든 사람이 동일한 내용을 이해하도록 보장하며, 이는 더 효율적인 워크플로로 이어집니다.

도구 통합 (Tool integration): 디자인 토큰은 UI 디자인 소프트웨어, 토큰 에디터, 번역 도구 (코드 생성기), 그리고 문서화 시스템을 포함한 다양한 디자인 및 개발 도구에 통합될 수 있습니다. 이를 통해 디자인 업데이트가 코드 베이스 (Code Base)에 빠르게 반영되고 팀 간에 동기화될 수 있습니다.

기술 적응성 (Technology adaptability): 디자인 토큰은 웹을 위한 CSS, SASS, JavaScript와 같은 다양한 기술로 변환될 수 있으며, Android 및 iOS와 같은 네이티브 플랫폼에서도 사용될 수 있습니다. 이러한 유연성은 다양한 플랫폼과 기기 전반에 걸쳐 디자인 일관성을 가능하게 합니다.

단일 진실 공급원 (Single Source of Truth) 구축

디자인 토큰의 핵심적인 이점은 디자인 팀과 엔지니어링 팀 모두를 위한 단일 진실 공급원 (Single Source of Truth) 역할을 할 수 있다는 점입니다. 이는 여러 제품이나 서비스가 시각적 및 기능적 일관성을 유지하도록 보장합니다.

번역 도구 (Translation Tool)는 하나 이상의 디자인 토큰 파일을 입력값으로 받아 플랫폼별 코드를 출력값으로 생성합니다. 일부 번역 도구는 HTML 형식으로 디자인 토큰에 대한 문서도 생성할 수 있습니다. 이 글을 쓰는 시점을 기준으로, 인기 있는 번역 도구로는 Style Dictionary, Theo, Diez 또는 Specify App이 있습니다.

그림 1: 번역 도구 (Translation tool)

자동화된 디자인 토큰 배포

이 섹션에서는 디자인 토큰 (Design tokens)을 제품 팀에 배포하는 과정을 어떻게 자동화할 수 있는지 살펴보겠습니다.

디자이너가 변경 사항을 만든 직후, 팀들에게 업데이트된 기술 특화 디자인 토큰을 즉시 제공하는 것을 목표로 한다고 가정해 봅시다. 이를 달성하기 위해 디자인 토큰을 위한 배포 파이프라인 (Deployment pipeline)을 사용하여 번역 및 배포 프로세스를 자동화할 수 있습니다. 플랫폼별 코드 아티팩트 (Code artifacts, 예: 웹을 위한 CSS, Android를 위한 XML 등) 외에도, 파이프라인은 디자인 토큰에 대한 문서 (Documentation)를 배포할 수도 있습니다.

한 가지 중요한 요구 사항은 디자인 토큰을 버전 관리 (Version control) 하에 두는 것입니다. 다행히 Figma와 같은 인기 있는 디자인 도구용 플러그인들은 이미 GitHub와 같은 Git 제공업체와 통합되어 있습니다. 디자인 도구 자체가 아닌, Git 저장소 (Git repository)를 디자인 토큰의 단일 진실 공급원 (Single source of truth)으로 사용하는 것이 권장되는 모범 사례 (Best practice)입니다. 하지만 이를 위해서는 플러그인이 저장소와 디자인 도구 간의 양방향 동기화 (Two-way syncing)를 지원해야 하는데, 모든 플러그인이 이를 지원하는 것은 아닙니다. 현재로서는 Tokens Studio가 이러한 양방향 동기화를 제공하는 플러그인입니다. Tokens Studio를 다양한 Git 제공업체와 통합하는 방법에 대한 자세한 안내는 해당 문서(Documentation)를 참조하십시오. 이 도구를 사용하면 대상 브랜치 (Target branch)를 구성할 수 있으며, 트렁크 기반 (Trunk-based) 워크플로와 풀 리퀘스트 (Pull-request) 기반 워크플로를 모두 지원합니다.

토큰이 버전 관리 하에 놓이면, 플랫폼별 소스 코드와 문서를 포함하여 제품 팀에 필요한 아티팩트를 빌드하고 배포하기 위한 배포 파이프라인을 설정할 수 있습니다. 소스 코드는 일반적으로 라이브러리 (Library) 형태로 패키징되어 아티팩트 레지스트리 (Artifact registry)를 통해 배포됩니다. 이러한 접근 방식은 제품 팀이 업그레이드 주기 (Upgrade cycle)를 제어할 수 있게 해줍니다. 팀은 단순히 의존성 (Dependencies)을 업데이트함으로써 업데이트된 스타일을 채택할 수 있습니다. 이러한 업데이트는 토큰 기반 스타일을 사용하는 컴포넌트 라이브러리 (Component libraries)의 업데이트를 통해 간접적으로 적용될 수도 있습니다.

그림 2: 자동화된 디자인 토큰 배포 (Automated design token distribution)

이러한 전반적인 설정을 통해 Thoughtworks의 팀들은 여러 프론트엔드(front-ends)와 팀에 걸쳐 작은 디자인 변경 사항을 단 하루 만에 배포할 수 있게 되었습니다.

완전 자동화된 파이프라인 (Fully automated pipeline)

파이프라인을 설계하는 가장 직관적인 방법은 완전 자동화된 트렁크 기반 워크플로 (trunk-based workflow)입니다. 이 설정에서는 자동화된 품질 게이트 (quality gates)를 통과하기만 하면 메인 브랜치 (main branch)에 푸시된 모든 변경 사항이 즉시 배포됩니다.

이러한 파이프라인은 다음과 같은 작업 (jobs)들로 구성될 수 있습니다:

Check (검사): 디자인 토큰 검증기 (design token validator) 또는 JSON 검증기 (JSON validator)를 사용하여 디자인 토큰 파일을 검증합니다.

Build (빌드): Style Dictionary와 같은 변환 도구를 사용하여 디자인 토큰 파일을 플랫폼별 형식으로 변환합니다. 이 작업은 변환 도구를 사용하거나 전용 문서화 도구를 통합하여 문서 (docs)를 빌드할 수도 있습니다.

Test (테스트): 이 작업은 테스트 전략에 크게 의존합니다. 디자인 토큰 파일을 직접 사용하여 일부 테스트를 수행할 수 있지만 (예: 색상 대비 확인), 일반적인 접근 방식은 Storybook과 같은 문서화 도구를 사용하여 생성된 코드를 테스트하는 것입니다. Storybook은 시각적 회귀 테스트 (visual regression tests), 접근성 테스트 (accessibility tests), 상호작용 테스트 (interaction tests) 및 기타 테스트 유형에 대해 뛰어난 테스트 지원을 제공합니다.

Publish (배포): 업데이트된 토큰을 패키지 관리자 (예: npm)에 배포합니다. 릴리스 프로세스 (release process)와 버전 관리 (versioning)는 semantic-release와 같이 Conventional Commits를 기반으로 하는 패키지 배포 도구를 통해 완전히 자동화할 수 있습니다. semantic-release는 또한 여러 플랫폼에 패키지를 배포할 수 있도록 지원합니다. 배포 작업은 디자인 토큰에 대한 문서도 함께 배포할 수 있습니다.

Notify (알림): 이메일이나 채팅을 통해 팀에 새로운 토큰 버전을 알려 팀들이 의존성 (dependencies)을 업데이트할 수 있도록 합니다.

그림 3: 완전 자동화된 배포 파이프라인 (Fully automated deployment pipeline)

수동 승인이 포함된 파이프라인 (Pipeline including manual approval)

때로는 완전히 자동화된 품질 게이트 (quality gates)만으로는 충분하지 않을 수 있습니다. 게시 전 수동 검토 (manual review)가 필요한 경우, 일반적인 접근 방식은 최신 디자인 토큰 (design token)이 적용된 문서의 업데이트 버전을 프리뷰 환경 (preview environment, 임시 환경)에 배포하는 것입니다.

만약 Storybook과 같은 도구를 사용한다면, 이 프리뷰에는 디자인 토큰뿐만 아니라 애플리케이션에서 사용되는 컴포넌트 (components)와 통합된 모습까지 보여줄 수 있습니다.

승인 프로세스 (approval process)는 풀 리퀘스트 (pull-request) 워크플로우를 통해 구현할 수 있습니다. 또는 파이프라인 내에서 수동 승인 / 배포 단계로 구현할 수도 있습니다.

그림 4: 수동 승인이 포함된 배포 파이프라인 (Deployment pipeline with manual approval)

레이어별 토큰 구성 (Organizing tokens in layers)

앞서 논의한 바와 같이, 디자인 토큰 (design tokens)은 디자인 결정 사항을 데이터로 나타냅니다. 하지만 모든 결정이 동일한 세부 수준에서 이루어지는 것은 아닙니다. 대신, 이상적으로는 일반적인 디자인 결정이 더 구체적인 결정을 안내해야 합니다. 토큰(또는 디자인 결정)을 레이어 (layers)로 구성하면 디자이너가 적절한 추상화 수준에서 결정을 내릴 수 있어, 일관성 (consistency)과 확장성 (scalability)을 지원할 수 있습니다.

예를 들어, 새로운 컴포넌트가 생길 때마다 개별적인 색상을 선택하는 것은 실용적이지 않습니다. 대신, 기초적인 컬러 팔레트 (color palette)를 정의한 다음, 해당 색상들을 어떻게 그리고 어디에 적용할지 결정하는 것이 더 효율적입니다. 이러한 접근 방식은 일관된 룩앤필 (look and feel)을 유지하면서 결정의 횟수를 줄여줍니다.

디자인 토큰이 사용되는 디자인 결정에는 세 가지 핵심 유형이 있으며, 이들은 서로를 기반으로 쌓아 올려집니다.

무엇을 (What) 사용할 수 있는 디자인 옵션이 있는가?
어떻게 (How) 해당 스타일들이 사용자 인터페이스 (user interface) 전반에 적용되는가?
어디에 (Where) 해당 스타일들이 정확히 적용되는가 (어떤 컴포넌트에서)?

이 세 가지 유형의 토큰에는 다양한 명칭이 있습니다 (늘 그렇듯, 네이밍은 어려운 작업입니다). 이 글에서는 Samantha Gordashko가 제안한 용어인 옵션 토큰 (option tokens), 결정 토큰 (decision tokens), 컴포넌트 토큰 (component tokens)을 사용하겠습니다.

색상 예시를 사용하여 디자인 토큰이 위의 세 가지 질문에 어떻게 답할 수 있는지 살펴보겠습니다.

옵션 토큰 (Option tokens): 제공되는 디자인 옵션 정의하기

Option tokens (옵션 토큰, 또는 primitive tokens, base tokens, core tokens, foundation tokens, reference tokens라고도 함)는 애플리케이션에서 무엇을 (what) 스타일로 사용할 수 있는지를 정의합니다. 이들은 컬러 팔레트 (color palettes), 간격/크기 스케일 (spacing/sizing scales), 또는 글꼴 패밀리 (font families)와 같은 것들을 정의합니다. 이 토큰들이 모두 애플리케이션에서 반드시 사용되는 것은 아니지만, 합리적인 옵션들을 제시합니다.

우리의 예시를 사용하여, 각 색상마다 매우 밝은 색부터 채도가 높은 색까지 9개의 명도(shades)를 가진 컬러 팔레트가 있다고 가정해 보겠습니다. 아래에서는 블루 톤(blue tones)과 그레이 톤(grey tones)을 옵션 토큰 (option-tokens)으로 정의합니다:

{ "color": { "$type": "color", "options": { "blue-100": {"$value": "#e0f2ff"}, "blue-200": {"$value": "#cae8ff"}, "blue-300": {"$value": "#b5deff"}, "blue-400": {"$value": "#96cefd"}, "blue-500": {"$value": "#78bbfa"}, "blue-600": {"$value": "#59a7f6"}, "blue-700": {"$value": "#3892f3"}, "blue-800": {"$value": "#147af3"}, "blue-900": {"$value": "#0265dc"}, "grey-100": {"$value": "#f8f8f8"}, "grey-200": {"$value": "#e6e6e6"}, "grey-300": {"$value": "#d5d5d5"}, "grey-400": {"$value": "#b1b1b1"}, "grey-500": {"$value": "#909090"}, "grey-600": {"$value": "#6d6d6d"}, "grey-700": {"$value": "#464646"}, "grey-800": {"$value": "#222222"}, "grey-900": {"$value": "#000000"}, "white": {"$value": "#ffffff"} } } }