A token resolver is software that determines which values apply to design tokens for a given context, such as a light or dark theme. It can combine token sources in a defined order and follow references to determine the values a consuming tool should use.
What does a resolver do?
The DTCG Format Module defines token values and references. The separate Resolver Module defines how to select and combine sources for a context. For example, a resolver document can list a base set and then a theme modifier in resolutionOrder. The input selects a context such as dark for that modifier. Under the Resolver Module’s ordering rules, if selected sources declare the same token more than once, the last declaration wins.
A context choice and an alias answer different questions. The context selects which declaration of color.text.link applies. The alias points to the palette token whose value the link should use.
Example of resolving link text
Suppose Base defines both palette colors and a default link role. The theme modifier adds no sources for Light and adds one source, Dark, for Dark mode.
| Context | Sources applied in order | Winning reference for color.text.link |
|---|---|---|
| Light | Base | {color.blue.600} |
| Dark | Base, then Dark | {color.blue.300} |
The palette is present in both results because each context includes Base. After selecting the winning declaration, follow its reference to the corresponding color value. The component still uses the same link role.
What should you test?
- Source order. Confirm that Dark selects the override. If the value stays the same, check whether Base was applied after Dark.
- References. Check that the target exists in the final token set and that aliases do not form a cycle. For a missing target, start by checking which sources were selected.
- Consumer output. Verify the intended value in both contexts. A build tool can emit a literal or preserve the alias in a platform format that supports it.
Resolution determines what applies. Formatting determines how those decisions are represented, such as CSS custom properties. One tool can handle both jobs, or you can run a separate resolver before the platform build.