Apply shared DataOps shell tokens and primitives to the V1 portal shell

[alexeygrigorev]

Apply shared DataOps shell tokens and primitives to the V1 portal shell

Status: pending
Tags: enhancement, portal, frontend, design, P1
Depends on: #46
Blocks: None

Scope

Implement the first runtime migration slice from docs/design-system.md: make the current V1 portal shell use the shared DataOps --do-* token namespace and shell primitives while preserving the existing plain HTML/CSS/JavaScript stack.

This is not cosmetic-only. The goal is to make the portal feel like one unified operations workspace for the operations manager: daily operations queue, task/workflow context, proof controls, reminders/follow-ups, process docs in context, and assistant/artifact preview areas should all sit inside one consistent shell language.

Primary implementation surface:

• frontend/src/styles.css
• frontend/index.html
• frontend/src/app.js only where needed for shell/drawer/panel accessibility or class/state wiring
• docs/design-system.md as the source of token and primitive names

Apply this first slice to the current portal shell and operator surfaces:

• workspace shell, desktop sidebar, collapsed sidebar rail, mobile top bar, and mobile drawer;
• page toolbar, toolbar action groups, save state, notification/work bell entry point, and shell-level buttons;
• Operations Home layout, daily lanes, workflow/template/future assistant cards, and runtime-unavailable states only as needed to consume shared shell/card/button/status tokens;
• task detail panel and workflow/bundle detail panel layer behavior, proof/follow-up sections, file/artifact rows, and panel close/back affordances;
• popovers, modal/dialog layers, toasts, focus rings, reduced-motion rules, density, border/radius/shadow, and dark-mode token overrides;
• compatibility aliases from existing portal variables such as --bg, --sidebar, --surface, --line, --line-strong, --accent, and related button/status variables to canonical --do-* tokens.

Keep existing runtime behavior. This issue should not change task completion semantics, work-engine APIs, docs search behavior, editor save behavior, authentication, Lambda routing, or deployment configuration except for small shell/drawer/panel accessibility fixes needed by the shared primitives.

Product Intent

After this work, the operations manager should experience the portal as a coherent daily operations workspace rather than a docs site with several attached widgets. The user should be able to start at Operations Home, scan Today/Overdue/Waiting/Workflows, open a task or workflow panel, see proof/follow-up/docs/artifact context, and return to the same shell without visual drift or layout surprises on desktop or Pixel 7-sized mobile.

Acceptance Criteria

• The portal defines canonical --do-* tokens from docs/design-system.md for color, status, typography, spacing/density, radius, border, shadow, focus, layers/z-index, responsive widths, and breakpoint values used by the shell.
• Existing portal tokens remain as compatibility aliases during migration, so existing CSS/JS behavior continues to work while new or touched shell styles consume --do-* tokens.
• Desktop shell uses the shared do-shell/sidebar/page-toolbar primitives in practice: persistent sidebar, collapsed rail, page canvas, toolbar title/context, shell buttons, work bell, and action groups have consistent density, border, focus, hover, and dark-mode behavior.
• Mobile shell follows the Pixel 7 one-state-at-a-time rule from frontend/DESIGN.md and docs/design-system.md: compact top bar, modal workspace drawer, no long stacked global controls before the active work state, and no horizontal overflow.
• Mobile drawer behavior matches the design-system rules: visible scrim when content remains behind it, underlying page does not scroll while open, Escape and close button close the drawer, focus is trapped inside the drawer while open, and focus returns to the opener.
• Page toolbar and shell actions use shared button/icon-button/link primitives with accessible names, visible :focus-visible rings, touch-safe mobile sizing, and no emoji/decorative glyph as the only signifier for an action.
• Operations Home keeps the current daily operations UX but uses shared shell/card/list/status primitives for Today, Overdue, Waiting, Workflows, recurring operations, workflow templates, goal/reference docs, runtime-unavailable banners, and assistant/artifact preview cards.
• Task and workflow side panels use shared layer and panel tokens. On desktop, panels either reserve safe width or intentionally overlay without obscuring primary headings/actions; on Pixel 7-sized mobile, detail panels behave as a single focused state with a clear close/back action.
• Proof, reminder/follow-up, docs-in-context, file/artifact, status badge, progress, and assistant-preview UI areas keep their existing behavior but share the same visual language: text-first status, compact metadata, consistent borders/radii, and no color-only state.
• Dark mode remains supported through canonical dark --do-* values and compatibility aliases; shell, toolbar, drawer, Operations Home, panels, modals/popovers, buttons, and focus states remain readable.
• Reduced-motion support exists for shell/panel/drawer/hover transitions via prefers-reduced-motion: reduce.
• Existing portal behavior continues to work: document library navigation, document open/edit/save/discard, create flow, Operations Home default landing, task panel, workflow/bundle panel, notification panel, modals/toasts, sidebar resize/collapse, and dark-mode toggle.
• Implementation keeps the existing tech/framework. No frontend rewrite, package-level component library extraction, router rewrite, or new framework is introduced.
• Implementation does not modify ../dtc-operations, ../datatasks, or ../podcast-assistant.
• The issue body checkboxes are updated by Software Engineer/Tester as criteria are implemented and verified.

Test Scenarios

Scenario: Desktop shell uses shared tokens without changing behavior

Given: the portal is running locally with docs content and the current frontend bundle
When: the operator opens the portal at desktop viewport 1280x800
Then: Operations Home loads in the same shell, the sidebar and page toolbar are usable, the shell colors/density/focus styles come from --do-* tokens or aliases, and existing navigation/edit/create actions still work.

Scenario: Operations Home remains a daily operations queue

Given: Operations Home has live or stubbed /work/api data for today, overdue, waiting/follow-up, workflows, templates, and unavailable runtime states
When: the operator scans the first screen
Then: Today, Overdue, Waiting, Workflows, recurring operations, workflow templates, goal/reference docs, and assistant/artifact preview areas remain visible as operational context, not decorative cards or a generic docs dashboard.

Scenario: Task proof and follow-up panel stays in context

Given: an Operations Home task has a required link, file, or artifact proof state and may be waiting on a follow-up
When: the operator opens the task panel
Then: the panel opens inside the same portal shell, proof/follow-up/status/docs/file/artifact areas are readable and text-first, missing proof does not look complete, and closing the panel returns to Operations Home.

Scenario: Workflow detail panel uses the shared layer model

Given: an active workflow/bundle card is visible on Operations Home
When: the operator opens the workflow detail panel on desktop and Pixel 7-sized mobile
Then: desktop layout does not hide primary headings/actions, mobile shows one focused workflow state with a clear close/back action, and stage/progress/tasks/links/proof metadata use shared badge/card/list styling.

Scenario: Pixel 7 mobile drawer is modal and accessible

Given: the viewport is approximately 390x844
When: the operator opens the workspace drawer from the mobile top bar
Then: the drawer uses the shared drawer layer, the page behind it is inert and non-scrolling, focus stays in the drawer, Escape/scrim/close button close it, and focus returns to the opener with no horizontal overflow or text overlap.

Scenario: Dark mode and reduced motion remain safe

Given: the operator toggles dark mode and the browser has normal or reduced-motion preferences
When: the operator opens Operations Home, the drawer, a task panel, a workflow panel, a modal/popover, and toolbar controls
Then: contrast and focus remain readable in dark mode, and reduced-motion users do not get unnecessary animated shell/panel transitions.

Out of Scope

• Create first Playwright smoke suite for portal shell and operator surfaces #45 smoke-suite implementation. This issue may add/update focused checks for the changed shell behavior, but the cross-surface Playwright smoke suite remains separate.
• Full work-engine UI migration. Do not migrate work-engine cards, tables, forms, top nav, generated HTML, routes, APIs, task model, or DynamoDB behavior in this issue.
• Podcast Assistant or future assistant UI implementation. Only preserve/normalize current portal assistant/artifact placeholder areas so future assistant surfaces can reuse the shell language.
• Frontend framework migration, component package extraction, router rewrite, state-management rewrite, or rich-editor replacement.
• Redesigning information architecture, task/workflow semantics, proof rules, reminders/follow-up data model, authentication, search, Lambda broker behavior, SAM/CloudFormation, or CI/CD.
• Public DataTalksClub brand/marketing guidelines or user-facing prose polish.
• Editing or importing changes into ../dtc-operations, ../datatasks, or ../podcast-assistant.

Dependencies

• Create shared DataOps design system and component tokens #46 is the source design-system spec and must remain closed/available before implementation starts.
• Use docs/design-system.md, especially Token Namespace, Component Primitives, Portal mapping, Responsive Rules, Accessibility Rules, and Phase 1 of the Migration Plan.
• Use frontend/DESIGN.md for the Notion-like one-page-at-a-time portal model and Pixel 7 mobile rules.
• Use docs/operations-manager-platform-jtbd.md to preserve the operations-manager daily queue, proof, reminder/follow-up, workflow context, and docs-in-context JTBD.
• Use docs/local-development.md for local server and verification command expectations.
• No external credentials, production writes, OAuth, Telegram/email delivery, AWS mutation, or source-repo edits are required.

Required Verification

Engineer should run focused verification while developing:

git diff --check
uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_playwright_local_docs_flow.py

Tester should run the full relevant portal/frontend workflow for this touched surface:

git diff --check
uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app

If the implementation changes any work-engine/** file, Tester must also run:

npm --prefix work-engine test
npm --prefix work-engine run typecheck
npm --prefix work-engine run build
npm --prefix work-engine run test:e2e

Tester must capture screenshots under .tmp/screenshots/ and inspect each for 404s, error pages, broken layout, text overlap, unreadable contrast, missing focus/active state, or horizontal overflow:

• desktop 1280x800: Operations Home with persistent sidebar and page toolbar;
• desktop 1280x800: Operations Home with a task panel open showing proof/follow-up/docs/file or artifact context;
• desktop 1280x800: Operations Home with a workflow/bundle panel open showing stage/progress/tasks/links context;
• Pixel 7-class 390x844: Operations Home in compact shell;
• Pixel 7-class 390x844: workspace drawer open with scrim/focus state visible;
• Pixel 7-class 390x844: task or workflow detail state after opening from Operations Home;
• one desktop or Pixel 7 dark-mode screenshot covering shell plus panel/drawer state.

PM acceptance should review the screenshots from the operator perspective and reject if the result looks like disconnected docs/work widgets, hides daily work behind decorative layout, loses proof/follow-up/docs/artifact context, or treats this as visual polish without improving shared shell consistency.

On-Call after merge/push should confirm the relevant GitHub Actions run for the pushed commit succeeds, or explicitly report an expected no-op if path filters do not trigger. If deployment runs, include the workflow URL and any deploy/cache status in the issue comment.

[alexeygrigorev]

READY FOR TEST

SWE handoff for issue #55.

Changed files:

• frontend/index.html
• frontend/src/app.js
• frontend/src/styles.css
• tests/docs_app/test_playwright_local_docs_flow.py

What changed:

• Added canonical DataOps --do-* shell/status/type/spacing/layer/focus tokens and kept existing portal variables as compatibility aliases.
• Migrated the portal shell, toolbar controls, Operations Home lanes/cards/sections, notification popover, task/workflow side panels, dark mode, and reduced-motion handling toward the shared DataOps primitives.
• Added a real mobile drawer scrim plus drawer ARIA state, focus trap/return, inert background state, Escape close, scrim close, scroll locking, and desktop resize cleanup.
• Kept Operations Home as the daily queue and preserved task/workflow proof, follow-up, docs, file, link, and artifact context.
• Updated focused Playwright coverage and screenshots for mobile drawer/modal behavior, mobile detail state, dark drawer state, and workflow panel async title waiting.

Verification:

• git diff --check -> passed.
• node --check frontend/src/app.js -> passed.
• Exact required focused command: uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_playwright_local_docs_flow.py -> 3 skipped because Playwright is not injected in that uv environment.
• Browser focused command used for coverage: uv run --project lambda-functions --extra search --with pytest --with playwright python -m pytest tests/docs_app/test_playwright_local_docs_flow.py -> 3 passed.
• Exact required full command: uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app -> 86 passed, 3 skipped for the same Playwright-not-injected reason.
• Browser-inclusive full command: uv run --project lambda-functions --extra search --with pytest --with playwright python -m pytest tests/docs_app -> 89 passed.

Screenshots captured under .tmp/screenshots/:

• .tmp/screenshots/docs-operations-home-desktop.png
• .tmp/screenshots/docs-task-panel-missing-proof.png
• .tmp/screenshots/docs-workflow-panel-context.png
• .tmp/screenshots/docs-operations-home-mobile.png
• .tmp/screenshots/docs-workspace-drawer-mobile.png
• .tmp/screenshots/docs-task-panel-mobile.png
• .tmp/screenshots/docs-mobile-drawer-dark.png

Skips / not run:

• Work-engine tests were not run because no work-engine/** files were changed and Apply shared DataOps shell tokens and primitives to the V1 portal shell #55 explicitly excludes work-engine migration.
• No source repos outside dataops were modified.
• No commit, push, PR, merge, deploy, or cache refresh was performed.

[alexeygrigorev]

TEST PASS

Tester verification for issue #55 on /home/alexey/git/dataops/.tmp/worktrees/issue-55 (worktree-issue-55).

Commands run:

• git diff --check -> exit 0, no output.
• node --check frontend/src/app.js -> exit 0, no output.
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app/test_playwright_local_docs_flow.py -> exit 0; collected 3 items; 3 skipped in 0.72s because Playwright is not injected in that uv environment.
• uv run --project lambda-functions --extra search --with pytest --with playwright python -m pytest tests/docs_app/test_playwright_local_docs_flow.py -> exit 0; collected 3 items; 3 passed in 9.17s.
• uv run --project lambda-functions --extra search --with pytest python -m pytest tests/docs_app -> exit 0; collected 89 items; 86 passed, 3 skipped in 2.11s because Playwright coverage is skipped without the Playwright injection.
• uv run --project lambda-functions --extra search --with pytest --with playwright python -m pytest tests/docs_app -> exit 0; collected 89 items; 89 passed in 10.67s.

Acceptance and screenshot assessment:

• Canonical --do-* shell/status/type/spacing/radius/border/shadow/focus/layer/width/breakpoint tokens are present, and existing portal variables remain aliases to those tokens.
• Desktop shell/sidebar/page-toolbar/buttons/focus/dark-mode styling is consistent with the shared primitives in the changed surfaces.
• Pixel 7 mobile behavior shows one state at a time: compact Operations Home, modal workspace drawer, and full-screen focused task detail. Automated checks also assert no horizontal overflow.
• Mobile drawer has visible scrim, body scroll lock, inert background state, dialog ARIA, Escape close, scrim close, close-button close, focus trap, and focus return to the opener covered by code inspection and Playwright assertions.
• Operations Home still reads as a daily operations queue: Today, Overdue, Waiting / Follow-Ups, Active Workflows, recurring operations, workflow templates, goal/reference docs, and incoming/assistant/process quality placeholders remain operational context rather than decorative docs-first content.
• Task and workflow panels preserve proof, follow-up, docs-in-context, file/link/artifact, status, progress, and next-action context. Missing proof states remain text-first and not complete-looking.
• Dark drawer screenshot is readable, and reduced-motion support is present via prefers-reduced-motion: reduce.
• Screenshots inspected under .tmp/screenshots/: docs-operations-home-desktop.png, docs-task-panel-missing-proof.png, docs-workflow-panel-context.png, docs-operations-home-mobile.png, docs-workspace-drawer-mobile.png, docs-task-panel-mobile.png, and docs-mobile-drawer-dark.png. I saw no 404/error page, broken layout, unreadable contrast, horizontal overflow, or text overlap in the requested states.
• Existing stack/process boundaries held: changed files are only frontend/index.html, frontend/src/app.js, frontend/src/styles.css, and tests/docs_app/test_playwright_local_docs_flow.py; no package/framework/process-doc changes were detected; no work-engine files were touched, so work-engine commands were not required.

Source boundary note:

• git -C /home/alexey/git/dtc-operations status --short -> clean.
• git -C /home/alexey/git/datatasks status --short -> M e2e/.auth-state.json. I did not touch this repo during testing; the file mtime is 2026-06-24 23:21:12 +0200, outside this tester run.
• /home/alexey/git/podcast-assistant exists but is not a Git checkout in this environment (git status exits 128). I did not modify it.

No commit, push, PR, merge, deploy, cache refresh, or source-repo edit was performed.

[alexeygrigorev]

PM ACCEPTED

Evidence:

• Operations Home still reads as the daily operations queue: Today, Overdue, Waiting / Follow-Ups, Active Workflows, recurring operations, workflow templates, reference docs, and incoming/assistant/process-quality context remain visible and operational.
• Task/workflow panels keep proof, missing-proof blocking, follow-up/reminder, process-doc, link/file/artifact, status, progress, and next-action context in the same portal shell.
• Design-system adoption is real and scoped: canonical --do-* shell/status/type/spacing/radius/border/shadow/focus/layer/width/breakpoint tokens exist with compatibility aliases for legacy portal vars; no framework rewrite, work-engine UI migration, IA redesign, or source-repo import happened.
• Pixel 7 behavior has adequate evidence: screenshots cover compact home, modal drawer with scrim, focused task detail, and dark drawer; Playwright assertions cover no horizontal overflow, aria-expanded, scrim visibility, Escape close, scrim close, focus trap, and focus return.
• Alignment with .goal-v1.md and docs/operations-manager-platform-jtbd.md is preserved: docs remain in context, while daily work, follow-ups, proof, workflows, recurring work, and artifacts remain the primary experience.
• Verification evidence is adequate: Tester reported git diff --check, node --check, focused Playwright, and full docs_app runs passing when Playwright is injected; non-Playwright uv runs skip only the Playwright-dependent cases. I also reran git diff --check and node --check frontend/src/app.js clean.
• Changed files are limited to frontend/index.html, frontend/src/app.js, frontend/src/styles.css, and tests/docs_app/test_playwright_local_docs_flow.py. dtc-operations is clean; datatasks has a pre-existing e2e/.auth-state.json modification dated 2026-06-24 23:21:12 +0200; podcast-assistant is not a Git checkout here.

No PM blockers.

[alexeygrigorev]

COMMITTED

Commit: 08be0b3

Changed files:

• frontend/index.html
• frontend/src/app.js
• frontend/src/styles.css
• tests/docs_app/test_playwright_local_docs_flow.py

Summary:

• Added shared DataOps portal tokens and compatibility aliases.
• Updated shell/sidebar/mobile drawer interactions and accessibility state.
• Updated focused Playwright coverage for mobile drawer, task panel, dark drawer, and workflow title behavior.