CSS e JavaScript personalizados

Esta página mostra um exemplo em um site de demonstração chamado Harbor. O cabeçalho recebe o logotipo e as cores do Harbor, além de dois links extras, e um botão flutuante Ask AI fica no canto inferior direito. Você pode copiar os arquivos como estão e depois substituir o logotipo e as cores pelos seus.

As capturas de tela mostram a interface em inglês.

O que muda neste cabeçalho

Por padrão, o cabeçalho do Jam se mistura à página. No modo claro, ele é transparente e mostra o gradiente suave ao fundo. No modo escuro, tem o mesmo tom quase preto de todo o resto. Seus botões têm cantos levemente arredondados. A versão do Harbor muda quatro coisas:

• A barra é azul-marinho também no modo escuro.
• Uma linha laranja fina percorre a borda inferior.
• A caixa de pesquisa, Ask AI e Book a demo são botões em formato de pílula.
• O logotipo branco do Harbor substitui o padrão.

As alterações usam CSS e um arquivo de logotipo. O próprio cabeçalho do Jamdesk não é alterado. A pesquisa, o Ask AI, o seletor de tema e o menu para dispositivos móveis continuam funcionando como antes.

O exemplo usa estes arquivos no projeto:

harbor-docs/
├── docs.json              ← logo, header links and brand colors
├── style.css              ← header and button styles
├── script.js              ← creates the Ask AI button
└── images/
    └── harbor-logo.svg    ← white logo for the navy header

Comece com docs.json

A primeira parte não exige código. O logotipo, as cores, os links do cabeçalho e o botão Book a demo ficam em docs.json:

{
  "logo": {
    "light": "/images/harbor-logo.svg",
    "dark": "/images/harbor-logo.svg"
  },
  "colors": {
    "primary": "#C2410C",
    "light": "#D9480F",
    "dark": "#9A3412"
  },
  "navbar": {
    "links": [
      { "label": "Blog", "href": "https://example.com/blog" },
      { "label": "Status", "href": "https://example.com/status" }
    ],
    "primary": {
      "type": "button",
      "label": "Book a demo",
      "href": "https://example.com/demo"
    }
  }
}

O logotipo é branco. O cabeçalho é sempre azul-marinho. Use o mesmo arquivo para light e dark.

O Jamdesk usa sua cor primary no botão Book a demo, no item ativo da barra lateral e nos links. No modo escuro, usa a cor light. Escolha um tom escuro o suficiente para que o texto branco no botão continue fácil de ler. Consulte Links de navegação para ver todas as opções da navbar.

Estilize o cabeçalho

O texto, as bordas, a caixa de pesquisa e o arredondamento dos cantos do cabeçalho são definidos por variáveis CSS. Defina essas variáveis dentro do cabeçalho para alterar somente essa área:

/* header[data-has-tabs] matches the site header only.
   A plain `header` selector would also match the title
   block at the top of every page. */
header[data-has-tabs] {
  --header-top: #0f1d3a;
  --header-bottom: #1b2f5b;
  --header-stripe: #f97316;
  --color-text-primary: #ffffff;
  --color-text-secondary: #cbd5e1;
  --color-text-tertiary: #cbd5e1;
  --color-text-muted: #94a3b8;
  --color-bg-primary: #0f1d3a;
  --color-bg-secondary: rgba(255, 255, 255, 0.08);
  --color-bg-hover: rgba(255, 255, 255, 0.16);
  --color-border: rgba(255, 255, 255, 0.16);
  /* Rounds the search box, Ask AI and buttons into pills */
  --radius-md: 999px;
  --radius-lg: 999px;
}

html.dark header[data-has-tabs] {
  --header-top: #0a1328;
  --header-bottom: #13234a;
  --color-bg-primary: #0a1328;
}

/* Some themes keep the header background transparent on
   purpose, so paint the color on a layer behind it. */
header[data-has-tabs]::before {
  content: "";
  position: absolute;
  inset: 0 -24px; /* reach past the 16-24px page gutter */
  z-index: -1;
  background: linear-gradient(
    90deg, var(--header-top), var(--header-bottom)
  );
  border-bottom: 3px solid var(--header-stripe);
}

/* The sparkle icon uses the accent color, which is hard to
   see on navy, so give it the stripe color instead */
header[data-has-tabs] .fa-sparkles {
  color: #fdba74;
}

O azul-marinho fica em uma camada ::before porque o tema Jam define o background do cabeçalho como none com !important. Uma regra background normal no cabeçalho não teria efeito. A camada fica atrás do conteúdo do cabeçalho. Ela funciona em todos os temas.

Definir --radius-md e --radius-lg como 999px transforma os botões do cabeçalho em pílulas. A alteração fica restrita a header[data-has-tabs]. Os cartões e blocos de código da página mantêm os cantos habituais.

O ícone Ask AI no cabeçalho usa a cor de destaque. Essa cor fica difícil de ver no azul-marinho. A última regra o deixa laranja-claro.

O Jamdesk adiciona a classe dark a <html> no modo escuro. O bloco html.dark deixa o azul-marinho um pouco mais escuro nesse modo:

Adicione um botão flutuante Ask AI

Seu script adiciona um <button> comum à página. Ao clicar nele, o script envia Ctrl+I, o atalho de teclado que abre e fecha o painel de chat. O botão Ask AI no cabeçalho faz o mesmo.

(function () {
  if (document.getElementById('ask-ai-fab')) return;

  var button = document.createElement('button');
  button.id = 'ask-ai-fab';
  button.type = 'button';

  // Jamdesk loads Font Awesome, so its icons are available here
  var icon = document.createElement('i');
  icon.className = 'fa-solid fa-sparkles';
  icon.setAttribute('aria-hidden', 'true');
  button.append(icon, ' Ask AI');

  button.addEventListener('click', function () {
    // Same as pressing Ctrl+I / Cmd+I: toggles the chat panel
    var shortcut = { key: 'i', ctrlKey: true, bubbles: true };
    document.dispatchEvent(new KeyboardEvent('keydown', shortcut));
  });

  document.body.appendChild(button);
})();

Depois, adicione os estilos do botão a style.css:

#ask-ai-fab {
  position: fixed;
  right: 24px;
  bottom: 24px;
  z-index: 40; /* below the header, search and mobile menu */
  display: inline-flex;
  align-items: center;
  gap: 8px;
  padding: 12px 18px;
  border: 0;
  border-radius: 999px;
  background: #c2410c;
  color: #fff;
  font: inherit;
  font-weight: 600;
  box-shadow: 0 6px 20px rgba(15, 29, 58, 0.25);
  cursor: pointer;
}

#ask-ai-fab:hover {
  background: #9a3412;
}

#ask-ai-fab:focus-visible {
  outline: 2px solid #f97316;
  outline-offset: 2px;
}

/* Hide the button while the chat panel is open. On mobile
   the closed panel stays in the page with data-open="false",
   so exclude that case. */
body:has([data-chat-panel]:not([data-open="false"])) #ask-ai-fab {
  display: none;
}

@media (max-width: 767px) {
  #ask-ai-fab {
    right: 16px;
    bottom: 16px;
  }
}

Em celulares, o botão fica a 16px das bordas. O chat aberto cobre a maior parte da tela. O botão fica oculto até o chat ser fechado:

O chat com IA precisa estar ativado para que o botão funcione. Se chat.enabled estiver definido como false em docs.json, clicar no botão não fará nada. Nesse caso, não adicione o botão.

Um widget de suporte, como Crisp ou Intercom, provavelmente também fica no canto inferior direito. Mantenha os dois separados usando left: 24px em vez de right em #ask-ai-fab. Ou aumente bottom para colocar o botão acima do widget.

Execute o código após cada mudança de página

Seu script é executado uma vez, quando um visitante abre o site pela primeira vez. Ao clicar em um link na documentação, o conteúdo da página é trocado sem recarregá-la. O script não é executado novamente. O botão Ask AI não é afetado: ele está anexado a <body>, que permanece no lugar.

O código que lê ou altera o conteúdo da página precisa saber quando ela muda. Este trecho observa a coluna principal e verifica se o URL mudou. Coloque-o no mesmo script.js, abaixo do código do botão:

(function () {
  var lastPath = location.pathname;
  var main = document.getElementById('main-content') || document.body;

  function onPageChange() {
    // Your per-page code goes here
    console.log('Now on', location.pathname);
  }

  new MutationObserver(function () {
    if (location.pathname === lastPath) return;
    lastPath = location.pathname;
    onPageChange();
  }).observe(main, { childList: true, subtree: true });
})();

onPageChange é executada uma vez para cada página nova, seja quando o visitante clica em um link da barra lateral, usa a pesquisa ou pressiona o botão Voltar.

Seletores a usar

Os nomes de classe do Jamdesk vêm do Tailwind e podem mudar em qualquer versão. Os rótulos dos botões também mudam. Em sites multilíngues, eles são traduzidos. Use estes seletores:

Teste suas alterações

jamdesk dev mostra seu CSS, mas não executa JavaScript personalizado. O chat com IA só funciona no site publicado. Para testar o script localmente, cole-o no console do navegador na página de pré-visualização. O botão aparecerá, mas não abrirá o chat até você publicar.

Confira o resultado em uma tela do tamanho de um celular (375px de largura) e no modo escuro, não apenas no desktop. É nesses casos que as cores do cabeçalho e os botões fixos costumam apresentar problemas.

O que vem a seguir?