SimilarBuild

Visual migration framework para Claude Code — clona uma página live e entrega arquivo pronto pra colar como WordPress/Elementor HTML widget ou Shopify section .liquid, validado e auto-corrigido.

O que é

SimilarBuild é uma framework distribuída como plugin de skills do Claude Code. Em vez de você manualmente abrir DevTools, copiar HTML, ajustar CSS, corrigir anti-patterns e medir diff visual, a framework orquestra 8 sub-skills determinísticas atrás de 3 slash commands que entregam o arquivo pronto:

• /build-page <url> — clona uma página live → arquivo pronto.
• /build-site <url> — descobre todas as páginas, confirma com você (único checkpoint humano), clona em batch.
• /clip-section <url> --selector <css> — clona uma section específica via CSS selector → widget HTML / section Liquid.

Pipeline padrão (cada step é uma sub-skill):

inspect-live → extract-assets → build-{wp|shopify} → validate-static-render
            → compare-visual → review-checks → (auto-correct loop) → entrega

Características principais:

• Mobile-first (iPhone 14, 390×844 CSS px, DPR 3) — alinhado live↔build.
• WordPress/Elementor ou Shopify Section (com {% schema %} editável).
• Auto-correção: review-checks + compare-visual alimentam fixHints num loop determinístico (até auto_correct_max_iterations).
• Decision matrix 2×2 (review.passed × compare.passed) decide entrega vs loop vs escalation — sem heurísticas frágeis baseadas só em diff%.
• Memória machine-parseable (anti-patterns / patterns / fixes / design-knowledge) lida via cascata <plugin> → ~/.claude/similarbuild-memory → bundled fallback.
• Cumulative HTML report com slider live⇆build interativo, history embutido como <script type="application/json"> no próprio arquivo.

Quick start

Pré-requisitos

• Node.js ≥ 20 (usa fetch e crypto nativos).
• Claude Code instalado (claude.ai/code ou CLI).
• ~150MB livres pra npx playwright install chromium.

Instalar no seu projeto

Dentro de qualquer diretório de projeto onde você quer usar a framework:

npx similarbuild install

O installer faz, em ordem:

1. Verifica Node ≥ 20.
2. Pergunta 5 configurações (com defaults sensatos):
   • output_folder (default: sb-output)
   • default_target (wp | shopify, default: wp)
   • default_viewport (default: iphone-14)
   • auto_correct_max_iterations (default: 3)
   • diff_threshold_percent (default: 10)
3. Copia templates pra .claude/{commands,skills,skills/sb-shared/{memory,presets},templates/reports}.
4. Cria .claude/sb-config.yaml (seguro re-rodar — preserva config existente).
5. Garante ~/.claude/similarbuild-memory/ pra auto-learn per-user.
6. Cria stub package.json se faltar e instala 10 deps runtime (playwright, sharp, pixelmatch, cheerio, liquidjs, etc.).
7. Confirma e roda npx playwright install chromium.

Flags úteis:

| Flag | Quando usar | |------------------|-------------------------------------------------------| | --yes, -y | usa defaults sem prompts (CI / re-install rápido) | | --no-deps | pula npm install (deps já instaladas) | | --no-chromium | pula download do Chromium (~150MB) | | --dry-run | só imprime o que faria, sem escrever |

Atualizar

npx similarbuild update

Re-baixa templates novos preservando .claude/sb-config.yaml e ~/.claude/similarbuild-memory/.

Primeira execução

Abra o projeto no Claude Code e rode:

/build-page https://example.com

A framework dispara o pipeline ponta-a-ponta e entrega o arquivo em <output_folder>/<project-slug>/{slug}/build.{html|liquid}.

Slash commands

/build-page <url> [--target wp|shopify] [--selector <css>]

Clona uma página live e entrega arquivo pronto. Se --selector for passado, só extrai e clona aquele scope (equivalente a /clip-section por baixo).

Output: {output_folder}/{project-slug}/{page-slug}/build.{html|liquid}, render.json, compare.json, review.json, screenshots, report.html.

/build-site <url> [--target wp|shopify]

Descobre páginas via sitemap.xml (fallback: crawl HTML) → apresenta tabela → você aplica filtros (skip/only/exclude/include) → confirma → clona em batch sequencial.

Único checkpoint humano da framework. Confirmação dupla pra reduzir erros em batches grandes (Pattern #35).

Output: mesmo layout do /build-page por página, mais report.html cumulativo agregado e auto-learn consolidado no fim.

/clip-section <url> --selector <css>

Single-shot section via CSS selector. Validação rigorosa do selector (escala se não casar — sem fabrication). Live é element-only (sem --crop-live-bbox).

Configuração

.claude/sb-config.yaml — gerado pelo installer, editável livremente:

output_folder: sb-output
default_target: wp                    # ou: shopify
default_viewport: iphone-14
auto_correct_max_iterations: 3
diff_threshold_percent: 10

Skills usam defaults inline se a config estiver ausente — você pode deletar o arquivo e tudo continua funcionando.

Memória

Três camadas, lidas em cascata (Pattern #21):

1. <plugin>/templates/memory/*.md — versionada, vem com o release npm.
2. ~/.claude/similarbuild-memory/*.md — per-user, populada por /build-site auto-learn batched.
3. <skill>/references/*.md — bundled fallback dentro de cada skill.

Cada arquivo é machine-parseable (campos id/name/applies-to/applies-when/symptom/fix-recipe/detector/severity/origin).

Como funciona — sub-skills

| Sub-skill | Papel | |------------------------|--------------------------------------------------------------------| | sb-inspect-live | Playwright + stealth → DOM, tokens, screenshot, bbox da section. | | sb-extract-assets | Baixa imagens, strip metadata (EXIF/XMP/IPTC), dedupe content-hash. | | sb-build-wp | Compõe HTML/Elementor com defensive specificity + a11y/perf. | | sb-build-shopify | Compõe .liquid com {% schema %} editável + shims locais. | | sb-validate-static-render | Renderiza fragment offline (preset YAML), captura screenshot+tokens.| | sb-compare-visual | pixelmatch + token cross-check, scope-aware crops simétricos. | | sb-review-checks | Cheerio audit de 14 anti-patterns + 12 design checks (a11y/perf/web).| | sb-tweak | Edita arquivo entregue via pedido natural PT/EN, atomic-revert. | | sb-crawl-and-list | Sitemap-first + cheerio fallback, classifica + ordena pra UI. |

Targets suportados

WordPress / Elementor (--target wp)

Saída: HTML standalone com defensive specificity (#elementor-editor / .elementor-widget), mobile-first CSS, alt text, loading="lazy", fetchpriority="high" no hero img, rel="preload" quando bg-image.

Cole no widget HTML do Elementor.

Shopify Section (--target shopify)

Saída: .liquid com {% schema %} editável (settings, presets), imagem hero via image_picker setting (sem default — anti-pattern #12), fallback via SVG base64 inline (sem path absoluto — anti-pattern #16), {{ block.shopify_attributes }} em qualquer iteração, sem Google Fonts <link> inline (anti-pattern #14).

Cole em sections/<nome>.liquid no tema Dawn / OS 2.0 / Sense.

Anti-patterns que a framework previne

A v0.1.0 codifica 14 anti-patterns descobertos em smoke tests reais (example-store.com WP+Shopify track):

1. 100vh no hero — quebra mobile (URL bar dinâmica).
2. Hero <img> sem fetchpriority="high" + <link rel="preload"> quando é background-image (detection two-step com confidence-tier).
3. <img> sem alt — bloqueia a11y.
4. CSS sem mobile-first — desktop-first quebra responsive.
5. Defensive specificity ausente (selectors que vazam pro tema host).
6. Caminho absoluto do dev em fallback (/Users/..., C:\Users\...).
7. Schema image_picker com default fixo — UX ruim (Shopify).
8. Block iteration sem {{ block.shopify_attributes }} (Shopify).
9. Google Fonts <link> inline na section (Shopify).
10. Inspector full-page com section específica (scope mismatch no diff).
11. 404 silencioso em CDN do source — comportamento normal, não escalar.
12. Prettier corrompendo {% schema %} JSON — fix via placeholder.
13. {% style %}/{% javascript %} em liquidjs vanilla — shim local.
14. image_picker sem default + mock context vazio infla diff — --assets-map-path resolve.

Veja templates/memory/anti-patterns.md pro contrato machine-parseable.

CI / publishing

Releases tagged via GitHub triggam npm publish automático (.github/workflows/publish.yml).

Setup obrigatório no repo (uma vez):

1. Settings → Secrets and variables → Actions → New repository secret.
2. Nome: NPM_TOKEN.
3. Valor: token gerado em https://www.npmjs.com/settings//tokens (tipo: Automation — pula 2FA challenge no publish).

Depois disso, gh release create v0.1.0 (ou Releases → Draft new release → Publish) dispara o workflow e publica no npm.

prepublishOnly roda scripts/sync-templates.mjs (.claude/{commands,skills/sb-*} → templates/{commands,skills/}) — garante que o tarball sempre tem a versão mais nova das skills sem precisar lembrar.

Roadmap V2 (próximos)

A v0.1.0 cobre MVP V1: 12 entry points (3 slash commands + 9 sub-skills), 14 anti-patterns codificados, 2 targets (WP + Shopify), decision matrix explícita.

Itens em consideração pra V2:

• Paralelismo no /build-site — hoje é sequencial (1 página por vez), V2 com pool de N workers.
• sb-tweak em batch — receber lista de pedidos PT/EN, aplicar todos com two-phase confirmation (Pattern #35).
• Targets adicionais — Webflow, Framer, raw HTML standalone, MDX.
• sb-build-react — componente .tsx em vez de markup serializado.
• Detector de anti-pattern #16 em sb-review-checks — regex pra paths absolutos (/Users/, /home/, C:\Users\\) no output final.
• Visual regression suite — report.html com diff cumulativo de N runs, gráfico de evolução do diff%.
• i18n no sb-tweak — hoje aceita PT/EN, expandir pra ES/FR.

Issues e sugestões: https://github.com/eggonbassoli/similarbuild/issues

Desenvolvimento

git clone https://github.com/eggonbassoli/similarbuild
cd similarbuild
npm install                          # instala devDependencies (deps reais das skills)
npm run sync-templates               # .claude/* → templates/*
npm run smoke:install                # bin/install.js --help

Cada sub-skill tem testes em .claude/skills/sb-<nome>/scripts/tests/. Rodar:

node .claude/skills/sb-inspect-live/scripts/tests/test-inspect-live.mjs
# ... etc

Total V1: 153 unit/smoke tests passando.

Licença

MIT © 2026 SimilarBuild Authors — veja LICENSE.