Projektipäeviku esimene postitus tutvustab theme.json faili – WordPress Full Site Editing teema tähtsaimat üksikfaili. See on koht, kus elab kogu disainisüsteem: värvid, vahed, fondi-suurused, raadiused, varjud. Kogu kujundus voolab siit edasi nii Site Editor’i UI-sse kui ka frontendi.

Mis on theme.json?

Kuni WordPress 5.9 oli FSE veel eksperimentaalne, ja teemastiilide haldamine käis CSS-failide ja PHP-koodi kaudu. Alates 5.9-st on theme.json ametlik viis defineerida:

• Settings – mis disaini-väärtused on saadaval (värvi-palett, spacingu skaala, fondi-perekonnad)
• Styles – kuidas vaikimisi asjad välja näevad (body taust, h1-h6, button’id, lingid)
• Block-spetsiifilised stiilid – eraldi seaded igale bloki-tüübile
• Template parts – header, footer, jne registreerimine

Üks theme.json-i seade võib mõjutada nii Block Editor’i UI-d kui ka avaldatud lehte. WordPress genereerib selle põhjal CSS muutujad ja Block Editor’i konfiguratsiooni automaatselt.

Meie projekti disainisüsteem

Figma’st tõime üle 38 muutujat nelja kategooriasse:

Värvid (11 tk) – settings.color.palette

Mitte kasutame “Background”, “Text”, “Accent” – vaid täpsemad nimed: bg-default, bg-gray, bg-dark, text-default, text-muted, text-light, text-inverse, accent-default, border-default, border-strong, placeholder. Iga slug muutub CSS muutujaks: var(--wp--preset--color--bg-default).

Vahed (10 tk) – settings.spacing.spacingSizes

Spacingute skaala mahajääb xs-ist (4px) kuni xxxxxxl-ini (96px). Suuremad väärtused (xl ja edasi) on tehtud fluid’iks CSS clamp() funktsiooniga:

{ "slug": "xxxxxxl", "size": "clamp(40px, 3vw + 16px, 96px)" }

Tulemus: mobile-vaates 40px, desktop’is 96px, vahepeal sujuv üleminek. Mida väiksem spacing, seda väiksem muutus – UI-tihendid (4-16px) jäävad fikseerituks, sektsiooni-padding’ud (32px+) kahanevad mobiilis. Üks padding-väärtus, töötab kõigil ekraanidel.

Fondi-suurused (12 tk) – settings.typography.fontSizes

Sarnaselt spacingule: xs (12px) → xxxxxxxl (56px). Samuti fluid clamp() väärtustega. Vaikimisi seadame Inter-perekonna ja line-height’i relaxed (1.6).

Raadiused (4 tk) – settings.custom.radius

sm (4px), md (6px), lg (8px), pill (999px). Custom muutujad on tarbitavad var(--wp--custom--radius--md) kaudu.

Õppetund: slug ei tohi alata numbriga

Ehitamise käigus jooksime kokku ühe peidetud lõksuga. Algselt olid font-size slug’id numbri-prefiksiga: 2xl, 3xl, 5xl, 7xl – Tailwind’i stiilis. Aga frontend’is jäid kõik h1, h2, h3 ja paragraafid täpselt ühe suurusega (14px).

Põhjus

WordPress normaliseerib slug’i CSS muutuja nimes: kui slug algab numbriga ja siis tuleb täht, lisatakse sidekriips:

theme.json slug:  "5xl"
WP CSS muutuja:   --wp--preset--font-size--5-xl    (sidekriipsuga!)

AGA: kui sa kasutad seda muutujat styles.elements.h2-s nii:

"fontSize": "var(--wp--preset--font-size--5xl)"

…siis WordPress ei normaliseeri seda viidet. Tulemus: muutuja, millele h2 viitab, ei eksisteeri. Brauser kasutab fallback’i (body font-size = 14px). Kõik pealkirjad jäävad 14px.

Lahendus

Vältida numbri-prefiksiga slug’e. Asendasime kõik vormid mitme x-iga:

Vana slug	Uus slug	Suurus
2xl	xxl	24px
3xl	xxxl	28px
4xl	xxxxl	32px
5xl	xxxxxl	40px
6xl	xxxxxxl	48px
7xl	xxxxxxxl	56px

Sama lõksu märkasime varem ka spacing’utes – sealgi 2xl-vormid ei töötanud, ja xxl-vorm lahendas selle. Niisiis: kogu projektis ühtne reegel – slug ei algagi numbriga.

theme.json kihiline süsteem

Üks oluline mõiste mõista: theme.json-il on kolm “kihti”, mille väärtused omakorda kombineeruvad:

1. WordPress core – vaikimisi värvid, fondid, vahed (sa võid need vaikimisi välja lülitada defaultPalette: false jne kaudu)
2. Teema theme.json – see, mida meie defineerime
3. Kasutaja kohandused – kui kasutaja muudab Site Editor’is Styles’i

Hilisem kiht võidab varasema. Meie näiteks lülitame välja WordPress’i vaikimisi värvi-paleti, sest see segab Figma disainisüsteemi. Selleks: "defaultPalette": false.

Mida theme.json EI tee

• Ei sisalda templates’eid (need on templates/*.html failid)
• Ei sisalda patterneid (need on patterns/*.php failid)
• Ei sisalda CPT-d (need lähevad plugin’isse)
• Ei sisalda dünaamilist loogikat (PHP – see on functions.php)

theme.json on ainult deklaratiivne konfiguratsioon: “millised väärtused on, kuidas vaikimisi näevad”. Kogu ülejäänud loogika elab teistes failides.

Edasi: arhitektuuri-otsused

Järgmises postituses (Projektipäevik #2) räägime laiematest arhitektuuri-otsustest: kus CPT-d elavad (plugin vs teema), miks valisime page-by-page lähenemise, ja kuidas dokumenteerime kogu protsessi.