bitstyles 0.8.0 → 0.9.1

data/scss/bitstyles/generic/_all.scss

@@ -0,0 +1,2 @@
+@import 'box-sizing';
+@import 'normalize';

data/scss/bitstyles/layout/_content.scss

@@ -2,15 +2,19 @@
 //
 // Content
 //
-// Semi-fixed-width centred content wrapper. Takes full width available up to a maximum,
-// at which point width stays the same. Always remains centred.
+// **A generic wrapper for content with side padding and a maximum width**.
+//
+// This layout object ensures:
+// - there is always whitespace at the sides of the viewport; content will never touch the edge.
+// - content spans the full width of the screen, up to a maximum set by `$bitstyles-content-max-width`
+// - content remains centred within its parent element.
 //
 // markup:
 // <div class="l-content">
 //   <p>Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer. Gummies cheesecake oat cake sugar plum icing cupcake tiramisu bonbon. Cotton candy chupa chups tootsie roll chupa chups cotton candy liquorice jelly gingerbread. Pastry gummi bears liquorice tart cotton candy marshmallow. Ice cream cotton candy chocolate cake cookie. Bonbon candy jelly-o sugar plum cotton candy carrot cake icing ice cream. Sweet chocolate marzipan. Candy canes danish cake carrot cake bonbon. Gummi bears sesame snaps tart bear claw pie chocolate bar. Ice cream candy canes sugar plum cookie. Macaroon biscuit biscuit carrot cake liquorice. Muffin pudding gingerbread powder jelly-o chocolate bar powder jelly beans toffee.</p>
 // </div>
 //
-// Styleguide 5.1
+// Styleguide 3.1
 
 @import '../settings/content';
 

data/scss/bitstyles/layout/_grid.scss

@@ -1,22 +1,33 @@
 // Grid Systems
 //
-// Responsive grid system using inline-block (no floats, no flexbox).
-// Note this means whitespace is important. If necessary, use html comments between
-// each `.grid__item` to remove any whitespace, otherwise the browser will display
-// a small gap between grid items.
+// **A responsive html grid system using inline-block** (no floats, no clearfix, no flexbox).
 //
-// Each grid item needs the class `.l-grid__item` and a width class. With current defaults,
-// the widths create a 12-column system e.g. 1-of-12, 2-of-12, 3-of-12 … 11-of-12, 12-of-12.
+// Note this means *whitespace is important*. If necessary, use html comments between
+// each `.l-grid__item` to remove any whitespace (see the markup example below),
+// otherwise the browser will display a small gap between grid items.
+//
+// As it’s an HTML grid system (not CSS), some wrapping elements are needed to create rows
+// and columns (again see the markup in the examples below). Each of these grid items needs the class
+// `.l-grid__item` and a width class. With current defaults, the widths provided
+// include a 12-column system e.g. 1-of-12, 2-of-12, 3-of-12 … 11-of-12, 12-of-12.
+//
+// Grids can be nested.
 //
 // Dependencies:
 // - `layout/width`
-// - `tools/width`
 //
-// Styleguide 5.3
+// Styleguide 3.2
 
 // Grid system — base
 //
-// Proportional widths but not responsive.
+// **In the base grid system, columns are of proportional widths (a percentage of
+// the full width) but not responsive**.
+//
+// This means e.g. they cannot change from being 3-column
+// on larger screens, to one column stacked on small screens (if you can, try
+// resizing your browser window to see that the number of columns in the example
+// below doesn’t change). See the Responsive Grid below for information on how
+// to make your grid responsive.
 //
 // markup:
 // <ul class="l-grid">
@@ -103,7 +114,7 @@
 //    </li>
 // </ul>
 //
-// Styleguide 5.3.1
+// Styleguide 3.2.1
 
 @import '../settings/grid';
 
@@ -117,32 +128,44 @@
   display: inline-block;
   width: 100%;
   padding-left: $bitstyles-grid-gutter;
-  box-sizing: border-box;
   vertical-align: top;
+  box-sizing: border-box;
 }
 
 // Grid system - responsive
 //
-// The grid system can also be used responsively. Append the name of a breakpoint
-// to the end of a width class to have it activate only at that breakpoint. Multiple
-// l-width--item/breakpoints combinations can be used to define a grid item’s width
-// at various breakpoints (for all breakpoints you define in `$bitstyles-widths-breakpoints`).
+// **The grid system can also be used responsively — setting different widths for an
+// element based on the viewport size**.
+//
+// To do this, append the name of a breakpoint
+// to the width class to have it activate only at that breakpoint e.g.
+// `.l-width--12-of-12.l-width--6-of-12@medium` to create an element that’s
+// fullwidth for all screens, then becomes half width for `medium`-screens and larger.
+// Multiple l-width--item/breakpoints combinations can be used to define a grid item’s width
+// at several breakpoints (for all the breakpoints defined in the
+// `$bitstyles-widths-breakpoints` Sass list).
 //
 // This is commonly used to set a default mobile-first width of `.l-width--12-of-12`
-// and a larger-screen width of e.g. `.l-width--4-of-12-medium-and-up` for a
+// and a larger-screen width of e.g. `.l-width--4-of-12@medium` for a
 // three-column layout that becomes a single-column stack on small screens.
 //
 // markup:
 // <ul class="l-grid">
-//   <li class="l-grid__item l-width--12-of-12 l-width--4-of-12-medium-and-up">
-//     <div class="background-grey">6-of-12 / 2-of-12-medium-and-up</div>
+//   <li class="l-grid__item l-width--6-of-12 l-width--4-of-12@medium">
+//     <div class="background-grey">6-of-12 / 4-of-12@medium</div>
+//   </li><!--
+//--><li class="l-grid__item l-width--6-of-12 l-width--4-of-12@medium">
+//     <div>6-of-12 / 4-of-12@medium</div>
+//   </li><!--
+//--><li class="l-grid__item l-width--6-of-12 l-width--4-of-12@medium">
+//     <div class="background-grey">6-of-12 / 4-of-12@medium</div>
 //   </li><!--
-//--><li class="l-grid__item l-width--12-of-12 l-width--4-of-12-medium-and-up">
-//     <div>6-of-12 / 2-of-12-medium-and-up</div>
+//--><li class="l-grid__item l-width--12-of-12 l-width--6-of-12@medium">
+//     <div class="background-grey">12-of-12 / 6-of-12@medium</div>
 //   </li><!--
-//--><li class="l-grid__item l-width--12-of-12 l-width--4-of-12-medium-and-up">
-//     <div class="background-grey">6-of-12 / 2-of-12-medium-and-up</div>
+//--><li class="l-grid__item l-width--12-of-12 l-width--6-of-12@medium">
+//     <div>12-of-12 / 6-of-12@medium</div>
 //   </li>
 // </ul>
 //
-// Styleguide 5.3.2
+// Styleguide 3.2.2

data/scss/bitstyles/layout/_topbar.scss

@@ -2,14 +2,25 @@
 //
 // Topbar
 //
-// Fixed-position topbar/menu.
+// A fixed-position element that sticks to the top of the viewport, and spans
+// its full width. Commonly used to contain site navigation, logo etc.
+// Note that as it’s fixed, the main content element will need padding at the top
+// to ensure it’s not obscured by the topbar.
 //
 // markup:
 // <header class="l-topbar">
-//   <h1>Topbar content here (menu, logo…)</h1>
+//   <h1 class="o-h2 t-no-margin">Logo, menu, search, and other important nav</h1>
 // </header>
 //
-// Styleguide 1.6
+// sg-wrapper:
+// <div class="fixed-height-block new-render-context">
+//   <sg-wrapper-content/>
+//   <div class="fixed-height-block">
+//     <div class="min-height-block background-grey">Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer. Gummies cheesecake oat cake sugar plum icing cupcake tiramisu bonbon. Cotton candy chupa chups tootsie roll chupa chups cotton candy liquorice jelly gingerbread. Pastry gummi bears liquorice tart cotton candy marshmallow. Ice cream cotton candy chocolate cake cookie. Bonbon candy jelly-o sugar plum cotton candy carrot cake icing ice cream. Sweet chocolate marzipan. Candy canes danish cake carrot cake bonbon. Gummi bears sesame snaps tart bear claw pie chocolate bar. Ice cream candy canes sugar plum cookie. Macaroon biscuit biscuit carrot cake liquorice. Muffin pudding gingerbread powder jelly-o chocolate bar powder jelly beans toffee.</div>
+//   </div>
+// </div>
+//
+// Styleguide 3.3
 
 @import '../settings/topbar';
 
@@ -20,6 +31,10 @@
   left: 0;
   z-index: z($bitstyles-global-z, topbar);
   padding: $bitstyles-topbar-vertical-padding $bitstyles-topbar-horizontal-padding;
-  transition: background-color $bitstyles-transition-duration $bitstyles-transition-easing, transform 0.3s $bitstyles-transition-easing;
+  color: $bitstyles-topbar-color;
+  background-color: $bitstyles-topbar-background-color;
+  transition:
+    background-color $bitstyles-transition-duration $bitstyles-transition-easing,
+    transform 0.3s $bitstyles-transition-easing;
   backface-visibility: hidden;
 }

data/scss/bitstyles/layout/_width.scss

@@ -1,22 +1,29 @@
 // Widths
 //
-// Creates a series of classes that control width. Commonly used as part of a
-// grid system (see our grid system), but can be used alone if needed (as shown here).
+// **Bitstyles provides a series of classes focused on controlling width**.
 //
-// Set `$bitstyles-widths` to define which fractions you need a row split into e.g.
-// `$bitstyles-widths: (10, 12)` to create classes that split a row into 10ths and 12ths:
+// They’re most commonly used as part of a grid system (see our [grid system](/section/3.2)
+// for more information on that), but should also be used alone if setting an
+// element’s width is needed — as shown here — *instead of defining widths in a new CSS component*.
+//
+// Set the `$bitstyles-widths` variable to define how many columns you need. To create multiple grid
+// systems with different numbers of equal-width columns you can specify more than one column-count
+// (most often only on is needed though) e.g. `$bitstyles-widths: (10, 12)` creates
+// classes that can be used to split a row into 10 or 12 columns:
 //
 // `.l-width--1-of-10` … `.l-width--10-of-10`
 //
 // `.l-width--1-of-12` … `.l-width--12-of-12`.
 //
-// If you define `$bitstyles-widths-breakpoints` to contain the names of one or more
-// breakpoints (defaults to just `medium-and-up`), widths will also be created
-// for those breakpoints:
+// If you define the `$bitstyles-widths-breakpoints` Sass list to contain the names
+// of one or more breakpoints (it defaults to just `medium`), widths will also
+// be created that apply only at those breakpoints:
 //
-// `.l-width--4-of-12-medium-and-up`
+// `.l-width--1-of-12@medium`…
 //
-// See the section on grid systems for an example of this.
+// This allows you to create an element that is displayed at different sizes based on
+// viewport size. See the section on [responsive grid systems](/section/3.2.2) for
+// an example of the most common uses for this.
 //
 // Requires:
 // - `settings/widths`
@@ -33,7 +40,7 @@
 //     <div class="background-grey">6-of-12</div>
 //   </div>
 //
-// Styleguide 5.2
+// Styleguide 3.4
 
 @import '../settings/width';
 
@@ -42,7 +49,7 @@
 @each $width-breakpoint in $bitstyles-widths-breakpoints {
   @include media-query($width-breakpoint) {
     @each $i in $bitstyles-widths {
-      @include width($i, -#{$width-breakpoint});
+      @include width($i, \@#{$width-breakpoint});
     }
   }
 }

data/scss/bitstyles/objects/_absolute-center.scss

@@ -2,14 +2,20 @@
 //
 // Absolute Center
 //
-// Centres an element vertically & horizontally, relative to its closest relatively-positioned parent element.
+// **Centres an element vertically & horizontally**, relative to its closest non-statically
+// positioned parent element.
+//
+// This object class makes use of `position: absolute`
+// so the element is no longer in the document flow and has no width or height as
+// far as the parent element is concerned — the parent element must instead provide
+// the dimensions for the `.o-absolute-center` to align itself to.
 //
 // markup:
 // <div class="background-grey min-height-block">
 //   <p class="o-absolute-center">Centred content</p>
 // </div>
 //
-// Styleguide 1.11
+// Styleguide 4.1
 
 .#{$bitstyles-namespace}o-absolute-center {
   @include absolute-center;

data/scss/bitstyles/objects/_absolute-cover.scss

@@ -2,14 +2,23 @@
 //
 // Absolute Cover
 //
-// The element will cover its nearest relatively-positioned parent element from edge to edge.
+// **An element that covers its parent element from edge to edge** — vertically and
+// horizontally — **regardless of how it may stretch**.
+//
+// Not recommended for images, media etc. (elements width inherent dimensions) due
+// to that. This is most commonly used for container elements.
 //
 // markup:
 // <div class="o-absolute-cover background-grey">
 //   <p>Covering content</p>
 // </div>
 //
-// Styleguide 1.16
+// sg-wrapper:
+// <div class="min-height-block">
+//   <sg-wrapper-content/>
+// </div>
+//
+// Styleguide 4.2
 
 .#{$bitstyles-namespace}o-absolute-cover {
   @include absolute-cover;

data/scss/bitstyles/objects/_block.scss

@@ -2,12 +2,15 @@
 //
 // Block
 //
-// Display an element as a block.
+// **Forces an element to display as a block**, when it otherwise may be `inline`/
+// `inline-block`. This can be used to force an inline element onto a ‘new line’,
+// but also has implications for an element’s size (block elements expand horizontally
+// to the available width).
 //
 // Markup:
 // <span class="o-block background-grey">Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer.</span>
 //
-// Styleguide 1.25
+// Styleguide 4.3
 
 .#{$bitstyles-namespace}o-block {
   @include block;

data/scss/bitstyles/objects/_bordered-header.scss

@@ -2,12 +2,17 @@
 //
 // Bordered Header
 //
-// Creates equally-sized horizontal lines to the left & right of the element.
+// Creates equally-sized horizontal lines to the left & right of the text within
+// the element.
+//
+// The text is centered and the lines are of equal length. No background colour tricks
+// are used, so it can be used on any background — including images (some current techniques
+// for this cannot).
 //
 // markup:
 // <h2 class="o-bordered-header">Bordered header</h2>
 //
-// Styleguide 1.17
+// Styleguide 4.4
 
 @import '../settings/bordered-header';
 
@@ -22,9 +27,9 @@
   &::before,
   &::after {
     display: inline-block;
+    min-width: $bitstyles-bordered-header-line-min-width;
     vertical-align: middle;
     flex-grow: 1;
-    min-width: $bitstyles-bordered-header-line-min-width;
     border-top: $bitstyles-bordered-header-border;
     content: '';
   }

data/scss/bitstyles/objects/_break-long-words.scss

@@ -2,13 +2,16 @@
 //
 // Break long words
 //
-// A cross-browser friendly emthod of ensuring no words exceed the width of the container.
-// Use especially with user-generated content.
+// **Forces text content within an element to break if longer than the element is wide.**.
+//
+// A cross-browser friendly method of ensuring no words exceed the width of the
+// container. Commonly used to ensure user-generated content doesn’t break or
+// overflow your page layout.
 //
 // markup:
 // <p class="o-break-long-words">LongcontentwithnolinebreaksgoeshereLongcontentwithnolinebreaksgoeshereLongcontentwithnolinebreaksgoeshereLongcontentwithnolinebreaksgoeshereLongcontentwithnolinebreaksgoeshere</p>
 //
-// Styleguide 1.8
+// Styleguide 4.5
 
 .#{$bitstyles-namespace}o-break-long-words {
   @include break-long-words;

data/scss/bitstyles/objects/_button--icon.scss

@@ -1,13 +1,17 @@
 // Icon Button
 //
+// **A button with only an icon as visible content.**
+//
 // A specialised button type — (visible) content is intended to be only an icon.
-// Specify the svg `<title>` when `<use>`ing the icon element so the button has valid text to use as button label (see example markup),
-// or provide a `<span class="visuallyhidden"></span>` as sibling to the icon.
+// Commonly used for share buttons (facebook, twitter etc.).
+// Specify the svg `<title>` when `<use>`ing the icon element so the button has
+// valid text to use as button label (see example markup), or provide a
+// [visuallyhidden](/section/4.22) element containing descriptive text as sibling to the icon.
 //
 // markup:
 // <button class="o-button o-button--icon {$modifiers}">
 //   <svg class="o-icon">
-//     <title>Twitter logo</title>
+//     <title>Share on twitter</title>
 //     <use xlink:href="assets/images/icons.svg#icon-twitter"></use>
 //   </svg>
 // </button>
@@ -16,7 +20,7 @@
 // :hover        - Hover state.
 // :focus        - Focus state.
 //
-// Styleguide 1.2
+// Styleguide 4.6
 
 @import '../settings/button--icon';
 

data/scss/bitstyles/objects/_button.scss

@@ -1,12 +1,18 @@
 /** @define button */
 //
-// Button
+// Buttons
 //
-// Styleguide 1.1
+// **Buttons perform actions (they’re not links, nor navigation)**, and are ideally a `<button>`
+// element. Sometimes out of technical necessity this class can be applied to `<a>` elements
+// but beware — that’s code smell…
+//
+// Styleguide 4.7
 
 // Button - generic
 //
-// Produces a larger-than-text hit target. Intended to be an action, not a link — most often a `<button>` rather than `<a href="#">`.
+// **Produces a larger-than-text hit target**. Intended to be an action,
+// not a link, therefore most often a `<button>` rather than `<a href="…">` (and never
+// `<a href="#">`).
 //
 // markup:
 // <button class="o-button {$modifiers}">
@@ -18,7 +24,7 @@
 // :focus       - Focus state.
 // :disabled    - Disabled state.
 //
-// Styleguide 1.1.1
+// Styleguide 4.7.1
 
 @import '../settings/button';
 
@@ -49,10 +55,10 @@
   }
 
   &:disabled {
-    background: $bitstyles-button-background-color-disabled;
-    border-color: $bitstyles-button-border-color-disabled;
     color: $bitstyles-button-color-disabled;
     cursor: default;
+    background: $bitstyles-button-background-color-disabled;
+    border-color: $bitstyles-button-border-color-disabled;
   }
 }
 
@@ -64,35 +70,38 @@
 
 // Button - with icon
 //
-// A button can be used with an optional decorative icon, placed before the
-// text. Source order dictates icon position.
+// **The same base button can contain an optional decorative icon**.
+//
+// Here it’s placed before the text. Source order dictates icon position. There must be no whitespace between the icon and text — can be achieved using comments as shown here.
 //
 // markup:
 // <button class="o-button {$modifiers}">
-//   <svg class="o-button__icon o-icon"><use xlink:href="assets/images/icons.svg#icon-twitter"></use></svg><span class="o-button__label">Button Text</span>
+//   <svg class="o-button__icon o-icon"><use xlink:href="assets/images/icons.svg#icon-twitter"></use></svg><!--
+//   --><span class="o-button__label">Button Text</span>
 // </button>
 //
 //              - Base state
 // :hover       - Hover state.
 // :focus       - Focus state.
 //
-// Styleguide 1.1.2
+// Styleguide 4.7.2
 
 // Button - with icon, reversed
 //
-// A button can be used with an optional decorative icon, placed before the
+// **The same base button can contain an optional decorative icon**. Here it’s placed after the
 // text. Source order dictates icon position.
 //
 // markup:
 // <button class="o-button {$modifiers}">
-//   <span class="o-button__label">Button Text</span><svg class="o-button__icon o-icon"><use xlink:href="assets/images/icons.svg#icon-twitter"></use></svg>
+//   <span class="o-button__label">Button Text</span><!--
+//   --><svg class="o-button__icon o-icon"><use xlink:href="assets/images/icons.svg#icon-twitter"></use></svg>
 // </button>
 //
 //              - Base state
 // :hover       - Hover state.
 // :focus       - Focus state.
 //
-// Styleguide 1.1.3
+// Styleguide 4.7.3
 
 .#{$bitstyles-namespace}o-button__icon + .#{$bitstyles-namespace}o-button__label {
   margin-left: $bitstyles-button-icon-spacing;