DESIGN.md

name	Regression Native Utility
description	Contrato visual del lanzador macOS de barra de menús para ejecutar Steam de Windows de forma autónoma con Regression.
colors	primary secondary success warning error surface on-surface #5E5CE6 #0A84FF #30D158 #FFD60A #FF453A #1C1C1E #F2F2F7
typography	title body callout caption fontFamily fontSize fontWeight lineHeight SF Pro 17px 600 22px fontFamily fontSize fontWeight lineHeight SF Pro 13px 400 18px fontFamily fontSize fontWeight lineHeight SF Pro 14px 500 19px fontFamily fontSize fontWeight lineHeight SF Pro 11px 400 14px
rounded	control card panel 8px 12px 14px
spacing	unit compact regular section 4px 8px 12px 16px
components	status-row status-success status-warning game-row progress menu-bar-icon backgroundColor textColor typography rounded padding {colors.surface} {colors.on-surface} {typography.body} {rounded.card} {spacing.regular} backgroundColor textColor {colors.success} {colors.surface} backgroundColor textColor {colors.warning} {colors.surface} backgroundColor textColor typography rounded padding {colors.surface} {colors.on-surface} {typography.body} {rounded.card} {spacing.regular} backgroundColor textColor typography rounded padding {colors.surface} {colors.on-surface} {typography.caption} {rounded.control} {spacing.compact} width height padding 18px 18px 1px

Overview

Regression es una utilidad nativa de macOS que vive en la barra de menús. Su panel debe sentirse como una extensión discreta del sistema, no como un gestor de botellas ni como una réplica visual de otro producto. La jerarquía prioriza el estado operativo, la custodia de la biblioteca propia y la acción principal para abrir Steam.

El panel usa controles SwiftUI y materiales de macOS. No se crean imitaciones personalizadas de Liquid Glass, barras de título ni ventanas flotantes superpuestas. La identidad propia se concentra en la R de la barra de menús, con una variante estática y nítida para cada estado real de la aplicación.

La expresión pública de la marca —GitHub, documentación y releases— reutiliza la R oficial, fondos grafito, índigo como color primario, azul para acciones y verde solo para compatibilidad certificada. La voz es directa, técnica y demostrable: explica primero el resultado, reduce jerga en la portada y enlaza la evidencia profunda en vez de acumularla en el mensaje principal.

Colors

Los valores anteriores documentan el tono semántico de referencia. En código se prefieren Color.accentColor, Color.primary, Color.secondary y los colores de estado del sistema para conservar contraste, vibrancy, accesibilidad y adaptación automática a los modos claro, oscuro y de alto contraste.

• Índigo del sistema para la identidad de Regression y la acción principal.
• Azul del sistema para enlaces y acciones secundarias.
• Verde, amarillo y rojo únicamente para éxito, advertencia y error.
• Nunca comunicar un estado solo mediante color: acompañarlo con icono y texto.

Typography

Se usa exclusivamente la tipografía del sistema. Los títulos emplean headline; el contenido, body o callout; los metadatos y App ID, caption con diseño monoespaciado cuando ayude a escanear datos técnicos. Se respetan Dynamic Type y los tamaños de accesibilidad disponibles en macOS.

Layout

El panel tiene un ancho ideal de 380 puntos y una altura flexible con desplazamiento cuando la lista de juegos lo requiera. Aplica una cuadrícula de 4 puntos, márgenes exteriores de 16 puntos y separación de 12 a 16 puntos entre secciones. Las colecciones potencialmente grandes se buscan y revelan en lotes incrementales; el popover nunca materializa miles de filas a la vez.

Orden de contenido:

1. Identidad, estado actual y progreso.
2. Acciones para abrir, mostrar, actualizar o cerrar Steam de forma segura.
3. Estado de la biblioteca propia y, solo durante la transición, progreso de custodia y rollback.
4. Resumen de juegos, verificaciones y motores observados.
5. Juegos detectados y lanzamiento por App ID.
6. Aprendizaje local y mantenimiento bajo divulgación progresiva.
7. Versión, privacidad local y salida.

Elevation & Depth

La profundidad procede del material nativo del NSPopover y de separadores del sistema. Las tarjetas internas usan fondos secundarios discretos; no se apilan materiales ni sombras fuertes. El foco visual se obtiene con espaciado y tipografía.

Shapes

Los controles conservan su forma nativa. Los contenedores auxiliares usan radios de 10 a 12 puntos. No se mezclan píldoras, rectángulos y círculos sin función semántica. Los iconos funcionales proceden de SF Symbols; la marca R de Regression usa sus cuatro assets estáticos propios.

Components

• Icono de barra de menús: lienzo exacto de 18 puntos con variante Retina de 36 píxeles. La huella alfa mide 32 píxeles Retina de alto, queda centrada horizontalmente y aplica una corrección óptica vertical de un píxel hacia arriba. Una NSImageView decorativa y transparente a eventos conserva ese tamaño exacto dentro del NSStatusBarButton nativo y corrige el centro vertical en −0,5 puntos. Usa cuatro imágenes estáticas: ready, working, running y error. Los PNG se tratan como plantillas para adaptarse a las apariencias clara y oscura.
• Estado: el icono cambia sin animación al cambiar el estado operativo. El panel mantiene además resumen legible, insignia semántica y detalle técnico; la imagen nunca es el único canal de información. Si un prerrequisito bloquea Steam, la primera pantalla muestra “Atención”, la causa y una única recuperación, aunque la operación general estuviese en reposo.
• Acción principal: un botón prominente cuyo texto cambia entre “Abrir Steam”, “Mostrar Steam” y “Reintentar”.
• Custodia de biblioteca: tarjeta prioritaria con fases reales, impacto explícito, una sola copia física y acciones transaccionales de validar o revertir.
• Juegos: campo nativo de búsqueda por nombre o App ID y filas compactas reveladas en lotes de 24, con nombre, App ID y botón de reproducción; no muestran datos privados de la cuenta. La certificación verde procede exclusivamente de una ejecución local perfecta de Regression y siempre se etiqueta como tal.
• Historial: resumen exclusivamente local de ejecuciones, perfiles y motores de Regression, con blindados revelados en lotes de 8 y exportación bajo demanda. No consulta, sincroniza ni compara valoraciones públicas. La sección distingue candidatos tecnológicos de casos y pruebas reales de I+D; los contadores nunca presentan uno como si fuese el otro.
• Errores: mensaje comprensible, causa técnica desplegable y una acción concreta como “Reparar componente”, “Abrir diagnóstico” o “Usar motor de Regression”.
• Salud del runtime: VC++/UCRT, multimedia y Apple GPTK reutilizan una presentación común de estado, explicación y recuperación. Un componente sellado ausente o alterado nunca convive con una cabecera “Listo”.
• Apple GPTK: onboarding asistido, no descarga oculta. Abre solo Apple Developer, permite elegir el DMG, lo inspecciona antes de mutar, muestra la licencia RTF exacta en una hoja nativa y exige confirmación explícita. Tras autorizar, conserva recibo privado y caché verificada para reparación automática. La UI nombra la generación exigida por cada perfil y nunca ofrece una versión moderna como sustituto de un componente histórico incompatible.
• Accesibilidad: títulos navegables como cabeceras, controles críticos de al menos 32 puntos y tipografía/controlSize adaptativos. El footer cambia de fila a columna cuando no cabe en tamaños accesibles.

Do's and Don'ts

Do

• Mostrar progreso durante detección, preparación, cambio de motor y lanzamiento.
• Cambiar automáticamente la variante estática de la R al cambiar el estado operativo.
• Mantener una sola instancia de Steam activa.
• Explicar cualquier cambio de botella, biblioteca o licencia antes de ejecutarlo.
• Usar etiquetas, ayuda contextual y accesibilidad para todos los controles.
• Presentar Regression como único motor operativo y explicar que la biblioteca física pertenece a su botella.
• Mantener verificaciones, historial y aprendizaje dentro de los datos locales de Regression.
• Mantener buscables las bibliotecas grandes sin sacrificar la respuesta inmediata del popover.

Don't

• No mostrar la aplicación en el Dock durante el uso normal.
• No reproducir, interpolar ni fundir fotogramas en la barra de menús.
• No animar información decorativa dentro del panel.
• No mostrar CrossOver como selector, requisito, propietario de juegos ni acción operativa.
• No crear ni instalar otra botella o copia de Steam automáticamente.
• No almacenar credenciales, identificadores de cuenta ni registros sin filtrar.
• No recrear enlaces de juegos hacia CrossOver ni mantener dos copias de steamapps.
• No presentar referencias, valoraciones ni comparaciones externas como parte del estado operativo o la certificación de Regression.