Working with styles

Neptune CSS provides all the CSS you need to style your application.

Getting started

Refer to the setup guide for information on how to install and import Neptune CSS into your application.

Usage

Refer to the documentation for information on available utility classes.

We recommend using Neptune CSS with our Neptune Web React components, but it will also work with our Angular components.

Note: Do not use component CSS directly. It is considered an implementation detail and may change without warning.

Migrating from Bootstrap

Previously, apps at TransferWise were styled using a fork of Bootstrap. Neptune CSS is based heavily off this fork, with minor modifications. We want to move everyone off Bootstrap and on to Neptune CSS, where we will continue to make improvements.

If you are still using Bootstrap, it's time you switched! Refer to the upgrading guide to see what has changed, and to the setup guide for installation instructions.

Tokens (custom properties)

We maintain a separate package where we define platform agnostic variables like spacing and colour codes.

These are imported in neptune.css and are available as root level custom properties which you can use in your app. If you're unfamiliar with custom properties, have a read of the MDN entry or this introductory article.

If you don't want to use them in your application, there is nothing for you to do. They will work in Neptune CSS with no special setup.

Installation

To use custom properties in your own app, you will need to do some setup to ensure fallbacks are correctly generated. We presume you are using postcss.

1. Install the postcss-custom-properties plugin. We recommend using this fork, which enables fallbacks not only for old browsers, but for modern browsers too (in the case of a missing custom property).
2. Set up your postcss config to point the plugin to the custom properties files (see an example config file below). If you're using the fork (and I hope you are), set preserveWithFallback to true.
3. (Optional but recommended): Set up stylelint in your repository, and configure the stylelint-value-no-unknown-custom-properties plugin to similarly point to the custom properties files, to ensure you are not using any that don't exist.

Remember: you only need to include root level custom properties once in your application. Including them on your components will result in duplicate definitions.

require('@arshaw/postcss-custom-properties');

module.exports = {
  plugins: {
    '@arshaw/postcss-custom-properties': {
      importFrom: ['../../node_modules/@transferwise/neptune-css/dist/props/neptune-tokens.css'],
      preserveWithFallback: true,
    },
  },
};

Usage

Information on what is available can be found in the tokens documentation.

import '@transferwise/neptune-css/dist/css/neptune.css';

.my-button {
  background-color: var(--color-primary);
  border: 1px solid transparent;

  color: #fff;
  cursor: pointer;

  padding: var(--size-8);
}