Copyright © 2025 the Contributors to the Design Tokens Resolver Module 2025.10 Specification, published by the Design Tokens Community Group under the W3C Community Final Specification Agreement (FSA). A human-readable summary is available.
이 명세서는 포맷을 확장하고 디자인 토큰을 여러 컨텍스트(예: “라이트 모드”와 “다크 모드” 색상 테마 등)에서 사용할 수 있는 방법을 설명합니다.
이 명세서는 Design Tokens Community Group에서 발행하였습니다. 이는 W3C 표준이 아니며, W3C 표준 트랙에도 속하지 않습니다. 또한, W3C 커뮤니티 최종 명세 협약(FSA)에 따라 추가 조건이 적용될 수 있습니다. W3C 커뮤니티 및 비즈니스 그룹에 대해 더 알아보세요.
이 절은 이 문서가 발행된 시점에서의 상태를 설명합니다. 이 문서는 이후의 다른 문서에 의해 대체될 수 있습니다. 현재의 W3C 커뮤니티 그룹 보고서와 이 보고서의 최신 개정본 목록은 https://www.w3.org/community/reports/에서 조회할 수 있습니다.
이 문서는 DTCG에서 Candidate Recommendation 으로 발행하였으며, W3C 프로세스에 따라 정의된 내용을 따릅니다. 이 초안에 대한 기여는 커뮤니티 기여자 라이선스 계약(CLA) 의 적용을 받으며, W3C 커뮤니티 그룹 프로세스에 명시된 조건을 따릅니다.
비록 W3C 권고는 아니지만, 이 분류는 충분한 합의 과정을 거친 후 이 명세가 구현을 위한 것임을 분명히 하기 위한 것입니다.
이 명세는 안정적인 것으로 간주됩니다. 향후 업데이트는 상위 명세에서 제공될 예정입니다.
본 명세에 대한 논의는 GitHub Issues에서 진행하는 것을 권장합니다.
이 절은 비규범적입니다.
디자인 토큰을 사용하는 소비자는 서로 다른 컨텍스트에서 적용되는 대체 값을 표현해야 하는 경우가 자주 있습니다. 다음은 그 예시이며 이에 국한되지 않습니다:
그러나 이러한 대체 컨텍스트는 조합 폭발에 취약하여 저장 및 관리가 번거로워질 수 있습니다.
이 포맷은 모든 컨텍스트 전반에 걸쳐 토큰의 반복 값을 중복 제거하고, 컨텍스트의 모든 순열을 열거하는 메커니즘을 설명합니다.
이 절은 비규범적입니다.
각각 상호 배타적인 토큰에서 작동하는 두 개 이상의 컨텍스트를 설명하는 특성으로, 즉 서로 겹치지 않습니다. 수정자는 MAY 직교일 수 있으나, 필수는 아닙니다.
가능한 한 수정자를 직교적으로 만드는 것은 인지 부하를 줄이고 사용자 오류를 감소시킵니다.
순열은 리졸버 문서의 가능한 단일 순열입니다. 순열은 input과 1:1로 매핑되지만, “input”은 사용된 modifier 컨텍스트를 강조하는 반면 “순열”은 최종 토큰 집합을 강조합니다.
리졸버 문서는 표준 JSON 구문([RFC8259])을 MUST 사용해야 합니다.
도구는 문서를 정상 JSON으로 변환해도 토큰 값에 영향을 주지 않는 한 JSONC 또는 JSON5와 같은 확장을 MAY 지원할 수 있습니다.
사용자는 리졸버 문서의 이름을 지정할 때 .resolver.json 파일 확장자를 SHOULD 사용해야 합니다.
HTTP를 통해 리졸버 문서를 전송할 때, 사용자는 Content-Type 헤더([RFC1341])에서
기대되는
application/json MIME 타입([RFC6838])을 SHOULD 사용해야 합니다.
사용자는 사용자 정의 또는 예상치 못한 MIME 타입을 SHOULD NOT 사용해야 합니다.
리졸버 문서는 최상위 레벨에서 다음 속성을 포함합니다:
| Name | Type | Required | Description |
|---|---|---|---|
| name | string |
문서에 대한 짧고 사람이 읽을 수 있는 이름. | |
| version | YYYY.MM |
Y | 버전. 2025.10이어야 합니다. |
| description | string |
이 문서에 대한 사람이 읽을 수 있는 설명. | |
| sets | Map[string, Set] |
세트의 정의. | |
| modifiers | Map[`string, Modifier] | 수정자의 정의. | |
| resolutionOrder | (ReferenceObject | Set | Modifier)[] |
Y | 세트와 수정자의 해상(적용) 순서. |
문서는 최상위 레벨에서 사람이 읽을 수 있는 name을 제공할 수 있습니다 MAY. 이는 파일명만으로 충분하지
않은 경우 하나의 리졸버 문서를 다른 문서와 구분하는 데 도움이 됩니다.
문서는 최상위 레벨에서 버전을 제공해야 하며 MUST, 이는 2025.10이어야 합니다 MUST. 이는 향후 변경 사항이 도입되어 파괴적 변경(breaking changes)이 발생하는 경우를 대비해 예약되어 있습니다.
문서는 최상위 레벨에서 description을 제공할 수 있습니다 MAY. 이는 name에 존재하지 않는 추가 설명이나 컨텍스트를 추가하는 데 사용될 수 있습니다.
세트는 DTCG 포맷의 디자인 토큰 모음입니다. 세트는 sources 배열을 포함해야 하며 MUST, 직접 선언된 토큰 또는 디자인 토큰을 포함한 JSON 파일을 가리키는 reference object, 또는 이 둘의 조합이어야 합니다.
세트는 세트의 목적을 설명하는 description을 포함할 수 있습니다 MAY.
배열이 여러 소스를 선언하는 경우, 배열 순서대로 병합되며, 동일 토큰이 여러 번 선언되면 배열의 마지막 항목이 최종 값이 됩니다. 도구는 배열 순서를 MUST 존중해야 합니다.
수정자는 set과 유사하지만, contexts 맵을 통해 조건부 포함을 허용합니다.
수정자는 string 값을 토큰 소스 배열에 매핑하는 contexts 맵을 선언해야 합니다 MUST.
토큰 소스 배열은 ReferenceObject, 인라인 토큰, 또는 이 둘의 조합이어야 합니다 MUST.
수정자는 두 개 이상의 contexts를 갖는 것이 바람직합니다 SHOULD. 하나만 있으면 set과 동일하므로, 수정자는 빈 contexts 맵을 가져서는 안 됩니다 MUST NOT. 도구는 컨텍스트가 1개뿐인 수정자에 대해 오류를 발생시키는 것이 바람직합니다 SHOULD. 컨텍스트가 0개인 수정자에 대해서는 도구가 오류를 발생시켜야 합니다 MUST.
sets와 마찬가지로, 배열 순서는 반드시 존중되어야 하며 MUST, 충돌 시 배열에서 토큰의 마지막 발생이 최종 값을 생성합니다.
수정자는 컨텍스트 값 내부에서 set을 참조할 수 있습니다 MAY. 그러나 수정자는 다른 수정자를 참조해서는 안 되며 MUST NOT, 동일 수정자 내의 다른 컨텍스트조차도 참조해서는 안 됩니다.
수정자는 사람이 읽을 수 있는 description을 선언할 수 있습니다 MAY.
수정자는 default 값을 선언할 수 있으며 MAY, 이는 contexts의 키
중 하나와 일치해야 합니다 MUST. 값이 contexts에 존재하지 않는 경우 도구는 오류를 발생시켜야
합니다 MUST.
문서가 생성할 수 있는 가능한 resolutions의 수는 모든 수정자에 걸친
contexts의 곱으로 예측할 수 있습니다.
resolutionOrder 키는 최종 토큰 결과를 생성하도록 순서가 지정된 sets 및 modifiers의 배열입니다. 순서는 중요하며, 충돌 시 배열 후반의 토큰이 이전의 토큰을 재정의합니다.
resolutionOrder에서, set 또는 modifier를
인라인으로 선언할 수 있으며 MAY, 단 객체에 name과
type 키를 추가해야 합니다:
| Property | Type | Required | Description |
|---|---|---|---|
| name | string |
Y | 고유한 이름으로, resolutionOrder 내의 다른 어떤 name과도
충돌해서는 안 됩니다 MUST NOT. |
| type | "set" | "modifier" |
Y | 해당 유형에 따라 "set" 또는
"modifier"여야 합니다 MUST.
|
도구는 인라인 객체에서 name 또는 type이 누락된 경우, 또는 name이 객체들 사이에서 중복된
경우 오류를 발생시켜야 합니다 MUST.
인라인 세트 및 수정자는 어떤 방식으로도 참조되어서는 안 됩니다 MUST NOT. 도구는 reference object가 해상도 순서 항목을 가리키는 경우 오류를 발생시키는 것이 바람직합니다 SHOULD.
이 절은 비규범적입니다.
resolutionOrder 배열은 사용자가 원하는 어떤 순서로든 세트와 수정자를 배치할 수 있습니다. 그러나 많은 세트가 충돌을 해결하기 위해 수정자
뒤에 나타나야 하는 시나리오에서는, 예측 불가능하고 취약한 토큰 구성의 냄새일 가능성이 높습니다. 이상적으로는 수정자가 조건부 값을 충분히 잘
처리하여 거의 또는 전혀 재정의가 필요하지 않아야 합니다(직교성 참조). 실무적으로 이는 다음을 의미합니다
다른 JSON 문서 또는 동일 문서 내 구조를 참조할 때는 참조 객체를 사용해야 합니다 MUST. 이는 JSON Schema 2020-12에서
$ref 키를 가지며 그 문자열이 [RFC6901]에 설명된 유효한 JSON 포인터인 객체로
설명됩니다.
도구는 리졸버 문서의 모든 참조 객체를 해석해야 합니다 MUST.
참조 객체는 순환되어서는 안 되며 MUST NOT, 자기 자신을 참조하는 다른 포인터를 참조하거나 참조 객체의 부모 노드를 참조해서는 안 됩니다.
도구는 동일 문서 참조 객체를 지원해야 하며 MUST, 이는 이 리졸버 모듈을 지원하기 위한 최소 요구사항입니다. 그 beyond로, 도구는 로컬 파일 시스템의 파일 가져오기나 TCP/IP를 통한 원격 URI 등 일부 URI 유형을 지원하지 않기로 개별적으로 결정할 수 있습니다.
포인터는 동일 문서 내 어디든 가리킬 수 있습니다 MAY, 다음 예외를 제외하고:
#/modifiers/…)를 참조할 수 있습니다.
세트와 수정자는 다른 수정자를 참조해서는 안 됩니다 MUST NOT.#/resolutionOrder/…)의 어떤
항목도 가리켜서는 안 됩니다 MUST NOT.
해상도 순서는 본질적으로 문서의 많은 다른 부분을 참조합니다. 이를 복제하는 것은 복잡하고 예측하기 어려운 연쇄를 생성합니다.도구는 어떤 잘못된 포인터를 만나더라도 오류를 발생시켜야 합니다 MUST.
JSON Schema 2020-12가 허용하듯,
다른 키가 $ref와 함께 참조 객체에 존재할 수 있습니다 MAY. 이러한 시나리오에서,
$ref와 함께 있는 로컬 키는 오버라이드로 처리되어야 합니다 MUST.
$ref와 함께 있는 키가 객체 또는 배열을 선언하는 경우, 도구는 이를 얕게 평탄화해야 하며 MUST, 즉
객체와 배열은 병합하지 않습니다.
$extensions 객체는 임의의 메타데이터를 선언하기 위해 어떤 set,
modifier, 또는 인라인 set/modifier에도 추가될 수
있습니다 MAY. 개별 도구가 이를 사용할지 무시할지 결정합니다.
제공되는 경우, $extensions는 벤더 별 네임스페이스를 키로 가지는 객체여야 합니다 MUST. 이는 여러 도구가
충돌 없이 이 메타데이터를 사용할 수 있게 합니다.
도구는 JSON Schema $defs에서
구조 정의를 허용할 수 있으나 MAY, 필수는 아닙니다. 다만, 도구는 $defs를 만나도 오류를 발생시키지 않아야
하며 MUST NOT, 지원하지 않는 경우 해당 키를 무시해야 합니다 MUST.
리졸버 문서는 조건부 토큰 값이 어떻게 생성될 수 있는지에 대해서만 설명합니다 MAY. 그러나 그 조건은 어딘가에서 제공되어야 합니다. “input”이라는 용어는 도구에 전달되는 컨텍스트 값들의 임의의 선택을 의미합니다.
도구는 입력값을 JSON 직렬화 가능한 객체로 받아들여야 합니다 MUST. 예: JavaScript의 object 또는 Python의 dictionary.
수정자를 선언하는 리졸버를 로드하는 도구는, 함께 제공되는 입력값이 없을 경우 오류를 발생시키는 것이 바람직합니다 SHOULD.
입력값은 대소문자를 구분하지 않는 것이 바람직합니다 SHOULD. 예를 들어,
{ "theme": "dark" }, { "Theme": "Dark" }, { "THEME": "DARK" }는
서로 동등해야 합니다 SHOULD. 다만, 도구는 대소문자 구분에 대해 개별적인 결정을 내릴 수 있습니다 MAY.
입력값의 값은 문자열이어야 합니다 MUST. 입력값에 { "beta": true } 또는
{ "size": 100 }처럼 비문자열 값이 포함된 경우 도구는 오류를 발생시켜야 합니다 MUST.
도구는 올바른 출력을 생성하기 위해 해상도 단계들을 처리해야 합니다 MUST.
resolutionOrder 배열을 추적.도구는 모든 inputs가 제공된 modifier 컨텍스트와 일치하도록 요구해야 합니다 MUST.
리졸버가 어떠한 수정자도 선언하지 않는 경우, 이 단계를 건너뛰고 정렬로 진행하십시오.
도구는 resolutionOrder 배열을 순서대로 반복 처리해야 합니다 MUST.
배열의 각 항목에 대해 그것이 set인지 modifier인지 판별하고, 배열 순서대로 단일 토큰 구조로 평탄화합니다.
sources를 결합하여 단일 토큰 구조를 생성합니다.context만 선택하여 배열 순서대로
결합해 단일 토큰 구조를 생성합니다.resolutionOrder 배열의 끝에 도달할 때까지 반복합니다.
최종 결과는 처음부터 하나의 소스였던 것처럼 동작하는 토큰 구조가 됩니다.
별칭은 이 단계 이전에 해결되어서는 안 됩니다 MUST NOT.
정렬이 단일 토큰 구조로 평탄화된 후, 남은 유일한 단계는 별칭을 해결하는 것입니다. 별칭은 format에 설명된 방식과 정확히 동일하게 해결됩니다:
$type을 가리켜야 합니다.이 절은 비규범적입니다.
리졸버 문서는 구성 목적을 위해 토큰을 여러 JSON 파일에 존재하도록 허용합니다. 그러나 이식성의 관점에서, 단일 JSON 문서만을 다루는 것이 유리할 수 있습니다.
“번들링(Bundling)”은 리졸버 문서를 단일 파일로 축약하는 과정을 의미합니다. 이를 달성하기 위한 전략은 여러 가지가 있으며, 이 문서가 설명하는 것보다 많습니다. 다만, 설명을 위해 가능한 접근 방식 중 2가지를 개괄합니다:
인라인은 원격 파일에 대한 모든 reference objects를 가져와 그 내용으로 대체하는 것을 포함합니다. 이는 최종 목표를 달성하는 간단한 전략이지만, 동일한 파일이 여러 번 참조될 때마다 중복이 발생합니다. 도구는 중복된 토큰에 문제 없을 수 있지만, 이 문서를 읽는 사람은 생성될 코드 라인의 수를 읽는 데 어려움을 겪을 수 있습니다.
$defs에 설명된 바와 같이, $defs는 리졸버 문서에서 정의된 동작이 없습니다. JSON Schema의 이 기능을 지원하도록
도구가 결정한 경우에만 사용할 수 있습니다.
이 전략은 최상위에 $defs 키를 생성하고, 각 최상위 키에 해당 파일의 내용을 포함시키는 것을 포함합니다.
$defs를 사용하는 유일한 단점은, 리졸버 문서의 최소 요구사항이 아니기 때문에 일부 도구는 이를 무시하기로 선택할 수 있다는 점입니다.
비규범적으로 표시된 절뿐만 아니라, 이 명세의 모든 작성 지침, 다이어그램, 예제 및 노트는 비규범적입니다. 그 외의 모든 내용은 규범적입니다.
이 문서의 키워드 MAY, MUST, MUST NOT, SHOULD, SHOULD NOT은 BCP 14 [RFC2119] [RFC8174] 에서 설명된 대로, 그리고 여기 표시된 것처럼 대문자로 나타날 때에만 해석되어야 합니다.
리졸버 명세를 구현하는 도구는 다음을 수행해야 합니다 MUST:
이 절은 비규범적입니다.
이 리졸버 명세는 Hyma 팀의 도움 없이는 이루어지지 않았습니다. Mike Kamminga, Andrew L’Homme, Lilith 등을 포함하되 이에 국한되지 않습니다. 또한 Joren Broekema, Louis Chenais의 중요한 기여가 있었습니다. 우리는 Design Tokens Community Group 구성원들의 기여와 피드백에 감사드립니다.