⚡ 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)
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
npm run command |
Description |
|---|---|
build:jsdoc |
builds jsDoc documentation to dist/ |
build:tokens |
builds all distributions of design tokens to dist/ |
build:components |
builds all components and base stylesheet to dist/ |
build |
builds everything |
test |
runs all jest tests |
storybook |
starts storybook in dev server mode on :6006 |
watch |
watches src dir, triggering build on changes |
dev |
Start storybook and watch for all src changes |
stats:components |
analyzes a given project and reports component usage |
stats:classes |
analyzes a given project and reports class usage |
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.
The workflow that runs visual snapshot testing is "Chromatic PR Checks"/run_chromatic. All pull requests will block merging until this workflow passes.
On every push to a PR, this workflow will run snapshots and report results via a comment on the PR. Use the provided links to review diffs in the Chromatic build and/or view the Storybook preview build.
For a detailed step-by-step guide on resolving failing Chromatic checks, see the Visual Regression Tests contributing guide.
🔑 Authentication Required: While the Storybook preview is public, you must log into Chromatic with Narmi engineering credentials to view details on the build and approve or deny snapshot changes.
In rare circumstances, you may need to manually publish a version of NDS outside of the normal automated release process.
- Rebuild NDS (
npm run build) - Update the
versionfield of package.json to be a beta of the next minor. For example, you would change2.35.2to2.36.0-beta.0. DO NOT COMMIT THIS CHANGE. - Publish the package (
npm publish --tag beta) - In your consuming application, you can point the
@narmi/[email protected]
If you need to make additional changes after the beta is published...
- Rebuild NDS (
npm run build) - Bump the beta version number in package.json (
2.36.0-beta.0->2.36.0-beta.1) - Install the new beta version in your consuming application.
In rare cases, you may need to publish a patch over a previous version (e.g., patching 2.35.2 when the current version is 2.36.0).
Follow the same steps as publishing a beta version, but without the --tag beta flag:
- Rebuild NDS (
npm run build) - Update the
versionfield of package.json to the desired patch version (e.g.,2.35.3). DO NOT COMMIT THIS CHANGE. - Publish the package (
npm publish)
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. See Publishing a beta version for instructions.
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.