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

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