fix(ui): align contextual documentation with headings

Verified with the coordinated workspace changes by devkit full run
2026-09-08T225814-186389-0000-3e3ed7cd (all seven phases passed).
This shared UI pass does not mark the individual module reviews complete.

README.md

@@ -26,3 +26,21 @@ profile and integration prerequisites are documented in
 [the POLYAS provider profile](docs/POLYAS_PROVIDER_PROFILE.md). Development of
 a native certifiable provider follows the staged, independently evaluated
 [certifiable Voting program](docs/CERTIFIABLE_VOTING_PROGRAM.md).
+
+## Git-source WebUI package
+
+The repository root exposes `@govoplan/voting-webui` for Git-tagged release
+dependencies. It mirrors the owning `webui/package.json` version, public
+TypeScript/CSS exports and peer requirements, with entry paths under
+`webui/src`. Consumers provide the shared Core/React peers; the facade runs no
+development or install scripts. The source archive contains `webui/src`, this
+README and any repository license file. Run module development checks from `webui/`; Python
+installation remains governed by `pyproject.toml`.
+
+Das Repository stellt `@govoplan/voting-webui` am Wurzelpfad für versionierte
+Git-Abhängigkeiten bereit. Version, öffentliche TypeScript-/CSS-Exporte und
+Peer-Anforderungen entsprechen `webui/package.json`; die Einstiegspfade liegen
+unter `webui/src`. Gemeinsame Core-/React-Peers stellt die einbindende Anwendung
+bereit. Die Fassade führt keine Entwicklungs- oder Installationsskripte aus.
+Entwicklungsprüfungen bleiben in `webui/`, die Python-Installation weiterhin in
+`pyproject.toml` definiert.

package.json

@@ -0,0 +1,32 @@
+{
+  "name": "@govoplan/voting-webui",
+  "version": "0.1.21",
+  "private": true,
+  "type": "module",
+  "main": "webui/src/index.ts",
+  "module": "webui/src/index.ts",
+  "types": "webui/src/index.ts",
+  "exports": {
+    ".": {
+      "types": "./webui/src/index.ts",
+      "import": "./webui/src/index.ts"
+    },
+    "./styles/voting.css": "./webui/src/styles/voting.css"
+  },
+  "peerDependencies": {
+    "@govoplan/core-webui": "^0.1.45",
+    "lucide-react": "^1.23.0",
+    "react": ">=19.2.7 <20",
+    "react-dom": ">=19.2.7 <20"
+  },
+  "peerDependenciesMeta": {
+    "@govoplan/core-webui": {
+      "optional": true
+    }
+  },
+  "files": [
+    "webui/src",
+    "README.md",
+    "LICENSE"
+  ]
+}

pyproject.toml

@@ -4,12 +4,12 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "govoplan-voting"
-version = "0.1.20"
+version = "0.1.21"
 description = "Governed voting, ballot assurance, tally, and certification for GovOPlaN."
 readme = "README.md"
 requires-python = ">=3.12"
 authors = [{ name = "GovOPlaN" }]
-dependencies = ["govoplan-core>=0.1.18", "govoplan-access>=0.1.18"]
+dependencies = ["govoplan-core>=0.1.45", "govoplan-access>=0.1.18"]
 
 [tool.setuptools.packages.find]
 where = ["src"]

src/govoplan_voting/__init__.py

@@ -1,3 +1,3 @@
 """GovOPlaN Voting module."""
 
-__version__ = "0.1.20"
+__version__ = "0.1.21"

src/govoplan_voting/backend/manifest.py

@@ -55,7 +55,7 @@ from govoplan_voting.backend.local_confidential_provider import (
 
 MODULE_ID = "voting"
 MODULE_NAME = "Voting"
-MODULE_VERSION = "0.1.20"
+MODULE_VERSION = "0.1.21"
 READ_SCOPE = "voting:ballot:read"
 MANAGE_SCOPE = "voting:ballot:manage"
 CAST_SCOPE = "voting:ballot:cast"
@@ -323,6 +323,27 @@ manifest = ModuleManifest(
     ),
     tenant_summary_providers=(_tenant_summary,),
     documentation=(
+        DocumentationTopic(
+            id="voting.workspace-layout",
+            title="Voting workspace layout",
+            summary="Find workspace actions and read consistently arranged content.",
+            body="Documentation books sit immediately beside the visible heading or contextual label for "
+            "Voting and ballot dialogs, not among operational action buttons. Field help remains beside "
+            "its label. "
+            "Reload and New ballot remain in the workspace-wide top bar, even when a ballot is selected or the catalogue is empty. Reload sits immediately before New. Ballot actions such as opening, casting, certification, challenge, and annulment stay with the selected ballot. New ballot stays visible but disabled without management permission. The shared layout changes no electorate or assurance policy; administrators retain the existing separate management, casting, certification, and administrative grants.",
+            layer="static",
+            documentation_types=("user", "admin"),
+            audience=("user", "module_admin", "operator"),
+            order=5,
+            translations={"de": {
+                "title": "Abstimmungen: Aufbau des Arbeitsbereichs",
+                "summary": "Arbeitsbereichsaktionen finden und einheitlich angeordnete Inhalte lesen.",
+                "body": "Dokumentationsbücher stehen unmittelbar neben der sichtbaren Überschrift oder "
+                "Kontextbezeichnung für Abstimmungen und Abstimmungsdialoge, nicht zwischen ausführbaren "
+                "Aktionsschaltflächen. Feldhilfe bleibt neben der Feldbezeichnung. "
+                "Neu laden und Neue Abstimmung bleiben in der arbeitsbereichsweiten oberen Leiste, auch bei ausgewählter Abstimmung oder leerem Katalog. Neu laden steht unmittelbar vor Neu. Öffnen, Stimmabgabe, Zertifizierung, Anfechtung und Annullierung bleiben bei der ausgewählten Abstimmung. Neue Abstimmung bleibt ohne Verwaltungsrecht sichtbar, aber deaktiviert. Das gemeinsame Layout verändert weder Wählerschaft noch Zusicherung; die getrennten Verwaltungs-, Stimmabgabe-, Zertifizierungs- und Administrationsrechte bleiben bestehen.",
+            }},
+        ),
         DocumentationTopic(
             id="voting.data-subject-requests",
             title="Voting data-subject requests",

webui/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@govoplan/voting-webui",
-  "version": "0.1.20",
+  "version": "0.1.21",
   "private": true,
   "type": "module",
   "main": "src/index.ts",
@@ -14,7 +14,7 @@
     "./styles/voting.css": "./src/styles/voting.css"
   },
   "peerDependencies": {
-    "@govoplan/core-webui": "^0.1.18",
+    "@govoplan/core-webui": "^0.1.45",
     "lucide-react": "^1.23.0",
     "react": ">=19.2.7 <20",
     "react-dom": ">=19.2.7 <20"

webui/src/features/voting/VotingBallotDialog.tsx

@@ -114,7 +114,7 @@ export default function VotingBallotDialog({
   return (
     <Dialog
       open={open}
-      title={ballot ? `Edit ${ballot.title}` : "New ballot"}
+      title={ballot ? `Edit ${ballot.title}` : "New ballot"} titleHelp={<DocumentationHelpLink reference={VOTING_FIELD_DOCUMENTATION} />}
       onClose={requestClose}
       closeDisabled={busy}
       portal
@@ -127,7 +127,7 @@ export default function VotingBallotDialog({
         </>
       }>
       <div className="voting-ballot-editor">
-        <div className="voting-editor-help"><DocumentationHelpLink reference={VOTING_FIELD_DOCUMENTATION} /></div>
+
         {error && <DismissibleAlert tone="danger" resetKey={error}>{error}</DismissibleAlert>}
       <FormGrid columns={2} gap="compact" collapseAt="workspace">
           <FormField label="Title"><input value={draft.title} disabled={busy} onChange={(event) => setDraft({ ...draft, title: event.target.value })} /></FormField>

webui/src/features/voting/VotingPage.tsx

@@ -18,6 +18,7 @@ import { ActionBlockerHint,
   StatePanel,
   StatusBadge,
   WorkspaceActionBar,
+  WorkspaceFrame,
   WorkspaceLayout,
   hasScope,
   i18nMessage,
@@ -150,7 +151,17 @@ export default function VotingPage({ settings, auth }: PlatformRouteContext) {
   }
 
   return (
-    <main className="voting-page">
+    <WorkspaceFrame as="main" className="voting-page" label="Ballots" interfaceId="voting.workspace" helpContextId="voting.workspace" helpModuleId="voting">
+      <WorkspaceActionBar
+        scope="workspace"
+        variant="collection"
+        refreshable
+        reloadAction={{ onReload: () => void loadList().catch((reason) => setError(message(reason, "Ballots could not be loaded."))), loading: loading || busy, label: "Refresh ballots" }}
+        createAction={<Button variant="primary" disabled={!canManage || busy} disabledReason={busy ? VOTING_I18N.busy : !canManage ? VOTING_I18N.manageReason : undefined} onClick={() => setEditing("new")}><Plus size={16} aria-hidden="true" />New ballot</Button>}
+        title="Ballots"
+        titleLevel={1}
+        titleHelp={<DocumentationHelpLink reference={VOTING_DOCUMENTATION} />}
+      />
       <WorkspaceLayout
         variant="split"
         primarySize="default"
@@ -165,15 +176,6 @@ export default function VotingPage({ settings, auth }: PlatformRouteContext) {
         helpContextId="voting.workspace"
         helpModuleId="voting"
         primary={<>
-          <WorkspaceActionBar
-            scope="collection-pane"
-            variant="collection"
-            refreshable
-            reloadAction={{ onReload: () => void loadList(), loading: loading || busy, label: "Refresh ballots" }}
-            className="voting-toolbar"
-            createAction={<Button variant="primary" disabled={!canManage} disabledReason={!canManage ? VOTING_I18N.manageReason : undefined} onClick={() => setEditing("new")}><Plus size={16} aria-hidden="true" />New ballot</Button>}
-            helpAction={<DocumentationHelpLink reference={VOTING_DOCUMENTATION} />}
-          />
           <PageScrollViewport className="voting-list-viewport">
             {loading && <LoadingIndicator label="Loading ballots" />}
             {!loading && items.length === 0 && <StatePanel size="compact" description="No ballots." />}
@@ -317,7 +319,7 @@ export default function VotingPage({ settings, auth }: PlatformRouteContext) {
           void cast();
         }}
       />
-    </main>
+    </WorkspaceFrame>
   );
 }
 

webui/src/i18n/generatedTranslations.ts

@@ -1,6 +1,7 @@
 import type { PlatformTranslations } from "@govoplan/core-webui";
 
 const en = {
+  "Ballots": "Ballots",
   "i18n:govoplan-voting.voting": "Voting",
   "i18n:govoplan-voting.loading_reason": "Ballot data is still loading.",
   "i18n:govoplan-voting.busy_reason": "Another ballot action is still running.",
@@ -76,6 +77,7 @@ const en = {
 } as const;
 
 const de: Record<keyof typeof en, string> = {
+  "Ballots": "Abstimmungen",
   "i18n:govoplan-voting.voting": "Abstimmungen",
   "i18n:govoplan-voting.loading_reason": "Abstimmungsdaten werden noch geladen.",
   "i18n:govoplan-voting.busy_reason": "Eine andere Abstimmungsaktion läuft noch.",