skip to content

In the Design Tokens Community Group format, what do $value, $type and $description hold, and what makes an object a token rather than a group?

level: juniorimportance: must knowfreq 48%

answer

  1. plain JSON, keys are names
  2. one property decides token or group
  3. the value's shape depends on its type
  4. type can sit on an enclosing group
  5. dollar prefix marks format properties

basics

~20 s

In the Design Tokens Community Group format any JSON object with a $value is a token and any object without one is a group; $value holds the value, $type declares its kind, and $description explains its purpose in plain text.

solid answer

~50 s

The format is plain JSON. Each object's key is its name. An object that carries `$value` is a **token**; an object without `$value` is a **group** that nests tokens or further groups, and an object with both a value and children is an error. `$value` holds the value in the shape its type requires - a color is an object with `colorSpace` and `components`, a dimension is an object with a numeric `value` and a `unit`, either an idealised pixel or a multiple of the default text size. `$type` names the kind of value, such as `color`, `dimension`, `duration` or `typography`, and can be set on the token or on an enclosing group. `$description` is an optional plain string stating the token's purpose, which documentation and code generators can surface. Every format property starts with `$`, which is why a token or group name may not.

code

json · 13 lines
json
{
  "donate": {
    "action-fill": {
      "$type": "color",
      "$value": { "colorSpace": "srgb", "components": [0.05, 0.45, 0.35] },
      "$description": "Background of the primary donate action on every platform"
    },
    "amount-gap": {
      "$type": "dimension",
      "$value": { "value": 12, "unit": "px" }
    }
  }
}

go deeper

for a junior

Recall the one rule: an object with $value is a token, one without it is a group. Know what $value, $type and $description each hold.

for a middle

Explain why value shapes are typed objects, such as a dimension with value and unit, and what the optional $deprecated and $extensions properties carry.

for a senior

Show how the file behaves as a contract between tools: preserved extensions, a pinned draft version, and validation that rejects mixed token-group objects.

for a principal

Weigh adopting a still-evolving community draft against a home-grown format: interoperability and tool choice versus exposure to changes in the draft.

## Why a tool-agnostic file exists A **design token** is a named design decision - a color, a spacing size, a duration - shared by a web front end, native mobile apps and the design editor. Each tool that handles tokens used to have its own export shape, so teams wrote glue code between them and paid again whenever they changed tools. The **Design Tokens Community Group format** defines one JSON file shape for exchanging tokens between tools. It is a Community Group draft, not a W3C Standard, and its details are still moving, so a team should pin the version its tooling supports. ## Tokens and groups The whole file is nested JSON objects, and one rule sorts them: - An object **with** a `$value` property is a **token**. Its key is the token's name. - An object **without** `$value` is a **group**. Groups organise tokens and may contain tokens, other groups and group-level properties such as `$type` or `$description`. - An object that has `$value` **and** child tokens or groups is invalid, and tools must report it: nothing can be both a token and a group. Because every property the format defines starts with `$`, token and group names must not begin with that character. ## The token properties | Property | Required | Holds | |---|---|---| | `$value` | yes | the value, shaped according to the type, or a reference to another token | | `$type` | no, if it can be resolved another way | the kind of value: `color`, `dimension`, `fontFamily`, `fontWeight`, `duration`, `cubicBezier`, `number`, or a composite such as `typography`, `shadow`, `border` | | `$description` | no | a plain string explaining the token's purpose | | `$deprecated` | no | `true`, or a string explaining the deprecation; `false` can override a group default | | `$extensions` | no | tool- or team-specific data under vendor-style keys | Two rules on these deserve emphasis: 1. `$type` may be omitted on a token only if the type can be resolved from a referenced token or from an enclosing group's `$type`; otherwise the token is invalid. 2. Tools must **preserve** `$extensions` data they do not understand when they save the file, so one tool's metadata survives a round trip through another. ## Value shapes by type The type fixes what `$value` must look like, which is what lets any tool read it without guessing: - **Color** - an object with a `colorSpace` and `components`, plus optional fields such as `alpha`; the full color model sits in a separate Color module of the draft. - **Dimension** - an object with a numeric `value` and a `unit` of `px` or `rem`; the unit is required even when the value is zero. - **Duration** - an object with a numeric `value` and a unit of milliseconds or seconds. - **Font weight** - a number from 1 to 1000 or one of the named aliases such as `thin` or `bold`. - **Number** - a plain JSON number, used for things like unitless line heights. ## A charity example A charity's donation site might keep a group `donate` holding the tokens for its giving flow: the fill of the donate action, the gap between suggested gift amounts, the duration of the progress bar's fill animation. Each is an object with `$value` and a type, and the fill carries a `$description` such as 'Background of the primary donate action on every platform'. A designer reading the file in a documentation tool and an engineer reading generated constants see the same purpose statement. ## Common mistakes - Treating the format as a loose key-value file and writing a dimension as a bare number: without a unit, a native app cannot tell whether 16 means an idealised pixel or a multiple of the text size. - Nesting child tokens under an object that also has `$value`, expecting it to act as both a default and a group. - Stripping unknown `$extensions` when a script rewrites the file, silently deleting another tool's data. - Treating the draft as final and depending on details that may still change.

  • In the Design Tokens Community Group format, why is a dimension value an object with a unit instead of a bare number?
    Because platforms interpret sizes differently. The draft allows two units: an idealised pixel, which native platforms map to their own density-independent units, and a multiple of the user's default text size. A bare number would force every translation tool to guess which was meant; the unit is required even for zero.
  • What should a script that rewrites a Design Tokens Community Group file do with $extensions entries it does not recognise?
    Keep them. The format requires tools to preserve extension data they do not understand when saving, so metadata written by one tool survives a pass through another. A script that drops unknown keys breaks that promise and can silently delete information another team depends on.

saying these in an interview costs you the question

  • Any object at the deepest nesting level counts as a token.
  • Every token must carry its own $type, even inside a typed group.
  • A dimension can be written as a bare number without a unit.
  • Tools may drop $extensions entries they do not understand.
  • The format is a finished W3C Standard.