ping-mee-self-service-platform/_bmad-output/initiative-ping-mee-portal/epic-platform-and-sign-in/story-page-shell-preferences-and-translations-plan.md

title, type, ticket, created, status, baseline_revision, route, route_source, risk, review, review_source, context

title	type	ticket	created	status	baseline_revision	route	route_source	risk	review	review_source	context
Page shell, preferences and translations	feature	6	2026-10-17	built	3c69c2a	full	auto	medium	quick	pinned	{project-root}/_bmad-output/architecture/architecture-ping-mee-self-service-platform-2026-10-15/ARCHITECTURE-SPINE.md {project-root}/_bmad-output/ux-designs/ux-ping-mee-self-service-platform-2026-10-15/DESIGN.md {project-root}/_bmad-output/ux-designs/ux-ping-mee-self-service-platform-2026-10-15/EXPERIENCE.md

Intent

Problem: After sign-in the user sees an unstyled English page. Every later epic needs one shared layout, the three per-device preferences and German/English text before it can add a page.

Approach: One base layout (top bar, left menu with role-based groups, profile menu, skip link) in plain server-rendered HTML styled with the design tokens, with the Fluent web components used for the interactive controls and bundled into the image. Theme, language and German form of address are stored in cookies and read by the server to render the page. All existing text moves to a German formal, German informal and English catalogue.

Boundaries & Constraints

Always: AD-15 and AD-16 apply. No inline script, inline style or inline event handler (CSP stays script-src 'self'); no network request for fonts, icons or scripts at runtime. The theme is an attribute on <html>; system is resolved by CSS (prefers-color-scheme) only. Preferences are never sent to the server except as cookies. Every user-visible string goes through translation. The menu is declared in one place with the role each entry needs; a hidden entry is also refused by its view (decorators from 1.5). Touch targets are at least 44 px; the break between wide and narrow layout is 720 px. The page works for navigation and sign-out without JavaScript.

Never: No dashboard content (account card, announcements): that is the account epic. No Admin colour or background settings: the accent colour is a CSS variable with the default #0F6CBD, set by a later entry. No server-stored preferences. No Node.js or npm in the runtime image. No CDN.

I/O & Edge-Case Matrix

Scenario	Input / State	Expected Output / Behavior	Error Handling
Shell after sign-in	Signed-in user	Top bar with portal name and avatar (initials), left menu, content; their display name is shown in the profile menu	n/a
Menu by role	User / Publisher / Admin	User: Startseite. Publisher adds group "Veröffentlichen". Admin adds group "Administration". A Publisher who is not Admin sees no Administration group	A direct address to a hidden page shows "Dazu fehlt Ihnen die Berechtigung." (403)
First visit	No preference cookies	Theme System, language from Accept-Language (de or en, else en), German form formal	n/a
Choose preference	Profile menu	Cookie set, page re-renders with the new value; with JavaScript it applies at once without reloading	An unknown value is ignored, the cookie is not set
Informal form	Language English, form "du"	Form has no effect on English and the control is hidden	n/a
Informal German	Language German, form "du"	Strings use "du" forms; a string with no informal entry falls back to the formal one	n/a
Unsafe return address	next outside the site	Ignored; the user goes to /	n/a
Phone width	360 px	Menu behind a menu button, one column, no horizontal scroll	n/a
Signed-out and error pages	Not signed in	Same layout without menu and avatar; preferences still readable from the cookies	n/a

Code Map

• portal/templates/base.html -- new shared layout; accounts/base.html becomes a thin extension of it. All 1.5 pages move onto it.
• portal/shell/ -- new app: menu.py (declaration of entries: label, URL name, required role, group), preferences.py (read and validate the three cookies, cookie names and lifetime), middleware.py (activates the language, sets request.preferences), context.py (context processor: menu filtered by role, preferences), views.py (POST /preferences), urls.py.
• portal/frontend/ -- new: package.json, package-lock.json, an entry file that imports only the Fluent components used, and a build script.
• portal/static/portal/ -- shell.css (tokens from DESIGN.md, light and dark, phone layout), shell.js (menu button, profile menu, apply preference at once; no inline code).
• portal/locale/{de,de_DU,en}/LC_MESSAGES/django.po -- catalogues; de_DU holds only the informal differences and falls back to de.
• Dockerfile -- a frontend build stage on node:*-slim runs npm ci and the bundle; the result is copied into portal/static/vendor/ before collectstatic. Message catalogues are compiled in the builder stage.
• portal/config/settings.py -- add the app, middleware and context processor, LANGUAGES with the informal variant.
• portal/config/middleware.py -- CSP gains style-src 'self' and img-src 'self' data: only if the Fluent bundle needs them (decided at build; no unsafe-inline).
• Placeholder pages for the Publisher and Admin groups (one view each, decorated with publisher_required / admin_required, text "Diese Seite folgt.") so role visibility and the direct-address refusal can be checked now; later epics replace them.
• portal/tests/ -- test_preferences.py, test_shell.py, test_translations.py.

Tasks & Acceptance

Execution:

• portal/frontend/ and Dockerfile stage -- build the Fluent bundle into the image, pinned by lockfile -- AD-16
• portal/shell/preferences.py, middleware.py -- cookies in, validated preferences out, language activated per request -- AD-15
• portal/templates/base.html, shell.css, shell.js -- layout, themes, profile menu, phone menu, skip link
• portal/shell/menu.py, context.py -- role-filtered menu and active-item marker
• portal/locale/ -- German formal, German informal and English text for every existing string; compile step in the Docker build
• Move the 1.5 pages onto the shell; placeholder Publisher and Admin pages
• Tests for every matrix row

Acceptance Criteria:

• Given a signed-in user, when the home page loads, then the top bar, menu and their display name are in the page and no script, style or event-handler attribute is inline.
• Given a User, a Publisher and an Admin, when the menu renders, then it shows Startseite, plus "Veröffentlichen" only for Publishers and "Administration" only for Admins, and a direct request to a hidden page returns 403.
• Given cookies theme=dark, lang=de, form=du, when a page renders, then <html> carries the dark theme and the page text uses the informal form; with lang=en it is English and ignores the form.
• Given no cookies and Accept-Language: de-DE, when a page renders, then it is German formal and the theme is System.
• Given an invalid preference value, when it is posted, then no cookie changes.
• Given every {% trans %} and gettext string in the code, when the catalogue test runs, then each has a German entry and no entry is fuzzy or empty.
• Given a viewport of 360 px, when the page loads, then the menu is behind a button and there is no horizontal scrolling (checked by hand at the done step; the CSS rule is checked by test).

Design Notes

Preferences are cookies named pm_theme, pm_lang, pm_form, SameSite=Lax, Secure, one year, not HttpOnly so shell.js can apply a change without a reload; they hold no personal data. The informal German register is a language code de-du whose catalogue holds only differing strings; Django's gettext lookup falls back to de, which falls back to msgid. If that fallback does not behave as expected in the build, the plan changes to a template filter, not to duplicated catalogues.

msgfmt and xgettext (GNU gettext) are not available on the Windows development machine, so strings are added to the catalogues by hand and a test (using polib) keeps them complete; the compile step runs in the Docker builder stage, which installs gettext. Message extraction with makemessages can be run in a container later when the string count grows.

Fluent web components render inside shadow DOM; if a component needs inline styles that the CSP refuses, the control falls back to plain HTML and CSS rather than loosening the policy.

Verification

Commands:

• uv run pytest -- expected: all tests pass, including the new ones
• uv run ruff check portal manage.py docker -- expected: no findings
• uv run python manage.py makemigrations --check --dry-run -- expected: no changes detected
• docker compose up --build on the Linux host -- expected: image builds with the front-end stage; pages load with no CSP violations in the browser console

Manual: sign in as ptest-user1, ptest-publisher, ptest-admin; check the menu groups, change the three preferences and reload, narrow the window to phone width, and open / in a private window to see the defaults.

Implementation Notes

• Built inline; pytest 247 passed, 6 skipped (live LDAP), ruff check clean, makemigrations --check no changes.
• Judgement calls: the Fluent bundle contains only the avatar (the one control the shell needs that works with a fallback); buttons and menus are native HTML so the shell works without JavaScript. The profile menu is a <details> element. Theme applies at once; language and form reload the page because the server renders the text. LocaleMiddleware is replaced by PreferencesMiddleware. The de_DU catalogue fell back to de as hoped (tested). No locale/en catalogue: the message ids are English. Placeholder pages live at /publish/announcements and /administration/{appearance,settings,audit,status}.
• Not verified: the Docker build (Node stage, compilemessages) and the visual result in a browser, including the Fluent avatar tokens and the phone layout, since neither runs on the Windows machine.