---
phase: 05-image-handling
plan: 01
subsystem: ui
tags: [image-upload, hero-area, zod, tailwind, forms]

# Dependency graph
requires:
  - phase: none
    provides: existing ImageUpload, ItemForm, CandidateForm components
provides:
  - Working image persistence (Zod schema fix)
  - Hero image preview area component
  - Redesigned form layout with image-first UX
affects: [06-category-icons]

# Tech tracking
tech-stack:
  added: []
  patterns: [hero-image-area, inline-svg-icons]

key-files:
  created: []
  modified:
    - src/shared/schemas.ts
    - src/client/components/ImageUpload.tsx
    - src/client/components/ItemForm.tsx
    - src/client/components/CandidateForm.tsx

key-decisions:
  - "Used inline SVGs instead of adding lucide-react dependency -- keeps bundle lean for 3 icons"
  - "Root cause of image bug: Zod schemas missing imageFilename field, validator silently stripped it"

patterns-established:
  - "Hero image area: full-width 4:3 aspect ratio clickable area with placeholder/preview states"

requirements-completed: [IMG-01, IMG-03, IMG-04]

# Metrics
duration: 3min
completed: 2026-03-15
---

# Phase 5 Plan 1: Image Display Fix & Hero Area Summary

**Fixed image persistence bug (Zod schema missing imageFilename) and redesigned ImageUpload as 4:3 hero area at top of item/candidate forms**

## Performance

- **Duration:** 3 min
- **Started:** 2026-03-15T16:08:51Z
- **Completed:** 2026-03-15T16:11:27Z
- **Tasks:** 2
- **Files modified:** 4

## Accomplishments
- Identified and fixed root cause of image display bug: imageFilename was missing from Zod validation schemas, causing @hono/zod-validator to silently strip it from payloads
- Redesigned ImageUpload into a full-width 4:3 hero image area with placeholder, preview, upload spinner, and remove states
- Moved ImageUpload to first element in both ItemForm and CandidateForm, removing redundant labels

## Task Commits

Each task was committed atomically:

1. **Task 1: Fix image display bug and investigate root cause** - `8c0529c` (fix)
2. **Task 2: Redesign ImageUpload as hero area and move to top of forms** - `3243be4` (feat)

## Files Created/Modified
- `src/shared/schemas.ts` - Added imageFilename to createItemSchema and createCandidateSchema
- `src/client/components/ImageUpload.tsx` - Redesigned as 4:3 hero area with placeholder/preview/spinner states
- `src/client/components/ItemForm.tsx` - Moved ImageUpload to top, removed label wrapper
- `src/client/components/CandidateForm.tsx` - Moved ImageUpload to top, removed label wrapper

## Decisions Made
- Used inline SVGs instead of adding lucide-react dependency -- only 3 icons needed, avoids bundle bloat
- Root cause identified as Zod schema issue, not static file serving or Vite proxy (both were working correctly)

## Deviations from Plan

None - plan executed exactly as written.

## Issues Encountered
None.

## User Setup Required
None - no external service configuration required.

## Next Phase Readiness
- Image display and upload flow fully functional
- Hero area component ready for any future image-related enhancements in plan 05-02
- Forms have clean image-first layout

---
*Phase: 05-image-handling*
*Completed: 2026-03-15*