skip to content

In the Design Tokens Community Group format, when should typography, shadow or border values be one composite token rather than a group?

level: middleimportance: should knowfreq 40%

answer

  1. parts that always travel together
  2. a fixed structure versus a free container
  3. sub-values can still be references
  4. border: three parts; shadow: five plus one
  5. line height as a multiplier

basics

~20 s

Use a composite token when sub-values are always applied together as one style, such as a text style, shadow or border, so they cannot be mismatched; use a group when tokens are merely organised together and applied separately.

solid answer

~40 s

A **composite token** has a single type whose value is a predefined structure of typed sub-values: a `border` has `color`, `width` and `style`; a `shadow` has `color`, `offsetX`, `offsetY`, `blur`, `spread` and an optional `inset`, and may be an array of layers; a `typography` token has `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing` and `lineHeight`. A **group** imposes no structure and no type; it just organises. I reach for a composite when the parts form one decision that must be applied whole - a campaign headline style, a card's raised shadow - so nobody pairs this size with that weight. Each sub-value can still reference a simpler token, so the palette and size ladder stay reusable. I keep separate tokens when the parts are chosen independently in different places.

code

json · 14 lines
json
{
  "type": {
    "campaign-headline": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.family.display}",
        "fontSize": "{font.size.600}",
        "fontWeight": "{font.weight.bold}",
        "letterSpacing": { "value": 0, "unit": "px" },
        "lineHeight": 1.2
      }
    }
  }
}

go deeper

for a junior

Recall that a composite token bundles typed parts applied together, and name the parts of a border: color, width and style.

for a middle

Explain the fixed structure of typography, shadow and border, that sub-values may be references, and how that differs from an untyped group.

for a senior

Show the judgement of where to draw the composite boundary: parts that change independently stay separate, shared steps are referenced, not copied.

for a principal

Weigh atomic styles that prevent mismatches against the flexibility teams lose, and how that choice shapes what consuming platforms receive.

## Single values and composite values Most token types in the **Design Tokens Community Group format** hold one value: a color is one color, a dimension one size. Some design decisions are a bundle. A shadow is a color plus two offsets, a blur and a spread; a text style is a family, size, weight, letter spacing and line height. The format models these bundles as **composite types**: a token with one `$type` whose `$value` is an object (or array) with a **predefined structure**, where each part - a **sub-value** - has its own required type. ## The composite types most asked about | Type | Sub-values | Notes | |---|---|---| | `border` | `color`, `width`, `style` | `width` is a dimension; `style` is a stroke style such as `solid` or `dashed` | | `shadow` | `color`, `offsetX`, `offsetY`, `blur`, `spread`, optional `inset` | the value may be an array of shadow layers | | `typography` | `fontFamily`, `fontSize`, `fontWeight`, `letterSpacing`, `lineHeight` | `lineHeight` is a number, read as a multiplier of the font size | The draft also defines `strokeStyle`, `transition` and `gradient` as composite types. Every sub-value may be an explicit value **or a reference** to a token of the matching type, so a typography token can point its `fontSize` at a token on the size ladder and its `fontWeight` at a weight token. ## Groups versus composites They can look alike - both are objects with named children - but the draft stresses that they solve different problems: - A **group** is a container that sits outside tokens. It imposes no rules on how many children it has, what they are called or what types they hold, and tools are told not to read meaning into it. - A **composite token** is one token. Its structure is fixed by its type, and every part is validated against the type that part requires. ## When to choose a composite 1. **The parts are one decision.** A charity site's campaign headline style was designed as a whole; applying its size with a different weight produces a style nobody designed. 2. **Consumers should apply it atomically.** Handing a native team a `typography` token lets their generated text style carry all five parts at once, instead of five tokens they might wire up inconsistently. 3. **The parts are validated together.** A shadow missing its `blur` is caught as an invalid token, not discovered as a flat card on one platform. ## When separate tokens are better - **The parts vary independently.** If the border color of a gift-amount chip changes on selection while its width never does, the color is its own decision. - **Only part of the bundle is shared.** When many styles reuse a spacing or size step, keep that step as its own token and reference it from each composite. - **A platform applies the parts separately.** Some outputs need the parts one by one; composites can still be broken apart at build time, but the source should reflect how designers decide. ## A charity example An impact-story card on the donation site uses `card.shadow.raised`, a shadow composite with two layers - a tight contact shadow and a soft ambient one - whose colors reference the palette. The campaign page's headline uses `type.campaign-headline`, a typography composite whose `fontSize` and `fontWeight` reference ladder tokens and whose `lineHeight` is a number such as 1.2. The suggested-amount chips use `chip.border.default`, a border composite, while the selected chip's border color stays a separate color token because only that part changes. ## Pitfalls - Writing `lineHeight` as a dimension: the draft types it as a number interpreted as a multiplier of the font size, and says so explicitly. - Treating a group as a pseudo-composite: tools will not validate that all its parts exist. - Copying literal sub-values into every composite, so a palette change misses half of them; references avoid that. - Forgetting that the composite definitions carry open feedback issues in the draft, so details may still move.

  • In the Design Tokens Community Group format, how do you express a card shadow that has two layers?
    A `shadow` token's value may be an array. Each element is either an explicit shadow object with color, offsets, blur and spread, or a reference to another shadow token. References inside the array resolve to single shadow objects and are not flattened, so a raised card can combine a contact shadow and an ambient one.
  • Why does the Design Tokens Community Group typography type make lineHeight a number instead of a dimension?
    The draft reads it as a multiplier of the font size, so one value keeps working when the size changes or scales with the user's text setting. A fixed length would need retuning for every size. The draft itself flags this choice as open for feedback, so it is worth watching.

saying these in an interview costs you the question

  • A group of tokens and a composite token are interchangeable.
  • Composite sub-values must be literals, never references.
  • A border composite includes a corner radius.
  • Typography line height must be a dimension with a unit.
  • Every related pair of values should become a composite.