backnotprop / backnotprop/plannotator

feat: rich directive components for structured visual blocks

Open
#834 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.