From 31caeb7bedf68a48238e72ea8132f3c8b01abf8f Mon Sep 17 00:00:00 2001 From: Cory LaViska Date: Fri, 7 Aug 2020 07:44:00 -0400 Subject: [PATCH] Add CSS var + CSS part section --- CONTRIBUTING.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 085b3353..bd3ae3ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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`.