Módulo 3.6 · Edge cases + GitHub flow + URLs internas

🐙 GitHub flow completo (4 tools encadeadas)

Citação literal

"Quando você receber uma mensagem 'GitHub connected', cumprimente brevemente o usuário e convide-o a colar uma URL de repositório http://github.com. Explique que você pode explorar a estrutura do repositório e importar arquivos selecionados para usar como referência em mockups de design. Limite-se a duas frases."

As 4 tools do flow GitHub

Tool	Quando	Retorna
`connect_github`	Tools indisponíveis ainda — solicita autorização ao usuário	Confirmação de conexão
`github_list_repos`	Para obter `default_branch` de um repo	Lista repos + metadata
`github_get_tree`	Ver estrutura de pastas/arquivos	Tree do path_prefix
`github_import_files`	Copiar arquivos selecionados para o projeto Claude Design	Confirmação de import
`github_read_file`	Ler arquivo único sem importar	Conteúdo do arquivo

Parsing de URL GitHub

"Analise a URL em owner/repo/ref/path — http://github.com/OWNER/REPO/tree/REF/PATH ou .../blob/REF/PATH. Para uma URL simples http://github.com/OWNER/REPO, obtenha default_branch de github_list_repos para usar como ref. Chame github_get_tree com path como path_prefix para ver o que existe ali, depois github_import_files para copiar o subconjunto relevante para este projeto; os arquivos importados vão para a raiz do projeto. Para uma URL de arquivo único, github_read_file a lê diretamente, ou você pode importar sua pasta pai."

Fluxo padrão (você cola URL)

// Você: "Cole para o repo: github.com/myorg/myrepo/tree/main/src/components"

// Claude internamente:
1. parseURL → { owner: "myorg", repo: "myrepo", ref: "main", path: "src/components" }
2. github_get_tree({ path_prefix: "src/components" })
   → ["Button.tsx", "Card.tsx", "Modal.tsx", "Tabs.tsx", ...]
3. (Claude analisa o que é relevante)
4. github_import_files({ files: ["Button.tsx", "Card.tsx"] })
5. Lê os imports para extrair tokens de design

🔗 URLs entre páginas: relativas + legacy #file=

Citação literal

"Para permitir que usuários naveguem entre páginas HTML que você criou, use tags <a> padrão com URLs relativas (por exemplo, <a href='my_folder/My Prototype.html'>Ir para a página</a>). [...] caminho relativo codificado em URL. Links antigos podem usar #file= em vez de ?file= — trate os dois da mesma forma."

Estilos de URL aceitos

// ✓ MELHOR: caminho relativo direto
<a href="my_folder/My Prototype.html">Ir</a>
<a href="../shared/About.html">Sobre</a>

// ✓ ACEITO: query string ?file= (URL encoded)
<a href="?file=my_folder/My%20Prototype.html">Ir</a>

// ✓ ACEITO (legacy): hash #file= (URL encoded)
<a href="#file=my_folder/My%20Prototype.html">Ir</a>

// ✗ EVITE: URL absoluta para projeto interno
<a href="https://claude.ai/design/projects/abc/file.html">Ir</a>

Use URL encoding para nomes com espaços (My%20Prototype.html).

Multi-page prototypes

Para protótipos multi-tela (onboarding com 6 telas, app com nav), use múltiplos arquivos HTML linkados:

project/
├── 01 Splash.html        → <a href="02%20Login.html">Continue</a>
├── 02 Login.html         → <a href="03%20Onboarding.html">Next</a>
├── 03 Onboarding.html
└── shared/
    └── styles.css         → <link href="shared/styles.css">

🔒 Cross-project: read-only + copy_files explícito

A regra que pega muito iniciante

Outro projeto Claude Design seu é read-only. Claude pode LER arquivos (texto, código) — mas se você referenciar um asset (imagem, CSS) via path direto, o HTML renderizado não carrega (path externo bloqueado pelo iframe).

// ✗ ERRADO: referenciar asset de outro projeto
<img src="../other-project/logo.svg">
// Resultado: imagem quebrada no preview

// ✓ CORRETO: copiar primeiro
"Use copy_files to bring 'logo.svg' from project 'acme-pitch'
into the current project. Then reference it as ./logo.svg"

copy_files herda asset metadata

"Revisões feitas via copy_files herdam automaticamente o asset." — system prompt

Se você copia Hero.html (que tinha asset: 'final') para Hero v2.html, o asset metadata vai junto. Aparece no painel de revisão automaticamente.

Limite de copy_files em massa

"Não copie em massa pastas grandes de recursos (>20 arquivos) — faça cópias direcionadas apenas dos arquivos necessários, ou escreva primeiro seu arquivo e depois copie somente os assets que ele referencia."

⛔ As proibições absolutas (4 itens)

Proibição	Por quê	Use em vez
`scrollIntoView()`	Bagunça o web app que envolve o iframe	`window.scrollTo()` ou manual via offsetTop
`type="module"` em scripts	Quebra escopo do Babel inline	Plain `<script>` ou `<script type="text/babel">`
`const styles = {}`	Naming collision em scope global do Babel	`const buttonStyles = {}` (prefixo único)
Versão React não-pinned	Quebra integrity check	React@18.3.1 com SHA específico

⚠️ Crash silencioso #1 da Claude Design

Naming collision em styles. Por ser silencioso (nenhum erro de console), você só descobre quando algo "não funciona" sem motivo aparente. Sempre prefixe.

📐 .napkin sketches + content fixo + IP rule

Esboços .napkin (citação literal)

"Quando um arquivo .napkin for anexado, leia sua miniatura em scraps/.{filename}.thumbnail.png — o JSON é só dado bruto de desenho, não é útil diretamente."

Se você usa Napkin (ferramenta de sketch da própria Anthropic), Claude lê a thumbnail PNG, não o JSON. Esboço vira input visual.

Conteúdo de tamanho fixo (defaults)

"Decks de slides, apresentações, vídeos e outros conteúdos de tamanho fixo devem implementar sua própria escala em JS para que o conteúdo caiba em qualquer viewport: uma tela fixa (padrão 1920×1080, 16:9) envolta em um palco de viewport completo que a enquadra em preto via transform: scale(), com controles anterior/próximo fora do elemento escalado para que continuem utilizáveis em telas pequenas."

Aspect ratio	Resolução	Use case
16:9 (default)	1920×1080	Decks, vídeos horizontais
9:16 (vertical)	1080×1920	Stories, Reels, vertical video
1:1 (square)	1080×1080	Posts Instagram, square ads
4:3 (legacy)	1024×768	Apresentações antigas

Para qualquer ratio diferente de 16:9, peça explicitamente — deck_stage.js é hardcoded 1920×1080.

⚖️ IP rule — não-overridable

Claude verifica seu domínio de email. Não pode recriar UI distintiva de outra empresa a menos que você seja daquela empresa. Faz parte do "ethical floor" — user prompt NÃO sobrescreve.

Email	Pedido	Resultado
@stripe.com	"recrie a UI do Stripe"	permitido
@anyone.com	"recrie a UI do Stripe"	recusa + alternativa original
@anyone.com	"design inspirado em Stripe"	permitido (inspiração ≠ recriação)

🧰 Tools no-op + tags <system> + a estrutura de mensagens

Tools "no-op" — não bloqueiam

"A ferramenta de tarefas não bloqueia nem fornece saída útil, então chame sua próxima ferramenta imediatamente na mesma mensagem."

Algumas tools (como o gerenciador de tarefas interno) não retornam output útil para você ver. Claude as usa em paralelo com outras na mesma mensagem.

Tags <system> e <webview_inline_comments>

Algumas mensagens dentro da conversa vêm com tags de sistema:

•<system> — instruções sistema runtime (você não vê, Claude lê)
•<webview_inline_comments> — quando você comenta no canvas, vem nesse envelope
•<mentioned-element> — bloco com react/dom/id (visto em 3.3)

Se você perguntar "o que diz a tag system?" — Claude recusa (regra "não divulgar").

Resumo extremamente breve no fim

"Resuma de forma EXTREMAMENTE BREVE — apenas ressalvas e próximos passos."

Por isso Claude Design quase nunca faz "wall of text" no fim. Se você QUER explicação detalhada, peça explicitamente: "Now explain in detail what you built and why".

✅ Resumo do Módulo

✓

GitHub flow 4 tools — connect_github → list_repos (default_branch) → get_tree (path_prefix) → import_files. Plus github_read_file solo.

✓

URLs entre páginas — relative path (preferido) · ?file= · #file= legacy. URL encoded para espaços.

✓

Cross-project read-only — copy_files explícito. Asset metadata herdado. Limite >20 arquivos.

✓

4 proibições absolutas — scrollIntoView, type="module", const styles={}, versão não-pinned.

✓

.napkin via thumbnail PNG — não JSON cru.

✓

Aspect ratios fixos — 1920×1080 default; 1080×1920 vertical; 1080×1080 square; 1024×768 legacy.

✓

IP rule não-overridable — domínio de email gate. "Inspirado em" funciona, "recrie" não.

✓

Tags <system> secretas — Claude lê mas não revela. Resumo final é "EXTREMAMENTE BREVE".

Próximo Módulo:

3.7 — 🎛️ Tweaks protocol completo: 4 mensagens postMessage + EDITMODE-BEGIN/END

← Módulo 3.5 Módulo 3.7 →