ngx-monorepo

Design system React para prototipagem interna. Componentes fiéis ao Figma, documentados no Storybook, consumidos pelos protótipos da empresa.

Não é uma biblioteca de produção — é a base para montar protótipos rápido, com componentes reais (não mockups) e visual alinhado ao Figma.

Estrutura

packages/tokens/      @ngx/tokens     — tokens CSS (Style Dictionary, gerados do Figma)
packages/components/  @ngx/components — componentes React + CSS Modules
apps/storybook/                       — documentação interativa dos componentes
apps/proto-template/                  — template de protótipo (Vite + React)

Pré-requisitos

• Node.js 18+
• pnpm 9+ (npm install -g pnpm)

Como rodar (primeira vez)

pnpm install     # instala as dependências
pnpm build       # gera os tokens (dist/) — necessário antes de rodar
pnpm storybook   # abre o Storybook em http://localhost:6006

O pnpm build precisa rodar uma vez após clonar (e sempre que os tokens mudarem), porque o Storybook/protótipos importam o tokens.css já gerado.

Outros comandos úteis:

pnpm dev      # storybook + proto-template em paralelo
pnpm proto    # abre o template de protótipo (http://localhost:5173)
pnpm turbo test

Montar um protótipo

Os protótipos vivem dentro deste repositório, em apps/. Use o template pronto apps/proto-template:

1. Clone o repositório (acesso privado no GitHub) e rode os passos acima.
2. Copie o template:

   cp -r apps/proto-template apps/meu-prototipo
   # Windows/PowerShell: Copy-Item -Recurse apps/proto-template apps/meu-prototipo

3. Troque o name em apps/meu-prototipo/package.json para meu-prototipo.
4. Instale e rode:

   pnpm install
   pnpm --filter meu-prototipo dev

5. Monte sua tela em src/App.tsx, importando o que precisar:

   import { Button, Select, Menu } from '@ngx/components';

O template já importa tokens/fontes em src/main.tsx — mantenha esses imports. Veja o catálogo de componentes com pnpm storybook.

Atualizar os componentes (rebater mudanças)

A biblioteca e os protótipos vivem no mesmo repositório, então a propagação é o próprio Git:

• Quem mantém os componentes: edita em packages/components, commita e dá git push.
• Quem está montando protótipo: roda git pull para receber a versão mais recente. Se houver dependências novas, pnpm install; se tokens mudaram, pnpm build.

Um git pull rebate as atualizações de componente para todo mundo que estiver consumindo.

Propriedade — o que é seu vs. o que é da pessoa

| Pasta | Quem edita | |---|---| | packages/ (tokens + componentes) | Só o mantenedor (dono do repo). É a biblioteca. | | apps/storybook, apps/proto-template | Mantenedor. | | apps/<seu-prototipo> | Quem está prototipando — só aqui. |

Regra: quem monta protótipo edita exclusivamente a própria pasta em apps/. Ninguém altera packages/ — esse é o design system, mantido só pelo dono.

• Garantia: com acesso read-only (ver abaixo), alterações em packages/ por consumidores não chegam ao repositório — só o dono tem escrita.
• Localmente ainda é possível editar por engano (inclusive uma IA pode "consertar" um componente sem querer). O git denuncia: git status mostra modified: packages/.... Para reverter ao original (offline, sem afetar o protótipo):

  git restore packages/

• Cada protótipo já vem com um CLAUDE.md instruindo agentes a nunca tocar em packages/ — só na pasta do protótipo.

Acesso e segurança

Para evitar que protótipos sobrescrevam ou baguncem o monorepo:

• Quem monta protótipo recebe acesso somente-leitura (GitHub → Settings → Collaborators → Role: Read). Com isso o git push dessas pessoas é recusado pelo GitHub — elas só clonam, criam o protótipo localmente e dão git pull. O dono é o único que dá push nos componentes.
• Proteção de branch no main (GitHub → Settings → Branches → Add rule): marque "Require a pull request before merging" e "Do not allow force pushes". Cinto-e-suspensório contra push direto / reescrita de histórico.

O git não sobrescreve nada sozinho: um push que diverge do main é rejeitado (erro non-fast-forward); só um git push --force intencional — e com permissão de escrita — reescreveria. Read-only + branch protection tornam isso impossível.

Quem quer salvar/versionar o próprio protótipo

Como o protótipo fica local (read-only não dá push), quem quiser backup deve fazer um fork do repositório: o push vai para o fork da própria pessoa, nunca para este repo. Para receber atualizações dos componentes, configura este repo como upstream e dá git pull upstream main.

Pipeline de tokens

Figma plugin "Design Tokens" → export .json
  └── pnpm tokens:sync <arquivo.json>   → packages/tokens/raw-tokens.json (fonte de verdade)
        └── pnpm tokens:build           → dist/tokens.css, dist/fonts.css

Componentes usam exclusivamente var(--color-*), var(--font-*), var(--shadow-*) — nunca hex hardcoded.

Convenções

As regras de construção de componentes, tokens, scrollbar compartilhada e building blocks estão no CLAUDE.md.