Querying a SDTF graph
Learn more about how to query your SDTF token graph.
Introduction
Your token system can be more complex than it seems. You will often need to interact with your token graph to transform a specific set of design tokens within a Specify configuration.
This article will help you understand how you can query your token graph to select a specific set of tokens.
Compatible parsers
Query structure
Every Query holds a single a where property being an object, to select one branch of the graph, or an array of objects, to select many branches of the graph (OR statement).
Type Query = { where: Where | Array<Where> }The where property splits in 3 kinds: token, group, collection - offering a dedicated set of options to match against the given kind.
The name property accepts a RegExp for a value. These resources will help you debug your regular expressions:
Where Token
type WhereToken = {
token:
| string
| {
name?: string;
description?: string?;
}
select:
| true
| {
token?: boolean;
parents?:
| true
| {
groups?: true;
collections?: true;
}
}
}Where Group
type WhereGroup = {
group: string;
select:
| true
| {
group?: boolean;
parents?:
| true
| {
groups?: true;
collections?: true;
}
children:
| true
| {
groups?: true;
collections?: true;
tokens?: true;
}
}
}Where Collection
type WhereCollection = {
collection: string;
select:
| true
| {
collection?: boolean;
parents?:
| true
| {
groups?: true;
}
children:
| true
| {
groups?: true;
tokens?: true;
}
}
}Use cases
Select tokens from a specific collection
{
"primitive": {
"$description": "`primitive` is a group used for semantic grouping.",
"spacing": {
"1": {
"$type": "dimension",
"$value": {
"default": {
"value": 4,
"unit": "px"
}
}
}
}
},
"Colors": {
"$description": "`Colors` is a collection.",
"$collection": {
"$modes": [
"default"
]
},
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
},
"white": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
}
}Select tokens from several collections matching a naming pattern
{
"primitive": {
"$description": "`primitive` is a group used for semantic grouping.",
"spacing": {
"1": {
"$type": "dimension",
"$description": "`primitive.spacing.1` is a dimension token without modes.",
"$value": {
"default": {
"value": 4,
"unit": "px"
}
}
}
}
},
"Core - Colors": {
"$collection": {
"$modes": [
"default"
]
},
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
},
"white": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
},
"Core - Spacing": {
"$collection": {
"$modes": [
"default"
]
},
"space-1": {
"$type": "spacing",
"$value": {
"default": { "value": 1, "unit": "px" }
}
},
"space-2": {
"$type": "spacing",
"$value": {
"default": { "value": 2, "unit": "px" }
}
}
}
}Select tokens from a specific group
{
"primitive": {
"$description": "`primitive` is a group used for semantic grouping.",
"spacing": {
"1": {
"$type": "dimension",
"$description": "`primitive.spacing.1` is a dimension token without modes.",
"$value": {
"default": {
"value": 4,
"unit": "px"
}
}
}
},
"font": {
"interBold": {
"$type": "font",
"$value": {
"default": {
"family": "Inter",
"postScriptName": "Inter Bold",
"weight": "bold",
"style": "normal",
"files": [
{
"format": "ttf",
"url": "https://static.specifyapp.com/sdtf-seeds/inter-bold.ttf",
"provider": "Specify"
}
]
}
}
}
}
},
"Text Styles": {
"heading": {
"$type": "textStyle",
"$value": {
"default": {
"font": {
"$alias": "primitive.font.interBold",
"$mode": "default"
},
"color": null,
"fontSize": {
"value": 32,
"unit": "px"
},
"lineHeight": {
"value": 40,
"unit": "px"
},
"fontFeatures": null,
"letterSpacing": null,
"paragraphSpacing": null,
"textAlignHorizontal": null,
"textAlignVertical": null,
"textDecoration": null,
"textIndent": null,
"textTransform": null
}
}
},
"display": {
"$type": "textStyle",
"$value": {
"default": {
"font": {
"$alias": "primitive.font.interBold",
"$mode": "default"
},
"color": null,
"fontSize": {
"value": 56,
"unit": "px"
},
"lineHeight": {
"value": 64,
"unit": "px"
},
"fontFeatures": null,
"letterSpacing": {
"value": -1,
"unit": "px"
},
"paragraphSpacing": null,
"textAlignHorizontal": null,
"textAlignVertical": null,
"textDecoration": null,
"textIndent": null,
"textTransform": null
}
}
}
}
}Select tokens of a specific type from a collection
{
"Android": {
"$collection": {
"$modes": [
"default"
]
},
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
},
"white": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
},
"primitive": {
"gray": {
"0": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#f8f9fa",
"alpha": 1
}
}
},
"9": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#212529",
"alpha": 1
}
}
}
}
}
}Select all tokens from a collection and from groups matching a naming pattern
{
"Android": {
"$collection": {
"$modes": [
"default"
]
},
"primitive": {
"gray": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#f8f9fa",
"alpha": 1
}
}
}
},
"components": {
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
},
"white": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
}
}
}Select tokens from several groups with different names
{
"group1": {
"token1": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
}
},
"group2": {
"token2": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
},
"group3": {
"token3": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#FFFFFF",
"alpha": 1
}
}
}
}
}Select design tokens from a specific type
{
"dimensions": {
"spacing": {
"1": {
"$type": "dimension",
"$value": {
"default": {
"value": 4,
"unit": "px"
}
}
}
}
},
"colors": {
"black": {
"$type": "color",
"$value": {
"default": {
"model": "hex",
"hex": "#000000",
"alpha": 1
}
}
}
}
}Last updated
Was this helpful?