# nc-designs

Latest version **0.0.111** (published 2024-10-09) · ISC license · 0 weekly downloads

## Install

```sh
npm install nc-designs
pnpm add nc-designs
yarn add nc-designs
bun add nc-designs
```

## Health

**Score 30/100 (F)** — status: abandoned.

Positive: has types; esm support; no vulnerabilities; high quality score.

Warnings: low downloads; pre 1.0.

Negative: abandoned; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.0.111 |
| Published | 2024-10-09 |
| First published | 2023-02-16 |
| Weekly downloads | 0 |
| License | ISC |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 1 |
| Unpacked size | 3.3 MB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | northcoders-devs |

## Links

- npm: https://www.npmjs.com/package/nc-designs
- Repository: https://github.com/northcoders-dev/nc-designs
- Homepage: https://github.com/northcoders-dev/nc-designs#readme
- Issues: https://github.com/northcoders-dev/nc-designs/issues
- npm.io page: https://npm.io/package/nc-designs

## Dependencies (1)

- [lodash](https://npm.io/package/lodash.md) ^4.17.21

## Recent versions

- 0.0.111 (latest) — 2024-10-09
- 0.0.110 — 2024-10-07
- 0.0.109 — 2024-09-09
- 0.0.108 — 2024-09-03
- 0.0.107 — 2024-08-13
- 0.0.106 — 2024-08-06
- 0.0.105 — 2024-07-30
- 0.0.104 — 2024-07-30
- 0.0.103 — 2024-07-30
- 0.0.102 — 2024-07-29
- 0.0.100 — 2024-07-29
- 0.0.99 — 2024-07-29
- 0.0.98 — 2024-07-19
- 0.0.97 — 2024-07-18
- 0.0.96 — 2024-07-10
- … 76 more at https://npm.io/package/nc-designs/versions

## README

# nc-designs

## Getting started with the NPM package

### Prerequisites

The components in this package are styled using [Tailwind CSS](https://tailwindcss.com/). As such your project will also need to use Tailwind CSS to receive the stylings applied.

### Install Steps

```bash
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.

```js
// 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.

</br>

![Button1 Example](./assets/images/Button1.png)

</br>

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

```bash
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:

```tsx
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:

- [Windows](https://support.microsoft.com/en-us/windows/turn-high-contrast-mode-on-or-off-in-windows-909e9d89-a0f9-a3a9-b993-7a6dcee85025)
- [MacOS](https://support.apple.com/lv-lv/guide/mac-help/unac089/mac#:~:text=To%20quickly%20turn%20Invert%20Colors,press%20Touch%20ID%20three%20times)
- [Linux/Ubuntu](https://help.ubuntu.com/stable/ubuntu-help/a11y-contrast.html.en)

</br>

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

</br>

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

```tsx
import { Icon } from '@nc-designs/icons';

const MyComponent = () => {
  return <Icon name="icon-name" />;
};
```

</br>

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

```bash
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:

```bash
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:

```bash
 * [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](https://www.chromatic.com/) 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.

---
_Source: https://npm.io/package/nc-designs · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._
