Back to Details

plannotator-visual-explainer

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Plannotator Visual Explainer

Plannotator 可视化讲解工具

Three paths depending on content type. Each has its own references and structure.
根据内容类型分为三种路径，每种路径都有对应的参考文档和结构。

Route by content type

按内容类型选择路径

Implementation plan, design doc, or proposal → Follow the Plan path. Read 
references/design-system.md
and 
references/svg-patterns.md
. Prescriptive structure.
PR explainer, diff review, or code change walkthrough → Follow the PR path. Read 
references/design-system.md
and 
references/pr-components.md
. Prescriptive structure.
Everything else (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the Visual explainer path. Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
实施计划、设计文档或提案 → 遵循计划路径。阅读
references/design-system.md
和
references/svg-patterns.md
。采用规范结构。
PR说明文档、差异评审或代码变更讲解 → 遵循PR路径。阅读
references/design-system.md
和
references/pr-components.md
。采用规范结构。
其他所有内容（架构图、数据表、幻灯片、项目回顾、通用可视化讲解）→ 遵循可视化讲解路径。通过Plannotator主题标记交由nicobailon/visual-explainer处理。

Delivery

交付方式

Always deliver via Plannotator's annotation UI. Do NOT use 
open
or 
xdg-open
.
Plans/proposals (user should approve/deny):
bash
plannotator annotate <file> --render-html --gate
Everything else (informational):
bash
plannotator annotate <file> --render-html
始终通过Plannotator的注释UI交付内容。请勿使用
open
或
xdg-open
命令。
计划/提案（需用户审批/拒绝）：
bash
plannotator annotate <file> --render-html --gate
其他所有内容（仅供参考）：
bash
plannotator annotate <file> --render-html

Plan path

计划路径

For implementation plans, design docs, feature specs, migration guides, and proposals.
Before generating, read:
  1. references/design-system.md
    — Plannotator theme tokens, typography, component patterns
  2. references/svg-patterns.md
    — inline SVG building blocks for architecture diagrams, flowcharts, data flow
Document structure (in order, pick what fits):
  1. Header — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
  2. Summary strip — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
  3. Milestones / timeline — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
  4. Architecture / data flow — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
  5. Mockups — build UI mockups in HTML/CSS directly, not as descriptions
  6. Key code — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
  7. Risks & mitigations — table with severity badges (HIGH/MED/LOW)
  8. Open questions — callout cards with decision owner ("Decide with: backend team")
Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
Adapt to the task: Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
Quality bar: The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
适用于实施计划、设计文档、功能规格、迁移指南和提案。
生成前需阅读：
  1. references/design-system.md
    — Plannotator主题标记、排版规则、组件模式
  2. references/svg-patterns.md
    — 用于架构图、流程图、数据流的内嵌SVG构建模块
文档结构（按顺序选择适用部分）：
  1. 页眉 — 眉栏标签（等宽字体、大写）、标题（衬线字体、大字号）、提示框（原始需求简述）
  2. 摘要栏 — 3-5个统计卡片，快速展示关键数据（组件数量、接口数量、数据表数量等）
  3. 里程碑/时间线 — 垂直时间线展示阶段顺序，不含时间预估。阶段仅体现顺序和依赖关系，不体现时长。
  4. 架构/数据流 — 内嵌SVG图。适用于包含3个及以上交互组件的场景。新增组件用高亮框标注，异步路径用虚线箭头表示。
  5. 原型图 — 直接用HTML/CSS构建UI原型，而非文字描述
  6. 核心代码 — 深色主题代码块，带语法高亮。仅展示具有架构意义的接口/ schema，无需包含所有函数。
  7. 风险与缓解措施 — 包含严重程度标签（HIGH/MED/LOW）的表格
  8. 待解决问题 — 标注决策负责人的提示卡片（如“决策方：后端团队”）
并非所有计划都需要包含全部章节，可跳过与内容无关的部分。切勿包含时间预估、模板化章节或详尽文件列表。
根据任务调整结构： 后端任务→以数据流为核心；前端任务→以原型图为核心；重构任务→以对比图为核心；基础设施任务→以架构图为核心。
质量标准： 读者在30秒内即可理解计划的“是什么、为什么、怎么做”。留白是核心特性——每个视口只呈现一个核心观点。

PR path

PR路径

For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
Before generating, read:
  1. references/design-system.md
    — Plannotator theme tokens, typography, component patterns
  2. references/pr-components.md
    — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
Document structure (in order, pick what fits):
  1. Header — PR title, meta strip (file count, +/- lines, branch, author)
  2. TL;DR — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
  3. Why — motivation and before/after comparison (two-column grid)
  4. File tour — collapsible cards per file. Each has: file path + badge (NEW/MOD/DEL) + line stats, a "why" paragraph, and important diff hunks. High-risk files expanded, safe files collapsed.
  5. Risk map — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
  6. Where to focus — numbered callout cards. Each names a file/function and describes the concern.
  7. Test plan — checkbox-style verification checklist
  8. Rollout (if applicable) — phased deployment with feature flags
Use Pierre diffs via CDN for syntax-highlighted inline diffs — see 
references/pr-components.md
for the pattern.
适用于PR讲解、差异评审、代码变更说明和评审指南。
生成前需阅读：
  1. references/design-system.md
    — Plannotator主题标记、排版规则、组件模式
  2. references/pr-components.md
    — 差异渲染、评审评论气泡、风险标签、文件卡片、前后对比面板
文档结构（按顺序选择适用部分）：
  1. 页眉 — PR标题、元信息栏（文件数量、代码增减行数、分支、作者）
  2. TL;DR — 左侧带主色调边框的卡片。用2-3句话概括内容。即使读者只看这部分，也能理解核心要点。
  3. 背景原因 — 变更动机和前后对比（双列网格布局）
  4. 文件浏览 — 按文件划分的可折叠卡片。每个卡片包含：文件路径+标签（新增/修改/删除）+行数统计、一段说明文字，以及重要的代码差异片段。高风险文件默认展开，低风险文件默认折叠。
  5. 风险地图 — 可视化标签，标明哪些文件需要重点评审，哪些是机械性变更。分为三个等级：需关注（破坏性变更）、中等（警告）、安全（无风险）。
  6. 重点关注区域 — 带编号的提示卡片。每个卡片标注文件/函数名称及需要关注的问题。
  7. 测试计划 — 复选框形式的验证清单
  8. 发布计划（如适用）— 基于功能开关的分阶段部署方案
通过CDN使用Pierre diff实现带语法高亮的内嵌代码差异——具体模式请参考
references/pr-components.md
。

Visual explainer path

可视化讲解路径

For architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.
Before generating:
  1. Ensure 
    visual-explainer
    is installed:
    • Check: 
      ~/.claude/skills/visual-explainer/SKILL.md
      or 
      ~/.agents/skills/visual-explainer/SKILL.md
    • If not found: 
      npx skills add nicobailon/visual-explainer -g --yes
  2. Read visual-explainer's 
    SKILL.md
    (workflow, diagram types, anti-slop rules)
  3. Read the relevant visual-explainer references and templates for your content type
  4. Read 
    references/theme-override.md
    — Plannotator tokens replacing Nico's palettes
Follow visual-explainer's structure, component classes (
.ve-card
, 
.kpi-card
, 
.pipeline
), and anti-slop rules. The only override is the color/typography layer — Plannotator tokens instead of Nico's custom palettes.
适用于架构图、数据表、幻灯片、项目回顾、对比分析以及其他各类可视化讲解。
生成前准备：
  1. 确保已安装
    visual-explainer
    ：
    • 检查路径：
      ~/.claude/skills/visual-explainer/SKILL.md
      或 
      ~/.agents/skills/visual-explainer/SKILL.md
    • 若未安装：执行命令 
      npx skills add nicobailon/visual-explainer -g --yes
  2. 阅读visual-explainer的
    SKILL.md
    （工作流程、图表类型、精简规则）
  3. 阅读与内容类型对应的visual-explainer参考文档和模板
  4. 阅读
    references/theme-override.md
    — 用Plannotator标记替换Nico的调色板
遵循visual-explainer的结构、组件类（
.ve-card
, 
.kpi-card
, 
.pipeline
）和精简规则。仅需覆盖颜色/排版层——用Plannotator标记替代Nico的自定义调色板。

Design philosophy (all paths)

设计理念（所有路径通用）

  • Whitespace is a feature. Generous padding, large section gaps. If cramped, add space — don't shrink text.
  • One idea per viewport. Hero section, then diagram, then detail grid — not all crammed together.
  • Show, don't describe. A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.
  • No time estimates. Timelines show phases and dependencies. Never attach hour/day estimates.
  • 留白是核心特性。 使用充足的内边距和大段间距。如果内容拥挤，应增加空间而非缩小文字。
  • 每个视口只呈现一个核心观点。 先展示核心区域，再展示图表，最后展示详细网格——切勿将所有内容堆砌在一起。
  • 用展示替代描述。 时间线展示顺序，图表展示关系，代码块展示接口。
  • 不包含时间预估。 时间线仅展示阶段和依赖关系，切勿附加小时/天数预估。