Syntacss is a method to create and extend CSS systems. It aims to facilitate the process of organizing styles, naming classes and formatting code. It features a structure that embraces the power of cascade while works towards modularity.

Using its principles, you should get a powerful architecture tailored for modularity and a natural language syntax that results in understandable classes. No matter how simple or complex the project is, Syntacss helps you get things done right.

It drinks from a lot of great ideas. Picture it as a simplified version of Atomic Design architecture and metaphor; as having the intuitive syntax of Semantic UI; as a system that embraces principles and concepts of SMACSS, and OOCSS—all of that being compliant with mdo's Code Guide standards.

Organizing

The architecture is made of three stylesheets layers that, together, compose the design system.

Core blocks

The first layer, core blocks, contains the small foundational UI building pieces; they are a set of predetermined ingredients that will be used in the following levels. Also, they are named after the fundamental HTML tags; thus they should define base HTML styles as well.

All core blocks are interdependent, so it's crucial that the following order remains respected, even if the project doesn't need a specific block.

*Use identifier classes on core blocks only when needed. E.g., if the project doesn't have different types of tables, then a base table HTML should be enough.

Modules

The second layer, modules, are UI patterns that can easily be reused throughout the design system. They are formed by groups of core blocks functioning together as a unit.

For example, a .dropdown.module might contain .icons, .typography, and .buttons core blocks; a navigation bar may have .typography, .inputs, .buttons, and even other modules as well, like the .dropdown.module mentioned above. PS: Almost everything regarding design system has a .typography core block.

Unlike the core blocks, modules aren't predetermined—they may change according to each project's needs. So, you should create new modules as they make sense to the design system.

When a module has other modules as children elements, it should define how the nested modules are laid out, but shouldn't style them—for example, a .sidebar.module that has a .tab.module may lay out where the .tab are within the .sidebar (flex, position etc), but not how they should look (background-color, padding etc).

Pages

The third layer, pages, encompass specific styles for pages and themes. It also can be useful to tie a group of modules together, forming a cohesive layout. On smaller projects, this layer can be useful to tie core blocks together without worrying too much about modularity.

Naming

Naming things in Syntacss is quite simple. First, name a class after the core block/module/page's title. This will be called identifier class. Then, add one or more classes that describe a characteristic of the element you're working on (how it looks like? what's its purpose?). These attributes are called modifiers classes.

Take this core block .button as an example.

<button class="small rounded primary button"></button>

Here, this element has the .button identifier class that defines what it is, and other modifiers classes that tell how it looks like (.small and .rounded), and what's its role inside the design system (.primary). All of its styles are within buttons.scss file. In this case, .button.small may have sizing styles, .button.rounded border radius tweaks, and .button.primary a color theme for principal actions.

Another example: a .sidebar.module.

<aside class="sidebar module">            <!-- module wrapper -->
  <a class="sidebar logo" href="…">       <!-- module element -->
    <img src="…" alt="…">
  </a>
  <a class="sidebar link" href="…">       <!-- core `a` + module element -->
    <span class="discover icon"></span>   <!-- core block -->
    Discover
  </a>
</aside>

The .sidebar.module above has an identifier class (.sidebar) that is grouped with other modifiers classes (.sidebar.module is the main wrapper; .sidebar.logo is a sidebar's piece). It also contains core blocks like <a> and .icon. All of its styles are within sidebars.scss file.

A more complex example: a .navigation.module.

<nav class="navigation module">           <!-- module wrapper -->
  <a class="navigation logo" href="…">    <!-- module element -->
    <img src="…" alt="…">
  </a>
  <a class="navigation link" href="…">    <!-- core `a` + module element -->
    <span class="discover icon"></span>   <!-- core block -->
    Discover
  </a>
  <button class="toggle button" href="…"> <!-- core block -->
    <span class="profile icon"></span>    <!-- core block -->
    Profile
  </button>
  <ul class="dropdown module">            <!-- other module -->
    <li class="dropdown item">            <!-- other module's element -->
      <a href="…">
        Edit profile
      </a>
    </li>
  </ul>
</nav>

Summing up: an identifier class (core block, module, or page's titles) plus modifiers classes forms the naming scheme of an element.

One last note about modifiers classes: they can be either named after its structure (defining how things are laid out) or its appearance/semantic meaning (indicating how things look like or what purpose things have).

• Examples of structure modifiers: .sidebar.wrapper, .sidebar.container, .sidebar.row, etc.
• Examples of appearance modifiers: .big.button, .small.button, .rounded.button, etc.
• Examples of semantic modifiers: .active.button, .primary.button, .loading.button, etc.

Naming principles and rules

• Use of an identifier class (usually without style). Eg.: .button, .sidebar, .navigation
• Use of .module or .page as sufixes classes to wrap a module/page's children. Eg.: .sidebar.module, .login.page
• Use of interchangeable modifiers classes to set an element's appearance/behavior. Eg.: .button.primary
• Use of lisp-case for naming classes. All lowercase. Eg.: .big, .red, .box
• Use of space in HTML to separate class modifiers. Eg.: <div class="big red box">
• Composed-words separated by a single hyphen or underline (never double). Eg.: with-icon or with_icon
• Use syntax from natural languages like noun/modifier relationships, word order, and plurality to intuitively link concepts. Eg.: <button class="small rounded primary button"> or <div class="buttons">
• • Use / to visually separate different modules within a same HTML element. Eg.: <div class="big red box / narrow grid container">

Adjectives order

Use the proper English order of adjectives for achieving a more intuitive description of elements.

1. Quantity or number. Eg.: .three
2. Quality or opinion. Eg.: .beautiful
3. Size. Eg.: .big
4. Age. Eg.: .old
5. Shape. Eg.: .rounded
6. Color. Eg.: .blue
7. Proper adjective. Eg.: .brazilian, .translucid, .antique
   (Often nationality, other place of origin, or material)
8. Purpose or qualifier. Eg.: .tasty

For example, a way too much described .box.module:

<div class="big rounded blue antique brazilian box module">

Plurality to name groups

When elements of the same core block or module are grouped together, use its plural form to define a particular style within it. For example, a group of .buttons might remove margins, borders, and even some positioning.

<div class="buttons">
  <button class="small primary button"></button>
  <button class="small secondary button"></button>
</div>

Formatting

Every line of code should appear to be written by a single person, no matter the number of contributors.

Follow mdo's Code Guide standards to keep the code consistent. Things like properties ordering, values and unit format etc, are fundamental to achieve consistency.

Less/Sass style order

When declaring styles in a file, order as follow:

1. Sass/Less variables
2. HTML styles
3. Classes
4. IDs

Linter

Use SCSS Lint to help you stay on the right track. Install its plugin on your editor of choice. Also, use this Syntacss configuration file to remain compliant with mdo's Code Guide standards.

Autoprefixer

Use Autoprefixer to handle CSS vendor prefixes. In other words, you shouldn't manually write these annoying prefixes.

Git

Keep an eye on Guava's Git standards and on the following naming convention for branches.

• Use a hyphen to separate words (eg.: name-of-branch).
• Use a slash to separate branch prefix from branch name (eg.: prefix/name-of-branch).
• master—the main branch of design version.
• feature/…—adds something new.
• fix/…—fixes one or more bugs.
• chore/…—improves performance, etc.

Further reading

• Code Guide, by mdo
• Atomic Design Methodology, by Brad Frost
• An introduction to OOCSS, by Louis Lazaris
• Learning from Lego: A Step Forward in Modular Web Design, by Samantha Zhang
• Depth of Applicability, by Jonathan Snook
• BEM sucks, by Samuel Fine