Especificación de la fase 2: propuesta accesible, comentarios y sitio del proyecto

Esta fase cambia tres cosas: los criterios con que se escribe y diseña todo lo nuevo, el clon de Casiopea (que suma un modo de comentarios) y el sitio del proyecto (que deja el chrome de la wiki y pasa a ser un sitio propio, hijo de Stella Nova).

---

0. Problema, usuarios y criterio de éxito

Problema. Las ayudas deben permitir que cada persona aprenda de forma progresiva y gane independencia. Hoy la propuesta tiene la estructura (Diátaxis, ficha, recorridos), pero no tiene criterios explícitos de accesibilidad, usabilidad e inclusión que guíen cada texto y cada elemento. Además, la revisión de la propuesta ocurre fuera del sitio: no hay forma de dejar observaciones sobre un bloque concreto.

Usuarios.

Criterios de éxito.

1. Accesibilidad: todo lo nuevo cumple WCAG 2.2 nivel AA (lista de verificación en §7) en claro y oscuro, en los tres tamaños de letra y las dos familias de la skin.
2. Aprendizaje progresivo: en el test con usuarios, al menos el 80 % completa las 4 tareas sin ayuda, y al menos la mitad resuelve una quinta tarea nueva usando solo la referencia (Consultar) que conoció durante las anteriores. Esa quinta tarea mide la independencia.
3. Comentarios: una persona deja un comentario sobre un bloque en menos de 30 segundos, con mouse, con teclado o en el celular, y otra persona lo ve en su propio navegador.
4. Sitio del proyecto: toda la documentación es accesible desde la navegación, sin nada oculto detrás de un inicio de sesión ni de un plegado sin indicar.
5. Fidelidad: el clon no se distingue de la wiki real y el sitio del proyecto no se distingue de un espécimen de Stella Nova (método en §6).

---

1. Criterios de base

1.1 W3C: accesibilidad, usabilidad e inclusión (fuente)

• Se abordan juntas y desde el inicio: no se agrega accesibilidad al final.
• Accesibilidad: que las personas con discapacidad puedan percibir, entender, navegar e interactuar en igualdad de condiciones. Se usa WCAG como norma.
• Usabilidad: que la experiencia sea efectiva, eficiente y satisfactoria para todos.
• Inclusión: considerar idioma, nivel de lectura, conexión, dispositivo y experiencia previa (por ejemplo, alumnos de primer año que nunca han editado una wiki).
• Involucrar personas reales, incluidas personas con discapacidad, en el test (§8).

1.2 NN/g

• Ayuda y documentación (heurística 10, fuente): ayuda proactiva breve y descartable, y ayuda reactiva completa; preferir la ayuda que el usuario pide en contexto (pull) a la que se le impone (push); textos que se escanean (jerarquía, bloques cortos, listas); organizar por tarea y por nivel de experiencia.
• Revelado progresivo (fuente): dos niveles como máximo; lo frecuente a la vista y lo avanzado en un segundo nivel; el acceso al segundo nivel debe ser visible y con una etiqueta que anticipe su contenido; no separar cosas que se usan juntas.

1.3 Interaction Design Foundation

• Revelado progresivo y carga cognitiva (fuente): mostrar lo que se necesita cuando se necesita; señales claras (flechas, botones, etiquetas) de dónde hay más; un solo camino hacia cada información; ayuda contextual y recorridos iniciales que se pueden saltar.

1.4 Criterios propios del proyecto

Los criterios anteriores se aplican sobre dos bases que el proyecto no negocia: Diátaxis, que ordena el contenido, y Stella Nova, que define la interfaz. Sobre ellas, cada ayuda debe ser accesible, usable e inclusiva. Las reglas que permiten verificarlo están en §1.5.

Diátaxis: un propósito por ayuda. Siguiendo Diátaxis: el marco de las ayudas, toda página pertenece a uno de los cuatro modos: aprender, resolver, consultar o entender.

• Una ayuda no mezcla modos. Si la persona necesita otro tipo de información, la página la enlaza con un puente a la ayuda que corresponde.
• La portada permite entrar por lo que la persona quiere hacer, no solo por el tema.
• Cada modo tiene su forma propia: el tutorial acompaña paso a paso, la guía va directo a la tarea, la referencia es exacta y la explicación da el porqué.

Stella Nova: la skin manda. Las ayudas se construyen con lo que Casiopea ya tiene, para verse y comportarse como el resto de la wiki.

• Solo se usan los tokens semánticos y los componentes de la skin. No se crean colores, tipografías ni componentes que compitan con ella; si falta algo, se propone como mejora de la skin (§5).
• Se respetan las preferencias de lectura de la skin (tema claro u oscuro, tamaño de letra y familia tipográfica): ninguna ayuda las anula.
• Todo componente se puede publicar en la wiki como plantilla con su propia hoja de estilos (TemplateStyles), sin código externo ni cambios en el servidor. Lo que se prueba en el prototipo es lo mismo que se lleva a Casiopea.

Accesibilidad. Todo lo nuevo cumple WCAG 2.2 nivel AA, en tema claro y oscuro.

• Se usa completo con teclado, con el foco siempre visible y en un orden lógico (C7).
• Ningún significado depende solo del color: el modo y el estado se leen también por forma y por texto (C5).
• Los textos y controles tienen contraste suficiente, y los objetivos táctiles miden al menos 24 × 24 px (C8).
• La estructura es semántica (títulos, listas, tablas y regiones), para que se pueda recorrer con lector de pantalla.
• Se respetan el movimiento reducido, el alto contraste, los colores forzados y el texto ampliado al 200 % (C9, C10).

Usabilidad. Encontrar y usar una ayuda debe ser rápido y predecible.

• Cualquier ayuda está a dos clics como máximo: barra de la wiki, portada de ayudas y página.
• La primera línea dice qué se logra y cuánto toma (C1); el resto se ordena para escanear: bloques cortos, listas y títulos claros.
• El detalle avanzado se revela a pedido y en un solo nivel (C2, C4), para no cargar la página de entrada.
• Todas las ayudas de un mismo modo tienen la misma estructura, así lo aprendido en una sirve para la siguiente.
• Nunca hay un callejón sin salida: una ayuda pendiente ofrece qué usar mientras tanto, y cada ayuda termina con qué sigue (C3).

Inclusión. Las ayudas sirven a personas con distinta experiencia, contexto y dispositivo.

• Lenguaje claro: palabras comunes antes que técnicas, frases cortas y definición en línea de los términos propios de Casiopea, enlazados al glosario (C6).
• El perfil (Lector, Alumno, Profesor, Administrador, Mantenedor) es una pista para empezar, no una barrera: todas las ayudas quedan disponibles para todos.
• Se diseña primero para el teléfono: todo se lee sin desplazamiento horizontal desde 320 px de ancho (C9).
• El contenido funciona aunque falle JavaScript o la conexión sea lenta; lo interactivo es una mejora, no un requisito.
• Cada ayuda sube un peldaño hacia la autonomía (§2): quien empieza recibe acompañamiento y quien ya sabe va directo a lo que busca.

1.5 Traducción a reglas verificables

---

2. Aprendizaje progresivo: la escalera de autonomía

Cada persona pasa de depender de la ayuda a resolver sola. Las ayudas se encadenan para que cada recorrido suba un peldaño:

Reglas:

• C3 se cumple con el pie «Después» de la ficha: un tutorial sugiere una guía; una guía, su referencia; una referencia, su explicación.
• La ficha muestra el peldaño de cada ayuda con texto («Paso 2 de 4 hacia la autonomía»), no con una barra de progreso que no tiene datos reales.
• Las definiciones en línea enseñan el vocabulario la primera vez y enlazan al glosario. Así, la siguiente ayuda puede usar el término sin explicarlo.

---

3. Superficie A: el clon de Casiopea

El clon muestra solo los resultados aplicados: las ayudas tal como se verían en la wiki. No muestra documentación del proyecto. Mantiene el chrome capturado sin cambios, salvo el control del modo comentarios y el interruptor de revisión, que viven en las herramientas de usuario de la barra.

3.1 Modo comentarios

Qué hace. Permite marcar un bloque de la página (un título, un párrafo, un elemento de lista, una tabla o un componente) y dejar un comentario con usuario, fecha y hora, y texto.

Flujo.

1. En la barra, el botón Comentar activa el modo. Mientras está activo, el botón queda presionado (aria-pressed="true") y un aviso en la página dice «Modo comentarios: elige un bloque».
2. Al pasar el cursor o al llegar con Tab, cada bloque comentable muestra un contorno. Con clic, toque o Enter se elige.
3. Se abre un panel lateral (en móvil, un panel inferior) con:
   • el bloque elegido, citado en una línea;
   • los comentarios que ya tiene ese bloque;
   • el formulario: Tu nombre (se recuerda en ese navegador), Comentario (obligatorio, hasta 1000 caracteres) y Publicar.
4. La fecha y la hora las pone el servidor al guardar y se muestran en hora de Chile (por ejemplo, «5 oct 2026, 16:42»).
5. Los bloques con comentarios llevan un contador (número en cápsula) que abre el panel en ese bloque.
6. Un listado de todos los comentarios de la página, en orden del documento, permite recorrerlos y saltar a cada bloque.
7. Escape cierra el panel y devuelve el foco al bloque. Volver a presionar Comentar sale del modo.

Anclaje. El generador da a cada bloque un identificador estable (data-mx-bloque), calculado a partir de la página, el tipo de elemento y su posición dentro de su sección. Si una página cambia y un bloque desaparece, sus comentarios no se pierden: quedan en el listado como «Bloque que ya no existe», con la cita original.

Almacenamiento compartido (Vercel).

• Una función del servidor (api/comentarios) con dos operaciones: listar los comentarios de una página y publicar uno nuevo.
• Cada comentario se guarda como un archivo JSON propio en Vercel Blob (comentarios/<página>/<fecha>-<id>.json). Un archivo por comentario evita que dos personas que publican a la vez se pisen.
• Validación en el servidor: nombre y texto obligatorios, longitud máxima, texto plano (sin HTML).
• Sin servidor (por ejemplo, al abrir el sitio desde la carpeta local), el comentario se guarda en el navegador y el panel avisa «Sin conexión al servidor: tu comentario se guardó solo en este navegador». Un botón Exportar descarga los comentarios en un archivo .json.

Accesibilidad. El panel es una región complementary con título; los avisos de «Comentario publicado» o de error se anuncian con una región aria-live; los contornos y contadores no dependen solo del color; el modo se apaga con ?revision=0, igual que el resto de la capa de revisión.

Comentarios en el sitio del proyecto. El mismo modo existe en todas las páginas del proyecto, con el botón Comentar en la cabecera. Cada comentario guarda su superficie: prototipo (páginas de la wiki) o proyecto (documentación). El panel lo dice en su título («Comentarios sobre el prototipo» o «Comentarios sobre la documentación») y explica qué se comenta en cada lugar. La página Comentarios del proyecto reúne todos, del más reciente al más antiguo, con un filtro Todos, Del prototipo y Del proyecto.

Ir a la documentación. La barra de herramientas del prototipo tiene el botón Ir a la documentación, siempre visible (en móvil, en la barra flotante). Pasa por el aviso de salida, que explica cómo volver.

Fuera de alcance. Responder comentarios en hilo, editar o borrar desde la interfaz (se hace desde el almacenamiento) e inicio de sesión.

---

3.2 Aviso de salida

Antes de ir a la wiki real, a un sitio externo o a la documentación del proyecto, un diálogo dice a dónde se va y cómo volver.

• Opciones: Quedarme en el prototipo (con el foco, por defecto), Abrir en una pestaña nueva (el prototipo queda abierto) y Salir en esta pestaña (o Ir a la documentación).
• Bloque «Para volver»: usar Atrás del navegador, o el botón «Ver prototipo» de la cabecera del proyecto.
• «No volver a avisar en esta visita» lo apaga por tipo de destino hasta cerrar el navegador. Escape o clic fuera cierran sin salir.
• Clic con Ctrl, Cmd, Mayúscula o rueda abre directo: la persona ya eligió abrir aparte.

3.3 Recorrido de bienvenida

Cuatro pasos que señalan elementos reales de la página: 1) esto es un prototipo (aviso superior), 2) dónde están las ayudas (menú → Wiki → Ayuda, con botón a la portada de ayudas), 3) Comentar y Revisión, 4) dónde está la documentación (con botón para ir).

• Aparece la primera vez en cada navegador; no aparece con ?revision=0.
• Se repite con «Cómo usar» en la barra o con «Cómo usar este prototipo» en el aviso superior.
• Se puede saltar en cualquier paso; Escape lo cierra. Todo lo demás de la página queda oscurecido e inactivo mientras dura.

---

4. Superficie B: el sitio del proyecto y el espécimen

Todo lo que no es el clon (resumen, árbol, decisiones, carta Gantt, documentos y espécimen) deja el chrome de la wiki y pasa a un sitio propio, hijo de Stella Nova.

4.1 Qué significa «hijo de Stella Nova»

• Usa los archivos de la skin sin modificarlos: tokens.css, stella-nova.css, fuentes e íconos.
• Toma la estructura del espécimen publicado: cabecera spec-top con marca, navegación y controles; contenido en spec-main; una sección por tema.
• No desafía ningún elemento existente: no redefine tokens, no cambia la apariencia de un componente de la skin y no inventa una variante de algo que ya existe.
• Propone elementos nuevos en una capa aparte y señalada (§5).

4.2 Preferencias y accesibilidad (las mismas de la wiki)

Se usan las mismas claves que la skin, así una preferencia elegida en el clon se mantiene en el sitio del proyecto. Además: vista de impresión, movimiento reducido (prefers-reduced-motion), alto contraste (prefers-contrast: more) y colores forzados (forced-colors).

4.3 Detectar lo que el navegador soporta

El sitio usa funciones modernas de CSS que la skin ya usa (light-dark(), color-mix(), :has()) y algunas nuevas (por ejemplo, popover para los paneles). Cada una:

• se usa como mejora progresiva, con una alternativa que funciona sin ella (@supports en CSS y detección en JavaScript);
• aparece en una tabla del Resumen del proyecto, «Este navegador», que muestra qué funciones están disponibles en el navegador de quien mira y qué alternativa se está usando.

4.4 Toda la documentación a la vista

• La navegación lista todas las páginas del proyecto, sin menús ocultos en escritorio. En móvil, la navegación se abre con un botón con etiqueta («Secciones») y no solo con un ícono.
• Cada documento muestra su índice de secciones al inicio.
• Los plegados se usan solo para detalles secundarios, siempre con una etiqueta que dice qué contienen (regla C2).

4.5 Responsive, mobile first

• Se diseña primero a 360 px y se amplía. Puntos de quiebre: los de la skin (48rem y 64rem).
• Tablas largas: a menos de 48rem cada fila pasa a ser una ficha apilada (como el catálogo de incrustables).
• Carta Gantt: en móvil, lista por semana (ya existe).

---

5. Propuestas a Stella Nova

El espécimen muestra solo los elementos de las ayudas; por eso allí aparece únicamente la propuesta 5.2. Las propuestas viven en una sección propia, «Propuesta para la skin», con el mismo mecanismo que usa el espécimen de la skin para sus pruebas: una hoja de overrides que se carga aparte y que se puede encender y apagar. Así se ven con la skin y sin ella.

5.1 Capa de revisión: token de nota y componente «Comentario anclado» (fuera del espécimen)

Problema. Hoy la revisión usa --sn-warn (ámbar) para las decisiones. El ámbar significa «advertencia» en el resto de la wiki, y una anotación no es una advertencia.

Tokens propuestos (capa semántica):

Componente «Comentario anclado»: contorno del bloque, contador en cápsula (uso permitido de --sn-radius-pill: es un número) y tarjeta de comentario (nombre, fecha y hora, texto). Lo usarían el modo comentarios y, si se aprueba, los marcadores de decisión.

5.2 Modos de Diátaxis: marca de modo

Problema. El sello de modo (forma + palabra) es útil fuera de las ayudas, por ejemplo, en cualquier página que se quiera clasificar como tutorial o referencia.

• Componente: sn-badge-modo, variante oficial del badge con la forma de cada modo (●, ▲, ■, ◆).
• Tokens: --sn-mode-mark (color de la forma; por defecto, --sn-icon) y --sn-mode-mark-size (tamaño de la forma, relativo al texto). No hay un color por modo: la forma y la palabra distinguen.

---

6. Fidelidad («pixel perfect»)

Los valores computados (tamaño, interlineado, colores resueltos) se comparan con una herramienta automática, además de la comparación visual. Cualquier diferencia se corrige o se registra como decisión.

---

7. Lista de verificación de accesibilidad (WCAG 2.2 AA)

• Contraste de texto 4,5:1 (3:1 en texto grande) y de componentes 3:1, en claro y oscuro.
• Todo funciona con teclado; foco siempre visible; sin trampas de foco.
• Orden de lectura y de foco lógico; encabezados en jerarquía; regiones (banner, navigation, main, complementary, contentinfo).
• Idioma de la página declarado (lang="es").
• Objetivos táctiles de 24 × 24 px como mínimo.
• Sin desplazamiento horizontal a 320 px; legible con texto al 200 %.
• Nada depende solo del color.
• Mensajes de estado anunciados (aria-live).
• Formularios con etiquetas visibles, errores en texto y sin límite de tiempo.
• Movimiento reducido, alto contraste y colores forzados respetados.
• Probado con VoiceOver (macOS e iOS) y con NVDA o Narrador.

---

8. Test con usuarios

• 3 a 5 personas, de las cuales al menos una usa tecnología de apoyo (lector de pantalla, ampliación o solo teclado) y al menos una lo hace desde el celular.
• Tareas: las 4 de la SPEC más una quinta tarea de independencia, resuelta solo con una referencia (criterio de éxito 2).
• Con ?revision=0: sin marcadores ni modo comentarios.

---

9. Decisiones

---

10. Plan y avance

Verificación del 5 oct 2026

• Revisión automática con axe (WCAG 2.0, 2.1 y 2.2, niveles A y AA) en 7 páginas, en claro y oscuro, con el modo comentarios abierto: sin errores.
• Fidelidad: los valores computados de la cabecera, la navegación, los títulos, la entrada, las notas, el código y el pie del espécimen del proyecto son idénticos a los del espécimen de Stella Nova v0.9.0 a 1280 px, en claro y oscuro.
• Sin desplazamiento horizontal a 320 px en el sitio del proyecto y en las ayudas. En móvil, los controles de revisión flotan abajo para que la cabecera sea idéntica a la de la wiki.
• Corrección: el foco usaba --sn-focus-ring, que es una sombra y no un color, y quedaba invisible. Ahora usa --sn-focus-border, como la skin.

---

11. Referencias

• W3C WAI: Accessibility, Usability, and Inclusion · WCAG 2.2
• NN/g: Help and Documentation · Progressive Disclosure
• Interaction Design Foundation: Progressive Disclosure
• Stella Nova: espécimen publicado
• Para fases futuras (adopción, documentación y medición del sistema de diseño): serie «Sistemas de diseño 101» de Figma (¿Qué es un sistema de diseño?, Cómo crear tu sistema de diseño, Cómo impulsar la adopción, Cómo seguir el ROI), guardada en micrositio-ayudas-trabajo/referencias/.