Automating Code Delivery

At this point, you should know how to pick and install an exporter that suits your needs, how to manually export the code, and how to set up the default exporter for your codebase so you can get production-ready code on demand, every time something changes.

But in many settings, the design system pipeline must be automated, usually with some combination of your CI/CD, possibly using Style Dictionary, and also tons of scripts and code to glue it all to work together.

Building and maintaining such a pipeline is a daunting task and will always result in a brittle solution, because the services that provide you the data (such as Figma API, Style Dictionary definitions, and so on..) evolve and change over time, and the potential for breaking is exponentially proportional to moving parts in your pipeline. Worse yet, when you change the underlying tech stack, you usually have to rework a major part of such pipeline.

With Supernova, you don't need to go through the pain of creating and maintaining such a complex system, because we have created a flexible, plug-and-play, end-to-end pipeline for you.

Supernova Design Continuous Delivery (DCD)

Supernova brings the very first Design Continuous Delivery system flexible enough to be "bent" to any situation or technological stack. At the highest level, it works like this:

  • First, you configure an automatic observer that watches for events in the design system

  • Next, you select the exporter you want to run when such change happens

  • Last, you set a delivery URL for the generated code

This configuration is called hook. With the hookin place, the DCD will work fully automatically:

  • Every time the specific event happens inside the design system, your exporter runs

  • Once the exporter finishes, the exported code is delivered to your destination automatically

You are completely shielded from any complicated implementation — you only really care about what you do with the code that the system generates on your behalf.

Configuring Hooks

Configuring hooks can be done by accessing Supernova Cloud > Code Integration > Hooks. To create a new hook, simply click on + NEW button to show the configuration dialog.

You must fill all properties except notify, which is optional (but highly recommended):

  • name represents human-readable name of the hook so you know what is what

  • design system represents a single design system that will be watched

  • event represents the event upon which this hook will be called

  • exporter represents exporter which will run when the event happens

  • notify (optional) represents API URL which should be called when hook finishes

To create a hook and enable it right away, click confirm. If you want to disable the hook, you must delete it using the appropriate option in the hook detail. Lastly, the hook can be updated at any moment just by reconfiguring their properties. Please note that any modification to the hook will be immediately applied and used on the next run.

Event types

Currently, there are two types of events you can watch, with distinct purposes:

Version released

The exporter will run every time a new version of a design system is released. This is a recommended setting when you use Supernova in production environments and you have a more mature design system with semantic versioning, to always keep your codebase up to date with the stable, polished version.

Head changed

With this setting, Supernova will run exporter every time anything changes in your design system, with a short buffer window so you don't get overwhelmed with the updates.

This is useful for cases where you are experimenting with a design system, and you want to be pushing updates constantly to be always up to date with your design system data.

Source updated

The exporter will run every time the source is updated and there is new data, for example, if a Figma file is published.

Do you have a different requirement for what events you want to observe? We would love to hear from you to design it! We will be expanding number of options quickly based on the real use-cases that you will tell us. Join our discord and tell us more!

Code Delivery and payload

The pipeline can work in two ways: With, and without notifying you about the result. When you don't want to consume the code right away and you want to just keep it available to your developers, then notify should be left empty. This will create a build for each run and will keep it securely stored on our servers until you want to access the code.

However, the more useful choice is to be notified that the code was generated and is ready to be used. In this case, you need to provide notify URL which will point to your API that will manage the incoming data.

With notify set, every time the exporter runs (either successfully or with potential error), we will invoke your API and send the following JSON payload through POST:

{
  "event": "job:updated",
  "workspace": {
    "id": "1",
    "name": "Example workspace"
  },
  "designSystem": {
    "id": "2",
    "name": "Example Design System"
  },
  "designSystemVersion": {
    "id": "3",
    "name": "A version name",
    "version": "v0.1"
  },
  "exporter": {
    "id": "4",
    "name": "Example exporter"
  },
  "hook": {
    "id": "5",
    "name": "Example hook"
  },
  "job": {
    "id": "6",
    "status": "Success",
    "logs": [
      {
        "id": "",
        "time": "2021-03-25T16:13:28.804Z",
        "type": "info",
        "message": "Finished exporting source colors.pr"
      },
    ],
    "urls": [
      "https://example.supernova.io/codegen/job-results/2/example-01234567-89ab-cdef/result.zip"
    ]
  }
}

There are several important pieces to this payload:

Hook Configuration

You will get a complete set of the configuration attributes inside the payload, allowing you to precisely identify which event happened, in which design system, and forward the code wherever you want to.

Job

Job describes the result of the run:

  • id uniquely identifies the job / exporter run inside your workspace

  • status results either to Success or Failure

  • logs give you full log of exporter run, using Pulsar logging engine

URLs

If the exporter created code successfully, urls will be provided as well. At this point, there will always be just one link, but we are reserving this option for more flexibility down the road.

The URL links to a secure, signed .zip file that can only be accessed with the URL provided in the payload, containing the structured output of the exporter.

We have made this system so you can consume the data in any form or shape you want - so it is completely possible to forward them to your build pipeline or for example commit to GitHub from your API without us not needing to have access to your repositories. This way, you are always in control.

That being said, we realize not everyone wants to handle the code delivery through their API, and in many cases, it would be possible to push to source control on your behalf. For this reason, we are actively building a way to automatically open pull requests within git repositories. Stay tuned for our announcements during early access.

Using multiple hooks together

If you run a more complex tech stack with multiple platforms, or you have several design systems for different purposes, you can create an unlimited number of hooks with different combinations of exporters / design systems or even delivery URLs. For example, more complex stacks can configure hooks in the following fashion:

  • iOS exporter responding to a new version released of iOS DS

  • Android exporter responding to a new version released of Android DS

  • Both responding to version released of Shared DS

  • Documentation exporter responding to HEAD change

This way Android and iOS both move with stable versions from multiple design systems, however, documentation exporter that exports HTML preview of the available tokens runs immediately after the change, so designers always have the latest preview available to them.

We believe that with this system, you can get extremely creative and ultimately efficient. And to give you full control over how to export the data, the next part of this documentation will walk you through the creation and anatomy of the exporters, so you can build any export and code generation task you want if you have specific needs not available on the Exporter Store.

Last updated