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'
| nullThe 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
{
"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"
}
}
}
}
}
}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"
}
}
]
}
]
}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
{
"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"
}
}
}
}
}
}.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"
}
}
]
}
]
}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
{
"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"
}
}
}
}
}.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"
}
}
]
}
]
}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"
}
}
}
}
}Last updated