Skip to content

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Latest commit

ย 

History

1 Commit

Folders and files

Repository files navigation

๐ŸŒ Lumen Earth

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.

Lumen Earth Preview

โœจ Features

  • ๐ŸŽจ 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

๐Ÿš€ Quick Start

Prerequisites

  • Node.js 18+ and npm 9+

Installation

# Navigate to project directory
cd lumen-earth

# Install dependencies
npm install

# Start development server
npm run dev

The app will be available at http://localhost:3000

Build for Production

npm run build

Build output will be in the dist/ directory.

Run Tests

# Run tests
npm test

# Run tests with UI
npm test:ui

๐Ÿ“ Project Structure

lumen-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

๐ŸŽจ Design System

Color Tokens

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

Typography

  • Display Font: Patrick Hand (handwritten)
  • Body Font: Inter (sans-serif)
  • Scales: H1 (40-56px), H2 (28-36px), Body (16px), Small (13px)

Spacing Scale

4px, 8px, 12px, 16px, 24px, 32px, 48px, 64px

Animations

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)

๐ŸŽฏ Usage Guide

Switching Themes

  1. Navigate to Settings page
  2. Click the "Dark Mode" or "Light Mode" button
  3. Theme changes apply instantly and persist to localStorage

Enabling Demo Mode

  1. Go to Settings
  2. Enable "Demo Mode"
  3. The app will auto-simulate activity every 10-30 seconds, showing:
    • Tree growth animations
    • Chat messages appearing
    • Action completions

Completing Actions

  1. Navigate to Actions page
  2. Click any micro-action card
  3. Follow the step-by-step instructions
  4. Click "Complete Action" to earn growth

Accessibility Features

  • Keyboard Navigation: Tab through all interactive elements, Enter/Space to activate
  • Focus Indicators: Visible focus rings on all controls
  • Reduced Motion: Respects prefers-reduced-motion setting; can also be toggled in Settings
  • ARIA Labels: Screen reader support for dynamic content

๐Ÿงช Testing

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

๐Ÿ› ๏ธ Development

Code Quality

# Lint code
npm run lint

# Format code
npm run format

Project Guidelines

  • 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

๐Ÿ“ฆ Data Management

Export Data

  1. Go to Settings โ†’ Data Management
  2. Click "Export Data (JSON)"
  3. Downloads a JSON file with all your data

Clear Data

  1. Go to Settings โ†’ Data Management
  2. Click "Clear All Data"
  3. Confirm to reset all progress

All data is stored in localStorage under the key lumen_earth_v1.

๐ŸŽจ Generating Design Preview

To create a design preview screenshot:

  1. Start the dev server: npm run dev
  2. Open http://localhost:3000 in your browser
  3. Use browser dev tools or a screenshot extension to capture:
    • Desktop view (1920x1080 recommended)
    • Mobile view (375x812 recommended)
  4. Save as public/assets/design-preview.png

๐Ÿค Contributing

This is a production-ready front-end template. To extend:

  1. Add new pages: Create in src/pages/ and add route in App.tsx
  2. New components: Add to src/components/ui/ for reusable UI
  3. New actions: Add to src/data/seed.ts micro-actions array
  4. Theme colors: Update src/styles/theme.ts and Tailwind config

๐Ÿ“„ License

MIT License - Feel free to use this project as a template for your own applications.

๐Ÿ™ Acknowledgments

  • 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 ๐ŸŒฑ

About

No description, website, or topics provided.

Resources

Stars

0 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages