This doc describes guiding principles and philosophy behind the styleguide.
To get up to speed on the specifics of Architecture, see architecture.md.
For conventions and implementation details, see conventions.md.
To generate this living style guide we use Hologram, which creates a style guide by taking metadata from the actual Sass files and compiling that to static HTML & CSS.
The styleguide becomes the contract between engineering and design. By having an enforced style guide, we can ensure a seamless transition from design to engineering.
To make it easier for back-end developers to quickly re-use an existing module, a living style guide is helpful. It contains a collection of markup for all available modules and components. By applying the current version of the actual CSS to this collection, developers can visually pick a module or component, copy/paste its markup or use the appropriate class name and "it just works".
DRY is a principle of software development aimed at reducing repetition of information of all kinds, especially useful in multi-tier architectures. When the DRY principle is applied successfully, a modification of any single element of a system does not require a change in other logically unrelated elements. Additionally, elements that are logically related all change predictably and uniformly, and are thus kept in sync.
In practice, the goal is to create something only once, and to create it in such a way that it can be easily reused. For example, an button shouldn't be "created" anew each time it is used in a design or it is implemented. It should be sufficient to only include a marker that says "include button here." The added benefit of this is that if the button itself changes, all instances of that button are automatically updated. Instead of creating a new element, maybe you really only need variant. For an element that is more complex, perhaps you can build it from existing smaller elements.
"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system".
There is plenty of literature on the web about responsive desgin, so there's no need to go into detail here. As part of our overriding DRY philosophy, don't create multiple versions of an element - create a single version that is responsive and conforms to its available area, be it a viewport, a layout bay, or whatever.
(Avoid "one-off" designs, fixes, and code)
When designing/implementing new elements, do so with an intent for reusability. Ask yourself, "How can I design/build this so that another person can easily incorporate it into their project? How can I make this element so that it's easily amenable to becoming a new variant."
This is basically a reiteration of the DRY philosophy, but it emphasizes the practicality of creating something once.
Another way of saying this is that one should avoid specificity in development - try to avoid creating elements, styles or functions that can only be used once or are page/context-specific.
DON'T Create Page Specific Styling: Page specific styling is used to style elements based on the page they appear on. This isn't a modular approach, because code can't be reused without duplicating CSS (or at least adding more selectors to the CSS). By scoping styles to (grouped) elements instead of pages, they are made portable, reusable and predictable.
When you need a new element, you should first check to make sure that the element hasn't already been created.
If you truly need to create a new element, first determine the purpose of the element. What sub-elements does it need? Is it truly a new element, or is just a variant of an existing element? How would you determine if the element is accomplishing its goal?
See architecture.md to help you answer these questions.
Separation of Concerns (SoC) is a defining characteristic of modular design. Fundamentally, structure, styling and behavior should all be handled in separate areas of the code base.
Additionally, elements should have their own roles and responsibilities that can be easily identified and which should not overlap (i.e. The Single Responsibility Principle). There are many reasons for this, but the reason most important to our guiding philosophy is that this allows elements (atoms / molecules / organisms / etc.) to be responsible for a single job, regardless of the context in which they are used. For example, a submit button should be used for submitting a form. It shouldn't care which form it's submitting. An user profile card (an organism) should display user information, regardless of which user or what page or what else is going on around it.
Predictable Code By taking a documented approach that takes into account SoC between structure, styling & behavior, there's no guessing in how one is tied to the other. Predictable code leads to less ad hoc changes and makes for easier transfer from front-end to back-end. This leads to both developer and designer happiness.
Portable Code Predictable code is portable. It can be re-used without side-effects, because of SoC.
Extensible Code The SoC makes it easy to add new modules are extend existing ones without having to guess its implications. This also makes code less prone to regression, because it's predictable how changes are reflected throughout the application.
Write "Self-documenting" Code when possible, document when it's not.
The separation of concerns as well as clear standards on code structuring and coupling makes code self-documenting. By looking at the markup, it's instantly clear where code and assets reside in the project.
In most cases good naming and good structure will reveal intent. If what you've created isn't intuitively understood, leave an explanation as a comment for the next person.
What is the "Pit of Success"
The "Pit of Success" is a concept that anyone that is following our prescribed rules of engagement (this guide, for example, or a UX flow) should simply "fall" into winning practices.