@pnx-mixtape/mxds NPM

Mixtape

The PreviousNext Design System: mixtape.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

npm install @pnx-mixtape/mxds --save

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

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.

mixtape.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 git@github.com:previousnext/mixtape.git
cd mixtape

Install project dependcencies:

make install

Then you can up the Docker container and start watching for changes with;

make up

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

Publishing changes

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

npm 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 and helps to determine the version when publishing to npm.

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

Once approved, merge the PR.

CircleCI will go through and bump the version number to a "prerelease" version. It will change the version number in package.json, commit the change to git and publish to NPM.

When you are ready for a full release, merge the master branch into releases. This will trigger a deploy in CircleCI to update mixtape.pnx.io. Approval is then required to publish to the NPM registry.