bitstyles 0.8.0 → 0.9.1

data/scss/bitstyles/objects/_clearfix.scss

@@ -2,9 +2,12 @@
 //
 // Clearfix
 //
-// Force an element to behave as if its floated children have been `clear: both`ed.
-// The element will therefore be of the correct height (including backgrounds etc.)
-// and will be separated from other content (as cleared elements are).
+// **Cleanup after `float`ed elements**.
+//
+// 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.
 //
 // markup:
 // <div class="o-clearfix background-grey">
@@ -12,7 +15,7 @@
 //   <div class="floated-element">Content goes here</div>
 // </div>
 //
-// Styleguide 1.7
+// Styleguide 4.8
 
 .#{$bitstyles-namespace}o-clearfix {
   @include clearfix;

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

@@ -2,20 +2,35 @@
 //
 // Fixed-ratio
 //
-// Enforces an aspect ratio on this element anbd its contents. Default ratio is 16:9, element take 100% width and height matches.
+// **Enforces an aspect ratio on this element and its contents**.
+//
+// The element takes 100% width, then the height is set to the keep the element
+// at the specified ratio. Default ratio is defined as 16:9 in the Sass map
+// `$fixed-ratio-default-ratio` under the keys `width` and `height` e.g.
+// `$fixed-ratio-default-ratio: ('width': 10, 'height': 20)`
 //
 // markup:
-// <figure>
-//   <div class="o-fixed-ratio">
-//     <img class="o-fixed-ratio__inner" src="assets/images/placeholder_16-9.png">
-//   </div>
-//   <figcaption>An image at 16:9 aspect ratio</figcaption>
-// </figure>
+// <div class="o-fixed-ratio">
+//   <img class="o-fixed-ratio__inner" src="assets/images/placeholder_16-9.png">
+// </div>
+//
+// sg-wrapper:
+// <div class="object-section">
+//   <figure>
+//     <sg-wrapper-content/>
+//     <figcaption>An image at 16:9 aspect ratio</figcaption>
+//   </figure>
+// </div>
 //
-// Styleguide 1.18
+// Styleguide 4.9
+
+@import '../settings/fixed-ratio';
 
 .#{$bitstyles-namespace}o-fixed-ratio {
-  @include fixed-ratio;
+  @include fixed-ratio(
+    map-get($fixed-ratio-default-ratio, 'width'),
+    map-get($fixed-ratio-default-ratio, 'height')
+  );
 }
 
 .#{$bitstyles-namespace}o-fixed-ratio__inner {

data/scss/bitstyles/objects/_flex.scss

@@ -2,18 +2,22 @@
 //
 // 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**.
+//
+// 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.
 //
 // markup:
-// <ul class="o-flex">
-//  <li>Some content here</li>
-//  <li class="o-flex__primary">Some more important content here</li>
-//  <li>Some content here</li>
-//  <li>Some content here</li>
+// <ul class="o-flex o-list-reset">
+//  <li>List item one</li>
+//  <li class="o-flex__primary">Important content here</li>
+//  <li>List item three</li>
+//  <li>List item four</li>
 // </ul>
 //
-// Styleguide 1.10
+// Styleguide 4.10
 
 .#{$bitstyles-namespace}o-flex {
   @include flex;

data/scss/bitstyles/objects/_hidden.scss

@@ -2,12 +2,15 @@
 //
 // Hidden
 //
-// Fully hides an element & its children — does not affect document flow, does not get read by google or screenreaders.
-// Available at every breakpoint defined in `$hidden-breakpoints`.
+// **Hidden from everyone — you, search engines, screenreaders…**
 //
-// .o-hidden          - Hide this element always (generally so it can be revealed using JS)
-// .o-hidden@small    - Hide this content on smallscreens
-// .o-hidden@large    - Hide this content on larger screens
+// Fully hides an element & its children — it will be taken out of the document
+// flow, and will therefore not be read by google or screenreaders. Available at
+// every breakpoint defined in `$bitstyles-hidden-breakpoints`.
+//
+// .o-hidden               - Hide this element always (generally so it can be revealed using JS)
+// .o-hidden@small-only    - Hide this content on smallscreens
+// .o-hidden@large         - Hide this content on larger screens
 //
 // markup:
 // <p>Paragraph 1 content</p>
@@ -16,7 +19,7 @@
 // <p class="{$modifiers}">Paragraph 4 content</p>
 // <p>Paragraph 5 content</p>
 //
-// Styleguide 1.13
+// Styleguide 4.11
 
 @import '../settings/hidden';
 
@@ -24,7 +27,7 @@
   @include hidden;
 }
 
-@each $breakpoint in $hidden-breakpoints {
+@each $breakpoint in $bitstyles-hidden-breakpoints {
   @include media-query($breakpoint) {
     .#{$bitstyles-namespace}o-hidden\@#{$breakpoint} {
       @include hidden;

data/scss/bitstyles/objects/_icon.scss

@@ -2,9 +2,20 @@
 //
 // Icons
 //
-// We use an svg-based icon system. All icons are present as symbols within `icons.svg`, and are used by embedding svg tags (see example markup).
-// Provide a `<title>` element at the point an icon is used to ensure there is some text content (equivalent to the alt property on `<img>`s.)
-// Set icon sizes by overiding the `$bitstyles-icon-sizes` map (see settings file). Default icon size is the same as surrounding text i.e. `1em`.
+// **SVG icon system**.
+//
+// All icons are present as symbols within
+// `icons.svg`, and are used by embedding svg tags (see example markup).
+// Icons should be accompanied by some machine-readable text for accessibility &
+// SEO purposes. If there is to be no such text (e.g. based on design mockups),
+// provide an alternative:
+// - provide a `<title>` element containing text, next to the `<use>` element
+// - Next to the `<svg>` element place a `<span class="o-visuallyhidden">` containing descriptive text
+//
+// Set icon sizes by overiding the `$bitstyles-icon-sizes` list (see `settings/_icon.scss`) e.g.
+// ``$bitstyles-icon-sizes: ('small' 2rem, 'medium' 4rem, 'large' 8rem);`
+//
+// The base icon size is the same as surrounding text i.e. `1em`.
 //
 // markup:
 // <svg class="o-icon {$modifiers}">
@@ -12,12 +23,12 @@
 //   <use xlink:href="assets/images/icons.svg#icon-twitter"></use>
 // </svg>
 //
-// default          - Base size, matches font-size of parent element.
+//                    - Base size, matches font-size of parent element.
 // .o-icon--small     - Small icon (given default vars).
 // .o-icon--medium    - Medium icon (given default vars).
 // .o-icon--large     - Large icon (given default vars).
 //
-// Styleguide 1.3
+// Styleguide 4.12
 
 @import '../settings/icon';
 
@@ -32,12 +43,9 @@
   fill: currentColor;
 }
 
-@each $icon-size in $bitstyles-icon-sizes {
-  $alias: nth($icon-size, 1);
-  $size: nth($icon-size, 2);
-
+@each $icon-size-alias, $icon-size-size in $bitstyles-icon-sizes {
   /* postcss-bem-linter: ignore */
-  .#{$bitstyles-namespace}o-icon--#{$alias} {
-    font-size: $size;
+  .#{$bitstyles-namespace}o-icon--#{$icon-size-alias} {
+    font-size: $icon-size-size;
   }
 }

data/scss/bitstyles/objects/_input.scss

@@ -1,16 +1,18 @@
 /** @define input */
 // Form inputs
 //
-// Basic styling for input elements. All inputs stretch to fill their parent —
-// their width can be constrained by the parent element.
+// **Base styling for input elements**.
+// All inputs stretch to fill their parent — their width is constrained by the parent element.
 //
-// Styleguide 1.22
+// Styleguide 4.13
 
 @import '../settings/input';
 
 // Form inputs - text
 //
-// Text inputs are those that accept a string input — text, email, number, date.
+// **All inputs that accept a string input e.g. text, email, number, date**
+//
+// Includes styles for focus, active & disabled states.
 //
 // Markup:
 //   <label class="o-label" for="input_1">This is labeling text</label>
@@ -21,7 +23,7 @@
 // :disabled    - Disabled state.
 // :active      - Active/focus state
 //
-// Styleguide 1.22.1
+// Styleguide 4.13.1
 
 .#{$bitstyles-namespace}o-input {
   @include block;
@@ -31,19 +33,19 @@
 
 .#{$bitstyles-namespace}o-input--text {
   padding: $bitstyles-input-padding;
+  color: $bitstyles-input-color;
   background-color: $bitstyles-input-background;
   border: $bitstyles-input-border;
   border-radius: $bitstyles-input-border-radius;
-  color: $bitstyles-input-color;
 
   &::placeholder {
     color: $bitstyles-input-placeholder-color;
   }
 
   &:disabled {
-    background: $bitstyles-input-background-color-disabled;
     color: $bitstyles-input-color-disabled;
     cursor: default;
+    background: $bitstyles-input-background-color-disabled;
   }
 
   &:active,
@@ -54,6 +56,8 @@
 
 // Form inputs - Select
 //
+// Base styling for select elements. Not much can be done here, sadly.
+//
 // Markup:
 //   <label class="o-label" for="select_1">This is labeling text</label>
 //   <select class="o-input" id="select_1">
@@ -62,17 +66,20 @@
 //     <option value="value3">Value 3</option>
 //   </select>
 //
-// Styleguide 1.22.2
+// Styleguide 4.13.2
 
 // Form inputs - Checkbox
 //
+// Base styling for checkboxes. Not much can be done here, but size and spacing
+// are set.
+//
 // Markup:
 //    <label class="o-label">
 //      <input type="checkbox" class="o-input o-input--checkbox">
 //      This is labeling text. Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer. Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer. Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer. Jelly cake marshmallow. Pie cotton candy chupa chups marzipan liquorice cheesecake wafer.
 //    </label>
 //
-// Styleguide 1.22.3
+// Styleguide 4.13.3
 
 .#{$bitstyles-namespace}o-input--checkbox {
   display: inline-block;

data/scss/bitstyles/objects/_label.scss

@@ -1,13 +1,13 @@
 /** @define label */
 // Form labels
 //
-// Default styling for form labels.
+// **Default styling for form labels**.
 //
 // Markup:
 //   <label class="o-label" for="input_1">This is label text</label>
 //   <input class="o-input o-input--text" type="text" placeholder="Placeholder text" id="input_1" />
 //
-// Styleguide 1.23
+// Styleguide 4.14
 
 .#{$bitstyles-namespace}o-label {
   display: block;

data/scss/bitstyles/objects/_link.scss

@@ -1,29 +1,32 @@
 /* @define Link */
 // Link
 //
-// Mimicking standard anchors e.g. allows a `<button>` to look like a link
+// Mimicking the appearance of standard anchor elements e.g. allows a `<button>` to look like a link.
+// This is generally a bad practice — if it looks like a link, it should be a link —
+// but it’s sometimes necessary for technical reasons e.g. it can’t be a link because no
+// url change occurs when displaying a modal or similar. This is always code smell
+// but is sometimes necessary.
 //
 // Markup:
-// <p>Read our <button class="o-link">Privacy Policy</button>.</p>
+// <button class="o-link {$modifiers}">Privacy Policy</button>
 //
-// Styleguide 1.26
+//                - Default state
+// :hover         - Hover state
+// :focus         - Focus state
+// :visited       - Visited state
+//
+// sg-wrapper:
+// <p>Read our <sg-wrapper-content/>.</p>
+//
+// Styleguide 4.15
 
 @import '../settings/link';
 
 .#{$bitstyles-namespace}o-link {
+  @include link;
+
   padding: 0;
-  background: none;
-  color: $bitstyles-color-link;
   border: 0;
-  cursor: pointer;
+  transition: $bitstyles-link-transition;
   -webkit-appearance: none; // stylelint-disable-line property-no-vendor-prefix
-
-  &:visited {
-    color: $bitstyles-color-link-visited;
-  }
-
-  &:hover,
-  &:focus {
-    color: $bitstyles-color-link-hover;
-  }
 }

data/scss/bitstyles/objects/_list-inline.scss

@@ -0,0 +1,26 @@
+/** @define list-inline */
+//
+// List inline
+//
+// **Display a list of items inline**.
+//
+// Wherever a list is useful semantically but the default vertical-stack layout
+// for bullet points isn’t correct, this object is useful. Often used to display
+// a list of links (anchors wrapped in `<li>`s) in a row next to each other.
+//
+// markup:
+// <ul class="o-list-inline">
+//   <li class="o-list-inline__item"><a href="#one">link one</a></li>
+//   <li class="o-list-inline__item"><a href="#two">link two</a></li>
+//   <li class="o-list-inline__item"><a href="#three">link three</a></li>
+// </ul>
+//
+// Styleguide 4.16
+
+.#{$bitstyles-namespace}o-list-inline {
+  list-style: none;
+}
+
+.#{$bitstyles-namespace}o-list-inline__item {
+  display: inline;
+}

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

@@ -1,8 +1,10 @@
 /** @define list-reset */
 // List reset
 //
-// List reset removes the default margin, padding and bullets on a list, making
-// it more useful as a semantic container.
+// **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.
 //
 // Markup:
 // <ul class="{$modifiers}">
@@ -14,7 +16,7 @@
 // o-list-reset                 - Remove padding, margin and list-style-type
 // o-list-reset--bullets-only   - Remove list-style-type only. Does not rely on `list-reset`. Useful if `list-reset` would adversely affect the margin or padding of another component.
 //
-// Styleguide 1.19
+// Styleguide 4.17
 
 .#{$bitstyles-namespace}o-list-reset {
   @include list-reset();

data/scss/bitstyles/objects/_media.scss

@@ -1,7 +1,14 @@
 /** @define media */
 // 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/)**.
+//
+// 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.
 //
 // markup:
 // <div class="o-media">
@@ -9,7 +16,7 @@
 //   <p>Some text here that sits against the featured image on its left</p>
 // </div>
 //
-// Styleguide 1.21
+// Styleguide 4.18
 
 .#{$bitstyles-namespace}o-media {
   @include media;

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

@@ -0,0 +1,20 @@
+// Object-fit Cover
+//
+// Any element with inherent size (e.g. an `<img>`) will expand to fill the available space
+// while maintaining their aspect ratio. One dimension will overflow its parent as needed
+// in order to fill the other dimension.
+//
+// markup:
+//  <div class="fixed-height-block">
+//    <img class="o-object-cover" src="assets/images/placeholder_16-9.png">
+//  </div>
+//
+// Styleguide 4.24
+
+.o-object-cover {
+  display: block;
+  width: 100%;
+  height: 100%;
+  object-fit: cover;
+  font-family: 'object-fit: cover;'; // Required for the polyfill
+}

data/scss/bitstyles/objects/_overflow.scss

@@ -0,0 +1,20 @@
+/** @define overflow */
+// 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 class at least ensures no scrollbars are displayed unless there’s
+// something to scroll.
+//
+// markup:
+// <div class="o-overflow 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>
+//
+// Styleguide 4.23
+
+.o-overflow {
+  @include overflow;
+}