Styles Contract (--wk-*)

Styles Contract je zavezujoč vmesnik CSS med predlogami in vtičniki: stalen nabor lastnosti CSS po meri (–wk-*). To paleto ima v lasti vtičnik oblikovnega sistema wkfluentui, predloga pa prispeva rezervne vrednosti. Vtičniki in izsečki uporabljajo izključno te žetone – zato je celotno spletno mesto pod vsako predlogo videti enotno, »kot iz enega kalupa«, ne da bi bilo treba prilagajati CSS vtičnikov.

Različica: 17 · Normativni vir: lib/tpl/wkbizway/css/tokens.css

Osnovno pravilo: barva, pisava, videz fokusnega obroča in širina vsebine se v CSS vtičnika nikoli ne pojavijo kot lastna vrednost v hex, pikslih ali kot ime pisave – vedno kot var(–wk-…, rezervna vrednost). Postavitev, notranji in zunanji odmiki, lastna imena razredov, ikone, zgradba komponent in obnašanje JavaScripta so povsem prosti; pogodba tu ničesar ne omejuje.

Pravilo odločanja – žeton ali prosta izbira?

• Obvezen žeton iz spodnje preglednice: vsaka barva, družina oziroma sklad pisav, videz fokusnega obroča, širina vsebine.
• Povsem prosto: postavitev (flexbox/grid), odmiki, lastna imena razredov, ikone, zgradba komponent, obnašanje JavaScripta.
• Ne izmišljajte si sami: če vtičnik potrebuje barvo ali pisavo, za katero ni žetona z ustreznim pomenom, jo tu predlagajte kot nov obvezni ali razširitveni žeton (glejte »Pravila« spodaj), namesto da uvedete priložnostno vrednost – sicer ob naslednji menjavi barvne sheme neopazno poruši enotnost.

Posledica, če osnovno pravilo prezrete: brez napake, brez sesutja – vtičnik le ne sodeluje več pri menjavi barvne sheme (riviera/night/white, glejte spodaj). Trdo kodirana modra ostane modra, tudi ko uporabnik zamenja shemo; CSS, ki temelji na žetonih, se zamenja samodejno.

/* 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 izbirna: če vtičnik teče pod tujo predlogo brez te pogodbe, žeton ne obstaja – brez rezervne vrednosti lastnost ostane prazna. Rezervna vrednost mora že sama dati sprejemljiv videz.

Dejanske vrednosti so zapisane izključno v tokens.css oziroma color-palette.css aktivne predloge – nikoli jih ne odčitavajte s posnetka zaslona in jih ne ugibajte, saj se med barvnimi shemami razlikujejo (glejte »Barvne sheme« spodaj).

Ta stran ureja žetone in konvencije CSS. Vse drugo – vzorce postavitve, gradnike, obnašanje – opisuje knjižnica oblikovnega sistema WvdS FluentUI. Za razvijalce brez predznanja o WvdS, v vrstnem redu branja:

Gradniki CSS, ki se naložijo na vseh straneh spletnega mesta (wkfluentui/css/widgets.css prek dogodka CSS_STYLES_INCLUDED) – preden karkoli zgradite sami, preverite, ali razred že obstaja; ustvarjajte jih raje s pripadajočo metodo pomočnika (api):

DokuWikijev prevajalnik CSS, ki temelji na lessphp (lib/exe/css.php), se pri dveh vzorcih v celoti ustavi – celotno spletno mesto izgubi oblikovanje, ne le vaše pravilo (brskalniki s starim predpomnilnikom tseed izpad sprva prikrijejo):

1. */ v besedilu komentarja – npr. v naštevanju žetonov, kot je a-/b-: */ predčasno zaključi blokovni komentar, ostanek se razčleni kot neveljaven CSS. Zapišite brez poševnice (a-* or b-*).
2. min()/calc() z mešanimi enotami – npr. calc(100% - 2px) v določenih kontekstih ali min(100%, 40em): uporabite vrednosti v isti enoti ali mrežne stolpce z minmax().

Preverjanje po vsaki spremembi CSS: prenesite lib/exe/css.php wikija (npr. s curl) – več sto KB pomeni, da je vse v redu; nekaj sto bajtov z rdečim sporočilom o napaki pomeni, da se je prevajanje prekinilo. Nato posodobite čas spremembe datoteke conf/local.php (zamenjava tseed, glejte preverjanje).

1. Samo žetoni: vsako barvo in pisavo zapišite kot var(–wk-…, rezervna vrednost) (osnovno pravilo zgoraj); vrednosti iščite izključno v tokens.css/color-palette.css.
2. Najprej poiščite, potem gradite: namesto lastnih podvojitev uporabite ustrezen razred .wk-* oziroma metodo pomočnika iz zgornje preglednice; lastni razredi dobijo predpono vtičnika (<vtičnik>-…), nikoli ne spadajo v imenski prostor wk-.
3. Skrbniške gumbe razvrstite po trobarvni semantiki (Contract v3 spodaj): belo = običajno dejanje, vključno s shranjevanjem, modro = posebno dejanje, rdeče = destruktivno dejanje.
4. Izogibajte se pastem prevajalnika (razdelek zgoraj) in po vsaki spremembi preverite css.php in tseed.
5. Preizkusite z vsemi tremi barvnimi shemami (riviera/night/white, razdelek »Barvne sheme«) in enkrat pod tujo predlogo (takrat veljajo rezervne vrednosti).

Če gradite celoten skrbniški modul: Vodnik: gradnja prvega skrbniškega zaslona s FluentUI.

1. Vtičnik oblikovnega sistema določa vse obvezne žetone; predloga svoje rezervne vrednosti deklarira na html, na :root pa le tisto, pri čemer izrecno vztraja.
2. Vtičniki in izsečki vedno pišejo var(–wk-…, rezervna vrednost).
3. Brez barv hex v CSS vtičnika zunaj rezervnih vrednosti v var().
4. V CSS predloge so dobesedne barve dovoljene le za nevtralne učinke (črne in bele sence ter prekrivne plasti, kot je rgba(0,0,0,.45)), ki delujejo v vsaki barvni shemi.
5. Nove žetone uvajamo samo prek te strani (zvišajte različico pogodbe, dopolnite obe datoteki predloge).
6. Prosojne različice barv žetonov tvorite s color-mix(in srgb, var(–wk-…) N%, transparent), ne kot lastne dobesedne vrednosti rgba.

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

Zgornji trak okvira strani v območju spletnega mesta ima stalen slonokoščeni ton in ni odvisen od sheme; žetona zanj ni.

• CSS predlog: wkbizway/css/* (v celoti na žetonih), flat/css/customFlat.css, flat/css/accessibility.css
• Nabora predlog wkblog tpl/wvds in 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 in skladnosti)

Barvna shema je drugačna zasedba obveznih žetonov (css/schemes/<ime>.css v predlogi, samo preglasitve na :root). Ker vsi porabniki gredo prek žetonov, shema zamenja videz celotnega spletnega mesta brez drugih sprememb CSS. Trije poudarki znamke: riviera (privzeto), night, white. Možnost colorscheme vpliva le na profil območja site – profil območja wiki (in z njim vsak zaslon do=admin) se vedno izriše s shemo white, ne glede na to nastavitev. Podrobnosti: BizWay (hišna predloga).

Veriga ima natanko tri člene in vsak vidi le prejšnjega:

1. tokens.css – osnovne vrednosti, vsi obvezni žetoni
2. css/schemes/<ime>.css – preglasitve na :root, aktivna je natanko ena shema
3. Porabniki – CSS predloge, wkblog, wkacmenu, wksnippet in skrbniška prekrivna plast CSS (_admin-forms.css, _admin-drawer.css)

Porabnik nikoli ne bere datoteke sheme, temveč vedno le žetone. Prav zato shema zamenja ves videz, ne da bi bilo treba spremeniti eno samo pravilo pri porabnikih.

Poleg tega aktivni barvni shemi samodejno sledi tudi od tega neodvisna, DokuWikiju lastna pogodba style.ini-[replacements] (__text__, __link__ itd., ki jo prek spremenljivk LESS @ini_* uporablja vsak vtičnik, ne le porabniki –wk-*) – podrobnosti in preglednica nadomestnih oznak: barvne_sheme.

Območje do=admin se izriše z DokuWikijevim izvornim skrbniškim okvirom, ne z lastno nadzorno ploščo. –wk-admin-accent/-accent-light/-hover uporablja css/_admin-forms.css (dodatna strukturna plast nad izvornim skrbniškim HTML-jem, nobena datoteka vtičnikov jedra se ne spremeni) za fieldsete v obliki kartic, poudarek vrstice pod kazalcem, preglednice DataGrid in aktivne elemente (npr. drevo ACL). Skrbniški poudarek tako sledi izbrani barvni shemi. Barvno ni poudarjeno: »vrednost ustreza vgrajeni privzeti« v upravitelju nastavitev (običajni primer, ne izjema); poudarjeno je: »zaščiteno« (ni mogoče spremeniti) in napake pri preverjanju.

Izjema pri slikovnih virih: tekstura menijske vrstice, senca drsnika ter grafike stranske vrstice in noge (assets/images/*-blue.png) so stalne bitne slike iz izvirne teme BizWay in jih z žetoni ni mogoče prebarvati.

Meja pokritosti: _admin-forms.css namensko pokriva zaslone do=admin, ki so priloženi DokuWikiju: acl, config, usermanager, extension, logviewer, styling, popularity, revert, discussion, sqlite (in sam pregled do=admin). Vtičniki drugih ponudnikov zunaj tega seznama in lastna skrbniška orodja wvds* (wkvault, wvdsremote, wvdsdwmmx, wksqliteds, wkdoadogit, wvdsmd, wksnippet) v to pokritost niso vključeni – zanje je odgovoren posamezni vtičnik, ki lahko skrbniški poudarek po želji uporablja sam (wvdsentra in wkblog to že počneta z lastnim skrbniškim videzom). Noben selektor v _admin-forms.css se ne sklicuje na razred ali ID wvds*, temveč le na žetone var(–wk-…) – zato je predloga neodvisna od tega, kateri vtičniki drugih ponudnikov ali lastni vtičniki so nameščeni.

Dopolnjuje zgornjo izjemo za skrbniški videz s tretjo razsežnostjo: pomenom barv dejanj za gumbe v območju do=admin, neodvisno od pogodbe primarno (modro) / sekundarno (obroba) za celotno spletno mesto iz css/design.css (ta ureja prijavo, profil in urejevalnik wikija in ostane nespremenjena). Referenčna izvedba: wkidentity.

Odločitev poteka v tem vrstnem redu in velja prvo pravilo, ki ustreza: destruktivno ali pomembno za varnost → rdeča; sicer posebno dejanje → modra; sicer bela, izrecno vključno s shranjevanjem.

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

Lastni žetoni namesto ponovne uporabe –wk-btn-primary: ta je glavna pogodba za gumbe na celotnem spletnem mestu (prijava, profil, urejevalnik); prihodnja sprememba pomena tam ne sme nehote spremeniti tudi trobarvne semantike v skrbniškem območju, čeprav se oba trenutno sklicujeta na isti modri ton.

Pravilo za imena razredov – odvisno od tega, ali je vir mogoče urejati:

• Vtičniki jedra DokuWiki (PHP ni mogoče urejati, glejte razdelek »Popravki jedra« spodaj): barve se dodelijo izključno prek obstoječih, stabilnih atributov id/name v _admin-forms.css/_admin-drawer.css, nikoli prek vidnega besedila. Zgled: #usrmgr__del, button[name=„fn[export]“]. Predpona ID je pogosto nujna zaradi specifičnosti: _admin-forms.css se naloži pred design.css.
• Lastni vtičniki WvdS (PHP je mogoče urejati): razred se dodeli neposredno v PHP, po vzorcu <predpona-vtičnika>-btn–danger/–accent (zgled: wt-btn–danger v 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 ali v vtičniku: osrednje (_admin-forms.css), kadar ima vtičnik en sam korenski selektor in malo gumbov; v vtičniku (zgled wkidentity/admin.css), kadar vtičnik že prinaša lasten CSS ali ima tako zapleten uporabniški vmesnik, da bi omejevanje z ID-ji v tuji osrednji datoteki otežilo vzdrževanje.

Brez lokalnih plasti žetonov v vtičnikih: slog vtičnika ne deklarira lastnih lastnosti po meri –<predpona-vtičnika>-*, ki le zrcalijo osrednji žeton – vsako pravilo se neposredno sklicuje na osrednji žeton (color: var(–wk-admin-accent, #0f6cbd);). Izjema: blok @media (prefers-color-scheme: dark) ne more preklopiti statične rezervne vrednosti v klicu var() – prizadete selektorje je treba tam ponoviti s temnimi dobesednimi vrednostmi.

Prednostni vrstni red ikon za nove ikone v orodnih vrsticah in na gumbih: 1. Codicons (ustrezajo oblikovnemu jeziku Fluent/ADO), 2. FontAwesome (že gostovan na lastnem strežniku, assets/fonts/fontawesome-webfont.*), 3. DokuWikijeve lastne ikone (lib/images/), le kadar ne ustreza ne Codicon ne FontAwesome. Gre zgolj za prednostni seznam pri prihodnji izbiri simbolov, ne za obveznost zamenjave obstoječih pravilnih ikon.

Politika barv in pisav: iz reference Fluent/Azure DevOps se prevzame izključno strukturni oblikovni jezik (polmeri, fokusni obroč, konvencije za mreže, orodne vrstice in zavihke, stopnje velikosti pisave) – nikoli konkretne Microsoftove vrednosti barv ali pisav. Barve ostanejo lastna paleta znamke (bela, slonokoščena, mornarsko modra, bordo rdeča, zlata). Pisave ostanejo obstoječe pisave Google Fonts, gostovane na lastnem strežniku (Arimo/Roboto/Noto Sans).

Mehanizem ini: trenutno noben porabnik @ini_* v skrbniškem območju ne uporablja barve za nevarnost ali napako (le __theme_color__ → accent, ki je že preslikan). Če bo prihodnji skrbniški zaslon na osnovi LESS potreboval ton za nevarnost prek @ini_*, v $map v wkbizway_sync_style_ini_replacements() (main.php) dodajte ključ z imenskim prostorom __wk_danger__, preslikan na error. Brez vnosa na zalogo, dokler ni porabnika.

Razmejitev od lib/plugins/wvdsdwui/: drugi, neodvisno nastali oblikovni sistem WvdS (lasten nabor žetonov, komponent in ponudnika ikon, repozitorij wk-dw-ui-plugin). Noben tu obravnavani skrbniški vtičnik ne uporablja wvdsdwui – ta semantika skrbniških gumbov in okvira velja izključno za svet prekrivne plasti CSS premium-navy-ivory.

Jedra DokuWiki in priloženih vtičnikov (lib/plugins/{acl,extension,usermanager,config,styling,logviewer,discussion,sqlite,…}, inc/*) ne spreminjamo. Potrjeno napako v jedru prijavimo projektu DokuWiki, namesto da bi jo popravili lokalno: te datoteke niso pod lastnim nadzorom različic, lokalni popravek pa bi ob naslednji posodobitvi jedra neopazno izginil.

Družina obveznih žetonov –wk-sidebar-* (preglednica zgoraj) je skupna osnova za raven vsebnika (ozadje, obroba) vsakega območja na spletnem mestu, ki je podobno stranski vrstici ali auxbaru – »dokument ali aplikacija« je pri tem edina dovoljena vizualna razlika, izražena kot dva poimenovana nabora vrednosti za iste žetone, ne kot samostojna izvedba za vsako območje.

Oba nabora vrednosti sta določena v premium-navy-ivory/css/tokens.css: nabor za dokument kot osnovna vrednost v bloku :root (wiki je v inc/area.php globalno privzeta vrsta območja), nabor za aplikacijo kot preglasitev neposredno na obstoječih imenih razredov .wk-shell-sidebar/.wk-shell-auxbar (brez novega označevalnega razreda in brez spremembe HTML-ja). Dodelitev je statična arhitekturna odločitev za vsako vrsto območja – ni stikala za uporabnika in ni preklapljanja med izvajanjem.

Porabniki: area-wiki.css (.premiumnavyivory-doc-sidebar/.premiumnavyivory-page-toc–desktop/–mobile, ozadje) in wkfluentui/style.css (.wk-shell-sidebar/-auxbar, ozadje in obroba, druga raven rezervne vrednosti v var()). Obarvanje prihaja osrednje iz pogodbe in samodejno velja za vsakega porabnika .wk-shell-sidebar/-auxbar; preglasitev v vtičniku za to ni potrebna. Za statusno in ukazno vrstico ustrezne družine žetonov ni; njuno obarvanje je lokalna preglasitev.

Zgled: kazalo upravitelja nastavitev (.wk-shell-sidebar premiumnavyivory-admin-toc-sidebar, glejte inc/wiki-shell.php) samodejno podeduje obarvanje in obrobo aplikacije – lasten selektor CSS za to stran ni potreben.

Skrbniška območja (stranska vrstica z drevesom objektov, tirnica modulov) so tako kot stranska vrstica dokumentacije in tirnica s kazalom v wikiju prava sorodna elementa <aside> ob <main> in niso ugnezdena v main > .premiumnavyivory-wiki-card > .page.group > …. Za to velja splošna pogodba:

• Skrbniški vtičnik, ki sam izriše celotno lupino (vsebina + auxbar + statusna vrstica), implementira javno metodo getShellRegions(): ?array (oblika rezultata {sidebarHtml: ?string, railHtml: ?string, auxOpen: bool} ali null), ki jo je mogoče poklicati pred tpl_content() – podobno kot DokuWikijeva pogodba getTOC(), vendar vezano na predlogo (ni vmesnik jedra). inc/wiki-shell.php splošno, z method_exists(), preveri, ali aktivni skrbniški vtičnik to metodo ponuja – brez trdo kodiranega seznama imen vtičnikov.
• Če getShellRegions() manjka, vtičnik pa vrne neprazen getTOC(), se njegova vsebina izriše s komponento tree() vtičnika wkfluentui – obe poti se končata na istem mestu <aside id=„dokuwiki__docsidebar“> kot stranska vrstica dokumentacije v wikiju.
• railHtml (le pri vtičnikih z lastno lupino) se izriše kot samostojen <aside id=„dokuwiki__adminmodulerail“> na istem vizualnem mestu kot tirnica s kazalom v wikiju – namenoma z lastnim id/aria-label, ker ima drug pomen (dejanja modula, ne kazalo strani).
• Varnostna zahteva: getShellRegions() se izvede pred DokuWikijevim lastnim preverjanjem skrbniškega dostopa (ki deluje šele pri razvejanju znotraj tpl_content()), zato mora sama uporabiti isto preverjanje zmožnosti kot dejanska metoda html() – sicer bi nepooblaščena globoka povezava v drevesu stranske vrstice pokazala imena povezav ali tabel, čeprav bi bil dostop do vsebine pravilno zavrnjen.
• sidebar-collapsed/rail-collapsed se nastavita le, kadar vsebine za stransko vrstico ali tirnico dejansko ni – po isti logiki, kot jo za svojo stransko vrstico in kazalo uporabljajo strani wikija.

Pristojnost družin razredov: premiumnavyivory-* (last predloge: kljuke za območja, npr. -doc-sidebar/-action-rail) in wk-shell-*/wk-workbench* (last vtičnika: postavitev in obnašanje, npr. wk-shell-sidebar/wk-workbench–no-sidebar) se smeta pojaviti skupaj na istem elementu (npr. class=„premiumnavyivory-doc-sidebar premiumnavyivory-doc-sidebar–app wk-shell-sidebar“), vendar ne brez komentarja – vsaka družina ostane odgovorna za svojo pristojnost (pripadnost območju ali splošna postavitev), nobena ne prevzema pristojnosti druge.

Zavezujoče pravilo: vsaka barvna shema (riviera/night/white) MORA bodisi določiti vsak žeton surove palete, ki se kjerkoli uporablja prek var(), bodisi je žeton izrecno dokumentiran kot neodvisen od sheme (samo :root, nobena datoteka sheme ga ne preglasi – npr. družina –wk-wiki-card-*, ki je namenoma nastavljena le enkrat v tokens.css, da je bralna površina wikija ne glede na poudarek vedno videti kot bel dokument). Tihe tretje možnosti (»v dveh od treh shem«) ni.

Obvezen dokaz kontrasta: za novo dodelitev žetona, ki služi kot meja komponente uporabniškega vmesnika (npr. obroba gumba, kadar je polnilo gumba enako okoliški površini), je treba skladnost z WCAG 1.4.11 (kontrast nebesedilnih elementov, ≥3:1 glede na sosednjo površino) dokazati z izračunom, ne le s tem, da je »bolj vidna od druge možnosti«. Zgled –wk-admin-btn-neutral-border: privzeta vrednost na :root se sklicuje na var(–wk-text-alt) (~5,85:1 v riviera/white); night ima lastno preglasitev #557AA3 (~3,27:1), ker je –wk-text-alt v shemi night svetla barva, namenjena temnim površinam.

Dodatne lastnosti po meri brez spremembe različice pogodbe (zgolj dodane, noben obstoječi porabnik ne spremeni obnašanja):

• --wk-workbench-{sidebar,auxbar}-width / -track – širine stolpcev splošne mreže delovne površine (workbench); ovoji -track pripadajo prelomnim točkam, vrednosti -width pa delilniku (sash, vrstični slog). Porabnik: wkfluentui, razdelek WORKBENCH GRID.
• --wk-shell-statusbar-h – odvisna od gostote: body[data-wk-density="compact"] jo nastavi na 20px (privzeto 22px).
• data-wk-density="compact" na body je edino stikalo plasti gostote (razdelek DENSITY v wkfluentui/style.css); barve stanj v obvestilih (toast) uporabljajo obstoječe žetone stanj --wk-{success,warning,error}.