Making HTML Artifacts Collaborative for AI Workflows

Bharath Nayak — Tue, 02 Jun 2026 11:23:28 +0000

Recently, there has been a lot of discussion around a simple question:

Should AI artifacts default to Markdown or HTML?

Markdown is simple, readable, and token-friendly.

HTML is heavier, but it can represent information in a much richer way. With HTML, an artifact can have proper sections, tables, cards, callouts, layouts, visual hierarchy, and even interactive components. While HTML may consume more tokens upfront, the additional structure and clarity can reduce ambiguity and back-and-forth later.

My thinking went in a slightly different direction:

If HTML becomes a serious medium for AI-generated artifacts, how do we make it collaborative?

That's where I noticed a gap.

At work, I use Confluence extensively. Someone writes a specification, others leave comments on specific sections, and those comments are later addressed by the author—or increasingly, by AI. The workflow feels natural.

But with HTML artifacts, collaboration isn't as straightforward.

If I want to comment on a specific paragraph, table row, section, or card, how do I point an AI to the exact location?

"Change the third section" is vague.
Copying and pasting text is brittle.
Raw HTML isn't easy to review visually.

So I started building HTML Review Kit.

GitHub Repository: https://github.com/bharathnayak03/html-review-kit

What is HTML Review Kit?

HTML Review Kit makes static HTML artifacts reviewable and AI-editable.

You can:

Open an HTML artifact in a browser
Annotate specific parts of the rendered page
Leave review comments
Generate a prompt that can be sent directly to an AI coding agent

The generated prompt includes both the review comments and the targeting information needed to locate the corresponding source content.

The approach is inspired by the W3C Web Annotation Data Model:

https://www.w3.org/TR/annotation-model/

How does targeting work?

To help AI identify the exact content being reviewed, the tool captures multiple targeting mechanisms, including:

data-hrk-id
Text Quote Selectors
CSS Selectors
XPath
Source file metadata

This gives AI enough context to reliably locate and modify the correct part of the source document.

Workflow

The workflow looks like this:

Generate or write an HTML artifact
Review it visually
Leave comments on specific elements
Copy the generated review prompt
Ask an AI agent to address the comments
Update the source HTML

Potential Use Cases

HTML Review Kit can be useful for:

AI-generated specifications
Design documents
Product requirement documents
Reports
Dashboards
Knowledge-base articles
Rich documentation
Any HTML-based artifact that benefits from review and iteration

AI Agent Skill Included

I've also added an AI agent skill to the repository.

Install it with:

bash npx skills add bharathnayak03/html-review-kit

Once installed, simply ask your AI coding agent to use html-review-kit while generating HTML artifacts.

x.com

Looking for Feedback

This is an early exploration into making HTML a more collaborative medium for AI workflows.

I'd love to hear your thoughts:

Is this a problem you've run into?
Would a review workflow like this be useful for your team?
What features would make it more valuable?

Feedback, ideas, and contributions are welcome.