home / skills / velt-js / agent-skills / velt-comments-best-practices

velt-comments-best-practices skill

safe

This skill helps you implement Velt collaborative comments in React/Next.js apps by following best practices for modes, surfaces, and data.

npx playbooks add skill velt-js/agent-skills --skill velt-comments-best-practices

Review the files below or copy the command above to add this skill to your agents.

Files (42)

SKILL.md

4.1 KB

---
name: velt-comments-best-practices
description: Velt Comments implementation patterns and best practices for React, Next.js, and web applications. Use when adding collaborative commenting features, comment modes (Freestyle, Popover, Stream, Text, Page), rich text editor comments (TipTap, SlateJS, Lexical), media player comments, or chart comments.
license: MIT
metadata:
  author: velt
  version: "1.0.0"
---

# Velt Comments Best Practices

Comprehensive implementation guide for Velt's collaborative comments feature in React and Next.js applications. Contains 33 rules across 9 categories, prioritized by impact to guide automated code generation and integration patterns.

## When to Apply

Reference these guidelines when:
- Adding collaborative commenting to a React/Next.js application
- Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
- Integrating comments with rich text editors (TipTap, SlateJS, Lexical)
- Adding comments to media players (Video, Lottie animations)
- Adding comments to charts (Highcharts, ChartJS, Nivo)
- Building custom comment interfaces with standalone components

## Rule Categories by Priority

| Priority | Category | Impact | Prefix |
|----------|----------|--------|--------|
| 1 | Core Setup | CRITICAL | `core-` |
| 2 | Comment Modes | HIGH | `mode-` |
| 3 | Standalone Components | MEDIUM-HIGH | `standalone-` |
| 4 | Comment Surfaces | MEDIUM-HIGH | `surface-` |
| 5 | UI Customization | MEDIUM | `ui-` |
| 6 | Data Model | MEDIUM | `data-` |
| 7 | Debugging & Testing | LOW-MEDIUM | `debug-` |
| 8 | Moderation & Permissions | LOW | `permissions-` |
| 9 | Attachments & Reactions | LOW | `attach-` |

## Quick Reference

### 1. Core Setup (CRITICAL)

- `core-provider-setup` - Initialize VeltProvider with API key
- `core-authentication` - Authenticate users before using comments
- `core-document-setup` - Configure document context for comments

### 2. Comment Modes (HIGH)

- `mode-freestyle` - Pin comments anywhere on page
- `mode-popover` - Google Sheets-style cell comments
- `mode-stream` - Google Docs-style sidebar stream
- `mode-text` - Text highlight comments
- `mode-page` - Page-level comments via sidebar
- `mode-inline-comments` - Traditional inline thread style
- `mode-tiptap` - TipTap editor integration
- `mode-slatejs` - SlateJS editor integration
- `mode-lexical` - Lexical editor integration
- `mode-canvas` - Canvas/drawing comments
- `mode-lottie-player` - Lottie animation frame comments
- `mode-video-player-prebuilt` - Velt prebuilt video player
- `mode-video-player-custom` - Custom video player integration
- `mode-chart-highcharts` - Highcharts data point comments
- `mode-chart-chartjs` - ChartJS data point comments
- `mode-chart-nivo` - Nivo charts data point comments
- `mode-chart-custom` - Custom chart integration

### 3. Standalone Components (MEDIUM-HIGH)

- `standalone-comment-pin` - Manual comment pin positioning
- `standalone-comment-thread` - Render comment threads
- `standalone-comment-composer` - Add comments programmatically

### 4. Comment Surfaces (MEDIUM-HIGH)

- `surface-sidebar` - Comments sidebar component
- `surface-sidebar-button` - Toggle sidebar button

### 5. UI Customization (MEDIUM)

- `ui-comment-dialog` - Customize comment dialog
- `ui-comment-bubble` - Customize comment bubble
- `ui-wireframes` - Use wireframe components

### 6. Data Model (MEDIUM)

- `data-context-metadata` - Add custom metadata
- `data-comment-annotations` - Work with annotations
- `data-filtering-grouping` - Filter and group comments

### 7. Debugging & Testing (LOW-MEDIUM)

- `debug-common-issues` - Common issues and solutions
- `debug-verification` - Verification checklist

## How to Use

Read individual rule files for detailed explanations and code examples:

```
rules/shared/core/core-provider-setup.md
rules/shared/mode/mode-popover.md
```

Each rule file contains:
- Brief explanation of why it matters
- Incorrect code example with explanation
- Correct code example with explanation
- Source pointers to official documentation

## Compiled Documents

- `AGENTS.md` — Compressed index of all rules with file paths (start here)
- `AGENTS.full.md` — Full verbose guide with all rules expanded inline

Overview

This skill documents implementation patterns and best practices for integrating Velt collaborative comments into React, Next.js, and web applications. It prioritizes 33 pragmatic rules across nine categories to guide setup, comment modes, editor integrations, media/chart comments, and UI/data patterns. Use it to standardize reliable, secure, and extensible comment features.

How this skill works

The skill inspects common integration points and prescribes code patterns: provider and authentication setup, document context configuration, and mode-specific integrations (Freestyle, Popover, Stream, Text, Page, Inline). It also covers rich text editor adapters (TipTap, Slate, Lexical), media and chart comment hooks, standalone components, UI customization, data modeling, and debugging checks. Rules are ordered by priority so you apply critical setup first and lower-impact items later.

When to use it

Adding collaborative commenting to a React or Next.js app
Implementing any Velt comment mode (Freestyle, Popover, Stream, Text, Page, Inline)
Integrating comments into rich text editors like TipTap, SlateJS, or Lexical
Attaching comments to media players (video, Lottie) or charts (Highcharts, ChartJS, Nivo)
Building standalone comment components or customizing comment surfaces

Best practices

Initialize VeltProvider with an API key and enforce user authentication before exposing comment features
Configure and pass a document context so comments are scoped and resolvable across sessions
Choose the right comment mode for content: popovers for point comments, stream/sidebar for document review, freestyle for visual pinning
Integrate editor adapters using established adapters (TipTap/Slate/Lexical) to preserve annotations and selection state
Expose standalone components (pin, thread, composer) to allow programmatic comment control and reuse
Add metadata and filtering options to the data model for robust grouping, permissions, and moderation

Example use cases

Code review UI with stream sidebar and inline text highlights using mode-stream and mode-text
Video player with frame-anchored comments and timeline pins using mode-video-player-custom
Design feedback tool where users pin comments on images or canvas using mode-freestyle and mode-canvas
Embedded rich-text editor comments in a CMS using mode-tiptap or mode-slatejs with data-comment-annotations
Interactive dashboards where users comment on chart points (Highcharts/ChartJS/Nivo) using the respective chart modes

FAQ

Do I need authentication to enable comments?

Yes. Authenticate users before exposing comment actions to associate identity, enforce permissions, and support moderation workflows.

Which comment mode should I choose for document review?

Use the stream/sidebar mode for long-form document review and inline or text modes for precise selection-based comments.