Styles Contract (--wk-*)

Različica: 15 (2026-07-13) · Normativna vira: lib/tpl/premium-navy-ivory/css/tokens.css in lib/tpl/flat/css/color-palette.css

Styles Contract je zavezujoč vmesnik CSS med predlogami in vtičniki: fiksen nabor lastnosti CSS Custom Properties (–wk-*), ki ga vsaka predloga v celoti definira z lastno paleto. Vtičniki in izsečki uporabljajo izključno te žetone — zato je celotno mesto pod vsako predlogo videti „iz iste hiše“, ne da bi bilo treba prilagajati CSS vtičnikov.

Osnovno pravilo: barva, pisava, videz fokusnega obroča in širina vsebine se nikoli ne pojavijo kot lastna vrednost hex/piksel/pisave v CSS vtičnika — vedno kot var(–wk-…, rezervna vrednost). Postavitev, notranji/zunanji razmiki, lastna imena razredov, ikone, struktura komponent in vedenje JavaScript so povsem prosti; pogodba tega ne omejuje.

Odločitveno pravilo — žeton ali prosta izbira?

• Obvezen žeton iz spodnje tabele: vsaka barva, družina/sklad pisave, videz fokusnega obroča, širina vsebine.
• Povsem prosto: postavitev (flexbox/grid), razmiki, lastna imena razredov, ikone, struktura komponent, vedenje JavaScript.
• Ne izmišljajte sami: če vtičnik potrebuje barvo/pisavo brez ustrezne pomenske vrednosti žetona, jo tu predlagajte kot nov obvezen ali razširitveni žeton (glejte „Pravila“ spodaj), namesto da uvedete ad-hoc vrednost — sicer neopazno podre doslednost ob naslednji zamenjavi barvne sheme.

Posledica neupoštevanja osnovnega pravila: brez napake, brez sesutja — vtičnik le izgubi sodelovanje pri zamenjavi barvne sheme (riviera/night/white, glejte spodaj). Trdo kodirana modra ostane modra tudi, ko uporabnik zamenja shemo; CSS, ki temelji na žetonih, se samodejno zamenja skupaj z njo.

/* Wrong - hardcoded colors, ignores the active color scheme and any
   foreign template without this contract */
.my-plugin-button {
    background: #1d86b6;
    color: #ffffff;
    border: 1px solid #148fb9;
}
 
/* Right - token with a sensible fallback for templates without the contract */
.my-plugin-button {
    background: var(--wk-btn-primary, #1d86b6);
    color: var(--wk-btn-text, #ffffff);
    border: 1px solid var(--wk-accent, #148fb9);
}

Rezervna vrednost (drugi argument var()) je obvezna, ne neobvezna: če vtičnik teče pod tujo predlogo brez te pogodbe, žeton ne obstaja — brez rezervne vrednosti lastnost ostane prazna. Rezervna vrednost mora sama po sebi dati sprejemljiv videz.

Dejanske vrednosti so izključno v tokens.css oziroma color-palette.css aktivne predloge — nikoli jih ne odčitavajte s posnetka zaslona ali ugibajte, vrednosti se razlikujejo po barvni shemi (glejte „Barvne sheme“ spodaj).

Ta stran ureja žetone in konvencije CSS. Vse ostalo — vzorci postavitve, gradniki, vedenje — je v knjižnici oblikovnega sistema WvdS FluentUI. Za razvijalce brez predznanja WvdS, v vrstnem redu branja:

Gradniki CSS, naloženi na ravni celotnega mesta (wkfluentui/css/widgets.css prek dogodka CSS_STYLES_INCLUDED) — pred vsako lastno izdelavo preverite, ali razred že obstaja; izdelavo raje izvedite prek pripadajoče metode pomočnika (api):

Prevajalnik DokuWiki, ki temelji na lessphp (lib/exe/css.php), se v celoti prekine pri dveh vzorcih — celotno mesto izgubi svoj slog, ne le lastno pravilo (brskalniki s staro predpomnilnikom tseed sprva prikrijejo izpad):

1. */ znotraj besedila komentarja — npr. v naštevanjih žetonov, kot je

a-/b-: */ predčasno konča blokovni komentar, preostanek se razčleni kot smeti

  CSS. Izberite formulacijo brez poševnice (''a-* or b-*'').
- **''min()''/''calc()'' z mešanimi enotami** — npr. ''calc(100% - 2px)'' v določenih
  kontekstih oziroma ''min(100%, 40em)'': uporabite vrednosti iste enote ali mrežne stolpce
  ''minmax()''.

Preverjanje po vsaki spremembi CSS: curl http://localhost:8880/lib/exe/css.php — nekaj sto KB = v redu; nekaj sto bajtov z rdečim sporočilom o napaki = prekinjeno prevajanje. Nato dotaknite conf/local.php (rotacija tseed, glejte preverjanje).

1. Le žetoni: vsaka barva/pisava kot var(–wk-…, rezervna vrednost) (osnovno pravilo zgoraj); vrednosti iščite izključno v tokens.css/color-palette.css.
2. Najprej poiščite, nato gradite: uporabite ustrezen razred .wk-* oziroma metodo pomočnika iz zgornje tabele namesto lastnega podvojevanja; lastni razredi imajo predpono vtičnika (<vtičnik>-…), nikoli imenski prostor wk-.
3. Klasificirajte skrbniške gumbe po 3-barvni semantiki (Contract v3 spodaj): belo = običajno, vključno s shranjevanjem, modro = posebno dejanje, rdeče = destruktivno.
4. Izogibajte se pastem prevajalnika (odsek zgoraj) in po vsakem urejanju preverite css.php + tseed.
5. Testirajte proti vsem trem barvnim shemam (riviera/night/white, odsek „Barvne sheme“) in enkrat pod tujo predlogo (takrat veljajo rezervne vrednosti).

Kdor poleg tega gradi celoten skrbniški modul: Vodnik: gradnja prvega skrbniškega zaslona z FluentUI.

1. Vsaka predloga definira vse obvezne žetone v natanko eni datoteki (tokens.css oziroma color-palette.css).
2. Vtičniki/izsečki vedno pišejo var(–wk-…, rezervna vrednost).
3. Brez barv hex v CSS vtičnika zunaj rezervnih vrednosti var().
4. V CSS predloge so dobesedne barve dovoljene le za nevtralne učinke (črno-bele sence in prekrivke, kot je rgba(0,0,0,.45)), ki delujejo pod vsako barvno shemo.
5. Novi žetoni se uvajajo le prek te strani (povečajte različico pogodbe, dopolnite obe datoteki predlog).
6. Alfa različice barv žetonov gradite prek color-mix(in srgb, var(–wk-…) N%, transparent), ne kot lastne dobesedne vrednosti rgba.

Predloge smejo definirati dodatne žetone za lastne podrobnosti videza; vtičniki se nanje ne smejo zanašati.

Prejšnji žeton –wk-brand-frame (barva okvira) je bil odstranjen 2026-07-10 (preveč zlate v glavi) — zgornji trak okvira lupine strani mesta je od takrat fiksen ivory ton, ni več barva, odvisna od sheme.

• CSS predloge: premium-navy-ivory/css/* (v celoti temelji na žetonih), flat/css/customFlat.css, flat/css/accessibility.css
• Nabori predlog wkblog tpl/wvds + tpl/premiumnavyivory — oba prek premium-navy-ivory/css/blog.css
• Vtičniki: wvdstheme/style.css, wkacmenu/style.css, značke wvdsaudit
• Izsečki wksnippet (~40 gradnikov HTML z vrstičnim var(–wk-…, rezervna vrednost))
• Konfiguracijski izsečki v conf/local.php (značke revizije/skladnosti)

Barvna shema je alternativna dodelitev obveznih žetonov (css/schemes/<ime>.css v predlogi, le preglasitve :root). Ker vsi odjemalci gredo prek žetonov, zamenjava sheme spremeni videz celotnega mesta brez nadaljnjih sprememb CSS. Trije znamkovni poudarki od 2026-07-10: riviera (privzeto), night, white. Možnost colorscheme vpliva le na profil območja site — profil območja wiki (in s tem vsak zaslon do=admin) se vedno izriše z white, ne glede na to nastavitev. Podrobnosti: BizWay (hišna predloga).

<mermaid> raw graph TD

  A["tokens.css<br/>(osnovne vrednosti, vsi obvezni žetoni)"] --> B["css/schemes/riviera.css<br/>ALI night.css ALI white.css<br/>(preglasitve :root, ena shema aktivna)"]
  B --> C["Odjemalci:<br/>CSS predloge, wkblog, wvdstheme,<br/>wkacmenu, wvdsaudit, wksnippet,<br/>Skrbniška prekrivka CSS (_admin-forms.css/_admin-drawer.css)"]

  classDef neutral fill:#FFFFFF,stroke:#D9D2C0,stroke-width:2px,color:#1f1f1f
  class A,B,C neutral

</mermaid>

Od 2026-07-11 dodatno samodejno sledi aktivni barvni shemi tudi od tega neodvisna, DokuWiki-izvorna pogodba style.ini [replacements] (__text__, __link__ itd., ki jo prek spremenljivk LESS @ini_* uporablja vsak vtičnik, ne le odjemalci –wk-*) — podrobnosti in tabela ograničevalnikov: barvne_sheme.

Območje do=admin se izriše prek izvornega skrbniškega chroma DokuWiki, ne prek lastne nadzorne plošče (prejšnja admin-chrome.css + nadzorna plošča „BizWay Admin“ je bila odstranjena 2026-07-09). –wk-admin-accent/-accent-light/-hover so bili prej neuporabljeni obvezni žetoni; od 2026-07-09 jih uporablja css/_admin-forms.css (aditivna strukturna prekrivka prek izvornega skrbniškega markupa, nobena datoteka vtičnika jedra se ne spreminja) za kartice fieldsetov, lebdenje vrstic, tabele data grid in aktivne elemente (npr. drevo ACL). Skrbniški poudarek tako sledi izbrani barvni shemi. Ni barvno poudarjeno: „vrednost ustreza vgrajeni privzeti“ v Config Managerju (običajen primer, ne izjema); poudarjeno: „zaščiteno“ (ni spremenljivo) in napake preverjanja.

Izjema slikovnih sredstev: tekstura menijske vrstice, senca drsnika in grafike stranske vrstice/noge (assets/images/*-blue.png) so fiksne bitne slike iz izvirne teme BizWay, ne morejo se prebarvati z žetonom.

Meja pokritosti: _admin-forms.css ciljno pokriva zaslone do=admin, ki so priloženi DokuWiki: acl, config, usermanager, extension, logviewer, styling, popularity, revert, discussion, sqlite (poleg samega pregleda do=admin). Vtičniki tretjih oseb zunaj tega seznama in lastna skrbniška orodja wvds* projekta (wkvault, wvdsremote, wvdsdwmmx, wksqliteds, wkdoadogit, wvdsmd, wksnippet) niso del te pokritosti — odgovornost je pripadajočega vtičnika, ki lahko po želji sam uporablja skrbniški poudarek (wvdsentra, wkblog to že počneta z lastnim skrbniškim videzom). Noben selektor _admin-forms.css ne referencira razreda/ID-ja wvds*, le žetone var(–wk-…) — s tem predloga ostane neodvisna od tega, kateri vtičniki tretjih oseb/lastni so nameščeni.

Zgornji izjemi skrbniškega chroma dodaja tretjo razsežnost: semantiko barv dejanj za gumbe v območju do=admin, neodvisno od pogodbe primarno(modro)/sekundarno(obris) na ravni celotnega mesta iz css/design.css (ki še naprej streže prijavi/profilu/urejevalniku wiki in se ne spreminja). Uvedena 2026-07-11 (referenčna izvedba: wkidentity), izpopolnjena po povratnih informacijah uporabnikov 2026-07-12.

<mermaid> raw graph TD

  A["Skrbniški gumb: katero dejanje?"] --> B{"destruktivno ali<br/>varnostno pomembno?"}
  B -- "da (brisanje/ponastavitev/<br/>preklic/onemogočitev)" --> D["rdeče — danger"]
  B -- ne --> C{"posebno dejanje?<br/>(izvoz/pretvorba/sinhronizacija/test)"}
  C -- da --> E["modro — accent"]
  C -- "ne (tudi shranjevanje)" --> F["belo — neutral"]

  classDef neutral fill:#FFFFFF,stroke:#D9D2C0,stroke-width:2px,color:#1f1f1f
  classDef accent fill:#3B7EA8,stroke:#3B7EA8,color:#FFFFFF
  classDef danger fill:#C0392B,stroke:#C0392B,color:#FFFFFF
  class F neutral
  class E accent
  class D danger

</mermaid>

Novi žetoni (tokens.css, med blokom gumbov in blokom razširitvenih žetonov):

Lastni žetoni namesto ponovne uporabe –wk-btn-primary: slednji je glavna pogodba gumba na ravni celotnega mesta (prijava/profil/urejevalnik); prihodnja sprememba pomena tam ne sme nenamerno spremeniti tudi znotraj-skrbniške 3-barvne semantike, čeprav oba trenutno referencirata isti modri ton.

Konvencija poimenovanja razredov, glede na urejljivost vira:

• Vtičniki jedra DokuWiki (PHP ni urejljiv; glejte odsek „Popravki jedra“ spodaj za ozko izjemo od tega): dodelitev barve izključno prek obstoječih, stabilnih atributov id/name v _admin-forms.css/_admin-drawer.css, nikoli prek vidnega besedila. Referenca: #usrmgr__del, button[name=„fn[export]“]. Predpona ID je pogosto nujnost specifičnosti: _admin-forms.css se naloži pred design.css.
• Lastni vtičniki WvdS (PHP urejljiv): neposredna dodelitev razreda v PHP, vzorec <predpona-vtičnika>-btn–danger/–accent (referenca: wt-btn–danger vtičnika wkidentity). Pravila CSS prek var(–wk-…, rezervna vrednost) kažejo na osrednje žetone.
• Splošni primer: ponovno uporaben par razredov .wk-admin-btn–danger/–accent v _admin-forms.css.
• Osrednje proti lokalnemu v vtičniku: osrednje (_admin-forms.css), kadar ima vtičnik enoten korenski selektor in malo gumbov; lokalno v vtičniku (zgled wkidentity/admin.css), kadar vtičnik že prinaša lasten CSS ali ima tako zapleten UI, da bi obseganje z ID v tuji osrednji datoteki poslabšalo vzdržljivost.

Brez lokalnih plasti žetonov v vtičnikih: slog vtičnika ne deklarira lastnih lastnosti CSS Custom Properties –<predpona-vtičnika>-*, ki le zrcalijo osrednji žeton — vsako pravilo neposredno referencira osrednji žeton (color: var(–wk-admin-accent, #0f6cbd);). Izjema: blok @media (prefers-color-scheme: dark) ne more preklopiti statične rezervne vrednosti klica var() — prizadeti selektorji morajo biti tam ponovljeni s temnimi dobesednimi vrednostmi.

Prednost ikon za novo ikonografijo orodne vrstice/gumbov: 1. Codicons (ustreza oblikovnemu jeziku Fluent/ADO), 2. FontAwesome (že samostojno gostovan, assets/fonts/fontawesome-webfont.*), 3. lastne ikone DokuWiki (lib/images/), le kadar ne ustreza niti Codicon niti FontAwesome. Čist prednostni seznam za prihodnje izbire simbolov, brez obveznosti zamenjave obstoječih pravilnih ikon. Sam vendoring Codicon (assets/fonts/codicon.ttf + podnabor v css/icons.css) je odprt, odložen zaradi pomanjkanja konkretnega odjemalca.

Politika barv in pisav: iz reference Fluent/Azure DevOps se prevzame le strukturni oblikovni jezik (radij, fokusni obroč, konvencije mreže/orodne vrstice/zavihkov, stopnje velikosti tipografije) — nikoli konkretnih vrednosti barv ali pisav Microsofta. Barve ostanejo lastna znamkovna paleta (bela, ivory, mornarsko modra, bordo rdeča, zlata). Pisave ostanejo obstoječi, samostojno gostovani Google Fonts (Arimo/Roboto/Noto Sans).

Mehanizem Ini: trenutno noben odjemalec @ini_* v skrbniškem območju ne uporablja barve danger/napake (le __theme_color__ → accent, že preslikano). Če bi prihodnji skrbniški zaslon na osnovi LESS potreboval ton danger prek @ini_*: dodajte ključ z imenskim prostorom __wk_danger__ v $map v premiumnavyivory_sync_style_ini_replacements() (main.php), preslikan na error. Brez proaktivnega vnosa brez odjemalca.

Razmejitev od lib/plugins/wvdsdwui/: drug, neodvisno razvit oblikovni sistem WvdS (lasten nabor žetonov/komponent/ponudnika ikon, repozitorij wk-dw-ui-plugin). Noben tu obravnavan skrbniški vtičnik ne uporablja wvdsdwui — ta semantika skrbniških gumbov/chroma velja izključno za svet prekrivke CSS premium-navy-ivory. Znana, namerno nerešena ugotovitev.

Za datoteke jedra DokuWiki brez lastnega nadzora različic (lib/plugins/{acl,extension,usermanager,config,styling,logviewer,discussion,sqlite,…}, inc/*) velja ozka izjema od načela „jedra se nikoli ne dotikaj“: ciljan, dokumentiran popravek namesto obhoda, kadar je popravek ozek/ciljan (brez refaktoriranja) in je zunaj wikija shranjena varnostna kopija izvirne datoteke skupaj z utemeljitvijo. Oblika urejanja v izvorni kodi DokuWiki: nič brisati/zamenjati — izvirno vrstico/vrstice zakomentirajte, novo vrstico/vrstice posamično vrstično komentirajte, oznaka WvdS <LLMMDD>:, jezik komentarja angleščina. Za samo popravljeno datoteko potek dela git ni mogoč (ni repozitorija) — sledljivost prek datoteke WI, vrstičnih komentarjev in varnostne kopije namesto uveljavitev. Odsek s tem imenom danes ne obstaja več v pravilih projekta — konvencija je opisana samo tukaj.

<mermaid> raw graph TD

  A["Napaka v datoteki DokuWiki"] --> B{"Ima datoteka lasten .git?"}
  B -- da --> G["Običajen potek dela git:<br/>veja, uveljavitve, PR"]
  B -- ne --> C{"Popravek ozek/ciljan,<br/>brez refaktoriranja?"}
  C -- ne --> H["Brez popravka — dokumentirajte<br/>kot znano omejitev"]
  C -- da --> P["Popravek jedra:<br/>varnostna kopija + utemeljitev<br/>zunaj wikija,<br/>izvirnik zakomentiran"]

  classDef neutral fill:#FFFFFF,stroke:#D9D2C0,stroke-width:2px,color:#1f1f1f
  classDef danger fill:#C0392B,stroke:#C0392B,color:#FFFFFF
  class G neutral
  class P danger

</mermaid>

Prvi zgled po tej konvenciji: lib/plugins/extension/GuiAdmin.php — trije bloki catch (Exception $e) so zaradi manjkajoče kvalifikacije imenskega prostora ujeli le lasten razred Exception vtičnika, ne globalne RuntimeException PHP iz Extension::initFromRemoteData() pri pokvarjenem odzivu repozitorija; popravljeno z razširitvijo na catch (\Throwable $e). Predhodni popravek (pred uvedbo te formalne konvencije, varnostna kopija takrat shranjena zunaj wikija): napaka polja Extension::getDependencyList().