coulomb/railiance-fabric
Archived
2
0
Fork 0
generated from coulomb/repo-seed
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Refine graph explorer UI workplan

Browse Source
This commit is contained in:
Bernd Worsch
2026-05-18 23:25:24 +02:00
parent 95901feb0d
commit 2a2616653f
1 changed files with 84 additions and 22 deletions
Download Patch File Download Diff File Expand all files Collapse all files

106
workplans/RAIL-FAB-WP-0009-graph-explorer-ui-refinement.md
View File

@@ -39,15 +39,21 @@ Refinement should focus on:
- a calmer, denser toolbar that still exposes the important controls - a calmer, denser toolbar that still exposes the important controls
- clearer information architecture for the graph, selection details, - clearer information architecture for the graph, selection details,
orientation hints, saved views, and hidden elements orientation hints, saved views, node visibility, and edge visibility
- map-first behavior where the graph remains the dominant surface - map-first behavior where the graph remains the dominant surface
- useful empty, loading, and error states - useful empty, loading, and error states
- visual encodings that make repo/service/interface/dependency/binding layers - visual encodings that make repo/service/interface/dependency/binding node types
distinguishable without becoming noisy distinguishable without becoming noisy
- explicit node-type and edge-type controls that support multi-selection
- a filtering model that separates hiding from removing entities from layout
- contextual controls that explain which attributes and modifiers apply to
which node and edge types
- floating map navigation controls and selection anchors that do not depend on
changing node borders
- better onboarding-gap and unresolved-dependency workflows - better onboarding-gap and unresolved-dependency workflows
- URL and browser-local saved views that are understandable to a human user - URL and browser-local saved views that are understandable to a human user
- responsive behavior that remains usable on laptop and narrow screens - responsive behavior that remains usable on laptop and narrow screens
- keyboard, focus, contrast, and screen-reader basics - bubble-help explanations, keyboard, focus, contrast, and screen-reader basics
- explicit seams for a later repo-scoping adapter and shared engine extraction - explicit seams for a later repo-scoping adapter and shared engine extraction
## Extraction Guardrail ## Extraction Guardrail
@@ -81,8 +87,10 @@ Acceptance notes:
overrides, saved views, copied state URLs, and reset behavior. overrides, saved views, copied state URLs, and reset behavior.
- Capture a concise refinement backlog in repo docs or the workplan. - Capture a concise refinement backlog in repo docs or the workplan.
- Identify which issues block real use and which can wait for extraction. - Identify which issues block real use and which can wait for extraction.
- Confirm where the current UI still says `Layer`, where global controls like
Review and Unresolved are ambiguous, and which terms need bubble help.
### T02 - Layout And Information Architecture ### T02 - Node And Edge Control Architecture
```task ```task
id: RAIL-FAB-WP-0009-T02 id: RAIL-FAB-WP-0009-T02
@@ -91,19 +99,27 @@ priority: high
state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c" state_hub_task_id: "751a2fc5-2263-48b0-9ef2-d55e37a0735c"
``` ```
Refine the toolbar, side panel, detail sections, saved-view controls, legend, Refine terminology, toolbar structure, side panel placement, map controls,
hidden-summary surface, and orientation hints so the graph remains central and saved-view controls, legend, hidden-summary surface, and orientation hints so
the controls are easier to scan. the graph remains central and the controls are easier to scan.
Acceptance notes: Acceptance notes:
- Replace user-facing `Layer` wording with `Nodes`, `Node type`, or
`Node types`. Internal manifest fields may keep `layer` until extraction if
that avoids churn.
- Replace the single node layer selector with a multi-select node type control.
- Add a multi-select edge type control for showing and hiding relationships by
edge type.
- Move pan, zoom, fit, focus, and reset navigation controls into a floating map
menu.
- Reduce visual clutter in the toolbar without hiding core workflows. - Reduce visual clutter in the toolbar without hiding core workflows.
- Give selection details, orientation workflows, saved views, and legend - Give selection details, orientation workflows, saved views, and legend
predictable places. predictable places.
- Make hidden/blurred overrides and active filters easy to understand. - Make hidden/blurred overrides and active filters easy to understand.
- Keep the first screen as the working map, not documentation. - Keep the first screen as the working map, not documentation.
### T03 - Visual Encoding And Graph Readability ### T03 - Graph Readability, Layout Semantics, And Selection Anchors
```task ```task
id: RAIL-FAB-WP-0009-T03 id: RAIL-FAB-WP-0009-T03
@@ -112,38 +128,51 @@ priority: high
state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade" state_hub_task_id: "3e60397c-c833-4bd7-ba1b-b754b203dade"
``` ```
Improve graph readability through better layer styling, labels, edge treatment, Improve graph readability through better node-type styling, labels, edge
selection affordances, unresolved/onboarding markers, and layout defaults. treatment, selection affordances, unresolved/onboarding markers, layout
defaults, and repo-local layout affinity.
Acceptance notes: Acceptance notes:
- Layer colors are distinguishable and not dominated by one hue family. - Node type colors are distinguishable and not dominated by one hue family.
- Node and edge labels do not overwhelm dense views. - Node and edge labels do not overwhelm dense views.
- Selected, hovered, hidden, blurred, unresolved, and registered-only states are - Selected, hovered, hidden, blurred, unresolved, and registered-only states are
visually distinct. visually distinct.
- Selection is represented by an arrow or anchor pointing to the focused entity
rather than by relying on border changes.
- A selected entity can be hidden and unhidden without losing the selection
anchor; the anchor changes only when focus changes.
- Repo-local nodes stay closer together than cross-repo relationships, while
servers and deployments bind tightly to their runtime/deployment entities and
more loosely to service repos.
- Default layout gives a useful first impression with the current registry data. - Default layout gives a useful first impression with the current registry data.
### T04 - Orientation Workflow Polish ### T04 - Filter Rule Builder And Visibility Semantics
```task ```task
id: RAIL-FAB-WP-0009-T04 id: RAIL-FAB-WP-0009-T04
status: todo status: todo
priority: medium priority: high
state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93" state_hub_task_id: "1b446ac8-eeba-4de6-9a32-d7f980d70b93"
``` ```
Make the Fabric-specific orientation workflows easier to use for service Design and implement an optional filtering panel that can express detailed
dependencies, interface consumers, onboarding gaps, unresolved dependencies, node and edge rules without turning type-specific attributes into unexplained
and saved operational contexts. global controls.
Acceptance notes: Acceptance notes:
- Selecting a service shows a readable dependency/provider chain. - Users can create a list of rules that target nodes or edges by type and by
- Selecting an interface shows consumers and impact context. supported attributes.
- Registered-only repos are visible as actionable onboarding gaps. - Type-specific concepts such as Review and Unresolved appear only when they
- Saved local views have understandable names, status, and sharing behavior. apply to the selected node or edge types, either as contextual controls or
rule templates.
- Rules can apply modifiers such as show, hide, blur, highlight, or remove.
- Node and edge filtering supports two explicit result modes: hide while
preserving the current layout, or remove from layout and redraw the graph.
- The active rule list is inspectable, editable, reorderable, and resettable.
### T05 - Accessibility, Responsiveness, And Failure States ### T05 - Bubble Help, Accessibility, Responsiveness, And Failure States
```task ```task
id: RAIL-FAB-WP-0009-T05 id: RAIL-FAB-WP-0009-T05
@@ -153,10 +182,16 @@ state_hub_task_id: "67a9cbc9-ebaa-4cb1-bec9-46bf250faf41"
``` ```
Harden the graph explorer UI for basic accessibility, responsive use, and Harden the graph explorer UI for basic accessibility, responsive use, and
failure handling before it becomes a candidate shared engine. failure handling before it becomes a candidate shared engine. Explain the
domain terms directly where users encounter them.
Acceptance notes: Acceptance notes:
- Add bubble-help explanations to graph terms and controls, including Nodes,
Node types, Edge types, Layout, Review, Unresolved, Hide, Remove, Blur,
Focus, Fit, and saved views.
- Bubble help must explain what the control changes, whether it affects layout,
and why a term might not apply to every node or edge type.
- Controls have useful labels, focus order, and keyboard-accessible behavior. - Controls have useful labels, focus order, and keyboard-accessible behavior.
- Text fits on narrow and desktop viewports. - Text fits on narrow and desktop viewports.
- Loading, empty graph, fetch failure, and missing Cytoscape states are - Loading, empty graph, fetch failure, and missing Cytoscape states are
@@ -179,7 +214,34 @@ Acceptance notes:
- Identify remaining Fabric-specific assumptions in the UI shell. - Identify remaining Fabric-specific assumptions in the UI shell.
- Confirm which controls should be manifest-driven before extraction. - Confirm which controls should be manifest-driven before extraction.
- Confirm that user-facing node and edge terminology can be supplied through
manifest labels or host-provided vocabulary without leaking Fabric internals.
- Confirm that the rule-panel data model can support repo-scoping manifests as
well as Fabric ecosystem manifests.
- Update `docs/graph-explorer-operations.md` or contract docs with any refined - Update `docs/graph-explorer-operations.md` or contract docs with any refined
engine boundary. engine boundary.
- Recommend whether the next workplan should be repo-scoping adapter parity or - Recommend whether the next workplan should be repo-scoping adapter parity or
one more Fabric-side UI hardening pass. one more Fabric-side UI hardening pass.
### T07 - Orientation Workflow Polish
```task
id: RAIL-FAB-WP-0009-T07
status: todo
priority: medium
state_hub_task_id: "6cf1fb8b-9d50-4550-942a-69bc29d14eaa"
```
Make the Fabric-specific orientation workflows easier to use for service
dependencies, interface consumers, onboarding gaps, unresolved dependencies,
and saved operational contexts after the node, edge, and rule controls are in
place.
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.
- Orientation workflows reuse the same hide/remove, node type, edge type, and
selection anchor semantics as the rest of the map.