al-design-system 0.0.0-stage → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Guilherme Domingues
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,181 @@
-# Temporary Holding Version
+# AL Design System
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![npm](https://img.shields.io/npm/v/al-design-system)](https://www.npmjs.com/package/al-design-system)
+[![license](https://img.shields.io/github/license/guilhermedworakowski/al-design-system)](LICENSE)
+[![build](https://github.com/guilhermedworakowski/al-design-system/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/guilhermedworakowski/al-design-system/actions/workflows/build.yml)
+
+An open-source design system, from Figma to code. Plain CSS, a little vanilla JavaScript only where CSS can't reach, and no dependencies.
+
+**English** · [Português](README.pt-BR.md) · [Documentation site](https://al.guilhermedesignd.com)
+
+## What it is
+
+- **Foundation + 24 components**, designed in Figma and coded from the same tokens.
+- **Light and dark themes** built in. It follows the operating system by default, and you can force one.
+- **Accessibility is checked by the build.** Every rendered combination (variant × state × theme) is measured for contrast against the background it actually sits on, and each component's markup contract is verified. If something fails, the build stops.
+- **Nothing is typed by hand.** Tokens, CSS variables, `tokens.json` and the documentation tables are all generated from one source.
+
+## Components
+
+| Group | Component | Script | Guidelines |
+|---|---|:---:|---|
+| Actions and display | Button | | [guidelines](src/components/button/guidelines.md) |
+| | Icon | | (70 icons, see [Icons](#icons)) |
+| | Icon Button | | [guidelines](src/components/icon-button/guidelines.md) |
+| | Link | | [guidelines](src/components/link/guidelines.md) |
+| | Tag | | [guidelines](src/components/tag/guidelines.md) |
+| | Avatar | | [guidelines](src/components/avatar/guidelines.md) |
+| Forms | Select | | [guidelines](src/components/select/guidelines.md) |
+| | Checkbox | | [guidelines](src/components/checkbox/guidelines.md) |
+| | Radio | | [guidelines](src/components/radio/guidelines.md) |
+| | Switch | | [guidelines](src/components/switch/guidelines.md) |
+| | Input | | [guidelines](src/components/input/guidelines.md) |
+| | Textarea | | [guidelines](src/components/textarea/guidelines.md) |
+| | Password | ✓ | [guidelines](src/components/password/guidelines.md) |
+| Structure and overlays | Divider | | [guidelines](src/components/divider/guidelines.md) |
+| | Card | | [guidelines](src/components/card/guidelines.md) |
+| | Tab | ✓ | [guidelines](src/components/tab/guidelines.md) |
+| | Accordion | | [guidelines](src/components/accordion/guidelines.md) |
+| | Modal | ✓ | [guidelines](src/components/modal/guidelines.md) |
+| | Drawer | ✓ | [guidelines](src/components/drawer/guidelines.md) |
+| Navigation | Sidebar | ✓ | [guidelines](src/components/sidebar/guidelines.md) |
+| | Breadcrumb | ✓ | [guidelines](src/components/breadcrumb/guidelines.md) |
+| Feedback | Tooltip | ✓ | [guidelines](src/components/tooltip/guidelines.md) |
+| | Toast | ✓ | [guidelines](src/components/toast/guidelines.md) |
+| | Alert | ✓ | [guidelines](src/components/alert/guidelines.md) |
+
+Each guidelines file holds the usage rules (when to use it, when not to, content, behavior and accessibility) and, when there are any, the contrast exceptions the component declares.
+
+## Install
+
+```bash
+npm install al-design-system
+```
+
+Or straight from a CDN, pinned to a version:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.1.0/dist/al.css">
+```
+
+Each [GitHub Release](https://github.com/guilhermedworakowski/al-design-system/releases) also carries the `dist/` folder as a zip.
+
+### What's in the package
+
+| File | What it is |
+|---|---|
+| `al.css` | Foundation + all 24 components, in one file |
+| `foundation.css` | Only the Foundation: color, typography, spacing, radius, icon size, elevation, focus ring and motion |
+| `components/<name>.css` | One component (its tokens + its CSS) |
+| `components/<name>.js` | The behavior, for the 9 components that have a script |
+| `icons/*.svg`, `icons/icons.json` | The 70 icons |
+| `tokens.json` | The Foundation tokens, to read from code |
+
+## Usage
+
+### CSS
+
+The simplest way is the whole thing:
+
+```js
+import 'al-design-system';            // same as al-design-system/al.css
+```
+
+Or only what the product uses. The Foundation always comes first, because every component token points to one of its tokens:
+
+```js
+import 'al-design-system/foundation.css';
+import 'al-design-system/components/button.css';
+```
+
+Then the markup uses the `.al-*` classes:
+
+```html
+<button type="button" class="al-btn al-btn--primary al-btn--md">Save</button>
+```
+
+The exact markup of each component (which element, which attributes) is described at the top of its CSS file and on the [documentation site](https://al.guilhermedesignd.com).
+
+### Scripts
+
+Password, Tab, Modal, Drawer, Sidebar, Breadcrumb, Tooltip, Toast and Alert need their script, loaded once per page. Each one wires up the components already on the page by itself:
+
+```html
+<script src="node_modules/al-design-system/dist/components/modal.js" defer></script>
+```
+
+Content added later is wired with `init`, for example `window.alModals.init(element)`. Toast and Alert are opened from code: `alToast.show(...)` and `alAlert.show(...)`. The usage of each script is at the top of its file.
+
+### Theme
+
+Without anything on `<html>`, the theme follows the operating system (`prefers-color-scheme`). To force one:
+
+```html
+<html data-theme="dark">
+```
+
+### Fonts
+
+Fonts are not in the package. The Foundation asks for `Inter` and `JetBrains Mono`, with system fallbacks. Loading the font files is up to the product, preferably hosted alongside it.
+
+### Icons
+
+The SVGs go inline, with the `.al-icon` class on the `<svg>` itself, so they inherit the text color (`<img>` doesn't). The file only has the drawing. The accessibility contract is added by whoever uses it:
+
+- decorative: `aria-hidden="true" focusable="false"`;
+- carries meaning: `role="img"` and an `aria-label`.
+
+## Tokens
+
+Three layers, each with one job:
+
+1. **Primitive**: the raw color ramps, in OKLCH, on a single lightness scale shared by every family. No component uses them directly.
+2. **Semantic**: the role (`bg-brand`, `text-secondary`, `border-focus`), with one value per theme. This is where the theme is resolved.
+3. **Component**: an alias of a semantic token, one per role in the component (`button-primary-bg-hover`). Never a loose hex value.
+
+In CSS they are custom properties prefixed with `--al-`. `tokens.json` has the same values for anyone who wants to read them from code.
+
+## Accessibility
+
+The minimums are the WCAG contrast ones: 4.5:1 for text, 3:1 for icons, borders and focus. When the brand color doesn't reach the minimum, the exception is named one by one, never goes below 3:1, and is paid for with a usage rule (a visible label, a title, a second cue). When a component has exceptions, they are listed in its guidelines.
+
+Besides contrast, each component has a markup contract checked against the HTML: the right native element, an accessible name, the right attributes, nothing interactive where it shouldn't be.
+
+## Versioning
+
+AL follows semantic versioning, read like this:
+
+- **third digit** (1.0.**1**): an adjustment, with no new component or layer;
+- **middle digit** (1.**1**.0): a new component or layer;
+- **first digit** (**2**.0.0): a change that breaks what already exists.
+
+What changed in each version is in the [CHANGELOG](CHANGELOG.md).
+
+## Repository structure
+
+```
+src/foundation/        the Foundation source (color, typography, spacing...) in Python
+src/components/<name>/ one folder per component:
+  tokens.py              the component tokens (aliases of the Foundation)
+  <name>.css             the handwritten CSS
+  <name>.js              the script, when there is one
+  check.py, a11y.py      the gates (literal CSS, orphan tokens, contrast, markup)
+  guidelines.md          the usage rules
+site/                  the documentation site generator
+tools/                 what the build shares (paths, dist assembly)
+build.py               runs everything, in order
+build/                 generated output (CSS, tokens, site)
+dist/                  the package that goes to npm
+```
+
+To build from source you only need Python 3.9 or later, with no packages to install:
+
+```bash
+python3 build.py
+```
+
+It regenerates everything and runs every gate. Details are in [CONTRIBUTING](CONTRIBUTING.md).
+
+## License
+
+[MIT](LICENSE) © 2026 Guilherme Domingues. The icons come from [Lucide](https://lucide.dev) (ISC); see [`icons/NOTICE`](src/components/icon/NOTICE).

package/README.pt-BR.md

@@ -0,0 +1,181 @@
+# AL Design System
+
+[![npm](https://img.shields.io/npm/v/al-design-system)](https://www.npmjs.com/package/al-design-system)
+[![licença](https://img.shields.io/github/license/guilhermedworakowski/al-design-system)](LICENSE)
+[![build](https://github.com/guilhermedworakowski/al-design-system/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/guilhermedworakowski/al-design-system/actions/workflows/build.yml)
+
+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](README.md) · **Português** · [Site de documentação](https://al.guilhermedesignd.com)
+
+## O que é
+
+- **Foundation + 24 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](src/components/button/guidelines.md) |
+| | Icon | | (70 ícones, ver [Ícones](#ícones)) |
+| | Icon Button | | [diretrizes](src/components/icon-button/guidelines.md) |
+| | Link | | [diretrizes](src/components/link/guidelines.md) |
+| | Tag | | [diretrizes](src/components/tag/guidelines.md) |
+| | Avatar | | [diretrizes](src/components/avatar/guidelines.md) |
+| Formulários | Select | | [diretrizes](src/components/select/guidelines.md) |
+| | Checkbox | | [diretrizes](src/components/checkbox/guidelines.md) |
+| | Radio | | [diretrizes](src/components/radio/guidelines.md) |
+| | Switch | | [diretrizes](src/components/switch/guidelines.md) |
+| | Input | | [diretrizes](src/components/input/guidelines.md) |
+| | Textarea | | [diretrizes](src/components/textarea/guidelines.md) |
+| | Password | ✓ | [diretrizes](src/components/password/guidelines.md) |
+| Estrutura e sobreposição | Divider | | [diretrizes](src/components/divider/guidelines.md) |
+| | Card | | [diretrizes](src/components/card/guidelines.md) |
+| | Tab | ✓ | [diretrizes](src/components/tab/guidelines.md) |
+| | Accordion | | [diretrizes](src/components/accordion/guidelines.md) |
+| | Modal | ✓ | [diretrizes](src/components/modal/guidelines.md) |
+| | Drawer | ✓ | [diretrizes](src/components/drawer/guidelines.md) |
+| Navegação | Sidebar | ✓ | [diretrizes](src/components/sidebar/guidelines.md) |
+| | Breadcrumb | ✓ | [diretrizes](src/components/breadcrumb/guidelines.md) |
+| Feedback | Tooltip | ✓ | [diretrizes](src/components/tooltip/guidelines.md) |
+| | Toast | ✓ | [diretrizes](src/components/toast/guidelines.md) |
+| | Alert | ✓ | [diretrizes](src/components/alert/guidelines.md) |
+
+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
+
+```bash
+npm install al-design-system
+```
+
+Ou direto de uma CDN, fixado numa versão:
+
+```html
+<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/al-design-system@1.1.0/dist/al.css">
+```
+
+Cada [Release no GitHub](https://github.com/guilhermedworakowski/al-design-system/releases) também traz a pasta `dist/` num zip.
+
+### O que vem no pacote
+
+| Arquivo | O que é |
+|---|---|
+| `al.css` | Foundation + os 24 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 9 componentes que têm script |
+| `icons/*.svg`, `icons/icons.json` | Os 70 ícones |
+| `tokens.json` | Os tokens da Foundation, para ler por código |
+
+## Uso
+
+### CSS
+
+O jeito mais simples é tudo de uma vez:
+
+```js
+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:
+
+```js
+import 'al-design-system/foundation.css';
+import 'al-design-system/components/button.css';
+```
+
+Depois, a marcação usa as classes `.al-*`:
+
+```html
+<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](https://al.guilhermedesignd.com).
+
+### Scripts
+
+Password, Tab, Modal, Drawer, Sidebar, Breadcrumb, 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:
+
+```html
+<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
+<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`.
+
+## 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.
+
+## 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.
+
+## 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](CHANGELOG.md).
+
+## 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)
+  guidelines.md          as regras de uso
+site/                  o gerador do site de documentação
+tools/                 o que o build compartilha (caminhos, montagem do dist)
+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, basta o Python 3.9 ou mais novo, sem nenhum pacote para instalar:
+
+```bash
+python3 build.py
+```
+
+Ele regera tudo e roda todos os portões. Os detalhes estão no [CONTRIBUTING](CONTRIBUTING.md) (em inglês).
+
+## Licença
+
+[MIT](LICENSE) © 2026 Guilherme Domingues. Os ícones vêm do [Lucide](https://lucide.dev) (ISC); ver [`icons/NOTICE`](src/components/icon/NOTICE).