diff --git a/template/README.md b/template/README.md index 8ff1098d..4c9e270e 100644 --- a/template/README.md +++ b/template/README.md @@ -30,7 +30,7 @@ For additional details in regards to using Orion Design Tokens with components, ### CSS Custom Property fallbacks -[CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) are not supported in older browsers. For this, fallback properties are pre-generated and included with the npm. +[CSS Custom Properties](https://developer.mozilla.org/en-US/docs/Web/CSS/Using_CSS_custom_properties) are not supported in older browsers. For this, fallback properties are pre-generated and included with the npm. Any update to the Orion Design Tokens will be immediately reflected with browsers that support CSS Custom Properties, legacy browsers will require updated components with pre-generated fallback properties. @@ -56,7 +56,7 @@ class Ods[name] extends LitElement ### Styling (experimental) -Option(s) for component customization. +Option(s) for component customization. [Place relative content here if ::part() is to be considered for support] @@ -64,7 +64,7 @@ Option(s) for component customization. |----|----|----|---| | ::part() | pseudo-element | experimental | Update shadowDOM CSS from outside the component | -See [caniuse.com](https://caniuse.com/#search=%3A%3Apart) for more information. +See [caniuse.com](https://caniuse.com/#search=%3A%3Apart) for more information. ### [name] use cases @@ -100,51 +100,31 @@ Default [name] ## Alternate build solutions -Included with all Orion Custom Elements, the distributed npm contain two additional directories, `./altImportsCanonical` and `./altImportsVariable`. +Why would you need this? With all Orion custom elements the CSS for the element is embedded within the shadow DOM of the custom element. If your development environment is not allowing for the use of shadow DOM elements, the CSS for each element is distributed via additional resources within the npm package. -| directory | description | -|---|---| -| altImportsCanonical† | Sass using canonical values within the scope of the file | -| altImportsVariable* | Sass using CSS Custom Properties within the scope of the file | +[Read more about how to use alternate CSS build resources](https://github.com/AlaskaAirlines/OrionStatelessComponents__docs/blob/master/docs/ALT_BUILD.md) -† Using canonical CSS properties breaks inheritance chain from Orion Design Tokens +## Development -\* Orion Design Tokens are required to import any file using CSS Custom Properties. Also see Orion Design Tokens [pre-processed resources](https://github.com/AlaskaAirlines/OrionDesignTokens#install-pre-processed-resources). PostCSS using `postcss-custom-properties` will need to be added to your project if you are supporting legacy browsers. +In order to develop against this project, if you are not part of the core team, you will be required to fork the project prior to submitting a pull request. -Within the respective directories is the `style_clean.scss` file. +Please be sure to review the [contribution guidelines](.github/CONTRIBUTING.md) for this project. Please make sure to **pay special attention** to the [conventional commits](.github/CONTRIBUTING.md#conventional-commits) section of the document. -```bash -├── altImports -| ├── canonical -| | ├── style.css -| | └── style_clean.scss -| └── variable -| ├── style.css -| └── style_clean.scss -``` +### Start development environment -It is highly recommended that you import the `style_clean.scss` this into a name-space as not to create style collisions. For example: +Once the project has been cloned to your local resource and you have installed all the dependencies you will need to open three different shell sessions. One is for the Gulp tasks, the second is for a series of npm tasks and the last is to run the Polymer server. -```scss -.ods-[name] { - @import "./node_modules/@alaskaairux/ods-[name]/altImports/variable/style_clean.scss"; -} -``` +```shell +// shell terminal one +$ gulp dev -This pattern will produce all the selectors within `style_clean.scss` with the prefixed selector. +// shell terminal two +$ npm run dev -```scss -.ods-[name] .[name] { - display: var(--ods-[name]-display); - font-family: var(--ods-[name]-font-family); - border-width: var(--ods-[name]-border-width); - border-radius: var(--ods-[name]-border-radius); - ... -} +// shell terminal three +polymer serve ``` -**Warning!** Using the canonical CSS will break the chain of using Design Tokens. If Tokens are updated, this will require the update of the components and their canonical output. Use with caution. - ## Alaska Airlines Orion Design System