convert-color

This parser helps you convert the color formats of color compatible tokens over a SDTF graph.

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	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.

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