Google utiliza tecnología de IA para traducir contenido a tu idioma preferido. Las traducciones realizadas con IA pueden contener errores.

Cómo Nordhealth usa propiedades personalizadas en componentes web

Los beneficios de usar propiedades personalizadas en sistemas de diseño y bibliotecas de componentes.

David Darnes

Soy Dave y soy desarrollador de frontend sénior en Nordhealth. Trabajo en el diseño y desarrollo de nuestro sistema de diseño Nord, que incluye la creación de componentes web para nuestra biblioteca de componentes. Quería compartir cómo resolvimos los problemas relacionados con el diseño de los componentes web con las propiedades personalizadas de CSS y algunos de los otros beneficios de usar propiedades personalizadas en sistemas de diseño y bibliotecas de componentes.

Cómo creamos componentes web

Para compilar nuestros componentes web, usamos Lit, una biblioteca que proporciona mucho código estándar, como estado, estilos con alcance, plantillas y mucho más. Lit no solo es liviano, sino que también se basa en APIs nativas de JavaScript, lo que significa que podemos entregar un paquete de código optimizado que aprovecha las funciones que ya tiene el navegador.


import {html, css, LitElement} from 'lit';

export class SimpleGreeting extends LitElement {
  static styles = css`:host { color: blue; font-family: sans-serif; }`;

  static properties = {
    name: {type: String},
  };

  constructor() {
    super();
    this.name = 'there';
  }

  render() {
    return html`Hey ${this.name}, welcome to Web Components!
`;
  }
}
customElements.define('simple-greeting', SimpleGreeting);

Un componente web escrito con Lit.

Sin embargo, lo más atractivo de los componentes web es que funcionan con casi cualquier framework de JavaScript existente o incluso sin ningún framework. Una vez que se hace referencia al paquete principal de JavaScript en la página, usar un componente web es muy similar a usar un elemento HTML nativo. La única señal real de que no es un elemento HTML nativo es el guion coherente dentro de las etiquetas, que es un estándar para indicarle al navegador que se trata de un componente web.

Encapsulamiento de estilo del Shadow DOM

De la misma manera que los elementos HTML nativos tienen un Shadow DOM, también lo tienen los componentes web. El Shadow DOM es un árbol oculto de nodos dentro de un elemento. La mejor manera de visualizar esto es abrir el inspector web y activar la opción "Mostrar árbol del Shadow DOM". Una vez que lo hayas hecho, intenta mirar un elemento de entrada nativo en el inspector. Ahora tendrás la opción de abrir esa entrada y ver todos los elementos que contiene. Incluso puedes probar esto con uno de nuestros componentes web: intenta inspeccionar nuestro componente de entrada personalizado para ver su Shadow DOM.

El shadow DOM inspeccionado en las Herramientas para desarrolladores. — Ejemplo del Shadow DOM en un elemento de entrada de texto normal y en nuestro componente web de entrada de Nord.

Una de las ventajas (o desventajas, según tu perspectiva) del Shadow DOM es la encapsulación de estilos. Si escribes CSS dentro de tu componente web, esos estilos no se filtrarán ni afectarán la página principal ni otros elementos, sino que estarán completamente contenidos dentro del componente. Además, el CSS escrito para la página principal o un componente web superior no puede filtrarse en tu componente web.

Esta encapsulación de estilos es un beneficio en nuestra biblioteca de componentes. Nos da más garantías de que, cuando alguien use uno de nuestros componentes, se verá como lo planeamos, independientemente de los estilos aplicados a la página superior. Y para asegurarnos aún más, agregamos all: unset; a la raíz, o "host", de todos nuestros componentes web.


:host {
  all: unset;
  display: block;
  box-sizing: border-box;
  text-align: start;
  /* ... */
}

Código estándar de un componente que se aplica a la raíz de sombra o al selector de host.

Sin embargo, ¿qué sucede si alguien que usa tu componente web tiene un motivo legítimo para cambiar ciertos estilos? Tal vez haya una línea de texto que necesite más contraste debido a su contexto, o un borde deba ser más grueso. Si no se pueden aplicar estilos a tu componente, ¿cómo puedes desbloquear esas opciones de diseño?

Ahí es donde entran en juego las propiedades personalizadas de CSS.

Propiedades personalizadas de CSS

Las propiedades personalizadas tienen un nombre muy apropiado: son propiedades de CSS a las que puedes asignarles el nombre que quieras y aplicarles el valor que necesites. El único requisito es que les agregues un prefijo con dos guiones. Una vez que hayas declarado tu propiedad personalizada, el valor se puede usar en tu CSS con la función var().


:root {
  --n-color-accent: rgb(53, 89, 199);
  /* ... */
}

.n-color-accent-text {
  color: var(--n-color-accent);
}

Ejemplo de nuestro framework de CSS de un token de diseño como propiedad personalizada y su uso en una clase auxiliar.

En lo que respecta a la herencia, se heredan todas las propiedades personalizadas, lo que sigue el comportamiento típico de las propiedades y los valores de CSS normales. Cualquier propiedad personalizada que se aplique a un elemento superior o al elemento en sí se puede usar como valor en otras propiedades. Usamos mucho las propiedades personalizadas para nuestros tokens de diseño aplicándolas al elemento raíz con nuestro framework de CSS, lo que significa que todos los elementos de la página pueden usar estos valores de token, ya sea un componente web, una clase auxiliar de CSS o un desarrollador que quiera extraer un valor de nuestra lista de tokens.

Esta capacidad de heredar propiedades personalizadas, con el uso de la función var(), es la forma en que atravesamos el Shadow DOM de nuestros componentes web y permitimos que los desarrolladores tengan un control más detallado cuando aplican diseño a nuestros componentes.

Propiedades personalizadas en un componente web de Nord

Cada vez que desarrollamos un componente para nuestro sistema de diseño, adoptamos un enfoque reflexivo para su CSS: nos gusta apuntar a un código eficiente, pero muy fácil de mantener. Los tokens de diseño que tenemos se definen como propiedades personalizadas dentro de nuestro framework de CSS principal en el elemento raíz.


:root {
  --n-space-m: 16px;
  --n-space-l: 24px;
  /* ... */
  --n-color-background: rgb(255, 255, 255);
  --n-color-border: rgb(216, 222, 228);
  /* ... */
}

Propiedades personalizadas de CSS que se definen en el selector raíz.

Luego, se hace referencia a estos valores de tokens dentro de nuestros componentes. En algunos casos, aplicaremos el valor directamente en la propiedad de CSS, pero, en otros, definiremos una nueva propiedad personalizada contextual y le aplicaremos el valor.


:host {
  --n-tab-group-padding: 0;
  --n-tab-list-background: var(--n-color-background);
  --n-tab-list-border: inset 0 -1px 0 0 var(--n-color-border);
  /* ... */
}

.n-tab-group-list {
  box-shadow: var(--n-tab-list-border);
  background-color: var(--n-tab-list-background);
  gap: var(--n-space-s);
  /* ... */
}

Propiedades personalizadas que se definen en la raíz de sombra del componente y, luego, se usan en los estilos del componente. También se usan propiedades personalizadas de la lista de tokens de diseño.

También abstraeremos algunos valores que son específicos del componente, pero que no están en nuestros tokens, y los convertiremos en una propiedad personalizada contextual. Las propiedades personalizadas que son contextuales para el componente nos brindan dos beneficios clave. En primer lugar, significa que podemos ser más "secos" con nuestro CSS, ya que ese valor se puede aplicar a varias propiedades dentro del componente.


.n-tab-group-list::before {
  /* ... */
  padding-inline-start: var(--n-tab-group-padding);
}

.n-tab-group-list::after {
  /* ... */
  padding-inline-end: var(--n-tab-group-padding);
}

La propiedad personalizada contextual de padding del grupo de pestañas se usa en varios lugares dentro del código del componente.

En segundo lugar, hace que los cambios de estado y variación de los componentes sean muy limpios: solo se debe cambiar la propiedad personalizada para actualizar todas esas propiedades cuando, por ejemplo, se aplica un estilo a un estado activo o de desplazamiento o, en este caso, a una variación.


:host([padding="l"]) {
  --n-tab-group-padding: var(--n-space-l);
}

Una variación del componente de pestaña en la que el padding se cambia con una sola actualización de propiedad personalizada en lugar de varias actualizaciones.

Sin embargo, el beneficio más importante es que, cuando definimos estas propiedades personalizadas contextuales en un componente, creamos una especie de API de CSS personalizada para cada uno de nuestros componentes, que el usuario de ese componente puede aprovechar.


<nord-tab-group label="Title">
  <!-- ... -->
</nord-tab-group>

<style>
  nord-tab-group {
    --n-tab-group-padding: var(--n-space-xl);
  }
</style>

Usar el componente de grupo de pestañas en la página y actualizar la propiedad personalizada de relleno a un tamaño mayor

En el ejemplo anterior, se muestra uno de nuestros componentes web con una propiedad personalizada contextual que se cambió con un selector. El resultado de todo este enfoque es un componente que proporciona suficiente flexibilidad de diseño al usuario, a la vez que mantiene bajo control la mayoría de los estilos reales. Además, como beneficio adicional, los desarrolladores de componentes tenemos la capacidad de interceptar esos estilos aplicados por el usuario. Si queremos ajustar o extender una de esas propiedades, podemos hacerlo sin que el usuario tenga que cambiar nada de su código.

Este enfoque nos parece muy potente, no solo para nosotros como creadores de los componentes de nuestro sistema de diseño, sino también para nuestro equipo de desarrollo cuando usa estos componentes en nuestros productos.

Lleva las propiedades personalizadas más allá

En el momento de escribir este artículo, no revelamos estas propiedades personalizadas contextuales en nuestra documentación. Sin embargo, planeamos hacerlo para que nuestro equipo de desarrollo más amplio pueda comprender y aprovechar estas propiedades. Nuestros componentes se empaquetan en npm con un archivo de manifiesto, que contiene todo lo que hay que saber sobre ellos. Luego, consumimos el archivo de manifiesto como datos cuando se implementa nuestro sitio de documentación, lo que se hace con Eleventy y su función de datos globales. Planeamos incluir estas propiedades personalizadas contextuales en este archivo de datos de manifiesto.

Otra área que queremos mejorar es cómo estas propiedades personalizadas contextuales heredan los valores. Ahora, por ejemplo, si quisieras ajustar el color de dos componentes de divisor, tendrías que orientar ambos componentes específicamente con selectores o aplicar la propiedad personalizada directamente en el elemento con el atributo de estilo. Esto puede parecer correcto, pero sería más útil si el desarrollador pudiera definir esos estilos en un elemento contenedor o incluso en el nivel raíz.


<nord-divider></nord-divider>

<section>
  <nord-divider></nord-divider>
   <!-- ... -->
</section>

<style>
  nord-divider {
    --n-divider-color: var(--n-color-status-danger);
  }

  section {
    padding: var(--n-space-s);
    background: var(--n-color-surface-raised);
  }
  
  section nord-divider {
    --n-divider-color: var(--n-color-status-success);
  }
</style>

Dos instancias de nuestro componente divisor que necesitan dos tratamientos de color diferentes. Uno está anidado dentro de una sección que podemos utilizar para un selector más específico, pero tenemos que apuntar al divisor específicamente.

El motivo por el que debes establecer el valor de la propiedad personalizada directamente en el componente es que los definimos en el mismo elemento con el selector de host del componente. Los tokens de diseño globales que usamos directamente en el componente pasan directamente, sin verse afectados por este problema, y hasta se pueden interceptar en los elementos superiores. ¿Cómo podemos obtener lo mejor de ambos mundos?

Propiedades personalizadas privadas y públicas

Las propiedades personalizadas privadas son un concepto que creó Lea Verou, que es una propiedad personalizada "privada" contextual en el componente, pero que se establece en una propiedad personalizada "pública" con un resguardo.



:host {
  --_n-divider-color: var(--n-divider-color, var(--n-color-border));
  --_n-divider-size: var(--n-divider-size, 1px);
}

.n-divider {
  border-block-start: solid var(--_n-divider-size) var(--_n-divider-color);
  /* ... */
}

El CSS del componente web divisor con las propiedades personalizadas contextuales ajustadas para que el CSS interno dependa de una propiedad personalizada privada, que se estableció en una propiedad personalizada pública con un resguardo.

Definir nuestras propiedades personalizadas contextuales de esta manera significa que podemos seguir haciendo todo lo que hacíamos antes, como heredar valores de tokens globales y reutilizar valores en todo el código de nuestro componente, pero el componente también heredará de forma elegante nuevas definiciones de esa propiedad en sí mismo o en cualquier elemento superior.


<nord-divider></nord-divider>

<section>
  <nord-divider></nord-divider>
   <!-- ... -->
</section>

<style>
  nord-divider {
    --n-divider-color: var(--n-color-status-danger);
  }

  section {
    padding: var(--n-space-s);
    background: var(--n-color-surface-raised);
    --n-divider-color: var(--n-color-status-success);
  }
</style>

Nuevamente, los dos divisores, pero esta vez se puede cambiar el color del divisor agregando la propiedad personalizada contextual del divisor al selector de sección. El divisor lo heredará, lo que producirá un fragmento de código más limpio y flexible.

Si bien se puede argumentar que este método no es realmente "privado", creemos que es una solución bastante elegante para un problema que nos preocupaba. Cuando tengamos la oportunidad, abordaremos este problema en nuestros componentes para que nuestro equipo de desarrollo tenga más control sobre el uso de los componentes y, al mismo tiempo, se beneficie de las protecciones que tenemos implementadas.

Espero que esta información sobre cómo usamos los componentes web con las propiedades personalizadas de CSS te resulte útil. Cuéntanos qué te parece y, si decides usar alguno de estos métodos en tu propio trabajo, puedes encontrarme en Twitter @DavidDarnes. También puedes encontrar a Nordhealth @NordhealthHQ en Twitter, así como al resto de mi equipo, que trabajó arduamente para reunir este sistema de diseño y ejecutar las funciones mencionadas en este documento: @Viljamis, @WickyNilliams y @eric_habich.

Cómo Nordhealth usa propiedades personalizadas en componentes web Organiza tus páginas con colecciones Guarda y categoriza el contenido según tus preferencias.