Skip to content

SPEC.md

Latest commit

 

History

History
266 lines (223 loc) · 7.84 KB

SPEC.md

File metadata and controls

266 lines (223 loc) · 7.84 KB

VibeShift - Vibe-to-Spec Transformation Tool

Project Overview

  • Project Name: VibeShift
  • Project Type: Web Application (SPA)
  • Core Functionality: Transform vague "vibe" descriptions into structured AI prompts and technical specifications
  • Target Users: Developers, designers, and product managers who want to convert intuitive ideas into actionable specs

UI/UX Specification

Layout Structure

Page Sections:

  1. Header - Logo, app name, dark/light mode toggle
  2. Input Section - Large textarea for vibe prompt
  3. Action Section - Transform button with loading state
  4. Output Section - Dual panel display (AI Prompt + Markdown Spec)
  5. History Section - Recent transformations list

Responsive Breakpoints:

  • Mobile: < 768px (stacked layout, tabs for outputs)
  • Tablet: 768px - 1024px (side-by-side with reduced padding)
  • Desktop: > 1024px (full side-by-side layout)

Visual Design

Color Palette:

Light Mode:

  • Background: #FAFAFA
  • Surface: #FFFFFF
  • Primary: #6366F1 (Indigo)
  • Primary Hover: #4F46E5
  • Secondary: #F1F5F9
  • Text Primary: #1E293B
  • Text Secondary: #64748B
  • Border: #E2E8F0
  • Accent Success: #10B981
  • Accent Error: #EF4444

Dark Mode:

  • Background: #0F172A
  • Surface: #1E293B
  • Primary: #818CF8
  • Primary Hover: #A5B4FC
  • Secondary: #334155
  • Text Primary: #F8FAFC
  • Text Secondary: #94A3B8
  • Border: #334155
  • Accent Success: #34D399
  • Accent Error: #F87171

Typography:

  • Font Family: "Inter", system-ui, -apple-system, sans-serif
  • Logo/Brand: "Space Grotesk", sans-serif (bold, 1.5rem)
  • Headings:
    • H1: 2rem / 700 weight
    • H2: 1.5rem / 600 weight
    • H3: 1.25rem / 600 weight
  • Body: 1rem / 400 weight
  • Small/Caption: 0.875rem / 400 weight
  • Monospace (for code/output): "JetBrains Mono", "Fira Code", monospace

Spacing System:

  • Base unit: 4px
  • xs: 4px
  • sm: 8px
  • md: 16px
  • lg: 24px
  • xl: 32px
  • 2xl: 48px
  • Container max-width: 1200px
  • Container padding: 24px

Visual Effects:

  • Border radius: 8px (buttons), 12px (cards), 16px (containers)
  • Shadows (light mode):
    • sm: 0 1px 2px rgba(0,0,0,0.05)
    • md: 0 4px 6px -1px rgba(0,0,0,0.1)
    • lg: 0 10px 15px -3px rgba(0,0,0,0.1)
  • Shadows (dark mode):
    • sm: 0 1px 2px rgba(0,0,0,0.3)
    • md: 0 4px 6px -1px rgba(0,0,0,0.4)
    • lg: 0 10px 15px -3px rgba(0,0,0,0.5)
  • Transitions: 200ms ease-in-out (all interactive elements)
  • Loading spinner: Rotating circle with primary color

Components

1. Header

  • Logo: Stylized "V" icon with gradient (indigo to purple)
  • App name: "VibeShift" with gradient text
  • Dark/Light toggle: Sun/Moon icons with smooth transition
  • Height: 64px
  • Sticky position on scroll

2. Vibe Input

  • Large textarea (min-height: 200px)
  • Placeholder: "Describe your vibe... (e.g., 'I want a cozy coffee shop app that feels like warm autumn afternoons')"
  • Character count display (bottom-right corner)
  • Max characters: 1000
  • Border: 2px solid (focus: primary color)
  • Background: surface color

3. Transform Button

  • Full width on mobile, auto width on desktop
  • Height: 48px
  • Primary gradient background
  • States:
    • Default: Primary gradient
    • Hover: Darkened gradient + slight scale (1.02)
    • Loading: Spinner + "Transforming..." text
    • Disabled: Grayed out + cursor not-allowed
  • Icon: Sparkle/Magic wand icon

4. Output Panels

  • Two panels: "AI Prompt" and "Markdown Spec"
  • Tab navigation on mobile
  • Side-by-side on desktop (50% width each)
  • Each panel has:
    • Header with title + copy button
    • Scrollable content area with monospace font
    • Syntax highlighting for markdown (basic)
  • Copy button:
    • Icon: Clipboard
    • States: Default, Success (checkmark), Tooltip "Copied!"

5. Download Button

  • Positioned below output panels
  • Icon: Download
  • Text: "Download as .md"
  • Downloads combined AI prompt + spec

6. History Section

  • Collapsible section
  • Title: "Recent Transformations"
  • List of last 5 items
  • Each item:
    • Truncated vibe preview (first 50 chars)
    • Timestamp (relative: "2 min ago", "1 hour ago")
    • Click to restore (populates input + outputs)
    • Delete button (X icon)
  • Empty state: "No transformations yet"

7. Error State

  • Red border on input
  • Error message below input
  • Toast notification for critical errors

Functionality Specification

Core Features

1. Vibe Input

  • Multi-line text input
  • Real-time character counting
  • Persists to localStorage on transform

2. Transformation Logic (Client-Side)

  • Extract intent keywords (app, website, tool, feature, etc.)
  • Identify emotional descriptors (cozy, modern, minimal, playful, etc.)
  • Identify color/temperature references (warm, cool, dark, bright, etc.)
  • Identify functional requirements (fast, secure, responsive, etc.)
  • Map vibes to concrete UI elements:
    • "cozy" → warm colors, rounded corners, soft shadows
    • "modern" → clean lines, sans-serif fonts, minimal decoration
    • "playful" → bright colors, bouncy animations, rounded shapes
    • "professional" → neutral colors, sharp edges, structured layout

Output Generation:

  • AI Prompt: Detailed prompt for an AI to generate the actual application
  • Markdown Spec: Structured specification with sections:
    • Overview
    • Visual Design
    • Functional Requirements
    • Technical Considerations

3. Copy to Clipboard

  • Copy button for each output panel
  • Visual feedback (checkmark + "Copied!" tooltip)
  • Uses navigator.clipboard API

4. Download as .md

  • Downloads file with format: vibeshift-{timestamp}.md
  • Contains both AI prompt and Markdown spec
  • Proper markdown formatting

5. History Management

  • Store last 5 transformations in localStorage
  • Each entry contains:
    • id: unique identifier
    • vibe: original input
    • aiPrompt: generated prompt
    • markdownSpec: generated spec
    • timestamp: creation time
  • Click to restore full transformation
  • Delete individual items

6. Dark/Light Mode

  • Toggle in header
  • Persists preference in localStorage
  • Respects system preference on first load
  • Smooth transition between modes

User Interactions and Flows

  1. Initial Load:

    • Check localStorage for theme preference
    • Check for saved history
    • Display empty input state

  2. Transform Flow:

    • User types vibe → character count updates
    • User clicks Transform → button shows loading
    • System processes (simulated 1.5s delay)
    • Outputs appear → history updates
    • User can copy/download

  3. History Flow:

    • User clicks history item → inputs + outputs restore
    • User can re-transform or modify

Edge Cases

  • Empty input: Disable transform button
  • Very short input (<10 chars): Show warning
  • localStorage unavailable: Graceful degradation, no history
  • Clipboard API unavailable: Show fallback "select all" text

Acceptance Criteria

Visual Checkpoints

  • Header displays logo, name, and theme toggle
  • Input textarea is large and shows character count
  • Transform button shows loading state during transformation
  • Output panels display side-by-side on desktop
  • Output panels use tabs on mobile
  • Copy buttons provide visual feedback
  • History shows last 5 items with timestamps
  • Dark mode applies correct colors throughout
  • All transitions are smooth (200ms)

Functional Checkpoints

  • Character count updates in real-time
  • Transform generates both AI prompt and Markdown spec
  • Copy to clipboard works for both outputs
  • Download creates valid .md file
  • History persists across page reloads
  • Clicking history item restores that transformation
  • Theme preference persists across sessions
  • Mobile layout is fully functional

Technical Checkpoints

  • Built with Vite + React
  • Styled with Tailwind CSS
  • State managed with React hooks
  • localStorage used for persistence
  • No console errors in production
  • Responsive at all breakpoints