@spscommerce/colors

Design approved colors distributed in various formats

I want to use existing colors, see availabe colors, or add or change colors.

Using Existing Colors

Ensure you have access to and have configured our private jFrog Artifactory npm registry.

npm install --save @spscommerce/colors

# OR

yarn add @spscommerce/colors

Finally, make sure that your CI environment is set up to be able to install from JFrog Artifactory. Your Jenkins user must have JFrog Artifactory permissions. Additionally you should have GH_TOKEN set in your jenkins so that builds can be pushed back to github. In order to do this we recommend setting up a github bot account. Make sure that the jenkins bot or jenkins bot group is added to all your new repos with write access. An example group is the Github group commerce-platform-bot-writable which contains a github user called jenkins-identity-service. This is required for it to create releases and to tag those releases back on Github. You can see our Dockerfile, run-build.sh (build a simple docker file), run-ci.sh (runs releases). We use semantic-release to release our builds. Other things to make sure that you do:

Add always-auth=true to your .npmrc file.

Here is our CI build step:

echo "About to remove old .npmrc file"
rm ~/.npmrc

# Dont show secrets in logs
set +x
JFROG_NPM_USERNAME='INSERT_JFROG_USER_HERE'
JFROG_NPM_PASSWORD='INSERT_JFROG_PASSWORD_HERE'
JFROG_NPM_EMAIL='[email protected]'
JFROG_NPM_PASSWORD_BASE64=$(echo $JFROG_NPM_PASSWORD | base64)
echo "Printing jfrog base64 pass"
echo $JFROG_NPM_PASSWORD_BASE64
GH_TOKEN="INSERT_GH_TOKEN_HERE"
cat >~/.npmrc <<EOL
init.author.name=SPS Commerce
[email protected]
init.author.url=https://www.spscommerce.com
init.license=UNLICENSED
always-auth=true
@spscommerce:registry=https://spscommerceinc.jfrog.io/spscommerceinc/api/npm/npm/
//spscommerceinc.jfrog.io/spscommerceinc/api/npm/npm/:_password=${JFROG_NPM_PASSWORD_BASE64}
//spscommerceinc.jfrog.io/spscommerceinc/api/npm/npm/:username=${JFROG_NPM_USERNAME}
//spscommerceinc.jfrog.io/spscommerceinc/api/npm/npm/:email=${JFROG_NPM_EMAIL}
//spscommerceinc.jfrog.io/spscommerceinc/api/npm/npm/:always-auth=true"
EOL
set -x
echo "Finished writing new .npmrc file"
./other/build-ci.sh
./other/run-ci.sh $GH_TOKEN $JFROG_NPM_USERNAME $JFROG_NPM_EMAIL

Note we don't pass any --build-arg or use the docker ENV directive because that would be stored in the docker history which is not good from a security perspective. The downside is that our build steps are a bit more complex.

Reusable instructions for your users

Before you actually use any color format in your package or application you will probably want to help developers understand how to use colors or add or change colors. You can do so by including the following instructions about @spscommerce/colors in your README.md:

### @spscommerce packages

This package uses the SPS Commerce private jFrog Artifactory NPM repository. You should make sure that you [have it configured](https://atlassian.spscommerce.com/wiki/display/STM/Getting+started+with+private+NPM+packages+in+jFrog+Artifactory) before using this package.

### Using colors

Colors in this project are sourced from [@spscommerce/colors](https://github.com/SPSCommerce/colors). See the [available colors](https://github.com/SPSCommerce/colors#available-colors).

### Adding or changing colors

If you would like to add or change a color then please follow the [@spscommerce/colors instructions](https://github.com/SPSCommerce/colors#adding-or-changing-colors). Once your color has been approved and @spscommerce/colors has been released to our private jFrog Artifactory NPM then come back here and upgrade to the latest version of @spscommerce/colors using `npm install --save @spscommerce/colors@latest` or `yarn add @spscommerce/colors@latest`. 

Now choose a format that you'd like to use. The following formats are available:

• CommonJS
• CSS Variables
• JSON
• Less
• SCSS
• YAML

If you want more formats please open a pull request.

CommonJS

const colors, { red100 } = require('@spscommerce/colors');
console.log(colors.red100); // > #ffeaec
console.log(red100); // > #ffeaec

CSS Variables

@import 'path/to/node_modules/@spscommerce/colors/dist/colors.css';

.myclass {
    color: var(--gray400);
}

JSON

ln -s path/to/node_modules/@spscommerce/colors/dist/colors.json colors.json

Less

@import 'path/to/node_modules/@spscommerce/colors/dist/colors';

.myclass {
    color: @gray400;
}

SCSS

@import 'path/to/node_modules/@spscommerce/colors/dist/colors';

.myclass {
    color: $gray400;
}

YAML

ln -s path/to/node_modules/@spscommerce/colors/dist/colors.yml colors.yml

View this package on jFrog Artifactory on jFrog Artifactory

Available colors

white

black

gray100

gray200

gray300

gray400

gray500

gray600

blue100

blue200

blue300

orange100

orange200

orange300

yellow100

yellow200

yellow300

purple100

purple200

purple300

green100

green200

green300

red100

red200

red300

Adding or Changing Colors

You can add a color using these steps:

1. Fork and clone this repo then cd into it
2. yarn or npm install
3. Edit src/colors.json to add your color.
4. Run yarn build or npm run build.
5. You should now commit your changes using commitizen or the conventional-commit guidelines.
6. Put in a pull request against the main repo. A new version of @spscommerce/colors should be released on merge.
7. Finally, put in a new pull request to SPS-Styles to upgrade @spscommerce/colors to the latest version and to place the color in a color-group (if you added a new color).
8. A new version should be released when your PR is merged into master. Voila!

Commands

yarn build  # Build files from src/ into dist/ and copies a markdown
            # representation of the colors into README.md's colors
            # section. You should commit README.md after this change.

yarn clean  # Delete all files in dist/