Architecture!

After creating your project, if you navigate to the src folder you should see 2 subdirectories: sass (unless you specified a different format) and scripts.

Styles

Clarion offers a unique architecure to help reduce the complexity of styling small and large web applications and sites.

What's with the numbers?

Seeing folders prefixed with numbers may seem a little awkward or even down-right blasphemous to you at first. There is a method to this madness. The reason for it is to put the folder structure in the order in witch the styles are implemented in your style sheet. This servers two purposes:

  • Knowing the order that your styles are implemented allows you to see which rules are overriding other rules. Rules in the style sheets higher up in the folder structure will be overridden by the rules that are lower in the file structure (for example - rules in the Components section will override rules in the Elements section.
  • Understanding how the styles cascade should allow you to reduce, if not eliminate, the need to use !important. It has it's uses and appropriate applications, but abuse if this feature leads to style sheets that are painful to maintain and very difficult to troubleshoot.

00_Abstracts

This folder is for your style tools and helpers used across the project. Your reusable code such as global variables, functions, mixins and placeholders should be put in here.

The code contained in this folder should not be code that outputs CSS directly.

With larger projects you may want to break this into subdirectories like variables, functions, and mixins. Subdirectories are supported in the Clarion CLI.

01_Base

This folder holds the boilerplate code for the project. You would add your reset files and typographic rules. Keep in mind that most front-end frameworks like Bootstrap and Foundation already have their own CSS resets built into their styles, so additional resets may not be necessary.

02_Vendors

The Vendors folder contains third-party themes and plug-ins for your website. This file has been added higher in the architecture so that if you would like to create customizations, you can do so in the subsequent folders like Components, Layouts, and Pages. This will allow you to override the theme's rules without modifying the theme directly and ruining the integrity of the code.

03_Elements

The Elements folder is for styling specific elements such as links, buttons, form inputs, and header tags. These are the smallest building blocks in the web and cannot be broken up into smaller parts. Browsers, by default, have their own styling in place for these elements, but tend to be inconsistent. Because of this, adding a reset to the 01_Base directory or adding one to build pipeline is recommended.

04_Components

Components are groups of elements. This can be things like a search box, navbar, or carousel. These groups of elements together have a specific purpose.

05_Layouts

This folder contains everything that takes part in laying out the web site or application. These could be containers used for organizing elements and components within them like like a header, footer, or sidebar. This could also be used for your grid-system.

06_Pages

This folder is for any page-specific styles, if you have any. Some sites may have custom styling for the Home page or the Contact Us page.

07_Utilities

The Utilities are used to create overrides or call out specific rules for an elements or components. For example, you could have a class for making text bold or aligning it to the right. The rule of thumb is to make it specific and make it simple.

Manifest Files

Each of these directories will have an index file (index.scss). This is called your manifest file. When a new file is added to a directory, it will automatically be added to this manifest file. Feel free to reorder the import statements in this file to something that works best for you. Also, if you would like to exclude a file from compilation, you can just comment it out until you are ready to incorporate it back into the code.

Main Style Manifest

At the root of your less or sass file, you should see your main manifest file (if you used the default configuration, it will be called styles.scss). This file is your main manifest file. Inside you will find import statements for each of the manifest files from the various subdirectories.

Customize the Architecture

That's right! If this naming Convention doesn't work for you or you feel like it is missing something, feel free to change it up. Just make sure you update the references in the references in the main manifest file.

Adding New Directories

Not only can you rename directories, but you can also create new directories. A popular trend is to create a directory called "Shame". This directory is used for adding style hot fixes until the style can be added to the appropriate file later. The idea is to have this file lower down in the architecture so I overrides any of the previous rules. Adding a new directory is similar to adding a new file, but we use the directory keyword.

clarion add directory 08_Shame

You should now see the new directory along with your other style directories and in it you will see the index manifest file. You will also see a reference to the new directory's manifest file in the main styles manifest file.

Scripts

The default script section was intentionally left fairly simple. The components directory is used for component-specific JavaScript like menus and modals. The services directory is used for reusable functions and methods.