Part y exportparts para aplicar estilos externos

La estricta encapsulación de estilos de Shadow DOM impide que los consumidores vuelvan a aplicar estilos a elementos individuales dentro de un componente. Las variables CSS funcionan para propiedades globales, pero, por ejemplo, no puede asignar un border-radius personalizado al botón interno "close". Para eso sirven los parts.

Marque un elemento interno del shadow con part="name". Los consumidores podrán seleccionarlo mediante el pseudoelemento ::part(name): my-dialog::part(close-button) { color: red; }. El elemento con nombre se convierte en un punto de extensión para aplicar estilos, mientras el resto del shadow permanece encapsulado.

Separe los nombres con espacios para exponer un elemento como varios parts: part="button primary". ::part(button) lo selecciona de forma genérica, mientras que ::part(primary) lo selecciona como un elemento de estilo principal. Cada nombre se compara de forma independiente.

::part solo permite determinadas pseudoclases (:hover, :focus, :disabled), no combinadores de descendientes ni selecciones estructurales adicionales. ::part(card) p no es válido; no puede acceder al interior de un part mediante selectores de descendientes.

Cuando un elemento personalizado anida otro elemento personalizado dentro de su propio shadow, los parts del elemento interno normalmente no se exponen a la página exterior. El atributo exportparts="close-button" del elemento anidado reenvía esos parts al host exterior.

exportparts="close-button: dismiss" exporta el part interno con un nombre nuevo en el elemento exterior. Esto permite que el componente exterior ofrezca una interfaz de nombres clara, independientemente de los elementos internos que componga.

Las propiedades personalizadas exponen valores (colores, espaciado y fuentes). Los parts exponen elementos (toda la superficie CSS: bordes, transformaciones y animaciones). Use propiedades personalizadas para los tokens globales y parts para personalizaciones puntuales a nivel de elemento. Ambos pueden coexistir en el mismo componente.

Una práctica habitual en los sistemas de diseño consiste en exponer una pequeña superficie de parts para los elementos que más se personalizan (botones, encabezados e indicadores), además de un conjunto amplio de propiedades personalizadas para el color, el espaciado y la tipografía. Los consumidores pueden tematizar el componente a nivel de valor o de elemento, según sus necesidades.

Los nombres de part pasan a formar parte de la API pública del componente; cambiarlos rompe el CSS de los consumidores. Elija nombres que describan el papel del elemento ("close-button", "header", "track") en lugar de su posición ("first-button"), para que la API siga siendo significativa a medida que evoluciona la implementación.

Enumere todos los parts disponibles (y los parts exportados) en el readme del componente. Sin documentación, los consumidores deben inspeccionar el DOM para descubrir los parts, lo que los acopla a lo que encuentren en ese momento. Trate la lista de parts como la lista de props de un componente de un framework.

::part y exportparts están disponibles en todos los navegadores modernos. Incluso las versiones antiguas de Safari ya son compatibles con ::part. Úselos sin problemas; para navegadores muy antiguos (en su mayoría obsoletos), recurra a propiedades personalizadas de CSS adicionales como alternativa.

El atributo part expone elementos shadow individuales para aplicarles estilos externamente mediante ::part(name), con toda la potencia de CSS sin romper la encapsulación. exportparts reenvía los parts de elementos personalizados anidados al host exterior y permite cambiarles el nombre. Combine parts con propiedades personalizadas de CSS para obtener una superficie de tematización completa y documente la lista de parts como parte de la API del componente.