Menu

Inclusion
Single-page framework

Experimental scss/less framework, this time for single-page layout.
Part Two: dark side

Scroll down

Dark side. Basics

Actually this is just another part of Inclusion home page with technical details, shortcodes and cheatsheet. But I've decided to make it in dark colors using current framework's options. It's just because when I find some interesting things like frameworks or similar tools I'd like to see how their demo represent all abilities and worth. That's why Inclusion have so huge demo and complex home page..

In the first part we talked about importing inclusions and styling our markup, and then we checked demo with all available elements. But what exactly we have inside Inclusion?
First of all this is typography. In this project there are three basic fonts and two helpers, that was properly chosen:

I'm tried to be ascetic with fonts and use common safe system fonts. For this purpose I've used nice website CSS Font Stack, which show us percent of system support for each font. For custom fonts, like Open Sans was used google fonts cdn. (There are local copies of used fonts inside framework's font directory). Monospace fonts were used for Prism syntax highlighter. As for iconic font - it was used for all those little icons, and exactly this font set was customized by Fontello - we've got lightweight and responsive solution.

CSS Font Stack complete safe fonts collection
CSS Font Stack

Colors were one of important parts of work with fonts and page in general. So there are four basic colors: dark (#2b2b2b), light(#efefef), and two others - their shades, lighten-dark (30% lighten than dark color) and darken-light (30% darken than light color). Of course there is special color palette for code highlight but it's just customized Prism color scheme.
If we talk about colors, I must said that there are two transparent dotted pattern-images for jumbotron sections: light and dark. This trick allows us to use text blocks within jumbotron section with contrast background images.

One important thing - all block elements in this framework have box-sizing equal to border-box and it's defined in reset file.
There is one component - external mixin library, it's just useful mixins like transformations, shadows or calc-mixin. Or you can use native css3 properties with autoprefixer instead this lib.

Layout

One column page layout with some extra areas.

This framework doesn't have any traditional grids, but there is one option - extra margins. It allows us to position content a little bit outside our container. Actually it's something like trick, because in general main column - special container element has 1200px width and 120px side paddings. But in our case box-sizing property is set to border-box, so we get empty areas around content.
Also almost each inclusion have $position option, that allows us to float elements (if value is "left" or "right") and give them width equal to 47%. If $position set to center - element's width is equal to 90% and clear: both.
When we use $extra option for element and set it to extra - we give negative margin to this element equal to side padding. As a result we have elements with "extra margin". It looks pretty nice)

Under spoiler you can see screenshot with demo of large page layout with float and extra positioned elements.

Large page layout
Layout for screens which width is 640px-1200px
Large layout

For screens which width is less than 640px, floated elements have width equal to 90% with no extra margins. That's why Inclusion doesn't support old browsers - extra margins and extra width options created with css3 "calc" property.

Under spoiler you can see mobile layout, for devices which screen with is less than 640px

Mobile page layout
Layout for screens which width is less than 640px
Mobile layout

We need to go deeper... or grid system

For some reason, like creating gallery or something else I've decided to create several inclusions to generate grids right inside Inclusion. It's pretty easy and very useful.

Actually there are four mixins: grid container, grid column, grid row, push and pull. So this is not about layout, but this like layout inside layout (yo dawg heard you like layouts...) More inclusions and usage about usage you can find in a Cheatsheet section

Right, now we know about basic components and idea of page layout, so we can talk about usage of framework and discuss the next theme: "pretty code vs messy compiled code in case of performance" - each choice will bring us to different solutions (to use extends or mixins). Yeah, I have thought about this too:)

Usage

How to start using Inclusion with all these mixins and parameters

Here we'll check quick start examples and compiled output code. This is important, because if for some reason we need nice and readable compiled css we should take other version of current framework. We'll talk about this later and now - quick start!

Right now we'll create page in a few steps. Let's say we have boilerplate like this one:

 
<!DOCTYPE html>
<html>
	<head>
		<title>Some page</title>
	</head>
	<body>

	</body>
</html>				
							
Example of boilerplate

Ok, we added styles and scripts. Inclusion's scripts based on jQuery lib, so we connected it too. In our stylesheet we have imported framework.

We use preprocessor, so our style.scss stylesheet will be compiled and then minified into style.min.css

 
<!DOCTYPE html>
<html>
	<head>
		<title>Some page</title>
		<link rel="stylesheet" href="styles/style.min.css">
	</head>
	<body>

	<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>        
    <script src="js/assembled.min.js"></script>
	</body>
</html>				
							
Connection of styles and scripts in our markup
 
/* ==============================
   $Inclusion styles
   ==============================*/
@import "inclusion.scss";				
							
Import framework in our stylesheet

Pretty good, now we're ready to create amazing things. For example, here we've added some markup: title, image, paragraph, blockquote and then we've applied some styles using Incusion.

 
<!DOCTYPE html>
<html>
	<head>
		<title>Kittens ipsum</title>
		<link rel="stylesheet" href="styles/style.min.css">
	</head>
	<body>
		<section class="kittens-sect">
			<div class="container">
				<h2 class="kittens-title">Kittens ipsum dolor sit amet:)</h2>
				<figure class="kittens-img">
					<img class="js-lazy js-view" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" 
					data-src="/src/lab/inclusion/img/kittens.jpg" 
					data-title="Kittens ipsum" 
					alt="A bunch of cute kittens" />
					<figcaption>A bunch of cute kittens</figcaption>
				</figure>
				<p class="kittens-text">Kittens ipsum dolor sit amet, use lap as chair, for leave hair everywhere so jump off balcony, onto stranger's head. </p>
				<blockquote class="kittens-bq"><p>Flop over flop over scamper run in circles. Shake treat bag. Flop over chase mice, or intrigued by the shower chase imaginary bugs.</p></blockquote>
			</div>
		</section>
	<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>        
    <script src="js/assembled.min.js"></script>
	</body>
</html>				
							
Kittens ipsum in action!
 
/* ==============================
   $Inclusion styles
   ==============================*/
@import "inclusion.scss";

@include selection($color: light);  

body{
	@include body($align: left, $color: dark);
}
.container{
	@include container();
}
/* ==============================
   $Kittens styles
   ==============================*/
   	.kittens-sect{
		@include section($bg-color: dark, $shadow: false, $align: center);
	}	
	.kittens-title{
		@include typo($align: center, $font: serif);
	}
	.kittens-img{
		@include figure($type: image, $position: left);
	}
	.kittens-text{
		@include typo($align: justify);
	}
	.kittens-bq{
		@include blockquote($align: center);
	}				
							
Styles for our kittens ipsum example

And here is the result! Only six inclusions and we've got nice page. If we want to change position, align or color - just need to set other value to desirable property. Using of this framework makes creating typical pages faster with awesome results.

Kittens ipsum demo

Kittens ipsum dolor sit amet:)

A bunch of cute kittens
A bunch of cute kittens

Cat ipsum dolor sit amet, use lap as chair, for leave hair everywhere so jump off balcony, onto stranger's head. Present belly, scratch hand when stroked destroy couch. All of a sudden cat goes crazy stand in front of the computer screen, but destroy couch, but hide when guests come over, and chase dog then run away destroy couch. Jump off balcony, onto stranger's head climb leg, and use lap as chair. Destroy couch chew iPad power cord, so shake treat bag give attitude, and chase imaginary bugs. Give attitude stick butt in face. Chase imaginary bugs inspect anything brought into the house. Scamper sleep nap climb leg. Give attitude eat grass, throw it back up and swat at dog eat grass, throw it back up for hunt anything that moves chase dog then run away but hopped up on catnip. Nap all day sun bathe.

Flop over flop over scamper run in circles. Shake treat bag. Flop over chase mice, or intrigued by the shower chase imaginary bugs.

Predefined elements

Some complex page elements like images, code blocks, spoilers or blockquotes need some special structure and here I'll give an example of markup for them:

 
<!-- Apply header() mixin  to this page element-->
<header class="main-header">
	<!-- ...and nav() mixin to this nav -->
	<nav class="navbar js-nav">
		<ul>
			<!-- Don't forget for all this js hooks class names! -->
			<li><a class="js-anchor js-link" href="#home">Home</a></li>
			<li><a class="js-anchor js-link" href="#about">About</a></li>
			<li><a class="js-anchor js-link" href="#demo">Demo</a></li>
			<li><a class="js-anchor js-link" href="#download">Download</a></li>
		</ul>
	</nav>
	<!-- ...and hgroup() mixin to this header group -->
	<div class="hgroup">
		<a class="js-navtoggle" href="#">Menu</a>					
		<ul>
			<li><a class="is-selected">en</a></li>
		</ul>
	</div>
</header>				
							
Header and nav markup example
 
<!-- Apply section() mixin this element --> 	 								
<section class="home" id="home">
<!-- Apply container() mixin to this element --> 	
	<div class="container">
		<!-- content goes here -->
	</div>		
</section>				
							
Section markup example
 
<!-- Apply figure() mixin with `image` option to this element --> 								
<figure>
	<img class="js-lazy js-view" src="data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7" data-src="img/demo.jpg" data-title="Title for full view caption" alt="Description for full view caption" />
	<figcaption>Caption for this picture</figcaption>
</figure>				
							
Image figure markup example

<!-- Apply figure() mixin with `code` option to this element --> 		 								
<figure>
	<pre><code class="language-javascript">	
	</code></pre>
	// Your javascript code example with syntax highlight goes here
	<figcaption>Caption for code example</figcaption>
</figure>				
							
Code block markup example

<!-- Apply blockquote() mixin to this element --> 								
<blockquote>
	<p>Lorem ipsum dolor sit amet, consectetuer adipiscing elit. </p>
	<cite><a rel="nofollow" href="http://www.lipsum.com/">Lorem Ipsum is simply dummy text of the printing and typesetting industry</a></cite>
</blockquote>				
							
Blockquote markup example
 
<!-- Apply block() mixin with `spoiler` option to this element -->
<div class="js-spoiler">
	<a href="#" class="js-panel">Spoiler title</a>									
	<!-- Content goes here -->
</div>				
							
Spoiler block markup example

Performance vs pretty output code

Well, we've seen simple example that was created in a few steps, it was really easy. And now we should check compiled css and make challenge: mixins vs extends. Under spoiler you can see stylesheet of those four elements (heading, image, paragraph, blockquote), that we'll get after compilation. I won't include basic components or inherited styles, just output styles of our example elements, that will be enough to understand what kind of compiled code we'll get while using Inclusion with extends.

Output css styles
 
/* ==============================
   $Typo element
   ==============================*/

/* Typo alignement */
.kittens-title{
  text-align: center;
}
.kittens-text {
  text-align: justify;
}

/* Typo font family */
.kittens-title {
  font-family: Georgia, Times, "Times New Roman", serif;
}


/* ==============================
   $Blockquote element
   ==============================*/

/* Common blockquote */
.kittens-bq p:first-child:before {
  content: "\201C";
  padding-right: 10px;
  font-size: 60px;
  line-height: 0;
  vertical-align: middle;
}

/* Blockquote alignement */
.kittens-bq {
  text-align: left;
}

/* Blockquote color */
.kittens-bq {
  color: #777777;
}


/* ==============================
   $Figure element
   ==============================*/

/* Common figure */
.kittens-img figcaption{
  font-family: "Open Sans Condensed", sans-serif;
  margin: 10px 0 5px;
  padding: 0 10px;
  font-size: 25px;
}
@media screen and (max-width: 960px) {
.kittens-img figcaption{
    font-size: 20px;
  }
}

/* Figure alignement */
.kittens-img figcaption {
  text-align: left;
}

/* Figure border */
.kittens-img figcaption {
  border-left: 3px solid #777777;
}

/* Figure float */
.kittens-img {
  width: 47%;
  float: left;
  margin: 10px 3% 10px 0;
}
@media screen and (max-width: 640px) {
  .kittens-img {
    float: none;
    clear: both;
    width: 90%;
    max-width: 90%;
    margin: 10px auto 20px;
  }
}

/* Figure color */
.kittens-img {
  color: #777777;
}
								
Output styles

Now you see that output code looks like chopped, that because for each property was generated special placeholder and then it was extended within our element. Why it's happened? - Let's see source code of typo mixin:

 
@mixin typo($align:inherit, $color: inherit, $font: inherit, $text-shadow:none){         
   @extend %typo-#{$align}-align !optional; 
   @extend %typo-#{$font} !optional;
   @extend %typo-color-#{$color} !optional;
   
   @if $text-shadow != "none"{
      text-shadow: 1px 1px 1px $text-shadow;
   }   
}    
  
/* Typo alignement */
   @each $position in $align{
      %typo-#{nth($position, 1)}-align{
         text-align: #{nth($position, 1)};
      }
   } 

/* Typo font family */
   @each $font in $fonts{
      %typo-#{nth($font, 1)}{
         font-family: #{nth($font, 2)};
      }
   }

/* Typo color */
   @each $color in $colors{
      %typo-color-#{nth($color, 1)}{
         color: #{nth($color, 2)};
      }
   }				
							
Typo mixin

If there was other element (let's say heading) with same color or font-family but with its own class name - then it would be have the same extended placeholder inside. With many different class names we can get messy code with comma separated selectors, but in the same time, output code will be dry, that's the point.
It'll be more productive when we have many elements with different class names but with the same properties. We describe content, and we're able to give different class names to elements, but styles will be the same and css code will be still dry.
Besides there is alternative solution - framework with ready styles and defined html classes, I think Inclusion will have this option soon.

Javascript

And now it's time to talk about javascript.

I know, this is the css preprocessor framework, but there were used some plugins to implement useful functionality, like code highlighting, fullscreen image preview, navigation toggle and smooth anchor scrolling, spoiler toggle and at last for better performance - image lazy loading.

In build version we have one javascript file called inclusion.js For proper work it requires jquery. If you use Grunt or other task runner, all javascripts will be assembled and minified so for current example I'll use assembled.min.js

 
<!DOCTYPE html>
<html>
	<head>
		<title>Some page</title>
		<link rel="stylesheet" href="styles/style.min.css">
	</head>
	<body>

	<!-- Here comes jQUery lib -->
	<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>       
    <!-- If you haven't other scripts you can place inclusion.min.js instead assembled.min.js -->
    <script src="js/assembled.min.js"></script>
	</body>
</html>				
						
Connect scripts to our markup

We have connected jQuery lib and Inclusion scripts so all should work with predefined class names that have .js-* prefix as javascript hook.
By the way, you're able to adjust class names in dev version inclusion-settings.js file or in assembled inclusion.js

So here comes default class names for js hooks with explanations:

As you can see all adjustments are pretty simple, also settings file is well documented.

Inclusion js plugins settings
 
$(function(){
	/* jQuery navKit plugin init and settings
	*
	* navAnchor: "js-anchor"	anchor class name link for smooth scrolling
	* navLink: "js-link"		link class name for hightlight on current section
	* navIcon: "js-navtoggle"	icon class name for toggling navbar
	* iconOpen: "is-open"		class name of icon, when navbar is open (change icon to cross instead burger)
	* activeLink: "is-active"	class name of active and highlighted link
	* state: "closed"			default state of navbar
	*/
	$(".js-nav").navKit({ state: "closed" }); //apply plugin to navbar with .js-nav classname


	/* jQuery Lazy load plugin init and settings
	* more settings here http://www.appelsiini.net/projects/lazyload
	*/
	$(function(){
	    var lazyImage = $(".js-lazy"); //lazy load of images with .js-lazy classname
	    lazyImage.lazyload({ effect : "fadeIn", threshold : 200 });
	});


	/* jQuery simpleSpoiler plugin init and settings
	*
	* spoilerPanel: "js-panel"		spoiler panel class name. Click on it will toggle spoiler
    * spoilerClosed: "is-closed"	class name of closed spoiler
    * state: "closed"				default tate of current spoiler or spoilers
	*/
	$(".js-spoiler").simpleSpoiler({ state: "closed" }); //apply plugin to spoilers with .js-spoiler classname
});


/* Intense image view plugin
* More details here https://github.com/tholman/intense-images
*
* Run it only on desktops (thx to http://detectmobilebrowsers.com/), 
* because there are some troubles with touch scrolling
*/
(function(){
	//check for mobile devices
	window.mobilecheck = function() {
		//here comes regex for mobile check, it's too large for this snippet
	}
	// if not mobile - run Intense plugin
	if(!(window.mobilecheck())){
		var elements = document.getElementsByClassName( 'js-view' ); // apply plugin to images with js-view class name
		Intense( elements );
	}
})();				
							
Inclusion js settings file

Inclusion cheatsheet

Here you can find available inclusions, their mixins with properties, values and defaults.

Inclusions, mixins, properties, values, defaults
Inclusion nameMixinPropertyValueDefault
Common inclusions
Typography@include typo();$aligninherit, left, right, center, justifyinherit (justify)
$colorinherit, dark, light, lighten, darkeninherit (dark)
$fontinherit, sans, serif, condensedinherit (sans)
$text-shadownone, color(rgb, rgba, etc)none
Blockquote@include blockquote();$alignleft, right, centercenter
$positionnormal, left, right, centernormal
$extrabooleanfalse
$colordark, light, lighten, darkendark
$fontinherit, sans, serif, condensedinherit (serif)
List@include list();$typeul, olul
$positionnormal, left, rightnormal
$extrabooleanfalse
$colordark, light, lighten, darkendark
$fontsans, serif, condensedserif
Figure (Images and code blocks)@include figure();$typeimage, code, videoimage
$positionleft, right, centercenter
$extrabooleanfalse
$colordark, light, lighten, darkendark
Table@include table();$alignleft, right, centercenter
$positionleft, right, centercenter
$extrabooleanfalse
$colordark, light, lighten, darkendark
$fontsans, serif, condensedserif
Block (container for other content)@include block();$positionnone, left, right, centernone
$extrabooleanfalse
$spoilerbooleanfalse
$spoiler-colordark, light, lighten, darkendark
Button@include button();$positionnone, left, right, centernone
$sizesmall, regular, largeregular
$colordark, light, lighten, darkendark
$fontsans, serif, condensedsans
$stateenabled, disabledenabled
Icon button@include icon-button();$iconup, down, twitter, vk, gplus, skype, bitbucket, linkedin, mail, git, pencil, fbdown
$shaperect, roundrect
$colordark, light, lighten, darkendark
Basic inclusions (helpers)
Text selection@include selection();$colordark, lightdark
Body@include body();$alignleft, right, center, justifyleft
$colordark, light, lighten, darkendark
Container@include container();
Main fixed header@include header();
Header group (nav icon and languages)@include hgroup();$colordark, light, lighten, darkenlight
Navigation@include nav();$colordark, light, lighten, darkenlight
Section@include section();$aligninherit, left, right, center, justifyinherit (justify)
$colorinherit, dark, light, lighten, darkeninherit (dark)
$bg-colornone, dark, light, lighten, darkennone
$shadowbooleanfalse
$bg-imagenone, "url"none
$overlaynone, light, darknone
$jumbobooleanfalse
$bg-attfixed, scrollfixed
Chapter@include chapter();$dividernone, top, bottombottom
Grid system inclusions
Grid container or grid row@include gs();$gs_widthpercents or pixels100%
$gs_gutter-widthpercents or pixelsn0
$gs_gutter-heightpercents or pixels0
$gs_gutter-width-fallbacksame units as $gs_width0
Grid column@include gs-column();$column_countint number1
$column_total-countint number12
$column_gutter-widthpercents or pixelsn2%
$column_gutter-heightpercents or pixels2%
$column-heightpercents, pixels, autoauto
$column_gutter-width-fallbacksame units as $gs_width2%
$column_gutter-height-fallbacksame units as $gs_width2%
$gs_widthpercents or pixels100%
Push@include gs-push();$column_countint number1
$column_total-countint number12
$column_gutter-widthpercents or pixels2%
$column_gutter-width-fallbacksame units as $gs_width2%
$gs_widthpercents or pixels100%
Pull@include gs-pull();$column_countint number1
$column_total-countint number12
$column_gutter-widthpercents or pixels2%
$column_gutter-width-fallbacksame units as $gs_width2%
$gs_widthpercents or pixels100%

And that's all with mixins! But I think I should say here about requiered helper elements, like page container, navigation or spoiler elements and then - post here boilerplate for markup. In a Javascript section was similar list with predefined classnames for js hooks. Don't worry, there are only 4 required elements and here they are:

Pretty easy,isn't it? Just take look at markup boilerplate, I'm sure all will become more clear:

Markup boilerplate
	
<!DOCTYPE html>
<html lang="en">
    <head>
        <meta charset="utf-8">
        <title>Boilerplate</title>
        <link rel="shortcut icon" href="favicon.ico" />
		<link rel="stylesheet" href="css/style.min.css">	
    </head>
    <body>			
    	<!-- Apply header() mixin  to this page element-->
		<header class="main-header">
			<!-- ...and nav() mixin to this nav -->
			<nav class="navbar js-nav">
				<ul>
					<!-- Don't forget for all this js hooks class names! -->
					<li><a class="js-anchor js-link" href="#home">Home</a></li>
					<li><a class="js-anchor js-link" href="#about">About</a></li>
					<li><a class="js-anchor js-link" href="#demo">Demo</a></li>
					<li><a class="js-anchor js-link" href="#download">Download</a></li>
				</ul>
			</nav>
			<!-- ...and hgroup() mixin to this header group -->
			<div class="hgroup">
				<a class="js-navtoggle" href="#">Menu</a>					
				<ul>
					<li><a class="is-selected">en</a></li>
				</ul>
			</div>
		</header>
		<!-- Apply section() mixin with desirable options to this section -->
		<sectipon class="awesome">
			<!-- ...and container() mixin to this container -->
			<div class="container">
				<h1>Hello world!</h1>
			</div>
		</sectipon>
		<!-- Footer is just another section, so go ahead and apply section() mixin to it -->
		<footer class="main-footer">
			<div class="container">
				<h5 class="main-footer__info">Powered by <a class="inclusion" href="http://orlovmax.com/lab/tools/inclusion">Inclusion</a></h5>
			</div>
		</footer> 		
		<script src="//ajax.googleapis.com/ajax/libs/jquery/1.10.2/jquery.min.js"></script>
        <script>window.jQuery || document.write('<script src="js/jquery-1.10.2.min.js"><\/script>')</script>
        <script src="inclusion.min.js"></script> 
    </body>
</html>								
							
Markup boilerplate

Live examples

These demo pages from my code lab were created using Inclusion

Credits

Here comes credits and used third-party code licensing information

That's all!

Compatible browsers: IE9+, Firefox, Chrome, Opera, Safari, Yandex.browser

Fork me on github to get source code or check some details. Also some improvements coming soon, like variant without extends (less compact, but maximum readable), and no-preprocessor version with html classes for inclusions ( I think it will be with BEM-styled class names)