Un componente que funcionaba y no renderizaba nada

El paquete de analítica con consentimiento tiene dos componentes visuales. Uno es un aviso flotante que lee propiedades personalizadas de CSS, --surface, --fg, --accent, con valores de reserva razonables para modo oscuro ya incorporados. Si una app consumidora ya define esas variables, y la mayoría de los sitios de la familia lo hace porque es una convención compartida, el aviso coincide con el tema del sitio sin CSS adicional. Genuinamente sin configuración, y el README lo dice.

El otro componente, un explicador para la página /privacy, está estilizado enteramente con clases de utilidad de Tailwind: text-fg, text-muted, space-y-12. Los mismos nombres de token, un mecanismo de entrega completamente distinto. Y la sección de Styling del README solo describía el contrato del primer componente.

Cómo se ve realmente “sin estilo en silencio”

Un componente de propiedades personalizadas de CSS que no recibe configuración simplemente usa sus valores de reserva. Nada se rompe, nada se ve mal, en el peor de los casos no combina perfectamente con el tema del sitio.

Un componente de utilidades de Tailwind que no recibe configuración es una falla completamente distinta. Las clases de utilidad hacen referencia a colores que nunca se generaron en el CSS compilado del sitio, porque Tailwind solo genera las clases que puede ver referenciadas en archivos que coinciden con el glob de content configurado. Un nuevo consumidor que lea solo la sección de Styling existente configuraría las propiedades personalizadas de CSS, conectaría bien el aviso, agregaría PrivacyExplainer, y obtendría una pared de texto sin estilo, sin ningún error, ninguna advertencia, nada en la consola.

Funciona, en el sentido que más importa, el explicador se alimenta deliberadamente en forma directa de la configuración de analítica activa, así que su contenido nunca puede desviarse de lo que realmente se inyecta. Simplemente no se ve como nada.

Esa brecha solo existe porque dos componentes en el mismo paquete eligieron en silencio dos estrategias de estilo distintas, y solo una de esas estrategias quedó documentada. Un paquete compartido que se desincroniza consigo mismo se está volviendo un tema recurrente en esta familia de repositorios.

La solución fue reafirmar una decisión, no tomar una nueva

Había dos caminos sobre la mesa: documentar el requisito real, o reescribir el componente sobre el mismo contrato de propiedades personalizadas de CSS que el aviso, para que el paquete cuente una historia de estilo consistente. Opté por documentar.

Reescribir habría significado re-derivar cada decisión de espaciado y color como estilos en línea impulsados por propiedades personalizadas en vez de utilidades de Tailwind, trabajo real para un componente que ya renderiza correctamente una vez que existen las dos líneas de configuración faltantes. El camino de menor riesgo era hacer visible el requisito existente, no eliminarlo.

El agregado son dos líneas que hacen falta: crear alias de los colores de token en tailwind.config.mjs (el mismo bloque que el paquete hermano de blog ya documenta), e incluir este paquete en el glob de content de Tailwind. Ahora escrito en el único lugar donde alguien realmente miraría antes de conectar el componente.

Qué revisaría la próxima vez

Cuando un paquete tiene más de un componente visual, conviene revisar si todos realmente comparten un contrato de estilo antes de escribir, o confiar en, una única sección de Styling que describe solo uno de ellos. “El README tiene una sección de Styling” no es la misma afirmación que “la sección de Styling del README cubre todo lo que necesita estilo.”