Add CSS var + CSS part section

pull/168/head
Cory LaViska 2020-08-07 07:44:00 -04:00
rodzic e96705a6ae
commit 31caeb7bed
1 zmienionych plików z 10 dodań i 0 usunięć

Wyświetl plik

@ -102,6 +102,16 @@ When designing a component's API, standard properties ("props") are generally us
There are some exceptions to this (e.g. when it significantly improves developer experience), but a good rule of thumbs is "will this need to change based on screen size?" If so, you probably want to use a CSS variable.
### When to use a CSS custom property vs. a CSS part
There are two ways to enable customizations for components. One way is with CSS custom properties ("CSS variables"), the other is with CSS parts ("parts").
CSS variables are scoped to the host element and can be reused throughout the component. A good example of a CSS variable would be `--border-width`, which might get reused throughout a component to ensure borders share the same width for all internal elements.
Parts let you target a specific element inside the component's shadow DOM but, by design, you can't target a part's children or siblings. You can _only_ customize the part itself. Use a part when you need to allow a single element inside the component to accept styles.
This convention can be relaxed when the developer experience is greatly improved by not following these suggestions.
### Boolean Props
Boolean props should _always_ default to `false`, otherwise there's no way for the user to unset it without JavaScript. To keep the API as friendly and consistent as possible, use a name like `noHeader` with a default value of `false` instead of `header` with a default value of `true`.