Design Concepts Style Guide Notes Github

Hello, Sassypants.

This "Style Guide" (or cheat sheet) is a collection of loosely nested dependent components and elements. The basic ones are built with SCSS, and complex ones with SCSS + JS. - Each component needs to be as independent as possible.


Stylecoeur is a personal cheat sheet and boilerplate to make prototyping or development both quick and professional. It's my own alternative to Bootstrap. It prioritizes development speed over reliability and load times. It uses grids and flexbox for layouts, so modern browsers only (no polyfills provided).

Stylecoeur is for prototyping, and not for every project.

  • Priotitize speed of development.
  • More reuse, less complexity. Use helpers; include files. Dno't reinvent.
  • This is only a collection of examples. Build off of them
  • Use as much open source as possible
  • Everything is alive; every aspect will improve over time.
  • This documentation will ALWAYS be behind (even changelog), so inspect the code for the latest updates


The base framework is stylecoeur and is loosely based on atomic design.

  • _heart.scss — contains units, sizes and other base definitions
  • /head — provides the core dependencies, like typography, color, animation mixins, and grids
  • /neck — consists of basic display assets like links, cards, and buttons
  • /torso — is all the components that depend on the heart, head and neck. These may also require js

Component Names

Naming convention is inspired BEM, and keeps elements and components organzied. These are not hard and fast rules, but suggestions. This is a simpler version of BEM.

< element class="element _component_name-attribute1-attr2 --state_1 --state_2 ></element>
  • .element Local objects are called elements and only exists for the page or component
  • ._component Global stylecoeur components (like buttons) contain a leading underscore
  • .element_one `. Use underscore to separate words
  • _form-section-one Use dashes to add attributes: .element-descriptor-attribute, ._color-bg-yellow describes color with a -bg (background color), and -yellow (yellow background color)
  • _component .--descriptor State descriptors, are defined with --state flags, like .container .--open or ._message .--success. Descriptor flags are useful when they can be reused.

Here's a quick example of how this would work in SCSS:

._component-title {

  &.--open {
    [open styles]
  &.--success {
    [success styles]
  • When defining styles use separate variables for definitions and context, but make sure to always refer to the context variable when possible. This separation makes changing context colors easier in the future (like switching $color-success to $color-blue):
 $color-green: #00ff00;         // definition
 $color-success: $color-green;  // context
  • Options for SCSS rules exist as %placeholders, ._classes for ease. Sometimes it makes more sense to drop in styling like margins, paddings, and alignment straight into html with class="_padding-top" instead of creating lots of stylesheets

  • Using - to separate names and descriptors helps with double-click selecting the entire name. BEM syntax .my-component__list-item is annoying b/c double clicking the component name selects the wrong parts of the name. Instead, .my_component-list_item allows you to select the right parts with a simple double-click
  • Avoid the use of &–state as much as possible, as these are hard to search for with cmd-f
  • Keep reusability and extensibility in mind
  • Use contextual variables!! Don't just copy rule definitions like colors or font size.

Just remember to maintain modularity, and separate context from the definition. Helpers and components should be as reusable as possible.

Using stylecoeur

The style guide is very modular, so only link the SCSS components you need to keep the file size down. Either include the entire thing or select what you want to import. Remember that they depend on each other to work.

  • @import '_styles/' to automatically import the index.scss file which contains all parts, or
  • individually import each part like @import 'neck'; or
  • import each module separately @import 'neck-code';

Copying Files

Preferred Method: Copy the full styles folder over to a new project. If the core changes, just make sure to copy over the newest version. Eventually there might be a build task to ensure it stays up to date. This method is preferred, as changes to the core won't affect the build. Copy over whatever JS files you need and/or link to them.

Symlinked Project

Creating a symlink will give control of editing the core, but changes ripple across projects if they're all symlinked. [right-click to create an alias doesn't work with the compiler] Using the command-line interface, go to your new project's SCSS folder, then:

  1. Create a direct symlink file:
ln -s ~/path/to/stylecoeur_folder/styles/index.scss _stylecoeur.

Note how the name is changed to _stylecoeur.scss to conform to SCSS naming standards, but it doesn't really matter.

  1. Or create a symlink to the folder in CLI. Navigate to the project's stylesheet folder:
ln -s ~/path/to/styles/stylecoeur_folder stylecoeur
ln -s /Users/janzheng/Desktop/projects/stylecoeur/styles stylecoeur

I prefer the latter option, because you can now import the folder as a whole:

@import 'stylecoeur/stylecoeur.scss';

or pick specific compontents

@import 'stylecoeur/components/form';

(Symlinks are simpler than using an npm module, since projects like static sites might not use symlinks)

Developing Stylecoeur

Please refer to the developing stylecoeur section for running, building, deploying and developing Stylecouer further.

Other Resources