Primitivos de interfaz — Una guía de campo
Si alguna vez has mirado una aplicación moderna y pensado “¿cómo llaman a esa cosa?” — esta página es para ti.
Cada interfaz que usas está construida a partir de un conjunto sorprendentemente pequeño de bloques reutilizables llamados primitivos de interfaz. Tienen nombres. A veces, nombres raros. Pero una vez que ves la metáfora, ya no puedes dejar de verla.
En Parlant~ usa Mantine, una biblioteca de componentes React que proporciona todos estos elementos de serie. Aquí tienes tu guía de campo.
Los que suenan a mobiliario
Sección titulada «Los que suenan a mobiliario»Un toast es una pequeña notificación que aparece desde el borde de la pantalla, se queda unos segundos y luego se desliza hasta desaparecer. Como una rebanada de pan que salta de la tostadora — excepto que la gravedad funciona al revés y eventualmente vuelve a meterse.
En En Parlant~, los toasts aparecen en la esquina inferior derecha (mediante @mantine/notifications de Mantine) para cosas como:
- “Base de datos cargada correctamente” — pop
- “Voz TTS no configurada” — pop
- “Error al conectar con Lichess” — pop, y te sientes un poco triste
Nunca los pediste. Simplemente aparecen, entregan su mensaje y se van. Son las palomas mensajeras del mundo de la interfaz.
Una card (tarjeta) es un contenedor rectangular con un borde o sombra que agrupa contenido relacionado. Imagina una ficha sobre un escritorio — tiene un borde definido, contiene una sola cosa y puedes tomarla y moverla.
En En Parlant~, verás tarjetas para:
- Vistas previas de partidas en el explorador de bases de datos (
GameCard) — nombres de jugadores, resultado, fecha - Editor de posición del tablero (
EditingCard) — la tarjeta que volteas al configurar una posición personalizada - Entradas de bases de datos en la página de bases de datos — cada base de datos tiene su propia tarjeta en una cuadrícula
Las tarjetas tienen un primo cercano llamado Paper, que es básicamente una tarjeta que fue a la escuela de arte. La misma idea — un contenedor con borde o sombra — pero con menos significado semántico. Paper simplemente dice “soy una superficie”. Aparece como fondo detrás de los paneles de análisis y las vistas de información de bases de datos.
Drawer / Sheet
Sección titulada «Drawer / Sheet»Actualmente no se usa en En Parlant~, pero vale la pena conocerlo: un drawer (cajón) es un panel que se desliza desde el borde de la pantalla, como un cajón de escritorio. (Eso es todo. Esa es toda la metáfora. Los diseñadores de interfaces estuvieron muy literales ese día.)
Los que bloquean tu camino
Sección titulada «Los que bloquean tu camino»Un modal es un diálogo emergente que exige tu atención. Oscurece el fondo y te obliga a lidiar con él antes de hacer cualquier otra cosa. Es el niño pequeño de los patrones de interfaz — “MÍRAME AHORA MISMO.”
En Parlant~ usa modales para momentos que genuinamente necesitan tu atención:
- “¿Seguro que quieres borrar todos los datos?” (
ClearDataModal) — con casillas de verificación para que elijas qué datos obliterar - “Hay una actualización disponible” (
UpdateModal) — con una barra de progreso mientras se descarga - “Importar una partida” (
ImportModal) — pega un PGN, introduce un FEN o suelta un enlace - “Crear un nuevo repertorio” (
CreateRepertoireModal) — nómbralo, configúralo, adelante - “Acerca de En Parlant~” (
About) — información de versión, créditos, el habitual pase entre bastidores
Los modales dicen: “Esto es una conversación. La estamos teniendo ahora.”
Un dialog (diálogo) es el primo educado del modal. En Mantine son esencialmente el mismo componente, pero en la teoría del diseño de interfaces, un diálogo es más pequeño y más enfocado — una sola pregunta y respuesta. “¿Guardar cambios?” Sí / No. Listo.
En Parlant~ usa ConfirmModal para estos rápidos momentos de sí o no, como confirmar que quieres descartar cambios sin guardar.
Los que van y vienen
Sección titulada «Los que van y vienen»Tooltip
Sección titulada «Tooltip»Un tooltip (información emergente) es una pequeña etiqueta que aparece al pasar el ratón sobre algo. Es el extraño amable que te susurra la respuesta cuando pareces confundido.
Los tooltips están por todas partes en En Parlant~. Pasa el ratón sobre casi cualquier botón de icono y aparecerá uno:
- Pasa el ratón sobre el botón ↻ → “Recargar”
- Pasa el ratón sobre una ruta de archivo truncada → aparece la ruta completa
- Pasa el ratón sobre un símbolo de anotación → qué significa ese símbolo
- Pasa el ratón sobre un movimiento en el panel de análisis → aparece una vista previa del tablero en miniatura
Los tooltips son el “no se necesita manual” original.
Popover
Sección titulada «Popover»Un popover es un tooltip que hizo un posgrado. En lugar de mostrar solo una etiqueta de texto, puede contener cualquier cosa — botones, imágenes, incluso un pequeño tablero de ajedrez.
En En Parlant~, cuando pasas el ratón sobre un movimiento en el análisis del motor, un popover muestra una vista previa del tablero en esa posición. Es un tooltip, pero que trajo material visual.
Un menu (menú) es una lista de acciones que aparece cuando haces clic (o clic derecho) en algo. Los has usado desde los albores de la informática — Archivo, Editar, Ver. Ya conoces el procedimiento.
En Parlant~ tiene dos variantes:
- Menús de la barra superior — la clásica barra de menú Archivo / Editar / Ver, construida con el componente
Menude Mantine. Atajos de teclado listados a la derecha. Un patrón de diseño tan antiguo que ya tiene pensión. - Menús contextuales — haz clic derecho en un movimiento del árbol de la partida y obtendrás opciones como Promover Variante, Eliminar desde Aquí y Copiar Línea. Estos usan la biblioteca
mantine-contextmenupara un acabado extra.
Los menús tienen su propio sub-vocabulario: Menu.Target (lo que haces clic), Menu.Dropdown (la lista que aparece), Menu.Item (cada opción) y Menu.Divider (la línea fina que dice “ahora empieza otra sección”).
Los que organizan el espacio
Sección titulada «Los que organizan el espacio»Stack y Group
Sección titulada «Stack y Group»Son la mantequilla y el pan del diseño de maquetación.
- Stack organiza cosas verticalmente — una encima de otra. Como apilar libros.
- Group organiza cosas horizontalmente — una al lado de la otra. Como alinear piezas de ajedrez en una estantería.
Aparecen en literalmente más de 100 archivos cada uno. Son los componentes más comunes de toda la aplicación. Cada vez que las cosas están ordenadamente dispuestas, un Stack o Group es responsable.
Flex es el primo navaja suiza de Stack y Group. Cuando las cosas necesitan ajustarse, estirarse, encogerse, invertirse o comportarse de forma irregular, Flex interviene con control total sobre el modelo CSS Flexbox.
Se usa en la lista de movimientos del panel de análisis — esas secuencias de movimientos que se ajustan y fluyen como texto? Eso es Flex haciendo el trabajo pesado.
Un Box es un <div> con sombrero de copa. No hace nada por sí solo — es simplemente un contenedor genérico. Pero acepta las propiedades de estilo de Mantine, lo que lo convierte en un envoltorio increíblemente práctico para “necesito algo alrededor de esta otra cosa.”
Box aparece en más de 150 archivos. Es la cinta adhesiva de la biblioteca de componentes.
Hace exactamente lo que dice. Pone algo en el centro. Horizontalmente. Verticalmente. Ambos. Listo.
Aparece en estados vacíos — cuando no hay cuentas vinculadas, no hay bases de datos cargadas, no hay datos aún. Un icono grande, un mensaje, y Center asegurándose de que esté perfectamente posicionado. A nadie le gusta un estado vacío descentrado.
SimpleGrid
Sección titulada «SimpleGrid»Una cuadrícula que es simple. Le dices cuántas columnas quieres y organiza tus tarjetas en una cuadrícula ordenada que se reajusta cuando cambia el tamaño de la ventana. La página de bases de datos la usa para disponer las tarjetas de bases de datos en una cuadrícula responsiva.
ScrollArea
Sección titulada «ScrollArea»Un contenedor que permite desplazamiento cuando su contenido desborda. Pensarías que esto vendría gratis — y en cierto modo así es, con CSS overflow: auto — pero ScrollArea añade barras de desplazamiento estilizadas, desplazamiento con inercia y detección de desbordamiento. Envuelve el panel del árbol de partida, las líneas de análisis y cualquier lugar donde el contenido pueda crecer más que su contenedor.
AppShell
Sección titulada «AppShell»El AppShell es la maquetación maestra — el esqueleto de toda la aplicación. Define dónde va el encabezado, dónde va la barra lateral y dónde vive el contenido principal. Todo lo demás se anida dentro.
Solo lo usas una vez. Es los cimientos de la casa.
Un Portal es un agujero de gusano mágico. Renderiza un componente fuera de su posición normal en el árbol del DOM y lo coloca en otro lugar — generalmente en la raíz del documento. Así es como los popovers y las vistas previas del tablero evitan ser recortados por contenedores padre con overflow: hidden.
Nunca ves un Portal. Solo ves sus efectos. Es el equipo de tramoya de los componentes de interfaz.
Los que te permiten interactuar
Sección titulada «Los que te permiten interactuar»Un rectángulo clicable con texto. Ya lo conoces. En Mantine, los botones vienen en variantes:
- filled — color sólido, alto énfasis. “Haz clic en mí, soy importante.”
- outline — solo un borde. “Soy una opción, pero sin presión.”
- subtle — apenas visible. “Estoy aquí si me necesitas.”
- default — un punto medio neutral.
En Parlant~ usa todos estos en más de 150 archivos. El patrón más común: un Group de botones en la parte inferior de un modal — “Cancelar” (subtle) y “Confirmar” (filled). Un clásico.
ActionIcon
Sección titulada «ActionIcon»Un ActionIcon es un botón que renunció a su etiqueta de texto y se comprometió completamente con el estilo de vida del icono. Es compacto, cuadrado y depende de su icono (más un tooltip) para comunicar su propósito.
Botones de barra de herramientas, controles de panel, botones de cerrar — todos son ActionIcons. Son la forma más eficiente en espacio de ofrecer una acción.
Un Switch es un interruptor que parece un pequeño interruptor de luz. Gíralo a la izquierda, gíralo a la derecha. Encendido. Apagado.
En la configuración, los switches controlan opciones binarias:
- Sonido activado/desactivado
- Narración TTS habilitada/deshabilitada
- Modo oscuro / modo claro
La metáfora física es tan buena que hasta tus abuelos la entienden.
Un Slider es una pista con un control que arrastras de un lado a otro para seleccionar un valor. Como una perilla de volumen que fue aplanada.
En Parlant~ usa sliders para:
- Tamaño de fuente — arrastra para ajustar
- Volumen — arrastra para ajustar (por supuesto)
- Núcleos de CPU — ¿cuántos núcleos debería usar el motor?
- Memoria hash — ¿cuánta RAM para la tabla hash del motor?
También existe un RangeSlider con dos controles para seleccionar un rango — usado para filtrar partidas por clasificación Elo (p. ej., 2000–2200) y períodos de tiempo.
SegmentedControl
Sección titulada «SegmentedControl»Una fila de botones donde exactamente uno está seleccionado a la vez. Es como los preajustes de una radio de coche — presionas uno y los demás se sueltan.
Se usa para alternar entre:
- Evaluación en centipeones vs. porcentajes de Victoria/Tablas/Derrota en el gráfico de análisis
- Diferentes formatos de notación de movimientos
- Cantidad de líneas del motor
Checkbox y Select
Sección titulada «Checkbox y Select»Los conoces. Checkboxes para “selecciona todos los que apliquen,” menús desplegables Select para “elige uno de esta lista.” Aparecen en configuraciones, filtros y formularios a lo largo de la aplicación. El modal de Borrar Datos tiene un conjunto particularmente satisfactorio de checkboxes donde puedes elegir tu propia destrucción.
Autocomplete
Sección titulada «Autocomplete»Un campo de texto que sugiere completados mientras escribes. La búsqueda de jugadores en el explorador de bases de datos usa esto — empieza a escribir un nombre y los jugadores coincidentes aparecen debajo.
FileInput y DateInput
Sección titulada «FileInput y DateInput»FileInput abre un selector de archivos al hacer clic — usado en el modal de importación para cargar archivos PGN. DateInput abre un calendario para seleccionar una fecha — usado para filtrar partidas por fecha. También existen MonthPickerInput y YearPickerInput para cuando necesitas menos precisión (filtrado de base de datos de Lichess por mes, filtrado de base de datos de Masters por año).
Los que muestran progreso
Sección titulada «Los que muestran progreso»Barra de progreso
Sección titulada «Barra de progreso»Una barra horizontal que se llena de izquierda a derecha para mostrar cuánto ha avanzado algo. Se usa durante las actualizaciones de la aplicación (progreso de descarga) y — de forma más creativa — para mostrar las probabilidades de Victoria/Tablas/Derrota en el panel de análisis. Tres secciones de colores (blanco, gris, negro) llenan la barra proporcionalmente. Es un pequeño gráfico de barras disfrazado de indicador de progreso.
Un Loader es una animación giratoria que dice “estoy trabajando en ello, dame un segundo.” Aparece mientras se cargan las bases de datos, se obtienen estadísticas de jugadores o cualquier cosa asíncrona está ocurriendo.
Skeleton
Sección titulada «Skeleton»Un Skeleton es un marcador gris que imita la forma del contenido que aún no se ha cargado. En lugar de una pantalla en blanco o un spinner, ves siluetas fantasma de dónde estarán las tarjetas y el texto. Es el plano arquitectónico de un estado de carga — “los muebles de verdad vienen en camino.”
La página de bases de datos usa skeletons mientras se carga la cuadrícula de tarjetas. Mucho más elegante que un spinner solo.
LoadingOverlay
Sección titulada «LoadingOverlay»Una manta semitransparente que se coloca sobre un componente mientras se carga. El gráfico de análisis usa esto — todavía puedes ver el gráfico detrás de la capa, pero está atenuado, y hay un spinner encima. “Sigo aquí, solo me estoy actualizando.”
Los que etiquetan cosas
Sección titulada «Los que etiquetan cosas»Un Badge (insignia) es una pequeña etiqueta de color — como una credencial en una conferencia. En En Parlant~, el componente SpeedBadge usa insignias para mostrar controles de tiempo con código de colores:
- 🩷 Rosa — UltraBullet
- 🔴 Rojo — Bullet
- 🟠 Naranja — Blitz
- 🟢 Verde — Rapid
- 🔵 Azul — Classical
- 🟣 Púrpura — Correspondence
Cada insignia es pequeña, colorida y comunica instantáneamente la velocidad de la partida de un vistazo.
Abreviatura de keyboard (teclado). Muestra una tecla del teclado con ese característico estilo de tecla en relieve. Se usa en la configuración de atajos de teclado para mostrar cosas como Ctrl + Z. Es una recreación CSS de una tecla física real de tu teclado. Deliciosamente esqueumórfico.
Los que separan y colapsan
Sección titulada «Los que separan y colapsan»Divider
Sección titulada «Divider»Una línea horizontal que separa secciones. Eso es todo. Es una línea. Pero es una línea con estilo, y opcionalmente puede tener una etiqueta de texto en el medio — como el divisor ”— O —” en el modal de importación que separa “pega un PGN” de “introduce un FEN.”
Más de treinta archivos usan Divider. Resulta que las cosas necesitan separarse bastante.
Collapse
Sección titulada «Collapse»Un Collapse es una sección que se expande y contrae con una animación suave. Haz clic para revelar, haz clic para ocultar. Las opciones de filtro de la base de datos usan esto — no siempre necesitas ver todos los filtros, así que se esconden detrás de un Collapse hasta que los quieras.
Los sofisticados
Sección titulada «Los sofisticados»RichTextEditor
Sección titulada «RichTextEditor»Un editor de texto completo con formato visual directo, construido sobre TipTap. Negrita, cursiva, listas, todo. Usado para escribir anotaciones de partidas — esas notas de comentario que agregas para explicar por qué un movimiento fue brillante o terrible.
Este es el único primitivo que es más un organismo compuesto que una célula individual. Internamente, es TipTap + ProseMirror + estilos de Mantine. Pero desde la perspectiva del usuario, es simplemente un cuadro de texto donde el formato funciona.
AreaChart
Sección titulada «AreaChart»Desde @mantine/charts (que envuelve Recharts), el AreaChart impulsa el gráfico de evaluación — esa forma de onda que corre a lo largo de la parte inferior del panel de análisis. El área blanca sobre la línea media significa que las blancas van ganando; la negra debajo significa que las negras van ganando.
Puedes hacer clic en cualquier punto del gráfico para saltar a ese movimiento. La visualización interactiva de datos se encuentra con el análisis de ajedrez. Incluso tiene tooltips personalizados y líneas de referencia que marcan las fases de la partida (apertura → medio juego → final).
DataTable
Sección titulada «DataTable»A través de la biblioteca mantine-datatable — una tabla de datos completa con ordenamiento, paginación, selección de filas y filtrado. Alimenta la lista de partidas, la lista de jugadores y la lista de torneos del explorador de bases de datos. Es una hoja de cálculo que sabe que está en una aplicación de ajedrez.
Los invisibles
Sección titulada «Los invisibles»Algunos primitivos no renderizan nada visible por sí mismos, pero hacen que todo lo demás funcione:
- MantineProvider — envuelve toda la aplicación y proporciona el tema (colores, modo oscuro, valores predeterminados de componentes)
- Portal — teletransporta contenido renderizado a una parte diferente del DOM
- useHotkeys — un hook (no un componente) que conecta los atajos de teclado
- useForm — gestiona el estado del formulario, la validación y el manejo de errores
- useDebouncedValue — espera a que dejes de escribir antes de lanzar una búsqueda. El hook educado.
El inventario completo
Sección titulada «El inventario completo»Como referencia, aquí están todas las familias de primitivos usados en En Parlant~, agrupados por su función:
| Categoría | Primitivos |
|---|---|
| Maquetación | AppShell, Box, Center, Flex, Group, Stack, SimpleGrid, ScrollArea, Portal |
| Superficies | Card, Paper |
| Capas superpuestas | Modal, Tooltip, Popover, Menu, ContextMenu, LoadingOverlay |
| Notificaciones | Toast (vía @mantine/notifications) |
| Botones | Button, ActionIcon, CloseButton, ThemeIcon |
| Entradas | TextInput, Textarea, NumberInput, Select, Autocomplete, Checkbox, Switch, Slider, RangeSlider, SegmentedControl, FileInput, DateInput, MonthPickerInput, YearPickerInput |
| Visualización de datos | Table, DataTable, Badge, Code, Kbd, Rating, Image |
| Tipografía | Text, Title, Anchor |
| Progreso | Progress, Loader, Skeleton |
| Estructura | Divider, Collapse |
| Contenido enriquecido | RichTextEditor (TipTap), AreaChart (Recharts) |
| Tematización | MantineProvider, createTheme, useColorScheme |
| Hooks | useForm, useHotkeys, useToggle, useDebouncedValue, useClickOutside, useElementSize |
Todos provienen de Mantine v8 y sus paquetes del ecosistema: @mantine/core, @mantine/notifications, @mantine/dates, @mantine/charts, @mantine/form, @mantine/tiptap, mantine-datatable y mantine-contextmenu.
Ahora ya lo sabes
Sección titulada «Ahora ya lo sabes»La próxima vez que veas un pequeño mensaje deslizarse desde la esquina de tu pantalla — eso es un toast. El rectángulo alrededor de una vista previa de partida — eso es una card. Las manchas grises que parpadean antes de que cargue el contenido — esos son skeletons.
Una vez que aprendes los nombres, empiezas a verlos en todas partes. En cada aplicación. En cada sitio web. Las mismas dos docenas de primitivos, reorganizados de mil formas diferentes.
Son piezas de Lego, hasta el fondo.