uidna

UI DNA is REA for user interfaces. REA's promise is "see a feature you like, understand how it works, down to the binary, show the evidence, build it." UI DNA's promise: see an interface you like, understand how it is structured, how it behaves and how to reproduce it, down to the token, the component and the state transition, then rebuild it as code you own, with proof.

agent asks about a target  →  UI DNA captures, crawls, measures, explores
                           →  returns a UI DNA document + evidence + unknowns
agent reconstructs, verifies, repairs, reports

Contents

• Quick start

• How it works

• What ships today

• Tools and commands

• The UI DNA document

• A measured run

• Authorized use

• Limitations

• Development

• License

Related MCP server: art-director-mcp

Quick start

npm install -g @rohzzn/uidna
npx playwright install chromium
uidna setup      # registers the MCP server in Claude Code, Codex and Cursor; asks first, backs up
uidna doctor     # browser availability, CDP reachability, registration state

uidna setup prints the planned changes to ~/.claude.json, ~/.codex/config.toml and ~/.cursor/mcp.json, asks for confirmation and backs up every file it touches. Use --scope project to write .mcp.json and .cursor/mcp.json in the current directory instead, and --yes to skip the prompt. The registered command is npx -y @rohzzn/uidna@latest serve (wrapped in cmd /c on Windows).

Manual MCP configuration, if you prefer:

{
  "mcpServers": {
    "uidna": { "type": "stdio", "command": "npx", "args": ["-y", "@rohzzn/uidna@latest", "serve"] }
  }
}

The shipped skill, skills/uidna/SKILL.md, teaches the agent the loop. Copy it into your agent's skills directory (for Claude Code, ~/.claude/skills/uidna/).

To run the whole loop without an agent, on one page:

uidna reconstruct https://example.com ./example-clone --viewports 1280,768,390

On a small site you own, following up to five same-origin pages, capturing JSON responses as data and exercising its forms with synthetic values:

uidna reconstruct http://localhost:3000 ./my-site --crawl '{"maxPages":5}' --capture-bodies json --policy forms

How it works

Every value in the document carries provenance: measured, observed, inferred (agent only) or unknown with a reason. Nothing is rounded into a guess, and no result is a single blended score.

What ships today

Phase 1, the single-page loop. From URL to verified React project, proven in CI with a real Chromium against Fixture A, a marketing page with a responsive navbar and hamburger menu, a hero, two call-to-action buttons, a three-card grid, an image, an FAQ accordion and a footer, at 1280, 768 and 390 pixels wide.

• Two browser modes: Playwright-launched Chromium for public pages, and attach to your own Chrome over the DevTools Protocol for sessions you are authorized to analyze.

• robots.txt honored, per-origin rate limits, Chromium sandbox requested (with an honest limitation when the host cannot provide one), secrets redacted before anything is stored.

• Twelve tools with one evidence envelope, identical over MCP and the CLI; setup and doctor on the CLI; --json, a config file and debug logging.

• A versioned, framework-neutral schema published separately as @rohzzn/uidna-schema.

• The generated project builds; its build, the recorded transitions, and an injected CSS and behavior regression are each a CI test.

Phase 2, sites, forms, data, collections and breakpoints. Each capability below is a CI gate on its own fixture.

• Multi-page crawl. crawl: { maxPages, include, exclude } follows same-origin links breadth-first; cross-origin links are recorded and never followed. Pages carry their depth and the link that discovered them. Components are matched across pages, and the header and footer every page shares become one layout.

• Navigation transitions. A click on a link to another crawled page is recorded as a transition between the two pages. The generator wires it as a router link and the verifier replays it through the original link.

• Forms. The forms policy fills controls with synthetic values (never real credentials; hidden and file inputs are never filled), submits the empty form to observe client-side validation and the filled form to observe the result. Validation states keep aria-invalid, the error message and the browser's validity. Every submission request is blocked, recorded as a side effect and never repeated.

• Data. captureBodies: "json" stores JSON responses from fetch and XHR as redacted, size-capped data assets. The generator turns each one into a typed mock.

• Responsive rules. Breakpoints are located where the layout actually changes, not at the scanned widths: stylesheet thresholds are read and confirmed one pixel apart by resizing, and changes no stylesheet explains are found by bisection within a budget. Probing only resizes the page and blocks every non-GET request. The document lists each breakpoint with its bracket and condition and the layout values that change there; the generator declares those breakpoints and attributes each style change to the one that explains it; the verifier checks the generated layout on both sides of each.

• Search, filter and sort. Tables, lists and card grids become collections with item identity, fields and value kinds. A search box is tried with a query taken from the items' own text; chips, tabs and column headers are clicked as usual. Each change is classified against the base items: a search with its match and fields, a filter with the field and value it keeps, a sort with its field, direction and comparator, a reset. The generated project renders the items through that state, and the verifier compares the generated items with the original's by identity and order.

• Row actions. A control repeated in every item of a collection (an "Archive" button per row) is one action: once it causes a side effect, it is skipped in every other item.

• Behavior tests. The generated project includes tests/behavior.spec.ts: one Playwright test per implemented transition, asserting the observed delta. Transitions the generator did not reproduce, or that caused a side effect when observed, are skipped with the reason. verify_reconstruction runs the suite when asked.

Fixture B is an orders dashboard: a table loaded from a JSON endpoint with a search box, status chips and sortable columns, a row action that posts, and breakpoints at 600, 960 and 1100px, none of them a scanned width. Fixture C is a signup form with client-side validation, a POST endpoint and a JSON list. Fixture D is a three-page site with a shared header and footer, tabs, a pricing toggle and a cross-origin footer link.

Tools and commands

Every tool returns the same envelope; add --json on the CLI to see it:

{
  "result": {},
  "evidence_id": "ev_3f9a1c7b2d4e",
  "evidence": { "kind": "scan", "inputs": {}, "artifacts": [], "capturedAt": "2026-10-13T17:29:00.000Z" },
  "limitations": [],
  "unknowns": []
}

The full catalog, generated from the contracts, is in docs/tools.md.

The UI DNA document

A UI DNA document describes an interface the way an engineer needs it described to rebuild it: pages and navigation, observed states and the transitions between them, component candidates with their instances, visual tokens with the measurements behind them, layout constraints per node, form facts and validation states, observed behavior, assets and data with origin and authorization, and what could not be observed.

{
  "value": "248px",
  "provenance": {
    "kind": "measured",
    "source": "computed-style",
    "stateId": "st_01",
    "viewport": { "width": 1280, "height": 800 },
    "evidenceId": "ev_3f9a1c7b2d4e",
    "capturedAt": "2026-10-13T17:29:00.000Z",
    "confidence": 0.98
  }
}

Schema 0.2.0 adds pages with depth and discovery, form facts on nodes, fill and submit actions, navigation transitions and data assets; every 0.1.0 document is still valid. The reference is docs/ui-dna.md; a complete validated example from Fixture A is in docs/examples/fixture-a.dna.json.

A measured run

Measured on Fixture A (http://127.0.0.1:51767/) by scan scan_20261014_13cdb7 with tool version 0.2.0:

Pixel ratios depend on the fonts of the machine that rendered them; the counts do not.

Attempts 2 and 4 are the CI loop's injected regressions (a changed primary color, then a script that swallows clicks); attempts 3 and 5 are the reverts. The 21 baseline findings are all the unauthorized illustration rendered as a labeled placeholder, by design. The table is written by scripts/readme-numbers.ts from the scan that produced it.

Authorized use

Scan interfaces you own or are allowed to analyze. UI DNA never bypasses authentication, CAPTCHAs, anti-bot measures or access controls, never stores credentials, and never redistributes third-party assets: unauthorized assets become labeled placeholders until you mark them authorized with annotate_dna. See DISCLAIMER.md and SECURITY.md.

Exploration blocks every non-GET request for the whole run, including beacons sent while a page unloads: an action that tries to send one is recorded as a side effect and never repeated, and the request never reaches its server. A page that loads its content with POST requests shows its error state instead. The forms policy types synthetic values into the page and runs its submit handlers; search boxes are typed into with text taken from the page's own items. Use them only on interfaces you may test that way. A crawl stays on the seed's origin, honors robots.txt and stops at its page budget.

To analyze an authenticated app, start your own Chrome with --remote-debugging-port=9222, open the page, then uidna scan --cdp-endpoint http://localhost:9222. The session stays yours; UI DNA reads the page and performs the same safe interactions.

Limitations

• A crawl follows same-origin <a href> links only, up to 50 pages. Navigations made by scripts are blocked and reported, not followed.

• Server responses to form submissions are never observed, because the requests are blocked. Success states that depend on the server are reproduced only as far as the page showed them without one, and the generated README says so.

• <iframe> content and shadow DOM are not entered; they are reported as limitations.

• Inline <svg> markup is not captured; such nodes become placeholders.

• Breakpoints are located from readable stylesheets and by resizing between the scanned widths. Cross-origin stylesheets, container queries and continuously varying values (clamp(), vw) are not breakpoints; a threshold above the widest or below the narrowest scanned width is read from the stylesheet but not seen. When two located breakpoints fall between the same scanned widths, a property that changes twice there is generated at the later one.

• Collections are explored through search boxes outside forms, and through the chips, tabs and column headers the click round already clicks. Selects, checkboxes, combined filters, server-side search, pagination and load-more are not explored or reproduced; generated collections show the captured items, not the endpoint's data.

• Spacing tokens are used values: a margin: auto shows up as the pixel margin it produced.

• Hover and focus transitions are reproduced as CSS variants at every viewport. Click toggles are reproduced, sharing their state across section files when the changed nodes live elsewhere; component instances changed together with nodes outside them are rendered inline instead. Every behavior the generator could not implement is listed in the generated README and skipped in its Playwright suite.

• The generator is a baseline, not a finished product: names are placeholders and the agent is expected to repair against the DiffReport.

• Verification compares at the scanned viewports with system fonts; cross-machine pixel diffs reflect font rendering differences, which is why findings carry the measured values rather than a single score.

Development

packages/schema/   @rohzzn/uidna-schema: Zod schema, JSON Schema, types, changelog
src/domain/        fingerprints, clustering, colors, safe-action and forms policy, Result, budgets
src/contracts/     tool contracts and the canonical catalog (docs/tools.md is generated)
src/browser/       Playwright launch + CDP attach adapters, capture, robots, redaction, JSON bodies
src/analysis/      normalization, token clustering, components, layout, multi-page assembly
src/explore/       interaction rounds, navigation, form chains, state graph, revert
src/generate/      UI DNA document → React project, router, forms, mocks, Playwright tests
src/verify/        render, visual + behavioral compare, generated-test runs, DiffReport, HTML report
src/application/   workflows shared by the CLI and the MCP server, crawl, scan store
src/server/        MCP adapter
skills/uidna/      SKILL.md
fixtures/          A (marketing page), B (dashboard), C (signup form and data), D (three-page site)
tests/             end-to-end loops on Fixtures A, B, C and D, and the MCP server over stdio

npm ci
npm run build
npm run test:unit    # real Chromium against the fixtures and synthetic pages, no module mocks
npm run test:e2e     # the Phase 1 and Phase 2 loops and the MCP server (about 35 minutes)
npm run docs:catalog

Conventional Commits, ESM TypeScript in strict mode, Zod at every boundary, tagged errors with Result, no any, no non-null assertions, no floating promises. See CONTRIBUTING.md.

License

MIT. See LICENSE.