Design Tokens Format Module

Information associated with a name, at minimum a name/value pair.

Few examples:

• 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
• Metadata
• Description

Visual design creation and editing tools.

This includes:

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

Token translation tools are tools that translate token data from one format to another.

Few examples:

• Theo
• Style Dictionary
• Diez
• Specify

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.

Sets 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.

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 and it may not always be possible to configure web servers as needed, it is also acceptable to use the plain 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 that 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: “token value”

Name and value are both required.

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. Tools MAY use the description in various ways. For example:

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

The description property must be a plain JSON string, for example:

Declares the type of the token. See “Types” for more information.

The 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 may 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, export 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). 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. Export 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 export 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 “font”. 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 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 “cubic-bezier”. 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:

At first glance, groups and composite types 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 tokens whose value is made up of several sub-values following a predefined structure.
  • The values of different composite tokens that share the same type are guaranteed to have the same internal structure (unlike multiple groups, where there is no guarantee whatsoever of how their contents are structured). Tools can therefore check their validity and potentially apply specialized processing or presentation to composite tokens.
  • You can think of a composite type as something "inside" an individual token.

Just as with “normal” types for tokens, using a custom, composite type will allow tools to check that the values you use match the expected type. In our color pair example above, attempting to do the following would be invalid and tools should ignore the token and show an error to the user, since “Comic Sans MS” is not a valid color value.

Likewise, IDEs can offer appropriate auto-completions to users that manually author design token files.

Since composite types are user-defined, tools cannot provide specialized handling of them since they have no advanced knowledge of the type declarations. Here are some suggested strategies to get the most value out of user-defined composite types: