Mixtape

[!NOTE] This is taken from the 3.x branch of mixtape (monorepo). 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

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

Add the tokens and override the values or just copy/paste from Mixtape and update;

eg. project-tokens.mjs

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

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

@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

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

Or partially imported;

eg. buttons.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.

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

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

Cascade layers

@layers 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;

@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

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

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

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 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 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 or join the #mixtape channel in the PNX Slack to ask questions.

Adding 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 [email protected]: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 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. Approval is then required to publish to the NPM registry.

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"