A composite design token represents one design decision with a value made up of several related properties. For example, a shadow can combine a color, two offsets, a blur radius, and a spread. A component can use the named shadow as one decision.
How is a composite token different from a group?
A group organizes separate tokens. In the DTCG format, a composite token declares one $value that contains the parts of a single decision. In a group named elevation, card and dialog could be two separate shadow tokens. Each of those tokens can carry its own set of shadow properties.
DTCG example of a shadow token
{
"elevation": {
"card": {
"$type": "shadow",
"$value": {
"color": { "colorSpace": "srgb", "components": [0, 0, 0], "alpha": 0.16 },
"offsetX": { "value": 0, "unit": "px" },
"offsetY": { "value": 2, "unit": "px" },
"blur": { "value": 8, "unit": "px" },
"spread": { "value": 0, "unit": "px" }
}
}
}
}
Here elevation is the group and elevation.card is the token path. This shadow uses the five required properties in a single value. The format also allows an optional inset flag. Use the fields supported by the token’s type. The DTCG Format Module defines each composite type and which properties may reference other tokens.
When should you use a composite token?
Use one when the properties belong together in the consuming interface. If several components need the same card shadow, one token gives them a shared way to request that shadow. If an offset also needs to be reused independently, define an offset token and reference it inside the shadow where the format and tools support that reference.
Check what each consumer expects. For the example above, a web build could produce 0 2px 8px 0 rgb(0 0 0 / 16%) for CSS box-shadow. Another platform may expect separate parameters. Verify the generated output and judge the rendered result in a real component before adopting the token across the library.