diff --git a/Gruntfile.js b/Gruntfile.js index 9cb65298c..2d34e6d66 100644 --- a/Gruntfile.js +++ b/Gruntfile.js @@ -25,7 +25,6 @@ module.exports = function(grunt) { autofill: ['requires', 'throws'], exclude: [ 'vendors/*', - 'base/*' ], display: { sort: [ @@ -35,6 +34,33 @@ module.exports = function(grunt) { 'file', ], }, + groups: { + '_variables|__decanter': 'Decanter Settings', + '_variables|_bourbon': 'Bourbon Settings', + '_variables|_neat': 'Neat Settings', + '_variables|animations': 'Animation & Transition Variables', + '_variables|borders': 'Border Variables', + '_variables|breakpoint-boundaries': 'Breakpoint Variables', + '_variables|grid-media': 'Grid Media Variables', + '_variables|buttons': 'Button Variables', + '_variables|colors': 'Color Variables', + '_variables|containers': 'Container Variables', + '_variables|forms': 'Form Variables', + '_variables|typography': 'Typography Variables', + '_variables|vertical-rhythm': 'Vertical Rhythm Variables', + 'font-management': 'Font Loading & Management', + 'functions': 'Functions', + 'mixins': 'Mixins', + 'base|_documentation': 'Documentation for Base', + 'base|box-model': 'Box Model', + 'base|body': 'Body', + 'base|typography': 'Typography', + 'base|forms': 'Forms', + 'base|lists': 'Lists', + 'base|tables': 'Tables', + 'base|media-elements': 'Media Elements', + 'base|buttons': 'Buttons', + }, }, }, base: { @@ -52,7 +78,15 @@ module.exports = function(grunt) { ], }, groups: { + 'base|_documentation': 'Documentation for Base', + 'base|box-model': 'Box Model', + 'base|body': 'Body', 'base|typography': 'Typography', + 'base|forms': 'Forms', + 'base|lists': 'Lists', + 'base|tables': 'Tables', + 'base|media-elements': 'Media Elements', + 'base|buttons': 'Buttons', }, }, }, diff --git a/core/base/_body.scss b/core/base/_body.scss index 269871ebf..6d9c452e8 100644 --- a/core/base/_body.scss +++ b/core/base/_body.scss @@ -3,46 +3,117 @@ //// /// Root html element styles for the body and main elements. /// Style placement and basic settings for the top level html elements. +/// /// @group base|body +/// +/// @type map +/// +/// @see $group__element--default +/// @see $group__element //// +// --------------------------------------------------------------------------------------------------------------------- +/// - Default body element styling /// -/// Body defaults -/// +/// @example scss - Used in `base/_body.scss` by the `body` element +/// body { +/// @include properties($body__body--default, $body__body); +/// } +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body +$body__body--default: ( + min-height: 100vh, + display: flex, + flex-direction: column, + overflow-x: hidden, + margin: 0, +) !default; + +$body__body: () !default; + body { - min-height: 100vh; - display: flex; - flex-direction: column; - overflow-x: hidden; - margin: 0; + @include properties($body__body--default, $body__body); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up source order for mobile first approach +/// +/// @example scss - Used in `base/_body.scss` by the `body > header` element +/// body > header { +/// @include properties($body__body-header--default, $body__body-header); +/// } +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header +$body__body-header--default: ( + order: -50 +) !default; + +$body__body-header: () !default; + +body > header { + @include properties($body__body-header--default, $body__body-header); } -/// We rely on source order for mobile-first approach -/// in this case: +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up source order for mobile first approach /// -/// -50 header -/// -40 nav -/// 1 main -/// 50 footer +/// @example scss - Used in `base/_body.scss` by the `body > nav` element +/// body > nav { +/// @include properties($body__body-nav--default, $body__body-nav); +/// } /// -body > header { order: -50; } +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/nav +$body__body-nav--default: ( + order: -40, +) !default; -/// Nav html element. -body > nav { order: -40; } +$body__body-nav: () !default; -/// Main html element of body. -body > main { order: 1; } +body > nav { + @include properties($body__body-nav--default, $body__body-nav); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up source order for mobile first approach +/// - Set up basic properties for the `main` element +/// +/// @example scss - Used in `base/_body.scss` by the `body > main, body > #main` elements +/// body > main { +/// @include properties(body__body-main--default, body__body-main); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/main +$body__body-main--default: ( + order: 1, + overflow: hidden, + background-color: color(background), + flex: 1, + + '@media print': ( + background: transparent, + ), +) !default; -// footer html element of body. -body > footer { order: 50; } +$body__body-main: () !default; + +body > main, +body > #main { + @include properties( $body__body-main--default, $body__body-main ); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up source order for mobile first approach +/// +/// @example scss - Used in `base/_body.scss` by the `body > footer` element +/// body > main { +/// @include properties(body__body-footer--default, body__body-footer); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/footer +$body__body-footer--default: ( + order: 50, +) !default; -/// Main html element. -main { - overflow: hidden; - background-color: color(background); - flex: 1; +$body__body-footer: () !default; - @media print { - background: transparent; - } +body > footer { + @include properties($body__body-footer--default, $body__body-footer ); } diff --git a/core/base/_box-model.scss b/core/base/_box-model.scss index 7d4836ff1..ecf0ead8e 100644 --- a/core/base/_box-model.scss +++ b/core/base/_box-model.scss @@ -2,29 +2,52 @@ //// /// Box model default styles. +/// /// @group base|box-model +/// +/// @type map +/// +/// @see $group__element--default +/// @see $group__element //// -/// Set up a decent box model on the root element. +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up box model for the root element +/// +/// @example scss - Used in `base/_box-model.scss` by the `html` root element +/// html { +/// box-sizing: border-box; +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/html +$box-model__html--default: ( + box-sizing: border-box, +)!default; + +$box-model__html: ()!default; html { - font-size: 62.5%; // 1rem = 10px; - box-sizing: border-box; + @include properties( $box-model__html--default, $box-model__html ); } -/// Make all elements from the DOM inherit from the parent box-sizing -/// Since `*` has a specificity of 0, it does not override the `html` value -/// making all elements inheriting from the root box-sizing value -/// See: https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/ +// --------------------------------------------------------------------------------------------------------------------- +/// - Make all elements from the DOM inherit from the parent box-sizing +/// - Since `*` has a specificity of 0, it does not override the `html` value, +/// making all elements inheriting from the root box-sizing value +/// +/// @example scss - Used in `base/_box-model.scss` by the `*, *::before, *::after` elements +/// *, *::before, *::after { +/// @include properties(box-model__box-sizing--default, box-model__box-sizing); +/// } +/// +/// @link https://css-tricks.com/inheriting-box-sizing-probably-slightly-better-best-practice/ +/// +$box-model__box-sizing--default: ( + box-sizing: inherit, +) !default; -*, *::before, *::after { - box-sizing: inherit; -} +$box-model__box-sizing: ()!default; -/// Set the base body font size. -/// @require {function} em Relative unit function -/// @require {variable} $base-font-size Base font size - -body { - @include font-size($base-font-size, $root-font-size); +*, *::before, *::after { + @include properties($box-model__box-sizing--default, $box-model__box-sizing); } diff --git a/core/base/_buttons.scss b/core/base/_buttons.scss index 784b31fa8..741664107 100644 --- a/core/base/_buttons.scss +++ b/core/base/_buttons.scss @@ -3,104 +3,37 @@ //// /// Button base styles. /// @group base|buttons +/// @group buttons +/// +/// @type map +/// +/// @see $group__element--default +/// @see $group__element //// /// Generic Button Styles. -/// @require {function} color Returns a color from the color map. -/// @require {function} em normalized relative values. -/// @require {mixin} material-shadow adds a shadow. -/// @require {variable} $base-font-family The default base font styles. -/// @require {variable} $base-line-height Base line height setting. -/// @require {variable} $base-transition Base transition setting. -/// @require {variable} $small-spacing Base small space setting. +/// @require button +/// @require $base-button %button__generic { - $_font-family: $base-font-family; - $_line-height: $base-line-height; - $_transition: $base-transition; - $_spacing: $small-spacing; - - @include material-shadow(flat); - - appearance: none; - background-color: color(action); - border: none; - color: color(reverse-text); - cursor: pointer; - display: inline-block; - font-family: $_font-family; - font-size: inherit; - -webkit-font-smoothing: antialiased; - font-weight: inherit; - line-height: $_line-height; - padding: em(6px) em($_spacing) em(7px); - text-align: center; - text-decoration: none; - user-select: none; - vertical-align: middle; - transition: $_transition; - - &:hover, - &:focus, - &:active { - background-color: color(action--active); - color: color(reverse-text--active); - text-decoration: none; - } - - &:disabled, - &.disabled { - background-color: color(action); - color: color(reverse-text); - cursor: not-allowed; - opacity: .5; - - &:hover { - cursor: not-allowed; - } - } + @include button($base-button); } /// Primary Button Styles. -/// @require {function} em normalized relative values. -/// @require {function} color Returns a color from the color map. -/// @require {placeholder} button__generic -/// @require {variable} $base-spacing +/// @require %button__generic +/// @require button +/// @require $primary-button %button__primary { - $_spacing: $base-spacing; - @extend %button__generic; - - background-color: color(action); - color: color(reverse-text); - font-weight: 600; - padding: em(10px) em($_spacing) em(12px); - - @include on-event { - background-color: color(action--active); - color: color(reverse-text); - } + @include button($primary-button); } /// Secondary Button Styles. -/// @require {function} em normalized relative values. -/// @require {function} color Returns a color from the color map. -/// @require {placeholder} button__generic -/// @require {variable} $base-spacing +/// @require %button__generic +/// @require button +/// @require $secondary-button %button__secondary { - $_spacing: $base-spacing; - @extend %button__generic; - background-color: inherit; - border: $base-border; - color: color(text); - font-weight: 600; - padding: em(7px) em($_spacing) em(9px); - - @include on-event { - background-color: inherit; - border-color: color(action); - color: color(action); - } + @include button($secondary-button); } /// Apply all button styles. diff --git a/core/base/_decanter-base.scss b/core/base/_decanter-base.scss index 46420d784..5284c8832 100644 --- a/core/base/_decanter-base.scss +++ b/core/base/_decanter-base.scss @@ -13,12 +13,12 @@ //// @import - 'body', - 'box-model', - 'buttons', - 'fonts', - 'forms', - 'lists', - 'media-elements', - 'tables', - 'typography'; + 'box-model' +, 'body' +, 'typography' +, 'forms' +, 'lists' +, 'tables' +, 'media-elements' +, 'buttons' +; diff --git a/core/base/_documentation.scss b/core/base/_documentation.scss new file mode 100644 index 000000000..97945b28a --- /dev/null +++ b/core/base/_documentation.scss @@ -0,0 +1,132 @@ +@charset "UTF-8"; + +//// +/// Documentation for all Base variable maps +/// +/// @ignore +/// This file is not actually built by the CSS system, it is here to provide top-level documentation for the `base` css scaffold +/// +/// @group base|_documentation +/// +/// @type map +/// +/// @see {mixin} properties +//// + +// --------------------------------------------------------------------------------------------------------------------- +/// # Default Element Map +/// This map generates the default `property`: `value` pairs for a given CSS element. +/// +/// In Decanter, the intended use case for the `base/` `--default` variables is to output a set of normalized HTML properties. +/// +/// To change the output of `base`, modify it's corresponding `group__element` map in your own project, which will be merged with the default map so you don't have to re-declare properties. +/// +/// There may be some cases in which you want to completely override the `group__element--default` map, if that's the case, you should also do this in your own project's variables. +/// +/// **Note:** *Due to the way `key:value` pairs work in SCSS maps, you can only declare one property per map. This means edge cases where you want to output fallbacks for a property should probably be handled in a different way.* +/// +/// **Second Note:** When merging nested maps, the map merge will replace the value of the entire nested map. This is a limitation of Sass's implementation. This means if you want to replace a single property in a :before nested declaration, for example, you'll have to redeclare the entire element in the override map. +/// +/// This pattern applies to all default variable maps in `base/` +/// +/// @example scss - SCSS - Default element map +/// group__element--default: ( +/// property1: value1, +/// property2: value2, +/// property3: value3, +/// // etc... +/// )!default; +/// +/// @example css - CSS - Default Output +/// element { +/// property1: value1; +/// property2: value2; +/// property3: value3; +/// // etc... +/// } +/// +$group__element--default: ( + property1: value1, + property2: value2, + property3: value3, + // etc... +)!default; + +// --------------------------------------------------------------------------------------------------------------------- +/// # Element Map +/// This map generates `property`: `value` overrides for it's corresponding `--default` map. +/// +/// In `base.scss`, the intended use case for this map is to serve as a hook to modify the base styling generated by decanter, so you would declare this variable in your own project before importing `base` +/// +/// You will notice that on the base decanter project, all of these are empty placeholder maps. This is by design. +/// +/// This pattern applies to all variable maps in `base/` +/// +/// @example scss - Default element map +/// group__element--default: ( +/// property1: value1, +/// property2: value2, +/// property3: value3, +/// // etc... +/// )!default; +/// +/// @example scss - Element map +/// $group__element: ( +/// property1: my-value1, +/// property3: null, // By explicitly declaring a +/// // null value in the merged map, +/// // we can suppress this property +/// my-new-property: my-new-value, +/// // etc... +/// } +/// +/// @example scss - Merged SCSS Output +/// element { +/// property1: my-value1; +/// property2: value2; +/// my-new-property: my-new-value; +/// // etc... +/// } +/// +$group__element: ( + property1: my-value1, + property3: null, + my-new-property: my-new-value, + // ... +)!default; + +/// `CSS Elements` in `base` are generated via the `properties()` mixin, which merges the above maps and outputs the corresponding css +/// +/// @example scss - In use throughout `base/`: +/// element { +/// @include properties($group__element--default, $group__element); +/// } +/// +/// @require {mixin} properties> +%element { + @include properties($group__element--default, $group__element); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// - Base styles for the `eelement` element +/// +/// @example scss - Used in `base/_lists.scss` by the `eelement` element +/// eelement { +/// @include properties($lists__eelement--default, $typography__eelement); +/// } +/// +/// @require -- +/// +/// @todo -- +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/eelement +/// + +$lists__eelement--default: () !default; + +$lists__eelement: () !default; + +eelement { + @include properties($lists__eelement--default, $lists__eelement); +} diff --git a/core/base/_fonts.scss b/core/base/_fonts.scss deleted file mode 100644 index d463b538f..000000000 --- a/core/base/_fonts.scss +++ /dev/null @@ -1,9 +0,0 @@ -@charset "UTF-8"; -//// -/// Base font styles. -/// This file contains all @font-face declarations, if any. -/// @group base|fonts -//// - -//// Load the font-face declarations. -@include load-fonts($decanter-default-fonts); diff --git a/core/base/_forms.scss b/core/base/_forms.scss index c695de551..0bb0c3f33 100644 --- a/core/base/_forms.scss +++ b/core/base/_forms.scss @@ -2,119 +2,266 @@ //// /// Form base styles. /// @group base|forms +/// +/// @type map +/// @see $group__element--default +/// @see $group__element //// -/// Fieldset defaults. +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `fieldset` element +/// +/// @example scss - Used in `base/_forms.scss` by the `fieldset` element +/// fieldset { +/// @include properties($forms__fieldset--default, $typography__fieldset); +/// } +/// +/// @require -- +/// +/// @todo -- +/// +/// link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/fieldset +/// +$forms__fieldset--default: ( +background-color: transparent, +border: 0, +margin: 0, +padding: 0, +) !default; + +$forms__fieldset: () !default; + fieldset { - background-color: transparent; - border: 0; - margin: 0; - padding: 0; + @include properties($forms__fieldset--default, $forms__fieldset); } -/// Legend defaults. -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `legend` element +/// +/// @example scss - Used in `base/_forms.scss` by the `legend` element +/// legend { +/// @include properties($forms__legend--default, $typography__legend); +/// } +/// +/// @require $small-spacing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/legend +/// +$forms__legend--default: ( + font-weight: 600, + margin-bottom: $small-spacing / 2, + padding: 0, +) !default; + +$forms__legend: () !default; + legend { - $_spacing: $small-spacing; - font-weight: 600; - margin-bottom: $_spacing / 2; - padding: 0; + @include properties($forms__legend--default, $forms__legend); } -/// Label defaults. -/// @require {variable} $small-spacing + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// - Base styles for the `label` element +/// +/// @example scss - Used in `base/_forms.scss` by the `label` element +/// label { +/// @include properties($forms__label--default, $typography__label); +/// } +/// +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/label +/// @require $small-spacing +/// +$forms__label--default: ( + display: block, + font-weight: 600, + margin-bottom: $small-spacing / 2, +) !default; + +$forms__label: () !default; + label { - $_spacing: $small-spacing; - display: block; - font-weight: 600; - margin-bottom: $_spacing / 2; + @include properties($forms__label--default, $forms__label); } -/// Input defaults. -/// @require {variable} $base-font-family +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// - Base styles for the `input`, `select` and `textarea` elements +/// +/// @example scss - Used in `base/_forms.scss` by the `input` element +/// input, +/// select, +/// textarea { +/// @include properties($forms__input--default, $typography__input); +/// } +/// +/// @require $base-font-family +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea +/// +$forms__input--default: ( + display: block, + font-family: $base-font-family, +) !default; + +$forms__input: () !default; + input, select, textarea { - $_font-family: $base-font-family; - display: block; - font-family: $_font-family; + @include properties($forms__input--default, $forms__input); } -/// All Text Input defaults. +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `#{}all-text-inputs}` element +/// +/// @example scss - Used in `base/_forms.scss` by all text inputs element +/// #{$all-text-inputs} { +/// @include properties($forms__all-text-inputs--default, $typography__all-text-inputs); +/// } +/// /// @require bourbon -/// @require {function} color -/// @require {mixin} on-event -/// @require {variable} $base-border -/// @require {variable} $base-border-radius -/// @require {variable} $form-box-shadow -/// @require {variable} $base-spacing -/// @require {variable} $base-duration -/// @require {variable} $base-timing -/// @group base +/// @require color +/// @require hokus on-event +/// @require $base-border +/// @require $base-border-radius +/// @require $form-box-shadow +/// @require $base-spacing +/// @require $base-duration +/// @require $base-timing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input +/// +$forms__all-text-inputs--default: ( + appearance: none, + background-color: color(background), + border: $base-border, + border-radius: $base-border-radius, + box-shadow: $form-box-shadow, + box-sizing: border-box, + margin-bottom: $base-spacing, + padding: $base-spacing / 3, + transition: border-color $base-duration $base-timing, + width: 100%, + + #{$hocus}: ( + border-color: shade(color(border), 20%), + ), + '&:disabled': ( + background-color: shade(color(background), 5%), + cursor: not-allowed, + + '&:hover': ( + border: $base-border, + ), + ), + + '&::placeholder': ( + color: tint(color(text), 40%), + ), +) !default; + +$forms__all-text-inputs: () !default; + #{$all-text-inputs} { - $_border: $base-border; - $_border-radius: $base-border-radius; - $_box-shadow: $form-box-shadow; - $_spacing: $base-spacing; - $_small-spacing: $base-spacing; - $_duration: $base-duration; - $_timing: $base-timing; - - appearance: none; - background-color: color(background); - border: $_border; - border-radius: $_border-radius; - box-shadow: $_box-shadow; - box-sizing: border-box; - margin-bottom: $_small-spacing; - padding: $_spacing / 3; - transition: border-color $_duration $_timing; - width: 100%; - - @include on-event { - border-color: shade(color(border), 20%); - } - - &:disabled { - background-color: shade(color(background), 5%); - cursor: not-allowed; - - &:hover { - border: $_border; - } - } - - &::placeholder { - color: tint(color(text), 40%); - } + @include properties($forms__all-text-inputs--default, $forms__all-text-inputs); } -/// Text area styles. +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `textarea` element +/// +/// @example scss - Used in `base/_forms.scss` by the `textarea` element +/// textarea { +/// @include properties($forms__textarea--default, $typography__textarea); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea +/// + +$forms__textarea--default: ( + resize: vertical, +) !default; + +$forms__textarea: () !default; + textarea { - resize: vertical; + @include properties($forms__textarea--default, $forms__textarea); } -/// Checkboxes and radios -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `[type="checkbox"]` and `[type="radio"]` input elements +/// +/// @example scss - Used in `base/_forms.scss` by the `[type="checkbox"]` and `[type="radio"]` elements +/// [type="checkbox"], +/// [type="radio"] { +/// +/// @include properties($forms__radiocheck--default, $typography__radiocheck); +/// } +/// +/// @require $small-spacing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input +/// + +$forms__radiocheck--default: ( + display: inline, + margin-right: $small-spacing / 2, +) !default; + +$forms__radiocheck: () !default; + [type="checkbox"], [type="radio"] { - $_spacing: $small-spacing; - display: inline; - margin-right: $_spacing / 2; + @include properties($forms__radiocheck--default, $forms__radiocheck); } -/// File fields. -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `[type="file"]` input element +/// +/// @example scss - Used in `base/_forms.scss` by the `[type="file"]` element +/// [type="file"] { +/// @include properties($forms__input-file--default, $typography__input-file); +/// } +/// +/// @require $small-spacing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input +/// + +$forms__input-file--default: ( + margin-bottom: $small-spacing, + width: 100%, +) !default; + +$forms__input-file: () !default; + [type="file"] { - $_spacing: $small-spacing; - margin-bottom: $_spacing; - width: 100%; + @include properties($forms__input-file--default, $forms__input-file); } -/// Select styles. -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `select` element +/// +/// @example scss - Used in `base/_forms.scss` by the `select` element +/// select { +/// @include properties($forms__select--default, $typography__select); +/// } +/// +/// @require $small-spacing +/// +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/select +/// +$forms__select--default: ( + margin-bottom: $small-spacing, + width: 100%, +) !default; + +$forms__select: () !default; + select { - $_spacing: $small-spacing; - margin-bottom: $_spacing; - width: 100%; + @include properties($forms__select--default, $forms__select); } diff --git a/core/base/_lists.scss b/core/base/_lists.scss index f2f49f989..bce0a1e20 100644 --- a/core/base/_lists.scss +++ b/core/base/_lists.scss @@ -5,92 +5,231 @@ //// -/// List classes. +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for `plain` lists +/// +/// @example scss - Used in `base/_lists.scss` by the `.plain` class +/// ul.plain, +/// ol.plain, +/// dl.plain, +/// dt.plain { +/// @include properties($lists__plain--default, $typography__plain); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl +/// + +$lists__plain--default: ( + font-weight: normal, + list-style-type: none, + margin: 0, + padding: 0, +) !default; + +$lists__plain: () !default; + ul.plain, -ol.plain { - list-style-type: none; - margin: 0; - padding: 0; +ol.plain, +dl.plain, +dt.plain, +%plain { + @include properties($lists__plain--default, $lists__plain); } -/// plain -dl.plain { - margin: 0; -} -/// plain -dt.plain { - font-weight: 600; - margin: 0; -} -/// plain -dd.plain { - margin: 0; -} -/// List styles. -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `ul` and `ol` elements +/// +/// @example scss - Used in `base/_lists.scss` by the `ul` and `ol` elements +/// ul, +/// ol { +/// @include properties($lists__lists--default, $typography__lists); +/// } +/// +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/li +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol +/// + +$lists__lists--default: ( + margin: 0 0 modular-scale(0) modular-scale(1), + padding-left: 0, + li: ( + margin-bottom: modular-scale(-5), + ), +) !default; + +$lists__lists: () !default; + ul, ol { - margin: 0 0 modular-scale(0) modular-scale(1); - padding-left: 0; - li { - margin-bottom: modular-scale(-5); - } + @include properties($lists__lists--default, $lists__lists); } -/// uls + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `ul` element +/// +/// @example scss - Used in `base/_lists.scss` by the `ul` element +/// ul { +/// @include properties($lists__ul--default, $typography__ul); +/// } +/// +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ul +/// + +$lists__ul--default: ( + list-style: disc, + ul: ( + list-style: circle, + ul: ( + list-style: square, + ), + ), +) !default; + +$lists__ul: () !default; + ul { - list-style: disc; - ul { - list-style: circle; - ul { - list-style: square; - } - } + @include properties($lists__ul--default, $lists__ul); } -/// Ordered List styles -/// @require {function} em +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `ol` element +/// +/// @example scss - Used in `base/_lists.scss` by the `ol` element +/// ol { +/// @include properties($lists__ol--default, $typography__ol); +/// } +/// +/// @require em +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol +/// + +$lists__ol--default: ( + list-style: decimal, + + li: ( + padding-left: em(4px), + margin-left: em(-4px), + ), + + ol: ( + list-style: upper-alpha, + ol: ( + list-style: lower-roman, + ol: ( + list-style: lower-alpha, + ), + ), + ), +) !default; + +$lists__ol: () !default; + ol { - list-style: decimal; - - li { - padding-left: em(4px); - margin-left: em(-4px); - } - - ol { - list-style: upper-alpha; - ol { - list-style: lower-roman; - ol { - list-style: lower-alpha; - } - } - } + @include properties($lists__ol--default, $lists__ol); } -/// Nested list styles. -/// @require modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for nested-lists +/// +/// @example scss - Used in `base/_lists.scss` by the `li > ul` and `li > ol` elements +/// li > ul, +/// li > ol { +/// @include properties($lists__nested-lists--default, $typography__nested-lists); +/// } +/// + +$lists__nested-lists--default: ( + margin-top: modular-scale(-5), + margin-bottom: modular-scale(-5), + margin-left: modular-scale(1), +) !default; + +$lists__nested-lists: () !default; + li > ul, li > ol { - margin-top: modular-scale(-5); - margin-bottom: modular-scale(-5); - margin-left: modular-scale(1); + @include properties($lists__nested-lists--default, $lists__nested-lists); } -/// Definition list styles. -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `dl` element +/// +/// @example scss - Used in `base/_lists.scss` by the `dl` element +/// dl { +/// @include properties($lists__dl--default, $typography__dl); +/// } +/// +/// todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dl +/// + +$lists__dl--default: ( + margin: 0 0 modular-scale(-5), +) !default; + +$lists__dl: () !default; + dl { - margin: 0 0 modular-scale(-5); + @include properties($lists__dl--default, $lists__dl); } -/// dt + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// - Base styles for the `dt` element +/// +/// @example scss - Used in `base/_lists.scss` by the `dt` element +/// dt { +/// @include properties($lists__dt--default, $typography__dt); +/// } +/// +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dt +/// + +$lists__dt--default: ( + font-weight: 600, +) !default; + +$lists__dt: () !default; + dt { - font-weight: 600; + @include properties($lists__dt--default, $lists__dt); } -/// DD list styles. -/// @require {variable} $base-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// - Base styles for the `dd` element +/// +/// @example scss - Used in `base/_lists.scss` by the `dd` element +/// dd { +/// @include properties($lists__dd--default, $typography__dd); +/// } +/// +/// @require $base-spacing +/// +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dd +/// + +$lists__dd--default: ( + margin: 0 0 $base-spacing, +) !default; + +$lists__dd: () !default; + dd { - margin: 0 0 $base-spacing; + @include properties($lists__dd--default, $lists__dd); } diff --git a/core/base/_media-elements.scss b/core/base/_media-elements.scss index 7d365e919..ef4b8a2cb 100644 --- a/core/base/_media-elements.scss +++ b/core/base/_media-elements.scss @@ -2,16 +2,43 @@ //// /// Meida base styles. -/// @group base|media +/// @group base|media-elements +/// +/// @type map +/// @see $group__element--default +/// @see $group__element //// // @import '../utilities/settings/settings'; +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `img`, `picture`, `figure` elements +/// +/// @example scss - Used in `base/_media-elements.scss` by the `img`, `picture`, `figure` elements +/// img, +/// picture, +/// figure { +/// @include properties($media-elements__images--default, $typography__images); +/// } +/// +/// @todo implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/image +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure +/// + +$media-elements__images--default: ( + width: auto, + max-width: 100%, + height: auto, + margin: 0, +) !default; + +$media-elements__images: () !default; + img, picture, figure { - width: auto; - max-width: 100%; - height: auto; - margin: 0; + @include properties($media-elements__images--default, $media-elements__images); } diff --git a/core/base/_tables.scss b/core/base/_tables.scss index 59f3a2ddc..59736b672 100644 --- a/core/base/_tables.scss +++ b/core/base/_tables.scss @@ -2,40 +2,115 @@ //// /// Media base styles. /// @group base|tables +/// +/// @type map +/// @see $group__element--default +/// @see $group__element //// //@import '../utilities/settings/settings'; -/// Table styles. -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `table` element +/// +/// @example scss - Used in `base/_tables.scss` by the `table` element +/// table { +/// @include properties($tables__table--default, $typography__table); +/// } +/// +/// @require $small-spacing +/// +/// @todo - Implement vertical rhytm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/table +/// +$tables__table--default: ( + border-collapse: collapse, + margin: $small-spacing 0, + table-layout: fixed, + width: 100%, +) !default; + +$tables__table: () !default; + table { - border-collapse: collapse; - margin: $small-spacing 0; - table-layout: fixed; - width: 100%; + @include properties($tables__table--default, $tables__table); } -/// TH Styles. -/// @require {function} shade -/// @require {function} color -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `th` element +/// +/// @example scss - Used in `base/_tables.scss` by the `th` element +/// th { +/// @include properties($tables__th--default, $typography__th); +/// } +/// +/// @require bourbon +/// @require color +/// @require $small-spacing +/// +/// @link http://neat.bourbon.io Bourbon documentation +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th +/// +$tables__th--default: ( + border-bottom: 1px solid shade(color(border), 25%), + font-weight: 600, + padding: $small-spacing 0, + text-align: left, +) !default; + +$tables__th: () !default; + th { - border-bottom: 1px solid shade(color(border), 25%); - font-weight: 600; - padding: $small-spacing 0; - text-align: left; + @include properties($tables__th--default, $tables__th); } -/// TD styles. -/// @require {variable} $base-border -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `td` element +/// +/// @example scss - Used in `base/_tables.scss` by the `td` element +/// td { +/// @include properties($tables__td--default, $typography__td); +/// } +/// +/// @require $base-border +/// @require $small-spacing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td +/// +$tables__td--default: ( + border-bottom: $base-border, + padding: $small-spacing 0, +) !default; + +$tables__td: () !default; + td { - border-bottom: $base-border; - padding: $small-spacing 0; + @include properties($tables__td--default, $tables__td); } +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles shared by the `tr`, `td`, `th` elements +/// +/// @example scss - Used in `base/_tables.scss` by the `tr`, `td`, `th` elements +/// tr, +/// td, +/// th { +/// @include properties($tables__tr-td-th--default, $typography__tr-td-th); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tr +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th +/// +$tables__tr-td-th--default: ( + vertical-align: middle, +) !default; + +$tables__tr-td-th: () !default; + tr, td, th { - vertical-align: middle; + @include properties($tables__tr-td-th--default, $tables__tr-td-th); } diff --git a/core/base/_typography.scss b/core/base/_typography.scss index 1de9a8486..5fe05ad82 100644 --- a/core/base/_typography.scss +++ b/core/base/_typography.scss @@ -1,198 +1,657 @@ @charset "UTF-8"; + //// /// This file contains Site-wide typography base styles. /// @group base|typography +/// +/// @type map +/// @see $group__element--default +/// @see $group__element //// -// @import '../utilities/settings/settings'; -/// Body font styles. -/// @require {function} color -/// @require {function} font-size -/// @require {variable} $base-font-family -/// @require {variable} $base-line-height +// --------------------------------------------------------------------------------------------------------------------- +/// - Set the root body font size +/// - Since most browsers default their `normal` font size to 16px, +/// we use that as the basis for our percentage calculation, using +/// the declared `$root-font-size` variable. +/// +/// +/// @example scss - Used in `base/_typography.scss` by the `html` root element +/// html { +/// @include properties($typography__html--default, $typography__html); +/// } +/// +/// @require {variable} $root-font-size Root font size +/// +$typography__html--default: ( + font-size: percentage($root-font-size/16px), +) !default; + +$typography__html: () !default; + +html { + @include properties($typography__html--default, $typography__html); +} + + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for `body` (line-height, font-family, font-size) +/// +/// @example scss - Used in `base/_typography.scss` by the `body` element +/// body { +/// @include properties($typography__body--default, $typography__body); +/// } +/// +/// @require em() +/// @require $base-font-size +/// @require $root-font-size +/// @require $base-font-family +/// @require $base-line-height +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/body +$typography__body--default: ( + line-height: $base-line-height, + font-family: $base-font-family, + font-size: em($base-font-size, $root-font-size), +) !default; + +$typography__body: () !default; + body { - color: color(text); - font-family: $base-font-family; - @include font-size($base-font-size, $root-font-size); - line-height: $base-line-height; + @include properties($typography__body--default, $typography__body); } -/// Heading base styles. -/// @require {variable} $heading-font-family -/// @require {variable} $heading-line-height -/// @require {variable} $small-spacing + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for all heading levles +/// +/// @example scss - Used in `base/_typography.scss` by the `#{all-headlines}` variable +/// #{$all-headlines} { +/// @include properties($typography__headlines--default, $typography__headlines); +/// } +/// +/// @require $all-headlines +/// @require $heading-font-family +/// @require $heading-line-height +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__headlines--default: ( + font-family: $heading-font-family, + font-weight: 700, + line-height: $heading-line-height, + margin: modular-scale(-1) 0 modular-scale(-3), +) !default; + +$typography__headlines: () !default; + #{$all-headlines} { - font-family: $heading-font-family; - line-height: $heading-line-height; - margin: modular-scale(-1) 0 modular-scale(-3); - font-weight: 700; + @include properties($typography__headlines--default, $typography__headlines); } -/// @require {function} font-size -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 1 +/// +/// @example scss - Used in `base/_typography.scss` by the `h1` element +/// h1 { +/// @include properties($typography__h1--default, $typography__h1); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h1--default: ( + font-size: modular-scale(5), +) !default; + +$typography__h1:() !default; + +h1 { + @include properties($typography__h1--default, $typography__h1); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 2 +/// +/// @example scss - Used in `base/_typography.scss` by the `h2` element +/// h2 { +/// @include properties($typography__h2--default, $typography__h2); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h2--default: ( + font-size: modular-scale(4), +) !default; + +$typography__h2:() !default; + h2 { - @include font-size(modular-scale(4)); + @include properties($typography__h2--default, $typography__h2); } -/// @require {function} font-size -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 3 +/// +/// @example scss - Used in `base/_typography.scss` by the `h3` element +/// h3 { +/// @include properties($typography__h3--default, $typography__h3); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h3--default: ( + font-size: modular-scale(3), +) !default; + +$typography__h3:() !default; + h3 { - @include font-size(modular-scale(3)); + @include properties($typography__h2--default, $typography__h2); } -/// @require {function} font-size -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 4 +/// +/// @example scss - Used in `base/_typography.scss` by the `h4` element +/// h4 { +/// @include properties($typography__h4--default, $typography__h4); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h4--default: ( + font-size: modular-scale(2), +) !default; + +$typography__h4:() !default; + h4 { - @include font-size(modular-scale(2)); + @include properties($typography__h4--default, $typography__h4); } -/// @require {function} font-size -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 5 +/// +/// @example scss - Used in `base/_typography.scss` by the `h5` element +/// h5 { +/// @include properties($typography__h5--default, $typography__h5); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h5--default: ( + font-size: modular-scale(2), +) !default; + +$typography__h5:() !default; + h5 { - @include font-size(modular-scale(1)); + @include properties($typography__h5--default, $typography__h5); } -/// @require {function} font-size -/// @require {function} modular-scale +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for Heading 6 +/// +/// @example scss - Used in `base/_typography.scss` by the `h6` element +/// h6 { +/// @include properties($typography__h6--default, $typography__h6); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements +$typography__h6--default: ( + font-size: modular-scale(2), +) !default; + +$typography__h6:() !default; + h6 { - @include font-size(modular-scale(0)); + @include properties($typography__h6--default, $typography__h6); } -/// @require {variable} $small-spacing +// --------------------------------------------------------------------------------------------------------------------- +/// - Set up base typography for paragraphs +/// +/// @example scss - Used in `base/_typography.scss` by the `p` element +/// p { +/// @include properties($typography__p--default, $typography__p); +/// } +/// +/// @require modular-scale() +/// @todo +/// - Implement vertical rhythm +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p +/// +$typography__p--default: ( + margin: 0 0 modular-scale(1), +) !default; + +$typography__p:() !default; + p { - margin: 0 0 modular-scale(1); + @include properties($typography__p--default, $typography__p); } +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for emphasis elements +/// +/// @example scss - Used in `base/_typography.scss` by the `dfn, cite, em, i` elements +/// dfn, cite, em, i { +/// @include properties($typography__emphasis--default, $typography__emphasis); +/// } +/// +/// @require modular-scale() +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/cite +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/dfn +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/em +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/i +$typography__emphasis--default: ( + font-style: italic, +) !default; + +$typography__emphasis:() !default; + dfn, cite, em, i { - font-style: italic; + @include properties($typography__emphasis--default, $typography__emphasis); } -/// @require {function} modular-scale -// see https://css-tricks.com/almanac/properties/q/quotes/ -blockquote { - margin: 0 modular-scale(2); - quotes: "\201c" "\201d" "\2018" "\2019"; +// --------------------------------------------------------------------------------------------------------------------- +/// - Base quote styles and spacing for blockquotes +/// +/// @example scss - Used in `base/_typography.scss` by the `blockquote` element +/// blockquote { +/// @include properties($typography__blockquote--default, $typography__blockquote); +/// } +/// +/// @require modular-scale() +/// @link https://css-tricks.com/almanac/properties/q/quotes/ +/// @todo +/// - Implement vertical rhythm +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/blockquote +/// +$typography__blockquote--default: ( + margin: 0 modular-scale(2), + quotes: '"\201c" "\201d" "\2018" "\2019"', + + '&::before': ( + content: open-quote, + ), + '&::after': ( + content: close-quote, + ), +) !default; - &::before { - content: open-quote; - } - &::after { - content: close-quote; - } +$typography__blockquote:() !default; + +blockquote { + @include properties($typography__blockquote--default, $typography__blockquote); } -// see https://css-tricks.com/almanac/properties/q/quotes/ -q { - margin: 0; - quotes: "\201c" "\201d" "\2018" "\2019"; +// --------------------------------------------------------------------------------------------------------------------- +/// - Base typography for quotations +/// +/// @example scss - Used in `base/_typography.scss` by the `q` element +/// q { +/// @include properties($typography__q--default, $typography__q); +/// } +/// +/// @require modular-scale() +/// @link https://css-tricks.com/almanac/properties/q/quotes/ +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/q +/// +$typography__q--default: ( + quotes: '"\201c" "\201d" "\2018" "\2019"', + + '&::before': ( + content: open-quote, + ), + '&::after': ( + content: close-quote, + ), +) !default; + +$typography__q:() !default; - &::before { - content: open-quote; - } - &::after { - content: close-quote; - } +q { + @include properties($typography__q--default, $typography__q); } -/// @require {variable} $base-spacing + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base typography for address elements +/// +/// @example scss - Used in `base/_typography.scss` by the `address` element +/// address { +/// @include properties($typography__address--default, $typography__address); +/// } +/// +/// @require modular-scale() +/// +/// @todo +/// - Implement vertical rhythm +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/address +/// +$typography__address--default: ( + margin: 0 0 modular-scale(2), +) !default; + +$typography__address:() !default; + address { - margin: 0 0 modular-scale(2); + @include properties($typography__address--default, $typography__address); } -/// @require {function} shade -/// @require {function} color -/// @require {variable} $monospace-font-family -/// @require {variable} $base-line-height +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for preformatted text +/// +/// @example scss - Used in `base/_typography.scss` by the `pre` element +/// pre { +/// @include properties($typography__pre--default, $typography__pre); +/// } +/// +/// @require rgba +/// @require color +/// @require $monospace-font-family +/// @require $base-line-height +/// @require modular-scale +/// @require em +/// @todo +/// - Implement vertical rhythm +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/pre +/// +$typography__pre--default: ( + background: rgba(color(light-grey), .6), + font-family: $monospace-font-family, + font-size: em(16px), + line-height: $base-line-height, + margin-bottom: modular-scale(2), + max-width: 100%, + overflow: auto, + padding: 1.6em, + border: 1px solid color(grey), + white-space: pre-wrap, +) !default; + +$typography__pre: () !default; + pre { - background: rgba(color(light-grey), .6); - font-family: $monospace-font-family; - @include font-size(16px); - line-height: $base-line-height; - margin-bottom: modular-scale(2); - max-width: 100%; - overflow: auto; - padding: 1.6em; - border: 1px solid color(grey); - white-space: pre-wrap; + @include properties($typography__pre--default, $typography__pre); } + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for phrase tags +/// +/// @example scss - Used in `base/_typography.scss` by the `code`, `kbd`, `tt`, `var`, `samp` elements +/// code, kbd, tt, var, samp { +/// @include properties($typography__code--default, $typography__code); +/// } +/// /// @require {variable} $monospace-font-family /// @require {function} font-size -code, kbd, tt, var { - font-family: $monospace-font-family; - @include font-size(16px); - padding: modular-scale(-10) modular-scale(-5); - position: relative; - background-color: rgba(color(light-grey), .6); - border: 1px solid color(grey); +/// *Note:* the HTML tag `tt` (teletype) was deprecated in HTML 5. +/// - for computer code, consider the `code` element; +/// - For keyboard input, consider the `kbd` element; +/// - for variables, consider the `var` element; +/// - and for computer output, consider the `samp` element +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/code +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/kbd +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/var +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp +/// +$typography__code--default: ( + font-family: $monospace-font-family, + font-size: em(16px), + padding: modular-scale(-10) modular-scale(-5), + position: relative, + background-color: rgba(color(light-grey), .6), + border: 1px solid color(grey), +) !default; + +$typography__code: () !default; + +code, kbd, var, samp { + @include properties($typography__code--default, $typography__code); } -/// @require {function} color +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styling for abbreviation and acronym tags +/// +/// @example scss - Used in `base/_typography.scss` by the `abbr`, `acronym` elements +/// base, acronym { +/// @include properties($typography__abbr--default, $typography__abbr); +/// } +/// +/// @require color +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr +/// +$typography__abbr--default: ( + border-bottom: 1px dotted color(border), + cursor: help, +) !default; + +$typography__abbr: () !default; + abbr, acronym { - border-bottom: 1px dotted color(border); - cursor: help; + @include properties($typography__abbr--default, $typography__abbr); } +// --------------------------------------------------------------------------------------------------------------------- +/// - Shared styling for document markup (insert, delete, mark). +/// +/// @example scss - Used in `base/_typography.scss` by the `mark`, `ins`, `del` elements +/// mark, ins, del { +/// @include properties($typography__edits--default, $typography__edits); +/// } +/// +$typography__edits--default: ( + padding: 0 .25em .15em, +) !default; + +$typography__edits: () !default; + mark, ins, del { - padding: 0 .25em .15em + @include properties($typography__edits--default, $typography__edits); } -/// @require {function} color +// --------------------------------------------------------------------------------------------------------------------- +/// - Base documentation cut & paste template. +/// +/// @example scss - Used in `base/_typography.scss` by the `del` element +/// del { +/// @include properties($typography__del--default, $typography__del); +/// } +/// +/// @require color +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/del +/// +$typography__del--default: ( + color: color(text), + background: color(light-red), + text-decoration: line-through, + text-decoration-color: color(red), +) !default; + +$typography__del: () !default; + del { - color: color(text); - background: color(light-red); - text-decoration: line-through; - text-decoration-color: color(light-red); + @include properties($typography__del--default, $typography__del); } -/// @require {function} color +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `ins` element +/// +/// @example scss - Used in `base/_typography.scss` by the `ins` ins +/// ins { +/// @include properties($typography__ins--default, $typography__ins); +/// } +/// +/// @require color +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/ins/ins +/// + +$typography__ins--default: ( + color: color(text), + background: color(light-green), + text-decoration: none, +) !default; + +$typography__ins: () !default; + ins { - color: color(text); - background: color(light-green); - text-decoration: none; + @include properties($typography__ins--default, $typography__ins); } -/// @require {function} color +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `mark` element +/// +/// @example scss - Used in `base/_typography.scss` by the `mark` mark +/// mark { +/// @include properties($typography__mark--default, $typography__mark); +/// } +/// +/// @require color +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/mark +/// +$typography__mark--default: ( + color: color(text), + background: color(light-yellow), + text-decoration: none, +) !default; + +$typography__mark: () !default; + mark { - color: color(text); - background: color(light-yellow); - text-decoration: none; + @include properties($typography__mark--default, $typography__mark); } -/// @require {function} font-size -/// @require {function} modular-scale -/// @require {variable} $ratio -small, -.small-text { - @include font-size(modular-scale(-1, $ratio: 1.125)); +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `small` and `.text-text` elements +/// +/// @example scss - Used in `base/_typography.scss` by the `small' and `.small-text` elements +/// text, .small-text { +/// @include properties($typography__small-text--default, $typography__small-text); +/// } +/// +/// @require modular-scale +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/small +$typography__small-text--default: ( + font-size: modular-scale(-1, $ratio: 1.125), +) !default; + +$typography__small-text: () !default; + +small, .small-text { + @include properties($typography__small-text--default, $typography__small-text); } -/// @require {function} font-size -/// @require {function} modular-scale -big, + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `.large-text` element +/// +/// **Note**: *The `big` element has been deprecated from the HTML spec. Use the `.large-text` class instead.* +/// +/// @example scss - Used in `base/_typography.scss` by the `.large-text` selector +/// .large-text { +/// @include properties($typography__large-text--default, $typography__large-text); +/// } +/// +/// @require modular-scale +/// @deprecated +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/big +/// +$typography__large-text--default: ( + font-size: modular-scale(1), +) !default; + +$typography__large-text: () !default; + .large-text { - @include font-size(modular-scale(1)); + @include properties($typography__large-text--default, $typography__large-text); } -/// @require {function} color -/// @require {mixin} on-event -a { - color: color(action); - text-decoration: none; +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `hr` element +/// +/// @example scss - Used in `base/_typography.scss` by the `hr` element +/// hr { +/// @include properties($typography__hr--default, $typography__hr); +/// } +/// +/// @require $base-border +/// @require $base-spacing +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/hr +/// +/// @todo +/// - Implement vertical rhythm +$typography__hr--default: ( + border-top: 0, + border-right: 0, + border-bottom: $base-border, + border-left: 0, + margin: modular-scale(1) 0, +) !default; - @include on-event { - color: color(action-active); - text-decoration: underline; - } -} +$typography__hr: () !default; -// @require {variable} $base-border -// @require {variable} $base-spacing hr { - border-top: 0; - border-right: 0; - border-bottom: $base-border; - border-left: 0; - margin: modular-scale(1) 0; + @include properties($typography__hr--default, $typography__hr); +} + +// --------------------------------------------------------------------------------------------------------------------- +/// - Base styles for the `a` element +/// +/// @example scss - Used in `base/_typography.scss` by the `a` element +/// a { +/// @include properties($typography__a--default, $typography__a); +/// } +/// +/// @require color +/// @require $hocus +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/a +/// +$typography__a--default: ( + color: color(action), + text-decoration: none, + + #{$hocus}: ( + color: color(action-active), + text-decoration: underline, + ), +) !default; + +$typography__a: () !default; + +a { + @include properties($typography__a--default, $typography__a); } diff --git a/core/components/breakpoint-helper/_breakpoint-helper.scss b/core/components/breakpoint-helper/_breakpoint-helper.scss index 817067bc5..0f39da1fa 100644 --- a/core/components/breakpoint-helper/_breakpoint-helper.scss +++ b/core/components/breakpoint-helper/_breakpoint-helper.scss @@ -14,7 +14,7 @@ $breakpoint-helper-map: ( @mixin breakpoint-helper($selector: '#breakpoint-helper', $map: $breakpoint-helper-map ) { #{$selector} { - @include material-shadow(flat); + box-shadow: material-shadow(flat); background-color: transparentize(color(dark-grey), .2); border-radius: $base-border-radius; border-top-right-radius: 0; @@ -32,8 +32,8 @@ $breakpoint-helper-map: ( white-space: nowrap; z-index: 9999; - @include on-event { - @include material-shadow(medium); + #{$hocus} { + box-shadow: material-shadow(medium); right: 0; overflow: hidden; font-size: .75em; diff --git a/core/components/helpers/_helpers.scss b/core/components/helpers/_helpers.scss index e945631fb..8a4be3fb0 100644 --- a/core/components/helpers/_helpers.scss +++ b/core/components/helpers/_helpers.scss @@ -6,8 +6,8 @@ } -/// Helper classes -/// These all have corresponding placeholders in utilities/placeholders. +// Helper classes +// These all have corresponding placeholders in utilities/placeholders. .sr-only-text { @extend %hide-text; diff --git a/core/utilities/functions/_color.scss b/core/utilities/functions/_color.scss index 0a843000c..848918011 100644 --- a/core/utilities/functions/_color.scss +++ b/core/utilities/functions/_color.scss @@ -1,13 +1,12 @@ @charset 'UTF-8'; //// -/// File comment here +/// Color function +/// @group functions //// /// Return a color from the color map. /// -/// @group core functions -/// /// @name color /// /// @arg {color} color [null] - The color returned by the function diff --git a/core/utilities/functions/_decanter-functions.scss b/core/utilities/functions/_decanter-functions.scss index 08f79cb46..92ace31b6 100644 --- a/core/utilities/functions/_decanter-functions.scss +++ b/core/utilities/functions/_decanter-functions.scss @@ -5,9 +5,12 @@ //// @import -'color' -, 'unitconversion' + 'unitconversion' +, 'color' , 'fonts/check-loaded-font' , 'fonts/log-loaded-font' , 'layout/set-container-padding' -, 'layout/adjust-container-margin'; +, 'layout/adjust-container-margin' +, 'material-shadow' +, 'smart-merge' +; diff --git a/core/utilities/functions/_material-shadow.scss b/core/utilities/functions/_material-shadow.scss new file mode 100644 index 000000000..071d24b6a --- /dev/null +++ b/core/utilities/functions/_material-shadow.scss @@ -0,0 +1,49 @@ +//// +/// Material Shadow +/// @group functions +/// @author Kevin Garcia +//// + +/// Returns a material-design style shadow. +/// +/// May be flat, shallow, medium, or deep, or a number between 1-12 +/// +/// @param {keyword (flat|shallow|medium|deep) | number(unitless, 1-12)} Depth - How deep the shadow appears to be. +/// +/// @example - scss SCSS +/// .element { +/// box-shadow: material-shadow(shallow) +/// } +/// +/// @example - css CSS +/// .element { +/// box-shadow: 0px 0px 10px rgba(0, 0, 0, 0.15), 0px 3px 3px rgba(0, 0, 0, 0.15); +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/box-shadow +/// @link http://sass-lang.com/documentation/Sass/Script/Functions.html +/// +/// @ignore •Note• the `rgba`, `round`, `floor` functions are core Sass functions. +/// +@function material-shadow($depth) { + // Keyword depths + @if type_of($depth) == number { + @if $depth == 0 { + @return 0px 0px 10px rgba(0, 0, 0, 0.1), 0px 0px 5px rgba(0, 0, 0, 0.1); + // Programatic shadows from 0 through 10 + } @else if ($depth > 0) and ($depth < 13) { + @return 0px 0px floor(10px + ($depth / 5) ) rgba(0, 0, 0, (.1 + ($depth / 66.66666667))), 0px round(2px + ($depth - ($depth / 7))) round(2px + ($depth - ($depth / 20))) rgba(0, 0, 0, (.1 + ($depth / 66.66666667))) + } + } @else if $depth == 'flat' { + // Box Shadow: offset-x | offset-y | blur-radius | spread-radius | color + @return 0px 0px 10px rgba(0, 0, 0, 0.1), 0px 0px 5px rgba(0, 0, 0, 0.1); + } @else if $depth == 'shallow' { + @return 0px 0px 10px rgba(0, 0, 0, 0.15), 0px 3px 3px rgba(0, 0, 0, 0.15); + } @else if $depth == 'medium' { + @return 0px 0px 10px rgba(0, 0, 0, 0.2), 0px 7px 10px rgba(0, 0, 0, 0.2); + } @else if $depth == 'deep' { + @return 0px 0px 12px rgba(0, 0, 0, 0.25), 0px 11px 12px rgba(0, 0, 0, 0.25); + } + @warn 'Material shadow supports a range from 1-12, or the keywords "flat, shallow, medium deep"'; + @return false +} \ No newline at end of file diff --git a/core/utilities/functions/_smart-merge.scss b/core/utilities/functions/_smart-merge.scss new file mode 100644 index 000000000..e0399eaab --- /dev/null +++ b/core/utilities/functions/_smart-merge.scss @@ -0,0 +1,59 @@ +@charset 'UTF-8'; + +//// +/// Smart merge +/// @group functions +/// @author Kevin Garcia +//// + +/// Returns a merged map, a single map, or a null value, depending on the results of the function's operations +/// +/// **Limitations:** When merging nested maps, the map merge will replace the value of the entire nested map. This is a limitation of Sass's implementation. This means if you want to replace a single property in a :before nested declaration, for example, you'll have to redeclare the entire element in the override map. +/// +/// @param {map} default-map - The default map the mixin consumes +/// @param {map} map [null] - The optional override map to merge in +/// +/// @example scss - SCSS +/// $map--default: ( +/// property1: value1, +/// property2: value2, +/// property3: value3, +/// // etc... +/// )!default; +/// +/// $my-new-map: ( +/// property1: my-value1, +/// property3: null, // By explicitly declaring a +/// // null value in the merged map, +/// // we can suppress this property +/// my-new-property: my-new-value, +/// // etc... +/// ); +/// +/// $merged-map: smart-merge($map--default, $my-new-map); +/// +/// +/// @example scss - Merged SCSS Map +/// $merged-map: ( +/// property1: my-value1, +/// property2: value2, +/// my-new-property: my-new-value, +/// // etc... +/// ); +/// +@function smart-merge($default-map, $map) { + @if $map { + @if $default-map { + @return map-merge($default-map, $map); + } @else { + @return $map; + } + } @else { + @if $default-map { + @return $default-map; + } @else { + @warn 'Could not return map.'; + @return false; + } + } +} diff --git a/core/utilities/functions/_unitconversion.scss b/core/utilities/functions/_unitconversion.scss index 39ee95f2c..e90178e22 100644 --- a/core/utilities/functions/_unitconversion.scss +++ b/core/utilities/functions/_unitconversion.scss @@ -1,7 +1,10 @@ // ____________________________________________________________________________ -// -// Unit Conversion v.2.1.3 -// https://github.com/jakob-e/unitconversion +//// +/// Unit Conversion v.2.1.3 +/// @author Jakob Eriksen +/// @link https://github.com/jakob-e/unitconversion +/// @group functions +//// // ____________________________________________________________________________ // // Function Input units @@ -95,6 +98,8 @@ @function khz($input){ @return to-unit(khz, $input); } // Relative lengths +/// Returns em relative units +/// @require to-unit @function em($input...){ $em: to-unit(em, nth($input,1)); // Adjust for compounds (visual size) @@ -105,6 +110,9 @@ } @return $em; } + +/// Returns REM root units +/// @require to-unit @function rem($input){ @return to-unit(rem, $input); } // Inconvertible relative lengths – depends on font @@ -138,6 +146,9 @@ // Conversion function +/// Conversion function +/// @require $base-font-size +/// @require $root-font-size @function to-unit($unit, $input){ // Test against valid CSS units $to-unit: map-get(( diff --git a/core/utilities/functions/fonts/_check-loaded-font.scss b/core/utilities/functions/fonts/_check-loaded-font.scss index d6d4df7ca..e1d9bfc07 100644 --- a/core/utilities/functions/fonts/_check-loaded-font.scss +++ b/core/utilities/functions/fonts/_check-loaded-font.scss @@ -1,7 +1,12 @@ @charset "UTF-8"; -/// @access private +//// +/// Font loading function. +/// @group font-management +//// + /// Checks the global variable for loaded fonts +/// @require $loaded-fonts @function _check-loaded-font($url) { $_value: index($loaded-fonts, $url); @if type-of($_value) == number { diff --git a/core/utilities/functions/fonts/_log-loaded-font.scss b/core/utilities/functions/fonts/_log-loaded-font.scss index 687208190..0e9b21b28 100644 --- a/core/utilities/functions/fonts/_log-loaded-font.scss +++ b/core/utilities/functions/fonts/_log-loaded-font.scss @@ -1,8 +1,13 @@ @charset "UTF-8"; -/// @access private +//// +/// Font loading function. +/// @group font-management +//// + /// Internal function to keep track of loaded fonts /// so we don't duplicate calls. +/// @require $loaded-fonts @function _log-loaded-font($url) { $loaded-fonts: append($loaded-fonts, $url, comma) !global; @return true; diff --git a/core/utilities/functions/layout/_adjust-container-margin.scss b/core/utilities/functions/layout/_adjust-container-margin.scss index fe64f8eb8..013489a11 100644 --- a/core/utilities/functions/layout/_adjust-container-margin.scss +++ b/core/utilities/functions/layout/_adjust-container-margin.scss @@ -1,11 +1,14 @@ @charset "UTF-8"; - +//// /// Adjust Container Margin +/// @group functions +//// + /// Adjusts the margin of a container by growing or shrinking it by a certain number of columns. /// This is a companion function to set-container-padding, which allows a container to break out /// of it's own boundaries. /// -/// todo: Documentation +/// @todo: Documentation @function _adjust-container-margin( $columns, diff --git a/core/utilities/functions/layout/_set-container-padding.scss b/core/utilities/functions/layout/_set-container-padding.scss index be63c74bb..d2585ddca 100644 --- a/core/utilities/functions/layout/_set-container-padding.scss +++ b/core/utilities/functions/layout/_set-container-padding.scss @@ -1,5 +1,10 @@ @charset "UTF-8"; +//// +/// Padding +/// @group functions +//// + /// Set Container padding /// Creates a fluid container of a certain number of columns. /// Can be constrained to a specific max width, or to the project's global `$max-container-width`. @@ -12,7 +17,6 @@ @function _set-container-padding( $columns: null, $grid: $neat-grid, - $v-space: 1em, $max-width: false ) { @@ -24,17 +28,17 @@ // Checks to see if we need to calculate a gutter @if $_grid-columns >= $_columns { $_column-multiplier: $_grid-columns - $_columns; - @return $v-space calc(((50% /#{$_grid-columns}) * #{$_column-multiplier}) + #{$_grid-gutter}); + @return calc(((50% /#{$_grid-columns}) * #{$_column-multiplier}) + #{$_grid-gutter}); } @else { - @return $v-space $_grid-gutter; + @return $_grid-gutter; } // Otherwise we calculate the max width in pixels } @else if type_of($max-width) == number { $_container-width: (((px($max-width / 2)) / $_grid-columns) * $_columns); - @return $v-space calc(50% - (#{$_container-width} - #{$_grid-gutter})); + @return calc(50% - (#{$_container-width} - #{$_grid-gutter})); // Finally, if max width is set to true, we use the project's "max-container-width" configuration option. } @else if ($max-width == true) { $_container-width: ((($max-container-width / 2) / $_grid-columns) * $_columns); - @return $v-space calc(50% - (#{$_container-width} - #{$_grid-gutter})); + @return calc(50% - (#{$_container-width} - #{$_grid-gutter})); } } diff --git a/core/utilities/mixins/__nested-properties.scss b/core/utilities/mixins/__nested-properties.scss new file mode 100644 index 000000000..b4baef888 --- /dev/null +++ b/core/utilities/mixins/__nested-properties.scss @@ -0,0 +1,39 @@ +@charset "UTF-8"; + +//// +/// Nested properties +/// @author Kevin Garcia +/// @group mixins +//// + +/// +/// Returns a list of recursively nested `$property`: `$value` pairs. +/// The mixin will continue to iterate as long as any map value is a nested map. +/// +/// @param {css property} $_property - The CSS Property +/// @param {css value | map} $_value - The CSS Value the property contains, or, if a map, the properties of the nested selector. +/// +/// @access private + +@mixin _nested-properties($_property, $_value) { + // Checks for nested maps + @if type-of($_value) == map { + // Uses map key as element selector + #{$_property} { + // Iterates over property:value pairs + @each $_nested-property, $_nested-value in $_value { + // Recursive check for nested maps + @if type-of($_nested-value) == map { + // If nested map, call self and restart loop + @include _nested-properties($_nested-property, $_nested-value); + } @else { + // Outputs property:value CSS + #{$_nested-property}: #{$_nested-value}; + } + } + } + } @else { + // Outputs property:value CSS + #{$_property}: #{$_value}; + } +} diff --git a/core/utilities/mixins/_button.scss b/core/utilities/mixins/_button.scss new file mode 100644 index 000000000..56d713f97 --- /dev/null +++ b/core/utilities/mixins/_button.scss @@ -0,0 +1,16 @@ +@charset "UTF-8"; + +/// +/// The button mixin is a functional alias of the `properties` mixin, however, it's there to provide a semantic +/// demarcation for it's intended purpose. Namely, we are using it to mimic the `extend` functionality for cases +/// where CSS inheritance causes unintended cascading of button properties. In those cases, +/// you can `@include button($base-button, $secondary-button)`, and have this mixin provide all the computed +/// values that would normally be overriden if we had used %extend +/// +@mixin button($default-settings, $settings: null) { + $_settings: smart-merge($default-settings, $settings); + + @each $_property, $_value in $_settings { + @include _nested-properties($_property, $_value); + } +} diff --git a/core/utilities/mixins/_center-block.scss b/core/utilities/mixins/_center-block.scss index 05f2ea1de..d738eb00c 100644 --- a/core/utilities/mixins/_center-block.scss +++ b/core/utilities/mixins/_center-block.scss @@ -1,5 +1,6 @@ @charset "UTF-8"; +/// @group mixins /// Center block @mixin center-block { display: block; diff --git a/core/utilities/mixins/_decanter-mixins.scss b/core/utilities/mixins/_decanter-mixins.scss index 1e0dc167d..9fa904975 100644 --- a/core/utilities/mixins/_decanter-mixins.scss +++ b/core/utilities/mixins/_decanter-mixins.scss @@ -16,9 +16,12 @@ , 'theme/color-theme' , 'theme/color-themes' // Misc helpers +, '_nested-properties' +, 'properties' +, 'button' , 'center-block' , 'material-shadow' -, 'font-size' -, 'on-event' +, 'font-size' // deprecated +, 'on-event' // deprecated , 'load-fonts' ; diff --git a/core/utilities/mixins/_font-size.scss b/core/utilities/mixins/_font-size.scss index 21f78fa77..c3cc789ee 100644 --- a/core/utilities/mixins/_font-size.scss +++ b/core/utilities/mixins/_font-size.scss @@ -4,12 +4,13 @@ /// FILE COMMENT HERE //// -/// -/// Function font-size -/// - @import '../functions/unitconversion'; +/// +/// Mixin font-size +/// @group mixins +/// @deprecated +/// @require em @mixin font-size($_size: 16px, $_base: null) { @if $_base == null { font-size: em($_size); diff --git a/core/utilities/mixins/_load-fonts.scss b/core/utilities/mixins/_load-fonts.scss index 2d86c3b31..895826efd 100644 --- a/core/utilities/mixins/_load-fonts.scss +++ b/core/utilities/mixins/_load-fonts.scss @@ -2,7 +2,7 @@ //// /// Font loading function. -/// @group functions +/// @group font-management //// /// Global default fonts. @@ -13,6 +13,11 @@ $loaded-fonts: () !default; /// Load a collection of @font-face fonts /// +/// @require $fonts +/// @require $loaded-fonts +/// @require log-loaded-fonts +/// @require _check-loaded-font +/// @require _log-loaded-font @mixin load-fonts($load: $fonts) { // String @@ -20,12 +25,12 @@ $loaded-fonts: () !default; // Cast the item to a string to be sure we don't pass // strange variables to the loader. $_item_string: '#{$load}'; - @if (_is-loaded_font($_item_string) != true) { + @if _check-loaded_font($_item_string) { + @debug "Font: #{$_item_string} already loaded."; + } @else { $_tmp: _log-loaded-font($_item_string); $_item_string: quote($_item_string); @import url($_item_string); - } @else { - @debug "Font: #{$_item_string} already loaded."; } // List } @else if type-of($load) == list { @@ -34,14 +39,13 @@ $loaded-fonts: () !default; // Cast the item to a string to be sure we don't pass // strange variables to the loader. $_item_string: '#{$_item}'; - @if (_is-loaded_font($_item_string) != true) { + @if _check-loaded-font($_item_string) { + @debug "Font: #{$_item_string} already loaded."; + } @else { $_tmp: _log-loaded-font($_item_string); $_item_string: quote($_item_string); @import url($_item_string); } - @else { - @debug "Font: #{$_item_string} already loaded."; - } } // Map } @else if type-of($load) == map { @@ -51,14 +55,13 @@ $loaded-fonts: () !default; // Cast the item to a string to be sure we don't pass // strange variables to the loader. $_item_string: '#{$_font}'; - @if (_is-loaded_font($_item_string) != true) { + @if _check-loaded-font($_item_string) { + @debug "Font: #{$_item_string} already loaded."; + } @else { $_tmp: _log-loaded-font($_item_string); $_item_string: quote($_item_string); @import url($_item_string); } - @else { - @debug "Font: #{$_item_string} already loaded."; - } } } } diff --git a/core/utilities/mixins/_material-shadow.scss b/core/utilities/mixins/_material-shadow.scss index ab8611683..037289ff1 100644 --- a/core/utilities/mixins/_material-shadow.scss +++ b/core/utilities/mixins/_material-shadow.scss @@ -3,7 +3,6 @@ /// Creates a material-design style shadow. May be flat, shallow, medium, or deep. /// /// @author Kevin Garcia -/// @group mixins /// /// @arg {string} Depth [shallow] - How deep the shadow appears to be. Default is Shallow. /// @require {function} rgba @@ -17,21 +16,15 @@ /// .element { /// box-shadow: 0px 0px 12px 0px rgba(0,0,0,0.10), 2px 4px 7px 0px rgba(0,0,0,0.15); /// } -@mixin material-shadow -( - $depth: shallow -) { -// Depths: flat | shallow | medium | deep - @media screen { - @if $depth == 'flat' { - // Box Shadow: offset-x | offset-y | blur-radius | spread-radius | color - box-shadow: 0px 0px 10px 0px rgba(0, 0, 0, 0.05); - } @else if $depth == 'shallow' { - box-shadow: 0px 0px 10px 0px rgba(0, 0, 0, 0.05), 0px 3px 3px 1px rgba(0, 0, 0, 0.05); - } @else if $depth == 'medium' { - box-shadow: 0px 0px 10px 0px rgba(0, 0, 0, 0.09), 0px 7px 10px 0px rgba(0, 0, 0, 0.15); - } @else if $depth == 'deep' { - box-shadow: 0px 0px 12px 0px rgba(0, 0, 0, 0.10), 0px 11px 12px 0px rgba(0, 0, 0, 0.2); - } +/// +/// @group mixins +/// +/// @deprecated +/// This mixin is deprecated in favor of the `material-shadow` function +/// +/// @see {function} material-shadow +@mixin material_shadow( $depth: shallow ) { + @media only screen { + box-shadow: material-shadow($depth); } } diff --git a/core/utilities/mixins/_on-event.scss b/core/utilities/mixins/_on-event.scss index 87d2da997..f338ebe61 100644 --- a/core/utilities/mixins/_on-event.scss +++ b/core/utilities/mixins/_on-event.scss @@ -1,7 +1,11 @@ /// Event wrapper +/// @group mixins /// @author Harry Roberts /// @param {Bool} $self [false] - Whether or not to include current selector /// @link https://twitter.com/csswizardry/status/478938530342006784 Original tweet from Harry Roberts +/// @deprecated in favor of the `$hocus` and `$pocus` variables +/// @see $hocus +/// @see $pocus @mixin on-event($self: false) { @if $self { &, diff --git a/core/utilities/mixins/_properties.scss b/core/utilities/mixins/_properties.scss new file mode 100644 index 000000000..2a86b275c --- /dev/null +++ b/core/utilities/mixins/_properties.scss @@ -0,0 +1,119 @@ +@charset 'UTF-8'; + +//// +/// Properties +/// @author Kevin Garcia +/// @group mixins +//// + +/// Returns a list of `$property`: `$value` pairs +/// +/// @param {map} default-settings - The default map the mixin consumes +/// @param {map} settings [null] - The optional override map to merge in +/// +/// @example scss - source SCSS +/// $default-map: ( +/// color: blue, +/// margin: 0 auto, +/// ); +/// +/// $map-override: ( +/// color: red, +/// overflow: hidden, +/// ); +/// +/// .default-element { +/// @include properties($default-map); +/// } +/// +/// .override-element { +/// @include properties($map-override); +/// } +/// +/// .merged-element { +/// @include properties($default-map, $map-override); +/// } +/// +/// @example css - output CSS +/// +/// .default-element { +/// color: blue; +/// margin: 0 auto; +/// } +/// +/// .override-element: { +/// color: red; +/// overflow: hidden; +/// }; +/// +/// .merged-element { +/// color: red; +/// margin: 0 auto; +/// overflow: hidden; +/// } +/// +/// @example scss - When to use default + merged elements (scss) +/// +/// // The main use case is when one wants to output variations of an element. +/// +/// $default-button: ( +/// background-color: #333333, +/// color: white, +/// margin: 0 auto, +/// padding: 1em, +/// ); +/// +/// $blue-button: ( +/// background-color: blue, +/// ); +/// +/// // You can pass it a default map +/// .button { +/// @include element-properties($default-button); +/// } +/// +/// // You can pass it a named map +/// .button--blue { +/// @include element-properties($default-button, $blue-button); +/// } +/// +/// // You may also pass it an inline map +/// .button--green { +/// @include element-properties($default-button, (font-size: 1.125em, background-color: green, color: inherit, margin: null, )); +/// } +/// +/// @example css - When to use default + merged elements (output) +/// +/// .button: { +/// background-color: #333333; +/// color: white; +/// margin: 0 auto; +/// padding: 1em; +/// }; +/// +/// .button--blue: ( +/// background-color: blue; +/// color: white; +/// margin: 0 auto; +/// padding: 1em; +/// ); +/// +/// /* Notice that explicitly null values in overrides are removed from the output */ +/// .button--green: ( +/// background-color: green; /* <- overriden value */ +/// color: inherit; /* <- overriden value */ +/// padding: 1em; /* <- Notice that the margin property is gone. */ +/// font-size: 1.125em /* <- values not present in the default map are amended to the end */ +/// ); +/// +/// +/// @requires [function] smart-merge +/// @requires [mixin] _nested-properties +/// +@mixin properties($default-settings, $settings: null) { + $_settings: smart-merge($default-settings, $settings); + + @each $_property, $_value in $_settings { + @include _nested-properties($_property, $_value); + } +} \ No newline at end of file diff --git a/core/utilities/mixins/layout/_adjust-container-width.scss b/core/utilities/mixins/layout/_adjust-container-width.scss index c04275644..41e7d3c49 100644 --- a/core/utilities/mixins/layout/_adjust-container-width.scss +++ b/core/utilities/mixins/layout/_adjust-container-width.scss @@ -1,8 +1,8 @@ @charset "UTF-8"; -// Adjust the current container by insetting or breaking out by X columns -// Can accept negative numbers -// todo: documentation. - +/// Adjust the current container by insetting or breaking out by X columns +/// Can accept negative numbers +/// todo: documentation. +/// @mixin adjust-container-width ( $columns: 2, diff --git a/core/utilities/mixins/layout/_centered-container.scss b/core/utilities/mixins/layout/_centered-container.scss index 5acc55c60..00131d2b2 100644 --- a/core/utilities/mixins/layout/_centered-container.scss +++ b/core/utilities/mixins/layout/_centered-container.scss @@ -4,7 +4,10 @@ /// centered-container mixin /// Creates a wrapper-less centered container using padding /// Depends on Neat. We use the global neat-grid variable for grid default, but you may pass it any value. - +/// @require _set-container-padding +/// @require $neat-grid +/// +/// @link http://neat.bourbon.io Neat @mixin centered-container( $columns: null, $v-space: 1em, @@ -17,10 +20,15 @@ $_grid-columns: _retrieve-neat-setting($grid, columns); // Retrieves the number of max columns from the specified grid $_grid-gutter: _retrieve-neat-setting($grid, gutter); // Retrieves the gutter from the specified grid - padding: _set-container-padding($columns, $grid, $v-space, $max-width); - @include grid-container; @if $grid-collapse == true { @include grid-collapse; } + + @if $v-space { + padding: $v-space _set-container-padding($columns, $grid, $max-width); + } @else { + padding-left: _set-container-padding($columns, $grid, $max-width); + padding-right: _set-container-padding($columns, $grid, $max-width); + } } diff --git a/core/utilities/mixins/theme/_color-theme.scss b/core/utilities/mixins/theme/_color-theme.scss index 48554725f..7a7962fa5 100644 --- a/core/utilities/mixins/theme/_color-theme.scss +++ b/core/utilities/mixins/theme/_color-theme.scss @@ -1,4 +1,8 @@ @charset "UTF-8"; +//// +/// Color themes +/// @group mixins|color +//// // Dependency on the $colors variable. @import '../../variables/colors'; @@ -20,7 +24,7 @@ /// the `$selector` argument allows you to specify a different class than the current. It's /// especially useful when used with the `render-color-themes` mixin. /// -/// @example SCSS +/// @example scss - SCSS /// $green-theme: ( /// brand: #2c853c, /// action: #00992b, @@ -40,24 +44,26 @@ /// } /// } /// -/// @example CSS +/// @example css - CSS output /// .card { /// background-color: #fff; /// color: #121111; /// } /// -/// @example SCSS +/// @example scss - SCSS /// @include color-theme($green-theme, '.card') { /// background-color: color(background); /// color: color(text-active); /// } /// -/// @example CSS +/// @example css - CSS output /// .card { /// background-color: #fff; /// color: #121111; /// } /// +/// @require color +/// @require $colors @mixin color-theme($palette, $selector: '&') { $_default-color-palette: $colors; diff --git a/core/utilities/mixins/theme/_color-themes.scss b/core/utilities/mixins/theme/_color-themes.scss index a7f668dd2..3cd29b195 100644 --- a/core/utilities/mixins/theme/_color-themes.scss +++ b/core/utilities/mixins/theme/_color-themes.scss @@ -2,13 +2,12 @@ //// /// Color Themes mixin -/// @group mixins|theme +/// @group functions|color //// // Dependency on the $colors variable. @import '../../variables/colors'; -/// /// $default-theme-group: ( default: ( palette: $colors, selector: '&' ), @@ -29,7 +28,7 @@ $default-theme-group: ( /// has ended, the default color map will revert to its original state as defined by `$color`. /// /// -/// @example SCSS +/// @example scss - SCSS /// $green-theme: ( /// brand: #2c853c, /// action: #00992b, @@ -67,7 +66,7 @@ $default-theme-group: ( /// } /// } /// -/// @example CSS +/// @example css - CSS Output /// .card { /// background-color: #fff; /// color: #808080; @@ -81,6 +80,9 @@ $default-theme-group: ( /// color: #297C85; /// } /// +/// @require color +/// @require $colors +/// @require color-theme @mixin color-themes($theme-group: null) { @each $_theme, $_map in $theme-group { diff --git a/core/utilities/variables/_borders.scss b/core/utilities/variables/_borders.scss index f80978421..26ff0b3fb 100644 --- a/core/utilities/variables/_borders.scss +++ b/core/utilities/variables/_borders.scss @@ -2,11 +2,12 @@ //// /// Borders -/// @group variables|borders +/// @group _variables|borders //// /// Base border radius. $base-border-radius: 3px !default; /// Base Border. +/// @require color $base-border: 1px solid color(border) !default; diff --git a/core/utilities/variables/_breakpoints.scss b/core/utilities/variables/_breakpoints.scss index 461c7bc43..aa55ec57e 100644 --- a/core/utilities/variables/_breakpoints.scss +++ b/core/utilities/variables/_breakpoints.scss @@ -2,64 +2,56 @@ //// /// Breakpoints +/// @type variable //// // Breakpoint Boundaries /// Lower Boundary for extra small screens -/// @group variables|breakpoint-boundaries -/// @type variable +/// @group _variables|breakpoint-boundaries $screen-xs-min: 0px !default; /// Lower boundary for small screens -/// @group variables|breakpoint-boundaries -/// @type variable +/// @group _variables|breakpoint-boundaries $screen-sm-min: 576px !default; /// Lower boundary for medium screens -/// @group variables|breakpoint-boundaries -/// @type variable +/// @group _variables|breakpoint-boundaries $screen-md-min: 768px !default; /// Lower boundary for large screens -/// @group variables|breakpoint-boundaries -/// @type variable +/// @group _variables|breakpoint-boundaries $screen-lg-min: 992px !default; /// Lower boundary for extra large screens -/// @group variables|breakpoint-boundaries -/// @type variable +/// @group _variables|breakpoint-boundaries $screen-xl-min: $max-container-width !default; /// Upper boundary for extra small screens -/// @group variables|breakpoint-boundaries +/// @group _variables|breakpoint-boundaries /// @requires $screen-xs-min -/// @type variable $screen-xs-max: $screen-sm-min - 1px !default; /// Upper boundary for small screens -/// @group variables|breakpoint-boundaries +/// @group _variables|breakpoint-boundaries /// @requires $screen-sm-min -/// @type variable $screen-sm-max: $screen-md-min - 1px !default; /// Upper boundary for medium screens -/// @group variables|breakpoint-boundaries +/// @group _variables|breakpoint-boundaries /// @requires $screen-lg-min -/// @type variable $screen-md-max: $screen-lg-min - 1px !default; /// Upper boundary for large screens -/// @group variables|breakpoint-boundaries +/// @group _variables|breakpoint-boundaries /// @requires $screen-xl-min -/// @type variable $screen-lg-max: $screen-xl-min - 1px !default; // Neat Media Queries -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -78,7 +70,7 @@ $media-xs: ( media: $screen-xs-min, ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -97,7 +89,7 @@ $media-xs-only: ( media: 'only screen and (max-width: #{$screen-xs-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -116,7 +108,7 @@ $media-xs-max: ( media: 'only screen and (max-width: #{$screen-xs-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -135,7 +127,7 @@ $media-sm: ( media: $screen-sm-min, ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -155,7 +147,7 @@ $media-sm-only: ( media: 'only screen and (min-width: #{$screen-sm-min}) and (max-width: #{$screen-sm-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -174,7 +166,7 @@ $media-sm-max: ( media: 'only screen and (max-width: #{$screen-sm-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -193,7 +185,7 @@ $media-md: ( media: $screen-md-min, ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -213,7 +205,7 @@ $media-md-only: ( media: 'only screen and (min-width: #{$screen-md-min}) and (max-width: #{$screen-md-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -232,7 +224,7 @@ $media-md-max: ( media: 'only screen and (max-width: #{$screen-md-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -251,7 +243,7 @@ $media-lg: ( media: $screen-lg-min, ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -270,7 +262,7 @@ $media-lg-only: ( media: 'only screen and (min-width: #{$screen-lg-min}) and (max-width: #{$screen-lg-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -289,7 +281,7 @@ $media-lg-max: ( media: 'only screen and (max-width: #{$screen-lg-max})', ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat Docs - Grid Media /// @type map /// @@ -308,7 +300,7 @@ $media-xl: ( media: $screen-xl-min, ) !default; -/// @group variables|grid-media +/// @group _variables|grid-media /// @link http://neat.bourbon.io/docs/latest/#grid-media Neat | Grid Media /// @type map /// diff --git a/core/utilities/variables/_buttons.scss b/core/utilities/variables/_buttons.scss index 9e7de14bb..998ab2179 100644 --- a/core/utilities/variables/_buttons.scss +++ b/core/utilities/variables/_buttons.scss @@ -2,59 +2,85 @@ //// /// Colors -/// @group Variables|Buttons +/// @group _variables|buttons //// /// This variable is a sass map that overrides our generic button map. /// /// @name Base button /// -/// @property {Color} bg-color [color(action)] - Background color -/// @property {Color} color [color(reverse-text)] - Text Color -/// @property {length(with unit) | string} border ['none'] - Border properties. Accepts shorthand. +/// @require $base-font-family +/// @require $base-line-height +/// @require $small-spacing +/// @require $base-transition +/// @require material-shadow +/// @require color +/// @require em $base-button: ( - bg-color: color(action), - color: color(reverse-text), - border: none, - cursor: pointer, - display: inline-block, - material-shadow: flat, - font-family: $base-font-family, - line-height: $base-line-height, - font-weight: inherit, - font-size: inherit, + box-shadow: material-shadow(flat), + appearance: none, + background-color: color(action), + border: none, + color: color(reverse-text), + cursor: pointer, + display: inline-block, + font-family: $base-font-family, + font-size: inherit, + -webkit-font-smoothing: antialiased, + font-weight: inherit, + line-height: $base-line-height, + padding: em(6px) em($small-spacing) em(7px), + text-align: center, + text-decoration: none, + user-select: none, + vertical-align: middle, + transition: $base-transition, + + '#{$hocus}': ( + background-color: color(action--active), + color: color(reverse-text--active), text-decoration: none, - transition: $base-transition, - padding: 'em(6px) em($_spacing) em(7px)', - text-align: center, - spacing: $small-spacing, - bg-color--active: color(action--active), - color--active: color(reverse-text--active), - border--active: null, - material-shadow--active: null, - text-decoration--active: none, + ), + + '&:disabled, &.disabled': ( + background-color: color(action), + color: color(reverse-text), + cursor: not-allowed, + opacity: .5, + + '&:hover': ( + cursor: not-allowed, + ), + ), ) !default; $primary-button: ( - bg-color: color(action), + background-color: color(action), + color: color(reverse-text), + font-weight: 600, + padding: em(10px) em($base-spacing) em(12px), + + '#{$hocus}': ( + background-color: color(action--active), color: color(reverse-text), - font-weight: 600, - padding: 'em(10px) em($_spacing) em(12px)', - bg-color--active: color(action-active), - color--active: color(reverse-text--active), - material-shadow--active: null, - text-decoration--active: none, + text-decoration: none, + ), ) !default; +/// +/// @require $base-border +/// @require $base-spacing +/// @require $hocus $secondary-button: ( - bg-color: inherit, - border: $base-border, - border--active: color(action), + background-color: inherit, + border: $base-border, + color: color(text), + font-weight: 600, + padding: em(7px) em($base-spacing) em(9px), + + '#{$hocus}': ( + background-color: inherit, + border-color: color(action), color: color(action), - font-weight: 600, - padding: 'em(7px) em($_spacing) em(9px)', - bg-color--active: inherit, - color--active: color(text--active), - material-shadow--active: null, - text-decoration--active: none, + ), ) !default; diff --git a/core/utilities/variables/_colors.scss b/core/utilities/variables/_colors.scss index 3c74ae53f..50f751dbe 100644 --- a/core/utilities/variables/_colors.scss +++ b/core/utilities/variables/_colors.scss @@ -2,7 +2,7 @@ //// /// Colors -/// @group variables|colors +/// @group _variables|colors //// /// This variable is a sass map that overrides our generic color map. diff --git a/core/utilities/variables/_containers.scss b/core/utilities/variables/_containers.scss index 45036e828..9b3578661 100644 --- a/core/utilities/variables/_containers.scss +++ b/core/utilities/variables/_containers.scss @@ -2,7 +2,7 @@ //// /// Containers -/// @group variables|containers +/// @group _variables|containers //// /// Default Responsive Container diff --git a/core/utilities/variables/_decanter-variables.scss b/core/utilities/variables/_decanter-variables.scss index 23e9eff7b..3598cc915 100644 --- a/core/utilities/variables/_decanter-variables.scss +++ b/core/utilities/variables/_decanter-variables.scss @@ -20,11 +20,11 @@ , 'neat-omega' ; -// Base variables. +// Base settings. @import 'vertical-rhythm' , 'typography' - , 'animations' + , 'transitions' , 'borders' , 'breakpoints' , 'buttons' diff --git a/core/utilities/variables/_forms.scss b/core/utilities/variables/_forms.scss index 3ac492e05..d5ef48b95 100644 --- a/core/utilities/variables/_forms.scss +++ b/core/utilities/variables/_forms.scss @@ -2,14 +2,14 @@ //// /// Forms -/// @group variables|forms +/// @group _variables|forms //// -/// Form box shadow default. -/// @require {function} color +/// Default form box-shadow +/// @require color $form-box-shadow: inset 0 1px 3px rgba(color(black), 0.06) !default; -/// Form box shadow focus default. -/// @require {variable} lightness -/// @require {variable} alpha -$form-box-shadow-focus: $form-box-shadow, 0 0 5px adjust-color(color(blue), $lightness: -5%, $alpha: -0.3) !default; +/// Default focused form box-shadow +/// @require color +/// @link http://sass-lang.com/documentation/Sass/Script/Functions.html#adjust_color-instance_method adjust-color() documentation +$form-box-shadow--focus: $form-box-shadow, 0 0 5px adjust-color(color(blue), $lightness: -5%, $alpha: -0.3) !default; diff --git a/core/utilities/variables/_animations.scss b/core/utilities/variables/_transitions.scss similarity index 92% rename from core/utilities/variables/_animations.scss rename to core/utilities/variables/_transitions.scss index 0a3726242..892f8240f 100644 --- a/core/utilities/variables/_animations.scss +++ b/core/utilities/variables/_transitions.scss @@ -2,7 +2,7 @@ //// /// Animations -/// @group variables|animations +/// @group _variables|animations //// /// Base property animation default. diff --git a/core/utilities/variables/_typography.scss b/core/utilities/variables/_typography.scss index 10122edfa..303cd41ad 100644 --- a/core/utilities/variables/_typography.scss +++ b/core/utilities/variables/_typography.scss @@ -2,49 +2,99 @@ //// /// Typography -/// @group variables|typography +/// @group _variables|typography //// -/// Font Stack Monospace. /// -/// This is outputted via `font-family: $font-stack-monospace;` - -$decanter-default-fonts: ( +$base-fonts: ( monospace: 'https://fonts.googleapis.com/css?family=Source+Code+Pro', sans-serif: 'https://fonts.googleapis.com/css?family=Noto+Sans:400,400i,700,700i', serif: 'https://fonts.googleapis.com/css?family=Noto+Serif:400,400i,700,700i', ) !default; -$decanter-font-families: ( +/// +$base-font-families: ( monospace: "'Source Code Pro', #{$font-stack-monaco}", sans-serif: "'Noto Sans', #{$font-stack-helvetica}", serif: "'Noto Serif', #{$font-stack-georgia}" ) !default; +/// Load the font-face declarations. +@include load-fonts($base-fonts); + // Semantic definitions // These map the generic `$font-family-serif` stacks to more functional, semantic // font stacks. `$base-font-family`, `$heading-font-family`, `$code-font-family` // -------------------- /// Base Font Family Setting. -$base-font-family: unquote(map-get($decanter-font-families, sans-serif)) !default; +$base-font-family: unquote(map-get($base-font-families, sans-serif)) !default; /// Heading Font Family. -$heading-font-family: unquote(map-get($decanter-font-families, serif)) !default; +$heading-font-family: unquote(map-get($base-font-families, serif)) !default; /// Monospace Font Family. -$monospace-font-family: unquote(map-get($decanter-font-families, monospace)) !default; +$monospace-font-family: unquote(map-get($base-font-families, monospace)) !default; /// Base Line Height. /// @todo find out where this is used and let people know. I assume everywhere. -/// @type number $base-line-height: 1.5 !default; /// Heading Line Height. /// @todo find out where this is used and let people know. I assume everywhere. -/// @type number $heading-line-height: 1.2 !default; -/// All Headlines list selector -/// @type list +/// All Headlines selector +/// +/// **Note:** This selector must be used with variable interpolation when used to declare an element. +/// +/// @example scss - Use Documentation +/// #{$all-headlines} { +/// font-weight: bold; +/// } +/// +/// @example css - Output +/// h1, h2, h3, h4, h5, h6 { +/// font-weight: bold; +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/HTML/Element/Heading_Elements $all-headlines: 'h1, h2, h3, h4, h5, h6' !default; + +/// `hover`, `active`, `focus` pseudo-class variable +/// +/// **Note:** This selector must be used with variable interpolation when used to declare an element. +/// +/// @example scss - Use Documentation +/// #{$hocus} { +/// font-weight: bold; +/// } +/// +/// @example css - Output +/// &:hover, &:active, &:focus { +/// font-weight: bold; +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:hover +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:active +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:focus +$hocus: '&:hover, &:active, &:focus' !default; + +/// `hover`, `focus` pseudo-class variable +/// +/// **Note:** This pseudo-class must be used with variable interpolation when used to declare an element. +/// +/// @example scss - Use Documentation +/// #{$pocus} { +/// font-weight: bold; +/// } +/// +/// @example css - Output +/// &:hover, &:focus { +/// font-weight: bold; +/// } +/// +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:hover +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:active +/// @link https://developer.mozilla.org/en-US/docs/Web/CSS/:focus +$pocus: '&:hover, &:focus' !default; diff --git a/core/utilities/variables/_variables-bourbon.scss b/core/utilities/variables/_variables-bourbon.scss index e6b77d01b..79240dbc9 100644 --- a/core/utilities/variables/_variables-bourbon.scss +++ b/core/utilities/variables/_variables-bourbon.scss @@ -3,7 +3,7 @@ //// /// Bourbon settings /// This file contains bourbon specific variable overrides. -/// @group variables|bourbon +/// @group _variables|_bourbon //// /// Bourbon Settings diff --git a/core/utilities/variables/_variables-decanter.scss b/core/utilities/variables/_variables-decanter.scss index d5437de10..bed6b80ad 100644 --- a/core/utilities/variables/_variables-decanter.scss +++ b/core/utilities/variables/_variables-decanter.scss @@ -3,7 +3,7 @@ //// /// Decanter settings /// This file contains decanter specific variables. -/// @group variables|decanter +/// @group _variables|__decanter //// /// Root font size in pixels. diff --git a/core/utilities/variables/_variables-neat.scss b/core/utilities/variables/_variables-neat.scss index e559bdefe..f159aa883 100644 --- a/core/utilities/variables/_variables-neat.scss +++ b/core/utilities/variables/_variables-neat.scss @@ -3,7 +3,7 @@ //// /// Neat settings /// This file contains neat specific variable overrides. -/// @group variables|neat +/// @group _variables|_neat //// /// This variable is a sass map that overrides Neat's default grid settings. diff --git a/core/utilities/variables/_vertical-rhythm.scss b/core/utilities/variables/_vertical-rhythm.scss index a46ab1b11..200b394c1 100644 --- a/core/utilities/variables/_vertical-rhythm.scss +++ b/core/utilities/variables/_vertical-rhythm.scss @@ -2,11 +2,11 @@ //// /// Vertical Rhythm -/// @group variables|vertical-rhythm +/// @group _variables|vertical-rhythm //// /// Base vertical spacing. -/// Uses the bourbon function modular-scale to procude an em size. +/// Uses the bourbon function modular-scale to produce an em size. /// @require {function} modular-scale /// @type String /// @link http://bourbon.io/docs/#modular-scale @@ -17,7 +17,7 @@ $base-spacing: modular-scale(0) !default; /// Small vertical spacing. -/// Uses the bourbon function modular-scale to procude an em size. +/// Uses the bourbon function modular-scale to produce an em size. /// @require {function} modular-scale /// @type String /// @link http://bourbon.io/docs/#modular-scale diff --git a/docs/base/index.html b/docs/base/index.html index 62a8f933c..1618fcc82 100644 --- a/docs/base/index.html +++ b/docs/base/index.html @@ -1,135 +1,424 @@