muriel
muriel is a design skill for coding agents. It translates between design languages, from the Visible Language Workshop's typography-as-data to film-style sci-fi interfaces, and expresses them in a multitude of mediums, from paper figures to video. It juries its own work. And it keeps every piece on brand and readable, with tokens from one brand.toml and text held to 8:1 contrast.
Artifacts are generated by scripts saved next to them, so they can be rerun when the data changes.
It runs as a Claude Code plugin or in any harness that reads the Agent Skills format. The Python package and muriel CLI also work without an agent. The name is Muriel Cooper's; she founded the Visible Language Workshop at MIT.
Examples are in the gallery at muriel.mindbendingpixels.com, a site built with muriel.
Install
In a Claude Code session:
/plugin marketplace add andyed/muriel
/plugin install muriel@andyed-muriel
Invoke it with /muriel:compose, or let the agent load it when a task has an open visual decision. The critique agent and jury seats install with it. /plugin uninstall removes everything.
For other harnesses, the Python package, or a development checkout, see More ways to install.
Channels
A channel is one output medium. Each has a markdown file of recipes, tools, and anti-patterns under channels/, and the agent reads the one that matches the job.
| Channel | For (main tools) |
|---|
| Raster | Store assets, icons, banners, wordmarks (Pillow, muriel.typeset) |
| SVG | Paper figures, data-driven vectors, icons, wave fields (plain SVG, optionally svgwrite and cairosvg) |
| Diagrams | Named forms such as 2×2, cycle, pyramid, swimlane, Sankey, treemap, and DAG, each with a stated test for when it fits (muriel's generators; Mermaid and MathJax through Node) |
| Charts | Quantitative charts in JS libraries (Recharts, ECharts, Chart.js, Plotly, D3) |
| Science | Paper figures, notebook editorial, APA-style stats (matplotlib, LaTeX, muriel.stats) |
| Infographics | Single-image explainers (generated SVG) |
| Web | Blog posts, magazine layouts, HTML to PNG or PDF (marginalia, pandoc, Playwright or WeasyPrint) |
| Interactive | Live demos with parameter controls (WebGL, Canvas, D3, PixiJS) |
| Polish |
Two references apply to every channel. Dimensions covers social cards, device sizes, paper, and video resolutions. Style guides defines the brand.toml schema, which imports from Google Stitch design.md (muriel import) and exports W3C design tokens (muriel export-dtcg).
The web and kinetic-type docs default to two sibling projects, marginalia and iblipper, because they pass muriel's rules without changes. Substitute your own libraries freely. Each channel names the library it assumes, and none of the rules depend on it.
Collections of many images default to a third sibling, Wunderkammer, whose 3D views draw with muriel's renderer; references/collections.md covers when to use it and how.
Design languages
A channel is a medium; a vocabulary is a style the agent can work in. Ten ship under vocabularies/:
- Visible Language Workshop: dynamic typography, information landscapes, type as data
- FUI: the HUDs and consoles of film and game interfaces
- Kinetic typography: letters that move with intent
- Declassified: the look of released and redacted documents, from black bars to scan damage
- Surfaces: composed archetypes such as decks, dashboards, posters, and social cards
- Data-viz platforms: the charting guides of Apple, Material, Carbon, Observable, and newsrooms
- ECharts, PixiJS, and KaTeX: the idioms of each library
- muriel's own brand, written up the same way
Rules every channel enforces
From SKILL.md:
- Text contrast of at least 8:1 against its background. No opacity on text; pick an explicit color.
- Body copy and captions at 16 px or larger, body weight 500 or heavier.
- Measure text width, plot bounds, and target dimensions before drawing.
- Label every important number, unit, axis, state, and control.
- One dominant focal point per composition.
- Pointer targets of at least 40 × 40 px.
- Reproducible output: fixed seeds, recorded dimensions, local assets.
- Use the project's brand. Without one, use near-black, cream, and cyan.
Most of the rules predate the tooling. They come from Cooper's Visible Language Workshop, Tufte's data-ink ratio, Bertin's retinal variables, Gestalt grouping, and eye-movement research.
Interaction design
muriel designs how an interface behaves as well as how it looks. It draws on cognitive psychology, perception research, and HCI to choose a mechanism, then builds the mechanism and exercises it in the host product. Rendering and interaction checks are evidence about the artifact; claims about comprehension, workload, or learning need evidence from people.
human-capabilities.md covers cognitive task analysis, the split of work between people and AI, and the limits of evidence. microstrategies.md is built on Gray's Milliseconds Matter: small differences in the cost of reaching information change the routines people adopt. Convention is a starting hypothesis. muriel can propose a new interaction, build a working probe, and weigh what it makes possible against what it costs to learn.
Zooming interfaces, semantic zoom, linked displays, brushing, and faceted exploration share one contract, in multiscale-coordination.md: entities keep a stable identity when their representation changes, queries and selections have explicit meanings, and gestures are recoverable. Camera navigation is covered in zooming-interfaces.md and attribute filters in faceted-exploration.md. Adapters for D3, Vega-Lite, ECharts, and Canvas are in multiscale-adapters.md, and briefs and fixtures for testing the contract in other domains are in multiscale-evaluation.md. The Linked Atlas lab (source) is a working example with synthetic data and no dependencies.
The literature reviews behind these references are in research/.
Checking its own work
muriel renders what it makes and measures the result:
muriel diagram-check fails a figure whose labels collide, run off the canvas, or spill out of their shapes, or whose text falls below 8:1 contrast.muriel.layout.place_label puts an annotation where it collides with nothing, falling back to the margin. It never shrinks text or hides data behind a halo.muriel capture screenshots a page across viewport sizes.muriel squint blurs the capture to show whether the hierarchy survives.muriel loupe cuts 4× close-ups of the busiest regions to show whether line ends and joints hold up.
muriel-critique is a read-only subagent. Given a rendered artifact, it lists each way the artifact breaks muriel's rules, the channel's anti-patterns, or an optional brand.toml, with evidence. It is hardened against instructions and fake contrast claims embedded in the image. Ask for it by name:
Run muriel-critique on path/to/artifact.png with channel raster and brand examples/muriel-brand.toml.
The verdict is PASS, NEEDS REVISION, or FAIL, followed by numbered issues with rule, evidence, fix, and severity. Any CRITICAL issue fails the artifact; any HIGH issue sends it back for revision. Adversarial and baseline test cases live in examples/critique-fixtures/, and new attacks are welcome as pull requests.
A jury splits that review across six narrower seats, used to find defects or to choose between design directions. Each seat sees the artifact through one restricted view, defined in references/jury.md:
| Seat | Judges | Denied |
|---|
muriel-squinter | Hierarchy and reading order under heavy blur | The sharp render, all text, the brief |
muriel-thumbnail | Whether the main signal survives at 1/8 scale and 16 px | The full-size render and the blur ladder |
muriel-loupe | Whether line ends, joints, and edges hold up in 4× close-ups | The whole composition, the brief |
muriel-stranger | What the artifact is for, from a single read | The brief, other ballots, project context |
muriel-forger | Whether a generic template can rebuild it, by trying | The brand tokens |
muriel-pedant | Labels, units, and numeric claims | The rendered composition |
Run each seat as its own subagent. The restrictions hold only because the seat never receives the withheld material in its context.
More ways to install
Other agent harnesses
SKILL.md uses the Agent Skills format. The repo includes .agents/skills/muriel, a symlink to the skill, which Codex CLI reads natively and Cursor, Gemini CLI, GitHub Copilot, OpenCode, and Pi read as an alternate path. Not every harness has been verified yet; HARNESSES.md tracks the checklist. Kiro, Qoder, Rovo Dev, and Trae need manifest shims that have not landed.
Python package and CLI
muriel is not on PyPI yet. Install the wheel from the latest release:
pip install https://github.com/andyed/muriel/releases/download/v0.14.0/muriel-0.14.0-py3-none-any.whl
The core package has no dependencies. Extras add one backend each: raster (Pillow, NumPy), critique (cairosvg), faces (MediaPipe), text (EasyOCR), saliency (ONNX Runtime), or all. muriel doctor reports what is installed.
from muriel import matplotlibrc_dark # applies a dark matplotlibrc on import
from muriel.stats import format_comparison # APA-style reporting
from muriel.contrast import audit_svg # 8:1 contrast audit
from muriel.styleguide import load_styleguide # brand.toml loader
from muriel.dimensions import figsize_for, OG_CARD
muriel # list subcommands
muriel contrast page.svg # 8:1 audit of an SVG or HTML file
muriel diagram-check figure.svg # accessibility lint, label geometry, contrast
muriel capture https://example.com # screenshots across viewport sizes
muriel squint capture.png # blur ladder: does the hierarchy survive?
muriel loupe figure.svg # 4× close-ups: do the joints hold up?
muriel styleguide brand.toml --css # CSS custom properties from a brand.toml
muriel heroshot in.png out.png --tilt 12 --brand brand.toml --target og.card
Each subcommand also runs as a module, for example python -m muriel.capture.
From a checkout
To work on muriel itself, install from a clone so edits take effect immediately:
git clone https://github.com/andyed/muriel ~/Documents/dev/muriel
cd ~/Documents/dev/muriel && ./install.sh
install.sh links plugins/muriel/skills/compose/ to ~/.claude/skills/muriel and plugins/muriel/agents/ to ~/.claude/agents/muriel. New channels and jury seats appear without a re-run, and the bare /muriel command works. The script refuses to run if the plugin is already installed, to avoid loading muriel twice. If it finds an older mount, it reports it and stops; ./install.sh --repair moves the old mount to muriel.bak-<timestamp> and links the new one.
Repository layout
plugins/muriel/skills/compose/: the skill (SKILL.md, channels, references, vocabularies, examples)plugins/muriel/agents/: the critique agent and the five jury seatsmuriel/: Python package and CLIrender_assets/: Three.js and CSS3D exemplars for the spatial channelresearch/: literature reviews and bibliographies behind the references.claude-plugin/marketplace.json: the marketplace entry. The plugin manifest is plugins/muriel/.claude-plugin/plugin.json.
In use
Scrutinizer's brand and perceptual tokens page is built with muriel. It uses the scrutinizer-brand.toml style guide, the foveal_overlay and engine_sectors_overlay diagram primitives, and the palettes module.
Prior art
muriel borrows openly and says where from. PRIOR_ART.md lists each source, what muriel took, and what it changed, and THIRD_PARTY_NOTICES.md carries the licenses for incorporated material. The most direct debts:
License
MIT. See LICENSE.
