Sistema de Diseño — manual-churreria
1. Paleta de colores
Derivada de Paleta C (startup fresca / clara) adaptada a documentation hub con acento violeta técnico (carácter IA/agéntico).
Fuente: ux.md v1 §3.1 + §3.2.
1.1. Fondos (Backgrounds)
1.2. Texto
1.3. Primary y Accent
1.4. Bordes
—color-border
#E2E8F0 · slate-200
—color-border-strong
#CBD5E1 · slate-300
1.5. Callouts semánticos
—color-callout-note
#EFF6FF · blue-50
—color-callout-warn
#FFFBEB · amber-50
—color-callout-tip
#F0FDF4 · green-50
—color-callout-tech
#EDE9FE · violet-50
1.6. Tabla de contraste completa
| Token de texto | Token de fondo | Ratio | WCAG 2.2 AA regular (≥4.5:1) | WCAG 2.2 AA texto grande (≥3:1) |
|---|---|---|---|---|
--color-text #0F172A | --color-bg #F8FAFC | 17.9:1 | ✅ | ✅ |
--color-text #0F172A | --color-surface #FFFFFF | 18.9:1 | ✅ | ✅ |
--color-text-muted #475569 | --color-bg #F8FAFC | 7.4:1 | ✅ | ✅ |
--color-text-muted #475569 | --color-surface #FFFFFF | 7.7:1 | ✅ | ✅ |
--color-primary #2563EB | --color-surface #FFFFFF | 5.4:1 | ✅ | ✅ |
--color-primary #2563EB | --color-sidebar-bg #F1F5F9 | 5.1:1 | ✅ | ✅ |
--color-accent #7C3AED | --color-surface #FFFFFF | 6.9:1 | ✅ | ✅ |
--color-text-on-dark #F8FAFC | --color-code-block-bg #0F172A | 17.9:1 | ✅ | ✅ |
--color-text-faint #94A3B8 | --color-surface #FFFFFF | 3.5:1 | ⚠️ Solo ≥14px | ✅ |
2. Tipografía
Fuente: ux.md v1 §3.3. Sin web fonts externas — sin penalización de red en LCP.
2.1. Familias tipográficas
El arnés churrerIA
ABCDEFGHIJKLMNOPQRSTUVWXYZ 0123456789
—font-body
system-ui, -apple-system, BlinkMacSystemFont, “Segoe UI”, Roboto, sans-serif
Para: cuerpo, titulares, UI
agente.po, ciclo.md
const x = 42; // comentario
—font-mono
ui-monospace, “SF Mono”, Menlo, Monaco, Consolas, monospace
Para: código, paths, identificadores
2.2. Escala tipográfica
H1 — Título principal (2rem / 32px, 700)
H2 — Sección principal (1.5rem / 24px, 600)
H3 — Sub-sección (1.25rem / 20px, 600)
H4 — Sub-sub-sección (1rem / 16px, 600)
Body — Cuerpo del texto (1rem / 16px, 400). Interlineado 1.6 para lectura larga. Ancho máximo 72ch para confort de lectura según USA-012 (entre 45-75 caracteres por línea).
Small / auxiliar — 14px, color-text-muted. Usado en captions, metadatos, fechas. Mínimo absoluto del sistema.
Tiny / faint — 14px mono, color-text-faint. Solo para LiveDocBadge, timestamps. Excepción USA-013.
2.3. Parámetros de layout de texto
| Parámetro | Valor | Fuente |
|---|---|---|
| Tamaño base | 16px | USA-012 |
| Auxiliar mínimo | 14px | USA-012 |
max-width contenido | 72ch | USA-012 + ux.md §3.4 |
| Interlineado body | 1.6 | ux.md §3.3 |
| Interlineado titulares | 1.2 | ux.md §3.3 |
3. Espaciado y Radios
3.1. Escala de espaciado
| Token | Valor | Visual |
|---|---|---|
--space-1 | 4px | |
--space-2 | 8px | |
--space-3 | 12px | |
--space-4 | 16px | |
--space-5 | 20px | |
--space-6 | 24px | |
--space-8 | 32px | |
--space-10 | 40px | |
--space-12 | 48px | |
--space-16 | 64px |
3.2. Radios de borde
—radius-sm
2px—radius-md
4px—radius-lg
6px—radius-xl
8px—radius-2xl
12px—radius-full
9999px (pill)4. Iconografía
5. Componentes
Catálogo de los 13 componentes identificados en ux.md v1 §9. Cada uno con su mock visual, variantes de estado y notas de accesibilidad.
5.1. Callout (info / warning / tip / tech)
💡 Nota
Callout de tipo note — información complementaria no crítica. Fondo —color-callout-note.
⚠️ Advertencia
Callout de tipo warning — atención necesaria. Fondo —color-callout-warn.
✅ Tip
Callout de tipo tip — recomendación positiva. Fondo —color-callout-tip.
🤖 Técnico / Agéntico
Callout de tipo tech — información de carácter técnico o agéntico. Fondo —color-callout-tech. Acento violeta marca el carácter IA del sistema.
Accesibilidad: todos los callouts usan role="note". Los de advertencia añaden aria-label="Advertencia". El texto del tipo no depende solo del color.
5.2. LiveDocBadge
↑ Footer global en todas las páginas. Implementado en src/components/LiveDocBadge.astro.
Accesibilidad: <aside> con aria-label, <dl>/<dt>/<dd> semánticos, <time> con datetime ISO. Texto usa --color-text-faint ≥14px (excepción USA-013 documentada).
5.3. AgentCard
Variantes: una por agente (8 total: PO, Director, Arquitecto, UX, Backend, Frontend, SRE, QA). Los tags de carril usan --color-accent-soft / --color-callout-note según categoría.
5.4. Tabla (TableDocs)
| Artefacto | Propietario | Tipo | Estado |
|---|---|---|---|
funcional.md v2 | PO | MD + render PDF/HTML | firmado D-1 |
tecnica.md v1 | Arquitecto | MD + render PDF/HTML | firmado D-1 |
ux.md v1 | UX | MD | firmado D-1 |
arbol-contenidos.md v1 | UX | MD (Mermaid) | firmado D-1 |
acta-kickoff.md v1 | Director | MD + render PDF/HTML | firmado D-1 |
Accesibilidad: <table> con <th scope="col"> en cabecera. Responsive con overflow-x: auto en contenedor.
5.5. CodeBlock (inline y multilínea)
Inline: ciclo.md, etapa-2, ux.md v1 §3.2 — fondo --color-code-bg (#F1F5F9), fuente --font-mono.
Multilínea (dark theme, fondo --color-code-block-bg #0F172A):
def extraer_seccion(source_path: str, seccion_id: str) -> str: """Extrae un bloque de contenido del arnés según su ID de sección.""" with open(source_path, "r", encoding="utf-8") as f: contenido = f.read() # … aplicar allowlist de extracción return contenido5.6. Heading con ancla
Etapa 2 — Kickoff y definición a alto nivel #
↑ El icono de ancla (#) aparece al hover. Visible siempre en teclado para navegación por focus.
Accesibilidad: el ancla tiene aria-label descriptivo. No depende solo del hover — el ancla es navigable por teclado (Tab).
5.7. Link (interno y externo)
Ver Etapa 2 — Kickoff y definición a alto nivel
(link interno — texto descriptivo)Astro Starlight — documentación oficial ↗
(link externo — icono ↗ + aria-label)Etapa 2 — foco visible
(estado focus — outline 2px primary)Accesibilidad: texto de link siempre descriptivo (prohibido “haz clic aquí”). Links externos con rel="noopener noreferrer" + indicador visual ↗ + aria-label.
5.8. Button
| Estado | Descripción |
|---|---|
| Default | Fondo --color-accent, texto blanco |
| Hover | Fondo más oscuro (--color-accent +10% dark) |
| Focus | Outline 2px --color-primary, offset 2px |
| Active | Fondo --color-accent con scale(0.98) |
| Disabled | aria-disabled, cursor not-allowed, opacidad reducida |
5.9. Paginación (Prev/Next)
Accesibilidad: aria-label completo en cada link. Flechas con aria-hidden. Navegable por teclado.
5.10. Breadcrumb
Accesibilidad: <nav aria-label="Migas de pan"> + <ol> semántico + aria-current="page" en el último item + separadores con aria-hidden.
5.11. Sidebar (desktop y mobile drawer)
Mobile drawer (≤640px): el sidebar se colapsa. Un botón ☰ en el topbar lo despliega como overlay lateral. aria-expanded, aria-hidden en el overlay, focus trap mientras está abierto, prefers-reduced-motion respetado.
5.12. Layout Docs (estructura de página completa)
La estructura de página interior del manual sigue el patrón de documentation hubs de referencia (GitBook, Docusaurus, Starlight):
┌──── Topbar (mobile) / Nav header (desktop) ─────────────────────────────┐│ churrerIA [búsqueda Pagefind] [theme toggle] │├──── Sidebar (240px, desktop persistente) ────┬──── Contenido (max 72ch) ─┤│ ▸ Concepto │ <nav> breadcrumb ││ ▸ Ciclo │ <main> ││ ● Etapa 2 │ <h1> título ││ Etapa 3 │ contenido ││ ▸ Gates │ callouts ││ ▸ Agentes │ tablas ││ En esta página: │ </main> ││ Flujo normal │ <nav> paginación ││ Flujos alt. │ <aside> LiveDocBadge │└──────────────────────────────────────────────┴───────────────────────────┘Implementado por Astro Starlight out-of-the-box con override del Footer slot para el LiveDocBadge.
5.13. Skip Link
Ir al contenido principal
↑ En producción el skip link está visualmente oculto (clip) y solo aparece al recibir foco (Tab #1). Este mock lo muestra visible para ilustrar el estilo.
Accesibilidad: primer elemento del DOM. Visible al recibir foco. href apunta a #main-content (el <main> del layout). Permite a usuarios de teclado/lector de pantalla saltar directamente al contenido sin recorrer el sidebar.
6. Responsive — Breakpoints
| Viewport | Rango | Comportamiento |
|---|---|---|
| Móvil | < 640px | Sidebar colapsado en ☰ → drawer lateral overlay. Contenido full-width. Topbar compacto. |
| Tablet | 640–1023px | Sidebar colapsado por defecto, toggle visible. Contenido en columna central ancha. |
| Desktop | ≥ 1024px | Sidebar izquierdo persistente (240px) + contenido central (max 72ch) + índice de página derecho (≥1280px). |
Mínimo móvil: 360px (USA-019). Desktop referencia: 1280px; funcional desde 1024px.
6.1. Maqueta mobile (≤ 640px)
7. Tokens CSS — Referencia completa
Todos los tokens definidos en src/styles/tokens.css (P-02.a). Estado: pre-S-2 (se confirman como definitivos tras firma del Stakeholder).
:root { /* Backgrounds */ --color-bg: #F8FAFC; /* slate-50 */ --color-surface: #FFFFFF; --color-sidebar-bg: #F1F5F9; /* slate-100 */ --color-code-bg: #F1F5F9; --color-code-block-bg: #0F172A; /* slate-900 */
/* Texto */ --color-text: #0F172A; /* slate-900 */ --color-text-muted: #475569; /* slate-600 */ --color-text-faint: #94A3B8; /* slate-400 — solo ≥14px */ --color-text-on-dark: #F8FAFC;
/* Primary */ --color-primary: #2563EB; /* blue-600 */ --color-primary-hover: #1D4ED8; /* blue-700 */
/* Accent */ --color-accent: #7C3AED; /* violet-600 */ --color-accent-soft: #EDE9FE; /* violet-50 */
/* Bordes */ --color-border: #E2E8F0; /* slate-200 */ --color-border-strong: #CBD5E1; /* slate-300 */
/* Callouts */ --color-callout-note: #EFF6FF; /* blue-50 */ --color-callout-warn: #FFFBEB; /* amber-50 */ --color-callout-tip: #F0FDF4; /* green-50 */ --color-callout-tech: #EDE9FE; /* violet-50 */
/* Tipografía */ --font-body: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif; --font-mono: ui-monospace, "SF Mono", Menlo, Monaco, Consolas, monospace;
/* Layout */ --content-max-width: 72ch; --line-height-body: 1.6; --line-height-heading: 1.2;}8. WCAG 2.2 AA — Declaración de cumplimiento
| Criterio | Estado | Notas |
|---|---|---|
| 1.4.3 Contraste (AA) | ✅ (con excepción) | Todos los pares ≥4.5:1 excepto --color-text-faint (excepción USA-013 declarada, solo ≥14px) |
| 1.4.4 Resize text | ✅ | Tipografía en rem/em, sin tamaños fijos en px salvo excepciones documentadas |
| 1.3.1 Información y relaciones | ✅ | <nav> semánticos, <table> con <th>, <dl> en badge, <h1>...<h4> jerárquicos |
| 2.1.1 Teclado | ✅ | Sidebar, drawer, paginación, links, skip link — todo navegable por Tab |
| 2.4.3 Focus visible | ✅ | Outline 2px --color-primary, offset 2px en todos los focusable |
| 2.4.6 Headings y etiquetas | ✅ | Titulares descriptivos, labels en formularios |
| 4.1.2 Nombre, función, valor | ✅ | aria-label, aria-expanded, aria-current="page", aria-hidden donde corresponde |
| Reduced motion | ✅ | @media (prefers-reduced-motion: reduce) en tokens.css deshabilita todas las animaciones |
| Idioma | ✅ | <html lang="es"> (Starlight config: defaultLocale: 'es') |
Validación automatizada: axe-core en CI sobre rutas /, /ciclo/etapa-2, /agentes/po, /gates, /privacidad (P-08 step 9, umbral a11y ≥90).
9. Heredabilidad entre proyectos del arnés
El sistema de diseño de manual-churreria introduce el patrón “documentation hub” al catálogo del arnés:
| Pieza nueva | Descripción | Reusable en proyectos futuros |
|---|---|---|
Layout docs | Sidebar + breadcrumb + contenido + paginación | Sí, para cualquier proyecto de documentación |
Callout tech | Variante agéntico/IA (violeta) | Sí, para proyectos del arnés que documenten agentes |
AgentCard | Ficha estructurada de agente | Sí, para futuras versiones del manual |
LiveDocBadge | Indicador de documentación viva | Sí, si otros proyectos tienen regeneración periódica |
| Paleta Paleta-C clara | Base visual para docs hub | Sí, como paleta de referencia para documentation hubs |
Sistema de diseño — versión 1 (P-11 Etapa 4) · Sub-gate 4.2 S-2 · acta-diseno.md v1 · Propietario: UX churrerIA