Skip to content

Commit

Permalink
feat: add scope and prefix options to selector
Browse files Browse the repository at this point in the history
* #22 update location of fonts to CDN URL
  • Loading branch information
blackfalcon committed Jan 3, 2020
1 parent f4e627e commit 70bc80a
Show file tree
Hide file tree
Showing 35 changed files with 4,295 additions and 881 deletions.
2 changes: 1 addition & 1 deletion .github/ISSUE_TEMPLATE/general-support.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,7 +9,7 @@ assignees: blackfalcon

# General Support Request
<!--- The scope of this request is to neither communicate a bug or feature request. -->
<!--- If this is a bug or feature request, please close this issue and reference the previus templates. -->
<!--- If this is a bug or feature request, please close this issue and reference the previous templates. -->

## Support request
<!--- Please describe the issue you are reporting -->
Expand Down
156 changes: 123 additions & 33 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,26 @@ WC Style sheets is a responsive, mobile-first collection of styles and tools des

## What's included

This repository is a library of core level styles, functions, and mixins that can be used for consistent front-end UI development.
This repository is a library of core level styles, functions, and mixins that can be used for consistent front-end UI development. This will include full descriptions of CSS selectors, mixins and any other supporting functions or tools.

## All styles documented

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.

## 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

Expand All @@ -20,12 +39,65 @@ OWCSS is made up of a series of Sass files that allows for vast flexibility of u
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
```

In some cases supporting legacy UIs will be an issue and simply importing a Sass file with its selectors will clash with existing selectors. In those situations it may be useful to wrap all the selectors inside a parent selector at the time of import as the following illustrates.
### Scoping

Be sure to see the [prefixing and scoping API](http://alaskaairlines.github.io/OrionWebCoreStyleSheets/#scope-prefix) in the documentation site.

In some cases when supporting legacy UIs will be an issue and simply importing a Sass file with its selectors will clash with existing selectors. In those situations it may be useful to have a scoped selector placed on a parent container to constrain CSS application to the view.

To enable, simply set the `$scope` variable to be `true` prior to importing any selectors that support this setting.

```scss
.[parent-selector] {
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
}
$scope: true;
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
```

This setting will result in the following CSS selectors

```css
html.auro { ... }

.auro body,
.auro .baseType { ... }
```

### Prefixing

Some teams may prefer that the included Auro selectors be prefixed to clearly determine the difference between locally written selectors that those imported from the library.

To enable, simply set the `$prefix` variable to be `true` prior to importing any selectors that support this setting.

```scss
$prefix: true;
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
```

This setting will result in the following CSS selectors

```css
html { ... }

body,
.auro_baseType { ... }
```

### Scoping and prefixing

If needed, both `$scope` and `prefix` can work in tandem. To enable, simply set both the `scope` and `prefix` variables to `true` prior to importing any selectors that support these settings.

```scss
$scope: true;
$prefix: true;
@import "~@alaskaairux/orion-web-core-style-sheets/dist/ ... "
```

This setting will result in the following CSS selectors

```css
html.auro { ... }

.auro body,
.auro .auro_baseType { ... }
```

## WCSS Supports ...
Expand Down Expand Up @@ -100,10 +172,53 @@ $important: !important;
@import "./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/utilityClasses/responsive";
```

## CSS writing conventions

## Peer Dependencies
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.

### Utility

Universally applicable selectors in cases where applying this style is not an appropriate responsibility of another selector. These selectors are typically considered UI trump cards as they may use the `!important` flag.

To learn more about how the `!important` flag can be used with WCSS, please [see the api spec](https://alaskaairlines.github.io/OrionWebCoreStyleSheets/#variable-important).

(may define shape or layout without direct context to any element, component or object)

```css
.util_hidden {
display: none;
}

.util_hiddenVisually {
border: 0;
clip: rect(1px, 1px, 1px, 1px);
height: 1px;
overflow: hidden;
padding: 0;
position: absolute;
width: 1px;
}
```

### Auro supporting styles

Auro web component styles are a special class of utility selectors where common UIs that are mainly addressed in Auro web components are needed in situations where web components cannot be used.

These selectors will be visible by the `.auro_` prefix in the selector name, for example;


```css
.auro_roleButton { ... }

.auro_hyperlink { ... }
```

**NOTE:** The `auro_` prefix will be appended to an Auro supporting selector regardless of the `$prefix` flag setting. Also, the `auro_` prefix will not be duplicated if the `$prefix` flag is set `true`.

### Additional documentation

To learn more about Auro standards in CSS selector conventions, please see [this document](https://github.com/AlaskaAirlines/OrionWebCoreStyleSheets/blob/master/staticDocs/cssConventions.md).

WC Style Sheets has a project peer dependency on [Design Tokens](https://github.com/AlaskaAirlines/OrionDesignTokens), as well as Sass and Style Dictionary. WCSS is not a stand alone project, but is part of a specific dependency chain when building a Design System based applications.

## Dependencies

Expand Down Expand Up @@ -131,22 +246,6 @@ Use of the the `focus-visible` library brings in the capability to be selective

CSS to support this capability is within the `_baseline.scss` and `_baselineLTE.scss` files.

## Experimental styles

To help address the UI of `<input />` elements, there is an experimental style sheet located in the npm. Please refer to the documentation in this code for any information related to it's use.

```scss
@alaskaairux/orion-web-core-style-sheets/dist/formElements/inputTypeText
```

DO NOT include Sass file without a parent wrapper as illustrated below:

```scss
.[parent-selector] {
@import "./node_modules/@alaskaairux/orion-web-core-style-sheets/dist/formElements/inputTypeText";
}
```

The use of the parent selector is to define a custom selector that will wrap these experimental input style as not to pollute the rest of the app's CSS.

## Getting started
Expand All @@ -161,19 +260,10 @@ WCSS consists of resources to be ingested a la carte. For example, you wish to u
@import "@alaskaairux/orion-web-core-style-sheets/dist/breakpoints";
```

## 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.

To learn more, please reference [this document](https://github.com/AlaskaAirlines/OrionWebCoreStyleSheets/blob/master/staticDocs/cssConventions.md).

## Linters

Prior to adding new Sass to this repo, please run the Sass-Lint tests to ensure that any new code is compliant with the set-forward standard. To run the tests, run the following command:

```
$ npm run sassLint
```
Sass-Lint tests to ensure that any new code is compliant with the set-forward standard. Sass-Lint is run as a pre-commit hook in this project. No commits will be allowed unless all linter tests are passed.

If there is an error, this will generate a `.html` file at the root of the project. To view this generated file, run the following command:

Expand Down
2 changes: 1 addition & 1 deletion docs/assets/css/main.css

Large diffs are not rendered by default.

Loading

0 comments on commit 70bc80a

Please sign in to comment.