diff --git a/docs/visual-audit/README.md b/docs/visual-audit/README.md new file mode 100644 index 0000000..21230a1 --- /dev/null +++ b/docs/visual-audit/README.md @@ -0,0 +1,64 @@ +# T01 Baseline Visual Audit (Before Redesign) + +Date: 2026-03-26 +Task: T01 — Baseline Visual Audit +Owner: agent-ui-audit + +## Baseline screenshots (captured) + +Saved under `docs/visual-audit/before/`: + +- `home-desktop.png` +- `home-mobile.png` +- `recipe-new-desktop.png` +- `recipe-new-mobile.png` +- `import-url-desktop.png` +- `import-url-mobile.png` +- `recipe-detail-desktop.png` +- `recipe-detail-mobile.png` + +## Capture notes / blockers + +- ✅ Frontend runs at `http://127.0.0.1:4173` and screenshots were captured. +- ⚠️ Backend dev server failed to start (`ERR_MODULE_NOT_FOUND` for `src/backend/db/database.js` from `src/backend/index.ts`). +- Impact: recipe list/detail/import states shown in screenshots are baseline UI without live backend data. + +## Prioritized visual issues by page + +Severity legend: **High** = materially harms UX/clarity, **Medium** = noticeable polish debt, **Low** = minor inconsistency. + +### Global shell (header/footer) + +1. **Medium** — Visual language is inconsistent (glassmorphism header + mixed flat cards/buttons across pages). +2. **Medium** — Emoji-heavy iconography reduces perceived product quality and visual cohesion. +3. **Low** — Footer hierarchy is weak; feels detached from page sections and brand system. + +### Home / Recipe List (`/`) + +1. **High** — Primary CTA competition (`Add Recipe` appears in hero and again in list section), reducing action clarity. +2. **High** — Hero occupies significant vertical space before core content (recipe discovery), especially on mobile. +3. **Medium** — Mixed color semantics (orange hero accent, blue actions, slate sections) without a clearly unified token system. +4. **Medium** — Search and filters appear visually secondary despite being primary list interactions. +5. **Low** — Spacing rhythm varies between hero, filter panel, and card grid (inconsistent section cadence). + +### Recipe Detail / New (`/recipe/new`, `/recipe/:id`) + +1. **High** — Detail view lacks true hero media treatment; page relies on gradients/emoji rather than appetizing imagery. +2. **High** — Action row density is high (edit/cook/delete) and becomes crowded on smaller widths. +3. **Medium** — Card styles differ across sections (ingredients/instructions/additional info) creating weak visual hierarchy. +4. **Medium** — Typography hierarchy can flatten in long content blocks (meta vs body text contrast not strong enough). +5. **Low** — Border/shadow intensity differs subtly between cards and wrappers, creating visual noise. + +### Import URL (`/import/url`) + +1. **Medium** — Progress UI is visually strong but dominates above-the-fold area relative to the core URL action. +2. **Medium** — Form field and button styles do not fully match recipe form/list control treatments. +3. **Low** — Mixed icon/emoji style in flow states leads to inconsistent product tone. + +## Recommended redesign focus (P0 → P2) + +- **P0**: Unify design tokens (color roles, typography scale, spacing/elevation) and normalize interaction hierarchy. +- **P0**: Rebalance home above-the-fold layout so search/discovery is surfaced earlier. +- **P1**: Introduce consistent, high-quality food imagery strategy (home + detail + cards). +- **P1**: Reduce action clutter in detail and establish one primary action per context. +- **P2**: Replace ad-hoc emoji iconography with a coherent icon system. diff --git a/docs/visual-audit/before/home-desktop.png b/docs/visual-audit/before/home-desktop.png new file mode 100644 index 0000000..7f8d86b Binary files /dev/null and b/docs/visual-audit/before/home-desktop.png differ diff --git a/docs/visual-audit/before/home-mobile.png b/docs/visual-audit/before/home-mobile.png new file mode 100644 index 0000000..ef1e8b5 Binary files /dev/null and b/docs/visual-audit/before/home-mobile.png differ diff --git a/docs/visual-audit/before/import-url-desktop.png b/docs/visual-audit/before/import-url-desktop.png new file mode 100644 index 0000000..54a8e64 Binary files /dev/null and b/docs/visual-audit/before/import-url-desktop.png differ diff --git a/docs/visual-audit/before/import-url-mobile.png b/docs/visual-audit/before/import-url-mobile.png new file mode 100644 index 0000000..46a0f5b Binary files /dev/null and b/docs/visual-audit/before/import-url-mobile.png differ diff --git a/docs/visual-audit/before/recipe-detail-desktop.png b/docs/visual-audit/before/recipe-detail-desktop.png new file mode 100644 index 0000000..73e220e Binary files /dev/null and b/docs/visual-audit/before/recipe-detail-desktop.png differ diff --git a/docs/visual-audit/before/recipe-detail-mobile.png b/docs/visual-audit/before/recipe-detail-mobile.png new file mode 100644 index 0000000..10a2da7 Binary files /dev/null and b/docs/visual-audit/before/recipe-detail-mobile.png differ diff --git a/docs/visual-audit/before/recipe-new-desktop.png b/docs/visual-audit/before/recipe-new-desktop.png new file mode 100644 index 0000000..d59ba57 Binary files /dev/null and b/docs/visual-audit/before/recipe-new-desktop.png differ diff --git a/docs/visual-audit/before/recipe-new-mobile.png b/docs/visual-audit/before/recipe-new-mobile.png new file mode 100644 index 0000000..380d1ea Binary files /dev/null and b/docs/visual-audit/before/recipe-new-mobile.png differ diff --git a/docs/visual-audit/checklist.md b/docs/visual-audit/checklist.md new file mode 100644 index 0000000..feed4dc --- /dev/null +++ b/docs/visual-audit/checklist.md @@ -0,0 +1,56 @@ +# Visual Redesign Acceptance Checklist (Measurable) + +Use this checklist to validate redesign completion against T01 baseline. + +## 1) Visual Identity & Design System + +- [ ] A single token source exists for: color, typography, spacing, radius, shadow, and motion. +- [ ] No page uses hard-coded ad-hoc hex colors outside token definitions (except documented one-offs). +- [ ] Heading scale is consistent (`h1/h2/h3`) across home, list, detail, add/edit, and import pages. +- [ ] Primary/secondary/destructive button styles are identical across all pages (same radius, padding, states). + +## 2) Home/List Page + +- [ ] Above-the-fold includes clear single primary CTA (no competing primary actions). +- [ ] Search + filter controls are visible without scrolling at 1280x720. +- [ ] Recipe cards render in responsive grid: + - [ ] 1 column at ~390px width + - [ ] 2 columns at >=640px + - [ ] 3 columns at >=1280px +- [ ] Empty state includes clear next action and is visually distinct from error state. + +## 3) Detail + Add/Edit + +- [ ] Detail page uses a consistent hero treatment (image or media block) with fallback behavior. +- [ ] Primary actions are prioritized (max 1 prominent primary action per context area). +- [ ] Ingredients and instructions sections share the same section component anatomy (header/body spacing + borders). +- [ ] Form fields have consistent spacing and validation states across add/edit/import draft forms. + +## 4) Import URL Flow + +- [ ] URL form, progress card, and preview editor use shared component styles from the design system. +- [ ] Progress states are perceivable in <200ms feedback and remain readable at mobile width (~390px). +- [ ] Error states are mapped to semantic variants (invalid input, timeout/network, parse failure). + +## 5) Accessibility (AA baseline) + +- [ ] Text/background contrast meets WCAG AA for body text and interactive controls. +- [ ] All interactive controls have visible focus indicators (keyboard-only check). +- [ ] Touch targets are at least ~44x44 px on mobile for primary actions. +- [ ] Page remains usable at 200% zoom without content overlap/loss. + +## 6) Responsive QA & Regression + +- [ ] Before/after screenshots captured for desktop and mobile for key routes: + - [ ] `/` + - [ ] `/recipe/new` + - [ ] `/recipe/:id` + - [ ] `/import/url` +- [ ] Lighthouse (desktop + mobile) shows no major regression in performance/accessibility best-practice categories. +- [ ] No layout shift or overflow issues during initial page load and route changes. + +## 7) Done Definition + +- [ ] All P0 items closed. +- [ ] All high-severity T01 audit issues addressed or explicitly deferred with rationale. +- [ ] QA signoff recorded with date and reviewer.