Skip to content
Convert Storybook into Sketch symbols πŸ’Ž
JavaScript
Branch: master
Clone or download
Pull request Compare This branch is 53 commits behind chrisvxd:master.
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
src
.babelrc
.eslintignore
.eslintrc
.gitignore
.prettierignore
.yarnrc
CHANGELOG.md
LICENSE
README.md
commitlint.config.js
package.json
webpack.config.js
yarn.lock

README.md

story2sketch πŸ’Ž

Convert Storybook stories into Sketch symbols.

Uses the amazing and experimental html-sketchapp. Only supports web.

Quickstart

Firstly, get Sketch and npm. Then install asketch2sketch.sketchplugin into Sketch:

Installing Sketch plugin

Install story2sketch:

npm i story2sketch -g

Now navigate to your Storybook 3.3.x project. You'll want to take full control of your Storybook webpack.config.js if you haven't already done so, adding:

module.exports = (storybookBaseConfig, configType) => {
  const newConfig = {
    ...storybookBaseConfig
  };

  // Add this:
  // Export bundles as libraries so we can access them on page scope.
  newConfig.output.library = "[name]";

  return newConfig;
}

Manually export the getStorybook function in your ./config/storybook/config.js file:

import { getStorybook } from "@storybook/react";

...

export { getStorybook }

Run story2sketch, pointing towards a Storybook iframe URL. See configuration for more options, or if you have a lot of stories.

story2sketch --url https://localhost:9001/iframe.html --output stories.asketch.json

Import the generated file into Sketch via Plugins > From *Almost* Sketch to Sketch in Sketch menu bar.

Using sketch plugin

Success!

Why?

As stated by react-sketchapp, it's complicated to manage assets in a design system. Many teams building design systems or component libraries already produce Sketch files for distributing designs and use Storybook to prototype and present the developed components. It can become difficult to keep designs up to date with the latest components, with designers ever playing catchup. story2sketch generates a Sketch file from your components via Storybook, so your Sketch designs always stay up to date.

Configuration

You can configure story2sketch using the API via the CLI, configuring your package.json or adding a story2sketch.config.js file.

CLI

Simply call story2sketch with options from the API.

$ story2sketch --stories all --output dist/great-ui.asketch.json

package.json

Add the following to your package.json:

{
  "story2sketch": {
    "stories": "all",
    "output": "dist/great-ui.asketch.json"
  }
}

story2sketch.config.js

Create a file called story2sketch.config.js on the root of your project:

module.exports = {
  output: "dist/great-ui.asketch.json",
  stories: "all"
}

API

Parameter Explanation Input Type Default
output Specifies the filename for the generated asketch.json file. string "dist/stories.asketch.json"
input The location of Storybook's generated iframe.html. Use this over url if possible for performance. string "dist/iframe.html"
url Storybook iframe URL. Will end in iframe.html. Prefer input for performance if possible. string "http://localhost:9001/iframe.html"
stories Stories to extract from Storybook. You should probably override the default. object/string "all"
concurrency Number of headless Chrome tabs to run in parallel. Drastically impacts performance. integer 4
symbolGutter Gutter to place between symbols in Sketch. integer 100
viewports Viewport configuration. Will be arranged left-to-right by width. Try to avoid changing the key, as this is used to identify the symbol. object Mobile viewport (320px wide) and desktop viewport (1920px wide). See example below.
querySelector Query selector to select your node on each page. Uses document.querySelectorAll. string "#root"
verbose Verbose logging output. boolean false

Example story2sketch.config.js

module.exports = {
  output: "dist/great-ui.asketch.json",
  input: "dist/iframe.html",
  concurrency: 2,
  symbolGutter: 200,
  viewports: {
    narrow: {
      width: 320,
      height: 1200,
      symbolPrefix: "Mobile/"
    },
    standard: {
      width: 1920,
      height: 1200,
      symbolPrefix: "Desktop/"
    }
  },
  pageTitle: "great-ui",
  stories: [
    {
      kind: "Buttons/Button",
      stories: [
        {
          name: "Button"
        }
      ]
    },
    {
      kind: "Buttons/ButtonGroup",
      stories: [
        {
          name: "Default",
          displayName: "Horizontal"
        },
        {
          name: "Vertical"
        }
      ]
    },
    {
      kind: "Table",
      stories: [
        {
          name: "Table"
        }
      ]
    }
  ]
}

Questions

Why does my stuff look bad?

Because this project is experimental, and so is it's core dependency. If your stuff looks bad, either it's not supported by html-sketchapp yet (see support here), or you need to configure story2sketch.

Why don't you use react-sketchapp instead of html-sketchapp?

react-sketchapp only supports React Native, or forces you to use React Native component naming conventions. html-sketchapp supports good ol' fashioned HTML, and doesn't care what web framework you're using.

Can I use this on anything other than Storybook?

Not yet, but we have plans to add support for multiple and custom adaptors.

You can’t perform that action at this time.