faculdadephorte.edu.br
Para quem desenvolve
ProntoO 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. As versões são lidas do
package.json: o que está aqui é o que está instalado.1. 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`. |
No editor (opcional): 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`.
2. Clonar e rodar
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 git remote rename mantém o caminho de volta para a origem — o processo inteiro de clone e de receber correções está em docs/processo-de-clone.md.
3. 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. |
4. 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. |
5. O gate, antes de todo commit
O mesmo conjunto que o CI roda, na mesma ordem. Se um falhar, não commite: sem PR, este bloco é o único aviso antes da main.
npm run typecheck && npm run lint && npm run build && npm run audit:check && npm run a11y && npm run test