npm package: @spscommerce/sps-styles
Description: A tool for SPS Commerce UI Engineers.
Latest version: 2.1.0

# SPS Styles 

[![SPS Commerce](https://img.shields.io/badge/sps-commerce-0097cc.svg?style=flat-square&colorA=62686b)](https://www.spscommerce.com) ![Version](https://sps-badges.now.sh/@spscommerce/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](https://getbootstrap.com/) as a foundation.  The pattern library application is a customized instance of [Fabricator](https://fbrctr.github.io/). 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:

```html
<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](https://www.conventionalcommits.org/en/v1.0.0-beta.2/) 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](https://atlassian.spscommerce.com/wiki/display/STM/Getting+started+with+private+NPM+packages+in+jFrog+Artifactory) and installed in your CI. The [Drone jFrog Npm Plugin](https://github.com/SPSCommerce/plugin-npm-auth) 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](https://atlassian.spscommerce.com/wiki/display/STM/Getting+started+with+private+NPM+packages+in+jFrog+Artifactory).
- Install [node.js](https://nodejs.org/en/) 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](https://github.com/semantic-release/semantic-release#commit-message-format).

## Build & Deploy

### Building

Building is all automated via Docker and Drone. For more information see the [build documentation](./docs/build.md).

### Deploying

Deploying is all done via the SPS Drone Deploy Pipeline. For more information see the [deploy documentation](./docs/deploy.md).

## Accessibility Testing

Basic Accessibility testing can be done against the pattern library using [Pa11y](https://github.com/pa11y/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](http://fbrctr.github.io/docs)
- [Bootstrap 4 Intro](https://getbootstrap.com/docs/4.0/getting-started/introduction/)
- [Theming Bootstrap](https://getbootstrap.com/docs/4.0/getting-started/theming/)