Skip to content
This repository has been archived by the owner on Dec 5, 2022. It is now read-only.

Latest commit

 

History

History
255 lines (153 loc) · 9.94 KB

README.md

File metadata and controls

255 lines (153 loc) · 9.94 KB
Raw

Build Status Dependency Status devDependency Status Gitter

The Dress Code

The Dress Code is a style library / style guide which is designed for maintainability and modularity.

Used by Zalando Brand Solutions department to solve the challenge of consistency between multiple apps.

We open sourced the project because we think it's a good example of how collaboration between UX Designers and Developers is enhancing consistency and user experience with the help of technology.

If you want to know more about the history and the process behind this project you might be interested in this article.

Quick links

Main Features

  • Follows BEM — Block Element Modifier methodology

  • Follows Atomic Design principles

  • Built with Sass, that means:

    • Modular - import just what you need
    • Reusable - apply styles on your own components by using Sass mixins
    • Customizable - "tweak" the look and feel by overriding variables or extending existing classes

  • Updated interactive demo site

Status

The Dress Code core is actively maintained by two teams within Zalando. The core components are in a stable state, should you however encounter any bugs, feel free to create an issue and/or a pull request

We are always looking forward to open source community feedback and contributions especially about:

  • browser/device compatibility bugs
  • enhancements

We usually mark the issues where we would like to see community contributions with a "help wanted" label.

Feel free to open issues and/or fork the project to contribute (see Development & Contrbuting section).

Browser Compatibility

Chrome 48+, Firefox 44+, Safari 8+, IE 10+.

Semantic Versioning

The Dress Code follows semantic version standards.

However, to be clear, we must describe which part of the exposed API we consider public and which one we consider private. When using common programming languages such as Java, PHP or Javascript this concept is usually defined by the language semantics (eg. private or protected keywords) or by some naming conventions (eg. having an _underscore before the name of the function or the variable).

The Dress Code considers part of the PUBLIC API just:

  • all css class names and selectors exposed by the library
  • all mixins representing a corresponding css selector (eg. @mixin dc-btn)
  • all others documented Sass variables/placeholder/mixins (we consider a Sass variable/mixin/placeholder documented just if it's mentioned in the Sass reference published on the documentation website).

Everything else is considered PRIVATE, that means you can still use it but at your own "risk".

Getting Started

Requirements

  • modernizer ~2.8.2 included in the <head> of your web page.

Installation

npm install dress-code --save

⚠️ NOTE: We recently dropped bower support (from version 2.1.0). Keep calm and do npm.

Usage

Include this in your <head>:

<link href="node_modules/dress-code/dist/css/dress-code.min.css" rel="stylesheet">

How to use Dress Code with Sass

If you are already using Sass in your project, you can import the Dress Code directly.

@import "node_modules/dress-code/dist/sass/dress-code";
@include dc-everything; // output dc-* selectors

When using Sass, customization can be achieved by:

  • Updating variable values, you can take a look at src/styles/core/_variables.scss to see all available variables and their default values.

  • Apply mixins to your elements, nearly every css selector has a corresponding mixin.

NOTE: Given that, for example, the compiled css file will be served at /styles/main.css, by default Fonts and Images will be served from /fonts and /img path.

To adjust this behavior according to your setup, update the $dc-font-path and $dc-image-path variable values.

Compass notes

For those using Compass, you can add this to your config.rb file:

add_import_path "node_modules"

Then you can import the dress-code like so:

@import "dress-code/dist/sass/dress-code";

Development & Contributing

Developers interested in contributing should read the following:

Install

Requirements

  • node.js. Make sure your have v7.0.0 or higher installed before proceeding.

Install

$ git clone https://github.com/zalando/dress-code.git && cd dress-code
$ npm install

Start the local development environment:

$ npm start

To open a new browser window or to pass a value to browserSync open option:

npm start -- --open

Visual regression tests

Initialization:

In order to avoid unexpected visual changes we have setup an automated visual regression testing system based on PhantomCSS, which generates and compares screenshots taken on all the components of Dress Code with their previous state, based on the demo page templates, notifying the developer about all the discrepancies found so they can be reviewed and ajusted properly before opening a pull request.

This system can be initialized in three different modes by using any of the following npm scripts:

$ npm run test

$ npm run test:minified

$ npm run test:rebase

By default, with the former npm script, the system will run all the test cases using an unminified version of the artifact, which will be built to incorporate the current changes.

The second option is intended for releases, which will run the tests by using the minified version of the artifact bundled to be distributed with the new version about to be released.

Last, the latter option regenerates the baseline used for further image comparisons, which represents the current validated state of the Dress Code components. By using this option, the developer states that the changes notified by the diff are done purposely and will become the new look of such affected component from that moment on.

Test cases:

Test cases are described in tests/globals.js by specifying the name of the component (atom or molecule) to be tested and an array containing the names of the template files related to that component in the demo.

On execution, descriptive messages will be shown in console informing about each test suite's results.

Screenshots:

The system will generate a screenshot per each file and store them into several directories, grouped by component name, under either tests/screenshots/baseline or tests/screenshots/results depending on the execution mode chosen.

Since storing that many generated binary files in Git is not recommended as it may lead to problems in repositories drastically growing in size, we took advantage of GitHub's open source library Git Large File System (LFS) which replaces the content of a binary file by text pointers to the actual content location where they are stored in the server.

Please make sure to follow the steps described at their website to install and configure it properly.

Adding new icons

Make sure your icons have a size of 512x512px and flatten and simplify the paths before you export them. Place each icon as SVG file into src/icons/. Add each new icon in the demo by adding it in docs/demo/materials/03-atoms/icons/01-icons.html such as

    <div class="sg-icon dc-column">
        <i class="dc-icon dc-icon--[ICON-FILENAME]"></i><span>[ICON-FILENAME]</span>
    </div>

and replace [ICON-FILENAME] with the actual icon filename. Run npm start -- --open to see the result.

Development Environment Features

  • Sass compilation (using node-sass)
  • Sass linting (using scss-lint)
  • CSS Auto-prefixing / Optimization
  • Image optimization
  • Icon Font generator
  • Demo/docs site generator
  • Live preview sever (using BrowserSync)
  • CHANGELOG generator
  • Visual regression testing

Build & Deploy

Build distribution:

$ npm run build

The distribution build artifacts output to the dist directory.

Build demo:

$ npm run demo:build

Fabricator builds both a static documentation site and optimized CSS and JS toolkit files.

The demo build artifacts output to the .tmp/.demo directory. This can be deployed to any static hosting environment - no language runtime or database is required.

Deploy demo:

$ npm run demo:deploy

Publish the demo as github-pages website @ https://zalando.github.io/dress-code

License

Copyright 2016 Zalando SE

The Dress Code is released under the MIT license. See LICENSE for details.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.