Manipula??o de SVG com Claude Code: guia pr?tico

Antes de pedir SVG ao Claude Code

SVG e excelente para ?cones, logos, diagramas e pequenas visualiza??es porque escala sem perder nitidez e pode herdar estilos de CSS. Claude Code consegue ler o reposit?rio, editar arquivos e executar verifica??es, entao funciona bem para transformar SVGs soltos em componentes de UI reutilizaveis.

O risco esta nos prompts vagos. “Crie um ?cone SVG” pode gerar algo bonito, mas sem viewBox, com cores fixas, sem nome acessivel, com anima??o invasiva ou com uma configura??o de otimiza??o que quebra o redimensionamento. Masa encontrou esse problema em uma pequena UI de teste do ClaudeCodeLab: o ?cone parecia correto, mas precisava de ajustes manuais quando era usado em bot?o com texto, bot?o s? com ?cone e tema escuro.

Este guia organiza um fluxo mais seguro: preservar viewBox, usar currentColor, separar ?cones decorativos de ?cones com significado, adicionar anima??o leve e otimizar com SVGO sem remover atributos essenciais. As referencias oficiais sao MDN <svg>, MDN viewBox, MDN ARIA img role, MDN aria-hidden, SVGO e a documentacao do Claude Code.

Fluxo recomendado

Trabalhar com SVG n?o e apenas desenhar. Em uma aplicacao real, isso envolve design system, acessibilidade, performance, seguran?a e revisao.

flowchart LR
  A["Definir objetivo"] --> B["Fixar viewBox"]
  B --> C["Usar currentColor"]
  C --> D["Escolher aria-label ou aria-hidden"]
  D --> E["Integrar em HTML ou React"]
  E --> F["Otimizar com SVGO"]
  F --> G["Revisar layout e seguran?a"]

Um prompt melhor seria: “Crie um componente de ?cones SVG com viewBox="0 0 24 24", stroke="currentColor", ?cones decorativos com aria-hidden, ?cones aut?nomos com role="img" e title, e uma configura??o de SVGO que preserve viewBox.”

Inline SVG e viewBox

Inline SVG significa colocar o markup <svg> diretamente em HTML ou JSX, em vez de carregar um arquivo por img. Isso e util quando o ?cone precisa herdar cor, reagir a hover, receber props ou animar levemente.

viewBox define o sistema de coordenadas interno. A MDN descreve quatro numeros: min-x min-y width height. Para iniciantes, viewBox="0 0 24 24" significa que o desenho vive em uma grade de 24 por 24, mesmo que seja exibido em 16px, 24px ou 48px.

<button class="icon-button" type="button" aria-label="Pesquisar">
  <svg
    class="icon"
    viewBox="0 0 24 24"
    width="24"
    height="24"
    fill="none"
    stroke="currentColor"
    stroke-width="2"
    stroke-linecap="round"
    stroke-linejoin="round"
    aria-hidden="true"
    focusable="false"
  >
    <circle cx="11" cy="11" r="7" />
    <path d="M20 20l-4.5-4.5" />
  </svg>
</button>

O bot?o ja tem o nome acessivel, entao o SVG e decorativo. Se o bot?o tivesse somente o ?cone visivel, o nome deveria estar no bot?o. Se o SVG for uma imagem independente com significado, o pr?prio SVG precisa de nome.

Tema com currentColor e vari?veis CSS

Cores fixas dentro do SVG viram divida tecnica. Se um path cont?m fill="#111827", Claude Code tera que editar o SVG em cada troca de tema. Para ?cones de UI, deixe o SVG herdar a cor do CSS.

:root {
  --color-text: #172033;
  --color-muted: #667085;
  --color-accent: #0f766e;
  --color-danger: #b42318;
}

[data-theme="dark"] {
  --color-text: #eef2f7;
  --color-muted: #a9b4c3;
  --color-accent: #2dd4bf;
  --color-danger: #f97066;
}

.icon {
  color: var(--icon-color, var(--color-text));
  display: inline-block;
  inline-size: 1.25rem;
  block-size: 1.25rem;
  flex: 0 0 auto;
}

.icon-button {
  color: var(--color-muted);
}

.icon-button:hover {
  color: var(--color-accent);
}

.icon-button[data-variant="danger"] {
  --icon-color: var(--color-danger);
}

<button class="icon-button" type="button" aria-label="Excluir" data-variant="danger">
  <svg class="icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
    <path d="M4 7h16" />
    <path d="M10 11v6" />
    <path d="M14 11v6" />
    <path d="M6 7l1 14h10l1-14" />
    <path d="M9 7V4h6v3" />
  </svg>
</button>

Depois da refatoracao, peca ao Claude Code para procurar cores fixas com rg "fill=\"#|stroke=\"#". Logos podem ser exce??o, mas ?cones comuns devem usar currentColor.

Componente React acessivel

Um SVG com significado precisa de nome acessivel. Um SVG decorativo deve ser escondido da ?rvore de acessibilidade. A MDN recomenda role="img" e r?tulo para SVG embutido que atua como imagem, e aria-hidden="true" para conte?do decorativo n?o interativo.

import { useId } from "react";

type IconName = "search" | "check" | "close";

const paths: Record<IconName, string> = {
  search: "M10.5 18a7.5 7.5 0 1 1 5.3-12.8 7.5 7.5 0 0 1-5.3 12.8Zm5.3-2.2L21 21",
  check: "M5 12.5l4.5 4.5L19 7",
  close: "M6 6l12 12M18 6L6 18",
};

type SvgIconProps = {
  name: IconName;
  title?: string;
  decorative?: boolean;
  size?: number;
  className?: string;
};

export function SvgIcon({
  name,
  title,
  decorative = false,
  size = 24,
  className,
}: SvgIconProps) {
  const titleId = useId();
  const isMeaningful = !decorative && Boolean(title);

  return (
    <svg
      className={className}
      width={size}
      height={size}
      viewBox="0 0 24 24"
      fill="none"
      stroke="currentColor"
      strokeWidth={2}
      strokeLinecap="round"
      strokeLinejoin="round"
      role={isMeaningful ? "img" : undefined}
      aria-labelledby={isMeaningful ? titleId : undefined}
      aria-hidden={decorative ? true : undefined}
      focusable="false"
    >
      {isMeaningful ? <title id={titleId}>{title}</title> : null}
      <path d={paths[name]} />
    </svg>
  );
}

<button type="button">
  <SvgIcon name="check" decorative />
  Salvar
</button>

<SvgIcon name="search" title="Pesquisar" />

N?o coloque aria-hidden="true" em elementos que podem receber foco. Um bot?o somente com ?cone precisa de aria-label no bot?o ou texto visivel.

Animacao simples

Animacao SVG funciona melhor para carregamento, sucesso e pequenos destaques. Mantenha dimensoes estaveis e respeite prefers-reduced-motion.

<svg class="spinner" viewBox="0 0 48 48" width="48" height="48" role="img" aria-label="Carregando">
  <circle class="spinner-track" cx="24" cy="24" r="20" />
  <circle class="spinner-head" cx="24" cy="24" r="20" />
</svg>

.spinner {
  color: #0f766e;
  animation: spin 900ms linear infinite;
}

.spinner-track,
.spinner-head {
  fill: none;
  stroke-width: 4;
}

.spinner-track {
  stroke: #d0d5dd;
}

.spinner-head {
  stroke: currentColor;
  stroke-linecap: round;
  stroke-dasharray: 80 45;
}

@keyframes spin {
  to {
    transform: rotate(360deg);
  }
}

@media (prefers-reduced-motion: reduce) {
  .spinner {
    animation: none;
  }
}

Para movimento mais avancado, veja tamb?m anima??es CSS avancadas com Claude Code. SVG define forma; CSS define estado e movimento.

Pequenos graficos em SVG

SVG pode criar graficos pequenos sem biblioteca pesada. Se o texto vier de dados externos, escape antes de colocar dentro de <text>.

type BarDatum = {
  label: string;
  value: number;
};

function escapeXml(value: string): string {
  return value.replace(/[<>&"']/g, (char) => {
    const entities: Record<string, string> = {
      "<": "&lt;",
      ">": "&gt;",
      "&": "&amp;",
      '"': "&quot;",
      "'": "&apos;",
    };
    return entities[char];
  });
}

export function createMiniBarChart(data: BarDatum[]): string {
  const width = 420;
  const height = 180;
  const padding = 32;
  const gap = 12;
  const maxValue = Math.max(...data.map((item) => item.value), 1);
  const barWidth = (width - padding * 2 - gap * (data.length - 1)) / data.length;

  const bars = data
    .map((item, index) => {
      const barHeight = (item.value / maxValue) * 100;
      const x = padding + index * (barWidth + gap);
      const y = height - padding - barHeight;

      return `
        <rect x="${x}" y="${y}" width="${barWidth}" height="${barHeight}" rx="6" fill="currentColor" />
        <text x="${x + barWidth / 2}" y="${height - 10}" text-anchor="middle" font-size="12">
          ${escapeXml(item.label)}
        </text>`;
    })
    .join("");

  return `<svg viewBox="0 0 ${width} ${height}" role="img" aria-label="Consultas mensais" xmlns="http://www.w3.org/2000/svg">
    <g color="#0f766e">${bars}</g>
  </svg>`;
}

Use isso em mini dashboards, artigos ou prova social em landing pages. Para eixos, legendas, tooltips, zoom ou muitos dados, escolha uma biblioteca de graficos.

Otimizacao com SVGO

Exports de ferramentas de design geralmente incluem metadados e atributos desnecessarios. SVGO limpa esse excesso. Comece com uma configura??o conservadora e revise o diff.

// svgo.config.mjs
export default {
  multipass: true,
  plugins: [
    {
      name: "preset-default",
      params: {
        overrides: {
          cleanupIds: false
        }
      }
    },
    "removeDimensions",
    {
      name: "removeAttrs",
      params: {
        attrs: ["data-name"]
      }
    }
  ]
};

{
  "scripts": {
    "svg:optimize": "svgo --config svgo.config.mjs --folder src/assets/icons"
  },
  "devDependencies": {
    "svgo": "^4.0.0"
  }
}

SVGO documenta preset-default, removeDimensions e outros plugins. Cuidado com removeViewBox: a documentacao alerta que ele pode impedir o SVG de escalar e causar recortes.

Casos de uso e armadilhas

Casos comuns: sistema de ?cones de produto; diagramas em artigos tecnicos; visuais perto de precos, checklists e bot?es de compra; pequenos graficos de leitura, cliques em CTA ou volume de consultas.

Erro	Resultado	Corre??o
Remover viewBox	Icone corta ou n?o escala	Preservar no SVGO e revisar diff
Cores fixas	Dark mode e hover falham	Usar currentColor
Esconder ?cone com significado	Leitor de tela perde a acao	Nomear bot?o ou SVG
Ler ?cone decorativo	Nomes duplicados	Usar aria-hidden="true"
Inserir SVG enviado por usu?rio	Risco de scripts e eventos	Inline so para SVG confiavel
Ignorar movimento reduzido	Pode incomodar usu?rios	Usar prefers-reduced-motion

MDN documenta o elemento SVG <script>, entao n?o trate SVG enviado por usu?rios como texto inofensivo. Claude Code pode revisar diffs, mas limite a pasta alvo e leia as mudancas. Para permiss?es e comandos, veja tamb?m a p?gina de seguran?a do Claude Code.

Prompt reutiliz?vel

Crie um sistema de ?cones SVG para este reposit?rio.
Requisitos:
- Manter viewBox="0 0 24 24"
- Usar currentColor em fill ou stroke
- Ocultar ?cones decorativos com aria-hidden=true
- Usar role=img e title em ?cones aut?nomos com significado
- Adicionar um SVG de carregamento que respeite prefers-reduced-motion
- Adicionar configura??o SVGO que n?o remova viewBox
- Reportar riscos, arquivos alterados e comandos de verificacao

Depois, conecte o trabalho a otimiza??o de performance com Claude Code, porque ?cones, diagramas e anima??es tamb?m influenciam peso de p?gina e renderizacao.

CTA e resultado testado

Se voce quer transformar isso em uma base reutiliz?vel, veja os produtos e templates da ClaudeCodeLab ou leve um reposit?rio real para treinamento e consultoria Claude Code. SVG e um bom primeiro caso porque o escopo e pequeno, mas toca design, acessibilidade, performance e revisao.

Na UI de teste de Masa, mover cores fixas para currentColor permitiu usar os mesmos ?cones em tema claro, tema escuro e bot?es destrutivos. O erro real foi de acessibilidade: um bot?o de busca s? com ?cone perdeu o nome quando aria-hidden foi aplicado mecanicamente. A regra final foi nomear o bot?o e esconder apenas ?cones decorativos.