App Shell UI

Estás implementando App Shell UI: una habilidad de diseño frontend reutilizable con dos modos. Elige la superficie antes de elegir los píxeles. No conviertas cada solicitud en un shell de escritorio, y no conviertas cada aplicación en una página de marketing genérica.

Elige la superficie primero

Modo	Úsalo para	Estructura por defecto	No lo uses para
Modo App	Herramientas con sesión iniciada, configuraciones, consolas, chat, correo, bancos de trabajo, flujos operativos	Navegación izquierda persistente + lienzo de tareas	Marketing público, lectura, comercio o superficies de portafolio
Modo Sitio Web	Sitios de marketing, lanzamientos de productos, portafolios, páginas editoriales, catálogos, docs, contenido público	Una macroestructura específica de la página seleccionada del recorrido del usuario	Una plantilla genérica de héroe + tres tarjetas + CTA, o un shell de aplicación falso

Si la solicitud tiene ambas superficies, diséñalas por separado: Modo Sitio Web para adquisición o información pública, Modo App para el producto con sesión iniciada. Comparte tokens de marca cuando sea apropiado, pero no fuerces la misma maquetación o densidad en ambas.

Pre-vuelo (ambos modos)

Antes de tomar decisiones visuales en un proyecto existente, inspecciona la ruta y su fuente de verdad visual más cercana: tokens actuales, tipografía, mecanismo de tema, activos, framework, primitivas de componentes y bibliotecas de iconos/movimiento instaladas. Preserva un sistema establecido a menos que el usuario solicite un rediseño. Revisa package.json antes de añadir una dependencia; no des por sentado que una biblioteca existe ni mezcles dos sistemas de diseño no relacionados en una misma superficie.

Si el briefing es genuinamente ambiguo entre dos resultados materialmente diferentes, haz exactamente una pregunta corta. De lo contrario, indica la inferencia en una oración y continúa. No conviertas una solicitud de implementación pequeña en una entrevista de requisitos.

Flujo de trabajo del Modo App

Elige una plantilla de maquetación (requerida antes de los píxeles):
- 设置型 — navegación izquierda estrecha + formulario / lista de alternancia
- 控制台型 — navegación izquierda + cuadrícula de tarjetas / lista de estado
- 工作台型 — árbol de sesiones + estado vacío centrado + tarjeta de compositor
- IM / 三栏型 — barra de iconos + lista + detalle
Establece el presupuesto de viewport — define el viewport de escritorio objetivo (mínimo 1280×800) y la tarea principal única para la ruta antes de añadir contenido. Consulta references/layouts.md → Presupuesto de viewport / 单页容量.
Bloquea los tokens de tema dual — usa references/tokens.md (claro + oscuro son ambos requeridos por defecto).
Compón a partir de recetas — usa references/components.md (elemento de navegación, tarjeta, fila de lista, alternancia, píldora, vacío/compositor). Las recetas son agnósticas al tema; solo cambian las variables.
Implementa con variables CSS + data-theme="light"|"dark"; añade un alternador de tema; mapeo opcional a Tailwind/shadcn.
Autoevaluación — ejecuta la lista de verificación al final de este archivo en ambos temas y en el viewport objetivo antes de la entrega.

Stack por defecto cuando hay libertad de elección:

Capa	Por defecto
Marcado	HTML semántico o React
Estilo	Variables CSS + utilidad ligera/Tailwind
Componentes	shadcn / estilo @coss (New York + neutros tipo zinc)
Iconos	Trazo 1.5–2px estilo Lucide, una sola familia
Tema	Claro + Oscuro (alternador + opcional `prefers-color-scheme` del SO)

Prefiere un único HTML autocontenido para demos a menos que el usuario quiera integración en un proyecto.

Arquitectura del Modo App

L0  Marco de ventana (opcional semáforos / barra de título / herramientas superiores + alternador de tema)
L1  Barra lateral o barra de iconos
L2  Lienzo de contenido (gris suave claro / gris carbón suave oscuro)
L3  Superficies (tarjetas elevadas, paneles, listas)

Ancho de la barra lateral: 220–260px (navegación de texto) o 48–56px (barra de iconos). Relleno del contenido: 20–28px. Espaciado en cuadrícula de 4px.

Presupuesto de página por defecto: el estado inicial de escritorio debe completar su tarea principal en un viewport después de incluir el marco del shell. Mantén un pequeño espacio de respiro en la parte inferior; no hagas que toda la página se desplace verticalmente solo para revelar contenido secundario rutinario. Las colecciones largas pueden usar una región de desplazamiento interno acotada cuando el producto realmente lo necesite. Preferencia en chino: cada página intenta llenar una pantalla, el contenido alcanza la capacidad de la primera pantalla y se detiene.

Aspectos no negociables del Modo App

Dos temas: entrega conjuntos de tokens claro y oscuro a menos que el usuario quiera explícitamente solo uno.
Un color primario de marca para: botones primarios, alternancia ON, relleno de progreso, borde/fondo seleccionado, enlaces. El primario oscuro puede ser un gemelo ligeramente más brillante (p. ej. #007AFF → #0A84FF).
Escalera de superficies (ambos temas): fondo de app → fondo de barra lateral → superficie elevada (contraste débil). Claro: gris suave + tarjetas blancas. Oscuro: carbón suave + tarjetas grises elevadas — no página #000 pura + tarjetas #fff puras.
Escalera de texto: primario / secundario / terciario (los valores difieren por tema).
Jerarquía mediante bordes de 1px primero; sombra opcional y específica del tema.
Escalera de radio: 8 / 12 / 16 / 999 (compartida entre temas).
Patrón de copia: título + una línea de subtítulo atenuada.
Movimiento: 150–200ms solo para color/fondo; sin teatro de rebotes.
Cambio de tema: data-theme en la raíz + alternador visible; persistir con localStorage cuando sea posible.
Restricción de iconos (contenido): el contenido del lado derecho por defecto es texto + iconos de trazo + píldoras de estado. Emoji/ilustración son acentos opcionales solamente — nunca el valor predeterminado para cada fila de lista o tarjeta. Prefiere cero emoji en listas densas; como máximo un marcador decorativo en un banner o estado vacío.
Pares de igual altura: cualquier par de contenido lado a lado (lista + compositor, panel + panel, hermanos de estadísticas que forman un par de tarjetas en una fila) debe compartir el mismo borde inferior exterior. Usa grid/flex stretch + flex de columna + flex: 1 en las superficies — nunca align-items: start que deja una tarjeta corta. Consulta references/layouts.md → Columnas lado a lado de igual altura.
Presupuesto de contenido de un solo viewport: en escritorio, la ruta por defecto no debe requerir desplazamiento vertical a nivel de página. Llena el lienzo utilizable con contenido priorizado, pero detente antes de que se supere el primer viewport. Si el contenido no cabe, elimina, acorta, pagina, revela, tabula o divídelo en otra ruta; nunca recortes controles ni reduzcas el texto por debajo de la legibilidad. En móvil, mantén la acción principal y el estado en el primer viewport; el desplazamiento natural está reservado para contenido genuinamente largo.

Hacer / No hacer del Modo App

Hacer	No hacer
Navegación izquierda + contenido derecho	Arte de héroe a sangre completa como toda la app
Lienzo suave + tarjetas elevadas en ambos temas	Cibernético neón oscuro o negro OLED puro por defecto
Acento único (emparejado claro/oscuro)	Iconos de navegación arcoíris como múltiples primarios
Iconos de trazo (estilo Lucide) en navegación + contenido	Conjuntos de iconos de relleno + trazo mixtos
Tarjetas/listas primero texto; píldora para estado	Emoji en cada fila / tarjeta / encabezado de sección
Estado como pequeñas píldoras / texto atenuado	Banners de alerta completos y ruidosos para estados normales
Alternador de tema en el marco	Modo oscuro mediante `filter: invert()`
Separación de bordes mediante tokens	Colores de marco `#fff` / `#000` codificados
Espaciado aireado	Empaquetado denso tipo hoja de cálculo
≤1 acento emoji por región principal (o ninguno)	Banner + tarjetas + listas todos con muchos emoji
Tarjetas lado a lado de igual altura (stretch)	Un par alto / uno bajo (`align-items: start`)
Ruta de una pantalla con bloques priorizados	Desplazamiento de página sin límite para contenido rutinario
Desplazamiento interno acotado para colecciones largas	Ocultar o recortar contenido con alturas fijas

Orden de ensamblaje de página del Modo App

Shell (ventana + barra lateral + principal)
Bloque de marca en la barra lateral
Grupos de navegación + elemento activo
Encabezado de página (H1 + subtítulo atenuado + acciones)
Alternador de tema en la barra de título o configuración (requerido para demos)
Barra de herramientas opcional (búsqueda + filtro segmentado)
Bloques de contenido por prioridad: banner → estadísticas → cuadrícula/lista principal → columna secundaria de dos. Detente cuando el presupuesto de viewport esté lleno; mueve los bloques de menor prioridad a pestañas, revelación, paginación u otra ruta.
Para cada fila de pares de dos columnas: aplica la receta de igual altura (stretch + superficies flex) sin forzar el desbordamiento.
Conecta la interacción: cambio de navegación, selección, alternancias, filtros, alternador de tema

Notas de implementación del Modo App

Coloca los tokens claros en :root, :root[data-theme="light"] y los oscuros en :root[data-theme="dark"] (consulta references/tokens.md).
Los componentes solo consumen variables — sin valores hexadecimales de marca/superficie codificados en reglas de componentes.
Navegación seleccionada: lavado primario suave + texto primario, radio 8px (la mezcla de lavado difiere por tema).
Tarjetas: --bg-surface + 1px --border + radio 12; seleccionado: anillo/borde primario. Marca principal = icono de trazo en placa atenuada o sin marca — no emoji por defecto.
Filas de configuración / feed: icono de trazo de 16–18px (placa suave opcional) + título + descripción atenuada + control derecho. Evita iconos de lista emoji.
Estado vacío / nueva sesión: título centrado + compositor grande redondeado; chips + CTA primario. La marca de agua vacía puede ser un icono de trazo tenue o un solo glifo discreto — no una pila de emoji.
Banner: primero texto; opcional como máximo un pequeño azulejo de acento (a menudo ninguno).
Zona de añadir punteada para "colección vacía + crear" (signo más, no emoji).
Botones secundarios, pistas de segmento, pistas de alternancia OFF deben usar tokens de tema (--secondary-btn-bg, --seg-track, --toggle-off) — el rgba gris claro no funciona en oscuro.
Mantén el shell de la página fijo (min-height: 0; overflow: hidden) por defecto. Si una lista, registro, tabla o historial de mensajes es inherentemente largo, coloca el desplazamiento en una región secundaria acotada con un presupuesto de altura claro; no hagas que el cuerpo del documento o todo el lienzo de contenido sea el contenedor de desplazamiento predeterminado.
Valida el estado de carga inicial en un viewport de escritorio de al menos 1280×800 (y un viewport móvil estrecho). Verifica que la tarea principal, los controles y el estado sean visibles sin desplazamiento de página y que ningún texto o control esté recortado.

API de tema (canónica)

// data-theme = "light" | "dark"
// clave localStorage: "app-shell-theme"
// el alternador cambia el atributo; init lee storage luego prefers-color-scheme

Bloque de tokens CSS mínimo

Copia el bloque de tema dual de references/tokens.md.

Esqueleto HTML mínimo

<html data-theme="light">
…
<div class="window">
  <header class="titlebar">
    …
    <button type="button" data-theme-toggle aria-label="Cambiar tema claro/oscuro">…</button>
  </header>
  <div class="shell">
    <aside class="sidebar">…</aside>
    <main class="main">…</main>
  </div>
</div>

Semilla de prompt del Modo App

Claro

UI de escritorio macOS claro: barra lateral gris suave de 240px (iconos de trazo + etiqueta, seleccionado = lavado primario claro + radio 8px), lienzo principal gris suave con tarjetas blancas redondeadas; primario único #007AFF para botones, alternancias, progreso, anillo de selección; tres grises de texto; radio 8–16px; casi sin sombra, bordes claros de 1px; filas de configuración/lista con iconos de trazo pequeños (no emoji) + título/desc + alternancia derecha o píldora de estado; área de contenido primero texto, mínimo o sin emoji; estado vacío = título centrado + compositor grande redondeado.

Oscuro

Mismo shell en modo oscuro: lienzo carbón suave #1C1C1E, barra lateral #161617, tarjetas elevadas #2C2C2E, bordes blanco 8% alfa, texto #F5F5F7 / #A1A1A6 / #6C6C70, primario #0A84FF, navegación seleccionada = primario 22% mezclado en la superficie de la tarjeta; sin página negra pura; sin filtro invert; incluye alternador de tema.

Solo intercambia los sustantivos de negocio; mantén las reglas del shell + tema dual.

Flujo de trabajo del Modo Sitio Web

El Modo Sitio Web es para trabajo frontend orientado al público. Puede usar desplazamiento de documento normal y no debe heredar el lienzo fijo, la barra lateral, el marco de ventana artificial o el límite de contenido de un viewport del Modo App. Lee references/web-frontend.md antes de implementar el Modo Sitio Web.

Haz una lectura de diseño — indica el tipo de página, la audiencia, el trabajo principal y un tono concreto. "Limpio y moderno" no es una dirección. Infiere a partir del briefing y la marca existente; haz una pregunta corta solo cuando dos direcciones producirían un trabajo materialmente diferente.
Elige el modo de superficie — Persuadir para una página de conversión o lanzamiento, Leer para docs o contenido editorial, Experiencia para portafolio/galería/evento, o Catálogo para navegar y comprar. El producto con sesión iniciada permanece en Modo App.
Elige una macroestructura antes que los componentes — elige una forma de página que se ajuste al trabajo, como revelación de producto, historia liderada por evidencia, narrativa editorial, índice de trabajo, catálogo, guía de lectura o póster de campaña. No uses por defecto héroe centrado -> tres tarjetas iguales -> CTA.
Comprométete con un sistema visual — bloquea una paleta, roles tipográficos, reglas de espaciado/radio, tratamiento de imagen y un diferenciador visible. Reutiliza tokens de marca existentes; de lo contrario define variables CSS semánticas y consúmelas en lugar de improvisar colores o fuentes por sección.
Planifica la verdad y los medios — usa hechos proporcionados, capturas de pantalla reales/estados del producto, activos con licencia o mapas de bits generados apropiados para el briefing. No inventes clientes, métricas, testimonios, logotipos, paneles falsos, marcos de navegador o datos de marcador de posición que se lean como reales. Las afirmaciones desconocidas permanecen visiblemente marcadas como marcadores de posición o se omiten.
Construye el viaje de información — usa puntos de referencia semánticos y una jerarquía que haga obvia la siguiente acción. Deja que las secciones varíen en composición cuando sus trabajos difieran; las tarjetas son para elementos repetidos y acotados, no un contenedor de sección de página predeterminado.
Implementa el comportamiento completo — usa controles y enlaces nativos, focus visible, estados de carga, vacío, error, deshabilitado y éxito cuando sea relevante. El movimiento debe explicar la retroalimentación o el cambio espacial, usar transform/opacity, respetar prefers-reduced-motion y mantenerse fuera de flujos de alta frecuencia a menos que sea efectivamente instantáneo.
Inspecciona la salida renderizada — valida capturas de pantalla de escritorio y móvil, extremos de contenido real, contraste, navegación por teclado, dimensiones de imagen de carga, desbordamiento y el primer viewport. La propuesta del héroe, la acción principal y el punto focal visual deben caber en 1280x800; el desplazamiento de la página por debajo es normal para un sitio web.

Aspectos no negociables del Modo Sitio Web

No envuelvas un sitio web público en el marco del Modo App a menos que el usuario pida explícitamente una vista previa del producto o una ruta de aplicación con sesión iniciada.
Dale a cada página pública un propósito claro, una jerarquía de contenido y un flujo de interacción adaptado a su trabajo — sin envolver información pública en un shell de aplicación genérico.
El scroll de página es normal y esperado en sitios web. No apliques el presupuesto de contenido de un viewport o el lienzo fijo del Modo App a una página pública; usa el scroll natural del documento y secciones con altura variable.
Prefiere HTML semántico accesible y CSS moderno para sitios web públicos. Usa JavaScript con moderación y solo cuando mejore la experiencia principal.
Todas las interacciones, animaciones y transiciones deben funcionar sin JavaScript y mejorar progresivamente. El contenido debe ser legible y navegable con CSS desactivado.
El texto debe tener un contraste de al menos 4.5:1 con su fondo (AA normal) y los componentes de la interfaz deben mantener un contraste de 3:1 con los fondos adyacentes (AA para componentes de interfaz no textuales).

Pautas de implementación del Modo Sitio Web

Usa diseño responsivo con consultas de medios y unidades relativas (rem, %, vw, etc.).
Implementa navegación por teclado completa y estados focales visibles.
Optimiza para rendimiento de carga: imágenes responsivas, carga diferida, minimizar solicitudes HTTP.
Usa puntos de referencia HTML5 (<header>, <main>, <nav>, <section>, <article>, <footer>) para mejorar la accesibilidad y el SEO.
Para páginas de marketing, prioriza una jerarquía clara: propuesta de valor → beneficios → prueba social → CTA.
Para portafolios, deja que el trabajo hable: imágenes grandes, texto mínimo, navegación simple.
Para documentación, prioriza la legibilidad: estructura de tabla de contenidos, navegación consistente, tipografía clara.
Para catálogos, enfatiza la navegabilidad: filtros, búsqueda, presentación clara de productos.

Lista de verificación de implementación (ambos modos)

Antes de entregar, confirma:

Referencias

Ver archivos en references/ para:

tokens.md — variables CSS de tema dual
components.md — recetas de componentes
layouts.md — plantillas de maquetación y directrices de viewport
web-frontend.md — pautas detalladas del Modo Sitio Web

yg2224/app-shell-ui

¿Qué es app-shell-ui?

Preguntar en tu IA favorita

Documentación