gettengineering / prism

Gett's Design System code generator. Use Zeplin Styleguides as your R&D's Single Source of Truth.

Prism is a Design System code generator developed by the team at Gett 🚕.

Synchronizing design teams with engineering teams is a huge challenge.

As teams scale, new growing pains start around how to properly align colors, text styles, spacing and other design details between teams, in a uniform way, from a single source of truth.

Prism was built to solve this very problem! It takes either Zeplin project/styleguide or a set of Figma files as input, and generates any output code you want from these based on a set of templates in your project, resulting in cross-platform code that is always synchronized from a single source-of-truth (Your design files).

Prism is especially useful when used in your CI/CD process to remove the friction of design handoff and review, and making sure all of your teams are properly synchronized in regards to naming, values, and more.

Getting Started

📹 Videos

• A 60 seconds introduction to Prism
• Design a Design System @ Swift Heroes, Italy (25 minutes)

🌈 Getting Prism

There are five options to install prism:

1. Install with Homebrew: brew install GettEngineering/tap/prism
2. Install using Mint: mint install GettEngineering/Prism
3. Build from source: make install
4. Run directly with SPM: swift run prism generate
5. Running on Windows (experimental)

🔑 Getting a Provider API Token

Figma

To use Prism with Figma, you'll need to generate a Personal Access Token (JWT) to Figma's API by going to https://www.figma.com. Then, go the Settings section under your profile:

Scroll to the bottom of the Account tab, find the Personal access tokens section, and create your new token:

You'll need to expose this token to run the prism CLI tool. Make sure you have a FIGMA_TOKEN environment variable with your token configured.

When running prism in a CI environemnt, we recommend adding FIGMA_TOKEN as an Environment Secret.

When using prism locally or bootstrapping your project for the first time, you can simply run export FIGMA_TOKEN='zeplin_personal_token' before running prism locally.

Zeplin

To use Prism with Zeplin, you'll need to generate a Personal Access Token (JWT) to Zeplin's API by going to https://app.zeplin.io/profile/developer and click the Create new token button in the Personal access tokens section:

You'll need to expose this token to run the prism CLI tool. Make sure you have a ZEPLIN_TOKEN environment variable with your token configured.

When running prism in a CI environemnt, we recommend adding ZEPLIN_TOKEN as an Environment Secret.

When using prism locally or bootstrapping your project for the first time, you can simply run export ZEPLIN_TOKEN='zeplin_personal_token' before running prism locally.

👢 Bootstrap Prism for your Project

Inside your project folder, run prism init.

It will guide you through selecting a Zeplin project/styleguide, or a set of Figma files as source along with other useful information for proper code generation. Once prism init is successful, you'll find a new .prism folder with a config.yml file outlining your preferences.

🎨 Creating Templates

Prism uses templates with the .prism suffix located in your project's .prism folder. These Prism templates are basically plain text files — Prism doesn't really care what format or language you use, it can make any kind of output as long as you can express it in a Prism template file.

Prism looks for something called Tokens inside your templates. These tokens follow the following format: {{%token%}}. You can find a couple of sample templates in the Examples folder.

Here are two short example of generating colors code for iOS and Android using Prism templates.

Colors.swift.prism:

colors.xml.prism:

Development

• Run make or make install to build a release binary of the prism CLI tool and install it to /usr/local/bin.
• Run make build to build a release binary of the prism CLI tool
• Run make project to create an Xcode project and start working.
• Run make test to run all tests.
• Run make clean to clear the generated Xcode project.

prism's Issues

Link to a detached Styleguide without a project

With the introduction of sectioned projects, there is a very valid use-case of companies that use a project-per-feature and a single base style guide.

In these scenarios, using Prism with a single Project ID is subpar.

We should support using a Styleguide ID, instead of a Project ID, for these specific use-cases.

This would be an if/or scenario, e.g. - you can either use Prism with a Styleguide, or a Project, but not both (which makes sense)

Ignore style guide ids

Hi,

@freak4pc asked if I wanted to open an issue discussing implementation see #46

We want to be able to not fetch certain style guides, in our workspace we use the same naming in multiple style guides. Because of this, we want to be able to skip the fetching of certain style guides.

Thanks!

Rounding of letter spacing

Here is my text style in Zeplin:

Here is generated code for the style:

static let searchBarPlaceholder: TextStyle = {
        let style = TextStyle()
        style.font = .SFProText-Regular(ofSize: 17.0, weight: .semibold)
        style.kerning = -0.408
        style.color = .additional1d
        style.lineHeight = 22.0
        return style
}()

I guess there are some hidden rules of rounding. I use this logic for code generation. What do you think? Should Prism update digit values from Zeplin?>

Template Loops and last/first line emit

Really love the simplicity of the templating language. I was trying to emit some JSON with it, which unfortunately does not allow trailing commas.

For example, this template

{
  {{% FOR color %}}
  "{{% color.identity.camelcase %}}": "{{% color.rgb %}}",
  {{% END color %}}
}

emits

{
  "black": "#000000",
  "white": "#ffffff",
}

So the trailing comma in the penultimate line is a problem. Do you have any idea how this could be solved?

Text Style "properties" not exposed as tokens or missing

Thanks @freak4pc for making it possible to test Prism on our project without text style colors. I really like the simplicity of it.

I notices the following font styles are not exposed as tokens:

• font_weight
• font_style
• font_stretch

all but the last one are in the model and apparently not even optional in the API.

HTTP 404 during `prism generate`

Thank you for the amazing tools!!

I face the error below if I use the first project, any other project working fine.

The first project related to the design system and it contains colors, style guides, and spacing.

Appreciate your support

Support line spacing

Hi! Thanks for this super helpful tool!

I'm currently building templates for an Android app. In Zeplin the line height is defined for some of our text styles (e.g. 18.2) with a text size of e.g. 15. To configure this in Android we need to have the "line spacing extra" being 3.2 in this example (18.2 - 15).

It would be great to do something like {{% textStyle.lineHeight - textStyle.fontSize %}} or a similar syntax.

Failed decoding Array<TextStyle>

I'm getting the following output. Do you have any advice for me?

 prism generate
❌ Error: Failed decoding Array<TextStyle>

xib Support

Hi,
Can the Prism TextStyle be used within a xib / storyboard?

Styleguide Trees

Are there plans to support Zeplin Global Styleguides and Styleguide trees with parent‑child relationships?

Allow installing via Homebrew

Hello, guys! At first, thanks for the tool! It looks useful and solid, especially for syncing. BTW, I use Zepcode, Zeplin extension for Swift code snippets, but extensions have no logic for syncing. Anyway, I tried to install Prism with attached release, but have two errors

• “prism-macOS.dms” cannot be opened because it is from an unidentified developer.. Classic security error.
• The contents of "prism-macOS.dms" cannot be extracted with The Unarchiver after allowing to install the package.
  It's not convenient to download and build Prism from sources, especially for new releases. Are you going to add Homebrew support?

Prism in-app "Hot Reload"

Hi,
I was wondering to know if there is the possiblity to allow Prism to automatically download the updated colours/font/whatever file directly from Zeplin even when the application is live.

USE CASE:

1. I released on the store the myApp v:1.0.0 where all my button are blue
2. I change the buttonColor inside the Zeplin board from blue to green
3. The very next time I open myApp it automatically download the new colour file and magically all my buttons turns to green.

In my understanding at the moment this is not possible, because I have to manually generate the colours file from the console and then later add it in my Xcode project.

Is it correct ?

Thank you very much!

FontName SnakeCase for Android compatibility

Hi @freak4pc!

Nice work so far!
Just found something that's annoying me
At the Examples/Android folder for textStyles it's using:

<item name="android:fontFamily">@font/{{% textStyle.fontName|lowercase|replace(-,_) %}}</item>
On that part it's using the transformation lowercase and replace but when I run the prism generate I get an error ❌ Error: There is no transformation called 'replace(-,_) ' or lowercase if I delete that transformation.
Is there something I'm missing? Do you think it make sense to add the snakecase token for this property also?
Cheers

That one color.a edge case

Now that you introduced inverting conditionals, the alpha component of the color token has come to my attention. In most cases, when it is 1.0, it can be ignored. Unfortunately if it is not, one might need a different emit. For example color.rgb vs color.argb.

Do you think it would make sense to allow to use a conditional on color.a?

In one possible implementation this could be {{% IF color.a %}}. This would match all but 1.0. Which i can see, might be confusing. As the value would cast to the opposite. Alternatively maybe

• {{% IF color.hasAlpha %}}
• {{% IF color.isOpaque %}}
• {{% IF color.a == 1.0 %}}

The latter probably being the most complicated to implement and just opening a completely different can of worms.

Sorry for bombarding you with issues.

Can Prism create ful UI layouts in XML ?

I am wondering if Prism can download full screen and convert them into xml ? Or could you point to where can I find it in the docs? Thanks :)

Support == and != operands

Based on discussion in #31, it could be nice to support basic operands of equality and inequality for tokens, e.g. :

{{% IF color.alpha == 1.0 %}}

This could have potentially a bunch of edge-cases with numerics, etc, but still worth thinking over and experimenting with.

textStyle.fontSize does not roundedToNearest

I notices some tokens output floats, where others seem to look like integer.

• textStyle.fontSize gives a float
• where textStyle.lineHeight appears to be an integer

in some emitted languages one or the other might not be desirable, or will have to be specified. On further inspection i than noticed that roundToNearest always produces a float. So i assume that by not having any decimal places, it did not appear as one in the emit. This is already quite ideal for languages that don't need that . to specify the type.

Would it be possible for fontSize to be consistent with that rounding? Or do you think different emits would be needed.

I see that it would be nice to keep it rather simple.

Thanks for creating this great project.