Como estilizar um mapa com marca personalizada (modo escuro, cores, sem marcas dagua)

Todo mapa que você já viu no aplicativo de um concorrente usa o mesmo estilo padrão. As estradas bege genéricas, a água azul-petróleo médio, os ícones de POI lotados que competem por atenção com sua própria interface, esses são os padrões universais, projetados para não ofender ninguém e não encantar ninguém. Comunicam uma coisa claramente: este produto está usando uma biblioteca de mapas, não tendo uma experiência de mapa própria.

A estilização personalizada de mapas muda isso. Um mapa no modo escuro em um painel de logística, uma rede de estradas na cor da marca em um aplicativo imobiliário, um estilo minimalista limpo com seu logotipo onde ficava a marca d'água de atribuição, esses são detalhes que elevam uma ferramenta a um produto.

Este tutorial percorre a Especificação de Estilo Mapbox conforme implementada pelo MapAtlas, desde a estrutura do JSON de estilo até um toggle completo de claro/escuro em React. Você não precisa de experiência em GIS. Você precisa estar confortável com JSON e JavaScript.

Se você ainda não configurou um mapa básico, comece com Como Adicionar Mapas Interativos ao Seu Site primeiro e depois volte aqui para a estilização.

Por Que os Estilos de Mapa Padrão Parecem Genéricos

O estilo padrão de um provedor de tiles é projetado para ser universalmente legível para o público mais amplo possível, no contexto mais amplo possível. Prioriza densidade informacional em detrimento de opinião estética. As estradas precisam ser visíveis. Os rótulos precisam ter contraste. Os ícones de POI precisam ser reconhecíveis.

Nenhum desses objetivos se alinha com os objetivos do seu produto. Seu aplicativo provavelmente se importa com um subconjunto pequeno do que está no mapa, rotas de entrega, locais de propriedades, instalações de saúde, e todo o resto é ruído visual.

A estilização personalizada permite que você suprima o que não precisa, enfatize o que precisa, e garanta que o mapa seja lido como parte do seu produto em vez de um widget de terceiros inserido.

Entendendo a Especificação de Estilo

Um estilo MapAtlas é um documento JSON com cinco seções principais:

{
  "version": 8,
  "name": "My Brand Style",
  "sources": { ... },
  "glyphs": "https://tiles.mapatlas.eu/fonts/{fontstack}/{range}.pbf?key=YOUR_API_KEY",
  "sprite": "https://tiles.mapatlas.eu/sprites/basic?key=YOUR_API_KEY",
  "layers": [ ... ]
}

• sources, de onde vêm os dados do mapa (endpoints de tiles vetoriais do MapAtlas)
• glyphs, de onde carregar arquivos de fonte para renderização de rótulos
• sprite, de onde carregar imagens de ícones para marcadores de POI
• layers, a lista ordenada de camadas visuais, cada uma com propriedades de pintura e layout

O array layers é onde você passa a maior parte do tempo. Cada camada especifica um tipo de dados (fill, line, symbol, circle, fill-extrusion), quais features de origem desenhar, e como pintá-las.

Aqui está um estilo mínimo mas completo que renderiza uma base de tile vetorial:

{
  "version": 8,
  "name": "Brand Base",
  "sources": {
    "mapatlas": {
      "type": "vector",
      "tiles": ["https://tiles.mapatlas.eu/v1/tiles/{z}/{x}/{y}.mvt?key=YOUR_API_KEY"],
      "minzoom": 0,
      "maxzoom": 14
    }
  },
  "glyphs": "https://tiles.mapatlas.eu/fonts/{fontstack}/{range}.pbf?key=YOUR_API_KEY",
  "sprite": "https://tiles.mapatlas.eu/sprites/basic?key=YOUR_API_KEY",
  "layers": [
    {
      "id": "background",
      "type": "background",
      "paint": { "background-color": "#f5f0eb" }
    }
  ]
}

Isso renderiza uma tela em branco na cor de fundo escolhida. A partir daí você adiciona camadas para água, uso do solo, estradas, edifícios e rótulos.

Modo Escuro: Mudando as Cores Principais

Um mapa no modo escuro não é simplesmente uma imagem raster invertida. É um conjunto completamente diferente de propriedades de pintura aplicadas à mesma geometria vetorial. Esta é uma das razões principais para a existência dos tiles vetoriais, um tile, infinitas interpretações visuais.

As cores principais a atualizar para um tema escuro:

Veja como aplicar isso em uma camada de estilo:

{
  "id": "water",
  "type": "fill",
  "source": "mapatlas",
  "source-layer": "water",
  "paint": {
    "fill-color": "#0d3b66",
    "fill-opacity": 1
  }
}

{
  "id": "road-major",
  "type": "line",
  "source": "mapatlas",
  "source-layer": "transportation",
  "filter": ["==", "class", "primary"],
  "layout": {
    "line-join": "round",
    "line-cap": "round"
  },
  "paint": {
    "line-color": "#3a3a5c",
    "line-width": ["interpolate", ["linear"], ["zoom"], 10, 1, 16, 4]
  }
}

A expressão interpolate em line-width escala a largura da estrada com base no nível de zoom, estreita em zoom baixo, mais larga conforme você aproxima. Isso é estilização orientada a dados sem nenhuma solicitação adicional de rede.

Aplicando Cores da Marca

A maioria dos sistemas de design define uma cor primária (digamos, #97C70A), uma cor secundária e uma paleta neutra. O mapa deve usar exatamente esses mesmos valores, não aproximações.

Defina essas camadas para aplicação de cores da marca:

Estradas como elementos de marca. Se a cor da sua marca é vibrante o suficiente, use-a para estradas principais ou rotas destacadas:

{
  "id": "road-highlighted",
  "type": "line",
  "source": "mapatlas",
  "source-layer": "transportation",
  "filter": ["==", "class", "primary"],
  "paint": {
    "line-color": "#97C70A",
    "line-width": 3,
    "line-opacity": 0.8
  }
}

Marcadores de POI personalizados. Substitua os ícones padrão do sprite pelos seus próprios hospedando uma folha de sprite personalizada e atualizando a URL sprite. Em seguida, referencie seus ícones nas camadas de símbolo:

{
  "id": "brand-poi",
  "type": "symbol",
  "source": "mapatlas",
  "source-layer": "poi",
  "layout": {
    "icon-image": "brand-pin",
    "icon-size": 1.2,
    "text-field": ["get", "name"],
    "text-font": ["Inter Bold", "Noto Sans Regular"],
    "text-size": 12,
    "text-offset": [0, 1.5],
    "text-anchor": "top"
  },
  "paint": {
    "text-color": "#97C70A",
    "text-halo-color": "#1a1a2e",
    "text-halo-width": 1
  }
}

Fontes Personalizadas para Rótulos do Mapa

As fontes padrão dos rótulos do mapa são genéricas. Se sua marca usa Inter, Roboto ou uma fonte personalizada, você pode usá-la também para os rótulos do mapa.

O MapAtlas serve glyphs de seu próprio endpoint de glyph, que suporta o formato de glyph padrão do Mapbox. Para usar uma fonte personalizada:

1. Gere arquivos de glyph .pbf da sua fonte usando uma ferramenta como fontnik.
2. Hospede os arquivos de glyph em uma CDN ou no seu próprio servidor.
3. Atualize o campo glyphs no seu JSON de estilo:

{
  "glyphs": "https://your-cdn.com/fonts/{fontstack}/{range}.pbf"
}

4. Referencie a fonte na propriedade text-font de qualquer camada de símbolo:

"text-font": ["Inter Bold", "Noto Sans Regular"]

Sempre forneça uma fonte de fallback (Noto Sans cobre caracteres Unicode que sua fonte primária pode não incluir). O renderizador usa a primeira fonte no array que contém um glyph para cada caractere.

Removendo Marcas D'água e Atribuições

O MapAtlas permite implantação totalmente white-label. Você pode remover completamente o logotipo do MapAtlas do mapa.

No SDK, a atribuição é tratada por um controle que você pode desabilitar:

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  center: [4.9041, 52.3676],
  zoom: 12,
  attributionControl: false,  // Remove o controle de atribuição padrão
});

Se você quiser manter a atribuição mas estilizá-la para combinar com sua interface, oculte o controle padrão e adicione o seu próprio:

map.addControl(
  new mapmetricsgl.AttributionControl({
    customAttribution: 'Map data © OpenStreetMap contributors',
    compact: true,
  }),
  'bottom-left'
);

Isso substitui a marca por uma atribuição mínima e legalmente compatível que respeita a licença do OpenStreetMap enquanto combina com sua interface. Diferentemente do Google Maps, que exige que seu logotipo permaneça visível em todos os momentos independentemente do seu plano, o MapAtlas dá a você controle total.

Toggle de Tema Claro/Escuro em React

Aqui está um componente React completo que gerencia um mapa com toggle claro/escuro, usando propriedades CSS personalizadas para manter o tema sincronizado com o restante da sua interface:

import { useEffect, useRef, useState } from 'react';
import mapmetricsgl from '@mapmetrics/mapmetrics-gl';
import '@mapmetrics/mapmetrics-gl/dist/mapmetrics-gl.css';

const STYLES = {
  light: 'https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY',
  dark:  'https://tiles.mapatlas.eu/styles/dark/style.json?key=YOUR_API_KEY',
};

export function BrandedMap({ center = [4.9041, 52.3676], zoom = 12 }) {
  const containerRef = useRef(null);
  const mapRef       = useRef(null);
  const [theme, setTheme] = useState('light');

  useEffect(() => {
    const map = new mapmetricsgl.Map({
      container:        containerRef.current,
      style:            STYLES.light,
      center,
      zoom,
      attributionControl: false,
    });

    map.addControl(
      new mapmetricsgl.AttributionControl({ compact: true }),
      'bottom-left'
    );

    mapRef.current = map;
    return () => map.remove();
  }, []);

  useEffect(() => {
    if (mapRef.current) {
      mapRef.current.setStyle(STYLES[theme]);
    }
  }, [theme]);

  return (
    <div style={{ position: 'relative' }}>
      <div ref={containerRef} style={{ width: '100%', height: '500px' }} />
      <button
        onClick={() => setTheme(t => t === 'light' ? 'dark' : 'light')}
        style={{
          position: 'absolute',
          top: 12,
          right: 12,
          padding: '8px 16px',
          background: theme === 'dark' ? '#ffffff' : '#1a1a2e',
          color:      theme === 'dark' ? '#1a1a2e' : '#ffffff',
          border: 'none',
          borderRadius: 6,
          cursor: 'pointer',
          zIndex: 1,
        }}
      >
        {theme === 'light' ? 'Modo escuro' : 'Modo claro'}
      </button>
    </div>
  );
}

A chamada setStyle re-renderiza o mapa com o novo esquema de cores. Os dados de tile que já estão em cache não são re-buscados, apenas a interpretação visual muda.

Hospedando um JSON de Estilo Personalizado

Para controle total, hospede seu JSON de estilo como um arquivo estático na sua CDN ou bucket S3. Isso permite que você:

• Controle a versão do seu estilo junto com o código do aplicativo.
• Atualize o design visual sem reimplantar o aplicativo (basta atualizar o JSON hospedado).
• Use estilos diferentes para diferentes ambientes (preview versus produção).

Carregue um estilo hospedado em tempo de execução:

const map = new mapmetricsgl.Map({
  container: 'map',
  style: 'https://your-cdn.com/styles/brand-dark.json',
  center: [4.9041, 52.3676],
  zoom: 12,
});

A única restrição é o CORS: o JSON de estilo deve ser servido com Access-Control-Allow-Origin: * (ou seu domínio específico) para que o navegador possa buscá-lo de origem cruzada.

Fluxo de Trabalho de Desenvolvimento de Estilo

A maneira mais rápida de construir um estilo personalizado é iterativa, veja as mudanças em tempo real sem reescrever código.

1. Comece com um JSON de estilo base do MapAtlas como sua fundação. Baixe-o buscando https://tiles.mapatlas.eu/styles/basic/style.json?key=YOUR_API_KEY.
2. Edite o JSON no seu editor, observando qual camada afeta qual elemento visual.
3. Recarregue o mapa com seu JSON de estilo modificado para ver o resultado.
4. Uma vez estável, commite o JSON de estilo no seu repositório e hospede-o na sua CDN.

Para uma personalização mais profunda, consulte a documentação de Visualização e Estilização de Mapas para a referência completa de camadas, tipos de propriedade de pintura e sintaxe de expressão.

E para o fundamento arquitetônico de por que os tiles vetoriais tornam tudo isso possível, Tiles Vetoriais vs. Tiles Raster explica o pipeline de renderização em detalhes.

Resumo

A estilização personalizada de mapas não é um luxo, é a diferença entre um mapa que parece um widget de terceiros e um que parece ter sido construído para o seu produto. Com o MapAtlas:

• A especificação de estilo é JSON padrão compatível com as ferramentas do Mapbox GL JS.
• O modo escuro é uma troca de JSON de estilo, não um novo conjunto de tiles ou configuração de servidor.
• As cores da marca se aplicam a estradas, rótulos e ícones de POI por meio de propriedades de pintura.
• Fontes personalizadas carregam de qualquer endpoint de glyph que você controla.
• Marcas d'água e atribuição são totalmente configuráveis, white-label é suportado em todos os planos pagos.
• O estilo inteiro pode ser alternado em tempo de execução sem recarregar a página.

Comece a construir seu mapa com marca hoje. Cadastre-se para uma chave de API MapAtlas gratuita e carregue o JSON de estilo base como ponto de partida. O primeiro estilo personalizado leva cerca de 30 minutos para ficar certo, as iterações subsequentes levam minutos.