---
stepsCompleted: [1, 2, 3, 4, 5, 6, 7, 8]
inputDocuments: ["/var/www/html/ai_cats/_bmad-output/planning-artifacts/prd.md", "/var/www/html/ai_cats/_bmad-output/planning-artifacts/architecture.md", "/var/www/html/ai_cats/_bmad-output/project-context.md"]
---

# UX Design Specification AI-Assisted Product Categorization System

**Author:** Sayre
**Date:** 2026-05-19

---

<!-- UX design content will be appended sequentially through collaborative workflow steps -->

## Executive Summary

### Project Vision

An internal, self-hosted operational tool for product data stewards and system administrators to manage AI-assisted product categorization at scale. The system automates high-confidence categorization decisions (≥90%) and routes lower-confidence predictions into Akeneo Collaborative Workflow for human review — with full auditability, explainable evidence, and clear operational status at every step. The UI exists to make this process efficient, trustworthy, and diagnosable.

### Target Users

**Data Stewards (Primary)**
Operational users who upload supplier CSV enrichment data, monitor batch categorization jobs, and review AI predictions routed to Akeneo Collaborative Workflow. They need to quickly understand what needs their attention, why a category was suggested, and what Akeneo workflow action is pending or complete. They process potentially many items and need efficient, scannable interfaces.

**System Administrators (Secondary)**
Configure Akeneo API credentials, set and adjust confidence thresholds, manage user accounts, monitor system health, and troubleshoot failed imports or batches. They need clear configuration panels, system status visibility, and enough diagnostic detail to resolve integration issues without needing to read logs directly.

### Key Design Challenges

1. **Evidence density vs. clarity** — Each prediction must surface enough evidence to be actionable (what data drove this? what attributes are missing?) without overwhelming data stewards who may be reviewing many items in a session.

2. **Confidence-based workflow routing** — The UI must make it immediately obvious which items were auto-approved, which are pending Akeneo workflow action, and what their current Akeneo status is — without requiring users to track state mentally. Status labels must be unambiguous.

3. **Batch job visibility** — Import and categorization jobs are long-running background processes. Users need meaningful, real-time-feeling progress feedback without constant manual page refreshes, and clear summaries when jobs complete or partially fail.

### Design Opportunities

1. **Review queue efficiency** — A well-designed bulk review interface with inline evidence and compact filtering could dramatically reduce time-per-item for data stewards, making the human-review workflow feel fast rather than burdensome.

2. **Trust-building through inline evidence** — Surfacing evidence directly in the review list (not hidden behind modals) helps data stewards build calibrated trust in AI recommendations over time and speeds up approval decisions.

3. **Proactive exception surfacing** — A dashboard that surfaces actionable exceptions (failed imports, stuck batches, Akeneo rejections needing re-review) before users go looking turns a reactive monitoring tool into a proactive workflow assistant.

## Core User Experience

### Defining Experience

The core user action is **reviewing AI categorization predictions for products sourced from Akeneo and deciding what to submit to Akeneo Collaborative Workflow vs. what to adjust**. Products flow in from Akeneo via API — they are not uploaded by the user. The data steward's job is to manage the prediction review queue and ensure clean, confident categorizations make it back into Akeneo through the approved workflow.

The one action that must be completely effortless: **understanding at a glance why a prediction was made and whether to trust it** — without leaving the list view.

### Platform Strategy

Desktop web application — internal tool, mouse and keyboard, modern browser. No mobile requirement. No offline functionality. No special device capabilities. Server-side rendered PHP with JavaScript for interactive elements (status polling, bulk actions, AJAX updates).

### Effortless Interactions

- Opening the review queue and immediately seeing only items that need a human decision (not auto-approved items — those are done)
- Understanding a prediction's confidence score and top evidence without opening a detail view
- Submitting a group of low-confidence items to Akeneo Collaborative Workflow in one action
- Importing a CSV enrichment file and immediately knowing whether it was valid and what job was created
- Knowing the current status of any batch without refreshing — statuses poll automatically

### Critical Success Moments

1. **First successful Akeneo sync + categorization** — products are pulled from Akeneo, AI predictions are generated with confidence scores and evidence, and the data steward can see and act on the review queue immediately
2. **First round-trip completion** — low-confidence items are submitted to Akeneo Collaborative Workflow, Akeneo approvals/rejections come back, and the system reflects those outcomes automatically without the steward having to check Akeneo manually
3. **Diagnosing a failed batch or import** — the steward can identify exactly what went wrong (which rows, which API calls, which products) from the UI alone, without needing a developer or server log access

### Experience Principles

1. **Surface what needs action, hide what doesn't** — The default view is the work queue: items requiring a human decision. Auto-approved items and completed batches are history, not the working view.
2. **Evidence earns trust** — Every AI prediction shows its reasoning inline. A reviewer should never need to approve a category on faith alone.
3. **Status is never ambiguous** — Every product, batch, and Akeneo workflow item has exactly one clear, human-readable status. No inferring required.
4. **Errors are diagnosable without escalation** — Any import failure, batch error, or Akeneo API issue must be understandable from the UI. Data stewards should not need to involve a developer for routine troubleshooting.
5. **Akeneo is the system of record** — This tool prepares and routes decisions; Akeneo owns the final approved state. The UI reflects what Akeneo says, not just what was submitted.

## Desired Emotional Response

### Primary Emotional Goals

**Primary: Confident and in control**

A data steward should feel they are making *informed* decisions, not rubber-stamping AI output. The evidence system, clear status labels, and transparent confidence scores are all in service of this — they make the steward feel like the expert in the loop, not a bottleneck in a black-box process.

**Secondary feelings:**
- **Productive and efficient** — the queue clears, work moves forward, batches complete without hand-holding
- **Calm, not anxious** — especially around Akeneo submissions and auto-approved items
- **Competent** — errors are explainable without needing a developer; the steward feels capable of diagnosing and resolving routine issues themselves

**Emotions to avoid:**
- **Anxiety** — "Did I approve something wrong? Did my submission actually reach Akeneo?"
- **Confusion** — "What does this status mean? Is this waiting on me or waiting on Akeneo?"
- **Overwhelm** — seeing everything at once instead of what needs action
- **Distrust** — predictions with no visible reasoning force blind approval

### Emotional Journey Mapping

| Stage | Target Feeling | Design Support |
|---|---|---|
| Opening the tool | Oriented, focused | Default view = work queue, not a summary of everything |
| Reviewing a prediction | Informed, in control | Inline evidence, confidence score, missing attributes visible |
| Submitting to Akeneo workflow | Calm confidence | Clear confirmation, status updates automatically |
| Akeneo approves/rejects | Satisfied closure | Outcome reflected automatically, no manual checking |
| Something goes wrong | Informed, not panicked | Human-readable errors with actionable guidance |
| Returning after absence | Reliable familiarity | Consistent UI, predictable behavior, no surprises |

### Micro-Emotions

- **Trust vs. Skepticism** — Evidence inline tips the balance toward trust; thin evidence should visually signal that skepticism is warranted
- **Confidence vs. Confusion** — Every status label must eliminate ambiguity; "Awaiting Akeneo Approval" is better than "Submitted"
- **Accomplishment vs. Frustration** — A visible queue counter and completion states make progress feel tangible
- **Calm vs. Anxiety** — Auto-polling removes the need to refresh; confirmations remove the "did it work?" loop

### Design Implications

- **Confidence** → confidence scores with visual treatment (color/badge) scaled to certainty level; never just a raw percentage
- **Trust** → evidence displayed inline in the review list, not behind a click
- **Calm** → predictable auto-refresh, explicit status transitions, no silent failures
- **Accomplishment** → queue progress indicators, clear "all done" empty states
- **Competent** → error messages written for data stewards, not developers (e.g., "Row 47: part number '1234AB' could not be matched — check supplier column name" not "DB constraint violation")

### Emotional Design Principles

1. Never make a steward wonder if their action worked — confirm it
2. Never show an error that doesn't tell the steward what to do next
3. Confidence scores mean nothing without the evidence that earned them
4. A clear queue is the reward — make progress visible at all times

## UX Pattern Analysis & Inspiration

### Inspiring Products Analysis

**GitHub Issues / Linear — work queue management**
Clear status, assignee, and priority visible in list view. Enough context to act without clicking through. Fast filtering. "My queue" vs. "everything" is a first-class distinction. Bulk actions feel natural.

**Datadog / Grafana — operational dashboards**
System state understandable at a glance. Status is color-coded and unambiguous. Alerts surface exceptions rather than requiring users to hunt. Time-series context available without overwhelming the default view. Muted palettes handle dense data without visual fatigue.

**Sentry — error management for triage**
Each error has a clear summary, a stack of context, and an obvious action. "Resolved / Ignored / Active" states are unambiguous. Users can diagnose issues without needing raw logs. Error messages are translated into human-readable summaries.

### Transferable UX Patterns

**Navigation Patterns:**
- **Queue-first navigation** (GitHub/Linear) — primary nav item is "needs review," not "all products"
- **Status filter tabs** (Linear) — quick toggle between "awaiting review / submitted / approved / rejected" without a full filter panel

**Interaction Patterns:**
- **Bulk select + floating action bar** (GitHub Issues) — checkbox selection with a contextual action bar for submitting selected items to Akeneo workflow
- **Inline expandable evidence** (Sentry) — expand a row to see the full evidence trail without leaving the list view
- **Auto-refreshing status** (Datadog) — live-updating batch progress without manual page reload

**Visual Patterns:**
- **Confidence badge** (inspired by Sentry severity levels) — color-coded badge (green/yellow/red) for confidence level; communicates certainty at a glance without reading numbers
- **Muted dark-capable palette** (Datadog/Grafana) — dense operational data without visual fatigue; status colors pop against neutral backgrounds
- **Empty state as reward** (Linear) — "Nothing left to review" is a positive completion state, not just a blank page

### Anti-Patterns to Avoid

- **Modal-heavy detail views** — forcing click-through to see evidence breaks review flow; evidence should be expandable inline
- **Ambiguous status labels** — "Pending" means nothing; "Awaiting Akeneo Approval" means exactly one thing
- **Dashboard-as-homepage** — a summary dashboard as entry point adds an unnecessary navigation hop before data stewards reach their work
- **Toast-only confirmations** — toasts disappear; Akeneo submission confirmations need a persistent status change, not just a 3-second toast
- **Raw technical errors** — "SQLSTATE[23000]" exposed to a data steward is a UX failure; every error needs a human-readable translation

### Design Inspiration Strategy

| | Pattern | Reason |
|---|---|---|
| **Adopt** | Queue-first navigation (Linear) | Matches "surface what needs action" principle |
| **Adopt** | Inline expandable evidence (Sentry) | Keeps reviewers in the list, not drilling in and out |
| **Adopt** | Color-coded confidence badge | Confidence level scannable without reading numbers |
| **Adopt** | Bulk select + floating action bar | Efficient submission of multiple items at once |
| **Adapt** | Operational dashboard (Datadog) | Simplified for non-technical users; focus on batch status and queue count, not raw metrics |
| **Avoid** | Modal-first detail views | Breaks review flow for high-volume queues |
| **Avoid** | Raw system error messages | Conflicts with "diagnosable without escalation" principle |

## Design System Foundation

### Design System Choice

**Bootstrap 5** — CSS/JS component library, vendored or CDN, no build step required.

### Rationale for Selection

- No build tooling required — CSS/JS files drop directly into the PHP project structure
- Dark mode support built in via `data-bs-theme="dark"` on `<html>`
- All required component types are available: tables, badges, cards, forms, nav tabs, progress bars, modals
- Muted neutral palette aligns with the "minimal and clean" UX preference from project context
- Bootstrap 5 CSS variables enable easy customization without fighting the framework
- Low onboarding cost — any developer touching this project will know Bootstrap
- Suitable for dense operational data interfaces (`.table-sm`, expandable rows, filter tabs)

### Implementation Approach

- Vendor Bootstrap 5 CSS and JS into `public/assets/` (no CDN dependency in production)
- Set `data-bs-theme="dark"` as default on `<html>`; optionally expose a user toggle
- Use Bootstrap's grid and utility classes for layout; avoid writing custom layout CSS
- Use Bootstrap JS plugins for dropdowns, modals (used sparingly), and tooltips
- No npm, no webpack, no build pipeline required for Bootstrap itself

### Customization Strategy

| Element | Approach |
|---|---|
| Confidence badges | Custom badge variants (`badge-confidence-high`, `badge-confidence-medium`, `badge-confidence-low`) via Bootstrap color tokens |
| Status labels | Pill badges with fixed color-to-status mapping — never reuse a color for two statuses |
| Dark mode | `data-bs-theme="dark"` default on `<html>` |
| Muted palette | Bootstrap `secondary` and `dark` color scheme as base; override primary accent via CSS variable |
| Dense tables | Bootstrap `.table-sm` with custom row-expand pattern for inline evidence |
| Empty states | Custom styled components within Bootstrap card structure; positive framing ("Nothing left to review") |

## 2. Core User Experience

### 2.1 Defining Experience

**"Review an AI prediction, understand why it was made, and decide in seconds whether to trust it."**

This is the defining interaction. Not the CSV upload, not batch submission — the moment a data steward looks at a predicted category, sees the evidence trail, reads the confidence score, and decides: *yes, I agree* or *no, something's off*. Everything else supports this moment.

### 2.2 User Mental Model

Data stewards think like auditors, not approvers. They're looking to catch mistakes before they enter Akeneo. They bring a mental model shaped by spreadsheet review — scanning rows, looking for anomalies, acting on exceptions. They expect:

- Normal/obvious items already handled (auto-approved at ≥90%)
- Their queue to contain only uncertain or borderline items
- Each item to provide what they need to decide — without additional research

Current solutions (manual categorization, spreadsheet review) are slow and don't explain their reasoning. The defining "magical" moment: *the system tells me why it thinks this is the right category, and it's right.*

### 2.3 Success Criteria

- A steward can scan a row and make a decision in under 10 seconds for clear cases
- Evidence is visible without any click — confidence score + top 2–3 evidence signals inline
- "Submit to Akeneo workflow" is a single action from the review list, not a multi-step process
- After submitting, status updates immediately — no wondering if it worked
- A steward can process a full queue of 50 low-confidence items without leaving the list view

**Success indicators:**
- Queue counter visibly decreases as items are acted on
- "Nothing left to review" empty state reached and celebrated
- Zero items require the steward to open a separate tool to make a decision

### 2.4 Novel UX Patterns

The core interaction uses established patterns — a list view with inline detail expansion and bulk action — with one key adaptation: **evidence is first-class content in the row, not a detail panel.**

Most review tools put detail behind a click. For this product, the evidence *is* the decision-making tool. It must be visible in the list, not hidden behind a modal. This is a conscious deviation inspired by how Sentry shows error context inline — appropriate for a workflow where every item requires a judgment call, not just a status check.

### 2.5 Experience Mechanics

**1. Initiation**
- Data steward lands on the Predictions queue (default navigation destination)
- Queue shows only `needs_review` status items — no noise from auto-approved or completed items
- Row count visible: "14 items awaiting review"

**2. Interaction**
- Each row shows: product name/SKU, suggested category, confidence badge (color-coded), top 2 evidence signals inline
- Checkbox for selection; click row to expand inline evidence trail (full reasoning, missing attributes)
- Bulk select → floating action bar appears: "Submit X items to Akeneo workflow" | "Adjust category"
- Single-item row actions: submit, adjust, skip

**3. Feedback**
- Submitting: row status badge updates immediately to "Submitted to Akeneo Workflow" — no page reload
- Adjusting: inline category picker opens; save confirms with status update
- Error: banner below row with human-readable message and suggested action
- Progress: queue counter decrements with each action

**4. Completion**
- Queue empties → positive empty state: "All predictions reviewed. Nothing waiting on you."
- Summary accessible: how many auto-approved, how many submitted, how many adjusted

## Visual Design Foundation

### Color System

**Inspiration:** GitHub Primer — muted neutrals, purposeful semantic colors, dark-first for operational contexts.

**Implementation:** Bootstrap 5 CSS variable overrides in `public/assets/css/styles.css`.

**Base Palette:**

| Token | Dark Value | Light Value | Usage |
|---|---|---|---|
| `--bs-body-bg` | `#0d1117` | `#f6f8fa` | Page background |
| `--bs-body-color` | `#e6edf3` | `#1f2328` | Primary text |
| `--bs-secondary-color` | `#7d8590` | `#656d76` | Muted/secondary text |
| `--bs-border-color` | `#30363d` | `#d0d7de` | Borders, dividers |
| `--bs-tertiary-bg` | `#161b22` | `#ffffff` | Cards, table rows, surfaces |
| `--bs-primary` | `#1f6feb` | `#0969da` | Primary actions, links |

**Semantic Status Colors:**

| Status | Color | Hex (dark) | Usage |
|---|---|---|---|
| Success / High confidence | Green | `#3fb950` | ≥90% confidence, approved, completed |
| Warning / Medium confidence | Amber | `#d29922` | 70–89% confidence, needs review |
| Danger / Low confidence | Red | `#f85149` | <70% confidence, errors, rejected |
| Info / Neutral status | Blue | `#58a6ff` | Submitted, in-progress, informational |
| Muted / Historical | Gray | `#7d8590` | Auto-approved (done, not actionable) |

**Confidence Badge Mapping:**

| Confidence | Badge Class | Color |
|---|---|---|
| ≥90% (auto-approved) | `badge-confidence-high` | Green |
| 70–89% (needs review) | `badge-confidence-medium` | Amber |
| <70% (needs review) | `badge-confidence-low` | Red |

**Product Status Label Mapping** (one color per status, never reused):

| Status | Color |
|---|---|
| Predicted | Blue (info) |
| Needs Review | Amber (warning) |
| Submitted to Akeneo Workflow | Blue (info) |
| Awaiting Akeneo Approval | Amber (warning) |
| Approved in Akeneo | Green (success) |
| Rejected in Akeneo | Red (danger) |
| Auto-Approved | Muted gray |
| Import Failed | Red (danger) |

### Typography System

**Font stack** (system fonts, Primer-style — no external loading):
```css
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Noto Sans", Helvetica, Arial, sans-serif;
```

**Monospace** (SKUs, part numbers, MPNs):
```css
font-family: "SFMono-Regular", Consolas, "Liberation Mono", Menlo, monospace;
```

**Type scale:**

| Element | Size | Weight | Usage |
|---|---|---|---|
| Page title (h1) | 20px | 600 | Section headers |
| Section header (h2) | 16px | 600 | Card/panel titles |
| Body | 14px | 400 | Table content, labels |
| Small/muted | 12px | 400 | Timestamps, secondary info |
| Badge/pill | 12px | 500 | Status labels, confidence |
| SKU/part number | 13px mono | 400 | Product identifiers |

14px body matches Primer's density preference — more content per screen without feeling cramped.

### Spacing & Layout Foundation

**Base unit:** 8px (Bootstrap default)

**Density:** Compact. Bootstrap `.table-sm` for all data tables. Card padding `p-3`.

**Layout:**
- Fixed left sidebar navigation (220px) + main content area
- Max content width: 1200px centered
- Dashboard: 3-column stat cards + full-width table below
- Review queue: full-width table with expandable rows
- Admin settings: 2-column form layout

**Component spacing:**
- Between cards on dashboard: `gap-3` (24px)
- Between form fields: `mb-3` (16px)
- Between sections: `mb-4` (24px)

### Accessibility Considerations

- All semantic status colors meet WCAG AA contrast ratio against both dark and light backgrounds
- Color never used alone — status labels always pair color with text ("Approved in Akeneo", not just a green dot)
- Confidence badges show both color and percentage value
- Focus indicators preserved (Bootstrap default outlines retained)
- Monospace font for part numbers prevents misreading of similar characters (0/O, 1/l)
- System font stack ensures optimal rendering on all platforms without web font loading