About Luz de Arcanos

Luz de Arcanos is an AI-powered tarot reading web application that combines ancient divination practices with cutting-edge artificial intelligence to provide personalized, meaningful readings.

Project Overview

The application offers real-time tarot consultations where users:

Enter their name and question
Watch three beautifully animated cards reveal (Past, Present, Future)
Receive a personalized AI-generated interpretation

Each reading is unique, contextual, and designed to provide practical insights you can apply immediately.

Purpose

Luz de Arcanos was created to make tarot readings:

Accessible: Free consultations (5 per day) available to anyone
Modern: Powered by advanced AI for nuanced, context-aware interpretations
Practical: Focused on actionable advice rather than mystical language
Beautiful: Featuring 3D card animations and immersive design
Safe: Built-in restrictions prevent health-related questions

The name “Luz de Arcanos” means “Light of the Arcana” in Spanish, reflecting the project’s goal of illuminating insight through the tarot’s major and minor arcana.

Technology Stack

Built with modern, performant web technologies:

Technology	Purpose
Astro 5	Framework with SSR and Server Actions
Google Gemini API	AI-powered reading generation (2.5 Flash, 2.0 Flash, 2.0 Flash Lite)
TypeScript	Type-safe development across components and actions
Pure CSS	3D card flip animations using `transform-style: preserve-3d`
Vercel	Deployment and hosting with SSR adapter

Key Technical Features

✨ AI Integration

Google Gemini 2.5 Flash for generating unique readings
Automatic fallback between three Gemini models (handles API quota errors)
Fallback to template-based readings if all AI models fail
Maximum 250-word readings for concise, actionable advice

🎴 Card Mechanics

Full 78-card tarot deck (Major and Minor Arcana)
Random card selection with 50% reversal probability
Each card has upright and reversed keyword sets
Three-card spread: Past, Present, Future

🎨 User Experience

3D CSS card flip animations (no JavaScript animation libraries)
Looping video background with responsive overlay
Staggered paragraph fade-in for readings
Fully responsive design (desktop, tablet, mobile)
Smooth scrolling and section transitions

🛡️ Safety & Limits

5 consultations per day per user (localStorage-based)
Health question restrictions built into AI prompt
Input validation (name: 1-60 chars, question: 1-500 chars)
Graceful error handling with user-friendly messages

📊 SEO & Metadata

Complete Open Graph tags
Twitter Card metadata
JSON-LD Schema.org structured data
Canonical URLs and favicons for all devices

The AI: Seraphina

Readings are generated by Seraphina, the AI persona that acts as a professional, empathetic tarotist. Her style is:

Warm but direct: Conversational tone without excessive mysticism
Practical: Focuses on actionable insights
Structured: Covers greeting, past, present, future, and concrete advice
Accessible: Uses clear language, avoids complex esoteric terms

The AI prompt instructs Seraphina to provide readings under 250 words and avoid clichéd mystical language like “tapiz del universo” or “vibrar en centurias.”

The Seraphina persona is implemented in the system prompt at src/actions/index.ts:53-73.

Live Demo

Experience Luz de Arcanos yourself: 🔗 luzdearcanos.vercel.app Try a free consultation and see the AI-powered tarot readings in action.

Open Source

Luz de Arcanos is fully open source. You can:

View the complete source code
Report bugs and suggest features
Contribute improvements
Run your own instance with unlimited consultations

To run your own instance, you’ll need a Google Gemini API key from Google AI Studio. The key should be added to your environment as GEMINI_API_KEY.

Running Locally

git clone [repository-url]
cd luz-de-arcanos
bun install
bun dev

See the README.md in the repository for complete setup instructions.

Creator

Luz de Arcanos was created by KERNEL, a development studio focused on innovative web experiences. 🔗 kernel-rosario.vercel.app Learn more about KERNEL’s projects and philosophy.

Project Goals

Luz de Arcanos demonstrates:

AI Integration in Traditional Practices: Combining cultural practices with modern AI
Practical UX Design: Making complex systems feel magical and simple
Responsible AI Use: Implementing safety restrictions and transparent limitations
Modern Web Performance: Using SSR, type safety, and optimized rendering
Open Source Values: Sharing knowledge and enabling community contributions

Future Development

Potential enhancements being considered:

Additional spread types (Celtic Cross, etc.)
Multi-language support beyond Spanish
User accounts for reading history
Customizable card decks
Mobile app versions

Want to suggest a feature or contribute? Visit the GitHub repository and open an issue or pull request. Community contributions are welcome!

Contact & Links

Live Demo: luzdearcanos.vercel.app
Creator: KERNEL
GitHub: Check repository for source code and issues
Support: See Support page

Luz de Arcanos is provided as-is for entertainment and reflection purposes. While the AI provides thoughtful interpretations, readings should not replace professional advice for important life decisions.

Get Started

Features

User Guide

Technical

Resources

About Luz de Arcanos