Skip to content

docs(#48): finalize phase 1 UX layout and interaction proposal #46

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
OmarEhab007 merged 2 commits into from
Apr 20, 2026
Merged

docs(#48): finalize phase 1 UX layout and interaction proposal #46

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
ec1eec1
docs(#40): finalize phase 1 UX layout handoff draft
OmarEhab007 Apr 20, 2026
35d5eea
docs(#40): add phase 2 guardrails and sign-off block
OmarEhab007 Apr 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
141 changes: 126 additions & 15 deletions docs/plans/2026-04-20-phase-1-ux-audit-ia-proposal-draft.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,25 +1,22 @@
# Phase 1 Deliverable: UX Audit and Information Architecture Proposal (IA v0.2)
# Phase 1 Deliverable: UX Layout and Interaction Proposal (IA v1.0)

**Date**: 2026-04-20
**Ticket**: [https://github.com/OmarEhab007/RemedyIQ/issues/30](https://github.com/OmarEhab007/RemedyIQ/issues/30)
**Parent Epic**: [https://github.com/OmarEhab007/RemedyIQ/issues/28](https://github.com/OmarEhab007/RemedyIQ/issues/28)
**Status**: Draft v0.2 (working)
**Ticket**: [https://github.com/OmarEhab007/RemedyIQ/issues/40](https://github.com/OmarEhab007/RemedyIQ/issues/40)
**Parent Epic**: [https://github.com/OmarEhab007/RemedyIQ/issues/38](https://github.com/OmarEhab007/RemedyIQ/issues/38)
**Related PRD**: `projects/RemedyIQ/prd-dashboard-rebuild-ops-admin.md`
**Status**: In Progress (ticket #40)

---

## 0) Issue #30 Acceptance Criteria Traceability
## 0) Issue #40 Acceptance Criteria Traceability


| Issue #30 Acceptance Criteria | Status | Evidence in this Draft |
| Issue #40 Acceptance Criteria | Status | Evidence in this Draft |
| ------------------------------------------------------------------------ | ------ | ----------------------------------- |
| UI audit classifies all major elements into core vs secondary | Done | Sections 2, 3, and 5.5 |
| IA proposal for dashboard and navigation hierarchy is published | Done | Sections 4 and 5 |
| Final IA decisions are recorded by 2026-05-01 | Done | Section 10 (finalized decision log) |
| Frontend feasibility review is completed against current architecture | Done | Section 7 |
| Required component refactors and shared primitives are identified | Done | Section 11 |
| Current event coverage is mapped to proposed IA journeys | Done | Sections 8 and 12 |
| Tracking gaps blocking KPI measurement are identified | Done | Sections 8 and 12 |
| Scenario matrix is drafted for system admin and operations lead personas | Done | Section 6 |
| UX proposal reviewed with product owner | In Progress | Sections 4, 5, 10 |
| Table and card behavior documented for desktop breakpoints | In Progress | Sections 5.2, 5.8, 11 |
| Graph/table layout rules approved for frontend implementation | In Progress | Sections 5, 11 |
| Handoff notes attached for implementation | In Progress | Sections 11, 13, 14 |


---
Expand Down Expand Up @@ -529,4 +526,118 @@ Phase 1 validation checkpoints:

1. Maintain dual-read dashboard until two full weekly windows show stable event parity.
2. Reject releases where mandatory event properties fall below 99% population.
3. Publish a versioned event dictionary changelog with each Phase 1 release increment.
3. Publish a versioned event dictionary changelog with each Phase 1 release increment.

---

## 15) Frontend Handoff Package (for Issue #41)

### 15.1 Dashboard Layout Contract (Desktop-First)

**Target desktop breakpoints**

- `xl` (>= 1280px): no frequent horizontal scrolling in primary dashboard views.
- `lg` (>= 1024px): critical KPI cards remain readable with no text overflow.
- `md` (< 1024px): controlled wrapping/stacking is allowed, but core workflow actions remain visible.

**Row composition rules**

1. **Row 1 (KPI Cards)**: health + key metric cards only; fixed visual rhythm and overflow-safe text.
2. **Row 2 (Activity + Distribution)**: throughput trend and log-type distribution side-by-side on `xl`, stacked on lower breakpoints.
3. **Row 3 (Top Entries + Workflow Table)**: top-N view and table view aligned as paired analysis surfaces.
4. **Deep diagnostics**: excluded from dashboard surface; route users to Log Explorer for deep investigation.

### 15.2 Card Behavior Rules

- Card titles and values must never escape container bounds.
- Truncation + tooltip pattern required for long labels.
- Numeric hierarchy: value first, supporting label second.
- Avoid paragraph-length explanatory text inside cards.

### 15.3 Table Behavior Rules

- Define column-priority tiers (`P0`, `P1`, `P2`) per workflow table.
- `P0` columns remain visible at `lg` and above.
- Horizontal scroll is allowed only as fallback after priority rules and width constraints are applied.
- Sticky headers and consistent row density required for scanability.

### 15.4 Graph and Table Co-location Rules

- Charts and corresponding tables should share the same section when they support the same question.
- Chart legends and table dimensions must use matching labels.
- Avoid mixing unrelated graph/table pairs in one row.

### 15.5 Build-Ready Task Breakdown (Phase 2 Input)

1. Implement new dashboard section order and row contract.
2. Refactor KPI cards for overflow-safe typography and spacing.
3. Apply column-priority strategy to primary tables.
4. Align chart/table pairs based on workflow context (API, SQL, Escalation, Filter).
5. Validate no backend contract changes are required.

### 15.6 Definition of Done for Phase 1 Handoff

- [x] Core-vs-secondary IA documented.
- [x] Navigation and transition matrix finalized.
- [x] Desktop breakpoint behavior documented for cards/tables/layout.
- [x] Frontend-ready task inputs written for issue #41.
- [ ] Product owner sign-off comment captured on issue #40.

### 15.7 Product Review Checklist (Issue #40 Sign-off)

- Confirm row composition order (KPI cards -> charts -> top entries/tables).
- Confirm top-card text treatment (truncate + tooltip) is acceptable.
- Confirm table column-priority strategy matches ops/admin needs.
- Confirm chart/table pairing rules are clear for frontend implementation.
- Confirm "deep diagnostics -> Log Explorer" guidance is acceptable for Phase 1 scope.

---

## 16) Implementation Constraints and Guardrails (Phase 2)

### 16.1 Must-Preserve Constraints

- No backend API, schema, or data-contract changes.
- No net-new data dependencies for dashboard rendering.
- Existing core workflows (API, SQL, Escalation, Filter) must remain functionally intact.
- Existing auth/permissions behavior must remain unchanged.

### 16.2 Release Guardrails

- Do not ship layout changes that increase median click depth for any core workflow.
- Do not ship if KPI events lose required fields (`workflow_type`, `entry_surface`, `role`).
- Do not merge Phase 2 UI changes without updated screenshots for desktop breakpoints.
- Do not deprecate dashboard affordances until equivalent Investigate links are verified.

### 16.3 Known Risks and Mitigations

| Risk | Impact | Mitigation |
|------|--------|------------|
| Card compaction reduces context clarity | Users may misread KPIs | Keep concise helper text and tooltip support |
| Table priority hides fields some teams rely on | Slower investigations for edge cases | Validate column priorities with ops/admin reviewers before freeze |
| Chart/table co-location introduces dense rows | Reduced readability on medium screens | Enforce breakpoint stack behavior and spacing tokens |
| Event contract drift during implementation | KPI comparison invalidated | Add event payload checks to QA validation checklist |

---

## 17) Phase 1 Sign-off Block (Issue #40)

### Required approvals

- Product owner approval (issue #40 comment)
- UX approval that IA and interaction rules are complete
- Frontend lead confirmation that handoff is implementation-ready

### Sign-off template

Use this in issue `#40`:

`Approved for Phase 2 build. IA v1.0 and UX interaction handoff accepted.`

### Handoff completion checklist

- [x] IA hierarchy and transitions documented
- [x] Layout and breakpoint behavior documented
- [x] Card/table/graph behavior rules documented
- [x] Phase 2 task breakdown documented
- [ ] Approval comment posted on issue #40
Loading