stash-pile/CLAUDE.md

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

/* 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

• 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

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?"