dylanslewis / stylesync

A command line tool to extract shared styles from a Sketch document, and generate native code for any platform.

Welcome to stylesync, a command line tool that extracts text and colour styles from a Sketch document, and generates native code for your project's platform, language and style.

Why?

A unified design system is essential to building better and faster; better because a cohesive experience is more easily understood by our users, and faster because it gives us a common language to work with.

Karri Saarinen, Airbnb

A design system is vital resource for any product that values a consistent experience for users across platforms. Unfortunately maintaining a design system in code is a cumbersome process, since changes may be subtle and the time required for developers to maintain styles is not always respected by businesses. Tools like Zeplin allow a one off export, but don’t help with maintainability and often lead to design debt.

stylesync automates the generation and maintenance of a design system in code, using your project's preferred code style.

This means your Sketch file can be a single source of truth for your brand’s identity, created and maintained by designers, leaving developers to get on with the actual implementation of interfaces using these styles.

Features

Template-based exports

stylesync exports code based on templates, which means you can export code that matches your project's platform, language and style.

The template files look very similar to the exported code, except placeholder values are denoted using a simple templating language, e.g. <#=hex#>. The Templates README contains more information on templates, with links to some examples.

Continuous integration

stylesync works best when used as part of a CI system. The tool can branch, commit, push and raise pull requests for any changes that occur, showing a clear breakdown in the pull request's description. This makes sure your styles are always up to date with the latest version of your design system.

Project maintenance

Style names can change, so in addition to updating your style guide code, stylesync also updates any references to those styles anywhere in your project. This makes sure your project doesn't break as a result of changes made by designers.

Deprecation

No project is completely up to date with the designs, and there might come a time when a style is removed from the design system but still exists in your project. stylesync handles this gracefully by keeping the removed style in code, but deprecating it so you can start thinking about removing it. Once stylesync finds no more references to the deprecated style, it will be removed from the generated code.

Installation

You can install stylesync using the Swift Package Manager:

$ git clone https://github.com/dylanslewis/stylesync.git
$ cd stylesync
$ swift build -c release -Xswiftc -static-stdlib
$ cp -f .build/release/stylesync /usr/local/bin/stylesync

How to use

Before using stylesync, you’ll need to create a text style template and color style template. The Templates README contains information on how to create a template, and links to some examples.

After creating your template, you can run stylesync from your project’s root directory and you’ll be taken through a set up wizard. Once completed, a stylesyncConfig.json file will be saved, so next time you can simply run stylesync.

Sample project

See stylesync in action in this small sample project, which showcases a design system in a simple iOS app. It’s already set up with templates and a stylesyncConfig.json file, so you can just run stylesync to see how it works!

Contributions

A tool that improves collaboration between designers and developers should be available to everyone for free, which is why stylesync is open source.

If you find a bug or want to add an interesting feature, feel free to raise an issue or submit a pull request.

Just note that you'll need to run swift build to install the dependancies if you want to use the Xcode project.

License

stylesync is available under the MIT license. See the LICENSE file for more information.

stylesync's Issues

Sketch v48 text style colours are not parsed

The format has changed from a 64 bit representation to a dictionary of RGBa. Since a pre-version 48 file saved in version 48 doesn't update the representation unless a change occurs,stylesync will need to handle both representations simultaneously.

Line heights with default values aren't handled well

When a default line height is used in Sketch, stylesync currently exports that line height as 0. While some platforms understand this as the default value, it causes issues with line spacing multiplier and line spacing extra calculations.

To get the default value, the text style could be parsed as an NSFont, at which point the correct default value can be extracted.

Issue when creating a style with the same name as an existing style

This results in two styles: one deprecated and one normal.

To avoid this, just check the exported styles for those with the same name, and give preference to undeprecated styles.

Add a `CONTRIBUTING.md` file

Will need to come up with a set of repository guidelines.

Support namespacing of text style names

To get around Sketch's strict limitation of one alignment and colour per text style, some Sketch projects are set up with text styles that may look like this:

• TextStyle1/Left/White
• TextStyle1/Centre/White
• TextStyle1/Right/White
• TextStyle2/Left/White
• TextStyle2/Centre/White
• TextStyle2/Right/White

There should be a parameter to treat these namespaced text styles as the same style, so that only TextStyle1 and TextStyle2 would be exported.

The issues that need to be resolved are:

• Checking that all namespaces styles share the same other variables, e.g. make sure TextStyle1/Left/White has the same point size as TextStyle1/Centre/White.
• Which identifier to use? There will be multiple identifiers for each style, and between runs of stylesync there may be identifiers added or removed. It's vital that stylesync has a persistent reference to a style's identifier

When a style name is contained in the name of another variable, it gets erroneously updated

To fix this, make this conditions for replacement better than just replaceOccurrences. One option could be to look at the characters around an occurrence, and make sure that the characters before and after are both in NSCharacterSet.alphanumeric.

Add more sample templates

Add more sample templates in more languages and more platforms, including:

• ReactNative
• CSS
• Swift (macOS)
• Objective-C (iOS)
• Objective-C (macOS)
• Kotlin (Android)

The barrier to this right now is an Int-based font weight, which is available from NSFontManager.weight(of:.

Avoid attempting to raise a pull request if nothing has changed

The definition of 'nothing has changed' is:

• no styles have changed
• the exported code has not changed

Therefore, it is not possible to just compare the versions of the exports, and the actual content of the template needs to be looked at too.

Show any warnings generated in the pull request

All warnings currently go through ErrorManager, so it would be pretty simple for that object to keep a reference of all warnings generated in this session, and show them in the pull request for extra clarity.

Support organisation name prefix

Prefix all exported text styles with the given organisation name

Support Sketch v53

Named colours are now supported in Sketch, so add this support to stylesync.

This may allow #42 to be closed.

Add Swift Lint

This could be a little tricky due to the Xcode project being able to be re-generated at any time.

Refactor `StyleExporter.swift`

It's far too big, and should be split up into more decoupled components.

Add a `VISION.md` file

Talk about the long term goals of the project, which at a very coarse level are related to the generation and maintenance of design systems across various platforms.

Allow exporting text styles that use non-shared colours

Currently a text style can only be exported if it uses a design system colour, which can be limiting. Allow the template to export raw colours too.

Only commit updated files

Currently when committing files, stylesync uses git commit -a which commits all changed files. This can cause problems if stylesync is not being run from a CI, since the user may have other unstaged changes. stylesync should commit all files that have been updated (can get this when iterating over every file in the project and tracking updated files) and also the generated files.

A more precise method has been created ShellOutCommand.gitCommitWithoutAdding, but is not currently in use.

Add iconography support

Similar to #35, this is difficult to do from Sketch, but would be well supported from Lona. For Sketch, a tag could potentially be added to an image, but this doesn't handle the problem of shapes drawn within Sketch.

Issue when renaming a style to an existing styles name

Scenario:

Heading Style
Title Style

Heading Style is renamed to Title Style, Title Style. is renamed to Something Else.

The export is:

Something Else
Something Else

This is because Heading Style is updated to Title Style, and then both instances are renamed to Something Else.

Update to Version 49 API

Relevant changes to stylesync in text style definition:

• NSParagraphStyle is renamed to paragraphStyle
• NSKern is renamed to kerning

Support multiple file exports

Some projects may require multiple files to be exported, so stylesync should allow an array of templates to export, rather than just a single file.

Add Danger

Initial implementation could just look at Swift Lint rules, but more can be added.

Support Sketch v50 text styles

Text styles are no longer encoded as 64 bit strings, and are now dictionaries, e.g.:

"MSAttributedStringFontAttribute": {
	"_class": "fontDescriptor",
	"attributes": {
		"name": "DINAlternate-Bold",
		"size": 16
	}
},

This is a great step forwards, because Sketch v50 files can now be parsed without Cocoa, meaning stylesync can run on Linux if support for v50 is added. 🎉

This should just be a case of updating the Font type within SketchDocument. Since simply saving a v50 Sketch file updates the encoding now, it should be possible to remove support for pre v50 Sketch files. For users of Sketch pre v50, they can always install an earlier release of stylesync.

Current failing tests:

• testSketchFileWithOneTextStyleIsParsedCorrectlyPostVersion49
• testSketchFileWithFiveTextStylesAndFiveColorStylesIsParsedCorrectlyPostVersion48
• testSketchFileWithFiveTextStylesAndFiveColorStylesIsParsedCorrectlyPostVersion49

Paths with spaces are not handled well

Steps to reproduce:

• Create a Sketch file with spaces in the file name
• Start the stylesync wizard
• For the Sketch file, attempt to reference the Sketch file

Expected behaviour:

• Wizard recognises Sketch file and continues

Actual behaviour:

• Wizard claims the path is invalid

Extract styles from more inputs

There are more tools emerging for creating a design system in a separate app to Sketch, so stylesync should become more versatile in the type of inputs it can handle, including:

• Lona
• InVision DSM
• Figma

Lona stores styles as simple JSON files, so it should be pretty easy to parse all the information. It may even be worth raising a PR to Lona once this is implemented, since its code generation feature is still very nascent.

Create a JIRA ticket when raising a pull request

If a pull request is going to be raised, then a JIRA ticket should also be raised so that the updated styles can be tested by QA after the pull request has been merged.

The required information to collect from the config file is:

• OAuth token
• Board name
• Initial status (most likely some 'In Review' equivalent)

After creating the ticket, the pull request can then have the ticket reference in the title, rather than [stylesync] (which can still be used as a fallback if the user doesn't want to raise a JIRA ticket.)

This could potentially be done as a separate Swift framework, which just accepts these configuration variables as parameters. The dependancy to that framework can then just be added to Package.swift.

Add MIT license to all file headers

Add to all existing files, and also add an Xcode template to add it to all existing files, using https://github.com/mattt/Xcode-Licensed-Templates.

Check if this will cause any issues with SPM, since the project can be regenerated at any time.

Generate before and after screenshots

To aid the testing of the generated pull request, stylesync should get before and after screenshots of the key screens. This will require a special UI test, written by the user, which traverses the app and takes screenshots using XCAttachment, e.g.:

let screenshot = self.screen.screenshot()
let attachment = XCTAttachment(screenshot: screenshot)
attachment.lifetime = .keepAlways

To avoid generating hundreds of screenshots, the Xcode project should not take automatic screenshots, since this tends to generate lots of duplicates.

stylesync would first run this test on a 'beforeBranch' and then again on an afterBranch. The screenshots would all be saved in Derived Data and would need to be uploaded to GitHub. Unfortunately you can't programatically upload images to an issue, so it may need to upload to a dedicated repository, the same way that fastlane handles storing your certificates.

The config would need to following attributes:

• Test suite
• Test case
• Test name
• Derived data location
• Repository name? (could automate this)

Similar to #16 this should be done as a separate Swift Package, since it solves a general problem so should be well separated (e.g. you could use this for translation update screenshots).

Add button support

This is a bit difficult from Sketch, since it doesn't have a very good template for button symbols well defined within the format. It might be better suited to exports from Lona or InVision DSM, although a Sketch extension could be used to define this type.

Buttons are also much more difficult to have a one-size-fits-all approach for templates, since there are many different types of button, including:

• Text
• Image
• Borders
• Element placement
• Highlighting behaviour

Pull request errors are not always shown

When GitHubPullRequestManager.swift makes a URL request to raise a pull request, if the response has an error status code, but no actual error contained, then stylesync currently ignores this.

Instead it should look at the response, and inform the user of any issues if the response has an error status code.

Allow exporting to more outputs

Whilst templating works well for single files to be exported, they are not a good fit for exporting to file formats that have lots of other information in the same file. Update stylesync to allow exporting to:

• Sketch
• Figma
• InVision DSM
• Xcode 9 assets catalogue
• Lona

When combined with #23, this should allow much more flexibility in the use of stylesync.

Allow all config values to be passed as arguments

Also allow a mix of the two, e.g. if you have an open source project you can't keep the GitHub personal access token in the config file.