⚡ Build your own experiences on the Narmi platform!

This design system provides low level utilities and UI components for building custom experiences in combination with the Narmi API.

Narmi Design System is published as a single NPM package.

npm install @narmi/design_system --save

Your project must provide the following packages as peer dependencies:

• React (>=16.9, supports Hooks)

• 📖 Storybook (latest)
• 🎨 Design Guidelines
• ✏️ Contributing

Components can be imported from package root:

import { Button, Tooltip } from '@narmi/design_system';

NDS provides a set of global CSS helper classes to make it easy to tweak styling in your markup with standard Narmi design values. For example:

<div className="padding--all">
  <p className="fontWeight--semibold fontSize--l">
    Semibold large text in a box padded with a standard gutter
  </p>
</div>

For full documentation of available classes, see storybook docs.

All available distributions of design tokens can be found in dist/tokens. All CSS custom properties from design tokens are already included in the base stylesheet, dist/style.css.

To request a new distribution, please file an issue.

This project uses Semantic Versioning. Refer to the Changelog for details.

See .browserslistrc for officially supported browsers or run npx browserslist in this project locally to see a full list of targeted browsers.

This project does not support any version of Internet Explorer.

To run project locally:

git clone [email protected]:narmi/design_system.git
cd design_system
npm run dev

This project uses semantic-release, configured to use Conventional Commits.

Any time new commits are added to the main branch, the GitHub Action "release" will run semantic-release. The job will parse recent git tags and commit messages to determine the new version number, tag the release, publish to NPM, and update the changelog.

All PRs target main unless it contains breaking changes. Any branch containing breaking change commits should target the open major release branch. For example, if NDS is on major version 1, breaking changes should target the branch major/v2.

Branches containing breaking change commits should follow the naming convention breaking/<branch name>.

This project requires structured commit messages in the Conventional Commits format:

<type>(<optional scope>): <short description>

Allowed types are [build, chore, ci, docs, feat, fix, perf, refactor, revert, style, test] . The build, chore, and ci commit types will skip CI and do not trigger a release. Adding a bang (!) to the commit type denotes a breaking change (see docs for more details).

Making a fix without scope specified:

fix: update global `text-rendering` value

Adding a feature within the scope of the Button component:

feat(Button): add secondary button variant

Breaking change within the Button component scope:

refactor(Button)!: remove variant `disabled`. The `disabled` boolean prop is now used to disable a button.

Any modification to the design system that requires consumers to update their usage of NDS is considered a breaking change. For example:

• removing or renaming a component
• changing a public className
• interface changes in public methods
• renamed or retyped component props

If you are making a breaking change, please note it in your commit message appropriately.

Development of Narmi Design System should be done in isolation within this repo. There are however, some rare circumstances where you may need to test NDS changes against some consuming application.

The best way to approach testing unpublished NDS changes in a consumer is to use beta versions.

⚠️ Only do this if absolutely necessary

1. Rebuild NDS (npm run build)
2. Update the version field of package.json to be a beta of the next minor. For example, you would change 2.35.2 to 2.36.0-beta.0. DO NOT COMMIT THIS CHANGE.
3. Publish the package (npm publish --tag beta)
4. In your consuming application, you can point the @narmi/design_system version to the beta version you just published.

If you need to make additional changes after the beta is published...

1. Rebuild NDS (npm run build)
2. Bump the beta version number in package.json (2.36.0-beta.0 -> 2.36.0-beta.1)
3. Install the new beta version in your consuming application.

Source code is under a custom license based on MIT. The license restricts @narmi/design_system usage to applications that integrate or interoperate with Narmi software or services, with additional restrictions for external, stand-alone applications. Please see LICENSE.md for full details.