# Estándares de la Suite de análisis económico · Imatia

Este documento es el contrato que hace que todas las herramientas parezcan **una misma suite**. Aplica a cualquier herramienta que se añada al repositorio. La implementación de referencia de todo lo que sigue está en `shared/imatia-suite.css` y `shared/imatia-suite.js`; aquí se explica el *porqué* y el *qué*, no se reescribe el código.

## 1. Identidad visual (marca Imatia)

Fuente: manual de marca de Imatia (marca.imatia.com). Tokens en `:root` de `imatia-suite.css`.

- **Color.** Rojo `#FF5033` como **acento** (≈10% de la superficie: barras activas, foco, líneas de tendencia, subrayado de pestaña). Blanco dominante (≈60%). Negros y grises corporativos para estructura y texto (≈30%). El rojo nunca es fondo dominante.
  - Grises: `#1A1918 #2C2A29 #403E3E #535151 #7A7876 #A8A5A2 #D5D2CF #E8E5E2 #F4F2F0 #FAF9F8`.
  - Semánticos sobrios para estados: verde `#2F8F5B` (ok), ámbar `#C4762A` (revisar). No compiten con el rojo de marca.
- **Tipografía.** Imatia Sans (corporativa, basada en Plus Jakarta Sans). Como no siempre está instalada, la suite usa **Plus Jakarta Sans** (Google Fonts) con **Arial** de fallback — Arial es la alternativa que marca la propia marca.
- **Logotipo.** Positivo (rojo) sobre blanco en la barra superior. Es el wordmark oficial extraído de la plantilla corporativa (`shared/assets/imatia-logo.svg`). No deformar, rotar ni recolorear.
- **Elementos gráficos.** "Hilos" (líneas sinuosas con terminaciones rectas) de la marca, usados con moderación como acento decorativo (`shared/assets/imatia-hilo.svg`). Esquinas ligeramente redondeadas en tarjetas e imágenes.
- **Radios y sombras.** Radios 6/10/14 px; sombras muy discretas. Nada de degradados llamativos ni neón.

## 2. Maquetación y UX (esqueleto común)

Toda herramienta comparte el mismo esqueleto, que monta `IM.init`:

- **Barra superior fija**: logo Imatia · separador · título + subtítulo de la herramienta · **filtro de área** · **badge de origen de datos**.
- **Cuerpo** centrado (máx. 1280 px), organizado en secciones con un rótulo en versalitas y un pequeño guion rojo.
- **Pie** con la frase de trazabilidad: de qué fichero y hoja se han leído los datos, cuántas filas y qué área está en pantalla.
- **Estado vacío** con zona de arrastre para cargar el Excel.
- Densidad de analítica: tablas compactas, números tabulares alineados a la derecha, jerarquía tipográfica clara.

Patrones de interacción estándar: pestañas para subvistas, tablas ordenables por columna, y un **panel lateral (drawer)** único para todo el drill-down.

**Libertad de diseño.** La plantilla es un punto de partida, no un molde. Cada herramienta es libre de plantear los KPIs, gráficos, tablas, secciones y vistas que mejor cuenten su análisis —e incluso componentes nuevos— siempre que se construyan con los componentes y tokens de la suite (nada de estilos ni paletas ajenos a la marca) y se respeten las reglas 3, 4 y 5. Lo que no es negociable es *cómo* se ve y *cómo* se traza; *qué* se muestra lo decide la herramienta.

## 3. Filtro de área (análisis vertical)

- Todas las vistas son **globales por defecto** (todas las áreas).
- El filtro permite seleccionar **una o varias áreas** (`General, Innovación, Servicios, Soluciones, Talento`). Es multiselección: "Todas" o un subconjunto.
- Al cambiar la selección, **todo** se recalcula (KPIs, tablas, gráficos e incoherencias) sobre el subconjunto. El director ve el global y, con un clic, la vertical de su área.
- El área sale de una columna del Excel (por defecto `División`; configurable en el mapeo). La librería normaliza variantes del ERP a las áreas canónicas y, si no reconoce una, la deja filtrable igualmente.

## 4. Trazabilidad y drill-down (regla central)

El objetivo: que nadie tenga que fiarse de una cifra a ciegas.

- **Origen del dato.** El badge superior muestra el fichero y el número de filas; al pulsarlo se abre el panel de origen: fichero, hoja, filas leídas, **filas ignoradas** (vacías o de totales del ERP) y por qué, columna de área, mapeo de campos y lista de columnas leídas. Así se sabe **de qué Excel y qué información en bruto** se ha partido.
- **Drill-down por defecto.** Cada KPI, cada fila de tabla y cada elemento de gráfico (barra, segmento del donut, punto de la línea, celda del heatmap) es **clicable** y abre el drawer con **los registros de origen** que componen esa cifra, mostrando su número de fila real en el Excel.
- **Explicación del cálculo.** El drawer incluye una caja "proceso" que dice en una línea qué operación y qué columnas producen el número (p. ej. "suma de `Base total` sobre 182 facturas del área seleccionada").
- **Exportable.** El detalle se puede exportar a CSV desde el propio drawer.
- **Sin cifras huérfanas.** No se muestra un número calculado sin su drill asociado.
- **Apartado de datos en bruto (obligatorio).** Toda herramienta incluye una vista de *raw data* con las filas tal cual se leyeron —todas las columnas, ordenables y exportables a CSV— por cada fuente cargada. Se monta con `IM.bloqueRaw()` (o `IM.tablaRaw({fuente})` para una sola). Sirve para revisar el dato de partida sin salir de la herramienta y para contrastar cualquier cálculo contra el origen.

## 5. Datos de entrada

- Fuente: uno o varios **Excel** descargados del ERP, **comunes a los directores** y ubicados en la carpeta compartida de **SharePoint** (Gerentes). El repo (código) se clona aparte, en una carpeta local; los Excel no se versionan (`.gitignore` los excluye).
- Se leen **en el navegador** (SheetJS). No se suben a ningún servicio.
- **Varias fuentes.** Una herramienta puede declarar varias fuentes (`IM.init({fuentes:[{id,titulo,mapeo}]})`), cada una con su propio badge de origen y su carga independiente. Los cruces entre fuentes se hacen con `IM.cruzar(izq, der, campoIzq, campoDer, {prefijo})`, que conserva la trazabilidad (fila de origen de cada lado). Cada fuente aparece por separado en el apartado de datos en bruto.
- La librería descarta filas vacías/de totales usando un campo clave y lo deja anotado en el panel de origen; las herramientas no deben sumar esas filas a mano.
- Si un dato no está en el Excel, no se inventa.

## 6. Tono de los textos de interfaz

Los textos que escribe la herramienta (rótulos, etiquetas, mensajes) siguen el tono de marca: claro, directo, en tercera persona, frases cortas. Se evita la jerga de marketing ("transformación disruptiva", "soluciones 360º", "ecosistema", "sinergias") y las muletillas de relleno.

## 7. Accesibilidad y robustez

- Contraste suficiente entre texto y fondo; el color nunca es el único portador de significado (los estados llevan etiqueta, no solo color).
- La herramienta funciona abierta con doble clic desde la carpeta del repo. Si el navegador bloquea la lectura de ficheros locales por seguridad, se usa el selector/arrastre de fichero (que siempre funciona) o un servidor local sencillo.