En esta página
Docs / UI / Design System

Design System

Guía completa de tokens de diseño, tipografía y componentes del sistema visual "Engineering Notebook". Todos los valores están disponibles como CSS custom properties.

Color Tokens

La paleta del sistema se organiza en cinco grupos funcionales: Base (fondos oscuros), Jerarquía de texto, Acentos neón (estados UI), Syntax (resaltado de código) y Bordes. Cada token se expone como CSS custom property en :root.

Base (The Void)

Fondos del sistema. El color primario --bg-void no es negro puro; contiene un tinte cálido imperceptible que reduce la fatiga visual en sesiones largas de lectura.

—bg-void#0f0f11
—bg-surface#18181b
—bg-surface-hover#27272a
—bg-overlayrgba(15,15,17,0.8)
—bg-code#0a0a0a

Jerarquía de Texto

Cinco niveles de luminosidad para establecer jerarquía sin recurrir a tamaño o peso tipográfico.

—text-primary#f4f4f5
—text-secondary#a1a1aa
—text-muted#71717a
—text-dim#52525b
—text-ghost#3f3f46

Acentos Neón (Estados UI)

Colores de alta saturación reservados para estados interactivos y comunicación semántica. Cada acento tiene un significado funcional asociado.

—accent-yellow#fde047
—accent-pink#f472b6
—accent-cyan#22d3ee
—accent-green#86efac
—accent-red#fb7185
—accent-orange#fb923c
—accent-purple#a78bfa
TokenHexEstado UISignificado Semántico
--accent-yellow#fde047Focus / ActiveAtención primaria, subrayador, advertencias
--accent-pink#f472b6HoverElementos interactivos secundarios, UI decorativa
--accent-cyan#22d3eeLinkEnlaces, arquitectura, flujo de datos
--accent-green#86efacSuccessValidaciones, terminal success, “copiado”
--accent-red#fb7185ErrorErrores de compilación, alertas críticas
--accent-orange#fb923cWarningAdvertencias no críticas, deprecaciones
--accent-purple#a78bfaDecorativeCategorías, badges, tags de contenido

Syntax & Code

Tokens para resaltado de sintaxis en bloques de código. El esquema está basado en una variante personalizada de Dracula/Monokai adaptada al tema oscuro.

—code-keyword#c678dd
—code-func#61afef
—code-string#98c379
—code-comment#71717a

Bordes

—border-default#27272a
—border-subtle#1f1f23
—border-strong#3f3f46

Variables CSS completas

css 
:root {
  /* Base (The Void) */
  --bg-void: #0f0f11;
  --bg-surface: #18181b;
  --bg-surface-hover: #27272a;
  --bg-overlay: rgba(15, 15, 17, 0.8);
  --bg-code: #0a0a0a;

  /* Text Hierarchy */
  --text-primary: #f4f4f5;
  --text-secondary: #a1a1aa;
  --text-muted: #71717a;
  --text-dim: #52525b;
  --text-ghost: #3f3f46;

  /* Neon Accents */
  --accent-yellow: #fde047;
  --accent-pink: #f472b6;
  --accent-cyan: #22d3ee;
  --accent-green: #86efac;
  --accent-red: #fb7185;
  --accent-orange: #fb923c;
  --accent-purple: #a78bfa;

  /* Syntax Highlighting */
  --code-keyword: #c678dd;
  --code-func: #61afef;
  --code-string: #98c379;
  --code-comment: #71717a;

  /* Borders */
  --border-default: #27272a;
  --border-subtle: #1f1f23;
  --border-strong: #3f3f46;
}

Uso de acentos

Los colores de acento neón deben usarse exclusivamente sobre fondos oscuros (—bg-void o —bg-surface). Nunca combines dos acentos como fondo + texto entre sí.

Typography

El sistema tipográfico utiliza cuatro familias con roles claramente diferenciados. La combinación de fuentes técnicas (mono) y manuscritas (hand) refuerza la estética de “cuaderno de ingeniero”.

Familias tipográficas

FuenteVariable CSSUso principalEjemplo
Inter--font-sansBody text, headings de documentaciónThe quick brown fox
JetBrains Mono--font-monoCódigo, labels técnicos, rutas, botonesconst x = 42;
Patrick Hand--font-handNotas al margen, tooltips, comentarios de códigoNota al margen!
Permanent Marker--font-markerTítulos de sección principales del heroHEADER

Escala de tipos (Type Scale)

Configuración base: 16px con line-height de 1.6 para lectura prolongada.

ElementoFuenteTamañoPesoTrackingLine HeightUso
H1 HeroJetBrains Mono48px — 60px700-0.02em1.1Título principal del hero. Estilo técnico impactante.
H1 DocInter36px700-0.01em1.2Título de página de documentación.
H2Inter24px600-0.01em1.3Secciones principales. Borde inferior opcional.
H3Inter20px600Normal1.4Sub-secciones dentro de un H2.
BodyInter16px300 / 400Normal1.6Texto de lectura. Color —text-primary.
Mono TextJetBrains Mono14px400Normal1.5Rutas, variables inline, fragmentos de código.
HandwrittenPatrick Hand18px — 20px4000.02em1.4Notas al margen, tooltips, comentarios visuales.
Label / TagJetBrains Mono12px5000.05em1.2Uppercase. Tags, badges, categorías.

Estrategia de carga de fuentes

Todas las fuentes se cargan desde Google Fonts con display=swap para evitar FOIT (Flash of Invisible Text). El orden de carga prioriza Inter y JetBrains Mono como fuentes críticas.

html 
<link rel="preconnect" href="https://fonts.googleapis.com" />
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@300;400;500;600;700&family=JetBrains+Mono:wght@400;500;700&family=Patrick+Hand&family=Permanent+Marker&display=swap" rel="stylesheet" />
css 
:root {
  --font-sans: 'Inter', system-ui, -apple-system, sans-serif;
  --font-mono: 'JetBrains Mono', 'Fira Code', monospace;
  --font-hand: 'Patrick Hand', cursive;
  --font-marker: 'Permanent Marker', cursive;
}

Fallbacks del sistema

Cada variable incluye fallbacks del sistema operativo. Si Google Fonts no carga, la experiencia se degrada elegantemente a system-ui para sans-serif y monospace para código.

Spacing & Layout

El sistema de espaciado utiliza una escala de 8 niveles basada en rem para garantizar consistencia y adaptabilidad a diferentes tamaños de pantalla.

Escala de espaciado

TokenValorPíxeles (base 16)Uso típico
--space-xs0.25rem4pxSeparación entre íconos y texto, padding de badges.
--space-sm0.5rem8pxGaps internos en botones, padding de tags.
--space-md1rem16pxPadding estándar de componentes, gap de grids.
--space-lg1.5rem24pxSeparación entre bloques de contenido.
--space-xl2rem32pxMargen entre secciones menores.
--space-2xl3rem48pxSeparación entre secciones de documentación.
--space-3xl4rem64pxPadding vertical de secciones principales.
--space-4xl6rem96pxSeparación entre el hero y el contenido.
css 
:root {
  --space-xs: 0.25rem;   /* 4px  */
  --space-sm: 0.5rem;    /* 8px  */
  --space-md: 1rem;      /* 16px */
  --space-lg: 1.5rem;    /* 24px */
  --space-xl: 2rem;      /* 32px */
  --space-2xl: 3rem;     /* 48px */
  --space-3xl: 4rem;     /* 64px */
  --space-4xl: 6rem;     /* 96px */
}

Contenedor principal

El contenido de documentación se limita a un ancho máximo para mantener una longitud de línea óptima (65-80 caracteres).

css 
.doc-container {
  max-width: 72rem;       /* 1152px */
  margin-inline: auto;
  padding-inline: var(--space-md);
}

Breakpoints responsivos

El sistema utiliza un enfoque mobile-first con cuatro breakpoints principales.

NombreMin-widthUso
sm640pxTeléfonos en horizontal, ajustes de texto y padding.
md768pxTablets. Se activa la sidebar de navegación.
lg1024pxDesktop. Layout de documentación completo (sidebar + contenido).
xl1280pxDesktop amplio. Se muestra el Table of Contents a la derecha.
css 
/* Ejemplo de uso de breakpoints */
.doc-layout {
  display: grid;
  grid-template-columns: 1fr;
  gap: var(--space-lg);
}

@media (min-width: 768px) {
  .doc-layout {
    grid-template-columns: 260px 1fr;
  }
}

@media (min-width: 1280px) {
  .doc-layout {
    grid-template-columns: 260px 1fr 240px;
  }
}

Sistema de grid

El grid interno para tarjetas y galerías utiliza auto-fill con tamaño mínimo configurable para adaptarse automáticamente al espacio disponible.

css 
.doc-grid {
  display: grid;
  grid-template-columns: repeat(auto-fill, minmax(280px, 1fr));
  gap: var(--space-lg);
}

Unidades relativas

Siempre usa rem para spacing y em para ajustes proporcionales al tamaño de texto. Evita px fijos excepto en bordes y sombras.

Shadows & Depth

En el sistema “Engineering Notebook” no se utilizan sombras difusas (con blur). Todas las sombras son duras — desplazamiento sólido sin difuminado — para reforzar la estética de pegatina, recorte de papel o sticker sobre el cuaderno.

Escala de sombras

TokenValor CSSUso
--shadow-sm2px 2px 0 0 #27272aBotones pequeños, tags, badges.
--shadow-md4px 4px 0 0 #27272aTarjetas, botones primarios, callouts.
--shadow-lg8px 8px 0 0 #000000Modales, ventanas flotantes, elementos emergentes.
--shadow-neon0 0 10px 0 rgba(34,211,238,0.3)Elementos “encendidos” o activos en diagramas. Única excepción con blur.
--shadow-white4px 4px 0 0 #ffffffBotones sobre fondo oscuro. Alto contraste visual.
css 
:root {
  --shadow-sm: 2px 2px 0px 0px #27272a;
  --shadow-md: 4px 4px 0px 0px #27272a;
  --shadow-lg: 8px 8px 0px 0px #000000;
  --shadow-neon: 0px 0px 10px 0px rgba(34, 211, 238, 0.3);
  --shadow-white: 4px 4px 0px 0px #ffffff;
}

Radios de borde (Border Radius)

TokenValorUso
--radius-sm2pxBotones técnicos, inputs, elementos rectangulares precisos.
--radius-md4pxTarjetas estándar, contenedores de código.
--radius-lg8pxModales, contenedores grandes.
--radius-sketch2px 255px 3px 25px / 255px 5px 225px 5pxEfecto mano alzada. Para elementos con estilo “dibujado”.
css 
:root {
  --radius-sm: 2px;
  --radius-md: 4px;
  --radius-lg: 8px;
  --radius-sketch: 2px 255px 3px 25px / 255px 5px 225px 5px;
}

/* Ejemplo: tarjeta con efecto sketch */
.card-sketch {
  border: 2px solid var(--border-default);
  border-radius: var(--radius-sketch);
  box-shadow: var(--shadow-md);
}

Sin blur

La única excepción a la regla “sin blur” es —shadow-neon, que se reserva exclusivamente para indicadores activos en diagramas interactivos. Nunca apliques blur a sombras de componentes estándar.

Components

Especificaciones detalladas de cada componente del sistema de diseño. Incluyen estructura, estilos base y estados interactivos.

Botón Primario “Terminal”

Botón principal con estética de terminal. Fondo sólido con borde de alto contraste.

css 
.btn-terminal {
  display: inline-flex;
  align-items: center;
  gap: var(--space-sm);
  padding: var(--space-sm) var(--space-lg);
  font-family: var(--font-mono);
  font-size: 14px;
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.05em;
  color: #000000;
  background: #ffffff;
  border: 2px solid #ffffff;
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-white);
  cursor: pointer;
  transition: all 0.2s ease;
}

/* Hover: desplazamiento con sombra */
.btn-terminal:hover {
  transform: translate(-2px, -2px);
  box-shadow: 6px 6px 0px 0px #ffffff;
}

/* Active: efecto de pulsación mecánica */
.btn-terminal:active {
  transform: translate(0, 0);
  box-shadow: none;
}

/* Focus visible: outline de accesibilidad */
.btn-terminal:focus-visible {
  outline: 2px solid var(--accent-yellow);
  outline-offset: 2px;
}

Botón Secundario “Sketch”

Botón transparente con borde estilo dibujado a mano. Menor prominencia visual.

css 
.btn-sketch {
  display: inline-flex;
  align-items: center;
  gap: var(--space-sm);
  padding: var(--space-sm) var(--space-lg);
  font-family: var(--font-mono);
  font-size: 14px;
  font-weight: 500;
  color: var(--text-primary);
  background: transparent;
  border: 2px solid var(--border-default);
  border-radius: var(--radius-sketch);
  cursor: pointer;
  transition: all 0.2s ease;
}

/* Hover: borde neón y leve rotación */
.btn-sketch:hover {
  border-color: var(--accent-yellow);
  color: var(--accent-yellow);
  transform: rotate(-0.5deg);
}

/* Active */
.btn-sketch:active {
  transform: rotate(0deg) scale(0.98);
}

/* Focus visible */
.btn-sketch:focus-visible {
  outline: 2px solid var(--accent-yellow);
  outline-offset: 2px;
}

Input de búsqueda (Ctrl+K)

Campo de búsqueda global con indicador de atajo de teclado.

html 
<div class="search-input">
  <svg class="search-input__icon"><!-- lupa --></svg>
  <input type="text" placeholder="Buscar documentación..." />
  <kbd class="search-input__kbd">Ctrl+K</kbd>
</div>
css 
.search-input {
  display: flex;
  align-items: center;
  gap: var(--space-sm);
  padding: var(--space-sm) var(--space-md);
  background: var(--bg-code);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-sm);
  transition: border-color 0.2s ease;
}

.search-input:focus-within {
  border-color: var(--accent-yellow);
  outline: none;
}

.search-input input {
  flex: 1;
  background: transparent;
  border: none;
  color: var(--text-primary);
  font-family: var(--font-sans);
  font-size: 14px;
  outline: none;
}

.search-input input::placeholder {
  font-family: var(--font-hand);
  color: var(--text-dim);
}

.search-input__kbd {
  padding: 2px 8px;
  font-family: var(--font-mono);
  font-size: 11px;
  color: var(--text-muted);
  background: var(--bg-surface);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-sm);
  box-shadow: var(--shadow-sm);
}

Callout / Admonición (Efecto cinta adhesiva)

No se usan los típicos cuadros de colores planos. Se aplica el concepto de “cinta adhesiva” (tape) para reforzar la estética de cuaderno.

html 
<div class="callout callout--warning">
  <div class="callout__tape"></div>
  <div class="callout__content">
    <span class="callout__icon"><!-- icono --></span>
    <div>
      <strong class="callout__title">Advertencia</strong>
      <p>Contenido del callout...</p>
    </div>
  </div>
</div>
css 
.callout {
  position: relative;
  background: #1f1f23;
  border-left: 4px solid var(--accent-yellow);
  padding: var(--space-md);
  margin-top: var(--space-lg);
}

/* Efecto de cinta adhesiva */
.callout__tape {
  position: absolute;
  top: -12px;
  left: 50%;
  transform: translateX(-50%) rotate(1deg) skewX(12deg);
  width: 96px;
  height: 24px;
  background: rgba(253, 224, 71, 0.2);
  pointer-events: none;
}

.callout__content {
  display: flex;
  gap: var(--space-sm);
}

/* Variantes por tipo */
.callout--warning { border-left-color: var(--accent-yellow); }
.callout--info    { border-left-color: var(--accent-cyan); }
.callout--tip     { border-left-color: var(--accent-green); }
.callout--danger  { border-left-color: var(--accent-red); }

Tablas (Data Grids)

Estilo minimalista sin bordes verticales. Header con fuente monoespaciada.

css 
.doc-table {
  width: 100%;
  border-collapse: collapse;
}

.doc-table thead {
  background: var(--bg-surface);
}

.doc-table th {
  padding: var(--space-sm) var(--space-md);
  font-family: var(--font-mono);
  font-size: 12px;
  font-weight: 500;
  text-transform: uppercase;
  letter-spacing: 0.05em;
  color: var(--text-muted);
  text-align: left;
  border-bottom: 1px solid var(--border-default);
}

.doc-table td {
  padding: var(--space-sm) var(--space-md);
  font-family: var(--font-sans);
  font-size: 14px;
  color: var(--text-primary);
  border-bottom: 1px dashed var(--border-default);
}

.doc-table tbody tr:hover {
  background: var(--bg-surface);
}

Bloques de código (con header y botón de copia)

Cada bloque de código incluye un header con el nombre del lenguaje y un botón para copiar el contenido al portapapeles.

html 
<div class="code-block">
  <div class="code-block__header">
    <span class="code-block__lang">css</span>
    <button class="code-block__copy" aria-label="Copiar código">
      <!-- icono copiar -->
    </button>
  </div>
  <pre class="code-block__pre"><code>...</code></pre>
</div>
css 
.code-block {
  background: var(--bg-code);
  border: 1px solid var(--border-default);
  border-radius: var(--radius-md);
  overflow: hidden;
}

.code-block__header {
  display: flex;
  justify-content: space-between;
  align-items: center;
  padding: var(--space-xs) var(--space-md);
  background: var(--bg-surface);
  border-bottom: 1px solid var(--border-default);
}

.code-block__lang {
  font-family: var(--font-mono);
  font-size: 12px;
  color: var(--text-muted);
  text-transform: uppercase;
}

.code-block__copy {
  padding: var(--space-xs);
  color: var(--text-muted);
  background: transparent;
  border: none;
  cursor: pointer;
  transition: color 0.2s ease;
}

.code-block__copy:hover {
  color: var(--accent-green);
}

.code-block__pre {
  padding: var(--space-md);
  overflow-x: auto;
  font-family: var(--font-mono);
  font-size: 14px;
  line-height: 1.5;
}

Tarjetas de librería (Library Cards)

Tarjetas con rotación sutil que refuerzan la estética de notas pegadas en un cuaderno. Cada tarjeta tiene una rotación pseudo-aleatoria basada en su posición.

css 
.library-card {
  position: relative;
  background: var(--bg-surface);
  border: 2px solid var(--border-default);
  border-radius: var(--radius-md);
  padding: var(--space-lg);
  box-shadow: var(--shadow-md);
  transition: all 0.2s ease;
  transform: rotate(-0.5deg);
}

.library-card:nth-child(even) {
  transform: rotate(0.75deg);
}

.library-card:nth-child(3n) {
  transform: rotate(-0.25deg);
}

/* Hover: se eleva y endereza */
.library-card:hover {
  transform: rotate(0deg) translate(-2px, -4px);
  box-shadow: var(--shadow-lg);
  border-color: var(--accent-cyan);
}

/* Label de categoría */
.library-card__category {
  display: inline-block;
  font-family: var(--font-mono);
  font-size: 12px;
  font-weight: 500;
  text-transform: uppercase;
  letter-spacing: 0.05em;
  padding: 2px 8px;
  border-radius: var(--radius-sm);
}

Rotación de tarjetas

La rotación varía entre -0.75deg y +0.75deg. Para un efecto más orgánico, asigna rotaciones con :nth-child o genera valores aleatorios con JavaScript al montar el componente.

Animations & Transitions

Las animaciones del sistema son sutiles y funcionales. Nunca decorativas sin propósito. La transición estándar es 0.2s ease para todos los estados interactivos.

Transición estándar

css 
/* Valor base para todas las interacciones */
.interactive {
  transition: all 0.2s ease;
}

Hover de tarjetas

Desplazamiento vertical con incremento de sombra. Simula que la tarjeta se “despega” del cuaderno.

css 
.card-hover {
  transition: transform 0.2s ease, box-shadow 0.2s ease;
}

.card-hover:hover {
  transform: translate(-2px, -4px);
  box-shadow: var(--shadow-lg);
}

Efecto de pulsación de botón

El botón se “hunde” al hacer clic, eliminando la sombra para simular una pulsación mecánica.

css 
.btn-press {
  box-shadow: var(--shadow-md);
  transition: all 0.2s ease;
}

.btn-press:hover {
  transform: translate(-2px, -2px);
  box-shadow: 6px 6px 0px 0px var(--border-default);
}

.btn-press:active {
  transform: translate(0, 0);
  box-shadow: none;
  transition-duration: 0.05s;
}

Fade-in de secciones

Animación de entrada para secciones de contenido al hacer scroll. Se activa mediante Intersection Observer.

css 
@keyframes fadeInUp {
  from {
    opacity: 0;
    transform: translateY(16px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.section-animate {
  opacity: 0;
}

.section-animate.is-visible {
  animation: fadeInUp 0.4s ease forwards;
}
js 
// Intersection Observer para activar animaciones
const observer = new IntersectionObserver(
  (entries) => {
    entries.forEach((entry) => {
      if (entry.isIntersecting) {
        entry.target.classList.add('is-visible');
      }
    });
  },
  { threshold: 0.1 }
);

document.querySelectorAll('.section-animate').forEach((el) => {
  observer.observe(el);
});

Rotación estilo sticky-note

Rotación sutil para elementos que simulan notas adhesivas o papeles pegados. El rango va de -0.75deg a +0.75deg.

css 
/* Rotación estática por posición */
.sticky-rotate:nth-child(odd)  { transform: rotate(-0.75deg); }
.sticky-rotate:nth-child(even) { transform: rotate(0.75deg); }
.sticky-rotate:nth-child(3n)   { transform: rotate(-0.25deg); }
.sticky-rotate:nth-child(4n)   { transform: rotate(0.5deg); }

/* Al hacer hover, se endereza */
.sticky-rotate:hover {
  transform: rotate(0deg);
  transition: transform 0.2s ease;
}

Movimiento reducido (Reduced Motion)

Obligatorio respetar la preferencia del usuario para movimiento reducido. Todas las animaciones se desactivan o simplifican.

css 
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }

  .section-animate {
    opacity: 1;
  }

  .sticky-rotate,
  .library-card {
    transform: none !important;
  }
}

Rendimiento

Limita las animaciones a propiedades que el navegador puede optimizar con el compositor GPU: transform y opacity. Evita animar width, height, margin o padding.

Grid Background

El fondo de cuadrícula de ingeniería es un elemento esencial de la atmósfera visual del sistema. Simula el papel milimetrado de un cuaderno técnico.

Especificaciones

  • Tamaño de celda: 40px x 40px
  • Grosor de línea: 1px
  • Color de línea: #27272a (mismo que --border-default)
  • Máscara: Degradado radial que desvanece la cuadrícula en los bordes
  • Opacidad: 0.15 (muy sutil, apenas perceptible)

CSS listo para copiar

css 
.bg-grid-pattern {
  position: fixed;
  inset: 0;
  z-index: 0;
  pointer-events: none;
  background-size: 40px 40px;
  background-image:
    linear-gradient(to right, #27272a 1px, transparent 1px),
    linear-gradient(to bottom, #27272a 1px, transparent 1px);
  mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
  -webkit-mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
  opacity: 0.15;
}

Uso en el HTML

El patrón se coloca como primer hijo del <body> o del contenedor principal, con position: fixed para que cubra toda la ventana sin interferir con el scroll.

html 
<body>
  <div class="bg-grid-pattern" aria-hidden="true"></div>
  <div class="app-content">
    <!-- Contenido de la aplicación -->
  </div>
</body>

Variante con CSS custom properties

Para mayor flexibilidad, se pueden parametrizar los valores con variables:

css 
.bg-grid-pattern {
  --grid-size: 40px;
  --grid-color: var(--border-default);
  --grid-opacity: 0.15;

  position: fixed;
  inset: 0;
  z-index: 0;
  pointer-events: none;
  background-size: var(--grid-size) var(--grid-size);
  background-image:
    linear-gradient(to right, var(--grid-color) 1px, transparent 1px),
    linear-gradient(to bottom, var(--grid-color) 1px, transparent 1px);
  mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
  -webkit-mask-image: radial-gradient(circle at center, black 40%, transparent 100%);
  opacity: var(--grid-opacity);
}

aria-hidden

Siempre incluye aria-hidden=“true” en el elemento del grid. Es puramente decorativo y no debe ser anunciado por lectores de pantalla. Además, pointer-events: none asegura que no interfiera con clics.

Accessibility

El sistema “Engineering Notebook” cumple con las pautas WCAG 2.1 nivel AA. A continuación se detallan los ratios de contraste, estrategias de foco y consideraciones para tecnologías asistivas.

Ratios de contraste WCAG AA

Todos los colores de acento neón sobre los fondos oscuros del sistema superan el ratio mínimo de 4.5:1 para texto normal y 3:1 para texto grande.

ColorHexSobre —bg-void (#0f0f11)Sobre —bg-surface (#18181b)AA NormalAA Grande
--accent-yellow#fde04713.2:112.1:1PasaPasa
--accent-pink#f472b65.9:15.4:1PasaPasa
--accent-cyan#22d3ee9.6:18.8:1PasaPasa
--accent-green#86efac11.5:110.5:1PasaPasa
--accent-red#fb71856.1:15.6:1PasaPasa
--accent-orange#fb923c7.4:16.8:1PasaPasa
--accent-purple#a78bfa5.5:15.0:1PasaPasa
--text-primary#f4f4f516.1:114.7:1PasaPasa
--text-secondary#a1a1aa6.8:16.2:1PasaPasa
--text-muted#71717a4.0:13.6:1Solo grandePasa

--text-muted

El token —text-muted (#71717a) no alcanza el ratio 4.5:1 para texto de tamaño normal. Úsalo solo para texto grande (18px+), elementos decorativos o texto que no sea esencial para la comprensión del contenido.

Estados :focus-visible

Todos los elementos interactivos deben mostrar un indicador de foco visible cuando se navega con teclado. El estilo estándar del sistema es:

css 
/* Estilo de foco global */
:focus-visible {
  outline: 2px solid var(--accent-yellow);
  outline-offset: 2px;
}

/* Eliminar outline nativo solo cuando focus-visible no aplica */
:focus:not(:focus-visible) {
  outline: none;
}
TeclaAcción
Tab / Shift+TabNavegar entre elementos interactivos en orden lógico del DOM.
Enter / SpaceActivar botones, enlaces y controles.
EscapeCerrar modales, menús desplegables y overlays.
Ctrl+KAbrir el buscador global de documentación.
Arrow Up/DownNavegar resultados de búsqueda y menús.

Consideraciones para lectores de pantalla

  • Todos los íconos decorativos llevan aria-hidden="true".
  • Los íconos funcionales incluyen aria-label descriptivo.
  • El grid de fondo siempre lleva aria-hidden="true".
  • Los bloques de código incluyen un aria-label con el lenguaje.
  • Las imágenes de documentación requieren alt descriptivo.
  • El botón de copiar código anuncia “Copiado” con aria-live="polite".
  • Los callouts usan role="note" para ser identificados correctamente.
html 
<!-- Icono decorativo -->
<svg aria-hidden="true">...</svg>

<!-- Icono funcional -->
<button aria-label="Copiar código al portapapeles">
  <svg aria-hidden="true">...</svg>
</button>

<!-- Anuncio de estado -->
<span class="sr-only" aria-live="polite" id="copy-status"></span>

Movimiento reducido

El sistema respeta la preferencia prefers-reduced-motion del usuario. Cuando está activa, todas las animaciones se reducen a transiciones instantáneas y las rotaciones decorativas se eliminan.

css 
@media (prefers-reduced-motion: reduce) {
  *,
  *::before,
  *::after {
    animation-duration: 0.01ms !important;
    animation-iteration-count: 1 !important;
    transition-duration: 0.01ms !important;
    scroll-behavior: auto !important;
  }
}

Clase auxiliar screen-reader-only

Clase utilitaria para contenido visible solo por lectores de pantalla.

css 
.sr-only {
  position: absolute;
  width: 1px;
  height: 1px;
  padding: 0;
  margin: -1px;
  overflow: hidden;
  clip: rect(0, 0, 0, 0);
  white-space: nowrap;
  border-width: 0;
}

Testing de accesibilidad

Verifica los ratios de contraste con herramientas como WebAIM Contrast Checker o la pestaña de Accesibilidad de Chrome DevTools. Prueba la navegación completa con teclado antes de cada release.

END OF DOCUMENT

¿Necesitas más? Volver a la Librería →