theme.json WordPress và vai trò trung tâm cấu hình block theme

Trước khi có tệp này, một theme muốn đổi màu chủ đạo phải sửa CSS rải rác ở nhiều chỗ, lại còn cập nhật riêng cho trình soạn thảo (editor) để khớp với mặt tiền (front-end). Cách làm đó dễ lệch và khó bảo trì. Từ WordPress 5.8, một tệp JSON duy nhất gánh toàn bộ phần khai báo này, và đến 2026 nó là nền tảng bắt buộc của mọi block theme.

theme.json giải quyết vấn đề gì

Hãy hình dung một dự án có 20 file CSS, mỗi nơi định nghĩa một màu coral khác nhau một chút. Khi khách yêu cầu đổi sang màu khác, bạn phải dò từng file. Với theme.json, bạn khai báo màu đó một lần ở phần settings; WordPress tự tạo ra một biến CSS (CSS variable — biến dùng lại được trong CSS) như --wp--preset--color--primary và áp cho cả trình soạn thảo lẫn trang hiển thị. Sửa một dòng, đổi cả site.

Đó là lý do tệp này được ví như hệ thần kinh trung tâm của theme: nó là nguồn sự thật duy nhất (single source of truth) cho màu, font, spacing và bố cục. Khi tự code theme cho khách, đội Web22 đặt phần lớn quyết định thiết kế vào đây thay vì viết tay từng đoạn CSS — vừa gọn, vừa cho khách chỉnh qua giao diện mà không phá vỡ hệ thống.

Cấu trúc một tệp theme.json

Tệp gồm vài khối cấp cao nhất (top-level): $schema, version, settings, styles, và các khối liên quan đến cấu trúc trang như customTemplates, templateParts, patterns. Hai khối quan trọng nhất là settings (cho phép chỉnh gì) và styles (mặc định trông ra sao).

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {
    "appearanceTools": true,
    "useRootPaddingAwareAlignments": true
  },
  "styles": {}
}

$schema giúp trình soạn thảo code gợi ý cú pháp và báo lỗi sớm. appearanceTools: true bật một loạt công cụ thiết kế (viền, đổ bóng, khoảng cách…) chỉ bằng một dòng thay vì bật từng cái.

Khối settings — khai báo màu, font, spacing

Đây là nơi định nghĩa các giá trị có sẵn (preset). Ví dụ bảng màu:

"settings": {
  "color": {
    "palette": [
      { "name": "Coral",  "slug": "primary", "color": "#FF6986" },
      { "name": "Mực",     "slug": "ink",     "color": "#1A1A1A" },
      { "name": "Nền nhạt","slug": "base",    "color": "#FAFAF8" }
    ]
  }
}

Mỗi mục có slug riêng. WordPress sẽ sinh biến --wp--preset--color--primary và một lớp tiện ích .has-primary-color. Bạn dùng lại biến này ở bất kỳ đâu trong styles mà không cần gõ lại mã màu.

Phần typography (chữ) tương tự, và từ WordPress 6.6 có thêm fluid typography (cỡ chữ co giãn theo bề rộng màn hình) — chữ tự lớn dần trên màn rộng, nhỏ lại trên điện thoại, không cần media query (truy vấn theo kích thước màn hình):

"typography": {
  "fluid": true,
  "fontSizes": [
    {
      "name": "Tiêu đề lớn",
      "slug": "x-large",
      "size": "2.5rem",
      "fluid": { "min": "1.75rem", "max": "2.5rem" }
    }
  ]
}

Khối settings.spacing (với spacingScale hoặc spacingSizes) và settings.layout (khai contentSize, wideSize cho bề rộng nội dung) hoàn thiện bộ khung. Nhờ vậy, nút canh “wide” (rộng) hay “full” (tràn) trong editor đều ăn khớp đúng số đo bạn đặt.

Khối styles — diện mạo mặc định

Nếu settings là “được phép dùng gì” thì styles là “mặc định trông thế nào”. Đáng giá nhất ở đây là styles.elements — định kiểu cho các phần tử dùng chung như nút, liên kết, tiêu đề, mà không cần viết CSS riêng:

"styles": {
  "color": { "background": "var(--wp--preset--color--base)" },
  "elements": {
    "link":   { "color": { "text": "var(--wp--preset--color--primary)" } },
    "button": {
      "color": {
        "background": "var(--wp--preset--color--primary)",
        "text": "var(--wp--preset--color--base)"
      }
    }
  }
}

Khai một lần ở đây, mọi nút và liên kết trong toàn site đồng nhất. Muốn chỉnh sâu hơn cho một block cụ thể (ví dụ chỉ block trích dẫn), bạn lồng vào styles.blocks theo tên block.

Vai trò trong Full Site Editing

Full Site Editing (FSE — chỉnh sửa toàn site bằng block, gồm cả header, footer, mẫu trang) chỉ chạy trơn khi có theme.json làm nền. Hai khối liên quan trực tiếp:

• templateParts: khai báo các phần dùng lại như header, footer kèm thuộc tính area, để WordPress nhận diện và cho khách thay thế như những mảnh ghép độc lập.
• customTemplates: đăng ký các mẫu trang riêng (ví dụ mẫu trang đích không sidebar) và quy định post type nào được dùng.

Quan trọng hơn, mọi nút chỉnh màu, font, spacing mà khách thấy trong giao diện Styles của FSE đều bắt nguồn từ những preset bạn khai trong theme.json. Bạn kiểm soát “sân chơi”, khách tự do trong sân đó mà không làm vỡ thiết kế. Đây cũng là điểm khác cốt lõi giữa block theme và classic theme đời cũ.

Version 3 khác version 2 ở đâu

Thuộc tính version hiện nhận giá trị 2 hoặc 3. Version 3 ra mắt cùng WordPress 6.6 và là khuyến nghị cho mọi theme nhắm 6.6 trở lên. Nó giữ nguyên kiến trúc version 2 (nâng cấp mượt, tương thích ngược) và bổ sung:

• Bộ chọn (selector) ngữ nghĩa và độ ưu tiên (specificity) rõ ràng hơn, giảm xung đột CSS.
• Tinh gọn lượng CSS mà WordPress sinh ra, nhẹ trang hơn.
• Hỗ trợ tốt hơn cho fluid typography và spacing.

Nếu đang khởi tạo theme mới năm 2026, hãy bắt đầu thẳng với "version": 3. Nếu nâng từ theme cũ, đổi số version rồi rà lại phần selector tùy biến là phần lớn việc đã xong.

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

theme.json đặt ở đâu trong theme?

Ngay thư mục gốc của theme, cùng cấp với style.css và functions.php. WordPress tự nhận và đọc, không cần khai báo thêm trong code.

Có thay thế hoàn toàn file style.css không?

Không. theme.json lo các giá trị toàn cục và preset. Những hiệu ứng đặc thù, hoạt ảnh hay style ngoài phạm vi block vẫn cần CSS. Cách phối hợp lành mạnh nằm trong cách tổ chức functions.php gọn gàng.

Classic theme dùng được theme.json không?

Có thể dùng một phần để cấu hình editor, nhưng sức mạnh đầy đủ (styles, FSE) chỉ phát huy với block theme.

Khi xây nền tảng theme đúng cách ngay từ theme.json, mọi việc thiết kế và bảo trì về sau đều nhẹ đi. Nếu bạn cần một website WordPress với theme tự code chuẩn block, đội Web22 nhận làm theme tùy biến theo yêu cầu trên nền tảng này.