Communitygithub.com

WordPress 主题构建

将静态 HTML/CSS/JS 设计转化为客户端可编辑的自定义 WordPress 主题,涵盖主题结构、theme.json、脚本入队、区块模式、自定义文章类型和可编辑内容。当需要将设计或静态网站转换为 WordPress、构建自定义或区块主题、使内容在古腾堡编辑器中可编辑、正确添加 GSAP 或其他脚本、或者解决主题编辑丢失或内容硬编码的问题时使用。

WordPress 主题构建 是什么?

该技能指导开发者将静态 HTML/CSS/JS 设计转换为专业、可维护的自定义 WordPress 主题,特别适合构建以设计为主导、注重动画的市场营销网站。它提供了明确的决策指导,帮助选择区块主题、混合经典主题或子主题方案,并强调将设计锁定在代码中,同时确保客户端内容在编辑器中完全可编辑,从而避免常见的硬编码文本带来的维护问题。 技能涵盖完整的构建工作流程:从冻结静态构建、拆分模板块、将设计令牌迁移到 theme.json,到正确入队资产并避免 CDN 依赖、根据不同内容类型选择适当的方法使内容可编辑(如自定义文章类型、区块模式、自定义字段、导航菜单等),以及正确处理动画相关的特殊注意事项(如编辑器兼容性、管理栏偏移、缓存插件的影响等)。 该技能适用于任何 WordPress 主题构建场景,无论是使用基于 HTML 的区块主题(通过 theme.json 和 Site Editor 进行完全可视化编辑),还是使用需要精确 HTML 控制的混合经典主题(PHP 模板结合 theme.json 和区块模式),亦或是对现有主题进行修改的子主题。它还强调良好的开发实践:始终转义输出、使用 WordPress 图像函数处理响应式图片、正确注册主题支持功能,并提供了详细的交接清单,确保客户端可以独立编辑所有可见内容。

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

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

WordPress 主题构建 是做什么的?

目标是创建一个设计锁定在代码中、内容在编辑器中可编辑的主题。模板中的硬编码文本是客户要求进行琐碎修改的最常见原因。

选择方法

方法何时选择
区块主题(theme.json、HTML 模板)新构建,客户在站点编辑器中进行编辑,内容主要是标准区块
混合经典主题(PHP 模板加上 theme.json 和区块模式)需要精确 HTML 控制的复杂自定义标记或大量动画
子主题修改现有主题;切勿直接编辑父主题,因为更新会覆盖它

对于以动画、设计为导向的市场营销网站,混合方法通常是务实的选择:在 PHP 中保留精确的标记,通过模式、字段和区块编辑器使内容可编辑。

最小结构

my-theme/
├── style.css            # 主题头部注释(必需)
├── functions.php        # 设置、入队、注册
├── theme.json           # 调色板、字号、间距、布局宽度
├── index.php            # 回退模板(经典/混合)
├── front-page.php       # 首页
├── header.php  footer.php
├── template-parts/      # 每个部分一个文件
├── patterns/            # 区块模式(自动注册)
├── assets/css  assets/js  assets/media
└── screenshot.png       # 1200x900

style.css 头部:

/*
Theme Name: 我的主题
Author: 你的名字
Version: 1.0.0
Requires at least: 6.4
Requires PHP: 8.0
Text Domain: my-theme
*/

转换工作流程

  1. 冻结静态构建。 首先完成 HTML、CSS 和 JS 并验证。转换一个不断变化的目标会使工作量加倍。
  2. 拆分为部件。 头部和脚部放入 header.php 和 footer.php,并调用 wp_head() 和 wp_footer()。每个首页部分成为 template-parts/ 中的一个文件,通过 get_template_part() 加载。
  3. 将令牌迁移到 theme.json(调色板、字号、间距、内容宽度),以便编辑器显示与前端的相同选项。保持与 CSS 自定义属性相同的值;WordPress 会生成 --wp--preset--* 变量,你可以为其创建别名。如果 webcraft CLI 可用,webcraft tokens "#brand" --format theme-json -o theme.json 会根据与 tokens.css 相同的值写入一个第 3 版文件。
  4. 入队资产,切勿硬编码:
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]);
});

尽可能将库文件打包到本地,而不是使用 CDN;这可以避免第三方请求和同意问题。 5. 使内容可编辑。 按部分选择:

  • 拥有独立页面的重复项(服务、作品集、推荐信):使用 WP_Query 查询的自定义文章类型。
  • 一次性章节文本和图片:客户端插入和编辑的区块模式,或自定义字段。
  • 全局项目(电话、社交链接、页脚文本):使用自定义器或小型选项页面。
  • 导航:register_nav_menus() 和 wp_nav_menu()。
  1. 输出时转义所有内容: esc_html()、esc_attr()、esc_url()、富文本使用 wp_kses_post()。使用 __() 或 esc_html__() 包裹字符串,并指定文本域。
  2. 图片: 使用 wp_get_attachment_image() 以便生成 srcset、sizes、尺寸和懒加载。使用 add_image_size() 注册所需的尺寸。
  3. 主题支持: title-tag、post-thumbnails、editor-styles、responsive-embeds、html5、wp-block-styles。

WordPress 中的动画

  • 隐藏内容的脚本不得在区块编辑器中运行。仅在前端入队它们(使用 wp_enqueue_scripts,而不是 enqueue_block_assets)。
  • 管理栏会使固定头部偏移 32px(移动端 46px);使用 body.admin-bar .header { top: var(--wp-admin--admin-bar--height, 32px); } 进行补偿。
  • 延迟或合并 JS 的缓存和优化插件可能会破坏加载顺序。正确声明依赖关系,并启用插件进行测试。
  • 编辑器中添加的内容不会具有你的动画属性。要么在 JS 中按区块类应用动画,要么提供包含这些属性的模式。

禁止事项

  • 编辑 WordPress 核心或父主题。
  • 将应在主题切换后保留的功能(自定义文章类型、短代码)放在主题中;如果客户可能会更换主题,小型插件才是正确的位置。
  • 在循环内部进行查询而不重置(wp_reset_postdata())。
  • 在启用 WP_DEBUG 的情况下发布带有通知的代码。开发时请打开 WP_DEBUG。
  • 捆绑付费插件或其许可证不允许再分发的资产。

交接清单

  • 客户可以更改所有可见文本、图片、菜单项和联系信息,而无需接触代码。
  • 在“设置”>“阅读”中设置首页;永久链接设置为文章名称。
  • 存在网站图标(站点图标)、404 模板、搜索模板、隐私页面。
  • 提供包含截图的单页编辑指南。
  • 然后运行 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.

相关技能