## The Headless CMS Visual Feedback Challenge

Headless architecture separates content from presentation:

**Content layer:** Contentful, Sanity, Strapi, Hygraph, etc.  **Presentation layer:** Next.js, Nuxt, Gatsby, Astro, etc.

**The problem:** Most CMS feedback features only work on content, not on how it renders.

- Contentful comments are on entries, not on the webpage
- Sanity's studio shows content, not the frontend
- Strapi's admin doesn't show the final design

**What teams actually need:** "This headline is too long for the hero section" or "The image crops poorly on mobile"—feedback that only makes sense when viewing the rendered frontend.

## Visual Feedback in the Headless Workflow

### Traditional (Non-Headless) Workflow:

1. Edit content in CMS
2. Preview changes in CMS preview
3. Comment on CMS preview
4. Publish

### Headless Workflow with Visual Feedback:

1. Edit content in headless CMS
2. Trigger frontend preview build (Vercel, Netlify preview)
3. Create visual feedback link for preview URL
4. Reviewers comment on rendered frontend
5. Feedback informs CMS edits AND code changes
6. Publish content AND deploy frontend

## Integrating Commentblocks with Headless CMS

### Step 1: Set up preview deployments

Most headless CMS platforms support preview URLs:

**Contentful:** Preview API + Next.js preview mode  
**Sanity:** GROQ preview + custom preview route  
**Strapi:** Draft content + preview plugin

These preview deployments show unpublished content on the actual frontend.

### Step 2: Create feedback links for preview URLs

When your preview deployment is ready:

1. Copy the preview URL (e.g., `preview.mysite.com/blog/new-post`)
2. Paste into Commentblocks
3. Get shareable feedback link
4. Share with editors, clients, stakeholders

### Step 3: Collect feedback on rendered content

Reviewers see the actual website—not the CMS admin. They can comment on:

- How content renders visually
- Layout issues caused by content length
- Image cropping and placement
- Typography and spacing
- Mobile responsiveness

### Step 4: Route feedback appropriately

Feedback might require:

- **Content changes** (handled in CMS by editors)
- **Code changes** (handled by developers)
- **Both** (coordinate between teams)

Visual feedback tools don't automatically know which is which—that's a workflow decision.

## Why Not Use CMS-Native Comments?

CMS comments serve a different purpose:

**CMS Comments**         | **Visual Feedback Tools**  
Comment on content fields  | Comment on rendered output  
Seen in CMS admin         | Seen on actual website  
For content team          | For content + design + client  
Text-based               | Visual (screenshots, pins)  
One content entry at a time | Full page context

**Both have value.** Use CMS comments for content-level discussion ("Is this headline accurate?") and visual feedback tools for presentation-level discussion ("This headline breaks the layout").

## Workflow Example: Contentful + Next.js + Commentblocks

### Content editing phase:

1. Editor creates/edits entry in Contentful
2. Uses Contentful comments for content questions
3. Saves as draft (not published)

### Preview phase:

1. Next.js preview mode loads draft content from Contentful
2. Preview URL generated (e.g., via Vercel preview deployments)
3. PM creates Commentblocks link for preview URL
4. Shares with client for review

### Visual QA phase:

1. Client reviews live preview (sees real rendering)
2. Pins comments on visual issues
3. Feedback appears in Commentblocks dashboard

### Resolution phase:

1. PM reviews feedback
2. Content issues → routed to editor (Contentful changes)
3. Design issues → routed to developer (code changes)
4. Both → coordinated implementation

### Publish phase:

1. Content published in Contentful
2. Frontend deployed
3. Feedback links archived or updated

## Tools That Work Well with Headless CMS

### Link-Based (Recommended for Headless)

**Commentblocks, Pastel, Markup.io**

- Work on any preview URL
- No code changes to frontend
- No CMS plugin needed

### Widget-Based (Requires Code)

**Userback, Marker.io**

- Can embed in preview environment
- More setup but deeper integration
- Might need conditional loading for preview-only

## Automating Feedback Links for Preview Deployments

For frequent preview deploys:

### Using Vercel + Zapier:

1. Vercel triggers webhook on successful deploy
2. Zapier catches webhook
3. Zapier creates Commentblocks feedback link
4. Zapier posts link to Slack

### Using GitHub Actions:

1. Deploy preview via CI
2. Action calls Commentblocks API to create link
3. Action comments on PR with feedback link

This automation means every preview deployment automatically gets a feedback link.

## Common Mistakes

**Collecting feedback in the CMS admin.** Editors can comment on content there, but clients and external reviewers need to see the actual website.

**Using the same feedback link for multiple preview versions.** Each preview deployment is a snapshot. Create new links for significant changes.

**Ignoring the content/code distinction.** Not all visual feedback can be fixed in the CMS. Some requires frontend development.

## Frequently Asked Questions

### Does visual feedback integrate back into Contentful/Sanity?

Not automatically. Feedback tools are separate from CMS platforms. You manually route feedback to the appropriate system.

### What if preview deployments are password-protected?

Link-based tools can handle authenticated URLs. You authenticate once when creating the link; reviewers access via the feedback URL.

### Can I use this for production site feedback too?

Yes. The same tools work on production URLs. You'd create feedback links for live pages during post-launch QA.