Design Tokens Format Module

Draft Community Group Report

Editors:
Daniel Banks
Donna Vitan
James Nash
Kevin Powell
Louis Chenais
Participate:
GitHub design-tokens/community-group
File an issue
Commit history
Pull requests

Abstract

This document describes the technical specification for a file format to exchange design tokens between different tools.

Status of This Document

This specification was published by the Design Tokens Community Group. It is not a W3C Standard nor is it on the W3C Standards Track. Please note that under the W3C Community Contributor License Agreement (CLA) there is a limited opt-out and other conditions apply. Learn more about W3C Community and Business Groups.

This is a snapshot of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C or the Design Tokens W3C Community Group Membership. Don’t cite this document other than as work in progress.

This document has been published to facilitate Wide Review.

This document was produced by the Design Tokens W3C Community Group, and contributions to this draft are governed by Community Contributor License Agreement (CLA), as specified by the W3C Community Group Process.

GitHub Issues are preferred for discussion of this specification.

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words MAY, MUST, MUST NOT, SHOULD, and SHOULD NOT in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here.

2. Introduction

This section is non normative

Design tokens are a methodology for expressing design decisions in a platform-agnostic way so that they can be shared across different disciplines, tools, and technologies. They help establish a common vocabulary across organisations.

There is a growing ecosystem of tools for design system maintainers and consumers that incorporate design token functionality, or would benefit from doing so:

It is often desirable for design system teams to integrate such tools together, so that design token data can flow between design and development tools. For example:

While many tools now offer APIs to access design tokens or the ability to export design tokens as a file, these are all tool-specific. The burden is therefore on design system teams to create and maintain their own, bespoke "glue" code or workflows. Furthermore, if teams want to migrate to different tools, they will need to update those integrations.

This specification aims to facilitate better interoperability between tools and thus lower the work design system teams need to do to integrate them by defining a standard file format for expressing design token data.

3. Terminology

These definitions are focused on the technical aspects of the specification, aimed at implementers such as design tools vendors. Definitions for designers and developers are available at designtokens.org.

3.1 (Design) Token

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

Few examples:

The name may be associated with additional Token Properties.

3.2 (Design) Token Properties

Information associated with a token name.

For example:

3.3 Design tool

Visual design creation and editing tools.

This includes:

3.4 Translation tool

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

Few examples:

3.5 Type

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

For example:

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

For example:

3.6 Groups

Sets of tokens belonging to a specific category. For example:

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

3.7 Alias (Reference)

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.

3.8 Composite (Design) Token

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.

4. File format

Design token files are JSON (https://www.json.org/) files that adhere to the structure described in this specification.

JSON was chosen as an interchange format on the basis of:

4.1 Media type (MIME type)

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:

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.

4.2 File extensions

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:

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.

Editor's note: JSON schema

The group is currently exploring the addition of a JSON Schema to support the spec.

Editor's note: JSON file size limitations

A concern about file size limitations of JSON files was raised by one of the vendors. The working group continues to gather feedback about any limitations the JSON format imposes.

5. Design token

5.1 Name and value

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 and value are both required.

5.1.1 Token value type

Token values may be any valid JSON type:

  • string
  • number
  • array
  • object
  • boolean
  • null

Additionally, tokens may be defined with a more specific Token Type

Issue 55: Object vs Array Format Issue

The structure in the example above is a JSON object, an unordered set of name/value pairs.

  • Objects can't contain members with duplicate keys
  • Ordering of object members may not be preserved (as per RFC 7159), meaning token retrieval may or may not result in the same ordering as the input

Please raise concerns if these limitations create problems for implementers.

Issue 59: Token name case sensitivity Format Issue
Should token names be case sensitive?
Issue 60: Unicode range restriction Format Issue
Should the specification restrict the name property to a specific Unicode range or make certain characters invalid at the start/middle/end of a name (such as white space, line breaks…)? If so, what characters and why?
Issue 61: Reserved words Format Issue
Are there any reserved words that should not be allowed in token names?

5.2 Additional properties

While “value” is the only required property for a token, a number of additional properties may be added:

5.3 Description

A plain text description explaining the token’s purpose. Tools MAY use the description in various ways. For example:

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

Issue 62: Token descriptions optional or required Format Issue
Are token descriptions optional or required?

5.4 Type

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

Issue 63: Token types optional or required Format Issue
Are token types optional or required?

5.5 Extensions

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.

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.

Editor's note: Extensions section

The extensions section is not limited to vendors. All token users can add additional data in this section for their own purposes.

5.6 More token properties TBC

6. Groups

A file may contain many tokens and they may be nested arbitrarily in groups like so:

The names of the groups leading to a given token (including that token’s name) are that token’s path, which is a computed property. It is not specified in the file, but parsers that conform to this spec must be able to expose the path of a token. The above example, therefore, defines 4 design tokens with the following properties:

Because groupings are arbitrary, tools MUST NOT use them to infer the type or purpose of design tokens.

Editor's note: Naming practices

The format editors acknowledge existing best-practices for token naming, but place no direct constraints on naming via the specification.

6.1 Additional group properties

6.1.1 Description

Groups may include an optional description property. For example:

Suggested ways tools may use this property are:

  • A style guide generator could render a section for each group and use the description as an introductory paragraph
  • A GUI tool that lets users browse or select tokens could display this info alongside the corresponding group or as a tooltip
  • Export tools could output this as a source code comment
Issue 72: Group & file level properties Format Issue

Groups may support additional properties like type and description. Should other properties be supported at the group level?

6.2 Use-cases

6.2.1 File authoring & organization

Groups let token file authors better organize their token files. Related tokens can be nested into groups to align with the team’s naming conventions and/or mental model. When manually authoring files, using groups is also less verbose than a flat list of tokens with repeating prefixes.

For example:

...is likely to be more convenient to type and, arguably, easier to read, than:

6.2.2 GUI tools

Tools that let users pick or edit tokens via a GUI may use the grouping structure to display a suitable form of progressive disclosure, such as a collapsible tree view.

Progressive disclosure groups

6.2.3 Export tools

Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, export tools may need to export design tokens in a uniquely identifiable way, such as variables in code. Export tools should therefore use design tokens' paths as these are unique within a file.

For example, a translation tool like Style Dictionary might use the following design token file:

...and output it as Sass variables like so by concatenating the path to create variable names:

7. Aliases / references

Instead of having explicit values, tokens can reference the value of another token. To put it another way, a token can be an alias for another token. This spec considers the terms "alias" and "reference" to be synonyms and uses them interchangeably.

Aliases are useful for:

For a design token to reference another, its value should be a string containing the period-separated (.) path to the token it’s referencing enclosed in curly brackets. For example:

When a tool needs the actual value of a token it must resolve the reference - i.e. lookup the token being referenced and fetch its value. In the above example, the "alias name" token’s value would resolve to 1234 because it references the token whose path is {group name.token name} which has the value 1234.

Tools should preserve references and therefore only resolve them whenever the actual value needs to be retrieved. For instance, in a design tool, changes to the value of a token being referenced by aliases should be reflected wherever those aliases are being used.

Aliases may reference other aliases. In this case, tools should follow each reference until they find a token with an explicit value. Circular references are not allowed. If a design token file contains circular references, then the value of all tokens in that chain is unknown and an appropriate error or warning message should be displayed to the user.

Editor's note: JSON Pointer syntax

The format editors are currently researching JSON Pointer syntax to inform the exact syntax for aliases in tokens. https://datatracker.ietf.org/doc/html/rfc6901#section-5

8. Types

Many tools need to know what kind of value a given token represents in order to process it sensibly. Export tools may need to convert or format tokens differently depending on their type. Design tools may present the user with different kinds of input when editing tokens of a certain type (such as color picker, slider, text input, etc.). Style guide generators may use different kinds of previews for different types of tokens. Since design token files are JSON files, all the basic JSON types are available:

Additionally, this spec defines a number of more design-focused types. To set a token to one of these types, it MUST have a type property specifying the chosen type. Furthermore, that token’s value must then follow rules and syntax for the chosen type as defined by this spec.

If the type property is absent, tools MUST treat values as one of the basic JSON types and not attempt to infer any other type from the value.

If a type is set, but the value does not match the expected syntax then that token is invalid and an appropriate error should be displayed to the user. To put it another way, the type property is a declaration of what kind of values are permissible for the token. (This is similar to typing in programming languages like Java or TypeScript, where a value not compatible with the declared type causes a compilation error).

8.1 Color

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:

8.2 Dimension

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:

8.3 Font name

Issue 53: Type: font name Format Issue

A naive approach like the one below may be appropriate for the first stage of the specification, but this may be more complicated than it seems due to platform/OS/browser restrictions.

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:

8.4 Duration

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:

8.5 Cubic Bézier

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:

8.6 Additional types

Editor's note: Additional types
Types still to be documented here are likely to include:
  • Font weight: might be something like an enum of allowed values ("bold", "normal" etc.) and/or numeric values 0-1000 (like.in variable fonts)
  • Font style: might be an enum of allowed values like ("normal", "italic"...)
  • Border style/stroke style: maybe an enum (solid, dashed, dotted, etc.) and/or a way to specify dash & gap lengths?
  • Duration: a time duration, in seconds or milliseconds, e.g. for animations, delays, etc.
  • Percentage/ratio: e.g. for opacity values, relative dimensions, aspect ratios, etc.
    • Not 100% sure about this since these are really "just" numbers. An alternative might be that we expand the permitted syntax for the "number" type, so for example "1:2", "50%" and 0.5 are all equivalent. People can then use whichever syntax they like best for a given token.
  • File: for assets - might just be a relative file path / URL (or should we let people also express the mime-type?)
  • Easing definitions: for animation

9. Composite types

Issue 54: Should composites be part of the MVP specification? Format Issue

If so, which composites should be included initially?

  • Would composites allow for better integration with design tools?
  • How would user-defined composites be rendered within design tools?

The types described in the previous chapter are all for singular values (a color, a dimension, etc.). However, it can often be useful to group related values as a single token so that they can be used or referenced as a single unit. A typical example of this is a “typography style” as found in many design tools, which is a combination of the font name, weight, style, and color.

Other examples might be:

9.1 Benefits of composite types over groups

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:

9.2 Type checking

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.

9.3 Tool support

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:

9.3.1 Fallbacks

Given that composite types are ultimately composed of the core design token types, tools that encounter unfamiliar composite tokens could fall back to treating their individual values as separate tokens. In effect, the composite token would be treated the same way as a group of tokens.

Using the color pair type as an example, an export tool like Style Dictionary could just export 2 color variables for it. A token file like this…

… might be exported to Sass like this:

In a similar vein, a GUI tool can "pluck" out the individual values of a composite token and use them as it would normally.

E.g. a design tool like Figma might not have the concept of a color pair, so it can't do anything special with tokens of that type. However, that doesn't prevent it from displaying the foreground and background colors of those tokens alongside any plain color tokens in a color picker.

9.3.2 Appending custom type definitions

A tool might not understand certain user-defined type definitions in a token file and therefore can't do anything special with them. However, that tool could export or modify token files by adding their own type definitions.

For example, imagine Sketch wanted to export all layer styles from a Sketch document to a token file. The Sketch app could have a built-in type definition that corresponds to layer styles. Perhaps something like this:

It could then save out that type definition into the token file it exports. Other tools could then make use of that same type definition and do useful things with tokens of that type.

9.3.3 Custom configuration

Via configuration files or settings menus, tools could let users define custom behavior for types they have defined. For instance, in an export tool like Style Dictionary, users might be able to configure a custom transform or formatter for their composite types. Then, this example...

...could be configured to export, for example, a mixin instead of 2 variables:

The downside is of course that teams need to set up and maintain these configurations themselves.

9.3.4 GUIs

Since composite types are ultimately composed of the core design token types, a design tool could automatically display an appropriate UI for creating, editing, or previewing them.

For instance, the color pair example above consists of 2 colors, one with the key foreground and the other with the key background. A design tool could therefore display two color picker widgets using those keys as the respective labels.

A. Issue Summary

B. References

B.1 Normative references

[RFC2119]
Key words for use in RFCs to Indicate Requirement Levels. S. Bradner. IETF. March 1997. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc2119
[RFC8174]
Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words. B. Leiba. IETF. May 2017. Best Current Practice. URL: https://www.rfc-editor.org/rfc/rfc8174