UI design system unification — one stylesheet, canonical primitives, nav fix (#284 )

* docs(plan): design-system unification plan (post-review revisions)

Plan covers consolidating two CSS files into one, introducing
canonical primitives (.btn family, .search-input, .filter-bar,
.page-header, .data-table, .empty-state, .toast, .stat-card,
.tab-strip), unifying the top-nav Admin trigger with sibling
links, and migrating 41 templates that today carry inline
<style> blocks.

Post-review revisions: nav fix moved to first commit (user
complaint lands first); sticky-header and dark-mode skeleton
tasks dropped (defer to follow-up PRs); contract test class
detection tokenizes class="..." attributes properly; baseline
screenshot loop added to Task 0; vendor-token grep widened.

* fix(nav): unify Admin trigger with sibling nav links

The top-nav Admin entry is a <button class="app-nav-link
app-nav-menu-trigger">, siblings are <a class="app-nav-link">.
.app-nav-menu-trigger used to override .app-nav-link with
"color: inherit; font: inherit", resetting font-size from 13px
back to body default and color from --text-secondary to body
color. Active state diverged too: .is-active on links used
--primary blue, [aria-expanded=true] on the button used
--border-light grey.

Fix: expand .app-nav-link so it covers <button>-element resets
(font-family: inherit, border: 0, background: transparent,
cursor: pointer, display: inline-flex for chevron alignment).
Add [aria-expanded="true"] as another active-state selector
so the dropdown's open state highlights identically to .is-active
on links. Delete the now-redundant .app-nav-menu-trigger rules
that stripped button chrome.

Extract the inline <script> from _app_header.html into a new
app/web/static/app.js (loaded by base.html only — base_login.html
has no nav). Sets up window.appUI.wireDropdown for both the user
menu and the Admin dropdown via DOMContentLoaded.

* style(css): consolidate style.css into style-custom.css + add cache-bust

One stylesheet for the whole web UI:
- style.css (1086 lines, legacy Google-inspired tokens + components)
  absorbed into style-custom.css under a labeled block, placed after
  the modern :root + body so style-custom's component rules continue
  to override the legacy ones (preserves the original cascade order
  that came from loading style.css first).
- style.css deleted; <link> dropped from base.html + base_login.html.
- static_url() now appends ?v=<mtime> to /static/<path>. Cheap
  per-request os.stat — auto-invalidates browser + proxy caches on
  redeploy without operator intervention. Mtime survives across
  uvicorn restarts as long as the file content is unchanged.

Legacy classes (.btn, .card, .login-*, .badge, .code-block, .flash,
.form-group, .username-box, .btn-copy, .auth-tabs, .divider, etc.)
still render — they live in style-custom.css now. Login pages,
error page, password setup, and the dashboard's Claude Code Setup
card all kept working in browser smoke.

* test(design): contract test for design-system invariants

7 structural invariants enforced from this commit onwards:
- style.css must stay deleted
- no template links style.css via static_url
- exactly one bare :root block in style-custom.css
- canonical primitives declared (.btn, .btn-primary, .search-input,
  .filter-bar, .page-header, .data-table, .empty-state, .toast, …)
- no deprecated class names in templates (.users-table, .gp-table,
  .marketplaces-table, .audit-table, .users-search, .marketplaces-search,
  .modal-btn, .btn-primary-v2, …)
- app.js loaded by base.html, NOT by base_login.html
- 3 helper-level unit tests for the class-attribute tokenizer
  (multi-line attrs, Jinja-conditional fragments, false-positive prose)

Two of the assertions intentionally start FAILING after this commit
(missing primitives + legacy class refs in 7 admin templates) and
will turn green as Tasks 4–7 add primitives and Tasks 8–15 migrate
the templates.

* feat(css): canonical button family + legacy token aliases

Adds at top of :root: legacy token aliases (--bg, --card-bg, --text,
--text-light, --secondary, --radius) pointing at modern equivalents.
Absorbed style.css rules referenced these names; without aliases
they fell back to 'unset'. Aliases live until Task 16 alongside
their absorbed rules.

Appends canonical .btn variants at end of file (last cascade):
  .btn-primary + .btn-primary-v2 + .modal-btn.primary (alias group)
  .btn-secondary + .btn-secondary-v2 + .modal-btn:not(.primary):not(.danger)
  .btn-ghost + .btn-ghost-v2
  .btn-danger + .modal-btn.danger
  .btn-lg
  .btn:disabled + .btn:focus-visible (focus ring via --focus-ring)

Existing absorbed .btn, .btn-primary, .btn-secondary, .btn-sm rules
remain — the canonical block adds the missing variants + selector-list
aliases so .modal-btn and v2 markup keep rendering until migration
tasks swap them out.

Contract test: .btn-danger now declared (one less missing primitive).
Browser smoke: /admin/tokens hero + filter pills + empty state render
correctly with the absorbed style.css rules now backed by real tokens.

* feat(css): form-control primitives — .search-input + .filter-bar + .filter-pill + .form-input

Canonical filter bar shape: 36px-height inputs (matches button height
for vertical rhythm), 28px pills with .is-active state, consistent
focus ring via --focus-ring token.

Selector-list aliases for legacy per-page classes:
- .users-search / .marketplaces-search / .kb-search → .search-input
- .filters-card → .filter-bar
- .pill[aria-pressed="true"] also matches the .filter-pill active state

.form-input added as a sibling of .search-input for forms — same
baseline height + radius + focus treatment, with textarea.form-input
auto-sizing to min 96px and using the mono font (matches CSV/SQL
pasted-snippet patterns on /admin/agent-prompt + /admin/workspace-prompt).

Contract test: .search-input + .filter-bar + .filter-pill now declared.

* feat(css): .page-header primitive + variants + .tab-strip

Canonical page-header pattern with title (22px) + optional subtitle +
optional eyebrow + right-aligned actions slot. Two modifiers:
- .page-header--hero: gradient background (primary→primary-dark),
  28px white title, semi-transparent subtitle/eyebrow. For
  /marketplace, /store, /profile-style pages that already use this
  layout via per-page inline <style>. Migration tasks delete the
  duplicated rules.
- .page-header--compact: 18px title for dense admin index pages.

.tab-strip + .tab-strip__item — the secondary tab row pattern used by
/marketplace?tab=flea and similar. .is-active / [aria-selected=true]
both flip the active treatment (primary color + bottom border).

Contract test: .page-header / __title / __subtitle / __actions all
now declared (4 fewer missing primitives).

* feat(css+js): .data-table + .empty-state + .toast + .stat-card primitives

Last primitive batch. All 8 canonical-primitives invariants in
test_design_system_contract.py now green; only the template-migration
test fails (expected — Tasks 8–15).

.data-table (+ --compact modifier): selector-list aliases for legacy
per-page table classes (.users-table, .gp-table, .marketplaces-table,
.audit-table) so existing markup keeps rendering until migration.
Compact modifier shrinks padding + font for dense lists (audit log).

.empty-state with __icon / __title / __description / __actions —
replaces the ad-hoc 'no results' rendering scattered across pages
(corporate_memory, admin_users, admin_marketplaces, etc.).

.toast / .toast-container — paired with window.appToast({kind, msg,
timeout}) appended to app.js. Bottom-right stacked, click-to-dismiss,
auto-dismiss after 4s by default. Kind 'success' / 'warning' / 'error'
/ 'info' shows a 3px colored left border.

.stat-card (+ --accent variant) + .stat-row grid — for the dashboard
metric tile row.

* style(templates): migrate 8 templates off deprecated class names

Mechanical class-attribute rewrite via tokenizer (preserves Jinja
conditionals + multi-line attrs):

  modal-btn primary    -> btn btn-primary
  modal-btn danger     -> btn btn-danger
  modal-btn            -> btn btn-secondary
  users-table          -> data-table
  gp-table             -> data-table
  marketplaces-table   -> data-table
  audit-table          -> data-table
  users-search         -> search-input
  marketplaces-search  -> search-input

8 templates touched: admin_groups, admin_marketplaces, admin_tokens,
admin_users, admin_welcome, admin_workspace_prompt, my_tokens,
corporate_memory_admin. 43 lines updated total.

Inline <style> blocks in these templates still define rules for the
old class names — those rules no longer match anything and become
dead code, removed in Task 16's alias cleanup along with the
selector-list aliases in style-custom.css.

Contract test (tests/test_design_system_contract.py) now fully green:
9/9 invariants enforced from this commit onward.

* feat(css): extend .data-table selector list to 13 more bespoke -table classes

Visual unification of remaining tables across the codebase without
per-template edits. The .data-table baseline rules (uppercase header
tracking, 12px padding, hover state, border-radius) now apply to:

  .ad-table / .ea-table / .md-table / .members-table /
  .obs-table / .overview-stats-table / .registry-table /
  .sample-table / .sched-table / .sess-table / .sub-table /
  .subs-table / .ud-table

These class names live in 12 templates (activity_center, admin_access,
admin_group_detail, admin_scheduler_runs, admin_sessions,
admin_store_submissions, admin_tables, admin_usage, admin_user_detail,
catalog, me_debug, profile_sessions) that have their own per-page
<style> blocks. Per-page rules with higher specificity still win for
their custom needs (column widths, etc.) — this commit only sets a
shared baseline so every table renders with the same chrome.

Contract test stays green: 9/9 invariants enforced.

* style(css): remove now-unused legacy class aliases

Phase A renamed 8 templates off these names; no markup references
them any more, so the selector-list memberships are dead weight.
Removed from style-custom.css:

  .btn-primary-v2 / .btn-secondary-v2 / .btn-ghost-v2
  .modal-btn / .modal-btn.primary / .modal-btn.danger /
  .modal-btn:not(.primary):not(.danger)
  .users-search / .marketplaces-search / .kb-search
  .users-table / .gp-table / .marketplaces-table / .audit-table
  .filters-card

37 lines smaller. Contract test catches any reintroduction.

KEPT aliases (still in untouched template markup):
- .pill (marketplace_plugin_detail.html, marketplace.html — these
  pages weren't part of Phase A's deprecated-class sweep; their
  own .pill CSS rules still apply)
- All .data-table family extensions (.ad-table, .ea-table, .md-table,
  .members-table, .obs-table, .overview-stats-table, .registry-table,
  .sample-table, .sched-table, .sess-table, .sub-table, .subs-table,
  .ud-table) — these still render data tables in 12 templates;
  selector-list aliasing keeps them visually unified with .data-table
  baseline.
- Legacy token aliases (--bg / --text / --text-light / --secondary /
  --card-bg / --radius) — still resolve absorbed style.css rules.

Templates' inline <style> blocks still contain dead rules for the
renamed classes (.users-search, .modal-btn, etc.); harmless but
bloat. Optional follow-up: a separate sweep can drop those.

* docs(changelog): design-system unification under [Unreleased]

* feat(css): unify page-shell width — .container baseline 1280px + modifiers

Inventory found 30+ unique max-width values across templates (280px
login → 1600px admin/tables). The legacy .container default was 800px,
which made every admin page set its own wider inline override —
30+ ad-hoc widths drifted as a result.

Canonical: .container max-width = var(--width-app) (1280px). Pages
that need a different shape opt in via modifiers:

  .container--narrow → var(--width-narrow)  (800px) — long-form text,
                                                     setup wizards
  .container--wide   → var(--width-wide)    (1400px) — admin lists,
                                                     marketplace grids
  .container--full   → max-width: none — hero / landing

Pages that already set a NARROWER inline max-width (setup, login flows
inside .login-card, etc.) still render at their narrower size — the
inline override beats the new canonical 1280px. The visible change
hits the ~20 admin pages currently rendering at 800px via the legacy
default, which jump to 1280px and pick up consistent breathing room.

Spacing also normalized: padding 24px 20px → var(--space-6) var(--space-5).

* fix(home+catalog): gut dashboard sections + remove confusing toggle + fix table count

Dashboard /home cleanup:
- Remove 'Your Data' card — Data Packages is already a top-nav entry,
  so duplicating data sources on the landing page just adds noise.
- Remove 'Account' card — group memberships + scripts + last sync
  belong on /profile, not on the welcome screen.
- Remove entire right-column (Corporate Memory + Activity Center
  widgets) — both surfaces have dedicated admin pages reachable from
  the Admin dropdown.
- Keep stats row (Tables/Columns/Rows/Data Size/Unstructured),
  env-setup-CTA, and Notifications card.

/catalog cleanup:
- Strip the 'Always included' badge + the locked toggle-switch from
  Core Business Data and Business Metrics cards. The toggle was
  always 'checked disabled' — it visually looked like a switch but
  could not be toggled, which was confusing. The 'Always included'
  copy itself was redundant once the toggle was gone. Agnes Internal
  already rendered without these, so the three cards are now visually
  consistent.

Catalog data_stats fix:
- 'total_tables' was len(sync_state) — counted only tables that had
  ever synced, so a 30-row table_registry with 0 ever synced rendered
  as '0 tables'. Switched to len(tables) — the registered
  business-data table list — so the count reflects what's actually
  available, not what's been touched.

* fix(home): real stat numbers + drop unstructured tile + cleanup dead CSS

Dashboard stats were hardcoded zeros (columns: 0, size_display:
'0 MB', unstructured_display: '0 MB') and the table counter pulled
from sync_state (synced) instead of table_registry (registered).
On a fresh deployment with 30 registered tables and 0 ever synced,
the page rendered '0 / 0 / 0 / 0 MB / 0 MB' — useless.

Now:
- Tables: COUNT(*) FROM table_registry WHERE source_type != 'internal'.
  Matches the /catalog Core Business Data counter.
- Columns: SUM(sync_state.columns). Zero only when nothing's synced yet.
- Rows: unchanged (SUM(sync_state.rows), already correct).
- Data Size: SUM(sync_state.file_size_bytes), human-formatted via
  inline _fmt_bytes helper (KB/MB/GB).
- Unstructured: tile dropped — was always '0 MB' and had no source.
- last_updated: now derived from sync_state max(last_sync), wasn't set
  before so the 'Synced …' tag never rendered.

Dashboard.html cleanup: ~725 lines of orphan inline <style> removed —
.section-title, .data-source*, .toggle-switch*, .catalog-cta*,
.memory-card / .memory-stat / .memory-description / .memory-footer
/ .btn-memory, .activity-card / .activity-stat / .activity-text
/ .btn-activity, .account-grid / .account-row / .account-scripts
/ .badge-role / .badge-group / .cron-line, .badge-included /
.badge-beta / .badge-demo. All matched markup deleted in the
previous commit; the CSS was dead code until now.

* ui(catalog): rename page heading 'Data Catalog' → 'Data Packages'

The top-nav entry says 'Data Packages' but the page itself said
'Data Catalog' — confusing two-name product. Aligns the heading and
<title> with the nav label. Subtitle trimmed too: 'manage your
subscriptions' was a vestige of the toggle UI that just got removed,
replaced with a one-liner describing what the page is for.

Two other 'Data Catalog' strings stay: they live inside the table-
profiler overlay JS and refer to an EXTERNAL catalog system (e.g.
OpenMetadata / Atlan) that an operator may link to per table — that
is a generic term for any external data-catalog product, not our
page name.

* fix(nav): dropdown clicks always work + mutual-exclusion close

Two bugs in the wireDropdown helper:

1. Clicking trigger B while trigger A's menu was open left both open.
   e.stopPropagation() in trigger.click prevented the document-click
   handler from firing, so trigger A's open menu had no way to learn
   that something else was clicked. Net effect: state diverged across
   the two dropdowns the more you clicked.

2. The target-vs-trigger equality check (e.target !== trigger) was
   strict. Clicking the chevron <svg> inside the button reports the
   svg or its <path> child as e.target — not the button — so removing
   stopPropagation alone would trip the close branch in the same
   click that just opened the panel.

Fix both at once: drop e.stopPropagation() AND switch the doc-handler
guard to trigger.contains(e.target). Now any click outside both the
trigger subtree and the panel subtree closes; any click on another
trigger closes via the OTHER dropdown's doc handler; clicks inside
the trigger (button OR svg child) are fully ignored by the doc
handler and only the trigger's own toggle handler fires.

* feat(ui): canonical blue-gradient hero on every admin page

The UI had a per-page hero pattern on ~10 onboarding/marketing pages
(admin_tokens / profile / install / setup_advanced / marketplace /
my_tokens / store_upload / home_*), each with its own ad-hoc CSS
(.tokens-hero, .profile-hero, .install-hero, .upload-hero, …). The
admin section's index + detail pages had plain H1/H2 with their own
.users-title / .gp-title / .obs-title / .cfg-title / … inline styling.
Net effect: half the app felt like a product, half felt like a
spreadsheet.

Now:
- .page-header--hero CSS upgraded to match the look analysts already
  liked from admin_tokens: 28px/32px/24px padding, 14px radius, soft
  primary-tinted box-shadow (0 4px 16px rgba(0,115,209,0.2)), 28px
  semibold title, optional uppercase eyebrow + 13.5px subtitle.
  Narrow-viewport breakpoint included.
- New _page_hero.html partial wraps the boilerplate. Usage:
    {% set page_hero_eyebrow  = "Users & Access" %}
    {% set page_hero_title    = "Users" %}
    {% set page_hero_subtitle = "…" %}
    {% include "_page_hero.html" %}
- 15 admin templates migrated to it: admin_users / admin_groups /
  admin_marketplaces / admin_access / admin_sessions /
  admin_session_detail / admin_store_submissions /
  admin_scheduler_runs / admin_usage / admin_user_detail /
  admin_welcome / admin_workspace_prompt / admin_server_config /
  activity_center / admin/news_editor. Each gets a grouped eyebrow
  (Users & Access / Data / Agent Experience / Activity Center /
  Server) matching the Admin dropdown sections so the page identity
  is unambiguous at a glance.

Legacy *-title H2/H1 + adjacent subtitle paragraphs deleted; their
per-page CSS rules are dead now (harmless, retire in a follow-up
sweep alongside other inline-style cleanup the reviewers flagged).

admin_tables.html intentionally NOT migrated — it's a standalone
HTML page that doesn't extend base.html; a separate refactor.

Test: test_admin_users_page_renders_for_admin assertion updated
from .users-title to .page-header__title + .page-header--hero (the
canonical pair). All other web/template tests stay green.

* refactor(ui): dedup _humanbytes, drop 267 lines of dead inline CSS

(1) _humanbytes consolidation:
- Add TB branch + optional precision param (default 2 preserves existing
  Store detail callers; dashboard uses precision=1 for headline tiles).
- Delete inline _fmt_bytes from dashboard handler — was a copy of
  _humanbytes with different rounding. One canonical helper now.

(2) Dead inline-CSS sweep across 17 migrated templates:
- Conservative regex: a CSS rule is deleted only when its primary class
  matches one of the known-dead names AND that name is NOT referenced
  from any class= attribute in the same file's markup.
- Per-file 'in-use' guard saved several false positives that the deny
  list would have nuked (e.g. .users-toolbar, .gp-search, .obs-subtitle,
  .marketplaces-toolbar are still in use; only .users-table, .users-search,
  .users-title, .modal-btn, etc. that have NO markup left went away).
- Removed: -267 lines across admin_users (-42), admin_marketplaces (-45),
  admin_groups (-31), my_tokens (-38), admin_tokens (-29), admin_access
  (-9), admin_user_detail (-6), admin_welcome (-8), admin_workspace_prompt
  (-8), admin_server_config (-2), admin_sessions (-1), admin_session_detail
  (-1), admin_usage (-1), admin_store_submissions (-3), admin_scheduler_runs
  (-3), activity_center (-4), corporate_memory_admin (-36).

Contract test stays green (9/9); all web/template/render/user_management
tests pass.

* feat(ui): canonical hero on /catalog (Data Packages)

Same .page-header--hero treatment as the admin pages — Data eyebrow,
Data Packages title, Browse-the-data-sources subtitle. Removes the
ad-hoc .page-title block (h1 / p / wrapper-div) and its CSS rules
(now dead, 3 rule blocks deleted).

* fix(nav): load app.js from _app_header.html — works on standalone pages

The previous nav-fix commit moved the inline dropdown script from
_app_header.html into app/web/static/app.js + added <script src=…>
to base.html. That broke EVERY page that includes _app_header.html
WITHOUT extending base.html (catalog, corporate_memory*,
admin_tables, install). They got the nav markup but no JS → both
Admin and AD dropdowns dead on those pages.

Fix: emit the <script src=app.js defer> directly inside the
_app_header.html partial. Any page that includes the header now
gets the script automatically — base.html-extenders AND standalone
HTML pages alike. base.html's duplicate <script> line removed.

Also fixes the wide-hero on /catalog: .page-header--hero now sets
its own max-width: var(--width-app) (1280px) so standalone pages
without a .container parent don't render the gradient edge-to-edge.
catalog's .source-cards bumped from 900px → 1280px to match the
hero, otherwise the page reads two-tier (wide blue band, narrow
content) which the user flagged.

Verified locally via agent-browser: Admin + AD dropdowns now click
through on /catalog, /admin/tables, /corporate-memory.

* docs(plan): standalone pages → base.html framework migration plan

Plan + Plan-agent review (8 must-fix items applied) for converting
the 5 templates that ship their own <html><head><body> scaffold
(catalog, install, corporate_memory, corporate_memory_admin,
admin_tables) to extend base.html. Root cause of yesterday's
'dropdown dead on /catalog' regression: shared infrastructure in
base.html doesn't propagate to standalones.

* feat(base): body_attrs block + migrate install.html to extend base

base.html: new {% block body_attrs %}{% endblock %} slot so pages
that need <body> attributes (admin_tables has data-source-type)
can carry them through extends.

install.html: convert from standalone <html><head><body> scaffold
to {% extends "base.html" %} with title / body_attrs / head_extra
/ layout / scripts blocks. Drops:
- <!DOCTYPE>, <html>, </html>, <head>, </head>
- <meta charset>, <meta viewport>
- Duplicate <link rel="stylesheet" href="...style-custom.css">
  (base.html already provides one)
- <body> opening + closing tags
- Leading _app_header.html include + _version_badge.html include
  (base.html handles both)

Preserves per-page CSS (in head_extra), per-page JS (in scripts),
the Inter font preconnect (kept inline; not hoisted to base in
this PR — separate decision).

Pilots the migration recipe before the 4 larger pages.

* refactor(memory): extend base.html

Same recipe as install.html. corporate_memory.html now inherits
<html>/<head>/<body> + nav + app.js script tag from base.html.
Page-specific CSS and JS preserved in head_extra + scripts blocks.

* refactor(memory-admin): extend base.html

Same recipe as install/corporate_memory. Curation page now in the
shared rendering pipeline.

* refactor(catalog): extend base.html

catalog.html had the most complexity: 7 head-level assets (chart.js,
Prism, prism-sql, metric_modal.css link + 2 preconnects + Inter
stylesheet), 5 body-level <script> blocks including a <script type=
"module"> for the metric modal, 2 duplicate style-custom.css links
in <head>. The migration script preserved all of them — head-level
externals hoisted to {% block head_extra %} in source order, body
scripts relocated to {% block scripts %} in source order (so chart.js
loads before the IIFE that builds Chart instances), duplicate
style-custom.css links dropped (base.html provides one).

* refactor(admin-tables): extend base.html + carry data-source-type

The biggest of the 5 standalones at 3563 lines. <body data-source-
type="{{ data_source_type }}"> attribute carried through via the
new {% block body_attrs %} slot (admin_tables JS reads
document.body.dataset.sourceType to switch between keboola and
bigquery rendering paths).

* release: 0.54.10 — UI design system unification + homepage status frame + initial workspace override + store guardrails

Co-Authored-By: zdenek.srotyr <zdenek.srotyr@keboola.com>

* refactor(web): migrate remaining templates to canonical design primitives

- admin_group_detail: .data-table, .btn family, appToast(), remove duplicate table/button/toast CSS
- admin_store_submission_detail: .data-table, .btn family, appToast(), remove duplicate btn/toast CSS
- profile_sessions: .data-table, _page_hero.html, remove duplicate table/title CSS
- me_debug: .data-table, .btn family, remove duplicate table/button CSS
- marketplace: .btn-primary/.btn-secondary, remove duplicate button CSS
- store_edit: remove duplicate .btn-primary/.btn-link CSS, canonical button classes
- store_upload: remove duplicate .btn-primary/.btn-secondary/.btn-link CSS

Co-Authored-By: zdenek.srotyr <zdenek.srotyr@keboola.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>

2026-05-14 13:28:03 +02:00

25 KiB

Raw Blame History

Standalone Pages → base.html Framework Migration Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking. One PR continuation (zs/design-pass).

Goal: Migrate the 5 templates that currently ship their own <html>, <head>, <body> scaffold to extend base.html. After this lands, every page that includes _app_header.html shares ONE rendering pipeline — same font load, same theme include, same script load, same nav. The class of bug that surfaced today (dropdown JS dead on /catalog, /admin/tables, /corporate-memory because <script src="app.js"> lived only in base.html) goes away permanently.

Architecture:

Five pages have private <head> + <body> scaffolding (10 486 lines combined, of which ~4 169 are inline <style> blocks and ~4 201 are inline <script> blocks).
base.html already exposes the right block surface: title, head_extra, layout, content, scripts.
Migration is mechanical per page: convert <html>...</html> → {% extends "base.html" %}{% block X %}...{% endblock %}. No behavior change; same per-page CSS/JS, just hoisted into the right block.
One small base.html change: add {% block body_attrs %}{% endblock %} so admin_tables.html can keep its data-source-type attr on <body>.

Tech Stack: FastAPI + Jinja2 templates, vanilla CSS, vanilla JS. Tests via pytest + agent-browser for visual smoke.

Why now / why one PR: The current zs/design-pass PR already touched all the affected pages (hero migration, dead-CSS sweep). Continuing the migration in the same PR keeps related changes together. Each per-page migration ships as its own commit so individual reverts stay surgical.

Post-review revisions

External Plan-agent review flagged 8 must-fix items before execution. Applied:

Script-extraction bug fixed: original recipe used script_m[-1] which would pick the LAST inline <script> and drop earlier ones. Catalog has TWO (868-line IIFE + 26-line module). Revised script collects all inline <script> blocks in order, preserving each block's tag attributes (so type="module" survives).
External assets hoist: per-page <link rel="stylesheet"> and <script src> inside <head> (e.g. catalog's chart.js, Prism, metric_modal.css) must land at the TOP of {% block head_extra %} — the original recipe captured only inline <style> and silently dropped externals.
Duplicate stylesheet detection: catalog.html ships a second <link rel="stylesheet" href="style-custom.css"> after its <style> block. base.html already loads it once. The migration drops duplicates.
Layout block default: changed from {% block content %} to {% block layout %}. Each standalone has its own top-level wrapper (<main class="main">, <div class="container-memory">, etc.) — putting that inside base.html's .container would double-wrap. Layout block opts out of the .container wrap entirely; we must re-include _app_header.html (and _version_badge.html if base.html includes one) inside the override.
Font preconnect hoist DEFERRED: Task 0 Step 3 (move Inter preconnect into base.html) is dropped from this PR. The 4 pages that need it keep their inline preconnect inside head_extra. Hoisting affects ALL base.html pages (admin section currently lives on system Inter fallback) — separate decision worth its own measurement.
Contract test added: Task 7 now adds an assertion to tests/test_design_system_contract.py that each migrated page extends base.html and the rendered HTML has exactly one <html> / <head> / <body>. Prevents future regression back to standalones.
Chart.js smoke verification: Task 4 (catalog) now requires an explicit "chart rendered" browser screenshot, not just "page loads".
Reviewer-fatigue caveat acknowledged: user explicitly chose "all in one PR". Per-page commits land in zs/design-pass for surgical revert. Reviewer can bisect per commit.

Out of scope (defer to follow-up PRs):

dashboard.html — already extends base.html per grep -l "extends.*base"; no migration needed. (Verify Step 0).
home_onboarded.html / home_not_onboarded.html — already extend base.html; no migration needed.
marketplace.html, marketplace_*_detail.html — not part of today's bug surface; can adopt the framework later.

File structure (touch list)

Modified:

app/web/templates/base.html — add {% block body_attrs %}{% endblock %} after <body.
app/web/templates/install.html — convert to extends.
app/web/templates/corporate_memory.html — convert to extends.
app/web/templates/corporate_memory_admin.html — convert to extends.
app/web/templates/catalog.html — convert to extends.
app/web/templates/admin_tables.html — convert to extends; preserve data-source-type body attr via the new block.

Possibly modified (per migration verification):

_app_header.html — script tag already lives there from the previous fix; no change expected unless we move it back to <head> for defer performance.
base.html — add {% block body_attrs %} (one line).

Tests:

tests/test_web_ui.py — likely has assertions on rendered HTML for these routes. Verify, update as needed.
tests/test_design_system_contract.py — should stay green (it doesn't care about page chrome).

No template deletes. Every standalone page becomes shorter; CSS/JS volume stays the same per page (just relocates into blocks).

Migration recipe (applied per page)

For every standalone template, the conversion follows a fixed pattern. Carry this recipe forward through Tasks 2–6.

Source structure (before)

<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <title>Foo - {{ config.INSTANCE_NAME }}</title>
    {% if not config.THEME_FONT_URL %}
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
    {% endif %}
    <style>
        /* … page-specific CSS … */
    </style>
    {% include '_theme.html' %}
</head>
<body>
    {% include '_app_header.html' %}
    {# page-specific content … #}
    <script>
        /* … page-specific JS … */
    </script>
</body>
</html>

Target structure (after)

{% extends "base.html" %}

{% block title %}Foo - {{ config.INSTANCE_NAME }}{% endblock %}

{% block head_extra %}
<style>
    /* … same page-specific CSS, verbatim … */
</style>
{% endblock %}

{% block layout %}
{# Use `layout` (not `content`) when the page renders its OWN top-level
   wrapper (e.g. dashboard.html does <main class="main">). Use `content`
   when the page is happy inside base.html's <div class="container">. #}
<main class="page-foo">
    {# page-specific markup, verbatim (minus the _app_header include —
       base.html includes it already). The <body data-x=…> attribute, if
       any, moves to a {% block body_attrs %}data-x="…"{% endblock %} #}
</main>
{% endblock %}

{% block scripts %}
<script>
    /* … same page-specific JS, verbatim … */
</script>
{% endblock %}

Deletions per page

<!DOCTYPE html> + <html> + </html> (base.html provides)
<head> + </head> (base.html provides)
<meta charset>, <meta name="viewport"> (base.html provides)
Font preconnect block — base.html doesn't ship it today, so this is a small behavior change: pages will lose the explicit Inter preconnect. Mitigation: add the preconnect once to base.html's {% block head_extra %} parent (or to base.html itself above the stylesheet link). See Step 1.
<link rel="stylesheet" href="…style-custom.css"> if any (base.html provides)
{% include '_theme.html' %} (base.html provides)
<body> opening tag (base.html provides; attrs go to {% block body_attrs %})
{% include '_app_header.html' %} at start of body (base.html includes it)
</body> + closing tags

Preserved per page

<title> text → {% block title %}
All inline <style> content → {% block head_extra %}<style>...</style>{% endblock %}
All page markup → {% block content %} or {% block layout %}
All inline <script> content → {% block scripts %}<script>...</script>{% endblock %}
Page-specific JS variable usage (e.g. data-source-type on body) → {% block body_attrs %}

Task 0: Setup + verify base.html blocks + add body_attrs slot

Files:

Modify: app/web/templates/base.html
Step 1: Verify dashboard.html / home_*.html already extend base.html.

grep -l "extends.*base\.html" app/web/templates/*.html

Expected output includes dashboard.html, home_onboarded.html, home_not_onboarded.html. Confirms our scope is exactly the 5 standalones, not more.

Step 2: Add {% block body_attrs %} to base.html.

The admin_tables.html template currently renders <body data-source-type="{{ data_source_type }}">; its inline JS reads that attribute. We must preserve the attribute.

Read base.html's <body> line, then change it from:

<body>

to:

<body {% block body_attrs %}{% endblock %}>

The default empty block keeps non-admin_tables pages unchanged.

Step 3: Add Inter font preconnect to base.html.

Currently base.html ships only the stylesheet + _theme.html include. The 4 standalone pages that ship their own font preconnect (catalog, corporate_memory*, install) would lose the optimization after migration. Add to base.html <head> right BEFORE the stylesheet link:

{% if not config.THEME_FONT_URL %}
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap" rel="stylesheet">
{% endif %}

This change benefits ALL base.html consumers — admin pages currently rely on the system Inter being present. With this addition, base.html-extended pages always have the canonical font loaded.

Step 4: Confirm test pass + render check before any per-page migration.

.venv/bin/python -m pytest tests/test_web_ui.py tests/test_web_home_page.py tests/test_design_system_contract.py -q

Expected: green. Captures the baseline before migrations begin.

Step 5: Commit.

git add app/web/templates/base.html
git commit -m "feat(base): body_attrs block + Inter font preconnect

Adds a body_attrs Jinja block (default empty) so pages that extend
base.html can carry their own <body> attributes — admin_tables.html
needs data-source-type for its JS reading.

Hoists the Inter font preconnect + stylesheet link into base.html's
<head> so every page that extends base gets the same font load. The
5 standalone pages about to be migrated each had this block inline;
centralising it here means future changes (e.g. self-hosting the
font) land in one place."

Task 1: Migrate install.html (smallest pilot)

Why install first: smallest of the 5 (1097 lines), simplest layout, no admin gating, well-contained. Validates the recipe before tackling the big templates.

Files:

Modify: app/web/templates/install.html
Step 1: Read full install.html.

wc -l app/web/templates/install.html
sed -n '1,30p' app/web/templates/install.html   # head (lines 1-30)
sed -n '640,660p' app/web/templates/install.html # </head> + <body> boundary
sed -n '935,945p' app/web/templates/install.html # <script> start area
tail -5 app/web/templates/install.html

Note the exact boundaries. Note any <body … attribute> (install.html: none).

Step 2: Convert via Python script (post-review revisions applied).

import pathlib, re

def migrate(filename: str) -> dict:
    """Convert a standalone Jinja template to extend base.html.

    Captures, in order:
      - <title>
      - Per-page <link> / <script src> / <style> inside <head> → head_extra (top)
      - Inline <style> blocks (with attributes preserved) → head_extra (after links)
      - <body> attributes → body_attrs
      - Body markup with the leading _app_header.html / _theme.html includes
        stripped and all inline scripts pulled out → layout block contents
      - All <script> blocks inside body (inline OR src, attributes preserved
        verbatim) → scripts block, in order

    Drops:
      - <!DOCTYPE>, <html>, </html>
      - <head>, </head>
      - <meta charset>, <meta viewport>
      - Duplicate <link rel="stylesheet" href=".../style-custom.css">
        (base.html already ships one)
      - </body>
    """
    path = pathlib.Path(f"app/web/templates/{filename}")
    text = path.read_text(encoding="utf-8")

    # 1) <title>
    title_m = re.search(r"<title>(.*?)</title>", text, re.DOTALL)
    title = title_m.group(1).strip() if title_m else filename

    # 2) Split <head> from <body>
    head_m = re.search(r"<head[^>]*>(.+?)</head>", text, re.DOTALL)
    body_m = re.search(r"<body([^>]*)>(.+?)</body>", text, re.DOTALL)
    if not head_m or not body_m:
        raise RuntimeError(f"missing <head> or <body> in {filename}")
    head = head_m.group(1)
    body_attrs = body_m.group(1).strip()
    body = body_m.group(2)

    # 3) Inside <head>: collect head-level <link>, <script src>, <style>.
    head_assets = []  # list of (kind, raw_tag) preserving source order
    cursor = 0
    HEAD_PATTERNS = [
        ("link",   re.compile(r"<link\b[^>]*?>", re.IGNORECASE)),
        ("script", re.compile(r"<script\b[^>]*?>.*?</script>", re.IGNORECASE | re.DOTALL)),
        ("style",  re.compile(r"<style\b[^>]*?>.*?</style>", re.IGNORECASE | re.DOTALL)),
    ]
    # Concatenate matches found in head, in their original source position.
    matches = []
    for kind, pat in HEAD_PATTERNS:
        for m in pat.finditer(head):
            matches.append((m.start(), kind, m.group(0)))
    matches.sort()
    for _, kind, raw in matches:
        # Skip duplicate style-custom.css link (base.html already provides).
        if kind == "link" and "style-custom.css" in raw:
            continue
        # Skip <link rel="preconnect/stylesheet" pointing at font.googleapis> —
        # we keep the inline preconnect block per page to preserve current
        # behaviour; do NOT dedupe against base.html in this pass.
        head_assets.append(raw)

    head_extra = "\n".join(head_assets)

    # 4) Inside <body>: pull out every <script> (inline OR src), in order,
    # for relocation to {% block scripts %}. Strip the leading
    # _app_header.html include + any leading {% include "_theme.html" %}.
    script_blocks = []
    SCRIPT_BODY_RE = re.compile(r"<script\b[^>]*?>.*?</script>", re.IGNORECASE | re.DOTALL)
    for m in SCRIPT_BODY_RE.finditer(body):
        script_blocks.append(m.group(0))
    body_no_scripts = SCRIPT_BODY_RE.sub("", body)

    # Strip leading _app_header.html include (with optional surrounding
    # whitespace and HTML comments).
    body_no_header = re.sub(
        r"^\s*(?:<!--[^>]*-->\s*)*\{%\s*include\s+['\"]_app_header\.html['\"]\s*%\}\s*",
        "", body_no_scripts, count=1
    )

    # 5) Compose output.
    layout_indent = "    "
    out = ['{% extends "base.html" %}', "", f"{{% block title %}}{title}{{% endblock %}}"]
    if body_attrs:
        out += ["", f"{{% block body_attrs %}}{body_attrs}{{% endblock %}}"]
    if head_extra.strip():
        out += ["", "{% block head_extra %}", head_extra, "{% endblock %}"]
    out += [
        "",
        "{% block layout %}",
        "{% include '_app_header.html' %}",
        body_no_header.rstrip(),
        "{% endblock %}",
    ]
    if script_blocks:
        out += ["", "{% block scripts %}"]
        out += script_blocks
        out += ["{% endblock %}"]
    out.append("")

    new_text = "\n".join(out)
    path.write_text(new_text, encoding="utf-8")
    return {
        "name": filename,
        "old_lines": len(text.splitlines()),
        "new_lines": len(new_text.splitlines()),
        "head_assets": len(head_assets),
        "script_blocks": len(script_blocks),
        "body_attrs": bool(body_attrs),
    }

result = migrate("install.html")
print(result)

Step 3: Decide content vs layout block.

install.html's top-level wrapper after the header — read it. If it's just standard content, {% block content %} is right (base.html wraps it in <div class="container">). If it has its own <main> or full-bleed elements, switch to {% block layout %} (which overrides base.html's container entirely) and manually re-add the _app_header.html include and <main> wrapper. Default to content; switch only if the page looks broken in browser.

Step 4: Smoke test in dev server.

LOCAL_DEV_MODE=1 DATA_DIR=/tmp/agnes-design-pass-data .venv/bin/uvicorn app.main:app --port 8765 > /tmp/uv-install.log 2>&1 &
sleep 4
agent-browser open http://localhost:8765/install --wait-until networkidle
agent-browser screenshot /tmp/install-after.png --full
# Click Admin dropdown
agent-browser snapshot -i | grep -E "Admin|Hide"
# Verify install page's own behavior (whatever it does — copy buttons, accordions, etc.)
pkill -f "uvicorn.*8765"

Compare install-after.png against the baseline from /tmp/design-pass-baseline/.

Step 5: Run tests + commit.

.venv/bin/python -m pytest tests/ -k "install or web_ui" -q
git add app/web/templates/install.html
git commit -m "refactor(install): extend base.html instead of standalone

Pilots the 5-page standalone→framework migration. install.html now
inherits <head>, <body>, font preconnect, theme include, app-header,
and the app.js script tag from base.html. Page-specific styles and
scripts kept verbatim inside head_extra + scripts blocks. -1097 line
template becomes ~+200 less (head/body scaffolding deleted)."

Task 2: Migrate corporate_memory.html

Files: app/web/templates/corporate_memory.html

Same recipe as Task 1. Note: page is admin-gated ({% if session.user %} checks in markup). The wrapping logic isn't part of the migration — base.html's _app_header.html already handles the auth check.

Step 1–5: Apply Task-1 recipe verbatim. Commit as refactor(memory): extend base.html.
Step 6: Verify memory-page-specific JS (knowledge filter, voting, sync status) still works on /corporate-memory. Browser test: click a knowledge item, click upvote, click filter pill.

Task 3: Migrate corporate_memory_admin.html

Files: app/web/templates/corporate_memory_admin.html

Same recipe. Admin-only curation page; modals + accordion behavior to verify.

Apply recipe + commit refactor(memory-admin): extend base.html.
Browser test: open a knowledge item modal, edit, save (don't commit DB; just verify modal opens and closes).

Task 4: Migrate catalog.html

Files: app/web/templates/catalog.html

The biggest of the four "memory + catalog + install" group (2524 lines). Has source-cards, accordion, profiler overlay, two inline <script> blocks (868 lines + 26 lines).

Step 1: Concatenate the TWO inline <script> blocks before relocating. Otherwise only the last one would land in {% block scripts %} and the smaller post-script would orphan. Either:
- Order them as script_outer + "\n\n" + script_inner in the migration script, OR
- Verify both are independent and emit them as two consecutive <script> blocks inside {% block scripts %}.
Apply recipe + commit refactor(catalog): extend base.html.
Browser test: load /catalog, click an accordion to expand, click a table row to open profiler overlay, verify "Live" / "Local" badges render.

Task 5: Migrate admin_tables.html (biggest, highest risk)

Files: app/web/templates/admin_tables.html

3563 lines. Has the data-source-type body attribute (uses {% block body_attrs %} from Task 0). 850-line <style> block. 1795-line <script> block — biggest JS on the site (registry mutations, modal forms, AJAX, table polling).

Step 1: Apply the recipe with body_attrs override.

Add in the new template:

{% block body_attrs %}data-source-type="{{ data_source_type }}"{% endblock %}

Step 2: Stress-test the JS. This page has the most behavior. Manual checks:
- Source-type filter switcher
- "+ Register table" modal opens
- Click into a registered table row → edit modal opens
- Cache warm-up trigger button
- Table search filter
Apply recipe + commit refactor(admin-tables): extend base.html.

Task 6: Cross-page browser smoke + full pytest

Files: none (verification only).

Step 1: Boot dev server + iterate ALL 5 migrated routes via agent-browser.

LOCAL_DEV_MODE=1 DATA_DIR=/tmp/agnes-design-pass-data .venv/bin/uvicorn app.main:app --port 8765 > /tmp/uv-smoke.log 2>&1 &
sleep 4
for r in /install /corporate-memory /corporate-memory/admin /catalog /admin/tables; do
    safe="${r//\//-}"
    agent-browser open "http://localhost:8765${r}" --wait-until networkidle
    agent-browser screenshot "/tmp/framework-after${safe}.png" --full
done

# Click Admin dropdown on each — confirm it opens
for r in /install /corporate-memory /catalog /admin/tables; do
    agent-browser open "http://localhost:8765${r}"
    snap=$(agent-browser snapshot -i)
    admin_ref=$(echo "$snap" | grep -oE 'button "Admin"[^@]*@e[0-9]+' | grep -oE 'e[0-9]+' | head -1)
    hide_ref=$(echo "$snap" | grep -oE 'link "Hide »"[^@]*@e[0-9]+' | grep -oE 'e[0-9]+' | head -1)
    [ -n "$hide_ref" ] && agent-browser click "@$hide_ref"
    sleep 1
    agent-browser click "@$admin_ref"
    sleep 1
    echo "$r — Admin: $(agent-browser snapshot -i | grep -c menuitem) menu items"
done

pkill -f "uvicorn.*8765"

Expected: each page → 15+ menuitem entries when Admin dropdown opens.

Step 2: Full pytest.

.venv/bin/python -m pytest tests/ --tb=line -n auto -q

Expected: same baseline pass count (4500+) + 12 pre-existing Keboola/clean-install fails.

Step 3: Visual diff vs baseline. Open at least one screenshot per migrated page and compare against /tmp/design-pass-baseline/. Any unexpected layout shift → flag for fix before commit.

Task 7: CHANGELOG entry + final push

Step 1: Add to CHANGELOG.md [Unreleased].

Under ### Changed:

- All web templates now extend `base.html`. Previously 5 templates
  (`catalog.html`, `corporate_memory.html`, `corporate_memory_admin.html`,
  `install.html`, `admin_tables.html`) shipped their own `<html>` /
  `<head>` / `<body>` scaffold — a source of drift when shared
  infrastructure changed (today's symptom: the nav-dropdown
  `app.js` script lived only in `base.html`, so those 5 pages had
  dead dropdowns). `base.html` now exposes a `body_attrs` Jinja
  block + emits the Inter font preconnect, so all pages share one
  rendering pipeline.

Step 2: Final pytest + push.

.venv/bin/python -m pytest tests/ --tb=line -n auto -q | tail -8
git push origin zs/design-pass

PR #284 auto-updates with the new commits.

Risk register

Page-specific JS reads from elements that base.html wraps differently. Mitigation: keep {% block content %} markup byte-identical to the old body content (sans _app_header.html include). IDs, classes, data attrs all preserved. JS sees the same DOM.
<body data-source-type=…> on admin_tables.html. Mitigation: {% block body_attrs %} slot added to base.html in Task 0.
Per-page CSS specificity collisions with style-custom.css. Inline <style> blocks have always loaded AFTER style-custom.css. After migration, the inline <style> is in {% block head_extra %} which sits AFTER style-custom.css link in base.html. Order preserved. No specificity flip.
Page-specific font preconnect already loaded twice. Currently 4 of the 5 pages have the Inter preconnect inline; after migration they inherit it from base.html. Mitigation: Task 0 Step 3 hoists the preconnect to base.html before any per-page migration. After Task 0, the inline ones become duplicates → harmless but should be deleted as part of each per-page conversion (the migration script captures only <style> content + script content, so preconnect lines naturally drop).
Login pages (base_login.html consumers). Not in scope. Login pages still use base_login.html. The framework migration is for authed-content pages only.
Reviewer fatigue. ~5000 LOC of diff across 6 commits. Mitigation: per-page commit boundary → reviewer can read one commit, ack, move on.

Self-review

Spec coverage: 5 standalone pages enumerated; all 5 have a task. ✅
Block-mapping completeness: title, head_extra, content/layout, scripts, body_attrs all addressed. ✅
No placeholders: each migration step has concrete shell + Python code. ✅
Tests run before each commit: Task 0 Step 4, Task 1 Step 5, Task 6 Step 2. ✅
CHANGELOG entry: Task 7 Step 1. ✅
One-PR continuation: lands on existing zs/design-pass. ✅
Rollback granularity: per-page commits; revert individual migrations cleanly. ✅

25 KiB Raw Blame History Unescape Escape