kvyatkovskys/swiftui-component-preview

SwiftUI Component Preview

Crea un render de componente a partir de un fixture SwiftUI pequeño y determinista. Requiere macOS 14 o posterior y Xcode 15 o posterior (Swift 5.9+); Swift 6 no es necesario. La incorporación del proyecto, la galería HTML y el constructor en vivo también requieren Python 3.8 o posterior (solo biblioteca estándar). Elige PNG para inspección estática, la galería para comparaciones de imágenes o una ventana nativa para interacciones reales con el fixture. Estos asistentes no proporcionan Xcode Canvas ni recarga en caliente.

Elige la salida

Decide la salida antes de construir nada, en este orden:

1. Palabra explícita. Si la solicitud o los argumentos de la habilidad comienzan o nombran png, gallery o live (también "screenshot", "render" para PNG; "window", "interactive" para live), usa esa.

2. Intención de la solicitud.

   El usuario quiere	Salida
   ver cómo se ve, comprobar diseño, espaciado, texto, un estado, una configuración regional	PNG
   comparar claro y oscuro, o con marco y sin marco, lado a lado o alternando	Galería
   hacer clic, escribir, alternar, navegar, abrir una hoja o alerta, comprobar un flujo	Ventana en vivo

   Cuando una solicitud coincide con más de una fila, la interacción gana: cualquier cosa que solo aparezca después de un clic o entrada necesita la ventana en vivo.

3. Pantalla completa o flujo, sin señal. Si el objetivo es una pantalla completa o un flujo de varios pasos y ninguna regla anterior se aplica, como en "previsualizar la pantalla de pago", haz una pregunta ofreciendo PNG, galería y ventana en vivo.

4. Predeterminado. Para un solo componente sin señal, produce un PNG claro, con tamaño fit. Es la salida más rápida y la única que puedes inspeccionar tú mismo. Luego agrega una línea ofreciendo las otras dos salidas.

Las reglas 1, 2 y 4 proceden sin preguntar. Cuando se solicitan varias salidas, prodúcelas todas desde la misma configuración. No almacenes la elección en .swiftui-preview/config.json: pertenece a la solicitud, no al proyecto.

Primer uso en un proyecto

<skill-directory> en los comandos a continuación es el directorio que contiene este SKILL.md; resuélvelo desde la ubicación instalada. Claude Code lo indica como el directorio base de la habilidad cuando la habilidad se carga (${CLAUDE_SKILL_DIR}); en Codex y otros agentes usa la ruta desde la que se leyó este archivo. No se necesitan rutas o configuraciones específicas del desarrollador. Usa la raíz del proyecto actual del usuario y ejecuta descubrimiento de solo lectura:

python3 "<skill-directory>/scripts/bootstrap.py" discover --root "<project-root>"

El descubrimiento informa sobre manifiestos SwiftPM, proyectos/espacios de trabajo Xcode, fuentes SwiftUI, presencia de #Preview y evidencia textual de plataforma. Nunca evalúa manifiestos, ejecuta complementos, compila ni modifica el proyecto. Se omiten directorios de dependencias/compilación anidados y enlaces simbólicos. La falta de metadatos de plataforma significa desconocido, no no compatible. Usa la solicitud y las rutas descubiertas para elegir el proyecto y componente previstos. Pregunta solo por selección que siga siendo genuinamente ambigua; múltiples marcadores por sí solos no obligan a hacer una pregunta cuando la fuente solicitada es clara.

Lee el código fuente real elegido, su construcción #Preview existente y las definiciones locales necesarias antes de crear un fixture. El agente de la habilidad realiza esta adaptación como parte de la primera solicitud de vista previa; no te detengas en instrucciones que le digan al usuario que lo adapte manualmente cuando puedas hacerlo de manera segura. Mantén la jerarquía de vistas real del componente, sus controles, estilos y entradas. Extrae su vista de valor e incluye las definiciones locales requeridas, reemplazando las dependencias de servicios con valores sintéticos y acciones locales. No sustituyas una pantalla similar, una demostración genérica o el ejemplo incluido por el componente solicitado. Los ejemplos solo ilustran la API del fixture.

Guarda el fixture adaptado dentro del proyecto del usuario, por ejemplo .swiftui-preview/fixtures/StatusCard.swift. Nunca copies el código fuente del proyecto en la habilidad compartida instalada. No incluyas @main, delegado de aplicación, raíz de composición de producción, macro #Preview ni servicios de producción. configure, run y refresh escanean el fixture como texto y lo rechazan cuando aparece @main, #Preview o import UIKit en cualquier lugar, incluso en comentarios; mantén esas cadenas fuera de los comentarios también. El error nombra el token coincidente y su línea. Inspecciona todo el fixture antes de ejecutarlo: el Swift ejecutable se ejecuta con los permisos normales del llamante; este asistente no es una caja de arena. Los hashes de configuración no pueden establecer la fidelidad visual ni la ausencia de efectos secundarios.

Si las API explícitas de UIKit o solo de iOS hacen que el componente sea incompatible con macOS, usa un flujo de trabajo disponible de iOS Simulator/Xcode Canvas o informa la dependencia no compatible precisa. El host genérico de macOS no ejecuta UIKit. Si los módulos, activos o catálogos de cadenas no se pueden adaptar de manera segura al contrato de un solo archivo, usa un flujo de trabajo disponible específico del proyecto o indica la limitación concreta. No vincules silenciosamente la aplicación de producción, ejecutes su ciclo de vida ni cambies su configuración de compilación.

Después de preparar y revisar el fixture genuino, guarda las rutas seleccionadas (relativas a la raíz del proyecto):

python3 "<skill-directory>/scripts/bootstrap.py" configure --root "<project-root>" \
  --project "Package.swift" --source "Sources/StatusCard.swift" \
  --fixture ".swiftui-preview/fixtures/StatusCard.swift" --component StatusCard

--project también acepta un directorio .xcodeproj o .xcworkspace relativo; init es un alias de configure. Agrega --live-fixture "<ruta relativa>" para registrar un fixture con estado separado para compilaciones en vivo (consulta references/live.md). El archivo versionado .swiftui-preview/config.json almacena solo rutas relativas, nombre del componente, plataforma macos y hashes SHA-256 de la fuente seleccionada y el fixture adaptado. Se reubica con el proyecto y el usuario puede confirmarlo; no realices acciones de Git a menos que se solicite. La configuración existente se conserva a menos que se reemplace explícitamente con configure --replace después de la inspección y adaptación. Las rutas seleccionadas y la configuración deben existir dentro de la raíz, sin enlaces simbólicos ni traversal de rutas.

Después de que configure tenga éxito, produce la primera vista previa con run como se describe a continuación. Los asistentes directos en secciones posteriores son para fixtures únicos que no tienen configuración guardada.

Vistas previas posteriores

Cuando existe configuración, inspecciónala y usa run. Valida el esquema, las rutas y los hashes antes de despachar un asistente conocido con posiciones de argumentos fijas:

python3 "<skill-directory>/scripts/bootstrap.py" run --root "<project-root>" \
  --mode render --output "/absolute/task-output/card.png" \
  --width 480 --height 320 --locale en_US --theme light --frame

Usa --mode gallery con una salida .html o --mode live con una salida .app nueva. --theme y --frame se aplican solo a render; las galerías incluyen todas las variantes y las vistas previas en vivo tienen controles nativos. El directorio padre de la salida debe existir; bootstrap rechaza salidas existentes en lugar de reemplazarlas, a diferencia de los asistentes directos render.sh y gallery.sh; para volver a renderizar, elige un nuevo nombre de archivo o elimina primero el artefacto propiedad de la tarea anterior. Las rutas de salida relativas se resuelven desde la raíz del proyecto. --mode live solo compila; las reglas de inicio e inspección están en references/live.md.

Los cambios en los hashes de la fuente o del fixture detienen la ejecución. Vuelve a inspeccionar el componente real, actualiza el fixture, luego ejecuta configure --replace con las rutas seleccionadas, o refresh cuando se esté iterando una ventana en vivo. También inspecciona los cambios en definiciones/recursos de soporte: los hashes cubren la fuente principal y el fixture autónomo, no todo el grafo de dependencias. Cambiar de componente sigue el flujo de trabajo de adaptación del primer uso antes de reemplazar la configuración. Conserva las ediciones del usuario en los fixtures existentes.

Contrato del fixture y asistentes directos

El renderizador compila un archivo Swift autónomo junto con su asistente. Su punto de entrada es:

import SwiftUI

@MainActor
enum PreviewFixture {
    static func makeView() -> some View {
        Text("Ejemplo")
    }
}

Los asistentes compilan en modo de lenguaje Swift 6 con concurrencia estricta cuando el compilador lo admite, y en modo Swift 5 en caso contrario. Cuando un fixture adaptado de un proyecto Swift 5 falla solo en diagnósticos de concurrencia (Sendable, aislamiento de actor), no reescribas el componente para satisfacerlos: pasa --swift-version 5 a run o refresh, o establece PREVIEW_SWIFT_VERSION=5 para los asistentes directos, y di que la vista previa se compiló en modo Swift 5.

Usa datos sintéticos y estado inicial fijo. Usa acciones inertes para renders estáticos; los fixtures en vivo pueden implementar cambios de estado local de la vista, validación y navegación. Incluye los tipos de vista local requeridos del componente en el fixture; conserva los controles SwiftUI reales como Form, TextField, SecureField y Toggle. Mantén fuera del fixture los almacenes de credenciales, llamadas de red, persistencia y trabajo que sobreviva a la vista; un fixture en vivo puede simular un servicio con un breve retardo en memoria.

Cuando el proyecto ya tenga fixtures #Preview, reutiliza su construcción de vista y sus entradas. No compiles la macro #Preview ni una @main App en este fixture independiente. No reescribas la configuración del proyecto solo para renderizar un componente.

El mismo contrato de fixture funciona en todos los proyectos para componentes SwiftUI que compilan para macOS. Los componentes solo de UIKit requieren un flujo de trabajo de simulador de iOS. Los asistentes no vinculan automáticamente módulos de proyecto arbitrarios ni compilan/copian activos y catálogos de cadenas. Extrae una vista de valor autónoma cuando sea práctico. Si el componente necesita módulos o paquetes del proyecto, explica que este comando independiente necesita una compilación explícitamente adaptada; no afirmes que la inyección de configuración regional proporciona traducciones o recursos faltantes.

Renderizar e inspeccionar

Usa rutas apropiadas para la tarea actual. Resuelve el directorio de la habilidad desde la ubicación de esta habilidad, cita cada ruta y crea primero el directorio padre de la salida. Invoca:

bash "<skill-directory>/scripts/render.sh" \
  "/absolute/path/Fixture.swift" "/absolute/path/component-light.png" \
  480 320 light en_US

Los argumentos son fixture, PNG de salida, ancho de contenido, alto de contenido, apariencia (light o dark) e identificador de configuración regional. El ancho y el alto son enteros de 1 a 4096, renderizados a un píxel por punto, o fit. Un archivo de salida existente se reemplaza atómicamente; elige rutas propiedad de la tarea. Repite con dark y un nombre de archivo distinto cuando la comparación de apariencia sea útil. La configuración regional establece solo el entorno de SwiftUI; selecciona la dirección de diseño RTL explícitamente en un fixture si eso es parte de la prueba.

Elegir el viewport. Ajústalo al componente, no a los números de ejemplo. Para una pantalla completa, usa el tamaño de la ventana o dispositivo objetivo en puntos. Para una fila, tarjeta o control, pasa el ancho de su contenedor real y fit para la altura, como 390 fit; el renderizador mide el tamaño ideal del fixture en cada eje ajustado e imprime render: fitted content size WxH en stderr. fit fit es adecuado para controles con tamaño intrínseco, pero las vistas construidas alrededor de Spacer, maxWidth: .infinity o ScrollView se colapsan a su mínimo en un eje ajustado, así que dales un número. run --mode render acepta --width fit y --height fit; la galería y el modo en vivo necesitan números, así que reutiliza el tamaño informado allí.

Agrega --frame solo cuando se solicite o sea útil para la presentación. Agrega una barra de título decorativa y relleno circundante fuera del viewport de contenido fijo: las dimensiones de salida se convierten en ancho + 48 por alto + 88. Sus semáforos son formas dibujadas. No crea una ventana real ni valida el cromo de la ventana nativa.

Inspecciona la imagen generada con el visor de imágenes local disponible antes de informar los resultados visuales. Si el contenido está ausente o recortado, primero verifica el diseño del fixture y el viewport. Detente y explica los componentes que necesitan una ventana, ciclo de vida de la aplicación o recursos no disponibles en lugar de iniciar silenciosamente la aplicación de producción.

Galería y ventana en vivo

Dos salidas adicionales usan el mismo contrato de fixture. Lee la referencia vinculada en su totalidad antes de producir cualquiera de ellas; cada una tiene reglas sobre rutas de salida, inicio y lo que cuenta como verificado.

• Galería de temas HTML, cuando el usuario quiera comparar claro/oscuro o alternar el marco decorativo: run --mode gallery, o scripts/gallery.sh directamente. Consulta references/gallery.md.
• Ventana nativa en vivo, para botones reales, entrada de texto, enfoque y navegación: run --mode live, o scripts/live.sh directamente. Compila un .app y no lo inicia. Un fixture estático con acciones inertes no muestra nada al hacer clic; references/live.md explica cuándo agregar un fixture con estado separado con configure --live-fixture. Una ventana abierta nunca recoge cambios de código: después de actualizar el fixture, refresh recompila la aplicación en la misma ruta, cierra la ventana antigua y la vuelve a abrir (misma referencia).

Presentar el resultado

Inspecciona cada artefacto tú mismo antes de mostrarlo, luego preséntalo con lo que ofrezca el agente actual. Usa las herramientas realmente disponibles en la sesión; no asumas que existe una de esta lista.

Ubicación de salida. Usa un directorio propiedad de la tarea. Cuando el cliente solo pueda mostrar archivos dentro del proyecto, escribe en <project-root>/.swiftui-preview/artifacts/ (créralo primero) y no realices acciones de Git en él a menos que se solicite.

Claude Code.

• PNG: lee el archivo con la herramienta Read para inspeccionar la imagen. Para mostrarla, usa la herramienta de presentación de archivos o vista previa de la sesión cuando exista; de lo contrario, da la ruta absoluta como enlace y ejecuta open "/absolute/path/component-light.png" cuando el usuario haya pedido verla. Las imágenes Markdown en línea no se renderizan en una terminal.
• Galería HTML: ábrela en un navegador o herramienta de vista previa disponible usando su URL file://, o ejecuta open "/absolute/path/component-gallery.html". Prueba los controles de tema y marco a través de una herramienta de navegador antes de informarlos como verificados; sin ella, di que los controles no se probaron.
• Aplicación en vivo: ejecuta open "/absolute/path/SwiftUI Preview.app" cuando el lanzamiento esté dentro de la solicitud; refresh abre la aplicación a menos que se le dé --no-launch. Verifica la interactividad...