Para qué sirve un catálogo
El estándar compartido hace que todos los productos de Weblabor usen los mismos tokens y los mismos componentes base. No hace que dos pantallas del mismo producto se parezcan: un recuadro del panel construido en marzo y su gemelo construido en septiembre pueden seguir los dos el estándar y aun así ser distintos, porque nada dice qué es un recuadro en este producto.
/design-catalog es el responsable de diseño de tu producto para ese nivel. El catálogo que planea son dos cosas, y ninguna es un documento:
- Componentes compuestos en la capa de diseño propia de tu producto, construidos encima de los componentes base y nunca duplicándolos con otro nombre, y llamados desde cada pantalla como
<x-design::nombre>. - La pantalla de diseño de la base en
/admin/design, que muestra cada componente de diseño en uso. Una pantalla que importa los componentes reales no puede describir una versión de ellos que ya no existe.
Planea, y no construye nada en tu producto. No crea componentes, no edita pantallas y no hace commits propios ahí. Lo que deja son documentos de tu proyecto en el toolkit: tu manual de identidad, los planes que construyen el catálogo y filas de tus hallazgos pendientes. La construcción ocurre en la cola. Puede abrir tu producto en el navegador para ver aquello en lo que trabaja. Lo único que puede cambiar fuera del toolkit es un arreglo en weblabor-base o weblabor-teams, y solo cuando tú dices que sí, junto con el merge que trae ese arreglo a tu producto.
Dónde corre
Corre dentro del repositorio de tu propio producto, y revisa tres cosas antes que nada. Cuando una falla dice cuál y se detiene, sin haber escrito nada:
- No es el repositorio del toolkit. Vuelve a lanzarlo desde tu producto.
- El checkout es una aplicación, con vistas y estilos donde construir un catálogo.
- La capa de diseño de weblabor-base ya llegó por merge. Si tu producto integró la base por última vez antes de que existiera la capa, intégrala primero y vuelve a correrlo.
También necesita el toolkit conectado, porque todo lo que escribe vive ahí. Y la carpeta donde van tus componentes tiene que llevar el nombre propio de tu producto, que se lee de config/app.php; mientras siga apuntando a la de la base o a la genérica, te dice que configures primero el nombre de tu proyecto.
Tu manual de identidad, en identity/
Al empezar te pide tu manual de identidad o de interfaz. Dale lo que tengas: el manual, tus logos, un PDF o una imagen de la marca, por su ruta en tu computadora, o un documento o archivo ya subido a tu proyecto en la sección Proyectos, nombrado por su ruta.
Todo lo que ayuda a entender el diseño se guarda en la carpeta identity/ de tu proyecto en el toolkit:
- Un documento Markdown se guarda tal cual.
- Una imagen, un logo o un PDF se sube tal como es, sin tocarlo, y junto a él va una descripción escrita de lo que muestra: los colores con sus valores, la tipografía, el espaciado, los ejemplos y las reglas de uso.
- Un archivo que solo adjuntaste a la conversación, sin ruta en tu computadora, no se puede subir desde ahí: te pide su ruta, o que lo subas tú desde la página de tu proyecto, y el reporte dice qué archivos siguen esperando.
- Si tu asistente no puede leer imágenes, te pide los valores con palabras. Colores, una escala tipográfica y espaciados descritos con palabras son un manual completo.
El brief de tu landing — qué es el producto, para quién es, qué promete — también se guarda ahí, nunca en tu repositorio. Cuando identity/ ya tiene documentos o archivos, los lee, incluidos los originales, y solo agrega o actualiza lo que le diste esta vez. A partir de ahí esa carpeta es la referencia permanente: los planes toman de ella sus colores y su fuente, y la revisión de diseño de la cola juzga contra ella lo que se construyó.
Lo que lee antes de proponer nada
Lee el producto entero, no las partes probables: tu capa de diseño y lo que ya trae la base, las pantallas que dibujan a mano lo que un componente de diseño ya muestra, los bloques que se repiten entre pantallas sin un componente detrás, los componentes que construiste fuera de tu capa de diseño, la navegación, el marco de la sesión iniciada y el panel de administración, cada pantalla agrupada por área, lo que el producto dice de sí mismo para su landing — entre ello tu visión del producto — y lo que tu carpeta analysis/ y tus hallazgos pendientes ya planean o anotan.
Un componente que resulta ser de la base, y no tuyo, nunca lo mueve ni lo edita un plan. Uno cuyo origen no se puede resolver se deja fuera de todos los planes y se nombra.
La propuesta, en dibujos para elegir
Tú decides el diseño, y un diseño se juzga viéndolo. Por eso la propuesta no es un texto para aprobar: es una página que se muestra al lado de la conversación, en rondas. Cada ronda pone una de tus pantallas actuales — por ejemplo la de inicio del área con sesión, reconstruida desde el código — junto a dos a cuatro propuestas dibujadas sobre esa misma pantalla. La primera ronda también te dice lo que encontró y lo que guardó en identity/, para que corrijas una descripción antes de que algo se apoye en ella.
- Las rondas van de lo general a lo particular: primero la dirección general, luego los colores de la que elegiste y luego la estructura del menú y del marco. La primera ronda siempre corre; una posterior que tu manual de identidad ya contesta se salta, y una elección que deja dudas abre otra ronda.
- Lo que eliges se aplica a todo. Si eliges bordes redondeados una vez, todos los componentes los llevan; no se pregunta pantalla por pantalla.
- Un rediseño tiene que notarse. Además de colores y componentes, las propuestas rehacen el marco: el menú, las barras laterales, el área con sesión y el panel de administración.
- Todas las áreas reciben el mismo tratamiento. Si alguna recibe menos, el dibujo lo dice, con la razón.
El agente ux-designer propone lo que se dibuja, y el conjunto más chico de componentes que necesita tu producto: las variantes de un mismo patrón se vuelven un solo componente siempre que un ajuste pueda absorber la diferencia. Tú solo decides lo que ves. Qué componentes, cómo se dividen los planes y todo lo técnico se decide por ti, y ningún plan se te enseña para aprobarlo. La única decisión que no es un dibujo es la de un arreglo en una base, más abajo; aparte de eso, solo te pide lo que no puede encontrar por su cuenta, como los archivos de tu manual o qué hilo corre la cola. Los dibujos son solo para decidir el diseño: todo lo demás que te dice — un aviso, su reporte, esa pregunta sobre un arreglo en una base — llega en texto normal.
Los planes que escribe
Cada plan tiene la forma de un plan de /plan-prompt, abre con la línea Origen: escrito por /design-catalog. y se guarda en la carpeta analysis/ de tu proyecto como Listo para ejecutar. Se dividen para que la cola los pueda construir en paralelo:
- Un plan base: tus colores y tu fuente, y el marco — el menú, las barras laterales, el área con sesión y el panel de administración.
- Un plan por cada familia de componentes, y uno para la landing, cada uno apoyado en el plan base. Cada pantalla pertenece a uno solo de ellos, así que dos planes nunca tocan el mismo archivo.
- Un último plan que recorre todas las pantallas en tu navegador a 375, 768 y 1440 píxeles de ancho, apoyado en todos los demás.
Tu color primario, tu acento y tu fuente van en el archivo de tema de tu producto, resources/css/themes/tu-proyecto.css, como las variables de marca que describe la guía Brand and interface de weblabor-base — con la importación de tu fuente cuando hay que cargarla, y sin estilos propios; todo lo demás del aspecto vive en los componentes. Cada pantalla es un punto de su plan, con su propia fila del checklist. Una pantalla que queda fuera de todos los planes se nombra en el reporte, con el porqué. La prueba de cada plan abre /admin/design y cada pantalla que toca, porque un reestilizado que perdió un ajuste solo se nota como algo que falta en pantalla.
No se escribe nada en tu repositorio, y no se commitea nada ahí. La corrida termina nombrando los planes y mandándote a /next.
Cómo los construye la cola
/next construye cada plan, lo revisa en el navegador con /test y luego hace que ux-designer abra las pantallas que construyó y las juzgue contra tu catálogo y tu manual de identidad. Cuando no siguen los dos, la corrección del diseñador se escribe en el mismo plan, que la cola construye y vuelve a revisar, dentro de los mismos tres intentos que cualquier otra revisión. Esa revisión se describe en Correr la cola con /next.
Sigue la cola hasta el final
Guardar los planes no es el final. Programa un coordinador — el mismo que pone /coordinate, con la misma regla — que cada 20 minutos revisa el hilo donde corre /next, por defecto el llamado Next steps: que esté trabajando, que un plan suyo no esté detenido por preguntas — que contesta con lo que elegiste en las rondas, y solo te pregunta, con dibujos, lo que esas elecciones dejan abierto del diseño, y lo técnico lo decide él solo — y que no se haya quedado fuera un documento nuevo, que le avisa a ese hilo. Si no hay ningún hilo con ese nombre, te pregunta cuál revisar. Nunca construye ni corre /next por su cuenta. Se detiene cuando todos sus planes están implementados o detenidos donde solo tú puedes moverlos — descartados, pausados, bloqueados tras tres intentos o esperando una pregunta para ti — y no queda nada más en camino. Si tu asistente no puede programar esto, te lo dice y te pide que le escribas cada cierto tiempo para revisar.
Un arreglo que es de una base
Si encuentra algo que se arregla en weblabor-base o en weblabor-teams y no en tu producto, te pregunta: encontramos esto, se arregla desde ese proyecto, ¿lo hacemos? Si dices que sí, lo arregla directamente ahí, con un commit propio que lleva solo ese arreglo. No lo sube: subirlo te toca a ti. Cuando el arreglo está en el repositorio del que tu producto hace merge directamente, el coordinador lo lleva a la rama base-update de tu producto y de ahí lo integra con un merge a la rama donde se guardaron los planes de tu producto, el mismo camino que sigues a mano. Solo mueve base-update hacia adelante: si esa rama tiene commits que la base no tiene, te lo dice y espera. No espera a los planes que la cola construye cada uno en su propio worktree, solo a uno que se construye directamente sobre la rama, en tu producto o en la base, y a un plan que la cola de tu producto está comprobando en el navegador. Tu producto necesita esa rama base-update: si no la tiene, te lo dice al montar el coordinador, y el arreglo espera hasta que la crees. Y si el coordinador encuentra un conflicto que no puede resolver con certeza, te lo deja a ti con el archivo y el motivo. Un arreglo hecho más arriba en la cadena te toca bajarlo a ti. Lo demás sigue: los planes que lo necesitan esperan ese comportamiento por su cuenta, y te avisa cuando el arreglo ya está en la base.
Correrlo otra vez
Cuando tu producto ya tiene catálogo, esta es la corrida más frecuente: las pantallas construidas después se alejan de él, o traen patrones que no cubre. Una corrida posterior revisa cada pantalla contra el catálogo e identity/, en los dos sentidos: patrones que ningún componente cubre, y componentes que una pantalla ignoró, o un color, un tipo de letra o un espaciado que se aparta del manual. Lo que no cumple se vuelve un plan de corrección; lo que hace falta de nuevo, un plan nuevo. Los dos pasan por las mismas rondas.
Componentes que podrían servirle a todos los productos
Un componente que no depende de nada de tu producto — ni de su marca ni de su dominio — es candidato para weblabor-base. Se escribe como una fila en los Hallazgos pendientes de tu proyecto, nombrando las pantallas a las que sirve, para que la señal sobreviva a la conversación. La fila se va cuando tu producto adopta la versión de la base. Un reestilizado de un componente base nunca es candidato.
Lo que no hará
- Cambiar el estándar compartido de Tailwind. Es un solo estándar para todos los productos; para cambiarlo, usa
/improve-toolkit. - Editar archivos que la base guarda para sí, ni weblabor-base mismo, salvo un arreglo que aprobaste. Un producto cambia el aspecto de la base con una copia del mismo nombre en su propia capa de diseño, y sus colores y su fuente en su propio archivo de tema.
- Ordenar el proyecto en general. Eso es
/cleanup.
Sigue por aquí
- Correr la cola con /next — cómo se construyen los planes y se revisan en diseño.
- Escribir la visión del producto — de dónde se leen los textos de la landing.
- Lo que el analizador no puede revisar — reutilizar un componente, una de las revisiones que ningún archivo suelto prueba.