Web UI Architecture

Author: James Millar

This document describes an architecture for implementing HTML & CSS for web development. Much has been said on this evolving topic; please see references for great resources with great ideas. As this is a reference document for projects we are working on I have started with our implementation. Read beyond this for descriptions and explanations.

Implementation

css/
	style.css | main.css
	base/variables.css
	base/colors.css
	base/fonts.css
	base/mixins.css
	base/resets.css
	base/elements.css
	base/layout.css
	components/<name>.css

html/
	page.html
	layout/<name>.html
	components/<name>.html

js/
	components/<name>.js
img/
libs/

• Substitute css for project appropriate pre-processor variants; eg .scss, .less
• Substitute html for project appropriate templating/backend variants; eg .twig, .php

Main - main.css | style.css

The main file is an aggragation point to draw all styles together and should not contain any styles itself. A typical main will look like:

@import
  "base/variables",
  "base/colors",
  "base/fonts",
  "base/mixins",
  "base/normalize",
  "base/elements",
  "base/layout",
  "components/<component>"
  ;

Variables - variables.css

The variables files contains explicit global values, such as margins/padding or other structural values, font stacks, defaults values, etc. This is the settings, or config file, for the project. For example a variables file may look like this:

@base-font-size: 16px;
@base-line-height: 1.4em;
@base-font-weight: 100;

@content-padding  : 25px;

@breakpoint-small  : 320px;
@breakpoint-medium  : 360px;
@breakpoint-large  : 480px;

Base Folder (base/)

The base folder contains all Base styles and variables for the project. This includes resets, element override, colour palettes, font declarations and mixins.

Components

Each components is represented by three possible constituent files:

• component stucture contained in: html/components/.html
• component styles contained in: css/components/.css
• component script contained in: js/components/.js

Each of the three possible files is named as per the name of the component, followed by the appropriate file extension, enabling easy location of a Components parts.

Component Style - CSS

Within the components css file will be all the styles for the component and its alternate states. Components are identified by a base class which will wrap all the styles and states for the component. Variants of the component can be wrapped, or moved outside by using the @extends with the component. Creating a variant component using a mixin of the base component should be avoided due to CSS bloat. When creating a components styles they should be created so that they:

- do not bleed,
- are reusable within a page,
- are nestable within other components.

Here is an example style for a button. Note there is a variant for a default clickable button, and there is also a variant for the 'label' sub-element (sub-component) demonstrating the two ways to create variants. There are also examples of three possible ways to create State styles:

.button
{
	width: 100%;
	height: 40px;
	background: blue;
	.label 
	{
		color: white;

		// ---- Variant ----
		&--warning
	  	{
	    	font-size: 2em;
	  	}
	}
	.description
	{
		color: grey;
	}

	// ---- States ----

	&:hover
	{
		border: 1px solid green;
	}

	&.is-active
	{
		background: red;
	}

	@media only screen and (min-width:480px){
        width: 180px;
    }
}

// ---- Variant ----
.button--default
{
	@extend .button;
	background: green;	
}

Component Structure - HTML

The HTML file will include the element structure for the component. The root node of the component has as its first class the name of the component, linking it to the component's style.

@todo more

<a class="button--default">
	<span class="label">Update</span>
	<span class="description">This will commence the update process on server</span>
</a>

<a class="button">
	<span class="label">Cancel</span>
	<span class="description">This will cancel the update process</span>
</a>

<a class="button">
	<span class="label--warning">Cancel All</span>
	<span class="description">This will cancel ALL pending update processes</span>
</a>

Hierarchy of Styles:

The hierarchy of styles gives a basis upon which styles can be catagorised, and the order of their application. Our hierarchy is:

• Base
• Layout
• Components
• States
• Themes

Base

Base styles refer to underlying styles that are a minimum for elements of the project. These include Resets for browser standardisation, and any element overrides for the project.

Layouts

Layouts act as containers for 'components' of the UI at a 'page layout' level. They provide page sturcture and are typically reused across a large number of pages.

Components

Components are logical visual units of the UI made up of a collection of elements. They are the reusable, nestable, stateful building blocks of a page.

States

States capture the alternative visual that may be applied to a components. For example if a button is clicked it is still a button but may visually change, such as changing colour.

Themes

Themes are Site wide alternative styles that may be applied. For example to provide an alternative look & feel, or to modify the styles based on user settings.

• Note: Layouts and Components are conceptually similar, Layouts are a specialised type of Component that act as 'page level' containers for other Components.

Handling Variants

@todo more

Handling State

State can be handled in three ways:

- psuedo class
- state class
- media query

@todo more

References:

• Scalable and Modular Architecture for CSS; Jonathan Snook
• Style Guide Driven Development; John Albin Wilkins, https://melbourne2015.drupal.org.au/sites/default/files/slides/styleguide-driven.pdf