Create shared DataOps design system and component tokens

[alexeygrigorev]

Create shared DataOps design system and component tokens

Status: pending
Tags: docs, design, portal, frontend, P0
Depends on: None
Blocks: #43, #44, first shared portal-shell component implementation issue

Scope

Create the internal DataOps design-system specification that keeps the unified
portal, docs workspace, work-engine flows, and future assistant surfaces in one
visual and interaction language.

This issue produces documentation only. It should not implement components or
change runtime UI behavior. The spec should be based on:

• .goal-v1.md: workflow-first daily operations workspace for the DataTalksClub
  operations manager.
• frontend/DESIGN.md: Notion-like, one-page-at-a-time workspace model.
• docs/local-development.md: current frontend/work-engine runtime split and
  verification commands.
• Current portal UI under frontend/: library, editor, create flow, operations
  home, sidebar/drawer, task/bundle/notification panels, document search, inline
  edit/save state, and dark mode tokens.
• Current work-engine UI under work-engine/src/pages/index.html and
  work-engine/src/public/app.js: sign-in, top navigation, dashboard, task
  tables, bundle cards, filters, recurring work, notifications, template editor,
  forms, empty states, badges, and proof/follow-up controls.

The output should define a practical V1 component and token system that can be
implemented incrementally with the current plain HTML/CSS/JavaScript stack. It
must preserve the work already done to make the surfaces feel close, while
identifying where the work-engine still uses legacy DataTasks visual patterns
that should be normalized into the shared DataOps system.

The spec should cover:

• Design principles for the operations manager experience: calm, focused,
  workflow-first, document context available but not dominant, and low-chrome
  daily execution.
• Tokens for color, typography, spacing, radii, borders, focus states, shadows,
  status colors, density, z-index/layers, and responsive breakpoints.
• Component inventory and usage rules for: workspace shell, sidebar/drawer,
  top bars, page headers, command/search, filters, segmented controls, tabs,
  buttons, icon buttons, links, forms, field groups, date inputs, tables, lists,
  task rows, workflow/bundle cards, status badges, reminder/follow-up chips,
  empty states, banners/toasts, modals/dialogs, panels/drawers, document cards,
  process-doc context blocks, proof/evidence controls, file/artifact rows, and
  assistant job/output panels.
• Mapping from existing portal/work-engine UI classes or surfaces to the shared
  component inventory.
• Responsive behavior for desktop, tablet, and Pixel 7-sized mobile layouts,
  including graceful degradation when the UI cannot show navigation, details,
  and editing at the same time.
• Accessibility rules for focus visibility, keyboard access, reduced motion,
  labels, contrast, status text, and non-color-only state.
• Implementation sequencing: what can be standardized first with CSS tokens and
  existing DOM, what needs HTML cleanup, what should wait for a future frontend
  framework decision, and what should not be changed in V1.
• A migration plan that keeps V1 usable while components are replaced
  incrementally.
• At least one concrete follow-up implementation issue to apply the first shared
  components to the V1 portal shell.

Designer audit is required before Software Engineer implementation. The Designer
should inspect current docs portal and work-engine screens, using screenshots
where possible, and comment with component inventory findings, visual drift, and
priority recommendations. The Software Engineer should use that audit as input
when writing the spec.

Acceptance Criteria

• A durable internal design-system spec exists under docs/ or _docs/
  with stable title, purpose, and links from the relevant docs index if
  appropriate.
• The spec explicitly references the V1 goal and frames the system around
  the operations manager's daily workflow, not a generic documentation site
  or admin dashboard.
• The spec defines V1 tokens for color, typography, spacing, radii, borders,
  focus states, shadows, status colors, density, layers, and responsive
  breakpoints.
• The spec defines component primitives and usage rules for the portal
  shell, navigation, search/filtering, document surfaces, task/workflow
  execution, proof/evidence capture, reminders/follow-ups, modals/panels,
  empty states, and assistant job/output surfaces.
• Existing frontend/ docs portal surfaces are audited and mapped to the
  component inventory, including library, editor, create flow, operations
  home, sidebar/drawer, document rows/cards, task/bundle panels, and
  notification panel.
• Existing work-engine/ UI surfaces are audited and mapped to the
  component inventory, including sign-in, top navigation, dashboard, task
  table, bundle cards, filters/forms, recurring work, notifications, and
  template editor.
• The spec names concrete visual drift between the current docs portal and
  legacy DataTasks/work-engine UI and gives a prioritized migration order.
• Responsive rules cover desktop, tablet, and Pixel 7-sized mobile behavior
  for the main workspace shell, document editing, task lists, workflow
  detail, assistant panels, and modals/drawers.
• Accessibility rules cover keyboard navigation, focus states, contrast,
  labels, status messaging, and state that is not communicated only by
  color.
• The spec identifies which pieces can be implemented with current
  HTML/CSS/JavaScript, which require DOM cleanup, and which should wait for
  a future frontend framework decision.
• The spec includes a phased migration plan that keeps V1 usable throughout
  the transition.
• At least one concrete follow-up GitHub issue is linked for applying the
  first shared components to the V1 portal shell.
• The spec explicitly says Podcast Assistant and future assistant UI must
  reuse the same DataOps components instead of introducing a second visual
  language.
• Designer audit findings are linked from the issue before Software
  Engineer implementation starts.

Test Scenarios

Scenario: Designer audits existing UI before implementation

Given: current frontend/ and work-engine/ UI surfaces are available locally
When: the Designer reviews the docs portal and work-engine screens
Then: the issue has a screenshot-backed or source-backed audit comment that
identifies current component patterns, visual drift, responsive risks, and
priority recommendations for the design-system spec.

Scenario: Engineer writes the design-system spec

Given: the Designer audit exists on this issue
When: the Software Engineer creates the design-system spec
Then: the document defines tokens, components, usage rules, surface mappings,
responsive behavior, accessibility rules, and migration sequence for the current
DataOps frontend/work-engine stack.

Scenario: Spec supports a first implementation issue

Given: the design-system spec exists
When: the next implementation issue applies shared shell/components to the V1
portal
Then: that issue can point to concrete token names, component names, responsive
rules, and migration boundaries instead of inventing a separate visual system.

Scenario: Assistant UI stays unified

Given: #44 or later assistant UI work is groomed
When: the PM or Designer references the design-system spec
Then: assistant job panels, outputs, artifacts, and review actions use the same
component vocabulary as tasks, workflows, documents, and reminders.

Out of Scope

• Implementing CSS, JavaScript, or runtime component changes.
• Rebuilding the portal shell, work-engine navigation, or Podcast Assistant UI.
• Choosing or migrating to a new frontend framework.
• Replacing the current plain HTML/CSS/JavaScript stack.
• Creating a public brand/design guideline for DataTalksClub marketing.
• User-facing prose polish or stylint-style review; this is internal product
  and design-system documentation.
• Redesigning the V1 information architecture beyond component and layout rules
  needed to keep Create portal UI information architecture #43/Implement Podcast Assistant portal UI in workflow context #44 aligned.

Dependencies

• No code dependency blocks grooming or starting this issue. The current
  imported frontend/ and work-engine/ surfaces are sufficient source
  material.
• Designer audit is required before Software Engineer implementation because
  this issue is a design-system specification and must preserve the existing
  visual work rather than relying only on source-code inspection.
• Create portal UI information architecture #43 and Implement Podcast Assistant portal UI in workflow context #44 should consume this design-system output when they are groomed or
  implemented; they should not define independent component languages.
• If the follow-up portal-shell implementation issue does not already exist,
  the Software Engineer or PM should file/link it as part of satisfying the
  acceptance criteria.

[alexeygrigorev]

PM GROOMING DONE

Issue: #46

Summary:

• Rewrote Create shared DataOps design system and component tokens #46 into the standard DataOps issue format: Status, Tags, Depends on, Blocks, Scope, Acceptance Criteria, Test Scenarios, Out of Scope, and Dependencies.
• Kept scope as internal product/design-system documentation only. No runtime UI/code implementation is included.
• Added docs and design labels; kept portal, frontend, and P0.
• Set Depends on: None because the current imported frontend/ and work-engine/ UI are enough source material.
• Set Blocks: #43, #44, first shared portal-shell component implementation issue so later IA, assistant UI, and shell work consume the same component language.
• Required a Designer audit before Software Engineer implementation, because the spec must preserve the existing visual work across the docs portal and work-engine instead of relying only on source-code inspection.
• Explicitly excluded user-facing prose/stylint-style review because this is internal product/design-system documentation.

Recommended next owner:

• Designer audit first, then Software Engineer writes the spec using the audit plus .goal-v1.md, frontend/DESIGN.md, docs/local-development.md, frontend/, and work-engine/ context.

[alexeygrigorev]

DESIGN FINDINGS

Designer audit complete for #46. I inspected the groomed issue, AGENTS.md, _docs/PROCESS.md, docs/local-development.md, frontend/DESIGN.md, frontend/index.html, frontend/src/app.js, frontend/src/styles.css, work-engine/src/pages/index.html, work-engine/src/public/app.js, and work-engine/src/public/api.js.

Screenshots captured under .tmp/screenshots/:

• issue-46-portal-operations-home-desktop.png
• issue-46-portal-task-panel-desktop.png
• issue-46-portal-create-flow-desktop.png
• issue-46-portal-operations-home-pixel7.png
• issue-46-portal-mobile-drawer-pixel7.png
• issue-46-portal-create-pixel7.png
• issue-46-work-engine-signin-desktop.png
• issue-46-work-engine-dashboard-desktop.png
• issue-46-work-engine-dashboard-pixel7.png
• issue-46-work-engine-tasks-desktop.png
• issue-46-work-engine-tasks-pixel7.png
• issue-46-work-engine-templates-desktop.png

Capture notes: the portal screenshots use the real frontend/ static bundle with mocked /docs, /work/api/*, /git/status, and /search responses because the local frontend proxy could not start in the host Python env (httpx missing). The work-engine screenshots use the real local dev server on port 3000 with seeded local auth (alexey@datatalks.club / 111). This is screenshot-backed for layout/CSS behavior and source-backed for route/data inventory.

Current component patterns observed:

• Portal/docs frontend already has the stronger DataOps direction: neutral/teal CSS variables, dark-mode variables, persistent workspace sidebar, mobile drawer, page toolbar, quiet/primary/icon buttons, custom selects, tree navigation, document rows, create form, Operations home stats/lanes, task and bundle side panels, notification bell panel, modals, toasts, quick nav, pending changes, and git/lint review surfaces.
• Portal interaction model matches frontend/DESIGN.md: one main state at a time, low-chrome document workspace, sidebar-first library, explicit create/edit/save flows.
• Work-engine has a newer polish layer in inline CSS with variables, skip link, focus-visible styles, responsive nav, empty states, dashboard cards, segmented bundle sort, template cards, badges, notification dropdown, and mobile table-to-card behavior.
• Work-engine still carries legacy DataTasks patterns: standalone DataTasks brand, top admin nav, blue primary system, card-heavy dashboard/form sections, inline styles in generated JS, duplicate older CSS rules before the polish layer, separate badge/button/card naming, and a broader admin-table mental model.

Visual drift to normalize in the design-system spec:

• Shell/navigation: portal uses DataOps sidebar + page toolbar; work-engine uses DataTasks sticky top nav. V1 should name the DataOps workspace shell as canonical and treat work-engine top nav as legacy/temporary.
• Tokens: portal uses --bg, --sidebar, --surface, --line, --accent; work-engine uses --bg, --surface, --border, --primary, plus older hard-coded #3498db, #2c3e50, green, warning, and purple badge values. Define one token namespace and a mapping table from both surfaces.
• Cards and density: portal is flatter, lower chrome, and document/workflow-first; work-engine uses larger rounded cards, shadows, blue buttons, and dashboard/admin spacing. Standardize card radius, shadow, empty state, and form-section behavior.
• Badges/chips: portal status/task chips and work-engine badge families (badge-stage, badge-status, progress-badge, badge-assignee, etc.) solve the same problem differently. Spec should define shared status, stage, assignee, reminder, proof-required, and progress badge variants.
• Panels/notifications: portal has right-side task/workflow and work-bell panels; work-engine has notification dropdown/page and no shared drawer vocabulary. Standardize panel/drawer/toast/dialog layers and z-index tokens.

Responsive risks:

• Portal desktop side panels overlay the Operations home and can visually cut off wide headings/lanes. The spec should require a drawer mode that either reserves space at wide widths or intentionally overlays with a scrim/clear clipping rules.
• Portal Pixel 7 create flow works but is visually oversized: the New page heading, disabled Save toolbar action, and scaffold radio layout consume too much first-screen space. Define compact mobile create/form density.
• Portal mobile drawer covers the page but the underlying content remains visibly active behind it. Treat the drawer as a modal layer with focus/scroll behavior rules.
• Work-engine Pixel 7 stacks controls correctly, but the task route puts date, filters, and create form before the task list; the spec should define mobile priority order for repeated daily execution.
• Work-engine desktop leaves large unused whitespace on dashboard/task empty states; define max-widths/density for operational pages separately from document pages.

Accessibility risks:

• Keep work-engine's skip link and :focus-visible approach; bring the portal focus rules into the same focus-visible/tokenized system.
• Require labels/ARIA names for icon-only controls and avoid relying on emoji/unicode glyphs as the only signifier.
• Drawers, modals, quick nav, and notification panels need explicit focus-trap/return-focus/escape behavior in the spec.
• Status must always include text, not color only. Current surfaces mostly include text, but badge variants should encode this as a rule.
• Add reduced-motion guidance; work-engine currently uses hover transforms and both apps use transitions.

Priority recommendations for the Software Engineer writing the spec:

1. Make the portal DataOps shell/tokens the V1 baseline, not the legacy DataTasks top-nav/dashboard look.
2. Define canonical tokens first: color roles, type scale, spacing, radius, border, shadow, focus, status colors, density, layers/z-index, and breakpoints, with a mapping from current portal/work-engine variables and hard-coded colors.
3. Specify shared primitives that can be implemented with current HTML/CSS/JS: button variants, icon buttons, fields/selects/date inputs, segmented controls, tabs, badges/chips, cards, empty states, banners/toasts, modals, drawers, tables/lists, and file rows.
4. Specify work-execution components next: task row, workflow/bundle card, follow-up/reminder chip, proof/evidence control, task detail panel, workflow detail panel, notification bell/dropdown, and assistant job/output panel. These should reuse the same vocabulary across portal, work-engine, and future assistant UI.
5. Sequence implementation as CSS-token normalization first, then DOM/class cleanup for work-engine generated HTML, then shared shell application. Do not choose a frontend framework or rewrite runtime UI in V1.
6. First follow-up implementation issue should apply the shared DataOps shell/tokens to the portal shell and define compatibility aliases for work-engine, then a second follow-up can migrate work-engine buttons/badges/cards/forms to those aliases.

Designer recommendation: proceed to Software Engineer spec writing, but the spec should explicitly call out the legacy work-engine/DataTasks visual language as a migration target and protect the calmer portal direction as the shared DataOps system.

[alexeygrigorev]

SWE HANDOFF

Changed files:

• docs/design-system.md - added the internal DataOps V1 design-system spec covering V1 workflow framing, tokens, component primitives, current portal/work-engine surface mapping, visual drift, responsive rules, accessibility, implementation sequencing, migration plan, and assistant UI reuse requirements.
• docs/README.md - linked the new design-system spec from the repo-meta docs index.

Follow-up issue:

• Apply shared DataOps shell tokens to the V1 portal shell #55: Apply shared DataOps shell tokens to the V1 portal shell #55

Acceptance criteria status:

• Updated all Create shared DataOps design system and component tokens #46 acceptance checkboxes to checked.
• Designer audit was already linked at Create shared DataOps design system and component tokens #46 (comment) and is referenced from the spec.

Verification:

• git diff --check passed.
• git diff --no-index --check /dev/null docs/design-system.md produced no whitespace warnings; exit code is the expected no-index diff code for a new file.
• Cheap reference/link inspection passed for local source/doc references and GitHub issue links in docs/design-system.md.

Skipped checks:

• Runtime UI, CSS, JS, Lambda, and work-engine tests were skipped because this is documentation/spec work only and no runtime files were changed.
• Stylint/user-facing prose tooling was not run per issue scope; this is internal product/design documentation.

No commit, push, close, or PR created.

[alexeygrigorev]

TEST PASS

Tester verification for #46.

Evidence reviewed:

• Read AGENTS.md and _docs/PROCESS.md.
• Read groomed issue body with gh issue view 46 --repo DataTalksClub/dataops --json number,title,body,labels,state,url.
• Read Designer audit: Create shared DataOps design system and component tokens #46 (comment).
• Read SWE handoff: Create shared DataOps design system and component tokens #46 (comment).
• Inspected uncommitted docs changes: docs/README.md diff and full docs/design-system.md contents.
• Verified follow-up issue Apply shared DataOps shell tokens to the V1 portal shell #55 exists and is concrete: Apply shared DataOps shell tokens to the V1 portal shell #55.

Commands run:

• git status --short -> only M docs/README.md and ?? docs/design-system.md.
• git ls-files --others --exclude-standard -> only docs/design-system.md.
• git diff --check; echo "exit:$?" -> exit:0.
• git diff --no-index --check /dev/null docs/design-system.md; echo "exit:$?" -> exit:1 with no whitespace warnings; exit 1 is expected because this is a new untracked file compared to /dev/null.
• Local reference checks with test -f passed for .goal-v1.md, frontend/DESIGN.md, docs/local-development.md, docs/operations-manager-platform-jtbd.md, docs/v1-runtime-architecture.md, work-engine/src/pages/index.html, and work-engine/src/public/app.js.
• gh issue view 55 --repo DataTalksClub/dataops --json number,title,state,url,body -> issue Apply shared DataOps shell tokens to the V1 portal shell #55 exists, open, and targets portal shell token implementation.

Per-AC results:

• PASS: Durable internal spec exists at docs/design-system.md with stable title/purpose/frontmatter, and docs/README.md links it from the docs index.
• PASS: V1 workflow framing is explicit via .goal-v1.md, operations manager daily work, proof, reminders, follow-ups, workflow state, and docs-in-context. It rejects generic docs/admin framing.
• PASS: Tokens are defined for color, typography, spacing/density, radii, borders, focus, shadows, status colors, layers/z-index, and responsive breakpoints.
• PASS: Component primitives and usage rules cover shell/navigation/search/filtering/docs/task/workflow/proof/reminders/modals/panels/empty states/assistant job and output surfaces.
• PASS: Portal surfaces are mapped, including library, editor, create flow, Operations Home, sidebar/drawer, rows/cards, task/bundle panels, notifications, modals, toasts, and dark mode.
• PASS: Work-engine surfaces are mapped, including sign-in, top nav, dashboard, tasks, bundles, filters/forms, recurring work, notifications, templates, proof, and follow-up controls.
• PASS: Visual drift is concrete and prioritized: DataOps sidebar shell vs legacy DataTasks top nav, teal vs blue primary, card density, badges/chips, panels, generated inline styles, and migration order.
• PASS: Responsive rules cover desktop, tablet, and Pixel 7-sized mobile for shell, document editing, task lists, workflow detail, assistant panels, modals, and drawers.
• PASS: Accessibility rules cover keyboard access, focus-visible, labels, contrast, text status, reduced motion, dialog/drawer focus behavior, table labels, and errors.
• PASS: Implementation boundaries are explicit: current HTML/CSS/JavaScript work, DOM/generated HTML cleanup, future framework decisions, and V1 no-change boundaries.
• PASS: Phased migration plan keeps V1 usable through spec, portal shell, work-engine aliases, generated HTML cleanup, unified execution, assistant surfaces, and possible future framework phase.
• PASS: Follow-up Apply shared DataOps shell tokens to the V1 portal shell #55 is linked and specific enough to apply the first shared portal-shell components/tokens.
• PASS: Podcast Assistant and future assistant UI are explicitly required to reuse DataOps components and avoid a second visual language.
• PASS: Designer audit findings are linked from the issue before SWE handoff and linked from the spec. The spec uses the audit findings directly, including Pixel 7 risks, drawer modality, legacy DataTasks nav/colors, badge drift, focus-visible/reduced-motion guidance, and assistant reuse.

Test scenarios:

• PASS: Designer audit exists, is screenshot-backed/source-backed, and names component patterns, visual drift, responsive risks, and priorities.
• PASS: Engineer spec defines tokens, components, usage rules, mappings, responsive behavior, accessibility, and migration sequence.
• PASS: First implementation issue Apply shared DataOps shell tokens to the V1 portal shell #55 can point to concrete token/component names, responsive rules, and migration boundaries.
• PASS: Assistant UI reuse is covered for Implement Podcast Assistant portal UI in workflow context #44/later assistant work.

Runtime/UI scope:

• PASS: No runtime UI/CSS/JS/HTML/Lambda/work-engine source changes were made in the Create shared DataOps design system and component tokens #46 diff. Screenshots are not required for this docs-only spec beyond the Designer audit artifacts.
• Stylint/user-facing prose tooling was intentionally not run, per issue scope.

Verdict: TEST PASS

[alexeygrigorev]

ACCEPTED

Final PM acceptance from the product/design perspective passes.

Reasons:

• docs/design-system.md is a practical V1 DataOps component/token spec, not a generic design guideline. It is grounded in the operations manager daily workflow: today/overdue work, follow-ups, proof, workflow state, and docs-in-context.
• The spec uses the current portal direction as the V1 baseline while clearly identifying legacy DataTasks/work-engine patterns as migration targets: top nav, blue primary color, card-heavy density, badge drift, generated inline styles, and duplicated class language.
• It defines implementable --do-* tokens and component primitives for the existing plain HTML/CSS/JavaScript stack, with compatibility mapping from current frontend/ and work-engine/ surfaces.
• It covers the required operational surfaces: shell/navigation, search/filtering, document/editor/create flow, task rows/detail, workflow/bundle cards/detail, proof/evidence, reminders/follow-ups, notifications, modals/drawers/panels, empty states, and assistant job/output panels.
• Responsive and accessibility constraints are concrete enough for follow-up implementation: desktop reserved/overlay panel behavior, tablet collapse, Pixel 7 one-state-at-a-time rules, modal drawer behavior, focus-visible, keyboard access, labels, text status, contrast, reduced motion, and dialog focus management.
• The migration sequence is safe for V1: tokens and portal shell first, work-engine aliases next, generated HTML cleanup after that, then unified execution and assistant surfaces. It also explicitly defers framework/package decisions.
• docs/README.md links the new spec, and follow-up Apply shared DataOps shell tokens to the V1 portal shell #55 gives the first implementation slice a concrete shell/token target.

No runtime UI/code changes were made, which matches the issue scope. This is accepted for commit/ship by the next pipeline owner.

[alexeygrigorev]

On-call report for the main push containing #46 and #47.

Commits checked:

• 08de397 Define DataOps design system (Closes Create shared DataOps design system and component tokens #46)
• a1f99de Decide DataOps knowledge repository boundary (Closes Decide separate repository strategy for operations documents #47)

Evidence:

• gh run list --repo DataTalksClub/dataops --limit 20 shows the latest workflow run is Deploy DataOps V1 Lambda for 37bcafb at 2026-06-27T21:24:08Z: https://github.com/DataTalksClub/dataops/actions/runs/28302211699. No runs are listed for a1f99de or 08de397.
• Actions API head-SHA queries for both pushed commits returned no workflow runs.
• Commit check-runs API returned total_count=0 for both pushed commits.
• Changed files were docs-only: Create shared DataOps design system and component tokens #46 changed docs/README.md and docs/design-system.md; Decide separate repository strategy for operations documents #47 changed docs/README.md and docs/decisions/dataops-knowledge-repository.md.
• Current push workflow path filters are for assistants/**, content/**, frontend/**, lambda-functions/**, scripts/**, tests/docs_app/**, work-engine/**, package/lock manifests, and workflow files. They do not include docs/**.

Classification: expected skip/no-op. No CI/deployment infrastructure failure, commit-related code/test failure, content/search validation failure, external account/secret issue, or flake observed.

Current status: #46 and #47 are closed by the pushed commits; no relevant workflows were expected or triggered for these docs-only changes.

Next step: none for on-call. Related report: #47.