Habilidade draw.io Diagram

1. Regras Básicas

• Edite apenas arquivos .drawio
• Não edite diretamente arquivos .drawio.png
• Use .drawio.png gerado automaticamente pelo hook pre-commit em slides

2. Configurações de Fonte

Para diagramas usados em slides Quarto, especifique defaultFontFamily na tag mxGraphModel:

<mxGraphModel defaultFontFamily="Noto Sans JP" ...>

Especifique também explicitamente fontFamily no atributo style de cada elemento de texto:

style="text;html=1;fontSize=27;fontFamily=Noto Sans JP;"

3. Comandos de Conversão

Veja script de conversão em scripts/convert-drawio-to-png.sh.

# Converter todos os arquivos .drawio
mise exec -- pre-commit run --all-files

# Converter arquivo .drawio específico
mise exec -- pre-commit run convert-drawio-to-png --files assets/my-diagram.drawio

# Executar script diretamente (usando o script da habilidade)
bash ~/.claude/skills/draw-io/scripts/convert-drawio-to-png.sh assets/diagram1.drawio

Comando interno utilizado:

drawio -x -f png -s 2 -t -o output.drawio.png input.drawio

Opção	Descrição
-x	Modo de exportação
-f png	Formato de saída PNG
-s 2	Escala 2x (alta resolução)
-t	Fundo transparente
-o	Caminho do arquivo de saída

4. Ajuste de Layout

4.1. Etapas de Ajuste de Coordenadas

1. Abra arquivo .drawio em editor de texto (formato XML puro)
2. Encontre mxCell do elemento a ajustar (pesquise pelo atributo value para o texto)
3. Ajuste as coordenadas na tag mxGeometry
   • x: Posição a partir da esquerda
   • y: Posição a partir do topo
   • width: Largura
   • height: Altura
4. Execute conversão e verifique

4.2. Cálculo de Coordenadas

• Coordenada do centro do elemento = y + (height / 2)
• Para alinhar múltiplos elementos, calcule e iguale as coordenadas do centro

5. Princípios de Design

5.1. Princípios Básicos

• Clareza: Crie diagramas simples e visualmente limpos
• Consistência: Unifique cores, fontes, tamanhos de ícones, espessura de linhas
• Precisão: Não sacrifique a precisão pela simplificação

5.2. Regras de Elementos

• Rotule todos os elementos
• Use setas para indicar direção (prefira 2 setas unidirecionais em vez de bidirecionais)
• Use ícones oficiais mais recentes
• Adicione legenda para explicar símbolos personalizados

5.3. Acessibilidade

• Garanta contraste de cor suficiente
• Use padrões além de cores

5.4. Divulgação Progressiva

Separe sistemas complexos em diagramas por etapas:

Tipo de Diagrama	Propósito
Diagrama de Contexto	Visão geral do sistema de perspectiva externa
Diagrama de Sistema	Componentes principais e relacionamentos
Diagrama de Componentes	Detalhes técnicos e pontos de integração
Diagrama de Implantação	Configuração de infraestrutura
Diagrama de Fluxo de Dados	Fluxo e transformação de dados
Diagrama de Sequência	Interações em série temporal

5.5. Metadados

Inclua título, descrição, última atualização, autor e versão nos diagramas.

6. Melhores Práticas

6.1. Cor de Fundo

• Remova background="#ffffff"
• Fundo transparente se adapta a vários temas

6.2. Tamanho da Fonte

• Use 1,5x o tamanho de fonte padrão (cerca de 18px) para legibilidade em PDF

6.3. Largura de Texto em Japonês

• Permita 30-40px por caractere
• Largura insuficiente causa quebras de linha indesejadas

<!-- Para texto com 10 caracteres, permita 300-400px -->
<mxGeometry x="140" y="60" width="400" height="40" />

6.4. Posicionamento de Setas

• Sempre coloque setas atrás (posicione no XML logo após o Título)
• Posicione setas para evitar sobreposição com rótulos
• Mantenha início/fim da seta a pelo menos 20px da borda inferior do rótulo

<!-- Título -->
<mxCell id="title" value="..." .../>

<!-- Setas (camada traseira) -->
<mxCell id="arrow1" style="edgeStyle=..." .../>

<!-- Outros elementos (camada frontal) -->
<mxCell id="box1" .../>

6.5. Conexão de Seta a Rótulos de Texto

Para elementos de texto, exitX/exitY não funcionam, então use coordenadas explícitas:

<!-- Bom: Coordenadas explícitas com sourcePoint/targetPoint -->
<mxCell id="arrow" style="..." edge="1" parent="1">
  <mxGeometry relative="1" as="geometry">
    <mxPoint x="1279" y="500" as="sourcePoint"/>
    <mxPoint x="119" y="500" as="targetPoint"/>
    <Array as="points">
      <mxPoint x="1279" y="560"/>
      <mxPoint x="119" y="560"/>
    </Array>
  </mxGeometry>
</mxCell>

6.6. Ajuste de Offset de edgeLabel

Ajuste o atributo offset para distanciar rótulos de seta das setas:

<!-- Colocar acima da seta (valor negativo para distanciar) -->
<mxPoint x="0" y="-40" as="offset"/>

<!-- Colocar abaixo da seta (valor positivo para distanciar) -->
<mxPoint x="0" y="40" as="offset"/>

6.7. Remover Elementos Desnecessários

• Remova ícones decorativos irrelevantes para o contexto
• Exemplo: Se ECR existe, ícone Docker separado é desnecessário

6.8. Rótulos e Títulos

• Nome do serviço apenas: 1 linha
• Nome do serviço + informação complementar: 2 linhas com quebra de linha
• Notação redundante (ex: ECR Container Registry): encurte para 1 linha
• Use tag <br> para quebras de linha

6.9. Frame de Fundo e Posicionamento de Elementos Internos

Ao colocar elementos dentro de frames de fundo (caixas de agrupamento), garanta margem suficiente.

• OBRIGATÓRIO: Elementos internos devem ter pelo menos 30px de margem da borda do frame
• OBRIGATÓRIO: Considere cantos arredondados (rounded=1) e largura do traço
• OBRIGATÓRIO: Sempre verifique visualmente a saída PNG para overflow

Verificação de cálculo de coordenadas:

Frame de fundo: y=20, height=400 -> intervalo é y=20-420
Topo do elemento interno: frame y + 30 ou mais (ex: y=50)
Base do elemento interno: frame y + height - 30 ou menos (ex: até y=390)

Exemplo ruim (pode ter overflow):

<!-- Frame de fundo -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="400" />
</mxCell>
<!-- Texto: y=30 é muito próximo do topo do frame (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="30" width="540" height="35" />
</mxCell>

Exemplo bom (margem suficiente):

<!-- Frame de fundo -->
<mxCell id="bg" style="rounded=1;strokeWidth=3;...">
  <mxGeometry x="500" y="20" width="560" height="430" />
</mxCell>
<!-- Texto: y=50 está 30px do topo do frame (y=20) -->
<mxCell id="label" value="Title" style="text;...">
  <mxGeometry x="510" y="50" width="540" height="35" />
</mxCell>

7. Referência

• Diretrizes de Layout
• Ícones AWS
• Script de Busca de Ícones AWS

Exemplos de busca de ícones AWS:

python ~/.claude/skills/draw-io/scripts/find_aws_icon.py ec2
python ~/.claude/skills/draw-io/scripts/find_aws_icon.py lambda

8. Checklist

• Nenhuma cor de fundo definida (page="0")
• Tamanho de fonte apropriado (maior recomendado)
• Setas posicionadas na camada traseira
• Setas não sobrepondo rótulos (verificar no PNG)
• Início/fim da seta suficientemente distante dos rótulos (pelo menos 20px)
• Setas não penetrando caixas ou ícones (verificar no PNG)
• Elementos internos não extravasando frame de fundo (verificar no PNG)
• Margem de 30px+ entre frame de fundo e elementos internos
• Nomes de serviços AWS são nomes oficiais/abreviações corretas
• Ícones AWS são versão mais recente (mxgraph.aws4.*)
• Nenhum elemento desnecessário restante
• Conversão PNG verificada visualmente

9. Exibição de Imagem em Slides reveal.js

Adicione auto-stretch: false ao cabeçalho YAML:

---
title: "Sua Apresentação"
format:
  revealjs:
    auto-stretch: false
---

Isso garante exibição correta de imagem em dispositivos móveis.