@assembleo/ui 0.1.0

package/README.md

@@ -0,0 +1,89 @@
+# assembleo-ui
+
+O design system do Assembleo: tokens, componentes e a camada expressiva que dão
+cara ao produto. Publicado como [`@assembleo/ui`](https://www.npmjs.com/package/@assembleo/ui)
+no npm, consumido pelo [`assembleo-web`](https://github.com/The-Fant-Company/assembleo-web).
+
+A ideia visual em uma linha: **a vida em comum de um condomínio** — superfícies
+claras e calmas, um azul cívico para a decisão, e uma paleta expressiva
+(telhado, jardim, luz de janela) reservada aos objetos do mundo do condomínio:
+prédios, crachás, livretos. Os princípios (Clareza, Deferência, Vida) estão em
+[`src/docs/introducao.mdx`](src/docs/introducao.mdx) e as decisões que
+valem para os quatro repos, nos ADRs 0008–0010 do repo
+[`assembleo`](https://github.com/The-Fant-Company/assembleo).
+
+## Consumir
+
+```bash
+pnpm add @assembleo/ui
+```
+
+```css
+/* app.css — a ordem importa */
+@import 'tailwindcss';
+@import '@assembleo/ui/theme.css';
+@source '../node_modules/@assembleo/ui/dist';
+```
+
+O `@source` é o que faz o Tailwind do app enxergar as classes usadas pelos
+componentes do package; sem ele, componente chega sem estilo. O caminho é
+relativo ao arquivo CSS.
+
+```tsx
+import { Button, Field, Input } from '@assembleo/ui'
+```
+
+### Tema
+
+Sem configurar nada, claro/escuro segue o aparelho. Para dar a escolha ao
+usuário, o sistema traz o gerenciador pronto:
+
+```tsx
+// main.tsx — antes do createRoot: aplica a escolha guardada sem flash
+import { initTheme } from '@assembleo/ui'
+initTheme()
+```
+
+```tsx
+// no app: o provider expõe useTheme(); o ThemeToggle é o seletor pronto
+<ThemeProvider>
+  <App />
+</ThemeProvider>
+```
+
+A escolha vira `data-theme` no `<html>` (o mesmo mecanismo dos tokens) e
+persiste em localStorage; "Sistema" apaga a escolha e devolve o controle ao
+aparelho.
+
+## Desenvolver
+
+```bash
+pnpm install
+pnpm storybook     # a documentação viva, em http://localhost:6006
+pnpm test          # vitest — comportamento, acessibilidade e contraste AA
+pnpm typecheck
+pnpm lint
+pnpm build         # tsup → dist/ + theme.css
+```
+
+O checklist para criar ou mudar componente está em
+[`docs/contribuindo.md`](docs/contribuindo.md); o piso de acessibilidade, em
+[`docs/acessibilidade.md`](docs/acessibilidade.md).
+
+## Estrutura
+
+```
+src/
+  tokens/       theme.css — cor, tipo, raio, elevação, movimento (e o teste
+                que verifica contraste AA e a paridade claro/escuro)
+  lib/          cn() e utilidades transversais
+  components/   as primitivas: botão, campo, diálogo, lista…
+  expressive/   a camada lúdica: prédio, crachá, livreto
+  docs/         páginas de fundação do Storybook
+```
+
+## Release
+
+Igual ao contracts (ADR 0002/0008): changeset por mudança visível
+(`pnpm changeset`), e o CI da main versiona e publica sozinho. Sem changeset
+pendente não há release — e PR sem changeset é mudança que não chega a ninguém.