npm package: @l9/style
Description: Layer9 style helpers
Author: Layer9 GmbH
Latest version: 0.0.27

# Styling components

## Style encapsulation

Web Components use style encapsulation, which helps to prevent CSS hell, but introduces an additional layer of complication. In general, there are four ways of styling content within a component without adapting the component itself. In order of preferability:

1. Set general styling rules such as `font-family` from the outside. Style inheritance works as usual despite style encapsulation. However, this approach won't work for non-inheritable properties and for cases where specific elements need to be targeted (e.g. to change `font-family` for all `h3` elements within a component).
2. Content that is inserted into a component via a slot can be styled just as if it remained part of the outer light DOM. This allows arbitrary styling changes, but only applies to the inserted content, not to content within the component, nor the slot's default content.
3. If the component's author has taken care to define its styling in terms of custom properties, these can be set from the outside.
4. Style the host element from the outside. While this may be useful in certain cases, it is discouraged in general, as it is not particularly powerful and might lead to unpredictable behaviour.

We use the first three mechanisms for skinning. A skin CSS file 

1. defines inheritable properties at the page level,
2. directly styles elements within the page's light DOM (including elements slotted into components) and
3. defines a lot of custom properties, which each component can use to change its inner styling in a pre-defined, predictable way.

As example for the third mechanism, if the `foo` component defines a rule
```
h3 { 
  font-family: var(--foo-font-family), sans-serif;
}
```
then the font-family of `h3` elements within the component can be changed by setting
```
foo { 
  --foo-font-family: 'Bar';
}
```
To make things a little bit easier for the creator of a skin CSS file, each component offers mixins in the form of a `_skin.sass` file that will in turn set the required custom properties. For example, the `_skin.sass` might define a mixin
```
=foo-font-family($font-family)
  --foo-font-family: #{$font-family}
```
which can be used to create a `custom-skin.css` file without needing to set individual custom properties:
```
+foo-font-family('Foo')
```
## Creating a skin

In order to create a skin, use the mixins inside the `@l9/style` module for mechanisms 1. and 2. and the mixins in each component's `_skin.sass` file for mechanism 3. If you keep your `custom-skin.sass` within the demo directory, the gulp task `watch-demo-styles` will automatically compile the file. On your own page, you might want to set up file watchers yourself.

![](style-workflow-skin.png)

## Styling a component

For maintainability, component style rules are organised into partials each dealing with different aspects of styling
* animation (`transition`, `@keyframes` etc.)
* appearance (`color`, `background`, `border`, etc.)
* layout (`margin`, `padding`, CSS grid definitions etc.)
* typography (`font-family`, `letter-spacing` etc.)

The gulp task `watch-partials` will watch changes to the partials and inject the compiled content into the component's `index.js` file, provided that it contains a suitable insertion marker.

![](style-workflow-component.png)