Pautas

Patrones de pantalla

Cómo construir las pantallas habituales de una app (ajustes, perfil, listas) con componentes de Alea, y las reglas de densidad, bordes, sombras, tipografía, estados vacíos, tarjetas y formularios que las mantienen coherentes.

Ejemplos

Página de ajustes

PageHeader, TabNav para las páginas de la sección y luego grupos SettingsSection de SettingRow. Un tamaño de título por rol, filas en lugar de tarjetas apiladas.

Página de perfil

SplitLayout con la persona en el lado estrecho y los detalles en el ancho. Datos de solo lectura en una PropertyList, ediciones en un Form con un espacio fijo.

Página de lista

PageHeader con la única acción principal, una Card con padding none alrededor de la lista y un EmptyState del tamaño de una tarjeta cuando no hay nada.

Páginas de ajustes

Empieza con PageHeader. Cuando los ajustes tienen más de una página de opciones, dale a cada tema su propia dirección y pon un TabNav en la cabecera (tabs). Dentro de una página, usa una SettingsSection por tema y una SettingRow por opción. El control va a la derecha; un Switch, un Select y un Button son los habituales.

Una página de ajustes corta no necesita pestañas: PageHeader y luego dos o tres secciones. Los ajustes que necesitan un botón Guardar son un Form, colocado bajo la sección a la que pertenece, con FormActions.

Páginas de perfil

Usa SplitLayout. La columna estrecha lleva a la persona (Avatar, nombre, rol) y la ancha los detalles. Los datos de solo lectura van en Descriptions; las ediciones, en un Form dentro de una Card. SplitLayout se apila según su propio ancho, así que la página aguanta una ventana estrecha.

Páginas de lista

PageHeader con una acción principal y luego una Card con padding="none" alrededor de la lista (ListView, Table o un árbol), para que las filas lleguen de borde a borde. Los filtros van en una Toolbar sobre la tarjeta. Cuando la lista está vacía, el EmptyState reemplaza la lista dentro de la misma tarjeta.

Densidad y espacio

Todo el espacio está en la escala de 4 px (Espacio y tamaños). Elige el espacio según la relación entre elementos, no por gusto.

Entre	Uso	Cómo
Secciones de una página	gap 5 (20 px)	Stack gap={5}
Tarjetas o filas de tarjetas	gap 4 (16 px)	Grid o Stack gap={4}
Campos de un formulario	16 px	Form gap={16}
Un título y su ayuda	2 px	Ya incluido en CardHeader y SettingsSection
Borde de la página	Lo define el shell	Nunca añadas padding alrededor de una página dentro de AppShell

Bordes y sombras

Una superficie que descansa sobre la página lleva borde o la sombra de tarjeta, nunca los dos. Los paneles que enmarcan una página (el panel del shell, una SettingsSection) usan un borde de 1 px. Las tarjetas usan el anillo suave. Solo las cosas flotantes (menús, popovers, diálogos) usan la sombra pop. No anides un panel con borde dentro de otro: usa appearance="plain" o una Card deep para el interior.

Jerarquía tipográfica

Un solo h1 por página, desde PageHeader. Las tarjetas y las secciones empiezan en el nivel 2 (headingLevel={2}).
Los títulos de tarjetas y secciones son los compactos en seminegrita: CardHeader y SettingsSection. Usa el título display grande solo para una tarjeta principal o un hero.
El texto de ayuda es Text size="sm" tone="muted". No inventes un cuarto tamaño de texto en una página.
Modales: titleSize="sm" para formularios y ajustes, el valor por defecto para diálogos que presentan algo.

Estados vacíos

Dentro de una tarjeta usa EmptyState size="sm"; para una página entera usa el tamaño por defecto. Di qué falta y da la única acción que lo arregla. No culpes a la persona.

Tarjetas

Un tema por tarjeta. No anides tarjetas.
Las tarjetas de una lista comparten ancho: usa Grid con columns="auto" y un minItemWidth.
Una tarjeta que contiene una lista o una tabla usa padding="none".
No sobrescribas el CSS de una tarjeta: elige las props surface, radius y padding.

Formularios

Etiquetas sobre los campos, una columna, Form gap={16} y un maxWidth de unos 520 px para que las líneas sean cortas.
Valida al enviar, muestra los errores del servidor en los campos y nunca deshabilites el botón de enviar para decir que el formulario está incompleto.
Agrupa los campos relacionados en un Fieldset. Pon el botón de enviar al inicio de la fila, después del último campo.