convert-dimension

This parser helps you convert units of dimension tokens (spacing, sizing, breakpoint, blur...) and composite tokens sub values (font-size, letter-spacing, border-width...)

Interface

interface parser {
  name: 'convert-dimension';
  options: {
    toFormat:
      | '%' 
      | 'px' 
      | 'em' 
      | 'rem' 
      | 'pt' 
      | 'pc' 
      | 'in' 
      | 'cm' 
      | 'mm' 
      | 'ex' 
      | 'cap' 
      | 'ch' 
      | 'ic' 
      | 'lh' 
      | 'rlh' 
      | 'vw' 
      | 'svw' 
      | 'lvw' 
      | 'dvw' 
      | 'vh' 
      | 'svh' 
      | 'lvh' 
      | 'dvh' 
      | 'vi' 
      | 'svi' 
      | 'lvi' 
      | 'dvi' 
      | 'vb' 
      | 'svb' 
      | 'lvb' 
      | 'dvb' 
      | 'vmin' 
      | 'svmin' 
      | 'lvmin' 
      | 'dvmin' 
      | 'vmax' 
      | 'svmax' 
      | 'lvmax' 
      | 'dvmax'
      | null;
    baseValue?: {
      rem?: number
    };
    applyTo?: SDTFQuery;
    applyToKeys?: {
      textStyle?: Array<'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>,
      shadow?: Array<'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>,
      border?: Array<'width' | 'rectangleCornerRadii'>,
    };
    excludeFormats?: array;
    includeFormats?: array;
  };
}

Options

Parameter	Required	Type	Default	Description
toFormat	required	| '%' | 'px' | 'em' | 'rem' | 'pt' | 'pc' | 'in' | 'cm' | 'mm' | 'ex' | 'cap' | 'ch' | 'ic' | 'lh' | 'rlh' | 'vw' | 'svw' | 'lvw' | 'dvw' | 'vh' | 'svh' | 'lvh' | 'dvh' | 'vi' | 'svi' | 'lvi' | 'dvi' | 'vb' | 'svb' | 'lvb' | 'dvb' | 'vmin' | 'svmin' | 'lvmin' | 'dvmin' | 'vmax' | 'svmax' | 'lvmax' | 'dvmax' | null		The target dimension format to convert to.
baseValue	false	{ rem: number }
applyTo	false	| { collection: string | true } | { group: string | true } | { token: string | true } | SDTFQuery	{ token: true }	The selection where to apply the transformation. collection, group, token take a Regex string or true to select anything of the kind. An SDTFQuery can be used for advance use cases.
applyToKeys	false	{ textStyle?: Array<'fontSize' | 'lineHeight' | 'letterSpacing' | 'paragraphSpacing'| 'textIndent'>, shadow?: Array<'offsetX' | 'offsetY' | 'blurRadius' | 'spreadRadius'>, border?: Array<'width' | 'rectangleCornerRadii'>, }		Select composite tokens sub-values to convert
excludeFormats	false	array		List of dimension formats you don't want to convert.
includeFormats	false	array		List of dimension formats you only want to convert.

Examples

Basic usage

Input

{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 8,
            "unit": "px"
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 12,
            "unit": "px"
          }
        }
      }
    }
  }
}

Config

We convert all dimensions from our SDTF graph in rem.

We then generate our transformed SDTF graph in a JSON file thanks to the to-sdtf parser.

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}

Output

tokens.json

{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.25,
            "unit": "rem"
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.5,
            "unit": "rem"
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.75,
            "unit": "rem"
          }
        }
      }
    }
  }
}

Generate unitless dimension tokens

Input

{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 4,
            "unit": "px"
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 8,
            "unit": "px"
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 12,
            "unit": "px"
          }
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert spacing in rem and generate tokens in JSON",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "toFormat": null
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "tokens.json"
          }
        }
      ]
    }
  ]
}

Output

tokens.json

{
  "Foundation": {
    "spacing": {
      "1": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.25,
            "unit": null
          }
        }
      },
      "2": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.5,
            "unit": null
          }
        }
      },
      "3": {
        "$type": "dimension",
        "$value": {
          "default": {
            "value": 0.75,
            "unit": null
          }
        }
      }
    }
  }
}

Convert text style's font-size from px to rem

Input

{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
          "fontSize": {
            "value": 14,
            "unit": "px"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}

Config

.specifyrc.json

{
  "version": "2",
  "repository": "@organization/repository",
  // Only use the personalAccessToken when working with the CLI
  "personalAccessToken": "<your-personal-access-token>",
  "rules": [
    {
      "name": "Convert font-sizes to rem",
      "parsers": [
        {
          "name": "convert-dimension",
          "options": {
            "applyToKeys": {
              "textStyle": [
                "fontSize"
              ]
            },
            "toFormat": "rem"
          }
        },
        {
          "name": "to-sdtf",
          "output": {
            "type": "file",
            "filePath": "public/tokens.json"
          }
        }
      ]
    }
  ]
}

Output

tokens.json

{
  "Text styles": {
    "Body": {
      "$type": "textStyle",
      "$value": {
        "default": {
          "font": {
            "family": "Neue Haas Grotesk Text Pro",
            "postScriptName": "Neue Haas Grotesk Text Pro",
            "weight": "roman",
            "style": "normal",
            "files": []
          },
          "fontSize": {
            "value": 0.875,
            "unit": "rem"
          },
          "color": null,
          "fontFeatures": null,
          "lineHeight": {
            "value": 150,
            "unit": "%"
          },
          "letterSpacing": {
            "value": 0.2,
            "unit": "px"
          },
          "paragraphSpacing": {
            "value": 0,
            "unit": "px"
          },
          "textAlignHorizontal": null,
          "textAlignVertical": null,
          "textDecoration": "none",
          "textIndent": {
            "value": 0,
            "unit": "px"
          },
          "textTransform": "none"
        }
      }
    }
  }
}