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

• filter

• change-case

• convert-color

• convert-dimension

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:

• https://regex101.com/

• https://regexr.com/

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

Input

{
  "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
        }
      }
    }
  }
}

Config

Output

Select tokens from several collections matching a naming pattern

Input

{
  "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" }
      }
    }
  }
}

Config

Output

Select tokens from a specific group

Input

{
  "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
        }
      }
    }
  }
}

Config

Output

Select tokens of a specific type from a collection

Input

{
  "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
          }
        }
      }
    }
  }
}

Config

Output

Select all tokens from a collection and from groups matching a naming pattern

Input

{
  "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
          }
        }
      }
    }
  }
}

Config

Output

Select tokens from several groups with different names

Input

{
  "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
        }
      }
    }
  }
}

Config

Output

Select design tokens from a specific type

Input

{
  "dimensions": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      }
    }
  },
  "colors": {
    "black": {
      "$type": "color",
      "$value": {
        "default": {
          "model": "hex",
          "hex": "#000000",
          "alpha": 1
        }
      }
    }
  }
}

Config

Output