npm package: @stepzen/design-system
Description: StepZen design system
Latest version: 0.3.0

# StepZen Design System

This npm package includes design tokens, styles and UI components shared across different StepZen web apps: the docs and marketing site stepzen.com, the "My Account" dashboard dashboard.stepzen.com, etc.

This repo includes [Storybook](https://storybook.js.org/) as a tool to visualise the contents of the design system, making it available on the web.
The Storybook for the `main` branch is automatically published to [https://main--62ba1d9d935e74836cf81cae.chromatic.com/](https://main--62ba1d9d935e74836cf81cae.chromatic.com/).

NOTE: it might take up to an hour after a push to `main` before changes appear on [https://main--62ba1d9d935e74836cf81cae.chromatic.com/](https://main--62ba1d9d935e74836cf81cae.chromatic.com/).

## How to use

### In a NextJS app

- add an npm dependency: `npm install --save @stepzen/design-system`
- inlcude styles into the `pages/_app.js`
  ```js
  import "@stepzen/design-system/dist/css/index.css";
  ```
- That's it. Now you can access to the CSS custom properties, global styles and UI components from the StepZen design system in your `.css` and `.js` / `.ts` files.

## Updating and publishing a new version

Manual publishing steps:

- `git clone git@github.com:steprz/design-system.git --depth 1`
- `cd design-system`
- `npm ci`
- `npm version [new version]`
- `npm run build`
- `npm publish`
- `git push` (to push the version commit)
- `git push --tags` (to push the new version tag)
- create a GitHub release from the new version tag
- post a summary to the `#dev-products-frontend` Slack channel

## Adding a new global style

Global style sheets set CSS custom properties on the HTML page `:root` and / or modify styles of the standard HTML elements such as `<h1>` or `<body>`.

How to add a new global style to the StepZen design system:

- consider if it would make sense to append the new style to one of the existing `.css` files
- if not, create a new `stylesheet-name.css` file under `src/styles` (or `src/styles/tokens` for new design tokens)
- write CSS as usual, assuming it is loaded into apps by a regular `<link rel="stylesheet">` tag
- import the new .css file into `src/styles/index.css` with a relative `@import()`
- create a `[StylesheetName].stories.mdx` file next to the `stylesheet-name.css` file (copy from one of the existing similar files)
- update the `<Meta title="Design Tokens/Colors" />` tag in the copied file appropriately
- describe the new stylesheet so that other engineers on the StepZen team know what it is and how to use it
- publish a new version of the `@stepzen/design-system` package to npm (most likely, this would be a minor)
- That's it. All apps using the StepZen design system via `import '@stepzen/design-system/dist/css/index.css'` will get new global styles after bumping the version of their `@stepzen/design-system` npm dependency.

## Adding a new UI component

**TBD**

Currently, the design system only includes a dummy sample `Button` component which is not intended for actual usage.

## Running locally

This repo uses NodeJS 16+ and npm 7+.

- `npm run build` - (re)create a production design system bundle in the `dist/` folder (includes `.css`, `.js`, and `.d.ts` files)
- `npm run storybook` - start a local Storybook server on http://localhost:6006
- `npm run build-storybook` - create a production storybook bundle in the `storybook-static/` folder
- `npx chromatic --project-token=<project-token>` - recreate a production srotybook bundle and publish it to `chromatic.com`. Copy the project token from https://www.chromatic.com/manage?appId=62ba1d9d935e74836cf81cae&view=configure. Typically you do not need to do that, since all branches on GitHub are automatically deployed to `chromatic.com` by the "Chromatic" GitHub workflow (see `.github/workflows/chromatic.yaml`).