Function List

Following is a reference list of all blueprint functions to obtain design system data:

Available Functions

• ds.allTokens

• ds.tokensByType

• ds.tokensByGroupId

• ds.allTokenGroups

• ds.allTokenGroupTrees

• ds.tokenGroupsOfType

• ds.tokenGroupTreeByType

• ds.currentDesignSystem

• ds.currentDesignSystemVersion

• ds.allDesignSystemVersions

• ds.tokenGroupContainingTokenId

• configuration

Tokens

ds.allTokens

This function retrieves all tokens from the targeted design system as a flattened array. Note that this function will retrieve all tokens of all types. If you want tokens for just one type, use ds.tokensByType with appropriate type instead.

Example Use

{*
   Following construct will:
   - Fetch all tokens from design system
   - Iterate through all of them
   - List token name
*}
{[ const tokens = @ds.allTokens() /]}
{[ for token in tokens ]}
   {{ token.name }}
   
{[/]}

Example Payload

Definition

ds.tokensByType

This function retrieves all tokens of a specified type from the targeted design system as a flattened array. The type can be any of the design token types.

Example Use

{*
   Following construct will:
   - Fetch all color tokens from design system
   - Iterate through all of them
   - List token name and their descriptions
*}
{[ const colorTokens = @ds.tokensByType("Color") /]}
{[ for token in colorTokens ]}
   {{ token.name }}: {{ token.description }}
   
{[/]}

Example Payload

Definition

ds.tokensByGroupId

Because groups don't contain the tokens they carry by default (only their IDs in tokenIds property), this function retrieves all tokens of a specified group from the targeted design system as a flattened array. The type can be any of the design token types.

Example Use

{*
   Following construct will:
   - Fetch all groups of type "Color"
   - Iterate through the groups
   - For each group, fetch the associated token
   - Iterate through tokens
   - List token names and associated groups
*}
{[ const groups = @ds.tokenGroupsOfType("Color") /]}
{[ for group in groups ]}
    {[ const tokens = @ds.tokensByGroupId(group.id) /]}
    {{ group.name }}:
    {[ for token in tokens ]}
        - {{ token.name }}
    {[/]}
    
{[/]}

Example Payload

Definition

Token Groups

ds.allTokenGroups

This function retrieves all token groups as a flat list.

Note that this function doesn't retrieve tokens that belong to this group. To fetch the token values as well, request the tokens by using ds.tokensByGroupId(group.id) for each group that you are interested in.

Example Use

{*
   Following construct will:
   - Fetch all groups in design system
   - Iterate through the groups
   - For each group, fetch the associated token
   - Iterate through tokens
   - List token names and associated groups, with their respective type
*}
{[ const groups = @ds.allTokenGroups() /]}
{[ for group in groups ]}
    {[ const tokens = @ds.tokensByGroupId(group.id) /]}
    {{ group.name }} ({{ group.tokenType }}):
    {[ for token in tokens ]}
        - {{ token.name }}
    {[/]}
    
{[/]}

Example Payload

Definition

ds.allTokenGroupTrees

Similarly to ds.allTokenGroups , this function retrieves all token groups defined inside the design system. However, in this case, instead of returning all groups a flat array, it returns trees instead. There will be exactly as many trees in the resulting array as there are token categories (ie. one for colors, one for gradients, and so on).

This function always gets you the root of each category. You can iterate through the tree recursively by using traverse flow, recursive for variant.

Example Use

{*
   Following construct will:
   - Fetch all group roots
   - Iterate through all root groups
   - For each group, traverse all subgroups
   - List all subgroups
   - Note: Alternatively use `traverse` instead of `traverseChildren` to include root groups in the list
*}
{[ const groups = @ds.allTokenGroupTrees() /]}
{[ for rootGroup in groups ]}
---
{[ traverse rootGroup property subgroups into subgroup ]}
    {[ if subgroup.isRoot ]}
    Root Group: {{ subgroup.name }}
    {[ else ]}
    - {{ subgroup.path.join("/") }}/{{ subgroup.name }}
    {[/]}
{[/]}
{[/]}

Example Payload

Definition

ds.tokenGroupsOfType

This function retrieves all token groups of one token type as a flat list. The result is the same as with ds.allTokenGroups, but other types than the provided one are filtered out.

Example Use

{*
   Following construct will:
   - Fetch all groups of type "Color"
   - Iterate through the groups
   - For each group, fetch the associated token
   - Iterate through tokens
   - List token names and associated groups, with their respective type
*}
{[ const groups = @ds.allTokenGroups() /]}
{[ for group in groups ]}
    {[ const tokens = @ds.tokensByGroupId(group.id) /]}
    {{ group.name }} ({{ group.tokenType }}):
    {[ for token in tokens ]}
        - {{ token.name }}
    {[/]}
    
{[/]}

Example Payload

Definition

ds.tokenGroupTreeByType

Similarly to ds.allTokenGroups , this function retrieves all token groups defined inside the design system for one specific token type. However, in this case, instead of returning all groups a flat array, it returns the root group instead. There is always only one root group per token type, so the result of this call is an object.

You can iterate through the tree recursively by using traverse flow, recursive for variant.

Example Use

{*
   Following construct will:
   - Fetch group root "Color"
   - Traverse all groups from root
   - List the group tree
*}
{[ const group = @ds.tokenGroupTreeByType("Color") /]}

{[ traverse group property subgroups into subgroup ]}
    {[ if subgroup.isRoot ]}
    Root Group: {{ subgroup.name }}
    {[ else ]}
    - {{ subgroup.path.join("/") }}/{{ subgroup.name }}
    {[/]}
{[/]}

Example Payload

Definition

ds.tokenGroupContainingTokenId

This function retrieves the group that directly contains the provided token id. There is always one group that contains one design token. This function is especially useful in injected blueprints, as you don't have to be passing groups with tokens - and can just request them instead.

Example Use

{*
   Following construct will:
   - Fetch token from context - context is property that gets created when you inject something
   - Fetch group to which it belongs
   - List all tokens under the same group as the provided token
*}

{[ const token = context.token /]}
{[ let group = @ds.tokenGroupContainingTokenId(token.id) /]}

All tokens similar to fetched token:
{[ for token in @ds.tokensByGroupId(group.id) ]}
    {[ for token in tokens ]}
        - {{ token.name }}
    {[/]}
{[/]}

Example Payload

Definition

Design Systems

ds.currentDesignSystem

This function retrieves metadata about the design system which is currently executed. You can use it to enhance exported files with additional information such as the design system name.

Example Use

{*
   Following construct will:
   - Fetch design system we are exporting
   - List its name inside sentence
*}
{[ const designSystem = @ds.currentDesignSystem() /]}
Currently exporting from {{ designSystem.name }} design system

Example Payload

Definition

Design System Versions

ds.currentDesignSystemVersion

This function retrieves the design system version which is currently executed. You can use it to enhance exported files with additional information such as the version name.

Example Use

{*
   Following construct will:
   - Fetch design system we are exporting
   - Fetch version we are exporting
   - Use the names inside sentence
*}
{[ const designSystem = @ds.currentDesignSystem() /]}
{[ const version = @ds.currentDesignSystemVersion() /]}
Currently exporting from {{ designSystem.name }} design system, version {{ version.version }}

Example Payload

Definition

ds.allDesignSystemVersions

This function retrieves all design system versions for the design system that is being used when exporting. You can, for example, use it to quickly create release notes of the entire design system.

Example Use

{*
   Following construct will:
   - Fetch design system we are exporting
   - Fetch all its versions
   - Create a list of published version
*}
{[ const designSystem = @ds.currentDesignSystem() /]}
{[ const versions = @ds.allDesignSystemVersions() /]}
Versions for {{ designSystem.name }}:

{[ for version in versions ]}
    - {{ version.name }} ({{ version.version }})
{[/]}

Example Payload

Definition

Configuration

configuration

This function retrieves the exporter configuration. You can read more about it in a section dedicated to exporter configuration.

Example Use

{*
   Following construct will:
   - Fetch exporter-wide configuration
   - Use configuration to decide whether to render the menu or not
*}
 {[ if @configuration().showTopMenu ]}
  <!-- Top menu-->
  <div class="top-menu">
    <ul>
      <li><a href="colors.html" class="selected">Colors</a></li>
    </ul>
  </div>
 {[/]}

Example Payload

Definition