Pular para conteúdo

Brand Customization Guide

Este documento descreve todas as customizações visuais aplicadas ao site de documentação da Apta (docs.apta.agency), alinhando o MkDocs Material com o Brand Guide oficial da Apta.

Overview

O tema base é MkDocs Material com esquema de cores slate (dark mode). Quatro arquivos CSS customizados sobrescrevem variáveis e estilos do Material, enquanto dois template overrides adicionam branding ao header e footer.

Arquivo Propósito Brand Guide Source
stylesheets/colors.css Palette de cores, links, focus states Colors.pdf
stylesheets/typography.css Tipografia, heading sizes, responsive Typography.pdf
stylesheets/components.css Buttons, cards, admonitions Colors.pdf, Typography.pdf
stylesheets/layout.css Header, nav, sidebar, footer, search Colors.pdf, Typography.pdf
overrides/main.html Wordmark "Apta" no header Logo.pdf
overrides/partials/copyright.html Logo + wordmark no footer Logo.pdf

Cores (stylesheets/colors.css)

Source: brand-guide/Colors.pdf

CSS Custom Properties

Todas as cores do brand guide são definidas como variáveis CSS --apta-* em :root, reutilizáveis em qualquer stylesheet:

Variável Valor Uso
--apta-brand-black #000000 Backgrounds (header, footer)
--apta-brand-white #FFFFFF Texto principal, headings
--apta-neutral-lightest #F0F0F0 Texto body
--apta-neutral-lighter #CCCCCC Texto secundário
--apta-neutral-light #AAAAAA Texto terciário, ícones
--apta-neutral #666666 Apenas decorativo (não usar para texto — falha WCAG AA)
--apta-neutral-dark #444444 Borders
--apta-neutral-darker #222222 Backgrounds secundários
--apta-neutral-darkest #111111 Background principal
--apta-success-green #027A48 Admonitions tip/hint
--apta-error-red #B42318 Admonitions danger/error

Material Theme Overrides

O seletor [data-md-color-scheme="slate"] sobrescreve variáveis --md-* do Material para aplicar a palette brand:

  • Background: --md-default-bg-color → --apta-neutral-darkest
  • Foreground: --md-default-fg-color → --apta-neutral-lightest
  • Primary: --md-primary-fg-color → --apta-brand-black
  • Links: --md-typeset-a-color → --apta-brand-white
  • Code blocks: --md-code-bg-color → --apta-neutral-darker

Acessibilidade

  • Focus visibility (*:focus-visible) com outline branco 2px em todos os elementos
  • Links usam border-bottom sutil ao invés de underline, transição para branco no hover
  • Links de navegação (nav, tabs, header, footer) não têm underline

Tipografia (stylesheets/typography.css)

Source: brand-guide/Typography.pdf

Fontes

Tipo Fonte Configuração
Texto Inter Tight theme.font.text em mkdocs.yml (Google Fonts)
Código Roboto Mono theme.font.code em mkdocs.yml (Google Fonts)

Não é necessário @font-face — o MkDocs Material carrega automaticamente via Google Fonts.

Headings

Desktop (>768px): peso Medium (500), tamanhos grandes

Heading Size Line-height
h1 2.5rem 1.2
h2 2rem 1.2
h3 1.625rem 1.2
h4 1.25rem 1.3
h5 1.1rem 1.4
h6 1rem 1.4

Mobile (≤768px): peso Bold (700), tamanhos reduzidos (h1: 2rem, h2: 1.75rem, h3: 1.5rem)

Extra-small (≤375px): tamanhos ainda menores (h1: 1.75rem, h2: 1.5rem, h3: 1.25rem)

Body Text

  • Font size: 0.875rem (14px)
  • Line height: 1.5
  • Code: 0.8125rem (13px), 0.75rem em ≤414px

Componentes (stylesheets/components.css)

Source: Colors.pdf, Typography.pdf

Buttons

Classe Estilo Hover
.md-button Outlined, borda --apta-neutral-light Background --apta-neutral-darker, borda branca
.md-button--primary Filled branco, texto preto Background --apta-neutral-lightest
.md-clipboard Ícone cinza claro Branco
.md-top Background --apta-neutral-darker Background --apta-neutral-dark
.md-tag Chip cinza escuro —

Todos usam border-radius: 4px e transições de 0.2s.

Admonitions (Callouts)

Base: background --apta-neutral-darker, borda 1px, border-left colorido de 4px.

Tipo Cor do border-left Title background
note --apta-neutral-lighter (#CCC) rgba(204,204,204, 0.1)
tip / hint / important --apta-success-green (#027A48) rgba(2,122,72, 0.1)
warning / caution / attention Amber (#E8A317) rgba(232,163,23, 0.1)
danger / error / bug --apta-error-red (#B42318) rgba(180,35,24, 0.1)

Sobre a cor amber

O brand guide não define uma cor de warning — usamos amber padrão (#E8A317) para manter distinção visual.

Cards

  • Background: --apta-neutral-darker
  • Border: 1px --apta-neutral-dark
  • Hover: border mais claro + shadow mais forte

Layout (stylesheets/layout.css)

Source: Colors.pdf, Typography.pdf

  • Background: preto (--apta-brand-black)
  • Border-bottom sutil + box-shadow
  • Site title em branco bold, page title em cinza claro
  • Logo SVG com wordmark "Apta" injetado via JS (ver overrides/main.html)

Tabs (Top Navigation)

  • Background: --apta-neutral-darkest
  • Links em cinza, active em branco bold
  • Overflow protection com white-space: nowrap em tablet
  • Background: --apta-neutral-darkest
  • Links em cinza claro, hover → branco
  • Active: branco + bold + border-left 2px (ToC)
  • Section titles: uppercase com letter-spacing
  • Form: background --apta-neutral-darker, hover mais claro
  • Results: background escuro, item borders sutis
  • Placeholder: --apta-neutral-light (WCAG-compliant)
  • Background: preto
  • Prev/next links em cinza, hover → branco
  • Social links e copyright em cinza claro
  • Logo + wordmark "Apta" via override (ver overrides/partials/copyright.html)

Responsividade

Breakpoint Ajustes
≤375px Header wordmark oculto, headings extra-small
≤414px Code font menor, buttons compactos, footer stacked
≤768px Word-break, tables com scroll horizontal, content overflow hidden
769px–1024px Sidebar reduzida (11rem), tabs overflow protection
1920px+ Grid max-width 75rem para readability

Template Overrides (overrides/)

main.html

Extends base.html. Usa o bloco extrahead para:

  1. CSS: Estiliza wordmark ao lado do logo
  2. JS: Injeta <span class="apta-wordmark">Apta</span> dentro do .md-header__button.md-logo

O JS é necessário porque copiar o partial inteiro do header criaria dependência de versão com o Material Theme.

partials/copyright.html

Sobrescreve o partial de copyright do Material. Adiciona:

  • Logo SVG (assets/icon-logo.svg) com filtro de brilho
  • Wordmark "Apta" ao lado do logo
  • Copyright text do config.copyright (mkdocs.yml)

Como Adicionar Novos Componentes

Para adicionar um novo componente seguindo o padrão visual:

  1. Identifique o arquivo CSS correto:

    • Cores/variáveis → colors.css
    • Tamanhos de texto → typography.css
    • Elementos interativos (buttons, cards) → components.css
    • Estrutura de página (header, nav, footer) → layout.css

  2. Use variáveis --apta-* ao invés de valores hex diretos: 

    [data-md-color-scheme="slate"] .my-component {
  background-color: var(--apta-neutral-darker);
  color: var(--apta-neutral-lightest);
  border: 1px solid var(--apta-neutral-dark);
  border-radius: 4px;
  transition: all 0.2s;
}

  3. Sempre prefixe com [data-md-color-scheme="slate"] para garantir que o estilo só se aplica no dark theme.

  4. Adicione hover states com transição de cor para branco: 

    [data-md-color-scheme="slate"] .my-component:hover {
  color: var(--apta-brand-white);
}

  5. Considere responsividade — adicione media queries para mobile (≤768px) e tablet (769px–1024px) se necessário.

  6. Verifique contraste — use --apta-neutral-light (#AAA) como mínimo para texto legível em backgrounds escuros. Nunca use --apta-neutral (#666) para texto.

Referências