# Guía para agentes > Las reglas de sistema y la anatomía de una app: lo que hay que leer antes de armar una pantalla con sebs7n-ui. Esta guía es para quien arma una app con sebs7n-ui, persona o agente. Son las reglas **del sistema**: valen para cualquier pantalla. Las de cada componente (props, teclado, cuándo sí y cuándo no) están en su página, y hay dos ejemplos completos para copiar: el [template de dashboard](/templates/dashboard) para una app y el [template de landing](/templates/landing) para una landing. Si sos un agente: leé esta guía antes de escribir la primera pantalla y elegí el template: **una landing o una página de marketing se arma como el de landing; una app de trabajo (sidebar, tablas, formularios), como el de dashboard**. Copiá la estructura y cambiá solo los datos y los textos. Ante una duda entre dos componentes, la sección [Elegir componente](#elegir-componente) decide. ## La referencia **iCloud web (icloud.com), no el macOS nativo.** Los valores están medidos en claro y en oscuro. Lo que iCloud no tiene (Switch, Tooltip, toasts, Tree, Stepper) se deriva de sus tokens. No se inventan estilos: si algo no existe en el paquete, se arma con sus tokens y sus componentes. El [Playground](/docs/playground) es la referencia viva de los defaults: si cambia un default, se actualiza ahí. Muestra cuatro pantallas dentro de un `AppShell` (con el panel del asistente, ⌘K y los atajos), y cada una trae su «Cómo se arma» con los componentes que usa, el código para copiar y las reglas que ilustra. ## Reglas de sistema ### Un solo acento sólido por pantalla `Button` por defecto es el primario, en el acento, y va **uno** por pantalla: la acción principal («Nueva factura»). El resto, `secondary` (gris) o `plain` (texto en el acento). Los estados prendidos de Checkbox y Switch llevan el acento y no cuentan; el de `Toggle` y `ToggleGroup` es neutro (gris, semibold). `destructive` solo si borra, y siempre detrás de un `AlertDialog`. ### Tamaños Una sola escala para campos y botones: `sm` 28 · `md` 36 · `lg` 40 (botones de ícono 28 · 36 · 40), texto de 14. - **`md` es el de una app**: contenido, formularios, diálogos. Es el default: no hace falta escribirlo. - **`sm` en barras**: toolbars, la barra de una tabla, paginación, filtros sobre una lista. - **Una barra de filtros, entera en `sm`**: la búsqueda (`SearchField`), los selectores (`Select`, `MultiSelect`, `DatePicker`), el `ToggleGroup` y los botones de la barra (`Pausar`, `Exportar`, `Columnas`). Mezclar `sm` y `md` en la misma fila deja los controles a distinta altura. Vale igual en un dashboard, en una consola y en la portada de un blog: que la lista sea «contenido» no la hace una excepción. - Lo que **no** es parte de la barra queda en `md`: la acción primaria de la página («Nueva factura», «Nuevo servicio»), los botones de un formulario y de un diálogo. - **`lg`** solo en pantallas de entrada (login) o una acción aislada muy importante. - El tamaño se elige **una vez por formulario**, no por campo. No hay una variable global de densidad: rompe el objetivo táctil. - Usá los defaults del paquete. Si un tamaño no queda bien, el problema es de la composición, no se corrige forzando `size` en cada componente. ### Radios Sin cápsulas. `rounded-control` 8 (botones, controles, ítem de menú), `rounded-field` / `rounded-item` 10 (campos, filas), `rounded-surface` / `rounded-panel` 11 (cards, diálogos), `rounded-menu` 12 (menús, popovers), `rounded-tag` 4. **Curvas concéntricas:** radio interior = exterior − distancia (menú 12 con padding 5 → ítems 8). ### Superficies Opacas y en capas. Si **es** la página, `bg-background`; si flota sobre ella, `bg-surface` + `shadow-menu` / `shadow-modal`. Sidebar `bg-surface-secondary` con borde `separator-strong`; barra global `bg-surface-header`; toolbar `bg-surface-bar`; card = cuerpo `bg-surface` + `shadow-widget` y cabecera `bg-surface-bar`; zona hundida `bg-fill-1` / `bg-grouped`; tooltip `bg-tooltip`. Hover y selección neutra con `fill-1/2/3`. En oscuro la página es `#1C1C1E`, no negro. Casi siempre esto ya lo pone el componente: no le agregues fondos ni bordes a `Card`, `Sidebar` o `AppShell`. **Translucidez solo sobre el wallpaper** (`AppShell ambient`): barras y `Toolbar` en `material-translucent`; cuerpo de `Card`, `WidgetCard` y `Sidebar` en `material-translucent-body`. Menús, diálogos y campos siguen opacos. Dentro de una app de trabajo, todo opaco. ### Selección El resaltado de menús, el ítem activo del sidebar y el elegido de un `Toggle`/`ToggleGroup` van en **gris** (`fill-2`, `fill-1`, `fill-3` o la pastilla del segmentado). El acento sólido es solo para la fila elegida de una lista o tabla **con foco**; sin foco, la fila elegida vuelve a gris. ### Tipografía Por roles, como iCloud: `text-large-title` 48 (el título de la página), `title-1/2/3` 28/21/19, `headline` y `body` 17, `subheadline` 15, `callout` 14 (el cromo: barras, menús, tablas), `footnote` 12, `caption` 11. Un `

` por página, que pone `PageHeaderTitle`. ### Color del texto Texto con `label` / `label-secondary` (≥ 4,5:1). `label-tertiary` no es para texto chico: solo glifos, deshabilitados y texto grande. `gray-800` no va como texto. Un solo vocabulario: los tokens del paquete, no los alias de shadcn (`--color-card`, `--color-muted`…). ### Links Un link con forma de botón o de card: `buttonVariants()` / `cardVariants()` sobre `` o ``. **Nunca** `render` de un `Button` para un link (Base UI le pone `role="button"`). Un link de texto: `linkVariants` (`inline`, `subtle`, `row`, `accent`). Una acción que abre un panel no es un link: es un ` {/* el único acento */} ``` **El modelo.** Cada widget es `{ id, title, size?, description?, preview?, icon?, render }`. `id` estable y en inglés (es lo que se guarda); `render` devuelve la card y se llama en cada render, así lee de la pantalla (el store, los filtros) sin pasar por el modelo; `description` y `preview` (un `Sparkline`, una cifra) son lo que se ve en el catálogo. `size` son las columnas de una grilla de 4: `sm` 1, `md` 2, `lg` 4; por container query la grilla pasa a 2 columnas desde 36 rem de ancho del contenedor y a 1 por debajo de eso (con el panel del asistente abierto, el contenido se angosta y la grilla se reacomoda sola; no hay `sm:`/`lg:` de ventana). Las cards de una fila quedan alineadas: la card llena el alto de su celda. Una métrica con `StatGrid` va con `columns={1}`. **La edición.** - **Editar / Listo:** el botón de la cabecera, secundario (el acento es de la acción primaria). Anuncia «Modo edición…» en una región `status`. - **Mover:** los widgets tiemblan (no con `prefers-reduced-motion`: ahí un contorno punteado). Se reordenan arrastrando la card entera o con el teclado: Espacio toma, flechas mueven, Espacio suelta, Escape cancela, todo anunciado en español. - **Sacar:** un «−» en cada widget, con el nombre en su `aria-label` («Sacar Clientes»). El foco pasa al «−» que queda y no se pierde. - **Agregar:** «Agregar widget» abre un `Popover` (en el teléfono, la hoja de abajo) con los widgets que no están en pantalla, cada uno con su descripción y vista previa. Elegir uno lo suma al final y el foco va a su «−». - **Restablecer:** vuelve al orden original (deshabilitado, pero enfocable, si ya lo es). - **Vacío:** sin widgets en pantalla hay un `EmptyState` con «Agregar widget» y «Restablecer». **Persistencia.** El orden y los widgets visibles se guardan en `localStorage` con `useStoredState`: el HTML del servidor muestra el orden original y se adopta lo guardado después de montar. Un ID guardado que ya no existe se descarta. Si el panel depende de un proyecto o una cuenta, la clave lleva su id (`console:${project.id}:overview-widgets`): al cambiarla se carga el panel del otro. **Carga diferida (presupuesto de JS).** Sin editar, `WidgetBoard` es una grilla estática: no trae `@dnd-kit`. El arrastre, la barra de edición y el catálogo viven en otro módulo que se pide con `React.lazy` la primera vez que se aprieta «Editar» (no `next/dynamic`: no entra al HTML del servidor); mientras llega se ve la misma grilla, sin saltos. Una vez cargado queda montado. Los peers `@dnd-kit/*` son opcionales: hacen falta solo si se usa este componente. El estado que el widget necesita conservar al editar (el período elegido en una métrica) vive en la pantalla, no en la card: al pasar a edición las cards se montan de nuevo. **Con el panel lateral.** Nada cambia: la grilla mide el contenedor. Un clic en «Agregar widget» o «Restablecer» no saca de la edición; un clic en un espacio vacío, Escape o «Listo» sí. ### Card de plan con uso El bloque de plan de Ajustes de iCloud: una `PromoCard` con el plan y, al lado, una `Card` con un `Meter` por cupo usado. Lo implementan Configuración › Facturación del dashboard (facturas, usuarios y espacio) y Estado y costos de la consola (cómputo, ancho de banda y almacenamiento). ```tsx
}>Cambiar de plan

Uso del plan
``` Una sola `PromoCard` por pantalla. Es un `Meter` (un valor que sube y baja dentro de un rango), no un `Progress`. «Cambiar de plan» es el link de la promo, no un botón con acento. Cada `Meter` lleva `label`; las cifras salen de los datos de la app, no de números sueltos. Las unidades van por `format` (`Intl.NumberFormat`). Si el bloque se repite en muchas pantallas de una app, extraelo a un componente propio con las cifras como props. ## Anatomía de una landing Así está armado el [template de landing](/templates/landing): es el default para landings y páginas de marketing. ``` div.bg-ambient[data-ambient] el wallpaper: barra y cards pasan solas a translúcidas ├── Navbar marca, links a anclas, una CTA en gris ├── main max-w-[1080px] gap-24 una columna centrada, mucho aire entre secciones │ ├── Hero el único

(text-large-title) y la acción primaria │ ├── Logos Marquee pauseControl="press" (tocar pausa y reanuda) │ ├── Beneficios #beneficios Card en grilla 1/2/3 │ ├── Precios #precios ToggleGroup mensual/anual, 3 planes; el recomendado con el acento │ ├── Testimonios Marquee variant="cards": cards con
, alineadas │ ├── Preguntas #preguntas Accordion │ └── Cierre #registro la acción del hero, otra vez └── Footer ``` - **Un acento por pantalla:** en una página que se recorre con scroll, la regla es por lo que se ve a la vez. La CTA del hero, el plan recomendado y el cierre van en el acento porque nunca comparten pantalla; la CTA de la barra y las secundarias, en gris. - Cada sección abre con un `

` en `text-title-1` y una bajada en `text-body text-label-secondary`, centrados. - Las secciones con ancla llevan `scroll-mt-20`: si no, el título queda debajo de la barra. - Server Components: cliente solo lo que cambia con un click (el toggle de precios). Una landing tiene que ser liviana. - Lo que se mueve solo (`Marquee`) tiene que poder pausarse: en una landing, `pauseControl="press"` (tocar la franja pausa y reanuda; el botón queda para teclado). Nunca sin pausa. - Todo el texto en un solo archivo de datos: adaptar la landing es cambiar ese archivo. - A 390 px: el grupo de CTA pasa a columna (`flex-col sm:flex-row`), las grillas a una columna. **El propio sitio de sebs7n-ui sigue esta receta.** La home (`/`) y `/templates` comparten con la landing de referencia: la barra (marca con la versión en `Badge`, `NavigationMenu` con paneles, búsqueda ⌘K, GitHub, `ThemeSwitcher` diferido y «Empezar» en gris; en el teléfono, un `Drawer`), el hero centrado con el único acento primario, `SectionHeader` en cada sección, el ancho de 1080 px, el `scroll-mt-20` de las anclas, el wallpaper y el pie con grupos de links. Lo propio del sitio es el contenido (versión, instalación, «Por qué existe», componentes destacados, cifras de `site.json`, sección para agentes). El patrón (menú, tema y hoja del teléfono con `next/dynamic` y `ssr: false`) está copiado en `docs/site/app/_components`, no extraído al paquete: depende de los datos de navegación de cada sitio. `test/home-structure.test.ts` fija lo que comparten. ## Los templates - [Template de dashboard](/templates/dashboard): una app de trabajo (Inicio, Facturas, Clientes, Configuración). Para agentes, con el código: `/templates/dashboard.md`. Para copiarlo: `npx shadcn@latest add https://ui.sebastianfermanelli.com/r/dashboard.json`. - [Template de landing](/templates/landing): el default para landings. Para agentes: `/templates/landing.md`. Para copiarlo: `npx shadcn@latest add https://ui.sebastianfermanelli.com/r/landing.json`. En los dos: cambiá los datos (`_data/`) y los textos, no la estructura.