Skip to content

Clarify annotations as implementation notes for AI agent handoff #127

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
mintlify wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Clarify annotations as implementation notes for AI agent handoff #127

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
a017e4f
Clarify annotations as implementation notes for AI agent handoff
mintlify[bot] Apr 10, 2026
a3b01cb
Replace Tip with Note to match docs conventions
mintlify[bot] Apr 13, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions packages/docs/learn/prototype-mode/annotations.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
---
title: Annotations
description: Add implementation notes to guide AI prototype generation.
description: Add implementation notes to guide AI prototype generation and code handoff.
---

<Frame>
Expand All @@ -20,8 +20,14 @@ You should see blue dots on elements for each annotation.

## Exporting to code

Annotations are also useful for documenting your design for handoff. Any annotation will be exported as comments in code:
Annotations double as implementation notes for design-to-code handoff. When you export a page, annotations are included as code comments — so any context you leave during design time carries over automatically.

<Frame>
<img src="/images/prototype-mode/annotation-as-code.png" alt="Annotation persisted as code comment" />
</Frame>

### Using annotations with AI agents

When an AI coding assistant like Claude Code, Cursor, or Codex fetches your design via the [MCP server](/guides/mcp-server), it reads your annotations as part of the exported code. This means you can leave implementation notes while designing — describing desired behaviors, edge cases, or business logic — and your AI agent will pick them up and act on them during implementation.

<Note>Use annotations to capture implementation details as you design, so nothing gets lost during handoff. For example, annotate a button with "Submit form and redirect to /dashboard on success" or a list with "Fetch from /api/items, show skeleton loader while loading."</Note>
Loading