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

  • By Zalando SE
  • Last update: Dec 9, 2022
  • Comments: 16

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


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


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


npm install dress-code --save

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


Include this in your :

<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:



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


$ 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


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.


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


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


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.




  • 1

    feat(button-link): add button link and button link with icon #137

    • feat(button-link): add button link and button link with icon #137
    • chore(fabricator): downgrade to 1.1.10 due to an issue, see https://github.com/fbrctr/fabricator-assemble/issues/40 #137

    PLEASE RUN: npm update fabricator-assemble

    @dami-gg @gabrielhl @xonic @mrac WDYT?

    !!! #159 must be merged before this one !!!

  • 2

    What if... PHANTOM CSS? (visual regression testing)

    I would really like to setup visual testing to prevent regression.

    I great article about visual testing: https://css-tricks.com/visual-regression-testing-with-phantomcss/

    @alexisinwork @mrac Can you help us on this one?

  • 3

    Topic/304 update release scripts

    #304 #293

    • To test this PR, make sure to remove && npm run push:release from the postrelease script before running the npm run release <VERSION> script.
    • After testing, you need to delete the created branch and revert the last commit.
  • 4

    topic/283-node-sass lint

    • remove "star hack" was causing problem to linter and is not needed since we don't support ie6/ie7 hopefully
    • remove scss-lint in favor of sass-lint
    • fix linting issue after introducing sass-lint
    • remove ruby, sass, scss-lint from development requirements (yeah nodejs all the things)
  • 5

    Support for latest Modernzir

    Dresscode depend on outdated Modernizr 2.8.3. Let's update for ver.3.x.x.

    In meanwhile we could add to README how to install the old modernizr. It can be done via: npm install --save [email protected]

  • 6

    Add "loading" state for the dialog molecule

    Most probably we will have to call endpoint before closing the dialog, like validating the username/password, etc

    So I think it'll be helpful to have "loading" state for the dialog like this, that blocks the user from submitting again or closing the dialog (we can make the closing optional, by adding/removing the close button like what I have here 👇)

    screen shot 2016-11-08 at 09 59 51


    • [ ] Add new state blocked to the dialog
    • [ ] Supports displaying loading and text+button
  • 7

    react support

    I know that your library do not have any "pre-defined" atoms and molecules for react. Have you heard about any extension that helps to utilise you library with react?

  • 8

    Add users icon; update help and user icon.

    Closes #319

    @dami-gg Here are the new/edited icons. The issue here is that if someone updates DC without updating to the new nav they will get the new user and help icons in the old nav.

  • 9

    Add vertical/horizontal tab to dress code

    Sometimes a number of charts or lists are to be shown to user, but user doesn't view them simultaneously. These view may or may not share context.

    Dress code should have vertical/horizontal tab css to show tab component as below.

    screen shot 2016-08-15 at 18 04 45 screen shot 2016-08-15 at 18 04 55 screen shot 2016-08-15 at 18 05 13
  • 10

    feat(input): add input-stack molecule

    Add input-stack block/molecule to close #396, this approach was taken to don't introduce breaking changes in v2. Must be reconsidered in v3.

    closes #396

    @xonic @sambhav-gore I am not 100% sure about this feature

  • 11

    Switch to yarn?

    Some of us have been using yarn over npm, and a yarn.lock has made its way into the repo. We should decide if we want to encourage contributors to use yarn instead of npm, including updating the yarn.lock when package.json changes.

  • 12

    Checkbox icon displayed incorrectly with non-default font size settings in Google Chrome

    Expected Behavior

    The icon should scale together with font size settings, or it should be centered in the checkbox rectangle.

    Actual Behavior

    The icon image is broken (e.g. with increased font size):



    Steps to Reproduce the Problem

    1. Open Settings: chrome://settings/
    2. Change font size to 'Large'.
    3. Navigate to a website using dress-code checkboxes.

    Your Environment

    | Tech | Version | |--------------|---------| | Dress Code | Where to look it up? ;-) | | Browser | Google Chrome Version 69.0.3497.100 (Official Build) (64-bit) | | OS | Ubuntu GNU/Linux 18.04 |

  • 13

    Regression tests mismatch when running in Travis

    When running visual regression tests in Travis CI, we get some errors on some components, for example:


    After some investigation, it could be related to differences in font rendering in different OS, since the current baseline is created in our Mac machines and Travis is running Ubuntu:


    It is actually really hard to figure out right now what's the diff found since Travis discards the instance right after it finished. It would be really useful to try to publish the failures somewhere so we could check in case an error happens. This article proposes a possible solution:


  • 14

    chore(npm): automate release and publish task

    Automate release and publish task with travis to always tests and publish from clean state.

    A proposal or more proposal on how the flow should work should be presented before hand.

  • 15

    Accessible colors & typography

    Dress code color palette is not yet accessible (especially primary blue). The color palette needs to be improved, some guidance on color usage should be added and typography needs adjustment to improve readability.

  • 16

    Update normalize.css and have a better strategy for including normalize

    Update to latest version of Normalize https://github.com/necolas/normalize.css

    We can also think about a better strategy for including the normalize lib.