zalando
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:warning: 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-* selectorsWhen using Sass, customization can be achieved by:
Updating variable values, you can take a look at
src/styles/core/_variables.scssto 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/fontsand/imgpath.
To adjust this behavior according to your setup, update the$dc-font-pathand$dc-image-pathvariable 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.0or higher installed before proceeding.
Install
$ git clone https://github.com/zalando/dress-code.git && cd dress-code
$ npm installStart the local development environment:
$ npm startTo 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:rebaseBy 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 buildThe distribution build artifacts output to the dist directory.
Build demo:
$ npm run build:demoFabricator 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 deploy:demoPublish 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.