tonym
cbca17a682
Smart household management frontend for Grocy servers. Features: - Dashboard with PulseRing status indicator - Shopping list with checkable items - Expiring soon / low stock alerts - Chores summary - Quick add with create product flow - PWA installable Tech: React 19, TypeScript, Vite, TanStack Router, Zustand, Tailwind CSS Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
146 lines
3.6 KiB
Markdown
146 lines
3.6 KiB
Markdown
# Grocy2
|
|
|
|
Modern household management frontend for Grocy. Context-aware, delightful, mobile-first.
|
|
|
|
## Quick Reference
|
|
|
|
**Backend:** Grocy server at `http://192.168.0.5:9283`
|
|
**Full Spec:** `docs/DESIGN_SPEC.md`
|
|
|
|
## Tech Stack
|
|
|
|
- React 18 + TypeScript
|
|
- Vite
|
|
- TanStack Router
|
|
- Zustand (state)
|
|
- React Query (data fetching) - TO ADD
|
|
- Lucide icons
|
|
- CSS custom properties (design tokens)
|
|
|
|
## Design Principles
|
|
|
|
1. **Context-Aware** - Dashboard adapts to time of day
|
|
2. **Progressive Disclosure** - Simple surface, power underneath
|
|
3. **Forgiving** - Everything undoable
|
|
4. **Glanceable** - Status in 1s, action in 2s, explore in 3s
|
|
5. **Rewarding** - Satisfying feedback on actions
|
|
6. **Calm** - Only demands attention when needed
|
|
|
|
## Dashboard Components
|
|
|
|
### Pulse Ring
|
|
Ambient status indicator (green/amber/red glow). Tap to expand.
|
|
|
|
### Smart Cards (priority order)
|
|
1. **Expiring Soon** - Swipe left=use, right=add to list
|
|
2. **Shopping List** - Quick view, "Start Shopping Trip" mode
|
|
3. **Low Stock** - Progress bars, "Add All to List"
|
|
4. **Recipe Suggestions** - Evening priority, shows what you can make
|
|
|
|
### Quick Action Bar (bottom)
|
|
- **[+] Add** - Bottom sheet with recent items + search
|
|
- **[Scan]** - Barcode camera
|
|
- **[Voice]** - Speech recognition
|
|
|
|
## Design Tokens
|
|
|
|
```css
|
|
/* Colors */
|
|
--color-primary: #6B8E6B; /* Sage green */
|
|
--color-accent: #E8927C; /* Soft coral */
|
|
--color-urgent: #C75B39; /* Terracotta */
|
|
--color-warning: #E4A853; /* Amber */
|
|
--color-background: #FAFAF8; /* Warm white */
|
|
--color-text-primary: #2D3436; /* Warm charcoal */
|
|
|
|
/* Spacing: 4, 8, 16, 24, 32, 48 */
|
|
/* Radius: 4, 8, 12, 16 */
|
|
/* Transitions: 150ms (fast), 250ms (normal), 350ms (slow) */
|
|
```
|
|
|
|
## Breakpoints
|
|
|
|
- Mobile: < 640px (single column, bottom nav)
|
|
- Tablet: 640-1024px (two column, side tabs)
|
|
- Desktop: > 1024px (sidebar, three column, keyboard shortcuts)
|
|
|
|
## Key Interactions
|
|
|
|
| Gesture | Action |
|
|
|---------|--------|
|
|
| Pull down | Refresh |
|
|
| Swipe left | Use/Delete |
|
|
| Swipe right | Add to list |
|
|
| Long press | Context menu |
|
|
|
|
## Folder Structure
|
|
|
|
```
|
|
src/
|
|
├── api/ # API client + React Query hooks
|
|
├── components/
|
|
│ ├── ui/ # Button, Card, Input, etc.
|
|
│ ├── dashboard/ # PulseRing, SmartCard, QuickActionBar
|
|
│ ├── stock/
|
|
│ ├── shopping/
|
|
│ └── layout/
|
|
├── hooks/ # useVoiceInput, useSwipeGesture
|
|
├── lib/ # cardPriority, voiceParser, utils
|
|
├── pages/
|
|
├── store/
|
|
├── styles/ # tokens.css, global.css
|
|
└── types/
|
|
```
|
|
|
|
## Implementation Phases
|
|
|
|
### Phase 1: Foundation
|
|
- [x] Project setup
|
|
- [ ] Design tokens (CSS custom properties)
|
|
- [ ] Base UI components
|
|
- [ ] Responsive layout shell
|
|
- [ ] Bottom nav (mobile) / Sidebar (desktop)
|
|
|
|
### Phase 2: Smart Dashboard
|
|
- [ ] PulseRing component
|
|
- [ ] SmartCard system
|
|
- [ ] Card priority algorithm
|
|
- [ ] Swipeable rows
|
|
- [ ] QuickActionBar
|
|
|
|
### Phase 3: Quick Actions
|
|
- [ ] AddItem bottom sheet
|
|
- [ ] Barcode scanning
|
|
- [ ] Voice input
|
|
- [ ] Optimistic updates
|
|
|
|
### Phase 4: Full Pages
|
|
- [ ] Stock page (filter, search, detail)
|
|
- [ ] Shopping mode
|
|
- [ ] Recipes page
|
|
- [ ] Settings
|
|
|
|
### Phase 5: Polish
|
|
- [ ] PWA setup
|
|
- [ ] Offline support
|
|
- [ ] Siri Shortcuts docs
|
|
- [ ] Performance optimization
|
|
|
|
## Commands
|
|
|
|
```bash
|
|
npm run dev # Start dev server
|
|
npm run build # Production build
|
|
npm run preview # Preview production build
|
|
```
|
|
|
|
## Siri Integration (Future)
|
|
|
|
URL scheme: `grocy://add?item=milk&list=shopping`
|
|
|
|
Voice intents to parse:
|
|
- "Add X to shopping list"
|
|
- "Used X" / "Consumed X"
|
|
- "Do we have X?"
|
|
- "What's expiring?"
|