Antes de AI-first, human-first

En el artículo anterior conté cómo estamos construyendo el Proyecto Harness Design System. El plan era claro: empezar con pocos componentes, probar con Claude Code, aprender antes de escalar.

La pregunta natural después de ese texto sería con qué componentes empezar. Esa fue la pregunta que traje a esta semana. Y cuando fui a responderla, descubrí que existía una pregunta anterior. Antes de decidir qué componente va primero, tuve que decidir qué va antes que los componentes. De eso trata este artículo.

El orden que quedó claro esta semana

La regla a la que llegué es simple de enunciar y más difícil de seguir: antes de AI-first, human-first.

Aplicar una capa de IA sobre un flujo que todavía tiene fricción entre designer y desarrollador no resuelve la fricción. La multiplica. Si el design system no está sincronizado entre Figma y el código hoy, en el flujo tradicional, cualquier agente que intente consumir ese sistema va a trabajar con dos fuentes de verdad al mismo tiempo. El problema que ya existe se va a volver más opaco, no más visible.

Incluso en el escenario en que la IA produzca cada vez más, siempre va a haber un humano operando en algún momento. Un designer revisando. Un desarrollador refactorizando. Un stakeholder validando. Si ese humano no puede confiar en la base, va a corregir cosas que generó la IA y el resultado va a parecer aleatorio. El orden es arreglar la base y después construir encima.

Dónde está la base hoy

En las últimas dos semanas, Glauber Franco y yo terminamos la tokenización completa en Figma. Aplicamos los tokens a componentes que ya existían, empezando por los más simples, como botones e inputs. Durante esa aplicación fuimos descubriendo lagunas semánticas. Un color de borde que no tenía token. Un fondo que necesitaba una variante nueva. Sombras que no estaban mapeadas. Cada laguna se convirtió en un ajuste en la variable correspondiente.

Un efecto colateral interesante apareció en este proceso: el dark mode casi de regalo. Cuando se trabaja bien con tokens y variables, el dark mode deja de ser un proyecto futuro y pasa a ser algo que se puede activar. No era una prioridad en el alcance, pero llegamos a un punto en que probar el dark mode fue casi trivial. La gente del equipo se entusiasmó, y los stakeholders también. Ese tipo de retorno inesperado es lo que pasa cuando el trabajo de base se hace bien. Arreglas la base y ganas cosas que no habías pedido.

El problema que todavía falta resolver

Los tokens están listos en Figma. En el código, no.

Si publicara el design system ahora, con los tokens nuevos en Figma y los antiguos corriendo en producción, crearía un problema peor que el actual. Los designers empezarían a entregar handoffs con colores y tipografías que el desarrollador no tiene cómo aplicar. Cada pantalla usada en una discusión con un stakeholder parecería una decisión tomada, pero lo que saldría a producción sería distinto. El ruido entre Figma y el código aparecería en todas las conversaciones, y nadie gana tiempo con eso.

Este es el tipo de problema que parece pequeño en la diapositiva y se vuelve grande cuando alcanza un sprint entero. Voy a tener cuidado para evitarlo.

Lo que viene la próxima semana

La próxima semana está dedicada a alinear con los desarrolladores de React y Flutter cómo van a aplicar la tokenización en el código que ya está en producción. Este trabajo no es pequeño. Cada color hardcodeado, cada referencia directa a un valor que debería ser un token, necesita ser revisada. Es trabajo de rastreo minucioso. Solo después de eso se puede publicar el design system en Figma y el flujo human-first vuelve a ser coherente.

En paralelo, empezamos a investigar una pregunta que todavía no sé responder: cómo hacer que los tokens sean consumibles por un LLM. Aquí vale una distinción que se ha vuelto importante en el Proyecto Harness Design System. Harness Design es la disciplina más amplia, el diseño de todo el sistema para que la IA pueda producir con dirección. LLM-readiness es una práctica específica dentro de eso: documentar y estructurar artefactos para que un LLM pueda leerlos y usarlos correctamente. Hacer que los componentes sean LLM-ready es parte del Harness Design. Hacer que los tokens sean LLM-ready también, y todavía no está claro cuánto trabajo va a exigir. Puede ser poco, puede ser mucho. Lo voy a descubrir la semana que viene.

Después de eso, los componentes. Y ahí vuelve la pregunta inicial

Cuando esa primera capa esté cerrada, la pregunta de con qué componentes empezar vuelve con peso. Y la respuesta intuitiva de tomar los más usados no basta por sí sola. Aplicar LLM-readiness en componentes sin tener una forma de probar si la aplicación está funcionando se vuelve actividad sin feedback. Mejoras la documentación, sigues al próximo componente y nunca sabes si lo que hiciste produjo resultado. Para probar, necesitas un escenario concreto.

La decisión: anclar en un patrón de pantalla

Miré nuestro sistema e identifiqué el patrón de pantalla que más se repite. Tiene cuatro componentes principales: menú, topbar, header y tabla. Es el patrón más básico que tenemos, y también el más frecuente. Voy a empezar por ahí. La decisión resuelve tres cosas a la vez.

Primera: los componentes de ese patrón están entre los más usados del sistema. Trabajarlos primero tiene un retorno alto incluso si el experimento de IA no da el resultado esperado, porque una mejor documentación para ellos sirve también para el flujo human-first.

Segunda: si Claude Code no logra reproducir bien esta pantalla, que es la más simple y estandarizada que tenemos, difícilmente va a lograr reproducir algo más complejo. Eso me da un criterio de falla claro, en lugar de una sensación vaga de que está más o menos.

Tercera: ya tenemos varias versiones de esta pantalla construidas manualmente, en el flujo tradicional. Eso se vuelve un caso de control. Puedo comparar lo que genera Claude Code con lo que el equipo produjo sin IA, y ver si está al mismo nivel, por debajo, o si necesita tanto ajuste que no vale la pena.

Lo que el experimento va a probar de verdad

Cuando los tokens estén aplicados en el código y esos cuatro componentes tengan la documentación de LLM-readiness, le voy a pedir a Claude Code que arme una pantalla de este patrón. La pregunta es si el resultado tiene una calidad cercana a la versión manual, sin necesitar mucho ajuste.

La respuesta va a ser sí, no o parcialmente. Cualquiera de las tres es información útil. Sí significa que el camino funciona y se puede escalar. No significa que algo está mal en algún lugar, y parte del trabajo va a ser descubrir si es en la documentación, en el método o en una premisa que todavía no vi. Parcialmente es el escenario más probable y el más interesante de documentar, porque va a mostrar dónde funciona, dónde se rompe y dónde necesita refinarse.

El orden del Proyecto Harness Design System

Resumiendo el orden que quedó claro esta semana. Tokens en el código primero. Design system publicado en Figma a continuación. LLM-readiness de los tokens investigada en paralelo. Después de eso, los componentes del patrón de pantalla más repetido, anclados en un experimento con caso de control.

Cada capa tiene que funcionar antes de que la siguiente sea confiable. Este artículo trata de cómo llegué a ese orden. Los próximos van a contar qué pasó cuando salí de él hacia la práctica, con las sorpresas que aparezcan en el camino.