Clarus CSS

Um framework CSS híbrido — componentes prontos e classes utilitárias atômicas na mesma folha de estilo, com zero dependências em tempo de execução.

Instalação · Por que Clarus CSS · Componentes · Documentação

Clarus CSS é um framework CSS open source construído com HTML, CSS e JavaScript nativo. Nasceu do uso recorrente do autor em projetos pessoais e profissionais, e é distribuído publicamente como produto para qualquer desenvolvedor que precise construir interfaces consistentes sem carregar React, Vue, Angular, jQuery ou qualquer outra dependência de runtime.

Status: 1.0.0, primeira versão estável. Base completa (monorepo, @layer, tokens OKLCH, layout, grid, utilitários, formulários com validação visual) mais um catálogo de mais de 45 componentes — dos elementos de conteúdo e navegação aos interativos avançados (Combobox, Datepicker, DataTable, Command Palette, Tree View e mais), todos com dark mode nativo, suporte a múltiplas marcas (data-brand) e uma API JavaScript consistente com tipos TypeScript (.d.ts) inclusos. Qualidade é gate de CI, não promessa: todo componente passa por regressão visual (Playwright), auditoria de acessibilidade automatizada (axe-core, WCAG 2.1 A/AA), checagem de contraste e budget de tamanho a cada PR. O catálogo atual está em Componentes; o histórico por versão, no CHANGELOG.md.

Este README é a visão geral do projeto. Para aprender a usar cada recurso em detalhe, com exemplos completos, consulte a documentação completa.

Por que Clarus CSS

A maioria dos frameworks CSS obriga você a escolher um lado: componentes prontos e opinativos ou utilitários atômicos e flexíveis. O Clarus CSS assume os dois de propósito — é essa a filosofia híbrida que orienta toda a arquitetura do projeto.

| | | | --- | --- | | Híbrido por design | Componentes prontos (.cl-btn, .cl-card, .cl-modal) e utilitários atômicos (.u-d-flex, .u-mt-3, .u-gx-2) convivem na mesma folha de estilo, com uma convenção de nomes (cl-/u-/is-) que evita colisão entre os dois mundos. | | Zero dependências | Nenhuma dependência de runtime — nem framework JS, nem CDN externo para fontes. HTML, CSS e JavaScript nativo, prontos para colar direto em qualquer página. | | Dark mode nativo | Suporte a tema escuro desde a primeira versão, via CSS Custom Properties e um único atributo (data-theme="dark") — sem plugin, sem JS extra. | | Multi-marca | data-brand="x" troca a cor de ação primária em runtime, sem recompilar CSS — combina com data-theme="dark" automaticamente (ver Theming). | | Acessibilidade não é opcional | ARIA, foco e navegação por teclado são parte da API de todo componente interativo desde o início, não um retrofit — e um gate axe-core no CI garante isso a cada PR (ver matriz de acessibilidade). | | Curva de aprendizado familiar | Nomenclatura de classes e grid seguem convenções amplamente adotadas — quem já usou um framework CSS de componentes se sente em casa em minutos. | | Customização sem fork | Toda a identidade visual (cores, espaçamento, tipografia, raios, sombras) é exposta via CSS Custom Properties — sobrescreva sem recompilar. | | TypeScript incluso | .d.ts hand-escritos para toda a API JS pública — autocomplete e checagem de tipos sem reescrever nada em TS. |

Instalação

Via npm:

npm install clarus-css

Ou direto via CDN (jsDelivr/unpkg), sem instalar nada:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/clarus-css/dist/css/clarus.css">
<script src="https://cdn.jsdelivr.net/npm/clarus-css/dist/js/clarus.js"></script>

O CSS também é distribuído em arquivos separados (layout.css, forms.css, components.css, helpers.css), e o ponto de entrada Sass está disponível para compilar com suas próprias variáveis. Detalhes em Instalação e Formas de uso.

As fontes self-hosted (Plus Jakarta Sans e Source Code Pro) são distribuídas à parte em fonts.css. Inclua-o antes do CSS principal para usá-las; sem ele, a tipografia cai no sans-serif/monospace do sistema:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/clarus-css/dist/css/fonts.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/clarus-css/dist/css/clarus.css">

Início rápido

Um componente interativo se inicializa sozinho via data-cl — basta incluir o CSS e o JS e escrever o HTML:

<link rel="stylesheet" href="node_modules/clarus-css/dist/css/clarus.min.css">

<button type="button" class="cl-btn cl-btn-primary" data-cl="modal" data-cl-target="#meuModal">
  Abrir modal
</button>

<div class="cl-modal" id="meuModal">
  <div class="cl-modal-dialog">
    <div class="cl-modal-content">
      <div class="cl-modal-header">
        <h3 class="cl-modal-title">Título</h3>
        <button type="button" class="cl-btn-close" data-cl-dismiss="modal" aria-label="Fechar"></button>
      </div>
      <div class="cl-modal-body">Conteúdo do modal.</div>
    </div>
  </div>
</div>

<script src="node_modules/clarus-css/dist/js/clarus.min.js"></script>

Todo componente interativo compartilha a mesma API (.show(), .hide(), .toggle(), .dispose(), getInstance() e eventos DOM cl:*). Os conceitos gerais estão em Formas de uso.

Componentes

• Layout: containers, grid Flexbox (.cl-row/.cl-col-*), Stack/Cluster/ Sidebar, sticky e utilitários de @container.
• Formulários: controles, select customizado, Combobox, Datepicker/ Timepicker, checkbox/radio/switch, Range/Slider, upload de arquivo (com drag-and-drop e versão avançada com progresso), input group.
• Conteúdo: botões, cards, alertas, badges/tags, tabelas, DataTable (sort/filtro/paginação/estados), tiles, divider, empty state, skeleton.
• Navegação: navbar, dropdown, nested menu, tabs, Tree View, paginação, breadcrumbs, accordion, collapse, stepper.
• Overlay: modal, alert dialog, offcanvas, tooltip, popover, Command Palette.
• Feedback: toast, notification center, spinner, progress bar.
• Interação avançada: carousel, rating, segmented control, timeline.

Cada componente tem um exemplo funcional dedicado (claro + escuro) em mockup/ — a forma mais rápida de ver o framework em ação sem escrever nenhum código. O passo a passo de uso de cada um está na documentação de componentes. Prefere ver tudo já montado numa página real? mockup/templates/ tem 4 templates prontos pra copiar (dashboard, autenticação, landing page e painel administrativo).

Customização e dark mode

Todos os tokens visuais são expostos como CSS Custom Properties (prefixo --cl-). Para customizar, redefina a variável no seu próprio CSS — sem fork, sem recompilar:

:root {
  --cl-color-primary: #6d28d9;
  --cl-radius-md: 10px;
}

O dark mode é ativado por um único atributo (<html data-theme="dark">), sem JavaScript obrigatório. Detalhes em Theming e Dark mode.

Ecossistema

Pacotes opcionais, publicados separadamente do core:

• clarus-icons — ícones SVG (Lucide), tree-shakeable, zero dependências em runtime.
• clarus-cli — CLI (build/theme/ analyze) para projetos consumidores.
• clarus-react — wrapper React fino (Modal/Dropdown/Tabs), delega pro JS vanilla existente.

Comparação com outros frameworks

Avaliando o Clarus contra outras opções? Clarus vs Bootstrap vs Tailwind CSS — filosofia, tamanho de bundle, dependências e dark mode nativo, com dados públicos e reproduzíveis.

Documentação

• docs/README.md — documentação completa: guias de uso, um arquivo por componente (anatomia, variações, estados, A11y, API JS, tokens, exemplo) e referência técnica.
• docs/reference/definitions.md — decisões de arquitetura e o catálogo técnico de cada componente (classes, tokens, módulos JS).
• docs/reference/scss-architecture.md — arquitetura dos módulos SCSS e do pipeline de build.
• docs/reference/browser-support.md — alvo de navegadores e matriz de compatibilidade por feature moderna.
• docs/reference/accessibility-matrix.md — teclado, ARIA e gestão de foco por componente.
• docs/reference/contrast-report.md — auditoria WCAG dos tokens de cor nos dois temas.
• docs/guides/migration-external.md — migrando de outro framework CSS pro Clarus.
• CONTRIBUTING.md — como rodar o projeto localmente, convenções de contribuição e processo de release.
• CHANGELOG.md — histórico de mudanças, seguindo Keep a Changelog e Semantic Versioning.

Licença

Distribuído sob a licença MIT — uso livre em projetos pessoais, comerciais e comunitários.

Desenvolvido integralmente por Jorge Wanderley Reis de Menezes — [email protected]