diff --git a/docs/README.md b/docs/README.md index 85cbbc9422d..bd2021581ce 100644 --- a/docs/README.md +++ b/docs/README.md @@ -23,6 +23,7 @@ It is based on Web Componen | [Contributing](./CONTRIBUTING.md) | How to contribute including creating pull requests, commit message guidelines, and more. | | [Component Guide](./component-guide.md) | Guidelines for implementing component states, accessibility, and more. | | [Sass Guidelines](./sass-guidelines.md) | Outlines scenarios where Sass members and comments should be used. | +| [CSS Shadow Parts Guidelines](./shadow-parts-guidelines.md) | Guidelines for CSS shadow parts in components. | ## Packages diff --git a/docs/component-guide.md b/docs/component-guide.md index 03b3ab9f761..6f72aeec110 100644 --- a/docs/component-guide.md +++ b/docs/component-guide.md @@ -17,6 +17,8 @@ * [Example Components](#example-components-4) * [Component Structure](#component-structure-1) - [Converting Scoped to Shadow](#converting-scoped-to-shadow) +- [Sass Variables](#sass-variables) +- [CSS Shadow Parts](#css-shadow-parts) - [RTL](#rtl) - [Adding New Components with Native Input Support](#adding-new-components-with-native-input-support) * [Angular Integration](#angular-integration) @@ -722,6 +724,14 @@ There will be some CSS issues when converting to shadow. Below are some of the d :host-context(ion-toolbar:not(.ion-color)):host(:not(.ion-color)) ::slotted(ion-segment-button) { ``` +## Sass Variables + +For guidelines on when to use Sass Variables, see the [Sass Guidelines](./sass-guidelines.md). + +## CSS Shadow Parts + +For guidelines on adding CSS shadow parts, see the [CSS Shadow Parts Guidelines](./shadow-parts-guidelines.md). + ## RTL When you need to support both LTR and RTL modes, try to avoid using values such as `left` and `right`. For certain CSS properties, you can use the appropriate mixin to have this handled for you automatically. diff --git a/docs/sass-guidelines.md b/docs/sass-guidelines.md index d48d496df54..3b3e104fd23 100644 --- a/docs/sass-guidelines.md +++ b/docs/sass-guidelines.md @@ -1,5 +1,6 @@ # Sass Guidelines +TABLE OF CONTENTS - [Definitions](#definitions) - [Scope](#scope) - [Historical Usage](#historical-usage) diff --git a/docs/shadow-parts-guidelines.md b/docs/shadow-parts-guidelines.md new file mode 100644 index 00000000000..a2dac311636 --- /dev/null +++ b/docs/shadow-parts-guidelines.md @@ -0,0 +1,277 @@ +# CSS Shadow Parts Guidelines + +TABLE OF CONTENTS +- [Definitions](#definitions) +- [Scope](#scope) +- [General Guidelines](#general-guidelines) +- [Standard Parts](#standard-parts) +- [Specialized Parts](#specialized-parts) +- [Documentation](#documentation) + +## Definitions + +**CSS Shadow Parts:** The CSS shadow parts module defines the [::part()](https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Selectors/::part) pseudo-element that can be set on a [shadow host](https://developer.mozilla.org/en-US/docs/Glossary/Shadow_tree). Using this pseudo-element, you can enable shadow hosts to expose the selected element in the shadow tree to the outside page for styling purposes. [^1] + +## Scope + +Ionic Framework components that use Shadow DOM expose CSS Shadow Parts to enable custom styling by end users. + +This document establishes a standardized naming convention for CSS Shadow Parts in Ionic Framework components. + +## General Guidelines + +1. **Attempt to use standard parts first**: Use `native`, `wrapper`, `inner`, `container`, and `content` wherever they apply before inventing new names. +2. **Use semantic, kebab-case names**: Choose descriptive names that communicate the role of the element (for example, `detail-icon`, `supporting-text`). +3. **Reuse names for the same concept**: Use the same part name across components when the element serves the same role (for example, `backdrop`, `handle`, `label`). + +## Standard Parts + +**Name parts by what the element does, not where it appears.** Ask what role the element plays: + +| Name | Role | +| --- | --- | +| `native` | Is it a native HTML element that the user interacts with (e.g. `