ADR-034: Patrones de documentación — cards, tabs y detalles expandibles¶
Estado: aceptado
Contexto¶
La documentación de SmallCountry ha evolucionado de manera orgánica. En las últimas semanas se han consolidado varios patrones editoriales que aparecen repetidamente en distintas páginas pero no estaban formalizados:
- Cards con detalles expandibles en páginas portal e índice (guía de estilo 4.8)
- Tabs "Para entenderlo / Para implementarlo" en páginas de manifiesto, compromisos y sistemas
- Iconos Material Design monocolor como estándar visual
- Dashboard auto-generado vía
_includes/ypymdownx.snippets - Descripciones sin HTML en los metadatos (validado por CI)
Sin formalización, cada colaborador —humano o agente— aplica criterios distintos, generando inconsistencia y fricción.
Decisión¶
Formalizar los siguientes patrones como obligatorios y extenderlos sistemáticamente:
1. Cards con detalles expandibles¶
Dónde: toda página portal o índice (*/index.md).
Formato canónico:
<div class="grid cards" markdown>
- :material-icono:{ .lg .middle } **[Título enlazado](destino.md)**
---
Texto de gancho — 1-2 líneas que invitan a entrar.
<details markdown="1"><summary>Pregunta que incita a desplegar</summary>
Contenido adicional con [enlaces](otra-pagina.md) inline. Entre 40 y 80 palabras.
</details>
</div>
Reglas:
- Icono: :material-*:{ .lg .middle } — Material Design, monocolor en el color de acento verde
- Título: **[texto](enlace)** — siempre clicable
- Gancho: 1-2 líneas, sin negrita, sin enlaces
- <details>: obligatorio en toda card. El <summary> es una pregunta atractiva
- Enlaces dentro de <details>: inline en el texto, no botones sueltos ni CTAs externos
- Separador: --- entre título y gancho
2. Tabs de audiencia dual¶
Dónde: páginas que beneficien tanto a lectores no técnicos como a administradores.
Formato:
=== "👀 Para entenderlo"
Explicación en lenguaje llano, sin jerga, con ejemplos cotidianos.
=== "⚙️ Para implementarlo"
Detalles técnicos, comandos, configuraciones, referencias a ADRs.
Reglas: - La pestaña "Para entenderlo" usa analogías y evita acrónimos sin explicar - La pestaña "Para implementarlo" asume familiaridad técnica y enlaza a fichas y ADRs - Cualquier página que tenga tanto audiencia general como técnica debe usar tabs
3. Iconos Material Design monocolor¶
Dónde: todas las páginas.
Reglas:
- Usar :material-*:{ .lg .middle } en cards de portal/índice
- Usar :material-*: simple en listas y tablas
- El color se hereda del acento verde de SmallCountry (#4CAF50 / var(--md-accent-fg-color))
- FontAwesome solo para casos excepcionales donde no exista equivalente Material
4. Dashboard auto-generado¶
Dónde: landing page y páginas que muestren métricas del sitio.
Formato: --8<-- "dashboard.md" — contenido generado por scripts/generate_dynamic_content.py en _includes/.
5. Descripciones sin HTML¶
Dónde: campo description: del frontmatter en todas las páginas.
Regla: prohibido incluir <img>, <div>, <a> o cualquier HTML en el campo description. Validado por CI con el paso html-in-desc.
Alternativas consideradas¶
A. Seguir con el enfoque ad-hoc¶
No formalizar patrones. Cada página decide su formato.
Descartada por inconsistencia y fricción para colaboradores nuevos.
B. Usar solo un patrón (todo tabs o todo cards)¶
Descartada porque cada patrón resuelve un problema distinto: las cards son para navegación/portal, los tabs para contenido dual-audiencia.
Consecuencias¶
Positivas¶
- Consistencia garantizada: cualquier página nueva sigue un patrón predecible
- Fricción cero para agentes IA: los patrones son parseables y repetibles
- Accesibilidad: los
<details>nativos funcionan sin JavaScript - CI validable: los patrones son verificables automáticamente
Negativas¶
- Curva de aprendizaje: colaboradores nuevos deben conocer los patrones
- Migración pendiente: páginas antiguas que no siguen los patrones necesitan actualización
Neutrales¶
- La guía de estilo (secciones 4.8, 4.10, 4.11, 4.12) es la fuente canónica de estos patrones; este ADR documenta la decisión de extenderlos a toda la web