claude-plugins/wordpress/skills/emcp-page-building/SKILL.md

name, description, layer

name	description	layer
emcp-page-building	Construção e edição de páginas Elementor via qualquer ligação MCP EMCP Tools (emcp-descomplicar, emcp-emanuelalmeida, emcp-tools/starter, ou outra). Cobre elementos atómicos Elementor 4.0+, containers/widgets legacy, templates, operações em lote, e as armadilhas reais de parâmetros/comportamento encontradas por teste ao vivo. Usar quando "construir página elementor", "emcp page building", "widget atómico", "add-flexbox", "apply-template", "criar página com mcp".	wiki

/emcp-page-building — Construção de Páginas Elementor via EMCP Tools

Aplica-se a qualquer ligação MCP EMCP Tools, não a um site específico. Confirma sempre o site alvo com core/get-site-info antes de escrever — nunca assumas pelo nome da ligação.

Factos abaixo verificados ao vivo contra uma instalação EMCP Tools 3.12.1 em produção (Elementor 4.2.2 + Pro), revertidos depois via ledger. Descrevem o comportamento do plugin, por isso generalizam a qualquer site com a mesma versão — reverifica numa página de rascunho descartável se o site tiver uma versão materialmente diferente.

Ordem de descoberta (antes de construir algo desconhecido)

1. detect-elementor-version — confirma suporte atómico + recommended_mode ("atomic" em sites 4.0+, usar tools atómicas por omissão).
2. list-widgets (opcional tier: free|pro|woo, category, ou pesquisa livre) — catálogo curado nativo Elementor/Pro/Woo. Não inclui widgets de terceiros (ElementsKit, PowerPack) — ver skills elementskit-widgets e powerpack-widgets.
3. get-widget-schema({ widget_type }) — o parâmetro é widget_type, não type. Nome errado falha com um erro genérico de "propriedade obrigatória" que não diz qual campo.
4. get-container-schema — schema completo de controlos de container (flex + grid).
5. get-page-structure({ post_id }) antes de tocar numa página existente — conhece sempre a árvore actual antes de mutar.

Atómico (Elementor 4.0+) vs legacy — coexistem na mesma página

Confirmado ao vivo: uma página com um e-flexbox atómico (com widgets e-heading/e-paragraph filhos) ao lado de um container legacy (com um widget heading legacy) gravou e renderizou a estrutura correctamente. Não é preciso escolher um modo por página.

• Containers atómicos: add-flexbox, add-div-block. Widgets atómicos só ligam a estes (ou a outro container atómico) como parent_id — add-atomic-heading etc. rejeitam um container legacy como pai.
• Containers legacy: add-container. Widgets legacy (add-free-widget, ex. widget_type: "heading") só ligam a containers legacy.
• Usa legacy para qualquer widget sem equivalente atómico ainda — confirmado ao vivo: widgets de terceiros como elementskit-*/elementskit-wp-forms só existem como widgets legacy.
• update-element funciona em elementos atómicos e legacy genericamente. update-atomic-widget é a variante de merge parcial específica para atómicos — preferir para atómicos, mas update-element é o fallback universal seguro.
• batch-update({ post_id, operations: [{element_id, settings}, ...] }) actualiza vários elementos (atómicos ou legacy, misturados) numa só gravação — preferir sempre isto a N chamadas sequenciais de update-element.

🔴 Armadilhas confirmadas ao vivo — não confiar só na descrição da tool

1. set-element-label: o campo real obrigatório é title, não label, apesar da descrição "Sets an element's Navigator label" sugerir label. Ler o schema (read xd://mcp__<ligação>_emcp_tools_set_element_label) antes da primeira utilização numa ligação nova.
2. add-custom-js: exige parent_id (tem de ser um container legacy — insere um widget HTML) e o campo de código é js, não code. Não liga a um e-flexbox/e-div-block atómico.
3. apply-template pode substituir TODO o conteúdo existente da página em vez de inserir. Testado: chamar apply-template(post_id, template_id) sem position explícito numa página com 7 elementos existentes resultou em substituição total — só ficaram os elementos do template (elements_added igual à contagem própria do template). A descrição sugere inserção ("at a given position, inserting its elements"); o comportamento observado foi sobrescrita. Sequência obrigatória: get-page-structure antes → apply-template(..., position: -1) explícito → get-page-structure depois, comparar. Se o conteúdo foi apagado, recuperar via rollback-change na entrada mais recente de list-changes para esse post_id (ver skill emcp-site-audit) — confirmado a funcionar.
4. create-theme-template fica publicado de imediato, não como rascunho. Testado: create-theme-template(type:"single", title:"...") devolveu status: "publish" com conditions.include: [{"object":"all-singular"}] por omissão — com conteúdo vazio, aplicar-se-ia de imediato a todo o singular do site. Chamar logo set-template-conditions para restringir o alcance antes de construir conteúdo, ou delete-theme-template de imediato se criado por engano (confirmado limpo/reversível).
5. get-element-settings normaliza os wrappers $$type atómicos; get-page-structure e export-page não. Para o mesmo heading atómico, get-element-settings devolve {"title": "string simples"} enquanto os outros dois mostram a estrutura crua {"$$type":"html-v3","value":{"content":{"$$type":"string","value":"..."}}}. Usar get-element-settings para "qual é o valor agora"; usar get-page-structure/export-page para entender ou reproduzir a estrutura crua de prop-types atómicos.
6. set-post-terms com create_missing:true deixa termos de taxonomia permanentes — sem tool de eliminação de termos no conjunto activo em nenhum site testado até agora. Confirmar o nome do termo antes de usar em conteúdo descartável/teste.

Construir uma página de raiz — sequência recomendada

1. create-page({ title, status: "draft" }) — nunca construir directamente numa página publicada.
2. add-flexbox({ post_id, settings: { flex_direction, gap } }) (ou add-div-block) para o primeiro container estrutural. add-container só se precisares especificamente de comportamento legacy ou nesting sob uma árvore legacy existente.
3. Aninhar widgets atómicos: add-atomic-heading/add-atomic-paragraph/add-atomic-button/add-atomic-image/add-atomic-svg/add-atomic-video/add-atomic-youtube/add-atomic-divider, ou o genérico add-atomic-widget para o que não tenha tool de conveniência.
4. Para qualquer widget legacy necessário (Pro/terceiros ainda sem versão atómica, add-pro-widget se o deny-list do site permitir): add-container depois add-free-widget.
5. Verificar com get-page-structure após cada passo relevante, não só no fim.
6. reorder-elements, move-element, duplicate-element, remove-element operam por ID de elemento das chamadas de structure/find-element — nunca adivinhar IDs.
7. set-element-label({ post_id, element_id, title }) para manter o Navigator legível em páginas complexas (campo title, ver armadilha #1).
8. update-page-settings para definições de página ao nível Elementor (background, padding, CSS custom — funcionalidades Pro degradam de forma graciosa se indisponíveis).
9. Antes de publicar: get-page-snapshot para um único digest normalizado (estrutura + contagens + cores/tipografia globais em uso + resumo SEO-lite) em vez de encadear chamadas separadas de structure/global-settings/classes.

Tokens de design globais

• get-global-settings — kit de todo o site (cores, tipografia, espaçamento, breakpoints).
• update-global-colors/update-global-typography — muta o kit directamente; afecta todas as páginas que usam esses tokens, confirmar com o utilizador primeiro.
• list-global-classes — resolve IDs g- do Class Manager do Elementor 4.0 para nomes/CSS legíveis. Normalmente só-leitura; create-global-class/update-global-class/delete-global-class/reorder-global-classes estão comummente no deny-list (mutação de CSS partilhado) — verificar se estão montadas antes de assumir que funcionam.

Templates

• list-templates (templates guardados na biblioteca Elementor, qualquer tipo: page/section/container) e save-as-template para criar novos. Não há tool de eliminação de template no conjunto comummente activo em nenhum site testado — guardar um template é efectivamente permanente via MCP. Obter confirmação explícita antes de save-as-template.
• import-template/export-page para estruturas JSON portáveis.
• Theme Builder (create-theme-template/list-theme-templates/get-theme-template/update-theme-template/set-template-conditions/resolve-template/delete-theme-template) — ver armadilha #4 acima. list-condition-targets antes de set-template-conditions para ver selectores/post-types/taxonomias válidos naquele site.

Padrão de teste seguro

Nunca experimentar numa página publicada real. create-page(status:"draft"), construir/mutar livremente, confirmar via get-page-structure, depois delete-post(post_id) (vai para o Lixo — reversível; só force:true se o utilizador pedir explicitamente remoção permanente). Verificar list-changes depois — toda a escrita aqui fica registada no ledger, por isso um teste falhado é sempre recuperável com rollback-change mesmo antes de chegares a apagar o rascunho.

Skills relacionadas

• emcp-content-ops — operações de conteúdo WordPress (posts/pages/media/menus/redirects/blocos).
• emcp-site-audit — scan de segurança, análise de performance, acesso só-leitura a BD/filesystem, ledger de mudanças.
• elementor-pro-widgets — catálogo completo de widgets nativos Elementor Pro.
• elementskit-widgets / powerpack-widgets — catálogos de widgets de terceiros (não estão no catálogo curado do EMCP).
• emcp-tools — arquitectura do plugin, inventário completo de ~162 abilities, mecanismo de deny-list.