# Function List

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

### Available Functions

* [ds.allTokens](#ds-alltokens)
* [ds.tokensByType](#ds-tokensbytype)
* [ds.tokensByGroupId](#ds-tokensbygroupid)<br>
* [ds.allTokenGroups](#ds-alltokengroups)
* [ds.allTokenGroupTrees](#ds-alltokengrouptrees)
* [ds.tokenGroupsOfType](#ds-tokengroupsoftype)
* [ds.tokenGroupTreeByType](#ds-tokengrouptreebytype)<br>
* [ds.currentDesignSystem](#ds-currentdesignsystem)<br>
* [ds.currentDesignSystemVersion](#ds-currentdesignsystemversion)
* [ds.allDesignSystemVersions](#ds-alldesignsystemversions)
* ds.tokenGroupContainingTokenId<br>
* configuration

###

### Tokens

#### ds.allTokens

This function retrieves all [tokens](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/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`](#ds-tokensbytype) with appropriate type instead.

{% tabs %}
{% tab title="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 }}
   
{[/]}
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
 [{
    "id": "149f7b03-8586-11eb-a324-c7f25166e00c",
    "name": "Methods",
    "description": "Methods",
    "tokenType": "Color",
    "origin": {
        "source": "Figma",
        "id": "S:32290b728349ad1f12133d58fcfa2d972477534a,",
        "name": "Code/Methods"
    },
    "value": {
        "hex": "874ce6ff",
        "r": 135,
        "g": 76,
        "b": 230,
        "a": 255,
        "referencedToken": null
    }
}]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.allTokens(): [Token]
```

{% endtab %}
{% endtabs %}

####

#### ds.tokensByType

This function retrieves all tokens of a specified type from the targeted [design system](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/design-system) as a flattened array. The type can be any of the [design token](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/tokens) types.

{% tabs %}
{% tab title="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 }}
   
{[/]}
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
 [{
    "id": "149f7b03-8586-11eb-a324-c7f25166e00c",
    "name": "Methods",
    "description": "Methods",
    "tokenType": "Color",
    "origin": {
        "source": "Figma",
        "id": "S:32290b728349ad1f12133d58fcfa2d972477534a,",
        "name": "Code/Methods"
    },
    "value": {
        "hex": "874ce6ff",
        "r": 135,
        "g": 76,
        "b": 230,
        "a": 255,
        "referencedToken": null
    }
}]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.tokensByType(tokenType: TokenType): [Token]
```

{% endtab %}
{% endtabs %}

#### ds.tokensByGroupId

Because groups don't contain the tokens they carry by default (only their IDs in `tokenIds` property), this function retrieves all [tokens](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/tokens) of a specified [group](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/token-groups) from the targeted [design system ](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/design-system)as a flattened array. The type can be any of the [design token types](https://supernova-developers.gitbook.io/supernova-dsm/tokens#token-types).

{% tabs %}
{% tab title="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 }}
    {[/]}
    
{[/]}
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
[
    {
        "id": "149fc92b-8586-11eb-a324-c7f25166e00c",
        "name": "10",
        "description": "10",
        "tokenType": "Color",
        "origin": {
            "source": "Figma",
            "id": "S:494296a45a5072718577cc0faae3bd89e6c47207,",
            "name": "Base/Pink/10"
        },
        "value": {
            "hex": "fef0f5ff",
            "r": 254,
            "g": 240,
            "b": 245,
            "a": 255,
            "referencedToken": null
        }
    },
    {
        "id": "149fc92c-8586-11eb-a324-c7f25166e00c",
        "name": "20",
        "description": "20",
        "tokenType": "Color",
        "origin": {
            "source": "Figma",
            "id": "S:5642100401a4019c765b51f22f0f203de2cd1a02,",
            "name": "Base/Pink/20"
        },
        "value": {
            "hex": "fdd5e4ff",
            "r": 253,
            "g": 213,
            "b": 228,
            "a": 255,
            "referencedToken": null
        }
    }
]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.tokensByGroupId(groupId: string): [Token]
```

{% endtab %}
{% endtabs %}

### Token Groups

#### ds.allTokenGroups

This function retrieves all [token groups](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/token-groups) as a flat list.&#x20;

Note that this function doesn't retrieve [tokens](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/tokens) that belong to this group. To fetch the [token](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/tokens) values as well, request the tokens by using `ds.tokensByGroupId(group.id)` for each [group](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/token-groups) that you are interested in.

{% tabs %}
{% tab title="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 }}
    {[/]}
    
{[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
[
    {
        "id": "22fedcd2-b919-4c3c-b4a8-3265459b363c",
        "name": "Primary Brand Borders",
        "description": "",
        "isRoot": true,
        "tokenType": "Border",
        "path": [],
        "tokenIds": [
            "db600240-92cf-11eb-ba3c-1356ef16cb2d"
        ],
        "subgroups": []
    },
    {
        "id": "e26884bb-0dde-4aa8-99bc-70e667d19940",
        "name": "Primary Brand Fonts",
        "description": "",
        "isRoot": true,
        "tokenType": "Font",
        "path": [],
        "tokenIds": [],
        "subgroups": []
    },
    ...
]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.allTokenGroups(): [TokenGroup]
```

{% endtab %}
{% endtabs %}

#### ds.allTokenGroupTrees

Similarly to [`ds.allTokenGroups`](#ds-alltokengroups) , this function retrieves all token [groups](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/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).&#x20;

This function always gets you the root of each category. You can iterate  through the tree recursively by using [`traverse`](https://supernova-developers.gitbook.io/supernova-dsm/pulsar-language/flows/traverse) flow, recursive `for` variant.&#x20;

{% tabs %}
{% tab title="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 }}
    {[/]}
{[/]}
{[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
[
    {
        "id": "22fedcd2-b919-4c3c-b4a8-3265459b363c",
        "name": "Border",
        "description": "",
        "isRoot": true,
        "tokenType": "Primary Brand Borders",
        "path": [],
        "tokenIds": [
            "db600240-92cf-11eb-ba3c-1356ef16cb2d"
        ],
        "subgroups": [
            {
                "id": "fe1bea60-92cf-11eb-ba3c-1356ef16cb2d",
                "name": "Most amazing borders there are",
                "description": "",
                "isRoot": false,
                "tokenType": "White Theme",
                "path": [],
                "tokenIds": [
                    "f686b140-92cf-11eb-ba3c-1356ef16cb2d"
                ],
                "subgroups": []
            }
        ]
    },
    {
        "id": "e26884bb-0dde-4aa8-99bc-70e667d19940",
        "name": "Font",
        "description": "",
        "isRoot": true,
        "tokenType": "Font",
        "path": [],
        "tokenIds": [],
        "subgroups": []
    },
    ...
]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.allTokenGroupTrees(): [TokenGroup]
```

{% endtab %}
{% endtabs %}

#### 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`](#ds-alltokengroups), but other types than the provided one are filtered out.

{% tabs %}
{% tab title="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 }}
    {[/]}
    
{[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
[
    {
        "id": "22fedcd2-b919-4c3c-b4a8-3265459b363c",
        "name": "Border",
        "description": "",
        "isRoot": true,
        "tokenType": "Border",
        "path": [],
        "tokenIds": [
            "db600240-92cf-11eb-ba3c-1356ef16cb2d"
        ],
        "subgroups": []
    }, {
        "id": "22fedcd2-b919-4c3c-b4a8-3265459b363x",
        "name": "Colored Borders",
        "description": "",
        "isRoot": false,
        "tokenType": "Border",
        "path": [],
        "tokenIds": [
            "db600240-92cf-11eb-ba3c-1356ef16cb2x"
        ],
        "subgroups": []
    }
]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.tokenGroupsOfType(tokenType: TokenType): [TokenGroup]
```

{% endtab %}
{% endtabs %}

#### ds.tokenGroupTreeByType

Similarly to [`ds.allTokenGroups`](#ds-alltokengroups) , this function retrieves all token [groups](https://supernova-developers.gitbook.io/supernova-dsm/design-system-data/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`](https://supernova-developers.gitbook.io/supernova-dsm/pulsar-language/flows/traverse) flow, recursive `for` variant.&#x20;

{% tabs %}
{% tab title="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 }}
    {[/]}
{[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
{
    "id": "22fedcd2-b919-4c3c-b4a8-3265459b363c",
    "name": "Border",
    "description": "",
    "isRoot": true,
    "tokenType": "Primary Brand Borders",
    "path": [],
    "tokenIds": [
        "db600240-92cf-11eb-ba3c-1356ef16cb2d"
    ],
    "subgroups": [
        {
            "id": "fe1bea60-92cf-11eb-ba3c-1356ef16cb2d",
            "name": "Most amazing borders there are",
            "description": "",
            "isRoot": false,
            "tokenType": "White Theme",
            "path": [],
            "tokenIds": [
                "f686b140-92cf-11eb-ba3c-1356ef16cb2d"
            ],
            "subgroups": []
        }
    ]
}
```

{% endtab %}

{% tab title="Definition" %}

```
ds.tokenGroupTreeByType(tokenType: TokenType): TokenGroup
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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 }}
    {[/]}
{[/]}
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
{
    "id": "22fedcd2-b919-4c3c-b4a8-3265459b363c",
    "name": "Border",
    "description": "",
    "isRoot": true,
    "tokenType": "Primary Brand Borders",
    "path": [],
    "tokenIds": [
        "db600240-92cf-11eb-ba3c-1356ef16cb2d"
    ],
    "subgroups": [
        {
            "id": "fe1bea60-92cf-11eb-ba3c-1356ef16cb2d",
            "name": "Most amazing borders there are",
            "description": "",
            "isRoot": false,
            "tokenType": "White Theme",
            "path": [],
            "tokenIds": [
                "f686b140-92cf-11eb-ba3c-1356ef16cb2d"
            ],
            "subgroups": []
        }
    ]
}
```

{% endtab %}

{% tab title="Definition" %}

```
ds.tokenGroupContainingTokenId(tokenId: string): TokenGroup
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
{
    "id": "70",
    "workspaceId": "20",
    "name": "Nebula",
    "description": "Our amazing little design system",
    "isPublic": false,
    "basePrefixes": [],
    "source": {
        "source": "Figma",
        "fileId": "123456789123456789",
        "fileName": "Nebula Design System"
    }
}
```

{% endtab %}

{% tab title="Definition" %}

```
ds.currentDesignSystem(): DesignSystem
```

{% endtab %}
{% endtabs %}

### 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.&#x20;

{% tabs %}
{% tab title="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 }}
```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
{
    "id": "76",
    "designSystemId": "70",
    "name": "Shared draft",
    "description": "",
    "version": "Shared draft",
    "changeLog": null,
    "isReadOnly": false
}
```

{% endtab %}

{% tab title="Definition" %}

```
ds.currentDesignSystemVersion(): DesignSystemVersion
```

{% endtab %}
{% endtabs %}

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

{% tabs %}
{% tab title="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 }})
{[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
[{
    "id": "76",
    "designSystemId": "70",
    "name": "Shared draft",
    "description": "",
    "version": "Shared draft",
    "changeLog": null,
    "isReadOnly": false
}, {
    "id": "90",
    "designSystemId": "70",
    "name": "Aurora",
    "description": "Initial Release",
    "version": "1.0.0",
    "changeLog": "Publishing initial stable version of design system",
    "isReadOnly": false
}]
```

{% endtab %}

{% tab title="Definition" %}

```
ds.allDesignSystemVersions(): [DesignSystemVersion]
```

{% endtab %}
{% endtabs %}

###

### Configuration

#### configuration

This function retrieves the exporter configuration. You can read more about it in a section dedicated to [exporter configuration](https://supernova-developers.gitbook.io/supernova-dsm/building-exporters/user-configuration).

{% tabs %}
{% tab title="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>
 {[/]}

```

{% endtab %}

{% tab title="Example Payload" %}

```javascript
{
    "id": "70",
    "workspaceId": "20",
    "name": "Nebula",
    "description": "Our amazing little design system",
    "isPublic": false,
    "basePrefixes": [],
    "source": {
        "source": "Figma",
        "fileId": "123456789123456789",
        "fileName": "Nebula Design System"
    }
}
```

{% endtab %}

{% tab title="Definition" %}

```
ds.currentDesignSystem(): DesignSystem
```

{% endtab %}
{% endtabs %}