bitstyles 0.8.0 → 0.9.1

data/scss/bitstyles/tools/_block.scss

@@ -1,8 +1,11 @@
 // 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).
 //
-// Styleguide 2.16
+// Styleguide 1.3
 
 @mixin block {
   display: block;

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

@@ -1,8 +1,12 @@
 // Break long words
 //
-// Forces text content within an element to break if longer than the element is wide.
+// **Forces text content within an element to break if longer than the element is wide.**.
 //
-// Styleguide 2.3
+// 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.
+//
+// Styleguide 1.4
 
 @mixin break-long-words {
   overflow-wrap: break-word;

data/scss/bitstyles/tools/_clearfix.scss

@@ -1,8 +1,13 @@
 // Clearfix
 //
-// Apply to a floated element (or its parent) to ensure following elements are cleared.
+// **Cleanup after `float`ed elements**.
 //
-// Styleguide 2.4
+// Force an element to behave as if its floated children have an element after them
+// with `clear: both`. The element will therefore be of the correct height (including
+// backgrounds etc.) instead of collapsing on the floated children, and will be correctly separated
+// from the following content, as cleared elements are.
+//
+// Styleguide 1.5
 
 @mixin clearfix {
   &::after {

data/scss/bitstyles/tools/_fixed-ratio.scss

@@ -1,10 +1,37 @@
 // Fixed Ratio
 //
-// An element that has intrinsic shape — width will be 100%, height will be limited to keep 16:9 aspect ratio.
+// **Enforces an aspect ratio on this element and its contents**.
 //
-// Styleguide 2.5
+// An element that has intrinsic shape — width will be 100%, height will be limited
+// to keep your aspect ratio. Pass in width & height parameters to set your aspect
+// ratio.
+//
+// Use the `fixed-ratio--variant` mixin to create modifier classes with ratios
+// different to your base class.
+//
+// e.g.
+//
+// ```scss
+// .o-fixed-ratio {
+//   @include fixed-ratio(16, 9);
+// }
+//
+// .o-fixed-ratio--16-10 {
+//   @include fixed-ratio--variant(16, 10);
+// }
+//
+// .o-fixed-ratio--square {
+//   @include fixed-ratio--variant(10, 10);
+// }
+// ```
+//
+// @param {Number} $width  Unitless number. Sets the width of the element.
+//
+// @param {Number} $height  Unitless number. Sets the height of the element.
+//
+// Styleguide 1.6
 
-@mixin fixed-ratio {
+@mixin fixed-ratio($width, $height) {
   position: relative;
   display: block;
   width: 100%;
@@ -12,11 +39,21 @@
 
   &::before {
     display: block;
-    padding-top: 56.25%;
+    padding-top: percentage-aspect-ratio($width, $height);
     content: '';
   }
 }
 
+@mixin fixed-ratio--variant($width, $height) {
+  &::before {
+    padding-top: percentage-aspect-ratio($width, $height);
+  }
+}
+
+@function percentage-aspect-ratio($width, $height) {
+  @return percentage($height / $width);
+}
+
 @mixin fixed-ratio__inner {
   @include absolute-cover;
 

data/scss/bitstyles/tools/_flex.scss

@@ -1,9 +1,13 @@
 // Flex
 //
-// Simple flex layout.
-// Make one of the children `.o-flex__primary` to make it take as much space as is available.
+// **Basic flex layout**.
 //
-// Styleguide 2.17
+// Apply to an element to simply make its children share the available width e.g.
+// a list of links in a menu.
+// Make one of the children `.o-flex__primary` to make it take as much space as is
+// available i.e. all the horizontal space left after its siblings take the minimum width they need.
+//
+// Styleguide 1.7
 
 @mixin flex {
   display: flex;

data/scss/bitstyles/tools/_font-face.scss

@@ -1,10 +1,19 @@
 // Webfont
 //
-// Helper mixin to output a widely cross-browser-compatible `@font-face` declaration.
+// Helper mixin to output a widely cross-browser-compatible `@font-face` declaration
+// for importing webfonts.
 //
 // ```@include webfont(Roboto, italic, 700, 'fonts/roboto-bold-italic');```
 //
-// Styleguide 2.15
+// @param {String} $font-family  The name by which this font will be referred to.
+//
+// @param {String} $font-style  The `font-style` of the font you’re defining e.g. `normal`, `italic`.
+//
+// @param {String} $font-weight  The `font-weight` of the font you’re defining e.g. `100`, `400`, `bold`.
+//
+// @param {String} $font-url  The location at which the font assets can be found. Expects `.eot`, `.woff2`, `.woff`, and `.ttf` versions to exist there.
+//
+// Styleguide 1.8
 
 @mixin webfont($font-family, $font-style, $font-weight, $font-url) {
   @font-face {

data/scss/bitstyles/tools/_hidden.scss

@@ -1,8 +1,11 @@
 // Hidden
 //
-// Fully hides an element & its children — does not affect document flow, does not get read by google or screenreaders.
+// **Hidden from everyone — you, search engines, screenreaders…**
 //
-// Styleguide 2.6
+// Fully hides an element & its children — the element will not affect document
+// flow, nor get read by google or screenreaders.
+//
+// Styleguide 1.9
 
 @mixin hidden {
   /* stylelint-disable declaration-no-important */

data/scss/bitstyles/tools/_link.scss

@@ -0,0 +1,25 @@
+/* @define Link */
+// Link
+//
+// Styling for all links.
+//
+// Styleguide 1.22
+
+@mixin link {
+  color: $bitstyles-color-link;
+  text-decoration: $bitstyles-text-decoration-link;
+  text-decoration-skip: $bitstyles-text-decoration-skip-link;
+  cursor: pointer;
+  background: $bitstyles-background-color-link;
+  transition: $bitstyles-link-transition;
+
+  &:visited {
+    color: $bitstyles-color-link-visited;
+  }
+
+  &:hover,
+  &:focus {
+    color: $bitstyles-color-link-hover;
+    text-decoration: $bitstyles-text-decoration-link-hover;
+  }
+}

data/scss/bitstyles/tools/_list-reset.scss

@@ -1,11 +1,15 @@
 // List reset
 //
-// Removes the default bullet points from a list, along with any margins and
-// padding.
+// **Removes the default margin, padding and bullets**
+//
+// This makes `<ul>`s much more usable as a semantic container, without it creating
+// styling issues due to browser defaults intended for bullet lists in text documents.
 //
 // Optional parameters to prevent removal of margins and padding.
 //
-// Styleguide 2.13
+// @param {Bool} $spacing  If true, all default margins & padding will removed, as well as the list’s bullets.
+//
+// Styleguide 1.10
 
 @mixin list-reset($spacing: true) {
   @if $spacing {

data/scss/bitstyles/tools/_media-query.scss

@@ -1,22 +1,29 @@
 // Media Query
 //
-// Helper function to ease usage of media-queries. Uses the breakpoints listed in $breakpoint sass variable.
+// **Helper function to ease usage of media-queries**.
+//
+// By default it uses the breakpoints listed in `$bitstyles-breakpoints` sass variable,
+// but you can also pass in a list as a parameter.
 //
 // Usage:
 //
-// `
+// ```scss
 // @media-query(breakpoint-name) {
 //    .selector {
 //       …styles here…
 //    }
 // }
-// `
+// ```
+//
+// @param {String} $media-query-name  Name of the media query you’re referring to, as defined in the $breakpoints parameter (see below).
+//
+// @param {Map} $breakpoints  Optional. A map of breakpoints. By default `$bitstyles-breakpoints` will be used, but if you pass in another list of breakpoints, that will be used instead.
 //
-// Styleguide 2.11
+// Styleguide 1.11
 
-@mixin media-query($mq, $breakpoints: $bitstyles-breakpoints) {
+@mixin media-query($media-query-name, $breakpoints: $bitstyles-breakpoints) {
 
-  $breakpoint-condition: map-get($breakpoints, $mq);
+  $breakpoint-condition: map-get($breakpoints, $media-query-name);
 
   @if ($breakpoint-condition) {
     @media #{$breakpoint-condition} {
@@ -25,6 +32,6 @@
   }
 
   @else {
-    @error "Oops! Breakpoint ‘#{$mq}’ does not exist.";
+    @error "Oops! Breakpoint ‘#{$media-query-name}’ does not exist.";
   }
 }

data/scss/bitstyles/tools/_media.scss

@@ -1,8 +1,15 @@
 // Media
 //
-// Nicole Sullivan’s OOCSS media object.
+// **[Nicole Sullivan’s OOCSS media object](http://www.stubbornella.org/content/2010/06/25/the-media-object-saves-hundreds-of-lines-of-code/)**.
 //
-// Styleguide 2.18
+// Contains a ‘feature’ element floated left e.g. a small user image. All other content
+// (perhaps the user’s comment) flows around it to the right. The feature element
+// should have either implicit size (like an image or video element), or have width set.
+//
+// If the feature element is as wide as the viewport, any adjacent content will drop drown
+// below it instead of ranging right.
+//
+// Styleguide 1.12
 
 @mixin media {
   display: block;
@@ -11,5 +18,5 @@
 
 @mixin media__feature {
   float: left;
-  margin-right: $bitstyles-spacing;
+  margin-right: spacing('base');
 }

data/scss/bitstyles/tools/_overflow.scss

@@ -0,0 +1,19 @@
+// Overflow
+//
+// **Vertical scrolling panel**
+//
+// Any vertical overflow on the element is allowed to scroll, horizontal overflow is not.
+// Different browsers/OSes have different strategies for displaying scrollbars when they’re
+// needed, this mixin at least ensures no scrollbars are displayed unless there’s
+// something to scroll.
+//
+// Styleguide 1.23
+
+// (1) Fixes bug in safari that causes the scrollbars to appear behind some content within the overflow element.
+
+@mixin overflow {
+  max-height: 100%;
+  -webkit-overflow-scrolling: touch;
+  overflow-y: auto;
+  transform: translateZ(0); // (1)
+}

data/scss/bitstyles/tools/_palette.scss

@@ -0,0 +1,28 @@
+// Palette
+//
+// **Returns requested colours from the global `$bitstyles-palette` map.**
+// e.g. `color: palette('text');`
+//
+// @param {String} $color  Base colour within the palette
+//
+// @param {String} $tone   Optional. Variant of the colour e.g. 'base', light', 'dark'. Defaults to `base`.
+//
+// Styleguide 1.20
+
+@function palette($color, $tone: 'base') {
+  @if map-has-key($bitstyles-palette, $color) {
+    $palette: map-get($bitstyles-palette, $color);
+
+    @if map-has-key($palette, $tone) {
+      @return map-get($palette, $tone);
+    }
+
+    @else {
+      @error "Oops! Color/tone ‘#{$color}/#{$tone}’ does not exist.";
+    }
+  }
+
+  @else {
+    @error "Oops! Color ‘#{$color}’ does not exist.";
+  }
+}

data/scss/bitstyles/tools/_spacing.scss

@@ -0,0 +1,22 @@
+// Spacing
+//
+// **Returns requested size/length from the global `$bitstyles-spacing-sizes` map**.
+//
+// e.g. `padding: spacing('small');`
+//
+// Default naming of sizes: `base`, `small`, `large` (suggested: `x-small`,
+// `xx-small` etc. for further variants)
+//
+// @param {String} $spacing-size  Name of the standardised size required, as defined in the map `$bitstyles-spacing-sizes`.
+//
+// Styleguide 1.21
+
+@function spacing($spacing-size) {
+  @if map-has-key($bitstyles-spacing-sizes, $spacing-size) {
+    @return map-get($bitstyles-spacing-sizes, $spacing-size);
+  }
+
+  @else {
+    @error "Oops! Spacing size ‘#{$spacing-size}’ does not exist.";
+  }
+}

data/scss/bitstyles/tools/_truncate-with-ellipsis.scss

@@ -1,9 +1,13 @@
 // Truncate with ellipsis(…)
 //
-// If an element is single-line inline or inline-block, this will truncate its content
-// and display an ellipsis (…) at the end of the line.
+// **When text content is wider than parent width, truncate text with an ellipsis (…).**
+// The parent element needs a set or limited width.
+// Note the exact algorithm is defined per browser and is of varying quality
+// — you may lose a couple of characters just to display an ellipsis instead.
 //
-// Styleguide 2.9
+// @param {Number} $truncation-boundary  CSS dimension with unit. Define the maximum allowed width of the element, before its text content will be truncated. Defaults to `100%`, so the element will fill its parent but no more.
+//
+// Styleguide 1.13
 
 @mixin truncate-with-ellipsis($truncation-boundary: 100%) {
   max-width: $truncation-boundary;

data/scss/bitstyles/tools/_typography-conversions.scss

@@ -1,18 +1,31 @@
 // Px to Rem sizing
 //
-// Converts pixels to rems — use to define font-sizes etc.
+// **Converts pixels to rems**.
 //
-// Styleguide 2.12.1
+// Used to define font-sizes (within the `set-font-size` and other mixins).
+//
+// @param {Number} $pixel-size  CSS dimension in `px` units. The font-size required, in pixels.
+//
+// @param {Number} $root-size  CSS dimension in `px` units. The current base font-size of the page (normally the font-size of the `html` element).
+//
+// Styleguide 1.14.1
 
 @function px-to-rem($pixel-size, $root-size: $bitstyles-font-size-base-small) {
   @return ($pixel-size / $root-size) * 1rem;
 }
 
-// em sizing
+// Px to em sizing
+//
+// **Converts pixels to ems**
 //
-// Converts pixels to ems — use to define font-sizes etc.
+// Used to define font-sizes (within the `set-font-size` and other mixins).
 //
-// Styleguide 2.12.2
-@function px-to-em($pixels, $browser-context: $bitstyles-font-size-base-small) {
-  @return ($pixels / $browser-context) + 0em; // stylelint-disable-line length-zero-no-unit
+// @param {Number} $pixel-size  CSS dimension in `px` units. The font-size required, in pixels.
+//
+// @param {Number} $root-size  CSS dimension in `px` units. The current base font-size of the page (normally the font-size of the `html` element).
+//
+// Styleguide 1.14.2
+
+@function px-to-em($pixel-size, $root-size: $bitstyles-font-size-base-small) {
+  @return ($pixel-size / $root-size) + 0em; // stylelint-disable-line length-zero-no-unit
 }

data/scss/bitstyles/tools/_typography.scss

@@ -1,17 +1,136 @@
+// Typographic helpers
+//
+// Styleguide 1.15
+
+// Generic heading
+//
+// **Shared styles for heading elements**
+//
+// Styleguide 1.15.1
+
 @mixin generic-heading {
-  margin: 0 0 $bitstyles-spacing;
+  margin: 0 0 spacing('base');
   font-family: $bitstyles-font-family-header;
   font-weight: $bitstyles-font-weight-bold;
   text-rendering: optimizeLegibility;
 
-  .fonts-loaded & {
-    font-family: $bitstyles-font-family-header-loaded;
+  @if $bitstyles-font-family-header-loaded != $bitstyles-font-family-header {
+    .fonts-loaded & {
+      font-family: $bitstyles-font-family-header-loaded;
+    }
   }
 }
 
-@mixin font-size($pixel-size, $browser-context: $bitstyles-font-size-base-small) {
+// Font-size helper
+//
+// **Standarised method to set font-size**.
+//
+// Sets font-sizes using `rem`s with `px` fallback.
+//
+// @param {Number} $pixel-size  CSS dimension in `px` units. The font-size required, in pixels.
+//
+// @param {Number} $root-size  CSS dimension in `px` units. The current base font-size of the page (normally the font-size of the `html` element).
+//
+// Styleguide 1.15.2
+
+@mixin set-font-size($pixel-size, $root-size: $bitstyles-font-size-base-small) {
   /* stylelint-disable declaration-block-no-duplicate-properties */
   font-size: $pixel-size;
-  font-size: px-to-rem($pixel-size, $browser-context);
+  font-size: px-to-rem($pixel-size, $root-size);
   /* stylelint-enable declaration-block-no-duplicate-properties */
 }
+
+// Font-size generator
+//
+// **Generate your typographic scale**
+//
+// Set your font-sizes in the map `$bitstyles-font-sizes` e.g.
+//
+// ```scss
+// $bitstyles-font-sizes: (
+//   'base': (
+//     'html': $bitstyles-font-size-base-small,
+//     'h0': 32px,
+//     'h1': 24px,
+//     'h2': 20px,
+//     'h3': 18px,
+//     'h4': $bitstyles-font-size-base-small,
+//     'h5': $bitstyles-font-size-base-small,
+//     'h6': $bitstyles-font-size-base-small
+//   ),
+//   'medium-and-up': (
+//     'html': $bitstyles-font-size-base,
+//     'h0': 86px,
+//     'h1': 40px,
+//     'h2': 28px,
+//     'h3': 20px,
+//     'h4': $bitstyles-font-size-base,
+//     'h5': $bitstyles-font-size-base,
+//     'h6': $bitstyles-font-size-base
+//   )
+// );
+// ```
+//
+// Use `px` to define font-sizes, the output will specify `rem`s with a `px` fallback.
+//
+// `base` is a reserved word, and results in font-sizes being output without an enclosing media query.
+//
+// The media-query names used should be defined in `$bitstyles-breakpoints`.
+//
+// @param {String} $prefix  Optional. Provide a string that will be prepended to the element name. Can include `.` to output classname selectors instead of elements.
+//
+// @param {List} $subset  Optional. Provide a list of element names for which to output font-sizes. Defaults to include all sizes defined in `$bitstyles-font-sizes`.
+//
+// Styleguide 1.15.3
+
+@mixin generate-font-sizes($prefix: '', $subset: ()) {
+  @each $media-query-name, $font-sizes in $bitstyles-font-sizes {
+    // Don’t wrap base classes in a media-query
+    @if $media-query-name == 'base' {
+      @include output-font-sizes($font-sizes, $prefix, $subset);
+    }
+
+    @else {
+      @include media-query($media-query-name) {
+        @include output-font-sizes($font-sizes, $prefix, $subset);
+      }
+    }
+  }
+}
+
+// Output font sizes
+//
+// **Private mixin**
+//
+// Used to output font-sizes from a map of font-sizes in `element-name: font-size` pairs.
+//
+// @param {Map} $font-sizes  A map of font-sizes in `element-name: font-size` pairs. See `$bitstyles-font-sizes` for an example.
+//
+// @param {String} $prefix  A string to prefix to the ouput selector.
+//
+// @param {List} $subset  Provide a list of element names for which to output font-sizes. Defaults to include all sizes defined in the `$font-sizes` parameter.
+
+@mixin output-font-sizes($font-sizes, $prefix, $subset) {
+  $base-size: $bitstyles-font-size-base-small;
+
+  @if map-has-key($font-sizes, 'html') {
+    $base-size: map-get($font-sizes, 'html');
+  }
+
+  @each $element-name, $font-size in ($font-sizes) {
+    @if (length($subset) == 0) or (index($subset, $element-name)) {
+      #{$bitstyles-namespace}#{$prefix}#{$element-name} {
+        /* stylelint-disable max-nesting-depth */
+        @if $element-name == 'html' {
+          // Base font-size must be relative to browser default, not itself!
+          @include set-font-size($font-size);
+        }
+
+        @else {
+          @include set-font-size($font-size, $base-size);
+        }
+        /* stylelint-enable max-nesting-depth */
+      }
+    }
+  }
+}