{"id":13528250,"url":"https://github.com/Yelp/salsa","last_synced_at":"2025-04-01T11:31:12.912Z","repository":{"id":56922038,"uuid":"125931028","full_name":"Yelp/salsa","owner":"Yelp","description":"A tool for exporting iOS components into Sketch 📱💎","archived":false,"fork":false,"pushed_at":"2023-03-24T10:51:00.000Z","size":318,"stargazers_count":61,"open_issues_count":4,"forks_count":7,"subscribers_count":8,"default_branch":"master","last_synced_at":"2025-03-12T22:35:48.130Z","etag":null,"topics":["cocoapod","design-systems","design-tools","ios","sketch","yelp"],"latest_commit_sha":null,"homepage":"","language":"Swift","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Yelp.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2018-03-19T22:58:19.000Z","updated_at":"2024-12-30T18:59:25.000Z","dependencies_parsed_at":"2024-01-13T22:33:29.714Z","dependency_job_id":null,"html_url":"https://github.com/Yelp/salsa","commit_stats":{"total_commits":13,"total_committers":4,"mean_commits":3.25,"dds":"0.23076923076923073","last_synced_commit":"baa75b628dfc5c21a4e0653595f5e0ed2f93b924"},"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fsalsa","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fsalsa/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fsalsa/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Yelp%2Fsalsa/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Yelp","download_url":"https://codeload.github.com/Yelp/salsa/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246631805,"owners_count":20808760,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cocoapod","design-systems","design-tools","ios","sketch","yelp"],"created_at":"2024-08-01T06:02:21.361Z","updated_at":"2025-04-01T11:31:11.947Z","avatar_url":"https://github.com/Yelp.png","language":"Swift","funding_links":[],"categories":["Swift","Sketch"],"sub_categories":["Handoff"],"readme":"[![Carthage compatible](https://img.shields.io/badge/Carthage-compatible-4BC51D.svg?style=flat)](https://github.com/Carthage/Carthage)\n[![CocoaPods Compatible](https://img.shields.io/cocoapods/v/Salsa.svg?style=flat)](https://img.shields.io/cocoapods/v/Salsa.svg)\n\n## What is Salsa?\nSalsa 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.\n\n## How it works\nRunning 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.\n\n### Why two steps?\nCertain 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.\n\n# Installing Salsa\n### Cocoapods\n```ruby\npod 'Salsa'\n```\n\n### Carthage\n```ruby\ngithub 'Yelp/salsa'\n```\n\n### Homebrew\n```bash\nbrew tap yelp/salsa\nbrew install salsa\n```\n\n# Using Salsa\n```swift\nimport Salsa\n```\n##### Converting a view to a [Sketch Group](https://www.sketchapp.com/docs/grouping/groups/)\n```swift\n// Configure the export directory\nSalsaConfig.exportDirectory = \"/some_directory\"\n\n// Convert a view into a group\nlet myGroup = myView.makeSketchGroup()\n```\n##### Putting a group into a sketch document and exporting to a salsa file\n```swift\n// Create a page containing the generated group, and insert it into a Document\nlet document = Document(pages: [Page(layers: [myGroup])])\n\n// Export the document to disk\ntry? document.export(fileName: \"my_file\")\n```\n\n##### Converting a salsa file to a sketch file\nIn your terminal of choice run the following:\n```bash\n$ salsa -f /some_directory/my_file.salsa -e /some_directory/my_file.sketch\n```\n\n## Creating a Sketch file documenting your standard UI elements\nWe provide some helpers to help you document your elements out of the box. You organize examples of your views into an [Artboard](https://www.sketchapp.com/docs/grouping/artboards/) by conforming your view class to [`ArtboardRepresentable`](https://yelp.github.io/salsa/Protocols/ArtboardRepresentable.html).\n```swift\nextension View1: ArtboardRepresentable {\n  static func artboardElements() -\u003e [[ArtboardElement]] {\n    ...\n  }\n}\n```\nIf you would like to also create [Symbols](https://sketchapp.com/docs/symbols/) of your views to go along with the generated Artboards you can instead conform your views to [`SymbolRepresentable`](https://yelp.github.io/salsa/Protocols/SymbolRepresentable.html).\n\n```swift\nextension View2: SymbolRepresentable {\n  static func artboardElements() -\u003e [[ArtboardElement]] {\n    ...\n  }\n}\n```\nCreate your Artboards and Symbols from these [`ArtboardRepresentable`](https://yelp.github.io/salsa/Protocols/ArtboardRepresentable.html)  and [`SymbolRepresentable`](https://yelp.github.io/salsa/Protocols/SymbolRepresentable.html) views\n```swift\n// Configure the export directory\nSalsaConfig.exportDirectory = \"/some_directory\"\n\n// Generate the artboards and symbols\nlet artboardsAndSymbols = makeArtboardsAndSymbols(from: [[View1.self], [View2.self]])\n\n// Put the artboards and symbols onto their own dedicated pages\nlet artboardPage = Page(name: \"Artboards\", layers: artboardsAndSymbols.artboards)\nlet symbolPage = Page(name: \"Symbols\", layers: artboardsAndSymbols.symbols)\n\n// Create a document with the generated pages and export it\nlet document = Document(pages: [artboardPage, symbolPage])\ntry? document.export(fileName: \"my_file\")\n```\n\n## Example Project\nCheck out the Example project to see how Sasla can be used in production. The Example app uses a test target to generate Sketch files without manually launching Xcode.  \n\nTo generate a Sketch file for the Example project run the following after cloning the repo:\n```bash\ncd Example\npod install\n./generate_sketch\n```\nThis should create a new file called `ExampleSketch.sketch` inside the project directory\n\nOpen up [`generate_sketch`](https://github.com/Yelp/salsa/blob/master/Example/generate_sketch) with a text editor to see how this is done.\n\n## Documentation\nFor a full breakdown of the Salsa API [check out the docs](https://yelp.github.io/salsa/index.html)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYelp%2Fsalsa","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FYelp%2Fsalsa","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FYelp%2Fsalsa/lists"}