4. Diseño del frontend

4.1 Stack obligatorio

• Framework: React 19 + TypeScript estricto.
• Build: Vite 6 · pnpm · ESLint + Prettier + Stylelint.
• Routing: React Router 7 · rutas anidadas por contexto (Admisión, ER, CE, Hosp, Quirófano, Lab, Farm, Admin).
• Estado servidor: TanStack Query 5 (queries, mutations, infinite, optimistic).
• Estado UI: Zustand para estado local complejo · React Context sólo para tema y usuario.
• Formularios: React Hook Form + Zod (validación tipada compartida con backend).
• Estilos: Tailwind CSS v4 con tokens del Design System Toscana Salud.
• Componentes: Radix UI primitives + capa propia @toscana/sih-ui.
• i18n: react-intl con catálogo ES-GT (idiomas mayas en consentimiento informado · etapa 2).
• Pruebas: Vitest + Testing Library + Playwright (E2E).

4.2 Estructura del proyecto

apps/web
├── src/
│   ├── app             // Bootstrapping, providers, layout principal
│   ├── contexts        // (subdominios) admision/ ce/ er/ hosp/ quirofano/ farmacia/ ...
│   │   └── ce/
│   │       ├── pages/        // ConsultaList.tsx · ConsultaDetail.tsx
│   │       ├── components/   // FormaConsulta.tsx
│   │       ├── api/          // useConsultas.ts (TanStack)
│   │       └── schemas/      // zod schemas compartidos
│   ├── shared          // ui, hooks, utils, i18n, design-tokens
│   └── routes          // Definición de rutas y guards
├── tests/              // Vitest + Playwright
└── public/                   // assets estáticos · iconos · sonidos de alerta

4.3 Design System Toscana Salud (resumen)

4.4 Cómo construir una pantalla (paso a paso)

1. Definir el contrato con backend (OpenAPI). Genera tipos TypeScript con openapi-typescript.
2. Crear el schema Zod en schemas/. Puede ser el mismo que valida el backend (compartido por monorepo).
3. Hook de datos en api/useConsultas.ts: useQuery para lectura, useMutation con onMutate optimista, invalidación de keys jerárquicas.
4. Componente de pantalla en pages/ConsultaDetail.tsx: orquesta layout, llama al hook, maneja estados isLoading · isError · data.
5. Formulario con useForm({ resolver: zodResolver(schema) }). Usar componentes de @toscana/sih-ui: <Field>, <Select>, <DatePicker>, <CodeSearch> (CIE-10/ATC).
6. Manejo de errores: errores de validación → mensajes inline; errores 4xx/5xx → <ErrorBanner> con trace_id visible para soporte.
7. Accesibilidad: navegación por teclado, focus visible, etiquetas label+aria-describedby, contraste AA, sin trampas de foco. Lector de pantalla anuncia cambios de estado.
8. Internacionalización: ningún string hardcodeado · <FormattedMessage id="ce.title" />. Fechas con <FormattedDate /> en zona America/Guatemala.
9. Tableros vivos (encamamiento, ER, quirófano): conectar WebSocket vía hook useLiveBoard(); reconectar con backoff exponencial; mostrar indicador de conexión.
10. Pruebas: Testing Library para componentes; Playwright para flujo crítico (CU-04 orden + resultado lab).
11. Performance: React.lazy por ruta · prefetch en hover · imágenes WebP · listas virtualizadas para censos >200 ítems.
12. Empaquetar: pnpm build · servir desde NGINX con cache-control agresivo en hash y cero en index.html.

4.5 Mapa de pantallas por rol

4.6 Listo cuando…

• ✓ Lighthouse ≥ 90 (Performance, A11y, Best Practices, SEO interno).
• ✓ Bundle inicial < 250 KB gzip · TTI < 3 s en laptop institucional.
• ✓ 100 % de strings con i18n.
• ✓ axe-core sin violaciones serias.
• ✓ Playwright cubre el flujo crítico del rol.
• ✓ Tema oscuro disponible para guardia nocturna en ER.