Cómo inspeccionar props de web components: guía para desarrolladores de sistemas de diseño

Pasas el cursor sobre un <ui-card> en DevTools y aparece la pregunta: ¿qué props acepta realmente este componente? El panel de atributos te muestra variant="elevated" y poco más, y ahora estás tres archivos adentro del código fuente tratando de reconstruir su API.

Inspeccionar props de web components debería ser una operación de un solo clic. Casi nunca lo es. Veamos por qué las herramientas estándar del navegador se quedan cortas, qué información necesitas ver de verdad y cómo convertir esto en una parte rápida y repetible de tu flujo de trabajo.

Por qué DevTools no muestra el panorama completo

Abre cualquier página que use un sistema de diseño basado en elementos personalizados. Inspecciona un componente. ¿Qué ves en el panel de Elements?

<ui-card variant="elevated" size="md" data-testid="featured-post">
  #shadow-root (open)
    ...
</ui-card>

Ves la etiqueta. Ves los atributos que están definidos en esta instancia. Lo que no ves es la interfaz completa del componente: las props que podría aceptar pero que ahora no tiene definidas, las que están en su valor por defecto, las que nadie llegó a documentar.

Esa brecha te cuesta cuando:

• Un diseñador te entrega una especificación y necesitas saber si una prop ya existe antes de escribir código nuevo
• Estás auditando una página para entender por qué un componente se ve mal
• Estás incorporando a un desarrollador nuevo que nunca ha visto tu sistema de diseño

Los atributos visibles en el DOM son una instantánea parcial del estado, no el contrato del componente.

Atributos vs. propiedades: la distinción que confunde a todos

Los elementos personalizados exponen dos interfaces paralelas, y confundirlas es de donde viene la mayor parte del dolor.

Los atributos son lo que ves en el markup. Siempre son cadenas de texto, los lees con getAttribute() y viven en el DOM.

Las propiedades son valores JavaScript en el objeto del elemento: booleanos, números, arrays, objetos completos. Viven en memoria y no necesariamente tienen un atributo equivalente. Un atributo y una propiedad pueden compartir nombre y mantenerse vinculados de forma laxa (un elemento puede reflejar su propiedad disabled a un atributo disabled), pero ese reflejo solo ocurre si quien escribió el componente programó el código para hacerlo.

<!-- Atributo — visible en el markup -->
<ui-button disabled>Enviar</ui-button>

// Propiedad — solo visible en JS
document.querySelector('ui-button').loading = true;

Supongamos que un componente acepta una propiedad loading que activa un spinner interno. Si quien lo escribió nunca la refleja a un atributo loading, definirla no deja rastro en el panel de Elements. Para encontrarla abres la consola, tomas el elemento y empiezas a recorrer su cadena de prototipos. Se puede, pero es el tipo de fricción que convierte una pregunta de 30 segundos en una pausa para el café.

El DOM muestra lo que está definido. No muestra lo que es posible.

El flujo de trabajo real del desarrollador de sistemas de diseño

Cuando construyes o consumes una biblioteca de componentes, lo que realmente necesitas responder rápido es:

1. ¿Qué etiqueta es este elemento?
2. ¿Qué atributos/props tiene definidos actualmente?
3. ¿A qué prefijo pertenece este componente (ui-, app-, ds-)?

El tercer punto importa en cuanto varios equipos publican componentes dentro de la misma aplicación. Un <ui-card> del sistema de diseño central y un <app-card> de un equipo de producto son componentes sin relación que casualmente se parecen en el DOM. Filtrar por prefijo, para ver todos los elementos ui- de una página al mismo tiempo, es la diferencia entre una auditoría del sistema de diseño que toma minutos y una que toma una tarde entera.

Cómo inspeccionar un elemento personalizado paso a paso

El enfoque manual más confiable:

// Obtener el elemento
const el = document.querySelector('ui-card');

// Ver todos los atributos reflejados
console.log(el.attributes);

// Inspeccionar sus propias propiedades (no heredadas)
console.log(Object.getOwnPropertyNames(Object.getPrototypeOf(el)));

Funciona, pero genera ruido. getOwnPropertyNames sobre el prototipo trae lo que define la clase, y un nivel más arriba quedas nadando entre métodos heredados de HTMLElement. Pasas más tiempo filtrando que leyendo.

Un enfoque más limpio: preguntarle a la propia clase qué atributos observa.

customElements.whenDefined('ui-card').then(() => {
  const ctor = customElements.get('ui-card');
  console.log(ctor.observedAttributes);
});

observedAttributes es el array estático que el componente declara para recibir llamadas a attributeChangedCallback cuando esos atributos cambian. Es lo más cercano a una superficie de API publicada que puedes leer sin abrir el código fuente. Dos limitaciones: el componente solo lista los atributos a los que reacciona activamente, así que no garantiza ser el conjunto completo, y no dice nada sobre APIs exclusivas de propiedades, como ese loading de antes.

Por qué un filtro de prefijo cambia la auditoría

Imagina una auditoría de adopción. Necesitas saber qué componentes de una página de producto ya usan el sistema canónico ui- y cuáles siguen en las versiones legacy- que se suponía debían migrarse el trimestre pasado. Hecho a mano, eso es leer cada nodo del árbol del DOM y llevar la cuenta en tu cabeza.

Un filtro de prefijo de componentes le da la vuelta. Escribes ui- y obtienes cada elemento personalizado de la página que coincide, con sus atributos actuales; escribes legacy- y ahí tienes tu backlog de migración. Es el tipo de inspección dirigida para la que un panel de elementos de propósito general nunca fue pensado.

La herramienta de Componentes de PxGuard está construida exactamente para este caso de uso. Muestra cada elemento personalizado en la página con su nombre de etiqueta y atributos activos, y permite filtrar por prefijo de componente para que puedas centrarte en los componentes de tu sistema de diseño sin navegar por elementos no relacionados. Es la respuesta a “¿qué es esto y qué tiene?” — directamente en el navegador, sin acrobacias en la Consola.

Si escribes componentes, hazlos inspeccionables

Buena parte de esta fricción es autoinfligida. Unos pocos hábitos hacen que tus componentes sean legibles para cualquiera que los depure después, incluido tu yo del futuro.

Refleja las props que la gente va a querer inspeccionar o estilizar. Si un desarrollador razonablemente podría seleccionar variant con CSS o leerlo en DevTools, refléjalo a un atributo dentro del setter. element.setAttribute('variant', value) son un par de líneas y hacen que la prop sea visible en todos lados.

Lista tus atributos en observedAttributes aunque manejes algunos de forma diferida. El array funciona también como documentación: lo leen las herramientas y también las personas que revisan tu clase por encima.

Cuidado con los valores por defecto silenciosos. Una prop size que tiene "md" por defecto no deja rastro en el DOM hasta que alguien la define explícitamente, así que la configuración más común es justo la que no puedes ver. Documéntala, y refléjala si vale la pena exponerla.

Y elige un prefijo por equipo y respétalo. ui- para el núcleo, app- para el producto, mkt- para marketing. Esa consistencia es lo que vuelve posible una auditoría a nivel de página.

Más recursos

• El modelo de caja de CSS, explicado — cómo funciona el espaciado dentro de tus componentes
• Errores de espaciado en CSS — las inconsistencias de espaciado que se infiltran en los sistemas de diseño
• Tu revisión WCAG en 5 minutos — lo básico de accesibilidad que todo desarrollador de sistemas de diseño debería conocer
• Cómo detectar imágenes estiradas y sobredimensionadas — la herramienta complementaria para detectar regresiones visuales

---

Instala PxGuard gratis →