generated from coulomb/repo-seed
Plan graph explorer UI refinement
This commit is contained in:
178
workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md
Normal file
178
workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md
Normal file
@@ -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.
|
||||||
Reference in New Issue
Block a user