Habilidad Universal de Arquitectura UI/UX para PySide6
Diseña y construye interfaces de escritorio limpias, responsivas y centradas en el ser humano con PySide6 para cualquier dominio de aplicación. Inspecciona siempre primero el tema, widgets y convenciones existentes del proyecto objetivo—integra de forma natural con ellos en lugar de sobrescribir abstracciones existentes. Carga solo los archivos de referencia específicos que necesites para la tarea actual.
1. Enrutamiento de Divulgación Progresiva (Lectura bajo demanda)
- Temas, hojas de estilo QSS, modo Claro/Oscuro, HiDPI o primitivas de layout → Lee
./references/design-system-and-qss.md - Arquitectura de ventana principal, barras laterales, pestañas, docks, splitters o paneles → Lee
./references/navigation-and-shell.md - Tablas de datos, listas, árboles, barras de búsqueda, filtros o estados vacío/carga → Lee
./references/data-tables-and-filters.md - Diálogos modales (
QDialog), formularios, paneles de detalle, validación o notificaciones toast/progreso → Lee./references/forms-dialogs-and-feedback.md - Atajos de teclado, accesibilidad, layouts i18n/RTL o hilos en segundo plano → Lee
./references/accessibility-i18n-and-async.md - Inicializar una nueva aplicación PySide6 desde cero sin tema existente → Opcionalmente referencia
./assets/base-theme.qss
2. Leyes UX Universales (Aplicadas a la UI de escritorio)
- Ley de Jakob: Sigue las convenciones de escritorio establecidas (
Ctrl+Sguardar,Ctrl+Fbuscar,Esccancelar/limpiar,F5refrescar, ubicación estándar de menús/barras de herramientas) para que los usuarios se sientan inmediatamente fluidos. - Ley de Fitts: Mantén las acciones primarias lo suficientemente grandes (
>= 36pxde alto,>= 42pxpara táctil/flujos de alta frecuencia) y ancladas cerca de donde ya está la atención del usuario; evita forzar recorridos largos del ratón para acciones repetidas. - Ley de Hick y Divulgación Progresiva: Limita las opciones visibles en cada momento. Agrupa opciones secundarias en cajones, pestañas o menús desbordables en lugar de amontonar todos los controles en una sola pantalla.
- Ley de Miller y Proximidad Gestalt: Agrupa controles relacionados en grupos visuales limpios (
CardFrame) con espaciado consistente (8pxdentro de un grupo,16px–24pxentre grupos) para que los usuarios escaneen la estructura sin esfuerzo. - Umbral de Doherty (
< 400msde respuesta percibida): Nunca congeles el bucle de eventos de Qt. Ejecuta I/O, red y cómputo pesado fuera del hilo principal (QThreadPool/QRunnable) y muestra retroalimentación inmediata de carga o progreso. - Prevención de errores y recuperación segura: Valida en línea antes del envío, deshabilita acciones imposibles con tooltips claros que expliquen por qué, y requiere confirmación explícita solo para operaciones destructivas o irreversibles.
3. Tokens de Sistema de Diseño por Defecto (Adaptables)
Si el proyecto ya define una paleta, tipografía o sistema de espaciado, sigue los tokens del proyecto. De lo contrario, usa estos valores limpios y de alto contraste:
- Acento y Enfoque:
- Acento Primario:
#0F766E(Hover:#0D5F59, Presionado:#0A4A45, Tinte Suave:#CCFBF1/#F0FDFA) — o adáptalo al tono de la marca de la aplicación. - Anillo de Enfoque:
2px soliddel acento primario en todos los inputs y botones interactivos.
- Acento Primario:
- Jerarquía de Superficie Neutra (Claro / Oscuro):
- Lienzo de la App:
#F8FAFC(Claro) /#0F172A(Oscuro) - Superficie Elevada / Tarjeta:
#FFFFFF(Claro) /#1E293B(Oscuro) - Superficie Secundaria Sutil (Cabeceras, Pies, Zebra):
#F1F5F9(Claro) /#334155(Oscuro) - Borde Fino / Divisor:
#E2E8F0(Claro) /#334155(Oscuro) - Borde de Input por Defecto:
#CBD5E1(Claro) /#475569(Oscuro)
- Lienzo de la App:
- Jerarquía de Tipografía y Tinta:
- Texto Primario:
#0F172A(Claro) /#F8FAFC(Oscuro) - Texto Secundario / Etiqueta:
#475569(Claro) /#CBD5E1(Oscuro) - Texto Atenuado / Deshabilitado:
#94A3B8(Claro) /#64748B(Oscuro) - Pila de Fuentes:
"Segoe UI", "Inter", "Cairo", system-ui, sans-serif(compatible limpiamente con interfaces en latín, árabe y multilingües). - Escala Tipográfica: Título de Página
20pxNegrita, Título de Sección15pxSemiNegrita, Cuerpo/Celda13pxRegular, Etiqueta/Pie de Foto12pxMediana, Métrica Hero22px–26pxNegrita.
- Texto Primario:
- Tokens de Estado Semántico:
- Éxito: Texto
#15803D, Relleno#DCFCE7(Oscuro:#4ADE80/#14532D) - Advertencia: Texto
#B45309, Relleno#FEF3C7(Oscuro:#FBBF24/#451A03) - Peligro: Texto
#B91C1C, Relleno#FEE2E2(Oscuro:#F87171/#450A0A) - Información: Texto
#0369A1, Relleno#E0F2FE(Oscuro:#38BDF8/#0C4A6E)
- Éxito: Texto
- Espaciado y Geometría:
- Escala de Espaciado:
4px(ajustado),8px(elementos relacionados),12px(espacio barra de herramientas/formulario),16px(relleno de tarjeta),20px–24px(márgenes de página). - Alturas de Control: Inputs/Botones Estándar
36px, Controles de Alta Frecuencia/Táctiles42px+, Cabecera de Tabla38px, Fila de Tabla>= 42px. - Radios de Borde: Controles
6px, Tarjetas/Paneles10px, Modales12px, Píldoras de Estado11px.
- Escala de Espaciado:
4. Reglas de Ingeniería PySide6 No Negociables
- Adápta primero al código existente: Reutiliza constantes de tema, widgets base y ayudantes existentes antes de introducir nuevas abstracciones.
- Agrupación espacial limpia: Usa tarjetas
QFrame(borde fino de1px, contraste de superficie sutil) o panelesQSplitteren lugar de bordes pesados deQGroupBoxanidados. - Modelo/Vista para datos tabulares y de árbol: Usa
QTableView/QTreeViewconQAbstractItemModel(QAbstractTableModel),QSortFilterProxyModelyQStyledItemDelegate. Evita poblar celdas deQTableWidgetcon widgets pesados anidados. - QSS semántico en lugar de spaghetti en línea: Estiliza mediante roles de
setObjectName(...)(PrimaryButton,DangerButton,Card,PageTitle) y propiedades dinámicas ([invalid="true"]conunpolish()/polish()) en lugar de esparcir cadenassetStyleSheet(...)sin procesar. - Layouts responsivos (sin tamaños fijos de contenedor): Nunca llames a
setFixedSize()en ventanas, tarjetas o tablas. Confía en layouts, factores de estiramiento,QSizePolicyyQScrollAreapara que las UIs escalen limpiamente a través de resoluciones, pantallas HiDPI y longitudes de texto traducido. - Explica estados deshabilitados y valida en línea: Cada llamada
setEnabled(False)DEBE incluirsetToolTip(...)explicando por qué está deshabilitado. Valida inputs en línea con etiquetas de error auxiliares—nunca interrumpas la escritura conQMessageBox. - Una ubicación canónica por acción: Nunca dupliques la misma acción en una barra superior y un pie de página inferior. Coloca las CTAs primarias de la página en la parte superior derecha del
PageHeader, y las CTAs primarias del formulario/diálogo en la parte inferior derecha del pie del modal. - Teclado primero y retroalimentación no bloqueante: Establece el foco inicial en
showEvent(), conectasetTabOrder(), soportaEnter/Esc, y usa notificaciones toast superpuestas no bloqueantes o barras de estado para confirmaciones rutinarias—reserva los diálogos modales para confirmaciones destructivas. - Insignias de estado comedidas y ajustadas al contenido: Nunca estires las píldoras de estado de la tabla a un ancho fijo uniforme amplio ni inundes cada fila saludable con insignias saturadas pesadas. Ajusta dinámicamente el ancho de la píldora a
QFontMetrics.horizontalAdvance(text) + padding, mantén los estados saludables rutinarios visualmente discretos (por ejemplo, un punto de estado sutil de7px+ texto nítido) para que las advertencias/errores resalten de inmediato, y preserva la selección de fila y los divisores finos inferiores dentro de las sobrescrituras deQStyledItemDelegate.paint()personalizado.
5. Control de Calidad Prevuelo
Antes de finalizar cualquier implementación de UI en PySide6, verifica:
- ¿Cada vista tiene una jerarquía visual clara (
PageHeadero barra de espacio de trabajo estructurada) sin controles flotantes huérfanos? - ¿Todos los controles interactivos comparten alturas uniformes (
>= 36px), estados claros de hover/enfoque y suficiente contraste de color? - ¿Las columnas numéricas/tabulares están alineadas a la derecha y formateadas según la configuración regional de la aplicación?
- ¿Las insignias de estado de la tabla están dimensionadas según su texto, visualmente tranquilas en filas saludables y alineadas sin problemas con la selección de fila y los divisores?
- ¿Los estados vacío, sin coincidencias y de carga usan un estado dedicado de
QStackedWidgeten lugar de espacio en blanco vacío? - ¿Cada control deshabilitado se explica a sí mismo mediante
setToolTip()? - ¿Las tareas de larga duración están descargadas del hilo de la UI para que la ventana nunca se congele?