@l9/style

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.

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.