@plannotator/pi-extension 0.19.13 → 0.19.14

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (8) hide show
  1. package/package.json +1 -1
  2. package/plannotator.html +2 -2
  3. package/review-editor.html +2 -2
  4. package/skills/plannotator-visual-explainer/SKILL.md +72 -86
  5. package/skills/plannotator-visual-explainer/references/design-system.md +560 -0
  6. package/skills/plannotator-visual-explainer/references/pr-components.md +717 -0
  7. package/skills/plannotator-visual-explainer/references/svg-patterns.md +368 -0
  8. package/skills/plannotator-visual-explainer/references/extended-patterns.md +0 -629
package/skills/plannotator-visual-explainer/SKILL.md CHANGED
@@ -2,124 +2,110 @@
2
2
  name: plannotator-visual-explainer
3
3
  disable-model-invocation: true
4
4
  description: >
5
- Generate beautiful, self-contained HTML visualizations themed with Plannotator's design system.
6
- Wraps the visual-explainer skill by nicobailon with Plannotator theme token integration. Use for
7
- architecture diagrams, diff reviews, plan reviews, data tables, slide decks, project recaps, or
8
- any visual explanation of technical concepts — whenever you want output styled consistently with
9
- Plannotator's UI and compatible with --render-html annotation. Triggers on the same prompts as
10
- visual-explainer (diagrams, architecture overviews, visual plans, diff reviews) but produces
11
- output that uses Plannotator CSS custom properties instead of custom palettes.
5
+ Generate self-contained HTML visualizations with Plannotator theming. Use for implementation
6
+ plans, PR explainers, architecture diagrams, data tables, slide decks, and any visual
7
+ explanation of technical concepts. Plans and PR explainers follow Plannotator's prescriptive
8
+ approach; all other visual content delegates to nicobailon/visual-explainer.
12
9
  ---
13
10
 
14
11
  # Plannotator Visual Explainer
15
12
 
16
- This skill wraps [visual-explainer](https://github.com/nicobailon/visual-explainer) by Nico Bailon with Plannotator theme integration and additional component patterns. You follow visual-explainer's workflow, references, templates, and anti-slop rules — with Plannotator's color/typography tokens and extended patterns for plans and technical documents.
13
+ Three paths depending on content type. Each has its own references and structure.
17
14
 
18
- ## Setup
15
+ ## Route by content type
19
16
 
20
- Before generating, ensure `visual-explainer` is available:
17
+ **Implementation plan, design doc, or proposal** → Follow the [Plan path](#plan-path). Read `references/design-system.md` and `references/svg-patterns.md`. Prescriptive structure.
21
18
 
22
- 1. Check if the skill exists at any of these paths (in order):
23
- - `~/.claude/skills/visual-explainer/SKILL.md`
24
- - `~/.agents/skills/visual-explainer/SKILL.md`
25
- - `~/.codex/skills/visual-explainer/SKILL.md`
19
+ **PR explainer, diff review, or code change walkthrough** → Follow the [PR path](#pr-path). Read `references/design-system.md` and `references/pr-components.md`. Prescriptive structure.
26
20
 
27
- 2. If not found, install it:
28
- ```bash
29
- npx skills add nicobailon/visual-explainer -g --yes
30
- ```
21
+ **Everything else** (architecture diagrams, data tables, slide decks, project recaps, general visual explanations) → Follow the [Visual explainer path](#visual-explainer-path). Delegates to nicobailon/visual-explainer with Plannotator theme tokens.
31
22
 
32
- 3. Read the visual-explainer `SKILL.md` to absorb its full workflow, diagram type routing, structure rules, and anti-slop guidelines. Read its `references/` and `templates/` as directed by its workflow.
23
+ ## Delivery
33
24
 
34
- ## Theme Override
25
+ Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
35
26
 
36
- Instead of visual-explainer's custom palettes and font pairings, use Plannotator's semantic theme tokens. Read `references/theme-override.md` for the exact CSS custom properties and mapping table. Apply these **after** reading visual-explainer's references — they replace only the color and typography layer.
27
+ **Plans/proposals** (user should approve/deny):
28
+ ```bash
29
+ plannotator annotate <file> --render-html --gate
30
+ ```
37
31
 
38
- ## Extended Patterns
32
+ **Everything else** (informational):
33
+ ```bash
34
+ plannotator annotate <file> --render-html
35
+ ```
39
36
 
40
- Plannotator adds component patterns that complement visual-explainer's toolkit. Read `references/extended-patterns.md` for timelines, inline SVG diagrams, code blocks with syntax highlighting, risk tables, and open question callouts. Use these alongside Nico's `.ve-card`, `.kpi-card`, `.pipeline` components — they share the same theme tokens.
37
+ ---
41
38
 
42
- ## Design Philosophy: Use the Power of HTML
39
+ ## Plan path
43
40
 
44
- The point of generating HTML instead of markdown is spatial layout. Don't pack every piece of information into dense cards. Let the page breathe.
41
+ For implementation plans, design docs, feature specs, migration guides, and proposals.
45
42
 
46
- - **Whitespace is a feature.** Generous padding, large section gaps, breathing room between cards. If a section feels cramped, it needs more space, not smaller text.
47
- - **One idea per viewport.** The reader should be able to absorb one concept at a time as they scroll. A hero section, then a diagram, then a detail grid — not all three crammed together.
48
- - **Visual weight signals importance.** Hero sections dominate (large type, accent-tinted backgrounds, more padding). Supporting details are compact and can collapse. Not everything deserves equal treatment.
49
- - **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A before/after grid shows change. A code block shows the interface. Use the right visual element — don't describe things in prose that a component could show directly.
50
- - **Timelines show sequence without estimates.** Show the phases and their dependencies, but do not attach hour/day/week estimates. AI consistently misjudges timing. Showing phases in order communicates sequencing; attaching numbers communicates false precision.
43
+ **Before generating, read:**
44
+ 1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
45
+ 2. `references/svg-patterns.md` — inline SVG building blocks for architecture diagrams, flowcharts, data flow
51
46
 
52
- ## Workflow
47
+ **Document structure (in order, pick what fits):**
53
48
 
54
- 1. **Read** visual-explainer's SKILL.md (full workflow, diagram types, quality checks)
55
- 2. **Read** the relevant visual-explainer references and templates for your content type
56
- 3. **Read** `references/theme-override.md` for Plannotator color/typography tokens
57
- 4. **Read** `references/extended-patterns.md` for additional components (timelines, code blocks, risk tables, SVG diagrams)
58
- 5. **Generate** following visual-explainer's structure and rules, with Plannotator tokens and extended patterns. Use Nico's component classes (`.ve-card`, `.ve-card--hero`, `.kpi-card`, `.pipeline`, etc.) for cards and layout. Use the extended patterns for timelines, code blocks, risk tables, and SVG diagrams.
59
- 6. **Deliver** via Plannotator's annotation UI:
49
+ 1. **Header** — eyebrow label (mono, uppercase), title (serif, large), prompt box (the original brief)
50
+ 2. **Summary strip** — 3-5 stat cards showing key numbers at a glance (components, endpoints, tables, etc.)
51
+ 3. **Milestones / timeline** — vertical timeline showing phases without time estimates. Phases show sequence and dependencies, not duration.
52
+ 4. **Architecture / data flow** — inline SVG diagram. Use for 3+ interacting components. Highlighted boxes for new components, dashed arrows for async paths.
53
+ 5. **Mockups** — build UI mockups in HTML/CSS directly, not as descriptions
54
+ 6. **Key code** — dark-theme code blocks with syntax highlighting. Only architecturally significant interfaces/schemas — not every function.
55
+ 7. **Risks & mitigations** — table with severity badges (HIGH/MED/LOW)
56
+ 8. **Open questions** — callout cards with decision owner ("Decide with: backend team")
60
57
 
61
- **If the output is a plan or proposal** (something the user should approve/deny):
62
- ```bash
63
- plannotator annotate <file> --render-html --gate
64
- ```
58
+ Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
65
59
 
66
- **If the output is a visual explainer, diagram, or informational page:**
67
- ```bash
68
- plannotator annotate <file> --render-html
69
- ```
60
+ **Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
70
61
 
71
- Always use `--render-html` so the HTML renders as-is in the Plannotator UI with theme inheritance and annotation support. Do NOT use `open` or `xdg-open` directly.
62
+ **Quality bar:** The plan answers "what, why, and how" within 30 seconds of reading. Whitespace is a feature — one idea per viewport.
72
63
 
73
- ## What visual-explainer provides (do not duplicate)
64
+ ---
74
65
 
75
- All of these come from visual-explainer — read them there, don't reinvent them:
76
- - Diagram type routing (architecture, flowchart, sequence, ER, state, mind map, etc.)
77
- - Mermaid integration (theming, zoom controls, scaling, layout direction)
78
- - CSS structural patterns (ve-card, grids, connectors, depth tiers, collapsibles)
79
- - Slide deck mode (viewport-snapping presentations)
80
- - Data table patterns (sticky headers, status indicators, responsive scrolling)
81
- - Anti-slop rules (forbidden fonts, colors, animations, patterns)
82
- - Quality checks (squint test, swap test, overflow protection)
83
- - Animation guidelines (staggered entrance, reduced-motion support)
66
+ ## PR path
84
67
 
85
- ## Plan-specific guidance
68
+ For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
86
69
 
87
- When the output is an implementation plan, design doc, or proposal:
70
+ **Before generating, read:**
71
+ 1. `references/design-system.md` — Plannotator theme tokens, typography, component patterns
72
+ 2. `references/pr-components.md` — diff rendering, review comment bubbles, risk chips, file cards, before/after panels
88
73
 
89
- **Adapt the visual vocabulary to the task:**
90
- - **Backend/API work**: Lead with data flow diagrams, schemas, API signatures
91
- - **Frontend/UI work**: Lead with mockups, component hierarchy, state flow
92
- - **Infrastructure/DevOps**: Lead with architecture diagrams, deployment flow
93
- - **Refactoring**: Lead with before/after diagrams showing structural change
94
- - **Cross-cutting features**: Lead with a system map showing all touchpoints
74
+ **Document structure (in order, pick what fits):**
95
75
 
96
- **Section menu — pick what fits:**
97
- Solution overview, architecture/data flow diagram, UI mockups, key code, integration points, risks & mitigations, open questions, considerations & rationale, reusability & code quality. Not every plan needs every section — choose what serves the content.
76
+ 1. **Header** — PR title, meta strip (file count, +/- lines, branch, author)
77
+ 2. **TL;DR** — bordered card with primary accent left border. 2-3 sentences. Readers who see nothing else should get the gist.
78
+ 3. **Why** — motivation and before/after comparison (two-column grid)
79
+ 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.
80
+ 5. **Risk map** — visual chips showing which files need careful review vs. which are mechanical. Three tiers: attention (destructive), medium (warning), safe (success).
81
+ 6. **Where to focus** — numbered callout cards. Each names a file/function and describes the concern.
82
+ 7. **Test plan** — checkbox-style verification checklist
83
+ 8. **Rollout** (if applicable) — phased deployment with feature flags
98
84
 
99
- **What NOT to include in plans:**
100
- - Time estimates (timelines showing sequence are fine, hour/day estimates are not)
101
- - Boilerplate sections that would just say "N/A"
102
- - Exhaustive file lists — show the important files, not every file touched
85
+ Use Pierre diffs via CDN for syntax-highlighted inline diffs — see `references/pr-components.md` for the pattern.
103
86
 
104
- **Quality bar for plans:** The plan should answer "what are we building, why, and how" within 30 seconds of reading.
87
+ ---
88
+
89
+ ## Visual explainer path
105
90
 
106
- ## PR explainer guidance
91
+ For architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.
107
92
 
108
- When the output is a PR walkthrough, diff review, or code change explainer:
93
+ **Before generating:**
109
94
 
110
- - **TL;DR first** — a bordered card summarizing what the PR does and why, so readers who skim get the gist
111
- - **Risk map** — visual chips showing which files need careful review vs. which are mechanical
112
- - **Inline diffs** — use the diff rendering pattern from `references/extended-patterns.md` for important hunks (not every hunk)
113
- - **File-by-file commentary** — collapsible cards per file with a "why" paragraph explaining the purpose of changes
114
- - **"Where to focus"** — numbered callouts telling reviewers exactly what to look at and why
115
- - **Before/after comparison** — two-column grid for behavior changes
95
+ 1. Ensure `visual-explainer` is installed:
96
+ - Check: `~/.claude/skills/visual-explainer/SKILL.md` or `~/.agents/skills/visual-explainer/SKILL.md`
97
+ - If not found: `npx skills add nicobailon/visual-explainer -g --yes`
98
+ 2. Read visual-explainer's `SKILL.md` (workflow, diagram types, anti-slop rules)
99
+ 3. Read the relevant visual-explainer references and templates for your content type
100
+ 4. Read `references/theme-override.md` — Plannotator tokens replacing Nico's palettes
116
101
 
117
- See `references/extended-patterns.md` for diff rendering, review comment bubbles, and file badge patterns.
102
+ 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.
103
+
104
+ ---
118
105
 
119
- ## What this skill adds
106
+ ## Design philosophy (all paths)
120
107
 
121
- - Plannotator theme tokens (colors, typography, radii) — see `references/theme-override.md`
122
- - Extended component patterns (timelines, code blocks, risk tables, SVG diagrams, open questions) — see `references/extended-patterns.md`
123
- - Plan-specific guidance (section menu, adaptation by task type, quality bar)
124
- - `--render-html` delivery with annotation support and theme inheritance
125
- - Design philosophy emphasizing spatial layout, breathing room, and visual hierarchy
108
+ - **Whitespace is a feature.** Generous padding, large section gaps. If cramped, add space — don't shrink text.
109
+ - **One idea per viewport.** Hero section, then diagram, then detail grid — not all crammed together.
110
+ - **Show, don't describe.** A timeline shows sequencing. A diagram shows relationships. A code block shows the interface.
111
+ - **No time estimates.** Timelines show phases and dependencies. Never attach hour/day estimates.