npm package: @indico-data/design-system
Description: <h1 align="center" style="border-bottom: none; margin-bottom: -15px;">❄️ Permafrost ❄️</h1> <h3 align="center">Indico Data's Design System</h3> <p align="center">     <a href="https://www.npmjs.com/package/@indico-data/design-system">         <img alt="np
Latest version: 3.23.0

<h1 align="center" style="border-bottom: none; margin-bottom: -15px;">❄️ Permafrost ❄️</h1>
<h3 align="center">Indico Data's Design System</h3>
<p align="center">
    <a href="https://www.npmjs.com/package/@indico-data/design-system">
        <img alt="npm package" src="https://img.shields.io/npm/v/@indico-data/design-system?style=flat-square"/>
    </a>
    <a href="https://github.com/semantic-release/semantic-release">
        <img alt="semantic release - eslint" src="https://img.shields.io/badge/semantic--release-eslint-e10079?logo=semantic-release&style=flat-square"/>
    </a>
</p>

## 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint). 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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint#eslint-convention), 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](https://github.com/semantic-release/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](https://github.com/semantic-release/semantic-release?tab=readme-ov-file#commit-message-format) (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](https://github.com/conventional-changelog/conventional-changelog/tree/master/packages/conventional-changelog-eslint) 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](https://semantic-release.gitbook.io/semantic-release/support/faq#why-is-the-package.jsons-version-not-updated-in-my-repository). 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.
   - At a minimum, please ensure that the svg `path` reasonably fills the viewbox dimensions. Use an [SVG path editor](https://yqnn.github.io/svg-path-editor/) as needed.
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 `path`s 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](https://svgomg.net/) 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](https://freesvgeditor.com/en/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.

## Rectifying Badly-Sized Icons

As of January 7, 2025, we have observed inconsistencies in the sizing of certain icons within this design system. If you intend to use an icon and find that it appears improperly sized within its parent container, we recommend utilizing an [SVG path editor](https://yqnn.github.io/svg-path-editor/) to adjust and scale the path accordingly, ensuring it fully occupies the viewbox of the surrounding SVG.

## 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