Sistema de UI para Bloques de Código

¿Qué hace Sistema de UI para Bloques de Código?

Propósito

El Sistema de UI para Bloques de Código proporciona un marco de diseño estandarizado, accesible y de alta legibilidad para mostrar fragmentos de código fuente, cargas útiles de solicitudes/respuestas de API, ejemplos de código de múltiples archivos, líneas de comandos de terminal y comparaciones de diferencias de código. Los bloques de código son componentes de interacción críticos en documentación técnica, sitios de marketing de herramientas para desarrolladores, portales de API, blogs de ingeniería y plataformas SaaS.

Diseñar interfaces de código efectivas requiere equilibrar la legibilidad tipográfica monoespaciada, el resaltado de tokens de sintaxis de alto contraste en temas claro y oscuro, barras de herramientas de acciones fijas (insignias de lenguaje, navegación por pestañas de archivos, activadores de copia al portapapeles), numeración de líneas, resaltado/enfoque a nivel de línea, comportamientos de ajuste vs. desplazamiento horizontal y experiencias accesibles para lectores de pantalla. Esta habilidad establece reglas espaciales, estándares de contraste de color de tokens, mecánicas de interacción y pautas de cumplimiento WCAG AA para la presentación de UI de código.

Casos de Uso

• Documentación para Desarrolladores y Portales de Referencia de API: Presentar ejemplos de SDK en múltiples lenguajes (p. ej., cURL, Node.js, Python, Go, Rust) y respuestas de API.
• Páginas de Aterrizaje de Herramientas para Desarrolladores: Mostrar fragmentos de código destacados, comandos de instalación CLI y bloques de demostración interactiva de productos.
• Blogs de Ingeniería y Tutoriales: Renderizar ejemplos de código en línea y en bloque con llamadas de línea específicas, resaltados de código paso a paso y anotaciones en línea.
• Interfaces de Control de Versiones y Revisión de Código: Mostrar diferencias de código (adiciones +, eliminaciones -), comentarios en línea y fragmentos de commits.
• Herramientas de Intercambio de Fragmentos y Playground de Código: Estructurar editores de archivos con múltiples pestañas, paneles de vista previa y tarjetas de fragmentos incrustables.

Cuándo NO Usar

• Editores de Código Completos en Navegador (IDE): Para IDE web interactivos complejos que requieren renderizado en canvas, árboles AST virtualizados, edición con múltiples cursores e integraciones de protocolo de servidor de lenguaje (LSP) (p. ej., Monaco Editor, CodeMirror), utilice implementaciones de editores dedicadas.
• Campos de Entrada de Texto Genéricos de Formularios: Para campos de texto plano multilínea sin resaltado de sintaxis ni números de línea, use form-design-system.
• Insignias de Código en Línea: Para referencias de código breves de una sola palabra dentro de párrafos de prosa (p. ej., npm install), use el estilo <code> en línea dentro de article-layout-system.
• Tablas de Datos Estructurados: Para datos tabulares de clave-valor o consultas de bases de datos formateadas como filas y columnas, use data-table-ui-system o property-and-attribute-system.

Entradas

1. Contenido de Código y Tipos de Sintaxis: La taxonomía de lenguaje (p. ej., TypeScript, JSON, Bash, YAML, GraphQL, SQL) y las características estructurales (archivo único, pestañas de múltiples archivos, diferencias).
2. Contexto de Tema: Tokens de paleta de colores activos para fondos de superficie, bordes y tokens de sintaxis en modo claro y modo oscuro (de accessible-color-system y dark-theme-design-system).
3. Tokens de Tipografía Monoespaciada: Pila de fuentes preferida (p. ej., ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace), tamaños de fuente y alturas de línea (de fluid-typography-system).
4. Activadores de Acción: Capacidades interactivas específicas requeridas por bloque (p. ej., botón de copia con 1 clic, alternancia de números de línea, alternancia de ajuste de palabras, expansión a pantalla completa, enlace a sandbox externo).

Salidas

1. Especificación del Contenedor de Código y Barra de Herramientas de Cabecera: Diseños espaciales para contenedores de bloques de código, barras de cabecera fijas, indicadores de lenguaje, pestañas de rutas de archivos y grupos de botones de acción.
2. Paleta de Colores de Tokens de Sintaxis Accesible: Mapeo de colores de tokens WCAG AA (relación de contraste mínima de 4.5:1) para palabras clave, cadenas, funciones, variables, comentarios, operadores y tipos en temas claro y oscuro.
3. Sistema de Jerarquía y Anotación a Nivel de Línea: Plano para numeración de líneas, resaltado/superposiciones de enfoque de líneas, indicadores de diferencias (+ / -) y enlaces de anclaje a nivel de línea.
4. Modelo de Navegación por Teclado y Lector de Pantalla Accesible: Atributos de roles ARIA, rutas de enfoque de teclado, enmascaramiento de números de línea (aria-hidden="true") y anuncios de estado de copia aria-live.
5. Estrategia de Desbordamiento y Desplazamiento Responsivo: Reglas para barras de desplazamiento horizontales, barras de herramientas de acción fijas, alternancias de ajuste de palabras y adaptaciones para viewports móviles.

---

Flujo de Trabajo

1. Estructurar el Shell del Bloque de Código y la Barra de Cabecera

Diseñar el contenedor y la barra de acciones de cabecera como una unidad cohesiva y unificada:

• Arquitectura del Contenedor: Establecer un contenedor redondeado (border-radius: 8px; border: 1px solid var(--border-subtle); overflow: hidden; background: var(--surface-code);). Usar un fondo de superficie distintivo (típicamente modo oscuro por defecto o que coincida con la superficie del tema).
• Diseño de la Barra de Herramientas de Cabecera: Renderizar una barra de cabecera fija en la parte superior (display: flex; align-items: center; justify-content: space-between; padding: 8px 16px; background: var(--surface-code-header); border-bottom: 1px solid var(--border-subtle);).
• Sección Izquierda de la Cabecera (Pestañas y Metadatos):
  • Archivo Único: Mostrar la ruta/nombre del archivo (p. ej., src/auth/jwt.ts) con un icono de tipo de archivo sutil, o una insignia de lenguaje en mayúsculas (p. ej., TYPESCRIPT).
  • Múltiples Archivos / Múltiples Lenguajes: Renderizar botones con pestañas (role="tablist"). La pestaña activa presenta texto de alto contraste y un indicador de borde inferior/píldora (border-bottom: 2px solid var(--brand-primary)).
• Sección Derecha de la Cabecera (Acciones): Agrupar activadores de acciones de utilidad:
  • Botón de Copia: Botón de icono de 32x32px (aria-label="Copiar código al portapapeles") con un icono de copia claro y etiqueta en viewports más amplios.
  • Alternancia de Ajuste / Desplazamiento (Opcional): Botón de icono para alternar el ajuste suave (white-space: pre-wrap) versus el desplazamiento horizontal (white-space: pre).
  • Enlace de Expansión / Sandbox (Opcional): Activador para abrir el fragmento en StackBlitz, CodeSandbox o pantalla completa.

2. Establecer Tipografía Monoespaciada y Cuadrícula de Diseño

Asegurar una legibilidad óptima para la lectura técnica y el escaneo de código:

• Pila de Fuentes: Definir una pila de fuentes monoespaciadas limpia y de alta legibilidad: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace. Asegurar que la configuración de características de fuente permita una distinción clara entre 0 (cero) y O (o mayúscula), y 1 (uno), l (L minúscula) e I (i mayúscula).
• Tamaño de Fuente y Altura de Línea: Establecer font-size: 0.875rem (14px) con una altura de línea generosa (line-height: 1.6 / 22.4px). Evitar alturas de línea ajustadas que hagan que los corchetes y operadores de código choquen.
• Contenedor del Cuerpo de Código: Usar <pre class="code-block"><code class="language-typescript"> con display: block; overflow-x: auto; padding: 16px 0; margin: 0; font-family: var(--font-mono);.

3. Diseñar Números de Línea, Resaltados de Línea y Diferencias

Estructurar elementos a nivel de línea sin degradar el comportamiento de copiar y pegar o del lector de pantalla:

• Estructura de Línea: Formatear cada línea como un contenedor de bloque distinto (display: table-row; o display: flex; width: 100%;).
• Números de Línea: Renderizar números de línea en un margen izquierdo (display: table-cell; text-align: right; width: 40px; padding-right: 16px; user-select: none; color: var(--text-code-muted);).
  • Regla de Accesibilidad: Envolver los números de línea en <span aria-hidden="true"> o usar contenido de contador CSS (content: counter(line)) para que los números de línea no se copien al seleccionar texto y no sean leídos en voz alta por los lectores de pantalla entre declaraciones de código.
• Líneas Resaltadas / Enfocadas: Para atraer la atención sobre líneas clave en un tutorial o diff:
  • Aplicar un fondo de resaltado de línea explícito (background: var(--surface-code-highlight); border-left: 3px solid var(--brand-primary);).
  • Asegurar que la superposición de resaltado cubra todo el ancho desplazable del contenedor de código (min-width: 100%).
• Líneas de Vista de Diferencias (Adición + / Eliminación -):
  • Línea Añadida: Fondo verde sutil (background: rgba(34, 197, 94, 0.15); border-left: 3px solid var(--color-success);). Mostrar un símbolo + en el margen envuelto en <span class="sr-only">Añadido:</span> para lectores de pantalla.
  • Línea Eliminada: Fondo rojo sutil (background: rgba(239, 68, 68, 0.15); border-left: 3px solid var(--color-danger);). Mostrar un símbolo - en el margen envuelto en <span class="sr-only">Eliminado:</span> para lectores de pantalla.

4. Crear una Paleta de Colores de Tokens de Sintaxis Accesible

Los tokens de sintaxis deben cumplir con las relaciones de contraste WCAG AA (mínimo 4.5:1) contra el fondo del bloque de código (var(--surface-code)):

• Texto Base / Variables: Neutro claro (p. ej., #E2E8F0 sobre fondo #0F172A; relación ~12.5:1).
• Palabras Clave (const, import, return, async): Púrpura/magenta vibrante (p. ej., #C084FC; relación ~7.2:1).
• Funciones y Métodos (fetchData, useState): Azul/cian brillante (p. ej., #38BDF8; relación ~8.5:1).
• Cadenas ("https://api.example.com"): Verde/esmeralda suave (p. ej., #4ADE80; relación ~9.1:1).
• Números y Booleanos (404, true): Naranja/ámbar cálido (p. ej., #FB923C; relación ~7.8:1).
• Comentarios (// Manejar respuesta de token): Gris frío apagado con cumplimiento WCAG AA (p. ej., #94A3B8; relación ~5.1:1). Nunca usar grises de bajo contraste (p. ej. 2:1) para comentarios.
• Operadores y Puntuación (=>, {, }, ;): Neutro medio (p. ej., #CBD5E1; relación ~10.2:1).

5. Construir Estados de Acción y Retroalimentación de Copia al Portapapeles

Proporcionar retroalimentación instantánea para acciones de copia evita clics duplicados y frustración del usuario:

• Estado Predeterminado: Mostrar botón de icono con icono de copia (dos rectángulos superpuestos) y etiqueta opcional ("Copiar").
• Estado de Flotación / Enfoque: Fondo de superficie elevado o resaltado de borde (background: var(--surface-hover); outline: 2px solid var(--focus-ring)).
• Estado Activo / Éxito: Al hacer clic, cambiar el icono a un icono de marca de verificación, actualizar la etiqueta del botón a "¡Copiado!" y aplicar un tinte de color de éxito (color: var(--color-success)).
• Notificación para Lector de Pantalla: Anunciar el estado de copia dinámicamente a través de una región invisible aria-live="polite": "Código copiado al portapapeles".
• Restablecimiento por Tiempo de Espera: Restablecer el botón al estado predeterminado después de 2000 ms.

6. Adaptación Móvil y Responsiva

Asegurar que los fragmentos de código largos sigan siendo funcionales en viewports pequeños:

• Contención de Desplazamiento Horizontal: Permitir el desplazamiento horizontal (overflow-x: auto) para líneas largas en móvil sin provocar desbordamientos de la barra de desplazamiento horizontal a nivel de página.
• Barra de Herramientas de Cabecera Fija: Mantener la barra de herramientas de cabecera anclada (position: sticky; top: 0; z-index: 10;) para que el botón de copia y la pestaña de archivo activa permanezcan accesibles incluso al desplazarse por más de 100 líneas de código.
• Objetivos Táctiles Móviles: Asegurar que los botones de copia, las alternancias de ajuste y las pestañas de múltiples archivos cumplan con un objetivo táctil mínimo de 44x44px en dispositivos táctiles.

---

Reglas de Decisión

Contraste de Tokens de Sintaxis y Modos de Tema

Categoría de Sintaxis	Rol de Token Recomendado	Color de Tema Claro (sobre #F8FAFC)	Color de Tema Oscuro (sobre #0F172A)	Relación de Contraste Mínima
Palabras Clave	--token-keyword	Violeta Profundo (#6B21A8)	Violeta Brillante (#C084FC)	≥ 4.5:1
Funciones	--token-function	Cian Oscuro (#0369A1)	Azul Cielo (#38BDF8)	≥ 4.5:1
Cadenas	--token-string	Verde Bosque (#15803D)	Esmeralda Brillante (#4ADE80)	≥ 4.5:1
Números / Booleanos	--token-number	Ámbar Oscuro (#C2410C)	Ámbar Brillante (#FB923C)	≥ 4.5:1
Comentarios	--token-comment	Pizarra Apagado (#475569)	Pizarra Suave (#94A3B8)	≥ 4.5:1
Base / Variables	--token-base	Carbón (#0F172A)	Luz Nítida (#F8FAFC)	≥ 7.0:1

Estrategia de Ajuste vs. Desplazamiento Horizontal

• Desplazamiento Horizontal (white-space: pre) (Recomendado por Defecto): Preserva la integridad del diseño del código, las alineaciones de sangría y el formato multilínea. Esencial para Python, YAML y diferencias de código donde la sangría transmite estructura semántica.
• Ajuste de Palabras Suave (white-space: pre-wrap) (Modo Opcional): Recomendado para cadenas de salida de terminal largas, ejemplos de línea de comandos o widgets de barra lateral estrechos donde el desplazamiento horizontal interrumpe el flujo de lectura.

---

Restricciones

• Accesibilidad (WCAG 2.1 AA):
  • SC 1.4.3 Contraste (Mínimo): Todos los colores de tokens de resaltado de sintaxis y comentarios deben lograr una relación de contraste mínima de 4.5:1 contra el fondo del código.
  • SC 2.1.1 Teclado: Los usuarios deben poder navegar y activar los botones de la cabecera del bloque de código (pestañas, botón de copia) usando Tab y Espacio/Enter.
  • SC 4.1.3 Mensajes de Estado: La retroalimentación del botón de copia debe anunciarse a la tecnología de asistencia a través de una región aria-live="polite".
  • SC 1.3.1 Información y Relaciones: Los números de línea deben ocultarse de los lectores de pantalla (aria-hidden="true" o contadores CSS) para evitar dígitos intercalados durante la lectura.
• Selección de Texto y Copia: La selección de texto dentro del bloque de código nunca debe seleccionar números de línea o marcadores de diferencias (+ / -) en el búfer del portapapeles.
• Prevención de Cambios en el Diseño (CLS): La expansión de pestañas de múltiples archivos o la alternancia del ajuste de línea debe especificar alturas de línea fijas o límites de contenedor para prevenir el Cambio Acumulativo en el Diseño (CLS).

---

Patrones de Falla Comunes

• Comentarios Ileíbles de Bajo Contraste: Usar texto gris tenue (p. ej., #4A5568 sobre #1A202C, contraste 2.8:1) para comentarios, asumiendo que los comentarios no son importantes, violando las pautas WCAG AA.
• Copiar Números de Línea: Renderizar números de línea como texto sin formato dentro de <pre>, lo que provoca que copiar y pegar produzca fragmentos de código no válidos prefijados con 1 2 3 4.
• Acciones de Copia No Anunciadas: Cambiar los iconos visuales del botón de copia sin actualizar aria-label o enviar un anuncio aria-live, dejando a los usuarios de lectores de pantalla inseguros sobre si la acción tuvo éxito.
• Derrames de Desbordamiento a Nivel de Página: No establecer max-width: 100% y overflow-x: auto en <pre>, lo que provoca que líneas de código de 120 caracteres rompan el diseño de la página en pantallas móviles.
• Trampas de Enfoque Inaccesibles en Desplazamiento Horizontal: Colocar tabindex="0" en el bloque de código desplazable sin indicadores visuales de contorno de teclado claros, lo que hace que los usuarios de teclado se queden atascados dentro de bloques de código largos.

---

Criterios de Validación

• El bloque de código cuenta con un contenedor estructurado con una barra de herramientas de cabecera fija que muestra el lenguaje, el archivo...

[truncado para traducción]