Code Conventions

Make it modular – There should be clear separation between components. When someone goes to work on a component there should be no confusion what files they should be editing.

Legibility is key – Developers should be able to understand CSS code at a glance and understand the purpose of any given selector.

Keep It Simple – Nesting in Sass can be very convenient, but runs the risk of poor output with overly long selector strings. We follow the Inception Rule and never nested Sass more than three layers deep.

Avoid conflicts – Since our design system code is going to be introduced into an app with much legacy styles we need to ensure that our styles do not conflict with other libraries and systems. This is accomplished by the system’s namespacing of class names, described in more detail below.

Global Namespace

All classes associated with the design system are prefixed with a global namespace, which is the name of the system followed by a hyphen:

.sage-

For example a Card component in sage looks something like this:

/* card.scss */

.sage-card {
  &__img { }
  &__title { }
  &__subtitle { }
}

Design Tokens

We utilize design tokens in the form of Scss variables. These variables are namespaced in the same way that classes are so that we do not run into conflicts with other Scss code.

sage-font-height()
sage-font-size()
sage-font-weight()

We utilize Scss functions to create these tokens so that you are able to pass in modifyers to get different values as needed.

sage-font-weight(regular)
sage-font-weight(semibold)
sage-font-weight(bold)

sage-font-size(xs)
sage-font-size(sm)
sage-font-size(md)
sage-font-size(lg)
sage-font-size(xl)
sage-font-size(2xl)
sage-font-size(3xl)
sage-font-size(4xl)

Parent Selectors

The design system will make use of Sass’s parent selector mechanism. This allows all rules for a given component to be maintained in one location.

/* button.scss */

.sage-btn {
  /* Button In Sidebar Takes Full Width */
  .sage-sidebar & {
    display: block;
    width: 100%;
    text-align: center;
  }
}

Media Queries

Component-specific media queries should be nested inside the component block.

/* button.scss */

.sage-btn {
  /* Button On Small Screen Takes Full Width */
  @media (min-width: sage-breakpoint()) {
    display: block;
    width: 100%;
    text-align: center;
  }
}

Utilities

Utilities should be used sparingly and only when there is no way to accurately modify the block to fit the needs of the mockup. If you find yourself in a situation where you are tempted to use a utility class it might be a good opportunity to reach out to the product developer and ask if the unique treatment in the situation is needed.

Utilities do not play well with responsive styling so a utility class should be used only in cases where the same treatment is needed on every device. When in doubt reach out to the designer or another developer.