Uso de Componentes

Convencao de Nomenclatura

Todas as classes do CANTA DS usam o prefixo .canta- para evitar conflitos com outros frameworks. A metodologia BEM (Block, Element, Modifier) garante previsibilidade e organizacao.

Tipo	Padrao	Exemplo	Descricao
Block	`.canta-[bloco]`	`.canta-btn`	Componente independente e reutilizavel
Element	`.canta-[bloco]__[elemento]`	`.canta-btn__icon`	Parte interna que depende do bloco
Modifier	`.canta-[bloco]--[modificador]`	`.canta-btn--primary`	Variacao de aparencia ou estado
Element + Modifier	`.canta-[bloco]__[el]--[mod]`	`.canta-card__title--lg`	Variacao de um elemento interno

Combinando Classes

Componentes sao construidos combinando a classe base (bloco) com modificadores. A classe base e sempre obrigatoria.

<!-- Base + variante + tamanho -->
<button class="canta-btn canta-btn--primary canta-btn--lg">
  Salvar
</button>

<!-- Base + variante + estado -->
<button class="canta-btn canta-btn--danger canta-btn--loading">
  Excluindo...
</button>

<!-- Card com elementos internos -->
<div class="canta-card">
  <div class="canta-card__header">Titulo</div>
  <div class="canta-card__body">Conteudo</div>
  <div class="canta-card__footer">Acoes</div>
</div>

<!-- ERRADO: modificador sem classe base -->
<button class="canta-btn--primary">Salvar</button>

<!-- ERRADO: misturar blocos diferentes -->
<button class="canta-btn canta-card--primary">Salvar</button>

<!-- ERRADO: classe sem prefixo canta- -->
<button class="btn btn-primary">Salvar</button>

Uso de Icones

O CANTA DS usa Material Symbols Rounded do Google Fonts. Os icones sao inseridos como texto dentro de um <span> com a classe material-symbols-rounded.

<!-- Icone + texto -->
<button class="canta-btn canta-btn--primary">
  <span class="material-symbols-rounded">add</span>
  Novo Item
</button>

<!-- Apenas icone -->
<button class="canta-btn canta-btn--primary canta-btn--icon-only">
  <span class="material-symbols-rounded">settings</span>
</button>

<!-- Icone em alerta -->
<div class="canta-alert canta-alert--success">
  <span class="material-symbols-rounded">check_circle</span>
  Operacao realizada com sucesso!
</div>

Catalogo completo de icones disponivel em Google Material Symbols. Use sempre a variante Rounded.

Responsividade

O CANTA DS e mobile-first. Os breakpoints seguem o padrao progressivo. Use as classes utilitarias ou os mixins SCSS para adaptar layouts.

Breakpoint	Largura	Dispositivo	Mixin SCSS
`sm`	≥ 576px	Mobile landscape	`@include media-up(sm)`
`md`	≥ 768px	Tablet	`@include media-up(md)`
`lg`	≥ 1024px	Desktop	`@include media-up(lg)`
`xl`	≥ 1280px	Desktop largo	`@include media-up(xl)`
`xxl`	≥ 1536px	Telas grandes	`@include media-up(xxl)`

// Mobile-first: estilos base para mobile
.meu-componente {
  padding: 16px;
  flex-direction: column;

  // Tablet: 2 colunas
  @include media-up(md) {
    flex-direction: row;
    padding: 24px;
  }

  // Desktop: mais espaco
  @include media-up(lg) {
    padding: 32px;
    max-width: 1200px;
  }
}

Dark Mode

O dark mode e ativado adicionando o atributo data-theme="dark" no elemento <html>. Todos os tokens de cor se adaptam automaticamente via CSS custom properties.

<!-- Light (padrao) -->
<html lang="pt-BR">

<!-- Dark mode -->
<html lang="pt-BR" data-theme="dark">

function toggleTheme() {
  const html = document.documentElement;
  const current = html.getAttribute('data-theme');
  const next = current === 'dark' ? 'light' : 'dark';
  html.setAttribute('data-theme', next);
  localStorage.setItem('canta-ds-theme', next);
}

// Restaurar preferencia salva
(function() {
  const saved = localStorage.getItem('canta-ds-theme');
  if (saved) {
    document.documentElement.setAttribute('data-theme', saved);
  }
})();

// Os tokens ja se adaptam automaticamente:
.meu-componente {
  background: var(--canta-color-surface);    // branco no light, escuro no dark
  color: var(--canta-color-text);            // preto no light, branco no dark
  border-color: var(--canta-color-border);   // cinza adaptativo
}

Acessibilidade

O CANTA DS segue as diretrizes WCAG 2.1 nivel AA. Todos os componentes incluem suporte a navegacao por teclado, leitores de tela e contraste adequado.

Recurso	Implementacao
Focus visible	Todos os interativos tem outline visivel via `:focus-visible`, anel azul de 2px
ARIA labels	Botoes icon-only devem ter `aria-label`; modais usam `aria-modal` e `role="dialog"`
HTML semantico	Use `<button>` para acoes, `<a>` para navegacao, `<nav>` para menus
Contraste	Todas as combinacoes de texto/fundo atendem ratio minimo de 4.5:1
Teclado	Tab para navegar, Enter/Space para ativar, Escape para fechar modais
Reduced motion	Animacoes desabilitadas quando `prefers-reduced-motion: reduce` ativo

<!-- Botao icon-only com aria-label -->
<button class="canta-btn canta-btn--primary canta-btn--icon-only"
        aria-label="Configuracoes">
  <span class="material-symbols-rounded">settings</span>
</button>

<!-- Modal com atributos ARIA -->
<div class="canta-modal" role="dialog" aria-modal="true"
     aria-labelledby="modal-titulo">
  <div class="canta-modal__header">
    <h2 id="modal-titulo">Confirmar acao</h2>
  </div>
  <div class="canta-modal__body">...</div>
</div>

<!-- Alerta com role -->
<div class="canta-alert canta-alert--error" role="alert">
  Erro ao salvar os dados.
</div>

<!-- Navegacao semantica -->
<nav aria-label="Menu principal">
  <a href="/dashboard">Dashboard</a>
  <a href="/relatorios">Relatorios</a>
</nav>