Initial commit
This commit is contained in:
@@ -0,0 +1,217 @@
|
||||
# Product Reviews Component
|
||||
|
||||
## Contents
|
||||
|
||||
- [Overview](#overview)
|
||||
- [Review Display Patterns](#review-display-patterns)
|
||||
- [Rating Summary and Distribution](#rating-summary-and-distribution)
|
||||
- [Sorting and Filtering](#sorting-and-filtering)
|
||||
- [Review Submission](#review-submission)
|
||||
- [Trust Signals](#trust-signals)
|
||||
- [SEO Integration](#seo-integration)
|
||||
|
||||
## Overview
|
||||
|
||||
Product reviews build trust and influence purchase decisions. Reviews with ratings convert 270% better than products without.
|
||||
|
||||
**Assumed knowledge**: Claude knows how to build forms and display lists. This guide focuses on ecommerce review patterns and trust signals.
|
||||
|
||||
### Key Requirements
|
||||
|
||||
- Star rating summary (1-5 stars) with distribution
|
||||
- Individual reviews with ratings, text, author, date
|
||||
- Sorting (Most Recent, Most Helpful, Highest/Lowest Rating)
|
||||
- Filtering by rating (5 stars only, 4+ stars)
|
||||
- Verified purchase badges
|
||||
- Helpful votes (upvote system)
|
||||
- Review submission form
|
||||
- Mobile-optimized
|
||||
|
||||
## Review Display Patterns
|
||||
|
||||
### Placement
|
||||
|
||||
**On product page:**
|
||||
- Below product details (after add-to-cart)
|
||||
- Before related products
|
||||
- Anchor link in product info: "★★★★★ (127 reviews)"
|
||||
|
||||
**Separate reviews page:**
|
||||
- Only for very large catalogs (500+ reviews)
|
||||
- Link: "View All Reviews"
|
||||
- Most stores show reviews inline on product page
|
||||
|
||||
## Rating Summary and Distribution
|
||||
|
||||
### Average Rating Display
|
||||
|
||||
**Show prominently:**
|
||||
- Average rating: "★★★★★ 4.5 out of 5"
|
||||
- Total review count: "Based on 127 reviews"
|
||||
- Large stars (24-32px)
|
||||
|
||||
### Rating Distribution (CRITICAL)
|
||||
|
||||
**Visual breakdown with clickable bars:**
|
||||
```
|
||||
5 ★ [████████████████████] 82 (65%)
|
||||
4 ★ [██████░░░░░░░░░░░░░░] 25 (20%)
|
||||
3 ★ [██░░░░░░░░░░░░░░░░░░] 10 (8%)
|
||||
2 ★ [█░░░░░░░░░░░░░░░░░░░] 5 (4%)
|
||||
1 ★ [█░░░░░░░░░░░░░░░░░░░] 5 (3%)
|
||||
```
|
||||
|
||||
**Make bars clickable:**
|
||||
- Click to filter reviews by rating
|
||||
- Shows only selected star ratings
|
||||
- "Show all" to reset filter
|
||||
|
||||
**Why distribution matters:**
|
||||
- Perfect 5.0 rating seems fake (customers trust 4.2-4.5 average)
|
||||
- Showing negative reviews builds trust
|
||||
- Distribution helps customers understand product quality
|
||||
|
||||
### No Reviews State
|
||||
|
||||
**When no reviews:**
|
||||
- "No reviews yet"
|
||||
- "Be the first to review this product"
|
||||
- "Write a Review" button prominent
|
||||
- Don't show 0 stars or empty rating
|
||||
|
||||
## Sorting and Filtering
|
||||
|
||||
### Sort Options (CRITICAL)
|
||||
|
||||
**Essential sorting:**
|
||||
- **Most Recent** (default) - shows latest feedback
|
||||
- **Most Helpful** (by upvotes) - surfaces best reviews
|
||||
- **Highest Rating** (5 stars first) - see positive feedback
|
||||
- **Lowest Rating** (1 star first) - see concerns
|
||||
|
||||
**Dropdown selector:**
|
||||
```
|
||||
Sort by: [Most Recent ▾]
|
||||
```
|
||||
|
||||
### Filter Options
|
||||
|
||||
**Filter by rating:**
|
||||
- All ratings (default)
|
||||
- 5 stars only
|
||||
- 4+ stars
|
||||
- 3 stars or less (see negative feedback)
|
||||
|
||||
**Filter by criteria:**
|
||||
- Verified purchases only (highest trust)
|
||||
- With photos only (visual proof)
|
||||
- Recent (last 30 days, 6 months)
|
||||
|
||||
**Show filtered count:**
|
||||
- "Showing 24 of 127 reviews"
|
||||
|
||||
## Review Submission
|
||||
|
||||
### Review Form Fields
|
||||
|
||||
**Required:**
|
||||
- Star rating (1-5 stars selector)
|
||||
- Review text (textarea, 50-500 characters)
|
||||
- Reviewer name (if not logged in)
|
||||
|
||||
**Optional:**
|
||||
- Review title/headline
|
||||
- Upload images (2-5 max)
|
||||
- Would you recommend? (Yes/No)
|
||||
|
||||
**Form placement:**
|
||||
- "Write a Review" button opens modal or inline form
|
||||
- Position near rating summary
|
||||
|
||||
### Form Validation
|
||||
|
||||
**Requirements:**
|
||||
- Rating must be selected
|
||||
- Minimum review length (50 characters)
|
||||
- Show character counter: "50 / 500 characters"
|
||||
- Validate before submit
|
||||
|
||||
**Success:**
|
||||
- "Thank you for your review!"
|
||||
- "Your review is pending approval" (if moderation enabled)
|
||||
|
||||
## Trust Signals
|
||||
|
||||
### Verified Purchase Badge (CRITICAL)
|
||||
|
||||
**Display:**
|
||||
- Badge or checkmark: "✓ Verified Purchase"
|
||||
- Position near reviewer name
|
||||
- Green color or checkmark icon
|
||||
- Only for confirmed customers
|
||||
|
||||
**Why it matters:**
|
||||
- Builds trust (real customer, not fake)
|
||||
- Reduces suspicion of paid reviews
|
||||
- Higher credibility
|
||||
|
||||
### Helpful Votes
|
||||
|
||||
**Upvote/downvote system:**
|
||||
- "Was this review helpful?"
|
||||
- [👍 Yes (24)] [👎 No (2)]
|
||||
- Click to vote (one vote per user)
|
||||
- Powers "Most Helpful" sorting
|
||||
|
||||
**Benefits:**
|
||||
- Surfaces most useful reviews
|
||||
- Community validation
|
||||
- Reduces impact of unhelpful reviews
|
||||
|
||||
### Review Images (Optional)
|
||||
|
||||
Customer-uploaded photos (3-4 max per review, 60-80px thumbnails, click to enlarge). Visual proof increases trust and engagement.
|
||||
|
||||
### Store Responses (Recommended)
|
||||
|
||||
Seller replies below original review (indented, light gray background). Respond to negative reviews professionally - shows you care, addresses concerns without being defensive.
|
||||
|
||||
## SEO Integration
|
||||
|
||||
**AggregateRating Schema (CRITICAL):** Add structured data to show star ratings in search results. Include `ratingValue` (avg rating), `reviewCount`, `bestRating` (5), `worstRating` (1).
|
||||
|
||||
**SEO benefits:** Star ratings in search results, higher CTR, rich snippets. See seo.md for implementation details.
|
||||
|
||||
**Important:** Only include if reviews are real. Fake reviews violate Google guidelines.
|
||||
|
||||
## Display Patterns
|
||||
|
||||
**Individual review card:**
|
||||
Star rating (16-20px) + text + reviewer name (first name + initial) + date + verified badge + helpful votes. Truncate long reviews (200-300 chars) with "Read more".
|
||||
|
||||
**Mobile:**
|
||||
Single column, touch-friendly votes (44px), full-screen sort select, filter bottom sheet, "Load more" pagination.
|
||||
|
||||
## Checklist
|
||||
|
||||
**Essential features:**
|
||||
|
||||
- [ ] Star rating summary (average + count)
|
||||
- [ ] Rating distribution bar chart (5 to 1 stars)
|
||||
- [ ] Clickable bars to filter by rating
|
||||
- [ ] Sort dropdown (Most Recent, Most Helpful, Highest/Lowest)
|
||||
- [ ] Filter options (verified, with photos, by rating)
|
||||
- [ ] Individual reviews with: stars, text, name, date
|
||||
- [ ] Verified purchase badge
|
||||
- [ ] Helpful votes (upvote/downvote)
|
||||
- [ ] Review submission form (rating, text)
|
||||
- [ ] Form validation (minimum length, required rating)
|
||||
- [ ] "Read more" for long reviews
|
||||
- [ ] Store responses to reviews (recommended)
|
||||
- [ ] Review images (customer uploads, optional)
|
||||
- [ ] Mobile: Touch targets 44px minimum
|
||||
- [ ] Pagination or "Load more" button
|
||||
- [ ] No reviews state ("Be the first to review")
|
||||
- [ ] AggregateRating structured data (SEO)
|
||||
- [ ] ARIA labels for star ratings
|
||||
- [ ] Keyboard accessible (all interactions)
|
||||
Reference in New Issue
Block a user