feat(rules): add SVG-first rendering guidance for Emacs app UIs

emacs.md gains an SVG Rendering section: default to svg.el for Emacs app UIs with real visual structure, prototype in HTML first, and stay inside the librsvg-safe constraint sheet from jotto's Emacs 30.2 pgtk spike. ui-prototyping.md points Emacs UI prototypes at the svg.el port target. jotto sent the proposal as inbox handoff 2026-07-11-0248.

1 files changed, 18 insertions, 0 deletions

diff --git a/claude-rules/emacs.md b/claude-rules/emacs.md
index ae4f7cb..2c3b729 100644
--- a/claude-rules/emacs.md
+++ b/claude-rules/emacs.md
@@ -33,3 +33,21 @@ This replaces the quit → relaunch → re-find-and-load-files cycle for most ed
 The reload caveats above are about pushing changes *into* the daemon. The inverse hazard: a tool that edits a file *on disk* while the daemon has an indirect buffer cloned from it. org-capture works through such a buffer, and a disk write (a hand edit, a `git pull` that fast-forwards the file, a `sed`/Write) reverts the base buffer underneath the capture. The capture is left on stale state, can no longer finalize with `C-c C-c`, and a freshly-typed item can be lost or written back against post-edit content. Orphaned `CAPTURE-*` buffers piling up as Craig retries is the visible symptom.
 
 The roam inbox (`~/org/roam/inbox.org`) is the live case — Craig captures into it constantly, and the inbox workflow's roam mode (Phase D) edits it. Before a disk write to a file the daemon may be capturing into, check first: `.ai/scripts/capture-guard <file>` exits non-zero (and names the buffer) when a live capture is cloned from `<file>`, and exits 0 — safe — when there's no capture or no reachable Emacs. Same principle as the reload rule, one layer out: leave the daemon's live buffers authoritative rather than yanking the file from under them.
+
+## SVG Rendering for Emacs App UIs
+
+Consider SVG rendering (`svg.el`) as the default for any Emacs app UI with real visual structure — boards, meters, gauges, status panels (Craig's directive, 2026-07-11). Verified on Emacs 30.2 pgtk via jotto's librsvg spike: `svg.el` cleanly renders rounded rects, linear gradients, fill-opacity, bold/italic/letter-spaced text, stroked shapes, and theme-derived colors.
+
+The payoff is the prototyping pipeline: design the UI as an HTML prototype first (per `ui-prototyping.md` — browser iteration), then port near-1:1 to `svg.el`, since browser SVG and librsvg share primitives.
+
+Constraints to design around:
+
+- **GUI-only.** No tty rendering — ship a second text renderer or accept GUI-only.
+- **The SVG region is an image, not text.** Input stays minibuffer/keymaps; no point-and-click into the drawing.
+- **Theme colors are pulled by hand.** Read them from faces at render time (`face-attribute`); the image inherits nothing.
+- **Whole-image regeneration per state change.** Design the render as a pure state → SVG function so regeneration is cheap to reason about.
+- **Stick to a librsvg-safe subset.** No SMIL, no JS-in-SVG, conservative CSS and filters. `feDropShadow` renders without error but is visually unverified — don't lean on it.
+
+Recommended shape: hybrid layouts — SVG for boards, meters, and visual state; text buffers for prose and transcripts.
+
+Prior art: archsetup's instrument-console widget gallery (`docs/prototypes/2026-07-03-panel-widget-gallery-prototype.html` in archsetup); jotto's spec records the full pipeline and constraint sheet.