O que as pessoas estão fazendo na prática
O padrão que surge nos catálogos de habilidades de agente é pegar as Human Interface Guidelines da Apple (ou Material, ou as orientações de acessibilidade de uma plataforma) e reempacotá-las como algo que o agente carrega antes de construir a UI. Um conjunto publicado divide o HIG em quatorze habilidades que cobrem plataformas, fundamentos e componentes: layout, controles, diálogos, menus, busca. Outros as entregam como uma única habilidade de design que promete componentes nativos, tipografia adequada e cores semânticas.
Este é um bom instinto. Um agente de código solicitado a criar uma tela de ajustes de iOS sem orientações produzirá algo que funciona, mas parece sutilmente errado: um modal onde o convencional seria um push, um controle que existe na web mas não na plataforma, alvos de toque dimensionados para um mouse. Carregar as regras da plataforma corrige uma classe real de erros, e faz isso de forma barata.
Isso também causa algo que as pessoas não esperam, e vale a pena ser preciso sobre isso.
O que sobrevive à tradução e o que não sobrevive
| Exemplo | O que o agente faz com isso | |
|---|---|---|
| Regras prescritivas | Alvo de toque mínimo, qual controle para qual função, quando um sheet é melhor que um push, mínimos de contraste | Aplica-as com precisão. Estas são verificáveis, então uma resposta errada é visivelmente errada |
| Princípios | "Clareza", "deferência", "profundidade" | Concorda com eles e, então, faz o que já faria de qualquer maneira |
Essa segunda linha é todo o problema, e não é algo específico da Apple. Uma instrução infalsificável não consegue mudar o comportamento, porque o modelo pode satisfazê-la com qualquer significado que ele já atribua àquela palavra. Peça clareza e você terá a ideia mediana de clareza do modelo, que é a mesma de qualquer outro modelo; é por isso que tantas UIs construídas por agentes convergem para as mesmas superfícies quase pretas, a mesma paleta de cinza com uma cor de destaque e os mesmos cards com cantos arredondados uniformemente.
Um agente consegue seguir uma regra. Ele consegue apenas concordar com um princípio.
Medimos a mesma falha na prática. Em 299 arquivos DESIGN.md públicos (documentos que desenvolvedores escrevem especificamente para que um agente os siga), 54% contêm pelo menos um adjetivo imensurável, sendo os mais comuns "clean" (39%) ou "moderno" (36%), e 44% nunca declaram um único valor de tamanho concreto. Esses arquivos parecem direcionamentos de design e funcionam como acordos.
O que uma diretriz de plataforma não está tentando te entregar
Aqui está a parte que surpreende quem instala uma habilidade de HIG esperando que seu app comece a ficar bonito: as diretrizes de plataforma são deliberadamente compartilhadas. Todo app na plataforma as segue. Esse é exatamente o objetivo. Um usuário deve ser capaz de abrir um app que nunca viu e saber como ele funciona. A conformidade é a meta, e a identidade explicitamente não é.
Portanto, uma skill de HIG pode tornar sua interface *correta* (componentes certos, navegação certa, tamanhos de alvo certos, contraste certo), mas ser correto não é o mesmo que ser distintivo. Se duas equipes carregarem a mesma diretriz e nenhum outro contexto de design, elas deverão produzir interfaces intercambiáveis. E geralmente produzem.
Isso é uma vantagem, até deixar de ser
Para um utilitário, um plugin ou qualquer coisa incorporada ao ambiente de terceiros, misturar-se ao entorno é a resposta certa e a diretriz é o briefing completo. A incompatibilidade só aparece quando o que está sendo construído é um produto que precisa ser reconhecível, e isso geralmente é descoberto por volta da quinta tela.
A configuração de duas camadas
Assim que você enxerga isso como dois trabalhos distintos, a solução torna-se óbvia e as camadas param de conflitar entre si.
| Camada de plataforma | Camada de identidade | |
|---|---|---|
| Respostas | Como isso deve se comportar aqui? | Qual deve ser a aparência disso em todos os lugares? |
| Fonte | As diretrizes da plataforma, como uma skill ou arquivo de regras | Seu conjunto de tokens e regras escritas, no repo |
| Altera quando | A plataforma muda | Sua marca muda |
| Falha se estiver ausente | UI com aparência correta, mas que parece estranha na plataforma | UI perfeita para a plataforma, indistinguível de qualquer outro app |
Mantenha-as em arquivos separados. É tentador fundir sua marca na skill de HIG para ter apenas um item para carregar, mas isso dará errado na primeira atualização de plataforma ou no primeiro rebranding, porque você terá que desmembrar quais frases pertenciam a quem.
Token specimen · real values
Ambient Sage
Live renderAmbient Sage's actual tokens — the same values its exports use.
Escrevendo uma regra que um agente consiga verificar
O teste é simples: alguém poderia olhar para o resultado e dizer, sem discussões, se a regra foi seguida? Se duas pessoas razoáveis pudessem discordar, o agente também discordará, e resolverá a divergência a favor de seus padrões (defaults).
| Acordado com | Seguido | |
|---|---|---|
| Cor | Use uma paleta limpa e moderna | Use apenas os tokens semânticos. Nunca use um hex bruto em um componente. Um destaque por tela |
| Tipografia | A tipografia deve parecer refinada | Duas famílias: display e body. Escalonamento em 1.25×. Nunca use um terceiro peso no corpo do texto |
| Superfícies | Mantenha as superfícies leves e arejadas | Cards são planos. Sem sombra em superfície plana. Borda de 1px, token border |
| Modo escuro | Suporte ao modo escuro | Cada função de cor definida em ambos os modos. Nunca envie uma alteração de modo claro sem sua contraparte no modo escuro |
Note que muitas das entradas à direita são proibições. Isso não é uma escolha estilística: uma preferência adiciona uma opção, enquanto uma proibição remove todas as outras. "Use nosso verde" mantém todos os padrões genéricos como válidos; "nunca introduza uma cor que não seja um token" não permite isso. Em nosso corpus, 76% dos arquivos listavam apenas preferências, o que é a descrição exata do porquê de eles pararem de funcionar.
Quando a diretriz e a sua marca divergem
Isso acontece com menos frequência do que as pessoas temem, pois as duas camadas geralmente abordam questões diferentes. Quando acontece, costuma ser um de três casos, e apenas um deles é um conflito real.
- Mínimos de acessibilidade versus cor da marca. Não é um conflito. O mínimo prevalece, e a sua cor de destaque precisa de ajuste para aquela superfície. Um agente instruído explicitamente sobre isso o fará; um agente deixado à escolha geralmente manterá a cor da marca, pois essa instrução pareceu mais específica.
- Convenção de plataforma versus padrão interno. Um trade-off real. Decida uma vez, escreva qual prevalece e por que, e coloque isso na camada de identidade para que não seja rediscutido a cada tela.
- Estilização padrão da plataforma versus seus tokens. Não é um conflito, embora pareça. As diretrizes especificam qual controle usar; raramente especificam sua cor exata. Use o componente da plataforma, estilizado com seus design tokens.
Defina qual camada prevalece, no arquivo
Um agente com dois documentos sem precedência declarada escolherá a cada turno, e não dirá qual escolheu. Uma única linha ("em caso de conflito, prevalecem os mínimos de acessibilidade, depois as convenções da plataforma e, por fim, o estilo interno") elimina toda uma categoria de inconsistência que, de outra forma, seria quase impossível de diagnosticar pelo resultado final.
Configuração prática
- 1
Carregue a camada da plataforma como uma skill ou arquivo de regras
O que quer que seu agente suporte: uma skill,
.cursor/rules,.devin/rules, uma seção no CLAUDE.md. Mantenha o mais próximo possível da diretriz original, para que possa ser substituído integralmente quando a plataforma for atualizada. - 2
Coloque a camada de identidade no repo
Um arquivo de tokens mais um DESIGN.md com suas regras e proibições. Ele deve estar no repositório em vez de em um prompt, porque o agente precisa relê-lo a cada tarefa, assim como a próxima pessoa que assumir o projeto.
- 3
Declare a precedência uma única vez
Uma frase no topo do arquivo de identidade nomeando o que prevalece em caso de conflito.
- 4
Teste na tela que ninguém projetou
Peça algo plausível que nenhuma das camadas previu: um estado vazio, um erro de permissão, um controle de paginação. O que o agente inventar é como será cada caso não mapeado, e essa é a sua real medida de cobertura.
O último passo é o que vale a pena repetir. Ambas as camadas cobrem os casos em que alguém pensou. Em um produto construído por um agente, a maioria das telas são casos em que ninguém pensou, e é por isso que a camada de identidade deve declarar regras gerais e proibições, em vez de enumerar componentes. Mais sobre o que pertence a esse arquivo: o que é um DESIGN.md.
A camada de identidade, como um único arquivo instalável
Cada kit do Identity Forge é serializado em um DESIGN.md completo (design tokens semânticos em light e dark, um pairing de fontes real, motivos e proibições explícitas) junto com o arquivo de tokens. Ele fica ao lado de qualquer orientação de plataforma que você carregue, e nunca conflita com ela.
FAQ
Um agente de IA consegue seguir as Human Interface Guidelines da Apple?
As partes prescritivas, sim: escolha de controles, padrões de navegação, alvos de toque mínimos, contrastes mínimos. Estes são verificáveis, então o agente os aplica com precisão. As partes principiológicas (clareza, deferência, profundidade) não conseguem mudar o comportamento, porque um agente satisfaz uma instrução não falsificável com o que ele já acredita que a palavra significa.
Uma skill de HIG fará meu app ficar bonito?
Fará com que ele fique correto, o que é diferente. As diretrizes de plataforma são deliberadamente compartilhadas por todos os apps da plataforma para que os usuários possam transferir conhecimento entre eles. Duas equipes carregando a mesma diretriz e nada mais deveriam produzir interfaces intercambiáveis. A distinção vem de uma segunda camada: seus próprios tokens e regras.
As diretrizes de plataforma e meu design system devem ficar em um único arquivo?
Não. Eles mudam em cronogramas diferentes (um quando a plataforma atualiza, outro quando sua marca muda) e fundi-los significa ter que desmembrar quais frases pertencem a quem futuramente. Mantenha dois arquivos e declare qual prevalece em caso de conflito.
O que eu faço quando uma cor da marca não atinge o mínimo de acessibilidade?
O mínimo prevalece e a cor de destaque precisa de ajuste para aquela superfície. Declare isso explicitamente em suas regras: um agente deixado à escolha geralmente mantém a cor da marca, porque essa instrução pareceu mais específica do que uma nota geral de acessibilidade.
Como sei se uma regra está escrita bem o suficiente para um agente?
Pergunte se um revisor poderia olhar para o resultado e dizer, sem discussão, que a regra foi seguida. "Use uma paleta limpa" falha nesse teste. "Use apenas os design tokens semânticos, nunca um hex bruto, um destaque por tela" passa no teste.