IDH Panamá lab

Banco de pruebas de narrativa de datos (scrollytelling) para el Informe Nacional de Desarrollo Humano de Panamá (PNUD). Replica la arquitectura documentada en evaluacion-tecnica-sizing-chaos.md —el motor de The Pudding— y aplica las seis mejoras que esa evaluación exige.

Prototipo técnico. No es una publicación oficial del PNUD.

Uso

npm install
npm run dev          # http://localhost:5173
npm run build        # sitio estático en build/ (raíz del dominio)
npm run build:wamp   # igual, pero servido desde http://localhost/pudding/build/
npm run preview

Para publicar bajo otra subcarpeta: BASE_PATH=/mi/ruta vite build.

Qué pone a prueba

Ruta	Qué explora
/ — Historia	7 capítulos de scrollytelling, cada uno con una técnica distinta
/explorador/	Tablero con gráficos enlazados, filtros, estado en la URL, tabla ordenable y descarga CSV
/componentes/	Catálogo vivo del sistema de diseño (tokens, tipografía, piezas, motor Scrolly, movimiento)

Capítulos de la historia

#	Componente	Técnica
00	Intro.svelte	Titular collage (Sellos), 100 unidades ilustradas por capas, enjambre con forceSimulation precalculado (3 layouts), bandas de categoría, tooltips detrás de los steps
—	TitlePage.svelte	Corte editorial a pantalla completa con entrada por inView
01	Serie.svelte	Serie temporal con revelado por clipPath + Tween, crosshair, etiquetas directas
02	Mapa.svelte	Coroplético real (d3-geo, 13 unidades) que se transforma en ranking de burbujas; cambio de métrica y de rampa
03	Dimensiones.svelte	Gráfico de rangos en HTML; filas reordenadas con animate:flip
04	Poblacion.svelte	Canvas: ~4.000 partículas entre 3 layouts (filotaxis → racimos geográficos → columnas)
05	Pobreza.svelte	Waffle de 100 personas con contador; al final del scroll el gráfico pasa a modo interactivo
06	Informes.svelte	Scroll vertical → desplazamiento horizontal continuo; se degrada a cuadrícula con prefers-reduced-motion

Navegación

• Cabecera que se oculta al bajar y reaparece al subir, con barra de progreso de lectura.
• Índice a pantalla completa en un <dialog> nativo (foco atrapado, Esc).
• Riel lateral de capítulos con deep-link por hash (/#mapa).
• Paginador de pasos con botones y teclado (← → / j k): la historia no depende solo del scroll.
• View Transitions API entre rutas y en el cambio de tema (mejora progresiva).
• Tema claro/oscuro con tokens elegidos a mano (sin parpadeo inicial).

Arquitectura

src/
├─ routes/                 +layout (prerender, View Transitions), /, /explorador, /componentes
├─ components/
│  ├─ Index.svelte         ORQUESTADOR: el orden de la historia
│  ├─ helpers/Scrolly.svelte   motor (IntersectionObserver ×101 umbrales; "to-enter"/"exit"; progress)
│  ├─ story/               un componente por capítulo + Person, Sellos, Leet, Text
│  ├─ charts/              ChoroMap, BarRank, Slope, Scatter (hover enlazado con bind:hoverId)
│  └─ ui/                  DataTable, StatTiles, ChapterRail, StepPager, ThemeToggle
├─ data/                   copy.json (guion + banderas por step), *.csv, meta.json, panama-geo.json, facts.js
├─ styles/                 variables.css (tokens), app.css (base + esqueleto scrolly)
├─ utils/                  media.svelte.js, random.js (semilla), md.js, format.js
└─ actions/                inView.js
tasks/                     build-data.js, build-geo.js
data-src/research.json     investigación de datos con fuentes y nivel de confianza

Decisiones clave

1. Estado declarativo por step. Cada step de copy.json lleva su texto y sus banderas (layout, highlight, metric, view, sort…). Los componentes hacen s = STEPS[value] y derivan todo de s: no hay índices mágicos.
2. Cifras vivas en el copy. El texto usa {{idhNacional}}, {{brecha}}… que facts.js calcula desde los CSV en build. Cambiar los datos actualiza la prosa.
3. Cero imágenes rasterizadas. Personas = sprite SVG de 4 capas con <use>; textura = gradientes CSS; titular = recortes tipográficos CSS. Fuentes woff2 autoalojadas (@fontsource).
4. Aleatoriedad con semilla (utils/random.js) → el HTML prerenderizado y el cliente coinciden (sin hydration_mismatch).
5. Movimiento accesible. Tokens de duración a 1ms por defecto, activados solo con prefers-reduced-motion: no-preference; en JS, dur(ms) apaga Tween/flip/canvas.
6. Accesibilidad de gráficos. Cada figura tiene role="img" + aria-label que cambia con el step, región aria-live, y tabla de datos alternativa (DataTable hidden).
7. Breakpoints unificados: 500 / 700 / 850 px (CSS y media.svelte.js).

Datos

node tasks/build-data.js regenera src/data/*.csv y meta.json desde data-src/research.json.

Dato	Fuente
IDH Panamá, ALC y mundo 1990–2023; IDH-D	PNUD, Informe sobre Desarrollo Humano 2025 (series compuestas)
IDH por provincia y comarca 2019 y 2022	PNUD Panamá, INDH 2024, Cuaderno I, Gráfica 4
Logro por dimensión 2014	PNUD Panamá, Atlas de Desarrollo Humano Local 2015 (Panamá Oeste incluida en Panamá)
Pobreza multidimensional 2017–2022	MEF / PNUD, IPM de Panamá, edición 2024
Población	INEC, Censo 2023
Límites	geoBoundaries (gbOpen PAN ADM1) · OpenStreetMap, ODbL

Advertencias: el IDH subnacional usa la metodología nacional del PNUD Panamá (promedio 0,791) y no es comparable con el IDH global (0,839); aquí se le aplican los umbrales internacionales solo con fines ilustrativos. Los valores subnacionales se leyeron de las etiquetas de un gráfico en PDF: deben reemplazarse por la base oficial antes de publicar.

Pendiente / siguientes pasos

• Conectar el micro-CMS (Google Docs + ArchieML → copy.json) como en el original.
• Versión en inglés (el contrato de copy.json ya lo permite: un JSON por idioma).
• Pruebas con lector de pantalla real y auditoría Lighthouse en el hosting definitivo.
• Imagen og:image para redes.