Guia de Migração · MGConnect Design System

Este documento descreve como integrar uma UI ao MGConnect Design System (DS) hospedado em https://designsystem.mgconnect.online. Destinado a times que mantêm UIs em VMs distintas do servidor principal — por exemplo, connect.mgtech360.com.br.

1. Setup mínimo (2 linhas de HTML)

Nenhum build, pacote NPM ou deploy é necessário. O DS é um arquivo CSS público com CORS aberto. Adicione duas linhas:

<head>
  ...
  <link rel="stylesheet" href="https://designsystem.mgconnect.online/mgconnect.css">
</head>

<body class="mgc-app">
  ...
</body>

<link> — carrega tokens (cores, espaçamentos, sombras) + classes (mgc-btn, mgc-card, mgc-modal-*, etc.).
body class="mgc-app" — ativa o tema global: font-family, background (gradient), color. Sem essa classe, o DS fornece apenas os componentes opt-in (sem mexer no body — útil para integrar em páginas existentes sem invadir o tema).

CORS: o CSS é servido com Access-Control-Allow-Origin: *. Qualquer origem pode consumir.

2. Convenções fundamentais

Todas as classes do DS usam prefixo mgc- — coexiste com CSS legado durante migração.
Dark mode é ativado via <body class="dark-mode">. O DS define overrides automaticamente. Não use dark sem o sufixo -mode — convenção compartilhada com as outras UIs.
Modais usam .is-open para abrir (em vez de style.display = 'block'): el.classList.add('is-open').
Cores duras (#hex) ficam apenas em casos específicos. Para qualquer cor de tema, use var(--mgc-*) (lista em §9).

3. Shell (header / main / footer)

<header class="mgc-header">
  <div class="mgc-logo-wrap">
    <img class="mgc-logo" src="/logo.png" alt="MGConnect">
    <span class="mgc-brand">MGConnect</span>
  </div>
  <div class="mgc-title"><span>🔐 Nome da App</span></div>
  <button id="btnDark" class="mgc-icon-btn" onclick="toggleDark()">🌙</button>
</header>

<main class="mgc-main">
  ...
</main>

<footer class="mgc-footer">
  App vN.N — algum subtítulo
</footer>

Convenção dos títulos: {emoji} {Nome} {Versão} — ex.: ⚙️ Service Buddy v1.2, 👤 Admin v1.0.

4. Formulários

Elemento	Classe	Variante
<fieldset>	`mgc-fieldset`	—
<legend>	`mgc-legend`	—
<label>	`mgc-label`	—
<input type="text">	`mgc-input`	`mgc-input--mono` (monospace), `mgc-input--error`
<select>	`mgc-select`	`mgc-select--error`
<textarea>	`mgc-textarea`	—

<fieldset class="mgc-fieldset">
  <legend class="mgc-legend">🔢 Identificar</legend>
  <label class="mgc-label">numSerie</label>
  <input class="mgc-input mgc-input--mono" type="text" maxlength="10">
</fieldset>

5. Botões

Classe	Uso
`mgc-btn`	Base (neutro outline)
`mgc-btn mgc-btn--primary`	Ação primária (escuro / contraste alto)
`mgc-btn mgc-btn--success`	Confirmar, criar, ativar (verde)
`mgc-btn mgc-btn--warning`	Operação reversível com cuidado (laranja)
`mgc-btn mgc-btn--danger`	Destrutivo, irreversível (vermelho)
`mgc-btn mgc-btn--ghost`	Cancelar, voltar (transparente)
`mgc-btn--sm` / `--xs` / `--lg`	Modificadores de tamanho
`mgc-icon-btn`	Botão só com ícone (header, toolbar)
`mgc-icon-btn--ghost-danger`	Ícone destrutivo discreto (ex: 🗑️ em linha de tabela)

<button class="mgc-btn mgc-btn--primary">Entrar</button>
<button class="mgc-btn mgc-btn--ghost">Cancelar</button>
<button class="mgc-btn mgc-btn--danger">Apagar</button>
<button class="mgc-btn mgc-btn--success mgc-btn--sm">Salvar+Enviar</button>

Vermelho ≠ decorativo. --danger é reservado para ações que não podem ser desfeitas. Use --warning (laranja) para "atenção, mas reversível".

6. Modais

Estrutura padrão — overlay full-screen + content centrado. Tamanhos --sm (~480px), --md (~640px), ou full-screen padrão.

<div id="meuModal" class="mgc-modal-overlay" role="dialog" aria-modal="true">
  <div class="mgc-modal-content mgc-modal-content--md">
    <h3>Título do Modal</h3>
    <p>Conteúdo...</p>
    <div class="mgc-modal-actions">
      <button class="mgc-btn mgc-btn--ghost" onclick="fechar()">Cancelar</button>
      <button class="mgc-btn mgc-btn--primary" onclick="confirmar()">Confirmar</button>
    </div>
  </div>
</div>

<script>
function abrir() { document.getElementById('meuModal').classList.add('is-open'); }
function fechar() { document.getElementById('meuModal').classList.remove('is-open'); }
</script>

7. Cards e Grid

<div class="mgc-grid">
  <a class="mgc-card is-interactive" href="...">
    <div class="mgc-card-head">
      <span>🗺️</span>
      <span class="status-dot up"></span>
    </div>
    <div class="mgc-card-title">MGConnect View</div>
    <div>Descrição do card...</div>
  </a>
  ...
</div>

mgc-grid: grid responsivo (auto-fill, mínimo 240px).
mgc-grid--mini: grade densa para monitoramento.
mgc-card.is-interactive: cursor pointer + hover translateY.
mgc-minicard: variante compacta (5-7px padding) para alta densidade.

8. Dark mode

<script>
function toggleDark(){
  const d = document.body.classList.toggle('dark-mode');
  document.getElementById('btnDark').textContent = d ? '☀️' : '🌙';
  localStorage.setItem('dark', d ? '1' : '0');
}
if (localStorage.getItem('dark') === '1') {
  document.body.classList.add('dark-mode');
  document.getElementById('btnDark').textContent = '☀️';
}
</script>

O DS define todos os tokens (--mgc-bg, --mgc-surface, --mgc-text, etc.) com valores diferentes dentro de body.dark-mode. Qualquer componente que use var(--mgc-*) respeita o tema automaticamente.

9. Tokens (variáveis CSS)

Token	Uso
`--mgc-bg`	Cor de fundo da página
`--mgc-bg-gradient`	Gradient do body (tema)
`--mgc-surface` / `--mgc-surface-2`	Superfícies (cards, painéis); -2 é mais sutil
`--mgc-card-bg`	Background específico de card
`--mgc-input-bg`	Background de input/select/textarea
`--mgc-text` / `--mgc-text-2` / `--mgc-text-3` / `--mgc-text-faint`	Hierarquia de texto (forte → fraco)
`--mgc-text-on-accent`	Texto sobre fundo colorido (sempre branco no light; ver §12 para dark)
`--mgc-text-link`	Cor de links
`--mgc-border` / `--mgc-border-subtle` / `--mgc-border-strong`	Bordas
`--mgc-success` / -tint / -text	Verde (confirmações)
`--mgc-danger` / -tint / -text	Vermelho (destrutivo, erro)
`--mgc-warning` / -tint / -text	Laranja (atenção)
`--mgc-info` / -tint / -text	Azul (informação)
`--mgc-neutral` / -tint / -text	Cinza neutro
`--mgc-radius-xs/sm/md/lg/xl/2xl/pill`	Raios de borda padronizados
`--mgc-space-0..10`	Escala de espaçamento
`--mgc-shadow-sm/md/lg/modal`	Sombras padrão
`--mgc-font-sans` / `--mgc-font-mono`	Famílias de fonte
`--mgc-text-xs..3xl`	Tamanhos de fonte
`--mgc-weight-medium/bold`	Pesos de fonte
`--mgc-trans-fast/slow`	Durações de transição

10. Exemplo antes / depois

Antes (CSS local hardcoded)

<style>
  body { background:#f0f2f5; font-family:Segoe UI,sans-serif; }
  header { background:linear-gradient(90deg,#2f3640,#718093); color:#fff; padding:10px 40px; }
  button { background:#40739e; color:#fff; padding:6px 12px; border-radius:6px; border:none; }
</style>
<body>
  <header>
    <h1>Minha App</h1>
  </header>
  <button onclick="salvar()">Salvar</button>
</body>

Depois (com DS)

<link rel="stylesheet" href="https://designsystem.mgconnect.online/mgconnect.css">

<body class="mgc-app">
  <header class="mgc-header">
    <div class="mgc-title"><span>Minha App</span></div>
  </header>
  <main class="mgc-main">
    <button class="mgc-btn mgc-btn--success" onclick="salvar()">Salvar</button>
  </main>
</body>

~30 linhas de CSS local viram uma linha de link. Estilo idêntico ao das demais UIs MGConnect (Albert View, Admin, Service, Server, Portal, Config Tool).

11. Workflow de mudanças e cache

Cache HTTP do CSS: max-age=300 (5 min). Mudanças propagam automaticamente em até 5 min nas UIs que linkam.
Para forçar atualização imediata em uma UI específica, usar query string de versão no link: ?v=20260524.
Quando precisar mudar algo no DS, comunicar com mantenedores das outras UIs antes — qualquer mudança aqui propaga em todas. Exemplo de mudança coordenada recente: body{} global virou opt-in via body.mgc-app em 2026-05-23.
Versionamento: o DS hoje é "live" (sem release tag). Se precisar versão imutável, considerar usar tag git + serving por path versionado (/v1.2/mgconnect.css) — não está implementado.

12. Casos especiais / FAQ

Como integrar em uma UI grande que já tem CSS rico (legado pesado)?

Não use body class="mgc-app". Linka apenas o CSS para herdar tokens. Aliase os tokens locais no :root da sua UI: --bg: var(--mgc-bg, fallback);. Assim a UI consome cores do DS sem deixar o DS controlar o body dela. Veja como a Albert View faz (mesma VM, /var/www/albert-view/albertviewui_v_2_0.html).

Dark mode quebrou meu visual

Provavelmente um color: #xxx hardcoded em style="..." inline fica sobre fundo escuro. Solução pontual: adicione override no seu CSS local: body.dark-mode #meuId [style*="color:#xxx"] { color: var(--mgc-text) !important; }.

O CSS atualizou mas o browser não pegou

Hard refresh: Ctrl+Shift+R (Chrome/Firefox) ou Cmd+Shift+R (macOS). Ou aguarde 5 minutos pelo cache HTTP expirar.

Posso baixar e hospedar o CSS na minha VM?

Sim, baixe https://designsystem.mgconnect.online/mgconnect.css e sirva local. Cuidado: você perde o auto-update. Recomendado apenas como fallback offline. Cópia oficial fica nesta VM em /var/www/mgconnect-ds/mgconnect.css.

E se a VM do DS cair?

As UIs perdem o styling até o serviço voltar. Mitigação opcional: hospedar uma cópia de fallback na sua VM, carregada por onerror:

<link rel="stylesheet" href="https://designsystem.mgconnect.online/mgconnect.css"
      onerror="this.onerror=null;this.href='/local/mgconnect.css'">

mgc-btn--primary tem comportamento estranho no dark

Fix histórico (2026-05-23): no dark, mgc-btn--primary tem color: var(--mgc-bg) para contrastar com o fundo claro do botão. Se você definir color: inline, override esse comportamento.

Mantido por MGtech · CSS fonte: /var/www/mgconnect-ds/mgconnect.css · Última revisão: 2026-05-23