Communitygithub.com

pyside6-ui

Habilidad universal de arquitectura y sistema de diseño UI/UX para PySide6 / Qt for Python, para cualquier aplicación de escritorio. Úsala siempre que diseñes, construyas, refactors, estilices o revises ventanas, shells de navegación, temas QSS, paneles, tablas de datos, barras de búsqueda/filtro, formularios CRUD, diálogos modales, capacidad de respuesta asíncrona, RTL/i18n o flujos de teclado.

¿Qué es pyside6-ui?

Esta habilidad proporciona un framework coherente y de alta calidad para construir interfaces de escritorio modernas con PySide6 (Qt for Python). Está diseñada para cualquier dominio de aplicación y se integra de forma natural con temas y widgets existentes en lugar de sobrescribirlos. Define reglas de ingeniería no negociables, como el uso de Model/View para datos tabulares, diseño responsivo sin tamaños fijos, validación en línea y estados deshabilitados con tooltips explicativos. Incluye un sistema de tokens de diseño por defecto (colores, tipografía, espaciado) que es adaptable a la marca de la aplicación, y aplica leyes UX universales (Jakob, Fitts, Hick, Miller, Doherty) para garantizar usabilidad, accesibilidad y rendimiento. La habilidad se organiza en secciones de referencia que se leen bajo demanda: sistema de diseño/QSS, navegación/shell, tablas/filtros, formularios/diálogos, y accesibilidad/i18n/asincronía, permitiendo una carga de información específica para cada tarea.

Compatible con~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/MohammedBoure/skills/tree/main/pyside6-ui

Preguntar en tu IA favorita

Abre un nuevo chat con esta habilidad de agente ya precargada.

Documentación

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)

  1. Ley de Jakob: Sigue las convenciones de escritorio establecidas (Ctrl+S guardar, Ctrl+F buscar, Esc cancelar/limpiar, F5 refrescar, ubicación estándar de menús/barras de herramientas) para que los usuarios se sientan inmediatamente fluidos.
  2. Ley de Fitts: Mantén las acciones primarias lo suficientemente grandes (>= 36px de alto, >= 42px para 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.
  3. 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.
  4. Ley de Miller y Proximidad Gestalt: Agrupa controles relacionados en grupos visuales limpios (CardFrame) con espaciado consistente (8px dentro de un grupo, 16px–24px entre grupos) para que los usuarios escaneen la estructura sin esfuerzo.
  5. Umbral de Doherty (< 400ms de 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.
  6. 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 solid del acento primario en todos los inputs y botones interactivos.
  • 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)
  • 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 20px Negrita, Título de Sección 15px SemiNegrita, Cuerpo/Celda 13px Regular, Etiqueta/Pie de Foto 12px Mediana, Métrica Hero 22px–26px Negrita.
  • 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)
  • 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áctiles 42px+, Cabecera de Tabla 38px, Fila de Tabla >= 42px.
    • Radios de Borde: Controles 6px, Tarjetas/Paneles 10px, Modales 12px, Píldoras de Estado 11px.

4. Reglas de Ingeniería PySide6 No Negociables

  1. Adápta primero al código existente: Reutiliza constantes de tema, widgets base y ayudantes existentes antes de introducir nuevas abstracciones.
  2. Agrupación espacial limpia: Usa tarjetas QFrame (borde fino de 1px, contraste de superficie sutil) o paneles QSplitter en lugar de bordes pesados de QGroupBox anidados.
  3. Modelo/Vista para datos tabulares y de árbol: Usa QTableView / QTreeView con QAbstractItemModel (QAbstractTableModel), QSortFilterProxyModel y QStyledItemDelegate. Evita poblar celdas de QTableWidget con widgets pesados anidados.
  4. 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"] con unpolish()/polish()) en lugar de esparcir cadenas setStyleSheet(...) sin procesar.
  5. Layouts responsivos (sin tamaños fijos de contenedor): Nunca llames a setFixedSize() en ventanas, tarjetas o tablas. Confía en layouts, factores de estiramiento, QSizePolicy y QScrollArea para que las UIs escalen limpiamente a través de resoluciones, pantallas HiDPI y longitudes de texto traducido.
  6. Explica estados deshabilitados y valida en línea: Cada llamada setEnabled(False) DEBE incluir setToolTip(...) explicando por qué está deshabilitado. Valida inputs en línea con etiquetas de error auxiliares—nunca interrumpas la escritura con QMessageBox.
  7. 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.
  8. Teclado primero y retroalimentación no bloqueante: Establece el foco inicial en showEvent(), conecta setTabOrder(), soporta Enter/Esc, y usa notificaciones toast superpuestas no bloqueantes o barras de estado para confirmaciones rutinarias—reserva los diálogos modales para confirmaciones destructivas.
  9. 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 de 7px + 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 de QStyledItemDelegate.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 (PageHeader o 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 QStackedWidget en 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?

Skills relacionados