theme.json στο WordPress: settings, styles και η σειρά υπεροχής

Το theme.json είναι ένα μοναδικό αρχείο ρυθμίσεων στη ρίζα ενός block theme που κάνει δύο ξεχωριστές δουλειές: το settings αποφασίζει τι προσφέρει ο επεξεργαστής μπλοκ στον χρήστη, και το styles αποφασίζει πώς φαίνεται πραγματικά το site από προεπιλογή. Το WordPress το διαβάζει, το συγχωνεύει με τις δικές του προεπιλογές και με ό,τι έχει αποθηκευτεί στον Site Editor, και βγάζει το αποτέλεσμα ως μεταβλητές CSS συν ένα ενσωματωμένο φύλλο στυλ σε κάθε σελίδα.

Το μπέρδεμα αυτών των δύο ρόλων είναι ο λόγος που οι περισσότερες αλλαγές στο theme.json μοιάζουν να μην κάνουν τίποτα. Το να δηλώσεις ένα χρώμα μέσα στο settings δεν το εφαρμόζει πουθενά. Δημιουργεί μόνο μια μεταβλητή και ένα δείγμα χρώματος στην πλαϊνή στήλη του επεξεργαστή.

Τα κλειδιά ανώτερου επιπέδου

Ένα ελάχιστο αρχείο μοιάζει κάπως έτσι:

{
  "$schema": "https://schemas.wp.org/trunk/theme.json",
  "version": 3,
  "settings": {},
  "styles": {},
  "templateParts": [],
  "customTemplates": []
}

Κλειδί	Τι κάνει
$schema	Μόνο αυτόματη συμπλήρωση και έλεγχος στον κειμενογράφο. Το WordPress το αγνοεί.
version	Λέει στο WordPress ποια μορφή σχήματος να διαβάσει. Δεν είναι η έκδοση του θέματός σου.
settings	Παράγει μεταβλητές CSS και ορίζει τι δείχνει ο επεξεργαστής.
styles	Εφαρμόζει την πραγματική προεπιλεγμένη εμφάνιση.
templateParts	Δηλώνει τα τμήματα στον φάκελο parts/ και σε ποια περιοχή ανήκουν.
customTemplates	Καταχωρεί πρότυπα σελίδας από το templates/ για τον επεξεργαστή άρθρων.

Το version μπερδεύει τον κόσμο επειδή μοιάζει με αριθμό έκδοσης του θέματος. Δεν είναι. Επιλέγει τρόπο ανάγνωσης, και οι παλαιότερες εκδόσεις του WordPress αγνοούν σιωπηλά κλειδιά από μια μορφή σχήματος που δεν γνωρίζουν. Αν υποστηρίζεις παλιές εγκαταστάσεις, στόχευσε στην έκδοση που καταλαβαίνουν αυτές, αντί να υποθέτεις ότι τα νεότερα κλειδιά ξεπέφτουν ομαλά. Η έκδοση 3 είναι η τρέχουσα τη στιγμή που γράφεται αυτό· η έκδοση 2 εξακολουθεί να είναι ευρέως εγκατεστημένη και να διαβάζεται κανονικά.

Το $schema δείχνει σε μια διεύθυνση σχήματος που φιλοξενεί το WordPress. Αν το καρφώσεις στο trunk, παίρνεις τις πιο πρόσφατες υποδείξεις μέσα στον κειμενογράφο σου· μια διεύθυνση συγκεκριμένης έκδοσης είναι ασφαλέστερη αν μένεις σκόπιμα σε παλαιότερο σχήμα.

settings: τι προσφέρει ο επεξεργαστής

Ό,τι βρίσκεται μέσα στο settings παράγει μια μεταβλητή CSS και, στις περισσότερες περιπτώσεις, ένα χειριστήριο στον επεξεργαστή. Τίποτα μέσα στο settings δεν μορφοποιεί κάτι.

{
  "settings": {
    "color": {
      "palette": [
        { "slug": "brand", "color": "#1f4ed8", "name": "Brand" },
        { "slug": "ink", "color": "#111827", "name": "Ink" }
      ],
      "custom": false
    },
    "typography": {
      "fontSizes": [
        { "slug": "small", "size": "0.875rem", "name": "Small" },
        { "slug": "large", "size": "1.5rem", "name": "Large" }
      ]
    },
    "layout": {
      "contentSize": "680px",
      "wideSize": "1200px"
    }
  }
}

Αυτό παράγει μεταβλητές που παίρνουν το όνομά τους από τη διαδρομή του preset και το slug:

--wp--preset--color--brand
--wp--preset--color--ink
--wp--preset--font-size--small
--wp--preset--font-size--large

Παράγει επίσης βοηθητικές κλάσεις όπως .has-brand-color και .has-brand-background-color, και έτσι ο επεξεργαστής εφαρμόζει σε ένα μπλοκ το χρώμα που διάλεξε ο χρήστης.

Η γραμμή "custom": false είναι το άλλο μισό του settings: το κλείσιμο επιλογών. Βάλ’ την και ο ελεύθερος επιλογέας χρώματος εξαφανίζεται, αφήνοντας στους χρήστες την παλέτα σου και τίποτε άλλο. Το ίδιο μοτίβο δουλεύει παντού — settings.typography.customFontSize, settings.spacing.customSpacingSize, settings.border και ούτω καθεξής. Τίποτα μέσα στο settings δεν είναι διακοσμητικό· κάθε κλειδί είτε προσθέτει μεταβλητή, είτε προσθέτει χειριστήριο, είτε αφαιρεί χειριστήριο.

Το settings.custom είναι ένας ελεύθερος χώρος για δικές σου μεταβλητές:

{
  "settings": {
    "custom": {
      "lineHeight": { "body": 1.6 },
      "shadow": { "card": "0 1px 3px rgba(0,0,0,0.12)" }
    }
  }
}

Αυτά γίνονται --wp--custom--line-height--body και --wp--custom--shadow--card. Πρόσεξε τη μετατροπή: τα κλειδιά σε camelCase σπάνε σε kebab-case, και η ένθεση ενώνεται με διπλές παύλες. Ένα λάθος στο όνομα μιας μεταβλητής είναι συνηθισμένος λόγος που μια τιμή γυρίζει σιωπηλά σε εφεδρική.

Μπορείς να περιορίσεις τα settings ανά μπλοκ, και έτσι επιτρέπεις επιλογέα χρώματος στα κουμπιά αλλά όχι στις παραγράφους:

{
  "settings": {
    "blocks": {
      "core/paragraph": {
        "color": { "custom": false, "customGradient": false }
      }
    }
  }
}

styles: τι εμφανίζεται στην πραγματικότητα

Το styles είναι εκεί όπου εφαρμόζονται οι τιμές. Ακολουθεί τη δομή του επεξεργαστή: πρώτα το επίπεδο ρίζας, μετά τα elements, μετά τα blocks.

{
  "styles": {
    "color": {
      "background": "var(--wp--preset--color--base)",
      "text": "var(--wp--preset--color--ink)"
    },
    "typography": {
      "lineHeight": "var(--wp--custom--line-height--body)"
    },
    "elements": {
      "link": {
        "color": { "text": "var(--wp--preset--color--brand)" },
        ":hover": { "typography": { "textDecoration": "none" } }
      }
    },
    "blocks": {
      "core/quote": {
        "typography": { "fontStyle": "italic" },
        "spacing": { "padding": { "left": "var(--wp--preset--spacing--40)" } }
      }
    }
  }
}

Τα styles του επιπέδου ρίζας προσγειώνονται στο σώμα της σελίδας. Τα elements καλύπτουν βασικά στοιχεία HTML που δεν είναι μπλοκ — σύνδεσμο, κουμπί, επικεφαλίδες, λεζάντα. Τα blocks στοχεύουν συγκεκριμένο τύπο μπλοκ με το όνομά του.

Ο περιορισμός, με ειλικρίνεια: το styles δεν μπορεί να εκφράσει ό,τι μπορεί το CSS. Δεν υπάρχει τρόπος να γράψεις δικά σου media queries, ούτε σύνθετοι επιλογείς, ούτε κινήσεις, και υποστηρίζεται μόνο ένα μικρό σύνολο ψευδοκλάσεων. Η ρευστή τυπογραφία και η διαστασιολόγηση με βάση τη διάταξη καλύπτουν πολλά από όσα έλυναν παλιά τα breakpoints, αλλά όχι όλα. Τα περισσότερα block theme που κυκλοφορούν κουβαλούν theme.json συν ένα μικρό φύλλο στυλ, και αυτό είναι φυσιολογική κατάληξη, όχι αποτυχία.

Η παγίδα settings εναντίον styles

Η πιο συχνή ερώτηση υποστήριξης είναι κάποια παραλλαγή του «πρόσθεσα το χρώμα της μάρκας μου και δεν άλλαξε τίποτα».

Σωστά. Προσθέτοντάς το στο settings.color.palette δημιούργησες το --wp--preset--color--brand και ένα δείγμα χρώματος. Δεν εφάρμοσες τίποτα. Για να γίνει το προεπιλεγμένο χρώμα των συνδέσμων πρέπει να το γράψεις και μέσα στο styles:

{
  "settings": {
    "color": {
      "palette": [{ "slug": "brand", "color": "#1f4ed8", "name": "Brand" }]
    }
  },
  "styles": {
    "elements": {
      "link": { "color": { "text": "var(--wp--preset--color--brand)" } }
    }
  }
}

Διάβασέ το έτσι: το settings είναι το κουτί με τα χρώματα που δίνεις στον χρήστη, το styles είναι το χέρι μπογιάς που περνάς πριν εκείνος φτάσει.

Η σειρά υπεροχής, από κάτω προς τα πάνω

Εδώ εξηγείται ένα site που «αγνοεί» το αρχείο του θέματος. Το WordPress συγχωνεύει αρκετά στρώματα πριν βγάλει CSS:

1. Προεπιλογές του πυρήνα του WordPress — ο πυρήνας κυκλοφορεί με δικό του theme.json, με βασική παλέτα, μεγέθη γραμματοσειράς και κλίμακα κενών.
2. Το theme.json του γονικού θέματος
3. Το theme.json του θυγατρικού θέματος — συγχωνεύεται πάνω στο γονικό κλειδί προς κλειδί, δεν αντικαθιστά ολόκληρο το αρχείο.
4. Τα Global Styles που είναι αποθηκευμένα στη βάση δεδομένων — ό,τι γράφει το πάνελ Styles του Site Editor.
5. Στυλ ανά μπλοκ σε μεμονωμένα μπλοκ — ιδιότητες αποθηκευμένες στο περιεχόμενο του άρθρου, που βγαίνουν ως ενσωματωμένα στυλ ή κλάσεις.

Το στρώμα 4 είναι αυτό που χαλάει τα site. Τη στιγμή που κάποιος ανοίξει το πάνελ Styles και αποθηκεύσει, το WordPress αποθηκεύει μια εγγραφή Global Styles και αυτή η εγγραφή κερδίζει έναντι του αρχείου σου για κάθε ιδιότητα που περιέχει. Οι μετέπειτα αλλαγές στο theme.json δεν αλλάζουν τίποτα ορατό για αυτές τις ιδιότητες, σε ένα site που δείχνει πανομοιότυπο μετά από κάθε ανέβασμα ενώ το αρχείο στον δίσκο είναι προφανώς διαφορετικό.

Η λύση είναι να καθαρίσεις την αποθηκευμένη εγγραφή, όχι να ανεβάσεις ένταση με !important. Άνοιξε τον Site Editor, πήγαινε στα Styles, άνοιξε το πάνελ αναθεωρήσεων και κάνε επαναφορά στις προεπιλογές του θέματος. Επιβεβαίωσέ το πρώτα με τον πελάτη ή τον ιδιοκτήτη του site — η επαναφορά πετάει τις δικές του προσαρμογές, που είναι πραγματικό κόστος, όχι κίνηση χωρίς συνέπειες.

Ο δεύτερος ύποπτος είναι η προσωρινή αποθήκευση. Το WordPress κρατά προσωρινά τα επεξεργασμένα δεδομένα του theme.json αντί να ξαναδιαβάζει το αρχείο σε κάθε αίτημα, που είναι ακριβώς ό,τι θέλεις στην παραγωγή και ακριβώς ό,τι δεν θέλεις όσο αναπτύσσεις. Ενεργοποιώντας το WP_DEBUG, ή τη ρύθμιση λειτουργίας ανάπτυξης θέματος στις νεότερες εκδόσεις, το WordPress ξαναδιαβάζει το αρχείο κάθε φορά. Αν οι αλλαγές σου εμφανίζονται μόνο μετά από ανέβασμα ή καθάρισμα προσωρινής μνήμης, αυτό βλέπεις.

templateParts και customTemplates

Και τα δύο είναι πίνακες που περιγράφουν αρχεία τα οποία ήδη βρίσκονται μέσα στο θέμα σου.

{
  "templateParts": [
    { "name": "header", "title": "Header", "area": "header" },
    { "name": "footer", "title": "Footer", "area": "footer" }
  ],
  "customTemplates": [
    { "name": "page-wide", "title": "Wide Page", "postTypes": ["page"] }
  ]
}

Το name ταιριάζει με το όνομα του αρχείου χωρίς την κατάληξή του — parts/header.html, templates/page-wide.html. Η τιμή του area μετράει: αποφασίζει αν το τμήμα τυλίγεται σε στοιχείο ορόσημο κεφαλίδας ή υποσέλιδου και πώς το κατηγοριοποιεί ο επεξεργαστής. Αν την παραλείψεις, το τμήμα μένει χωρίς κατηγορία.

Το customTemplates είναι αυτό που κάνει ένα πρότυπο να εμφανίζεται στη λίστα προτύπων του επεξεργαστή άρθρων. Χωρίς την καταχώριση, το αρχείο υπάρχει αλλά κανείς δεν μπορεί να το επιλέξει.

Μια γρήγορη σειρά διάγνωσης

Όταν ένα block theme δεν μορφοποιείται όπως λέει το αρχείο, πέρασε από αυτά πριν αγγίξεις οτιδήποτε:

1. Δες τον πηγαίο κώδικα της σελίδας και ψάξε το μπλοκ των παραγόμενων global styles. Αν η μεταβλητή σου δεν είναι εκεί, το πρόβλημα είναι στο settings ή σε ένα τυπογραφικό λάθος στο slug.
2. Αν η μεταβλητή υπάρχει αλλά δεν χρησιμοποιείται πουθενά, λείπει η αντίστοιχη καταχώριση στο styles.
3. Αν υπάρχουν και τα δύο αλλά κάτι τα υπερισχύει, ψάξε για αποθηκευμένη εγγραφή Global Styles.
4. Μόνο τότε κοίτα το δικό σου φύλλο στυλ, τα πρόσθετα ή κάποιον page builder που ρίχνει CSS αργότερα στη σειρά υπεροχής.