Lo que la gente está haciendo en realidad
El patrón que aparece en los catálogos de habilidades para agentes consiste en tomar las Human Interface Guidelines de Apple (o Material, o la guía de accesibilidad de una plataforma) y empaquetarlas como algo que el agente carga antes de construir la UI. Un conjunto publicado divide las HIG en catorce habilidades que cubren plataformas, fundamentos y componentes: diseño, controles, diálogos, menús y búsqueda. Otros lo distribuyen como una única habilidad de diseño que promete componentes nativos, tipografía adecuada y colores semánticos.
Es un instinto correcto. Un agente de código al que se le pide una pantalla de ajustes de iOS sin ninguna guía producirá algo que funciona pero que se siente sutilmente mal: un modal donde lo convencional sería un push, un control que existe en la web pero no en la plataforma, u objetivos táctiles dimensionados para un ratón. Cargar las reglas de la plataforma soluciona una clase real de errores, y lo hace de forma económica.
También provoca algo que la gente no espera, y es importante ser precisos al respecto.
Qué sobrevive a la traducción y qué no
| Ejemplo | Qué hace el agente con ello | |
|---|---|---|
| Reglas prescriptivas | Objetivo táctil mínimo, qué control para cada tarea, cuándo un sheet es mejor que un push, mínimos de contraste | Las aplica de forma fiable. Son verificables, por lo que una respuesta incorrecta es visiblemente errónea |
| Principios | "Claridad", "deferencia", "profundidad" | Está de acuerdo con ellos y luego hace lo que ya iba a hacer |
Esa segunda fila es el problema central, y no es exclusivo de Apple. Una instrucción no falsable no puede cambiar el comportamiento, porque el modelo puede satisfacerla con cualquier significado que ya atribuya a esa palabra. Si pide claridad, obtendrá la idea promedio de claridad del modelo, que es la misma que la de cualquier otro modelo; por eso tanta UI creada por agentes converge en las mismas superficies casi negras, la misma paleta de gris y un color de acento, y las mismas tarjetas con bordes redondeados uniformemente.
Un agente puede seguir una regla. Solo puede estar de acuerdo con un principio.
Hemos medido este mismo fallo en entornos reales. De 299 archivos DESIGN.md públicos (documentos que los desarrolladores escriben específicamente para que un agente los siga), el 54% contiene al menos un adjetivo no medible, siendo los más comunes "limpio" (39%) o "moderno" (36%), y el 44% nunca indica un único valor de tamaño concreto. Esos archivos se leen como una dirección de diseño y funcionan como un acuerdo.
Lo que una guía de plataforma no intenta darle
Esta es la parte que sorprende a quienes instalan una habilidad de HIG esperando que su aplicación empiece a verse bien: las guías de plataforma son deliberadamente compartidas. Todas las aplicaciones de la plataforma las siguen. Ese es precisamente el objetivo. Un usuario debe poder abrir una aplicación que nunca ha visto y saber cómo funciona. La conformidad es la meta; la identidad, explícitamente, no lo es.
Por lo tanto, una habilidad de HIG puede hacer que su interfaz sea *correcta* (componentes adecuados, navegación adecuada, tamaños de objetivo adecuados, contraste adecuado), pero lo correcto no es lo mismo que lo distintivo. Si dos equipos cargan la misma guía y ningún otro contexto de diseño, deberían producir interfaces intercambiables. Y generalmente ocurre así.
Esto es una ventaja hasta que deja de serlo
Para una utilidad, un plugin o cualquier cosa integrada en el entorno de otro, mimetizarse es la respuesta correcta y la guía constituye todo el briefing. La discrepancia solo aparece cuando lo que se está construyendo es un producto que debe ser reconocible, y eso suele descubrirse alrededor de la quinta pantalla.
La configuración de dos capas
Una vez que se percibe como dos tareas separadas, la solución es obvia y las capas dejan de entrar en conflicto.
| Capa de plataforma | Capa de identidad | |
|---|---|---|
| Respuestas | ¿Cómo debería comportarse esto aquí? | ¿Cómo debería verse esto en todas partes? |
| Fuente | Las guías de la plataforma, como una habilidad o archivo de reglas | Su conjunto de design tokens y reglas escritas, en el repo |
| Cambia cuando | La plataforma cambia | Su marca cambia |
| Fallo si falta | UI con apariencia correcta que se siente ajena a la plataforma | UI perfecta según la plataforma, indistinguible de cualquier otra aplicación |
Manténgalas en archivos separados. Es tentador integrar su marca en la habilidad de HIG para cargar un solo elemento, pero esto falla en la primera actualización de la plataforma o en el primer cambio de marca, porque entonces tendrá que desentrañar qué frases pertenecían a cada una.
Token specimen · real values
Ambient Sage
Live renderAmbient Sage's actual tokens — the same values its exports use.
Cómo escribir una regla que un agente pueda verificar
La prueba es sencilla: ¿podría alguien mirar el resultado y decir, sin discusión, si se siguió la regla? Si dos personas razonables pudieran discrepar, el agente también lo hará, y resolverá la discrepancia a favor de sus valores predeterminados.
| Acordado con | Seguido | |
|---|---|---|
| Color | Use una paleta limpia y moderna | Use solo los tokens semánticos. Nunca un hex puro en un componente. Un color de acento por pantalla |
| Tipografía | La tipografía debe sentirse refinada | Dos familias: display y body. Escala de pasos a 1.25×. Nunca un tercer peso en el cuerpo del texto |
| Superficies | Mantenga las superficies ligeras y aireadas | Las tarjetas son planas. Sin sombras en superficies planas. Borde de 1px, token border |
| Modo oscuro | Soporte para modo oscuro | Cada rol de color definido en ambos modos. Nunca implemente un cambio en modo claro sin su contraparte en modo oscuro |
Observe cuántas de las entradas de la derecha son prohibiciones. Esto no es una elección estilística: una preferencia añade una opción, mientras que una prohibición elimina todas las demás. "Use nuestro verde" deja que cualquier valor predeterminado genérico siga siendo válido; "nunca introduzca un color que no sea un token" no lo permite. En nuestro corpus, el 76% de los archivos solo enumeraban preferencias, lo cual es una descripción precisa de por qué dejan de funcionar.
Cuando la guía y la marca no coinciden
Esto ocurre con menos frecuencia de lo que se teme, ya que ambas capas abordan mayoritariamente preguntas diferentes. Cuando sucede, suele tratarse de uno de estos tres casos, y solo uno de ellos es un conflicto real.
- Mínimos de accesibilidad frente a un color de marca. No es un conflicto. El mínimo prevalece y el color de acento debe ajustarse para esa superficie. Un agente al que se le indique esto explícitamente lo hará; un agente que tenga que elegir suele mantener el color de marca, porque esa instrucción parecía más específica.
- Convención de la plataforma frente a un patrón interno. Un dilema real. Decida una sola vez, documente cuál prevalece y por qué, y colóquelo en la capa de identidad para no tener que rediscutirlo en cada pantalla.
- Estilo predeterminado de la plataforma frente a sus tokens. No es un conflicto, aunque lo parezca. Las guías especifican qué control utilizar; rara vez especifican su color exacto. Utilice el componente de la plataforma, pintado con sus design tokens.
Indique en el archivo qué capa prevalece
Un agente que maneje dos documentos sin una precedencia establecida elegirá según el turno y no le informará de cuál ha elegido. Una sola línea ("en caso de conflicto, prevalecen los mínimos de accesibilidad, luego las convenciones de la plataforma y, por último, el estilo interno") elimina toda una categoría de inconsistencias que, de otro modo, sería casi imposible de diagnosticar a partir del resultado.
Configuración práctica
- 1
Cargue la capa de la plataforma como una skill o un archivo de reglas
Sea lo que sea que soporte su agente: una skill,
.cursor/rules,.devin/ruleso una sección en CLAUDE.md. Manténgalo lo más fiel posible a la guía original para que pueda sustituirse íntegramente cuando la plataforma se actualice. - 2
Coloque la capa de identidad en el repo
Un archivo de tokens más un DESIGN.md con sus reglas y prohibiciones. Debe estar en el repositorio en lugar de en un prompt, porque el agente necesita volver a leerlo en cada tarea, al igual que la siguiente persona que trabaje en el proyecto.
- 3
Establezca la precedencia una sola vez
Una frase al principio del archivo de identidad indicando qué prevalece en caso de conflicto.
- 4
Pruebe en la pantalla que nadie diseñó
Solicite algo plausible que ninguna de las dos capas haya previsto: un estado vacío, un error de permisos, un control de paginación. Lo que el agente invente es como se verá cada caso no cubierto, y esa es la medida real de su cobertura.
El último paso es el que merece repetirse. Ambas capas cubren los casos en los que alguien pensó. En un producto creado por un agente, la mayoría de las pantallas son casos en los que nadie pensó, razón por la cual la capa de identidad debe establecer reglas generales y prohibiciones en lugar de enumerar componentes. Más sobre qué debe incluir ese archivo: qué es un DESIGN.md.
La capa de identidad, como un único archivo instalable
Cada kit de Identity Forge se serializa en un DESIGN.md completo (tokens semánticos en modo claro y oscuro, una combinación de fuentes real, motivos y prohibiciones explícitas) junto con el archivo de tokens. Se ubica junto a cualquier guía de plataforma que cargue y nunca entra en conflicto con ella.
FAQ
¿Puede un agente de IA seguir las Human Interface Guidelines de Apple?
Las partes prescriptivas, sí: elección de controles, patrones de navegación, objetivos táctiles mínimos, mínimos de contraste. Estos son verificables, por lo que el agente los aplica de forma fiable. Las partes basadas en principios (claridad, deferencia, profundidad) no pueden cambiar el comportamiento, porque un agente satisface una instrucción no falsable con lo que ya cree que significa la palabra.
¿Hará que mi aplicación se vea bien una skill de HIG?
Hará que sea correcta, que es distinto. Las guías de plataforma son deliberadamente compartidas por todas las aplicaciones de la plataforma para que los usuarios puedan transferir sus conocimientos entre ellas. Dos equipos que carguen la misma guía y nada más deberían producir interfaces intercambiables. La distintividad proviene de una segunda capa: sus propios tokens y reglas.
¿Deberían las guías de plataforma y mi sistema de diseño estar en un mismo archivo?
No. Cambian en calendarios diferentes (uno cuando la plataforma se actualiza, otro cuando lo hace su marca) y fusionarlos implicaría tener que desentrañar más tarde qué frases pertenecen a cada uno. Mantenga dos archivos y establezca cuál prevalece en caso de conflicto.
¿Qué hago cuando un color de marca no cumple con un mínimo de accesibilidad?
El mínimo prevalece y el color de acento debe ajustarse para esa superficie. Indique esto explícitamente en sus reglas: un agente que tenga que elegir suele mantener el color de marca, porque esa instrucción parecía más específica que una nota general de accesibilidad.
¿Cómo sé si una regla está lo suficientemente bien escrita para un agente?
Pregúntese si un revisor podría mirar el resultado y decir, sin discusión, que se ha seguido la regla. "Use una paleta limpia" no pasa la prueba. "Use solo los tokens semánticos, nunca un hex raw, un color de acento por pantalla" sí la pasa.