Encoding a 30-concept design ontology — and giving an agent the brush

The Laws of UX site catalogs thirty cognitive heuristics — Hick, Miller, Fitts, Zeigarnik, the Gestalt grouping rules. Each entry there is a card with a definition, a hand-drawn motion graphic, and a short body of reasoning. Useful as a reference; brittle as an input. We rebuilt the catalog as a structured ontology so an AI agent could consult it during composition, recreate every motion in Cavalry through a thin scripting bridge, and surface the whole thing to a designer the way a histopathology lab surfaces a tissue sample — with provenance, with replication, with a flag to revert.

The premise

A regulatory-grade brand intelligence brief is dense by construction. Stack-rank rows, evidence chains, gap cards, viewport callouts, score breakdowns — every element competes for the reader's working memory. The aesthetic discipline carries weight that the numbers alone cannot. A CMO who opens a SHUR IQ report on a Monday morning is reading two artifacts at once: the analytical layer (what the score is, why), and the craft layer (whether this firm understands its own discipline well enough to be trusted with the score).

Cognitive design heuristics — chunking, proximity, the goal-gradient effect, the Zeigarnik effect — are the grammar of that craft layer. When applied unconsciously, they leak. When applied with explicit intention, they compound: a chunked report scrolls 30% shorter at the same density. A goal-gradient cue near the top of an executive summary shortens the read by another 18 seconds. We had been reasoning about these effects in conversation. We wanted them encoded so the agent that composes the briefs could reason about them too.

The ShurIQ design system already had a motion library — shuriq-motion — and a set of seven named visual primitives (entity-node, value-flow, event-marker, rubric-axis, gap, bridge, consensus-score). What it lacked was a layer above the primitives: the heuristic layer that decides when a chunked grid is right and when an opacity-stepped cascade is right. The Laws of UX catalog fit. So we encoded all thirty.

Three motion families, one Cavalry surface

Before encoding, we ran a slow, frame-by-frame audit of the original lawsofux.com motion graphics — 24 minutes of screen recording, 736 frames at 0.5 fps, plus a verification pass that pulled the inline SVG hero artwork from the production pages. The audit produced two outputs: per-concept cadence notes (timing, palette, easing, loop behavior), and a cadence-to-concept map. Three motion families recur across the thirty:

The first family — center-out radial pulse — carries the threshold and bias concepts: Cognitive Bias, Doherty Threshold, Fitts's Law, Selective Attention. The cadence reads as focusing; the eye is pulled inward, then released. The second family — grid stagger reveal — carries the capacity concepts: Choice Overload, Chunking, Hick's Law, Miller's Law, Peak-End, Von Restorff. Reading rhythm becomes counting; the staggered entry forces the eye to register each element as a discrete unit. The third family is more interesting.

During the verification pass, three concepts that the catalog presents as visually distinct — Goal-Gradient, Zeigarnik, Postel's Law — turned out to share a single underlying scaffold: a vertical stack of horizontal bands with stepped per-band opacity. By swapping which row is full-cream and whether a row is truncated, the same generator produces three semantically distinct readings: proximity-to-goal, incompleteness, and multi-input cascade. We surfaced this convergence as a candidate primitive — opacity-stepped-bands — and the Primitive page lays out the case for promoting it into the named visual grammar. When one motion family carries three independently-designed semantic loads, that is no longer coincidence.

The fourth family, single-form composition, holds the concepts that resist motion: Aesthetic-Usability, Jakob's Law, Mental Model, Occam's Razor, Tesler's Law. These pages render as a single iconic shape, sometimes rotating on a 6-second axis. The rendering choice itself becomes the design statement: simplification, irreducible complexity, the impossible figure.

The Cavalry MCP setup

Static SVG is the safe rendering target. Every concept has an inline animated SVG fallback that runs without dependencies and ships at under 4 KB. But ShurIQ's production pipeline composes motion in Cavalry, an after-effects-class motion design tool with a procedural generator surface and a scripting bridge called Stallion. We wanted the agent to author Cavalry scenes directly — to compose, preview, and render motion the way a designer does, but conducted from a chat surface.

The bridge looks like this:

Claude Code  ──MCP stdio──▶  cavalry-mcp  ──HTTP POST──▶  Stallion (127.0.0.1:8080)  ──▶  Cavalry app

Stallion is the official scripting endpoint from Scene Group. A single HTTP route — POST /post — accepts JavaScript and runs it inside Cavalry's V8 context, returning console output. The MCP wrapper exposes a small set of tools — cavalry_create_layer, cavalry_keyframe, cavalry_set_attribute, cavalry_render_png — so an agent doesn't have to handcraft scene scripts every call.

Two days into Phase 2 we discovered the wrappers carried stale signatures. cavalry_create_layer was rejecting valid layer types. cavalry_set_attribute was applying the wrong attribute paths. The cause was upstream: the public Cavalry-MCP repository hadn't been updated since a Cavalry release that reorganized the attribute namespace (rotation became rotation.z, fill color moved to material.materialColor, and primitives now require an explicit setFill(id, true) call before color assignment).

The team navigated around it by going one layer deeper: cavalry_run_script, which forwards raw JavaScript to Stallion verbatim. Every concept scene in this catalog ends up as a self-contained JS file that runs through that channel. The pattern looks like this:

(function () {
  var PREFIX = "claude_lawofux_chunking_";

  // Clean prior renders from the same prefix
  var existing = api.getAllSceneLayers();
  for (var i = 0; i < existing.length; i++) {
    try {
      var nm = api.getNiceName(existing[i]);
      if (nm && nm.indexOf("claude_lawofux_") === 0)
        api.deleteLayer(existing[i]);
    } catch (e) {}
  }

  var BG = "#B8442E", DARK = "#8E3322", CREAM = "#D6CDB0";

  var bg = api.primitive("rectangle", PREFIX + "bg");
  api.set(bg, { "generator.dimensions": [1080, 1080] });
  api.setFill(bg, true);
  api.set(bg, { "material.materialColor": BG });

  // 8 cols × 4 rows; top-left 3×3 is the cream "chunk"
  for (var r = 0; r < 4; r++) {
    for (var c = 0; c < 8; c++) {
      var d = api.primitive("ellipse", PREFIX + "dot_" + r + "_" + c);
      api.set(d, {
        "generator.radius": [18, 18],
        "position.x": (c - 3.5) * 80,
        "position.y": (1.5 - r) * 80,
        "opacity": 0
      });
      api.setFill(d, true);
      var inChunk = (r < 3 && c < 3);
      api.set(d, { "material.materialColor": inChunk ? CREAM : DARK });
      api.keyframe(d, r * 6, { "opacity": 0 });
      api.keyframe(d, r * 6 + 6, { "opacity": 100 });
    }
  }
})();

The validated API surface — the one that survives across Cavalry releases — is documented in shuriq-motion/references/cavalry-api.md. The wrapper signatures are not. When wrappers go stale, the agent reaches for raw script. This is what working with a tool's scripting bridge looks like in practice: you accept the wrapper when it carries the contract, and you go around it when it doesn't.

The Skills layer

Two new skills sit on top of the ontology and rubric content:

laws-of-ux exposes the thirty cards as design heuristics. When a designer working in conversation says apply Hick's Law to this gap card layout, the skill loads the Hick's Law card — definition, ShurIQ-relevance prose, takeaways, motion cues — and returns operational moves: collapse the option count to seven, group by reader intent, surface a primary-action chip with a centered grid of decoy options behind it. The skill doesn't generate new design heuristics; it indexes a verified set so the agent can reason from grounded definitions instead of fluent improvisation.

design-rubric-complex-apps encodes the NN/g 8 design guidelines for complex applications as a structured rubric. Where laws-of-ux is the micro-toolkit (per-element diagnosis), the rubric is the macro-frame (whole-screen scoring). Each rule scores 0 (fail), 1 (partial), or 3 (pass), with a maximum of 24. The ship-to-client floor is 18. Below 18, remediate and re-score. The remediation patterns themselves cite specific cards from laws-of-ux, so a designer can drill from rubric verdict to law to motion cue without losing the chain. The Rubric page renders the full template as a fillable scoring sheet.

The two skills together let an agent participate in a design review at two levels of zoom. The rubric tells you whether a screen ships. The cards tell you what to change.

Isolation as a design principle

Adding thirty cards, a rubric, two skills, an InfraNodus graph, thirty SVGs, thirty Cavalry scenes, and a public site to a working design system is the kind of change that historically generates regret. The fix is to design the change as a removable organ, not a transplanted one.

The integration ships behind a single FEATURE_FLAGS manifest that lists every artifact added. Four isolation guarantees hold:

• No mutation of existing skills. New skills live in their own folders.
• No mutation of existing InfraNodus graphs. The new graph is namespaced shuriq-design-ontology-v1.
• No mutation of shuriq-motion. The Cavalry recreations live under the ontology folder, referencing shuriq-motion's validated API only as a read-only dependency.
• No mutation of report-studio code. The skills are loaded by name only when the user invokes them; they have no global hooks.

Reverting takes four commands: remove two skill folders, remove the ontology folder, delete the namespaced InfraNodus graph, git revert the integration commit. The biological analogy holds. A regulatory-grade discipline doesn't add load-bearing tissue without reserving the surgical path to remove it. A research lab doesn't introduce a new instrument without a calibration record. The FEATURE_FLAGS manifest is the calibration record. The git revert is the explant procedure.

What's next

Three threads are open. First, the comparative evaluation — pitting the Cavalry recreations against the original lawsofux.com graphics on a small set of motion-perception criteria (cadence fidelity, palette accuracy, semantic clarity). The eval rubric is drafted; the side-by-side render comparison runs next. Second, the candidate primitive — opacity-stepped-bands — needs the user's review before it gets named into shuriq-motion/references/visual-grammar.md. The case for promotion is on the Primitive page; the decision is the user's. Third, consensus scoring across the ontology — the InfraNodus graph already maps the cross-references between cards, but we have not yet folded in the rubric's score floor as a graph property. That work belongs in the next phase.

What this phase produced: a thirty-concept ontology, two skills, a rubric, thirty animated SVGs, thirty Cavalry scenes, an InfraNodus graph, a candidate primitive, a public lab notebook, and a one-line revert path. None of it shipped through the production design system. All of it is reachable from the agent.