diff --git a/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md b/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md new file mode 100644 index 0000000..fd13f7c --- /dev/null +++ b/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md @@ -0,0 +1,178 @@ +--- +id: RAIL-FAB-WP-0009 +type: workplan +title: "Graph Explorer UI Refinement" +domain: railiance +repo: railiance-fabric +status: active +owner: codex +topic_slug: railiance +planning_priority: high +planning_order: 9 +created: "2026-05-18" +updated: "2026-05-18" +--- + +# RAIL-FAB-WP-0009 - Graph Explorer UI Refinement + +## Goal + +Refine the interactive Fabric graph explorer user interface before extracting +it into a shared `graph-explorer-engine` repository. The shell is still local +to `railiance-fabric`, so this is the right moment to improve the interaction +model, visual hierarchy, orientation workflows, and large-graph ergonomics +while the engine boundary is still flexible. + +This workplan intentionally comes before extraction. The goal is to learn from +using the Fabric map against the current local registry, then turn the refined +UI into a stronger reusable engine candidate. + +## Design Direction + +The explorer should feel like an operational map, not a demo page. It should +make the registered infrastructure legible at a glance, then let a user narrow +into services, interfaces, dependencies, onboarding gaps, and saved operational +views without losing context. + +Refinement should focus on: + +- a calmer, denser toolbar that still exposes the important controls +- clearer information architecture for the graph, selection details, + orientation hints, saved views, and hidden elements +- map-first behavior where the graph remains the dominant surface +- useful empty, loading, and error states +- visual encodings that make repo/service/interface/dependency/binding layers + distinguishable without becoming noisy +- better onboarding-gap and unresolved-dependency workflows +- URL and browser-local saved views that are understandable to a human user +- responsive behavior that remains usable on laptop and narrow screens +- keyboard, focus, contrast, and screen-reader basics +- explicit seams for a later repo-scoping adapter and shared engine extraction + +## Extraction Guardrail + +Do not extract during this workplan. Extraction should wait until: + +- the Fabric UI refinement has produced a clearer shell contract +- the repo-scoping adapter parity work has proven a second real host +- any UI assumptions that are Fabric-specific have been moved behind manifest + fields, payload metadata, or host-provided mode definitions + +## Tasks + +### T01 - Baseline UI Review + +```task +id: RAIL-FAB-WP-0009-T01 +status: in_progress +priority: high +``` + +Run the current graph explorer against the local registry and capture concrete +UI friction before changing the implementation. + +Acceptance notes: + +- Start the local registry and open `/ui/graph-explorer`. +- Review desktop and narrow viewport behavior. +- Exercise search, filters, mode switching, selection, focus, manual + overrides, saved views, copied state URLs, and reset behavior. +- Capture a concise refinement backlog in repo docs or the workplan. +- Identify which issues block real use and which can wait for extraction. + +### T02 - Layout And Information Architecture + +```task +id: RAIL-FAB-WP-0009-T02 +status: todo +priority: high +``` + +Refine the toolbar, side panel, detail sections, saved-view controls, legend, +hidden-summary surface, and orientation hints so the graph remains central and +the controls are easier to scan. + +Acceptance notes: + +- Reduce visual clutter in the toolbar without hiding core workflows. +- Give selection details, orientation workflows, saved views, and legend + predictable places. +- Make hidden/blurred overrides and active filters easy to understand. +- Keep the first screen as the working map, not documentation. + +### T03 - Visual Encoding And Graph Readability + +```task +id: RAIL-FAB-WP-0009-T03 +status: todo +priority: high +``` + +Improve graph readability through better layer styling, labels, edge treatment, +selection affordances, unresolved/onboarding markers, and layout defaults. + +Acceptance notes: + +- Layer colors are distinguishable and not dominated by one hue family. +- Node and edge labels do not overwhelm dense views. +- Selected, hovered, hidden, blurred, unresolved, and registered-only states are + visually distinct. +- Default layout gives a useful first impression with the current registry data. + +### T04 - Orientation Workflow Polish + +```task +id: RAIL-FAB-WP-0009-T04 +status: todo +priority: medium +``` + +Make the Fabric-specific orientation workflows easier to use for service +dependencies, interface consumers, onboarding gaps, unresolved dependencies, +and saved operational contexts. + +Acceptance notes: + +- Selecting a service shows a readable dependency/provider chain. +- Selecting an interface shows consumers and impact context. +- Registered-only repos are visible as actionable onboarding gaps. +- Saved local views have understandable names, status, and sharing behavior. + +### T05 - Accessibility, Responsiveness, And Failure States + +```task +id: RAIL-FAB-WP-0009-T05 +status: todo +priority: medium +``` + +Harden the graph explorer UI for basic accessibility, responsive use, and +failure handling before it becomes a candidate shared engine. + +Acceptance notes: + +- Controls have useful labels, focus order, and keyboard-accessible behavior. +- Text fits on narrow and desktop viewports. +- Loading, empty graph, fetch failure, and missing Cytoscape states are + understandable. +- Tests cover the static UI wiring for new states and controls. + +### T06 - Repo-Scoping Adapter Readiness Review + +```task +id: RAIL-FAB-WP-0009-T06 +status: todo +priority: medium +``` + +Review the refined UI against the repo-scoping parity checklist before creating +the adapter workplan. + +Acceptance notes: + +- Identify remaining Fabric-specific assumptions in the UI shell. +- Confirm which controls should be manifest-driven before extraction. +- Update `docs/graph-explorer-operations.md` or contract docs with any refined + engine boundary. +- Recommend whether the next workplan should be repo-scoping adapter parity or + one more Fabric-side UI hardening pass.