Design Tokens Format Module

A (Design) Token is an information associated with a name, at minimum a name/value pair.

For example:

• color-text-primary: #000000;
• font-size-heading-level-1: 44px;

The name may be associated with additional Token Properties.

Information associated with a token name.

For example:

• Value
• Type
• Description

Additional metadata may be added by tools and design systems to extend the format as needed.

A design tool is a tool for visual design creation and editing.

For example:

• Bitmap image manipulation programs:
  • Photoshop
  • Affinity Photo
  • Paint.net
• Vector graphics tools:
  • Illustrator
  • Inkscape
• UI design, wireframing and prototyping tools:
  • Adobe XD
  • UXPin
  • Sketch
  • Figma
  • ...

Design token translation tools translate token data from one format to another.

For example:

• Theo
• Style Dictionary
• Diez
• Specify
• ...

A documentation tool is a tool for documenting design tokens usage.

For example:

• Storybook
• Zeroheight
• Backlight
• Specify
• Supernova
• Knapsack
• ...

A token's type is a predefined categorization applied to the token's value.

For example:

• Color
• Size
• Duration

Token tools can use Types to infer the purpose of a token.

For example:

• A translation tool might reference a token's type to convert the source value into the correct platform-specific format.
• A visual design tool might reference type to present tokens in the appropriate part of their UI - as in, color tokens are listed in the color picker, font tokens in the text styling UI's fonts list, and so on.

A group is a set of tokens belonging to a specific category.

For example:

• Brand
• Alert
• Layout

Groups are arbitrary and tools SHOULD NOT use them to infer the type or purpose of design tokens.

A design token's value can be a reference to another token. The same value can have multiple names or aliases.

The following Sass example illustrates this concept:

$color-palette-black: #000000;
$color-text-primary: $color-palette-black;

The value of $color-text-primary is #000000, because $color-text-primary references $color-palette-black. We can also say $color-text-primary is an alias for $color-palette-black.

A design token whose value is made up of multiple, named child values. Composite tokens are useful for closely related style properties that are always applied together. For example, a typography style might be made up of a font name, font size, line height, and color.

Here's an example of a composite shadow token:

{
  "shadow-token": {
    "$type": "shadow",
    "$value": {
      "color": "#00000080",
      "offsetX": "0.5rem",
      "offsetY": "0.5rem",
      "blur": "1.5rem",
      "spread": "0rem"
    }
  }
}

When serving design token files via HTTP / HTTPS or in any other scenario where a media type (formerly known as MIME type) needs to be specified, the following MIME type SHOULD be used for design token files:

• application/design-tokens+json

However, since every design token file is a valid JSON file, they MAY be served using the JSON media type: application/json. The above, more specific media type is preferred and SHOULD be used wherever possible.

Tools that can open design token files MUST support both media types.

When saving design token files on a local file system, it can be useful to have a distinct file extension as this makes them easier to spot in file browsers. It may also help to associate a file icon and a preferred application for opening those files. The following file extensions are recommended by this spec:

• .tokens
• .tokens.json

The former is more succinct. However, until this format is widely adopted and supported, the latter might be useful to make design token files open in users' preferred JSON editors.

Tools that can open design token files MAY filter available files (e.g. in an open file dialog) to only show ones using those extensions. It is recommended to also provide users with a way of opening files that do not use those extensions (e.g. a "show all files" option or similar).

Tools that can save design token files SHOULD append one of the recommended file extensions to the filename when saving.

An object with a $value property is a token. Thus, $value is a reserved word in our spec, meaning you can't have a token whose name is "$value". The parent object's key is the token name.

The example above therefore defines 1 design token with the following properties:

• Name: "token name"
• Value: "#fff000"
• Type: "color"

Name and value are both required.

Token names are case-sensitive, so the following example with 2 tokens in the same group whose names only differ in case is valid:

However, some tools MAY need to transform names when exporting to other languages or displaying names to the user, so having token names that differ only in case is likely to cause identical and undesirable duplicates in the output. For example, a translation tool that converts these tokens to Sass code would generate problematic output like this:

Tools MAY display a warning when token names differ only by case.

While $value is the only required property for a token, a number of additional properties MAY be added:

A plain text description explaining the token's purpose can be provided via the optional $description property. Tools MAY use the description in various ways.

For example:

• Style guide generators MAY display the description text alongside a visual preview of the token
• IDEs MAY display the description as a tooltip for auto-completion (similar to how API docs are displayed)
• Design tools MAY display the description as a tooltip or alongside tokens wherever they can be selected
• Translation tools MAY render the description to a source code comment alongside the variable or constant they export.

The value of the $description property MUST be a plain JSON string, for example:

Design tokens always have an unambiguous type, so that tools can reliably interpret their value.

A token's type can be specified by the optional $type property. If the $type property is not set on a token, then the token's type MUST be determined as follows:

• If the token's value is a reference, then its type is the resolved type of the token being referenced.
• Otherwise, if any of the token's parent groups have a $type property, then the token's type is inherited from the closest parent group with a $type property.
• Otherwise, if none of the parent groups have a $type property, the token's type cannot be determined and the token MUST be considered invalid.

Tools MUST NOT attempt to guess the type of a token by inspecting the contents of its value.

The $type property can be set on different levels:

• at the group level
• at the token level

The $type property MUST be a plain JSON string, whose value is one of the values specified in this specification's respective type definitions. The value of $type is case-sensitive.

For example:

The optional $extensions property is an object where tools MAY add proprietary, user-, team- or vendor-specific data to a design token. When doing so, each tool MUST use a vendor-specific key whose value MAY be any valid JSON data.

• The keys SHOULD be chosen such that they avoid the likelihood of a naming clash with another vendor's data. The reverse domain name notation is recommended for this purpose.
• Tools that process design token files MUST preserve any extension data they do not themselves understand. For example, if a design token contains extension data from tool A and the file containing that data is opened by tool B, then tool B MUST include the original tool A extension data whenever it saves a new design token file containing that token.

In order to maintain interoperability between tools that support this format, teams and tools SHOULD restrict their usage of extension data to optional meta-data that is not crucial to understanding that token's value.

Tool vendors are encouraged to publicly share specifications of their extension data wherever possible. That way other tools can add support for them without needing to reverse engineer the extension data. Popular extensions could also be incorporated as standardized features in future revisions of this specification.

Represents a 24bit RGB or 24+8bit RGBA color in the sRGB color space. The $type property MUST be set to the string color. The value MUST be a string containing a hex triplet/quartet including the preceding # character. To support other color spaces, such as HSL, translation tools SHOULD convert color tokens to the equivalent value as needed.

For example, initially the color tokens MAY be defined as such:

Then, the output from a tool's conversion to HSL(A) MAY look something like:

Represents an amount of distance in a single dimension in the UI, such as a position, width, height, radius, or thickness. The $type property MUST be set to the string dimension. The value must be a string containing a number (either integer or floating-point) followed by either a "px" or "rem" unit (future spec iterations may add support for additional units). This includes 0 which also MUST be followed by either a "px" or "rem" unit.

For example:

The "px" and "rem" units are to be interpreted the same way they are in CSS:

• px: Represents an idealized pixel on the viewport. The equivalent in Android is dp and iOS is pt. Translation tools SHOULD therefore convert to these or other equivalent units as needed.
• rem: Represents a multiple of the system's default font size (which MAY be configurable by the user). 1rem is 100% of the default font size. The equivalent of 1rem on Android is 16sp. Not all platforms have an equivalent to rem, so translation tools MAY need to do a lossy conversion to a fixed px size by assuming a default font size (usually 16px) for such platforms.

Represents a font name or an array of font names (ordered from most to least preferred). The $type property MUST be set to the string fontFamily. The value MUST either be a string value containing a single font name or an array of strings, each being a single font name.

For example:

Represents a font weight. The $type property MUST be set to the string fontWeight. The value must either be a number value in the range [1, 1000] or one of the pre-defined string values defined in the table below.

Lower numbers represent lighter weights, and higher numbers represent thicker weights, as per the OpenType wght tag specification. The pre-defined string values are aliases for specific numeric values. For example 100, "thin" and "hairline" are all the exact same value.

Number values outside of the [1, 1000] range and any other string values, including ones that differ only in case, are invalid and MUST be rejected by tools.

Example:

Represents the length of time in milliseconds an animation or animation cycle takes to complete, such as 200 milliseconds. The $type property MUST be set to the string duration. The value MUST be a string containing a number (either integer or floating-point) followed by an "ms" unit. A millisecond is a unit of time equal to one thousandth of a second.

For example:

Represents how the value of an animated property progresses towards completion over the duration of an animation, effectively creating visual effects such as acceleration, deceleration, and bounce. The $type property MUST be set to the string cubicBezier. The value MUST be an array containing four numbers. These numbers represent two points (P1, P2) with one x coordinate and one y coordinate each [P1x, P1y, P2x, P2y]. The y coordinates of P1 and P2 can be any real number in the range [-∞, ∞], but the x coordinates are restricted to the range [0, 1].

For example:

Represents a number. Numbers can be positive, negative and have fractions. Example uses for number tokens are gradient stop positions or unitless line heights. The $type property MUST be set to the string number. The value MUST be a JSON number value.

At first glance, groups and composite tokens might look very similar. However, they are intended to solve different problems and therefore have some important differences:

• Groups are for arbitrarily grouping tokens for the purposes of naming and/or organization.
  • They impose no rules or restrictions on how many tokens or nested groups you put within them, what they are called, or what the types of the tokens within should be. As such, tools MUST NOT try to infer any special meaning or typing of tokens based on a group they happen to be in.
  • Different design systems are likely to group their tokens differently.
  • You can think of groups as containers that exist "outside" of design tokens.
• Composite tokens are individual design tokens whose values are made up of several sub-values.
  • Since they are design tokens, they can be referenced by other design tokens. This is not true for groups.
  • Their type must be one of the composite types defined in this specification. Therefore their names and types of their sub-values are pre-defined. Adding additional sub-values or setting values that don't have the correct type make the composite token invalid.
  • Tools MAY provide specialised functionality for composite tokens. For example, a design tool may let the user pick from a list of all available shadow tokens when applying a drop shadow effect to an element.

Represents the style applied to lines or borders. The $type property MUST be set to the string strokeStyle. The value MUST be either:

• a string value as defined in the corresponding section below, or
• an object value as defined in the corresponding section below

Represents a border style. The $type property MUST be set to the string border. The value MUST be an object with the following properties:

• color: The color of the border. The value of this property MUST be a valid color value or a reference to a color token.
• width: The width or thickness of the border. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• style: The border's style. The value of this property MUST be a valid stroke style value or a reference to a stroke style token.

Represents a animated transition between two states. The $type property MUST be set to the string transition. The value MUST be an object with the following properties:

• duration: The duration of the transition. The value of this property MUST be a valid duration value or a reference to a duration token.
• delay: The time to wait before the transition begins. The value of this property MUST be a valid duration value or a reference to a duration token.
• timingFunction: The timing function of the transition. The value of this property MUST be a valid cubic bézier value or a reference to a cubic bézier token.

Represents a shadow style. The $type property MUST be set to the string shadow. The value must be an object with the following properties:

• color: The color of the shadow. The value of this property MUST be a valid color value or a reference to a color token.
• offsetX: The horizontal offset that shadow has from the element it is applied to. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• offsetY: The vertical offset that shadow has from the element it is applied to. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• blur: The blur radius that is applied to the shadow. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• spread: The amount by which to expand or contract the shadow. The value of this property MUST be a valid dimension value or a reference to a dimension token.

Represents a color gradient. The $type property MUST be set to the string gradient. The value MUST be an array of objects representing gradient stops that have the following structure:

• color: The color value at the stop's position on the gradient. The value of this property MUST be a valid color value or a reference to a color token.
• position: The position of the stop along the gradient's axis. The value of this property MUST be a valid number value or reference to a number token. The number values must be in the range [0, 1], where 0 represents the start position of the gradient's axis and 1 the end position. If a number value outside of that range is given, it MUST be considered as if it were clamped to the range [0, 1]. For example, a value of 42 should be treated as if it were 1, i.e. the end position of the gradient axis. Similarly, a value of -99 should be treated as if it were 0, i.e. the start position of the gradient axis.

If there are no stops at the very beginning or end of the gradient axis (i.e. with position 0 or 1, respectively), then the color from the stop closest to each end should be extended to that end of the axis.

Represents a typographic style. The $type property MUST be set to the string typography. The value MUST be an object with the following properties:

• fontFamily: The typography's font. The value of this property MUST be a valid font family value or a reference to a font family token.
• fontSize: The size of the typography. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• fontWeight: The weight of the typography. The value of this property MUST be a valid font weight or a reference to a font weight token.
• letterSpacing: The horizontal spacing between characters. The value of this property MUST be a valid dimension value or a reference to a dimension token.
• lineHeight: The vertical spacing between lines of typography. The value of this property MUST be a valid number value or a reference to a number token. The number SHOULD be interpreted as a multiplier of the fontSize.