backnotprop / backnotprop/plannotator
feat: rich directive components for structured visual blocks
- Dominant language
- TypeScript
- Stars
- 8.7k
- Forks
- 649
- Avg merge
- 11h 12m
- Merged PRs (30d)
- 109
Description
## Problem
Agents generating plans and explainers through Plannotator currently write 20-30KB of raw HTML with copy-pasted CSS tokens because the markdown renderer lacks structured visual components. The directive system (`:::kind ... :::`) already parses arbitrary kinds but only renders a generic Callout for all of them.
This causes token drift (agents regenerate CSS from memory), bloated output, annotation degradation (HTML uses iframe bridge), and theme disconnection (standalone HTML hardcodes light-theme tokens).
## Proposal
Extend the directive system with 5 purpose-built React components so agents write concise markdown instead of verbose, inconsistent HTML:
- **`:::stats`** — summary strip with stat cards (pipe-delimited: `value | label | color`)
- **`:::milestone [status]`** — timeline entry with vertical connector (`done`/`warn`/`blocked`)
- **`:::risks`** — risk grid with severity badges (`HIGH | name | mitigation`)
- **`:::cols`** — multi-column layout with `:::col` children (responsive, N-column)
- **`:::diagram [caption]`** — bordered panel for mermaid/graphviz or inline SVG
### Parser change
Extend the directive regex to capture optional trailing args on the opening line (`:::milestone done` → `directiveArgs='done'`). Backwards compatible — existing directives route to Callout via the default case.
### Theme integration
Components use Tailwind classes resolving through existing CSS variable bridge. No `:root` token declarations needed. Theme tokens flow from the `theme-{name}` class on ``.
### Annotation compatibility
Each component renders with `data-block-id` and `data-block-type="directive"`. Existing web-highlighter selection works on all rendered text.
### Skill updates
The `plannotator-visual-explainer` skill is updated to route plans through directives by default. HTML references (`design-system.md`, `svg-patterns.md`) are gated behind an explicit escape hatch — agents only read them when directives don't cover the layout. The `plannotator-setup-goal` skill's plan phase also gains directive awareness.
## Implementation
PR: victor-software-house/plannotator#1 (forthcoming)
~780 lines across 15 files. All existing tests pass; 5 new parser tests added.
Contributor guide
Assessment
This issue has not been assessed yet.