@plannotator/pi-extension 0.19.12 → 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 +73 -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
@@ -1,124 +1,111 @@
1
1
  ---
2
2
  name: plannotator-visual-explainer
3
+ disable-model-invocation: true
3
4
  description: >
4
- Generate beautiful, self-contained HTML visualizations themed with Plannotator's design system.
5
- Wraps the visual-explainer skill by nicobailon with Plannotator theme token integration. Use for
6
- architecture diagrams, diff reviews, plan reviews, data tables, slide decks, project recaps, or
7
- any visual explanation of technical concepts — whenever you want output styled consistently with
8
- Plannotator's UI and compatible with --render-html annotation. Triggers on the same prompts as
9
- visual-explainer (diagrams, architecture overviews, visual plans, diff reviews) but produces
10
- 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.
11
9
  ---
12
10
 
13
11
  # Plannotator Visual Explainer
14
12
 
15
- 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.
16
14
 
17
- ## Setup
15
+ ## Route by content type
18
16
 
19
- 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.
20
18
 
21
- 1. Check if the skill exists at any of these paths (in order):
22
- - `~/.claude/skills/visual-explainer/SKILL.md`
23
- - `~/.agents/skills/visual-explainer/SKILL.md`
24
- - `~/.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.
25
20
 
26
- 2. If not found, install it:
27
- ```bash
28
- npx skills add nicobailon/visual-explainer -g --yes
29
- ```
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.
30
22
 
31
- 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
32
24
 
33
- ## Theme Override
25
+ Always deliver via Plannotator's annotation UI. Do NOT use `open` or `xdg-open`.
34
26
 
35
- 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
+ ```
36
31
 
37
- ## Extended Patterns
32
+ **Everything else** (informational):
33
+ ```bash
34
+ plannotator annotate <file> --render-html
35
+ ```
38
36
 
39
- 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
+ ---
40
38
 
41
- ## Design Philosophy: Use the Power of HTML
39
+ ## Plan path
42
40
 
43
- 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.
44
42
 
45
- - **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.
46
- - **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.
47
- - **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.
48
- - **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.
49
- - **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
50
46
 
51
- ## Workflow
47
+ **Document structure (in order, pick what fits):**
52
48
 
53
- 1. **Read** visual-explainer's SKILL.md (full workflow, diagram types, quality checks)
54
- 2. **Read** the relevant visual-explainer references and templates for your content type
55
- 3. **Read** `references/theme-override.md` for Plannotator color/typography tokens
56
- 4. **Read** `references/extended-patterns.md` for additional components (timelines, code blocks, risk tables, SVG diagrams)
57
- 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.
58
- 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")
59
57
 
60
- **If the output is a plan or proposal** (something the user should approve/deny):
61
- ```bash
62
- plannotator annotate <file> --render-html --gate
63
- ```
58
+ Not every plan needs every section. Skip what doesn't serve the content. Never include time estimates, boilerplate sections, or exhaustive file lists.
64
59
 
65
- **If the output is a visual explainer, diagram, or informational page:**
66
- ```bash
67
- plannotator annotate <file> --render-html
68
- ```
60
+ **Adapt to the task:** Backend → lead with data flow. Frontend → lead with mockups. Refactoring → lead with before/after diagrams. Infrastructure → lead with architecture.
69
61
 
70
- 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.
71
63
 
72
- ## What visual-explainer provides (do not duplicate)
64
+ ---
73
65
 
74
- All of these come from visual-explainer — read them there, don't reinvent them:
75
- - Diagram type routing (architecture, flowchart, sequence, ER, state, mind map, etc.)
76
- - Mermaid integration (theming, zoom controls, scaling, layout direction)
77
- - CSS structural patterns (ve-card, grids, connectors, depth tiers, collapsibles)
78
- - Slide deck mode (viewport-snapping presentations)
79
- - Data table patterns (sticky headers, status indicators, responsive scrolling)
80
- - Anti-slop rules (forbidden fonts, colors, animations, patterns)
81
- - Quality checks (squint test, swap test, overflow protection)
82
- - Animation guidelines (staggered entrance, reduced-motion support)
66
+ ## PR path
83
67
 
84
- ## Plan-specific guidance
68
+ For PR walkthroughs, diff reviews, code change explainers, and reviewer guides.
85
69
 
86
- 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
87
73
 
88
- **Adapt the visual vocabulary to the task:**
89
- - **Backend/API work**: Lead with data flow diagrams, schemas, API signatures
90
- - **Frontend/UI work**: Lead with mockups, component hierarchy, state flow
91
- - **Infrastructure/DevOps**: Lead with architecture diagrams, deployment flow
92
- - **Refactoring**: Lead with before/after diagrams showing structural change
93
- - **Cross-cutting features**: Lead with a system map showing all touchpoints
74
+ **Document structure (in order, pick what fits):**
94
75
 
95
- **Section menu — pick what fits:**
96
- 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
97
84
 
98
- **What NOT to include in plans:**
99
- - Time estimates (timelines showing sequence are fine, hour/day estimates are not)
100
- - Boilerplate sections that would just say "N/A"
101
- - 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.
102
86
 
103
- **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
104
90
 
105
- ## PR explainer guidance
91
+ For architecture diagrams, data tables, slide decks, project recaps, comparisons, and any other visual explanation.
106
92
 
107
- When the output is a PR walkthrough, diff review, or code change explainer:
93
+ **Before generating:**
108
94
 
109
- - **TL;DR first** — a bordered card summarizing what the PR does and why, so readers who skim get the gist
110
- - **Risk map** — visual chips showing which files need careful review vs. which are mechanical
111
- - **Inline diffs** — use the diff rendering pattern from `references/extended-patterns.md` for important hunks (not every hunk)
112
- - **File-by-file commentary** — collapsible cards per file with a "why" paragraph explaining the purpose of changes
113
- - **"Where to focus"** — numbered callouts telling reviewers exactly what to look at and why
114
- - **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
115
101
 
116
- 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
+ ---
117
105
 
118
- ## What this skill adds
106
+ ## Design philosophy (all paths)
119
107
 
120
- - Plannotator theme tokens (colors, typography, radii) — see `references/theme-override.md`
121
- - Extended component patterns (timelines, code blocks, risk tables, SVG diagrams, open questions) — see `references/extended-patterns.md`
122
- - Plan-specific guidance (section menu, adaptation by task type, quality bar)
123
- - `--render-html` delivery with annotation support and theme inheritance
124
- - 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.