


Crie um app TypeScript para nativo e web seguindo as regras do repositório
Use ao criar ou alterar um app TypeScript que roda em nativo e web. A IA segue os scripts e a estrutura de pastas do repositório, reaproveita os componentes compartilhados, prepara os textos da tela para tradução e testa cada plataforma afetada antes de terminar.
Para usar estas regras de IA
## Rode testes, lint e builds pelos scripts do repositório
Trate o manifesto do pacote e os scripts do repositório como a fonte confiável para versões e comandos compatíveis. Prefira as APIs atuais que tenham suporte e substitua padrões legados ou obsoletos quando for seguro fazer isso no escopo afetado.
Use scripts do gerenciador de pacotes para:
- iniciar o servidor de desenvolvimento e cada plataforma compatível;
- executar testes unitários, lint, verificação de tipos e formatação;
- criar builds para a web e gerar projetos nativos.
Nunca invoque diretamente as ferramentas subjacentes de teste, lint, verificação de tipos ou formatação quando houver scripts do repositório. Os scripts podem fornecer configurações ou etapas preparatórias que os comandos diretos omitem.
Não execute comandos de extração ou compilação de localização quando a CI for responsável por essas tarefas. Adicione ou atualize strings traduzíveis no código-fonte e deixe que o fluxo automatizado agendado atualize os catálogos e as traduções em tempo de execução.
Antes de alterar o código, identifique as plataformas de destino, o script canônico de verificação e se os artefatos gerados são gerenciados localmente ou pela automação.
## Coloque novas telas e componentes na pasta certa
Coloque elementos compartilhados de UI que sejam independentes de plataforma em `components`. Coloque rotas de página completa em `screens`. Use `features` para recursos maiores que combinem contexto, acesso a dados, componentes e utilitários em várias telas.
Para uma tela complexa com componentes ou estado privados, crie um diretório para a tela e mantenha essas dependências no mesmo local. Não promova o código para uma pasta compartilhada até que mais de um consumidor precise dele.
Mantenha hooks de estado do servidor, preferências simples de UI, estado da sessão e persistência em módulos de estado bem definidos ou mantenha o estado específico de um recurso junto ao seu consumidor. Evite arquivos grandes que misturem responsabilidades sem relação entre si.
Use `lib` para utilitários reutilizáveis, clientes de API, formatadores e constantes que não pertençam a um recurso. Evite adicionar novos diretórios de código-fonte no nível superior quando o conteúdo já se encaixar em uma responsabilidade estabelecida.
Não adicione trabalho novo a diretórios legados de visualização. Preserve o código legado existente, a menos que a migração faça parte da tarefa, mas coloque telas, componentes e recursos novos na estrutura atual.
Use PascalCase para nomes de componentes e camelCase para arquivos, diretórios, variáveis e funções comuns. Um módulo substancial pode usar uma entrada `index.tsx` com componentes, hooks e utilitários no mesmo nível; mantenha um componente pequeno em um único arquivo.
Mantenha a documentação opcional de um recurso e seus testes junto a módulos maiores. Escreva comentários para explicar por que uma decisão existe, não o que o código já declara. Use blocos de documentação para declarações nomeadas, comentários em bloco para explicações com várias linhas e comentários de linha apenas para notas curtas.
## Monte a UI com o sistema de design e os componentes existentes
Use o sistema de design estabelecido antes de criar estilos brutos ou componentes duplicados. Combine átomos independentes do tema, átomos do tema e estilos brutos excepcionais nesta ordem:
1. átomos de flex e layout;
2. átomos de espaçamento;
3. átomos de tipografia;
4. cores e superfícies do tema;
5. estilos brutos com escopo restrito.
Use utilitários de estilo da plataforma para estilização condicional e hooks de pontos de interrupção para layouts responsivos. Mantenha as condições de plataforma dentro da composição de estilos, em vez de espalhá-las pela lógica do componente.
Antes de criar um controle, procure na biblioteca de componentes compartilhados um botão, uma caixa de diálogo, um menu, um campo de texto ou um elemento tipográfico básico adequado. Siga sua API composta e os usos canônicos existentes.
Para declarações de componentes:
- prefira a sintaxe abreviada de fragmentos, a menos que seja necessário um fragmento com chave;
- prefira declarações de função;
- desestruture as props na lista de parâmetros;
- use tipos explícitos de props em linha quando continuarem legíveis;
- forneça padrões razoáveis para props opcionais;
- mantenha componentes reutilizáveis independentes de plataforma sempre que possível.
Use campos de texto não controlados com `defaultValue` quando a arquitetura da plataforma tiver baixo desempenho com entradas controladas. Use valores controlados somente quando o comportamento realmente exigir.
O texto gerado por usuários pode conter emojis mesmo quando os exemplos não os incluírem. Ative o comportamento seguro para emojis do sistema tipográfico em conteúdo de usuários e omita-o apenas para texto estático conhecido.
## Prepare todo texto da tela para tradução
Envolva cada string voltada ao usuário com a macro ou o componente de tradução do projeto. Adicione comentários ou contexto para tradutores quando uma palavra tiver vários significados, como um substantivo e um verbo com a mesma grafia.
Use o ponto de entrada moderno de macros compatível com o framework de tradução. Dê um alias à função de tradução quando outro subsistema, como o de temas, já usar o mesmo nome curto de variável.
Use os recursos de pluralização do framework de tradução para contagens e seu formatador de datas para datas e horários. A formatação do framework deve ser executada novamente quando o idioma ativo mudar; a formatação direta de localidade frequentemente não faz isso.
Prefira pontuação Unicode tipograficamente correta no texto voltado ao usuário. Aplique de forma consistente as convenções de pontuação do projeto, incluindo aspas e espaçamento de travessões.
Não edite manualmente a saída de localidade gerada nem execute localmente tarefas de extração ou compilação que pertençam à CI. As alterações no código-fonte devem conter as mensagens encapsuladas e contexto suficiente para uma tradução precisa.
## Gerencie dados do servidor, navegação e arquivos por plataforma
Use a biblioteca estabelecida de consultas de estado do servidor para dados remotos e um estado baseado em contexto para preferências simples de UI. Exponha as preferências por meio de hooks pareados de leitura e atualização.
Crie chaves de consulta com o utilitário compartilhado de chaves e um objeto de argumentos. A raiz da chave deve corresponder ao nome do hook. Use nomes consistentes para hooks de consulta, hooks de mutação e utilitários de mutação que alterem somente o cache.
Escolha tempos de obsolescência entre as constantes compartilhadas. Para paginação por cursor, use uma consulta infinita, retorne o cursor da resposta como parâmetro da próxima página e achate as páginas apenas no limite de consumo.
Quando os dados persistidos de uma consulta mudarem de formato, incremente sua versão persistida para que os dados serializados obsoletos sejam descartados e buscados novamente.
Em caso de falhas de mutação:
- informe os usuários sobre falhas de rede esperadas sem duplicá-las nos registros de erros;
- trate explicitamente erros tipados de protocolo ou API;
- envie falhas inesperadas ao registro estruturado com uma mensagem segura.
Use parâmetros de rota tipados e o utilitário ou hook de navegação do projeto. Mantenha sincronizados a configuração, as definições e os tipos de rota.
Represente implementações de plataforma com sufixos de nome de arquivo como `.web`, `.native`, `.ios` e `.android`. Importe o caminho do módulo-base e permita que o bundler selecione a implementação. Nunca use imports condicionais em tempo de execução para escolher arquivos de plataforma.
Prefira agrupar variantes de plataforma por trás de um único diretório de módulo. Use sinalizadores de plataforma em tempo de execução apenas para comportamento, não para resolução de módulos. Use o alias de importação absoluta do repositório em vez de percorrer caminhos relativos profundos.
## Evite erros de tempo ao fechar diálogos e memoização desnecessária
Execute dentro do callback de fechamento do controle da caixa de diálogo toda ação que precise ocorrer depois que ela se fechar. Fechar primeiro e, logo em seguida, navegar, abrir outra sobreposição, atualizar o estado afetado ou invocar um callback do componente pai pode criar uma condição de corrida com a animação de fechamento.
A sequência obrigatória é:
1. chame o método de fechamento;
2. forneça um callback a esse método;
3. execute a navegação, a abertura de sobreposições, as atualizações de estado ou os callbacks do componente pai dentro dele.
Respeite componentes compostos específicos de cada plataforma. Um manipulador de caixa de diálogo ou item de contêiner de menu pode existir somente em plataformas nativas, enquanto um controle de fechamento ou divisor de menu pode existir somente na web. Teste as plataformas que executem cada ramo.
Quando a memoização automática do compilador estiver ativada, não adicione `useMemo` ou `useCallback` preventivamente. Use-os apenas para uma exigência concreta de estabilidade referencial, como uma dependência de efeito ou um contrato de biblioteca externa ao React.
Não sacrifique a legibilidade por uma otimização especulativa. Meça um problema real ou atenda a uma exigência explícita de estabilidade antes de adicionar memoização manual.
## Teste cada plataforma afetada antes de dar o trabalho por concluído
Antes da conclusão:
1. confirme que cada elemento interativo tenha um rótulo acessível e uma dica útil quando necessário;
2. confirme que todas as strings voltadas ao usuário estejam localizadas e que mensagens ambíguas incluam contexto;
3. verifique se os estilos usam de modo consistente átomos do sistema de design, valores do tema e utilitários da plataforma;
4. verifique se o estado do servidor, as preferências de UI e o estado da sessão usam os mecanismos pretendidos;
5. confirme que nenhum componente compartilhado existente tenha sido duplicado;
6. confirme que props e parâmetros de rota tenham tipos explícitos;
7. exponha identificadores de teste estáveis onde os testes de ponta a ponta precisarem deles;
8. execute os scripts do repositório para testes, lint, verificação de tipos e formatação;
9. teste todos os comportamentos nativos e web afetados.
Revise o diff em busca de novos usos de diretórios legados, imports condicionais de plataforma, edições diretas em arquivos de localização gerados, regressões entre entradas não controladas e controladas e condições de corrida após o fechamento de caixas de diálogo.
Relate qualquer plataforma ou script canônico que não tenha sido executado, incluindo o pré-requisito ausente. Não alegue conclusão multiplataforma com base em uma verificação de uma única plataforma.
