Communitygithub.com

WordPress 主題建置

將靜態 HTML/CSS/JS 設計轉換為客戶可編輯的自訂 WordPress 主題,涵蓋主題結構、theme.json、腳本入隊、區塊模式、自訂文章類型及可編輯內容。

WordPress 主題建置 是什麼?

這項技能提供了一套完整的流程,將靜態 HTML/CSS/JS 設計轉換為自訂 WordPress 主題。它涵蓋了主題結構、theme.json 設定、資產入隊、區塊模式、自訂文章類型和可編輯內容,確保設計鎖定在程式碼中,而內容可在編輯器中編輯。該技能介紹了三種方法:純區塊主題、混合經典主題和子主題,並附有選擇指南,協助開發者根據專案需求選擇最合適的方法。它包含詳細的轉換工作流程,從凍結靜態建置、拆解樣板,到將設計 token 移入 theme.json。此外,還說明了正確入隊腳本(包括 GSAP 等動畫函式庫)、使內容可編輯(使用自訂文章類型、區塊模式、自訂欄位、自訂器),以及正確輸出資料(使用 esc_html 等跳脫函式)的最佳實務。該技能也強調了動畫整合、除錯和交機檢查清單等注意事項,以防止常見錯誤,如硬編碼文字或破壞編輯器行為。支援的平台包括任何標準 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: My Theme
Author: Your Name
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. 將 token 移入 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.

相關技能