🧩 Guia de Integração do Design System (@ticket-and-go/tag-uikit)

Este documento explica como instalar e configurar o Design System local (Front-tag-ui) em qualquer projeto que o utilize, sem precisar publicar no npm.

📦 1. Instalação Local

No projeto que vai consumir o design system (exemplo: ticketandgo-frontend-consumidor-v2), execute:

npm install file:../Front-tag-ui

Isso cria uma dependência direta para a pasta local do design system e copia o build para dentro de node_modules/@ticket-and-go/tag-uikit.

⚠️ O caminho ../Front-tag-ui deve apontar para onde está o design system na sua máquina.

📁 Estrutura Recomendada

Os dois projetos devem estar na mesma pasta para que o caminho relativo funcione corretamente:

/Desktop/tag/
├── Front-tag-ui/
│   └── ...
└── ticketandgo-frontend-consumidor-v2/
    └── ...

💡 Também é possível ter vários projetos na mesma pasta, desde que o caminho relativo continue correto.

Exemplo com quatro projetos:

/Desktop/tag/
├── Front-tag-ui/
│   └── ...
├── ticketandgo-frontend-consumidor-v2/
│   └── ...
├── ticketandgo-dashboard/
│   └── ...
└── ticketandgo-backoffice/
    └── ...

🧩 2. Garantindo a Versão Correta do Node.js

Antes de rodar os comandos, certifique-se de estar usando a mesma versão do Node.js configurada no design system.
O projeto utiliza o NVM (Node Version Manager) para padronizar versões.

Verifique o arquivo .nvmrc no design system e use os comandos:

nvm install
nvm use

• nvm install: instala a versão correta, caso ainda não esteja disponível.
• nvm use: ativa essa versão para o terminal atual, garantindo compatibilidade durante o build e a instalação.

🛠️ 3. Build do Design System

Antes de instalar no projeto consumidor, é obrigatório gerar o build:

cd ../Front-tag-ui
npm run build

Esse comando cria a pasta dist/ com os arquivos necessários.

🔧 4. Importações no Projeto Consumidor

CSS Global

No seu arquivo src/index.css ou src/app/globals.css, importe o CSS do design system:

@import '@ticket-and-go/tag-uikit/styles.css';

Componentes React

Importe qualquer componente diretamente do pacote:

import { Button, Dropdown, Typography } from '@ticket-and-go/tag-uikit'

Utilitários

import { cn } from '@ticket-and-go/tag-uikit/utils'

Tailwind Preset

No tailwind.config.ts do seu projeto:

import twTagPreset from '@ticket-and-go/tag-uikit/tailwind-preset'

export default {
  presets: [twTagPreset],
  content: ['./src/**/*.{js,ts,jsx,tsx,mdx}', './app/**/*.{js,ts,jsx,tsx,mdx}'],
}

🔁 5. Atualizando o Design System

Se você fizer alterações no design system:

cd ../Front-tag-ui
npm run build

Depois, volte para o projeto que o consome e rode novamente:

npm install file:../Front-tag-ui

Isso atualiza a dependência local com a nova versão.

🚀 6. Problemas Comuns

| Erro | Causa | Solução | | ------------------------------------------------------------ | ------------------------------------------- | --------------------------------------------------------- | | Module not found: Can't resolve '@ticket-and-go/tag-uikit' | Build não gerado ou pasta dist ausente | Execute npm run build antes da instalação | | Can't resolve './styles/colors.css' | Pasta /styles não foi copiada para dist | Verifique tsup.config.ts e rode o build novamente | | Tipos TypeScript ausentes | Arquivo index.d.ts não gerado | Confirme que dts: true está ativado no tsup.config.ts |

🧠 Dica

Para evitar reinstalar manualmente, adicione um script no package.json do projeto consumidor:

"scripts": {
  "update:ds": "cd ../Front-tag-ui && npm run build && cd - && npm install file:../Front-tag-ui"
}

Assim, basta rodar:

npm run update:ds

✅ Pronto!

Agora seu projeto consome o Design System localmente com suporte a:

• CSS global
• Preset do Tailwind
• Componentes React
• Utilitários (cn, etc.)

📦 7. Atualizando a Versão Publicada no npm (@ticket-and-go/tag-uikit)

Esta seção explica como publicar uma nova versão do Design System no npm, utilizando o fluxo padrão via GitHub Releases.

⚠️ Importante: a versão publicada no npm sempre deve bater com a versão definida no package.json.

🔁 Passo 1 – Atualizar a versão no package.json

Na sua branch, altere a versão no arquivo package.json:

{
  "name": "@ticket-and-go/tag-uikit",
  "version": "0.0.44"
}

➡️ A nova versão sempre deve ser maior que a versão atual publicada (exemplo: de 0.0.43 para 0.0.44).

Depois disso:

Faça commit da alteração

Suba sua branch

Faça o merge da branch na main

🚀 Passo 2 – Criar uma nova Release no GitHub

No repositório Front-tag-ui, siga os passos abaixo:

No menu lateral direito, clique em Releases

Clique em Draft a new release

🏷️ Passo 3 – Criar a tag da nova versão

No campo Create new tag:

Se a última versão foi v0.0.43

Crie a nova tag como:

v0.0.44

📌 Regras importantes:

A tag deve começar com v

O número da tag deve ser exatamente o mesmo do package.json

Selecione a branch main como target da release.

📝 Passo 4 – Gerar as Release Notes

Após selecionar a tag:

Clique em Generate release notes

O GitHub irá preencher automaticamente:

O que mudou

PRs incluídos

Você pode editar o texto se quiser, mas não é obrigatório.

📤 Passo 5 – Publicar a Release

Por fim:

Verifique se a opção Set as the latest release está marcada

Clique em Publish release

✅ Ao publicar a release:

O GitHub cria a tag oficial

A nova versão é publicada automaticamente no npm

✅ Resultado Final

Após concluir todos os passos:

A nova versão estará disponível no npm.