Exploring braghettos/krateo-frontend: UI/UX changes and architectural enhancements

[fedepini]

Date: 2026-07-13
Status: Draft — open for discussion

---

Summary

This discussion documents a comparison between krateoplatformops/frontend at main and the fork at braghettos/krateo-frontend. The goal is to explore what has been built there, evaluate what could be adopted or adapted, and surface decisions that need team alignment before any convergence.

The fork has diverged substantially across two major parallel tracks:

1. A full UI/UX refresh enabled by moving to Ant Design 6, including a new chart and graph library stack
2. Autopilot — an AI copilot that drives the portal via a kagent A2A endpoint, with a hard architectural invariant: the agent never mutates data directly, it drives the real UI controls through the existing dispatcher

Additionally there are production hardening improvements and a set of new UI components that are largely independent of these larger changes and could be considered for backporting independently.

---

1. Ant Design 5 → 6: what it changes in practice

The most consequential dependency change is the upgrade to antd 6. This is a breaking change with real frontend developer impact:

Change	Impact
type prop on Button/Tag replaced by color + variant	Every <Button type="primary"> needs updating
List component removed	Widgets using List need rewrites (EventList, Notifications)
New design token system (@ant-design/cssinjs v2)	Existing theme overrides need review
Component reorganization into sub-packages	Import paths change in several places

The migration is widget-by-widget, not a search-and-replace. The payoff is access to @ant-design/plots and @ant-design/graphs, which both require antd 6, and a more expressive CSS token system that makes theming more powerful.

Key consequence for theming: with antd 6, the Theme widget's color and dark/light mode customizations automatically propagate into charts and flow diagrams. Today, chart colors and the portal theme are maintained independently — a dark-mode chart is a code change, not a configuration change.

---

2. UI/UX changes: what the fork actually looks like

2.1 Autopilot — the AI copilot rail

Autopilot adds a persistent 384px docked panel on the right side of the portal, toggled by an AutopilotToggle button in the header.

The panel anatomy:

• Context strip at the top showing the current page and widget context the agent sees
• Conversation bubbles — user messages right-aligned, agent messages left-aligned with an animated amber blink caret during streaming
• Action chips that appear when the agent executes a portal action (navigate, openDrawer, openModal) — showing the action type, target, and a status indicator
• Suggestion pills — the agent can surface quick-action suggestions the user can tap to auto-populate the composer
• Composer at the bottom — a textarea with a send button and a "stop" control during streaming

The hard invariant: the agent never calls APIs directly. It calls dispatchAction() — the same function a button click uses — which means all confirmation dialogs, loading states, and error handling apply equally to agent-triggered actions. Widget developers don't need to add AI-aware code paths.

2.2 Form prefill — AgentDraft

When Autopilot determines a form should be filled, it writes an AgentDraft — a structured payload mapping field names to values — to a context the Form widget reads on mount.

The UX is intentionally quiet:

• Fields are populated silently, no per-field AI indicator
• The connector rail (a thin colored stripe on the form's left edge) reflects the agent state: graphite (idle), amber (populating), teal (draft applied, user reviewing)
• A section navigator appears when the draft spans multiple form sections, showing completion per section
• A sticky action bar at the bottom shows "Review draft" / "Clear" — the user always controls the final submit
• Drafts are persisted to localStorage so they survive accidental navigations

2.3 Spotlight tours

Spotlight tours use the Ant Design Tour component. The agent uses a semantic anchor resolution strategy rather than DOM selectors:

• nav:path — highlights a nav item by its route path
• action:actionId — highlights a button or table action by its action ID
• text:label — falls back to text content matching

This means tour steps can be authored in agent responses without knowing DOM structure. Tours only activate if the agent has already navigated to the correct page.

2.4 Command palette (⌘K)

A CommandPalette component has been added, triggered by ⌘K / Ctrl+K. It searches across navigation items (routes), the current page's widget actions, and recent pages. This is a new interaction pattern with no equivalent in the current repo.

2.5 Widget-level visual changes

Reconciliation rail: Widgets that trigger REST mutations now show a thin horizontal bar below the widget with cells representing reconciliation steps. Active cells show a diagonal hatch pattern; completed cells show an amber glow tick. This gives operators visual feedback during slow Kubernetes reconciliation without blocking the UI.

Conditions pills: Widgets with displayingDependencies render small pills showing active condition state — useful for debugging complex form dependency trees.

Button: The antd 6 color/variant API exposes more visual variations — filled, outlined, text, link variants per color — enabling richer button styling without custom CSS.

Paragraph: Now uses CSS custom properties (local tokens) for color and weight instead of inline styles, making it responsive to theme changes.

RichRow (used in EventList): Extended with size variants (compact, default, expanded) and a hover state.

2.6 New widgets and components

Component	Type	Description
Card	Widget	Static content card with optional header, footer, and cover image
Statistic	Widget	KPI display — value, label, and trend indicator
Progress	Widget	Circular or linear progress bar driven by widgetData
CommandPalette	Component	⌘K global search across nav and actions
ThemeToggle	Component	Light/dark mode toggle in the header
AutopilotToggle	Component	Toggles the Autopilot rail

2.7 Structural widget kinds removed

The fork removes 11 "infrastructure" widget kinds — Route, RoutesLoader, NavMenu, NavMenuItem, Page, Theme, Drawer, Modal, and a few others — from the composable surface. These are now treated as platform internals rather than operator-composable widgets.

This simplifies the allowedResources list on Page widgets and reduces the conceptual surface area operators need to understand. It is a signal that the fork is starting to distinguish "platform plumbing" from "operator-facing composition units."

2.8 Loading and error states

• Skeleton screens now trigger on isPending (TanStack Query v5 canonical state) rather than isLoading, which was only true on the first fetch — re-fetches now also show a skeleton
• 404 responses are treated as transient (cold snowplow cache) and retried with exponential backoff before showing an error
• Error messages are specific — "Widget not found", "Permission denied", "Service unavailable" — rather than generic

2.9 Modal and drawer UX

• Modals use destroyOnHidden (antd 6 API) instead of destroyOnClose
• Form submit/cancel buttons in drawer mode are moved to the drawer's extra slot (top-right corner), freeing the form body for content

---

3. Production hardening (backport candidates)

These improvements are independent of antd 6 and could be backported without the larger migration.

Improvement	Problem it solves
fetchWithTimeout on all requests	Hanging requests stall the UI indefinitely
registerCleanup() for SSE streams	Open connections leak when navigating away mid-action
Staggered post-write revalidation (0ms + 800ms + 2200ms)	Users see stale data after form submission due to snowplow informer lag
Widget 404 retry with exponential backoff	Blank page on first deploy before informer cache warms
resolveNavigationTarget for query param merging	Same-page navigation loses active filters and pagination state
OTel tracing (no-op unless OTEL_COLLECTOR_URL set)	No observability into widget fetch and action performance

---

4. Action system: local features not yet in the fork

Our main branch has two action types not in the fork:

• externalNavigate — opens a URL in a new tab with JQ interpolation and optional confirmation. PR ci: set ci to use krateoctl v0.8.9 #24 on the fork targets this same feature — we should align before it merges.
• refresh — invalidates TanStack Query caches for specific resources or widget kinds without a page reload. Not referenced in any open PR on the fork.

---

5. Higher-level observations

The "agent drives UI" principle

The most architecturally significant choice in the fork is that Autopilot operates through dispatchAction() rather than through a parallel mutation path. This is a constraint, not a convenience — AI actions are governed by the same validation and confirmation logic as human actions, agent behavior is fully auditable through the same logs, and widget developers have zero additional surface area to protect. If we adopt AI integration at any point, documenting this constraint as an ADR would give future contributors a clear boundary.

Testability shift

Refactoring useHandleActions to a pure dispatchAction() function makes the action system unit-testable without a React environment. This is a meaningful improvement to the development feedback loop, independent of any AI integration plans.

The reconciliation rail as an operator UX gap

The reconciliation rail addresses a real gap in the current portal: operators submit a form, the UI returns to idle, but the Kubernetes resource is still reconciling. There is currently no way to know if a change is still propagating without watching cluster logs. The reconciliation rail closes this gap visually.

---

Discussion questions

1. antd 5 → 6 migration: Is this on our roadmap? What is the estimated scope? Should we open a milestone?
2. Autopilot / kagent: Is this part of the Krateo platform direction? What is the kagent service and who owns it?
3. New widgets (Card, Statistic, Progress): Should we adopt these? They address common dashboard composition needs.
4. Command palette (⌘K): Is this a UX pattern we want in the portal?
5. Reconciliation rail: This addresses a real operator pain point. Worth planning as a standalone feature independent of antd 6?
6. Production hardening sprint: Can we plan a sprint to backport request reliability and cache improvements? None of these require the antd 6 migration.
7. Repo convergence: Is braghettos/krateo-frontend an experiment branch intended to merge back, or is it tracking a separate product direction?

---

Generated 2026-07-13. Based on analysis of krateoplatformops/frontend at main and braghettos/krateo-frontend at main.