What is Salsa?

Salsa is an open source library that renders iOS views and exports them into a Sketch file. We built Salsa to help bridge the gap between design and engineering in an effort to create a single source of truth for visual styling of UI.

Why use Salsa

A few years ago, we started putting together a library of common components that developers and designers could use to build features. Initially, we had to manually maintain consistency between the designs in Sketch and their implementations in code. When we only had a handful components, this wasn’t difficult to maintain. However, as the library grew, it became increasingly difficult to keep the code and Sketch files in sync with one another.

Salsa allows us to ensure that designers and developers always have access to the exact same components. One of the unique advantages of Salsa is that it does not require Sketch to be installed on the machine it’s running on, enabling us to integrate Salsa into our continuous integration flow and generate a new master Sketch file any time a code change is made to the styleguide repository.

Salsa also allows us to create lots of permutations of the same component without any additional effort. We can even include loading states when generating components.

How it works

Running Salsa inside of an iOS simulator will output two things into a specified directory: a .salsa file and an images folder. You can then pass these two inputs into the salsa command line tool to compile them into a .sketch file.

Why two steps?

Certain macOS-only APIs need to be used to encode text for .sketch files. Having two steps allows us to define our own intermediate file format that’s easier to work with than the full sketch file format. This means we can leverage this file format in the future if we want to expand this tool for other platforms. If you want to create your own .salsa file, you can check out the schema here

Installing Salsa

pod 'Salsa'

brew tap yelp/salsa
brew install salsa

Using Salsa

import Salsa

Converting a view to a Sketch Group

// Configure the export directory
SalsaConfig.exportDirectory = "/some_directory"

// Convert a view into a group
let myGroup = myView.makeSketchGroup()

Putting a group into a sketch document and exporting to a salsa file

// Create a page containing the generated group, and insert it into a Document
let document = Document(pages: [Page(layers: [myGroup])])

// Export the document to disk
try? document.export(fileName: "my_file")

Converting a salsa file to a sketch file

In your terminal of choice run the following:

$ salsa -f /some_directory/my_file.salsa -e /some_directory/my_file.sketch

Creating a Sketch file documenting your standard UI elements

We provide some helpers to help you document your elements out of the box. You organize examples of your views into an Artboard by conforming your view class to ArtboardRepresentable.

extension View1: ArtboardRepresentable {
  static func artboardElements() -> [[ArtboardElement]] {
    ...
  }
}

If you would like to also create Symbols of your views to go along with the generated Artboards you can instead conform your views to SymbolRepresentable.

extension View2: SymbolRepresentable {
  static func artboardElements() -> [[ArtboardElement]] {
    ...
  }
}

Create your Artboards and Symbols from these ArtboardRepresentable and SymbolRepresentable views

// Configure the export directory
SalsaConfig.exportDirectory = "/some_directory"

// Generate the artboards and symbols
let artboardsAndSymbols = makeArtboardsAndSymbols(from: [[View1.self], [View2.self]])

// Put the artboards and symbols onto their own dedicated pages
let artboardPage = Page(name: "Artboards", layers: artboardsAndSymbols.artboards)
let symbolPage = Page(name: "Symbols", layers: artboardsAndSymbols.symbols)

// Create a document with the generated pages and export it
let document = Document(pages: [artboardPage, symbolPage])
try? document.export(fileName: "my_file")

Give it a Try

The source code for Salsa is available on github at https://github.com/yelp/salsa. If you’d like to contribute feel free to send us a pull request. We’re excited to see what kinds of cool things we can build together using Salsa!

Back to blog