wasely/ui-max

UI Max

Priorize a usabilidade do produto sobre efeitos decorativos. Escolha o sistema coerente mais simples que atenda ao requisito; não acumule bibliotecas de componentes.

Comece pelo produto

Antes de alterar código:

1. Inspecione o framework, roteador, sistema CSS, biblioteca de componentes, bibliotecas de ícones e animações, stack de formulários, tokens de design, modo escuro e padrões estabelecidos.
2. Defina o objetivo do usuário, fluxo de trabalho principal, hierarquia de informações, ações primárias e secundárias, estados necessários, superfícies responsivas e comportamento de teclado.
3. Reutilize nesta ordem: componentes locais, primitivas de design-system existentes, shadcn/ui, Radix UI, 21st.dev, uma biblioteca de aprimoramento especializada, implementação personalizada.
4. Mantenha um sistema de UI estável existente. Nunca introduza um sistema completo concorrente por um componente atraente.

Escolha uma fundação

Para novas interfaces de produto React, use por padrão:

React + TypeScript + Tailwind CSS
shadcn/ui -> primitivas Radix UI
Ícones Lucide
Motion para React apenas onde útil
React Hook Form + Zod para formulários substanciais
TanStack Table apenas para comportamento avançado de tabela

Não force este stack em projetos com um sistema estabelecido ou em projetos Vue/Svelte. Use bibliotecas nativas do ecossistema nesses casos.

Classifique a superfície antes de selecionar acréscimos:

• UI de produto principal: shadcn/ui + Radix UI + Tailwind CSS.
• UI de produto de IA: adicione Cult UI apenas para padrões reais de fluxo de trabalho de IA; use Motion Primitives para transições comedidas.
• Página de marketing: use 21st.dev para estrutura, Magic UI seletivamente e Aceternity apenas para seções genuinamente de alto impacto.
• Aplicação densa em dados: adicione TanStack Table quando ordenação, filtragem, paginação, seleção, visibilidade, virtualização ou modelos de dados complexos justificarem.
• Micro-interação: use Motion Primitives ou Motion. Use UIverse apenas após revisão de acessibilidade e manutenibilidade.

Leia references/component-selection.md ao escolher, instalar ou obter bibliotecas/componentes, comparar alternativas ou pesquisar padrões visuais.

Implemente de forma coerente

Normalize cada componente reutilizado ou copiado para os seguintes itens do projeto:

• tokens de cor semânticos
• escalas de tipografia, espaçamento, raio e sombra
• família de ícones
• convenções de acessibilidade
• comportamento responsivo
• temas claro e escuro

Use tokens semânticos em vez de valores codificados espalhados. Mantenha controles relacionados próximos; separe seções não relacionadas; evite cards aninhados injustificados; use listas/tabelas para comparação e cards para itens heterogêneos acionáveis individualmente. Mantenha ações primárias óbvias e ações destrutivas longe de ações rotineiras.

Use uma fonte de interface e uma família de ícones, a menos que a identidade visual exija o contrário. Use movimento apenas para comunicar estado, hierarquia, continuidade, causa/efeito, progresso ou foco. Respeite prefers-reduced-motion.

Leia references/design-standards.md antes de implementação visual substancial, trabalho responsivo, design de estado, formulários, tabelas ou trabalho de acessibilidade.

Cubra estados reais

Para UI assíncrona ou orientada a dados, considere:

• carregamento inicial e atualização em segundo plano
• resultados vazios e nenhuma correspondência de pesquisa
• sucesso, aviso, erro e falha parcial
• estados desabilitado e offline
• permissões ou integrações ausentes
• dados desatualizados

Prefira skeletons quando a estrutura é conhecida. Faça com que erros digam o que falhou, por que quando conhecido, se o trabalho foi preservado e o que resolve o problema. Nunca use dados mock sem significado, análises falsas, atividade de agente fabricada ou controles não funcionais em um produto finalizado.

Limpe UI existente

Audite duplicação, espaçamento, cores, tipografia, variantes, ícones, layout aninhado, utilitários repetidos, responsividade, acessibilidade, código/dependências não utilizados, excesso de animação e estados ausentes.

Consolide primitivas repetidas ou que carregam comportamento, como botões, inputs, badges de status, diálogos, menus, abas, cabeçalhos de página, estados vazio/erro/carregamento, itens de barra lateral e linhas de projeto. Não abstraia marcação única sem um benefício de consistência, lógica, reuso ou teste.

Tokenize valores repetidos. Remova wrappers desnecessários, cards aninhados, divisores decorativos, rótulos repetidos, ações/status redundantes, descrições excessivas e movimento injustificado.

Valide a saída renderizada

Verifique:

• HTML semântico, nomes acessíveis, rótulos, ordem de tabulação lógica, operação por teclado, foco de diálogo, foco visível e contraste
• estados de carregamento, vazio, desabilitado, erro, sucesso, texto longo e confirmação destrutiva
• layouts estreitos e largos sem cortes, tabelas ilegíveis, deslocamento de layout ou estouro horizontal
• comportamento de movimento reduzido, temas claro/escuro e navegação responsiva
• formatador, linter, TypeScript, testes, build de produção e saída do console

Teste em 320, 375, 768, 1024, 1280 e 1440 px quando relevante. Para extensões de navegador, teste também larguras de popup em torno de 320–420 px e painéis laterais em torno de 320–600 px.

Inspecione a UI realmente renderizada em larguras estreitas e largas antes de reivindicar conclusão. Use um loop de captura de tela ou o fluxo de trabalho de validação visual existente do projeto; confirme superfícies específicas da plataforma no alvo real.

Relate trabalho de UI

Quando solicitado a projetar ou reconstruir uma página, forneça seções concisas para:

1. Interpretação do produto: objetivo, fluxo principal, informações-chave, ação principal.
2. Plano de componentes: estrutura, componentes reutilizáveis, fundação, acréscimos especializados, comportamento responsivo, estados importantes.
3. Implementação: código funcional no stack existente.
4. Validação: acessibilidade, responsividade, estados, comportamento de teclado, consistência de tokens de design e revisão visual renderizada.

Não retorne um catálogo de bibliotecas a menos que o usuário peça opções.