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 las guías 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, 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 con fiabilidad. 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 tenga asignado 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 generada 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: que un usuario pueda abrir una aplicación que nunca ha visto y sepa cómo funciona. La conformidad es la meta; la identidad, explícitamente, no lo es.
Así que una habilidad de HIG puede hacer que su interfaz sea *correcta* —componentes adecuados, navegación adecuada, tamaños de objetivo adecuados, contraste adecuado— y 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 lo hacen.
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 es el briefing completo. 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 ve 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.
Color tokens
Ambient Sage
Core
background
H 72 · C0, 0, 2, 4
foreground
H 84 · C7, 0, 18, 89
card
H 70 · C0, 0, 3, 10
muted
H 80 · C1, 0, 3, 7
border
H 69 · C0, 0, 3, 15
Brand
primary
H 53 · C0, 8, 68, 0
primary-fg
H 84 · C7, 0, 18, 89
secondary
H 70 · C0, 0, 3, 10
accent
H 52 · C0, 8, 60, 3
ring
H 53 · C0, 8, 68, 0
Semantic
destructive
H 6 · C0, 70, 78, 25
destructive-fg
H 0 · C0, 0, 0, 0
success
H 130 · C61, 0, 51, 55
warning
H 35 · C0, 38, 91, 21
muted-fg
H 84 · C2, 0, 6, 66
Charts
chart-1
H 53 · C0, 8, 68, 0
chart-2
H 210 · C65, 33, 0, 17
chart-3
H 142 · C44, 0, 28, 25
chart-4
H 340 · C0, 48, 32, 12
chart-5
H 33 · C0, 30, 68, 9
Typography
Ambient Sage
Scale: compact-product
Density: balanced
Heading · Plus Jakarta Sans · 1.875rem
Sample headline
Subheading · Plus Jakarta Sans · 1.375rem
A warm-sage neutral-surface mobile kit with a single vivid yellow accent, flat tonal cards, and oversized display numerals.
Body · Plus Jakarta Sans · 1rem
Ambient Sage uses a near-white warm-sage canvas (#f3f4ef) with card panels distinguished only by a tonal shift to #e5e6e0, never by shadows or borders. A single vivid yellow (#fee951) is the only saturated color and appears sparingly at component scale as orbs, button fills, and focus rings. Primary data values render as oversized bold hero numerals with a small superscript unit. Typography is a friendly rounded geometric (Plus Jakarta Sans) with no uppercase and no tight tracking, while JetBrains Mono is reserved for hex codes and technical strings. Generous rounding and luminance-only contrast give the whole system a calm, minimal feel.
Mono · JetBrains Mono · 0.8125rem
npx shadcn add ambientsage.json
Aa
Plus Jakarta Sans · Heading
Aa
Plus Jakarta Sans · Body
ABCDEFGHIJKLM NOPQRSTUVWXYZ
abcdefghijklmnopqrstuvwxyz
0123456789 & @ # % →
Tokens
Ambient Sage primitives
Radius scale
Component radius
Elevation
Spacing · base 4px
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 raw en un componente. Un color de acento por pantalla |
| Tipografía | La tipografía debe sentirse refinada | Dos familias: display y body. Pasos de escala 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 | Soportar 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 hace. 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 deberse a uno de 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 parece más específica.
- Convención de plataforma frente a un patrón interno. Un dilema real. Decida una sola vez, documente cuál prevalece y por qué, y añádalo a la capa de identidad para no tener que rediscutirlo en cada pantalla.
- Estilos predeterminados 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. Use el componente de la plataforma, pero pintado con sus design tokens.
Especifique en el archivo qué capa prevalece
Un agente que maneje dos documentos sin una precedencia establecida elegirá uno en cada 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 en el resultado.
Configuración práctica
- 1
Cargue la capa de plataforma como una habilidad o archivo de reglas
Cualquier cosa que soporte su agente: una habilidad,
.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 repositorio
Un archivo de tokens más un DESIGN.md con sus reglas y prohibiciones. Debe estar en el repositorio y no 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 ha diseñado
Solicite algo plausible que ninguna de las dos capas haya previsto: un estado vacío, un error de permisos o un control de paginación. Lo que el agente invente es como se verá cualquier caso no cubierto, y esa es la medida real de su cobertura.
El último paso es el que merece la pena repetir. 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ó, por lo que la capa de identidad debe establecer reglas generales y prohibiciones en lugar de enumerar componentes. Más sobre qué incluir en 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.
Preguntas frecuentes
¿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 con fiabilidad. Las partes basadas en principios —claridad, deferencia, profundidad— no pueden cambiar el comportamiento, porque un agente satisface una instrucción no falsable basándose en lo que ya cree que significa esa palabra.
¿Hará que mi aplicación se vea bien una habilidad de HIG?
Hará que sea correcta, que es distinto. Las guías de plataforma son compartidas deliberadamente por todas las aplicaciones 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 —una cuando se actualiza la plataforma, otra cuando cambia su marca— y fusionarlas implicaría tener que desentrañar más tarde qué frases pertenecen a cada una. Mantenga dos archivos y especifique cuál prevalece en caso de conflicto.
¿Qué hago cuando un color de marca no cumple con el 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, ya que esa instrucción parece 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 valor hex puro, un solo color de acento por pantalla" sí la pasa.