First commit

2026-08-10 04:29:24 -06:00
commit 26851fa750
71 changed files with 8333 additions and 0 deletions
@@ -0,0 +1,49 @@
+# 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](https://vuejs.org/guide/typescript/composition-api): props y emits tipados con `<script setup>`.
+- [Vue: descripción general de TypeScript](https://vuejs.org/guide/typescript/overview): Vite transpila y `vue-tsc` realiza la comprobación estática.
+- [Vite: modo librería](https://vite.dev/guide/build.html#library-mode): entrada `build.lib`, externalización de dependencias y distribución de CSS.
+- [Tailwind CSS: variables de tema](https://tailwindcss.com/docs/theme): configuración CSS-first y tokens disponibles como variables CSS.
+- [Tailwind CSS: detección de clases](https://tailwindcss.com/docs/detecting-classes-in-source-files): una librería fuente externa exige `@source`; las clases deben existir de forma completa.
+- [Tailwind CSS: funciones y directivas](https://tailwindcss.com/docs/functions-and-directives): `@reference` es necesario para usar `@apply` en bloques de estilo procesados por separado.
+- [Tailwind CSS: compatibilidad](https://tailwindcss.com/docs/compatibility): Tailwind v4 está diseñado para navegadores modernos.
+- [WAI-ARIA Authoring Practices: patrones](https://www.w3.org/WAI/ARIA/apg/patterns/): comportamiento esperado para botones, tabs, diálogos, radio groups y switches.
+- [WAI-ARIA APG: Dialog modal](https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/): nombre accesible, foco contenido, Escape y retorno de foco.
+- [WAI-ARIA APG: Tabs](https://www.w3.org/WAI/ARIA/apg/patterns/tabs/): flechas, Home, End, roving tabindex y relación tab/panel.
+- [WCAG 2.2](https://www.w3.org/TR/WCAG22/), [Focus Appearance](https://www.w3.org/WAI/WCAG22/Understanding/focus-appearance.html) y [Status Messages](https://www.w3.org/WAI/WCAG22/Understanding/status-messages.html): foco perceptible y anuncios sin cambios de contexto.
+- [MDN: elemento dialog](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/dialog) y [`showModal()`](https://developer.mozilla.org/en-US/docs/Web/API/HTMLDialogElement/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.