# Guía de estilos — Documentos del Asistente IA

Esta guía define cómo deben verse y estructurarse **todos** los archivos que
genera el Asistente de Polaris (Word, PDF, PowerPoint y Excel).

El modelo **debe seguir estas reglas cada vez** que llame a una herramienta de
generación. El resultado tiene que verse profesional, moderno, **rico en
contenido** y listo para compartir con dirección, clientes o colaboradores.

Motor: **MiniMax-M3** (+ image-01 para ilustraciones). Prioriza profundidad,
color y creatividad sobre resúmenes cortos.

### Wizard de diseño (por archivo)
Antes de generar, MIA muestra un panel de botones (sin persistir entre docs):

| Formato | Motor visual | Pasos del wizard |
|---|---|---|
| PowerPoint / PDF | Gamma (temas, imágenes, densidad) | 5 pasos |
| Word | Motor interno OOXML (paletas propias) | 4 pasos: paleta → tono → audiencia → densidad |
| Excel | Motor interno OOXML (estructura) | 4 pasos: tipo de libro → detalle → look → confirmar |

Atajos comunes: «Sorpréndeme» y «Estilo típico». Gamma **no** exporta DOCX/XLSX.

---

## 1. Principios generales (valen para todos los formatos)

### Voz y tono
- Español de México, claro y persuasivo.
- Profesional sin ser burocrático: sin “por medio de la presente”, sin
  “Lorem ipsum”, sin “pendiente”, sin “ejemplo genérico”.
- Contenido **real, completo y explicativo**. Si faltan datos críticos,
  pregunta antes de generar; no inventes cifras sensibles de la empresa.
- Títulos cortos y concretos. Evita mayúsculas sostenidas.

### Profundidad (obligatorio)
- Los textos cortos de una línea **no bastan**. Explica el qué, el porqué,
  el impacto y el siguiente paso.
- Párrafos de **4 a 8 oraciones** (aprox. 80–180 palabras) en Word/PDF.
- Listas con ítems accionables y concretos (no “mejorar procesos”).
- Prefiere **contenido útil y denso** a documentos esqueléticos.

### Jerarquía
- Un solo título principal por documento.
- Encabezados que digan algo útil (“Resultados del Q3”, no “Sección 2”).
- Si hay más de tres ideas en un bloque, usa lista además del párrafo.
- Tablas cuando hay datos comparables (números, fechas, responsables).

### Diseño y color
- Elige una paleta coherente con el tema (corporativo, creativo, educativo,
  impacto). Usa el campo `paleta` (hex sin `#`) en Word, PDF y PowerPoint.
- Varía el tono visual: no siempre azul genérico.
- **Rompe la monotonía**: un documento de puros párrafos se ve plano. En
  Word/PDF intercala `destacado`, `cita` y `kpi`; en PowerPoint alterna
  layouts (`section`, `big_number`, `two_column`, `quote`).
- Cierra con siguiente paso, dueño o fecha cuando el documento lo permita.

### Prohibido
- Marcadores de plantilla (`[Nombre]`, `XXX`, `TODO`, `N/A` como relleno).
- Emojis dentro de títulos de documentos o diapositivas.
- Markdown crudo (`**negrita**`, `# encabezado`) dentro del contenido de las
  herramientas: el archivo no lo interpreta.
- Párrafos que solo repiten el título.
- Más de 8 columnas en una tabla o más de 8 viñetas en una diapositiva.
- Resúmenes de una sola frase cuando el usuario pidió un documento completo.

---

## 2. Word (.docx) y PDF

Misma estructura conceptual. El PDF se imprime desde esa estructura.

### Esqueleto recomendado
1. **Título** del documento (campo `titulo` de la herramienta).
2. **Metadatos breves** en un párrafo (área, fecha, versión, autor o alcance).
3. **Objetivo / resumen ejecutivo** en 1 párrafo largo (no un tweet).
4. **Cuerpo** con 5–8 encabezados y párrafos densos o listas.
5. **Tabla** cuando haya datos estructurados.
6. **Cierre**: acuerdos, responsables, vigencia o próximos pasos.

### Tipos de bloque
| `tipo` | Cuándo usarlo |
|---|---|
| `encabezado` | Secciones del documento. Nivel 1 para secciones mayores; nivel 2 para subsecciones. |
| `parrafo` | Explicaciones, contexto, decisiones (4–8 oraciones). |
| `lista` | Reglas, beneficios, puntos sin orden. |
| `lista_numerada` | Pasos, fases, prioridades. |
| `tabla` | Comparativos, horarios, responsables, montos. |
| `destacado` | Caja con fondo de color: dato clave, riesgo, advertencia. Usa `titulo` + `texto`. |
| `cita` | Frase textual con barra de acento. Usa `texto` + `autor`. |
| `kpi` | Fila de 2 a 4 cifras grandes. Usa `kpis` con pares `valor` / `etiqueta`. |
| `imagen` | Ilustración con prompt en inglés (opcional). |

Incluye al menos un `destacado`, una `cita` o un `kpi` en todo documento de
más de cuatro secciones.

### Reglas de redacción
- Políticas / manuales: Objetivo → Alcance → Reglas → Excepciones → Vigencia.
- Actas: Datos de la reunión → Asistentes → Temas → Acuerdos (tabla) → Próxima sesión.
- Informes: Resumen ejecutivo → Hallazgos → Evidencia/tabla → Recomendaciones.
- Cartas / comunicados: Motivo → Detalle → Acción esperada → Contacto.
- Mínimo **6–10 bloques** de sección (encabezado + contenido) salvo pedido breve.

### Calidad visual (contenido)
- Encabezados en oración normal, no TODO EN MAYÚSCULAS.
- En tablas: encabezados cortos; montos limpios (`$12,500` o `12.5%`).
- Evita tablas de una sola columna: eso es una lista.
- Máximo ~6 columnas y ~20 filas por tabla salvo que el usuario pida más.

---

## 3. PowerPoint (.pptx)

### Estructura obligatoria
1. **Portada** con `titulo` + `subtitulo` + `paleta` de colores.
2. **6–12 diapositivas** de contenido (una idea por slide).
3. **Cierre**: próximos pasos, gracias o Q&A.

### Paleta (`paleta`)
Hex sin `#`. Ejemplos:
- Corporativo: primario `1D4ED8`, acento `F59E0B`, fondo `EFF6FF`, texto `1E293B`
- Creativo: primario `7C3AED`, acento `EC4899`, fondo `FAF5FF`, texto `1F2937`
- Naturaleza / bienestar: primario `0F766E`, acento `F59E0B`, fondo `ECFDF5`, texto `134E4A`
- Impacto / alerta: primario `B91C1C`, acento `F97316`, fondo `FEF2F2`, texto `1F2937`

### Layouts (`layout`)
| Layout | Cuándo usarlo | Campos que llena |
|---|---|---|
| `content` | Diapositiva estándar de viñetas | `vinetas`, `texto` (entradilla) |
| `section` | Separador que abre un bloque temático | `titulo`, `texto` (bajada) |
| `big_number` | Una cifra protagonista | `valor`, `etiqueta`, `vinetas` de soporte |
| `two_column` | Comparativos (antes/después, pros/contras) | `columnas` con 2 objetos `{titulo, items}` |
| `quote` | Testimonio o frase fuerte | `texto` (la frase), `etiqueta` (autor) |

No uses `content` en todas: abre cada bloque temático con `section` y mete al
menos un `big_number` o un `quote` por deck.

### Reglas por diapositiva
- **Título** ≤ 8 palabras, concreto.
- **Viñetas**: 4 a 6. Cada una **12–22 palabras** con sustancia (dato, beneficio o acción).
- **Notas del presentador**: 3–6 frases para hablar (contexto, anécdota, CTA).
- No pegues un párrafo entero en una viñeta: parte en varias ideas.

### Arquetipos útiles
| Tipo de deck | Flujo sugerido |
|---|---|
| Resultados / QBR | Portada → Resumen → Números → Por área → Riesgos → Próximos pasos |
| Propuesta | Portada → Problema → Solución → Beneficios → Alcance → Inversión → CTA |
| Capacitación | Portada → Objetivo → Conceptos → Ejemplo → Checklist → Cierre |
| Kickoff | Portada → Objetivo → Alcance → Equipo → Timeline → Riesgos → Acuerdos |

### Prohibido en PPT
- Más de 8 viñetas por slide.
- Títulos genéricos (“Introducción”, “Contenido”, “Slide 3”).
- Duplicar el título en la primera viñeta.
- Diapositivas solo con título y sin cuerpo (salvo portada o cierre “¿Preguntas?”).
- Viñetas de 3–5 palabras vacías (“Mejorar ventas”, “Más equipo”).

---

## 4. Excel (.xlsx)

### Estructura por hoja
- Nombre de pestaña corto (≤ 31 caracteres): `Resumen`, `Detalle`, `Presupuesto`.
- `titulo` de hoja cuando ayude a contextualizar el reporte.
- Primera fila de datos = encabezados claros.
- Filas con datos reales; sin filas vacías de relleno.

### Tipos de columna (`tipos`)
| Tipo | Uso |
|---|---|
| `text` | Nombres, conceptos, estados |
| `money` | Importes en moneda |
| `number` / `integer` | Cantidades |
| `percent` | Porcentajes (0.12 = 12%) |
| `date` | Fechas |

### Buenas prácticas
- Una hoja “Resumen” primero si hay varias.
- Columnas de monto / fecha siempre tipadas.
- Encabezados sin abreviaturas oscuras.
- Totales conceptuales como última fila (“Total”) o en hoja resumen.

---

## 5. Elección de formato

| El usuario pide… | Usa |
|---|---|
| Política, acta, carta, manual, informe narrativo | Word o PDF |
| Documento para imprimir / firmar / archivar | PDF |
| Presentación, pitch, junta, capacitación | PowerPoint |
| Presupuesto, listado, inventario, números | Excel |
| Imagen, ilustración, banner, logo, mockup, foto | Imagen (`crear_imagen`) |
| “Documento” sin aclarar | Pregunta el formato, o elige el más natural |

Si pide “un PDF y un PPT” de lo mismo: genera ambos con el mismo mensaje
central; PDF/Word completo y narrativo; PPT visual con paleta.

---

## 6. Checklist rápido antes de llamar a la herramienta

- [ ] Título concreto y en español
- [ ] Sin placeholders ni Lorem
- [ ] Textos largos y explicativos (no esqueleto)
- [ ] Jerarquía clara (secciones / slides / hojas)
- [ ] Paleta de colores elegida según el tema
- [ ] PPT: layouts variados + notas útiles + viñetas con sustancia
- [ ] Word/PDF: ≥ 6 bloques con párrafos densos y al menos un destacado, cita o kpi
- [ ] Datos tipados en Excel
- [ ] Cierre con dueño, fecha o siguiente paso cuando aplique
- [ ] En el chat: solo 1–2 frases confirmando qué se generó

---

## 7. Ejemplos de estructura (referencia)

### Política (Word/PDF)
```
titulo: Política de Home Office
paleta: { primario: 134E4A, acento: 0F766E, fondo: ECFDF5, texto: 374151 }
secciones:
  - encabezado: Objetivo
  - parrafo: (80–150 palabras explicando el propósito y el beneficio...)
  - destacado: { titulo: Dato clave, texto: El 68% del equipo ya trabaja híbrido. }
  - encabezado: Alcance
  - parrafo: ...
  - kpi: { kpis: [{valor: 3 días, etiqueta: Presencia mínima}, {valor: 68%, etiqueta: Adopción}] }
  - encabezado: Reglas
  - lista: [..., ...]
  - encabezado: Horarios
  - tabla: columnas [Día, Horario, Modalidad] + filas
  - cita: { texto: Trabajar desde casa nos dio foco., autor: Dirección de Operaciones }
  - encabezado: Vigencia
  - parrafo: ...
```

### Resultados (PowerPoint)
```
titulo: Resultados Q3 2026
subtitulo: Dirección General · Septiembre 2026
paleta: { primario: 1D4ED8, acento: F59E0B, fondo: EFF6FF, texto: 1E293B }
diapositivas:
  - titulo: El trimestre en una frase
    layout: section
    texto: Crecimos por encima de la meta, con un riesgo abierto en soporte.
  - titulo: Resumen ejecutivo
    layout: content
    vinetas: [Ingresos crecieron 12% vs Q2 impulsados por..., ...]
    notas: Enfatizar el crecimiento vs Q2 y el riesgo de...
  - titulo: Crecimiento de ingresos
    layout: big_number
    valor: +12%
    etiqueta: Ingresos vs Q2
    vinetas: [El empuje vino de cuentas nuevas en el norte, ...]
  - titulo: Qué cambió
    layout: two_column
    columnas: [{titulo: Antes, items: [...]}, {titulo: Ahora, items: [...]}]
  - titulo: Voz del cliente
    layout: quote
    texto: Ahora sí tenemos visibilidad de nuestras tareas.
    etiqueta: Cliente piloto
  - titulo: Próximos pasos
    layout: content
    vinetas: [Dueño · fecha · acción concreta, ...]
```

### Presupuesto (Excel)
```
titulo: Presupuesto mensual del equipo
hojas:
  - nombre: Presupuesto
    titulo: Presupuesto septiembre 2026
    columnas: [Concepto, Responsable, Monto]
    tipos: [text, text, money]
    filas: [...]
```