VibeShift

Transform your creative "vibes" into detailed AI prompts and technical specifications.

What is VibeShift?

VibeShift is a web application that bridges the gap between intuitive, emotional ideas and concrete technical specifications. Whether you're a developer, designer, or product manager, VibeShift helps you convert vague "vibe" descriptions (like "I want a cozy coffee shop app that feels like warm autumn afternoons") into:

• Detailed AI prompts ready for code generation
• Structured Markdown specifications with sections for design, functionality, and technical considerations

Features

Core Functionality

• Intelligent Vibe Analysis - Extracts intent, emotions, colors, and requirements from natural language
• Dual Output Generation - Get both an AI-ready prompt and a comprehensive spec document
• Client-Side Processing - Works offline with no backend required (optional AI integration available)
• Dark/Light Mode - Beautiful, accessible themes with smooth transitions

User Experience

• Persistent History - Saves your last 5 transformations locally
• One-Click Copy - Copy either output to clipboard instantly
• Download as Markdown - Export your specifications as .md files
• Responsive Design - Works seamlessly on desktop, tablet, and mobile

AI Integration (Optional)

• Multiple Backends - Support for Gemini, OpenRouter, Copilot CLI, or custom OpenAI-compatible APIs
• Environment Variables - Secure API key management
• Connection Testing - Verify your AI backend configuration before use

Getting Started

Prerequisites

• Node.js 18+
• pnpm (recommended) or npm

Installation

# Clone the repository
git clone https://github.com/yourusername/vibeshift.git
cd vibeshift

# Install dependencies
pnpm install

# Copy environment configuration (optional, for AI features)
cp .env.example .env
# Edit .env and add your API keys if desired

# Start development server
pnpm dev

# Or use npm
npm install
npm run dev

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

Building for Production

pnpm build
pnpm preview

Usage Guide

Basic Workflow

1. Enter Your Vibe - Type a description of the feeling or aesthetic you want

   Example: "A modern fitness tracker with a dark theme, neon accents, and energetic vibes"
   

2. Transform - Click the "Transform" button (or press Ctrl+Enter)

   • Wait for processing (simulated 1.5s delay or AI-generated)
   • View two outputs:
     • AI Prompt: Detailed instructions for an AI to build your project
     • Markdown Spec: Structured specification document

3. Copy or Download - Use the copy buttons or download as a .md file

4. Access History - View and restore your recent transformations from the history panel

AI Backend Configuration

1. Click the Settings (gear icon) in the header
2. Select your AI backend:
   • Client-side (no AI) - Uses built-in pattern matching
   • Gemini API - Google's Gemini model
   • OpenRouter - Access multiple AI models
   • Custom - Any OpenAI-compatible endpoint
3. Enter your API key (if required)
4. Optionally customize endpoint and model
5. Test the connection
6. Save settings

For better security, set API keys in .env:

VITE_OPENROUTER_API_KEY=your_key_here
VITE_GEMINI_API_KEY=your_key_here

Project Structure

vibeshift/
├── src/
│   ├── components/       # React components
│   │   ├── Header.jsx           # App header with theme toggle
│   │   ├── VibeInput.jsx        # Multi-line text input
│   │   ├── TransformButton.jsx  # Action button with loading state
│   │   ├── OutputPanel.jsx      # Display for AI prompt/spec
│   │   ├── History.jsx          # Recent transformations
│   │   ├── MobileTabs.jsx       # Mobile navigation tabs
│   │   ├── DownloadButton.jsx   # Export functionality
│   │   └── SettingsModal.jsx    # AI backend configuration
│   ├── utils/
│   │   ├── storage.js           # localStorage utilities
│   │   ├── backends.js          # AI backend adapters
│   │   ├── transform.js         # Client-side transformation logic
│   │   └── debounce.js         # Debounce utility
│   ├── App.jsx                  # Main application component
│   ├── main.jsx                 # React entry point
│   └── index.css                # Global styles & CSS variables
├── docs/                       # AI-ready project documentation
├── public/                       # Static assets
├── .env.example                  # Environment variable template
├── vite.config.js                # Vite configuration
├── tailwind.config.js            # Tailwind CSS configuration
├── SPEC.md                       # Detailed project specification
└── package.json

Documentation

For AI-assisted development and brownfield PRD workflows, see the docs/ folder:

• docs/index.md — Master documentation index
• docs/architecture.md — System architecture
• docs/source-tree-analysis.md — Source tree with annotations
• docs/component-inventory.md — UI component inventory
• docs/development-guide.md — Setup & development guide
• docs/project-overview.md — Project summary

Technologies

• Framework: React 19
• Build Tool: Vite 7
• Styling: Tailwind CSS 4 with custom CSS variables
• Language: JavaScript (ES2022)
• Package Manager: pnpm (recommended)

Configuration

Environment Variables

Variable	Description	Backend
VITE_OPENROUTER_API_KEY	OpenRouter API key	OpenRouter
VITE_GEMINI_API_KEY	Google AI Studio API key	Gemini

LocalStorage Keys

• vibeshift_history - Recent transformations (max 5)
• vibeshift_theme - User's theme preference (light or dark)
• vibeshift_backend_config - AI backend configuration

Customization

Color Theme

Edit src/index.css to customize the color palette:

@theme {
  /* Light mode colors */
  --color-bg-light: #FDFCF8;
  --color-surface-light: #FFFFFF;
  --color-primary: #6366F1;
  
  /* Dark mode colors */
  --color-bg-dark: #0F172A;
  --color-surface-dark: #1E293B;
  --color-primary-dark: #818CF8;
}

Adding New AI Backends

1. Add backend type to BACKEND_TYPES in src/utils/backends.js
2. Create adapter implementing the transform() and testConnection() methods
3. Add configuration UI in SettingsModal.jsx
4. Update STORAGE_KEYS if needed

Development

Available Scripts

pnpm dev       # Start development server (http://localhost:5173)
pnpm build     # Build for production
pnpm preview   # Preview production build
pnpm lint      # Run ESLint

Code Style

• Formatting: Prettier (via editorconfig)
• Linting: ESLint with React-specific rules
• Components: Functional components with hooks
• Styling: Tailwind CSS classes + custom CSS variables

Browser Support

• Chrome/Edge 90+
• Firefox 88+
• Safari 14+
• Not supported: IE11 and older

Known Limitations

1. Client-side AI: The built-in transformation system is rule-based and less sophisticated than modern LLMs
2. Storage: localStorage has a ~5-10MB limit; history is capped at 5 items
3. API Keys: If stored in browser (not .env), they're accessible to any script on the page
4. No Server: All processing is local or via third-party APIs

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

MIT License - see LICENSE for details

Acknowledgments

• Built with Vite + React
• Styled with Tailwind CSS
• Icons from Heroicons
• Fonts: Inter & Space Grotesk

---

Built with ❤️ using VibeShift — Transform your ideas into specifications