Design Principles

Simplicity

Simple is not just in our name, simple it at the heart of our product design philosophy. Simplicity doesn't mean easy, nor dumbed down. Simplicity means nothing is more complex than it needs to be.

Data over decoration

The Simppler applications are full of data and that data is at the heart of the user's experience with Simppler. The data is the star of the show at all times, and all of our design is in service of taking the data and delivering it to our users so that it can quickly and easily become knowledge.

Interactive content

Many applications are interactive widgets with content inside. Simppler is content that is interactive when it needs to be. The value of our product comes from our users being able to quickly understand the data we provide and take action on it in service of their larger daily goals.

Trust in experts

While our primary audience for Simppler is recruiters doing the work of recruiting, trust in experts extends beyond our recruiter users. We trust in the skills of our users when it comes to the work we know is part of their daily jobs and we trust that they know their social networks better than we do. Trust means we provide options to our users and let them make the best decisions for the tasks they're trying to accomplish with our tools, from sending a message to sourcing a highly specialized candidate.

Styling Your Sass For Sandwich

Formatting

We have borrowed heavily from AirBNB's very well thought out CSS/Sass styleguide

General

• Use soft tabs (2 spaces) for indentation
• Prefer dashes over camelCasing in class names.
• Do not use ID selectors
• When using multiple selectors in a rule declaration, give each selector its own line.
• Put a space before the opening brace { in rule declarations
• In properties, put a space after, but not before, the : character.
• Put closing braces } of rule declarations on a new line
• Put blank lines between rule declarations
• Always use .scss, never .sass
• @include directives always at the beginning, so they can be overridden as needed

Comments

• Prefer line comments (// in Sass-land) to block comments.
• Prefer comments on their own line. Avoid end-of-line comments.
• Write detailed comments for code that isn't self-documenting:
  • Uses of z-index
  • Compatibility or browser-specific hacks

Styling separate from structure

Wherever possible, styles that define the structure of a module or component should be separated from styles that define the appearance of that module or component. We do this because structure is often portable while appearance maynot be.

Borders

Use border: 0 instead of border: none to specify that an element has no border.

ID selectors

While it is possible to select elements by ID in CSS, it should generally be considered an anti-pattern. ID selectors introduce an unnecessarily high level of specificity to your rule declarations, and they are not reusable.

Nested selectors

Nested selectors, if you need them, always follow any other rule declarations. There should always be a single line of whitespace between your rule declarations and nested selectors. Your nesting should never be more than 3 branches deep.

.incorrect {
  .foo {
    .foo2-the-sequel {
      .foo3-the-revenge {
        // Always stop at three, nothing good ever comes after that
        .foo4-in-too-deep {

        }
      }
    }
  }
  // rule declarations should always come before nested selectors
  display:block;
  font-size:1.7rem;
}

.correct {
  display:block;
  font-size:1.7rem;

  .foo {
    .foo2-the-sequel {
      .foo3-the-revenge{

      }
    }
  }
}

Naming

We require an OOCSS approach with a single-level of BEM naming. We use a variant of BEM where blocks are separated from elements by a double underscore ( __ ) and elements are separated from modifiers by a double hyphen ( -- ). This allows us to use single dashes to represent spaces in class names.

Markup (the JSX would follow the same structure)

<div class="card--employee-contacted-card">
  <div class="activity-feed">
    <h2 class="activity-feed__title">Contact history</h2>
    <ul class="activity-feed__activity-list">
      <li class="list__item">
        <div class="list__item--row activity-feed__row-one">Responded to message</div>
        <div class="list__item--row activity-feed__row-two">August 17th, 2017</div>
      </li>
      <li class="list__item">
        <div class="list__item--row activity-feed__row-one">Sent message</div>
        <div class="list__item--row activity-feed__row-two">August 14th, 2017</div>
      </li>
    </ul>
  </div>
</div>

Sass

.card--employee-contacted-card {}

.activity-feed {

  &__title {}

  &__activity-list {
    // this is an apperance only style. list__item--row is defined in the multi-line-list mixin.
    .activity-feed__row-one {}

    .activity-feed__row-two {}
  }
}

Variable names

Variables should be named in dash-case, $some-variable, not camelCased or snake_cased.

Javascript hooks

Avoid binding to the same class in both your CSS and JavaScript. Conflating the two often leads to, at a minimum, time wasted during refactoring when a developer must cross-reference each class they are changing, and at its worst, developers being afraid to make changes for fear of breaking functionality.

We recommend creating JavaScript-specific classes to bind to, prefixed with .js-:

<button class="button--primary js-destroy-deathstar-button">Destroy the Deathstar </button>

Mixins

We use mixins to DRY up our css. Styles are built modularly just like the rest of the UI. Use mixins to define reusable structures or decorative styles where ever possible.

Extend directive

@extend should be avoided because it has unintuitive and potentially dangerous behavior, especially when used with nested selectors. Even extending top-level placeholder selectors can cause problems if the order of selectors ends up changing later (e.g. if they are in other files and the order the files are loaded shifts).You can DRY up your stylesheets nicely with mixins.

Linting

We are using sass-lint for linting. There are multiple options for IDE integration for sass-lint. The configuration is stored in the .sass-lint.yml file in the rooter directory of the project.