convert-color

This parser helps you convert color formats of color tokens.

Interface

interface parser {
  name: 'convert-color';
  options: {
    toFormat:
      | 'hex'
      | 'rgb'
      | 'hsl'
      | 'hsb'
      | 'lch'
      | 'lab';
    applyTo?:
      | { collection: string | true }
      | { group: string | true }
      | { token: string | true }
      | SDTFQuery;
  };
}

Options

Parameter	Required	Type	Default	Description
toFormat	required	| 'hex' | 'rgb' | 'hsl' | 'hsb' | 'lch' | 'lab'		The target color format to convert to. Actual value conversion is done by the colord package.
applyTo	optional	| { 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. Learn more about how to query your SDTF graph.

Basic usage

Input

{
  "Colors": {
    "$collection": { "$modes": ["Light", "Dark"] },
    "Core": {
      "blue 100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 219,
            "blue": 254,
            "alpha": 1,
            "green": 236,
            "model": "rgb"
          },
          "Dark": {
            "red": 41,
            "blue": 67,
            "alpha": 1,
            "green": 52,
            "model": "rgb"
          }
        }
      },
      "blue 700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "Light": {
            "red": 17,
            "blue": 249,
            "alpha": 1,
            "green": 125,
            "model": "rgb"
          },
          "Dark": {
            "red": 96,
            "blue": 250,
            "alpha": 1,
            "green": 168,
            "model": "rgb"
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "Dark": {
                  "$mode": "dark",
                  "$alias": "Colors.Core.blue 100"
                },
                "Light": {
                  "$mode": "light",
                  "$alias": "Colors.Core.blue 700"
                }
              }
            }
          }
        }
      }
    }  
  }
}

Config

We convert all colors from our SDTF graph in hsl.

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

.specifyrc.json

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

Output

tokens.json

{
  "colors": {
    "$collection": { "$modes": ["light", "dark"] },
    "core": {
      "blue-100": {
        "$type": "color",
        "$description": "token 1 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "model": "hsl",
            "hue": 211,
            "saturation": 95,
            "lightness": 93,
            "alpha": 1
          },
          "dark": {
            "model": "hsl",
            "hue": 215,
            "saturation": 24,
            "lightness": 21,
            "alpha": 1
          }
        }
      },
      "blue-700": {
        "$type": "color",
        "$description": "token 2 aliased with n modes within collection within n groups",
        "$value": {
          "light": {
            "model": "hsl",
            "hue": 212,
            "saturation": 95,
            "lightness": 52,
            "alpha": 1
          },
          "dark": {
            "model": "hsl",
            "hue": 212,
            "saturation": 94,
            "lightness": 68,
            "alpha": 1
          }
        }
      }
    },
    "semantic": {
      "background": {
        "button": {
          "primary": {
            "hover": {
              "$type": "color",
              "$description": "alias token with n modes within collection within n groups",
              "$value": {
                "dark": {
                  "$mode": "dark",
                  "$alias": "colors.core.blue-100"
                },
                "light": {
                  "$mode": "light",
                  "$alias": "colors.core.blue-700"
                }
              }
            }
          }
        }
      }
    }  
  }
}