# Rules — Tenda Components Regras obrigatórias ao usar os componentes deste design system. --- ## Ícones - **Nunca** passe ícones como `children` de um componente. - Ícones só devem ser passados via props dedicadas (`iconBefore`, `iconAfter`, `iconLeft`, `iconRight`, `icon`, `leftIcon`, `rightIcon`). - Se o componente não possui nenhuma dessas props, **não insira ícones**. - Consulte `manifest.json` para verificar quais props de ícone cada componente aceita. --- ## Children - Só passe `children` em componentes que explicitamente declaram essa prop. - Não use `children` para passar ícones, imagens ou elementos visuais decorativos — use as props corretas. --- ## Props obrigatórias - Sempre forneça todas as props marcadas como `required: true` no `manifest.json`. - Nunca omita callbacks obrigatórios como `onChange`, `onOpenChange` ou `onClick`. --- ## Variantes e tamanhos - Use apenas os valores de `variant`, `type`, `size` e `shape` listados no `manifest.json`. - Não invente valores — o componente ignora ou quebra com valores inválidos. --- ## Eventos - Callbacks de mudança de estado (`onChange`, `onOpenChange`, `onPageChange`, etc.) devem sempre ser fornecidos quando o componente é controlado. - Não deixe componentes controlados sem handler — isso congela a UI. --- ## Componentes controlados vs. não controlados - Ao usar `value`, sempre forneça o `onChange` correspondente. - Para comportamento não controlado, use `defaultValue` quando disponível em vez de omitir o `onChange`. --- ## Imports - Importe sempre de `@tenda/components` (ou do caminho correto do pacote). - Não importe de caminhos internos do pacote como `@tenda/components/dist/...`. --- ## Accordion - Comum em FAQs e páginas de produtos, recomendado para grandes volumes de conteúdo. - Permite apresentar o conteúdo de forma gradual, de acordo com o desejo e necessidade do usuário, sem sobrecarregá-lo com excesso de informações. - Encurta interfaces ao comprimir o conteúdo em tópicos — mas informações cruciais para a compreensão do usuário não devem ser ocultadas. --- ## AlertBanner - Indicado para mensagens importantes e prioritárias que dizem respeito à aplicação como um todo. - Mensagens de feedback relacionadas a fluxos específicos devem usar outros componentes, como `Toast`. - Use com parcimônia — exiba apenas um alerta por vez, hierarquizado conforme a prioridade definida pela regra de negócio. --- ## Avatar - Ideal para atribuir vínculo ou crédito a informações presentes na interface. - Usos comuns: exibir o usuário logado, associar dados à imagem de um usuário ou indicar disponibilidade em um chat. --- ## Badge - Ideal para atribuir informações adicionais a componentes da interface, como atividades pendentes ou status de disponibilidade. - Permite comunicar algo sem que o usuário precise acessar áreas dedicadas da aplicação. - Usos comuns: quantidade de itens no carrinho, mensagens não lidas, seções novas, status de disponibilidade junto a avatares. - É um elemento **não interativo** que comunica o status de uma informação dinâmica. - Não confundir com `Tag`: Badge indica status dinâmico; Tag categoriza informações com texto/ícone e pode ser interativa (selecionável, removível). - Não possui suporte a ícones nem `children`. Use apenas `variant`, `type`, `count`, `size` e `maxDigits`. --- ## BottomNavigation - Indicada para aplicações **mobile**, permitindo fácil acesso às 3 a 5 áreas de maior interesse do usuário. - Ideal para evitar esconder funcionalidades importantes em menus hambúrguer. - Para aplicações **web**, prefira um menu de topo com esse objetivo. - Deve estar sempre visível ou, em interfaces com rolagem infinita, ser ocultada ao rolar para baixo e reexibida ao rolar para cima. --- ## Breadcrumbs - Indicados para hierarquias multiníveis, como gerenciadores de conteúdo e e-commerces. - Não recomendado para navegações simples de 1 a 2 níveis. - Não deve substituir estruturas de navegação como menus. --- ## Button - Buttons são indicados para executar ações, fazer escolhas e mover-se pelo fluxo de navegação. - Use variantes diversificadas para criar hierarquia visual e orientar o usuário sobre prioridades. A ordem de referência é: **Accent > Primary > Secondary** e **Solid > Outline > Ghost**. - Buttons realizam navegação dentro de uma mesma jornada de usuário, respeitando sua cadência. - Não use Button para apontar para páginas ou fluxos externos — nesses casos, use `Link`. - **Nunca** passe ícones dentro de `children`. Use sempre `iconBefore` ou `iconAfter` para inserir ícones no Button. --- ## Carousel - Ideal para informações não essenciais, exibidas momentaneamente ou conforme o desejo do usuário. - Eficaz para dar destaque a conteúdos, mas a rotação dos slides não garante que todos serão acessados. - A maioria dos usuários não visualiza todos os itens de um Carousel — projete a experiência considerando que apenas o primeiro slide costuma ser visto. - Não use Carousel para conteúdos críticos que o usuário precisa obrigatoriamente visualizar. --- ## DateSelector - O tipo de `value` e `onChange` depende do `mode` (`single`, `multiple`, `range`). - No modo `range`, o value é `{ from?: Date; to?: Date }`. --- ## EmptyState - Ideal para quando elementos de interface — tabelas, gráficos, listas e afins — não possuem nada para apresentar. - Evita que o usuário confunda ausência de conteúdo com erro ou carregamento. - Muito presente em jornadas de onboarding, após conclusão de tarefas ou quando buscas e filtros não retornam resultados. - Sempre comunique ao usuário o que ocorreu e forneça opções para prosseguir a jornada (`primaryAction`, `secondaryAction`). --- ## Link - Links estão relacionados à navegação, permitindo acesso a páginas e conteúdos que ocorrem de forma independente à jornada em curso. - Podem aparecer em meio a parágrafos e ter textos mais longos. - Podem ser usados como âncoras para outras seções dentro de uma mesma página. - Não use Link para executar ações ou navegar dentro de um fluxo de usuário — nesses casos, use `Button`. --- ## Pagination - O conteúdo a ser exibido deve determinar se haverá ou não paginação. - Quando houver, a interface pode utilizar `Pagination` ou recursos como scroll infinito — com carregamento automático ou um `Button` de "Carregar mais". - `Pagination` é mais adequada quando o usuário possui um objetivo claro, pois oferece maior controle e navegação com critérios definidos. - Scroll infinito é mais adequado para conteúdos exploratórios, sem necessidade de uma finalidade específica, como navegar em uma rede social. --- ## ProgressBar - Ideal para operações de duração estendida, geralmente superiores a 2 segundos, enquanto o sistema realiza uma tarefa. - Atua como mediador de transparência em operações de infraestrutura como instalações de software, sincronização de banco de dados ou submissão de formulários. - O processamento pode ser quantificável (ex: download de 0 a 100%) — use `value` e `max` — ou indeterminado quando a duração é desconhecida — use `indeterminate="yes"`. --- ## ProgressIndicator - Ideal para fluxos complexos que possam ser segmentados e sequenciados logicamente em um número definido de etapas (entre 3 e 7). - Deve estar posicionado com destaque na interface — no topo ou nas laterais — para contextualizar o usuário sobre seu progresso. - Não recomendado para processos muito curtos (2 etapas), onde botões de Avançar e Retornar já cumprem a função de navegação. - Não é ideal para processos dinâmicos cujas etapas mudam conforme o progresso, pois pode confundir o usuário. --- ## Select - Para seleção múltipla, use `multiple={true}` — não crie vários `