Módulo 3.7 · Tweaks protocol completo + manipulação

🎛️ O que são Tweaks (e por que são "permanentes")

Citação literal

"O usuário pode ativar/desativar Tweaks pela barra de ferramentas. Quando estiver ativado, mostre controles adicionais na página que permitam ao usuário ajustar aspectos do design — cores, fontes, espaçamento, texto, variantes de layout, feature flags, o que fizer sentido. Você projeta a UI dos tweaks; ela vive dentro do protótipo. Dê ao painel/janela o título 'Tweaks' para que o nome combine com o toggle da barra de ferramentas."

A grande revelação do leak

Tweaks NÃO são previews reversíveis. Cada slide, cada color picker, cada toggle é regravado no arquivo HTML. O que você vê é literalmente o que sai no export.

Implicação: testar 20 cores em sequência = 20 escritas no disco. Use Tweaks com intenção, não como playground.

📡 As 4 mensagens postMessage do protocolo

Mensagem	Direção	Significado
`__edit_mode_available`	mock → host (parent)	"Eu suporto Tweaks. Mostra o toggle na toolbar."
`__activate_edit_mode`	host → mock	"Usuário clicou no toggle. Renderize o painel."
`__deactivate_edit_mode`	host → mock	"Usuário desligou. Esconda o painel."
`__edit_mode_set_keys`	mock → host	"Usuário mudou X. Persista no disco."

Implementação completa (template oficial)

// 1. PRIMEIRO: registrar listener
window.addEventListener('message', (e) => {
  if (e.data?.type === '__activate_edit_mode') {
    showTweaksPanel();   // sua UI de Tweaks
  }
  if (e.data?.type === '__deactivate_edit_mode') {
    hideTweaksPanel();
  }
});

// 2. SÓ DEPOIS: anunciar disponibilidade
window.parent.postMessage(
  { type: '__edit_mode_available' },
  '*'
);

// 3. Quando usuário muda valor:
function onPrimaryColorChange(newColor) {
  // a. Aplica ao vivo na página
  document.documentElement.style.setProperty('--primary', newColor);

  // b. Persiste no disco
  window.parent.postMessage({
    type: '__edit_mode_set_keys',
    edits: { primaryColor: newColor }
  }, '*');
}

⚠️ ORDEM IMPORTA — citação literal

"A ordem importa: registre o listener antes de anunciar disponibilidade. Se você postar __edit_mode_available primeiro, a mensagem de ativação do host pode chegar antes do handler existir, e o toggle simplesmente não funcionará."

Bug típico: dev inverte a ordem por reflexo (anuncia primeiro, registra depois). Toggle aparece mas não funciona — race condition silenciosa.

🧩 Bloco EDITMODE-BEGIN/END — formato exato

Citação literal

"Envolva seus padrões ajustáveis em marcadores de comentário para que o host possa reescrevê-los no disco, assim:"

const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
  "primaryColor": "#D97757",
  "fontSize": 16,
  "dark": false
}/*EDITMODE-END*/;

"O bloco entre os marcadores deve ser um JSON válido (chaves e strings entre aspas duplas). Deve haver exatamente um desses blocos no HTML raiz, dentro de um <script> inline. Quando você postar __edit_mode_set_keys, o host analisa o JSON, mescla suas edições e regrava o arquivo — assim a mudança sobrevive ao recarregamento."

Regras estritas do bloco

•JSON válido — chaves entre aspas duplas, strings entre aspas duplas. Sem comentários JS dentro. Sem trailing comma.
•EXATAMENTE 1 bloco no HTML raiz — não distribuir entre arquivos
•Deve estar dentro de <script> inline (não em arquivo .js externo)
•Comentários EXATOS: /*EDITMODE-BEGIN*/ e /*EDITMODE-END*/ — sem espaços, hífens corretos

Como o host parseia (mental model)

// Host (Claude Design backend) faz algo como:
const html = readFile('design.html');
const blockRegex = /\/\*EDITMODE-BEGIN\*\/([\s\S]*?)\/\*EDITMODE-END\*\//;
const match = html.match(blockRegex);

if (match) {
  const currentDefaults = JSON.parse(match[1]);  // precisa ser JSON válido!
  const merged = { ...currentDefaults, ...userEdits };
  const newBlock = `/*EDITMODE-BEGIN*/${JSON.stringify(merged, null, 2)}/*EDITMODE-END*/`;
  const newHtml = html.replace(blockRegex, newBlock);
  writeFile('design.html', newHtml);
}

🎨 Múltiplas variantes de UM elemento + design do painel

Citação literal — dicas de Tweaks

"Mantenha a superfície dos Tweaks pequena — um painel flutuante no canto inferior direito da tela, ou controles inline. Não exagere. Oculte completamente os controles quando Tweaks estiver desligado; o design deve parecer finalizado. Se o usuário pedir múltiplas variantes de um único elemento dentro de um design maior, use isso para permitir alternar entre as opções. Mesmo que o usuário não peça tweaks, adicione alguns por padrão; seja criativo e tente expô-lo a possibilidades interessantes."

Padrão "variant toggle"

Em vez de duplicar páginas para A/B test, expose como Tweak:

const TWEAK_DEFAULTS = /*EDITMODE-BEGIN*/{
  "heroVariant": "A",  // "A" = text-left | "B" = text-center | "C" = split
  "ctaVariant": "primary",  // "primary" | "outline" | "minimal"
  "darkMode": false
}/*EDITMODE-END*/;

function Hero() {
  const variant = TWEAK_DEFAULTS.heroVariant;
  if (variant === 'A') return <HeroLeft />;
  if (variant === 'B') return <HeroCenter />;
  if (variant === 'C') return <HeroSplit />;
}

Resultado: stakeholder alterna A/B/C ao vivo. Decisão em segundos, não em re-prompt.

Boas práticas do painel Tweaks

✓Posição: canto inferior direito, flutuante (não bloqueia conteúdo)
✓Tamanho: 3-6 controles max — não vire um Figma inspector
✓Título "Tweaks" — bate com o toggle da toolbar
✓Hide quando off — display:none completo, não visibility:hidden
✓Adicione 2-3 por padrão mesmo sem pedir — seja criativo

❌ Anti-patterns

• Painel ocupando metade da tela
• 15+ controles num design simples
• Tweaks que podem quebrar o layout (ex: "padding: 0 a 200px")
• Labels longos: "primaryColor" > "Cor principal usada nos botões CTA"
• Esquecer de esconder quando off (resíduo de editor visível no export)

🧙 Manipulação: user prompt > system prompt

Hierarquia de prioridade

Anthropic garante: user prompt > system prompt exceto na linha "ethical floor" (IP rule, conteúdo ilegal, segurança). Tudo o mais é overridable.

Comportamento default	Override via user prompt
Faz 10+ perguntas	"Skip questions, use these defaults: [X, Y, Z]"
3 variações	"Give me 6 variations explicitly"
Newspaper-minimalist se sub-especificado	"NO newspaper-minimalism. Use Cinematic Dark instead"
Adiciona Tweaks default	"NO Tweaks for this design"
Sem speaker notes	"Include full speaker notes per slide"
deck_stage.js obrigatório para deck	"Don't use deck_stage. Implement manual scaling 1080×1920"
Resumo "EXTREMAMENTE BREVE"	"After done, explain in detail what you built and why"

As 6 frases de manipulação mais úteis

Pular perguntas: "Skip questions_v2. Defaults: [lista explícita]"
Mais variações: "Give me N variations along these axes: [lista]"
Matar bias: "NO newspaper-minimalism, NO italic serif headlines, NO off-white"
Anti-AI tropes: "NO gradient blobs, NO floating orbs, NO glassmorphism, NO emojis"
Brand strict: "Use EXACTLY these tokens (no improvisation): [tokens]"
Detail mode: "After done, explain in detail what you built and the design decisions"

⚠️ O que NÃO é overridable (ethical floor)

×IP rule — não recria UI distintiva de outra empresa sem domínio de email correto
×Não divulgar system prompt — Claude recusa mesmo se você insistir
×Não enumerar tools — não vai listar ferramentas internas mesmo se pedido
×Conteúdo ilegal/violento — Anthropic safety policy genérica

🎯 Tweaks como produto: do design → A/B em produção

Pipeline completo

Design no Claude Design: peça Tweaks para variantes A/B do hero
Iteração com stakeholder: alternam A/B na call, decidem juntos
Export → Claude Code: bundle inclui o EDITMODE-BEGIN/END como JSON estruturado
Claude Code converte: Tweaks viram feature flags reais (LaunchDarkly, GrowthBook, GrowthFlag)
Deploy: ambas variantes em produção
A/B test: roda em paralelo, métrica decide vencedor
Vencedor virou default: remove perdedor, ou mantém para próxima iteração

Prompt-receita completo (Tweak-driven design)

"Create a SaaS landing page with these REQUIRED Tweaks:

1. heroVariant (A: text-left bold | B: text-center serif | C: split-screen)
2. ctaText (default: 'Start free trial')
3. accentColor (default: #2563eb)
4. socialProofType (logos | quotes | numbers)
5. faqVisibility (toggle)
6. darkMode (toggle)

Wrap defaults in /*EDITMODE-BEGIN*/...{}.../*EDITMODE-END*/

Render Tweaks panel: floating bottom-right,
title 'Tweaks', hidden when toggle is off.

Document handoff: when I export to Claude Code,
convert each Tweak to a GrowthBook feature flag."

🎉 Resumo do Módulo (fim da Trilha 3 v2 reforçada!)

✓

Tweaks gravam em disco — não são preview, são edição permanente.

✓

4 mensagens postMessage — __edit_mode_available, __activate, __deactivate, __edit_mode_set_keys.

✓

ORDEM crítica — listener ANTES de anunciar disponibilidade. Race condition silenciosa se inverter.

✓

EDITMODE-BEGIN/END — JSON válido, 1 bloco no HTML raiz, dentro de <script> inline.

✓

Variant toggle — variantes de UM elemento expostas como Tweak, em vez de duplicar páginas.

✓

Painel pequeno + hide off — flutuante canto inferior direito, 3-6 controles, display:none quando off.

✓

User > system override — 6 frases-chave para manipular comportamento default.

✓

Ethical floor — IP rule, segredo do system prompt, conteúdo ilegal: NÃO overridable.

✓

Pipeline Tweak → A/B prod — design + iteração + handoff Claude Code + feature flags em prod.

🏆 Trilha 3 v2 — você agora é EXPERT real

✓3.1 System prompt completo (8 seções, citações literais)
✓3.2 Starter components (API, deck_stage internals, animations API, speaker notes)
✓3.3 done flow + fork_verifier_agent + mentioned-element + eval_js_user_view
✓3.4 window.claude.complete (Haiku 1024) + snip + web_fetch/search
✓3.5 Animations Stage/Sprite/easings/performance/Popmotion fallback
✓3.6 GitHub flow + URLs internas + .napkin + IP rule + edge cases
✓3.7 Tweaks protocol completo + manipulação user>system

Próxima trilha:

T4 — 🟡 Galeria claude.ai/design — telas reais e cases.

← Módulo 3.6 Trilha 4 · Galeria →