Design Tokens Format Module

All properties defined by this format are prefixed with the dollar sign ($). This convention will also be used for any new properties introduced by future versions of this spec. Therefore, token and group names MUST NOT begin with the $ character.

Furthermore, due to the syntax used for token aliases the following characters MUST NOT be used anywhere in a token or group name:

• { (left curly bracket)
• } (right curly bracket)
• . (period)

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.

The $deprecated property MAY be used to mark a token as deprecated, and optionally explain the reason. Reasons to deprecate tokens include but are not limited to the following:

• A future update to the design system will remove this token
• Removing the token now may break existing support
• This token is discouraged from future use

Tool makers MAY augment the string when it contains aliases such as the one given as an example. A tool could potentially resolve the token, and link to docs, code, or render a visual representation of it and link to the new token inside a UI. For example, “Please use {button.activeBorder} instead“ could be output in JS as:

Or

Groups MAY include an optional $deprecated property to mark the entire group as deprecated. This extends to all child tokens within the group unless explicitly overridden.

Groups MAY include an optional $extensions property where tools MAY add proprietary, user-, team- or vendor-specific data. Each tool MUST use a vendor-specific key whose value MAY be any valid JSON data.

The $extends property is semantically equivalent to JSON Schema's $ref keyword as specified in [json-schema-2020-12] and later versions. The following two group definitions are functionally identical:

Using $extends (Design Token syntax):

{
  "button-primary": {
    "$extends": "{button}",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.8, 0, 0.4],
        "hex": "#cc0066"
      }
    },
    "focus": {
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 0.2, 0.6],
        "hex": "#ff3399"
      }
    }
  }
}

Using $ref (JSON Schema syntax):

{
  "button-primary": {
    "$ref": "#/button",
    "background": {
      "$value": {
        "colorSpace": "srgb",
        "components": [0.8, 0, 0.4],
        "hex": "#cc0066"
      }
    },
    "focus": {
      "$value": {
        "colorSpace": "srgb",
        "components": [1, 0.2, 0.6],
        "hex": "#ff3399"
      }
    }
  }
}

Extension resolution follows a straightforward process:

1. Find the target: Resolve the $extends reference to locate the target group
2. Copy inherited content: Start with all tokens and properties from the target group
3. Apply local overrides: Replace any inherited tokens/properties where local ones exist at the same path
4. Add new content: Include any local tokens/properties that don't exist in the inherited group

This creates a new resolved group that combines inherited and local content according to the override rules above.

Group extension follows deep merge behavior where local properties override inherited properties at the same path:

1. Inheritance: All tokens and properties from the referenced group are inherited (circular references are not allowed)
2. Override: Local tokens and properties replace inherited ones with the same path
3. Addition: Local tokens and properties with new paths are added alongside inherited ones

Override Rules:

• Same path = override: If both the inherited group and local group define a token at the same path, the local definition wins
• Different paths = merge: Tokens at different paths coexist in the final result
• Complete replacement: When overriding, the entire token definition is replaced (not merged property-by-property)

Result for input-amount:

Multi-level Override Example:

Result for extended:

Groups MUST NOT create circular inheritance chains. The following patterns are invalid:

Valid inheritance patterns:

$extends supports the same reference formats as design token aliases.

$extends error handling follows JSON Schema $ref error patterns:

• Unresolvable references: When the target group cannot be found
• Invalid targets: When the reference points to a non-group (e.g., a token)
• Circular references: When extension chains create cycles
• Constraint violations: When local properties violate inherited constraints

Tools MUST implement the same error detection and reporting patterns used by JSON Schema validators for $ref resolution.

Tools implementing design token parsing MAY choose to:

1. Transform to $ref: Convert $extends to standard JSON Schema $ref syntax and use existing JSON Schema libraries for validation
2. Native implementation: Implement $extends directly using the same algorithms as JSON Schema $ref processing
3. Hybrid approach: Use JSON Schema libraries for validation while maintaining design token-specific reference syntax

Regardless of implementation approach, the semantic behavior MUST be equivalent to JSON Schema $ref as specified in JSON Schema 2020-12 or later.

This specification defines $extends as syntactic sugar for JSON Schema's $ref keyword, providing design token-specific reference syntax while maintaining equivalent behavior. The deep merge semantics described above align with how JSON Schema 2020-12 handles $ref with sibling properties.

For implementers familiar with JSON Schema, the $extends behavior is equivalent to:

• Converting "$extends": "{group}" to "$ref": "#/group"
• Applying JSON Schema 2020-12 $ref resolution with sibling property evaluation

Tools implementing this specification MAY choose to:

1. Transform approach: Convert $extends to $ref and use JSON Schema libraries
2. Direct implementation: Implement the deep merge behavior described above
3. Hybrid approach: Use JSON Schema for validation while maintaining design token syntax

Regardless of implementation approach, the user-visible behavior MUST match the deep merge semantics described in this specification.

Tools MUST support JSON Pointer references as defined by [rfc6901], using the $ref property:

When processing groups, tools MUST follow this resolution order:

1. Local tokens - Direct children with $value properties
2. Root tokens - Tokens with $root names
3. Extended tokens - Tokens inherited via $extends (if not overridden)
4. Nested groups - Process recursively

Token paths are constructed by concatenating group names and token names with periods (.). The reserved token name $root is included in the path to maintain explicit, unambiguous references.

Examples:

Type resolution follows these rules in order of precedence:

1. Token's explicit $type property (highest precedence)
2. Resolved group's $type property (after extension resolution)
3. Parent group's $type property (walking up the hierarchy)
4. Token is invalid if no type can be determined

Type Resolution with Extensions: Since $extends follows JSON Schema $ref semantics, type inheritance behavior is determined by constraint validation rather than explicit merge rules. Local type constraints are evaluated alongside inherited constraints according to JSON Schema validation patterns.

In this example, the group extended must satisfy both its local $type: "dimension" constraint and any applicable constraints from the referenced base group, following JSON Schema constraint resolution rules.

Tools MUST detect and throw an error on circular references in:

• Token aliases ({token} references)
• Group extensions ($extends references)
• JSON Pointer references ($ref properties, if supported)

Circular reference detection for $extends follows the same requirements as JSON Schema $ref circular reference detection. Tools SHOULD implement the same algorithms used by JSON Schema validators for cycle detection.

Tools MUST report this as an error affecting groups a, b, and c.

Resolved tokens:

• {input-amount.field.width} → { "value": 100, "unit": "px" } (overridden)
• {input-amount.field.background} → #ffffff (inherited from input)

This demonstrates the key use case where a component extends a base component but overrides specific tokens while inheriting others.

This structure creates tokens accessible as:

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:

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.

Token names are not guaranteed to be unique within the same file. The same name can be used in different groups. Also, translation tools MAY need to export design tokens in a uniquely identifiable way, such as variables in code. Translation 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:

The curly brace syntax is specifically designed for referencing complete token values and always resolves to the $value property of the target token.

In this example, {colors.blue} resolves to the entire color object {"colorSpace": "srgb", "components": [0, 0.4, 0.8], "hex": "#0066cc"}.

Important: Curly brace references can ONLY target complete tokens (objects with $value properties), not individual properties within token values or arbitrary document locations.

For advanced use cases requiring access to specific properties within token values or other parts of the document structure, tokens MUST support JSON Pointer notation as defined by [rfc6901], using the $ref property. Tools implementing this specification MUST support JSON Pointer syntax.

In this example:

• "$ref": "#/colors/blue/$value" is equivalent to "{colors.blue}"
• "$ref": "#/colors/blue/$value/components/0" accesses just the red component (0) of the blue color

Key Differences:

For Curly Brace References:

1. Parse reference: Extract token path from {group.token}
2. Split path: Convert to segments ["group", "token"]
3. Navigate to token: Find the target token object
4. Validate token: Ensure target has $value property
5. Return token value: Extract and return the $value content
6. Check for cycles: Maintain stack of resolving references

For JSON Pointer References:

1. Parse JSON Pointer: Extract path segments from #/path/to/target
2. Traverse document: Navigate through each path segment
3. Apply JSON Pointer rules:
   • Numeric segments in array contexts become array indices
   • All segments in object contexts become property names
   • Handle escaped characters (~0, ~1)
4. Validate target: Ensure the final target exists and is accessible
5. Return value: Extract and return the resolved value

Aliases MAY reference other aliases. In this case, tools MUST follow each reference until they find a token with an explicit value.

In this example, {semantic.link} resolves to the same color value as {base.primary} by following the chain: semantic.link → semantic.brand → base.primary.

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.

Tools MUST detect and report this as an error affecting all tokens in the circular chain.

In this example:

• semantic.primary keeps the same red and green components as base.blue but uses a different blue component (0.7)
• semantic.secondary keeps the same red and green components as base.blue but uses a different blue component (0.5)
• Changes to the hue of base.blue will automatically propagate to both semantic colors

In this example:

• layout.small uses the same numeric value as base.spacing (16) but with a different unit (rem)
• layout.large uses the same unit as base.spacing (px) but with a different numeric value (32)

In this example:

• Both headings inherit the fontFamily and lineHeight from base.text
• Each heading defines its own fontSize and fontWeight
• Changes to the base font family or line height automatically affect all headings

• Root reference: #/ (refers to the document root)
• Object properties: / separates each level (e.g., #/group/token/$value)
• Array indices: Numeric indices for array elements (e.g., #/color/$value/components/0)
• Special characters: Must be escaped according to JSON Pointer rules:
  • ~ becomes ~0
  • / becomes ~1

Since design tokens store their values in $value properties, JSON Pointer paths to token values follow a predictable pattern:

1. Parse JSON Pointer: Extract path segments from #/path/to/target
2. Traverse document: Navigate through each path segment
3. Apply JSON Pointer rules:
   • Numeric segments in array contexts become array indices
   • All segments in object contexts become property names
   • Handle escaped characters (~0, ~1)
4. Validate target: Ensure the final target exists and is accessible
5. Return value: Extract and return the resolved value

1. Parse reference: Extract token path from {group.token}
2. Split path: Convert to segments ["group", "token"]
3. Navigate to token: Find the target token object
4. Validate token: Ensure target has $value property
5. Return token value: Extract and return the $value content
6. Check for cycles: Maintain stack of resolving references

Tools MUST report errors for:

• Invalid syntax: Malformed curly braces or JSON Pointer syntax
• Unresolvable paths: Target path does not exist in document
• Invalid token references: Curly brace syntax targeting non-tokens
• Circular references: Reference chains that loop back to themselves
• Type mismatches: Referenced value incompatible with expected type

Tools implementing design token parsing MUST:

1. Support curly brace syntax as the primary reference mechanism for token-to-token references
2. Support JSON Pointer syntax for document-level references and property access
3. Validate reference targets to ensure they point to valid tokens (for curly brace) or valid document locations (for JSON Pointer)
4. Resolve references according to the resolution algorithms defined in this specification (Resolution Algorithms)
5. Detect circular references before attempting resolution
6. Preserve references in memory/storage and resolve only when values are needed
7. Propagate changes from referenced tokens to all aliases

Clear resolution:

Tools MUST report errors for:

• Invalid reference syntax: Malformed curly braces or JSON Pointer syntax
• Unresolvable references: Target path does not exist
• Circular references: Reference chains that loop back to themselves
• Type mismatches: Referenced property type incompatible with token type
• Invalid property paths: Attempting to reference non-existent properties

• $value.unit may only be "px" or "rem".
  • 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.
• $value.unit is still required even if $value.value is 0.

• $value.unit may only be "ms" or "s"

String stroke style values MUST be set to one of the following, pre-defined values:

• solid
• dashed
• dotted
• double
• groove
• ridge
• outset
• inset

These values have the same meaning as the equivalent "line style" values in CSS. As per the CSS spec, their exact rendering is therefore implementation specific. For example, the length of dashes and gaps in the dashed style may vary between different tools.

Object stroke style values MUST have the following properties:

• dashArray: An array of dimension values and/or references to dimension tokens, which specify the lengths of alternating dashes and gaps. Each element in the array must be either an explicit dimension value or a reference to a dimension token. If an odd number of values is provided, then the list of values is repeated to yield an even number of values.
• lineCap: One of the following pre-defined string values: "round", "butt" or "square". These values have the same meaning as those of the stroke-linecap attribute in SVG.

The string and object values are mutually exclusive means of expressing stroke styles. For example, some of the string values like inset or groove cannot be expressed in terms of a dashArray and lineCap as they require some implementation-specific means of lightening or darkening the color for portions of a border or outline. Conversely, a precisely defined combination of dashArray and lineCap sub-values is not guaranteed to produce the same visual result as the dashed or dotted keywords as they are implementation-specific.

Furthermore, some tools and platforms may not support the full range of stroke styles that design tokens of this type can represent. When displaying or exporting a strokeStyle token whose value they don't natively support, they should therefore fallback to the closest approximation that they do support.

The specifics of how a "closest approximation" is chosen are implementation-specific. However, the following examples illustrate what fallbacks tools MAY use in some scenarios.