animaapp / storybook-anima

Storybook integration for Anima

⚠️ DEPRECATION NOTICE

This repository is considered deprecated. Please check out our new command line interface tool for continuous integration between Storybook and Figma storybook-anima-cli

Storybook Anima addon

Storybook addon that extracts the Storybook data and transforms stories into Figma components for a better design-development workflow.

Learn more about the motivations and benefits in our our blog post

Demo

Requirements

• Storybook@>=6.0.0
• Anima Account
• Sign up for Anima's beta
• Anima's Figma plugin

This addon should work with any framework. If you find a case that the addon does not work, please open an issue.

⚠️ Currently, we only support Wepback builders, if you use a custom builder for storybook for example, vite or one of storybook's experimental features, please write to us or open an issue as the addon might not work as expected.

Getting started

1. Install

npm install --save-dev storybook-anima --legacy-peer-deps
# yarn add -D storybook-anima

2. Register the addon in .storybook/main.js

// .storybook/main.js
module.exports = {
  addons: ["storybook-anima"],
};

3. Set Anima access token

First get the access token from the Anima Figma plugin, or in your Anima team settings. Learn more about how to get the token from Anima.

You can then set the access token as an environment variable called STORYBOOK_ANIMA_TOKEN.

You can create .env file in your project's root folder, or you can provide the environment variable as a command line parameter when building or dynamically running Storybook.

# .env
STORYBOOK_ANIMA_TOKEN="<paste your TOKEN here>"

Design system tokens support

Anima can also use your design tokens when generating stories, automatically converting them to Figma styles.

To enable this feature, please follow these steps:

1 - Prepare your design system tokens file

The file should be written in the standard JSON format.

Example :

design-system-tokens.json

{
  "--primary": {
    "$value": "#1976D2"
  },
  "--secondary": {
    "$value": "#ffcd29"
  }
}

2 - Add your design system tokens file to the storybook preview

Go to .storybook/preview.js and export a new parameter called anima with the path of your design system tokens file under designTokens

// .storybook/preview.js
export const parameters = {
  ...
  anima: {
    designTokens: require('../design-system-tokens.json')
  },
};

That is it, now if you have components that use these design tokens they will be exported to Figma as components using native Figma styles.

Considerations

For the time being, this integration works best if the your stories composition consists of just the component itself, rather than complex stories with multiple examples or included documentation.

In short, what you see in the Storybook story, is what you'll get in Figma

Limitations with Boolean control types

Due to a Storybook bug, the addon can't correctly process boolean controls if they don't explicitly specify a type.

For example, we could have some trouble processing Stories with the following argTypes definition, as the arguments don't explicity specify a type:

  argTypes: {
    disabled: { control: "boolean" },
    isContained: { control: { type: "boolean" } },
  },

In such cases, it's necessary to add an explicit type for each boolean control:

  argTypes: {
    disabled: { control: "boolean", type: "boolean" },
    isContained: { control: { type: "boolean" }, type: "boolean" },
  },

Limits on the number of variants

The addon currently limits the number of variants to a maximum of 1025 for any given story. As a result, some props might be missing in the exported components.

In the near future, we are going to provide some options to customize which controls should be included or excluded during the export process.

Development

Run following commands in separate tabs to start development

npm run build
npm run dev

For more information visit : Anima Storybook integration

License

MIT © Anima

storybook-anima's Issues

For the beta feature, storybook-anima-beta was required

For the Anima beta feature, storybook-anima-beta was required to be included alongside the storybook-anima node package in a large OSS project. Also, there was a weird edge case where I had to include the react-is package too.

Seems to convert Web component Storybook to React

Fresh install of "@storybook/web-components": "^6.4.19",
Run Storybook to confirm it runs Web component version
Then i install "storybook-anima": "^1.2.2",
Then when starting Storybook it build the React version.
That error shows on web component stories : Objects are not valid as a React child (found: object with keys {_$litType$, strings, values}). If you meant to render a collection of children, use an array instead.