Styles-Contract (--wk-*)

Der Styles-Contract ist die verbindliche CSS-Schnittstelle zwischen Templates und Plugins: ein fester Satz CSS Custom Properties (–wk-*). Das Design-System-Plugin wkfluentui besitzt diese Palette, und eine Vorlage steuert einen Rückfall bei. Plugins und Snippets konsumieren ausschließlich diese Tokens – dadurch sieht die gesamte Site unter jedem Template „aus einem Haus“ aus, ohne dass Plugin-CSS angepasst werden muss.

Version: 17 · Normative Quelle: lib/tpl/wkbizway/css/tokens.css

Grundregel: Farbe, Schriftart, Fokus-Ring-Optik und Inhaltsbreite kommen nie als eigener Hex-/Pixel-/Font-Wert in Plugin-CSS – immer als var(–wk-…, Fallback-Wert). Layout, Innen-/Außenabstände, eigene Klassennamen, Icons, Komponentenstruktur und JavaScript-Verhalten sind vollständig frei; der Contract schränkt hier nichts ein.

Entscheidungsregel – Token oder frei wählbar?

• Pflicht-Token aus der Tabelle unten: jede Farbe, die Schriftfamilie/-stack, die Fokus-Ring-Optik, die Inhaltsbreite.
• Vollständig frei: Layout (Flexbox/Grid), Abstände, eigene Klassennamen, Icons, Komponentenaufbau, JavaScript-Verhalten.
• Nicht selbst erfinden: Braucht ein Plugin eine Farbe/Schrift ohne passende Token-Semantik, wird sie hier als neuer Pflicht- oder Extension-Token vorgeschlagen (siehe „Regeln“ unten) statt als Ad-hoc-Wert eingeführt – sonst bricht sie beim nächsten Farbschema-Wechsel unbemerkt die Konsistenz.

Folge bei Ignorieren der Grundregel: kein Fehler, kein Absturz – das Plugin verliert nur die Teilnahme am Farbschema-Wechsel (riviera/night/white, s. u.). Ein hartcodiertes Blau bleibt blau, auch wenn der Nutzer das Schema wechselt; token-basiertes CSS wechselt automatisch mit.

/* 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);
}

Der Fallback-Wert (zweites var()-Argument) ist Pflicht, nicht optional: läuft das Plugin unter einem fremden Template ohne diesen Contract, existiert der Token nicht – ohne Fallback bleibt die Eigenschaft leer. Der Fallback muss für sich allein eine akzeptable Optik ergeben.

Tatsächliche Werte stehen ausschließlich in tokens.css bzw. color-palette.css des aktiven Templates – nie aus einem Screenshot ablesen oder raten, Werte unterscheiden sich pro Farbschema (siehe „Farbschemata“ unten).

Diese Seite regelt Tokens und CSS-Konventionen. Alles Übrige – Layout-Muster, Widgets, Verhalten – steht in der Design-System-Bibliothek WvdS FluentUI. Für Entwickler ohne WvdS-Vorwissen in Lesereihenfolge:

Site-weit geladene CSS-Bausteine (wkfluentui/css/widgets.css über das CSS_STYLES_INCLUDED-Event) – vor jedem eigenen Bau prüfen, ob eine Klasse schon existiert; Erzeugung bevorzugt über die zugehörige Helper-Methode (api):

DokuWikis lessphp-basierter Compiler (lib/exe/css.php) bricht bei zwei Mustern komplett ab – die gesamte Site verliert ihr Styling, nicht nur die eigene Regel (Browser mit altem tseed-Cache kaschieren den Ausfall zunächst):

1. */ im Kommentartext – z. B. in Token-Aufzählungen wie a-/b-: das */ beendet den Blockkommentar vorzeitig, der Rest wird als CSS-Müll geparst. Formulierung ohne Schrägstrich wählen (a-* or b-*).
2. min()/calc() mit gemischten Einheiten – z. B. calc(100% - 2px) in bestimmten Kontexten bzw. min(100%, 40em): einheitengleiche Werte oder minmax()-Grid-Tracks verwenden.

Verifikation nach jeder CSS-Änderung: lib/exe/css.php des Wikis abrufen (z. B. mit curl) — mehrere hundert KB = ok; wenige hundert Bytes mit roter Fehlermeldung = Compile-Abbruch. Danach conf/local.php touchen (tseed-Rotation, siehe Verifikation).

1. Nur Tokens: jede Farbe/Schrift als var(–wk-…, Fallback) (Grundregel oben); Werte-Nachschlag ausschließlich in tokens.css/color-palette.css.
2. Erst suchen, dann bauen: passende .wk-*-Klasse bzw. Helper-Methode aus der Tabelle oben verwenden statt eigener Duplikate; eigene Klassen mit Plugin-Präfix (<plugin>-…), nie im wk--Namensraum.
3. Admin-Buttons klassifizieren nach der 3-Farben-Semantik (Contract v3 unten): weiß = gewöhnlich inkl. Speichern, blau = Sonderaktion, rot = destruktiv.
4. Compiler-Fallen meiden (Abschnitt oben) und nach jedem Edit css.php + tseed prüfen.
5. Gegen alle drei Farbschemata testen (riviera/night/white, Abschnitt „Farbschemata“) und einmal unter einem fremden Template (Fallback-Werte greifen dann).

Wer darüber hinaus ein komplettes Admin-Modul aufbaut: Tutorial: Erste Admin-Oberfläche mit FluentUI bauen.

1. Das Design-System-Plugin definiert alle Pflicht-Tokens; eine Vorlage deklariert ihren Rückfall auf html und nur das, worauf sie ausdrücklich besteht, auf :root.
2. Plugins/Snippets schreiben immer var(–wk-…, fallback).
3. Keine Hex-Farben in Plugin-CSS außerhalb von var()-Fallbacks.
4. In Template-CSS sind Literalfarben nur für neutrale Effekte erlaubt (Schwarz/Weiß-Schatten und -Overlays wie rgba(0,0,0,.45)), die unter jedem Farbschema funktionieren.
5. Neue Tokens werden nur über diese Seite eingeführt (Contract-Version erhöhen, beide Template-Dateien ergänzen).
6. Alpha-Varianten von Token-Farben über color-mix(in srgb, var(–wk-…) N%, transparent) bilden, nicht als eigene rgba-Literale.

Templates dürfen zusätzliche Tokens für eigene Skin-Details definieren; Plugins dürfen sich nicht darauf verlassen.

Der obere Rahmenstreifen der Site-Seitenhülle ist ein fester Ivory-Ton, keine schemaabhängige Farbe; einen Token dafür gibt es nicht.

• Template-CSS: wkbizway/css/* (vollständig token-basiert), flat/css/customFlat.css, flat/css/accessibility.css
• wkblog-Template-Sets tpl/wvds + tpl/premiumnavyivory — beide über premium-navy-ivory/css/blog.css
• Plugins: wvdstheme/style.css, wkacmenu/style.css, wvdsaudit-Badges
• wksnippet-Snippets (~40 HTML-Bausteine mit Inline-var(–wk-…, fallback))
• Config-Snippets in conf/local.php (Audit-/Compliance-Badges)

Ein Farbschema ist eine alternative Belegung der Pflicht-Tokens (css/schemes/<name>.css im Template, nur :root-Overrides). Weil alle Konsumenten über Tokens gehen, wechselt ein Schema die komplette Site-Optik ohne weitere CSS-Änderungen. Drei Marken-Akzente: riviera (Standard), night, white. Die Option colorscheme wirkt nur auf das Area-Profil site — das Area-Profil wiki (und damit jeder do=admin-Bildschirm) rendert ausnahmslos mit white, unabhängig von dieser Einstellung. Details: BizWay (Hausvorlage).

Die Kette hat genau drei Glieder, und jedes sieht nur das vorige:

1. tokens.css — Basiswerte, alle Pflicht-Tokens
2. css/schemes/<name>.css — :root-Overrides, genau ein Schema aktiv
3. Konsumenten — Template-CSS, wkblog, wkacmenu, wksnippet und das Admin-CSS-Overlay (_admin-forms.css, _admin-drawer.css)

Ein Konsument liest nie eine Schemadatei, sondern immer nur Tokens. Genau deshalb wechselt ein Schema die ganze Optik, ohne dass eine einzige Konsumentenregel angefasst werden müsste.

Zusätzlich folgt der davon unabhängige, DokuWiki-native style.ini-[replacements]-Kontrakt (__text__, __link__ usw., konsumiert über @ini_*-LESS-Variablen von jedem Plugin, nicht nur –wk-*-Verbrauchern) automatisch dem jeweils aktiven Farbschema — Details und Platzhalter-Tabelle: Farbschemata.

Der do=admin-Bereich rendert über DokuWikis natives Admin-Chrome, nicht über ein eigenes Dashboard. –wk-admin-accent/-accent-light/-hover konsumiert css/_admin-forms.css (additives Struktur-Overlay über das native Admin-Markup, keine Core-Plugin-Datei wird verändert) für Karten-Fieldsets, Zeilen-Hover, DataGrid-Tabellen und aktive Elemente (z. B. ACL-Baum). Der Admin-Akzent folgt damit dem gewählten Farbschema. Farblich nicht akzentuiert: „Wert entspricht dem eingebauten Standard“ im Config Manager (Normalfall, keine Ausnahme); akzentuiert: „geschützt“ (nicht änderbar) und Validierungsfehler.

Bild-Assets-Ausnahme: Menüleisten-Textur, Slider-Schatten und Sidebar-/Footer-Grafiken (assets/images/*-blue.png) sind feste Bitmaps aus dem BizWay-Original-Theme, nicht per Token umfärbbar.

Abdeckungsgrenze: _admin-forms.css deckt gezielt die mit DokuWiki mitgelieferten do=admin-Bildschirme ab: acl, config, usermanager, extension, logviewer, styling, popularity, revert, discussion, sqlite (plus die do=admin-Übersicht selbst). Drittanbieter-Plugins außerhalb dieser Liste und eigene wvds*-Admin-Tools (wkvault, wvdsremote, wvdsdwmmx, wksqliteds, wkdoadogit, wvdsmd, wksnippet) sind nicht Teil dieser Abdeckung — sie liegen in der Verantwortung des jeweiligen Plugins, das den Admin-Akzent optional selbst konsumieren kann (wvdsentra, wkblog tun das bereits mit eigener Admin-Optik). Keine _admin-forms.css-Selektor referenziert eine wvds*-Klasse/-ID, nur var(–wk-…)-Tokens — das Template bleibt dadurch unabhängig davon, welche Drittanbieter-/eigenen Plugins installiert sind.

Ergänzt die Admin-Chrome-Ausnahme oben um eine dritte Dimension: eine Aktions-Farbsemantik für Buttons im do=admin-Bereich, unabhängig vom sitweiten primär(blau)/sekundär(Outline)-Kontrakt aus css/design.css (der Login/Profil/Wiki-Editor bedient und nicht angefasst wird). Referenzumsetzung: wkidentity.

Die Entscheidung läuft in dieser Reihenfolge, und die erste zutreffende gewinnt: destruktiv oder sicherheitsrelevant → rot; sonst Sonderaktion → blau; sonst weiß, ausdrücklich einschließlich Speichern.

Neue Tokens (tokens.css, zwischen dem Buttons- und dem Extension-Tokens-Block):

Eigene Tokens statt Wiederverwendung von –wk-btn-primary: Letzterer ist der sitweite Haupt-Button-Kontrakt (Login/Profil/Editor); eine künftige Bedeutungsänderung dort darf die admin-interne 3-Farben-Semantik nicht ungewollt mit verändern, auch wenn beide aktuell denselben Blauton referenzieren.

Klassennamens-Konvention, nach Editierbarkeit der Quelle:

• DokuWiki-Core-Plugins (PHP nicht editierbar, s. Abschnitt „Core-Patches“ unten): Farbzuordnung ausschließlich über vorhandene, stabile id-/name-Attribute in _admin-forms.css/_admin-drawer.css, niemals über sichtbare Texte. Referenz: #usrmgr__del, button[name=„fn[export]“]. Ein ID-Präfix ist oft eine Spezifitäts-Notwendigkeit: _admin-forms.css lädt vor design.css.
• WvdS-eigene Plugins (PHP editierbar): direkte Klassenvergabe im PHP, Muster <plugin-präfix>-btn–danger/–accent (Referenz: wkidentitys wt-btn–danger). CSS-Regeln zeigen per var(–wk-…, Fallback) auf die zentralen Tokens.
• Generischer Fall: wiederverwendbares Klassenpaar .wk-admin-btn–danger/–accent in _admin-forms.css.
• Zentral vs. plugin-lokal: zentral (_admin-forms.css), wenn ein Plugin einen einzelnen Root-Selektor und wenige Buttons hat; plugin-lokal (Vorbild wkidentity/admin.css), wenn ein Plugin bereits eigenes CSS mitbringt oder eine so komplexe UI hat, dass ID-Scoping in einer fremden zentralen Datei die Wartbarkeit verschlechtern würde.

Keine lokalen Token-Layer in Plugins: ein Plugin-Stylesheet deklariert keine eigenen –<plugin-präfix>-*-Custom-Properties, die nur einen zentralen Token spiegeln — jede Regel referenziert den zentralen Token direkt (color: var(–wk-admin-accent, #0f6cbd);). Ausnahme: ein @media (prefers-color-scheme: dark)-Block kann den statischen Fallback-Wert eines var()-Aufrufs nicht umschalten — betroffene Selektoren müssen dort mit dunklen Literalen wiederholt werden.

Icon-Priorität für neue Toolbar-/Button-Iconografie: 1. Codicons (passt zur Fluent-/ADO-Formensprache), 2. FontAwesome (bereits selbst gehostet, assets/fonts/fontawesome-webfont.*), 3. DokuWikis eigene Icons (lib/images/), nur wenn weder Codicon noch FontAwesome passt. Reine Prioritätsliste für künftige Symbolwahl, kein Zwang zum Ersetzen bestehender korrekter Icons.

Farb- und Schriftpolitik: aus einer Fluent-/Azure-DevOps-Referenz wird ausschließlich die strukturelle Formensprache übernommen (Radius, Fokusring, Grid-/Toolbar-/Tab-Konventionen, Typo-Größenstufen) — niemals Microsofts konkrete Farb- oder Schriftwerte. Farben bleiben die eigene Marken-Palette (Weiß, Ivory, Navy-Blau, Burgund-Rot, Gold). Schriftarten bleiben die bestehenden, selbst gehosteten Google-Fonts (Arimo/Roboto/Noto Sans).

Ini-Mechanismus: aktuell konsumiert kein @ini_*-Verbraucher im Admin-Bereich eine Danger-/Fehlerfarbe (nur __theme_color__ → accent, bereits gemappt). Braucht ein künftiger LESS-basierter Admin-Screen einen Danger-Ton über @ini_*: einen namespaced Schlüssel __wk_danger__ zur $map in wkbizway_sync_style_ini_replacements() (main.php) ergänzen, gemappt auf error. Kein proaktiver Eintrag ohne Verbraucher.

Abgrenzung zu lib/plugins/wvdsdwui/: ein zweites, unabhängig gewachsenes WvdS-Design-System (eigener Token-/Komponenten-/Icon-Provider-Satz, Repo wk-dw-ui-plugin). Kein hier behandeltes Admin-Plugin nutzt wvdsdwui — diese Admin-Button-/Chrome-Semantik gilt ausschließlich für die premium-navy-ivory-CSS-Overlay-Welt.

Der DokuWiki-Kern und die mitgelieferten Plugins (lib/plugins/{acl,extension,usermanager,config,styling,logviewer,discussion,sqlite,…}, inc/*) werden nicht verändert. Eine bestätigte Fehlfunktion des Kerns wird beim DokuWiki-Projekt gemeldet statt lokal gepatcht: diese Dateien stehen unter keiner eigenen Versionskontrolle, und ein lokaler Patch ginge mit der nächsten Kernaktualisierung still verloren.

Die Pflicht-Token-Familie –wk-sidebar-* (Tabelle oben) ist die gemeinsame Basis für die Container-Ebene (Hintergrund, Rahmen) jeder Sidebar-/Auxbar-artigen Region der Site — „Dokument vs. App“ ist dabei der einzige sanktionierte optische Unterschied, ausgedrückt als zwei benannte Wertesätze für dieselben Tokens, nicht als eigenständige Implementierung je Bereich.

Beide Wertesätze sind in premium-navy-ivory/css/tokens.css definiert: der Dokument-Satz als Basiswert im :root-Block (Wiki ist inc/area.phps globaler Default-Bereichstyp), der App-Satz als Override direkt auf den bestehenden Klassennamen .wk-shell-sidebar/.wk-shell-auxbar (keine neue Marker-Klasse, keine Markup-Änderung nötig). Die Zuweisung ist eine statische Architektur-Entscheidung je Regionstyp — kein Nutzer-Toggle, keine Laufzeit-Umschaltung.

Konsumenten: area-wiki.css (.premiumnavyivory-doc-sidebar/.premiumnavyivory-page-toc–desktop/–mobile, Hintergrund) und wkfluentui/style.css (.wk-shell-sidebar/-auxbar, Hintergrund + Rahmen, zweiter var()-Fallback-Level). Die Tönung kommt zentral aus dem Contract und gilt automatisch für jeden .wk-shell-sidebar/-auxbar-Verbraucher; ein plugin-lokaler Override ist dafür nicht nötig. Für Statusbar und Commandbar gibt es keine entsprechende Token-Familie; ihre Tönung ist ein lokaler Override.

Beispiel: der Konfigurations-Manager-TOC (.wk-shell-sidebar premiumnavyivory-admin-toc-sidebar, siehe inc/wiki-shell.php) erbt automatisch die App-Tönung und den Rahmen — ein eigener CSS-Selektor für diese Seite ist nicht nötig.

Admin-Regionen (Objekt-Baum-Sidebar, Modul-Rail) liegen wie die Wiki-Doc-Sidebar/TOC-Rail als echte <aside>-Geschwister von <main>, nicht verschachtelt in main > .premiumnavyivory-wiki-card > .page.group > …. Dafür gilt ein generischer Kontrakt:

• Ein Admin-Plugin, das seine komplette Shell selbst rendert (Content+Auxbar+Statusbar), implementiert eine öffentliche Methode getShellRegions(): ?array (Rückgabeform {sidebarHtml: ?string, railHtml: ?string, auxOpen: bool} oder null), aufrufbar vor tpl_content() — analog zu DokuWikis eigenem getTOC()-Kontrakt, aber template-spezifisch (kein Core-Interface). inc/wiki-shell.php prüft generisch per method_exists(), ob das aktive Admin-Plugin diese Methode anbietet — keine hartcodierte Plugin-Namensliste.
• Fehlt getShellRegions(), aber liefert das Plugin ein nicht-leeres getTOC(), wird dessen Inhalt über wkfluentuis tree()-Komponente gerendert — beide Pfade münden in derselben <aside id=„dokuwiki__docsidebar“>-Position wie die Wiki-Doc-Sidebar.
• railHtml (nur bei eigenschalenbesitzenden Plugins) rendert als eigene <aside id=„dokuwiki__adminmodulerail“> im selben visuellen Slot wie die Wiki-TOC-Rail — bewusst eigene id/aria-label, andere Semantik (Modul-Aktionen, keine Seiten-TOC).
• Sicherheitsanforderung: getShellRegions() läuft vor DokuWiki-Cores eigener Admin-Zugriffsprüfung (die erst innerhalb von tpl_content()s Dispatch greift) und muss deshalb selbst denselben Capability-Gate wie die eigentliche html()-Methode anwenden — sonst könnte ein nicht autorisierter Deep-Link Verbindungs-/Tabellennamen im Sidebar-Baum sehen, obwohl der Content-Bereich korrekt verweigert würde.
• sidebar-collapsed/rail-collapsed werden nur gesetzt, wenn tatsächlich kein Sidebar-/Rail-Inhalt vorhanden ist — dieselbe Logik, die Wiki-Seiten für ihre eigene Sidebar/TOC anwenden.

Klassen-Familien-Zuständigkeit: premiumnavyivory-* (Template-Eigentum: Regions-/Bereichs-Hooks, z. B. -doc-sidebar/-action-rail) und wk-shell-*/wk-workbench* (Plugin-Eigentum: Layout/Verhalten, z. B. wk-shell-sidebar/wk-workbench–no-sidebar) dürfen gemeinsam auf einem Element stehen (z. B. class=„premiumnavyivory-doc-sidebar premiumnavyivory-doc-sidebar–app wk-shell-sidebar“), aber nicht unkommentiert — jede Familie bleibt für ihre eigene Zuständigkeit (Bereichszugehörigkeit vs. generisches Layout) verantwortlich, keine Familie überschreibt die Zuständigkeit der anderen.

Verbindliche Regel: jedes Farbschema (riviera/night/white) MUSS entweder jeden Rohpalette-Token definieren, der irgendwo per var() konsumiert wird, oder der Token wird als schema-invariant (:root-only, keine Schema-Datei überschreibt ihn — z. B. die –wk-wiki-card-*-Familie, die bewusst nur einmal in tokens.css gesetzt wird, damit die Wiki-Lesefläche unabhängig vom Akzent immer als weißes Dokument erscheint) explizit dokumentiert. Keine stille dritte Möglichkeit („in zwei von drei Schemata da“).

Kontrast-Nachweis-Pflicht: eine neue Token-Zuweisung, die als UI-Komponentengrenze dient (z. B. ein Button-Rahmen, wenn Button-Füllung == umgebende Fläche), muss WCAG 1.4.11 (Non-Text-Contrast, ≥3:1 gegen die angrenzende Fläche) rechnerisch nachgewiesen werden, nicht nur „sichtbarer als die Alternative“. Beispiel –wk-admin-btn-neutral-border: der :root-Default referenziert var(–wk-text-alt) (~5,85:1 in riviera/white); Night hat einen eigenen Override #557AA3 (~3,27:1), weil Nights –wk-text-alt eine für dunkle Flächen gedachte helle Farbe ist.

Zusätzliche Custom Properties ohne Contract-Versionsänderung (rein additiv, kein bestehender Konsument ändert sein Verhalten):

• --wk-workbench-{sidebar,auxbar}-width / -track — Spaltenbreiten des generischen Workbench-Grids; die -track-Wrapper gehören den Breakpoints, die -width-Werte dem Sash (Inline-Style). Konsument: wkfluentui Sektion WORKBENCH GRID.
• --wk-shell-statusbar-h — dichteabhängig: body[data-wk-density="compact"] setzt es auf 20px (Standard 22px).
• data-wk-density="compact" am body ist der einzige Schalter der Dichte-Wirkschicht (Sektion DENSITY in wkfluentui/style.css); Toast-Statusfarben nutzen die bestehenden Status-Tokens --wk-{success,warning,error}.