Communitygithub.com

wordpress-theme-build

Turn a static HTML/CSS/JS design into a custom WordPress theme that the client can edit, covering theme structure, theme.json, enqueueing scripts, block patterns, custom post types and editable content. Use this whenever someone wants to convert a design or static site to WordPress, build a custom or block theme, make sections editable in Gutenberg, add GSAP or other scripts to a theme properly, or asks why their theme edits are lost or their content is hard-coded.

What is wordpress-theme-build?

wordpress-theme-build is a Claude Code agent skill that turn a static HTML/CSS/JS design into a custom WordPress theme that the client can edit, covering theme structure, theme.json, enqueueing scripts, block patterns, custom post types and editable content. Use this whenever someone wants to convert a design or static site to WordPress, build a custom or block theme, make sections editable in Gutenberg, add GSAP or other scripts to a theme properly, or asks why their theme edits are lost or their content is hard-coded.

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

Ask in your favorite AI

Open a new chat with this agent skill pre-loaded.

Documentation

WordPress theme build

The goal is a theme where the design is locked in code and the content is editable in the editor. Hard-coded text in templates is the most common reason clients come back for trivial edits.

Choose the approach

ApproachChoose when
Block theme (theme.json, HTML templates)New build, client edits in the Site Editor, content is mostly standard blocks
Hybrid classic theme (PHP templates plus theme.json and block patterns)Complex custom markup or heavy animation that needs exact HTML control
Child themeModifying an existing theme; never edit a parent theme directly, since updates overwrite it

For animated, design-led marketing sites the hybrid approach is usually the pragmatic one: precise markup in PHP, editable content through patterns, fields and the block editor.

Minimum structure

my-theme/
├── style.css            # theme header comment (required)
├── functions.php        # setup, enqueues, registrations
├── theme.json           # palette, type scale, spacing, layout widths
├── index.php            # fallback template (classic/hybrid)
├── front-page.php       # homepage
├── header.php  footer.php
├── template-parts/      # one file per section
├── patterns/            # block patterns (auto-registered)
├── assets/css  assets/js  assets/media
└── screenshot.png       # 1200x900

style.css header:

/*
Theme Name: My Theme
Author: Your Name
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 8.0
Text Domain: my-theme
*/

Conversion workflow

  1. Freeze the static build. Finish HTML, CSS and JS first and validate it. Converting a moving target doubles the work.
  2. Split into parts. Header and footer go to header.php and footer.php with wp_head() and wp_footer(). Each homepage section becomes a file in template-parts/, loaded with get_template_part().
  3. Move tokens into theme.json (palette, font sizes, spacing, content width) so the editor shows the same choices as the front end. Keep the same values as CSS custom properties; WordPress generates --wp--preset--* variables you can alias. If the webcraft CLI is available, webcraft tokens "#brand" --format theme-json -o theme.json writes a version 3 file from the same values as tokens.css.
  4. Enqueue, never hard-code, assets:
add_action('wp_enqueue_scripts', function () {
    $v = wp_get_theme()->get('Version');
    $uri = get_theme_file_uri('assets');
    wp_enqueue_style('my-theme', "$uri/css/main.css", [], $v);
    wp_enqueue_script('gsap', "$uri/js/vendor/gsap.min.js", [], '3', ['strategy' => 'defer', 'in_footer' => true]);
    wp_enqueue_script('my-theme', "$uri/js/main.js", ['gsap'], $v, ['strategy' => 'defer', 'in_footer' => true]);
});

Bundle libraries locally rather than from a CDN where possible; it avoids a third-party request and a consent question. 5. Make content editable. Pick per section:

  • Repeating items with their own pages (services, portfolio, testimonials): a custom post type queried with WP_Query.
  • One-off section text and images: block patterns the client inserts and edits, or custom fields.
  • Global items (phone, social links, footer text): the Customizer or a small options page.
  • Navigation: register_nav_menus() and wp_nav_menu().
  1. Escape everything on output: esc_html(), esc_attr(), esc_url(), wp_kses_post() for rich text. Wrap strings in __() or esc_html__() with the text domain.
  2. Images: use wp_get_attachment_image() so srcset, sizes, dimensions and lazy loading are generated. Register needed sizes with add_image_size().
  3. Theme supports: title-tag, post-thumbnails, editor-styles, responsive-embeds, html5, wp-block-styles.

Animation inside WordPress

  • Scripts that hide content must not run in the block editor. Enqueue them only on the front end (wp_enqueue_scripts, not enqueue_block_assets).
  • The admin bar shifts sticky headers by 32px (46px on mobile); offset with body.admin-bar .header { top: var(--wp-admin--admin-bar--height, 32px); }.
  • Caching and optimization plugins that defer or combine JS can break load order. Declare dependencies properly so they are respected, and test with the plugin enabled.
  • Content added in the editor will not have your animation attributes. Either apply animations by block class in JS, or provide patterns that include the attributes.

Do not

  • Edit WordPress core or a parent theme.
  • Put functionality that should survive a theme switch (custom post types, shortcodes) in the theme when the client may change themes; a small plugin is the right place.
  • Query inside loops without resetting (wp_reset_postdata()).
  • Ship with WP_DEBUG notices. Develop with WP_DEBUG on.
  • Bundle paid plugins or assets whose licence does not allow redistribution.

Handover checklist

  • Client can change every visible text, image, menu item and contact detail without touching code.
  • Homepage set under Settings, Reading; permalinks set to post name.
  • Favicon (site icon), 404 template, search template, privacy page present.
  • A one-page editing guide with screenshots.
  • Then run the launch-qa skill.

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.

Related Skills