O que 21 Grams UX faz?
Uma passagem sobre fluxos que já existem. 21 Grams UX (o pacote de UX da família 21 Grams) não redesenha o produto nem adiciona um kit de UI. Ela percorre os fluxos reais, encontra onde produtos construídos por IA quebram para as pessoas que os utilizam (becos sem saída, estados faltantes, falhas silenciosas, ações irreversíveis, formulários que lutam contra o usuário) e os corrige através dos componentes e padrões que o projeto já possui.
21 Grams UI cuida da aparência. 21 Grams UX cuida se funciona. Quando ambos estiverem instalados, execute UX primeiro: não adianta polir uma etapa que não deveria existir.
Regra zero: use os próprios componentes do projeto
Cada mudança passa pelo que o projeto já utiliza. 21 Grams UX nunca constrói um conjunto paralelo de componentes ou um fluxo paralelo.
- Faça um inventário antes de tocar em qualquer coisa. Anote o roteador e o mapa de rotas, a biblioteca de componentes, a biblioteca de formulários e a abordagem de validação, os componentes de toast, diálogo e estado vazio, a camada de busca de dados (de onde vêm os estados de carregamento e erro) e a camada de análise ou eventos, se houver.
- Corrija as coisas onde elas vivem. Um estado de erro faltante vai para o componente compartilhado de dados ou estado vazio, não para uma tela. Um padrão de confirmação vai para o diálogo do projeto, não para um caso isolado.
- Nunca adicione um componente ou dependência quando um já existe para o trabalho. Nenhuma nova biblioteca de formulários, toasts ou tours para obter um efeito 21 Grams UX.
- Quando uma peça está genuinamente faltando (nenhum componente de estado vazio, nenhum desfazer), construa-a a partir dos primitivos existentes do projeto, seguindo sua estrutura de arquivos e nomenclatura. Diga isso no relatório.
- Decisões de produto continuam sendo do produto. 21 Grams UX não muda o que o produto faz, para quem é ou suas regras de negócio. Ela muda como as tarefas existentes são realizadas. Qualquer coisa que mudaria o escopo vai para o relatório como uma pergunta, não como uma correção.
Precedência: as palavras do usuário, depois os padrões estabelecidos do projeto e as regras do produto, depois as regras internas do 21 Grams UX.
O que está incluído
- A etapa de pesquisa de UX. Antes de projetar ou redesenhar um fluxo, analise o produto atual e três a cinco exemplos líderes do setor, um de cada vez, usando uma biblioteca de padrões como Mobbin quando estiver conectada. O processo completo está em
references/research.md. - As leis de UX. O conhecimento de onde vêm as regras, em
references/laws.md, citadas como A1, A2… por seção. A seção A são as leis principais: Hick's, Fitts's, Jakob's, Miller's, o Limiar Doherty, Tesler's e Postel's. Quando nenhuma regra cobrir um caso, raciocine a partir das leis. - As regras de UX. Regras numeradas em
references/rules.md, cada uma com a regra, como aplicá-la e o que sinalizar, além de uma lista de verificação rápida de auditoria. Escritas mobile-first e aplicadas também à web (navegação primária para "guia inferior", popover para "folha inferior" no desktop). - Regras de campo. Regras aprendidas em sessões de revisão reais em produtos construídos por IA e da pesquisa de UX em produtos líderes, em
references/field-rules.md, citadas como F1, F2…. Este arquivo cresce após cada sessão (veja "Cultivando as regras de campo"). - Regras internas por área em
rules/, um arquivo por área, cada um listando as leis, regras numeradas e regras de campo que pertencem a ela:
| Arquivo | Área |
|---|---|
navigation.md | Navegação e orientação |
forms.md | Formulários e entrada |
states.md | Estados vazio, carregamento, erro e sucesso |
feedback.md | Feedback e status do sistema |
onboarding.md | Integração e primeira execução |
destructive.md | Ações destrutivas e recuperação |
accessibility.md | Acessibilidade e teclado |
flows.md | Fluxos e duração da tarefa |
choice.md | Escolha e carga cognitiva |
As regras #1–5 estão reservadas e serão adicionadas em uma versão posterior. Até que uma área tenha regras, audite com base no julgamento geral de usabilidade e mencione isso no relatório.
Inegociáveis
- X fecha uma modal ou fluxo. Uma seta para a esquerda volta uma tela. (#6)
- Nunca uma tela em branco durante o carregamento: skeleton, spinner ou barra de progresso. (#7)
- Voltar para um feed restaura a posição exata da rolagem. (#8)
- Tocar na guia ativa retorna ao topo. (#9)
- A próxima página carrega antes que as pessoas cheguem ao final. (#10)
- Curtidas, seguir e salvar são otimistas, com reversão e uma mensagem em caso de falha. (#11)
- Rascunhos e entrada não finalizada são salvos automaticamente. (#12)
- Permissões são solicitadas quando o recurso é usado, nunca na inicialização. (#13)
- Ações rápidas abrem em uma folha inferior que desliza para baixo para dispensar. (#14)
- Notificações e links compartilhados abrem o conteúdo exato. (#15)
- Poucas escolhas por etapa com um padrão recomendado; o restante é revelado. (A1)
- A ação principal é grande e ao alcance; os alvos de toque são 44×44. (A2)
- Tarefas comuns usam o padrão comum. (A3)
- A informação é agrupada; nada precisa ser lembrado entre as etapas. (A4)
- Cada entrada é reconhecida imediatamente; esperas mais longas mostram progresso. (A5)
- O produto carrega a complexidade, não a pessoa. (A6)
- Aceite entrada confusa e retorne-a limpa, mas nunca afrouxe a segurança ou a integridade dos dados. (A7)
- Um controle por tarefa. (F1)
- Ações da tela agrupadas no canto superior direito, a principal no canto, nunca misturadas com seletores. (F2)
- Detalhes secundários sob demanda, nunca perdidos; nunca remova o único caminho acessível para eles. (F3, F5)
- Cada fato dito uma vez; nenhum número de versão, notas de design ou jargão interno na tela. (F6, F9)
- Quando uma interação muda, toda dica que a descreve também muda. (F8)
- Nova IU nunca afirma mais do que o escopo declarado do produto. (F10)
- Nenhuma etapa que repita a escolha que a abriu; uma opção significa apenas faça. (F13, F17)
- Uma seleção, uma barra de ferramentas contextual, que desaparece ao clicar fora. (F16)
- Tudo que pode ser adicionado pode ser removido, e uma exclusão mostra o que ela levará. (F18, F19)
- Atalhos são mostrados em tooltips e nunca usam teclas reservadas do navegador. (F20)
- Propostas de IA parecem provisórias, usam um único padrão de aceitar/rejeitar e aceitam instantaneamente. (F23)
- Integração: duas portas iguais, uma pergunta por tela com progresso, valor antes da conta, tours puláveis. (F28, F29, F32, F36)
- Dinheiro é honesto: um caminho gratuito real, testes com datas, upgrades no limite. (F35)
- Leitura e seleção acontecem em uma coluna estreita e centralizada; apenas o contexto da etapa e a ação permanecem fixos. (F37, F38)
- Dados faltantes dizem N/A, o texto é truncado e alinhado, e cada lista é verificada com volumes reais. (F43, F44, F45)
- Papéis mudam o ponto de partida, não o aplicativo; mobile e desktop compartilham os mesmos padrões. (F47, F50)
Fluxo de trabalho
- Faça o inventário (regra zero).
- Pesquise (
references/research.md). Para um novo fluxo, redesign ou integração, comece aqui: descubra o que está sendo projetado e para quem, analise o fluxo atual, recomende três a cinco exemplos líderes do setor e percorra-os um de cada vez com o usuário antes de mudar qualquer coisa. Pule isso apenas para pequenas correções em um fluxo existente. - Mapeie os fluxos. Liste as principais tarefas que uma pessoa vem fazer e, para cada uma, a rota através do produto: ponto de entrada, cada etapa, cada ramificação, o estado final. Anote de onde vêm os dados de cada etapa.
- Percorra cada fluxo no navegador, não apenas no código. Teste o caminho feliz, depois as bordas: nada ainda, rede lenta, uma solicitação com falha, entrada inválida, voltar, atualizar no meio do fluxo, apenas teclado, uma tela estreita.
- Audite antes de mudar qualquer coisa. Percorra as listas de verificação no final de
references/rules.md,references/laws.mdereferences/field-rules.md, e os arquivos de área. Liste os achados agrupados por área, número da regra e lei. Cada achado recebe o fluxo e a etapa, o arquivo e a linha, o que dá errado para a pessoa, a correção e em qual componente ou padrão existente a correção vai. Classifique-os: bloqueia a tarefa, retarda a tarefa, aresta áspera. - Mostre a auditoria ao usuário como uma lista curta e pergunte antes de aplicar mudanças amplas. Pequenas correções óbvias no escopo solicitado podem ser feitas diretamente.
- Aplique as correções nesta ordem: componentes e padrões compartilhados → fluxos → telas individuais. Mantenha os diffs com escopo e nas próprias convenções do projeto.
- Verifique percorrendo os fluxos novamente no navegador, incluindo os casos de borda da etapa 3. Capture antes e depois para cada etapa alterada.
- Relate o que mudou por fluxo e área, quais componentes foram tocados e as perguntas em aberto que são decisões de produto.
Cultivando as regras de campo
21 Grams UX aprende com o trabalho real. Quando o autor termina uma sessão de revisão em um produto construído por IA e pede para adicioná-la:
- Leia a conversa dessa sessão e liste cada mudança que o autor solicitou ou aceitou.
- Mantenha as mudanças de UX (fluxo, estrutura, posicionamento, estados, feedback, texto que guia as pessoas, caminhos de acessibilidade). Mudanças visuais (raio, cor, tipo, ícones, movimento) pertencem ao 21 Grams UI.
- Escreva cada uma como uma regra geral: a regra, como aplicá-la através dos próprios componentes do projeto e o que sinalizar. Nenhum nome de cliente, nome de produto ou conteúdo privado.
- Se uma regra refina uma existente, atualize essa regra em vez de adicionar uma nova.
- Adicione novas regras a
references/field-rules.mdsob um cabeçalho de sessão, continue a numeração F e liste-as nos arquivos de área corretos.