inspiration-app/Docs/front-end-spec.md

Inspiration Engine UI/UX Specification

Introduction

This document defines the user experience goals, information architecture, user flows, and visual design specifications for the Inspiration Engine's user interface. It serves as the foundation for visual design and frontend development, ensuring a cohesive and user-centered experience.

Overall UX Goals & Principles

Target User Personas

• The Individual Creative Professional: Digitally native professionals (designers, illustrators) who collect high volumes of multimodal assets and need frictionless capture and rediscovery.
• The Hobbyist / Personal Memory Curator: Heavy social and camera users who need automated organization for personal projects and memories.
• The Neurodivergent Organizer (ADHD): Users who rely on technology for object permanence and need an ultra-low-friction, dependable external memory to reduce cognitive load.

Usability Goals

• Ease of Learning: A new user can connect a source and save their first item in under 3 minutes.
• Efficiency of Use: A user can rediscover an asset via a semantic search in seconds, minimizing context switching.
• Error Prevention: The interface provides a calm, dependable experience that reduces anxiety about lost ideas.
• Memorability: The core search functionality is so intuitive that infrequent users can return and use it without needing to relearn anything.

Design Principles

1. Privacy by Design: Every design decision must uphold the zero-server-visibility and E2EE promises. User trust is paramount.
2. Effortless & Automated: Prioritize minimizing manual steps for the user through features like native, background ingestion.
3. Clarity Through Simplicity: The interface should be calm, uncluttered, and focused on the two core tasks: capture and rediscovery.
4. Immediate Feedback: Every action, especially search, should feel instant and responsive (e.g., ≤300ms search time).

Information Architecture (IA)

Rationale: This architecture was refined after a competitive analysis of services like Raindrop.io. We determined that our strategic advantage lies in simplicity and a focus on semantic search over manual organization. The structure is simplified to reinforce the core value proposition of "search by idea, not filename" and to create a clearer mental model for the user.

Refined Site Map

graph TD
    subgraph "Core Experience"
        B(Library) -- Central Search --> B
        B --> D[Item Details]
        B --> H((Discovery Grid))
        B --> E[Collections]
    end

    subgraph "Organization"
        E --> D
        E --> F[Moodboard View]
    end

    subgraph "Account Management"
        G[Settings]
        G1[Account Profile]
        G2[Manage Connections]
        G3[Export Data]
    end

    A[Login/Signup] --> B
    B --> G
    G --> G1 & G2 & G3

Refined Navigation Structure

• Primary Navigation: A persistent, prominent Search Bar as the central feature. It will be accompanied by top-level links to the Library, Collections, and Settings.
• Secondary Navigation: Contextual navigation that appears within a primary section (e.g., inside Settings).
• Breadcrumb Strategy: Path-based breadcrumbs will be used for nested content to ensure users are never lost.

User Flows

Rationale: These flows document the critical user paths that deliver the core value of the application. They are designed to be as frictionless as possible, supporting the user's creative momentum.

Flow 1: Rediscover an Item via Semantic Search

• User Goal: To find a previously saved piece of inspiration by describing its content or concept, without remembering its filename.
• Entry Points: The main Library view, specifically the persistent search bar.
• Success Criteria: The user finds the correct item within seconds and experiences the "rediscovery or surprise" that validates the product's purpose.
• Edge Cases:
  • No Results: The system should return a friendly message suggesting a broader search.
  • Irrelevant Results: A privacy-safe feedback mechanism (e.g., thumbs up/down) will be needed to tune relevance.
  • Slow Search: Must adhere to the ≤300ms average response time goal.

Flow 2: Capture an Item via Mobile Share Sheet

• User Goal: To frictionlessly save inspiration from any mobile app to their private library with minimal taps and no context switching.
• Entry Points: The native "Share" function in any iOS/Android app.
• Success Criteria: The user successfully saves the item in the background, receives a brief, non-intrusive confirmation, and feels confident their idea is captured.
• Edge Cases:
  • No Network Connection: The app must reliably queue the item for upload once a connection is re-established.
  • Duplicate Content: The ingestion pipeline will have a mechanism for deduplication.

Flow 3: Create a New Collection

• User Goal: To group related items into a cohesive collection or moodboard to support a specific project.
• Entry Points: Can be initiated top-down (from the main Collections screen) or bottom-up (from an item in the Library).
• Success Criteria: The process feels creative and additive, not like a chore. The user can easily create, populate, and view the collection as a moodboard.
• Enhancements: The system will support selecting multiple items at once via a "selection mode" and will eventually feature AI-powered suggestions for items to add to a collection, and even suggest automatically created collections based on thematic clusters in the user's library.

Flow 4: Search by Image

• User Goal: To find similar items in their library by uploading or providing a reference image.
• Entry Points: Inline image search toggle button adjacent to the main search bar in the Library view.
• Success Criteria: The user can quickly toggle to image search mode, upload an image via drag-and-drop or file picker, and receive visually similar results from their library.
• Implementation: An expandable dropzone slides down beneath the header when the image search icon is clicked, allowing users to upload images, paste URLs, or take photos without leaving the current view.

Wireframes & Mockups

• Design Tools: Low-fidelity concepts and wireframes will be developed using Excalidraw. High-fidelity mockups and visual design will be created in Adobe Photoshop.
• Key Screen Layout (Desktop: "Library / Search Results"): This layout is the blueprint for the application's primary view.
  • [ ZONE 1: HEADER ]: Left-aligned Logo; a large, prominent, centrally-placed Search Bar as the primary focus with an adjacent Image Search toggle button; right-aligned navigation links (Library, Collections) and a User/Settings Icon.
  • [ ZONE 1B: FILTER TOOLBAR ]: A compact horizontal toolbar beneath the header containing dropdown filter buttons (Collections, Source, Media Type, Date Added, Tags), result count, and view toggle controls (Grid/List).
  • [ ZONE 2: MAIN CONTENT AREA ]: A responsive, masonry-style "Discovery Grid" that fills the majority of the screen space with minimal spacing, populated with visual item tiles. Actions are revealed on hover to keep the UI clean.
• Key Screen Layout (Mobile Adaptation):
  • [ ZONE 1: HEADER / NAVIGATION ]: The header simplifies to a Logo and a Search Icon that expands on tap. Primary navigation moves to an ergonomic bottom tab bar.
  • [ ZONE 2: MAIN CONTENT AREA ]: The masonry grid reflows to a one- or two-column layout. Hover interactions are replaced with touch-based alternatives, such as a persistent "three-dot" menu icon on each tile.

Component Library / Design System

• Rationale: To accelerate development and ensure a high-quality, accessible foundation, the project will use a pre-built component library. An "unstyled" or "headless" library is chosen to provide maximum design freedom, allowing for a unique visual identity without fighting against opinionated default styles.
• Design System Approach: The project will use Shadcn/UI, built on Radix Primitives and styled with Tailwind CSS.

Branding & Style Guide

• Design Rationale: The visual identity is a synthesis of minimalist, editorial-style typography (inspired by Medium.com) and a bold, immersive, widescreen layout (inspired by artemiilebedev.com and foundry.basement.studio). The goal is to create a sophisticated, "calm," yet dynamic and visually engaging experience that avoids the common trend of centered, rounded-corner designs in favor of bold, sharp, full-bleed layouts.

Color Palette

Color Type	Hex Code	Usage
Background	#1c1917	The primary dark background with warm, earthy tones.
Surface	#292524	Secondary surfaces for cards, inputs, and elevated elements.
Foreground (Text)	#fafaf9	Main text color for high contrast and readability.
Subtle Text/Borders	#a8a29e	Secondary text, subtle dividers, and muted elements.
Border	#44403c	Borders for inputs and structural elements when needed.
Primary Action	#f97316	Buttons, active links, and key interactive elements.
Primary Hover	#ea580c	Hover state for primary interactive elements.
Accent (Highlight)	#fbbf24	Secondary highlights, callouts, or decorative elements.

Palette Rationale: The warm, earthy color scheme creates an inviting, creative atmosphere while maintaining sophistication. Orange as the primary action color provides energy and visibility without the aggression of pure red or the coldness of blue. The warm browns reduce eye strain during extended use compared to pure black backgrounds.

Typography

• Headings: Alata (Sans-serif) - Bold, clean, and strong.
• Body: Abhaya Libre (Serif) - Elegant and highly readable for paragraphs.

Layout & Interaction

• Layout: A widescreen, multi-column grid will be used to create split-screen sections and dynamic masonry layouts.
• Spacing Philosophy: The interface embraces a tight, immersive layout with minimal spacing between elements. Grid items use 2px gaps to create a dense, content-forward experience similar to Pinterest or Google Images, allowing the visual content to be the primary focus. This reduces visual noise and creates a more editorial, magazine-like feel.
• Shapes: All UI elements will use bold, strong shapes with sharp, 0px radius corners.
• Borders: Borders are used sparingly and only where necessary for functional clarity (e.g., input fields, structural separation). Content cards have no borders to maximize visual impact.
• Scrolling: The Lenis library will be used for smooth, sticky, and dynamic scrolling effects.

Accessibility Requirements

Compliance Target

• Standard: Web Content Accessibility Guidelines (WCAG) 2.2, Level AA.

Key Requirements

• Visual: All text must have a color contrast ratio of at least 4.5:1. All interactive elements must have a clear, visible focus indicator for keyboard users.
• Interaction: All features must be fully usable with only a keyboard. All images need descriptive alt text and controls must be properly labeled for screen readers.
• Motion & Animation: The application must detect the prefers-reduced-motion operating system setting. When enabled, all non-essential animations (smooth scrolling, transitions, etc.) will be disabled to prevent vestibular issues and improve usability for sensitive users.

Responsiveness Strategy

Breakpoints

Breakpoint	Min Width	Target Devices
Mobile (sm)	640px	Mobile phones (portrait & landscape)
Tablet (md)	768px	Tablets (portrait & landscape)
Laptop (lg)	1024px	Laptops, smaller desktops
Desktop (xl)	1280px	Standard desktop monitors
Widescreen (2xl)	1536px	Large and ultrawide monitors

Adaptation Patterns

• Layout Changes: The main content grid will reflow from a multi-column widescreen layout on desktops down to a two-column layout on tablets and a single-column layout on mobile.
• Navigation Changes: The persistent header navigation on desktop will collapse into a bottom tab bar on mobile for easy, ergonomic access.
• Interaction Changes: Hover-based interactions will be replaced with touch-based alternatives (e.g., a "three-dot" menu icon on each tile).

Animation & Micro-interactions

Motion Principles

• Fluid & Immersive: Utilize smooth scrolling and subtle scroll-based effects to create a continuous, engaging browsing experience.
• Responsive & Performant: Animations will provide fast, meaningful feedback to user interactions.
• Intentional & Unobtrusive: Motion will guide the user's focus and enhance the bold aesthetic but never obstruct core tasks.

Key Animation Definitions

• Page Transition ("Fluid Vertical Slide"): When navigating between main pages, the outgoing page will slide up and out of view while the incoming page slides up from the bottom. The animation will be fast and responsive, with a 300ms duration and an ease-out curve.
• Grid Item Loading ("Staggered Upward Reveal"): As new items load into the grid, they will animate into view sequentially with a slight delay. Each item will slide upward (e.g., 20 pixels) while fading in. The animation will have a 400ms duration and an ease-out curve.

Performance Considerations

Performance Goals

• Interaction Response: Average search response time must be ≤300ms to feel instant.
• Page Load: Target a Largest Contentful Paint (LCP) of under 2.5 seconds.
• Animation FPS: Maintain a consistent 60 frames per second (FPS).

Design Strategies

• Optimized Media: The system will generate and serve optimized, cached thumbnails for the library grid.
• Optimistic UI Updates: Actions like adding an item to a collection will update the UI instantly.
• Virtualization: For very large libraries, the grid will only render items currently visible on the screen.

Next Steps

Immediate Actions

1. Stakeholder Review: This detailed document should be reviewed for final approval.
2. High-Fidelity Design: Proceed with creating high-fidelity mockups in Adobe Photoshop.
3. Handoff for Architecture: This document can be handed off to a developer to begin technical planning.

Design Handoff Checklist

• All user flows documented
• Component inventory complete
• Accessibility requirements defined
• Responsive strategy clear
• Brand guidelines incorporated
• Performance goals established