MealQuest/design/MealQuest Requirements.md

MealQuest — Application Requirements

Everything decided while designing MealQuest, written so you can paste it into another LLM. Items marked [Decided] were confirmed by the client. Items marked [Design default] were proposed by the designer and not challenged; treat them as the current plan, but they can be changed.

---

1. Product summary

MealQuest is a mobile-first Progressive Web App (PWA) for weekly dinner planning for one household. The household enters the dinners they make regularly. An AI assistant suggests new dinners, which the household accepts or declines with a swipe interface like a dating app. The app builds a weekly dinner plan, pushes it to Google Calendar, and generates a shopping list for the planned dinners. Shopping lists are kept as a blog-style history you can browse by week, month or year. The app can also suggest dinners from a list of ingredients on hand, and offers quick dinner ideas. It sends push notifications and Google Chat messages through a webhook. An admin page configures the AI model (LLM).

2. Users & access

• [Decided] One shared household account. No per-person profiles.
• [Decided] Anyone in the household can open everything, including the Admin settings.
• [Design default] The household is shown as a single identity ("Our kitchen · Shared household"). Settings changes apply to everyone.

3. Platforms

• [Decided] Mobile first, delivered as a PWA (installable, with a service worker and app notifications).
• [Decided] Tablet and desktop layouts too. On larger screens the focus is reading ingredients and recipes, managing the calendar, and updating settings.
• [Design default] Breakpoints: mobile < 768px (bottom nav), tablet 768–1199px (96px icon rail), desktop ≥ 1200px (208px sidebar). Tablet is designed in landscape, for kitchen-counter use.
• [Design default] Works offline for the current plan, shopping list and recipes.

4. Navigation

• [Decided] Bottom nav on mobile, five items in this order: Home · Plan · Discover · Quick · Settings.
• [Decided] The Admin page lives inside Settings. It is not a nav tab.
• [Design default] The Shopping list and Shopping history are reached from Plan and Home (not tabs). The same five items appear in the tablet rail and the desktop sidebar.

5. Onboarding — regular dinners

• [Decided] The user enters the dinners the household routinely has ("regulars"). The AI uses these to come up with new suggestions.
• [Design default] Three steps; step 2 is "What's on your usual rotation?" with free-text entry, removable chips and suggested common dinners. Step 3 asks for notification permission.
• [Design default] Regulars can be edited later in Settings → Regular dinners.

6. AI dinner suggestions (Discover / swipe)

• [Decided] The AI suggests new dinners to try based on the household's regulars.
• [Decided] Swipe right / "Try it" = accept; swipe left / "Pass" = decline. Buttons and swipe gestures both work.
• [Decided] Accepted suggestions go into a "to try" pool (named the Quest log) and get scheduled later, not right away.
• [Decided] Each suggestion card shows: photo, why it was suggested (referencing the household's regulars), and difficulty.
• [Decided] Chosen layout: stacked photo cards (mockup 1a).
• [Design default] Declined suggestions are recorded so they aren't suggested again. A "Quest log · N" counter is shown on the screen. Suggestions arrive in batches; a push or Chat message announces new ones.

Required animations [Decided]

• Try it: the card wiggles, then flies off the right side of the screen.
• Pass: the card folds over and falls off to the left of the screen.
• Exact timings and easing are in the developer handoff README. Summary: "Try it!" stamp pops in → ±4° wiggle (420ms) → small pull-back → fly right with a 28° tilt (480ms). Pass: folds on its left edge (rotateY to −80°, shading darkens) → drops and tumbles off left (720ms). The cards behind move forward afterward (300ms). Dragging past 110px triggers the same exits; otherwise the card springs back.
• [Design default] Respect the device's reduced-motion setting (simple fade instead).

7. Weekly plan

• [Decided] The AI builds the week, mixing regulars and Quest-log meals; the user then adjusts it (swaps days).
• [Decided] No fixed rule for how many new vs. regular dinners go in a week.
• [Decided] The plan covers dinners (one per day).
• [Decided] Chosen mobile layout: draft board (mockup 1f). It shows an AI note ("I mixed 5 of your regulars with 2 from your Quest log…"), a 2-column grid of day tiles with new dinners highlighted, tap a day to swap, and a "Looks good — push to Calendar" button.
• [Design default] Tablet and desktop: a 7-column week view; drag a dinner from the Quest log or Regulars panel onto a day to swap it in. Includes week navigation, "Rebuild week" and "Push to Calendar".
• [Design default] Crock-pot dinners show a "Start by [time]" hint.

8. Google Calendar

• [Decided] The weekly schedule is placed in a Google Calendar.
• [Decided] The app is the source of truth and pushes to Google Calendar (one-way). Edits made in Google Calendar do not come back into the app.
• [Design default] Connect once with Google sign-in (OAuth) in Settings → Google Calendar; one calendar event per dinner; sync status is shown ("Synced to Google Calendar 2 min ago").

9. Shopping list

• [Decided] Generated from the ingredients needed for the dinners on the schedule.
• [Decided] Grouped by dinner (not by store aisle).
• [Decided] Pantry / on-hand handling: the user unchecks items they already have on the list. There is no separate pantry inventory.
• [Design default] Checked = needs buying; unchecked = "have it" (struck through, left out of the count). Shows a count like "19 / 23" and can be sent to Google Chat.

10. Shopping history (blog format)

• [Decided] Shopping lists are shown in a blog format: each weekly shopping list is a new post.
• [Decided] Browse by week / month / year for historical reference.
• [Design default] Each post shows a week label ("Week 41 · Oct 5 – 11"), an AI-written title, the number of dinners and items, how many items were already on hand, and dinner chips. Past posts are read-only.

11. Cook from what I have (ingredients → ideas)

• [Decided] Generate dinner ideas from a list of available ingredients.
• [Design default] Ingredient chip input, an "Any time / Quick only" filter, and a "Find ideas" button. Results show how many of your ingredients each idea uses and what's missing, with "Cook tonight" and "Add to Quest log" actions.

12. Quick dinners

• [Decided] A way to generate quick dinner ideas. "Quick" means cooked in a crock pot OR 30 minutes or less from prep to table.
• [Decided] Available in two places: a dedicated entry point (Quick nav tab plus a Home shortcut) and as a "Quick" filter on suggestions / ingredient search.
• [Decided] Shown as two tabs: Crock pot | 30 min or less.
• [Design default] Each result shows time and difficulty, has a "+" to add to the Quest log, and a "Show me more" option.

13. Recipe / dinner detail

• [Decided] A recipe / dinner detail screen.
• [Design default] Photo, tags (Regular/Side quest, difficulty, time), "Why it was picked", ingredients with quantities, steps, "Add to this week", and a favorite (heart) button.
• [Design default] Tablet kitchen reading mode: large text, ingredient checkboxes ("3 of 9 set out"), current step highlighted, Previous/Next step buttons, a Keep screen on toggle and a text-size control.

14. Notifications (push + Google Chat)

• [Decided] The PWA sends app (push) notifications.
• [Decided] The app sends messages to Google Chat using webhooks.
• [Decided] Events that trigger messages: New weekly plan ready · Shopping list ready · Day-of dinner reminder · New suggestions to swipe.
• [Design default] Push and Chat can be switched on or off separately for each event. The day-of reminder time can be changed (default 4:30 pm). Settings include the webhook URL, connection status and a "Send test" button.
• [Design default] On iOS, push only works once the app is installed to the home screen, so show an install hint.

15. Admin — LLM configuration (inside Settings)

• [Decided] An admin page for configuring the LLM the app uses, including:
  • Provider and model picker
  • API key management
  • Temperature / creativity
  • System prompt editor
• [Design default] The API key is stored on the server and only the last 4 characters are shown, with a "Replace" button and "Verified" date. Temperature slider from 0 to 1, labeled "Familiar ↔ Adventurous". Reset and Save buttons.
• Not requested: usage/cost tracking, test playground, global dietary restrictions.

16. Settings home

• [Design default] Sections: Household (Regular dinners, Google Calendar connection), Alerts (Notifications & Google Chat), Admin (AI assistant). Desktop shows Notifications, Webhook and AI assistant together on one page.

17. Visual design

• [Decided] Design system: Organic (warm, rounded, playful; pill-shaped buttons and inputs; soft shadows; generous spacing; photos softened and slightly desaturated).
• [Decided] Color palette "B4": Grape + teal blue on an off-white background.
  • Background #f9f6f1, surface #eee9de, text #201e1d
  • Primary (Grape) #5a358c; text on grape is always light #f9f6f1
  • Secondary (Teal blue) #29889c
  • Full light-to-dark scales are in the handoff tokens.css.
• [Decided] Heading font: Bagel Fat One (Google Fonts). Body font: Figtree.
• [Design default] Lucide icons with heavy strokes (2.75).
• [Decided] Copy tone: playful and quest-themed. Terms: Regulars (routine dinners), Side quests (AI suggestions), Quest log (to-try pool), Supply run (current shopping list), Supply archive (history).

18. Navigation animation

• [Decided] The purple pill in the bottom nav slides to the selected menu item.
• [Design default] 420ms with a slight overshoot; the other icons glide to their new spots; the label fades in after 120ms.

19. Accessibility [Design default]

• Swiping is never the only way to act: there are always buttons, and keyboard ←/→ arrows work.
• Text contrast of at least 4.5:1; tap targets of at least 44px; toggles and checkboxes are announced correctly to screen readers.

20. Suggested tech stack [Design default]

React + TypeScript + Vite, vite-plugin-pwa, React Router, TanStack Query, Web Animations API or Framer Motion, lucide-react. The backend handles LLM calls, Google Calendar sign-in and sync, Google Chat webhook posts, and push notifications.

21. Core data (summary)

• Dinner: name, photo, minutes, method (stovetop/oven/crock pot/other), difficulty, ingredients (name and quantity), steps, source (regular or suggestion).
• Suggestion: dinner, reason ("why this?"), status (pending/accepted/declined).
• Week plan: week start date, one dinner per day (flagged if new), status (draft/synced), last calendar sync time.
• Shopping list: week, items grouped by dinner (each marked needed or have-it), when it was sent to Chat, AI-written post title.
• Settings: Push/Chat switch for each event, reminder time, webhook URL, calendar, AI settings (provider, model, temperature, system prompt, last 4 of API key, verified date).
• A dinner counts as quick if it is a crock-pot meal or takes 30 minutes or less.

22. Not yet designed / open items

• Empty, loading and error states (suggested patterns are in the handoff README).
• The swap picker for a mobile plan day (suggested: a bottom sheet listing the Quest log and Regulars).
• Settings → Household and Regular dinners management screens.
• Onboarding steps 1 and 3.
• A tablet version of Settings, and portrait tablet layouts.