nc-designs
Getting started with the NPM package
Prerequisites
The components in this package are styled using Tailwind CSS. As such your project will also need to use Tailwind CSS to receive the stylings applied.
Install Steps
npm i nc-designs
You will need to merge your current tailwind config object with the config from within the package.
The function mergeTailwindConfig will take your current tailwind config object as its only argument. You will also need to ensure the receiving repo is able to access the exported tailwind config object by adding the path to your content array, as seen in the example below.
// tailwind.config.js
const { mergeTailwindConfig } = require('nc-designs');
module.exports = mergeTailwindConfig({
content: ['./node_modules/nc-designs/lib/index.esm.js'],
});
Example usage
Each component will need to be accessed via the main exported object upon being imported. Once imported you will be able to hover over the component to see some documentation including the properties and respective types for the props to be passed in.

Using Storybook
We use Storybook to allow us to develop and test our components in isolation. This allows us to test our components in a variety of different states without worrying about other components.
Getting started with Storybook
To get started, run the following command:
npm run storybook
Adding a new story
If you are creating a new atom, you will want to also create a story for the atom. Within the src/atoms/your-atom directory, create a file named your-atom.stories.tsx. This file will contain the stories for your atom.
For a simple template, you can copy the following:
import { Meta, StoryObj } from '@storybook/react';
import YourAtom from './your-atom';
export default {
title: 'Atoms/YourAtom',
component: YourAtom,
} as Meta<typeof YourAtom>;
type YourAtomStory = ComponentStory<typeof YourAtom>;
export const Main: YourAtomStory = {
args: {
prop: true,
},
};
Testing with Dark Mode
To enable the Dark Mode functionality within Storybook, you can click on the Half Moon icon in the top right of the Storybook window. This will change your component if you have any dark: prefixes within your Tailwind styles.
You can also change the background colour within Storybook by clicking on the Painting icon (looks like a Canvas, but it's not the link that reads 'Canvas'), and clicking either lightModeNC or darkModeNC.
Testing with High Contrast mode
There are two ways to enable High Contrast styles within Storybook.
Google Chrome Browser
Firstly, head to your DevTools and hold CMD + Shift + P
This will open a search bar of features; search for Rendering then click it.
You are now able to see a new tab come up, this has multiple different cool features you are able to use to change the way webpages are rendered. In this case, we want to scroll to Emulate CSS media feature prefers-contrast.
We want to change this option to prefers-contrast: more, or No Emulation to disable it.
System Preferences
There are ways to do this on your operating system, and you can find how at these following links:
Accessibility
When you run npm run storybook and it is running on localhost:6006, you can use the Accessibility tab to check for any accessibility issues. This will check for any accessibility issues, and tell you if there is anything wrong.
There are three tabs:
- Violations
- Passes
- Incomplete
Atomic Design
We use Atomic Design to structure our components. This allows us to create components in a way that is easy to understand, and allows us to reuse components across the project.
Atoms
Atoms are logically complete usable units of presentation. They require no additional content in order to be applied anywhere in code (most likely molecules or organisms). Generally they will be pairs/small groups of elements that will be presentationally co-employed (most notably any form input element alongside a label that correspond with each other via a passed in id prop), like FormInput.tsx, which combines label and input elements, as well as any styles that give it meaning in the application (see Bosons).
Quarks
In theory, where an atom comprises multiple elements, we can further subdivide it for the sake of reusability. For example, Input.tsx and Textarea.tsx could both employ the same Label.tsx quark; it's not appropriate for Label.tsx to be considered an atom because it is not logically coherent itself (what is it labelling?)
In practice, it may just be that the React element itself is all the abstraction you need, and using these within atoms and molecules directly is clear enough and does not significantly 'wet' the code. However sometimes using TypeScript to enforce certain properties into an element, such as those required for accessibility, make abstraction useful; for example, an Image.tsx component that wraps an <img /> element, passing through a src and alt prop.
Bosons
Bosons are mechanisms for providing styles or 'presentational weight' to components. Tailwind utilities (like bg-white) are essentially bosons in themselves and where these are employed in isolation or there is no meaning to their combination, they don't need wrapping in any way, just go ahead and use them.
However where a combination of elements represent a visual style that should apply in multiple areas, then use the globals.css file to define an @apply directive so the group can be utilised in class name strings with a semantic name. For example a visual-button class that utilises styles for background, cursor, font, border and pseudo classes for hover and disabled states may be used by multiple button atoms, as well as links or spans that want to present as buttons.
Differentiating between what should be a component, what should be tailwind utility classes, and what should draw from globals.css is more art than science and as long as you can justify your choice, you've likely made a valid one. This is probably most the case with layouts, positioning, tables and similar cases, where a mix of flexibility, JS behaviours and interdependence between elements can complicate the choice.
Molecules
Molecules are complex but unopinionated presentational structures. They may use several atoms and layouts that we wish to define in the system so they can be reused for presentational consistency. However if their implementations are specific to the organism, then they do not belong here.
Examples include a reusable card that always expects a title and content text but consistently applies styling to these, forms with predictable structures, or standardised modal presentations.
Typography
This is a folder full of components that are used to create text and anything typography based (links, titles, etc...)
These will handle anything such as dynamic font sizing, dark mode handling etc.
Icons
We have a folder full of icons that we can use within our components. These are all SVGs, and are exported as React components. To use an icon, you can import it into your component, and use it like so:
import { Icon } from '@nc-designs/icons';
const MyComponent = () => {
return <Icon name="icon-name" />;
};
Updating the package on NPM
Ensure that any new components have been added to the library file at src/index.ts.
We have made an npm package which is hosted online, and enables us to use the design system in other projects. To update the package, you will need to run the following command:
npm version patch
This will increment the version number of the package, and now we need to push the new 'tags' to the remote repository. To do this, run the following command:
git push --tags
This will start a pipeline which tests the package, and if it passes, it will be published to NPM.
Once the pipeline has passed you will see the following in the terminal where n is the version number:
* [new tag] v0.0.n -> v0.0.n
Be aware that the new version will not be available on npm immediately - it typically takes about 5 minutes for the new package version to go live but it can take anything up to 24 hours.
Chromatic
Chromatic is a visual testing tool used as part of the review process for pull requests made to nc-designs.
Each created pull request will trigger a new build as part of the pipeline, leading to a published Storybook on Chromatic. This will automatically create a message in the #nc-designs-review channel showing the state of the current build, as well as buttons to view the components that have changed and an up-to-date hosted Storybook.
For the PR to be mergeable, an approval on Chromatic is needed. This includes a review of both the build itself, which will display any UI changes on a component-by-component basis, as well as the open PR accessible under the 'Reviews' tab. By default, Ian is set as a reviewer for any new builds.
Once a build has been approved on the Chromatic platform, this will feed back to the open PR. The final step is a code approval on GitHub itself, which will allow the PR to be merged into main.