Skip to content

Commit

Permalink
docs: #38 address issue missing token info
Browse files Browse the repository at this point in the history
  • Loading branch information
@blackfalcon
blackfalcon committed Mar 19, 2020
1 parent 31ccde5 commit c894df7
Show file tree
Hide file tree
Showing 2 changed files with 79 additions and 45 deletions.
118 changes: 76 additions & 42 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -16,54 +16,20 @@ This repository is a library of core level styles, functions, and mixins that ca

Please see the [documentation site](https://alaskaairlines.github.io/OrionWebCoreStyleSheets/) for all information related to WC Style Sheets.

## †Deprecated

With each release of WC Style Sheets please be sure to pay attention to the †DEPRECATED section of the doc site. All styles that are designated as deprecated will be listed in this section and will be deleted with the next major release. Each deprecated item may list an alternative option. If there is not an alternative option, please consult with your team designer for an alternate solution.

#### Deprecated files

| deprecated file | new file | description |
|---|---|---|
| baselineLTE.scss | core.scss | File deprecation to support new features |
| baseline.scss | essentials.scss | `essentials.scss` does not import headings by default. For new Auro heading sselectors import `headings.scss`. These new selectors support scoping and prefixing.
| inputTypeText.scss | n/a | n/a |
| _layoutProperties.scss | see `_insetUtility.scss` `_layoutPropertiesGenerator.scss` and `_spacingUtility.scss` | The legacy layoutProperties file was broken up into separate concerns |

#### Missing tokens?

When you update to v2.8, if you get an error that there are missing Sass variables with the Auro namespace, e.g. `$auro- ...` simply import the new Auro Sass variables generated from the tokens.

```scss
@import "~@alaskaairux/orion-design-tokens/dist/tokens/SCSSVariables";
```

#### Missing layout selectors?

If you have been using selectors from the now deprecated `_layoutProperties.scss` file, you may be missing the following selectors from your CSS output

```css
.util_[margin/padding][Top/Right/Bottom/Left]--[none/xs/md/lg/xl]
```
## Install

The easy fix is to import the new layout properties generator file that will fill this gap.
OWCSS is made up of a series of Sass files that allows for an array of use cases. There is no core file to import, rather WCSS is an à la carte solution allowing for users to import what they want and when they want it. In most cases you can simply import the Sass file as illustrated below:

```scss
@import "./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/utilityMixins/layoutPropertiesGenerator";
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
```

For full details on this generator, please see the [generator documentation](https://alaskaairlines.github.io/OrionWebCoreStyleSheets/#utility-layout-mixin-auro_layoutPropertiesGenerator).
### Tokens Dependency


## Support

If at any time there is an issue discovered by either the document site or the core library itself, please submit an [issue](https://github.com/AlaskaAirlines/OrionWebCoreStyleSheets/issues/new/choose) as to alert the core team of the situation. We appreciate all your support!

## Install

OWCSS is made up of a series of Sass files that allows for an array of use cases. There is no core file to import, rather WCSS is an à la carte solution allowing for users to import what they want and when they want it. In most cases you can simply import the Sass file as illustrated below:
Sass code in WCSS has a dependency on the `SCSSVariables.scss` file from [Design Tokens](https://github.com/AlaskaAirlines/OrionDesignTokens) package. This reference needs to be imported prior to any reference of a WCSS partial.

```scss
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
@import "~@alaskaairux/orion-design-tokens/dist/tokens/SCSSVariables";
```

### Scoping
Expand Down Expand Up @@ -125,9 +91,29 @@ html.auro { ... }

### Importing utility classes and using the !important flag

When using the Utility Classes, there are two ways to include them. Either subscribe to each family of functional selectors individually, or include all families in a single request.
When importing utility selectors developers have the option to invoke the `!important` CSS flag. Within WCSS the global `$important` variable is `null` by default. To change, simply change the value of the variable prior to importing any utility partials.

```scss
$important: true;
```

Output of default selector

```css
.util_is-lgOnly {
display: none;
}
```

Output with `$important: true`

See [API](http://alaskaairlines.github.io/OrionWebCoreStyleSheets/#utility-variable-important)
```css
.util_is-lgOnly {
display: none !important;
}
```

See !important [spec](http://alaskaairlines.github.io/OrionWebCoreStyleSheets/#utility-variable-important)


### layoutPropertiesGenerator
Expand Down Expand Up @@ -162,6 +148,54 @@ none, xxxs, xxs, xs, sm, md, lg, xl, xxl, xxxl

See [API](http://alaskaairlines.github.io/OrionWebCoreStyleSheets/#utility-layout-mixin-auro_spacing)


## †Deprecated

With each release of WC Style Sheets please be sure to pay attention to the †DEPRECATED section of the doc site. All styles that are designated as deprecated will be listed in this section and will be deleted with the next major release. Each deprecated item may list an alternative option. If there is not an alternative option, please consult with your team designer for an alternate solution.

#### Deprecated files

| deprecated file | new file | description |
|---|---|---|
| baselineLTE.scss | core.scss | File deprecation to support new features |
| baseline.scss | essentials.scss | `essentials.scss` does not import headings by default. For new Auro heading sselectors import `headings.scss`. These new selectors support scoping and prefixing.
| inputTypeText.scss | n/a | n/a |
| _layoutProperties.scss | see `_insetUtility.scss` `_layoutPropertiesGenerator.scss` and `_spacingUtility.scss` | The legacy layoutProperties file was broken up into separate concerns |

## Troubleshooting

The following are frequently asked questions.

#### I updated my version and am now getting a missing variable error?

When you update to v2.8, if you get an error that there are missing Sass variables with the Auro namespace, e.g. `$auro- ...` simply import the new Auro Sass variables generated from the tokens.

```scss
@import "~@alaskaairux/orion-design-tokens/dist/tokens/SCSSVariables";
```

#### I updated my version, now some utility selectors are no longer there?

If you have been using selectors from the now deprecated `_layoutProperties.scss` file, you may be missing the following selectors from your CSS output

```css
.util_[margin/padding][Top/Right/Bottom/Left]--[none/xs/md/lg/xl]
```

The easy fix is to import the new layout properties generator file that will fill this gap.

```scss
@import "./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/utilityMixins/layoutPropertiesGenerator";
```

For full details on this generator, please see the [generator documentation](https://alaskaairlines.github.io/OrionWebCoreStyleSheets/#utility-layout-mixin-auro_layoutPropertiesGenerator).


## Support

If at any time there is an issue discovered by either the document site or the core library itself, please submit an [issue](https://github.com/AlaskaAirlines/OrionWebCoreStyleSheets/issues/new/choose) as to alert the core team of the situation. We appreciate all your support!


## CSS writing conventions

The implementation of WCSS uses a naming convention model that will be strictly adhered to throughout this library and compliance is expected for any contributed updates.
Expand Down
6 changes: 3 additions & 3 deletions docs/index.html
View file
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<!doctype html><html lang="en"><head><meta charset="utf-8"><title>@alaskaairux/orion-web-core-style-sheets - v2.8.11</title><link rel="stylesheet" href="assets/css/main.css"><link href="https://fonts.googleapis.com/css?family=Open+Sans:400,500,700" rel="stylesheet" type="text/css"><meta name="viewport" content="width=device-width"><meta content="IE=edge, chrome=1" http-equiv="X-UA-Compatible"><!-- Open Graph tags --><meta property="og:title" content="@alaskaairux/orion-web-core-style-sheets - SassDoc"><meta property="og:type" content="website"><meta property="og:description" content="<p>Orion core foundation Sass UI Kit</p>
"><!-- Thanks to Sass-lang.com for the icons --><link href="assets/images/favicon.png" rel="shortcut icon"></head><body><aside class="sidebar" role="nav"><div class="sidebar__header"><h1 class="sidebar__title">@alaskaairux/orion-web-core-style-sheets - 2.8.11</h1></div><div class="sidebar__body"><button type="button" class="btn-toggle js-btn-toggle" data-alt="Open all">Close all</button><p class="sidebar__item sidebar__item--heading" data-slug="accessibility"><a href="#accessibility">accessibility</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="accessibility-css"><a href="#accessibility-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="accessibility" data-name=".focus-visible :focus:not(.focus-visible)" data-type="css"><a href="#accessibility-css-.focus-visible :focus:not(.focus-visible)">.focus-visible :focus:not(.focus-visible)</a></li><li class="sidebar__item sassdoc__item" data-group="accessibility" data-name="#{$scope}.focus-visible" data-type="css"><a href="#accessibility-css-#{$scope}.focus-visible">#{$scope}.focus-visible</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="animation"><a href="#animation">animation</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="animation-mixin"><a href="#animation-mixin">mixins</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="animation" data-name="auro_transition" data-type="mixin"><a href="#animation-mixin-auro_transition">auro_transition</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="core"><a href="#core">core</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="core-css"><a href="#core-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="core" data-name="#{$scope} *" data-type="css"><a href="#core-css-#{$scope} *">#{$scope} *</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="essentials"><a href="#essentials">essentials</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="essentials-css"><a href="#essentials-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$sym}#{$prefix}html#{$scope}" data-type="css"><a href="#essentials-css-#{$sym}#{$prefix}html#{$scope}">#{$sym}#{$prefix}html#{$scope}</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}#{$sym}#{$prefix}body,
<!doctype html><html lang="en"><head><meta charset="utf-8"><title>@alaskaairux/orion-web-core-style-sheets - v2.8.12</title><link rel="stylesheet" href="assets/css/main.css"><link href="https://fonts.googleapis.com/css?family=Open+Sans:400,500,700" rel="stylesheet" type="text/css"><meta name="viewport" content="width=device-width"><meta content="IE=edge, chrome=1" http-equiv="X-UA-Compatible"><!-- Open Graph tags --><meta property="og:title" content="@alaskaairux/orion-web-core-style-sheets - SassDoc"><meta property="og:type" content="website"><meta property="og:description" content="<p>Orion core foundation Sass UI Kit</p>
"><!-- Thanks to Sass-lang.com for the icons --><link href="assets/images/favicon.png" rel="shortcut icon"></head><body><aside class="sidebar" role="nav"><div class="sidebar__header"><h1 class="sidebar__title">@alaskaairux/orion-web-core-style-sheets - 2.8.12</h1></div><div class="sidebar__body"><button type="button" class="btn-toggle js-btn-toggle" data-alt="Open all">Close all</button><p class="sidebar__item sidebar__item--heading" data-slug="accessibility"><a href="#accessibility">accessibility</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="accessibility-css"><a href="#accessibility-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="accessibility" data-name=".focus-visible :focus:not(.focus-visible)" data-type="css"><a href="#accessibility-css-.focus-visible :focus:not(.focus-visible)">.focus-visible :focus:not(.focus-visible)</a></li><li class="sidebar__item sassdoc__item" data-group="accessibility" data-name="#{$scope}.focus-visible" data-type="css"><a href="#accessibility-css-#{$scope}.focus-visible">#{$scope}.focus-visible</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="animation"><a href="#animation">animation</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="animation-mixin"><a href="#animation-mixin">mixins</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="animation" data-name="auro_transition" data-type="mixin"><a href="#animation-mixin-auro_transition">auro_transition</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="core"><a href="#core">core</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="core-css"><a href="#core-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="core" data-name="#{$scope} *" data-type="css"><a href="#core-css-#{$scope} *">#{$scope} *</a></li></ul></div><p class="sidebar__item sidebar__item--heading" data-slug="essentials"><a href="#essentials">essentials</a></p><div><p class="sidebar__item sidebar__item--sub-heading" data-slug="essentials-css"><a href="#essentials-css">css</a></p><ul class="list-unstyled"><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$sym}#{$prefix}html#{$scope}" data-type="css"><a href="#essentials-css-#{$sym}#{$prefix}html#{$scope}">#{$sym}#{$prefix}html#{$scope}</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}#{$sym}#{$prefix}body,
#{$scope}.#{$prefix}baseType" data-type="css"><a href="#essentials-css-#{$scope}#{$sym}#{$prefix}body,
#{$scope}.#{$prefix}baseType">#{$scope}#{$sym}#{$prefix}body, #{$scope}.#{$prefix}baseType</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}.#{$prefix}baseParagraph" data-type="css"><a href="#essentials-css-#{$scope}.#{$prefix}baseParagraph">#{$scope}.#{$prefix}baseParagraph</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}.#{$prefix}hyperlink" data-type="css"><a href="#essentials-css-#{$scope}.#{$prefix}hyperlink">#{$scope}.#{$prefix}hyperlink</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}#{$sym}#{$prefix}img" data-type="css"><a href="#essentials-css-#{$scope}#{$sym}#{$prefix}img">#{$scope}#{$sym}#{$prefix}img</a></li><li class="sidebar__item sassdoc__item" data-group="essentials" data-name="#{$scope}#{$sym}#{$prefix}small,
#{$scope}.#{$prefix}type--small" data-type="css"><a href="#essentials-css-#{$scope}#{$sym}#{$prefix}small,
Expand Down Expand Up @@ -1831,4 +1831,4 @@
display: inline-block $important;
}
}</code>" data-collapsed=".util_is-desktopOnly--inline { ... }"><code>.util_is-desktopOnly--inline { ... }</code></pre></div><h3 class="item__sub-heading">Description</h3><div class="item__description"><p>Utility class to restrain <code>block</code> visibility of UI element for <strong>max</strong> screens.</p><p><a href="/#utility-variable-important">Manage</a> <code>!important</code> flag.</p></div><h3 class="item__sub-heading">Example</h3><div class="item__example example"><div class="example__description"><p>import mixin file and selector partial file</p></div><pre class="example__code language-scss"><code>@import &quot;./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/breakpoints&quot;;
@import &quot;./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/utilityClasses/responsive&quot;;</code></pre></div></section></section></section><footer class="footer" role="contentinfo"><div class="container"><div class="footer__project-info project-info"><!-- Name and URL --> <span class="project-info__name">@alaskaairux/orion-web-core-style-sheets</span><!-- Version --> <span class="project-info__version">- v2.8.11</span><!-- License --> <span class="project-info__license">, under Apache-2.0</span></div><a class="footer__watermark" href="http://sassdoc.com"><img src="assets/images/logo_light_inline.svg" alt="SassDoc Logo"></a></div></footer></article><script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script><script>window.jQuery || document.write('<script src="assets/js/vendor/jquery.min.js"><\/script>')</script><script src="assets/js/main.min.js"></script></body></html>
@import &quot;./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/utilityClasses/responsive&quot;;</code></pre></div></section></section></section><footer class="footer" role="contentinfo"><div class="container"><div class="footer__project-info project-info"><!-- Name and URL --> <span class="project-info__name">@alaskaairux/orion-web-core-style-sheets</span><!-- Version --> <span class="project-info__version">- v2.8.12</span><!-- License --> <span class="project-info__license">, under Apache-2.0</span></div><a class="footer__watermark" href="http://sassdoc.com"><img src="assets/images/logo_light_inline.svg" alt="SassDoc Logo"></a></div></footer></article><script src="https://ajax.googleapis.com/ajax/libs/jquery/2.1.1/jquery.min.js"></script><script>window.jQuery || document.write('<script src="assets/js/vendor/jquery.min.js"><\/script>')</script><script src="assets/js/main.min.js"></script></body></html>

0 comments on commit c894df7

Please sign in to comment.