npm package: @pnx-mixtape/mxds
Description: The Mixtape Design System
Latest version: 0.0.30

# Mixtape

[![Commitizen friendly](https://img.shields.io/badge/commitizen-friendly-brightgreen.svg)](http://commitizen.github.io/cz-cli/)

> [!NOTE]
> This is taken from the 3.x branch of [mixtape (monorepo)](https://github.com/previousnext/mixtape).
> Refer to that repo if you need to make changes the original packages. This repo is dedicated to
> the `@pnx-mixtape/mxds` package.

### The PreviousNext Design System: [mxds.pnx.io](https://mxds.pnx.io/)

A design system helps align teams around how products are designed and built.

It improves team efficiency and reduces design debt by becoming a bridge which helps
designers and developers communicate.

Our design system has been created to help us establish what our collective best practices
are and how they apply to a suite of our most common UI elements.

It's like our greatest hits.

# Using Mixtape

## Installation

```
pnpm add @pnx-mixtape/mxds
```

## Usage

Once installed, you can `import` the css and javascript into your project's codebase.

### Importing and overriding styles

Dependencies:

- [postcss-design-tokens](https://www.npmjs.com/package/postcss-design-tokens)

Add the [tokens](https://github.com/previousnext/mxds/blob/main/src/tokens.js)
and override the values or just copy/paste from Mixtape and update;

_eg. project-tokens.mjs_

```js
import tokens from "@pnx-mixtape/mxds/tokens"

// Override existing ones;
tokens.colour.brand.primary = "rgb(0, 92, 250)"

//Add new ones;
tokens.newThing = "somethingNew"

export default tokens
```

The [custom properties](https://github.com/previousnext/mxds/blob/main/src/constants.css)
can also be included via @import or just copy/paste if you only need a limited set.

This file should be included in the browser.

_eg. project-constants.css_

```css
@import "@pnx-mixtape/mxds/src/constants.css";

:root {
  --my-colour-primary: rgb(0, 92, 250);
  --my-colour-secondary: rgb(247, 143, 29);
}
```

The [custom media](https://github.com/previousnext/mxds/blob/main/src/_custom-media.css)
should also be included, and is required in EVERY css file that uses them. PostCSS replaces this,
so there is no need to worry about duplication.

_eg. project-breakpoints.css_

```css
@import "@pnx-mixtape/mxds/src/_custom-media.css";

@custom-media --my-breakpoint (width >= "200px");
```

Once these 3 files are setup, you can proceed with adding the components.

_eg. buttons.css_

```css
@import "../project-breakpoints.css";
@import "@pnx-mixtape/mxds/src/Atom/Button/button.css";
```

Or partially imported;

_eg. buttons.css_

```css
@import "../project-breakpoints.css";
@import "@pnx-mixtape/mxds/src/Atom/Button/_buttons.css";
@import "@pnx-mixtape/mxds/src/Atom/Button/_buttons-styles.css";

.button--primary {
  --border-radius: 0;

  @media (--medium-up) {
    border-width: 6px;
  }
}
```

The packages are as modular as practical, so you can be specific about what to include
based on your projects requirements.

There are many custom properties that are available to override the default values. Any place you see an undefined
custom property before a mixtape fallback, you can set it in you project. eg.

```css
.line {
  border-color: var(--line-colour, var(--colour-border));
}
```

```css
.line--red {
  --line-colour: red;
}
```

#### Cascade layers

[@layers](https://developer.mozilla.org/en-US/docs/Web/CSS/@layer) are used in Mixtape to ensure ease in overriding CSS on a project
level. If you are importing `@pnx-mixtape/mxds/src/Atom/base.css` CSS then the layers are included.

If you are only partially importing the base CSS files, then you'll need to manually
include the layers at the start of your CSS;

```css
@layer design-system.defaults, design-system.atoms, design-system.layout, design-system.components, design-system.utilities;
```

Any CSS not wrapped in a layer will have higher specificity to Mixtape's CSS.
Alternatively you can append your own layers to the end of these, to achieve a
similar result.

### Importing React components

TODO

### Importing and extending javascript Elements

Some packages also provide vanilla javascript to manage simple user interactions. You can include
and initialise these by importing them into your projects `.entry.js` files (or whatever is
setup to run through a bundler like Rollup).

_eg. project-init.entry.js_

```js
import "@pnx-mixtape/mxds/src/Component/Accordion/Elements/Accordion"
```

To customise this javascript we recommend importing and then extending the Class;

```js
import Accordion from "@pnx-mixtape/mxds/src/Component/Accordion/Elements/Accordion"

class FancyAccordion extends Accordion {
  constructor(element) {
    super(element)
    this.isFancy = true
  }

  handleOpen() {
    super.handleOpen()
    this.isFancyAndOpen = true
  }
}

customElements.define("mx-fancy-accordion", FancyAccordion)
```

## Examples

**[pnx-project](https://github.com/previousnext/pnx-project/)** has Mixtape included in the
theme by default. Please refer to it (or use it directly) when setting up a Mixtape project.

**[mxds.pnx.io](https://mxds.pnx.io/)** is Mixtapes storybook.

## Updating a Mixtape based project

Mixtape goes through rapid development at times and Breaking Changes can be common. New packages
may not be compatible with old ones. Particularly due to;

- Introduction of design tokens
- Refactoring of several custom properties
- Introduction of CSS @layers
- Introduction of Container Queries
- Utility javascript being moved from base to its own package `../../utilities/utilities`
- Use of `inert` in place of `hidden`
- Various performance improvements
- Removal of the Lerna monorepo tools

If updating an entire project isn't feasible, and you get stuck, then please Log an issue.
We can look into back porting the required bug fix or feature, or help with a work-around.

# Contributing to Mixtape

## Finding and Logging issues

Please log bugs to [Jira](https://previousnext.atlassian.net/secure/RapidBoard.jspa?rapidView=5)
or join the #mixtape channel in the PNX Slack to ask questions.

Adding [patch-package](https://www.npmjs.com/package/patch-package) to your project will allow
you to create project specific patches for Mixtape, so you're not hampered by waiting for a bug
fix to released in Mixtape. Please upload any patches made to the relevant bug report in Jira.

## Build tools

This project uses Docker to manage node versions and build tasks.

### Dependencies and building

First clone this repository;

```
git clone git@github.com:previousnext/mxds.git
cd mxds
```

Install project dependcencies:

```
nvm install
pnpm install
```

Then you can start watching for changes with;

```
pnpm run dev
```

From here you can access the Storybook instance and get started.

### Linting and Test coverage

Before pushing a PR make sure your changes are linted and pass the test coverage.

```
pnpm run format
pnpm run lint
pnpm run test-storybook
```

These will all run by Github Actions on the PR but it's better to catch issues first.

Integration testing with Vitest will be added in a future release.

### Publishing changes

When you are ready to publish your change, commit your work and
follow the prompts using:

```
pnpm run commit
```

This uses [Commitizen](https://www.npmjs.com/package/commitizen) to manage
commit messages and versioning. You will be walked through an interactive
questionnaire.

Select the type of change from Feat (Feature), Fix, Docs, Style, Refactor,
Perf, Test, and Chore. This will be used in the commitizen changelog.

Then create a pull request, wait for builds to pass, and get the code reviewed.

Once approved, merge the PR.

When you are ready for a release, from `main`, run;

```
pnpm bump-version
```

To bump the patch version number in `package.json`, then tag the commit and push to `origin`.

This will trigger a deploy in CircleCI to update [mxds.pnx.io](https://mxds.pnx.io/).
Approval is then required to publish to the [NPM registry](https://www.npmjs.com/package/@pnx-mixtape/mxds).

Alternatively for a minor or major release, from `main`, run;

```
# Backward compatible new features
pnpm version minor -m "chore: tag %s"
```

```
# Changes that break backward compatibility
pnpm version major -m "chore: tag %s"
```