PIV Digital - Static Site Generator v3.3.5

Este projeto foi migrado de um template estático Bootstrap Studio para um gerador de site estático customizado baseado em Node.js e EJS, com suporte a configuração dinâmica de marca via JSON.

Pré-requisitos

• Node.js instalado (v14+ recomendado).

Instalação

1. Clone o repositório.
2. Na raiz do projeto, você não precisa rodar npm install manualmente se não quiser. O arquivo se autoinstalará quando você rodar o npm run build ou outro comando pela primeira vez, graças a um script de hook prévio (check-deps.js).

Estrutura do Projeto

• brand_config.json: Arquivo de configuração principal (Cores, Fontes, Textos, Links).
• /src: Código fonte.
  • /assets:
    • /files:
      • /horizontal: Logos horizontais.
      • /vertical: Logos verticais.
      • /symbol: Símbolos da marca.
      • /favicon: Favicons.
    • /img/stationery: Arquivos de papelaria (cartões, envelopes, etc).
    • /img: Imagens gerais e de mood (moodheader, moodsite, etc).
    • /css: Estilos customizados e gerados.
  • /template: Arquivos de página .ejs.
  • /partials: Componentes reutilizáveis (header, footer).
• /public: Pasta gerada com o site final (não edite arquivos aqui).
• build.js: Script de construção do site.
  • OBS: Também gera automaticamente o arquivo [slugname]-identidade-visual.md na raiz para consumo de agentes de IA.
• deploy_mamp.js: Script de deploy local para MAMP.

Configuração da Marca (brand_config.json)

Este arquivo controla a identidade do site. Use-o para definir:

• Tema: Cores (primária, secundária, etc.) e Fontes (Google Fonts).
• Conteúdo: Textos específicos como Sobre, Visão, Missão, Valores e textos de uso de marca.
• Links: Sua URL oficial base (manualUrl), downloads de logo, papelaria e contato WhatsApp.
• Arquétipos: Definição dos arquétipos da marca.

Nota: As descrições e imagens dos arquétipos são obtidas dinamicamente de uma fonte externa (vanheber/arquetipos) durante o build. As imagens podem ser servidas através de CDN (Cloudflare) conforme definido na fonte.

Comandos Disponíveis

New Client (Scaffolding)

Cria automaticamente a estrutura inicial para um novo cliente.

npm run new-client nome-do-cliente

Este comando irá:

• Fazer backup do brand_config.json atual
• Criar novo brand_config.json a partir do template
• Configurar CLIENT_SLUG no deploy_mamp.js
• Gerar checklist personalizado de setup
• Exibir próximos passos

Importante: Após executar este comando, use o agente GEM para gerar o conteúdo textual do manual (ver .agent/prompts/PROMPT_GEM_BRAND_CONTENT.md).

Build (Construção)

Gera o site estático na pasta /public.

npm run build

Publicação Manual (FTP)

Após a geração do diretório /public, você precisará enviá-lo de forma manual pro servidor, geralmente acessando hospedaegens CPanel ou usando clientes FTP como o FileZilla. A pasta gerada contém a estrutura final para rodar em produção.

Desenvolvimento

1. Configuração: Edite brand_config.json para alterar dados do cliente.
2. Assets: Substitua as imagens em src/assets/img/brand, src/assets/img/stationery e src/assets/img mantendo os nomes de arquivo padrão (veja MANUAL.md).
3. Templates: Edite os arquivos .ejs em src/template se precisar alterar a estrutura.
4. Estilos:
   • theme.css: Gerado automaticamente (não edite).
   • custom.css: Para estilos manuais adicionais e controle de tema (Dark/Light).
5. Rode npm run build para testar ou gerar os arquivos finais em /public.

Manual de Operação - PIV Digital v3.3.5

Este manual descreve como manter, configurar e expandir o site PIV Digital.

1. Visão Geral

O site utiliza EJS para templates e um arquivo brand_config.json para centralizar as informações da marca. Isso permite gerar sites para diferentes clientes apenas alterando a configuração e os ativos de imagem.

2. Geração de Conteúdo com Agente GEM

IMPORTANTE: Antes de preencher o brand_config.json, o conteúdo textual (missão, visão, valores, tom de voz, defesa do conceito) deve ser gerado com auxílio do agente GEM (Gerador de Estratégia de Marca) do cliente.

Por que usar o GEM?

• Alinhamento estratégico: O GEM conhece a identidade profunda da marca
• Consistência de tom: Garante copywriting alinhado com a personalidade da marca
• Arquétipos corretos: Sugere arquétipos baseados no posicionamento
• Copywriting profissional: Gera textos técnicos, não publicitários

Como usar

1. Localize o prompt: .agent/prompts/PROMPT_GEM_BRAND_CONTENT.md
2. Preencha o briefing do cliente no prompt
3. Envie o prompt completo ao agente GEM do cliente
4. Copie o JSON retornado e cole no brand_config.json

Veja o arquivo de prompt para instruções detalhadas.

3. Configuração da Marca (brand_config.json)

Este é o coração do sistema. Nele você define:

• Theme:
  • Colors (theme.colors): Hex codes para primary, secondary, tertiary, info, success, warning e danger. O sistema gera automaticamente o CSS com variáveis Bootstrap.
  • Fonts: URLs e nomes de fontes do Google Fonts.
• Content:
  • Textos para as seções "Sobre", "Visão", "Missão", "Valores".
  • Defesa do conceito da marca e arquétipos.
• Links:
  • manualUrl: URL base do manual hospedado (ex: https://piv.agenciaquadri.com/cliente). Usado no header/footer e gerado no documento de consumo para IAs.
  • O sistema gera automaticamente um ZIP com todos os ativos da pasta assets/files.
  • Link de download de papelaria pode ser configurado se for externo, ou usar o zip geral.
  • Número e mensagem do WhatsApp.

Nota: Campos comuns (como títulos de seções padrão) são fixos nos templates e não precisam estar no JSON.

Paleta de Cores (colors.primary)

As cores da paleta visual da marca — primária, secundária e (opcionalmente) terciária — são definidas no array colors.primary. Cada entrada usa o campo codes como objeto estruturado com os seguintes campos:

"codes": {
    "cmyk":     "C50 M30 Y0 K50",
    "pantoneC": "Pantone 7699 C",
    "pantoneU": "Pantone 7699 U"
}

Cores Funcionais (theme.colors)

As cores funcionais (info, success, warning, danger) são definidas apenas como hex em theme.colors. Elas não possuem entradas de CMYK ou Pantone — são de uso exclusivo em interfaces digitais (badges, alertas, ícones informativos).

Elevando uma Cor Funcional a Terciária

Se uma cor funcional for escolhida como cor terciária da paleta, ela deve ganhar uma entrada própria em colors.primary com o objeto codes completo:

{
    "name": "Cor terciária",
    "class": "bg-tertiary",
    "textClass": "text-dark",
    "codes": {
        "cmyk":     "C0 M35 Y70 K0",
        "pantoneC": "Pantone 7409 C",
        "pantoneU": "Pantone 7409 U"
    }
}

O template colors.ejs detecta automaticamente se codes é um objeto e renderiza os campos da cor. O hex em theme.colors.tertiary continua sendo usado para gerar o CSS do tema.

Ativos do Logotipo (logotype.assets)

As variações de logotipo exibidas na página de Identidade Visual são configuradas na seção logotype.assets. Isso permite alternar quais arquivos são exibidos e quais classes de fundo são aplicadas sem mexer no código do template.

"assets": {
    "horizontal": [
        { "bgClass": "bg-primary", "file": "lg-hz-color-inverted.webp", "title": "BG Primário", "key": "primary_bg" },
        ...
    ],
    "vertical": [
        { "bgClass": "bg-primary", "file": "lg-vt-color-inverted.webp", "title": "BG Primário", "key": "primary_bg" },
        ...
    ],
    "gradients": [
        { "id": 1, "symbol": "sy-color-inverted.webp", "title": "Gradient 1" },
        ...
    ]
}

Arquétipos

Os arquétipos da marca são definidos no brand_config.json na seção archetypes. Durante o build, o sistema busca automaticamente as descrições, termos e imagens de cada arquétipo da fonte oficial:

Fonte: vanheber/arquetipos

As descrições são copiadas literalmente e as imagens são servidas via CDN (https://img.agenciaquadri.com.br/cardscolor/), garantindo performance e centralização dos ativos.

4. Gestão de Ativos (Imagens)

Para trocar a identidade visual, substitua os arquivos nas pastas abaixo mantendo exatamente os mesmos nomes de arquivo:

Logos Horizontais (src/assets/files/horizontal/)

• lg-hz-color.webp - Logo horizontal colorida
• lg-hz-color-inverted.webp - Logo horizontal colorida (fundo escuro)
• lg-hz-bw.webp - Logo horizontal preto e branco

Logos Verticais (src/assets/files/vertical/)

• lg-vt-color.webp - Logo vertical colorida
• lg-vt-color-inverted.webp - Logo vertical colorida (fundo escuro)
• lg-vt-bw.webp - Logo vertical preto e branco

Símbolos (src/assets/files/symbol/)

• sy-color.webp - Símbolo colorido
• sy-color-inverted.webp - Símbolo colorido (fundo escuro)

Papelaria (src/assets/img/stationery/)

• business-card-front.webp - Frente do cartão de visita
• business-card-back.webp - Verso do cartão de visita
• letterhead.webp - Papel timbrado
• envelope-dl-front.webp - Frente do envelope DL
• envelope-dl-back.webp - Verso do envelope DL
• envelope-c4-front.webp - Frente do envelope C4
• envelope-c4-back.webp - Verso do envelope C4

Mood e Imagens Gerais (src/assets/img/)

• moodheader.webp - Imagem principal no topo da página Mood
• moodsite.webp - Imagem secundária de destaque
• moodimg01.webp, moodimg02.webp, etc. - Galeria de mood (numeração sequencial)

Favicons (src/assets/files/favicon/)

• favicon-light.png - Favicon para tema claro
• favicon-dark.png - Favicon para tema escuro

5. Adicionando Nova Página

1. Crie um novo arquivo .ejs na pasta src/template (ex: nova-pagina.ejs).
2. Use a estrutura base:

   <%- include('partials/header', { title: 'Título da Página' }) %>
   <div class="container">
       <!-- Seu conteúdo aqui -->
       <%# Use dados do config assim: %>
       <h1><%= brand.content.about.mission %></h1>
   </div>
   <%- include('partials/footer') %>
   

3. Se necessário, adicione a página ao menu editando src/partials/header.ejs.
4. Execute npm run build para gerar a nova página em /public.

6. Estilos e CSS

• Automático: O arquivo assets/css/theme.css é gerado a cada build com base no brand_config.json. Ele define variáveis como --bs-primary, --bs-font-sans-serif, etc.
• Manual: Para ajustes finos que não dependem da marca (layout, espaçamentos), use src/assets/css/custom.css.
• Bootstrap: Continue usando as classes utilitárias do Bootstrap 5.3 (text-center, p-4, d-flex, etc.).

7. Build e Deploy

IMPORTANTE: Sempre execute o build ANTES do deploy.

Passo 1: Construir o Site

Gera os arquivos finais na pasta /public com base no brand_config.json e templates EJS. Também injeta na raiz o manifesto Markdown <slugname>-identidade-visual.md contendo as diretrizes puras da marca para consumo do Agente GEM/IA.

npm run build

Passo 2: Publicação (Manual / FTP)

Você não precisa mais informar o caminho do build. A pasta /public gerada contém a estrutura final e isolada para o projeto que foi "buildado". Caso deseje colocar no ar, basta fazer o upload do conteúdo gerado nesta pasta public via FTP para o Client.

8. Checklist - Novo Cliente

Ao criar um novo repositório para um cliente:

• 1. Preparação

  • Clonar/Fork do repositório template PIVdigital
  • Renomear repositório com nome do cliente
  • Com as novas mudanças em check-deps.js, usar os comandos npm instalará automaticamente as dependências na primeira execução.

• 2. Configuração

  • Editar brand_config.json:
  • Cores do tema (theme.colors) — hex de todas as cores incluindo funcionais

    • Paleta visual (colors.primary) — objeto codes com cmyk, hex, pantoneC e pantoneU para cada cor

    • Fontes (theme.fonts)

    • Conteúdos (about, vision, mission, values)

    • Arquétipos escolhidos (archetypes)

    • Links (WhatsApp, downloads)

• 3. Ativos - Logos

  • src/assets/files/horizontal/ (3 arquivos)
  • src/assets/files/vertical/ (3 arquivos)
  • src/assets/files/symbol/ (2 arquivos)
  • src/assets/files/favicon/ (2 arquivos)

• 4. Ativos - Papelaria

  • src/assets/img/stationery/ (7 arquivos)

• 5. Ativos - Mood

  • src/assets/img/moodheader.webp
  • src/assets/img/moodsite.webp
  • src/assets/img/moodimg01.webp, moodimg02.webp, etc.

• 6. Build e Teste

  • Executar npm run build
  • Verificar pasta /public gerada
  • Testar site localmente abrindo o index.html da pasta public no seu navegador ou via live server.

• 7. Controle de Versão

  • Commit inicial com configurações do cliente
  • Push para repositório remoto

9. Sistema de Segurança e Backup 🛡️

Para prevenir a perda de arquivos não commitados (especialmente arquivos binários .af ou artes em andamento), o projeto inclui um sistema de backup automático integrado ao ciclo de vida de desenvolvimento.

Funcionalidades

O sistema cria arquivos ZIP compactados na pasta .backups/ na raiz do projeto, contendo o estado atual do desenvolvimento. Cada backup inclui:

• A pasta src/ (todos os ativos, templates e arquivos binários).
• O arquivo brand_config.json (configurações da marca).
• O arquivo package.json.

Gatilhos Automáticos

O backup é executado automaticamente, sem intervenção do usuário, nos seguintes momentos:

• Pre-Build: Ao executar npm run build, o sistema garante uma cópia de segurança antes do processamento.
• Pre-New-Client: Ao iniciar o scaffold de um novo cliente com npm run new-client.

Backup Manual

Você pode forçar a criação de um ponto de segurança a qualquer momento executando o comando:

npm run backup

Retenção e Restauração

1. Rotação: O sistema mantém apenas os 10 backups mais recentes para economizar espaço em disco. Backups antigos são excluídos automaticamente.
2. Localização: Os arquivos ZIP estão na pasta .backups/ (ignorada pelo Git).
3. Restauração: Para restaurar um estado anterior, localize o arquivo ZIP com o timestamp desejado e extraia seu conteúdo sobre a raiz do projeto, substituindo as pastas e arquivos correspondentes.

[!TIP] Os arquivos .af (Affinity Designer) localizados dentro da estrutura src/ são pesados e críticos. Este sistema garante que, mesmo sem commit, você tenha versões históricas das suas artes.

10. Sincronização com o Template Base 🔄

Projetos derivados (clientes) podem ser atualizados com as melhorias mais recentes, correções de bugs e novos componentes do repositório oficial pivdigital sem perder as personalizações locais.

O que é sincronizado?

O sistema de sincronização realiza uma fusão seletiva:

• Atualiza: build.js, lógica de scripts, templates EJS base (src/template/ e src/partials/), documentação e configurações de IA (.agent/).
• Protege: brand_config.json (seus dados), src/assets/files/, src/assets/img/ e src/assets/css/custom.css (seu estilo).
• Mescla: package.json (garante que novas dependências do template sejam instaladas mas as do cliente permaneçam).

Como atualizar um cliente

1. Abra o terminal na pasta do projeto do cliente.
2. Execute o comando de sincronização:

   npm run sync-template
   

3. O script irá clonar o projeto oficial, comparar e aplicar as melhorias.
4. Após o script terminar, execute npm install para garantir que novas bibliotecas foram instaladas.
5. Verifique as mudanças e faça o build de teste:

   npm run build
   

[!CAUTION] A sincronização sempre faz um backup automático via npm run backup antes de começar, mas é recomendado revisar os arquivos alterados com git diff antes de commitar as atualizações.