dui-inspector

Runtime introspection and mutation tool for web component design systems built on dui-primitives.

Inspect properties, tokens, slots, parts, style layers, and events. Mutate state live. Export changesets. Works headlessly for AI agent integration.

Install

npm install @deepfuture/dui-inspector

Usage

Full inspector (API + visual UI)

import "@deepfuture/dui-inspector";

This auto-mounts the visual inspector overlay and exposes the headless API on window.

Headless API only (for agents)

import "@deepfuture/dui-inspector/api";

Exposes window globals without mounting any UI:

// Inspect the entire page
window.__dui_inspect();

// Inspect a specific element
window.__dui_inspect('[data-dui-id="1"]');

// Mutations
window.__dui_mutate.setProp(selector, "variant", "outline");
window.__dui_mutate.setToken("--accent", "oklch(0.7 0.2 280)");
window.__dui_mutate.setComponentToken(selector, "--button-bg", "red");
window.__dui_mutate.setSlotContent(selector, "", "<span>New text</span>");
window.__dui_mutate.insertComponent(parentSelector, "beforeend", "dui-button", { variant: "outline" }, "Click me");
window.__dui_mutate.removeComponent(selector);
window.__dui_mutate.moveComponent(selector, newParentSelector, "afterend");

// Changelog
window.__dui_changelog.entries();
window.__dui_changelog.undo();
window.__dui_changelog.clear();

// Source map export
window.__dui_export();

// Observe mutations in real-time
const unsub = window.__dui_observe((entry) => console.log(entry));

How it works

The inspector has zero dependencies on any specific DUI design system. It works entirely through DOM introspection:

• Discovers components by walking the DOM and shadow roots (configurable prefix, default dui-)
• Reads properties via Lit's elementProperties static map
• Scans adopted stylesheets for var(--*) token references
• Resolves computed token values via getComputedStyle
• Detects slots and parts by querying shadow DOM
• Scans prototype method source for dispatchEvent calls to find events
• Analyzes style layers by adopted stylesheet position

This means it works with any component library built on dui-primitives — not just one particular design system.

Configuration

import { init } from "@deepfuture/dui-inspector";

init({
  sourceMap: {
    tokens: "src/tokens.css",
    page: "src/app.ts",
    themeStyles: {
      "dui-button": "src/theme/button.ts",
    },
  },
});

The source map configuration tells __dui_export() which source files correspond to runtime mutations, so AI agents can map changes back to code.

License

MIT