Skip to main content

UI Specifications

User interface specifications for TVL Platform applications

Overview​

This directory contains UI/UX specifications for all TVL Platform user-facing applications. UI specifications define WHAT screens, components, and user flows to build.

Who creates these: Design team (UX designers, product designers) When created: During design phase, before frontend implementation Format: Wireframes, mockups, Figma links, written specifications

⚠️ Important: Design-First Approach​

UI specifications should be created by the design team, not backend engineers.

Why:​

  • ✅ Designers understand UX principles, accessibility, user research
  • ✅ Designs iterate rapidly during prototyping (specs get stale if written too early)
  • ✅ Visual tools (Figma, Sketch) are more effective than written specs alone
  • ✅ Backend engineers writing UI specs often miss important UX considerations

When to Create UI Specs:​

  1. After user research - Understanding user needs and pain points
  2. During design phase - Wireframes → Mockups → Prototype
  3. Before frontend implementation - Specs finalized and reviewed
  4. Not during planning phase - Too early, designs will change

Files in This Directory​

FilePurposeStatus
v0-project-spec.mdv0.dev constraints and prompts✅ Ready for MVP.0
admin-ui-spec.mdAdmin dashboard specification📝 Placeholder (to be redesigned)

v0-project-spec.md​

Complete reference for using v0.dev to build TVL Platform UI.

This is the "source of truth" to feed v0.dev when generating components. Includes:

  • Tech stack constraints (from ADRs 0015-0021)
  • Database connection patterns (Supabase)
  • Authentication flow (Google OIDC)
  • Multi-tenancy patterns (org_id filtering)
  • Standard prompts for common components
  • Code review checklist
  • Parallel development strategy

Use this when:

  • Generating UI components with v0.dev
  • Need to reference ADR-compliant patterns
  • Want consistent Supabase integration
  • Building admin dashboard (MVP.0)

Related: v0.dev Usage Guide

Current Status​

ApplicationStatusOwnerTimeline
Admin Dashboard📝 Draft spec existsBackend team (placeholder)To be redesigned by design team
Property Owner Portal🕐 Waiting for designDesign team (not hired)MVP.1+
Guest Booking Flow🕐 Waiting for designDesign team (not hired)V1.0+
Mobile App🕐 Waiting for designDesign team (not hired)V2.0+

Planned UI Specifications​

1. Admin Dashboard (MVP.0)​

Current: admin-ui-spec.md - Placeholder spec

Purpose: Internal admin interface for managing properties, bookings, and viewing Hostaway sync data

Scope (MVP.0):

  • View synced properties from Hostaway
  • View synced bookings
  • Basic dashboard with key metrics
  • Property list with filters
  • Booking calendar view

Tech Stack:

  • React 18 + Next.js 14 (ADR-0015, ADR-0016)
  • Tailwind CSS (ADR-0017)
  • Shadcn UI components (ADR-0018)

Design Status: ⚠️ Needs redesign by design team

Action Required:

  • Hire UX designer
  • Conduct user research (property managers, admins)
  • Create wireframes in Figma
  • Prototype and user testing
  • Finalize design system
  • Update specification

2. Property Owner Portal (MVP.1+)​

Purpose: Self-service portal for property owners to manage their listings

Scope:

  • Property CRUD (create, read, update, delete)
  • Unit management (attach units to properties)
  • Availability calendar management
  • Booking overview
  • Revenue dashboard
  • Channel distribution settings (which channels to publish to)

User Personas:

  • Property owner (manages 1-10 properties)
  • Property manager (manages 10-100 properties)
  • Vacation rental company (100+ properties)

Design Status: 🕐 Waiting for design team

Dependencies:

  • Supply domain implementation (ADR-0009: Domain 03)
  • Multi-tenancy implementation (ADR-0001, ADR-0002)

Action Required:

  • User research with property owners
  • Define user flows (property creation, unit management, etc.)
  • Wireframe key screens
  • Create specification

3. Guest Booking Flow (V1.0+)​

Purpose: Public-facing booking interface for guests to search and book properties

Scope:

  • Property search (filters: location, dates, guests, amenities)
  • Property detail page (photos, description, availability, pricing)
  • Booking flow (select dates → guest info → payment → confirmation)
  • Guest account management
  • Booking history

User Personas:

  • Leisure traveler (booking vacation rental)
  • Business traveler (extended stay)
  • Event attendee (group bookings)

Design Status: 🕐 Waiting for design team

Dependencies:

  • Booking domain (ADR-0009: Domain 06)
  • Payment integration (Stripe - V1.0)
  • Direct booking capability (V1.0 feature)

Action Required:

  • Competitor analysis (Airbnb, VRBO UX patterns)
  • User research with guests
  • Define conversion funnel
  • A/B testing strategy
  • Create specification

4. Mobile App (V2.0+)​

Purpose: Native mobile app for property owners and guests

Scope:

  • Property owner: Booking notifications, calendar management, messaging
  • Guests: Search, book, check-in, messaging

Platforms: iOS + Android (React Native or Flutter)

Design Status: 🕐 Waiting for design team

Dependencies:

  • API maturity (RESTful API complete)
  • Mobile-first design system
  • Push notification infrastructure

Action Required:

  • Mobile UX research
  • Define mobile-specific features
  • Choose mobile framework (React Native vs Flutter)
  • Create specification

UI Specification Template​

When the design team creates UI specs, they should follow this structure:

Structure:​

# [Application Name] UI Specification

## Summary
Brief overview (1-2 paragraphs)

## User Personas
- Primary persona (with goals, pain points)
- Secondary personas

## User Flows
- Key user journeys (with diagrams)
- Happy path + edge cases

## Screens & Components

### Screen Name
**Route:** `/path/to/screen`
**Purpose:** What problem does this screen solve?
**User Story:** As a [user], I want to [action] so that [benefit]

**Layout:**
- Header: [components]
- Main content: [components]
- Sidebar: [components]
- Footer: [components]

**Components:**
1. Component Name
   - Props: [list]
   - States: [list]
   - Interactions: [list]

**Figma Link:** https://figma.com/...

## Design System
- Colors, typography, spacing
- Component library
- Accessibility requirements (WCAG 2.1 AA)

## Responsive Design
- Desktop breakpoints
- Tablet breakpoints
- Mobile breakpoints

## Interactions & Animations
- Loading states
- Error states
- Success states
- Transitions

## Accessibility
- Keyboard navigation
- Screen reader support
- Color contrast
- Focus management

## Performance Requirements
- Time to Interactive (TTI)
- First Contentful Paint (FCP)
- Largest Contentful Paint (LCP)

## Browser Support
- Chrome, Firefox, Safari, Edge
- iOS Safari, Android Chrome

## References
- Related ADRs
- Design system documentation
- User research findings

Design Tools & Assets​

Design System (To Be Created)​

Tool: Figma (recommended) Repository: Link to Figma workspace (when created)

Components:

  • Buttons, inputs, dropdowns
  • Cards, modals, toasts
  • Navigation, headers, footers
  • Tables, lists, calendars
  • Charts, graphs, dashboards

Design Tokens:

  • Color palette (primary, secondary, neutral, semantic)
  • Typography scale
  • Spacing scale
  • Border radius, shadows

Prototyping​

Tools:

  • Figma (interactive prototypes)
  • v0.dev (rapid prototyping with Shadcn UI - ADR-0018)

User Testing​

Tools:

  • UserTesting.com
  • Maze (for prototype testing)
  • Hotjar (heatmaps, session recordings)

Tech Stack (Per ADRs)​

All UI applications must follow these architectural decisions:

TechnologyADRNotes
React 18ADR-0015UI library
Next.js 14 App RouterADR-0016SSR framework
Tailwind CSSADR-0017Styling
Shadcn UIADR-0018Component library
ZustandADR-0019State management
TanStack QueryADR-0020Server state
React Hook Form + ZodADR-0021Forms + validation

Design Principles (To Be Defined)​

When the design team is onboarded, define:

  1. Accessibility First - WCAG 2.1 AA compliance minimum
  2. Mobile Responsive - Mobile-first design approach
  3. Performance - Core Web Vitals targets
  4. Consistency - Shared component library
  5. User-Centered - User research drives design decisions

FAQ​

Q: Can backend engineers write UI specs?

A: For early prototyping only (like the current admin-ui-spec.md). All production UI specs should come from the design team after user research and prototyping.

Q: When should we hire a designer?

A: Before MVP.1. MVP.0 can use basic Shadcn UI components without custom design, but MVP.1+ requires professional UX design for the property owner portal.

Q: Should we use a design system?

A: Yes. Start with Shadcn UI (ADR-0018) as the foundation, then customize as needed. A design system ensures consistency and speeds up development.

Q: Do we need Figma specs if we're using Shadcn UI?

A: Yes. Shadcn provides components, but you still need to design:

  • Page layouts
  • User flows
  • Custom components
  • Responsive behavior
  • Interactions and animations

Q: How detailed should UI specs be?

A: Just enough detail. Include:

  • ✅ Wireframes or mockups
  • ✅ Component list and hierarchy
  • ✅ User flows
  • ✅ Interaction states
  • ❌ Don't include: Pixel-perfect measurements (Tailwind handles this)
  • ❌ Don't include: CSS code (frontend devs write this)

Q: Who approves UI specs?

A: Product owner + frontend lead + UX designer (collaborative review)

Roadmap​

Phase 1: MVP.0 (Weeks 1-10)​

  • ✅ Use existing admin-ui-spec.md as placeholder
  • ✅ Build with Shadcn UI default components
  • ✅ Focus on functionality over design
  • ⏳ No custom design work required

Phase 2: MVP.1 (Weeks 11-16)​

  • 🎯 Hire UX designer (before week 11)
  • 🎯 User research with property owners
  • 🎯 Design property owner portal
  • 🎯 Create design system foundation

Phase 3: MVP.2 (Weeks 17-24)​

  • 🎯 Refine design system
  • 🎯 User testing and iteration
  • 🎯 Accessibility audit

Phase 4: V1.0 (Months 7-12)​

  • 🎯 Design guest booking flow
  • 🎯 A/B testing framework
  • 🎯 Conversion optimization

Phase 5: V2.0+ (Months 13+)​

  • 🎯 Mobile app design
  • 🎯 Advanced features (events, experiences)

Summary​

Current State:

  • 1 placeholder UI spec (admin dashboard)
  • No design team hired
  • Using Shadcn UI defaults for MVP.0

Next Steps:

  1. ✅ Move UI specs to /docs/specifications/ui/ (done)
  2. ⏳ Complete MVP.0 with basic UI (no design needed)
  3. 🎯 Hire UX designer before MVP.1 (Week 10)
  4. 🎯 Design team creates proper UI specs for MVP.1+

Principle: Don't over-design before you have users. Build, learn, iterate.

Last Updated: 2025-01-26 Status: Framework ready, waiting for design team Maintained By: Product + Design Team (when hired)