Schema config chuẩn của theme · v1

Schema chuẩn gồm 111 key, do hệ thống quản lý trong modules/themeconfig/standard.json. Mọi theme đều nhận schema này khi mở cấu hình và khi render. Theme không cần sao chép schema chuẩn.

File và cấu trúc

Chỉ có thư mục config/; các file nằm phẳng:

• config/config_schema.json: default của key chuẩn và định nghĩa field riêng của theme.
• config/config_data.json: giá trị user đã lưu.
• config/theme.json: thông tin theme hiện có, không thay bằng bộ schema này.
• config/nav-{key}.json: profile navigation riêng, tiếp tục giữ cơ chế hiện có.

Phiên bản schema chuẩn là 1 trong mã hệ thống. Không thêm trường version vào config_schema.json/config_data.json vì hai file này là map key → field/value.

Schema bất biến

Field chuẩn có type, label, group, standard_config=1, locked=true và translatable do hệ thống quy định. Theme chỉ được bổ sung default cho field chuẩn. Các thuộc tính type, locked, fallback, css_variable của theme không thay thế định nghĩa chuẩn. Xóa một key chuẩn khỏi file theme không xóa key đó khỏi schema có hiệu lực. Không có API xóa schema hệ thống. Field riêng vẫn khai báo bình thường và không được dùng trùng key chuẩn để đổi kiểu.

Thứ tự ưu tiên

1. Thiết kế riêng của element hoặc profile menu đã lưu.

2. config_data.json của website.

3. Default trong config_schema.json của theme.

4. Key fallback chuẩn, ví dụ button_radius → border_radius.

5. Default của element, nằm trong fallback CSS var.

Giá trị trống/null không tạo biến CSS riêng; 0 và false vẫn có ý nghĩa. User đổi theme config thì preview render lại và các element đang theo theme nhận giá trị mới. Không copy màu/font đã tính ra vào JSON của element.

Config thiết kế phát ra CSS variables --skai-{key-với-dấu-gạch-ngang}. Số của key kích thước có css_unit=px được chuyển sang px; line-height không tự thêm px. Font là CSS font-family; theme tự cung cấp font-face/stylesheet, hệ thống không tự tải font từ mạng.

Ví dụ schema theme

{
  "primary_color": {"default": "#f46b16"},
  "border_radius": {"default": 8},
  "body_font": {"default": "Inter, system-ui, sans-serif"},
  "brand_story": {"type": "textarea", "label": "Câu chuyện thương hiệu", "group": "Riêng của theme", "default": ""}
}

Ví dụ giá trị user

{
  "primary_color": "#14532d",
  "on_primary_color": "#ffffff",
  "button_radius": "12px",
  "body_font_size": "16px",
  "h1_font_size": "48px",
  "h1_font_size_mobile": "30px",
  "logo": {"src": "/assets/logo.svg", "alt": "Tên thương hiệu"},
  "site_name": "t:brand.name"
}

Element hệ thống và thiết kế riêng

Tất cả 104 định nghĩa element hệ thống đã có liên kết font chuẩn. Những thuộc tính màu, bo góc, khoảng cách, chữ và bóng có vai trò tương ứng được nối với token chuẩn, giữ fallback của element. Button mặc định dùng button_primary_background → primary_color và button_primary_color → on_primary_color. Button theo kiểu có tone primary/secondary dùng token của tone đó. Kiểu chữ tiêu đề có key riêng cho H1–H6 và tablet/mobile.

Logo lấy configs.logo khi chưa có ảnh riêng và logo_source=theme. Chọn logo_source=custom để dùng riêng, kể cả khi muốn để trống. Link, ảnh hoặc nội dung đã nhập riêng vẫn được giữ.

Trong tab Thiết kế, thuộc tính dùng token hiển thị nhãn Theo theme. Nhập giá trị mới tạo override riêng. Nhấn ↺ để bỏ override và trở lại default kế thừa của element. Responsive giữ thứ tự desktop → tablet → mobile như hiện tại.

Các preset mới trong thư viện dùng token thay cho những giá trị mẫu mang vai trò giao diện chung. Page/layout JSON cũ không bị sửa tự động: không thể phân biệt chắc chắn màu mẫu cũ và màu user chủ ý chọn. Muốn chuyển một thuộc tính cũ sang theo theme, reset thuộc tính đó hoặc đổi sang CSS var có fallback.

Custom element và theme code

.my-primary-button {
  background: var(--skai-button-primary-background, #6d28d9);
  color: var(--skai-button-primary-color, #ffffff);
  border-radius: var(--skai-button-radius, 6px);
  font-family: var(--skai-body-font, inherit);
}

Trong layout HTML cần có {{ head_content }} để nhận biến CSS; trang Visual được engine thêm biến trực tiếp vào style render. Custom element có thể khai báo cùng biểu thức var trong default_styles. User styles vẫn ghi đè default_styles.

Key header/footer chỉ áp dụng khi template gắn đúng vai trò đó. Không gắn màu footer vào mọi Menu dọc vì Menu dọc còn dùng ở sidebar. Key liên hệ, mạng xã hội và SEO là dữ liệu chuẩn để theme dùng qua configs; chúng không tự chèn nội dung, tạo menu hoặc thay markup SEO. Xem Object configs để đọc dữ liệu trong Lingo. Cơ chế fallback của CSS variables không tự thay toàn bộ các giá trị thô trong object configs.

Tương thích và đa ngôn ngữ

Giữ tên key đang dùng như primary_color, secondary_color, body_font, heading_font, border_radius. site_name đọc thêm name hoặc site_title khi chưa có giá trị chuẩn. Alias không ghi đè dữ liệu cũ. Các file legacy settings_schema.json/settings_data.json/setting_data.json vẫn được đọc theo quy tắc tương thích hiện có.

Nội dung văn bản hỗ trợ tham chiếu t: theo locale đang render. Màu sắc, kích thước và font không dịch. logo_dark/logo_mobile là các nguồn tùy chọn để theme chọn theo bố cục; element Logo mặc định dùng logo.

Danh sách key chuẩn

Kiểm thử khi thay đổi schema

• Sửa primary_color hai lần: nút theo theme đổi theo, nút có backgroundColor riêng giữ nguyên.
• Theme thiếu config: default element vẫn render đúng.
• border_radius=0 và link_underline=false không bị coi là trống.
• Theme khai báo primary_color là html: schema có hiệu lực vẫn là color.
• Lưu rồi tải lại: JSON element không bị ghi màu/font đã resolve.
• Logo riêng không bị configs.logo thay thế.
• Kiểm tra font và H1–H6 trên ba breakpoint.
• Mỗi lần thêm key cần cập nhật standard.json, tài liệu và test. Không đổi nghĩa key cũ âm thầm.