Eve library

OSHUN V1 Dense-Data Admin Ergonomic Rules

Guide

Revision 1

On this page

Status: Accepted v1.0
Owner: OSHUN Design + Product + Engineering
Last Updated: March 26, 2026
Implements: V1-UX-065
Related:

  • docs/releases/v1/specs/web-app-admin-v1-prd.md
  • docs/releases/v1/specs/layout-density-tiers.md
  • docs/releases/v1/scope/action-placement-rules.md
  • docs/releases/v1/scope/card-avoidance-rules.md
  • docs/releases/v1/specs/ergonomic-budgets.md
  • docs/releases/v1/specs/shared-component-accessibility-standards.md
  • docs/adr/ADR-0068-oshun-admin-severity-and-queue-state-ui-behavior.md
  • apps/oshun/web/src/design-system/components/AdminQueueRow.tsx
  • apps/oshun/web/src/design-system/components/AdminQueueFilter.tsx
  • apps/oshun/web/src/design-system/components/PolicyDiffPanel.tsx
  • apps/oshun/web/src/design-system/components/PolicyEditPanel.tsx
  • apps/oshun/web/src/design-system/components/ReviewDecisionControl.tsx
  • apps/oshun/web/src/components/studio/StudioBellonaBuildQueueTrackingWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioBellonaContentAddressableBuildCacheWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioBellonaFormatRegistryWorkspace.tsx
  • apps/oshun/web/src/components/studio/StudioBellonaVirtualProductionCameraTrackingWorkspace.tsx
  • docs/releases/v1/specs/todos.md

1. Purpose#

This document defines the canonical ergonomics rules for dense-data admin surfaces in OSHUN V1, especially:

  • tables
  • queue rows
  • diff views
  • compare panels
  • keyboard-first workflows

The goal is not to make operator surfaces sparse.

The goal is to make dense surfaces fast, low-noise, and repeatable under long sessions without turning them into dashboard clutter or keyboard-hostile forms.

2. Current Repo Signals, External Scan, And Gap#

The current repo already contains strong operator patterns:

  • the admin PRD explicitly requires keyboard-driven queue triage, side-by-side evidence review, and safe bulk actions
  • AdminQueueRow.tsx already treats queue rows as label-first rails rather than decorative cards
  • AdminQueueFilter.tsx and ReviewDecisionControl.tsx already support compact labeled controls with helper text instead of oversized form treatment
  • PolicyDiffPanel.tsx already compares baseline versus current state in a structured way instead of prose summaries
  • representative Studio workspaces already expose keyboard listbox patterns, aria-activedescendant, row focus movement, live-region notices, and explicit help text for Arrow/Home/End/Enter/Space interaction
  • existing density, card-avoidance, and admin-state docs already frame operator work as scan-first, keyboard-first, and panel-based rather than tile-based

External implementation research reinforces the same model:

  • WAI-ARIA Authoring Practices treats grid, listbox, roving-tabindex, and aria-activedescendant patterns as the canonical keyboard foundation for dense composite widgets
  • WAI-ARIA guidance also stresses that focus and selection must remain visually distinct and that focused rows or cells must be scrolled into view
  • Atlassian’s current design guidance describes dynamic tables as row-oriented data surfaces with built-in sorting and pagination rather than decorative summary tiles
  • Atlassian’s focusable guidance emphasizes explicit, visible keyboard focus as a first-class interaction signal

Inference from those sources plus the repo state:

  • OSHUN has the right building blocks for operator-grade density.
  • OSHUN still needs one governing rule set that explains how dense-data panels should be composed so queue rows, filters, inspectors, diffs, compare lanes, and keyboard shortcuts work as one coherent cockpit.

3. Canonical Thesis#

Dense-data admin surfaces in OSHUN should feel like instruments, not dashboards.

They should be:

  • compact
  • structured
  • label-first
  • keyboard-credible
  • detail-rich without being noisy

They should not be:

  • box-heavy
  • banner-heavy
  • hover-dependent
  • mouse-only
  • visually flat about state importance

4. Core Rules#

4.1 One Dominant Scan Lane#

Every dense surface still needs one primary scan lane.

Typical dominant lanes:

  • queue or table list
  • diff summary
  • selected-item detail
  • compare subject column

If multiple regions compete equally for first attention, the surface is too noisy.

4.2 Rows Must Read Before They Decorate#

Queue rows and table rows should prioritize:

  1. object identity
  2. operational state
  3. key timing or ownership metadata
  4. next safe action

Rows should not require the user to decode color or iconography before they know what the row is.

4.3 Density Comes From Compression, Not From Smaller Targets#

Dense admin surfaces may compress:

  • spacing
  • label length
  • repeated helper copy
  • panel padding

They must not compress:

  • focus visibility
  • minimum touch/click targets
  • state clarity
  • action separation

4.4 Keyboard-First Means Real Workflow Coverage#

Keyboard-first is not satisfied by tabbing through every control.

Operator surfaces should provide accelerated patterns such as:

  • Arrow navigation through rows
  • Home and End jumps
  • Enter to open detail or execute the focused default action
  • Space to toggle row selection when relevant
  • command palette or shortcut entry for high-frequency functions

4.5 Focus And Selection Must Be Different Signals#

Focused state answers where the keyboard is.

Selected state answers what the operator is acting on.

Do not collapse these into one visual treatment.

4.6 State Labels Beat Color-Only Signaling#

Admin surfaces must keep label-first state grammar:

  • Blocked queue
  • Critical severity
  • Approved
  • Changes requested

Color may reinforce the signal, but it cannot replace the label.

4.7 Keep Actions Near The Data They Act On#

High-frequency actions should sit:

  • inline with the row
  • in the row detail panel
  • in a sticky bulk-action summary tied to current selection

They should not live only in distant top-right toolbars.

5. Tables And Queue Rows#

5.1 Row Anatomy#

A canonical admin row should expose, in stable order:

  • name or identifier
  • current operational state
  • one or two critical metadata points
  • immediate action affordance or entry to detail

If every row has a different internal order, scan speed collapses.

5.2 Stable Height Beats Micro-Optimization#

Dense rows may be compact, but the default row height should remain stable across the visible list.

Avoid:

  • wildly expanding rows by default
  • metadata wrapping that changes rhythm unpredictably
  • hidden action clusters that appear only on hover

5.3 Bulk Operations Need A Separate Control Plane#

Bulk actions should appear only after selection and should live in:

  • a sticky summary bar
  • a compact secondary rail
  • or a contextual action cluster adjacent to the list

Do not duplicate bulk actions inside every row.

5.4 Empty And Filtered States Stay In The List Region#

When a filter returns no results, the empty state should render inside the list or table region, not replace the whole cockpit.

Dense work should preserve surrounding filters, saved views, and detail context.

6. Diff Views#

6.1 Compare Structured Values, Not Paragraphs#

Diff surfaces should align:

  • baseline
  • current
  • changed status
  • rationale or detail

Structured comparison is canonical. Narrative summary alone is not.

6.2 Changed Fields Rise To The Top#

Default diff posture:

  • changed fields first
  • unchanged fields collapsible or secondary

The operator’s first question is what drifted, not what stayed the same.

6.3 Parallel Columns Must Preserve Meaning#

Baseline and current values should sit in parallel columns or equivalent aligned rows.

Do not stack long before/after prose blocks if the values are meant to be compared field by field.

6.4 Use Tone Sparingly#

Tone in diffs should emphasize:

  • added or allowed
  • removed or blocked
  • risky drift

Do not flood every changed field with heavy warning fills. Operators need contrast, not alarm wallpaper.

7. Compare Panels#

7.1 One Primary Subject, One Comparison Partner#

Compare panels should not become a six-card mosaic.

The canonical compare posture is:

  • one primary subject
  • one secondary comparison subject
  • one compact summary or decision rail

7.2 Shared Axes Must Stay Locked#

When comparing:

  • policy versions
  • evidence bundles
  • queue snapshots
  • asset states

the comparison categories and order must stay aligned across panes.

7.3 Independent Scroll Needs Guard Rails#

If compare panes scroll independently, the surface must preserve:

  • visible pane titles
  • stable anchors
  • quick return to matched sections

Independent scroll is acceptable only when it improves review fidelity rather than creating drift.

8. Keyboard-First Workflow Rules#

8.1 Preferred Navigation Model#

For dense selectable lists, prefer:

  • listbox or grid semantics where appropriate
  • roving tabindex or aria-activedescendant
  • explicit help text for available shortcuts

This matches both current repo patterns and WAI-ARIA guidance.

8.2 Minimum Keyboard Contract#

If a dense-data operator list is keyboard-enabled, it should usually support:

  • ArrowUp and ArrowDown
  • Home and End
  • Enter
  • Space when selection is separate from opening detail
  • a live region or equivalent feedback for important keyboard actions

8.3 Focus Must Scroll Into View#

Keyboard movement that changes the active row or cell must also keep the active target visible.

The user should not lose the focus target off-screen.

8.4 Shortcuts Need Visible Discovery#

If shortcuts exist, surfaces should expose them through:

  • a help line
  • command palette hint
  • accessibility QA section
  • or visible menu disclosure

Hidden shortcuts alone are not sufficient.

9. Panel Composition Rules#

9.1 Two Or Three Regions Is The Norm#

Operator dense-data surfaces should usually resolve into:

  • list plus detail
  • list plus detail plus compact summary rail
  • diff plus edit panel

More regions are allowed only when each one has a sharply different job.

9.2 Headers Must Stay Short#

Dense-data surfaces need short headers so the viewport is reserved for work.

Long explanatory paragraphs belong in docs drawers, progressive disclosure, or secondary runbook panels.

9.3 No Card Mosaics For Operator Work#

Tables, queues, diffs, and compare panels are first-class layout primitives.

Do not translate operator data into a dashboard of peer cards just to make the surface look designed.

10. Do And Do Not Examples#

10.1 Queue Rows#

  • do: keep state badges, row identity, and next actions in one stable scan line
  • do not: scatter row meaning across unrelated chips, icons, and hover-only actions

10.2 Diff Review#

  • do: show baseline and current values in aligned structure
  • do not: summarize changes only in prose paragraphs

10.3 Keyboard Flows#

  • do: expose Arrow/Home/End/Enter patterns with visible focus and live feedback
  • do not: claim keyboard-first support when the operator still has to tab through every control

10.4 Compare Panels#

  • do: preserve one primary subject, one comparison subject, and one decision rail
  • do not: turn compare into a many-panel dashboard collage

10.5 Bulk Actions#

  • do: reveal bulk actions from current selection state
  • do not: repeat bulk controls inside every row

11. Definition Of Done#

Dense-data admin ergonomics is complete for a surface only when:

  • one dominant scan lane is obvious
  • row identity, state, and action are co-located
  • diff and compare structures align values rather than narrating them vaguely
  • keyboard navigation supports real task acceleration
  • focus and selection are distinct and visible
  • bulk action posture is contextual and compact
  • the surface relies on panels, rows, tables, and inspectors instead of card mosaics