Layout Reference

Happy Residential College students
0001-01-01

Table of Contents

Rules About Sections, Content Blocks, and Content Block Elements

Although some classes might work in multiple locations, the design system is supposed to work in a certain way. Things will work better in general and be less likely to break during upgrades if the general rules below are followed.

To do: This documentation needs more detail.

Sections

Sections are blocks that contain content and content blocks (e.g. columns blocks) in order to separate different parts of a page.Sections should be used for page layout only. Sections are not a required component of the Acora design system: content and content blocks might appear within or outside a section.

Sections are identified with the class name "section".

In general only use these classes on sections:

  • Background color - bg-color-1
  • Width if it's different to the page - width-screen (when the page is thin) or maxwidth-mid (when the page is full width)
  • Padding when you want space inside the block around the content area - padding, padding-thick, padding-vertical, etc.
  • Margin when you want the section separated from other things around it - margins-vertical,  margin-top-thick, etc.
    • Note that horizontal margins usually won't make sense and might even produce strange results, because sections fill the width of their container by default.
  • Avoid the use of design based elements even though they work - e.g. edge shapes, shadows, borders

Do Not Use

  • Stuff that should go on the content block - e.g. layout-1,  align-items-center
  • Although text alignment and certain other helper classes will work (e.g. text-center) they will apply to the entire section and every widget within it. Generally that will be more problematic than helpful, so it should be avoided.

Deprecated

  • box-wide still works but has problems and should be avoided. It should be handled as a combination of width-screen on the section and maxwidth-mid on the content block.

Boxes

A box is like a section in some ways but intended only to wrap around small portions of content so that the content within the box can be given special layout treatments.

Boxes are identified by the class name "box".

  • Boxes adopt standard site-wide settings by default (which might vary from site to site) such as padding, margin, shape, shadow, etc.), but these are easily adjusted or removed with standard utility classes.
  • Boxes fill the available content area width by default but this is easily adjusted with class names.
  • Boxes are the height of the content within them by default but classes are easily added, e.g. to give them a ratio ("ratio-1x1") or make them fill the available content area height ("height-full").

Other commonly useful classes for boxes include:

  • Background color - bg-color-1
  • Padding and margin
  • Shape - rounded-more
  • Shadow - shadow-1
  • Borders
  • Text/item horizontal alignment if it's just for this block - text-center
  • Vertical alignment of sub elements - align-items-center
  • Width if it's different to the content block - maxwidth-wide, maxwidth-mid, maxwidth-narrow, etc.

Content Blocks

Content blocks should be used for arranging the layout of items within the content. In general only use these classes on content blocks:

  • The block can be a "box" to establish the site-wide styling defaults (edge shape, padding, margin, shadow, etc.) - box
  • Background color - bg-color-1
  • Layout for columns blocks - layout-1
  • Vertical alignment of sub elements - align-items-center
  • Width if it's different to the content block - maxwidth-wide, maxwidth-mid, maxwidth-narrow, etc.
    • Note that the content block will fill the section width by default and the content block should never be wider than the section.
  • Some kinds of blocks might have their own layouts or styles
  • Edge shapes, shadows, borders, but only in rare cases if absolutely needed. Check the style guide first. If your style is not there, it probably shouldn't be used.

On Columns or Elements Within Content Blocks

  • The element can be a "box" to establish the site-wide styling defaults (edge shape, padding, margin, shadow, etc.) - box
  • Background color - bg-color-1
  • Text/item horizontal alignment if it's just for this block - text-center
  • Padding
  • Margin, but be mindful of what happens in responsive views. Margin is probably better kept to the block or section level.

On Compilation Widgets

There are two layers to a compilation widget:

  1. The content block, which behaves just like any other content block.
  2. The items within the collection. A special set of classes are used for these.

In general only use these classes on compilation widgets:

  • Compilation style classes -  cards, postcards ,   masonry, tiles, image-left-right, etc.
    • Some of these styles have extensions - e.g. cards-simple
  • Behaviour classes - carousel
  • Item classes. Since the image and the text are separated within items, these generally begin with  image- or  text-. E.g. image-ratio-16x9, image-hover-zoom,  text-padding-thick

On Other Widgets or in Special Circumstances

  • Ratio - This only works in special circumstances. It's designed for boxes, videos, and the image widget -  ratio-16x9

On Anything

But only if it's in the style guide...

  • Backgrounds
  • Padding on the inside of the element
  • Margin no the outside of the element
    • Note that margin might look like padding on the outer element when it's on a sub element inside something else like a content block or section.
  • Edge shapes, although they'll be less useful on sections
  • Shadows
  • Borders

Targeting Different Screen Sizes

Classes ending in -size in the reference sheet below can target different screen sizes, which cascade "downward" by default. E.g. using the class  padding-thick-medium will apply thick padding at the medium screen size and every screen size smaller than medium. This can be used to adjust effects at different screen sizes, e.g. " padding padding-none-medium" applies default padding on desktop screens and removes padding for medium screens and below.

The "-only" extension can be used to apply a screen size option only at a certain screen size and not screens that are larger or smaller. E.g. " padding padding-none-medium-only" applies default padding on large screens, removes padding on medium screens, and applies default padding on small (and smaller) screens. This approach is generally only needed for very advanced layout: avoid it unless you're a very experienced layout coder.

Layout Classes

Columns + gutters

Columns are the same width by default but can be modified with layout classes.

There is no "one column" block, that's just a regular block or a box.

  • Columns
    • 2 Columns - cols-2
    • 3 Columns - cols-3
    • 4 Columns - cols-4 small
    • 5 Columns - cols-5
    • 6 Columns - cols-6
  • Gutters options
    • gutters
    • -none
    • -border
    • -border-thick
    • -border-thicker
    • -border-thickest
    • -thinner
    • -thin
    • -thick
    • -thicker
    • Extend them with the standard screen size options - e.g. -small

Other columns options

  • Layout
    • Layouts vary based on the number of columns
    • layout-1
    • layout-2
    • Etc...
  • Dividers - Show a visible line/divider between columns
    • dividers
  • Reverse the order of columns (which only makes sense for two columns blocks) at different screen sizes
    • reverse-size
  • Stack at different screen sizes. Columns begin stacking at various screen sizes by default but this can be customised if you need different behaviour to the default.
    • stack-size
    • stack-none (override default settings and never stack the columns)
  • Advanced: Individual columns can be set to grow or shrink based on the content inside them.
    • grow-size
    • shrink-size
  • Sequence is a special columns layout that places graphic icons between columns
    • sequence

Rich text template blocks

Rich text template blocks

We have configured the ability to have drop in elements via the use of the rich text block widget.

The blocks are easy to configure and add however a downside is they are on the fragile side when it comes to the editing experience.  Further dicussion is required with the dev team about if we take a widget approach with fixed fields for blocks instead.

  • Accordion
  • Tabs
  • Summary Block

Colors

Main colors with gradients

(x can be a value of 1-7)

bg-lightest-color-x 
bg-lighter-color-x
bg-light-color-x
bg-mid-light-color-x
bg-mid-color-x
bg-mid-dark-color-x
bg-dark-color-x
bg-darker-color-x
bg-darkest-color-x

Spot colors

bg-spot-color-x

Text or object colors

color-1 (etc...)
spot-color-1 (etc...)

UI colors

Generally only for use by developers.

bg-lightest-color-ui
bg-lighter-color-ui
bg-light-color-ui
bg-mid-light-color-ui
bg-mid-color-ui
bg-mid-dark-color-ui
bg-dark-color-ui
bg-darker-color-ui
bg-darkest-color-ui

Boxes & Blocks

Borders

borders-none
borders-vertical-none
borders-horizontal-none
border-top-none
border-right-none
border-bottom-none
border-left-none
border-top-thick-light
border-top-bottom-light
border-right-thick-light
border-left-thick-light

Edges

rectangle
rounded-less
rounded
rounded-more
pill
ellipse

Spacing and alignment

Vertical alignment of items

align-items-top
align-items-center
align-items-bottom
align-items-stretch
align-items-baseline

Horizontal alignment of items

justify-start
justify-left
justify-center
justify-end
justify-right

Spacing around items

space-around
space-between
space-evenly

Screen sizes

Add -size or -size-only to maxwidth to adjust behaviour at different screen sizes.

Widths

width-screen
width-full

maxwidth-contain
maxwidth-narrowest
maxwidth-narrower
maxwidth-narrow
maxwidth-mid
maxwidth-wide
maxwidth-wider
maxwidth-widest

Add -size or -size-only to maxwidth to adjust behaviour at different screen sizes.

Heights

height-full
height-full-size

Hidden

Don't use these, they're for developers:

hide
hide-size

Only use this one if you understand it:

hide-from-sight

Text and Inline Element (e.g. Image) Alignment)

text-left
text-center
text-right
text-left- size -only
text-center- size -only
text-right- size -only

Padding

padding-none
padding-thinnest
padding-thinner
padding-thin
padding
padding-thick
padding-thicker
padding-thickest
padding-vertical-none
padding-vertical-thinnest
padding-vertical-thinner
padding-vertical
padding-vertical-thick
padding-vertical-thicker
padding-vertical-thickest
padding-horizontal-none
padding-horizontal-thinnest
padding-horizontal-thinner
padding-horizontal-thin
padding-horizontal
padding-horizontal-thick
padding-horizontal-thicker
padding-horizontal-thickest
padding-top-none
padding-top-thinnest
padding-top-thinner
padding-top-thin
padding-top
padding-top-thick
padding-top-thicker
padding-top-thickest
padding-right-none
padding-right-thinnest
padding-right-thinner
padding-right-thin
padding-right
padding-right-thick
padding-right-thicker
padding-right-thickest
padding-bottom-none
padding-bottom-thinnest
padding-bottom-thinner
padding-bottom-thin
padding-bottom
padding-bottom-thick
padding-bottom-thicker
padding-bottom-thickest
padding-left-none
padding-left-thinnest
padding-left-thinner
padding-left-thin
padding-left
padding-left-thick
padding-left-thicker
padding-left-thickest
padding-none-size-only
padding-thinnest-size-only
padding-thinner-size-only
padding-thin-size-only
padding-size-only
padding-thick-size-only
padding-thicker-size-only
padding-thickest-size-only

Padding cont'd...

padding-vertical-none-size-only
padding-vertical-thinnest-size-only
padding-vertical-thinner-size-only
padding-vertical-size-only
padding-vertical-thick-size-only
padding-vertical-thicker-size-only
padding-vertical-thickest-size-only
padding-horizontal-none-size-only
padding-horizontal-thinnest-size-only
padding-horizontal-thinner-size-only
padding-horizontal-thin-size-only
padding-horizontal-size-only
padding-horizontal-thick-size-only
padding-horizontal-thicker-size-only
padding-horizontal-thickest-size-only
padding-top-none-size-only
padding-top-thinnest-size-only
padding-top-thinner-size-only
padding-top-thin-size-only
padding-top-size-only
padding-top-thick-size-only
padding-top-thicker-size-only
padding-top-thickest-size-only
padding-right-none-size-only
padding-right-thinnest-size-only
padding-right-thinner-size-only
padding-right-thin-size-only
padding-right-size-only
padding-right-thick-size-only
padding-right-thicker-size-only
padding-right-thickest-size-only
padding-bottom-none-size-only
padding-bottom-thinnest-size-only
padding-bottom-thinner-size-only
padding-bottom-thin-size-only
padding-bottom-size-only
padding-bottom-thick-size-only
padding-bottom-thicker-size-only
padding-bottom-thickest-size-only
padding-left-none-size-only
padding-left-thinnest-size-only
padding-left-thinner-size-only
padding-left-thin-size-only
padding-left-size-only
padding-left-thick-size-only
padding-left-thicker-size-only
padding-left-thickest-size-only

Margins

margins-none
margins-thinnest
margins-thinner
margins-thin
margins
margins-thick
margins-thicker
margins-thickest
margins-vertical-none
margins-vertical-thinnest
margins-vertical-thinner
margins-vertical-thin
margins-vertical
margins-vertical-thick
margins-vertical-thicker
margins-vertical-thickest
margins-horizontal-none
margins-horizontal-thinnest
margins-horizontal-thinner
margins-horizontal-thin
margins-horizontal
margins-horizontal-thick
margins-horizontal-thicker
margins-horizontal-thickest
margin-top-none
margin-top-thinnest
margin-top-thinner
margin-top-thin
margin-top
margin-top-thick
margin-top-thicker
margin-top-thickest
margin-right-none
margin-right-thinnest
margin-right-thinner
margin-right-thin
margin-right
margin-right-thick
margin-right-thicker
margin-right-thickest
margin-bottom-none
margin-bottom-thinnest
margin-bottom-thinner
margin-bottom-thin
margin-bottom
margin-bottom-thick
margin-bottom-thicker
margin-bottom-thickest
margin-left-none
margin-left-thinnest
margin-left-thinner
margin-left-thin
margin-left
margin-left-thick
margin-left-thicker
margin-left-thickest
margins-none-size-only
margins-thinnest-size-only
margins-thinner-size-only
margins-thin-size-only
margins-size-only
margins-thick-size-only
margins-thicker-size-only
margins-thickest-size-only

Margins cont'd...

margins-vertical-none-size-only
margins-vertical-thinnest-size-only
margins-vertical-thinner-size-only
margins-vertical-thin-size-only
margins-vertical-size-only
margins-vertical-thick-size-only
margins-vertical-thicker-size-only
margins-vertical-thickest-size-only
margins-horizontal-none-size-only
margins-horizontal-thinnest-size-only
margins-horizontal-thinner-size-only
margins-horizontal-thin-size-only
margins-horizontal-size-only
margins-horizontal-thick-size-only
margins-horizontal-thicker-size-only
margins-horizontal-thickest-size-only
margin-top-none-size-only
margin-top-thinnest-size-only
margin-top-thinner-size-only
margin-top-thin-size-only
margin-top-size-only
margin-top-thick-size-only
margin-top-thicker-size-only
margin-top-thickest-size-only
margin-right-none-size-only
margin-right-thinnest-size-only
margin-right-thinner-size-only
margin-right-thin-size-only
margin-right-size-only
margin-right-thick-size-only
margin-right-thicker-size-only
margin-right-thickest-size-only
margin-bottom-none-size-only
margin-bottom-thinnest-size-only
margin-bottom-thinner-size-only
margin-bottom-thin-size-only
margin-bottom-size-only
margin-bottom-thick-size-only
margin-bottom-thicker-size-only
margin-bottom-thickest-size-only
margin-left-none-size-only
margin-left-thinnest-size-nly
margin-left-thinner-size-only
margin-left-thin-size-only
margin-left-size-only
margin-left-thick-size-only
margin-left-thicker-size-only
margin-left-thickest-size-only

Item Collections

Collection layouts

  • cards
  • tiles
  • masonry
  • masonry-columns
  • image-left
  • image-right
  • image-left-right
  • image-right-left
  • cols-2|3|4|5|6

Gutters

Collections can use the same gutters options as columns.

Stack

Only works for image-left, image-right and image-left-right currently:

stack-size

Cards extensions

Add a second class to create different kinds of cards layouts:

  • cards postcards
  • cards postcards postcards-bright
  • cards cards-simple
  • cards cards-plain
  • cards cards-dark
  • cards cards-smaller
  • date-overlay
  • cards cols-2|3|4
  • cards cards-120|150|180|210|240|280|320|260|400|480|560|640|720|800

Deprecated

  • cards cards-padded still works but should be avoided. Use text and image block padding instead.

Image left/right extensions

  • Thumbnail sizes???

Fixed column counts and sizes

Take care when using fixed column counts or card sizes; they can cause trouble because you can't choose when to stack them.

Card sizing is usually a better approach. 

Image and Text Boxes in Collections

Unless there are any exceptions noted below, these classes are only intended to work with content collections. If they work in other scenarios, it's an accident and it will probably break in a future update.

In general, the same classes will work for text blocks by substituting "image-" with "text-". (To do: More information is required on this.) 

Text and image

The examples below are about images. Many options also work for text blocks by replacing "image" with "text", e.g.

text-bg-color-1
text-rounded

Item titles

As a separate choice to what heading levels are used on a compilation, titles can be styled as though they are at a specific level.

title-style-h1
title-style-h2 etc...
title-style-p

Backgrounds

In certain collections (e.g. cards) backgrounds on the image block only make sense when there's also padding or other effects like opacity applied.

image-bg-lightest-color-ui
image-bg-lighter-color-ui
image-bg-light-color-ui
image-bg-mid-light-color-ui
image-bg-mid-color-ui
image-bg-mid-dark-color-ui
image-bg-dark-color-ui
image-bg-darker-color-ui
image-bg-darkest-color-ui

image-bg-lightest-color-x 
image-bg-lighter-color-x 
image-bg-light-color-x
image-bg-mid-light-color-x
image-bg-mid-color-x 
image-bg-mid-dark-color-x 
image-bg-dark-color-x 
image-bg-darker-color-x 
image-bg-darkest-color-x
image-bg-spot-color-x 

image-bg-spot-color-x

And text blocks have the same options, e.g.

text-bg-color-1

Padding

image-padding
text-padding

... and all the same size and edge options as standard padding rules.

Edges

image-rectangle
image-rounded-less
image-rounded
image-rounded-more
image-pill
image-ellipse
image-border

text-rounded, ryv.

Shapes (images only)

Note that each named shape has a numbered equivalent. E.g. image-ratio-square=image-ratio-1x1, image-ratio-wide=image-ratio-16x9. Perhaps it's better / more clear over time to get used to using the numbers.

image-ratio-1x1
image-ratio-2x3
image-ratio-3x4
image-ratio-4x3
image-ratio-3x2
image-ratio-16x9
image-ratio-21x9
image-ratio-21x7
image-ratio-21x5
image-ratio-21x4
image-ratio-21x3

image-ratio-square
image-ratio-portrait
image-ratio-tall
image-ratio-landscape
image-ratio-35mm
image-ratio-wide
image-ratio-panorama
image-ratio-ultra-wide
image-ratio-banner
image-ratio-strip-thick
image-ratio-strip

Deprecated

image-contain (all images within cards, ratios, or other blocks will be contained by default)

Fixed sizes (images only)

Fixed sizes apply to images only, not text blocks.

These classes expect the alternate dimension (height when width is set, width when height is set) to be dynamic. They're not expected to work when both dimensions are set. (This might change in the future.)

image-width-60
image-width-80
image-width-100
image-width-120
image-width-150
image-width-180
image-width-210
image-width-240
image-width-280
image-width-320
image-width-360
image-width-400
image-width-480
image-width-560
image-width-640
image-width-720
image-width-800

image-height-60
image-height-80
image-height-100
image-height-120
image-height-150
image-height-180
image-height-210
image-height-240
image-height-280
image-height-320
image-height-360
image-height-400
image-height-480
image-height-560
image-height-640
image-height-720
image-height-800

Effects (images only)

image-border

image-gradient-up
... which can be extended with standard site colors and spot colors:

image-gradient-up-color-1

Add lightening options (darkening doesn't make sense):

image-gradient-light
image-gradient-lighter
image-gradient-lightest

Effects (text only)

text-pre-line (respects line breaks within the text source content)

Opacity (images only)

image-opacity-least
image-opacity-lesser
image-opacity-less
image-opacity-mid
image-opacity-more
image-opacity-even-more
image-opacity-most

Micro interactions

hover-image-zoom

More comin...