hubble-scripts

Scripts repository to export design data like colors, fonts & text, and map them to design tokens.

The backbone of the Hubble ecosystem, this scripts repository exports design data like colors, fonts & text, and maps them to JSON design tokens to integrate in your applications. This repository is an attempt to further automate design systems & tooling at In The Pocket. Assets can also be exported as platform-friendly PNG & SVG formats.

Contents

• Prerequisites
• Installing
• Usage
• Contributing
• License

Prerequisites

For parsing Sketch:

• A recent bash version ([email protected] recommended)
• macOS with Sketch 60+ (latest Sketch recommended)

For parsing Figma:

• A Figma access token

For parsing Adobe XD:

• Recent version of Adobe XD

Installing

The easiest way to install is to download one of the releases and download the hubble-cli binary. This can be executed by most shells and will only output design tokens.

Sketch

If you're looking to also export assets for Sketch, download sketchtool.sh, which is a shell script wrapper around Sketch's sketchtool binary.

Usage

There is a sample .sketch file, .xd file and Figma file ID in the mocks folder with sample output that would be generated for this file.

hubble-scripts works best with a separate Sketch, Figma or Adobe XD library file. Take a look at the examples and short bits below, or refer to our the relevant documentation for your design tool.

Generating JSON config

You can use the hubble-cli binary to export design data out of your file and map it to a generic JSON design token format.

# This will generate a `hubble-data.json` file with text styles & colors found in a Sketch document:
$ ./hubble-cli "__mocks/sketch/sample_sketchfile.sketch"
$ ./hubble-cli --token "29-206..." HbgJuBVOwIOcoZMVnpG01LqA

# You can optionally specify a config output dir. Otherwise current working directory will be used:
$ ./hubble-cli "__mocks/sketch/sample_sketchfile.sketch" --outputDir="/var/hubble/"
$ ./hubble-cli "__mocks/sketch/sample_sketchfile.sketch" --outputDir="/var/hubble/"

If you need more fine-tuning over this export flow, Hubble provides even more options to customize your design token output.

Style Dictionary

hubble-scripts supports a variant on our default generic design tokens, which is compatible with the Style Dictionary build system. By taking advantage of Style Dictionary's structure, we can slot in their existing transformers to output to various platforms or languages.

For more information on our Style Dictionary output, check the wiki.

Exporting assets

Sketch

Assets can be exported using the sketchtool.sh script. This process exports all layers marked as exportable or that have been sliced.

# This will export normalized (lowercase, underscore) assets as SVG (for web) and PNG (1x, 2x, 3x for native)
$ ./sketchtool.sh "__mocks/sketch/sample_sketchfile.sketch"

# You can optionally specify an asset output dir. Otherwise current working directory will be used:
$ ./sketchtool.sh "__mocks/sketch/sample_sketchfile.sketch" "/var/hubble/assets/images"

Figma

TODO:

Adobe XD

Please see the Caveats

Integrating in a project

Copy hubble-cli and sketchtool.sh to a scripts folder in your project. This example uses npm run-tasks to describe the export flow:

{
  "scripts": {
    "hubble:tokens": "./scripts/hubble-cli ...",
    "hubble:assets": "./scripts/sketchtool.sh ...",
    "hubble": "npm run hubble:tokens && npm run hubble:assets"
  }
}

Contributing

❤ We appreciate every form of contribution, but before you contribute please make sure you have read the contribution guidelines

Development

hubble-cli is a compiled binary of cli.js, a Node.js CLI wrapper around our index.js script. If you have Node you can run this script directly:

$ node cli.js --help

  Usage
    $ hubble-cli <input> [options]

  Options
    --outputDir=<dir>, -o           The directory where parsed files will be placed after a run. Defaults to current working directory.
    --useStyleDictionaryOutput, -s  Generate Style Dictionary compatible output instead of the generic design token format.
    --dump, -d                      Generate a raw JSON dump from your design parser, before Hubble exports its tokens

  Options: Sketch
    --useColorArtboards             Use artboard formatting to export colors instead of using the document colors.
    --useGradientArtboards          Use artboard formatting to export gradients instead of using the document gradients.
    --ignoreTextStylePaths          Textstyles that use slashes to enable navigation in Sketch will be ignored
                                    and their id will be the first part of the path.

  Options: Figma
    --token, -t                     Authorization token when accessing the Figma API.
    --exportAssets, -e              Export assets from Figma.

  Examples
    $ hubble-cli "__mocks/sample_sketchfile.sketch"
    $ hubble-cli "__mocks/sample_sketchfile.sketch" -d --useColorArtboards --outputDir="config/"
    $ hubble-cli --token "29-206..." HbgJuBVOwIOcoZMVnpG01LqA
    $ hubble-cli --token "29-206..." HbgJuBVOwIOcoZMVnpG01LqA --useStyleDictionary

For more on running in development mode, check the [wiki].

License

MIT