Open format: how to modify Sketch files programmatically

Last time, we showed you how Monday Studio automated color token generation using a Sketch document as the source of truth. Now, they want to close the loop by automating the opposite task — updating all their design documents when they make changes to the Color Variables in their Library in code.

Automatically updating Sketch documents means no longer worrying about manually syncing your design tokens with tweaks and adjustments made during development (these can happen when solving accessibility issues, or when it’s faster to tweak values in code).

Automatically updating Sketch documents means your design and development teams spend less time wondering if they’re using the same colors, and more time wondering how they can make the product better, faster, or more engaging.

Automatically updating Sketch documents means you’re sure the design team is up to date with the latest changes you checked into your code repository. So you can spend less time guessing, and more time coding.

Requirements

To follow along, you’ll need to be fairly familiar with TypeScript, and have a reasonably recent version of node installed. For code editing, we recommend Visual Studio Code. You don’t need Sketch or a Mac — you can run the sample code on any operating system.

We’ve created a repository with the code for this article, so you can take a look at the finished project. To keep things short, we’ll only cover the more interesting bits of the code, so please refer to the full project for more implementation details.

You can use the repository as a starting point for your own projects by clicking the ‘Use this template’ button on GitHub’s website.

What we’ll build

Today, we’ll write code to read color information from a JSON file. Then we’ll insert that information into an existing Sketch document that Monday Studio’s designers use as a Library.

We’ll use the fromFile function — which we learned about in the previous post — to read the Sketch Library. Next, we’ll modify the data in the document, and then use toFile to write the Sketch Library back to disk.

Below, we’ll go over the repository code, to give you an insight into how it all works.

JSON to Sketch

Here’s the colors.json file Monday Studio uses to store color definitions (find out how to generate this in the previous post):

{
  "Brand/colors.brand.beige.50": "#604a1e",
  "Brand/colors.brand.beige.75": "#aa8d52",
  "Brand/colors.brand.beige.100": "#e0ca9e",
  "Brand/colors.brand.green.50": "#3c5a00",
  "Brand/colors.brand.green.75": "#7b993a",
  "Brand/colors.brand.green.100": "#bbd975",
  "Brand/colors.brand.purple.50": "#420d4c",
  "Brand/colors.brand.purple.75": "#854691",
  "Brand/colors.brand.purple.100": "#c18ccb",
  …
}

First, we load the JSON file as a module and store the values in a sourceColors object to extract color information from. We also create a targetColors object, and populate it with the existing colors in the document:

import sourceColors from '../colors.json'

const targetColors = document.sharedSwatches.objects

Replacing colors in Sketch using code

We can now use the color names to replace colors in targetColors with the new values in sourceColors. We’ll then use targetColors to replace the original swatches in the Sketch file. As we saw in the previous article, Sketch stores colors in RGB format, so we’ll convert them using the hex-rgb library.

Object.keys(sourceColors).forEach(colorName => {
  const colorValue = hexRgb(sourceColors[colorName])
  const swatch = targetColors.find(color => color.name === colorName)
  if (!swatch) return

  swatch.name = colorName
  swatch.value.red = colorValue.red / 255
  swatch.value.green = colorValue.green / 255
  swatch.value.blue = colorValue.blue / 255
  swatch.value.alpha = colorValue.alpha
})
parsedFile.contents.document.sharedSwatches.objects = targetColors

Saving a Sketch file programmatically

And with that, we’re ready to save the Sketch Library using toFile:

const exportableFile: SketchFile = {
  contents: parsedFile.contents,
  filepath: sketchFilePath,
}
toFile(exportableFile)

Running yarn start will run the code in the project, and update the Sketch Library with the colors from the JSON file.

Once we’ve saved the file, chances are we’ll want to automatically commit it to the repository. To do that, we’ve added a GitHub Action to the repository, which runs the code when colors.json file changes, and then commits the resulting file. You can use it as a starting point for more complex automation.

Testing our work

To make sure the code is doing its job, you can change the color of the first item in the JSON file and run yarn start again.

If you then open the color-library.sketch document, you’ll see your new color in the Components View by going to View > Components > Color Variables tab:

Great job — now you know how to modify an existing Sketch document!

Wrapping up

You can use this knowledge for other automation, such as changing the value of text layers or modifying attributes on layers.

If you want to keep exploring, see if you can combine the code in the last two articles to build a solution that keeps your data synced between the JSON and Sketch files.

In the next article in the series, we’ll show you how to create a new Sketch file from scratch, and populate it with data from an external source (in our case, all the icons in the Material Icons repository).