railiance-fabric/workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md

---
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.