design_system/docs/research.md

Investigación y decisiones

Investigación realizada el 10 de agosto de 2026. Se priorizaron fuentes oficiales y especificaciones.

Fuentes consultadas

• Vue: TypeScript con Composition API: props y emits tipados con <script setup>.
• Vue: descripción general de TypeScript: Vite transpila y vue-tsc realiza la comprobación estática.
• Vite: modo librería: entrada build.lib, externalización de dependencias y distribución de CSS.
• Tailwind CSS: variables de tema: configuración CSS-first y tokens disponibles como variables CSS.
• Tailwind CSS: detección de clases: una librería fuente externa exige @source; las clases deben existir de forma completa.
• Tailwind CSS: funciones y directivas: @reference es necesario para usar @apply en bloques de estilo procesados por separado.
• Tailwind CSS: compatibilidad: Tailwind v4 está diseñado para navegadores modernos.
• WAI-ARIA Authoring Practices: patrones: comportamiento esperado para botones, tabs, diálogos, radio groups y switches.
• WAI-ARIA APG: Dialog modal: nombre accesible, foco contenido, Escape y retorno de foco.
• WAI-ARIA APG: Tabs: flechas, Home, End, roving tabindex y relación tab/panel.
• WCAG 2.2, Focus Appearance y Status Messages: foco perceptible y anuncios sin cambios de contexto.
• MDN: elemento dialog y showModal(): top layer, fondo inerte, Escape y colocación inicial del foco.

Decisiones derivadas

Distribución

Vite construye una entrada ES y externaliza Vue. El paquete publica declaraciones TypeScript, index.js y design-system.css. vue es peerDependency para evitar dos runtimes en una aplicación.

El CSS se importa desde la entrada durante el build para garantizar su extracción, pero se expone como @omaresquivel/design-system/style.css y se documenta su importación explícita. sideEffects conserva los archivos CSS durante tree-shaking.

Tailwind y estilos

Se distribuye CSS compilado. Esta decisión evita que cada consumidor instale Tailwind, configure @source para node_modules o replique bloques @apply. Tailwind queda como herramienta interna y el resultado se controla mediante variables CSS semánticas.

Los componentes usan clases globales con namespace ds- en una única capa components. No se ejecuta Tailwind por cada <style scoped>, siguiendo su advertencia sobre el coste y el contexto aislado de los estilos SFC. Los nombres prefijados evitan colisiones y las variables conservan la capacidad de theming.

Accesibilidad

• Controles de formulario nativos antes que widgets ARIA recreados.
• <dialog>.showModal() para obtener top layer e inertización nativas en los navegadores objetivo.
• Tabs implementadas con el patrón APG y activación automática porque sus paneles son locales e inmediatos.
• Estados dinámicos anuncian status o alert solo mediante la prop live; contenido estático no se anuncia al montar.
• Foco visible global de 2 px y controles de altura mínima entre 36 y 48 px.

Alternativas descartadas

• Distribuir solamente fuentes Tailwind: obligaría al consumidor a escanear la librería y lo acoplaría a Tailwind.
• Incluir Vue en el bundle: produciría runtimes duplicados y rompería expectativas de plugins e inyección.
• Adoptar una librería visual completa: sustituiría el lenguaje propio en lugar de estandarizarlo.
• Implementar todos los widgets con ARIA: aumenta el riesgo frente a controles HTML nativos.
• Storybook en la primera versión: el playground separado ya valida la API pública y los casos de producto con menos infraestructura.
• Modo oscuro inicial: requiere una revisión visual y de contraste independiente; queda en el roadmap.