Reviewer Guide: Image Upload Use Cases

A step-by-step guide for Subject Matter Experts reviewing the Item Image Upload use case stories in Storybook. This guide assumes deep domain knowledge of inventory management workflows but no prior experience with Storybook, Agentation, or Hypothesis.

What You Are Reviewing

The Storybook contains high-fidelity mock-ups of how image upload will work in the Arda application. These are not live production screens — they are interactive prototypes built from the actual UI components that will ship. Your review determines whether the workflows match what customers need before engineering builds the real feature.

The stories cover three areas:

1. Setting an image — uploading a file, pasting from clipboard, entering a URL, previewing, cropping, and confirming
2. Removing an image — deleting an image from an entity and reverting to a placeholder
3. Viewing images — thumbnails in grids, hover preview, full-size inspection, and error states (broken links, missing images)

These behaviors apply to any entity with an image field. The stories use Items as the concrete example since that is the first entity type to get image support.

Getting Started

Accessing Storybook

Open the Storybook at arda-cards.github.io/ux-prototype. This is the published site — no local setup needed.

Finding the Use Case Stories

1. Look at the left sidebar. It shows a tree of sections.

2. Expand Use Cases.

3. Expand General Behaviors > Entity Media. This is where the image upload stories live.

4. You will see three groups:

   • GEN-MEDIA-0001 Set Entity Image — the main upload flow (7 sub-sections)
   • GEN-MEDIA-0002 Remove Entity Image — the removal flow
   • GEN-MEDIA-0003 View Entity Image — grid display, inspection, error states

5. Under Reference > Items, you will find:

   • ITM-0003 Create Item > 0010 Set Image — image upload in the context of creating a new item
   • ITM-0004 Edit Item > 0006 Change or Remove Image — image change and removal in the context of editing an item

Understanding the Sidebar Structure

Each use case is organized as:

Use Case Name
├── Description          ← Start here. Read what the scenario does.
├── Scenario 1
│   ├── Description      ← What this specific interaction covers
│   ├── Story Name (Interactive)
│   ├── Story Name (Stepwise)
│   └── Story Name (Automated)
├── Scenario 2
│   └── ...

Always start with the Description page for each section. It links to the full product specification and lists all scenarios with their implementation status.

Three Ways to Experience Each Story

Every scenario has up to three variants. Each shows the same workflow differently:

Interactive

What it is: A live, working prototype. You interact with it exactly as a real user would — click buttons, drag files, type URLs, hover over elements.

When to use it: When you want to explore the workflow yourself, try edge cases, or see how the UI responds to your actions.

How to use it: Just click and interact. The guide panel below the prototype shows what you should do at each step.

Stepwise

What it is: A guided walkthrough that shows the workflow one scene at a time. Each scene is a frozen snapshot with a description of what is happening.

When to use it: For design reviews, walkthroughs with stakeholders, or when you want to study each step without worrying about getting the interactions right.

How to use it: Click Next and Previous buttons below the scene to move through the workflow. A counter shows your position (e.g., “Scene 3 of 7”). Click Reset to go back to the beginning.

Automated

What it is: The workflow plays through automatically with pauses between each step, like a slow-motion demo. The scene description panel updates as each step plays.

When to use it: For a quick overview of the entire flow, or to show someone the workflow without manual interaction.

How to use it: Just watch. The story advances every 2 seconds.

Playground

Some scenarios also include a Playground variant. This is a sandbox where you can change settings using the Controls panel on the right side of the screen. For example, you can toggle between a loaded image, a broken image, or no image to see how the UI handles each state.

What to Look For

As a Subject Matter Expert, focus on whether the workflows match real customer needs. Here are the key questions for each area:

Set Entity Image (GEN-MEDIA-0001)

• Input methods (0002): Can a user provide an image the way they would in practice? Is file upload, clipboard paste, and URL entry sufficient? Is anything missing?
• Validation messages (0003, 0004): Are the error messages clear to a non-technical user? Would a warehouse worker understand “This file type isn’t supported. Try a JPEG, PNG, WebP, or HEIC image.”?
• Preview and crop (0005): Is the 1:1 (square) crop ratio right for product images? Is the comparison layout useful when replacing an existing image?
• Copyright acknowledgment (0006): Is the checkbox wording appropriate? Is it too aggressive? Not strong enough?
• Grid inline edit (0007): Can a user edit an image directly from the grid without opening a separate form? Is double-click discoverable?

Remove Entity Image (GEN-MEDIA-0002)

• Is the confirmation dialog clear? Does it prevent accidental deletion without being annoying?
• Does the placeholder after removal make sense?

View Entity Image (GEN-MEDIA-0003)

• Are the thumbnails in the grid useful at that size?
• Is the hover preview helpful or distracting?
• Does the error badge (broken image) communicate the right thing? Would a user know what to do?
• Does the inspector overlay (click to see full size) work as expected?

Item Integration (REF-ITM)

• Does the image field fit naturally in the Add Item form?
• Is the grid inline edit workflow intuitive?
• Does image removal from the detail panel feel right?

Providing Feedback

You have three ways to provide feedback, from simplest to most structured:

Option 1: Talk to the Team

The simplest approach. Note what you see and discuss it in your next meeting or Slack thread. Reference the specific story by its name in the sidebar (e.g., “In GEN-MEDIA-0001 > 0002 Input Detection > File Pick, the upload button label should say…”).

Option 2: Hypothesis Annotations (Persistent Comments)

Hypothesis lets you attach comments directly to story pages that the whole team can see and discuss. It works like Google Docs comments but for any web page.

Setup (one time):

1. Create a free account at hypothes.is/signup
2. Ask the team to add you to the arda-products group
3. See the documentation site commenting guide for detailed setup instructions

Using Hypothesis:

1. Look for the small < tab on the right edge of the Storybook page
2. Click it to open the Hypothesis sidebar
3. Select text on the page and click Annotate to leave a comment
4. Or click New page note to leave a general comment about the story
5. Your comments are visible to everyone in the arda-products group

Option 3: Agentation (Element-Level Annotation)

Agentation is a tool built into Storybook that lets you click on specific UI elements and attach feedback to them. It is more precise than Hypothesis — you can point at a button, a label, or an error message and say exactly what should change.

How to use Agentation:

1. Click the chat bubble icon in the Storybook toolbar (top of the page), or press Ctrl+Shift+A
2. A translucent overlay appears on the story
3. Click any element to select it — it highlights in blue
4. Write your comment and select an intent:
   • fix — something is wrong
   • change — it works but should be different
   • question — you need clarification
   • approve — this is correct
5. Select a severity: blocking, important, or suggestion
6. Click Copy feedback to save your annotations — they are automatically posted to Hypothesis for the team to see

For detailed instructions, see the Providing Feedback page in the Storybook Docs section, and the Agentation reference page.

Reference: Use Case Specifications

Every story links back to its full product specification in the documentation site. These specifications contain the detailed acceptance criteria, error messages, and behavioral rules that the stories implement.

Area	Specification
Entity Media behaviors	Entity Media Use Cases
Item-specific behaviors	Item Behaviors
Scoping decisions	Scoping
Decision log	Decision Log
User personas	Personas

When reviewing, keep in mind the personas who will use this feature:

• Irene Itemsworth (Inventory Manager) — manages the item catalog, uploads product images when setting up new items
• Sam Scansworth (Shop Floor Worker) — sees images on Kanban cards and item lists, does not typically upload images
• Owen Ownerton (Business Principal) — wants the catalog to look professional with consistent product imagery

What Is Not Included

The following are explicitly out of scope for this review round:

• Background removal from images
• Bulk image upload via CSV
• Server-side fetch-and-store of external URLs
• Detailed mobile camera UX (tap targets, viewfinder)
• Image retention/cleanup policies
• Cross-tenant image sharing

These are documented as deferred items in the scoping decisions. If you believe any of these should be reconsidered, note it in your feedback.

Tips for Efficient Review

1. Start with Stepwise mode for your first pass through each scenario. It is the fastest way to understand what each workflow does.
2. Switch to Interactive mode when you want to explore edge cases or try something the automated walkthrough does not cover.
3. Focus on the GEN-MEDIA-0001 stories first — they cover the core upload flow. The other use cases (remove, view, item integration) are simpler and build on the same patterns.
4. Read the Description page before diving into stories. It tells you what each scenario covers and links to the specification.
5. Use Hypothesis page notes for general comments and Agentation for specific element-level feedback. Both are visible to the whole team.

---

Copyright: (c) Arda Systems 2025-2026, All rights reserved