# Para quem desenvolve — Design System Phorte

> O que instalar antes de mexer no projeto, as dependências e para que serve cada uma, os comandos e o gate que roda antes de todo commit.

- Página: https://phorte-design-system.vercel.app/styleguide/comecar/desenvolvimento
- Índice: https://phorte-design-system.vercel.app/llms.txt

## Antes de começar: o que instalar

| O quê | Versão | Para quê | Como |
| --- | --- | --- | --- |
| Git | qualquer versão recente | Clonar o repositório e receber as correções da origem (o processo de clone usa `upstream`). | git-scm.com. No Windows, o Git for Windows já traz o Git Bash. |
| Node.js | 22 (a do CI) | Rodar o Next, o Storybook, os testes e o audit. O npm vem junto. | nodejs.org, a versão LTS 22 — ou um gerenciador de versões (nvm, fnm, Volta). |
| Python | 3.9 ou mais nova | O gate estático de acessibilidade (`npm run a11y`, o `verify-a11y.py` do A11Y.md). Sem dependências: só o Python. | python.org. O script procura `python3`, `python` e, no Windows, `py -3`. |
| Chromium do Playwright | o da versão do Playwright do projeto | Os testes das fichas (`npm run test`) rodam num navegador de verdade, com o axe. | Não precisa instalar à mão: o `npm run test` baixa sozinho na primeira vez (~1 min). No Linux sem interface, uma vez: `npx playwright install chromium --with-deps`. |

Extensões de editor que ajudam (opcionais): **ESLint** — Mostra no editor os erros que o `npm run lint` reprova — cor fora do token, `focus:`, itálico, as regras de acessibilidade. **Tailwind CSS IntelliSense** — Completa as classes, inclusive as do sistema (`bg-primary`, `gap-espaco-6`, `pagina`), lidas do `globals.css`.

## Clonar e rodar

```bash
git clone https://github.com/srbunnie/Pos-Phorte-Design-System.git meu-projeto
cd meu-projeto
git remote rename origin upstream
npm ci
npm run dev        # styleguide em http://localhost:3000/styleguide
npm run storybook  # fichas em http://localhost:6006
```

Nenhum token é necessário para desenvolver. O processo inteiro de clone e de receber correções da origem está em `docs/processo-de-clone.md`.

## As dependências

### O que as peças usam

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `date-fns` | ^4.1.0 | Datas em pt-BR, no fuso de São Paulo (EventDate). |
| `lucide-react` | ^0.546.0 | Os ícones (Lucide, a biblioteca oficial), sempre pelo átomo `Icone`. Presa na 0.546: a versão 1 tirou os ícones de marca que o Footer, a Navbar e o TeamGrid usam. |
| `motion` | ^13.2.0 | Motion para React (o antigo Framer Motion): as animações de entrada e de troca. Sempre pelos presets de `app/lib/motion-presets.ts` (`useMotionPresets`), que respeitam o movimento reduzido — importar os presets direto é erro de lint. |
| `next` | ^16.3.6 | O framework: o styleguide é uma aplicação Next (App Router). As peças usam o `next/link` e o `next/navigation`. A versão desta linha muda APIs: antes de escrever código, leia `node_modules/next/dist/docs/`. |
| `react` | ^19.0.0 | A biblioteca das peças. React 19, com o React Compiler. |
| `react-dom` | ^19.0.0 | O React no navegador. |

### Estilo e tokens

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `class-variance-authority` | ^0.7.1 | O `cva`: toda variante visual (`variant`, `size`) é declarada com ele, nunca com objeto de strings. |
| `clsx` | ^2.1.1 | Junta classes condicionais; é a metade do `cn()` (`app/lib/cn.ts`). |
| `tailwind-merge` | ^3.6.0 | Resolve conflito de classes (a `className` de quem usa vence a da peça); a outra metade do `cn()`, configurada com os tokens próprios em `app/lib/tw-merge.mjs`. |
| `@tailwindcss/postcss` | ^4.0.0 | Liga o Tailwind ao build do Next e do Storybook. |
| `tailwindcss` | ^4.1.14 | Tailwind v4: os tokens moram no `app/globals.css` (`:root` e `@theme`), não num arquivo de configuração. |

### Tipos, lint e testes

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `@types/node` | ^26.5.0 | Tipos do Node, para os scripts e as páginas que leem o disco. |
| `@types/react` | ^19.0.8 | Tipos do React. |
| `@types/react-dom` | ^19.0.3 | Tipos do React DOM. |
| `@vitest/browser` | ^4.1.11 | O Vitest num navegador de verdade, e não num DOM simulado. |
| `@vitest/browser-playwright` | ^4.1.11 | O Vitest guiando o Chromium pelo Playwright. |
| `eslint` | ^9.39.3 | O lint (`npm run lint`): as regras de cor, foco, itálico e movimento do sistema, em `eslint.config.mjs`. |
| `eslint-config-next` | ^16.3.6 | As regras do Next. |
| `eslint-plugin-jsx-a11y` | ^6.10.2 | As regras de acessibilidade da marcação, no conjunto recomendado, em erro. |
| `eslint-plugin-storybook` | ^10.2.19 | As regras das fichas do Storybook. |
| `playwright` | ^1.63.0 | O navegador dos testes e das medições (varredura de páginas, reflow a 320px). |
| `typescript` | ^5.9.3 | Os tipos (`npm run typecheck`). |
| `vitest` | ^4.1.11 | Roda as fichas como testes (`npm run test`): o axe e os testes de comportamento (`tags: ["teste"]`). |

### Catálogo e regressão visual

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `@chromatic-com/storybook` | ^5.0.1 | O Chromatic dentro do Storybook. |
| `@storybook/addon-a11y` | ^10.2.19 | O axe em cada ficha: no `npm run test`, violação reprova. |
| `@storybook/addon-docs` | ^10.2.19 | A página de documentação de cada ficha (`autodocs`). |
| `@storybook/addon-vitest` | ^10.2.19 | Liga as fichas ao Vitest. Tem um defeito com caminho acentuado, contornado em `vitest.config.ts` (ver `docs/upstream/`). |
| `@storybook/nextjs-vite` | ^10.2.19 | O Storybook para Next, sobre o Vite. |
| `chromatic` | ^18.7.2 | A regressão visual e a publicação do catálogo (`npm run chromatic`), no CI. Precisa do token, que clone não tem — e o CI pula o passo. |
| `storybook` | ^10.2.19 | O catálogo de fichas (`npm run storybook`, porta 6006), publicado no Chromatic. |

### Figma

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `@figma/code-connect` | ^1.5.3 | Code Connect (ligar componente do Figma ao código): Fase 2, desativado até o fim do projeto. |

### Ferramentas de build

| Pacote | Versão | Para quê |
| --- | --- | --- |
| `tsx` | ^4.21.0 | Roda scripts TypeScript direto no Node. |
| `vite` | ^8.0.0 | O empacotador do Storybook e do Vitest. |

## Os comandos

| Comando | Para quê |
| --- | --- |
| `npm run dev` | O styleguide em http://localhost:3000/styleguide, recarregando a cada mudança. |
| `npm run build` | O build de produção do Next (parte do gate). |
| `npm run start` | Serve o build de produção — é sobre ele que as varreduras medem. |
| `npm run storybook` | O catálogo de fichas em http://localhost:6006. |
| `npm run build-storybook` | O build estático do Storybook (o que o Chromatic publica). |
| `npm run typecheck` | Os tipos (`tsc --noEmit`). Parte do gate. |
| `npm run audit` | O medidor do sistema: contraste, tokens, cobertura, documentação. Mostra cada métrica. |
| `npm run audit:json` | O mesmo, em JSON (é de onde sai a tabela de contraste do REPORT.md). |
| `npm run audit:check` | O audit que reprova (sai com 1) se um limiar for violado. Parte do gate. |
| `npm run a11y` | O gate estático do A11Y.md e a conferência da tabela de contraste do REPORT.md. Parte do gate. |
| `npm run a11y:contraste` | Gera a tabela de contraste do REPORT.md a partir dos tokens. |
| `npm run lint` | O ESLint sobre `app` e `stories`. Parte do gate: 0 erro. |
| `npm run test` | As fichas em Chromium, com o axe e os testes de comportamento. Parte do gate. |
| `npm run test:watch` | O mesmo, em modo contínuo. |
| `npm run chromatic` | Publica no Chromatic (precisa do token; no CI). |
| `npm run figma:connect:parse` | Code Connect — Fase 2. |
| `npm run figma:connect:preview` | Code Connect — Fase 2. |
| `npm run figma:connect:dry-run` | Code Connect — Fase 2. |
| `npm run figma:connect:publish` | Code Connect — Fase 2. |
| `npm run figma:connect:create` | Code Connect — Fase 2. |

## O gate, antes de todo commit

O mesmo conjunto que o CI roda, na mesma ordem. Se um falhar, não commite.

```bash
npm run typecheck && npm run lint && npm run build && npm run audit:check && npm run a11y && npm run test
```

As regras de toda peça: cor só por token; `cn()` para as classes; `cva` para as variantes; `forwardRef` com `displayName`; `focus-visible:`; alvo de 44×44px; estado nunca só por cor; texto em pt-BR, inclusive `aria-label`. A acessibilidade segue o `docs/a11y/A11Y.md` (WCAG 2.2 AA) — veja o `AGENTS.md`.