Storybook Dev Server Initialization

Install dependencies with a simple yarn command.

yarn dev runs the command storybook dev -p 6006 which should boot the dev server and open the local host in a browser window.

Import Issues

When you first set this up, you might run into import issues due to Yarn 4. In order to resolve these, you need to run yarn dlx @yarnpkg/sdks vscode (assuming you are on VSCode). more information available here (https://stackoverflow.com/questions/54954337/is-it-possible-to-use-yarn-pnp-with-typescript-vscode)

Additional Scripts

Run the below like yarn <my command>

"build": "storybook build",
"test-storybook": "test-storybook",
"prepare": "husky install"

Commit Hygiene

This repository follows a slightly modified version of the ESLint Commit Message Format. This repository uses the PR title to configure the contents of the commit message of the squashed commit associated with the PR: In general, a PR should use the following structure:

Title

The title should have the following format: <Tag>: <Short description>

The <Tag> should be Fix, Update, New, or Breaking for controlling releases.

If the PR need not be associated with a new release, choose any other <Tag> from the ESLint commit convention tags, such as Docs (documentation), Build (build process), Upgrade (dependency upgrade), or Chore (non-user-facing tasks).

Examples:

• Update: button color adjustment
• New: [SNC-222] add dark mode

If your PR title does not follow these commit conventions, merging will be blocked.

See below for more information on how commit structure affects releases.

Releasing

This repository uses Semantic Release to control versioning and releases. Semantic Release's prime purpose is to remove developers from the version numbering process, and this repository embraces that philosophy.

Automatic Releases

Two things primarily determine how a new release is versioned:

1. The commit history leading up to the commit being released (to determine the base version from which to bump)
2. The message of the commit being released (to determine the version incrementation amount)

To release a new version as part of a pull request, use a semantic commit message (prefixes like Fix, Update, New, or Breaking) in the title of your pull request. This repo uses a slightly modified version of the ESLint conventional changelog to describe commit conventions.

• Fix or Update: Initiate a patch release
• New: Initiate a minor release
• Breaking: Initiate a major release

If your PR title does not follow these commit conventions, merging will be blocked.

Under the hood, Semantic Release controls the npm release process entirely by way of managed Git tags. Updating the package.json version number is unnecessary and discouraged.

Releasing a Non-Latest Version

To release a patch version on a previous major version:

• Checkout a new branch off the old version you'd like to release from: git checkout -b <branch-name> <tag-name> (e.g. git checkout -b ethan/patch-fix v2.0.2)
• Commit as normally, using the PR Title conventions outlined above
• Semantic Release will take care of the versioning

Tracking Releases

If you want to view the latest version of the Design System, you have a few options:

• From this repository, run yarn latest-release
• From outside this repository, run npm dist-tags ls @indico-data/design-system

If you want to see all releases:

• From this repository, run yarn all-releases
• From outside this repository, run npm view @indico-data/design-system versions
• View the git tags at https://github.com/IndicoDataSolutions/permafrost for specific information about each release
• Consult the npm registry at https://www.npmjs.com/package/@indico-data/design-system

Do NOT use the version attribute of package.json to track or initiate releases because:

• Semantic Release does not rely on this attribute to trigger releases: https://semantic-release.gitbook.io/semantic-release/support/faq
• Adding an additional commit to update the version number adds complexity to the CI process and clutters commit history

Manual Releases

Do not manually release Permafrost to npm, as it may cause issues with the Semantic Release pipeline.

Adding New Indicons

We support registering custom SVG icons (indicons) alongside the ones provided by Font Awesome. To add a new icon, add its SVG to the indicons object in src/components/icons/indicons.ts.

Not all SVGs can be valid Font Awesome icons. All custom SVGs must:

1. Have a viewBox attribute with width and height values;
   • While not required, a viewBox of "0 0 100 100" means it will render consistently with other Indicons and Font Awesome icons.
2. Have the xmlns and fill attributes set to "http://www.w3.org/2000/svg" and "currentColor" respectively.
3. For monotone icons, one (1) path element with the d attribute set to a valid SVG path, OR
4. For duotone icons, two (2) path elements each with a d attribute, and where the "bottom" / primary layer is has an opacity of "1.0" and the "top" / secondary layer has an opacity of "0.4". Opacity is just the method by which Font Awesome distinguishs between layers internally; the styling is meant to be overriden through the custom CSS.

For monotone icons, the currentColor attribute of the SVG ensures that the color of the icons inherits from the parent element.

For duotone icons, the two paths should not be intersecting; aka, the secondary layer should be cut out of the primary one.

To ease with meeting those requirements, we recommended passing exported SVGs through an optimizer like svgo to merge paths and remove unnecessary attributes (enabling every option except Remove xmlns, with a Precision of 2 usually results in an identical but cleaner SVG). SVG Editor Online is another good option for deleting nodes, paths, and general editing.

If an Indicon does not meet the requirements above, registration will fail.

Theming Addon Documentation

Addon - Themes

https://github.com/storybookjs/storybook/tree/next/code/addons/themes

CSS Data ATTR

https://github.com/storybookjs/storybook/blob/next/code/addons/themes/docs/api.md#writing-a-custom-decorator