![\"Zeplin](\"https://raw.githubusercontent.com/zeplin/storybook-zeplin/master/logo.png\"){kind=logo}
\n \n
\n\n[](https://badge.fury.io/js/storybook-zeplin)\n[](https://www.npmjs.com/package/storybook-zeplin)\n[](https://github.com/zeplin/storybook-zeplin/blob/master/LICENSE)\n[](https://app.netlify.com/sites/storybook-zeplin/deploys)\n[](https://opencollective.com/storybook-zeplin)\n\n
![\"Zeplin](\"https://raw.githubusercontent.com/zeplin/storybook-zeplin/master/screenshot.png\")
\n\n## Links\n\n- [Demo](https://storybook-zeplin.netlify.app)\n- [Blog Post](https://blog.zeplin.io/storybook-and-zeplin-a-new-integration-228951e336e9)\n- [Highlight Components](https://blog.zeplin.io/announcing-improved-storybook-integration-highlight-components)\n\n## Requirements\n\nStorybook Zeplin addon v4 is compatible with Storybook 10 and Node.js >=18.\n\nFor Storybook 8, use `storybook-zeplin@3`.\n\nFor Storybook 5-7, use `storybook-zeplin@2.0.3`.\n\n## Getting started\n\n### 1. Install\n\n```sh\nnpm install --save-dev storybook-zeplin\n# yarn add -D storybook-zeplin\n```\n\n### 2. Register the addon in `main.js`\n\n```js\n// .storybook/main.js\nexport default {\n addons: [\"storybook-zeplin\"],\n};\n```\n\n### 3. Linking components\n\nYou can either link an entire Zeplin project or styleguide via global story parameters (recommended), or link individual components one by one.\n\n#### Option A: Linking entire project or styleguide (Recommended)\n\nAdd `zeplinLink` to `.storybook/preview.js` with a link to the Zeplin project or styleguide that contains your designs.\n\nZeplin components linked to your stories will automatically appear in the addon panel.\n\nUsing a Zeplin web link\n\n```js\n//.storybook/preview.js\nexport const parameters = {\n zeplinLink: \"https://app.zeplin.io/project/5e7a6d478204d59183a1c76b\",\n};\n```\n\nUsing a Zeplin app link\n\n```js\n//.storybook/preview.js\nexport const parameters = {\n zeplinLink: \"zpl://project?pid=61f164b064e363a52fbb295f\",\n};\n```\n\nOnce the addon is set up, check out these articles to learn more about the Storybook integration on Zeplin:\n\n- [Connecting your Storybook instance with Zeplin](https://support.zeplin.io/en/articles/5674596-connecting-your-storybook-instance-with-zeplin)\n- [Linking your components in Zeplin with stories in Storybook](https://support.zeplin.io/en/articles/5679812-linking-your-components-in-zeplin-with-stories-in-storybook)\n\n#### Option B: Linking individual stories manually\n\nThe `zeplinLink` parameter accepts either a string link or an array of `{ name, link }` objects. Links can be a full Zeplin web URL or an app URI pointing to a component or screen.\n\nTo link all stories in a file to the same Zeplin component:\n\n```jsx\nexport default {\n title: \"Button\",\n component: Button,\n parameters: {\n zeplinLink:\n \"https://app.zeplin.io/project/5e7a6d478204d59183a1c76b/styleguide/components?coid=5eac833c5f1f2f1cb19f4f19\",\n },\n};\n\nexport const Primary = {\n render: () => ,\n};\n\nexport const Secondary = {\n render: () => ,\n};\n```\n\nTo link a single story to multiple Zeplin components:\n\n```jsx\nexport default {\n title: \"Button\",\n component: Button,\n};\n\nexport const Responsive = {\n render: () => ,\n parameters: {\n zeplinLink: [\n { name: \"Desktop\", link: \"zpl://components?pid=pid1&coid=coid1\" },\n { name: \"Tablet\", link: \"zpl://components?pid=pid1&coid=coid2\" },\n { name: \"Mobile\", link: \"zpl://components?pid=pid1&coid=coid3\" },\n ],\n },\n};\n```\n\n### 4. Set Zeplin access token\n\nTo access your Zeplin resources, provide an access token with your Zeplin account permissions. You can create one from the [Developer](https://app.zeplin.io/profile/developer) tab in your profile page.\n\nThe addon prompts for the token when you open the addon tab. The token is stored in the browser, so each user needs to create and set their own.\n\n![\"Setting](\"./token-screenshot.png\")
\n\n#### (Optional) Setting the access token via environment variable\n\nTo skip creating a token per user, provide it as `STORYBOOK_ZEPLIN_TOKEN` — either in a `.env` file in your project root, or as an environment variable when building or running Storybook.\n\n#### ⚠️ Disclaimer\n\n**When set via an environment variable, the access token is bundled into the Storybook build and can be read by anyone with access to the instance. Don't use this approach if your Storybook instance is accessible to third parties.**\n\n```shell\n# .env\nSTORYBOOK_ZEPLIN_TOKEN=\"eyJhbGciOiJIUzI1N..\"\n```\n\n## Overlaying the design\n\nOnce a Zeplin design is loaded in the panel, click the eye icon to overlay it on top of the rendered component. Adjust opacity and scaling to align the two, lock the overlay in place once positioned, or toggle difference mode to highlight pixel-level mismatches.\n\nYou can drag the overlay with your mouse, or nudge it one pixel at a time with Shift + arrow keys.\n\n## Development\n\nRun the following commands in separate tabs to start development:\n\n```shell\nnpm run watch\nnpm run storybook\n```\n\n## License\n\nMIT © [Mert Kahyaoğlu](https://mert-kahyaoglu.com)\n","readmeFilename":"README.md"}