oil-oil/oil-frontend

Oil Frontend

Primeiro, identifique a tarefa do usuário, os objetos de negócio e a origem dos dados; em seguida, remova conteúdo inválido e estabeleça a informação, estado, responsabilidade de código e implementação compartilhada corretos.

Sempre Observe

• Parta da tarefa real do usuário, dos objetos de negócio e do resultado final; mantenha apenas as informações visíveis que ajudem a identificar, comparar, julgar, operar ou compreender o resultado.
• Cada intenção do usuário é executada uma vez; a ação deve produzir um resultado real; os limites de dados, operação, ocupação e submissão devem ser consistentes; em caso de falha, preserve o objeto atual, a posição e o conteúdo já inserido.
• Para tarefas comuns, siga o conhecimento existente do usuário; a navegação de recursos é exibida por padrão, a edição deve ser explicitamente acionada, e os formulários coletam apenas os dados necessários para a tarefa atual e pertencentes ao objeto atual.
• Ícones, ênfases e tamanhos fixos devem expressar significados estáveis; não use decoração genérica de IA, bordas de destaque sem significado ou tamanhos que criam hierarquia apenas para a instância atual.
• Ajustes visuais primeiro reutilizem as variáveis de design, componentes e densidade existentes do projeto; depois tratem hierarquia, espaçamento, tipografia, superfícies e feedback; use valores de fallback das regras de referência somente quando não houver padrão do projeto; não expanda valores de fallback em um novo sistema de design.
• Mantenha apenas uma única fonte da verdade para os mesmos dados de negócio e para o mesmo significado; priorize a correção do fluxo de dados, layout pai e implementação compartilhada; não aplique remendos repetidos nos locais de uso das páginas.
• Organize componentes, Hooks, funções, tipos, estilos e testes por responsabilidade de negócio; coloque o código de um único módulo próximo a ele; mova para a camada compartilhada apenas quando for estável e reutilizado entre módulos.
• Ao encontrar lógica complexa, verifique primeiro as capacidades e bibliotecas maduras existentes no projeto; quando a dependência existente não for adequada, pode-se introduzir uma nova biblioteca bem mantida e compatível com o projeto; não implemente manualmente capacidades principais já cobertas por soluções maduras. Para lógica simples, implemente diretamente; não introduza novas dependências para pouco código.
• O histórico do projeto não é prova de correção; padrões incorretos devem ser substituídos e, após a migração dos locais de uso relacionados, o código antigo, fallback, lógica legada e estados obsoletos devem ser excluídos.

Ordem de Leitura dos Arquivos de Referência

1. Após o acionamento, leia apenas este arquivo para esclarecer a tarefa, o objeto e o escopo da alteração; não leia os arquivos de referência previamente.
2. Se a tarefa não envolver interface visível ao usuário, estado e fluxo de dados front-end, implementação de componentes ou organização de código front-end, pare de usar este Skill.
3. Primeiro, selecione uma regra principal com base no resultado que o usuário deseja alterar; não selecione regras com base no tipo de arquivo ou em palavras-chave de CSS ou animação que aparecem no código.
4. Para alterações locais simples, leia apenas uma regra principal; adicione uma segunda regra apenas se a tarefa realmente contiver um segundo problema independente. Apenas uma revisão abrangente entre páginas pode ler três regras, nunca mais.
5. Não continue lendo regras devido a palavras-chave que aparecem, links dentro do arquivo ou "por segurança". Quando os sintomas visuais forem causados por dados, estado ou layout pai, leia a regra que realmente trata a causa raiz; não carregue regras visuais adicionais.

Tarefa Atual	Regra Principal	Complementar Apenas Nestes Casos
"Parece errado", refinamento visual, hierarquia, espaçamento, tipografia, cor, borda arredondada, borda, sombra ou ícone	Engenharia Visual	Leia Componentes e Organização de Código quando precisar modificar Tokens compartilhados, estilos padrão de componentes ou variantes; mude para Viewport e Diálogos como regra principal ao alterar estrutura de colunas, rolagem ou responsividade
Animação, transição, microinteração, expandir/recolher, feedback de arrastar, efeito de rolagem ou travamento	Movimento e Performance	Leia Engenharia Visual quando a animação servir como feedback de ação ou hierarquia visual; mude para Estado e Carregamento como regra principal quando a causa raiz for estado assíncrono
Limite de módulo, componente, Hook, função, tipo, responsabilidade de estilo, estilo compartilhado, organização CSS ou implementação compartilhada	Componentes e Organização de Código	Leia Automação quando precisar adicionar novas verificações
Adicionar ou alterar texto, significado de ação, ícone, feedback de clique ou ênfase visual	Informação e Ação	Leia Reconhecimento de Recurso quando envolver identidade de objeto, imagem ou seletor

Dados, estado e layout continuam a ser selecionados com base no resultado:

Tarefa Atual	Regra Principal	Complementar Apenas Nestes Casos
Lista, cartão, detalhe, tabela ou operação em lote	Coleção e Detalhe	Leia Reconhecimento de Recurso quando envolver identidade de recurso; leia Interação e Edição quando envolver edição
Formulário, seleção, edição ou fluxo de trabalho em várias etapas	Interação e Edição	Leia Escopo de Dados e Operação quando envolver escopo de salvamento e continuidade do fluxo
Resultado de consulta, paginação, conjunto candidato, escopo de salvamento, escopo em lote ou responsabilidade do resultado da requisição	Escopo de Dados e Operação	Leia Estado e Carregamento quando alterar simultaneamente a apresentação de loading, refreshing, empty, error ou processing
loading, refreshing, empty, filtered-empty, error, queued, processing ou skeleton	Estado e Carregamento	Leia Escopo de Dados e Operação quando envolver instantâneo de consulta, escopo de operação ou responsabilidade do resultado de salvamento
Alterar tamanho de página, colunas, rolagem, estrutura de diálogo ou comportamento responsivo	Viewport e Diálogos	Leia Overlay quando envolver camadas flutuantes acionadas por trigger, como dropdown, menu ou dica de ferramenta

Não dispare leituras adicionais nos seguintes casos:

• A presença de Tailwind, CSS, transition ou bibliotecas de animação no código não significa que a tarefa seja visual ou de animação.
• Ao alterar cor, espaçamento, borda, sombra, tipografia ou outros atributos visíveis, use Engenharia Visual como regra principal; complemente com a regra de Componentes e Organização de Código apenas quando a tarefa também exigir ajuste na responsabilidade do estilo, forma de compartilhamento ou limite do módulo.
• Não leia a regra de Engenharia Visual ao corrigir apenas nomes de variáveis de cor, nomes de classe, tipos ou erros de importação que não alteram o resultado visual.
• Não leia a regra de Movimento ao alterar apenas estado de negócio, ligação de eventos ou fonte de dados para uma animação existente, sem alterar o modo de movimento ou desempenho.
• Não leia a regra de Informação e Ação ao mover apenas controles existentes, sem alterar texto, significado da ação ou feedback.
• Não leia a regra de Viewport e Diálogos ao ajustar apenas a responsabilidade de contêiner pai comum, sem alterar tamanho, rolagem, diálogo ou comportamento responsivo.
• Os links nos arquivos de referência indicam apenas a localização das regras relacionadas; não significam que devem ser lidos obrigatoriamente.

Glossário Rápido

As palavras principais neste arquivo e nas regras de referência devem ser entendidas conforme as definições abaixo:

• Identidade do recurso: A combinação mínima de informações que permite ao usuário reconhecer "qual objeto é este" — imagem + nome + um campo distintivo. Exemplo: a lista de membros exibe "avatar + nome + departamento", não "uuid + etiqueta de tipo".
• Pseudo-operação: Um controle que parece utilizável mas não produz resultado real. Exemplo: clicar em "salvar" altera apenas o state local, que é perdido ao atualizar; botão de excluir permanentemente desabilitado como placeholder.
• Remendo visual em um único componente: Aplicar estilo apenas a este componente no local de uso do componente compartilhado. Exemplo: <Dialog className="h-[640px]">, sobrescrita com !important, seletor de página específico para alterar o interior do componente. A abordagem correta é corrigir o próprio componente compartilhado ou adicionar uma variante de componente nomeada por propósito.
• Variante de componente nomeada por propósito: Nomear com base no motivo da diferença. Exemplo: variant="destructive", size="compact" são válidos; variant="blue", variant="userListPage" são inválidos.
• Ação principal: A única operação na página, diálogo ou área de operação que completa a tarefa principal. No máximo um botão de alta ênfase por área.
• Limite de submissão: Quando uma modificação realmente entra em vigor — imediatamente, salvamento automático, envio unificado explícito ou apenas visualização temporária.
• Escopo de ocupação: A menor área necessária para evitar operações duplicadas enquanto uma requisição está em andamento. Para requisições individuais, bloqueie apenas o item; não use uma máscara em toda a página.
• Instantâneo de consulta submetido: As condições de consulta, lista, número total de resultados e informações de paginação determinados conjuntamente pela mesma resposta. Até que uma nova consulta seja concluída, o instantâneo antigo ainda pertence às condições antigas.
• Tarefa em lote do mesmo tipo: Tarefa que preenche repetidamente o mesmo campo para um lote de objetos do mesmo tipo, como agendamento em lote, alteração de preço em lote.
• Planilha editável: Tabela que mantém várias linhas em estado de edição contínua para tarefas em lote do mesmo tipo. Em contraste, a lista de recursos é exibida por padrão e a edição deve ser explicitamente acionada.

Ordem de Decisão

Responda em ordem antes de fazer alterações.

Tarefa e Objeto:

1. Qual tarefa o usuário deseja concluir atualmente e qual resultado indica conclusão?
2. Qual objeto principal a página gerencia e a quem pertencem os campos?
3. A ação atual é navegação, comparação, seleção ou edição? A estrutura e terminologia familiares ao usuário são seguidas?

Dados e Escopo:

4. Os dados vêm de uma coleção completa, da coleção visível atual ou de resultados de pesquisa?
5. A operação, o estado de ocupação e o limite de submissão afetam qual escopo? As condições de consulta remota e a lista atual já pertencem ao mesmo resultado submetido?
6. Em quais informações o usuário confia para distinguir objetos adjacentes?
7. É possível remover texto, etapas, confirmações, entradas repetidas ou campos que o sistema já conhece?
8. Quais informações pertencem à coleção e quais pertencem apenas ao detalhe?

Estrutura e Estado:

9. Qual é a ação principal da página, diálogo ou área de operação atual?
10. Quem é responsável pela primeira tela, pelo contêiner de rolagem e pelos limites dos overlays?
11. Como loading, empty, filtered-empty, queued, processing, error e ready são mutuamente exclusivos?

Visual e Movimento, responda apenas quando a tarefa exigir alteração:

12. Quais Tokens, componentes e páginas adjacentes o projeto atual usa para definir hierarquia, densidade e linguagem de movimento? Qual atributo visível é realmente inconsistente?
13. A animação serve para feedback de estado, explicar relação espacial ou decoração? É possível concluir apenas com transform, opacity ou capacidades de componentes existentes?

Ponto de Aterrissagem:

14. Já existe um módulo, componente, Hook, função, tipo, variável de design unificada ou estilo com responsabilidade correta? Qual fonte de dados, layout pai ou implementação compartilhada deve ser modificado?

Quando não for possível responder claramente, pare de adicionar elementos de interface: faça ao usuário as 1–2 perguntas mais críticas; se não puder perguntar, implemente no menor escopo verificável e declare as suposições feitas na saída.

Fluxo de Execução

1. Restaurar os Fatos

• Pesquise módulos, componentes, Hooks, funções, tipos, variáveis de design unificadas e estilos existentes no projeto; confirme se o mesmo significado já possui uma implementação correta.
• Encontre todas as páginas e componentes que usam componentes compartilhados, bem como outras entradas para os mesmos dados.
• A revisão deve fornecer apenas evidências e sugestões; implemente apenas quando o usuário solicitar modificação.

2. Esclarecer o Escopo

• Esclareça o objeto principal, os proprietários dos campos, a coleção de dados, o escopo da operação, o escopo de ocupação e o limite de submissão.
• Diferencie problemas de estrutura de página, comportamento padrão de componente, erro de uso de página e erro de fluxo de dados.
• Para problemas visuais, registre apenas as diferenças que possam apontar o elemento específico, atributo, justificativa existente e local do código; quando não for possível determinar o valor correto, use primeiro os Tokens existentes do projeto ou componentes semelhantes adjacentes; não invente valores precisos com base em estética.

3. Primeiro, Excluir

• Remova conteúdo que não afeta o julgamento, estados duplicados, entradas duplicadas, confirmações duplicadas e remendos visuais aplicados a um único componente.
• Remova pseudo-operações que não têm mudança de estado real ou não podem realmente salvar dados.
• Remova componentes antigos, funções antigas, tipos antigos, estados antigos, fallback, lógica legada, estilos antigos e referências obsoletas que já foram substituídos por novas implementações.

4. Escolher a Estrutura

• Primeiro, verifique o uso estabelecido de páginas de tarefas semelhantes e componentes de contêiner compartilhados no projeto; reutilize apenas se o padrão existente estiver em conformidade com estas especificações; caso contrário, reescolha a estrutura com base na tarefa real.
• Com base na tarefa de navegação, comparação, seleção, configuração em lote ou edição aprofundada, escolha entre lista, tabela, planilha, seletor, diálogo ou área de trabalho completa.
• Faça a lista ser responsável por identificação e comparação; o detalhe, pelo conteúdo completo; e o editor, pela modificação.
• Processe os ajustes visuais na ordem: "hierarquia da informação → espaço e alinhamento → tipografia → superfície → estado do controle → movimento"; pare quando a camada anterior já resolver o problema; não continue empilhando decorações.

5. Corrigir o Local Realmente Errado

• Priorize a correção do escopo de dados, escopo de operação, layout pai, comportamento padrão de componentes compartilhados e variantes de componente com significado estável.
• Use componentes compartilhados para identidades de recurso que se repetem, menus, overlays, carregamento, diálogos e barras de ação.
• Abstraia apenas quando a responsabilidade, entrada/saída e comportamento se repetirem de forma estável; não copie componentes devido a semelhanças estruturais locais, nem use muitas flags de página para criar componentes universais.
• Quando o próprio componente compartilhado, função, estilo ou fluxo de dados existente estiver errado, corrija ou substitua diretamente a implementação compartilhada realmente errada dentro do escopo autorizado e trate todos os locais de uso afetados; não continue adicionando implementações erradas para compatibilidade com o histórico.
• Se não for possível concluir toda a correção no escopo atual, pare de expandir o padrão antigo, relate claramente quantos locais de uso antigos restam e até onde esta alteração chegou; não alegue que já foi unificado.
• Ao corrigir problemas que podem ser detectados repetidamente, julgue se o projeto realmente precisa de novas regras de lint, teste ou verificação; se necessário, leia complementarmente Automação conforme a tabela de roteamento e inclua no número de regras complementares. Para pequenas alterações, não construa automação prévia para isso.
• Não modifique áreas não relacionadas.

6. Verificar

• Execute as verificações de tipo, Lint, testes ou build existentes do projeto que estejam relacionadas à alteração.
• Para alterações locais simples, verifique apenas o local da modificação, o comportamento direto e os locais de uso mais próximos; não expanda para a matriz de estado completa.
• Quando a alteração envolver componentes compartilhados, escopo de dados, estado assíncrono, fluxo de formulário, rolagem, responsividade ou várias páginas, verifique os estados afetados, o escopo de dados, as viewports representativas e todos os locais de uso.
• Para alterações visuais, verifique o conteúdo real, os principais estados e as viewports afetadas; para alterações de movimento, verifique apenas por tipo os comportamentos de interrupção, acionamento repetido, saída, desmontagem ou rolagem aplicáveis. Use gravação de performance apenas para movimentos complexos ou travamentos reais; não transforme cada transição em uma tarefa especializada de performance.
• Relate apenas os itens verificados, os itens não verificados e o motivo do bloqueio.

Autoverificação Independente

Dispare uma autoverificação independente sem contexto de histórico apenas quando a revisão front-end envolver várias páginas, todos os locais de uso de componentes compartilhados, várias viewports ou estados, ou ajuste de regras em grande escala. Para páginas únicas, componentes únicos, capturas de tela únicas e diferenças locais, o Agente principal faz a verificação diretamente.

A autoverificação independente recebe apenas o objeto de verificação, o escopo e oil-frontend; não recebe histórico de conversa, conclusões existentes, suposições do problema, respostas esperadas ou planos de correção.

Requisitos de Saída

Primeiro dê a conclusão, depois as evidências. Produza apenas:

1. O problema específico;
2. O conteúdo que deve ser excluído;
3. A informação, ação e estrutura espacial corretas;
4. O módulo, componente compartilhado ou fluxo de dados que deve ser modificado;
5. Itens verificados e não verificados.

É proibido usar descrições que não orientam a implementação, como "melhorar a experiência", "mais moderno", "mais intuitivo".

Não expanda ativamente para uma auditoria especializada de acessibilidade. Ao implementar UI, continue usando elementos de interação nativos; não quebre o foco, teclado, rótulos e comportamento ARIA existentes do projeto; realize verificações apenas quando o usuário solicitar explicitamente ou quando a alteração atual tornar a tarefa impossível de ser concluída.