@dollarshaveclub-engineering/ui v2.6.4

UI is a CSS framework for interfaces commonly built at Dollar Shave Club. Jump to the code here. or dive into the interface.

• Guide
• Features
• Installing
• Developing
• Linting
• Deploying
• Contributing

Features

• Easy to include, just use a link tag.
• Small, clocking in at roughly 25.6kb.
• Create composable interfaces that are easy to make your own.
• Technology/Framework Agnostic, but still developer friendly.
• Generous documentation and examples.
• Source of truth for DSCs current standards in design.

Installing

HTML

The artifact of ui is a CSS file. Place the following code in the head of your document.

<!-- For including the local development version -->
<link rel="stylesheet" href="/face-assets/ui/local/ui.css">

<!-- For including a particular version -->
<link rel="stylesheet" href="/face-assets/ui/1.0.0/ui.css">

If integrating with face-assets, you may include that exact URL which will enable automatic integration with every environment, including local.

If you are not integrating with face-assets, you can include the CSS file in your application however you see fit.

NPM

Install UI via NPM

npm i --save-dev git+ssh://git@github.com/dollarshaveclub/ui

You are free to include node_modules/ui/dist/ui.css in your project however you see fit.

If you wish to import it via SASS, you must first specify the ui scss src folder as an includePath in your sass build configuration

// Your sass build may be different. Reference SASS includePaths for more information
const sassOptions = {
  includePaths: [ './node_modules/ui/src/' ],
}

Then you may import variables or mixins via sass

// Import UI Config or Mixins
@import "ui/config/colors"
@import "ui/mixins/breakpoints"

Developing

Developing with ui locally is easy.

nvm use # Ensure you're on the correct version of node
npm i # Install node dependencies
npm run build # Compile CSS and documentation
npm run build-watch # Builds & watch for changes
npm run prepublish # Builds UI react components and places them in dist/components
npm start # Serve documentation page

If you have face-assets installed in your local dev environment, the build task will copy the CSS files there automatically which will allow you to reference the latest local build file from a simple URL.

Building and Using UI React components

In order to use the react components and render them in storybook or consuming react app, you will need to run npm run prepublish. Prepublish runs a build task to be able to use it as a dependency in the consuming apps.

Example on how to include the component in your react components:

import BreadcrumbsLarge from 'ui/dist/components/breadcrumbs/large'

Linting

Linting is required to merge any branch to master. They not only dictate any style guides we'd like to adhere to, but help enforce various rules such as nesting depth and use of hex colors.

The linting rules are still a work in progress. Please read the contributing section if you want to add or modify any rules.

apm install linter-stylelint # Install the StyleLint for Atom
npm run lint # Run all linters
npm run eslint # Lint JavaScript
npm run stylelint # Lint SCSS

Deploying

This process is nearly identical to deploying face-engine.

1. Make your changes in a feature branch while being sure to update the version number in package.json. Also be sure to commit all dist files!
2. Merge to master through GitHub
3. Wait for circle job to create a tag for the new UI changes
4. In face-assets, run npm run download-ui, commit the resulting files, and deploy!

FAQ

How do I use this?

• Include the CSS file into your application in any way you see fit, or refer to the install section for more information. Then just use the class names and DOM structures provided in the documentation.

Why does this exist?

• Core visual components should be standardized. This means that there is a right way and a wrong way to style certain things, which makes it much easier to get right than it does to get wrong. CSS is hard, and this set of styles aims to provide consistency and harmony to compensate for that.

Why SCSS?

• SCSS was chosen because it is lexicographically easier to parse. This means that more libraries can interpret our styles and provide constructive feedback on things such as specificity, redundancy, and common predetermined conventions. SCSS = Acorn as ES6 = Babel. AST FTW.

I am on a different platform than the web and cannot adhere to these standards. What should I do?

• The styles demonstrated in the kitchen sink are exemplary of designs current standards. While each platform's requirements may differ, it is worthwhile to consider the holistic intentions design has set forth. If you feel some things are strangely out of place, consider opening a pull request to share your needs.

BEM is love. BEM is life. Right?

• The core difficulties most of us face with CSS are the same things that makes it so powerful; that is largely the cascade. BEM is not meant to be a dogmatic solution to all of our issues. It provides a set of rules that enable us to develop interfaces in equally powerful ways while still managing the cascade.

• Not every classname will follow BEM conventions, but that is ok. Most classes tend to do so where applicable. Considerate code review helps thwart oddly specific rules, but also allow strategic advantages in the code.

I want access to the variables and mixins UI provides, not the CSS

• Not a problem. Simply install ui with any package manager that supports git or github. Then simply build the src/index.scss file or build your own scss file that imports the desired ui files.

Contributing

Anyone may contribute to ui as long as the proper checks have been passed. If you're interested in helping with the migration to ui, anything in the UI - Transition project is "up for grabs". In favor of authoring code that meets UI standards, consider opening an issue or discussing with any UI counterparts beforehand.