feat(ui): baseline visual audit and checklist (T01)

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.

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.