Tạo theme WordPress từ đầu — 5 bước build block theme

Tự build theme WordPress từ đầu cho phép giữ markup, hiệu năng và brand identity dưới quyền kiểm soát hoàn toàn — không gánh 300-500KB cồng kềnh từ theme premium. Bài này hướng dẫn 5 bước build block theme 2026 cho shop bán hàng VN: cấu trúc folder, theme.json design system, template HTML, block pattern, deploy production.

Vì sao tự build theme block trong context 2026

Theme premium phổ biến như Astra Pro, Flatsome, Avada ship 200-500KB CSS và 250-350KB JS để cover mọi feature. Site thực tế chỉ dùng 10-30% lượng code đó, phần còn lại trở thành dead weight kéo tụt LCP.

Tự build theme cho shop riêng giúp giữ bundle 30-50KB total, code clean theo nghiệp vụ và dễ maintain dài hạn. Trade-off: dev time 40-80 giờ cho lần đầu, đổi lại tốc độ và quyền kiểm soát vượt trội.

3 lợi ích chính khi build theme từ đầu

• Hiệu năng tier 1: chỉ ship CSS và JS dùng — LCP dưới 1,5s khả thi mà không cần plugin tối ưu phụ trợ.
• Brand identity riêng: không bị template look-alike với 100k site khác cùng dùng một theme premium.
• Dễ maintain: code đơn giản, không hidden hook chain phức tạp — dev mới onboard 2-3 ngày là nắm.

Khi nào KHÔNG nên build theme từ đầu

Build theme từ đầu không phải lựa chọn cho mọi site. Có 3 trường hợp nên dùng theme premium hoặc child theme thay vì build mới.

• Site nhỏ ngân sách hạn chế: blog cá nhân, landing 1-2 trang dưới 5 triệu — theme miễn phí hoặc premium nhẹ tiết kiệm hơn 40-80 giờ dev.
• Deadline gấp dưới 2 tuần: build theme custom mất 4-6 tuần kể cả test, deadline gấp nên chọn theme có sẵn rồi tinh chỉnh nhỏ.
• Không có dev WordPress chuyên trách: theme custom đòi hỏi maintain liên tục — nếu không có dev trong team thì lệ thuộc freelancer dài hạn.

Bước 1 — Cấu trúc folder block theme

WordPress 6.0 trở lên yêu cầu block theme có folder structure cụ thể để FSE nhận diện. Folder /templates chứa HTML cho page template, /parts cho component tái dùng, /assets cho CSS+JS, /patterns chứa PHP cho block pattern.

Folder structure chuẩn

web22-shop/
├── style.css           # Theme metadata header + CSS chính
├── theme.json          # Design system config (color, font, layout)
├── functions.php       # Hook + enqueue + register
├── index.php           # Fallback (block theme không bắt buộc)
├── templates/
│   ├── index.html      # Default template (fallback)
│   ├── single.html     # Single post
│   ├── page.html       # Static page
│   ├── archive.html    # Category/tag archive
│   ├── single-product.html  # WooCommerce single product
│   └── 404.html
├── parts/
│   ├── header.html
│   ├── footer.html
│   └── post-meta.html
├── patterns/
│   ├── hero.php
│   ├── featured-products.php
│   └── footer-cta.php
└── assets/
    ├── css/
    └── js/

Vai trò từng file trong folder

Mỗi file trong block theme có nghiệp vụ riêng — hiểu sai vai trò dẫn tới hierarchy lỗi hoặc admin báo theme broken. Bốn file gốc cần nắm kỹ trước khi đi sâu vào template.

• style.css: WordPress đọc 12 dòng đầu để register theme — thiếu header này, theme không xuất hiện trong Appearance.
• theme.json: single source of truth cho color, font, spacing — Site Editor đọc file này để hiển thị token cho user.
• functions.php: chỉ chứa enqueue style+script, register pattern, theme support — KHÔNG nhét logic page vào đây.
• index.html trong /templates: fallback khi WordPress không tìm thấy template phù hợp — đảm bảo site không bao giờ trắng trang.

Bước 2 — style.css header và theme.json cơ bản

style.css đầu file phải có theme metadata header để WordPress register theme trong admin. theme.json chứa design system config dùng cho Site Editor và frontend cùng lúc.

style.css header bắt buộc

/*
Theme Name: Web22 Shop
Theme URI: https://web22.vn/themes/shop
Author: Web22
Description: Block theme cho shop bán hàng VN, performance-first
Version: 1.0.0
Requires at least: 6.0
Tested up to: 6.5
Requires PHP: 8.0
License: GPL v2 or later
Text Domain: web22-shop
Tags: full-site-editing, block-theme, woocommerce
*/

theme.json minimum config

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 2,
  "settings": {
    "color": {
      "palette": [
        { "slug": "primary", "color": "#0066cc", "name": "Primary" },
        { "slug": "text", "color": "#1a1a1a", "name": "Text" }
      ]
    },
    "typography": {
      "fontFamilies": [
        { "slug": "inter", "fontFamily": "Inter, sans-serif", "name": "Inter" }
      ]
    },
    "layout": {
      "contentSize": "720px",
      "wideSize": "1200px"
    }
  }
}

Mở rộng theme.json cho design system thật

Config minimum đủ cho prototype nhưng thiếu spacing scale, shadow, border radius — những token một shop production cần. Mở rộng thêm 3 nhóm token sau để Site Editor đủ control cho người không code.

• Spacing scale 8pt: definition 7 step từ 4px tới 96px dưới settings.spacing.spacingSizes — token này áp cho margin, padding, gap.
• Shadow preset: 3 level shadow (sm, md, lg) dưới settings.shadow.presets — Site Editor cho user chọn dropdown thay vì gõ tay CSS.
• Border radius scale: 0, 4px, 8px, 16px, 9999px dưới custom property — phù hợp 95% trường hợp design hiện đại.

Bước 3 — Template HTML core

Block theme dùng HTML file thay PHP cho template — cú pháp giống Gutenberg block markup. Index.html là fallback cho mọi context không match template cụ thể hơn trong hierarchy.

templates/index.html

<!-- wp:template-part {"slug":"header","tagName":"header"} /-->

<!-- wp:group {"tagName":"main","layout":{"type":"constrained"}} -->
<main class="wp-block-group">
  <!-- wp:query {"queryId":1,"query":{"perPage":10,"postType":"post"}} -->
  <div class="wp-block-query">
    <!-- wp:post-template -->
      <!-- wp:post-title {"isLink":true} /-->
      <!-- wp:post-excerpt /-->
    <!-- /wp:post-template -->
  </div>
  <!-- /wp:query -->
</main>
<!-- /wp:group -->

<!-- wp:template-part {"slug":"footer","tagName":"footer"} /-->

parts/header.html — component tái dùng

<!-- wp:group {"layout":{"type":"flex","justifyContent":"space-between"}} -->
<div class="wp-block-group">
  <!-- wp:site-logo /-->
  <!-- wp:navigation /-->
</div>
<!-- /wp:group -->

Template hierarchy WordPress áp dụng

Block theme tuân theo template hierarchy y như classic theme — WordPress tìm template theo thứ tự ưu tiên từ cụ thể tới chung. Hiểu hierarchy giúp đặt tên file đúng để override một context riêng mà không ảnh hưởng template chung.

• Single post: tìm theo thứ tự single-post-{slug}.html → single-post.html → single.html → index.html — đặt tên cụ thể để override 1 bài.
• Category archive: category-{slug}.html → category-{id}.html → category.html → archive.html → index.html — phổ biến để custom layout cho category lớn.
• WooCommerce single product: single-product.html → single.html → index.html — block theme support Woo từ phiên bản 8.3 trở lên.

Bước 4 — Register block pattern và nâng cao

Block pattern là markup tái dùng — user paste vào page editor 1 click thay vì gõ từng block. Register qua /patterns folder PHP với header comment, không cần đăng ký tay trong functions.php.

patterns/hero.php

<?php
/**
 * Title: Hero Section
 * Slug: web22-shop/hero
 * Categories: featured
 * Description: Hero section landing page với heading và CTA
 */
?>
<!-- wp:cover {"url":"<?php echo get_template_directory_uri(); ?>/assets/hero.webp"} -->
<div class="wp-block-cover">
  <!-- wp:heading {"level":1,"fontSize":"x-large"} -->
  <h1>Shop bán hàng tối ưu CWV cho VN</h1>
  <!-- /wp:heading -->
  <!-- wp:paragraph -->
  <p>Theme block 2026, performance-first, không cồng kềnh</p>
  <!-- /wp:paragraph -->
  <!-- wp:buttons -->
  <div class="wp-block-buttons">
    <!-- wp:button -->
    <div class="wp-block-button">
      <a class="wp-block-button__link" href="/shop/">Mua ngay</a>
    </div>
    <!-- /wp:button -->
  </div>
  <!-- /wp:buttons -->
</div>
<!-- /wp:cover -->

Block pattern category và sync pattern

WordPress 6.3 trở lên hỗ trợ sync pattern — pattern dùng nhiều nơi, sửa 1 chỗ tự update toàn site. Khác biệt với normal pattern (paste rời, sửa từng nơi) cần lưu ý khi thiết kế hệ thống pattern cho shop.

• Normal pattern: phù hợp hero section, FAQ block, đánh giá khách — mỗi page có nội dung riêng dù layout giống.
• Sync pattern: phù hợp footer CTA, contact box, banner promo — đổi 1 chỗ là update mọi page.
• Custom category: đăng ký category riêng qua register_block_pattern_category() để pattern shop xuất hiện trong tab riêng, không lẫn pattern WP core.

Register block custom React khi pattern không đủ

Khi pattern markup tĩnh không đáp ứng được nghiệp vụ (vd: product slider có config quantity, autoplay) cần build custom block React. Workflow build custom block xem chi tiết ở bài Custom block FSE riêng để giữ bài này tập trung vào theme structure.

Bước 5 — Deploy production

Theme dev local xong, deploy qua SFTP hoặc git pull trên VPS. Test toàn bộ template và pattern trên staging trước khi switch live để bắt lỗi sớm.

Workflow deploy chuẩn

1. Zip theme folder web22-shop/ với utility zip (giữ nguyên cấu trúc folder).
2. Vào Admin → Appearance → Themes → Add New → Upload Theme → chọn file zip.
3. Activate theme — WordPress sẽ hiển thị Site Editor mới.
4. Test mọi template: home, single post, category archive, search result, 404.
5. Test pattern: insert vào page mới, verify render đúng style.
6. Test responsive 3 breakpoint: mobile 375px, tablet 768px, desktop 1280px.
7. Test admin: Site Editor cho navigation menu, Customizer hoạt động.

Pre-launch checklist 6 điểm

• Lighthouse mobile score trên 90: chạy Lighthouse incognito 3 lần, lấy median — phải đạt cả Performance và Accessibility.
• 0 lỗi JS trong console: mở DevTools, browse hết 5-10 page, screenshot console — KHÔNG có warning hay error.
• Schema valid: test qua Schema.org validator hoặc Rich Results Test cho JSON-LD Article và Organization.
• Image hero reserved dimension: CLS dưới 0,1 — width+height attribute trên mọi img tag.
• Font self-host: KHÔNG nhúng Google Fonts CDN — download .woff2, upload /assets/fonts/, font-display: swap.
• Backup database và theme cũ: dùng UpdraftPlus hoặc lệnh mysqldump trước khi switch — rollback nhanh nếu issue.

Monitor và maintain sau launch

Theme custom sống dài hạn cần workflow monitor đều — bỏ qua maintain dẫn tới drift performance hoặc compatibility issue khi WordPress update major. Ba việc tối thiểu nên đưa vào lịch hàng tháng.

• Lighthouse audit hàng tháng: chạy lại Lighthouse mobile để bắt regression — score tụt 5 điểm trở lên cần investigate ngay.
• WP core update test: trước update WordPress major (vd 6.5 → 6.6) test theme trên staging 1 ngày để bắt deprecated function.
• Carbon Fields plugin compat: nếu theme dùng Carbon Fields cho meta box, check plugin version compat với WP version mới.

Câu hỏi thường gặp

Tài nguyên và bước tiếp theo

Build theme block từ đầu là bước nền — sau khi nắm cấu trúc cơ bản, mở rộng sang các topic chuyên sâu khác để hoàn thiện theme production. Các bài liên quan trong cụm WordPress development:

• theme.json 2026 — design system config cho block theme — chi tiết palette, font, spacing, layout token.
• Block theme vs Classic theme — so sánh 8 khía cạnh — decision matrix cho dự án 2026.
• Template hierarchy WordPress — 6 context và pattern override — nắm sâu hierarchy để custom đúng chỗ.
• Custom block FSE — 5 bước build block React — khi pattern markup không đủ, cần block React riêng.
• Dịch vụ thiết kế website WordPress chuyên nghiệp — tham khảo gói thi công theme custom trọn gói.

Cần đội Web22 dev theme/plugin WordPress custom theo nhu cầu shop của bạn? Xem dịch vụ thiết kế website WordPress của Web22 — báo giá rõ ràng theo phạm vi, không phát sinh sau khi ký hợp đồng.