A beautifully crafted, production-grade React + TypeScript front-end application for mindful personal growth and ecological awareness. Features a warm, handwritten paper aesthetic with a modern dark mode alternative.
- ๐จ Dual Theme System: Paper-Warm (light) and Midnight (dark) themes with instant switching
- ๐ณ Living Biome Visualization: Animated orb with tree growth based on your actions
- ๐ฌ AI Companion Chat: Conversational UI with provenance tags and streaming-style responses
- โก Micro-Actions: Grid of wellness actions with step-by-step guidance
- ๐ Memory Garden: Personal journal with timeline and pinning
- ๐ Insights Dashboard: Trends visualization with mood tracking
- โฟ Accessibility First: WCAG AA compliant, keyboard navigable, reduced motion support
- ๐ญ Framer Motion Animations: Smooth, delightful micro-interactions
- ๐พ Local-First Data: All data stored in localStorage with export capability
- ๐ฎ Demo Mode: Auto-simulation for showcasing features
- Node.js 18+ and npm 9+
# Navigate to project directory
cd lumen-earth
# Install dependencies
npm install
# Start development server
npm run devThe app will be available at http://localhost:3000
npm run buildBuild output will be in the dist/ directory.
# Run tests
npm test
# Run tests with UI
npm test:uilumen-earth/
โโโ public/
โ โโโ assets/
โ โ โโโ paper-texture.svg # Seamless paper texture
โ โ โโโ paper-crumple.svg # Overlay effect
โ โ โโโ orb.svg # Default orb graphic
โ โ โโโ icons/ # Hand-drawn SVG icons
โ โโโ index.html
โโโ src/
โ โโโ components/
โ โ โโโ ui/ # Reusable UI components
โ โ โ โโโ Button.tsx
โ โ โ โโโ Card.tsx
โ โ โ โโโ Modal.tsx
โ โ โ โโโ Badge.tsx
โ โ โ โโโ Tooltip.tsx
โ โ โ โโโ IconButton.tsx
โ โ โโโ AvatarOrb.tsx # Central biome visualization
โ โ โโโ Icon.tsx # Icon wrapper component
โ โ โโโ Layout.tsx # App layout with navigation
โ โโโ pages/
โ โ โโโ Home.tsx # Dashboard with orb & quick actions
โ โ โโโ Chat.tsx # AI companion interface
โ โ โโโ Actions.tsx # Micro-actions grid
โ โ โโโ Memory.tsx # Journal timeline
โ โ โโโ Dashboard.tsx # Trends & insights
โ โ โโโ Settings.tsx # App settings
โ โโโ lib/
โ โ โโโ store.ts # Zustand global state
โ โ โโโ storage.ts # localStorage wrapper
โ โ โโโ themeSwitch.ts # Theme utilities
โ โโโ data/
โ โ โโโ seed.ts # Demo data & types
โ โโโ hooks/
โ โ โโโ useOrbAnimation.ts # Orb growth calculations
โ โ โโโ useDemoMode.ts # Demo automation
โ โโโ styles/
โ โ โโโ theme.ts # Design tokens
โ โ โโโ animation.ts # Motion configuration
โ โ โโโ tailwind.css # Global styles
โ โโโ tests/ # Unit tests
โ โโโ App.tsx # Main app component
โ โโโ main.tsx # Entry point
โโโ tailwind.config.js
โโโ vite.config.ts
โโโ tsconfig.json
โโโ package.json
| Token | Light (Paper-Warm) | Dark (Midnight) | Usage |
|---|---|---|---|
--bg-paper |
#FCF7F0 |
#0D0F11 |
Main background |
--accent-teal |
#1F8775 |
#2FC9A8 |
Primary accent |
--accent-warm |
#E4D7C0 |
#FFE7C4 |
Secondary accent |
--ink-stroke |
#1E6F62 |
#2FC9A8 |
Icon strokes |
--text-primary |
#111827 |
#F5F5F6 |
Main text |
--muted-text |
#6B6B6B |
#9CA3AF |
Secondary text |
- Display Font: Patrick Hand (handwritten)
- Body Font: Inter (sans-serif)
- Scales: H1 (40-56px), H2 (28-36px), Body (16px), Small (13px)
4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px
All animations use Framer Motion with durations defined in src/styles/animation.ts:
- Breathe: 4s ease-in-out infinite (orb pulsing)
- Leaf Pop: 0.6s elastic (leaf growth)
- Fade In: 0.3s ease-out (page transitions)
- Navigate to Settings page
- Click the "Dark Mode" or "Light Mode" button
- Theme changes apply instantly and persist to localStorage
- Go to Settings
- Enable "Demo Mode"
- The app will auto-simulate activity every 10-30 seconds, showing:
- Tree growth animations
- Chat messages appearing
- Action completions
- Navigate to Actions page
- Click any micro-action card
- Follow the step-by-step instructions
- Click "Complete Action" to earn growth
- Keyboard Navigation: Tab through all interactive elements, Enter/Space to activate
- Focus Indicators: Visible focus rings on all controls
- Reduced Motion: Respects
prefers-reduced-motionsetting; can also be toggled in Settings - ARIA Labels: Screen reader support for dynamic content
Tests are written with Vitest and React Testing Library:
# Run all tests
npm test
# Run with UI
npm test:ui
# Test coverage includes:
# - Component rendering
# - User interactions
# - Theme switching
# - Orb growth calculations
# - Storage utilities# Lint code
npm run lint
# Format code
npm run format- TypeScript Strict Mode: Enabled for type safety
- ESLint: Configured with recommended rules + Prettier
- Component Pattern: Functional components with hooks
- State Management: Zustand for global state, React state for local
- Styling: Tailwind CSS with custom theme tokens
- Animations: Framer Motion with reduced motion support
- Go to Settings โ Data Management
- Click "Export Data (JSON)"
- Downloads a JSON file with all your data
- Go to Settings โ Data Management
- Click "Clear All Data"
- Confirm to reset all progress
All data is stored in localStorage under the key lumen_earth_v1.
To create a design preview screenshot:
- Start the dev server:
npm run dev - Open http://localhost:3000 in your browser
- Use browser dev tools or a screenshot extension to capture:
- Desktop view (1920x1080 recommended)
- Mobile view (375x812 recommended)
- Save as
public/assets/design-preview.png
This is a production-ready front-end template. To extend:
- Add new pages: Create in
src/pages/and add route inApp.tsx - New components: Add to
src/components/ui/for reusable UI - New actions: Add to
src/data/seed.tsmicro-actions array - Theme colors: Update
src/styles/theme.tsand Tailwind config
MIT License - Feel free to use this project as a template for your own applications.
- Fonts: Patrick Hand & Inter (Google Fonts)
- Icons: Hand-drawn SVG icon set (included)
- Animations: Powered by Framer Motion
- State: Zustand for elegant state management
Built with care for mindful growth ๐ฑ
