SPS Styles

This repo is home to both a library (@spscommerce/sps-styles) and a pattern library application to showcase them. The styles themselves use Bootstrap 4 as a foundation. The pattern library application is a customized instance of Fabricator. The scss folder at the root of the project contains overrides and extensions of the Bootstrap library to makes elements look the way we want.

Using @spscommerce/sps-styles in your app

There are currently several ways to add our styles into your UI.

Option 1: Use a link tag to our CDN

Put a link tag in the head of your index.html that points to our cdn:

<link rel="stylesheet" type="text/css" href="https://cdn.dev.spsc.io/web/framework/styles/sps-styles/SEMVER_RELEASE/index.css">

Note We have implemented semantic versioning based off git commit messages. You should use conventional commit style commit messages when merging PRs into this repository to ensure that a version is released upon merge.

Option 2: Install from NPM or Yarn

1. Ensure you have access to jFrog Artifactory

Ensure you have access to and have locally configured our jFrog Artifactory private npm repository and installed in your CI. The Drone jFrog Npm Plugin is super easy to use.

2. Install using npm or yarn

npm install @spscommerce/sps-styles or yarn add @spscommerce/sps-styles

3. Import it into your application

Assuming you are using a webpack based build system, open your root CSS file add this line to the top @import '~@spscommerce/sps-styles/dist/index.css';

Tip: The ~ tells your build system (webpack/parcel) to look inside node_modules. You could also provide a path to node_modules. Yet another alternative is to import the css directly using JavaScript instead using import '@spscommerce/sps-styles/dist/index.css';. Lastly, JSPM offers a similar ability to import css using require() plus an exclamation point on the end of the path to a css file.

Contributing Quick Start

To contribute to this library you can follow these steps.

• Fork and clone this repo
• Ensure you have access to and have locally configured our jFrog Artifactory private npm repository.
• Install node.js version 7.10.1 or greater
• Install project dependencies
  • Run npm install
• Finally run the app
  • Run npm start
  • Navigate to http://localhost:3000. The app will automatically reload if you change any of the source files.

Linking ui-angular or ui-react to local SPS Styles

When you build SPS Styles, the compiled CSS is located at dist > assets > toolkit > styles > toolkit.css. This file becomes index.css in the deployed artifact. So to link your locally checked out ui-angular or ui-react to your local SPS Styles, you need to create a link from node_modules > @spscommerce > sps-styles > index.css to the path of the file created when building SPS Styles.

Mac:

cd /path/to/ui-angular-or-react/node_modules/\@spscommerce/sps-styles
rm index.css
ln -s /path/to/sps-styles/dist/assets/toolkit/styles/toolkit.css index.css

Windows (run CMD as administrator):

cd path\to\ui-angular-or-react\node_modules\"@spscommerce"\sps-styles
del index.css
mklink index.css path\to\sps-styles\dist\assets\toolkit\styles\toolkit.css

Now, if you run npm start in SPS Styles, when it automatically rebuilds changes you make here, those changes should also be reflected in ui-angular and/or ui-react.

Commit Message Format

We are using semantic release on this repo, so please follow the commit message format described in their readme.

Build & Deploy

Building

Building is all automated via Docker and Drone. For more information see the build documentation.

Deploying

Deploying is all done via the SPS Drone Deploy Pipeline. For more information see the deploy documentation.

Accessibility Testing

Basic Accessibility testing can be done against the pattern library using Pa11y. You can run against localhost by serving the app (npm start), and then in another console running 'node accessibility-test.js local'. Alternatively, you can run against any build version with 'node accessibility-test.js [version]', where version is the version set in the package.json and can be found as the release names in git. (ex. 'node accessibility-test.js 0.36.0').

Changelog

We use the format recommended here: https://keepachangelog.com/en/1.0.0/

• Basically call out the types of changes in different sections.

Recommend Reading

• Fabricator Docs
• Bootstrap 4 Intro
• Theming Bootstrap