Integración de Librería de Íconos — Explainer de Alcance

Qué significa y por qué importa

Qué incluye SessDev

• Selección entre librerías mantenidas soportadas (Lucide como default, Heroicons como alternativa) con una recomendación liviana basada en cobertura de categorías y bundle size.
• Ingesta de íconos SVG provistos por el cliente mediante handoff estructurado: optimizados vía SVGO, validados por consistencia de stroke/fill, organizados en una única carpeta.
• Imports tree-shaken para que solo los íconos efectivamente renderizados se envíen al cliente; delta de bundle verificado por ícono agregado.
• Un set de tokens de sizing (xs, sm, md, lg, xl) cableado en el componente Icon para que cada consumidor referencie tamaños por intención, no por valores raw de píxeles.
• Color binding mediante currentColor y los tokens de color ya en alcance, de modo que los íconos hereden el foreground y respeten variantes dark/light automáticamente.
• Wiring de accesibilidad: aria-hidden por default para íconos decorativos, aria-label o title para íconos significativos, role=img cuando aplica, comportamiento focus-visible para íconos interactivos.
• Un único componente Icon como entry point exclusivo, con nombres de íconos tipados en TypeScript de modo que íconos no soportados fallen en build time, no en runtime.
• 1 pasada de validación: check de a11y Lighthouse en componentes con íconos, verificación de bundle size, chequeo de compatibilidad de licencia para la librería seleccionada.
• Documento de handoff que lista la librería seleccionada (con versión pinneada), la estructura de carpeta de íconos provistos, el contrato de tokens de sizing/color y el procedimiento para agregar un ícono sin tocar código de componentes.

Qué queda excluido

• Ilustración de íconos custom — dibujar íconos a medida, diseñar pictogramas específicos para features del producto, o extender una librería existente con glyphs custom.
• Diseño de sistema de íconos — definir stroke widths, corner radii, sistemas de grilla, reglas de corrección óptica o el lenguaje visual que sigue una familia de íconos.
• Research de iconografía, audits competitivos de sets de íconos, análisis de íconos por categoría o reviews de significado cultural.
• Autoría de iconografía de brand — íconos signature que doblan como marcas de brand, hero icons para páginas de marketing, variantes de app icon más allá del favicon bundle cubierto en brand-asset injection.
• Diseño de mascotas, ilustración de personajes o cualquier autoría de marca antropomórfica.
• Trabajo de ilustración — spot illustrations, ilustraciones de empty-state, hero illustrations o cualquier asset visual no-ícono.
• Autoría de íconos animados o archivos Lottie; el wiring de un asset de ícono animado existente está cubierto por el alcance de UI animation.
• Audit del set de íconos provisto, gap analysis contra necesidades del producto o recomendaciones para agregar o quitar íconos.
• Research multilingüe de pictogramas — verificar significado de íconos a través de culturas, sourcing de símbolos específicos por locale, o guidance de mirroring RTL para íconos direccionales.
• Expansión del set de íconos provisto — encargar íconos faltantes a un ilustrador, pedir variantes al autor de la librería, o backfill de categorías que la librería no cubre.
• Autoría de la documentación del sistema de iconografía de brand — reglas de uso, grillas do/don't, secciones de brand guidelines sobre iconografía.

Riesgos si no se define correctamente

• Sprawl de íconos a través de múltiples librerías

  Mezclar Lucide con Heroicons con SVGs sueltos de varias fuentes produce UI visualmente inconsistente e infla el bundle. El alcance enforça una librería primaria más una única carpeta de íconos provistos; la disciplina continua a medida que se envían nuevos componentes es lo que enforça el retainer Care.

• Labels de accesibilidad faltantes en íconos significativos

  Un botón icon-only sin aria-label es invisible para tecnología asistiva, rompiendo WCAG 4.1.2 y exponiendo al producto a reclamos de cumplimiento de accesibilidad. El componente Icon en alcance enforça la intención explícita decorativo vs significativo; bypassearlo re-introduce el riesgo.

• Bloat de payload por imports no tree-shakeados

  Importar una librería entera de íconos como default export envía cientos de íconos no usados a cada usuario. El wiring en alcance usa imports por ícono verificados para tree-shaking; un refactor futuro que rompa el patrón de import puede re-introducir el bloat silenciosamente.

• Brand drift por iconografía de librerías mezcladas

  Lucide y Heroicons siguen filosofías diferentes de stroke y corner. Mezclarlas dentro de una misma pantalla produce una inconsistencia visual que los usuarios perciben sin poder nombrarla. El handoff documenta la regla de una sola librería; enforzarla a largo plazo es responsabilidad del retainer Care.

• Sizing inconsistente entre consumidores

  Valores hardcoded en píxeles en íconos individuales (size=20, size=18, size=22) anulan el sistema de tokens de sizing y producen UI ópticamente irregular. El componente Icon en alcance solo acepta valores de token; reemplazarlo por imports raw de la librería re-abre el riesgo.

• Exposición a vulnerabilidades SVG por íconos sin sanitizar

  SVGs provistos por el cliente que retengan scripts inline, foreign objects o referencias remotas pueden ejecutarse en el browser cuando se inlinean. El paso de ingesta en alcance corre SVGO con config de sanitización estricta; bypassearlo para un solo ícono re-abre el vector de vulnerabilidad.

• Violaciones de licencia de íconos

  Lucide se distribuye bajo ISC y Heroicons bajo MIT, pero los íconos provistos por el cliente pueden traer licencias restrictivas (sets pagos, marcas con royalty, CC-NC-only). El paso de validación chequea compatibilidad de licencia para la carpeta provista; agregar íconos de sets pagos después sin un chequeo de licencia es la causa de drift más común post-launch.

Ítems de alcance relacionados

• brand_asset_injectionLos app icons y favicons viven en brand-asset injection; los íconos glyph a nivel producto viven acá. Mismo principio de exclusión: integración, no autoría.
• color_token_setupLos íconos heredan el foreground mediante los tokens de color definidos en el alcance de color tokens; las variantes dark/light fluyen automáticamente.
• typography_integrationLas librerías de íconos basadas en font pueden enviarse como fuentes; cablear una icon-font existente está cubierto acá, autorearla no.
• ui_animation_implementationLos íconos animados (Lottie, motion variants) se cablean mediante el alcance de UI animation usando los archivos de animación provistos.
• media_infrastructureLos SVGs inlineados usan las mismas primitivas de delivery que las imágenes para caching y reglas de CSP.
• technical_seoEl peso del payload de íconos alimenta Core Web Vitals (LCP) cableado mediante el alcance de technical SEO.

Preguntas frecuentes

¿Qué librería de íconos usan por default?

Lucide es el default para builds nuevos (licencia ISC, cobertura amplia, mantenimiento activo). Heroicons es la alternativa soportada cuando el equipo de diseño prefiere su estilo. Otras librerías pueden cablearse pero se convierten en una decisión liderada por el cliente y pueden traer implicaciones de licencia.

¿SessDev puede dibujar íconos custom para nosotros?

No. La ilustración de íconos custom es un entregable de la disciplina de ilustración y está explícitamente fuera de alcance. SessDev integra los íconos SVG que tu equipo de diseño o ilustrador externo provea, ingestados mediante handoff estructurado.

¿Pueden diseñar un sistema de íconos para nuestro brand?

No. El diseño de sistema de íconos — stroke widths, sistemas de grilla, reglas de corrección óptica, reglas de iconografía de brand — es un entregable del brand system y está fuera de alcance. SessDev integra el sistema que tu equipo de diseño entregue.

¿Cómo manejan la accesibilidad de los íconos?

El componente Icon en alcance enforça una elección explícita decorativo vs significativo a nivel API: los íconos decorativos reciben aria-hidden, los significativos requieren un aria-label. Los botones icon-only interactivos requieren un label en build time, no en runtime.

¿Se tree-shakeará el layer de íconos?

Sí. El wiring usa imports por ícono verificados para tree-shaking, y el paso de validación confirma el delta de bundle por ícono. Solo los íconos efectivamente renderizados se envían al cliente.