From 9e79bcc131a0f8636f5aee1bc640b15bff7bfce4 Mon Sep 17 00:00:00 2001 From: Angelos Chalaris Date: Mon, 29 Jan 2018 13:30:24 +0200 Subject: [PATCH] Documented utility module --- docs/doc-fragments/docFragments.js | 4 ++- docs/doc-fragments/elementDecorators.js | 27 ++++++++++++++++++ .../responsiveSpacingAndSizing.js | 20 +++++++++++++ docs/v3/DEVLOG.md | 3 ++ docs/v3/docs.html | 28 +++++++++++++++++-- 5 files changed, 79 insertions(+), 3 deletions(-) create mode 100644 docs/doc-fragments/elementDecorators.js create mode 100644 docs/doc-fragments/responsiveSpacingAndSizing.js diff --git a/docs/doc-fragments/docFragments.js b/docs/doc-fragments/docFragments.js index b5d0a93..070e159 100644 --- a/docs/doc-fragments/docFragments.js +++ b/docs/doc-fragments/docFragments.js @@ -24,6 +24,8 @@ var progressBars = require('./progressBars'); var donutSpinners = require('./donutSpinners'); var icons = require('./icons'); var visibilityHelpers = require('./visibilityHelpers'); +var elementDecorators = require('./elementDecorators'); +var responsiveSpacingAndSizing = require('./responsiveSpacingAndSizing'); module.exports = [ gettingStarted, @@ -35,5 +37,5 @@ module.exports = [ textHighlighting, toasts, tooltips, modalDialogs, spoilersAndAccordions, progressBars, donutSpinners, icons, - visibilityHelpers + visibilityHelpers, elementDecorators, responsiveSpacingAndSizing ] diff --git a/docs/doc-fragments/elementDecorators.js b/docs/doc-fragments/elementDecorators.js new file mode 100644 index 0000000..bb7551b --- /dev/null +++ b/docs/doc-fragments/elementDecorators.js @@ -0,0 +1,27 @@ +module.exports = { + id: 'element-decorators', + title: 'Element decorators', + keywords: ['border','border-radius', 'bordered', 'rounded', 'circular', 'shadowed', 'utility'], + description: '

You can apply generic borders, shadows or border radiuses to any element, by using the appropriate class (.bordered, .shadowed, .rounded or .circular).

', + example: '

placeholder  placeholder

', + samples: [`
<span class="bordered">Bordered element.</span>
+<span class="shadowed">Shadowed element.</span>
+<span class="rounded">Rounded element.</span>
+<span class="circular">Circular element.</span>
`], + notes: [ + 'Element decorators use !important declarations to override any other styles, so exercise caution when using them.', + 'Element decorators can be used with pretty much every element or component that is available.' + ], + customization: [ + `Boder color for the generic border decorator can be changed by changing the value of the --generic-border-color variable.`, + `Box shadow style for the generic shadow can be changed by changing the value of the --generic-box-shadow variable.` + ], + modifiers: [], + dos: [], + donts: [ + { + description: `Avoid applying the .rounded and .circular decorators on the same element.`, + sample: `
<span class="rounded circular">Do not do this.</span>
` + } + ] +} diff --git a/docs/doc-fragments/responsiveSpacingAndSizing.js b/docs/doc-fragments/responsiveSpacingAndSizing.js new file mode 100644 index 0000000..8c3702c --- /dev/null +++ b/docs/doc-fragments/responsiveSpacingAndSizing.js @@ -0,0 +1,20 @@ +module.exports = { + id: 'responsive-spacing-sizing', + title: 'Responsive spacing & sizing', + keywords: ['responsiveness', 'margin', 'padding', 'responsive-margin', 'responsive-margin'], + description: '

You can make elements\' spacing or sizing responsive by applying the appropriate class (.responsive-margin or .responsive-padding).

', + example: '', + samples: [`
<span class="responsive-margin">Responsive margin.</span>
+<span class="responsive-padding">Responsive padding.</span>
`], + notes: [ + 'Responsive spacing and sizing modifiers use !important declarations to override any other styles, so exercise caution when using them.', + 'Responsive spacing and sizing modifiers are independent, meaning that hiding or visually hiding an element in one screen size will not affect its visibility in any other screen size.' + ], + customization: [ + `Universal margin for elements can be changed globally by changing the value of the --universal-margin variable, affecting the responsive spacing modifier. As a rule of thumb, consider the universal margin to be the distance you want your paragraphs to have from the sides of the screen.`, + `Universal padding for elements can be changed globally by changing the value of the --universal-padding variable, affecting the responsive sizing modifier.` +], + modifiers: [], + dos: [], + donts: [] +} diff --git a/docs/v3/DEVLOG.md b/docs/v3/DEVLOG.md index 7b5538f..4ad234b 100644 --- a/docs/v3/DEVLOG.md +++ b/docs/v3/DEVLOG.md @@ -301,3 +301,6 @@ ## 20180129 - Documented visibility helpers. +- Documented element decorators. +- Documented responsive spacing and sizing modifiers. +- Updated version info to `v3.0.0-alpha.3`, soon ready to be released as the final alpha. diff --git a/docs/v3/docs.html b/docs/v3/docs.html index edc2bde..aed111e 100644 --- a/docs/v3/docs.html +++ b/docs/v3/docs.html @@ -23,7 +23,7 @@
- +

Getting started

@@ -1005,11 +1005,35 @@

Best practices

<p class="hidden-sm hidden-md">Not visible for users on screens under 1280px wide.</p>

Do: You can apply multiple responsive visibility helpers on the same element.

<p class="hidden visually-hidden">Do not do this.</p>

Don't: Avoid combining .hidden and .visually-hidden or responsive helpers for the same screen size.

Notes

  • Visibility helpers use !important declarations to override any other styles, so exercise caution when using them.
  • The specific breakpoints for small, medium and large screen sizes are as follows:
    • small: less than 768px wide
    • medium: more than or equal to 768px wide and less than 1280px wide
    • large: 1280px wide or more
  • Responsive visibility helper classes are independent, meaning that hiding or visually hiding an element in one screen size will not affect its visibility in any other screen size.
+

+

Element decorators

+ +

You can apply generic borders, shadows or border radiuses to any element, by using the appropriate class (.bordered, .shadowed, .rounded or .circular).

+

Example


placeholder  placeholder

+

Sample code

<span class="bordered">Bordered element.</span>
+<span class="shadowed">Shadowed element.</span>
+<span class="rounded">Rounded element.</span>
+<span class="circular">Circular element.</span>
+ +

Best practices

<span class="rounded circular">Do not do this.</span>

Don't: Avoid applying the .rounded and .circular decorators on the same element.

+

Notes

  • Element decorators use !important declarations to override any other styles, so exercise caution when using them.
  • Element decorators can be used with pretty much every element or component that is available.
+

Customization

  • Boder color for the generic border decorator can be changed by changing the value of the --generic-border-color variable.
  • Box shadow style for the generic shadow can be changed by changing the value of the --generic-box-shadow variable.
+

+

Responsive spacing & sizing

+ +

You can make elements' spacing or sizing responsive by applying the appropriate class (.responsive-margin or .responsive-padding).

+ +

Sample code

<span class="responsive-margin">Responsive margin.</span>
+<span class="responsive-padding">Responsive padding.</span>
+ + +

Notes

  • Responsive spacing and sizing modifiers use !important declarations to override any other styles, so exercise caution when using them.
  • Responsive spacing and sizing modifiers are independent, meaning that hiding or visually hiding an element in one screen size will not affect its visibility in any other screen size.
+

Customization

  • Universal margin for elements can be changed globally by changing the value of the --universal-margin variable, affecting the responsive spacing modifier. As a rule of thumb, consider the universal margin to be the distance you want your paragraphs to have from the sides of the screen.
  • Universal padding for elements can be changed globally by changing the value of the --universal-padding variable, affecting the responsive sizing modifier.