AL Design System

Design system open source, do Figma ao código. CSS puro, um pouco de JavaScript sem framework só onde o CSS não alcança, e nenhuma dependência.

English · Português · Site de documentação

O que é

• Foundation + 33 componentes, desenhados no Figma e codados a partir dos mesmos tokens.
• Temas claro e escuro já incluídos. Por padrão segue o sistema operacional, e dá para forçar um.
• A acessibilidade é conferida no build. Cada combinação renderizada (variante × estado × tema) tem o contraste medido contra o fundo onde ela realmente aparece, e o contrato de marcação de cada componente é verificado. Se algo reprova, o build para.
• Nada é digitado à mão. Tokens, variáveis CSS, tokens.json e as tabelas da documentação saem todos de uma fonte só.

Componentes

| Grupo | Componente | Script | Diretrizes | |---|---|:---:|---| | Ações e exibição | Button | | diretrizes | | | Icon | | (70 ícones, ver Ícones) | | | Icon Button | | diretrizes | | | Link | | diretrizes | | | Menu | ✓ | diretrizes | | | Tag | | diretrizes | | | Avatar | | diretrizes | | Formulários | Select | | diretrizes | | | Checkbox | | diretrizes | | | Radio | | diretrizes | | | Switch | | diretrizes | | | Input | | diretrizes | | | Textarea | | diretrizes | | | Password | ✓ | diretrizes | | | Number field | ✓ | diretrizes | | | Slider | ✓ | diretrizes | | | Rating | | diretrizes | | Estrutura e sobreposição | Divider | | diretrizes | | | Card | | diretrizes | | | Tab | ✓ | diretrizes | | | Accordion | | diretrizes | | | Modal | ✓ | diretrizes | | | Drawer | ✓ | diretrizes | | Navegação | Sidebar | ✓ | diretrizes | | | Breadcrumb | ✓ | diretrizes | | | Carousel | ✓ | diretrizes | | | Pagination | | diretrizes | | | Stepper | | diretrizes | | Feedback | Tooltip | ✓ | diretrizes | | | Toast | ✓ | diretrizes | | | Alert | ✓ | diretrizes | | | Progress | | diretrizes | | | Empty state | | diretrizes |

Cada arquivo de diretrizes traz as regras de uso (quando usar, quando não usar, conteúdo, comportamento e acessibilidade) e, quando houver, as exceções de contraste que o componente declara. Por enquanto as diretrizes estão em inglês; a versão em português chega junto com o site novo.

Instalação

npm install al-design-system

Ou direto de uma CDN, fixado numa versão:

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/al.css">

Cada Release no GitHub também traz a pasta dist/ num zip.

O que vem no pacote

| Arquivo | O que é | |---|---| | al.css | Foundation + os 33 componentes, num arquivo só | | foundation.css | Só a Foundation: cor, tipografia, espaçamento, radius, tamanho de ícone, elevação, anel de foco e motion | | components/<nome>.css | Um componente (os tokens + o CSS dele) | | components/<nome>.js | O comportamento, para os 13 componentes que têm script | | icons/*.svg, icons/icons.json | Os 70 ícones | | tokens.json | Os tokens da Foundation, para ler por código | | components.json | Por componente: o HTML a escrever, as regras de marcação e os arquivos a importar | | guidelines/<nome>.md | As regras de uso de cada componente | | mcp/ | O comando al-design-system: um validador de marcação e um servidor MCP para agentes de IA |

Uso

CSS

O jeito mais simples é tudo de uma vez:

import 'al-design-system';            // o mesmo que al-design-system/al.css

Ou só o que o produto usa. A Foundation vem sempre primeiro, porque todo token de componente aponta para um token dela:

import 'al-design-system/foundation.css';
import 'al-design-system/components/button.css';

Depois, a marcação usa as classes .al-*:

<button type="button" class="al-btn al-btn--primary al-btn--md">Salvar</button>

A marcação exata de cada componente (qual elemento, quais atributos) está descrita no topo do CSS dele e no site de documentação.

Scripts

Password, Number field, Slider, Menu, Tab, Modal, Drawer, Sidebar, Breadcrumb, Carousel, Tooltip, Toast e Alert precisam do script, carregado uma vez por página. Cada um liga sozinho os componentes que já estão na página:

<script src="node_modules/al-design-system/dist/components/modal.js" defer></script>

Conteúdo inserido depois é ligado com init, por exemplo window.alModals.init(elemento). Toast e Alert são abertos por código: alToast.show(...) e alAlert.show(...). O uso de cada script está no topo do arquivo.

Tema

Sem nada no <html>, o tema segue o sistema operacional (prefers-color-scheme). Para forçar um:

<html data-theme="dark">

Fontes

As fontes não vêm no pacote. A Foundation pede Inter e JetBrains Mono, com fontes do sistema como reserva. Carregar os arquivos de fonte fica com o produto, de preferência hospedados junto com ele.

Ícones

Os SVGs entram inline, com a classe .al-icon no próprio <svg>, para herdarem a cor do texto (o <img> não herda). O arquivo traz só o desenho. O contrato de acessibilidade é acrescentado por quem usa:

• decorativo: aria-hidden="true" focusable="false";
• carrega sentido: role="img" e um aria-label.

Agentes de IA

O pacote traz o que um agente precisa para usar o AL sem adivinhar, na mesma versão do CSS instalado e sem dependências. Nada roda na instalação: um projeto que só importa o CSS nunca encosta nisso.

• components.json: para cada componente, o HTML a escrever, cada regra de marcação com o motivo, e o CSS e o JS a importar.
• npx al-design-system validate pagina.html confere o HTML com essas regras e aponta a linha, o elemento e a regra.
• npx al-design-system mcp roda um servidor MCP por stdio, com list_components, get_component, get_tokens e validate_markup. Para adicionar no Claude Code:

claude mcp add al -- npx al-design-system mcp

O site também publica o llms.txt. As evals do repositório medem tudo isso: pedidos reais a um agente, com e sem o servidor MCP, pontuados por essas mesmas regras.

Tokens

Três camadas, cada uma com um trabalho:

1. Primitiva: as escalas de cor cruas, em OKLCH, numa única escada de lightness compartilhada por todas as famílias. Nenhum componente usa direto.
2. Semântica: o papel (bg-brand, text-secondary, border-focus), com um valor por tema. É onde o tema é resolvido.
3. Componente: um alias de um token semântico, um por papel do componente (button-primary-bg-hover). Nunca um hex solto.

No CSS, são custom properties com o prefixo --al-. O tokens.json tem os mesmos valores para quem quiser ler por código, e o color.usage diz, numa frase por token semântico, quando usar e o que vai por cima dele.

Acessibilidade

Os mínimos são os de contraste do WCAG: 4,5:1 para texto, 3:1 para ícone, borda e foco. Quando a cor da marca não chega ao mínimo, a exceção é nomeada uma a uma, nunca desce de 3:1 e é paga com uma regra de uso (um rótulo visível, um título, uma segunda pista). Quando um componente tem exceções, elas estão listadas nas diretrizes dele.

Além do contraste, cada componente tem um contrato de marcação conferido contra o HTML: o elemento nativo certo, um nome acessível, os atributos certos, nada interativo onde não deve. O HTML para copiar fica no topo do CSS de cada componente, num bloco MARKUP CONTRACT, e o build reprova se o CSS estiliza uma classe que o bloco não cita. As regras são dado, no contract.json de cada componente: o build confere no site, e o validador do pacote confere no seu, a partir do mesmo arquivo.

Versionamento

O AL segue o versionamento semântico, lido assim:

• terceira casa (1.0.1): ajuste, sem componente ou camada nova;
• casa do meio (1.1.0): componente ou camada nova;
• primeira casa (2.0.0): mudança que quebra o que já existe.

O que mudou em cada versão está no CHANGELOG.

Estrutura do repositório

src/foundation/        a fonte da Foundation (cor, tipografia, espaçamento...) em Python
src/components/<nome>/ uma pasta por componente:
  tokens.py              os tokens do componente (alias da Foundation)
  <nome>.css             o CSS escrito à mão
  <nome>.js              o script, quando existe
  check.py, a11y.py      os portões (CSS literal, token órfão, contraste, marcação)
  contract.json          o contrato de marcação, como dado
  guidelines.md          as regras de uso
src/mcp/               o comando do pacote: validador e servidor MCP, em Node
site/                  o gerador do site de documentação
tools/                 o que o build compartilha (caminhos, portões, montagem do dist, o llms.txt do site, as descrições do Figma)
evals/                 pedidos reais a um agente de IA, pontuados pelas regras do próprio pacote (fora do build)
build.py               roda tudo, na ordem
build/                 saída gerada (CSS, tokens, site)
dist/                  o pacote que vai para o npm

Para gerar a partir do código, bastam o Python 3.9 ou mais novo e o Node 18 ou mais novo (um portão roda o validador do pacote), sem nenhum pacote para instalar:

python3 build.py

Ele regera tudo e roda todos os portões. Os detalhes estão no CONTRIBUTING (em inglês).

Licença

MIT © 2026 Guilherme Domingues. Os ícones vêm do Lucide (ISC); ver icons/NOTICE.