ntucker/agent-friendly-design-systems

Sistemas de diseño para uso agentivo

Este skill informa decisiones de diseño; no las impone. Cada recomendación puede perder frente a un objetivo legítimo del proyecto (expresividad experta, necesidades de marca, límites de plataforma, convenciones existentes). Nombra la concesión y difiere a una elección deliberada en contrario. Los ejemplos son React y TypeScript porque es donde los priors de los modelos son más nítidos; el razonamiento se traslada a cualquier stack.

El objetivo

Un modelo generador de código es un muestreador. Emite el programa que encuentra más plausible dado lo que aprendió en el entrenamiento (el prior) y lo que hay en la sesión (el contexto), luego conserva lo que sobrevive a las comprobaciones que puede ejecutar. Una API humana pregunta "¿se puede expresar lo correcto?". Una API agente pregunta "de todo lo que parece correcto, ¿cuánto es realmente correcto?". Así que el objetivo tiene dos mitades: hacer que el programa más probable sea el correcto, y hacer que los improbables fallen antes de enviarse.

Esto es diseño de API ordinario (Bloch: "fácil de usar correctamente, difícil de usar incorrectamente"; Minsky: "hacer que los estados ilegales no sean representables"; el pozo del éxito) bajo dos suposiciones más estrictas: la familiaridad del consumidor es una distribución medible sobre código público, y el consumidor verifica solo lo que puede ejecutar.

Tres propiedades del consumidor

Todo lo siguiente deriva de estas. Lee el Registro de evidencia cuando una afirmación a continuación importe para una decisión o necesites medir localmente; contiene fuentes, salvedades de alcance y el protocolo de medición.

1. El prior está moldeado por frecuencias, mezclado por versiones y no parcheable. Un modelo conoce un patrón en proporción a la frecuencia con que apareció en el entrenamiento; la precisión aumenta log-linealmente con la frecuencia en el corpus. Cada versión de una librería que haya aparecido está superpuesta en una distribución, razón por la cual los modelos emiten APIs obsoletas el 25-38% del tiempo y obtienen alrededor del 50% en tareas con versiones fijas. Nada de lo que una librería publique puede editar esto. Solo se puede igualar o anular.

2. El contexto anula el prior, pero solo el contexto que está realmente presente. Los prompts extraídos de código desactualizado produjeron entre un 70 y 90% de uso de API obsoleta; los prompts extraídos de código actual produjeron entre un 9 y 18%. El código hermano en el archivo dirige la salida más que cualquier cosa que publique la librería. La documentación recuperada ayuda; una etiqueta de versión escueta ayuda un poco. La documentación publicada que el agente nunca carga no hace nada.

3. Solo la retroalimentación ejecutable es verificación. El verificador de tipos es determinista, barato y siempre está en el bucle, y el 94% de los errores de compilación en TypeScript generado por LLM son errores de tipo, por lo que atrapa mucho. El renderizado es caro, necesita configuración, y el juicio visión-lenguaje sobre el layout es débil incluso con una captura de pantalla en mano. Lo que los tipos no codifican se envía si el modelo lo hace mal.

Dos consecuencias. El costo del error es asimétrico: un humano ve un mal hueco y lo arregla en segundos, el mal hueco de un agente se envía, por lo que "fácil de arreglar" vale mucho menos que "difícil de hacer mal". Y la evolución debe ser aditiva: un cambio de nombre o de significado les cuesta a los agentes hasta la próxima ronda de entrenamiento, y la forma antigua nunca abandona del todo la distribución, así que cuando debas romper, pon la migración en los tipos y la documentación co-ubicada, no solo en un changelog.

Tres movimientos

Cada palanca de diseño es uno de estos. Al evaluar un diseño, pregúntate qué movimiento hace y cuál socava.

Movimiento 1: hacer que la opción por defecto sea la correcta

La primera suposición del agente es el prior más el contexto visible. Dos cosas la moldean.

Los nombres son apuestas sobre distribuciones. El valor de un nombre es nitidez por concordancia: cuán unívoco es su uso público, multiplicado por si ese significado es el tuyo. La nitidez sigue el tamaño del corpus, la antigüedad y la estabilidad; así que el vocabulario de HTML y CSS gana sobre los nombres de patrones ARIA, que ganan sobre palabras pan-librería (sm/md/lg, primary/danger, solid/outline/ghost), que ganan sobre los modismos de cualquier librería; ancla tan profundo como la semántica lo permita. La concordancia es binaria, y un nombre familiar con comportamiento diferente es el peor caso: el modelo aplica el significado aprendido con confianza y el código compila. Cuando ningún nombre nítido concuerda con tu semántica, compón uno novedoso a partir de gramática aprendida. Page/PageHeader/PageTitle no existe en ninguna librería importante, sin embargo la conjugación X/XHeader/XTitle transmite jerarquía y orden hijo de forma gratuita y sigue siendo descubrible en el autocompletado y en el propio plan del agente. Una prop cuyo significado depende de otra prop (align bajo un interruptor direction) son dos apuestas acopladas; desacóplalas en un componente por eje o nombres explícitos. La ganancia es un grado de libertad menos, no un prior rescatado; los modelos manejan bien el cambio de eje de CSS por sí solos.

El código visible es el prompt. Los usos hermanos, el catálogo y el ejemplo canónico son en lo que el agente realmente se condiciona. La regularidad comprime ese prompt: si cada componente conjuga los mismos ejes con el mismo vocabulario, dos componentes en contexto enseñan todo el catálogo, y cada sinónimo o excepción por componente es un hecho separado que hay que enseñar y generalmente no se enseña. El catálogo particiona la salida: los agentes planean en unidades como "encabezado de página" y "barra de herramientas" antes de leer el código y fuerzan el plan a través de lo que exista; nombra los componentes según esas unidades. Lo que los ejemplos muestren se convierte en el flujo de trabajo, incluyendo las sobrescrituras de className; muestra la ruta prevista y mantén los ejemplos con la versión correcta y co-ubicados con el código que el agente debe tocar.

La fuerza del prior justifica conformarse en la sintaxis que el agente debe escribir. Nunca justifica exponer una decisión que el agente no debería estar tomando; eso es el Movimiento 3.

Movimiento 2: hacer que la salida incorrecta falle antes de enviarse

Cualquier cosa que un renderizado o un runtime habría atrapado debe fallar antes, o se envía.

Donde los tipos puedan expresarlo, ponlo en el tipo. Uniones cerradas en lugar de combinaciones booleanas que nadie diseñó. Uniones discriminadas para props dependientes del modo. Omit lo que una parte no soporta en lugar de documentar "no uses esto aquí". Props requeridas para los niveles de comportamiento de significado que se dejan al consumidor (títulos de diálogo, etiquetas de botones con icono, texto de error; Radix y React Aria advierten sobre estos solo en una consola que el agente nunca ve). Errores de compilación para los casos no soportados de asChild/as, o variantes explícitas no polimórficas como ButtonLink. La prueba es la misma cada vez: un agente que completa la prop ve el vocabulario legal, y el programa ilegal no compila.

Donde los tipos no puedan expresarlo, haz que la divergencia sea visible donde se escribe el código. Los nombres conllevan expectativas de layout que ningún tipo codifica (un contenedor posee su padding, un bloque llena su padre, el espaciado proviene de los gaps del padre; el estudio de caso los lista). Un componente que rompe la expectativa que su nombre crea compila y renderiza silenciosamente mal en la única dimensión que el agente no puede ver. Señala la ruptura en el lugar de la llamada (una prop requerida, un nombre no conflictivo) o en el contexto que el agente carga de manera confiable (una regla junto al código). La documentación que el agente no encontrará no cuenta.

Movimiento 3: eliminar la decisión

Una decisión cuya corrección solo es visible al renderizar pertenece a la librería, no al lugar de la llamada. Un principio en cuatro granularidades:

• Valores. Cuantifica cada magnitud y resuelve la apariencia mediante roles semánticos: gap="3" y tone="danger" en el lugar de la llamada, px y hex en el tema. Los modelos conocen la mecánica de flex y grid; no pueden elegir 12 frente a 16 a ciegas, y las elecciones independientes se desvían entre archivos hacia un ritmo que nadie ve. Las palabras clave (justify="space-between") mantienen la semántica libre mientras la escala elimina la suposición.
• Composición. Posee el layout, no solo los widgets. La regla de Braid es la versión limpia: los componentes no envían espacio exterior, y los componentes de layout poseen todo el espaciado. Un sistema que se detiene en el límite del widget hace que cada lugar de llamada improvise.
• Patrones. Donde una composición se repite (FormField, EmptyState, PageHeader, ConfirmDialog), envíala. Cada re-derivación a partir de primitivas es una oportunidad de divergencia.
• Adaptación. Maneja viewport, longitud de contenido, dirección de escritura, preferencias de movimiento y contraste, y estados de carga/vacío/error por construcción, o requiérelos en el tipo. La lógica de media query en el lugar de la llamada es una decisión ciega.

Las vías de escape (className, style, variables CSS) deben existir y situarse por debajo de la ruta predeterminada en probabilidad: disponibles, clasificadas, nunca destacadas. Si son el flujo de trabajo demostrado, el Movimiento 1 las ha convertido en la suposición predeterminada.

El régimen decide legibilidad versus contrato

Existen dos filosofías coherentes; shadcn es la declaración más clara de la primera.

• Legibilidad. Envía el código fuente al repositorio. El agente lo lee y lo edita, y el estilo es visible donde se escribe. Correcto cuando el agente posee los componentes: abrirá el archivo, y la implementación legible (estilo co-ubicado, mínima indirección) es lo que necesita.
• Contrato. Expone una API tipada y oculta la implementación. Correcto cuando el agente consume los componentes desde el código de la aplicación: ve importaciones, tipos y algunos usos hermanos, y rara vez abre la implementación. El estilo legible es estilo editable, y el estilo en el lugar de la llamada es la entropía que el Movimiento 3 elimina.

La mayoría de los sistemas necesitan ambos, divididos por audiencia: legibilidad para quien mantiene components/, contrato para todos los que importan de allí. Decide en qué régimen está un archivo antes de aplicar los movimientos. Lee el estudio de caso de shadcn cuando el sistema se base en shadcn o se compare con él; analiza qué conservar, qué cambiar y por qué.

Tensiones

Dos, cada una con varias caras. Nombra la concesión; no pretendas que es gratuita.

• Probabilidad concentrada versus expresividad. Cada grado de libertad eliminado es la capacidad perdida de alguien. Aparece como componentes de intención versus primitivas, ejes cerrados versus props ortogonales, y estirar un eje versus dividirlo (estira mientras cada valor responde a la misma pregunta; la variante Button de shadcn, que fusiona intención, tratamiento e identidad de elemento, es el eje fusionado canónico). La vía de escape clasificada es la respuesta habitual.
• Alineación con el prior versus propiedad. Coincidir con la convención compra corrección gratuita e importa los defectos y la volatilidad de la convención. Aparece como nombres familiares versus distintos (los distintos cuestan capacidad de descubrimiento; los nombres novedosos que cumplen la gramática recuperan la mayor parte) y como prior-amigable versus mejor diseñado. Divergir cuesta alineación una vez; mantener un defecto cuesta corrección para siempre.

Mide en lugar de confiar

Las tres propiedades se miden a nivel del modelo. Los movimientos son mecanismos consistentes con esas mediciones, no medidos en ninguna librería de UI; el archivo de evidencia marca cuál es cuál. Antes de adoptar una regla, ejecútala: 20 a 40 tareas de UI realistas, muestreadas varias veces por régimen (sin contexto, tipos más dos usos hermanos, código fuente completo); puntúa compilación en el primer intento, mal uso atrapado por tipos versus silencioso, varianza de tokens entre lugares de llamada hermanos, lint de accesibilidad y una breve revisión visual; cambia una decisión de diseño; vuelve a ejecutar. Conserva lo que mueve los números.

Lista de verificación de revisión

• Movimiento 1: ¿un modelo familiarizado con librerías comparables adivinaría esto en el primer intento, y si el nombre está tomado prestado, se comporta de manera idéntica? ¿El ejemplo canónico muestra la ruta prevista?
• Movimiento 2: ¿todo mal uso realista falla al compilar? Donde se rompe la expectativa visual de un nombre, ¿la ruptura es visible donde se escribe el código?
• Movimiento 3: ¿se deja algún valor, composición, patrón o adaptación para que el lugar de la llamada decida a ciegas?
• Régimen: ¿este archivo es poseído o consumido por el agente, y la elección legibilidad/contrato es deliberada?
• Evolución: ¿este cambio rompería el código escrito a partir del prior del año pasado, y la migración es visible en los tipos y la documentación co-ubicada?