Communitygithub.com

construção-de-tema-wordpress

Converta um design HTML/CSS/JS estático em um tema WordPress personalizado que o cliente pode editar, abrangendo estrutura do tema, theme.json, scripts, padrões de bloco, tipos de post personalizados e conteúdo editável.

O que é construção-de-tema-wordpress?

Esta habilidade é um guia completo para desenvolvedores que desejam converter designs estáticos ou sites estáticos em temas WordPress totalmente funcionais e editáveis pelo cliente. O objetivo principal é garantir que o design permaneça fiel ao código, enquanto todo o conteúdo (textos, imagens, menus) possa ser gerenciado pelo editor do WordPress (Gutenberg) sem necessidade de tocar em código. A habilidade oferece três abordagens principais: tema de bloco (totalmente baseado em `theme.json` e templates HTML), tema híbrido (combinação de PHP com `theme.json` e padrões de bloco) e tema filho (para modificar temas existentes), ajudando o desenvolvedor a escolher a melhor opção com base nas necessidades do projeto. Além disso, fornece um workflow de conversão passo a passo, desde o congelamento do design estático e divisão em partes, passando pela configuração de `theme.json`, enfileiramento correto de ativos (como GSAP), criação de conteúdo editável com tipos de post personalizados e campos personalizados, até práticas recomendadas para escapar saída e evitar erros comuns como editar o núcleo do WordPress ou quebrar animações no editor. A habilidade também inclui uma checklist de entrega para garantir que o cliente possa gerenciar todo o conteúdo visível sem código.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add https://github.com/imperfec-t/webcraft/tree/HEAD/skills/wordpress-theme-build

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Construção de tema WordPress

O objetivo é um tema onde o design está fixo no código e o conteúdo é editável no editor. Texto codificado diretamente em templates é a razão mais comum pela qual clientes voltam para edições triviais.

Escolha a abordagem

AbordagemQuando escolher
Tema de bloco (theme.json, templates HTML)Nova construção, cliente edita no Editor do Site, conteúdo é principalmente blocos padrão
Tema clássico híbrido (templates PHP mais theme.json e padrões de bloco)Marcação personalizada complexa ou animação pesada que precisa de controle exato do HTML
Tema filhoModificar um tema existente; nunca edite um tema pai diretamente, pois atualizações o sobrescrevem

Para sites de marketing com design animado, a abordagem híbrida geralmente é a mais pragmática: marcação precisa em PHP, conteúdo editável através de padrões, campos e o editor de blocos.

Estrutura mínima

meu-tema/
├── style.css            # comentário de cabeçalho do tema (obrigatório)
├── functions.php        # configuração, enfileiramentos, registros
├── theme.json           # paleta, escala de tipos, espaçamento, larguras de layout
├── index.php            # template de fallback (clássico/híbrido)
├── front-page.php       # página inicial
├── header.php           # cabeçalho
├── footer.php           # rodapé
├── template-parts/      # um arquivo por seção
├── patterns/            # padrões de bloco (registrados automaticamente)
├── assets/css           # folhas de estilo
├── assets/js            # scripts
├── assets/media         # mídia
└── screenshot.png       # 1200x900

Cabeçalho style.css:

/*
Theme Name: Meu Tema
Author: Seu Nome
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 8.0
Text Domain: meu-tema
*/

Workflow de conversão

  1. Congele a construção estática. Termine o HTML, CSS e JS primeiro e valide. Converter um alvo em movimento dobra o trabalho.
  2. Divida em partes. Cabeçalho e rodapé vão para header.php e footer.php com wp_head() e wp_footer(). Cada seção da página inicial se torna um arquivo em template-parts/, carregado com get_template_part().
  3. Mova tokens para theme.json (paleta, tamanhos de fonte, espaçamento, largura de conteúdo) para que o editor mostre as mesmas opções que o front-end. Mantenha os mesmos valores das propriedades CSS personalizadas; o WordPress gera variáveis --wp--preset--* que você pode alias. Se o CLI webcraft estiver disponível, webcraft tokens "#brand" --format theme-json -o theme.json escreve um arquivo versão 3 a partir dos mesmos valores de tokens.css.
  4. Enfileire, nunca codifique, ativos:
add_action('wp_enqueue_scripts', function () {
    $v = wp_get_theme()->get('Version');
    $uri = get_theme_file_uri('assets');
    wp_enqueue_style('meu-tema', "$uri/css/main.css", [], $v);
    wp_enqueue_script('gsap', "$uri/js/vendor/gsap.min.js", [], '3', ['strategy' => 'defer', 'in_footer' => true]);
    wp_enqueue_script('meu-tema', "$uri/js/main.js", ['gsap'], $v, ['strategy' => 'defer', 'in_footer' => true]);
});

Agrupe bibliotecas localmente em vez de a partir de uma CDN sempre que possível; evita uma requisição de terceiros e uma questão de consentimento. 5. Torne o conteúdo editável. Escolha por seção:

  • Itens repetitivos com suas próprias páginas (serviços, portfólio, depoimentos): um tipo de post personalizado consultado com WP_Query.
  • Texto e imagens de seções únicas: padrões de bloco que o cliente insere e edita, ou campos personalizados.
  • Itens globais (telefone, links de redes sociais, texto do rodapé): o Customizer ou uma pequena página de opções.
  • Navegação: register_nav_menus() e wp_nav_menu().
  1. Escape tudo na saída: esc_html(), esc_attr(), esc_url(), wp_kses_post() para rich text. Envolva strings em __() ou esc_html__() com o text domain.
  2. Imagens: use wp_get_attachment_image() para que srcset, sizes, dimensões e lazy loading sejam gerados. Registre os tamanhos necessários com add_image_size().
  3. Suportes do tema: title-tag, post-thumbnails, editor-styles, responsive-embeds, html5, wp-block-styles.

Animação dentro do WordPress

  • Scripts que ocultam conteúdo não devem rodar no editor de blocos. Enfileire-os apenas no front-end (wp_enqueue_scripts, não enqueue_block_assets).
  • A barra de administração desloca cabeçalhos fixos em 32px (46px no mobile); compense com body.admin-bar .header { top: var(--wp-admin--admin-bar--height, 32px); }.
  • Plugins de cache e otimização que adiam ou combinam JS podem quebrar a ordem de carregamento. Declare dependências corretamente para que sejam respeitadas, e teste com o plugin ativado.
  • Conteúdo adicionado no editor não terá seus atributos de animação. Aplique animações por classe de bloco em JS, ou forneça padrões que incluam os atributos.

Não faça

  • Edite o núcleo do WordPress ou um tema pai.
  • Coloque funcionalidade que deve sobreviver a uma troca de tema (tipos de post personalizados, shortcodes) no tema quando o cliente pode trocar de tema; um pequeno plugin é o lugar certo.
  • Consulte dentro de loops sem resetar (wp_reset_postdata()).
  • Envie com avisos WP_DEBUG. Desenvolva com WP_DEBUG ligado.
  • Agrupe plugins pagos ou ativos cuja licença não permita redistribuição.

Checklist de entrega

  • O cliente pode alterar todo texto, imagem, item de menu e detalhe de contato visível sem tocar em código.
  • Página inicial definida em Configurações, Leitura; permalinks definidos como nome do post.
  • Favicon (ícone do site), template 404, template de busca, página de privacidade presentes.
  • Um guia de edição de uma página com capturas de tela.
  • Em seguida, execute a habilidade launch-qa.

Individual skills in this repo

This repo contains 8 individual skills — each has its own dedicated page.

design-tokens

Create a website's visual system as CSS custom properties, covering color palette, typography scale, spacing, radius and shadows, with contrast checked. Use this whenever someone asks for a color scheme, a palette from one brand color, font pairing, a type scale, "make it look consistent", dark mode, a rebrand of an existing site into new colors, or starts a build with no defined styles.

hero-section

Design and build the hero (first screen) of a website, including headline layout, media treatment, CTA, proof badge, marquee and entrance animation. Use this whenever someone asks for a hero section, a landing page header, "the top of my homepage", a cinematic or animated intro, a video background, a text marquee, or says their first screen looks plain or generic.

homepage-blueprint

Plan the section structure and content slots of a homepage for an agency, freelancer, studio or service business before any design or code. Use this whenever someone asks "what sections should my homepage have", "plan my website", "structure a landing page for my business", wants a wireframe or sitemap for a service site, or starts building a homepage without a clear outline.

launch-qa

Run a pre-launch quality check on a website covering performance, accessibility, SEO basics, forms, cross-device behavior and content, and report findings ranked by severity with fixes. Use this whenever someone says a site is "ready to launch", "going live", asks "can you check my site", wants a QA pass, a website audit, a Lighthouse-style review, or wants to know why a page is slow or scoring badly.

responsive-layout

Build page layouts that work from phones to wide desktops using CSS grid, flexbox, container queries and fluid sizing, including card grids, bento grids, split sections, sticky sidebars and navigation that collapses. Use this whenever someone says their site "breaks on mobile", asks for a responsive grid, a bento layout, a mobile menu, fixing horizontal scroll or overflow, or is laying out any multi-column section.

scroll-motion

Add scroll-driven and entrance animation to a website with GSAP, ScrollTrigger and Lenis, including reveals, parallax, pinned sections, horizontal scroll, line drawing, counters and preloaders. Use this whenever someone wants a site to "feel premium", asks for smooth scrolling, scroll animations, parallax, text reveals, a pinned or sticky scroll section, an animated preloader, or names GSAP, ScrollTrigger, Lenis, Locomotive or AOS.

site-teardown

Analyze a live website and turn it into a section-by-section build brief that another person or AI can rebuild from, with brand name, colors, fonts and images swapped for placeholders. Use this whenever someone shares a URL and says "analyze this site", "make something like this", "give me a prompt to build this", "recreate this effect", "clone the layout with my branding", or asks how a page's animation or structure works, even if they never say "teardown".

website-workflow

Plan and sequence a whole website build, from structure through design, code, WordPress and launch, by routing each stage to the right webcraft skill. Use this when someone asks to "build me a website", "design my site from scratch", "redo our homepage", wants an end-to-end plan for a marketing, agency, studio or service site, or the request spans more than one of structure, look, layout, motion, CMS and QA.

Habilidades Relacionadas