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